Skip to content

mdz-axo/hKask

BranchesTags

Repository files navigation

Kask Logo

ℏKask - A Minimal Viable Container for Users and AI Tools

Binary: kask - Crate prefix: hkask- - Version: v0.31.0 - License: MIT

A single hKask install deploys on a cloud server (Kubernetes / K3s) and serves a group of users. Each user gets exactly one userpod - a sovereign container with their own identity, memory, capabilities, and consent boundary - plus AI skills, 16 MCP servers, and multi-provider LLM access. Userpods, federation, and Matrix transport are the container's plumbing, not the point.1

What hKask Is

hKask is a minimal viable container for users and AI tools. A single install deploys on a cloud server (Kubernetes / K3s) and serves a group of users - each one gets exactly one userpod: their own sovereign identity, encrypted memory, capabilities, and consent boundary within the shared install. The deployment unit is the install; the sovereignty unit is the userpod (1:1 per user).

It is not an agent platform or an agent framework. There is no autonomous agent loop by default; the human is in the loop and skills escalate to the user, not away from them. The Curator is the system's cybernetic regulator, not an autonomous agent.

Three things sit between the user and a model:

  1. Skills — 51 iterative PDCA loops (.agents/skills/) that compose Jinja2 templates into Plan-Do-Check-Act cycles with convergence thresholds, gas budgets, and escalation. Where other systems give you a prompt, hKask gives you a process.2
  2. MCP servers — 16 built-in Model Context Protocol servers (research, memory, codegraph, media, filesystem, regulation, …) exposed as tools through rmcp.3
  3. Inference routing — one router across 8 providers (Cline, DeepInfra, fal.ai, KiloCode, Ollama, OpenRouter, Runpod, Together), with fusion, circuit breakers, and per-call gas accounting.

Everything else in the codebase - pods, federation, Matrix, wallet, ledger, regulation, keystore - exists to keep each user's session sovereign within the shared install: per-userpod SQLCipher, OCAP dual gate, visibility gating. An install has two roles, Admin and Member (invite flow, hkask-identity), but sovereignty is enforced below the role layer - the group install shares infrastructure, never userpod data.

What hKask Is Not

  • Not an agent framework. There is no autonomous agent loop by default; the human is in the loop and skills escalate to the user, not away from them.
  • Not a public multi-tenant SaaS. An install serves a defined group (an organization, a team, a household) via OAuth + invite, not arbitrary public sign-up. Per-userpod sovereignty is structural, not row-level.
  • Not a single-user local-only tool. Local kask tui is supported, but the reference deployment is a cloud server accessed via browser (xterm.js + WSS) or Matrix. Federation links installs.

Architecture Overview

flowchart TD
    %% ─── Outer install container ───────────────────────────────────
    subgraph Install["hKask install · K3s/Kubernetes · one per group of users"]
        direction TB

        Surface["Surface · kask tui (ratatui REPL) · xterm.js/WSS"]

        %% ─── Pods in the center — the sovereignty units ───────────
        subgraph Pods[" Pods — Solid Pod isomorphism · the sovereignty units "]
            direction LR

            subgraph UserPod[" UserPod · 1:1 per human · VSM S1 Implementation "]
                direction TB
                Human(["Human user — the principal"])
                UserMem["Per-pod SQLCipher<br/>episodic private + semantic public"]
                UserOcap["OCAP dual-gate tokens"]
                Human --> UserMem
                Human --> UserOcap
            end

            subgraph CuratorPod[" CuratorPod · singleton, system-owned · VSM S4 Intelligence "]
                direction TB
                Curator(["Curator — cybernetic regulator<br/>NOT autonomous · escalates to user"])
                SemIdx["SemanticIndex<br/>aggregated public hMems"]
                Curator --> SemIdx
            end

            UserPod -. "semantic publish · reg.semantic.published" .-> CuratorPod
            CuratorPod -. "calibrate directives" .-> UserPod
        end

        %% ─── Soft layer — the mutable thread · skills live here ──
        subgraph Soft[" Soft layer — the thread (mutable) · 52 skills live here "]
            direction TB
            Registry[("Skill registry · registry/templates/&lt;name&gt;/<br/>manifest.yaml (FlowDef) + *.j2 (WordAct/KnowAct/RenderAct)<br/>THE skill source of truth · 89 manifests · 391 templates")]
            SKILLmd["SKILL.md · .agents/skills/<br/>derived companion for Zed agent · NOT runtime"]
            Registry -. "derived via skill-translator" .-> SKILLmd
        end

        %% ─── Hard layer — Rust kernel (fixed) ────────────────────
        subgraph Hard[" Hard layer — Rust kernel (fixed) "]
            direction TB
            Turn["REPL turn · hkask-repl/turn<br/>memory recall + inference + tool dispatch<br/>+ gas reservation per turn"]
            Executor["ManifestExecutor<br/>select → populate → execute cascade<br/>matryoshka-bounded (7)"]
            Mcp["16 MCP servers · rmcp dispatch<br/>GovernedTool · OCAP-gated"]
            Guard["hkask-guard · ContentGuard + GuardedInferencePort<br/>scan_input / scan_output · reg.guard.*<br/>universal decorator at InferencePort seam"]
            Router["InferenceRouter · InferencePort<br/>8 providers · fusion · circuit breakers"]
        end

        %% ─── Regulation — the autonomic nervous system ───────────
        subgraph Reg[" Regulation — cybernetic self-regulation (VSM S1–S5) "]
            direction TB
            Sensors["SensorBus · pluggable sensors<br/>Variety · EnergyBudget · WalletKey<br/>WalletBalance · ToolReliability"]
            Cyber["CyberneticsLoop<br/>sense → compare → compute → act → verify"]
            Variety["SetPoints · AlgedonicManager<br/>VarietyTracker · Ashby's Law"]
            Sensors -->|"sense"| Cyber
            Cyber --> Variety
            Variety -. "algedonic signals" .-> Cyber
        end

        subgraph Econ[" Economy "]
            Wallet["Wallet + Ledger · rJoule gas<br/>1 rJ = 250,000 cycles"]
        end

        %% ─── Wiring: surface → REPL turn → pod authority ─────────
        Surface --> Turn
        Turn --> UserPod

        %% ─── Executor drives the soft layer: loads skill manifests,
        %%      renders their template_ref via inference, dispatches execute ──
        Executor -->|"loads BundleManifest"| Registry
        Executor -->|"select/populate via GuardedInferencePort"| Guard
        Executor -->|"execute step → ToolPort"| Mcp

        %% ─── Everything runs under pod authority (OCAP governs every execute) ──
        UserOcap -->|"govern every execute"| Executor
        Curator -->|"KnowAct via execute_knowact()"| Executor

        %% ── GuardedInferencePort wraps the InferenceRouter at the composition
        %%      root (build_loops) — all InferencePort callers route through it. ──
        Turn -->|"chat turn via GuardedInferencePort"| Guard
        Classify["Classify / extract / QA services<br/>own reqwest path — manual scan_input / scan_output"]
        Classify -->|"manual scan"| Guard
        Guard -->|"scanned input → InferenceRouter"| Router
        Router --> Providers["8 LLM/media providers<br/>Cline · DeepInfra · fal.ai · KiloCode<br/>Ollama · OpenRouter · Runpod · Together"]

        %% ─── PDCA skill loop: Executor iterates until convergence ──
        Executor -. "PDCA: iterate until convergence ≤ threshold" .-> Executor

        %% ─── Spans → RegulationLedger → sensors → CyberneticsLoop ──
        Executor -->|"reg.skill.* / reg.guard.*"| Sensors
        Mcp -->|"reg.* spans"| Sensors
        Router -->|"reg.inference.*"| Sensors
        Guard -->|"reg.guard.*"| Sensors

        %% ─── Wallet: Router debits rJoules; sensors read wallet health ──
        Router -->|"debit rJoules"| Wallet
        Wallet -. "wallet health sensed" .-> Sensors

        %% ─── Curator metacognition loop + human-in-the-loop ──────
        Cyber -. "algedonic alerts" .-> Curator
        Curator -->|"CuratorDirective::CalibrateThreshold"| Cyber
        Curator -. "observe → diagnose → calibrate / escalate" .-> Curator
        Curator -. "escalate to user" .-> Human
        Human -. "response / consent" .-> Curator
    end

    Federation["Federation + Matrix · cross-install · opt-in<br/>7R7 listener · Matrix standing session"]
    Install -. "cross-install" .-> Federation
Loading

The Architecture — Four Essential Patterns

hKask is governed by four irreducible patterns that compose into a single cybernetic whole. Remove any one and the system collapses into a qualitatively different — and non-viable — system. The full treatment lives in the Architecture Master; this is the one-page synthesis.1

Pattern A — Skills Model (WordAct / FlowDef / KnowAct / RenderAct)

A template type system that governs how hKask composes behavior. Where other systems give you a prompt, hKask gives you a process: 52 PDCA skill loops that iterate until they converge on a quality threshold, exhaust their energy budget, or escalate to the user. Selection intelligence lives in the Jinja2 templates and the LLM — not in Rust (P3 Generative Space). The Rust kernel is a fixed loom; the YAML/Jinja2 is the mutable thread.

Pattern B — Regulation Feedback Loop

The autonomic nervous system: every tool call, inference, and memory operation emits a reg.* span. VarietyTracker counts behavioral diversity (Ashby's Law); AlgedonicManager fires on deficit; SetPointCalibrator self-tunes the set-points, closing the Conant-Ashby loop. Not passive monitoring — active regulation.

Pattern C — Cybernetic Mediation (Curator)

The Curator is the system's cybernetic mediator (VSM S4 — Intelligence), not an autonomous agent. It mediates between the user and the system's AI tools and resources — skills, MCP servers, and inference — coordinating their use and managing hKask's regulation. It observes, assesses, escalates to the user, and tunes Regulation set-points — but it never bypasses OCAP, never acts without capability tokens, and never removes the human from the loop. Exactly one Curator per install (singleton invariant).

Pattern D — Sovereign Identity & Memory (UserPod)

The human user gets a single userpod — a sovereign container with its own identity, encrypted memory, capabilities, and consent boundary. The userpod is not an autonomous agent; it is the user's sovereign surface through which skills, tools, and inference act under the user's authority and consent.

Sovereignty Grounded in the Solid Pod Isomorphism

The userpod is architecturally grounded in the five invariants that define a W3C Solid Pod: (1) WebID-grounded identity, (2) self-contained storage (per-userpod SQLCipher file), (3) capability-based access control (OCAP dual gate), (4) interoperable data as linked-data triples (hMem), (5) the pod IS the deployment unit (PodDeployment owns its storage, Regulation, and tools).

This isomorphism is the structural guarantee of Magna Carta P1 (User Sovereignty): an install shares infrastructure, never userpod data. Data isolation is structural (one encrypted database per userpod), not row-level. Backup is a portable encrypted archive — export from one server, upload to another. The pod is portable; the user owns it.

Inference Routing

One InferenceRouter across 8 providers (Cline, DeepInfra, fal.ai, KiloCode, Ollama, OpenRouter, Runpod, Together). Model names carry a two-letter prefix (DI/, FA/, TG/, RP/, OR/, KC/, OM/, CL/) that routes to the correct backend; unprefixed names use the configured default. Each backend is gated on configuration (an API key), not reachability — unavailable providers are silently skipped. Fusion orchestrates multi-model deliberation (panel → synthesis/judge modes) provider-agnostically. Per-provider circuit breakers and rJoule gas accounting bound every call.

Five Anchors

# Anchor Implementation
1 User sovereignty Solid Pod isomorphism — per-userpod WebID, SQLCipher-at-rest, OCAP dual gate, OS keychain, private/public gating — Magna Carta P1–P4. The install shares infrastructure, never userpod data.
2 Skills & composition 52 PDCA skill loops compose 89 registry manifests + 391 Jinja2 templates into iterative cycles — the soft layer that offloads selection intelligence to the LLM2
3 Tools 16 MCP servers + inference router over 8 LLM/media providers with fusion and per-provider circuit breakers3
4 Regulation reg.* span registry, variety counters, algedonic escalation — the cybernetic nervous system4
5 Economy rJoule gas accounting (1 rJ = 250 000 gas cycles), double-entry ledger, per-call circuit breakers

The Skills Model - WordAct / FlowDef / KnowAct / RenderAct

hKask distinguishes two layers that other systems conflate:

  • Templates (391 Jinja2 .j2) — one-shot prompt executions. What Claude, ChatGPT, and most agent platforms call "skills." In hKask these are raw material: render once, return output, exit. Critically, selection intelligence lives in the templates and the LLM, not in Rust (P3 Generative Space) — the Rust kernel is a fixed loom; the Jinja2/YAML is the mutable thread that directs platform functions and absorbs complexity that would otherwise bloat the binary.
  • Skills (52 PDCA loops) — iterative cycles that compose templates into search, learning, and implementation loops. A skill has a manifest.yaml with convergence.threshold > 0, a gas.cap, and a loop action. It runs until it converges on a quality threshold, exhausts its energy budget, or escalates to the user.

The template type system spans four roles - the cognitive-act triad plus a non-inference render layer:2

Type Format Governs
WordAct Jinja2 .j2 "What to say" - system prompts, personas, performative utterances (inference-invoked)
FlowDef YAML .yaml "What to do" - select - populate - execute cascade, choice/escalate/abort/delegate verbs
KnowAct Jinja2 .j2 "How to think" - classification, reflection, calibration (inference-invoked)
RenderAct Jinja2 .j2 "What to render" - non-inference content: macro libraries, error views, reference material. Never sent to the LLM; loaded for rendering/reference only
Layer Format Count Behavior
Templates *.j2 (Jinja2) 391 One-shot: render → return output. Selection intelligence lives here, not in Rust (P3 Generative Space)
Skill manifests manifest.yaml 89 FlowDef contracts, convergence, gas budget
Skills .agents/skills/ 52 PDCA loops: compose → iterate → converge | max_out | escalate

The canonical source of truth for every skill is its registry crate (registry/templates/<name>/manifest.yaml + *.j2). The SKILL.md file in .agents/skills/ is a generated companion for the Zed coding agent, not a co-equal artifact.2

Crate Structure

39 core crates + 16 MCP servers = 55 workspace members (excluding fuzz).

Foundation

Crate Purpose
hkask-types ID types, regulation-record, vocabulary, visibility, Regulation spans
hkask-storage SQLite + SQLCipher, triples, embeddings, blobs (Store trait, locks, path sanitization)
hkask-memory Semantic / episodic pipelines (consolidation: episodic → semantic)
hkask-regulation Cybernetic nervous system — reg.* spans, loops, variety
hkask-templates Registry, vocabulary, cascade, resolver
hkask-pods Pod identity, WebID, bot/userpod, Curator persona, PodDeployment
hkask-keystore OS keychain, AES-256-GCM
hkask-mcp MCP runtime, dispatch, security
hkask-mcp-server MCP server framework + shared utilities for the 16 servers
hkask-capability OCAP delegation tokens
hkask-cli CLI — 21 subcommands + REPL host
hkask-api HTTP API, utoipa OpenAPI

Infrastructure

Crate Purpose
hkask-inference Inference router — 8 provider backends, 2-letter prefix routing, fusion, per-provider circuit breakers, fal.ai workflow DAGs, dynamic model discovery
hkask-communication Matrix transport, agent registry, 7R7 listener
hkask-condenser Context condensation engine
hkask-acp Agent Client Protocol — IDE integration
hkask-guard Content safety — mandatory LLM boundary scanning, OWASP LLM Top 10 aligned
hkask-repl Interactive REPL — slash commands, tab completion, fuzzy matching, TUI module (feature-gated)
hkask-forecast Superforecasting engine (Fermi decomposition, Bayesian update, Brier scoring)
hkask-git-cas Git content-addressable storage (BLAKE3 object store)
hkask-goal Goal specification and completion verification
hkask-identity Human identity & access control (HumanUser, OAuth, roles)
hkask-test-harness Test infrastructure (TestDb, TestWebId, mocks, strategies)
hkask-mcp-cloud-gateway Cloud MCP gateway for remote tool dispatch

Services

Crate Purpose
hkask-services-core Service-layer foundation — ServiceError, ServiceConfig, HkaskSettings
hkask-services-context AgentService context, Regulation runtime, cybernetic loops, storage guard
hkask-services-runtime Runtime services — text classification, provider intelligence, daemon
hkask-services-chat Chat session management and history
hkask-services-compose Style composition — exemplar retrieval, prose generation, centroid-distance voice validation
hkask-services-corpus Document corpus management and indexing
hkask-services-inference Inference provider intelligence and dispatch
hkask-services-kata-kanban Toyota Kata coaching/improvement + Kanban coordination
hkask-services-onboarding First-run and user onboarding
hkask-services-self-heal Autonomous self-healing loop
hkask-services-skill Skill discovery, publishing, hashing, auditing, bundle composition
hkask-services-wallet Gas budgeting, price feeds, Regulation integration

Wallet, Identity & Ledger

Crate Purpose
hkask-wallet rJoule wallet — self-custody deposits, API key issuance
hkask-ledger Double-entry accounting ledger (cost, crypto, securities)

Ontology Bridges

Crate Purpose
hkask-bridge-dublincore Dublin Core + BIBO + CiTO (bibliographic metadata, citations)

MCP Servers (16)

hkask-mcp-codegraph · hkask-mcp-communication · hkask-mcp-companies · hkask-mcp-condenser · hkask-mcp-curator · hkask-mcp-docproc · hkask-mcp-filesystem · hkask-mcp-kata-kanban · hkask-mcp-media · hkask-mcp-memory · hkask-mcp-regulation · hkask-mcp-replica · hkask-mcp-research · hkask-mcp-scenarios · hkask-mcp-skill · hkask-mcp-training

Current Metrics

Metric Value
Core crates 39
MCP servers 16
Workspace members (excl. fuzz) 55
Skills 52 PDCA loops (89 registry manifests, 391 Jinja2 templates)
Jinja2 templates 391 (WordAct + KnowAct + RenderAct; selection intelligence offloaded to the LLM)
Skill manifests 89 (FlowDef: select - populate - execute, convergence, gas budget)
CLI subcommands 21 (kask tui is the primary entry point)
Inference providers 8 (Cline, DeepInfra, fal.ai, KiloCode, Ollama, OpenRouter, Runpod, Together)
Codegraph MCP tools 11 (query, traverse, impact, analysis, context, structure, stats, reindex, feedback, embed, dead_code)
QA pipeline Fuzz triage, mutation analysis, autonomous script runner
Build / clippy / fmt / test / unused-deps All passing

Commands

The primary entry point is kask tui, which embeds the REPL inside a ratatui workspace. kask serve exposes the HTTP API; kask daemon runs the Unix-socket auth + Regulation monitor. The remaining subcommands are administrative (pod, mcp, sovereignty, git, backup, token, userpod, keystore, skill, doctor, onboard, settings, init, export, wallet, matrix, repair, deploy).

# Verification
cargo check --workspace
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
cargo fmt --check

# Dependency hygiene (nightly)
RUSTFLAGS="-D unused_crate_dependencies" cargo +nightly check --workspace

# Documentation health
bash docs/ci/verify-docs.sh
bash docs/ci/check-links.sh

Documentation

hKask follows the Diataxis documentation methodology — tutorials, how-to guides, reference, and explanation.5 The portal at docs/README.md is the canonical entry point.

Path Contents
AGENTS.md Agent operating guide — capability catalog, tooling policy, prohibitions
docs/README.md Documentation portal (Diataxis index)
docs/how-to/ Task-oriented guides: install, configure, bootstrap MCP, invoke skills, audit sovereignty
docs/reference/ API reference, skill registry, Regulation span registry, Magna Carta
docs/explanation/ Architecture decisions: hexagonal ports, Regulation loop, OCAP dispatch
docs/architecture/ ADRs, master architecture, provider/federation/database architecture
docs/specifications/DOCUMENTATION_STANDARDS.md Documentation standards — metadata, citations, diagrams, lifecycle
.github/workflows/ci.yml CI pipeline (fmt → clippy + unused-deps + build → test + doc → invariants)
.github/workflows/audit.yml Weekly dependency audit (cargo-deny + cargo-audit)

Design Philosophy

As simple as possible, but no simpler.

  • No silent draws on reserve — every change cited.
  • No hallucinations — all features traceable to spec.
  • No speculation — code not needed today is debt.
  • No ceremony — direct, technical, concise.

The loom and the thread:

Layer Technology Mutability
Hard (kernel) Rust Fixed, stable
Soft (material) YAML, Jinja2, Markdown Mutable, evolving (89 manifests, 391 templates)

Rust is the loom. YAML/Jinja2 is the thread. The users direct the weaving; the LLM renders the thread into action.

Logo & Brand

The Kask logo synthesizes four elements into a single mark:

Element Represents Visual form
The Kask (container) Typed container, governed surface Rectangular amphora with handles
Calligraphy (art) Human craft, temporal mark Varied stroke width, pressure-sensitive
Curator's eye (vision) Observation, governance, loyalty Almond eye with iris, pupil, reflection
Bitemporal shadow (perspective) Valid-time + transaction-time Offset shadow, reduced opacity

A simple container, drawn by hand, watching from within, remembering in two times.

Core principles: recognition < 400 ms · scalable 16 px–16 ft · monochrome-first · no gradients/effects. Full design principles → assets/LOGO-DESIGN-PRINCIPLES.md.

ℏKask - A Minimal Viable Container for Users and AI Tools - v0.31.0 Rust is the loom. YAML/Jinja2 is the thread. The userpod is the container.

Footnotes

  1. docs/architecture/core/hKask-architecture-master.md — "Primary user story" and "The Four Essential Patterns" (v0.31.0). The one-page synthesis is in § The Architecture — Four Essential Patterns above. ↩ ↩2

  2. docs/architecture/core/hKask-architecture-master.md § Pattern A - The Skills Model (WordAct / FlowDef / KnowAct / RenderAct; RenderAct is the non-inference render layer). ↩ ↩2 ↩3 ↩4

  3. Model Context Protocol specification; runtime via the rmcp crate. ↩ ↩2

  4. docs/reference/regulation-spans.md — reg.* span catalog and canonical namespaces. ↩

  5. Diátaxis documentation framework by Daniele Procida — four quadrants: tutorials, how-to guides, reference, explanation. ↩

About

No description, website, or topics provided.

Resources

Readme
MIT license
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages