@mindees/ai 0.1.0

package/LICENSE

@@ -0,0 +1,31 @@
+# License
+
+MindeesNative is dual-licensed under either of:
+
+- **Apache License, Version 2.0** ([LICENSE-APACHE](./LICENSE-APACHE) or
+  <https://www.apache.org/licenses/LICENSE-2.0>)
+- **MIT license** ([LICENSE-MIT](./LICENSE-MIT) or
+  <https://opensource.org/licenses/MIT>)
+
+at your option.
+
+This `MIT OR Apache-2.0` dual-license is the same model used by the Rust
+ecosystem and many modern open-source projects. It gives downstream users
+maximum flexibility: the MIT option is short and permissive, while the Apache
+option adds an explicit patent grant.
+
+## SPDX identifier
+
+```
+SPDX-License-Identifier: MIT OR Apache-2.0
+```
+
+## Contribution
+
+Unless you explicitly state otherwise, any contribution intentionally
+submitted for inclusion in the work by you, as defined in the Apache-2.0
+license, shall be dual-licensed as above, without any additional terms or
+conditions.
+
+Contributions are accepted under the **Developer Certificate of Origin (DCO)**.
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for details on signing off your commits.

package/README.md

@@ -0,0 +1,57 @@
+# @mindees/ai
+
+**Synapse** — provider-agnostic AI + dev-time intelligence for MindeesNative.
+
+> Status: 🧪 **Experimental** — Phase 11 (Synapse) is complete in its current scope.
+> Implemented and tested: the provider-agnostic AI contract, deterministic mock backend,
+> injected-`fetch` server/HTTP backend, Standard-Schema structured output, bounded tool
+> calling, and dev-time error explainer. **On-device LLM inference is inherently native**
+> (Apple Foundation Models, Android AICore/Gemini Nano, ExecuTorch, llama.rn) or web-only
+> (WebGPU/WASM), so it is a 🔬 **research track** — `createOnDeviceBackend()` throws
+> `NotImplementedError`; the mock/server backends are the working fallback. See the
+> repository [STATUS.md](../../STATUS.md).
+
+## What works today
+
+A provider-agnostic contract every backend implements (`@mindees/core` only, zero
+third-party deps):
+
+- **`createAi({ backend })`** → `ai.generate(req)` (one-shot) and `ai.stream(req)`
+  (streamed). Streaming is an **`AsyncIterable`** (no Web/Node streams), so it runs on
+  Node, browsers, and Hermes/RN. Cancellation via a structural `AbortLike`.
+- **`createMockBackend({ reply | script, chunkSize })`** — deterministic, no network, no
+  keys: powers tests and offline apps.
+- **`createOnDeviceBackend()`** — the research-track seam (same interface, throws).
+- Stable `AiError` codes; `Message`/`Part` types whose `tool-call`/`tool-result` parts
+  back the (11C) tool loop.
+- **`@mindees/ai/server`** — `createServerBackend({ fetch, baseUrl, model, ... })`
+  with OpenAI/Anthropic mappers and a pure-TS SSE parser, tested with fixture fetches
+  and no real network.
+- **Structured output** — `generateObject` / `streamObject` validate model JSON against
+  any Standard Schema, with bounded repair and sanitize-before-validate guards.
+- **Tool calling** — `runTools` validates args before execution, deduplicates identical
+  calls, supports parallel execution, and preserves an immutable transcript.
+- **`@mindees/ai/devtools`** — `explainError` and terminal formatting for build/dev tools;
+  surfaced by the CLI as `mindees ai explain <error>`.
+
+```ts
+import { createAi, createMockBackend } from '@mindees/ai'
+
+const ai = createAi({ backend: createMockBackend({ reply: 'Hello from Synapse' }) })
+
+console.log((await ai.generate({ messages: [{ role: 'user', content: 'hi' }] })).text)
+
+for await (const chunk of ai.stream({ messages: [{ role: 'user', content: 'hi' }] })) {
+  if (chunk.type === 'text-delta') process.stdout.write(chunk.delta)
+}
+```
+
+Design rationale: [ADR-0017](../../docs/adr/0017-synapse-ai-contract.md),
+[ADR-0018](../../docs/adr/0018-synapse-server-backend.md),
+[ADR-0019](../../docs/adr/0019-synapse-structured-output.md),
+[ADR-0020](../../docs/adr/0020-synapse-tool-calling.md), and
+[ADR-0021](../../docs/adr/0021-synapse-devtools.md).
+
+## License
+
+`MIT OR Apache-2.0`

package/dist/contract.d.ts

@@ -0,0 +1,113 @@
+//#region src/contract.d.ts
+/**
+ * The Synapse provider-agnostic AI contract — a small, hand-rolled, pure-TS surface
+ * every backend (mock, server, on-device) implements. Streaming is `AsyncIterable`
+ * only (no Web `ReadableStream`, no Node streams), so it runs on Node, browsers, and
+ * Hermes/RN. See `docs/adr/0017-synapse-ai-contract.md`.
+ *
+ * @module
+ */
+/** Who authored a message. */
+type Role = 'system' | 'user' | 'assistant' | 'tool';
+/** A plain text part. */
+interface TextPart {
+  readonly type: 'text';
+  readonly text: string;
+}
+/** A model's request to call a tool (the args are model-produced ⇒ untrusted). */
+interface ToolCallPart {
+  readonly type: 'tool-call';
+  readonly id: string;
+  readonly name: string;
+  readonly args: unknown;
+}
+/** The result of running a tool, fed back to the model. */
+interface ToolResultPart {
+  readonly type: 'tool-result';
+  readonly id: string;
+  readonly name: string;
+  readonly result: unknown;
+}
+/** A piece of message content. */
+type Part = TextPart | ToolCallPart | ToolResultPart;
+/** One message in a conversation. */
+interface Message {
+  readonly role: Role;
+  readonly content: string | readonly Part[];
+}
+/** Why a generation stopped. */
+type FinishReason = 'stop' | 'length' | 'tool-calls' | 'error';
+/** Token usage, when the backend reports it. */
+interface Usage {
+  readonly inputTokens?: number;
+  readonly outputTokens?: number;
+}
+/** Minimal cancellation signal — a real `AbortSignal` is structurally compatible. */
+interface AbortLike {
+  readonly aborted: boolean;
+}
+/**
+ * A tool the model may call, as sent to the backend (the **wire** shape — no `execute`).
+ * `parameters` is a provider-native JSON Schema sent verbatim; the runtime-validating
+ * {@link import('./tools').Tool} adds `execute` (+ an optional Standard Schema) on top.
+ */
+interface ToolDefinition {
+  readonly name: string;
+  readonly description?: string;
+  /** JSON Schema describing the arguments (sent to the provider as-is). */
+  readonly parameters?: Record<string, unknown>;
+}
+/** A one-shot or streaming generation request. */
+interface GenerateRequest {
+  readonly messages: readonly Message[];
+  /** 0–2-ish sampling temperature (backend-defined default). */
+  readonly temperature?: number;
+  /** Cap on output tokens (backend-defined default). */
+  readonly maxOutputTokens?: number;
+  /** Tools the model may call. A backend that can't express tools must throw, not drop them. */
+  readonly tools?: readonly ToolDefinition[];
+  /** Cancellation. */
+  readonly signal?: AbortLike;
+}
+/** The result of {@link AiBackend.generate}. */
+interface AiResult {
+  readonly text: string;
+  readonly toolCalls?: readonly ToolCallPart[];
+  readonly finishReason: FinishReason;
+  readonly usage?: Usage;
+}
+/** One chunk of a streamed generation. */
+type AiChunk = {
+  readonly type: 'text-delta';
+  readonly delta: string;
+} | {
+  readonly type: 'tool-call';
+  readonly id: string;
+  readonly name: string;
+  readonly args: unknown;
+} | {
+  readonly type: 'finish';
+  readonly finishReason: FinishReason;
+  readonly usage?: Usage;
+};
+/** The single seam every backend implements (mock, server, on-device). */
+interface AiBackend {
+  /** One-shot generation. */
+  generate(request: GenerateRequest): Promise<AiResult>;
+  /** Streamed generation as an async iterable (throws `AiError` on failure). */
+  stream(request: GenerateRequest): AsyncIterable<AiChunk>;
+}
+/** The app-facing AI handle. */
+interface Ai {
+  generate(request: GenerateRequest): Promise<AiResult>;
+  stream(request: GenerateRequest): AsyncIterable<AiChunk>;
+}
+/** Wrap a {@link AiBackend} in the app-facing {@link Ai} handle. */
+declare function createAi(options: {
+  readonly backend: AiBackend;
+}): Ai;
+/** Flatten a message's content to plain text (ignores non-text parts). */
+declare function messageText(message: Message): string;
+//#endregion
+export { AbortLike, Ai, AiBackend, AiChunk, AiResult, FinishReason, GenerateRequest, Message, Part, Role, TextPart, ToolCallPart, ToolDefinition, ToolResultPart, Usage, createAi, messageText };
+//# sourceMappingURL=contract.d.ts.map

package/dist/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","names":[],"sources":["../src/contract.ts"],"mappings":";;AAUA;;;;AAAgB;AAGhB;;;KAHY,IAAA;AAKG;AAAA,UAFE,QAAA;EAAA,SACN,IAAA;EAAA,SACA,IAAI;AAAA;;UAIE,YAAA;EAAA,SACN,IAAA;EAAA,SACA,EAAA;EAAA,SACA,IAAA;EAAA,SACA,IAAA;AAAA;;UAIM,cAAA;EAAA,SACN,IAAA;EAAA,SACA,EAAA;EAAA,SACA,IAAA;EAAA,SACA,MAAA;AAAA;;KAIC,IAAA,GAAO,QAAA,GAAW,YAAA,GAAe,cAAA;AAA7C;AAAA,UAGiB,OAAA;EAAA,SACN,IAAA,EAAM,IAAA;EAAA,SACN,OAAA,oBAA2B,IAAI;AAAA;;KAI9B,YAAA;;UAGK,KAAA;EAAA,SACN,WAAA;EAAA,SACA,YAAY;AAAA;AAdoC;AAAA,UAkB1C,SAAA;EAAA,SACN,OAAO;AAAA;;;;;;UAQD,cAAA;EAAA,SACN,IAAA;EAAA,SACA,WAAA;EApBa;EAAA,SAsBb,UAAA,GAAa,MAAM;AAAA;AAtBN;AAAA,UA0BP,eAAA;EAAA,SACN,QAAA,WAAmB,OAAA;;WAEnB,WAAA;EAxBY;EAAA,SA0BZ,eAAA;EAtBe;EAAA,SAwBf,KAAA,YAAiB,cAAA;EAvBV;EAAA,SAyBP,MAAA,GAAS,SAAA;AAAA;;UAIH,QAAA;EAAA,SACN,IAAA;EAAA,SACA,SAAA,YAAqB,YAAA;EAAA,SACrB,YAAA,EAAc,YAAA;EAAA,SACd,KAAA,GAAQ,KAAA;AAAA;;KAIP,OAAA;EAAA,SACG,IAAA;EAAA,SAA6B,KAAA;AAAA;EAAA,SAE7B,IAAA;EAAA,SACA,EAAA;EAAA,SACA,IAAA;EAAA,SACA,IAAA;AAAA;EAAA,SAEA,IAAA;EAAA,SAAyB,YAAA,EAAc,YAAA;EAAA,SAAuB,KAAA,GAAQ,KAAK;AAAA;;UAGzE,SAAA;EAvBN;EAyBT,QAAA,CAAS,OAAA,EAAS,eAAA,GAAkB,OAAA,CAAQ,QAAA;EAzBjB;EA2B3B,MAAA,CAAO,OAAA,EAAS,eAAA,GAAkB,aAAA,CAAc,OAAA;AAAA;;UAIjC,EAAA;EACf,QAAA,CAAS,OAAA,EAAS,eAAA,GAAkB,OAAA,CAAQ,QAAA;EAC5C,MAAA,CAAO,OAAA,EAAS,eAAA,GAAkB,aAAA,CAAc,OAAA;AAAA;;iBAIlC,QAAA,CAAS,OAAA;EAAA,SAAoB,OAAA,EAAS,SAAA;AAAA,IAAc,EAAE;;iBAStD,WAAA,CAAY,OAAgB,EAAP,OAAO"}

package/dist/contract.js

@@ -0,0 +1,18 @@
+//#region src/contract.ts
+/** Wrap a {@link AiBackend} in the app-facing {@link Ai} handle. */
+function createAi(options) {
+	const { backend } = options;
+	return {
+		generate: (request) => backend.generate(request),
+		stream: (request) => backend.stream(request)
+	};
+}
+/** Flatten a message's content to plain text (ignores non-text parts). */
+function messageText(message) {
+	if (typeof message.content === "string") return message.content;
+	return message.content.filter((part) => part.type === "text").map((part) => part.text).join("");
+}
+//#endregion
+export { createAi, messageText };
+
+//# sourceMappingURL=contract.js.map

package/dist/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","names":[],"sources":["../src/contract.ts"],"sourcesContent":["/**\n * The Synapse provider-agnostic AI contract — a small, hand-rolled, pure-TS surface\n * every backend (mock, server, on-device) implements. Streaming is `AsyncIterable`\n * only (no Web `ReadableStream`, no Node streams), so it runs on Node, browsers, and\n * Hermes/RN. See `docs/adr/0017-synapse-ai-contract.md`.\n *\n * @module\n */\n\n/** Who authored a message. */\nexport type Role = 'system' | 'user' | 'assistant' | 'tool'\n\n/** A plain text part. */\nexport interface TextPart {\n  readonly type: 'text'\n  readonly text: string\n}\n\n/** A model's request to call a tool (the args are model-produced ⇒ untrusted). */\nexport interface ToolCallPart {\n  readonly type: 'tool-call'\n  readonly id: string\n  readonly name: string\n  readonly args: unknown\n}\n\n/** The result of running a tool, fed back to the model. */\nexport interface ToolResultPart {\n  readonly type: 'tool-result'\n  readonly id: string\n  readonly name: string\n  readonly result: unknown\n}\n\n/** A piece of message content. */\nexport type Part = TextPart | ToolCallPart | ToolResultPart\n\n/** One message in a conversation. */\nexport interface Message {\n  readonly role: Role\n  readonly content: string | readonly Part[]\n}\n\n/** Why a generation stopped. */\nexport type FinishReason = 'stop' | 'length' | 'tool-calls' | 'error'\n\n/** Token usage, when the backend reports it. */\nexport interface Usage {\n  readonly inputTokens?: number\n  readonly outputTokens?: number\n}\n\n/** Minimal cancellation signal — a real `AbortSignal` is structurally compatible. */\nexport interface AbortLike {\n  readonly aborted: boolean\n}\n\n/**\n * A tool the model may call, as sent to the backend (the **wire** shape — no `execute`).\n * `parameters` is a provider-native JSON Schema sent verbatim; the runtime-validating\n * {@link import('./tools').Tool} adds `execute` (+ an optional Standard Schema) on top.\n */\nexport interface ToolDefinition {\n  readonly name: string\n  readonly description?: string\n  /** JSON Schema describing the arguments (sent to the provider as-is). */\n  readonly parameters?: Record<string, unknown>\n}\n\n/** A one-shot or streaming generation request. */\nexport interface GenerateRequest {\n  readonly messages: readonly Message[]\n  /** 0–2-ish sampling temperature (backend-defined default). */\n  readonly temperature?: number\n  /** Cap on output tokens (backend-defined default). */\n  readonly maxOutputTokens?: number\n  /** Tools the model may call. A backend that can't express tools must throw, not drop them. */\n  readonly tools?: readonly ToolDefinition[]\n  /** Cancellation. */\n  readonly signal?: AbortLike\n}\n\n/** The result of {@link AiBackend.generate}. */\nexport interface AiResult {\n  readonly text: string\n  readonly toolCalls?: readonly ToolCallPart[]\n  readonly finishReason: FinishReason\n  readonly usage?: Usage\n}\n\n/** One chunk of a streamed generation. */\nexport type AiChunk =\n  | { readonly type: 'text-delta'; readonly delta: string }\n  | {\n      readonly type: 'tool-call'\n      readonly id: string\n      readonly name: string\n      readonly args: unknown\n    }\n  | { readonly type: 'finish'; readonly finishReason: FinishReason; readonly usage?: Usage }\n\n/** The single seam every backend implements (mock, server, on-device). */\nexport interface AiBackend {\n  /** One-shot generation. */\n  generate(request: GenerateRequest): Promise<AiResult>\n  /** Streamed generation as an async iterable (throws `AiError` on failure). */\n  stream(request: GenerateRequest): AsyncIterable<AiChunk>\n}\n\n/** The app-facing AI handle. */\nexport interface Ai {\n  generate(request: GenerateRequest): Promise<AiResult>\n  stream(request: GenerateRequest): AsyncIterable<AiChunk>\n}\n\n/** Wrap a {@link AiBackend} in the app-facing {@link Ai} handle. */\nexport function createAi(options: { readonly backend: AiBackend }): Ai {\n  const { backend } = options\n  return {\n    generate: (request) => backend.generate(request),\n    stream: (request) => backend.stream(request),\n  }\n}\n\n/** Flatten a message's content to plain text (ignores non-text parts). */\nexport function messageText(message: Message): string {\n  if (typeof message.content === 'string') return message.content\n  return message.content\n    .filter((part): part is TextPart => part.type === 'text')\n    .map((part) => part.text)\n    .join('')\n}\n"],"mappings":";;AAoHA,SAAgB,SAAS,SAA8C;CACrE,MAAM,EAAE,YAAY;CACpB,OAAO;EACL,WAAW,YAAY,QAAQ,SAAS,OAAO;EAC/C,SAAS,YAAY,QAAQ,OAAO,OAAO;CAC7C;AACF;;AAGA,SAAgB,YAAY,SAA0B;CACpD,IAAI,OAAO,QAAQ,YAAY,UAAU,OAAO,QAAQ;CACxD,OAAO,QAAQ,QACZ,QAAQ,SAA2B,KAAK,SAAS,MAAM,EACvD,KAAK,SAAS,KAAK,IAAI,EACvB,KAAK,EAAE;AACZ"}

package/dist/devtools.d.ts

@@ -0,0 +1,43 @@
+import { AbortLike, AiBackend } from "./contract.js";
+
+//#region src/devtools.d.ts
+/** A normalized error to explain (a plain object, or pass an `Error` directly). */
+interface ExplainInput {
+  readonly message: string;
+  readonly stack?: string;
+  readonly code?: string | number;
+}
+/** Options for {@link explainError}. */
+interface ExplainOptions {
+  /** Language/runtime hint, e.g. `'TypeScript'` / `'Node 24'`. */
+  readonly language?: string;
+  /** Relevant source around the error, included verbatim in the prompt. */
+  readonly codeContext?: string;
+  /** Repair re-asks if the model's JSON is malformed (default `1`). */
+  readonly maxRepairs?: number;
+  /** Cancellation. */
+  readonly signal?: AbortLike;
+}
+/** A structured explanation of an error. */
+interface ErrorExplanation {
+  /** One- or two-sentence plain-language summary of what went wrong. */
+  readonly summary: string;
+  /** Most likely causes, most-likely first. */
+  readonly likelyCauses: readonly string[];
+  /** Concrete, ordered suggested fixes. */
+  readonly suggestedFixes: readonly string[];
+}
+/**
+ * Explain an error using the model behind `backend`, returning a validated
+ * {@link ErrorExplanation}. Built on {@link generateObject} (prompt → extract → sanitize →
+ * validate → bounded repair), so it runs offline against the mock and live against a server.
+ *
+ * @throws AiError `INVALID_OBJECT` if the model can't produce a usable explanation in the
+ * repair budget, or `ABORTED` on cancellation.
+ */
+declare function explainError(backend: Pick<AiBackend, 'generate'>, error: Error | ExplainInput, options?: ExplainOptions): Promise<ErrorExplanation>;
+/** Render an {@link ErrorExplanation} as readable terminal text. */
+declare function formatExplanation(explanation: ErrorExplanation): string;
+//#endregion
+export { ErrorExplanation, ExplainInput, ExplainOptions, explainError, formatExplanation };
+//# sourceMappingURL=devtools.d.ts.map

package/dist/devtools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"devtools.d.ts","names":[],"sources":["../src/devtools.ts"],"mappings":";;;AAmBe;AAAA,UAHE,YAAA;EAAA,SACN,OAAA;EAAA,SACA,KAAA;EAAA,SACA,IAAA;AAAA;;UAIM,cAAA;EAQN;EAAA,SANA,QAAA;EAMkB;EAAA,SAJlB,WAAA;EAQM;EAAA,SANN,UAAA;;WAEA,MAAA,GAAS,SAAS;AAAA;;UAIZ,gBAAA;EAMQ;EAAA,SAJd,OAAA;EAuDW;EAAA,SArDX,YAAA;;WAEA,cAAA;AAAA;;;;;;;;;iBAmDW,YAAA,CACpB,OAAA,EAAS,IAAA,CAAK,SAAA,eACd,KAAA,EAAO,KAAA,GAAQ,YAAA,EACf,OAAA,GAAS,cAAA,GACR,OAAA,CAAQ,gBAAA;;iBA2BK,iBAAA,CAAkB,WAA6B,EAAhB,gBAAgB"}

package/dist/devtools.js

@@ -0,0 +1,77 @@
+import { generateObject } from "./object.js";
+//#region src/devtools.ts
+function toStringArray(value) {
+	return Array.isArray(value) ? value.filter((x) => typeof x === "string") : [];
+}
+const explanationSchema = { "~standard": {
+	version: 1,
+	vendor: "mindees-devtools",
+	validate: (value) => {
+		const o = typeof value === "object" && value !== null ? value : void 0;
+		const summary = typeof o?.summary === "string" && o.summary.length > 0 ? o.summary : void 0;
+		if (summary === void 0) return { issues: [{
+			message: "summary must be a non-empty string",
+			path: ["summary"]
+		}] };
+		return { value: {
+			summary,
+			likelyCauses: toStringArray(o?.likelyCauses),
+			suggestedFixes: toStringArray(o?.suggestedFixes)
+		} };
+	}
+} };
+function normalize(error) {
+	if (error instanceof Error) {
+		const code = error.code;
+		return {
+			message: error.message,
+			...error.stack ? { stack: error.stack } : {},
+			...typeof code === "string" || typeof code === "number" ? { code } : {}
+		};
+	}
+	return error;
+}
+/**
+* Explain an error using the model behind `backend`, returning a validated
+* {@link ErrorExplanation}. Built on {@link generateObject} (prompt → extract → sanitize →
+* validate → bounded repair), so it runs offline against the mock and live against a server.
+*
+* @throws AiError `INVALID_OBJECT` if the model can't produce a usable explanation in the
+* repair budget, or `ABORTED` on cancellation.
+*/
+async function explainError(backend, error, options = {}) {
+	const input = normalize(error);
+	return (await generateObject(backend, {
+		messages: [{
+			role: "user",
+			content: [
+				"You are a senior debugging assistant for TypeScript/JavaScript applications.",
+				"Explain the error below and how to fix it — be concrete and concise.",
+				options.language ? `Language/runtime: ${options.language}.` : "",
+				`Error message: ${input.message}`,
+				input.code !== void 0 ? `Error code: ${input.code}` : "",
+				input.stack ? `Stack trace:\n${input.stack}` : "",
+				options.codeContext ? `Relevant code:\n${options.codeContext}` : "",
+				"Reply as JSON: { \"summary\": string, \"likelyCauses\": string[], \"suggestedFixes\": string[] }."
+			].filter(Boolean).join("\n")
+		}],
+		...options.signal ? { signal: options.signal } : {}
+	}, explanationSchema, { maxRepairs: options.maxRepairs ?? 1 })).object;
+}
+/** Render an {@link ErrorExplanation} as readable terminal text. */
+function formatExplanation(explanation) {
+	const lines = [`Summary: ${explanation.summary}`];
+	if (explanation.likelyCauses.length > 0) {
+		lines.push("", "Likely causes:");
+		for (const cause of explanation.likelyCauses) lines.push(`  • ${cause}`);
+	}
+	if (explanation.suggestedFixes.length > 0) {
+		lines.push("", "Suggested fixes:");
+		for (const fix of explanation.suggestedFixes) lines.push(`  • ${fix}`);
+	}
+	return lines.join("\n");
+}
+//#endregion
+export { explainError, formatExplanation };
+
+//# sourceMappingURL=devtools.js.map

package/dist/devtools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"devtools.js","names":[],"sources":["../src/devtools.ts"],"sourcesContent":["/**\n * Synapse dev-time intelligence — a **build/dev-only** error explainer over the same AI\n * contract. `explainError` turns a thrown error into a structured, actionable explanation via\n * {@link generateObject}, so it works against any backend (the deterministic mock in tests, a\n * server backend in a CLI). Exported from the `@mindees/ai/devtools` subpath to signal intent:\n * this is for your toolchain, not the device bundle (don't ship it into a running app). See\n * `docs/adr/0021-synapse-devtools.md`.\n *\n * @module\n */\n\nimport type { AbortLike, AiBackend, GenerateRequest, Message } from './contract'\nimport { generateObject } from './object'\nimport type { StandardSchemaV1 } from './standard-schema'\n\n/** A normalized error to explain (a plain object, or pass an `Error` directly). */\nexport interface ExplainInput {\n  readonly message: string\n  readonly stack?: string\n  readonly code?: string | number\n}\n\n/** Options for {@link explainError}. */\nexport interface ExplainOptions {\n  /** Language/runtime hint, e.g. `'TypeScript'` / `'Node 24'`. */\n  readonly language?: string\n  /** Relevant source around the error, included verbatim in the prompt. */\n  readonly codeContext?: string\n  /** Repair re-asks if the model's JSON is malformed (default `1`). */\n  readonly maxRepairs?: number\n  /** Cancellation. */\n  readonly signal?: AbortLike\n}\n\n/** A structured explanation of an error. */\nexport interface ErrorExplanation {\n  /** One- or two-sentence plain-language summary of what went wrong. */\n  readonly summary: string\n  /** Most likely causes, most-likely first. */\n  readonly likelyCauses: readonly string[]\n  /** Concrete, ordered suggested fixes. */\n  readonly suggestedFixes: readonly string[]\n}\n\nfunction toStringArray(value: unknown): string[] {\n  return Array.isArray(value) ? value.filter((x): x is string => typeof x === 'string') : []\n}\n\n// A lenient Standard Schema: requires a `summary` string; coerces the two arrays (a model may\n// omit them). Validated through the same sanitize→validate pipeline as any structured output.\nconst explanationSchema: StandardSchemaV1<unknown, ErrorExplanation> = {\n  '~standard': {\n    version: 1,\n    vendor: 'mindees-devtools',\n    validate: (value) => {\n      const o =\n        typeof value === 'object' && value !== null ? (value as Record<string, unknown>) : undefined\n      const summary = typeof o?.summary === 'string' && o.summary.length > 0 ? o.summary : undefined\n      if (summary === undefined) {\n        return { issues: [{ message: 'summary must be a non-empty string', path: ['summary'] }] }\n      }\n      return {\n        value: {\n          summary,\n          likelyCauses: toStringArray(o?.likelyCauses),\n          suggestedFixes: toStringArray(o?.suggestedFixes),\n        },\n      }\n    },\n  },\n}\n\nfunction normalize(error: Error | ExplainInput): ExplainInput {\n  if (error instanceof Error) {\n    const code = (error as { code?: unknown }).code\n    return {\n      message: error.message,\n      ...(error.stack ? { stack: error.stack } : {}),\n      ...(typeof code === 'string' || typeof code === 'number' ? { code } : {}),\n    }\n  }\n  return error\n}\n\n/**\n * Explain an error using the model behind `backend`, returning a validated\n * {@link ErrorExplanation}. Built on {@link generateObject} (prompt → extract → sanitize →\n * validate → bounded repair), so it runs offline against the mock and live against a server.\n *\n * @throws AiError `INVALID_OBJECT` if the model can't produce a usable explanation in the\n * repair budget, or `ABORTED` on cancellation.\n */\nexport async function explainError(\n  backend: Pick<AiBackend, 'generate'>,\n  error: Error | ExplainInput,\n  options: ExplainOptions = {},\n): Promise<ErrorExplanation> {\n  const input = normalize(error)\n  const prompt = [\n    'You are a senior debugging assistant for TypeScript/JavaScript applications.',\n    'Explain the error below and how to fix it — be concrete and concise.',\n    options.language ? `Language/runtime: ${options.language}.` : '',\n    `Error message: ${input.message}`,\n    input.code !== undefined ? `Error code: ${input.code}` : '',\n    input.stack ? `Stack trace:\\n${input.stack}` : '',\n    options.codeContext ? `Relevant code:\\n${options.codeContext}` : '',\n    'Reply as JSON: { \"summary\": string, \"likelyCauses\": string[], \"suggestedFixes\": string[] }.',\n  ]\n    .filter(Boolean)\n    .join('\\n')\n\n  const message: Message = { role: 'user', content: prompt }\n  const request: GenerateRequest = {\n    messages: [message],\n    ...(options.signal ? { signal: options.signal } : {}),\n  }\n  const result = await generateObject(backend, request, explanationSchema, {\n    maxRepairs: options.maxRepairs ?? 1,\n  })\n  return result.object\n}\n\n/** Render an {@link ErrorExplanation} as readable terminal text. */\nexport function formatExplanation(explanation: ErrorExplanation): string {\n  const lines: string[] = [`Summary: ${explanation.summary}`]\n  if (explanation.likelyCauses.length > 0) {\n    lines.push('', 'Likely causes:')\n    for (const cause of explanation.likelyCauses) lines.push(`  • ${cause}`)\n  }\n  if (explanation.suggestedFixes.length > 0) {\n    lines.push('', 'Suggested fixes:')\n    for (const fix of explanation.suggestedFixes) lines.push(`  • ${fix}`)\n  }\n  return lines.join('\\n')\n}\n"],"mappings":";;AA4CA,SAAS,cAAc,OAA0B;CAC/C,OAAO,MAAM,QAAQ,KAAK,IAAI,MAAM,QAAQ,MAAmB,OAAO,MAAM,QAAQ,IAAI,CAAC;AAC3F;AAIA,MAAM,oBAAiE,EACrE,aAAa;CACX,SAAS;CACT,QAAQ;CACR,WAAW,UAAU;EACnB,MAAM,IACJ,OAAO,UAAU,YAAY,UAAU,OAAQ,QAAoC,KAAA;EACrF,MAAM,UAAU,OAAO,GAAG,YAAY,YAAY,EAAE,QAAQ,SAAS,IAAI,EAAE,UAAU,KAAA;EACrF,IAAI,YAAY,KAAA,GACd,OAAO,EAAE,QAAQ,CAAC;GAAE,SAAS;GAAsC,MAAM,CAAC,SAAS;EAAE,CAAC,EAAE;EAE1F,OAAO,EACL,OAAO;GACL;GACA,cAAc,cAAc,GAAG,YAAY;GAC3C,gBAAgB,cAAc,GAAG,cAAc;EACjD,EACF;CACF;AACF,EACF;AAEA,SAAS,UAAU,OAA2C;CAC5D,IAAI,iBAAiB,OAAO;EAC1B,MAAM,OAAQ,MAA6B;EAC3C,OAAO;GACL,SAAS,MAAM;GACf,GAAI,MAAM,QAAQ,EAAE,OAAO,MAAM,MAAM,IAAI,CAAC;GAC5C,GAAI,OAAO,SAAS,YAAY,OAAO,SAAS,WAAW,EAAE,KAAK,IAAI,CAAC;EACzE;CACF;CACA,OAAO;AACT;;;;;;;;;AAUA,eAAsB,aACpB,SACA,OACA,UAA0B,CAAC,GACA;CAC3B,MAAM,QAAQ,UAAU,KAAK;CAsB7B,QAAO,MAHc,eAAe,SAAS;EAH3C,UAAU,CAAC;GAFc,MAAM;GAAQ,SAb1B;IACb;IACA;IACA,QAAQ,WAAW,qBAAqB,QAAQ,SAAS,KAAK;IAC9D,kBAAkB,MAAM;IACxB,MAAM,SAAS,KAAA,IAAY,eAAe,MAAM,SAAS;IACzD,MAAM,QAAQ,iBAAiB,MAAM,UAAU;IAC/C,QAAQ,cAAc,mBAAmB,QAAQ,gBAAgB;IACjE;GACF,EACG,OAAO,OAAO,EACd,KAAK,IAE+C;EAEpC,CAAC;EAClB,GAAI,QAAQ,SAAS,EAAE,QAAQ,QAAQ,OAAO,IAAI,CAAC;CAEF,GAAG,mBAAmB,EACvE,YAAY,QAAQ,cAAc,EACpC,CAAC,GACa;AAChB;;AAGA,SAAgB,kBAAkB,aAAuC;CACvE,MAAM,QAAkB,CAAC,YAAY,YAAY,SAAS;CAC1D,IAAI,YAAY,aAAa,SAAS,GAAG;EACvC,MAAM,KAAK,IAAI,gBAAgB;EAC/B,KAAK,MAAM,SAAS,YAAY,cAAc,MAAM,KAAK,OAAO,OAAO;CACzE;CACA,IAAI,YAAY,eAAe,SAAS,GAAG;EACzC,MAAM,KAAK,IAAI,kBAAkB;EACjC,KAAK,MAAM,OAAO,YAAY,gBAAgB,MAAM,KAAK,OAAO,KAAK;CACvE;CACA,OAAO,MAAM,KAAK,IAAI;AACxB"}

package/dist/errors.d.ts

@@ -0,0 +1,21 @@
+import { StandardSchemaV1 } from "./standard-schema.js";
+
+//#region src/errors.d.ts
+/** Stable code identifying why an AI operation failed. */
+type AiErrorCode = /** No transport/fetch was provided to a backend that needs one. */'NO_TRANSPORT' /** The server returned a non-2xx status. */ | 'HTTP_STATUS' /** A streaming response could not be parsed. */ | 'STREAM_PARSE' /** Structured output failed schema validation (after repair attempts). */ | 'INVALID_OBJECT' /** A tool-calling loop exceeded its step ceiling. */ | 'MAX_STEPS' /** A tool handler threw. */ | 'TOOL_FAILED' /** The request was aborted. */ | 'ABORTED' /** An on-device / research-track capability is not implemented. */ | 'NOT_IMPLEMENTED';
+/** Optional structured detail attached to an {@link AiError}. */
+interface AiErrorOptions {
+  /** Standard Schema issues — set on `INVALID_OBJECT` from schema validation. */
+  readonly issues?: ReadonlyArray<StandardSchemaV1.Issue>;
+}
+/** An AI error carrying a stable {@link AiErrorCode}. */
+declare class AiError extends Error {
+  /** Stable, machine-readable cause. */
+  readonly code: AiErrorCode;
+  /** Validation issues, when the failure came from schema validation. */
+  readonly issues?: ReadonlyArray<StandardSchemaV1.Issue>;
+  constructor(code: AiErrorCode, message: string, options?: AiErrorOptions);
+}
+//#endregion
+export { AiError, AiErrorCode, AiErrorOptions };
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","names":[],"sources":["../src/errors.ts"],"mappings":";;;AAUuB;AAAA,KAAX,WAAA,kTAqB4C;;UAFvC,cAAA;EAMiB;EAAA,SAJvB,MAAA,GAAS,aAAa,CAAC,gBAAA,CAAiB,KAAA;AAAA;;cAItC,OAAA,SAAgB,KAAA;EAIlB;EAAA,SAFA,IAAA,EAAM,WAAA;EAEiB;EAAA,SAAvB,MAAA,GAAS,aAAA,CAAc,gBAAA,CAAiB,KAAA;cAErC,IAAA,EAAM,WAAA,EAAa,OAAA,UAAiB,OAAA,GAAU,cAAA;AAAA"}

package/dist/errors.js

@@ -0,0 +1,18 @@
+//#region src/errors.ts
+/** An AI error carrying a stable {@link AiErrorCode}. */
+var AiError = class extends Error {
+	/** Stable, machine-readable cause. */
+	code;
+	/** Validation issues, when the failure came from schema validation. */
+	issues;
+	constructor(code, message, options) {
+		super(message);
+		this.name = "AiError";
+		this.code = code;
+		if (options?.issues) this.issues = options.issues;
+	}
+};
+//#endregion
+export { AiError };
+
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","names":[],"sources":["../src/errors.ts"],"sourcesContent":["/**\n * Errors for `@mindees/ai` (Synapse). Every failure carries a stable\n * {@link AiErrorCode} so callers can branch on the cause without string-matching.\n *\n * @module\n */\n\nimport type { StandardSchemaV1 } from './standard-schema'\n\n/** Stable code identifying why an AI operation failed. */\nexport type AiErrorCode =\n  /** No transport/fetch was provided to a backend that needs one. */\n  | 'NO_TRANSPORT'\n  /** The server returned a non-2xx status. */\n  | 'HTTP_STATUS'\n  /** A streaming response could not be parsed. */\n  | 'STREAM_PARSE'\n  /** Structured output failed schema validation (after repair attempts). */\n  | 'INVALID_OBJECT'\n  /** A tool-calling loop exceeded its step ceiling. */\n  | 'MAX_STEPS'\n  /** A tool handler threw. */\n  | 'TOOL_FAILED'\n  /** The request was aborted. */\n  | 'ABORTED'\n  /** An on-device / research-track capability is not implemented. */\n  | 'NOT_IMPLEMENTED'\n\n/** Optional structured detail attached to an {@link AiError}. */\nexport interface AiErrorOptions {\n  /** Standard Schema issues — set on `INVALID_OBJECT` from schema validation. */\n  readonly issues?: ReadonlyArray<StandardSchemaV1.Issue>\n}\n\n/** An AI error carrying a stable {@link AiErrorCode}. */\nexport class AiError extends Error {\n  /** Stable, machine-readable cause. */\n  readonly code: AiErrorCode\n  /** Validation issues, when the failure came from schema validation. */\n  readonly issues?: ReadonlyArray<StandardSchemaV1.Issue>\n\n  constructor(code: AiErrorCode, message: string, options?: AiErrorOptions) {\n    super(message)\n    this.name = 'AiError'\n    this.code = code\n    // Set only when present (exactOptionalPropertyTypes-safe).\n    if (options?.issues) this.issues = options.issues\n  }\n}\n"],"mappings":";;AAmCA,IAAa,UAAb,cAA6B,MAAM;;CAEjC;;CAEA;CAEA,YAAY,MAAmB,SAAiB,SAA0B;EACxE,MAAM,OAAO;EACb,KAAK,OAAO;EACZ,KAAK,OAAO;EAEZ,IAAI,SAAS,QAAQ,KAAK,SAAS,QAAQ;CAC7C;AACF"}

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+import { AbortLike, Ai, AiBackend, AiChunk, AiResult, FinishReason, GenerateRequest, Message, Part, Role, TextPart, ToolCallPart, ToolDefinition, ToolResultPart, Usage, createAi, messageText } from "./contract.js";
+import { StandardSchemaV1 } from "./standard-schema.js";
+import { AiError, AiErrorCode, AiErrorOptions } from "./errors.js";
+import { DEFAULT_MAX_INPUT_CHARS, ExtractResult, SanitizeLimits, ValidationOutcome, containsForbiddenKey, extractJson, formatIssues, lenientParseJson, sanitizeJson, validateStandard } from "./json.js";
+import { MockBackendOptions, MockReply, MockResponse, createMockBackend } from "./mock.js";
+import { GenerateObjectOptions, GenerateObjectResult, GeneratingBackend, StreamObjectChunk, StreamObjectOptions, StreamingBackend, generateObject, streamObject } from "./object.js";
+import { createOnDeviceBackend } from "./on-device.js";
+import { RunToolsOptions, RunToolsResult, Tool, ToolContext, runTools } from "./tools.js";
+import { Maturity, NotImplementedError, PackageInfo, notImplemented } from "@mindees/core";
+
+//#region src/index.d.ts
+/** The npm package name. */
+declare const name = "@mindees/ai";
+/** The package version. All `@mindees/*` packages share one locked version line. */
+declare const VERSION = "0.1.0";
+/** Current maturity of this package. See the repository `STATUS.md`. */
+declare const maturity: Maturity;
+/**
+ * Static identity + maturity metadata for this package. Frozen so the
+ * self-reported identity tooling introspects cannot be mutated at runtime,
+ * matching the `readonly` fields of {@link PackageInfo}.
+ */
+declare const info: PackageInfo;
+//#endregion
+export { type AbortLike, type Ai, type AiBackend, type AiChunk, AiError, type AiErrorCode, type AiErrorOptions, type AiResult, DEFAULT_MAX_INPUT_CHARS, type ExtractResult, type FinishReason, type GenerateObjectOptions, type GenerateObjectResult, type GenerateRequest, type GeneratingBackend, type Maturity, type Message, type MockBackendOptions, type MockReply, type MockResponse, NotImplementedError, type PackageInfo, type Part, type Role, type RunToolsOptions, type RunToolsResult, type SanitizeLimits, type StandardSchemaV1, type StreamObjectChunk, type StreamObjectOptions, type StreamingBackend, type TextPart, type Tool, type ToolCallPart, type ToolContext, type ToolDefinition, type ToolResultPart, type Usage, VERSION, type ValidationOutcome, containsForbiddenKey, createAi, createMockBackend, createOnDeviceBackend, extractJson, formatIssues, generateObject, info, lenientParseJson, maturity, messageText, name, notImplemented, runTools, sanitizeJson, streamObject, validateStandard };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;;;;;;;;cAoBa,IAAA;;cAGA,OAAA;AAGb;AAAA,cAAa,QAAA,EAAU,QAAyB;;;AAAA;AAOhD;;cAAa,IAAA,EAAM,WAAiE"}

package/dist/index.js

@@ -0,0 +1,29 @@
+import { createAi, messageText } from "./contract.js";
+import { AiError } from "./errors.js";
+import { DEFAULT_MAX_INPUT_CHARS, containsForbiddenKey, extractJson, formatIssues, lenientParseJson, sanitizeJson, validateStandard } from "./json.js";
+import { createMockBackend } from "./mock.js";
+import { generateObject, streamObject } from "./object.js";
+import { createOnDeviceBackend } from "./on-device.js";
+import { runTools } from "./tools.js";
+import { NotImplementedError, notImplemented } from "@mindees/core";
+//#region src/index.ts
+/** The npm package name. */
+const name = "@mindees/ai";
+/** The package version. All `@mindees/*` packages share one locked version line. */
+const VERSION = "0.1.0";
+/** Current maturity of this package. See the repository `STATUS.md`. */
+const maturity = "experimental";
+/**
+* Static identity + maturity metadata for this package. Frozen so the
+* self-reported identity tooling introspects cannot be mutated at runtime,
+* matching the `readonly` fields of {@link PackageInfo}.
+*/
+const info = Object.freeze({
+	name,
+	version: VERSION,
+	maturity
+});
+//#endregion
+export { AiError, DEFAULT_MAX_INPUT_CHARS, NotImplementedError, VERSION, containsForbiddenKey, createAi, createMockBackend, createOnDeviceBackend, extractJson, formatIssues, generateObject, info, lenientParseJson, maturity, messageText, name, notImplemented, runTools, sanitizeJson, streamObject, validateStandard };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * `@mindees/ai` (Synapse) — provider-agnostic AI + dev-time intelligence.\n *\n * Phase 11 ships the **contract** ({@link createAi}, {@link AiBackend}, messages,\n * {@link GenerateRequest}/{@link AiResult}/{@link AiChunk}, {@link AiError}) with\n * streaming as `AsyncIterable` only (Node/browser/Hermes-safe), a deterministic\n * {@link createMockBackend mock backend} (the working, offline, no-keys fallback),\n * Standard-Schema structured output, bounded tool calling, an inject-`fetch` server\n * backend on the `@mindees/ai/server` subpath, and a dev-time error explainer on the\n * `@mindees/ai/devtools` subpath. The {@link createOnDeviceBackend on-device seam}\n * throws because on-device LLM inference is inherently native and stays a 🔬 research\n * track.\n *\n * @module\n */\n\nimport type { Maturity, PackageInfo } from '@mindees/core'\nimport { NotImplementedError, notImplemented } from '@mindees/core'\n\n/** The npm package name. */\nexport const name = '@mindees/ai'\n\n/** The package version. All `@mindees/*` packages share one locked version line. */\nexport const VERSION = '0.1.0'\n\n/** Current maturity of this package. See the repository `STATUS.md`. */\nexport const maturity: Maturity = 'experimental'\n\n/**\n * Static identity + maturity metadata for this package. Frozen so the\n * self-reported identity tooling introspects cannot be mutated at runtime,\n * matching the `readonly` fields of {@link PackageInfo}.\n */\nexport const info: PackageInfo = Object.freeze({ name, version: VERSION, maturity })\n\nexport {\n  type AbortLike,\n  type Ai,\n  type AiBackend,\n  type AiChunk,\n  type AiResult,\n  createAi,\n  type FinishReason,\n  type GenerateRequest,\n  type Message,\n  messageText,\n  type Part,\n  type Role,\n  type TextPart,\n  type ToolCallPart,\n  type ToolDefinition,\n  type ToolResultPart,\n  type Usage,\n} from './contract'\nexport { AiError, type AiErrorCode, type AiErrorOptions } from './errors'\nexport {\n  containsForbiddenKey,\n  DEFAULT_MAX_INPUT_CHARS,\n  type ExtractResult,\n  extractJson,\n  formatIssues,\n  lenientParseJson,\n  type SanitizeLimits,\n  sanitizeJson,\n  type ValidationOutcome,\n  validateStandard,\n} from './json'\nexport {\n  createMockBackend,\n  type MockBackendOptions,\n  type MockReply,\n  type MockResponse,\n} from './mock'\nexport {\n  type GenerateObjectOptions,\n  type GenerateObjectResult,\n  type GeneratingBackend,\n  generateObject,\n  type StreamingBackend,\n  type StreamObjectChunk,\n  type StreamObjectOptions,\n  streamObject,\n} from './object'\nexport { createOnDeviceBackend } from './on-device'\nexport type { StandardSchemaV1 } from './standard-schema'\nexport {\n  type RunToolsOptions,\n  type RunToolsResult,\n  runTools,\n  type Tool,\n  type ToolContext,\n} from './tools'\n\nexport type { Maturity, PackageInfo }\nexport { NotImplementedError, notImplemented }\n"],"mappings":";;;;;;;;;;AAoBA,MAAa,OAAO;;AAGpB,MAAa,UAAU;;AAGvB,MAAa,WAAqB;;;;;;AAOlC,MAAa,OAAoB,OAAO,OAAO;CAAE;CAAM,SAAS;CAAS;AAAS,CAAC"}

package/dist/json.d.ts

@@ -0,0 +1,76 @@
+import { StandardSchemaV1 } from "./standard-schema.js";
+
+//#region src/json.d.ts
+/**
+ * Max characters of untrusted model text handed to `JSON.parse`. A size gate enforced BEFORE
+ * parsing (mirrors the SSE backend's `MAX_SSE_BUFFER`) so a hostile payload can't be fully
+ * allocated before the post-parse limits in {@link sanitizeJson} would reject it. ~8M chars.
+ */
+declare const DEFAULT_MAX_INPUT_CHARS: number;
+/** Limits that bound a sanitized value so hostile model JSON can't exhaust memory. */
+interface SanitizeLimits {
+  /** Max nesting depth. */
+  readonly maxDepth: number;
+  /** Max total nodes (objects + arrays + primitives) across the whole value. */
+  readonly maxNodes: number;
+  /** Max length of any single string. */
+  readonly maxStringLength: number;
+  /** Max own keys on any single object. */
+  readonly maxProps: number;
+}
+/** The outcome of {@link extractJson}. */
+type ExtractResult = {
+  readonly ok: true;
+  readonly value: unknown;
+} | {
+  readonly ok: false;
+  readonly reason: string;
+};
+/**
+ * Extract a JSON value from model text, trying in a fixed, testable order:
+ * 1. parse the whole (trimmed) text; 2. parse the first fenced code block; 3. parse the
+ * first balanced brace/bracket span. Never uses a capturing regex or `eval`.
+ */
+declare function extractJson(text: string, maxChars?: number): ExtractResult;
+/**
+ * Best-effort parse of *incomplete* JSON for streaming previews: closes any open string and
+ * unbalanced brackets, drops a dangling `,`/`:`, and parses. Returns `undefined` whenever it
+ * can't safely produce a value (never throws, never guesses a value token). The result is
+ * **unvalidated and unsanitized** — callers must treat it as an untyped preview only.
+ */
+declare function lenientParseJson(text: string, maxChars?: number): unknown;
+/**
+ * Deep-clone untrusted parsed JSON into a fresh value, throwing `AiError('INVALID_OBJECT')`
+ * on any prototype-pollution key (`__proto__`/`constructor`/`prototype`) at any depth or on
+ * any limit breach. Run this BEFORE handing a value to a Standard Schema validator — a
+ * validator can itself pollute the prototype by touching a poisoned object.
+ */
+declare function sanitizeJson(value: unknown, limits?: SanitizeLimits): unknown;
+/**
+ * Cheap recursive check for any prototype-pollution own key, WITHOUT cloning. Used to skip
+ * emitting an unsanitized streaming preview that carries a poison key (so a consumer who
+ * naively deep-merges the preview can't be tricked into polluting the prototype). Depth-capped
+ * and fail-closed: a value nested past `maxDepth` is treated as forbidden (skip the preview)
+ * rather than risking a stack overflow on a deeply-nested untrusted payload.
+ */
+declare function containsForbiddenKey(value: unknown, maxDepth?: number, depth?: number): boolean;
+/** Render Standard Schema issues into one readable line: `path: message; path2: message2`. */
+declare function formatIssues(issues: ReadonlyArray<StandardSchemaV1.Issue>): string;
+/** A normalized validation outcome (sync — the Promise has already been awaited). */
+type ValidationOutcome<T> = {
+  readonly ok: true;
+  readonly value: T;
+} | {
+  readonly ok: false;
+  readonly issues: ReadonlyArray<StandardSchemaV1.Issue>;
+};
+/**
+ * Validate a (already-sanitized) value through a Standard Schema, awaiting an async validator.
+ * Defensively narrows a malformed validator result (non-array `issues`) into a failure rather
+ * than crashing. Discriminates on `issues` truthiness — a valid output may legitimately be
+ * `undefined`, so `value` is not a reliable discriminant.
+ */
+declare function validateStandard<S extends StandardSchemaV1>(schema: S, value: unknown): Promise<ValidationOutcome<StandardSchemaV1.InferOutput<S>>>;
+//#endregion
+export { DEFAULT_MAX_INPUT_CHARS, ExtractResult, SanitizeLimits, ValidationOutcome, containsForbiddenKey, extractJson, formatIssues, lenientParseJson, sanitizeJson, validateStandard };
+//# sourceMappingURL=json.d.ts.map

package/dist/json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.d.ts","names":[],"sources":["../src/json.ts"],"mappings":";;;;;;;;cAqBa,uBAAA;;UAGI,cAAA;EAwBL;EAAA,SAtBD,QAAA;;WAEA,QAAA;EAqBI;EAAA,SAnBJ,eAAA;EAqBI;EAAA,SAnBJ,QAAA;AAAA;;KAgBC,aAAA;EAAA,SACG,EAAA;EAAA,SAAmB,KAAA;AAAA;EAAA,SAEnB,EAAA;EAAA,SACA,MAAA;AAAA;AAsGf;;;;AAE4C;AAF5C,iBAhCgB,WAAA,CACd,IAAA,UACA,QAAA,YACC,aAAa;;;;;;;iBA6BA,gBAAA,CACd,IAAA,UACA,QAA0C;AAyDM;AAgDlD;;;;;AAhDkD,iBAFlC,YAAA,CACd,KAAA,WACA,MAAA,GAAQ,cAAwC;;;AAmDvC;AAcX;;;;iBAjBgB,oBAAA,CACd,KAAA,WACA,QAAA,WACA,KAAA;;iBAcc,YAAA,CAAa,MAAA,EAAQ,aAAa,CAAC,gBAAA,CAAiB,KAAA;;KAiBxD,iBAAA;EAAA,SACG,EAAA;EAAA,SAAmB,KAAA,EAAO,CAAA;AAAA;EAAA,SAC1B,EAAA;EAAA,SAAoB,MAAA,EAAQ,aAAA,CAAc,gBAAA,CAAiB,KAAA;AAAA;;;;;;;iBAQpD,gBAAA,WAA2B,gBAAA,EAC/C,MAAA,EAAQ,CAAA,EACR,KAAA,YACC,OAAA,CAAQ,iBAAA,CAAkB,gBAAA,CAAiB,WAAA,CAAY,CAAA"}