toolnexus 0.21.0 → 0.22.0

package/dist/agents/agent.d.ts

@@ -8,7 +8,7 @@
  * Everything compiles down to the six host verbs in runtime.ts.
  */
 import type { PromptInput } from "../content.js";
-import type { Answer, Request, Tool } from "../types.js";
+import type { Answer, Request, Tool, ToolContext } from "../types.js";
 import { AgentRuntime, type AgentDef, type Budget, type RuntimeOptions, type TaskResult } from "./runtime.js";
 import { Loop, type Completion, type Guardrail } from "./loop.js";
 import type { ClientOptions } from "../client.js";
@@ -93,6 +93,8 @@ export declare class Agent {
      * case the tree stays parked and `result.runtime.resume(answer)` continues it.
      */
     run(prompt: PromptInput, opts?: AgentRunOptions): Promise<AgentRunResult>;
+    /** `run` that interrupts the child when `signal` aborts. */
+    private runSignal;
     /**
      * 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
@@ -100,6 +102,15 @@ export declare class Agent {
      * `{agent, turns, totalTokens}`.
      */
     asTool(opts?: AgentRunOptions): Tool;
+    /**
+     * `asTool` with options built per call from the calling tool's context (SPEC §4C), so the
+     * child runs under the parent turn's gates: set `hooks` (the same beforeTool permission gate —
+     * it also sees the child's tool calls), `waitFor` (the same ask bridge) and `onMetric`. A
+     * `hooks` on the agent's own spec replaces `opts.hooks` for that agent, so leave it unset when
+     * the gate must hold. When the calling turn is cancelled (`ctx.signal`), the child is
+     * interrupted and the tool returns a `cancelled:` error result.
+     */
+    asToolWith(per: (ctx?: ToolContext) => AgentRunOptions): Tool;
 }
 /** The one new noun: define an agent. */
 export declare function agent(name: string, spec: AgentSpec): Agent;

package/dist/agents/agent.js

@@ -73,6 +73,32 @@ export class Agent {
             await runtime.close(runtime.root);
         return { ...r, runtime };
     }
+    /** `run` that interrupts the child when `signal` aborts. */
+    async runSignal(prompt, opts, signal) {
+        if (!signal)
+            return this.run(prompt, opts);
+        const reason = () => (signal.reason instanceof Error ? signal.reason.message : String(signal.reason ?? "aborted"));
+        if (signal.aborted)
+            return { text: reason(), isError: true, turns: 0, totalTokens: 0, cancelled: true };
+        const runtime = this.createRuntime(opts);
+        const h = runtime.spawn(runtime.root, this.name);
+        if (isVerbError(h))
+            return { text: h.error, isError: true, turns: 0, totalTokens: 0 };
+        const onAbort = () => void runtime.close(runtime.root, { force: true }).catch(() => { });
+        signal.addEventListener("abort", onAbort, { once: true });
+        try {
+            const woke = runtime.wake(h, prompt);
+            const r = await runtime.wait(h);
+            if (signal.aborted)
+                return { text: reason(), isError: true, turns: r.turns, totalTokens: r.totalTokens, cancelled: true };
+            if (woke.ok && r.status !== "pending")
+                await runtime.close(runtime.root);
+            return r;
+        }
+        finally {
+            signal.removeEventListener("abort", onAbort);
+        }
+    }
     /**
      * 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
@@ -80,6 +106,17 @@ export class Agent {
      * `{agent, turns, totalTokens}`.
      */
     asTool(opts = {}) {
+        return this.asToolWith(() => opts);
+    }
+    /**
+     * `asTool` with options built per call from the calling tool's context (SPEC §4C), so the
+     * child runs under the parent turn's gates: set `hooks` (the same beforeTool permission gate —
+     * it also sees the child's tool calls), `waitFor` (the same ask bridge) and `onMetric`. A
+     * `hooks` on the agent's own spec replaces `opts.hooks` for that agent, so leave it unset when
+     * the gate must hold. When the calling turn is cancelled (`ctx.signal`), the child is
+     * interrupted and the tool returns a `cancelled:` error result.
+     */
+    asToolWith(per) {
         return defineTool({
             name: this.name,
             description: this.spec.does,
@@ -88,13 +125,12 @@ export class Agent {
                 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 },
-                };
+            run: async (args, ctx) => {
+                const r = await this.runSignal(String(args.prompt), per(ctx), ctx?.signal);
+                const metadata = { agent: this.name, turns: r.turns, totalTokens: r.totalTokens };
+                if (r.cancelled)
+                    return { output: `cancelled: ${r.text}`, isError: true, metadata };
+                return { output: r.text, isError: r.isError, metadata };
             },
         });
     }

package/dist/agents/compaction.d.ts

@@ -32,6 +32,25 @@ export interface CompactorOptions {
      * default. Composes with the memory builtin.
      */
     flushToMemory?: boolean;
+    /**
+     * Called after each compaction with what changed, so a host can tell its UI or log (SPEC §4C).
+     * Never called on a no-op. Awaited before the next model call.
+     */
+    onCompact?: (info: CompactInfo) => void | Promise<void>;
+}
+/** One compaction, for {@link CompactorOptions.onCompact}. Token counts come from `countTokens`. */
+export interface CompactInfo {
+    tokensBefore: number;
+    tokensAfter: number;
+    messagesBefore: number;
+    messagesAfter: number;
+    /** How many messages were folded into the summary. */
+    summarized: number;
+    /** The text `summarize` returned (without the header line). */
+    summary: string;
+    /** The summarized messages, verbatim, so a host can persist them (the loop saves only the
+     * compacted transcript). */
+    folded: Message[];
 }
 /** The event a `beforeLLM` hook receives (§8). */
 export interface BeforeLLMEvent {

package/dist/agents/compaction.js

@@ -89,7 +89,8 @@ export function compactor(opts) {
     const keepTail = opts.keepTail ?? Math.floor(opts.maxTokens / 2);
     return async (ev) => {
         const msgs = ev.messages;
-        if (count(msgs) <= opts.maxTokens)
+        const before = count(msgs);
+        if (before <= 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;
@@ -97,16 +98,37 @@ export function compactor(opts) {
         const split = findTailStart(msgs, headEnd, keepTail, count);
         if (split <= headEnd)
             return undefined; // nothing safely compactible
-        const older = msgs.slice(headEnd, split);
+        let older = msgs.slice(headEnd, split);
+        const tail = msgs.slice(split);
+        // The latest user prompt is never summarized away. When the only clean boundary is the first
+        // message after the system prompt (one prompt followed by a long agentic run), keep that
+        // prompt verbatim and summarize the work after it: [system, prompt, summary].
+        let pinned = [];
+        if (split === msgs.length && headEnd < msgs.length && isBoundary(msgs[headEnd])) {
+            pinned = msgs.slice(headEnd, headEnd + 1);
+            older = msgs.slice(headEnd + 1);
+        }
         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] };
+        const out = [...system, ...pinned, summaryMsg, ...flushNote, ...tail];
+        const after = count(out);
+        if (after >= before)
+            return undefined; // compaction would not shrink the transcript → no-op
+        await opts.onCompact?.({
+            tokensBefore: before,
+            tokensAfter: after,
+            messagesBefore: msgs.length,
+            messagesAfter: out.length,
+            summarized: older.length,
+            summary,
+            folded: older,
+        });
+        return { messages: out };
     };
 }
 /**

package/dist/agents/runtime.d.ts

@@ -293,6 +293,11 @@ export interface RuntimeOptions {
     /** §8 observability sink applied to EVERY agent's client, unless that agent's def
      * sets its own `onMetric`. Resolves independently of `hooks`. Forwarded verbatim. */
     onMetric?: (ev: MetricEvent) => void;
+    /** The runtime-level §10 interpreter (SPEC §4C): answers a suspension when no agent on the
+     * handle's chain has its own `waitFor`. Absent ⇒ unchanged (the suspension goes durable). A
+     * host running an agent as a tool (`asToolWith`) sets it so the child's asks reach the same
+     * bridge as the parent turn. */
+    waitFor?: (request: Request) => Promise<Answer>;
 }
 /**
  * The §7D agent runtime: six host verbs over a tree of Handles, three loud

package/dist/agents/runtime.js

@@ -595,12 +595,23 @@ export class AgentRuntime {
      * escalation traced (nearest interpreter wins; the Request's `data.path` names
      * the suspended subtree that is asking). */
     wrapWaitFor(h) {
-        const waitFor = h.def.waitFor;
+        const own = h.def.waitFor;
+        let waitFor = own;
+        if (!waitFor && this.opts.waitFor) {
+            // The runtime-level bridge answers only when NO agent on the chain has its own waitFor;
+            // otherwise the ask escalates to that nearest interpreter, as before.
+            let a = h.parent;
+            while (a && !a.def.waitFor)
+                a = a.parent;
+            if (!a)
+                waitFor = this.opts.waitFor;
+        }
         if (!waitFor)
             return undefined;
+        const answerer = own ? h.id : this.root.id;
         return async (req) => {
             const path = Array.isArray(req.data?.path) ? req.data.path.join("/") : h.id;
-            this.t(`${path}: escalate → ${h.id} answers ("nearest interpreter")`);
+            this.t(`${path}: escalate → ${answerer} answers ("nearest interpreter")`);
             return waitFor(req);
         };
     }

package/dist/builtin.d.ts

@@ -1,4 +1,5 @@
 import type { Tool } from "./types.js";
+import { BackgroundShells, type WebSearchFunc } from "./builtin_extras.js";
 /**
  * Config for the single global builtin toggle (mirrors MCP isEnabled precedence),
  * plus the host boundary: which interpreter `bash` runs, what a relative path
@@ -28,6 +29,21 @@ export type BuiltinsConfig = boolean | {
      * builtins, NOT a sandbox — `bash` still reaches the whole filesystem.
      */
     confineToBaseDir?: boolean;
+    /**
+     * POSIX wait in ms between SIGTERM and SIGKILL of a timed-out or cancelled
+     * `bash` job's process group. Absent or 0 ⇒ 2000. No effect on Windows,
+     * which has no graceful stop for a console process (SPEC §4A).
+     */
+    killGraceMs?: number;
+    /**
+     * Opt-in (SPEC §4C): `bash` takes `run_in_background` and the `bash_output` / `kill_shell`
+     * tools exist. The host owns the registry: call `closeAll()` on shutdown.
+     */
+    background?: BackgroundShells;
+    /** Opt-in (SPEC §4C): adds a `websearch` tool backed by this provider. The library ships none. */
+    webSearch?: WebSearchFunc;
+    /** Opt-in (SPEC §4C): adds the `notebook_edit` tool for .ipynb cells. */
+    notebookEdit?: boolean;
 };
 /**
  * Whether the builtin source is on. Default ON. Same precedence as MCP: