toolnexus 0.26.0 → 0.28.0

package/README.md

@@ -92,6 +92,9 @@ tool. Runnable: `npm run example:prompt-cache` ([`examples/prompt_cache.ts`](exa
   `after`; `read` / `grep` report truncation in metadata.
 - `agents.compactor({ onCompact })`, `agent.asToolWith(ctx => ({ hooks, waitFor }))`, runtime
   `waitFor`, `ctx.callId` on tools, `listModels(opts)`.
+- `compactOnOverflow: agents.compactor({ maxTokens: tighter })` — when the provider rejects a prompt as too
+  long (`isContextOverflow(status, body)`), compact and re-send the same turn; three rapid
+  compactions in a row fail with `ContextOverflowError` (SPEC §7F.1).
 
 An in-process model streams for real when it is given as `generateStream(request, emit)`; a plain
 `generate` still refuses `stream()`.
@@ -152,7 +155,8 @@ const rs = await c.states("a", "b").evaluate(judge.noul("q", "…"))      // [{
 
 - `backend`: `typesafe` (default) · `openrouter` (`typesafe/jev-1.14`) · `cloudflare` (`/ai/run`
   envelope; `${CLOUDFLARE_ACCOUNT_ID}` in the URL expands at call time, errors name it unexpanded)
-  · `vercel` · `custom` (requires `baseUrl` and `supports`). The table is data:
+  · `vercel` · `openai` (OpenAI Decisions API, `POST {baseUrl}/decisions`, `gpt-6-luna`,
+  `OPENAI_API_KEY`; raw questions are unsupported, `calibrated` is false) · `custom` (requires `baseUrl` and `supports`). The table is data:
   `CLASSIFIER_BACKENDS`; `supports: { images }` overrides it per classifier.
 - Images (style `systemone` only): image parts in the state are lifted into `assets` (cloudflare:
   data URLs). PNG/JPEG, 280–1568 px a side, ≤ 16 MiB each and 32 MiB per request — never resized.
@@ -317,7 +321,7 @@ Everything else — the full surface, with runnable examples — lives on the do
 | **Start here** | [Quickstart](https://muthuishere.github.io/toolnexus/quickstart/) · [Concepts](https://muthuishere.github.io/toolnexus/concepts/) · [Install](https://muthuishere.github.io/toolnexus/install/) |
 | **Tool sources** | [MCP](https://muthuishere.github.io/toolnexus/mcp/) · [Skills](https://muthuishere.github.io/toolnexus/skills/) · [Native](https://muthuishere.github.io/toolnexus/native/) · [HTTP](https://muthuishere.github.io/toolnexus/http/) · [Built-ins](https://muthuishere.github.io/toolnexus/builtins/) · [A2A](https://muthuishere.github.io/toolnexus/a2a/) |
 | **The loop** | [Streaming](https://muthuishere.github.io/toolnexus/streaming/) · [Memory](https://muthuishere.github.io/toolnexus/memory/) · [Suspension](https://muthuishere.github.io/toolnexus/suspension/) · [Resilience](https://muthuishere.github.io/toolnexus/resilience/) · [Observability](https://muthuishere.github.io/toolnexus/observability/) |
-| **Agents** | [Sub-agents & teams](https://muthuishere.github.io/toolnexus/subagents/) · [Personas](https://muthuishere.github.io/toolnexus/persona-agents/) · [Typed decisions](https://muthuishere.github.io/toolnexus/judge/) |
+| **Agents** | [Sub-agents & teams](https://muthuishere.github.io/toolnexus/subagents/) · [Personas](https://muthuishere.github.io/toolnexus/persona-agents/) · [Dreaming](https://muthuishere.github.io/toolnexus/dreaming/) · [Typed decisions](https://muthuishere.github.io/toolnexus/judge/) |
 | **API reference** | [JavaScript](https://muthuishere.github.io/toolnexus/api/javascript/) |
 | **Cookbook** | [Zero to agent](https://muthuishere.github.io/toolnexus/cookbook/zero-to-agent/) · [MCP servers](https://muthuishere.github.io/toolnexus/cookbook/mcp-servers/) · [Agent skills](https://muthuishere.github.io/toolnexus/cookbook/agent-skills/) · [Judge](https://muthuishere.github.io/toolnexus/cookbook/judge/) |
 

package/dist/acp.d.ts

@@ -48,15 +48,29 @@ export interface ACPOptions {
 /** One warm ACP connection: one child process, one session, alive across many
  *  turns. `.generate` has exactly the shape {@link InProcessOptions.generate}
  *  wants, so it plugs straight into {@link createInProcessClient}. */
+/** Per-call options for {@link ACPClient.generate} / {@link ACPClient.generateStream}. */
+export interface ACPGenerateOptions {
+    /** Cancels the turn: when it aborts mid-turn the `session/cancel` notification is sent,
+     *  the turn's reply is awaited (bounded by `requestTimeoutMs`, default 30s) so the next
+     *  turn never lands on a busy session, and the call rejects with an `AbortError`. The
+     *  process and session stay warm. */
+    signal?: AbortSignal;
+}
 export interface ACPClient {
-    generate: (request: InProcessRequest) => Promise<InProcessResponse>;
+    generate: (request: InProcessRequest, opts?: ACPGenerateOptions) => Promise<InProcessResponse>;
     /** {@link generate}, streaming: `emit` fires as each `session/update` arrives —
      *  agent_message_chunk → `text`, agent_thought_chunk → `thought` (via "acp"),
      *  tool_call → `tool_call` and a completed/failed tool_call_update → `tool_result`
      *  (both via "acp": the agent's own tools, reported, never executed by the loop).
      *  Shaped for {@link InProcessOptions.generateStream}. The returned content is the
      *  message text only. */
-    generateStream: (request: InProcessRequest, emit: (event: StreamEvent) => void) => Promise<InProcessResponse>;
+    generateStream: (request: InProcessRequest, emit: (event: StreamEvent) => void, opts?: ACPGenerateOptions) => Promise<InProcessResponse>;
+    /** Sends `session/set_mode {sessionId, modeId}` on the running session (no restart). The
+     *  agent's error rejects this call only; the client stays usable. */
+    setMode: (mode: string) => Promise<void>;
+    /** Changes the model on the running session exactly as the `model` option does:
+     *  `session/set_config_option {configId:"model"}`, then `session/set_model`; both failing rejects. */
+    setModel: (model: string) => Promise<void>;
     /** Terminates the agent's process group. Idempotent — a second call is a no-op. */
     close: () => Promise<void>;
     /** The agent's raw `initialize` result. */

package/dist/acp.js

@@ -276,29 +276,32 @@ export async function loadACP(opts) {
     if (opts.mode) {
         await step("session/set_mode", () => call("session/set_mode", { sessionId, modeId: opts.mode }));
     }
-    if (opts.model) {
-        // Passed through unchanged. Stable ACP spelling first, then the older session/set_model.
-        const model = opts.model;
-        await step(`set model ${JSON.stringify(model)}`, async () => {
+    // Passed through unchanged. Stable ACP spelling first, then the older session/set_model.
+    const sendModel = async (model) => {
+        try {
+            await call("session/set_config_option", { sessionId, configId: "model", value: model });
+        }
+        catch (e1) {
             try {
-                await call("session/set_config_option", { sessionId, configId: "model", value: model });
+                await call("session/set_model", { sessionId, modelId: model });
             }
-            catch (e1) {
-                try {
-                    await call("session/set_model", { sessionId, modelId: model });
-                }
-                catch (e2) {
-                    throw new Error(`${e1.message}; ${e2.message}`);
-                }
+            catch (e2) {
+                throw new Error(`${e1.message}; ${e2.message}`);
             }
-        });
+        }
+    };
+    if (opts.model) {
+        const model = opts.model;
+        await step(`set model ${JSON.stringify(model)}`, () => sendModel(model));
     }
     // Serialises turns: one ACP session is one conversation, so concurrent
     // prompts must not interleave into it. Idiomatic promise-chaining queue —
     // each generate() call attaches after whatever is already queued, and the
     // queue itself never rejects (a failed turn does not poison later ones).
     let turnQueue = Promise.resolve();
-    async function promptOnce(request, emit) {
+    async function promptOnce(request, emit, signal) {
+        if (signal?.aborted)
+            throw acpAbortError();
         const text = renderPrompt(request);
         const id = `c-${++nextId}`;
         let content = "";
@@ -338,12 +341,20 @@ export async function loadACP(opts) {
                     break;
                 }
                 case "tool_call_update": {
+                    const callId = u.toolCallId ?? "";
+                    // A non-empty title is remembered as the call's name for every later event (#188).
+                    if (u.title)
+                        toolNames.set(callId, u.title);
+                    const name = toolNames.get(callId) || "";
+                    const raw = u.rawInput;
+                    if (raw && typeof raw === "object" && !Array.isArray(raw) && Object.keys(raw).length > 0) {
+                        send({ type: "tool_call_args", id: callId, name, args: raw, via: "acp" });
+                    }
                     if (u.status !== "completed" && u.status !== "failed")
                         break;
-                    const name = u.title || toolNames.get(u.toolCallId ?? "") || "";
                     send({
                         type: "tool_result",
-                        id: u.toolCallId ?? "",
+                        id: callId,
                         name,
                         output: acpToolContentText(u.content),
                         isError: u.status === "failed",
@@ -361,8 +372,30 @@ export async function loadACP(opts) {
         const timeout = new Promise((_, reject) => {
             timer = setTimeout(() => reject(new Error(`toolnexus: ACP turn timed out after ${permissionTimeoutMs}ms`)), permissionTimeoutMs);
         });
+        let onAbort;
+        const cancelled = new Promise((resolve) => {
+            if (!signal)
+                return;
+            onAbort = () => resolve("cancelled");
+            signal.addEventListener("abort", onAbort, { once: true });
+        });
         try {
-            const msg = await Promise.race([replyPromise, timeout]);
+            const msg = await Promise.race([replyPromise, timeout, cancelled]);
+            if (msg === "cancelled") {
+                // ACP: session/cancel is a notification (no id); the agent then ends the turn with
+                // stopReason "cancelled". Wait (bounded) for that reply so the session is idle again.
+                write({ jsonrpc: "2.0", method: "session/cancel", params: { sessionId } });
+                const waitMs = opts.requestTimeoutMs && opts.requestTimeoutMs > 0 ? opts.requestTimeoutMs : 30000;
+                let wait;
+                await Promise.race([
+                    replyPromise,
+                    new Promise((r) => {
+                        wait = setTimeout(r, waitMs);
+                    }),
+                ]);
+                clearTimeout(wait);
+                throw acpAbortError();
+            }
             if (msg.error && msg.error.code === 0)
                 throw new Error(msg.error.message);
             if (msg.error)
@@ -371,14 +404,16 @@ export async function loadACP(opts) {
         }
         finally {
             clearTimeout(timer);
+            if (onAbort)
+                signal.removeEventListener("abort", onAbort);
             pending.delete(id);
             updateSink = null;
         }
     }
-    const generateStream = (request, emit) => {
+    const generateStream = (request, emit, callOpts) => {
         if (closed)
             return Promise.reject(new Error("toolnexus: ACP client is closed"));
-        const turn = turnQueue.then(() => promptOnce(request, emit));
+        const turn = turnQueue.then(() => promptOnce(request, emit, callOpts?.signal));
         turnQueue = turn.then(() => undefined, () => undefined);
         return turn;
     };
@@ -400,13 +435,31 @@ export async function loadACP(opts) {
         if (t === "late")
             await Promise.race([childGone, new Promise((r) => setTimeout(r, 1000).unref())]);
     }
-    const generate = (request) => generateStream(request);
-    const client = { generate, generateStream, close, initializeResult };
+    const generate = (request, callOpts) => generateStream(request, undefined, callOpts);
+    // SPEC §8C (#197): sent at once on the running session — no restart, not queued behind a turn.
+    const liveCall = async (label, fn) => {
+        if (closed)
+            throw new Error("toolnexus: ACP client is closed");
+        try {
+            await fn();
+        }
+        catch (e) {
+            throw new Error(`toolnexus: acp: ${label}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    };
+    const setMode = (mode) => liveCall("session/set_mode", () => call("session/set_mode", { sessionId, modeId: mode }));
+    const setModel = (model) => liveCall(`set model ${JSON.stringify(model)}`, () => sendModel(model));
+    const client = { generate, generateStream, setMode, setModel, close, initializeResult };
     // Non-enumerable, undocumented — internal test hook only, so the public
     // ACPClient surface stays exactly {generate, generateStream, close}.
     Object.defineProperty(client, "_pid", { value: child.pid, enumerable: false });
     return client;
 }
+function acpAbortError() {
+    const e = new Error("toolnexus: ACP turn cancelled");
+    e.name = "AbortError";
+    return e;
+}
 /** Signals the child's whole process group (POSIX), else the child itself. Never throws. */
 function killGroup(pid, signal) {
     if (process.platform !== "win32") {

package/dist/agents/home.d.ts

@@ -1,6 +1,7 @@
 import type { Tool } from "../types.js";
 import { Agent, type AgentRunOptions } from "./agent.js";
 import { AgentRuntime } from "./runtime.js";
+import type { ConversationStore } from "../client.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.
@@ -16,29 +17,72 @@ export declare const HEARTBEAT_OK = "HEARTBEAT_OK";
  * 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;
+/** The preset index cap (§7E "Memory hierarchy"): Claude Code's 200 lines / 25 KB. */
+export declare const MEMORY_INDEX_CAP_PRESET: {
+    readonly maxLines: 200;
+    readonly maxBytes: 25600;
+};
+/** `memoryIndexCap` option: `true` ⇒ the preset; an object's missing field ⇒ the preset's. */
+export type MemoryIndexCap = boolean | {
+    maxLines?: number;
+    maxBytes?: number;
+};
+/** Options for {@link composeSoul}. Absent ⇒ byte-identical to the pre-hierarchy soul. */
+export interface ComposeSoulOptions {
+    /** Second, smaller injection cap for `MEMORY.md` only (whole lines). Off by default. */
+    memoryIndexCap?: MemoryIndexCap;
+    /** Notes tier on — selects the notice wording that points at `note:<slug>`. */
+    notes?: boolean;
+}
+/** The exact notice appended to a capped `MEMORY.md` (§7E "Memory hierarchy"). */
+export declare function memoryIndexNotice(maxLines: number, maxBytes: number, notes: boolean): string;
+/**
+ * Apply the index cap to `MEMORY.md`'s (already 2 MB-capped) content. Lines are split on
+ * "\n"; one trailing "\n" does not start a line. Within both bounds ⇒ returned unchanged.
+ * Otherwise keep the first `maxLines` lines, drop trailing whole lines until the "\n"-joined
+ * UTF-8 length is <= `maxBytes` (a lone over-long first line is cut at a character
+ * boundary), and append {@link memoryIndexNotice}.
+ */
+export declare function applyIndexCap(content: string, cap: {
+    maxLines: number;
+    maxBytes: number;
+}, notes?: boolean): 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): {
+export declare function composeSoul(dir: string, opts?: ComposeSoulOptions): {
     soul: string;
     found: string[];
 };
+/** A valid note slug (§7E "Memory hierarchy"): lowercase, no path separators, no `..`. */
+export declare const NOTE_SLUG_RE: RegExp;
+/** Options for {@link memoryTool}. */
+export interface MemoryToolOptions {
+    /** Turn on the notes tier: `note:<slug>` targets plus `read`/`list`. Off ⇒ the tool is
+     * byte-identical to the pre-hierarchy tool (schema, description, behavior). */
+    notes?: boolean;
+}
+/** The notes-on description (§7E): says what memory is FOR, not rules about what to record. */
+export declare const MEMORY_NOTES_DESCRIPTION: 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
+ *   - `replace` — swap the first occurrence of an existing substring for `with`
+ *   - `remove`  — delete the first occurrence of an existing substring
+ *
+ * With `{notes: true}` it also takes `target: "note:<slug>"` (`<dir>/memory/<slug>.md`,
+ * never injected into the soul) and two read actions, `read` and `list`.
  *
  * 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;
+export declare function memoryTool(dir: string, opts?: MemoryToolOptions): Tool;
 /** Options for {@link fromDir}. */
 export interface FromDirOptions {
     /** Routing description a delegating model sees; default derived from the dir. */
@@ -51,6 +95,17 @@ export interface FromDirOptions {
     tools?: Tool[];
     /** Set `false` to omit the memory tool (a read-only persona). */
     memory?: boolean;
+    /** Cap the injected `MEMORY.md` (whole lines; `true` ⇒ 200 lines / 25600 bytes). Off by default. */
+    memoryIndexCap?: MemoryIndexCap;
+    /** Turn on the notes tier of the memory tool (`note:<slug>`, `read`, `list`). Off by default. */
+    notes?: boolean;
+    /** Dream on a schedule: when this persona is started with {@link startAgent}, a
+     * {@link dreamer} over the same dir runs on the same runtime every `everyMs`. */
+    dream?: {
+        everyMs: number;
+        store: ConversationStore;
+        instructions?: string;
+    };
 }
 /**
  * The directory IS the agent (§7E). Discovers the bootstrap files in `dir`, composes
@@ -59,6 +114,32 @@ export interface FromDirOptions {
  * all apply.
  */
 export declare function fromDir(dir: string, opts?: FromDirOptions): Agent;
+/**
+ * What a dream pass is FOR and the order it works in (§7E "Dreaming"). Byte-identical in
+ * every port. It becomes the dreamer's `## HEARTBEAT.md` section, so the ordinary
+ * {@link HEARTBEAT_PROMPT} wake drives a pass and `HEARTBEAT_OK` keeps an idle pass silent.
+ */
+export declare const DREAM_PROMPT: string;
+/** Options for {@link dreamer}. */
+export interface DreamerOptions {
+    /** The transcripts to verify memory against — must implement `list()`. Required. */
+    store: ConversationStore;
+    /** Host prose appended after {@link DREAM_PROMPT} (and after `DREAM.md`, if present). */
+    instructions?: string;
+    /** Agent name; default `<basename(dir)>-dreamer`. */
+    name?: string;
+    /** Model id; default `"inherit"` — the persona's client (use a cheap model there). */
+    model?: string;
+}
+/**
+ * The built-in dreamer preset (§7E "Dreaming"): a plain {@link Agent} whose tools are
+ * EXACTLY `memory` (notes on, over `dir`) and `transcript_search` (over `store`) — never
+ * the persona's shell/file tools. Its soul is one `## HEARTBEAT.md` section holding
+ * {@link DREAM_PROMPT}, then `DREAM.md` from `dir` (trimmed, if non-empty), then
+ * `instructions` (trimmed, if non-empty), joined by blank lines. Schedule it with
+ * {@link startAgent} or run one pass with `run(HEARTBEAT_PROMPT, …)`.
+ */
+export declare function dreamer(dir: string, opts: DreamerOptions): Agent;
 /** Heartbeat configuration for {@link startAgent}. */
 export interface HeartbeatOptions {
     /** Interval between beats, in ms (measured on the runtime's clock). */