@dikolab/kbdb 0.5.0 → 0.6.1

package/docs/goals/agents.md

@@ -1,751 +0,0 @@
-# Agents -- Delegatable AI Agent Personas
-
-*Named AI agent personas stored as knowledge base
-documents, each carrying a system prompt and an ordered
-list of skill references that a host AI can discover
-and delegate work to.*
-
-## Goal
-
-Agents are reusable AI agent persona definitions. Each
-agent has a persona (a system prompt that describes
-its role and behaviour) and an ordered list of skill
-references. A host AI agent can look up agents, retrieve
-their persona and skills, and delegate tasks to them.
-
-The motivation is composability: instead of encoding
-agent behaviour directly into application code, agent
-personas are stored in the knowledge base where they
-are discoverable, shareable, and independently
-updatable. The host AI decides how to use an agent
-definition -- the knowledge base does not execute
-agents.
-
-Agents are stored as knowledge base **documents** (not
-sections) with `type = 'agent'`. This distinguishes
-them from regular documents while reusing the same
-document manifest infrastructure. Skills are referenced
-by kbid, not by name, so that skill updates (which
-produce new kbids) make dangling references visible
-rather than silently binding to the wrong version.
-
-See [Skills](skills.md) for the skill definition
-format that agents reference.
-
-## Agent Document Schema
-
-### Agent Manifest Format
-
-Agents are persisted as TOML document manifests in
-`.kbdb/documents/{docid}.toml`. The format extends the
-standard document manifest with an `[agent]` table and
-`[[sections]]` entries that list skill kbids:
-
-```toml
-[document]
-docid = "agent-code-reviewer"
-title = "Code Reviewer Agent"
-type = "agent"
-created_at = "2026-06-19T10:00:00Z"
-
-[agent]
-description = "Reviews code for bugs, style, and best
-   practices"
-persona = """You are an expert code reviewer.
-You focus on correctness, readability, and
-maintainability. You provide actionable feedback
-with specific suggestions."""
-
-[[sections]]
-kbid = "abc123def456abc123def456ab"
-position = 0
-
-[[sections]]
-kbid = "def456abc123def456abc123de"
-position = 1
-```
-
-Key conventions:
-
-- `[document].type = "agent"` identifies this manifest
-  as an agent. Documents without a `type` field are
-  regular documents (backward-compatible).
-- `[document].title` is the display name of the agent
-  and is used as the prompt name in `prompts/list`.
-- `[agent].description` is the short description
-  surfaced in `prompts/list`.
-- `[agent].persona` is the full system prompt text
-  returned by `prompts/get`.
-- `[[sections]]` entries list skill kbids in ascending
-  `position` order. These are the skills the agent is
-  equipped with.
-
-### AgentDefinition type
-
-The full definition of an agent as returned by
-`agent-get` and `prompts/get`:
-
-```typescript
-interface AgentDefinition {
-   /** Document ID of the agent manifest. */
-   readonly docid: string;
-   /** Display name of the agent. */
-   readonly name: string;
-   /** Short description of the agent's purpose. */
-   readonly description: string;
-   /** System prompt text (persona). */
-   readonly persona: string;
-   /** Ordered list of resolved skill references. */
-   readonly skills: readonly {
-      /** Skill kbid. */
-      readonly kbid: string;
-      /** Skill name, or null when the skill is missing. */
-      readonly name: string | null;
-      /** Position index (0-based). */
-      readonly position: number;
-   }[];
-}
-```
-
-## Storage
-
-### Document Manifest File Format
-
-Agent manifests use the `.toml` extension and live in
-`.kbdb/documents/`. The file name is the `docid` with
-`.toml` appended:
-
-```
-.kbdb/
-  documents/
-    agent-code-reviewer.toml
-    agent-research-assistant.toml
-```
-
-The `docid` is chosen by the caller at creation time
-(supplied as `--name` on the CLI or `name` in the MCP
-tool call). It must be unique among all document IDs.
-Conventionally it is the agent name in kebab-case.
-
-Unlike sections, agent manifests are **not**
-content-addressed. The `docid` is stable across
-persona or skill-list changes. Updating an agent
-overwrites its manifest file in place.
-
-### Skill References
-
-Skills are referenced in `[[sections]]` entries by
-their kbid, ordered by `position`:
-
-- **kbid ordering.** The `position` field is an integer
-  starting at 0. Skills are presented to the host AI
-  in position order. The order is significant -- it
-  controls the sequence in which skills appear in the
-  `prompts/get` response.
-- **Validation at creation time.** When an agent is
-  created, all supplied skill kbids are validated to
-  exist as sections with `sectionType = 'skill'`. An
-  invalid kbid causes the create operation to fail with
-  an `INVALID_PARAMS` error.
-- **No re-validation on read.** When an agent is
-  retrieved, skill kbids are looked up but a missing
-  kbid is not an error. It appears as a dangling
-  reference with `name: null` (see
-  [Skill Resolution](#skill-resolution)).
-
-### Relationship Model
-
-The relationship between agents and skills is
-many-to-many:
-
-- One agent may reference many skills (its toolkit).
-- One skill may be referenced by many agents (shared
-  capability).
-
-Agents reference skills by kbid only. No inverse index
-tracks which agents reference a given skill. This means:
-
-- Deleting a skill does not cascade to agents. Agent
-  manifests retain the kbid as a dangling reference.
-- Deleting an agent does not delete any skill sections.
-- There is no circular reference possible -- agents
-  cannot reference other agents.
-
-## MCP Surface
-
-### Agents as MCP Prompts
-
-Agents appear in the MCP prompts protocol alongside
-skills. To distinguish agents from skills in
-`prompts/list`, agent prompt names use an `agent:`
-prefix followed by the agent's `docid`:
-
-```
-agent:code-reviewer
-agent:research-assistant
-```
-
-This prefix convention allows MCP clients to
-distinguish skill prompts (no prefix) from agent
-prompts (`agent:` prefix) without additional metadata.
-See [MCP](mcp.md) for the full prompt protocol
-specification.
-
-### prompts/list (agent entries)
-
-Agents appear in the `prompts/list` response alongside
-skill entries. Agent entries have an empty `arguments`
-array (agents accept no per-invocation arguments):
-
-```json
-{
-   "prompts": [
-      {
-         "name": "summarize-document",
-         "description": "Summarize a document into key
-            points with configurable depth",
-         "arguments": [
-            {
-               "name": "docid",
-               "description": "Document identifier",
-               "required": true
-            }
-         ]
-      },
-      {
-         "name": "agent:code-reviewer",
-         "description": "Reviews code for bugs, style,
-            and best practices",
-         "arguments": []
-      }
-   ]
-}
-```
-
-### prompts/get (agent retrieval)
-
-When `prompts/get` is called with an `agent:` prefixed
-name, the response contains two messages:
-
-1. **First message** (role `assistant`): the agent's
-   persona text. This becomes the system prompt for the
-   delegated agent.
-2. **Second message** (role `user`): a rendered listing
-   of the agent's available skills with their names and
-   descriptions.
-
-Request:
-```json
-{
-   "name": "agent:code-reviewer",
-   "arguments": {}
-}
-```
-
-Response:
-```json
-{
-   "messages": [
-      {
-         "role": "assistant",
-         "content": {
-            "type": "text",
-            "text": "You are an expert code reviewer.\nYou
-               focus on correctness, readability, and
-               maintainability. You provide actionable
-               feedback with specific suggestions."
-         }
-      },
-      {
-         "role": "user",
-         "content": {
-            "type": "text",
-            "text": "You have access to the following
-               skills:\n\n1. summarize-document --
-               Summarize a document into key points with
-               configurable depth\n2. code-review --
-               Review code and provide structured
-               feedback"
-         }
-      }
-   ]
-}
-```
-
-The skill listing in the second message is ordered by
-`position`. Dangling skill references (missing kbid)
-are omitted from the listing silently.
-
-## MCP Tools
-
-### agent-create
-
-Create a new agent in the knowledge base.
-
-| Parameter     | Type     | Required | Description                   |
-|---------------|----------|----------|-------------------------------|
-| `name`        | string   | yes      | Agent name / docid (kebab-case)|
-| `description` | string   | yes      | Short description of the agent|
-| `persona`     | string   | yes      | System prompt text            |
-| `skills`      | string[] | yes      | Ordered skill kbid list       |
-
-**Returns:** Agent creation result:
-
-```json
-{
-   "docid": "agent-code-reviewer",
-   "name": "code-reviewer",
-   "skills": [
-      "abc123def456abc123def456ab",
-      "def456abc123def456abc123de"
-   ]
-}
-```
-
-Fails with `INVALID_PARAMS` when any skill kbid in
-`skills` does not exist or does not have
-`sectionType = 'skill'`.
-
-Maps to client method: `client.createDocument({ type: 'agent', ... })`
-
-### agent-list
-
-List all agents stored in the knowledge base.
-
-No parameters.
-
-**Returns:** JSON array of agent summary objects:
-
-```json
-[
-   {
-      "docid": "agent-code-reviewer",
-      "name": "Code Reviewer Agent",
-      "description": "Reviews code for bugs, style,
-         and best practices",
-      "skillCount": 2
-   }
-]
-```
-
-Empty array when no agents are stored.
-
-Maps to client method: `client.listDocumentsByType('agent')`
-
-### agent-get
-
-Retrieve the full definition of an agent by docid.
-
-| Parameter | Type   | Required | Description            |
-|-----------|--------|----------|------------------------|
-| `docid`   | string | yes      | Agent document ID      |
-
-**Returns:** Full `AgentDefinition` with resolved
-skills:
-
-```json
-{
-   "docid": "agent-code-reviewer",
-   "name": "Code Reviewer Agent",
-   "description": "Reviews code for bugs, style, and
-      best practices",
-   "persona": "You are an expert code reviewer.\nYou
-      focus on correctness, readability, and
-      maintainability.",
-   "skills": [
-      {
-         "kbid": "abc123def456abc123def456ab",
-         "name": "summarize-document",
-         "position": 0
-      },
-      {
-         "kbid": "def456abc123def456abc123de",
-         "name": "code-review",
-         "position": 1
-      }
-   ]
-}
-```
-
-Dangling kbids appear with `"name": null`:
-
-```json
-{
-   "kbid": "abc123def456abc123def456ab",
-   "name": null,
-   "position": 0
-}
-```
-
-Maps to client method: `client.getDocument(docid)` +
-`client.getSection(kbid)` per skill reference.
-
-### agent-delete
-
-Remove an agent from the knowledge base by docid.
-
-| Parameter | Type   | Required | Description            |
-|-----------|--------|----------|------------------------|
-| `docid`   | string | yes      | Agent document ID      |
-
-**Returns:** Removal confirmation:
-
-```json
-{
-   "docid": "agent-code-reviewer",
-   "removed": true
-}
-```
-
-When the docid does not exist, `removed` is `false`
-and no error is thrown. Skill sections referenced by
-the agent are **not** deleted.
-
-Maps to client method: `client.removeDocument(docid)`
-
-## CLI Commands
-
-### kbdb agent create
-
-```
-kbdb agent create [options] --name <name>
-   --persona <file|-> --skills <kbid,...>
-```
-
-Create a new agent in the knowledge base.
-
-**Options:**
-
-| Option             | Short | Required | Description                    |
-|--------------------|-------|----------|--------------------------------|
-| `--name <n>`       |       | yes      | Agent name / docid (kebab-case)|
-| `--description`    |       | no       | Short agent description        |
-| `--persona <file>` |       | yes      | Persona file or `-` for stdin  |
-| `--skills <kbids>` |       | yes      | Comma-separated skill kbids    |
-| `--db <path>`      |       | no       | Path to .kbdb directory        |
-
-**Behaviour:**
-
-Reads the persona text from the specified file path or
-from stdin when `--persona -` is given. Parses
-`--skills` as a comma-separated list of kbids,
-validating each against the knowledge base. Creates a
-TOML agent manifest and stores it in
-`.kbdb/documents/`.
-
-**Output:**
-
-```json
-{
-   "docid": "agent-code-reviewer",
-   "name": "code-reviewer",
-   "skills": [
-      "abc123def456abc123def456ab",
-      "def456abc123def456abc123de"
-   ]
-}
-```
-
-**Delegation chain:**
-```
-src/cli.ts  parseArgs()
-  -> findDb() / promptUser() / runInit()
-  -> createWorkerClient({ contextPath })
-  -> versionGate(client, dbDir)
-  -> dispatchCommand(client, options)
-       -> runAgentCreate(client, options)
-            -> client.createDocument({
-                 type: 'agent',
-                 docid: name,
-                 title, description,
-                 persona,
-                 skills: kbidArray })
-                 -> IPC -> worker daemon
-                      -> kb-worker.wasm
-                           -> fs-database.wasm (write)
-```
-
-**Examples:**
-
-```sh
-# Create an agent from a persona file
-kbdb agent create --name code-reviewer \
-   --description "Reviews code for quality" \
-   --persona ./personas/code-reviewer.txt \
-   --skills abc123def456abc123def456ab,\
-def456abc123def456abc123de
-
-# Create an agent reading persona from stdin
-cat ./personas/assistant.txt | kbdb agent create \
-   --name research-assistant \
-   --persona - \
-   --skills abc123def456abc123def456ab
-
-# Specify database directory explicitly
-kbdb agent create --name my-agent \
-   --persona ./persona.txt \
-   --skills abc123def456abc123def456ab \
-   --db /path/to/project
-```
-
-### kbdb agent list
-
-```
-kbdb agent list [options]
-```
-
-List all agents stored in the knowledge base.
-
-**Options:**
-
-| Option        | Short | Required | Description             |
-|---------------|-------|----------|-------------------------|
-| `--db <path>` |       | no       | Path to .kbdb directory |
-
-**Output:**
-
-JSON array of agent summary objects:
-
-```json
-[
-   {
-      "docid": "agent-code-reviewer",
-      "name": "Code Reviewer Agent",
-      "description": "Reviews code for bugs, style,
-         and best practices",
-      "skillCount": 2
-   }
-]
-```
-
-Empty array when no agents are stored.
-
-**Delegation chain:**
-```
-src/cli.ts  parseArgs()
-  -> findDb() / promptUser() / runInit()
-  -> createWorkerClient({ contextPath })
-  -> versionGate(client, dbDir)
-  -> dispatchCommand(client, options)
-       -> runAgentList(client, options)
-            -> client.listDocumentsByType('agent')
-                 -> IPC -> worker daemon
-                      -> kb-worker.wasm
-                           -> fs-database.wasm (scan)
-```
-
-**Examples:**
-
-```sh
-# List all agents
-kbdb agent list
-
-# List agents from a specific database
-kbdb agent list --db /path/to/project
-```
-
-### kbdb agent get
-
-```
-kbdb agent get [options] <docid>
-```
-
-Retrieve the full definition of an agent by its docid,
-including resolved skill names.
-
-**Arguments:**
-
-- `<docid>` -- the agent document ID. Required.
-
-**Options:**
-
-| Option        | Short | Required | Description             |
-|---------------|-------|----------|-------------------------|
-| `--db <path>` |       | no       | Path to .kbdb directory |
-
-**Output:**
-
-Full `AgentDefinition` with resolved skills. Dangling
-skill references appear with `"name": null`.
-
-```json
-{
-   "docid": "agent-code-reviewer",
-   "name": "Code Reviewer Agent",
-   "description": "Reviews code for bugs, style, and
-      best practices",
-   "persona": "You are an expert code reviewer...",
-   "skills": [
-      {
-         "kbid": "abc123def456abc123def456ab",
-         "name": "summarize-document",
-         "position": 0
-      }
-   ]
-}
-```
-
-**Delegation chain:**
-```
-src/cli.ts  parseArgs()
-  -> findDb() / promptUser() / runInit()
-  -> createWorkerClient({ contextPath })
-  -> versionGate(client, dbDir)
-  -> dispatchCommand(client, options)
-       -> runAgentGet(client, options)
-            -> client.getDocument(docid)
-                 -> IPC -> worker daemon
-                      -> kb-worker.wasm
-                           -> fs-database.wasm (fetch)
-            -> client.getSection(kbid) per skill
-                 -> IPC -> worker daemon (resolve names)
-```
-
-**Examples:**
-
-```sh
-# Get an agent by docid
-kbdb agent get agent-code-reviewer
-
-# Get from a specific database
-kbdb agent get agent-code-reviewer \
-   --db /path/to/project
-```
-
-### kbdb agent delete
-
-```
-kbdb agent delete [options] <docid>
-```
-
-Remove an agent from the knowledge base. Skill
-sections referenced by the agent are not deleted.
-
-**Arguments:**
-
-- `<docid>` -- the agent document ID. Required.
-
-**Options:**
-
-| Option        | Short | Required | Description             |
-|---------------|-------|----------|-------------------------|
-| `--db <path>` |       | no       | Path to .kbdb directory |
-
-**Output:**
-
-```json
-{
-   "docid": "agent-code-reviewer",
-   "removed": true
-}
-```
-
-**Delegation chain:**
-```
-src/cli.ts  parseArgs()
-  -> findDb() / promptUser() / runInit()
-  -> createWorkerClient({ contextPath })
-  -> versionGate(client, dbDir)
-  -> dispatchCommand(client, options)
-       -> runAgentDelete(client, options)
-            -> client.removeDocument(docid)
-                 -> IPC -> worker daemon
-                      -> kb-worker.wasm
-                           -> fs-database.wasm (delete)
-```
-
-**Examples:**
-
-```sh
-# Delete an agent by docid
-kbdb agent delete agent-code-reviewer
-
-# Delete from a specific database
-kbdb agent delete agent-code-reviewer \
-   --db /path/to/project
-```
-
-## Skill Resolution
-
-When `agent-get` or `prompts/get` retrieves an agent,
-each kbid in the `[[sections]]` list is resolved to
-its skill name:
-
-1. Look up the kbid in the section store via
-   `client.getSection(kbid)`.
-2. If found and `sectionType === 'skill'`, read the
-   `title` field (which equals the skill `name`).
-   Return `{ kbid, name: title, position }`.
-3. If the kbid does not exist (skill was deleted),
-   return `{ kbid, name: null, position }`. This is a
-   warning condition, not an error.
-4. If the kbid exists but `sectionType !== 'skill'`
-   (non-skill section was referenced), the `name`
-   field is set to the section `title` and a warning
-   annotation is included in the response.
-
-The full `AgentDefinition` is returned in all cases.
-Callers can detect dangling references by checking
-for `name: null` in the `skills` array.
-
-## Edge Cases
-
-**Agent with zero skills.** An agent with an empty
-`skills` list (or `--skills` not supplied) is a
-persona-only agent. This is allowed. It is useful when
-the agent persona is standalone and does not need
-toolkit skills.
-
-**Agent referencing a non-existent skill.** When a
-skill is deleted after the agent has been created, the
-agent manifest retains the kbid. On retrieval,
-`agent-get` returns the dangling kbid with
-`"name": null`. The agent document is not modified.
-The host AI receives a signal that a skill is missing
-and can decide how to proceed.
-
-**Duplicate agent names.** Two agents may share the
-same `--name` value if they are created with different
-docids. However, because the docid is derived from the
-`name` option, duplicate `--name` values at creation
-time will overwrite the existing manifest unless the
-caller uses a unique docid. This behaviour is
-intentional -- updating an agent reuses the same docid.
-
-**Agent referencing non-skill sections.** The
-`[[sections]]` kbid list is not validated for
-`sectionType` at creation time. If a non-skill kbid is
-included, it is stored and returned during resolution
-with a best-effort name. This is not recommended but
-not blocked.
-
-**Deleting an agent.** Only the agent document manifest
-(`.kbdb/documents/{docid}.toml`) is removed. Skill
-sections remain in the knowledge base and are
-unaffected. Other agents referencing the same skills
-continue to work normally.
-
-## Design Constraints
-
-- **Agents are documents, not a separate entity type.**
-  Agents reuse the document manifest infrastructure
-  with `type = 'agent'`. No new storage schema,
-  separate directory, or index is introduced.
-- **Skills are referenced by kbid, not by name.**
-  Using kbids makes skill updates visible as dangling
-  references rather than silently binding to a
-  different skill version. The caller must look up the
-  kbid of a skill before creating an agent.
-- **No agent versioning.** Updating an agent means
-  writing a new manifest over the existing docid. The
-  docid is stable; there is no version history.
-- **No agent execution.** Agents are definitions only.
-  The knowledge base stores and surfaces them; the
-  host AI decides how to instantiate and use them.
-  The `prompts/get` response provides the persona and
-  skill listing -- execution is entirely the host
-  AI's responsibility.
-- **No circular references.** Agents reference skills
-  only. Skills do not reference other skills or agents.
-  An agent cannot reference another agent. There is no
-  cycle possible in the reference graph.