# Kapsules: harnesses and agents

A Kapsule is a HARNESS, not a plain agent: a model (local, API, or a coding CLI) wrapped with its own persona, tool allowlist, skills, permission policy, memory, schedule, chat threads and jobs, in one reviewable folder.

A Kapsule = a folder at <data>/kapsules/<name>/ with one kapsule.json. It can carry agents (persona+model+tools+schedule; one, or several via "agents": []), skills, and/or its own MCP tool server. Drop it in — mounts live, no restart. Each kapsule gets a private memory DB, a read-only home, a read-write <name>_workspace/, its own threads, schedule table and Jobs view.

## A harness, not just an agent
The harness fixes: model (which engine thinks) · persona + skills (how it works) · tools (what it may touch; a CLI model keeps its native tools alongside Kaptain's) · permissions (ask/sandbox/auto/full + trusted targets) · memory · schedule + standing task · threads + Jobs.
"Can bring in workers" OFF (default) = one persona, one toolset, one job — the normal case. ON = the kapsule may split a job across workers it creates; each worker gets only the tools its part needs; workers share each other's output; a worker that provably completes its job is kept under the kapsule's name and reused. One tab, one file format, one permission model either way.

## The two kinds of agents
- KDKA — Kaptain Defined Kapsule Agent: declared in kapsule.json; persistent; named by you; callable by name from chat, schedule, CLI and other agents; memory across runs when enabled; bounded by the kapsule's approval mode + allowlist.
- KDDA — Kapsule Defined Dynamic Agent: a worker the kapsule mints for one role while a job runs; born for a task; kept only if the job completed with evidence; role-shaped, earns an identity by succeeding (appears under Jobs as a proven worker); shares the job's board; NEVER wider than whatever minted it.
Alike in capability; the difference is lifetime and ownership (keep vs. created by the work). Same never-widen ceiling. UI words: "your kapsules" and "the workers they created".

## Create one in the UI
Kapsules tab > New kapsule: Name; one-line Purpose (+ "Generate persona" drafts the system prompt); Model (default: engine default); optional Tools allowlist (empty = full enabled catalog, approval-gated); Schedule + time (browser timezone shown); Standing task (a schedule without a task is refused); Create.

## Settings that matter
- Permissions: scheduled runs have nobody to answer prompts. Ask stops at the first risky step; Full access is the only mode that runs a CLI-harness kapsule unattended. Per kapsule (travels with the file) or inherit the model's.
- Remember previous runs: OFF by default — scheduled jobs start fresh from the task. Enable only when a job builds on its own last answer; "Reset run memory" recovers from a poisoned thread.
- Trusted scopes: pre-approve TARGETS, never tools — `path:/x rw`, `mcp:<server>`, `host:<domain>`. Approval mode still sets the ceiling.
- Can bring in workers: the harness switch. Off = does each job itself; On = may split a job across workers it creates; a worker is kept only with evidence.
- Delegation: may this kapsule call other kapsules and its workers. Default on when workers are on or an agent tool is granted.

## Schedules
- `daily@10:00` — every day at 10:00 in the kapsule's timezone
- `every 6h@08:00` — anchored interval, deterministic wall-clock slots
- `30m` / `1h` / `24h` — plain interval; empty = on demand
`schedule_tz` is IANA (e.g. America/Toronto). Each occurrence runs at most once ever; results persist.

## kapsule.json (core agent fields)
name, enabled, agent{ name, system (persona), model (""=default), tools[] (empty=full catalog), approval_mode (ask|sandbox|auto|full|""=inherit), schedule, schedule_tz, task, memory (default off), skills[], trusted_scopes[], swarm (= Can bring in workers), max_rounds, delegation{mode, allow_agents[]} }; composite form: agents[] instead of agent; use_kapsule_tools; top-level skills[] and mcp. Single-agent files stay valid.

## Jobs and proven workers
Per kapsule: Jobs lists the jobs split across workers and the workers that earned a place. Overview row: last run + result, review verdict, memory count, workers on/off. Results land under Jobs and in the bell; every worker turn is traceable in BlackBox.

## Run, chat, invoke (CLI)
kaptain agent list | run <name> "<task>" | chat <name> "<msg>" | history <name> | enable|disable <name> | set-model <name> <model>

## Agents calling agents
Off by default; opt in per kapsule via the delegation block. MCP-connected CLIs get agent_list / invoke_agent. Sub-agents are callable as tools named agent_<name> where granted.