@mindees/ai 0.1.0

package/dist/sse.js

@@ -0,0 +1,81 @@
+import { AiError } from "./errors.js";
+//#region src/sse.ts
+/**
+* A tiny, hand-rolled Server-Sent Events parser (no `eventsource` dep) for the server
+* backend's streaming responses. Pure-TS: buffers across chunk boundaries, joins
+* multi-line `data:` fields, skips `:` comments / keep-alives, and is driven by an
+* `AsyncIterable<string>` so it's golden-fixture-testable with zero network. See
+* `docs/adr/0018-synapse-server-backend.md`.
+*
+* @module
+*/
+/**
+* Cap on un-dispatched parser state (chars, not bytes — we measure post-decode string
+* length). Bounds BOTH a single line that never gets a newline AND an event whose `data:`
+* lines accumulate without a blank-line terminator, so a hostile/buggy server can't
+* exhaust memory (or stall the mid-stream abort) by streaming endless data with no event
+* boundary.
+*/
+const MAX_SSE_BUFFER = 8 * 1024 * 1024;
+/** Parse an SSE byte/string stream into dispatched {@link SseMessage}s. */
+async function* parseSse(chunks) {
+	let buffer = "";
+	let dataLines = [];
+	let dataSize = 0;
+	let event;
+	const dispatch = () => {
+		if (dataLines.length === 0) {
+			event = void 0;
+			return;
+		}
+		const message = {
+			data: dataLines.join("\n"),
+			event
+		};
+		dataLines = [];
+		dataSize = 0;
+		event = void 0;
+		return message;
+	};
+	const feedLine = (raw) => {
+		const line = raw.endsWith("\r") ? raw.slice(0, -1) : raw;
+		if (line.startsWith(":")) return;
+		const colon = line.indexOf(":");
+		const field = colon === -1 ? line : line.slice(0, colon);
+		let value = colon === -1 ? "" : line.slice(colon + 1);
+		if (value.startsWith(" ")) value = value.slice(1);
+		if (field === "data") {
+			dataLines.push(value);
+			dataSize += value.length;
+		} else if (field === "event") event = value;
+	};
+	for await (const chunk of chunks) {
+		buffer += chunk;
+		let newline = buffer.indexOf("\n");
+		while (newline !== -1) {
+			const line = buffer.slice(0, newline);
+			buffer = buffer.slice(newline + 1);
+			if (line === "" || line === "\r") {
+				const message = dispatch();
+				if (message) yield message;
+			} else feedLine(line);
+			if (dataSize > MAX_SSE_BUFFER) throw new AiError("STREAM_PARSE", `SSE event exceeded ${MAX_SSE_BUFFER} chars without a blank-line terminator`);
+			newline = buffer.indexOf("\n");
+		}
+		if (buffer.length > MAX_SSE_BUFFER) throw new AiError("STREAM_PARSE", `SSE line exceeded ${MAX_SSE_BUFFER} chars without a newline`);
+	}
+	if (buffer !== "") feedLine(buffer);
+	const tail = dispatch();
+	if (tail) yield tail;
+}
+/** Adapt a byte stream (e.g. `response.body`) to the string chunks {@link parseSse} expects. */
+async function* decodeChunks(bytes) {
+	const decoder = new TextDecoder();
+	for await (const chunk of bytes) yield decoder.decode(chunk, { stream: true });
+	const tail = decoder.decode();
+	if (tail) yield tail;
+}
+//#endregion
+export { decodeChunks, parseSse };
+
+//# sourceMappingURL=sse.js.map

package/dist/sse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.js","names":[],"sources":["../src/sse.ts"],"sourcesContent":["/**\n * A tiny, hand-rolled Server-Sent Events parser (no `eventsource` dep) for the server\n * backend's streaming responses. Pure-TS: buffers across chunk boundaries, joins\n * multi-line `data:` fields, skips `:` comments / keep-alives, and is driven by an\n * `AsyncIterable<string>` so it's golden-fixture-testable with zero network. See\n * `docs/adr/0018-synapse-server-backend.md`.\n *\n * @module\n */\n\nimport { AiError } from './errors'\n\n/**\n * Cap on un-dispatched parser state (chars, not bytes — we measure post-decode string\n * length). Bounds BOTH a single line that never gets a newline AND an event whose `data:`\n * lines accumulate without a blank-line terminator, so a hostile/buggy server can't\n * exhaust memory (or stall the mid-stream abort) by streaming endless data with no event\n * boundary.\n */\nconst MAX_SSE_BUFFER = 8 * 1024 * 1024\n\n/** One dispatched SSE event. */\nexport interface SseMessage {\n  /** The joined `data:` payload. */\n  readonly data: string\n  /** The `event:` type, if any. */\n  readonly event: string | undefined\n}\n\n/** Parse an SSE byte/string stream into dispatched {@link SseMessage}s. */\nexport async function* parseSse(chunks: AsyncIterable<string>): AsyncIterable<SseMessage> {\n  let buffer = ''\n  let dataLines: string[] = []\n  let dataSize = 0 // chars accumulated in dataLines since the last dispatch\n  let event: string | undefined\n\n  const dispatch = (): SseMessage | undefined => {\n    if (dataLines.length === 0) {\n      event = undefined\n      return undefined\n    }\n    const message: SseMessage = { data: dataLines.join('\\n'), event }\n    dataLines = []\n    dataSize = 0\n    event = undefined\n    return message\n  }\n\n  const feedLine = (raw: string): void => {\n    // Strip a trailing CR so CRLF and LF both work.\n    const line = raw.endsWith('\\r') ? raw.slice(0, -1) : raw\n    if (line.startsWith(':')) return // comment / keep-alive\n    const colon = line.indexOf(':')\n    const field = colon === -1 ? line : line.slice(0, colon)\n    let value = colon === -1 ? '' : line.slice(colon + 1)\n    if (value.startsWith(' ')) value = value.slice(1)\n    if (field === 'data') {\n      dataLines.push(value)\n      dataSize += value.length\n    } else if (field === 'event') event = value\n  }\n\n  for await (const chunk of chunks) {\n    buffer += chunk\n    let newline = buffer.indexOf('\\n')\n    while (newline !== -1) {\n      const line = buffer.slice(0, newline)\n      buffer = buffer.slice(newline + 1)\n      if (line === '' || line === '\\r') {\n        const message = dispatch()\n        if (message) yield message\n      } else {\n        feedLine(line)\n      }\n      // Catch an event whose data lines grow without a blank-line terminator.\n      if (dataSize > MAX_SSE_BUFFER) {\n        throw new AiError(\n          'STREAM_PARSE',\n          `SSE event exceeded ${MAX_SSE_BUFFER} chars without a blank-line terminator`,\n        )\n      }\n      newline = buffer.indexOf('\\n')\n    }\n    // Catch a single line that never receives a newline.\n    if (buffer.length > MAX_SSE_BUFFER) {\n      throw new AiError(\n        'STREAM_PARSE',\n        `SSE line exceeded ${MAX_SSE_BUFFER} chars without a newline`,\n      )\n    }\n  }\n  // Process a trailing line with no newline, then flush a final event.\n  if (buffer !== '') feedLine(buffer)\n  const tail = dispatch()\n  if (tail) yield tail\n}\n\n/** Adapt a byte stream (e.g. `response.body`) to the string chunks {@link parseSse} expects. */\nexport async function* decodeChunks(bytes: AsyncIterable<Uint8Array>): AsyncIterable<string> {\n  const decoder = new TextDecoder()\n  for await (const chunk of bytes) yield decoder.decode(chunk, { stream: true })\n  const tail = decoder.decode()\n  if (tail) yield tail\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAmBA,MAAM,iBAAiB,IAAI,OAAO;;AAWlC,gBAAuB,SAAS,QAA0D;CACxF,IAAI,SAAS;CACb,IAAI,YAAsB,CAAC;CAC3B,IAAI,WAAW;CACf,IAAI;CAEJ,MAAM,iBAAyC;EAC7C,IAAI,UAAU,WAAW,GAAG;GAC1B,QAAQ,KAAA;GACR;EACF;EACA,MAAM,UAAsB;GAAE,MAAM,UAAU,KAAK,IAAI;GAAG;EAAM;EAChE,YAAY,CAAC;EACb,WAAW;EACX,QAAQ,KAAA;EACR,OAAO;CACT;CAEA,MAAM,YAAY,QAAsB;EAEtC,MAAM,OAAO,IAAI,SAAS,IAAI,IAAI,IAAI,MAAM,GAAG,EAAE,IAAI;EACrD,IAAI,KAAK,WAAW,GAAG,GAAG;EAC1B,MAAM,QAAQ,KAAK,QAAQ,GAAG;EAC9B,MAAM,QAAQ,UAAU,KAAK,OAAO,KAAK,MAAM,GAAG,KAAK;EACvD,IAAI,QAAQ,UAAU,KAAK,KAAK,KAAK,MAAM,QAAQ,CAAC;EACpD,IAAI,MAAM,WAAW,GAAG,GAAG,QAAQ,MAAM,MAAM,CAAC;EAChD,IAAI,UAAU,QAAQ;GACpB,UAAU,KAAK,KAAK;GACpB,YAAY,MAAM;EACpB,OAAO,IAAI,UAAU,SAAS,QAAQ;CACxC;CAEA,WAAW,MAAM,SAAS,QAAQ;EAChC,UAAU;EACV,IAAI,UAAU,OAAO,QAAQ,IAAI;EACjC,OAAO,YAAY,IAAI;GACrB,MAAM,OAAO,OAAO,MAAM,GAAG,OAAO;GACpC,SAAS,OAAO,MAAM,UAAU,CAAC;GACjC,IAAI,SAAS,MAAM,SAAS,MAAM;IAChC,MAAM,UAAU,SAAS;IACzB,IAAI,SAAS,MAAM;GACrB,OACE,SAAS,IAAI;GAGf,IAAI,WAAW,gBACb,MAAM,IAAI,QACR,gBACA,sBAAsB,eAAe,uCACvC;GAEF,UAAU,OAAO,QAAQ,IAAI;EAC/B;EAEA,IAAI,OAAO,SAAS,gBAClB,MAAM,IAAI,QACR,gBACA,qBAAqB,eAAe,yBACtC;CAEJ;CAEA,IAAI,WAAW,IAAI,SAAS,MAAM;CAClC,MAAM,OAAO,SAAS;CACtB,IAAI,MAAM,MAAM;AAClB;;AAGA,gBAAuB,aAAa,OAAyD;CAC3F,MAAM,UAAU,IAAI,YAAY;CAChC,WAAW,MAAM,SAAS,OAAO,MAAM,QAAQ,OAAO,OAAO,EAAE,QAAQ,KAAK,CAAC;CAC7E,MAAM,OAAO,QAAQ,OAAO;CAC5B,IAAI,MAAM,MAAM;AAClB"}

package/dist/standard-schema.d.ts

@@ -0,0 +1,89 @@
+//#region src/standard-schema.d.ts
+/**
+ * Standard Schema — the validator-agnostic interface (types only, vendored).
+ *
+ * Synapse validates structured output and tool-call arguments through
+ * {@link StandardSchemaV1}, the common interface co-designed by the authors of Zod,
+ * Valibot, and ArkType. Any compliant validator (Zod ≥ 3.24 / all of 4.x, Valibot ≥ 1,
+ * ArkType ≥ 2, and 20+ others) exposes a `~standard` property and is accepted
+ * **directly** — no per-library adapters, no lock-in.
+ *
+ * These ~60 lines are **vendored on purpose** (the spec FAQ explicitly blesses
+ * copy/paste). Vendoring means `@mindees/ai` keeps **zero runtime dependency** to support
+ * every validator and never imports `@mindees/router` — the "batteries included,
+ * dependencies excluded" doctrine. (Kept in type-level sync with the router's copy: the type
+ * bodies are identical; only this package-specific header differs.)
+ *
+ * `validate` is typed single-argument — the subset Synapse needs; a spec 1.1.0 validator's
+ * optional second `options` argument remains assignable (fewer-params rule), so Zod 4 /
+ * Valibot 1 / ArkType 2 schemas are accepted directly.
+ *
+ * Portions adapted from `@standard-schema/spec`, MIT License,
+ * Copyright (c) 2024 Colin McDonnell. Permission is hereby granted, free of
+ * charge, to any person obtaining a copy of this software and associated
+ * documentation files, to deal in the Software without restriction. The above
+ * copyright notice and this permission notice shall be included in all copies or
+ * substantial portions of the Software.
+ *
+ * @see https://standardschema.dev
+ * @see https://github.com/standard-schema/standard-schema
+ * @module
+ */
+/** A schema that conforms to the Standard Schema specification. */
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+  /** The Standard Schema properties. */
+  readonly '~standard': StandardSchemaV1.Props<Input, Output>;
+}
+declare namespace StandardSchemaV1 {
+  /** The Standard Schema properties interface. */
+  interface Props<Input = unknown, Output = Input> {
+    /** The version number of the standard. */
+    readonly version: 1;
+    /** The vendor name of the schema library. */
+    readonly vendor: string;
+    /** Validates unknown input values. May be synchronous or asynchronous. */
+    readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
+    /** Inferred types associated with the schema (present only at the type level). */
+    readonly types?: Types<Input, Output> | undefined;
+  }
+  /** The result interface of the validate function. */
+  type Result<Output> = SuccessResult<Output> | FailureResult;
+  /** The result interface if validation succeeds. */
+  interface SuccessResult<Output> {
+    /** The typed output value. */
+    readonly value: Output;
+    /** The non-existent issues. */
+    readonly issues?: undefined;
+  }
+  /** The result interface if validation fails. */
+  interface FailureResult {
+    /** The issues of failed validation. */
+    readonly issues: ReadonlyArray<Issue>;
+  }
+  /** The issue interface of the failure output. */
+  interface Issue {
+    /** The error message of the issue. */
+    readonly message: string;
+    /** The path of the issue, if any. */
+    readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+  }
+  /** The path segment interface of the issue. */
+  interface PathSegment {
+    /** The key representing a path segment. */
+    readonly key: PropertyKey;
+  }
+  /** The Standard Schema types interface. */
+  interface Types<Input = unknown, Output = Input> {
+    /** The input type of the schema. */
+    readonly input: Input;
+    /** The output type of the schema. */
+    readonly output: Output;
+  }
+  /** Infers the input type of a Standard Schema. */
+  type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['input'];
+  /** Infers the output type of a Standard Schema. */
+  type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['output'];
+}
+//#endregion
+export { StandardSchemaV1 };
+//# sourceMappingURL=standard-schema.d.ts.map

package/dist/standard-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"standard-schema.d.ts","names":[],"sources":["../src/standard-schema.ts"],"mappings":";;AAgCA;;;;;;;;;;;;;;;;;;AAE4D;AAG5D;;;;;;;;;;;UALiB,gBAAA,2BAA2C,KAAA;EAmBf;EAAA,SAjBlC,WAAA,EAAa,gBAAA,CAAiB,KAAA,CAAM,KAAA,EAAO,MAAA;AAAA;AAAA,kBAGrC,gBAAA;EA2BkB;EAAA,UAzBhB,KAAA,2BAAgC,KAAA;IAiCjB;IAAA,SA/BrB,OAAA;IA+BO;IAAA,SA7BP,MAAA;IAuCsC;IAAA,SArCtC,QAAA,GAAW,KAAA,cAAmB,MAAA,CAAO,MAAA,IAAU,OAAA,CAAQ,MAAA,CAAO,MAAA;IAyCtD;IAAA,SAvCR,KAAA,GAAQ,KAAA,CAAM,KAAA,EAAO,MAAA;EAAA;EA2C0B;EAAA,KAvC9C,MAAA,WAAiB,aAAA,CAAc,MAAA,IAAU,aAAA;EA6CnD;EAAA,UA1Ce,aAAA;IAyCqD;IAAA,SAvC3D,KAAA,EAAO,MAAA;IAjBD;IAAA,SAmBN,MAAA;EAAA;EAnBsC;EAAA,UAuBhC,aAAA;IAnBN;IAAA,SAqBA,MAAA,EAAQ,aAAA,CAAc,KAAA;EAAA;EAnBQ;EAAA,UAuBxB,KAAA;IAvByC;IAAA,SAyB/C,OAAA;IAzB8D;IAAA,SA2B9D,IAAA,GAAO,aAAA,CAAc,WAAA,GAAc,WAAA;EAAA;EAzBrB;EAAA,UA6BR,WAAA;IAzBL;IAAA,SA2BD,GAAA,EAAK,WAAA;EAAA;EA3B2B;EAAA,UA+B1B,KAAA,2BAAgC,KAAA;IA5BhC;IAAA,SA8BN,KAAA,EAAO,KAAA;IA5BP;IAAA,SA8BA,MAAA,EAAQ,MAAA;EAAA;EAxBF;EAAA,KA4BL,UAAA,gBAA0B,gBAAA,IAAoB,WAAA,CACxD,MAAA;EA3BiB;EAAA,KA+BP,WAAA,gBAA2B,gBAAA,IAAoB,WAAA,CACzD,MAAA;AAAA"}

package/dist/tools.d.ts

@@ -0,0 +1,61 @@
+import { AbortLike, AiBackend, FinishReason, GenerateRequest, Message, Usage } from "./contract.js";
+import { StandardSchemaV1 } from "./standard-schema.js";
+
+//#region src/tools.d.ts
+/** Context passed to a {@link Tool}'s `execute`. */
+interface ToolContext {
+  /** Cancellation — long-running tools should honor it. */
+  readonly signal?: AbortLike;
+}
+/** A callable tool: the wire {@link ToolDefinition} plus runtime validation + `execute`. */
+interface Tool {
+  readonly name: string;
+  readonly description?: string;
+  /** JSON Schema for the args, sent to the provider verbatim. */
+  readonly parameters?: Record<string, unknown>;
+  /** Optional Standard Schema validating the model's args before `execute` (sync only). */
+  readonly validate?: StandardSchemaV1;
+  /** Run the tool. Receives validated, pollution-checked args. */
+  readonly execute: (args: unknown, context: ToolContext) => unknown | Promise<unknown>;
+}
+/** Options for {@link runTools}. */
+interface RunToolsOptions {
+  /** Hard ceiling on model calls (one `generate` = one step). Default `8`. */
+  readonly maxSteps?: number;
+  /** Cancellation, polled before/after every generate and execute. */
+  readonly signal?: AbortLike;
+  /** Run a turn's tool calls sequentially instead of in parallel. Default `false`. */
+  readonly sequential?: boolean;
+  /** Throw `TOOL_FAILED` on an `execute` throw instead of feeding the error back. Default `false`. */
+  readonly throwOnToolError?: boolean;
+  /** Truncate a stringified tool result longer than this before feeding it back. */
+  readonly maxToolResultChars?: number;
+  /** Sampling temperature forwarded to the backend. */
+  readonly temperature?: number;
+  /** Output-token cap forwarded to the backend. */
+  readonly maxOutputTokens?: number;
+}
+/** The result of {@link runTools}. */
+interface RunToolsResult {
+  /** The model's final text answer. */
+  readonly text: string;
+  /** How many model calls were made. */
+  readonly steps: number;
+  /** The full accumulated transcript (caller's input is never mutated). */
+  readonly messages: readonly Message[];
+  /** Accumulated usage across all steps, when reported. */
+  readonly usage?: Usage;
+  /** The final finish reason. */
+  readonly finishReason: FinishReason;
+}
+/**
+ * Run the bounded tool-calling loop.
+ *
+ * @throws AiError `MAX_STEPS` if the step ceiling is reached, `ABORTED` on cancellation,
+ * `TOOL_FAILED` only when `throwOnToolError` is set and an `execute` throws.
+ * @throws TypeError for tool-definition misconfiguration (duplicate/empty names).
+ */
+declare function runTools(backend: Pick<AiBackend, 'generate'>, request: GenerateRequest, tools: readonly Tool[], options?: RunToolsOptions): Promise<RunToolsResult>;
+//#endregion
+export { RunToolsOptions, RunToolsResult, Tool, ToolContext, runTools };
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","names":[],"sources":["../src/tools.ts"],"mappings":";;;;;UAqCiB,WAAA;EAcN;EAAA,SAZA,MAAA,GAAS,SAAS;AAAA;;UAIZ,IAAA;EAAA,SACN,IAAA;EAAA,SACA,WAAA;EAUM;EAAA,SARN,UAAA,GAAa,MAAA;;WAEb,QAAA,GAAW,gBAAA;EAQX;EAAA,SANA,OAAA,GAAU,IAAA,WAAe,OAAA,EAAS,WAAA,eAA0B,OAAA;AAAA;;UAItD,eAAA;EAUN;EAAA,SARA,QAAA;EAYA;EAAA,SAVA,MAAA,GAAS,SAAS;EAUH;EAAA,SARf,UAAA;EAYoB;EAAA,SAVpB,gBAAA;EAgBmB;EAAA,SAdnB,kBAAA;EAkBc;EAAA,SAhBd,WAAA;EAgB0B;EAAA,SAd1B,eAAA;AAAA;;UAIM,cAAA;EAQN;EAAA,SANA,IAAA;EAQA;EAAA,SANA,KAAA;EAM0B;EAAA,SAJ1B,QAAA,WAAmB,OAAA;EAoFR;EAAA,SAlFX,KAAA,GAAQ,KAAA;;WAER,YAAA,EAAc,YAAA;AAAA;;;;;;;;iBAgFH,QAAA,CACpB,OAAA,EAAS,IAAA,CAAK,SAAA,eACd,OAAA,EAAS,eAAA,EACT,KAAA,WAAgB,IAAA,IAChB,OAAA,GAAS,eAAA,GACR,OAAA,CAAQ,cAAA"}

package/dist/tools.js

@@ -0,0 +1,195 @@
+import { AiError } from "./errors.js";
+import { containsForbiddenKey, formatIssues } from "./json.js";
+//#region src/tools.ts
+/**
+* Deterministic JSON with sorted object keys (order-independent dedup key + size estimate).
+* Cycle- and bigint-safe so it never throws on a tool result: a back-reference becomes
+* `"[Circular]"` and a bigint its decimal string. (Dedup keys come from validated JSON args,
+* which can't cycle; the safety matters for `truncateResult` on arbitrary tool output.)
+*/
+function stableStringify(value, seen = /* @__PURE__ */ new WeakSet()) {
+	if (typeof value === "bigint") return `"${value.toString()}"`;
+	if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
+	if (seen.has(value)) return "\"[Circular]\"";
+	seen.add(value);
+	const out = Array.isArray(value) ? `[${value.map((v) => stableStringify(v, seen)).join(",")}]` : `{${Object.keys(value).sort().map((k) => `${JSON.stringify(k)}:${stableStringify(value[k], seen)}`).join(",")}}`;
+	seen.delete(value);
+	return out;
+}
+function addUsage(a, b) {
+	if (!a) return b;
+	if (!b) return a;
+	const sum = {};
+	if (a.inputTokens !== void 0 || b.inputTokens !== void 0) sum.inputTokens = (a.inputTokens ?? 0) + (b.inputTokens ?? 0);
+	if (a.outputTokens !== void 0 || b.outputTokens !== void 0) sum.outputTokens = (a.outputTokens ?? 0) + (b.outputTokens ?? 0);
+	return sum;
+}
+/** Validate args synchronously (tool schemas must be sync — an async validator throws). */
+function validateArgsSync(tool, args) {
+	if (!tool.validate) return {
+		ok: true,
+		value: args
+	};
+	const raw = tool.validate["~standard"].validate(args);
+	if (raw instanceof Promise) throw new AiError("TOOL_FAILED", `tool "${tool.name}" has an async argument schema (unsupported)`);
+	if (typeof raw !== "object" || raw === null) return {
+		ok: false,
+		message: "validator returned no result"
+	};
+	if (raw.issues) return {
+		ok: false,
+		message: formatIssues(Array.isArray(raw.issues) ? raw.issues : [])
+	};
+	return {
+		ok: true,
+		value: raw.value
+	};
+}
+function truncateResult(result, maxChars) {
+	if (maxChars === void 0) return result;
+	if (stableStringify(result).length <= maxChars) return result;
+	return {
+		error: "tool_result_truncated",
+		message: `result exceeded ${maxChars} chars`
+	};
+}
+/**
+* Run the bounded tool-calling loop.
+*
+* @throws AiError `MAX_STEPS` if the step ceiling is reached, `ABORTED` on cancellation,
+* `TOOL_FAILED` only when `throwOnToolError` is set and an `execute` throws.
+* @throws TypeError for tool-definition misconfiguration (duplicate/empty names).
+*/
+async function runTools(backend, request, tools, options = {}) {
+	const maxSteps = options.maxSteps ?? 8;
+	if (!Number.isInteger(maxSteps) || maxSteps < 1) throw new TypeError("maxSteps must be an integer >= 1");
+	const signal = options.signal ?? request.signal;
+	const byName = /* @__PURE__ */ new Map();
+	for (const tool of tools) {
+		if (!tool.name) throw new TypeError("every tool must have a non-empty name");
+		if (byName.has(tool.name)) throw new TypeError(`duplicate tool name "${tool.name}"`);
+		byName.set(tool.name, tool);
+	}
+	const definitions = tools.map((t) => t.parameters === void 0 ? {
+		name: t.name,
+		...t.description !== void 0 ? { description: t.description } : {}
+	} : {
+		name: t.name,
+		parameters: t.parameters,
+		...t.description !== void 0 ? { description: t.description } : {}
+	});
+	const messages = [...request.messages];
+	const callCache = /* @__PURE__ */ new Map();
+	let usage;
+	let steps = 0;
+	const aborted = () => signal?.aborted === true;
+	const runCall = async (call) => {
+		const tool = byName.get(call.name);
+		if (!tool) return {
+			error: "unknown_tool",
+			message: `no tool named "${call.name}"`
+		};
+		if (containsForbiddenKey(call.args)) return {
+			error: "invalid_arguments",
+			message: "arguments contain a forbidden key"
+		};
+		const validated = validateArgsSync(tool, call.args);
+		if (!validated.ok) return {
+			error: "invalid_arguments",
+			message: validated.message
+		};
+		const key = `${tool.name}:${stableStringify(validated.value)}`;
+		let exec = callCache.get(key);
+		if (!exec) {
+			if (aborted()) throw new AiError("ABORTED", "tool loop aborted");
+			exec = (async () => {
+				const ctx = signal ? { signal } : {};
+				const raw = await tool.execute(validated.value, ctx);
+				if (aborted()) throw new AiError("ABORTED", "tool loop aborted");
+				return truncateResult(raw, options.maxToolResultChars);
+			})();
+			callCache.set(key, exec);
+		}
+		try {
+			return await exec;
+		} catch (err) {
+			if (err instanceof AiError && err.code === "ABORTED") throw err;
+			if (options.throwOnToolError) throw new AiError("TOOL_FAILED", `tool "${tool.name}" failed: ${errorMessage(err)}`);
+			return {
+				error: "tool_failed",
+				message: errorMessage(err)
+			};
+		}
+	};
+	for (;;) {
+		if (steps >= maxSteps) throw new AiError("MAX_STEPS", `tool loop exceeded ${maxSteps} steps`);
+		if (aborted()) throw new AiError("ABORTED", "tool loop aborted");
+		const req = {
+			messages,
+			tools: definitions,
+			...options.temperature !== void 0 ? { temperature: options.temperature } : {},
+			...options.maxOutputTokens !== void 0 ? { maxOutputTokens: options.maxOutputTokens } : {},
+			...signal ? { signal } : {}
+		};
+		steps++;
+		const result = await backend.generate(req);
+		usage = addUsage(usage, result.usage);
+		if (aborted()) throw new AiError("ABORTED", "tool loop aborted");
+		const calls = result.toolCalls ?? [];
+		if (calls.length === 0) {
+			if (result.text) messages.push({
+				role: "assistant",
+				content: result.text
+			});
+			const finishReason = result.finishReason === "tool-calls" ? "stop" : result.finishReason;
+			return usage === void 0 ? {
+				text: result.text,
+				steps,
+				messages,
+				finishReason
+			} : {
+				text: result.text,
+				steps,
+				messages,
+				usage,
+				finishReason
+			};
+		}
+		const assistantParts = [];
+		if (result.text) assistantParts.push({
+			type: "text",
+			text: result.text
+		});
+		for (const c of calls) assistantParts.push(c);
+		messages.push({
+			role: "assistant",
+			content: assistantParts
+		});
+		if (aborted()) throw new AiError("ABORTED", "tool loop aborted");
+		let results;
+		if (options.sequential) {
+			results = [];
+			for (const call of calls) results.push(await runCall(call));
+		} else results = await Promise.all(calls.map((call) => runCall(call)));
+		for (let i = 0; i < calls.length; i++) {
+			const call = calls[i];
+			if (!call) continue;
+			messages.push({
+				role: "tool",
+				content: [{
+					type: "tool-result",
+					id: call.id,
+					name: call.name,
+					result: results[i]
+				}]
+			});
+		}
+	}
+}
+function errorMessage(err) {
+	return err instanceof Error ? err.message : String(err);
+}
+//#endregion
+export { runTools };
+
+//# sourceMappingURL=tools.js.map

package/dist/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","names":[],"sources":["../src/tools.ts"],"sourcesContent":["/**\n * The Synapse bounded tool-calling loop. `runTools` drives a model that can call tools:\n * generate → (validate args → execute tools → feed results back) → repeat, until the model\n * answers with text or a hard step ceiling is hit. Built purely on `AiBackend.generate`, so\n * the deterministic mock (scripted tool-call mode) exercises the whole loop offline.\n *\n * Safety is the point (tool args are model-produced ⇒ untrusted, tools can have side effects):\n * a hard `maxSteps` ceiling; deep prototype-pollution rejection + Standard-Schema validation\n * of **args** BEFORE any `execute`; invalid args are fed back as a recoverable tool-result (not\n * a thrown error); each `execute` is isolated (one tool's throw can't abort the batch);\n * identical repeated calls share ONE execution (no duplicate side effects, even within a\n * parallel turn); parallel execution with deterministic (request-order) result history;\n * four-point abort polling. See `docs/adr/0020-synapse-tool-calling.md`.\n *\n * Note: a tool's RETURN value is the tool author's responsibility and is passed through to the\n * transcript/caller as-is (not deep-sanitized) — it may be a rich object (Date, class). If a\n * tool returns untrusted fetched data, the tool should sanitize it before returning.\n *\n * @module\n */\n\nimport type {\n  AbortLike,\n  AiBackend,\n  FinishReason,\n  GenerateRequest,\n  Message,\n  Part,\n  ToolCallPart,\n  ToolDefinition,\n  Usage,\n} from './contract'\nimport { AiError } from './errors'\nimport { containsForbiddenKey, formatIssues } from './json'\nimport type { StandardSchemaV1 } from './standard-schema'\n\n/** Context passed to a {@link Tool}'s `execute`. */\nexport interface ToolContext {\n  /** Cancellation — long-running tools should honor it. */\n  readonly signal?: AbortLike\n}\n\n/** A callable tool: the wire {@link ToolDefinition} plus runtime validation + `execute`. */\nexport interface Tool {\n  readonly name: string\n  readonly description?: string\n  /** JSON Schema for the args, sent to the provider verbatim. */\n  readonly parameters?: Record<string, unknown>\n  /** Optional Standard Schema validating the model's args before `execute` (sync only). */\n  readonly validate?: StandardSchemaV1\n  /** Run the tool. Receives validated, pollution-checked args. */\n  readonly execute: (args: unknown, context: ToolContext) => unknown | Promise<unknown>\n}\n\n/** Options for {@link runTools}. */\nexport interface RunToolsOptions {\n  /** Hard ceiling on model calls (one `generate` = one step). Default `8`. */\n  readonly maxSteps?: number\n  /** Cancellation, polled before/after every generate and execute. */\n  readonly signal?: AbortLike\n  /** Run a turn's tool calls sequentially instead of in parallel. Default `false`. */\n  readonly sequential?: boolean\n  /** Throw `TOOL_FAILED` on an `execute` throw instead of feeding the error back. Default `false`. */\n  readonly throwOnToolError?: boolean\n  /** Truncate a stringified tool result longer than this before feeding it back. */\n  readonly maxToolResultChars?: number\n  /** Sampling temperature forwarded to the backend. */\n  readonly temperature?: number\n  /** Output-token cap forwarded to the backend. */\n  readonly maxOutputTokens?: number\n}\n\n/** The result of {@link runTools}. */\nexport interface RunToolsResult {\n  /** The model's final text answer. */\n  readonly text: string\n  /** How many model calls were made. */\n  readonly steps: number\n  /** The full accumulated transcript (caller's input is never mutated). */\n  readonly messages: readonly Message[]\n  /** Accumulated usage across all steps, when reported. */\n  readonly usage?: Usage\n  /** The final finish reason. */\n  readonly finishReason: FinishReason\n}\n\n/** A structured tool-result payload fed back to the model on a recoverable problem. */\ninterface ToolErrorResult {\n  readonly error: 'unknown_tool' | 'invalid_arguments' | 'tool_failed'\n  readonly message: string\n}\n\n/**\n * Deterministic JSON with sorted object keys (order-independent dedup key + size estimate).\n * Cycle- and bigint-safe so it never throws on a tool result: a back-reference becomes\n * `\"[Circular]\"` and a bigint its decimal string. (Dedup keys come from validated JSON args,\n * which can't cycle; the safety matters for `truncateResult` on arbitrary tool output.)\n */\nfunction stableStringify(value: unknown, seen: WeakSet<object> = new WeakSet()): string {\n  if (typeof value === 'bigint') return `\"${value.toString()}\"`\n  if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'null'\n  if (seen.has(value)) return '\"[Circular]\"'\n  seen.add(value)\n  const out = Array.isArray(value)\n    ? `[${value.map((v) => stableStringify(v, seen)).join(',')}]`\n    : `{${Object.keys(value as Record<string, unknown>)\n        .sort()\n        .map(\n          (k) =>\n            `${JSON.stringify(k)}:${stableStringify((value as Record<string, unknown>)[k], seen)}`,\n        )\n        .join(',')}}`\n  seen.delete(value)\n  return out\n}\n\nfunction addUsage(a: Usage | undefined, b: Usage | undefined): Usage | undefined {\n  if (!a) return b\n  if (!b) return a\n  const sum: { inputTokens?: number; outputTokens?: number } = {}\n  if (a.inputTokens !== undefined || b.inputTokens !== undefined) {\n    sum.inputTokens = (a.inputTokens ?? 0) + (b.inputTokens ?? 0)\n  }\n  if (a.outputTokens !== undefined || b.outputTokens !== undefined) {\n    sum.outputTokens = (a.outputTokens ?? 0) + (b.outputTokens ?? 0)\n  }\n  return sum\n}\n\n/** Validate args synchronously (tool schemas must be sync — an async validator throws). */\nfunction validateArgsSync(\n  tool: Tool,\n  args: unknown,\n): { ok: true; value: unknown } | { ok: false; message: string } {\n  if (!tool.validate) return { ok: true, value: args }\n  const raw = tool.validate['~standard'].validate(args)\n  if (raw instanceof Promise) {\n    throw new AiError(\n      'TOOL_FAILED',\n      `tool \"${tool.name}\" has an async argument schema (unsupported)`,\n    )\n  }\n  if (typeof raw !== 'object' || raw === null)\n    return { ok: false, message: 'validator returned no result' }\n  if (raw.issues)\n    return { ok: false, message: formatIssues(Array.isArray(raw.issues) ? raw.issues : []) }\n  return { ok: true, value: raw.value }\n}\n\nfunction truncateResult(result: unknown, maxChars: number | undefined): unknown {\n  if (maxChars === undefined) return result\n  const serialized = stableStringify(result)\n  if (serialized.length <= maxChars) return result\n  return { error: 'tool_result_truncated', message: `result exceeded ${maxChars} chars` }\n}\n\n/**\n * Run the bounded tool-calling loop.\n *\n * @throws AiError `MAX_STEPS` if the step ceiling is reached, `ABORTED` on cancellation,\n * `TOOL_FAILED` only when `throwOnToolError` is set and an `execute` throws.\n * @throws TypeError for tool-definition misconfiguration (duplicate/empty names).\n */\nexport async function runTools(\n  backend: Pick<AiBackend, 'generate'>,\n  request: GenerateRequest,\n  tools: readonly Tool[],\n  options: RunToolsOptions = {},\n): Promise<RunToolsResult> {\n  const maxSteps = options.maxSteps ?? 8\n  if (!Number.isInteger(maxSteps) || maxSteps < 1) {\n    throw new TypeError('maxSteps must be an integer >= 1')\n  }\n  const signal = options.signal ?? request.signal\n\n  // Validate tool definitions up front (programmer error, not a model error).\n  const byName = new Map<string, Tool>()\n  for (const tool of tools) {\n    if (!tool.name) throw new TypeError('every tool must have a non-empty name')\n    if (byName.has(tool.name)) throw new TypeError(`duplicate tool name \"${tool.name}\"`)\n    byName.set(tool.name, tool)\n  }\n  const definitions: ToolDefinition[] = tools.map((t) =>\n    t.parameters === undefined\n      ? { name: t.name, ...(t.description !== undefined ? { description: t.description } : {}) }\n      : {\n          name: t.name,\n          parameters: t.parameters,\n          ...(t.description !== undefined ? { description: t.description } : {}),\n        },\n  )\n\n  const messages: Message[] = [...request.messages]\n  // One promise per (name,args) for the whole run: concurrent identical calls share it (no\n  // double-fire in a parallel turn) AND a later identical call reuses the settled outcome —\n  // success OR failure — so a throwing tool isn't re-executed either (no duplicate side\n  // effects). The per-call error POLICY (throw vs feed-back) is applied at await, not cached.\n  const callCache = new Map<string, Promise<unknown>>()\n  let usage: Usage | undefined\n  let steps = 0\n\n  const aborted = (): boolean => signal?.aborted === true\n\n  // Execute one validated call (or produce a fed-back error result). Honors abort + dedup.\n  const runCall = async (call: ToolCallPart): Promise<unknown> => {\n    const tool = byName.get(call.name)\n    if (!tool) {\n      return {\n        error: 'unknown_tool',\n        message: `no tool named \"${call.name}\"`,\n      } satisfies ToolErrorResult\n    }\n    if (containsForbiddenKey(call.args)) {\n      return {\n        error: 'invalid_arguments',\n        message: 'arguments contain a forbidden key',\n      } satisfies ToolErrorResult\n    }\n    const validated = validateArgsSync(tool, call.args)\n    if (!validated.ok) {\n      return { error: 'invalid_arguments', message: validated.message } satisfies ToolErrorResult\n    }\n    const key = `${tool.name}:${stableStringify(validated.value)}`\n    let exec = callCache.get(key)\n    if (!exec) {\n      if (aborted()) throw new AiError('ABORTED', 'tool loop aborted')\n      exec = (async () => {\n        const ctx: ToolContext = signal ? { signal } : {}\n        const raw = await tool.execute(validated.value, ctx)\n        if (aborted()) throw new AiError('ABORTED', 'tool loop aborted')\n        return truncateResult(raw, options.maxToolResultChars)\n      })()\n      callCache.set(key, exec)\n    }\n    try {\n      return await exec\n    } catch (err) {\n      if (err instanceof AiError && err.code === 'ABORTED') throw err\n      if (options.throwOnToolError) {\n        throw new AiError('TOOL_FAILED', `tool \"${tool.name}\" failed: ${errorMessage(err)}`)\n      }\n      return { error: 'tool_failed', message: errorMessage(err) } satisfies ToolErrorResult\n    }\n  }\n\n  // The loop is bounded by the maxSteps check below (throws MAX_STEPS) and by terminal turns.\n  for (;;) {\n    if (steps >= maxSteps) {\n      throw new AiError('MAX_STEPS', `tool loop exceeded ${maxSteps} steps`)\n    }\n    if (aborted()) throw new AiError('ABORTED', 'tool loop aborted')\n\n    const req: GenerateRequest = {\n      messages,\n      tools: definitions,\n      ...(options.temperature !== undefined ? { temperature: options.temperature } : {}),\n      ...(options.maxOutputTokens !== undefined\n        ? { maxOutputTokens: options.maxOutputTokens }\n        : {}),\n      ...(signal ? { signal } : {}),\n    }\n    steps++\n    const result = await backend.generate(req)\n    usage = addUsage(usage, result.usage)\n    if (aborted()) throw new AiError('ABORTED', 'tool loop aborted')\n\n    const calls = result.toolCalls ?? []\n    // Drive on tool-call presence, not finishReason: 'tool-calls' with no calls is terminal,\n    // and a provider that under-reports finishReason but includes calls still executes them.\n    if (calls.length === 0) {\n      // Record the final assistant answer so the returned transcript is complete (callers may\n      // resume from `messages`).\n      if (result.text) messages.push({ role: 'assistant', content: result.text })\n      // Normalize a stale 'tool-calls' (no calls actually emitted) to 'stop' so a caller\n      // branching on the result's finishReason isn't told work is still pending.\n      const finishReason: FinishReason =\n        result.finishReason === 'tool-calls' ? 'stop' : result.finishReason\n      return usage === undefined\n        ? { text: result.text, steps, messages, finishReason }\n        : { text: result.text, steps, messages, usage, finishReason }\n    }\n\n    // Record the assistant turn (text part, if any, then the tool-call parts).\n    const assistantParts: Part[] = []\n    if (result.text) assistantParts.push({ type: 'text', text: result.text })\n    for (const c of calls) assistantParts.push(c)\n    messages.push({ role: 'assistant', content: assistantParts })\n\n    if (aborted()) throw new AiError('ABORTED', 'tool loop aborted')\n\n    // Execute (parallel by default), but append results in the model's REQUESTED order so the\n    // transcript is deterministic regardless of completion order.\n    let results: unknown[]\n    if (options.sequential) {\n      results = []\n      for (const call of calls) results.push(await runCall(call))\n    } else {\n      results = await Promise.all(calls.map((call) => runCall(call)))\n    }\n    for (let i = 0; i < calls.length; i++) {\n      const call = calls[i]\n      if (!call) continue\n      messages.push({\n        role: 'tool',\n        content: [{ type: 'tool-result', id: call.id, name: call.name, result: results[i] }],\n      })\n    }\n  }\n}\n\nfunction errorMessage(err: unknown): string {\n  return err instanceof Error ? err.message : String(err)\n}\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@mindees/ai",
+  "version": "0.1.0",
+  "description": "MindeesNative Synapse - provider-agnostic AI: a pure-TS contract with mock + server backends, streaming via async iterables, structured output, and tool calling (on-device runtime is a research track).",
+  "license": "MIT OR Apache-2.0",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    },
+    "./devtools": {
+      "types": "./dist/devtools.d.ts",
+      "import": "./dist/devtools.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mindees/mindees.git",
+    "directory": "packages/ai"
+  },
+  "dependencies": {
+    "@mindees/core": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit"
+  }
+}