toolnexus 0.10.0 → 0.13.0

package/dist/agents/agent.d.ts

@@ -22,6 +22,12 @@ export interface AgentSpec {
     waitFor?: (request: Request) => Promise<Answer>;
     onSpawn?: AgentDef["onSpawn"];
     onClose?: AgentDef["onClose"];
+    /** §8 lifecycle callbacks for this agent (e.g. a §7F `compactor`). Set ⇒ replaces
+     * the runtime-wide `hooks` for this agent; forwarded verbatim. */
+    hooks?: AgentDef["hooks"];
+    /** §8 observability sink for this agent. Set ⇒ replaces the runtime-wide
+     * `onMetric` for this agent; resolves independently of `hooks`. */
+    onMetric?: AgentDef["onMetric"];
 }
 /** Runtime options for a one-shot `run`/`asTool` (the registry is derived). */
 export type AgentRunOptions = Omit<RuntimeOptions, "registry">;

package/dist/agents/agent.js

@@ -38,6 +38,8 @@ export class Agent {
             waitFor: this.spec.waitFor,
             onSpawn: this.spec.onSpawn,
             onClose: this.spec.onClose,
+            hooks: this.spec.hooks,
+            onMetric: this.spec.onMetric,
         };
         for (const t of this.spec.team ?? [])
             t.registry(acc);

package/dist/agents/runtime.d.ts

@@ -14,7 +14,7 @@
  * the ConversationStore. SPEC pins transitions, never scheduling — conformance is
  * identical per-handle transition traces against `examples/subagent-*` fixtures.
  */
-import { type ClientStyle, type ConversationStore } from "../client.js";
+import { type ClientStyle, type ConversationStore, type Hooks, type MetricEvent } from "../client.js";
 import type { Answer, Request, Tool } from "../types.js";
 /** Injectable time source. All runtime timers, timeouts, and deadlines use it. */
 export interface Clock {
@@ -68,6 +68,14 @@ export interface AgentDef {
     onSpawn?: (h: Handle) => void | Promise<void>;
     /** Runs before the final checkpoint on close. */
     onClose?: (h: Handle, reason: CloseReason) => void | Promise<void>;
+    /** §8 lifecycle callbacks for THIS agent's client. Set ⇒ REPLACES the runtime-wide
+     * `hooks` for this agent (never merged — composing two transcript rewrites has no
+     * defined order). Forwarded verbatim; the runtime never reads or wraps it.
+     * This is how a §7F compactor attaches per agent. */
+    hooks?: Hooks;
+    /** §8 observability sink for THIS agent's client. Set ⇒ REPLACES the runtime-wide
+     * `onMetric` for this agent. Resolves independently of `hooks`. Forwarded verbatim. */
+    onMetric?: (ev: MetricEvent) => void;
 }
 /** An unsolicited inbox item. Delivered ONLY as part of a fresh turn's coalesced
  * drain, with provenance rendered per item (non-ancestor senders are untrusted). */
@@ -202,6 +210,13 @@ export interface RuntimeOptions {
     maxConcurrentTurns?: number;
     /** Graceful-close bound for a running turn before escalating to abort. Default 200. */
     shutdownMs?: number;
+    /** §8 lifecycle callbacks applied to EVERY agent's client, unless that agent's
+     * def sets its own `hooks` (def-over-runtime, replace never merge). Forwarded
+     * verbatim into `createClient` — never composed, wrapped, reordered or read. */
+    hooks?: Hooks;
+    /** §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 §7D agent runtime: six host verbs over a tree of Handles, three loud

package/dist/agents/runtime.js

@@ -579,6 +579,10 @@ export class AgentRuntime {
                 fetch: this.gatedFetch(),
                 store: this.store,
                 waitFor: oneShotWaitFor ?? this.wrapWaitFor(h),
+                // The §8 seams: def-over-runtime, REPLACE never merge, each field resolved
+                // independently, forwarded verbatim (never composed, wrapped or read).
+                hooks: h.def.hooks ?? this.opts.hooks,
+                onMetric: h.def.onMetric ?? this.opts.onMetric,
             });
             const r = await client.ask(input, { toolkit, id: h.id, signal: h.abort.signal });
             h.turnsTotal += r.turns;

package/dist/client.d.ts

@@ -5,6 +5,7 @@
  */
 import type { Toolkit } from "./toolkit.js";
 import type { ToolResult, Request, Answer } from "./types.js";
+import type { TranslateRequest, TranslateResult } from "./translate.js";
 export type ClientStyle = "openai" | "anthropic";
 export interface ClientOptions {
     baseUrl: string;
@@ -256,6 +257,28 @@ export declare class Client {
         signal?: AbortSignal;
         history?: any[];
     }): Promise<RunResult>;
+    /**
+     * Single-turn translation (§11): exactly ONE provider call, returned in OpenAI shape.
+     * No agent loop, no tool execution, no conversation state — every call is
+     * self-contained, so this may be run statelessly and concurrently.
+     *
+     * The inbound half of the adapters: `toAnthropic`/`toGemini` send declarations out,
+     * this reads the provider's tool calls back in. A `toolkit` passed in the request is
+     * DECLARED and never executed.
+     *
+     * Retries/backoff, requestParams merging and the `llm` metric are shared with the loop.
+     * `beforeLLM`/`afterLLM` fire once; tool hooks do not, because no tool runs.
+     */
+    translate(req: TranslateRequest): Promise<TranslateResult>;
+    /** OpenAI-style upstream: near-passthrough. */
+    private translateOpenAI;
+    /** Anthropic-style upstream: the real translation. */
+    private translateAnthropic;
+    /**
+     * Renders a translate result's tool calls as an OpenAI `tool_calls` array, ready to put
+     * on an assistant message. Convenience for assembling a response envelope.
+     */
+    static toolCallsJSON(res: TranslateResult): any[];
     /**
      * Stateful ask. With an `id`, the client's `store` remembers the conversation:
      * it loads that id's transcript, runs, saves the updated transcript, and returns

package/dist/client.js

@@ -1,4 +1,5 @@
 import { pendingOf } from "./types.js";
+import { finishReasonFor, argsString, openAIMessagesToAnthropic, openAIToolsToAnthropic, openAIToolChoiceToAnthropic, hasSystemMessage, } from "./translate.js";
 /** Default conversation provider — keeps transcripts in memory for the client's lifetime. */
 export class InMemoryConversationStore {
     map = new Map();
@@ -228,6 +229,152 @@ export class Client {
             ? this.runAnthropic(prompt, ctx.toolkit, ctx.signal, ctx.history)
             : this.runOpenAI(prompt, ctx.toolkit, ctx.signal, ctx.history);
     }
+    /**
+     * Single-turn translation (§11): exactly ONE provider call, returned in OpenAI shape.
+     * No agent loop, no tool execution, no conversation state — every call is
+     * self-contained, so this may be run statelessly and concurrently.
+     *
+     * The inbound half of the adapters: `toAnthropic`/`toGemini` send declarations out,
+     * this reads the provider's tool calls back in. A `toolkit` passed in the request is
+     * DECLARED and never executed.
+     *
+     * Retries/backoff, requestParams merging and the `llm` metric are shared with the loop.
+     * `beforeLLM`/`afterLLM` fire once; tool hooks do not, because no tool runs.
+     */
+    async translate(req) {
+        return this.opts.style === "anthropic" ? this.translateAnthropic(req) : this.translateOpenAI(req);
+    }
+    /** OpenAI-style upstream: near-passthrough. */
+    async translateOpenAI(req) {
+        const key = resolveKey(this.opts);
+        const declared = [...(req.toolkit ? req.toolkit.toOpenAI() : []), ...(req.tools ?? [])];
+        let messages = (req.messages ?? []).slice();
+        const sys = req.system ?? this.opts.systemPrompt ?? "";
+        if (sys && !hasSystemMessage(messages))
+            messages = [{ role: "system", content: sys }, ...messages];
+        let tools = declared;
+        if (this.opts.hooks?.beforeLLM) {
+            const ov = await this.opts.hooks.beforeLLM({ messages, tools, model: this.opts.model, turn: 0 });
+            if (ov?.messages)
+                messages = ov.messages;
+            if (ov?.tools)
+                tools = ov.tools;
+        }
+        const body = { model: this.opts.model, messages };
+        if (tools.length)
+            body.tools = tools;
+        if (req.toolChoice !== undefined)
+            body.tool_choice = req.toolChoice;
+        if (req.maxTokens)
+            body.max_tokens = req.maxTokens;
+        const signal = this.makeSignal(req.signal);
+        {
+            const data = await this.llmCallJson(`${this.opts.baseUrl.replace(/\/$/, "")}/chat/completions`, {
+                method: "POST",
+                headers: { "content-type": "application/json", authorization: `Bearer ${key}`, ...this.opts.headers },
+                body: JSON.stringify(this.finalizeBody(body)),
+            }, signal, "openai");
+            if (this.opts.hooks?.afterLLM)
+                await this.opts.hooks.afterLLM({ response: data, model: this.opts.model, turn: 0 });
+            const usage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+            addUsage(usage, data.usage, "openai");
+            const choice = data.choices?.[0];
+            const toolCalls = (choice?.message?.tool_calls ?? []).map((tc) => ({
+                id: String(tc.id ?? ""),
+                name: String(tc.function?.name ?? ""),
+                arguments: argsString(tc.function?.arguments),
+            }));
+            return {
+                text: choice?.message?.content ?? "",
+                toolCalls,
+                finishReason: choice?.finish_reason ?? finishReasonFor(toolCalls.length > 0),
+                usage,
+                model: this.opts.model,
+                raw: data,
+            };
+        }
+    }
+    /** Anthropic-style upstream: the real translation. */
+    async translateAnthropic(req) {
+        const key = resolveKey(this.opts);
+        const base = this.opts.baseUrl.replace(/\/$/, "");
+        const endpoint = base.endsWith("/v1") ? `${base}/messages` : `${base}/v1/messages`;
+        const converted = openAIMessagesToAnthropic(req.messages ?? []);
+        let messages = converted.messages;
+        const system = req.system ?? this.opts.systemPrompt ?? converted.system;
+        let tools = [
+            ...(req.toolkit ? req.toolkit.toAnthropic() : []),
+            ...openAIToolsToAnthropic(req.tools),
+        ];
+        if (this.opts.hooks?.beforeLLM) {
+            const ov = await this.opts.hooks.beforeLLM({ messages, tools, model: this.opts.model, turn: 0 });
+            if (ov?.messages)
+                messages = ov.messages;
+            if (ov?.tools)
+                tools = ov.tools;
+        }
+        const body = {
+            model: this.opts.model,
+            max_tokens: req.maxTokens && req.maxTokens > 0 ? req.maxTokens : 4096,
+            messages,
+        };
+        if (system)
+            body.system = system;
+        if (tools.length)
+            body.tools = tools;
+        const tc = openAIToolChoiceToAnthropic(req.toolChoice);
+        if (tc)
+            body.tool_choice = tc;
+        const signal = this.makeSignal(req.signal);
+        {
+            const data = await this.llmCallJson(endpoint, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    "x-api-key": key,
+                    "anthropic-version": "2023-06-01",
+                    ...this.opts.headers,
+                },
+                body: JSON.stringify(this.finalizeBody(body)),
+            }, signal, "anthropic");
+            if (this.opts.hooks?.afterLLM)
+                await this.opts.hooks.afterLLM({ response: data, model: this.opts.model, turn: 0 });
+            const usage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+            addUsage(usage, data.usage, "anthropic");
+            const text = [];
+            const toolCalls = [];
+            for (const b of data.content ?? []) {
+                if (b?.type === "text")
+                    text.push(b.text ?? "");
+                else if (b?.type === "tool_use") {
+                    toolCalls.push({
+                        id: String(b.id ?? ""),
+                        name: String(b.name ?? ""),
+                        arguments: JSON.stringify(b.input ?? {}),
+                    });
+                }
+            }
+            return {
+                text: text.join(""),
+                toolCalls,
+                finishReason: finishReasonFor(toolCalls.length > 0, data.stop_reason),
+                usage,
+                model: this.opts.model,
+                raw: data,
+            };
+        }
+    }
+    /**
+     * Renders a translate result's tool calls as an OpenAI `tool_calls` array, ready to put
+     * on an assistant message. Convenience for assembling a response envelope.
+     */
+    static toolCallsJSON(res) {
+        return res.toolCalls.map((tc) => ({
+            id: tc.id,
+            type: "function",
+            function: { name: tc.name, arguments: tc.arguments },
+        }));
+    }
     /**
      * Stateful ask. With an `id`, the client's `store` remembers the conversation:
      * it loads that id's transcript, runs, saves the updated transcript, and returns

package/dist/index.d.ts

@@ -8,6 +8,7 @@ export * from "./a2a.js";
 export * from "./serve.js";
 export * from "./mcpserve.js";
 export * from "./adapters.js";
+export * from "./translate.js";
 export * from "./toolkit.js";
 export * from "./client.js";
 export * as agents from "./agents/index.js";

package/dist/index.js

@@ -8,6 +8,7 @@ export * from "./a2a.js";
 export * from "./serve.js";
 export * from "./mcpserve.js";
 export * from "./adapters.js";
+export * from "./translate.js";
 export * from "./toolkit.js";
 export * from "./client.js";
 export * as agents from "./agents/index.js";

package/dist/translate.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Single-turn translation — the translator path (SPEC.md §11, ADR-0011).
+ *
+ * `client.translate(request)` is toolnexus used as a pure wire-format translator: OpenAI
+ * shapes in, exactly ONE provider call, OpenAI shapes out. No agent loop, no tool
+ * execution, no conversation state — so a caller can run it statelessly.
+ *
+ * It is the INBOUND half of the §5 adapters: `toOpenAI`/`toAnthropic`/`toGemini` send
+ * declarations out, this reads the provider's tool calls back in.
+ *
+ * Use it when the CALLER owns the conversation and executes tools itself (the standard
+ * OpenAI function-calling posture). When toolnexus owns the conversation, use the agent
+ * loop with relay tools + `runWithAnswer` (§10) instead.
+ */
+import type { Toolkit } from "./toolkit.js";
+import type { Usage } from "./client.js";
+/** An OpenAI-shaped chat request, handed over verbatim (§11). */
+export interface TranslateRequest {
+    /**
+     * The OpenAI `messages` array, verbatim — including assistant turns carrying
+     * `tool_calls` and `tool`-role results carrying `tool_call_id`.
+     */
+    messages: any[];
+    /**
+     * The OpenAI `tools` array, verbatim
+     * (`{type:"function",function:{name,description,parameters}}`). Declaration-only —
+     * nothing here is ever executed.
+     */
+    tools?: any[];
+    /**
+     * Declares an ordinary toolkit's tools to the provider WITHOUT executing any of them —
+     * MCP tools, skills, native functions, A2A agents, builtins. Use this when you have a
+     * toolkit and want the model's tool CALLS handed back to you to dispatch yourself.
+     * Composes with `tools`; toolkit declarations come first.
+     */
+    toolkit?: Toolkit;
+    /** The OpenAI `tool_choice`, verbatim. Omitted when absent. */
+    toolChoice?: any;
+    /** Overrides the system prompt. Absent uses any `system` message found in `messages`. */
+    system?: string;
+    /** Overrides the per-provider default max tokens. */
+    maxTokens?: number;
+    /** Aborts the in-flight provider call. */
+    signal?: AbortSignal;
+}
+/** One tool call the model asked for, in OpenAI shape (§11). */
+export interface TranslatedToolCall {
+    /** The tool-call id the caller must echo on its `tool` result message. */
+    id: string;
+    /** The function name. */
+    name: string;
+    /** Arguments as a JSON **string** — the OpenAI wire form, echoable byte-for-byte. */
+    arguments: string;
+}
+/** An OpenAI-shaped single-turn result (§11). */
+export interface TranslateResult {
+    /** Assistant text ("" when the model only called tools). */
+    text: string;
+    /** The tool calls the model emitted, in provider order. None is ever dropped. */
+    toolCalls: TranslatedToolCall[];
+    /** The OpenAI finish reason. A turn with any tool call is always `"tool_calls"`. */
+    finishReason: "stop" | "tool_calls" | "length" | "content_filter";
+    /** This single call's token usage. */
+    usage: Usage;
+    /** The model that answered. */
+    model: string;
+    /** The provider's decoded response, for fields this type does not model. */
+    raw?: any;
+}
+/**
+ * Maps a provider stop reason onto an OpenAI finish reason. Tool calls win: a turn that
+ * emitted any tool call is always `"tool_calls"` to a conforming client.
+ */
+export declare function finishReasonFor(hasToolCalls: boolean, providerStop?: string): TranslateResult["finishReason"];
+/** Flattens an OpenAI `content` value to text: the string form and the parts-array form. */
+export declare function contentText(content: unknown): string;
+/** Parses a tool-call arguments value into an object, tolerating both wire forms. */
+export declare function argsObject(args: unknown): Record<string, unknown>;
+/** Renders a tool-call arguments value as the JSON string the OpenAI wire format uses. */
+export declare function argsString(args: unknown): string;
+/** Reads an assistant message's OpenAI `tool_calls`. */
+export declare function toolCallsOf(m: any): TranslatedToolCall[];
+/**
+ * Converts an OpenAI `messages` array into Anthropic-native messages plus the extracted
+ * system prompt, preserving the tool structure a text flattening destroys (§11):
+ *
+ * - an assistant turn's `tool_calls` become `tool_use` blocks (arguments re-parsed to objects),
+ * - a `tool`-role result becomes a `tool_result` block keyed by `tool_call_id`, MERGED into a
+ *   single user turn when consecutive (providers want one result-bearing turn per assistant turn),
+ * - `system`/`developer` messages are hoisted out, since Anthropic takes system separately.
+ */
+export declare function openAIMessagesToAnthropic(messages: any[]): {
+    messages: any[];
+    system: string;
+};
+/**
+ * Converts an OpenAI `tools` array into Anthropic tool declarations. Entries that are
+ * already provider-native pass through; anything unrecognized is skipped.
+ */
+export declare function openAIToolsToAnthropic(tools: any[] | undefined): any[];
+/**
+ * Maps OpenAI `tool_choice` onto Anthropic's shape. Returns undefined for absent/"auto"
+ * (the provider default) and for anything unrecognized.
+ */
+export declare function openAIToolChoiceToAnthropic(choice: unknown): any;
+/** True when the message list already carries a system-ish message. */
+export declare function hasSystemMessage(messages: any[]): boolean;

package/dist/translate.js

@@ -0,0 +1,195 @@
+/**
+ * Single-turn translation — the translator path (SPEC.md §11, ADR-0011).
+ *
+ * `client.translate(request)` is toolnexus used as a pure wire-format translator: OpenAI
+ * shapes in, exactly ONE provider call, OpenAI shapes out. No agent loop, no tool
+ * execution, no conversation state — so a caller can run it statelessly.
+ *
+ * It is the INBOUND half of the §5 adapters: `toOpenAI`/`toAnthropic`/`toGemini` send
+ * declarations out, this reads the provider's tool calls back in.
+ *
+ * Use it when the CALLER owns the conversation and executes tools itself (the standard
+ * OpenAI function-calling posture). When toolnexus owns the conversation, use the agent
+ * loop with relay tools + `runWithAnswer` (§10) instead.
+ */
+/**
+ * Maps a provider stop reason onto an OpenAI finish reason. Tool calls win: a turn that
+ * emitted any tool call is always `"tool_calls"` to a conforming client.
+ */
+export function finishReasonFor(hasToolCalls, providerStop) {
+    if (hasToolCalls)
+        return "tool_calls";
+    switch (providerStop) {
+        case "max_tokens":
+        case "length":
+            return "length";
+        case "refusal":
+        case "content_filter":
+            return "content_filter";
+        default:
+            return "stop";
+    }
+}
+/** Flattens an OpenAI `content` value to text: the string form and the parts-array form. */
+export function contentText(content) {
+    if (typeof content === "string")
+        return content;
+    if (Array.isArray(content)) {
+        return content
+            .map((p) => (p && typeof p === "object" && typeof p.text === "string" ? p.text : ""))
+            .join("");
+    }
+    return "";
+}
+/** Parses a tool-call arguments value into an object, tolerating both wire forms. */
+export function argsObject(args) {
+    if (args && typeof args === "object")
+        return args;
+    if (typeof args === "string" && args.trim()) {
+        try {
+            const parsed = JSON.parse(args);
+            if (parsed && typeof parsed === "object")
+                return parsed;
+        }
+        catch {
+            /* fall through to {} — a malformed arguments string is not fatal */
+        }
+    }
+    return {};
+}
+/** Renders a tool-call arguments value as the JSON string the OpenAI wire format uses. */
+export function argsString(args) {
+    if (typeof args === "string")
+        return args;
+    if (args && typeof args === "object")
+        return JSON.stringify(args);
+    return "{}";
+}
+/** Reads an assistant message's OpenAI `tool_calls`. */
+export function toolCallsOf(m) {
+    const raw = m?.tool_calls;
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const tc of raw) {
+        const fn = tc?.function;
+        if (!fn)
+            continue;
+        out.push({ id: String(tc.id ?? ""), name: String(fn.name ?? ""), arguments: argsString(fn.arguments) });
+    }
+    return out;
+}
+/**
+ * Converts an OpenAI `messages` array into Anthropic-native messages plus the extracted
+ * system prompt, preserving the tool structure a text flattening destroys (§11):
+ *
+ * - an assistant turn's `tool_calls` become `tool_use` blocks (arguments re-parsed to objects),
+ * - a `tool`-role result becomes a `tool_result` block keyed by `tool_call_id`, MERGED into a
+ *   single user turn when consecutive (providers want one result-bearing turn per assistant turn),
+ * - `system`/`developer` messages are hoisted out, since Anthropic takes system separately.
+ */
+export function openAIMessagesToAnthropic(messages) {
+    const out = [];
+    const systemParts = [];
+    let pendingResults = [];
+    const flush = () => {
+        if (pendingResults.length) {
+            out.push({ role: "user", content: pendingResults });
+            pendingResults = [];
+        }
+    };
+    for (const m of messages ?? []) {
+        if (!m || typeof m !== "object")
+            continue;
+        switch (m.role) {
+            case "system":
+            case "developer": {
+                flush();
+                const s = contentText(m.content);
+                if (s)
+                    systemParts.push(s);
+                break;
+            }
+            case "tool":
+            case "function": {
+                const block = { type: "tool_result", content: contentText(m.content) };
+                if (m.tool_call_id)
+                    block.tool_use_id = String(m.tool_call_id);
+                pendingResults.push(block);
+                break;
+            }
+            case "assistant": {
+                flush();
+                const blocks = [];
+                const s = contentText(m.content);
+                if (s)
+                    blocks.push({ type: "text", text: s });
+                for (const tc of toolCallsOf(m)) {
+                    blocks.push({ type: "tool_use", id: tc.id, name: tc.name, input: argsObject(tc.arguments) });
+                }
+                if (!blocks.length)
+                    break; // an empty assistant turn would be rejected
+                out.push({ role: "assistant", content: blocks });
+                break;
+            }
+            default: {
+                flush();
+                const s = contentText(m.content);
+                if (s)
+                    out.push({ role: "user", content: s });
+                else if (Array.isArray(m.content) && m.content.length)
+                    out.push({ role: "user", content: m.content });
+            }
+        }
+    }
+    flush();
+    return { messages: out, system: systemParts.join("\n\n") };
+}
+/**
+ * Converts an OpenAI `tools` array into Anthropic tool declarations. Entries that are
+ * already provider-native pass through; anything unrecognized is skipped.
+ */
+export function openAIToolsToAnthropic(tools) {
+    const out = [];
+    for (const t of tools ?? []) {
+        if (!t || typeof t !== "object")
+            continue;
+        const fn = t.function;
+        if (!fn) {
+            if (t.name)
+                out.push(t); // already native
+            continue;
+        }
+        if (!fn.name)
+            continue;
+        const decl = { name: fn.name };
+        if (fn.description)
+            decl.description = fn.description;
+        decl.input_schema = fn.parameters ?? { type: "object", properties: {} };
+        out.push(decl);
+    }
+    return out;
+}
+/**
+ * Maps OpenAI `tool_choice` onto Anthropic's shape. Returns undefined for absent/"auto"
+ * (the provider default) and for anything unrecognized.
+ */
+export function openAIToolChoiceToAnthropic(choice) {
+    if (typeof choice === "string") {
+        if (choice === "required" || choice === "any")
+            return { type: "any" };
+        if (choice === "none")
+            return { type: "none" };
+        return undefined;
+    }
+    if (choice && typeof choice === "object") {
+        const name = choice.function?.name;
+        if (name)
+            return { type: "tool", name };
+    }
+    return undefined;
+}
+/** True when the message list already carries a system-ish message. */
+export function hasSystemMessage(messages) {
+    return (messages ?? []).some((m) => m?.role === "system" || m?.role === "developer");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolnexus",
-  "version": "0.10.0",
+  "version": "0.13.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/agents.test.ts test/home.test.ts test/compaction.test.ts",
+    "test": "npm run build && node --experimental-strip-types --test test/unit.test.ts test/agents.test.ts test/agent-hooks.test.ts test/home.test.ts test/compaction.test.ts",
     "example": "node --experimental-strip-types examples/basic.ts"
   },
   "keywords": [

package/src/agents/agent.ts

@@ -32,6 +32,12 @@ export interface AgentSpec {
   waitFor?: (request: Request) => Promise<Answer>
   onSpawn?: AgentDef["onSpawn"]
   onClose?: AgentDef["onClose"]
+  /** §8 lifecycle callbacks for this agent (e.g. a §7F `compactor`). Set ⇒ replaces
+   * the runtime-wide `hooks` for this agent; forwarded verbatim. */
+  hooks?: AgentDef["hooks"]
+  /** §8 observability sink for this agent. Set ⇒ replaces the runtime-wide
+   * `onMetric` for this agent; resolves independently of `hooks`. */
+  onMetric?: AgentDef["onMetric"]
 }
 
 /** Runtime options for a one-shot `run`/`asTool` (the registry is derived). */
@@ -66,6 +72,8 @@ export class Agent {
       waitFor: this.spec.waitFor,
       onSpawn: this.spec.onSpawn,
       onClose: this.spec.onClose,
+      hooks: this.spec.hooks,
+      onMetric: this.spec.onMetric,
     }
     for (const t of this.spec.team ?? []) t.registry(acc)
     return acc

package/src/agents/runtime.ts

@@ -14,7 +14,7 @@
  * the ConversationStore. SPEC pins transitions, never scheduling — conformance is
  * identical per-handle transition traces against `examples/subagent-*` fixtures.
  */
-import { createClient, InMemoryConversationStore, type ClientStyle, type ConversationStore } from "../client.js"
+import { createClient, InMemoryConversationStore, type ClientStyle, type ConversationStore, type Hooks, type MetricEvent } from "../client.js"
 import { createToolkit, type Toolkit } from "../toolkit.js"
 import { defineTool } from "../native.js"
 import type { Answer, Request, Tool, ToolResult } from "../types.js"
@@ -90,6 +90,14 @@ export interface AgentDef {
   onSpawn?: (h: Handle) => void | Promise<void>
   /** Runs before the final checkpoint on close. */
   onClose?: (h: Handle, reason: CloseReason) => void | Promise<void>
+  /** §8 lifecycle callbacks for THIS agent's client. Set ⇒ REPLACES the runtime-wide
+   * `hooks` for this agent (never merged — composing two transcript rewrites has no
+   * defined order). Forwarded verbatim; the runtime never reads or wraps it.
+   * This is how a §7F compactor attaches per agent. */
+  hooks?: Hooks
+  /** §8 observability sink for THIS agent's client. Set ⇒ REPLACES the runtime-wide
+   * `onMetric` for this agent. Resolves independently of `hooks`. Forwarded verbatim. */
+  onMetric?: (ev: MetricEvent) => void
 }
 
 /** An unsolicited inbox item. Delivered ONLY as part of a fresh turn's coalesced
@@ -270,6 +278,13 @@ export interface RuntimeOptions {
   maxConcurrentTurns?: number
   /** Graceful-close bound for a running turn before escalating to abort. Default 200. */
   shutdownMs?: number
+  /** §8 lifecycle callbacks applied to EVERY agent's client, unless that agent's
+   * def sets its own `hooks` (def-over-runtime, replace never merge). Forwarded
+   * verbatim into `createClient` — never composed, wrapped, reordered or read. */
+  hooks?: Hooks
+  /** §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
 }
 
 interface GateWaiter {
@@ -748,6 +763,10 @@ export class AgentRuntime {
         fetch: this.gatedFetch(),
         store: this.store,
         waitFor: oneShotWaitFor ?? this.wrapWaitFor(h),
+        // The §8 seams: def-over-runtime, REPLACE never merge, each field resolved
+        // independently, forwarded verbatim (never composed, wrapped or read).
+        hooks: h.def.hooks ?? this.opts.hooks,
+        onMetric: h.def.onMetric ?? this.opts.onMetric,
       })
       const r = await client.ask(input, { toolkit, id: h.id, signal: h.abort!.signal })
       h.turnsTotal += r.turns

package/src/client.ts

@@ -6,6 +6,16 @@
 import type { Toolkit } from "./toolkit.js"
 import type { ToolResult, Request, Answer } from "./types.js"
 import { pendingOf } from "./types.js"
+import type { TranslateRequest, TranslateResult, TranslatedToolCall } from "./translate.js"
+import {
+  finishReasonFor,
+  contentText,
+  argsString,
+  openAIMessagesToAnthropic,
+  openAIToolsToAnthropic,
+  openAIToolChoiceToAnthropic,
+  hasSystemMessage,
+} from "./translate.js"
 
 export type ClientStyle = "openai" | "anthropic"
 
@@ -401,6 +411,159 @@ export class Client {
       : this.runOpenAI(prompt, ctx.toolkit, ctx.signal, ctx.history)
   }
 
+  /**
+   * Single-turn translation (§11): exactly ONE provider call, returned in OpenAI shape.
+   * No agent loop, no tool execution, no conversation state — every call is
+   * self-contained, so this may be run statelessly and concurrently.
+   *
+   * The inbound half of the adapters: `toAnthropic`/`toGemini` send declarations out,
+   * this reads the provider's tool calls back in. A `toolkit` passed in the request is
+   * DECLARED and never executed.
+   *
+   * Retries/backoff, requestParams merging and the `llm` metric are shared with the loop.
+   * `beforeLLM`/`afterLLM` fire once; tool hooks do not, because no tool runs.
+   */
+  async translate(req: TranslateRequest): Promise<TranslateResult> {
+    return this.opts.style === "anthropic" ? this.translateAnthropic(req) : this.translateOpenAI(req)
+  }
+
+  /** OpenAI-style upstream: near-passthrough. */
+  private async translateOpenAI(req: TranslateRequest): Promise<TranslateResult> {
+    const key = resolveKey(this.opts)
+    const declared = [...(req.toolkit ? req.toolkit.toOpenAI() : []), ...(req.tools ?? [])]
+    let messages = (req.messages ?? []).slice()
+    const sys = req.system ?? this.opts.systemPrompt ?? ""
+    if (sys && !hasSystemMessage(messages)) messages = [{ role: "system", content: sys }, ...messages]
+
+    let tools = declared
+    if (this.opts.hooks?.beforeLLM) {
+      const ov = await this.opts.hooks.beforeLLM({ messages, tools, model: this.opts.model, turn: 0 })
+      if (ov?.messages) messages = ov.messages
+      if (ov?.tools) tools = ov.tools
+    }
+
+    const body: Record<string, any> = { model: this.opts.model, messages }
+    if (tools.length) body.tools = tools
+    if (req.toolChoice !== undefined) body.tool_choice = req.toolChoice
+    if (req.maxTokens) body.max_tokens = req.maxTokens
+
+    const signal = this.makeSignal(req.signal)
+    {
+      const data = await this.llmCallJson(
+        `${this.opts.baseUrl.replace(/\/$/, "")}/chat/completions`,
+        {
+          method: "POST",
+          headers: { "content-type": "application/json", authorization: `Bearer ${key}`, ...this.opts.headers },
+          body: JSON.stringify(this.finalizeBody(body)),
+        },
+        signal,
+        "openai",
+      )
+      if (this.opts.hooks?.afterLLM) await this.opts.hooks.afterLLM({ response: data, model: this.opts.model, turn: 0 })
+      const usage: Usage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 }
+      addUsage(usage, data.usage, "openai")
+      const choice = data.choices?.[0]
+      const toolCalls: TranslatedToolCall[] = (choice?.message?.tool_calls ?? []).map((tc: any) => ({
+        id: String(tc.id ?? ""),
+        name: String(tc.function?.name ?? ""),
+        arguments: argsString(tc.function?.arguments),
+      }))
+      return {
+        text: choice?.message?.content ?? "",
+        toolCalls,
+        finishReason: choice?.finish_reason ?? finishReasonFor(toolCalls.length > 0),
+        usage,
+        model: this.opts.model,
+        raw: data,
+      }
+    }
+  }
+
+  /** Anthropic-style upstream: the real translation. */
+  private async translateAnthropic(req: TranslateRequest): Promise<TranslateResult> {
+    const key = resolveKey(this.opts)
+    const base = this.opts.baseUrl.replace(/\/$/, "")
+    const endpoint = base.endsWith("/v1") ? `${base}/messages` : `${base}/v1/messages`
+
+    const converted = openAIMessagesToAnthropic(req.messages ?? [])
+    let messages = converted.messages
+    const system = req.system ?? this.opts.systemPrompt ?? converted.system
+    let tools = [
+      ...(req.toolkit ? req.toolkit.toAnthropic() : []),
+      ...openAIToolsToAnthropic(req.tools),
+    ]
+
+    if (this.opts.hooks?.beforeLLM) {
+      const ov = await this.opts.hooks.beforeLLM({ messages, tools, model: this.opts.model, turn: 0 })
+      if (ov?.messages) messages = ov.messages
+      if (ov?.tools) tools = ov.tools
+    }
+
+    const body: Record<string, any> = {
+      model: this.opts.model,
+      max_tokens: req.maxTokens && req.maxTokens > 0 ? req.maxTokens : 4096,
+      messages,
+    }
+    if (system) body.system = system
+    if (tools.length) body.tools = tools
+    const tc = openAIToolChoiceToAnthropic(req.toolChoice)
+    if (tc) body.tool_choice = tc
+
+    const signal = this.makeSignal(req.signal)
+    {
+      const data = await this.llmCallJson(
+        endpoint,
+        {
+          method: "POST",
+          headers: {
+            "content-type": "application/json",
+            "x-api-key": key,
+            "anthropic-version": "2023-06-01",
+            ...this.opts.headers,
+          },
+          body: JSON.stringify(this.finalizeBody(body)),
+        },
+        signal,
+        "anthropic",
+      )
+      if (this.opts.hooks?.afterLLM) await this.opts.hooks.afterLLM({ response: data, model: this.opts.model, turn: 0 })
+      const usage: Usage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 }
+      addUsage(usage, data.usage, "anthropic")
+      const text: string[] = []
+      const toolCalls: TranslatedToolCall[] = []
+      for (const b of data.content ?? []) {
+        if (b?.type === "text") text.push(b.text ?? "")
+        else if (b?.type === "tool_use") {
+          toolCalls.push({
+            id: String(b.id ?? ""),
+            name: String(b.name ?? ""),
+            arguments: JSON.stringify(b.input ?? {}),
+          })
+        }
+      }
+      return {
+        text: text.join(""),
+        toolCalls,
+        finishReason: finishReasonFor(toolCalls.length > 0, data.stop_reason),
+        usage,
+        model: this.opts.model,
+        raw: data,
+      }
+    }
+  }
+
+  /**
+   * Renders a translate result's tool calls as an OpenAI `tool_calls` array, ready to put
+   * on an assistant message. Convenience for assembling a response envelope.
+   */
+  static toolCallsJSON(res: TranslateResult): any[] {
+    return res.toolCalls.map((tc) => ({
+      id: tc.id,
+      type: "function",
+      function: { name: tc.name, arguments: tc.arguments },
+    }))
+  }
+
   /**
    * Stateful ask. With an `id`, the client's `store` remembers the conversation:
    * it loads that id's transcript, runs, saves the updated transcript, and returns

package/src/index.ts

@@ -8,6 +8,7 @@ export * from "./a2a.js"
 export * from "./serve.js"
 export * from "./mcpserve.js"
 export * from "./adapters.js"
+export * from "./translate.js"
 export * from "./toolkit.js"
 export * from "./client.js"
 export * as agents from "./agents/index.js"

package/src/translate.ts

@@ -0,0 +1,242 @@
+/**
+ * Single-turn translation — the translator path (SPEC.md §11, ADR-0011).
+ *
+ * `client.translate(request)` is toolnexus used as a pure wire-format translator: OpenAI
+ * shapes in, exactly ONE provider call, OpenAI shapes out. No agent loop, no tool
+ * execution, no conversation state — so a caller can run it statelessly.
+ *
+ * It is the INBOUND half of the §5 adapters: `toOpenAI`/`toAnthropic`/`toGemini` send
+ * declarations out, this reads the provider's tool calls back in.
+ *
+ * Use it when the CALLER owns the conversation and executes tools itself (the standard
+ * OpenAI function-calling posture). When toolnexus owns the conversation, use the agent
+ * loop with relay tools + `runWithAnswer` (§10) instead.
+ */
+
+import type { Toolkit } from "./toolkit.js"
+import type { Usage } from "./client.js"
+
+/** An OpenAI-shaped chat request, handed over verbatim (§11). */
+export interface TranslateRequest {
+  /**
+   * The OpenAI `messages` array, verbatim — including assistant turns carrying
+   * `tool_calls` and `tool`-role results carrying `tool_call_id`.
+   */
+  messages: any[]
+  /**
+   * The OpenAI `tools` array, verbatim
+   * (`{type:"function",function:{name,description,parameters}}`). Declaration-only —
+   * nothing here is ever executed.
+   */
+  tools?: any[]
+  /**
+   * Declares an ordinary toolkit's tools to the provider WITHOUT executing any of them —
+   * MCP tools, skills, native functions, A2A agents, builtins. Use this when you have a
+   * toolkit and want the model's tool CALLS handed back to you to dispatch yourself.
+   * Composes with `tools`; toolkit declarations come first.
+   */
+  toolkit?: Toolkit
+  /** The OpenAI `tool_choice`, verbatim. Omitted when absent. */
+  toolChoice?: any
+  /** Overrides the system prompt. Absent uses any `system` message found in `messages`. */
+  system?: string
+  /** Overrides the per-provider default max tokens. */
+  maxTokens?: number
+  /** Aborts the in-flight provider call. */
+  signal?: AbortSignal
+}
+
+/** One tool call the model asked for, in OpenAI shape (§11). */
+export interface TranslatedToolCall {
+  /** The tool-call id the caller must echo on its `tool` result message. */
+  id: string
+  /** The function name. */
+  name: string
+  /** Arguments as a JSON **string** — the OpenAI wire form, echoable byte-for-byte. */
+  arguments: string
+}
+
+/** An OpenAI-shaped single-turn result (§11). */
+export interface TranslateResult {
+  /** Assistant text ("" when the model only called tools). */
+  text: string
+  /** The tool calls the model emitted, in provider order. None is ever dropped. */
+  toolCalls: TranslatedToolCall[]
+  /** The OpenAI finish reason. A turn with any tool call is always `"tool_calls"`. */
+  finishReason: "stop" | "tool_calls" | "length" | "content_filter"
+  /** This single call's token usage. */
+  usage: Usage
+  /** The model that answered. */
+  model: string
+  /** The provider's decoded response, for fields this type does not model. */
+  raw?: any
+}
+
+/**
+ * Maps a provider stop reason onto an OpenAI finish reason. Tool calls win: a turn that
+ * emitted any tool call is always `"tool_calls"` to a conforming client.
+ */
+export function finishReasonFor(hasToolCalls: boolean, providerStop?: string): TranslateResult["finishReason"] {
+  if (hasToolCalls) return "tool_calls"
+  switch (providerStop) {
+    case "max_tokens":
+    case "length":
+      return "length"
+    case "refusal":
+    case "content_filter":
+      return "content_filter"
+    default:
+      return "stop"
+  }
+}
+
+/** Flattens an OpenAI `content` value to text: the string form and the parts-array form. */
+export function contentText(content: unknown): string {
+  if (typeof content === "string") return content
+  if (Array.isArray(content)) {
+    return content
+      .map((p) => (p && typeof p === "object" && typeof (p as any).text === "string" ? (p as any).text : ""))
+      .join("")
+  }
+  return ""
+}
+
+/** Parses a tool-call arguments value into an object, tolerating both wire forms. */
+export function argsObject(args: unknown): Record<string, unknown> {
+  if (args && typeof args === "object") return args as Record<string, unknown>
+  if (typeof args === "string" && args.trim()) {
+    try {
+      const parsed = JSON.parse(args)
+      if (parsed && typeof parsed === "object") return parsed
+    } catch {
+      /* fall through to {} — a malformed arguments string is not fatal */
+    }
+  }
+  return {}
+}
+
+/** Renders a tool-call arguments value as the JSON string the OpenAI wire format uses. */
+export function argsString(args: unknown): string {
+  if (typeof args === "string") return args
+  if (args && typeof args === "object") return JSON.stringify(args)
+  return "{}"
+}
+
+/** Reads an assistant message's OpenAI `tool_calls`. */
+export function toolCallsOf(m: any): TranslatedToolCall[] {
+  const raw = m?.tool_calls
+  if (!Array.isArray(raw)) return []
+  const out: TranslatedToolCall[] = []
+  for (const tc of raw) {
+    const fn = tc?.function
+    if (!fn) continue
+    out.push({ id: String(tc.id ?? ""), name: String(fn.name ?? ""), arguments: argsString(fn.arguments) })
+  }
+  return out
+}
+
+/**
+ * Converts an OpenAI `messages` array into Anthropic-native messages plus the extracted
+ * system prompt, preserving the tool structure a text flattening destroys (§11):
+ *
+ * - an assistant turn's `tool_calls` become `tool_use` blocks (arguments re-parsed to objects),
+ * - a `tool`-role result becomes a `tool_result` block keyed by `tool_call_id`, MERGED into a
+ *   single user turn when consecutive (providers want one result-bearing turn per assistant turn),
+ * - `system`/`developer` messages are hoisted out, since Anthropic takes system separately.
+ */
+export function openAIMessagesToAnthropic(messages: any[]): { messages: any[]; system: string } {
+  const out: any[] = []
+  const systemParts: string[] = []
+  let pendingResults: any[] = []
+
+  const flush = () => {
+    if (pendingResults.length) {
+      out.push({ role: "user", content: pendingResults })
+      pendingResults = []
+    }
+  }
+
+  for (const m of messages ?? []) {
+    if (!m || typeof m !== "object") continue
+    switch (m.role) {
+      case "system":
+      case "developer": {
+        flush()
+        const s = contentText(m.content)
+        if (s) systemParts.push(s)
+        break
+      }
+      case "tool":
+      case "function": {
+        const block: any = { type: "tool_result", content: contentText(m.content) }
+        if (m.tool_call_id) block.tool_use_id = String(m.tool_call_id)
+        pendingResults.push(block)
+        break
+      }
+      case "assistant": {
+        flush()
+        const blocks: any[] = []
+        const s = contentText(m.content)
+        if (s) blocks.push({ type: "text", text: s })
+        for (const tc of toolCallsOf(m)) {
+          blocks.push({ type: "tool_use", id: tc.id, name: tc.name, input: argsObject(tc.arguments) })
+        }
+        if (!blocks.length) break // an empty assistant turn would be rejected
+        out.push({ role: "assistant", content: blocks })
+        break
+      }
+      default: {
+        flush()
+        const s = contentText(m.content)
+        if (s) out.push({ role: "user", content: s })
+        else if (Array.isArray(m.content) && m.content.length) out.push({ role: "user", content: m.content })
+      }
+    }
+  }
+  flush()
+  return { messages: out, system: systemParts.join("\n\n") }
+}
+
+/**
+ * Converts an OpenAI `tools` array into Anthropic tool declarations. Entries that are
+ * already provider-native pass through; anything unrecognized is skipped.
+ */
+export function openAIToolsToAnthropic(tools: any[] | undefined): any[] {
+  const out: any[] = []
+  for (const t of tools ?? []) {
+    if (!t || typeof t !== "object") continue
+    const fn = (t as any).function
+    if (!fn) {
+      if ((t as any).name) out.push(t) // already native
+      continue
+    }
+    if (!fn.name) continue
+    const decl: any = { name: fn.name }
+    if (fn.description) decl.description = fn.description
+    decl.input_schema = fn.parameters ?? { type: "object", properties: {} }
+    out.push(decl)
+  }
+  return out
+}
+
+/**
+ * Maps OpenAI `tool_choice` onto Anthropic's shape. Returns undefined for absent/"auto"
+ * (the provider default) and for anything unrecognized.
+ */
+export function openAIToolChoiceToAnthropic(choice: unknown): any {
+  if (typeof choice === "string") {
+    if (choice === "required" || choice === "any") return { type: "any" }
+    if (choice === "none") return { type: "none" }
+    return undefined
+  }
+  if (choice && typeof choice === "object") {
+    const name = (choice as any).function?.name
+    if (name) return { type: "tool", name }
+  }
+  return undefined
+}
+
+/** True when the message list already carries a system-ish message. */
+export function hasSystemMessage(messages: any[]): boolean {
+  return (messages ?? []).some((m) => m?.role === "system" || m?.role === "developer")
+}