toolnexus 0.9.5 → 0.10.0

package/README.md

@@ -347,7 +347,37 @@ const res = await tk.execute(name, args)   // → { output, isError, metadata }
 | **HTTP / REST** | `httpTool({...})` — an endpoint becomes a tool, `${ENV}` headers |
 
 All appear as one uniform `Tool` in `tk.tools()`. Built-ins are a fifth source; remote A2A agents
-a sixth.
+a sixth; in-process **sub-agents** a seventh (below).
+
+## Sub-agents & teams
+
+An **Agent is a Tool**: a system prompt × a scoped toolkit view × the client loop. One agent
+delegates to another **in-process** via one `task` tool — isolated context, one result back,
+tokens rolled up, hierarchical budgets, durable suspension (`SPEC.md §7D`). The surface lives in
+the **`agents`** namespace (never the A2A `agent` above):
+
+```ts
+import { agents } from "toolnexus"
+
+const explore = agents.agent("explore", {
+  does: "read-only research",
+  uses: { tools: [lookup] },              // this child sees ONLY these tools
+})
+const coder = agents.agent("coder", {
+  does: "implements changes",
+  soulFile: "./AGENTS.md",                // identity file → system prompt
+  team: [explore],                        // team = the task tool's only targets; no team ⇒ no task tool
+  budget: { maxTokens: 10_000 },
+})
+
+const r = await coder.run("fix the failing test", {
+  llm: { baseUrl: "https://openrouter.ai/api/v1", style: "openai", model: "openai/gpt-4o-mini" },
+})
+console.log(r.status, r.text, r.totalTokens)   // "done" | "incomplete" | "pending", final text, tree-wide tokens
+```
+
+`agents.asTool(...)` drops an agent back into `extraTools` for the classic API. Full guide:
+[Sub-agents & teams](https://muthuishere.github.io/toolnexus/subagents/).
 
 ## API
 

package/dist/agents/agent.d.ts

@@ -0,0 +1,60 @@
+import type { Answer, Request, Tool } from "../types.js";
+import { AgentRuntime, type AgentDef, type Budget, type RuntimeOptions, type TaskResult } from "./runtime.js";
+/** The declarative agent spec (§7D Level-1 surface). */
+export interface AgentSpec {
+    /** Required routing description — what a delegating model sees. */
+    does: string;
+    /** The toolkit VIEW for this agent (scoping is the security model). */
+    uses?: {
+        tools?: Tool[];
+    };
+    /** Identity: inline soul text (becomes the system prompt). */
+    soul?: string;
+    /** Path form of `soul` — read when the registry is built. */
+    soulFile?: string;
+    /** Declaring agents here IS the subagent wiring: they become the `task`
+     * tool's only reachable targets. No team ⇒ no `task` tool. */
+    team?: Agent[];
+    budget?: Budget;
+    /** Model id; default "inherit" (the runtime's `llm.model`). */
+    model?: string;
+    /** §10 interpreter authority for this agent's subtree. */
+    waitFor?: (request: Request) => Promise<Answer>;
+    onSpawn?: AgentDef["onSpawn"];
+    onClose?: AgentDef["onClose"];
+}
+/** Runtime options for a one-shot `run`/`asTool` (the registry is derived). */
+export type AgentRunOptions = Omit<RuntimeOptions, "registry">;
+/** A one-shot run's result, with the runtime attached for durable resume. */
+export interface AgentRunResult extends TaskResult {
+    /** The runtime that ran this agent — call `runtime.resume(answer)` after a
+     * `status:"pending"` result to continue from the checkpoint. */
+    runtime: AgentRuntime;
+}
+export declare class Agent {
+    readonly name: string;
+    readonly spec: AgentSpec;
+    constructor(name: string, spec: AgentSpec);
+    /**
+     * Collect this agent plus its transitive team graph into a runtime registry —
+     * the registry IS the reachable graph; unreachable agents are not present.
+     */
+    registry(acc?: Record<string, AgentDef>): Record<string, AgentDef>;
+    /** Build a runtime scoped to this agent's reachable team graph. */
+    createRuntime(opts?: AgentRunOptions): AgentRuntime;
+    /**
+     * Level 1: one-shot. Builds a runtime, runs this agent to completion, and tears
+     * the tree down — unless the run suspends durably (`status:"pending"`), in which
+     * case the tree stays parked and `result.runtime.resume(answer)` continues it.
+     */
+    run(prompt: string, opts?: AgentRunOptions): Promise<AgentRunResult>;
+    /**
+     * The bridge: an Agent IS a Tool. Drop the result into the classic API's
+     * `extraTools`; the agent's own loop runs in isolation and the classic run
+     * receives one tool result carrying only the final text + metadata
+     * `{agent, turns, totalTokens}`.
+     */
+    asTool(opts?: AgentRunOptions): Tool;
+}
+/** The one new noun: define an agent. */
+export declare function agent(name: string, spec: AgentSpec): Agent;

package/dist/agents/agent.js

@@ -0,0 +1,99 @@
+/**
+ * Level-1 subagent surface — SPEC.md §7D.
+ *
+ * One new noun: `agent(name, spec)`. An Agent is (identity/system prompt × a
+ * filtered toolkit view × the shipped client loop), and — the §7A/§7B axiom
+ * completed locally — an Agent IS a Tool: `asTool()` bridges it into the classic
+ * API's `extraTools`; `run()` executes one-shot against a private runtime.
+ * Everything compiles down to the six host verbs in runtime.ts.
+ */
+import fs from "node:fs";
+import { defineTool } from "../native.js";
+import { AgentRuntime, isVerbError } from "./runtime.js";
+export class Agent {
+    name;
+    spec;
+    constructor(name, spec) {
+        this.name = name;
+        this.spec = spec;
+    }
+    /**
+     * Collect this agent plus its transitive team graph into a runtime registry —
+     * the registry IS the reachable graph; unreachable agents are not present.
+     */
+    registry(acc = {}) {
+        if (acc[this.name])
+            return acc;
+        let soul = this.spec.soul ?? "";
+        if (this.spec.soulFile)
+            soul = fs.readFileSync(this.spec.soulFile, "utf8");
+        acc[this.name] = {
+            name: this.name,
+            does: this.spec.does,
+            soul,
+            model: this.spec.model ?? "inherit",
+            tools: this.spec.uses?.tools,
+            team: (this.spec.team ?? []).map((a) => a.name),
+            budget: this.spec.budget,
+            waitFor: this.spec.waitFor,
+            onSpawn: this.spec.onSpawn,
+            onClose: this.spec.onClose,
+        };
+        for (const t of this.spec.team ?? [])
+            t.registry(acc);
+        return acc;
+    }
+    /** Build a runtime scoped to this agent's reachable team graph. */
+    createRuntime(opts = {}) {
+        return new AgentRuntime({ ...opts, registry: this.registry() });
+    }
+    /**
+     * Level 1: one-shot. Builds a runtime, runs this agent to completion, and tears
+     * the tree down — unless the run suspends durably (`status:"pending"`), in which
+     * case the tree stays parked and `result.runtime.resume(answer)` continues it.
+     */
+    async run(prompt, opts = {}) {
+        const runtime = this.createRuntime(opts);
+        const h = runtime.spawn(runtime.root, this.name);
+        if (isVerbError(h)) {
+            return { text: h.error, isError: true, status: "error", turns: 0, totalTokens: 0, runtime };
+        }
+        const woke = runtime.wake(h, prompt);
+        if (!woke.ok) {
+            return { ...(await runtime.wait(h)), runtime };
+        }
+        const r = await runtime.wait(h);
+        if (r.status !== "pending")
+            await runtime.close(runtime.root);
+        return { ...r, runtime };
+    }
+    /**
+     * The bridge: an Agent IS a Tool. Drop the result into the classic API's
+     * `extraTools`; the agent's own loop runs in isolation and the classic run
+     * receives one tool result carrying only the final text + metadata
+     * `{agent, turns, totalTokens}`.
+     */
+    asTool(opts = {}) {
+        return defineTool({
+            name: this.name,
+            description: this.spec.does,
+            inputSchema: {
+                type: "object",
+                properties: { prompt: { type: "string", description: "The task for this agent" } },
+                required: ["prompt"],
+            },
+            run: async (args) => {
+                const r = await this.run(String(args.prompt), opts);
+                return {
+                    output: r.text,
+                    isError: r.isError,
+                    metadata: { agent: this.name, turns: r.turns, totalTokens: r.totalTokens },
+                };
+            },
+        });
+    }
+}
+/** The one new noun: define an agent. */
+export function agent(name, spec) {
+    return new Agent(name, spec);
+}

package/dist/agents/compaction.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Context compaction (SPEC.md §7F) — keep a long-lived agent under budget.
+ *
+ * A long-running agent grows its transcript until it overflows the model's window.
+ * `compactor(opts)` returns a **`beforeLLM` hook** (§8) that summarizes the older
+ * transcript and keeps a recent tail. It rides the existing seam: the client loop
+ * applies a `beforeLLM` message rewrite by *replacing* the working transcript, and
+ * that array flows on into `RunResult.messages` and the `ConversationStore`. So
+ * compaction is a pure `messages → messages` helper and adds **no loop behavior** —
+ * it is the canonical use of the §8 `beforeLLM` hook.
+ *
+ * Invariants (SPEC §7F):
+ *   1. At/below `maxTokens` the hook is a **no-op** — it returns nothing and the run
+ *      is byte-identical to a run with no compactor.
+ *   2. **Tool-pair safety** — the retained tail always begins at a `user` turn, so no
+ *      `tool` message is ever orphaned from the `assistant` carrying its `tool_call_id`.
+ *   3. The **leading system prompt** (identity / soul / skills) is preserved verbatim;
+ *      only the body between it and the tail is summarized.
+ *
+ *   import { agents } from "toolnexus"
+ *   const client = createClient({
+ *     …,
+ *     hooks: { beforeLLM: agents.compactor({ maxTokens: 120_000, summarize }) },
+ *   })
+ */
+/**
+ * A chat message in the working transcript. Structural and provider-neutral — only the
+ * fields compaction reasons about are named; anything else on the message is carried
+ * through untouched.
+ */
+export interface Message {
+    role: string;
+    content?: unknown;
+    tool_calls?: unknown[];
+    tool_call_id?: string;
+    [key: string]: unknown;
+}
+/**
+ * Cheap, deterministic token estimate: `ceil(chars/4)` over each message's JSON
+ * serialization, summed. This is an *estimator*, not a tokenizer — exactness is the
+ * host's call. Override via `CompactorOptions.countTokens` for a real tokenizer.
+ */
+export declare function estimateTokens(messages: Message[]): number;
+/** Options for {@link compactor}. */
+export interface CompactorOptions {
+    /** Compact only when the transcript estimate exceeds this; at/below ⇒ no-op. */
+    maxTokens: number;
+    /** Keep at least this many tokens of the most recent tail. Default `maxTokens/2`. */
+    keepTail?: number;
+    /** Produce a summary of the older messages. MAY call an LLM (async). Required. */
+    summarize: (older: Message[]) => Promise<string> | string;
+    /** Token estimator; default `ceil(chars/4)` summed over messages. */
+    countTokens?: (messages: Message[]) => number;
+    /**
+     * When set, inject a pre-compact system reminder telling the model to persist
+     * durable facts via the §7E `memory` tool before the head is summarized. Off by
+     * default. Composes with the memory builtin.
+     */
+    flushToMemory?: boolean;
+}
+/** The event a `beforeLLM` hook receives (§8). */
+export interface BeforeLLMEvent {
+    messages: Message[];
+    tools: unknown[];
+    model: string;
+    turn: number;
+}
+/**
+ * Build a `beforeLLM` hook (§8) that compacts the transcript once it exceeds
+ * `maxTokens`. Below budget it returns nothing (a byte-identical no-op); above it, it
+ * replaces the transcript with `[leading system prompt, summary system message,
+ * (flush reminder?), …recent tail]`, splitting at a clean `user` boundary so tool
+ * groups are never broken.
+ */
+export declare function compactor(opts: CompactorOptions): (ev: BeforeLLMEvent) => Promise<{
+    messages: Message[];
+} | undefined>;

package/dist/agents/compaction.js

@@ -0,0 +1,96 @@
+/**
+ * Context compaction (SPEC.md §7F) — keep a long-lived agent under budget.
+ *
+ * A long-running agent grows its transcript until it overflows the model's window.
+ * `compactor(opts)` returns a **`beforeLLM` hook** (§8) that summarizes the older
+ * transcript and keeps a recent tail. It rides the existing seam: the client loop
+ * applies a `beforeLLM` message rewrite by *replacing* the working transcript, and
+ * that array flows on into `RunResult.messages` and the `ConversationStore`. So
+ * compaction is a pure `messages → messages` helper and adds **no loop behavior** —
+ * it is the canonical use of the §8 `beforeLLM` hook.
+ *
+ * Invariants (SPEC §7F):
+ *   1. At/below `maxTokens` the hook is a **no-op** — it returns nothing and the run
+ *      is byte-identical to a run with no compactor.
+ *   2. **Tool-pair safety** — the retained tail always begins at a `user` turn, so no
+ *      `tool` message is ever orphaned from the `assistant` carrying its `tool_call_id`.
+ *   3. The **leading system prompt** (identity / soul / skills) is preserved verbatim;
+ *      only the body between it and the tail is summarized.
+ *
+ *   import { agents } from "toolnexus"
+ *   const client = createClient({
+ *     …,
+ *     hooks: { beforeLLM: agents.compactor({ maxTokens: 120_000, summarize }) },
+ *   })
+ */
+/**
+ * Cheap, deterministic token estimate: `ceil(chars/4)` over each message's JSON
+ * serialization, summed. This is an *estimator*, not a tokenizer — exactness is the
+ * host's call. Override via `CompactorOptions.countTokens` for a real tokenizer.
+ */
+export function estimateTokens(messages) {
+    let total = 0;
+    for (const m of messages)
+        total += Math.ceil(JSON.stringify(m).length / 4);
+    return total;
+}
+/** The system reminder injected when `flushToMemory` is set. */
+const FLUSH_TO_MEMORY_REMINDER = "Before continuing: if anything from earlier is worth keeping, save it with the memory tool now — the earlier transcript is about to be summarized.";
+/** Prefix on the summary system message; hosts/tests key off this to detect a compaction. */
+const SUMMARY_PREFIX = "[Summary of earlier conversation]\n";
+/**
+ * Build a `beforeLLM` hook (§8) that compacts the transcript once it exceeds
+ * `maxTokens`. Below budget it returns nothing (a byte-identical no-op); above it, it
+ * replaces the transcript with `[leading system prompt, summary system message,
+ * (flush reminder?), …recent tail]`, splitting at a clean `user` boundary so tool
+ * groups are never broken.
+ */
+export function compactor(opts) {
+    const count = opts.countTokens ?? estimateTokens;
+    const keepTail = opts.keepTail ?? Math.floor(opts.maxTokens / 2);
+    return async (ev) => {
+        const msgs = ev.messages;
+        if (count(msgs) <= opts.maxTokens)
+            return undefined; // under budget → no-op
+        // Preserve a leading system prompt verbatim (identity / soul / skills — never summarized).
+        const headEnd = msgs[0]?.role === "system" ? 1 : 0;
+        const system = msgs.slice(0, headEnd);
+        const split = findTailStart(msgs, headEnd, keepTail, count);
+        if (split <= headEnd)
+            return undefined; // nothing safely compactible
+        const older = msgs.slice(headEnd, split);
+        if (older.length === 0)
+            return undefined;
+        const tail = msgs.slice(split);
+        const flushNote = opts.flushToMemory
+            ? [{ role: "system", content: FLUSH_TO_MEMORY_REMINDER }]
+            : [];
+        const summary = await opts.summarize(older);
+        const summaryMsg = { role: "system", content: `${SUMMARY_PREFIX}${summary}` };
+        return { messages: [...system, summaryMsg, ...flushNote, ...tail] };
+    };
+}
+/**
+ * Locate the index where the retained tail begins. Tool-pair safety requires the tail
+ * to start at a `user` turn: the largest user-boundary tail that still fits `keepTail`.
+ * If no user boundary fits within `keepTail`, fall back to the most recent user turn
+ * (favoring safety over size). Returns `msgs.length` (no tail) only when there is no
+ * user turn after the head at all.
+ */
+function findTailStart(msgs, headEnd, keepTail, count) {
+    let split = msgs.length;
+    for (let i = msgs.length - 1; i > headEnd; i--) {
+        if (count(msgs.slice(i)) > keepTail)
+            break;
+        if (msgs[i].role === "user")
+            split = i;
+    }
+    if (split !== msgs.length)
+        return split;
+    // No user boundary fit within keepTail — extend back to the most recent user turn.
+    for (let i = msgs.length - 1; i > headEnd; i--) {
+        if (msgs[i].role === "user")
+            return i;
+    }
+    return msgs.length;
+}

package/dist/agents/home.d.ts

@@ -0,0 +1,90 @@
+import type { Tool } from "../types.js";
+import { Agent, type AgentRunOptions } from "./agent.js";
+import { AgentRuntime } from "./runtime.js";
+/**
+ * Bootstrap discovery order (§7E): identity first, durable memory last. Each present
+ * file is injected into the soul as a `## <filename>` section, in exactly this order.
+ */
+export declare const BOOTSTRAP_ORDER: readonly ["AGENTS.md", "SOUL.md", "IDENTITY.md", "USER.md", "TOOLS.md", "HEARTBEAT.md", "MEMORY.md"];
+/** Per-file bootstrap cap (§7E): a larger file is injected truncated, disk untouched. */
+export declare const MAX_FILE_BYTES: number;
+/** Notice appended to a bootstrap file truncated at {@link MAX_FILE_BYTES}. */
+export declare const TRUNCATION_NOTICE = "\n[truncated: exceeds 2 MB bootstrap cap]";
+/** The silent-no-op sentinel: a heartbeat reply containing this surfaces nothing. */
+export declare const HEARTBEAT_OK = "HEARTBEAT_OK";
+/** The prompt a heartbeat wakes the persona with. Contains `HEARTBEAT_OK` so the
+ * model knows the silent-reply contract, and the word "Heartbeat" so a HEARTBEAT.md
+ * that keys off it can recognise the trigger. */
+export declare const HEARTBEAT_PROMPT: string;
+/**
+ * Compose the bootstrap files present in `dir` into one soul string — the frozen
+ * snapshot injected as the system prompt for the whole run. Only present files
+ * appear, always in {@link BOOTSTRAP_ORDER}, each as a `## <filename>` section.
+ */
+export declare function composeSoul(dir: string): {
+    soul: string;
+    found: string[];
+};
+/**
+ * The `memory` builtin (§7E, file-backed, opt-in). One tool, three actions over
+ * `MEMORY.md` (the agent's own notes) and `USER.md` (its model of the user):
+ *
+ *   - `add`     — append an entry
+ *   - `replace` — swap an existing substring for `with`
+ *   - `remove`  — delete an existing substring
+ *
+ * Every action writes to **disk**. It does **not** touch the live session's system
+ * prompt: the frozen-snapshot rule means the edit loads only at the START of the
+ * next session (keeping a long-lived persona cache-stable). A `replace`/`remove`
+ * whose substring is absent is a loud `isError` — never a silent no-op.
+ */
+export declare function memoryTool(dir: string): Tool;
+/** Options for {@link fromDir}. */
+export interface FromDirOptions {
+    /** Routing description a delegating model sees; default derived from the dir. */
+    does?: string;
+    /** Agent name; default the directory's basename. */
+    name?: string;
+    /** Model id; default `"inherit"` (the runtime's `llm.model`). */
+    model?: string;
+    /** Extra tools beyond the memory builtin. */
+    tools?: Tool[];
+    /** Set `false` to omit the memory tool (a read-only persona). */
+    memory?: boolean;
+}
+/**
+ * The directory IS the agent (§7E). Discovers the bootstrap files in `dir`, composes
+ * them into a frozen soul snapshot, and (unless `memory:false`) wires a `memory` tool
+ * over the same directory. Returns a plain {@link Agent} — `run`/`asTool`/`startAgent`
+ * all apply.
+ */
+export declare function fromDir(dir: string, opts?: FromDirOptions): Agent;
+/** Heartbeat configuration for {@link startAgent}. */
+export interface HeartbeatOptions {
+    /** Interval between beats, in ms (measured on the runtime's clock). */
+    everyMs: number;
+    /** Called for each SUBSTANTIVE beat — a `HEARTBEAT_OK` reply is stripped and never
+     * surfaces here. */
+    onBeat?: (text: string) => void;
+}
+/** A running persona: the live runtime, the collected substantive beats, and `stop`. */
+export interface StartedAgent {
+    /** The runtime the persona runs on — expose so a host can `post`/`wake` it (channels). */
+    runtime: AgentRuntime;
+    /** Substantive beats collected so far (HEARTBEAT_OK replies excluded). */
+    beats: string[];
+    /** Cancel the heartbeat and close the tree gracefully. */
+    stop: () => Promise<void>;
+}
+/**
+ * Give a persona its own clock (§7E). On each interval it `post`s a tick to its own
+ * inbox (the unsolicited rail — ticks **coalesce**, so a slow beat can't pile up) and,
+ * when idle, `wake`s it with {@link HEARTBEAT_PROMPT}. A reply containing
+ * {@link HEARTBEAT_OK} is treated as silent (no `onBeat`); only a substantive reply
+ * surfaces. All timing goes through the runtime's injectable clock, so a virtual-clock
+ * test is deterministic.
+ *
+ * Inbound channels are the host's job: deliver external events by calling
+ * `started.runtime.post`/`wake` on the persona's handle.
+ */
+export declare function startAgent(a: Agent, run: AgentRunOptions, hb: HeartbeatOptions): StartedAgent;

package/dist/agents/home.js

@@ -0,0 +1,203 @@
+/**
+ * Agent home — the persona surface over the §7D runtime (SPEC.md §7E).
+ *
+ * A persona is an identity that lives in **files**, keeps durable **memory** it can
+ * edit, and runs on a **heartbeat** so it can act unprompted. All three ride shipped
+ * seams — the composed soul is just a system prompt, the memory tool is a plain
+ * `Tool`, and the heartbeat is `post`+`wake` on the runtime's injectable clock — so
+ * this layer adds *no* new runtime behavior. It is convention (a directory layout)
+ * and composition (recipes over the six verbs), not new machinery.
+ *
+ *   import { agents } from "toolnexus"
+ *   const ava = agents.fromDir("./personas/ava")
+ *   const started = agents.startAgent(ava, { fetch, clock }, { everyMs: 30 * 60_000 })
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { defineTool } from "../native.js";
+import { agent } from "./agent.js";
+import { isVerbError } from "./runtime.js";
+/**
+ * Bootstrap discovery order (§7E): identity first, durable memory last. Each present
+ * file is injected into the soul as a `## <filename>` section, in exactly this order.
+ */
+export const BOOTSTRAP_ORDER = [
+    "AGENTS.md",
+    "SOUL.md",
+    "IDENTITY.md",
+    "USER.md",
+    "TOOLS.md",
+    "HEARTBEAT.md",
+    "MEMORY.md",
+];
+/** Per-file bootstrap cap (§7E): a larger file is injected truncated, disk untouched. */
+export const MAX_FILE_BYTES = 2 * 1024 * 1024;
+/** Notice appended to a bootstrap file truncated at {@link MAX_FILE_BYTES}. */
+export const TRUNCATION_NOTICE = "\n[truncated: exceeds 2 MB bootstrap cap]";
+/** The silent-no-op sentinel: a heartbeat reply containing this surfaces nothing. */
+export const HEARTBEAT_OK = "HEARTBEAT_OK";
+/** The prompt a heartbeat wakes the persona with. Contains `HEARTBEAT_OK` so the
+ * model knows the silent-reply contract, and the word "Heartbeat" so a HEARTBEAT.md
+ * that keys off it can recognise the trigger. */
+export const HEARTBEAT_PROMPT = `Heartbeat. Read your HEARTBEAT.md section and follow it. ` +
+    `If nothing needs attention, reply ${HEARTBEAT_OK}.`;
+/** Read a bootstrap file with the byte cap applied; `undefined` if it is absent. */
+function readCapped(file) {
+    let buf;
+    try {
+        buf = fs.readFileSync(file);
+    }
+    catch {
+        return undefined; // absent files are skipped (§7E)
+    }
+    if (buf.byteLength > MAX_FILE_BYTES) {
+        return buf.subarray(0, MAX_FILE_BYTES).toString("utf8") + TRUNCATION_NOTICE;
+    }
+    return buf.toString("utf8");
+}
+/**
+ * Compose the bootstrap files present in `dir` into one soul string — the frozen
+ * snapshot injected as the system prompt for the whole run. Only present files
+ * appear, always in {@link BOOTSTRAP_ORDER}, each as a `## <filename>` section.
+ */
+export function composeSoul(dir) {
+    const sections = [];
+    const found = [];
+    for (const file of BOOTSTRAP_ORDER) {
+        const body = readCapped(path.join(dir, file));
+        if (body !== undefined) {
+            sections.push(`## ${file}\n\n${body.trim()}`);
+            found.push(file);
+        }
+    }
+    return { soul: sections.join("\n\n"), found };
+}
+function memoryFile(dir, target) {
+    return path.join(dir, target === "user" ? "USER.md" : "MEMORY.md");
+}
+/**
+ * The `memory` builtin (§7E, file-backed, opt-in). One tool, three actions over
+ * `MEMORY.md` (the agent's own notes) and `USER.md` (its model of the user):
+ *
+ *   - `add`     — append an entry
+ *   - `replace` — swap an existing substring for `with`
+ *   - `remove`  — delete an existing substring
+ *
+ * Every action writes to **disk**. It does **not** touch the live session's system
+ * prompt: the frozen-snapshot rule means the edit loads only at the START of the
+ * next session (keeping a long-lived persona cache-stable). A `replace`/`remove`
+ * whose substring is absent is a loud `isError` — never a silent no-op.
+ */
+export function memoryTool(dir) {
+    return defineTool({
+        name: "memory",
+        description: "Persist durable memory. action=add appends an entry; replace swaps an " +
+            "existing substring (with); remove deletes one. target=self (MEMORY.md, " +
+            "default) or user (USER.md). Writes persist to disk and load at the START of " +
+            "your NEXT session — they do NOT change your current context.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                action: { type: "string", enum: ["add", "replace", "remove"] },
+                target: { type: "string", enum: ["self", "user"], description: "self=MEMORY.md (default), user=USER.md" },
+                text: { type: "string", description: "For add: the entry. For replace/remove: the existing text." },
+                with: { type: "string", description: "For replace: the replacement text." },
+            },
+            required: ["action", "text"],
+        },
+        run: (args) => {
+            const target = args.target ?? "self";
+            const file = memoryFile(dir, target);
+            const text = String(args.text);
+            const current = readCapped(file) ?? "";
+            let next;
+            switch (args.action) {
+                case "add":
+                    next = (current.trimEnd() + `\n- ${text}\n`).trimStart();
+                    break;
+                case "replace":
+                    if (!current.includes(text))
+                        return { output: `not found: ${text}`, isError: true };
+                    next = current.replace(text, String(args.with ?? ""));
+                    break;
+                case "remove":
+                    if (!current.includes(text))
+                        return { output: `not found: ${text}`, isError: true };
+                    next = current.replace(text, "");
+                    break;
+                default:
+                    return { output: `unknown action: ${String(args.action)}`, isError: true };
+            }
+            fs.mkdirSync(path.dirname(file), { recursive: true });
+            fs.writeFileSync(file, next);
+            return `ok (${String(args.action)} → ${path.basename(file)}); loads next session`;
+        },
+    });
+}
+/**
+ * The directory IS the agent (§7E). Discovers the bootstrap files in `dir`, composes
+ * them into a frozen soul snapshot, and (unless `memory:false`) wires a `memory` tool
+ * over the same directory. Returns a plain {@link Agent} — `run`/`asTool`/`startAgent`
+ * all apply.
+ */
+export function fromDir(dir, opts = {}) {
+    const { soul } = composeSoul(dir);
+    const tools = [...(opts.tools ?? [])];
+    if (opts.memory !== false)
+        tools.push(memoryTool(dir));
+    return agent(opts.name ?? path.basename(dir), {
+        does: opts.does ?? `persona agent from ${dir}`,
+        soul,
+        model: opts.model ?? "inherit",
+        uses: { tools },
+    });
+}
+/**
+ * Give a persona its own clock (§7E). On each interval it `post`s a tick to its own
+ * inbox (the unsolicited rail — ticks **coalesce**, so a slow beat can't pile up) and,
+ * when idle, `wake`s it with {@link HEARTBEAT_PROMPT}. A reply containing
+ * {@link HEARTBEAT_OK} is treated as silent (no `onBeat`); only a substantive reply
+ * surfaces. All timing goes through the runtime's injectable clock, so a virtual-clock
+ * test is deterministic.
+ *
+ * Inbound channels are the host's job: deliver external events by calling
+ * `started.runtime.post`/`wake` on the persona's handle.
+ */
+export function startAgent(a, run, hb) {
+    const runtime = a.createRuntime(run);
+    const handle = runtime.spawn(runtime.root, a.name);
+    if (isVerbError(handle))
+        throw new Error(handle.error);
+    const beats = [];
+    let stopped = false;
+    let cancel;
+    const beat = () => {
+        if (stopped)
+            return;
+        // Unsolicited rail: the tick lands in the inbox (coalesces); a wake — only when
+        // idle — drains the whole inbox as one turn.
+        runtime.post(handle, { from: "clock", channel: "timer", text: "tick" });
+        if (handle.state === "idle") {
+            const woke = runtime.wake(handle, HEARTBEAT_PROMPT);
+            if (woke.ok) {
+                void runtime.wait(handle).then((r) => {
+                    if (!r.isError && !r.text.includes(HEARTBEAT_OK)) {
+                        beats.push(r.text);
+                        hb.onBeat?.(r.text);
+                    }
+                });
+            }
+        }
+        cancel = runtime.clock.setTimeout(beat, hb.everyMs); // self-reschedule → one live timer
+    };
+    cancel = runtime.clock.setTimeout(beat, hb.everyMs);
+    return {
+        runtime,
+        beats,
+        stop: async () => {
+            stopped = true;
+            cancel?.();
+            await runtime.close(runtime.root);
+        },
+    };
+}

package/dist/agents/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Sub-agents & agent runtime (SPEC.md §7D), exported as the `agents` namespace:
+ *
+ *   import { agents } from "toolnexus"
+ *   const explore = agents.agent("explore", { does: "read-only research" })
+ */
+export * from "./runtime.js";
+export * from "./agent.js";
+export * from "./home.js";
+export * from "./compaction.js";