toolnexus 0.15.0 → 0.16.0

package/dist/client.d.ts

@@ -333,6 +333,51 @@ export declare class Client {
     private streamAnthropic;
 }
 export declare function createClient(opts: ClientOptions): Client;
+/** One tool call an in-process model asks for. Flat on purpose: the nested
+ *  `function: {}` wrapper is a wire detail, not something a model author should type.
+ *  `arguments` may be a structured value (encoded for you) or an encoded string. */
+export interface InProcessToolCall {
+    id?: string;
+    name: string;
+    arguments?: unknown;
+}
+/** What an in-process model is handed: the assembled request for THIS call. */
+export interface InProcessRequest {
+    messages: any[];
+    tools?: any[];
+    model: string;
+    /** Every other key the client assembled, for a model that wants them. */
+    body: Record<string, any>;
+}
+/** What an in-process model returns: exactly one assistant message. Return `content`
+ *  to finish, or `toolCalls` to ask for tools — never both. `usage` is optional; when
+ *  omitted the run reports zero tokens rather than failing. */
+export interface InProcessResponse {
+    content?: string;
+    toolCalls?: InProcessToolCall[];
+    usage?: {
+        promptTokens?: number;
+        completionTokens?: number;
+        totalTokens?: number;
+    };
+}
+/** Options for {@link createInProcessClient}: every client option EXCEPT the three
+ *  that describe a wire — `baseUrl`, `apiKey` and `style` — plus `generate`. */
+export type InProcessOptions = Omit<ClientOptions, "baseUrl" | "apiKey" | "style" | "fetch"> & {
+    /** Your model. Receives the assembled request, returns one assistant message. */
+    generate: (request: InProcessRequest) => InProcessResponse | Promise<InProcessResponse>;
+};
+/**
+ * A client backed by a model running IN THIS PROCESS — no server, no socket, and no
+ * HTTP types to construct.
+ *
+ * This is a second constructor, not a second seam: it builds on the same injectable
+ * transport that `fetch`/`httpClient` uses, so the tool-calling loop, MCP servers,
+ * skills, sub-agents, hooks, metrics and the completion gate all behave identically.
+ *
+ * Streaming is refused rather than faked — see the thrown error.
+ */
+export declare function createInProcessClient(opts: InProcessOptions): Client;
 /** Stateful multi-turn conversation: each send() continues the same transcript (memory). */
 export declare class Conversation {
     private readonly client;

package/dist/client.js

@@ -950,6 +950,84 @@ export class Client {
 export function createClient(opts) {
     return new Client(opts);
 }
+/** The sentinel base URL. Never dialled — the transport below answers every request
+ *  before the network is reached — but the client builds a URL string internally, so
+ *  it must be syntactically valid. `.invalid` is reserved by RFC 2606 precisely so a
+ *  name can never resolve. */
+const IN_PROCESS_BASE_URL = "http://in-process.invalid/v1";
+/**
+ * A client backed by a model running IN THIS PROCESS — no server, no socket, and no
+ * HTTP types to construct.
+ *
+ * This is a second constructor, not a second seam: it builds on the same injectable
+ * transport that `fetch`/`httpClient` uses, so the tool-calling loop, MCP servers,
+ * skills, sub-agents, hooks, metrics and the completion gate all behave identically.
+ *
+ * Streaming is refused rather than faked — see the thrown error.
+ */
+export function createInProcessClient(opts) {
+    const { generate, ...rest } = opts;
+    if (typeof generate !== "function") {
+        throw new Error("toolnexus: createInProcessClient requires a `generate` function");
+    }
+    const inProcessFetch = async (_url, init) => {
+        const body = JSON.parse(String(init?.body ?? "{}"));
+        // A generate() returns a whole answer, so a stream would be one chunk pretending
+        // to be many. Content and delta-count assertions cannot tell that from a real
+        // stream, so refuse instead of degrading silently.
+        if (body.stream) {
+            throw new Error("toolnexus: createInProcessClient does not support streaming — `generate` returns a " +
+                "complete answer. Use the non-streaming run, or supply a `fetch`/transport that streams.");
+        }
+        const answer = await generate({
+            messages: body.messages ?? [],
+            tools: body.tools,
+            model: body.model,
+            body,
+        });
+        const message = { role: "assistant" };
+        if (answer.toolCalls && answer.toolCalls.length > 0) {
+            message.tool_calls = answer.toolCalls.map((c, i) => ({
+                id: c.id ?? `call_${i}`,
+                type: "function",
+                function: {
+                    name: c.name,
+                    // A string is already encoded; anything else is encoded here so a model
+                    // author never has to think about the wire.
+                    arguments: typeof c.arguments === "string" ? c.arguments : JSON.stringify(c.arguments ?? {}),
+                },
+            }));
+        }
+        else {
+            message.content = answer.content ?? "";
+        }
+        const u = answer.usage ?? {};
+        const prompt = u.promptTokens ?? 0;
+        const completion = u.completionTokens ?? 0;
+        return new Response(JSON.stringify({
+            choices: [{ index: 0, message, finish_reason: message.tool_calls ? "tool_calls" : "stop" }],
+            usage: {
+                prompt_tokens: prompt,
+                completion_tokens: completion,
+                total_tokens: u.totalTokens ?? prompt + completion,
+            },
+        }), { status: 200, headers: { "content-type": "application/json" } });
+    };
+    return new Client({
+        // Retries default to ZERO here, unlike a network client. There is no wire, so
+        // there is no transient failure to ride out: whatever `generate` throws will
+        // throw again. Retrying it only buys backoff before the user sees their own bug —
+        // measured at 3.7s for the streaming refusal before this default. A host whose
+        // model really is flaky (a GPU that OOMs, say) can still set `retries`.
+        retries: 0,
+        ...rest,
+        baseUrl: IN_PROCESS_BASE_URL,
+        style: "openai",
+        // An in-process model has no endpoint to authenticate to, so the host must never need a key — but the client resolves one from the environment and fails when it finds none. A sentinel keeps that resolution from ever running. Caught by CI, which has no OPENROUTER_API_KEY; every local run passed because a developer shell has one.
+        apiKey: "in-process",
+        fetch: inProcessFetch,
+    });
+}
 /** Stateful multi-turn conversation: each send() continues the same transcript (memory). */
 export class Conversation {
     client;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolnexus",
-  "version": "0.15.0",
+  "version": "0.16.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/agent-hooks.test.ts test/home.test.ts test/compaction.test.ts test/loop.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 test/loop.test.ts test/in-process.test.ts",
     "example": "node --experimental-strip-types examples/basic.ts"
   },
   "keywords": [

package/src/client.ts

@@ -1097,6 +1097,135 @@ export function createClient(opts: ClientOptions): Client {
   return new Client(opts)
 }
 
+
+// --------------------------------------------------------------------------- //
+// In-process models (SPEC §8 Gap 2, semantic form).
+// --------------------------------------------------------------------------- //
+
+/** One tool call an in-process model asks for. Flat on purpose: the nested
+ *  `function: {}` wrapper is a wire detail, not something a model author should type.
+ *  `arguments` may be a structured value (encoded for you) or an encoded string. */
+export interface InProcessToolCall {
+  id?: string
+  name: string
+  arguments?: unknown
+}
+
+/** What an in-process model is handed: the assembled request for THIS call. */
+export interface InProcessRequest {
+  messages: any[]
+  tools?: any[]
+  model: string
+  /** Every other key the client assembled, for a model that wants them. */
+  body: Record<string, any>
+}
+
+/** What an in-process model returns: exactly one assistant message. Return `content`
+ *  to finish, or `toolCalls` to ask for tools — never both. `usage` is optional; when
+ *  omitted the run reports zero tokens rather than failing. */
+export interface InProcessResponse {
+  content?: string
+  toolCalls?: InProcessToolCall[]
+  usage?: { promptTokens?: number; completionTokens?: number; totalTokens?: number }
+}
+
+/** Options for {@link createInProcessClient}: every client option EXCEPT the three
+ *  that describe a wire — `baseUrl`, `apiKey` and `style` — plus `generate`. */
+export type InProcessOptions = Omit<ClientOptions, "baseUrl" | "apiKey" | "style" | "fetch"> & {
+  /** Your model. Receives the assembled request, returns one assistant message. */
+  generate: (request: InProcessRequest) => InProcessResponse | Promise<InProcessResponse>
+}
+
+/** The sentinel base URL. Never dialled — the transport below answers every request
+ *  before the network is reached — but the client builds a URL string internally, so
+ *  it must be syntactically valid. `.invalid` is reserved by RFC 2606 precisely so a
+ *  name can never resolve. */
+const IN_PROCESS_BASE_URL = "http://in-process.invalid/v1"
+
+/**
+ * A client backed by a model running IN THIS PROCESS — no server, no socket, and no
+ * HTTP types to construct.
+ *
+ * This is a second constructor, not a second seam: it builds on the same injectable
+ * transport that `fetch`/`httpClient` uses, so the tool-calling loop, MCP servers,
+ * skills, sub-agents, hooks, metrics and the completion gate all behave identically.
+ *
+ * Streaming is refused rather than faked — see the thrown error.
+ */
+export function createInProcessClient(opts: InProcessOptions): Client {
+  const { generate, ...rest } = opts
+  if (typeof generate !== "function") {
+    throw new Error("toolnexus: createInProcessClient requires a `generate` function")
+  }
+
+  const inProcessFetch: typeof fetch = async (_url, init) => {
+    const body = JSON.parse(String((init as any)?.body ?? "{}"))
+
+    // A generate() returns a whole answer, so a stream would be one chunk pretending
+    // to be many. Content and delta-count assertions cannot tell that from a real
+    // stream, so refuse instead of degrading silently.
+    if (body.stream) {
+      throw new Error(
+        "toolnexus: createInProcessClient does not support streaming — `generate` returns a " +
+          "complete answer. Use the non-streaming run, or supply a `fetch`/transport that streams.",
+      )
+    }
+
+    const answer = await generate({
+      messages: body.messages ?? [],
+      tools: body.tools,
+      model: body.model,
+      body,
+    })
+
+    const message: Record<string, any> = { role: "assistant" }
+    if (answer.toolCalls && answer.toolCalls.length > 0) {
+      message.tool_calls = answer.toolCalls.map((c, i) => ({
+        id: c.id ?? `call_${i}`,
+        type: "function",
+        function: {
+          name: c.name,
+          // A string is already encoded; anything else is encoded here so a model
+          // author never has to think about the wire.
+          arguments: typeof c.arguments === "string" ? c.arguments : JSON.stringify(c.arguments ?? {}),
+        },
+      }))
+    } else {
+      message.content = answer.content ?? ""
+    }
+
+    const u = answer.usage ?? {}
+    const prompt = u.promptTokens ?? 0
+    const completion = u.completionTokens ?? 0
+    return new Response(
+      JSON.stringify({
+        choices: [{ index: 0, message, finish_reason: message.tool_calls ? "tool_calls" : "stop" }],
+        usage: {
+          prompt_tokens: prompt,
+          completion_tokens: completion,
+          total_tokens: u.totalTokens ?? prompt + completion,
+        },
+      }),
+      { status: 200, headers: { "content-type": "application/json" } },
+    )
+  }
+
+  return new Client({
+    // Retries default to ZERO here, unlike a network client. There is no wire, so
+    // there is no transient failure to ride out: whatever `generate` throws will
+    // throw again. Retrying it only buys backoff before the user sees their own bug —
+    // measured at 3.7s for the streaming refusal before this default. A host whose
+    // model really is flaky (a GPU that OOMs, say) can still set `retries`.
+    retries: 0,
+    ...(rest as ClientOptions),
+    baseUrl: IN_PROCESS_BASE_URL,
+    style: "openai",
+    // An in-process model has no endpoint to authenticate to, so the host must never need a key — but the client resolves one from the environment and fails when it finds none. A sentinel keeps that resolution from ever running. Caught by CI, which has no OPENROUTER_API_KEY; every local run passed because a developer shell has one.
+    apiKey: "in-process",
+    fetch: inProcessFetch,
+  })
+}
+
 /** Stateful multi-turn conversation: each send() continues the same transcript (memory). */
 export class Conversation {
   /** Full running transcript (system + user + assistant + tool messages). */