toolnexus 0.27.0 → 0.29.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.
@@ -173,27 +177,67 @@ const rs = await c.states("a", "b").evaluate(judge.noul("q", "…"))      // [{
 
 ## Media generation
 
-Generate images, video and speech (plus transcription, voice cloning and talking-head video)
-from a **JSON style** instead of provider code. Async jobs are started and polled for you. The same
-verbs become agent tools (`generate_image`, `generate_video`, `generate_speech`, …), and whatever
-they produce lands in `RunResult.files`. `examples/media-styles/a2e.json` ships first and reads
-`A2E_API_KEY` at call time. Its result URLs expire in 3–30 days, so save what you keep. SPEC §7G;
-guide: <https://muthuishere.github.io/toolnexus/media/>.
+Images, video, speech, music, transcription, voice cloning and talking-head video, with **one
+client per media object**. The quickest start is a **CLI preset**: `MediaStyle.XaiGrokCli`, `MediaStyle.OpenAICodexCli` and `MediaStyle.GoogleAgyCli` drive the vendor's
+official CLI (`grok`, `codex`, `agy`) in its documented headless mode (`grok -p`, `codex exec`,
+`agy -p`), signed in by you. Grok does image and video; Codex and Antigravity do image. Each preset
+has a mock twin (`MediaStyle.XaiGrokCliMock`, …) for tests. Your provider's terms of service apply to how you use its CLI.
+Every Grok image carries a small visible **"Grok" mark in the bottom-right corner**; toolnexus does
+not remove it. Install, sign-in, Grok video, limits and models:
+<https://muthuishere.github.io/toolnexus/cookbook/cli-media-setup/>. SPEC §7G; guide: <https://muthuishere.github.io/toolnexus/media/>.
 
 ```ts
-import { loadMediaStyle, createMedia, createToolkit } from "toolnexus"
+import { generateMedia, createMedia, loadMediaStyle, createToolkit, MediaStyle } from "toolnexus"
 
-const media = createMedia(loadMediaStyle("examples/media-styles/a2e.json"), {
-  onProgress: ({ verb, status }) => console.log(verb, status),
-})
-const img = await media.image({ prompt: "a red fox in fresh snow", width: 1024, height: 768 })
-const vid = await media.video({ prompt: "the fox blinks", image: img.files[0].url, seconds: 5 })
+// one line
+const r = await generateMedia(MediaStyle.XaiGrokCli, "image", { prompt: "a red apple", aspectRatio: "16:9" })
+console.log(r.files[0].path)
 
-const tk = await createToolkit({ media })            // the agent gets generate_image, …
-const res = await agent.run("Draw a fox, then animate it.", { toolkit: tk })
-for (const f of res.files) console.log(f.from, f.mimeType, f.url)
+// or keep a media object, and give it to your agent
+const media = createMedia(loadMediaStyle(MediaStyle.XaiGrokCli))
+const clip = await media.video({ prompt: "the apple rolls off the table" })
+const tk = await createToolkit({ media })   // generate_image, generate_video (source "media")
 ```
 
+For an HTTP API, give `createMedia(client)` one named client — `OpenAIMediaClient`, `OpenRouterMediaClient`, `FalMediaClient`, `ElevenLabsMediaClient` or `A2EMediaClient`. Each reads its key from its env
+var (`OPENAI_API_KEY`, `FAL_API_KEY`, `ELEVENLABS_API_KEY`, …) at call time and never logs it.
+
+```ts
+import { createMedia, ElevenLabsMediaClient } from "toolnexus"
+
+const voice = createMedia(new ElevenLabsMediaClient({ gather: { mode: "url" } }))  // speech, music, transcribe, cloneVoice
+const say = await voice.speech({ text: "Hello from the fox." })
+```
+
+- **Typed verbs** — `image`, `video`, `speech`, `music`, `transcribe`, `cloneVoice`, `talk`, each
+  `(args & { signal?, deadline?, progress?, providerOptions? }) => Promise<MediaResult>`;
+  `generate(verb, args, ctx)` is the raw call. `MediaResult { files, text?, jobId?, status, usage? }`
+  — `usage` (`inputTokens`, `outputTokens`, `costUsd`, `raw`) only as the provider reported it
+  (OpenAI images, OpenRouter, Grok's `raw.costUsdTicks` unconverted), also on the tool's `metadata.usage`.
+  Args are checked per client: a client that does not accept an arg (e.g. `seconds` on
+  the Grok CLI preset, which takes `prompt` and size hints only) or lacks a required one fails with
+  `unavailable`; a key that is not a canonical arg of the verb fails at once.
+- **Config** (every built-in client, one shape): `model`, `models: { [verb]: model }`, `key`, `url`,
+  `command` (CLI), `loop: { intervalMs, timeoutMs, onProgress }` (timeout default 10 min),
+  `gather: { mode: "url" | "download" | "inline", dir, maxBytes, keep }` (default `download` into
+  `<tmp>/toolnexus-media`, 100 MiB cap), `fetch` (injected transport).
+- **Agents** — `createToolkit({ media })` (or `media.tools()`); produced files land in
+  `RunResult.files` (`{ type, mimeType, url?, data?, path?, from, callId }` — `path` is the saved
+  local file; it is never sent to the model). Only **image** parts are sent
+  back to the model; audio/video stay on `RunResult.files`.
+- **Your own provider** — implement `MediaClient` (`name`, `supports(verb)`, optional `args(verb)`,
+  any of the seven verb methods); throw `MediaUnavailableError` when it cannot serve a call (no key, no credits).
+  Advanced: `styleMediaClient(loadMediaStyle("my-style.json"))` turns a JSON style into a client.
+- **Errors** — a typed verb throws `MediaError` (`status`: `failed` | `timeout` | `cancelled` |
+  `unavailable`); a media tool never throws (`isError: true`).
+
+Run it: `npm run build && npm run example:media`. It uses whatever is present, in order: the `grok`
+and `codex` CLIs, `ELEVENLABS_API_KEY`, then `OPENAI_API_KEY`, `FAL_API_KEY`,
+`A2E_API_KEY`; makes an image, ElevenLabs speech (`MEDIA_VOICE` picks the voice) and calls the
+`generate_image` tool; `MEDIA_VIDEO=1` adds a Grok video, `MEDIA_PAID=1` paid video/talk. It prints
+client, verb, path or URL, mime type, size and usage per file, exits non-zero if a step fails, and
+exits 0 with a hint when nothing is available.
+
 ## MCP 2026-07-28 + OAuth
 
 `loadMcp` / `Toolkit.create({ mcpConfig })` now speak MCP **2026-07-28** first, with no MCP SDK on
@@ -317,7 +361,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

@@ -65,6 +65,12 @@ export interface ACPClient {
      *  Shaped for {@link InProcessOptions.generateStream}. The returned content is the
      *  message text only. */
     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,22 +276,23 @@ 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 —
@@ -340,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",
@@ -427,7 +436,20 @@ export async function loadACP(opts) {
             await Promise.race([childGone, new Promise((r) => setTimeout(r, 1000).unref())]);
     }
     const generate = (request, callOpts) => generateStream(request, undefined, callOpts);
-    const client = { generate, generateStream, close, initializeResult };
+    // 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 });

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). */