toolnexus 0.9.5 → 0.10.0

package/dist/client.d.ts

@@ -184,10 +184,14 @@ export interface RunResult {
     usage: Usage;
     /** The model used. */
     model: string;
-    /** "done" normally; "pending" iff a tool suspended and no waitFor was configured (§10). */
-    status: "done" | "pending";
+    /** "done" normally; "pending" iff a tool suspended and no waitFor was configured (§10);
+     * "incomplete" iff a limit stopped the run loudly (§7D) — a maxTurns stop with no final
+     * text is never a silent "done". */
+    status: "done" | "pending" | "incomplete";
     /** The unresolved suspension — present iff status === "pending" (§10). */
     pending?: Request;
+    /** The limit that stopped the run (e.g. "maxTurns") — present iff status === "incomplete". */
+    limit?: string;
 }
 /** Events yielded by client.stream(). */
 export type StreamEvent = {
@@ -242,7 +246,8 @@ export declare class Client {
     metrics(): string;
     /** Feed a semantic metric event to the built-in registry and the optional onMetric sink. */
     private emit;
-    /** Emit the terminal `run` metric event and build the RunResult. */
+    /** Emit the terminal `run` metric event and build the RunResult. `exhausted` marks a
+     * maxTurns loop exit — with no final text that is a LOUD "incomplete", never "done" (§7D). */
     private endRun;
     /** Emit a `run` error metric event (once, on a thrown run). */
     private emitRunError;

package/dist/client.js

@@ -213,10 +213,11 @@ export class Client {
         this.registry.record(ev);
         this.opts.onMetric?.(ev);
     }
-    /** Emit the terminal `run` metric event and build the RunResult. */
-    endRun(runStart, text, messages, toolCalls, turns, usage) {
+    /** Emit the terminal `run` metric event and build the RunResult. `exhausted` marks a
+     * maxTurns loop exit — with no final text that is a LOUD "incomplete", never "done" (§7D). */
+    endRun(runStart, text, messages, toolCalls, turns, usage, exhausted = false) {
         this.emit({ event: "run", model: this.opts.model, turns, toolCalls: toolCalls.length, totalTokens: usage.totalTokens, ms: Date.now() - runStart });
-        return this.result(text, messages, toolCalls, turns, usage);
+        return this.result(text, messages, toolCalls, turns, usage, exhausted);
     }
     /** Emit a `run` error metric event (once, on a thrown run). */
     emitRunError(runStart, toolCalls, turns, usage, e) {
@@ -436,15 +437,19 @@ export class Client {
                         return this.pendingRun(runStart, s.halted, messages, toolCalls, turns, usage);
                 }
             }
-            return this.endRun(runStart, lastText(messages), messages, toolCalls, turns, usage);
+            return this.endRun(runStart, lastText(messages), messages, toolCalls, turns, usage, true);
         }
         catch (e) {
             this.emitRunError(runStart, toolCalls, turns, usage, e);
             throw e;
         }
     }
-    result(text, messages, toolCalls, turns, usage) {
-        return { text, messages, toolCalls, toolCallCount: toolCalls.length, turns, usage, model: this.opts.model, status: "done" };
+    result(text, messages, toolCalls, turns, usage, exhausted = false) {
+        const incomplete = exhausted && text === "";
+        const r = { text, messages, toolCalls, toolCallCount: toolCalls.length, turns, usage, model: this.opts.model, status: incomplete ? "incomplete" : "done" };
+        if (incomplete)
+            r.limit = "maxTurns";
+        return r;
     }
     /** §10: a run halted because a tool suspended and no `waitFor` was configured. */
     pendingRun(runStart, request, messages, toolCalls, turns, usage) {
@@ -545,7 +550,7 @@ export class Client {
                 if (halted)
                     return this.pendingRun(runStart, halted, messages, toolCalls, turns, usage);
             }
-            return this.endRun(runStart, "", messages, toolCalls, turns, usage);
+            return this.endRun(runStart, "", messages, toolCalls, turns, usage, true);
         }
         catch (e) {
             this.emitRunError(runStart, toolCalls, turns, usage, e);
@@ -655,7 +660,7 @@ export class Client {
                     yield { type: "tool_result", id: c.id, name: c.name, output: result.output, isError: result.isError };
                 }
             }
-            yield { type: "done", result: this.endRun(runStart, lastText(messages), messages, toolCalls, turns, usage) };
+            yield { type: "done", result: this.endRun(runStart, lastText(messages), messages, toolCalls, turns, usage, true) };
         }
         catch (e) {
             this.emitRunError(runStart, toolCalls, turns, usage, e);
@@ -764,7 +769,7 @@ export class Client {
                 }
                 messages.push({ role: "user", content: results });
             }
-            yield { type: "done", result: this.endRun(runStart, "", messages, toolCalls, turns, usage) };
+            yield { type: "done", result: this.endRun(runStart, "", messages, toolCalls, turns, usage, true) };
         }
         catch (e) {
             this.emitRunError(runStart, toolCalls, turns, usage, e);

package/dist/index.d.ts

@@ -10,3 +10,4 @@ export * from "./mcpserve.js";
 export * from "./adapters.js";
 export * from "./toolkit.js";
 export * from "./client.js";
+export * as agents from "./agents/index.js";

package/dist/index.js

@@ -10,3 +10,4 @@ export * from "./mcpserve.js";
 export * from "./adapters.js";
 export * from "./toolkit.js";
 export * from "./client.js";
+export * as agents from "./agents/index.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolnexus",
-  "version": "0.9.5",
+  "version": "0.10.0",
   "description": "Dynamic MCP servers + agent skills as uniform tools for any LLM (opencode-style).",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,7 +17,7 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "npm run build && node --experimental-strip-types --test test/unit.test.ts",
+    "test": "npm run build && node --experimental-strip-types --test test/unit.test.ts test/agents.test.ts test/home.test.ts test/compaction.test.ts",
     "example": "node --experimental-strip-types examples/basic.ts"
   },
   "keywords": [

package/src/agents/agent.ts

@@ -0,0 +1,129 @@
+/**
+ * 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 type { Answer, Request, Tool } from "../types.js"
+import { AgentRuntime, isVerbError, type AgentDef, type Budget, type Handle, 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 class Agent {
+  constructor(readonly name: string, readonly 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> {
+    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: AgentRunOptions = {}): AgentRuntime {
+    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: string, opts: AgentRunOptions = {}): Promise<AgentRunResult> {
+    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 as Handle)), runtime }
+    }
+    const r = await runtime.wait(h as Handle)
+    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: AgentRunOptions = {}): Tool {
+    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: Record<string, unknown>) => {
+        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: string, spec: AgentSpec): Agent {
+  return new Agent(name, spec)
+}

package/src/agents/compaction.ts

@@ -0,0 +1,148 @@
+/**
+ * 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 function estimateTokens(messages: Message[]): number {
+  let total = 0
+  for (const m of messages) total += Math.ceil(JSON.stringify(m).length / 4)
+  return total
+}
+
+/** 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
+}
+
+/** 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: CompactorOptions,
+): (ev: BeforeLLMEvent) => Promise<{ messages: Message[] } | undefined> {
+  const count = opts.countTokens ?? estimateTokens
+  const keepTail = opts.keepTail ?? Math.floor(opts.maxTokens / 2)
+
+  return async (ev: BeforeLLMEvent): Promise<{ messages: Message[] } | undefined> => {
+    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: Message[] = opts.flushToMemory
+      ? [{ role: "system", content: FLUSH_TO_MEMORY_REMINDER }]
+      : []
+
+    const summary = await opts.summarize(older)
+    const summaryMsg: Message = { 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: Message[],
+  headEnd: number,
+  keepTail: number,
+  count: (messages: Message[]) => number,
+): number {
+  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/src/agents/home.ts

@@ -0,0 +1,250 @@
+/**
+ * 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 type { Tool } from "../types.js"
+import { agent, Agent, type AgentRunOptions } from "./agent.js"
+import { AgentRuntime, 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",
+] as const
+
+/** 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: string): string | undefined {
+  let buf: Buffer
+  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: string): { soul: string; found: string[] } {
+  const sections: string[] = []
+  const found: string[] = []
+  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 }
+}
+
+/** Which memory file an action targets. `self` → MEMORY.md, `user` → USER.md. */
+type MemoryTarget = "self" | "user"
+
+function memoryFile(dir: string, target: unknown): string {
+  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: string): Tool {
+  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: Record<string, unknown>) => {
+      const target = (args.target as MemoryTarget) ?? "self"
+      const file = memoryFile(dir, target)
+      const text = String(args.text)
+      const current = readCapped(file) ?? ""
+      let next: string
+      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`
+    },
+  })
+}
+
+/** 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 function fromDir(dir: string, opts: FromDirOptions = {}): Agent {
+  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 },
+  })
+}
+
+/** 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 function startAgent(a: Agent, run: AgentRunOptions, hb: HeartbeatOptions): StartedAgent {
+  const runtime = a.createRuntime(run)
+  const handle = runtime.spawn(runtime.root, a.name)
+  if (isVerbError(handle)) throw new Error(handle.error)
+
+  const beats: string[] = []
+  let stopped = false
+  let cancel: (() => void) | undefined
+
+  const beat = (): void => {
+    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/src/agents/index.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"