trail-code 0.0.0-stage → 0.28.0-semantic.3

package/dist/ai/llm/orcarouter.d.ts

@@ -0,0 +1,34 @@
+/**
+ * OrcaRouter transport. The OrcaRouter gateway speaks the OpenAI-compatible
+ * wire format, so this reuses the OpenAI adapter's request/response translation
+ * and simply points it at the gateway. The value over a bare `openai` provider +
+ * `baseUrl` is a first-class, self-describing provider: a sensible default
+ * gateway address and `/v1/models` auto-discovery (see {@link listOrcaRouterModels}),
+ * so callers can enumerate whatever upstream models the gateway routes to —
+ * reaching 150+ models from OpenAI, Anthropic, Google, DeepSeek, Qwen, and more
+ * through one endpoint without a per-vendor code path.
+ */
+import OpenAI from "openai";
+import { OpenAIChatModel, type OpenAIChatModelOptions } from "./openai.js";
+/** Public endpoint of the OrcaRouter AI gateway. */
+export declare const DEFAULT_ORCAROUTER_BASE_URL = "https://api.orcarouter.ai/v1";
+export type OrcaRouterChatModelOptions = OpenAIChatModelOptions;
+/**
+ * ChatModel backed by the OrcaRouter gateway. Inherits every translation detail
+ * from {@link OpenAIChatModel} (the gateway is OpenAI-compatible) and only
+ * changes the defaults: the gateway base URL and an `orcarouter:<model>` label.
+ */
+export declare class OrcaRouterChatModel extends OpenAIChatModel {
+    constructor(opts: OrcaRouterChatModelOptions);
+}
+/**
+ * Auto-discover the models the OrcaRouter gateway can route to via `GET
+ * /v1/models`. Returns the model ids so a caller can present/validate them
+ * instead of hardcoding a model string. A stub `client` may be injected for tests.
+ */
+export declare function listOrcaRouterModels(opts: {
+    apiKey: string;
+    baseUrl?: string;
+    client?: OpenAI;
+}): Promise<string[]>;
+//# sourceMappingURL=orcarouter.d.ts.map

package/dist/ai/llm/orcarouter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orcarouter.d.ts","sourceRoot":"","sources":["../../../src/ai/llm/orcarouter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,MAAM,MAAM,QAAQ,CAAC;AAC5B,OAAO,EAAE,eAAe,EAAE,KAAK,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAG3E,oDAAoD;AACpD,eAAO,MAAM,2BAA2B,iCAAiC,CAAC;AAE1E,MAAM,MAAM,0BAA0B,GAAG,sBAAsB,CAAC;AAEhE;;;;GAIG;AACH,qBAAa,mBAAoB,SAAQ,eAAe;gBAC1C,IAAI,EAAE,0BAA0B;CAO7C;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAUpB"}

package/dist/ai/llm/orcarouter.js

@@ -0,0 +1,45 @@
+/**
+ * OrcaRouter transport. The OrcaRouter gateway speaks the OpenAI-compatible
+ * wire format, so this reuses the OpenAI adapter's request/response translation
+ * and simply points it at the gateway. The value over a bare `openai` provider +
+ * `baseUrl` is a first-class, self-describing provider: a sensible default
+ * gateway address and `/v1/models` auto-discovery (see {@link listOrcaRouterModels}),
+ * so callers can enumerate whatever upstream models the gateway routes to —
+ * reaching 150+ models from OpenAI, Anthropic, Google, DeepSeek, Qwen, and more
+ * through one endpoint without a per-vendor code path.
+ */
+import OpenAI from "openai";
+import { OpenAIChatModel } from "./openai.js";
+import { transportRetries } from "./types.js";
+/** Public endpoint of the OrcaRouter AI gateway. */
+export const DEFAULT_ORCAROUTER_BASE_URL = "https://api.orcarouter.ai/v1";
+/**
+ * ChatModel backed by the OrcaRouter gateway. Inherits every translation detail
+ * from {@link OpenAIChatModel} (the gateway is OpenAI-compatible) and only
+ * changes the defaults: the gateway base URL and an `orcarouter:<model>` label.
+ */
+export class OrcaRouterChatModel extends OpenAIChatModel {
+    constructor(opts) {
+        super({
+            ...opts,
+            baseUrl: opts.baseUrl ?? DEFAULT_ORCAROUTER_BASE_URL,
+            label: opts.label ?? `orcarouter:${opts.model}`,
+        });
+    }
+}
+/**
+ * Auto-discover the models the OrcaRouter gateway can route to via `GET
+ * /v1/models`. Returns the model ids so a caller can present/validate them
+ * instead of hardcoding a model string. A stub `client` may be injected for tests.
+ */
+export async function listOrcaRouterModels(opts) {
+    const client = opts.client ??
+        new OpenAI({
+            apiKey: opts.apiKey,
+            baseURL: opts.baseUrl ?? DEFAULT_ORCAROUTER_BASE_URL,
+            maxRetries: transportRetries(),
+        });
+    const res = await client.models.list();
+    return res.data.map((m) => m.id);
+}
+//# sourceMappingURL=orcarouter.js.map

package/dist/ai/llm/orcarouter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orcarouter.js","sourceRoot":"","sources":["../../../src/ai/llm/orcarouter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,MAAM,MAAM,QAAQ,CAAC;AAC5B,OAAO,EAAE,eAAe,EAA+B,MAAM,aAAa,CAAC;AAC3E,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE9C,oDAAoD;AACpD,MAAM,CAAC,MAAM,2BAA2B,GAAG,8BAA8B,CAAC;AAI1E;;;;GAIG;AACH,MAAM,OAAO,mBAAoB,SAAQ,eAAe;IACtD,YAAY,IAAgC;QAC1C,KAAK,CAAC;YACJ,GAAG,IAAI;YACP,OAAO,EAAE,IAAI,CAAC,OAAO,IAAI,2BAA2B;YACpD,KAAK,EAAE,IAAI,CAAC,KAAK,IAAI,cAAc,IAAI,CAAC,KAAK,EAAE;SAChD,CAAC,CAAC;IACL,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,IAI1C;IACC,MAAM,MAAM,GACV,IAAI,CAAC,MAAM;QACX,IAAI,MAAM,CAAC;YACT,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,OAAO,EAAE,IAAI,CAAC,OAAO,IAAI,2BAA2B;YACpD,UAAU,EAAE,gBAAgB,EAAE;SAC/B,CAAC,CAAC;IACL,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IACvC,OAAO,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;AACnC,CAAC"}

package/dist/ai/llm/recover-tool.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Recover a forced-tool payload from assistant `content` when a gateway ignored
+ * `tool_choice` and wrote JSON text instead of `tool_calls` (#129).
+ *
+ * Conservative: only succeeds when `text` parses as JSON matching one of:
+ *   - `[{ name, parameters|arguments|args }]`
+ *   - `{ name, parameters|arguments|args }`
+ *   - a fenced ```json block wrapping either
+ *   - a bare object whose `payloadKey` is an array
+ * Anything else (prose, truncated JSON, a guessed shape) returns undefined.
+ * Callers MUST run the same schema validation they use for real tool calls.
+ */
+/** Leading/trailing ```json fence, linear in `raw.length` — no quantified-whitespace regex. */
+export declare function unwrapMarkdownFence(raw: string): string;
+export declare function recoverToolArgsFromContent(text: string, opts: {
+    toolNames: readonly string[];
+    payloadKey: string;
+}): Record<string, unknown> | undefined;
+/** One stderr line when a structured op got neither a tool call nor recoverable JSON. */
+export declare function warnToolChoiceIgnored(op: string, reason: "empty" | "unparsed"): void;
+//# sourceMappingURL=recover-tool.d.ts.map

package/dist/ai/llm/recover-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recover-tool.d.ts","sourceRoot":"","sources":["../../../src/ai/llm/recover-tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,+FAA+F;AAC/F,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CASvD;AAED,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE;IAAE,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GACzD,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAiErC;AAED,yFAAyF;AACzF,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,UAAU,GAAG,IAAI,CAMpF"}

package/dist/ai/llm/recover-tool.js

@@ -0,0 +1,109 @@
+/**
+ * Recover a forced-tool payload from assistant `content` when a gateway ignored
+ * `tool_choice` and wrote JSON text instead of `tool_calls` (#129).
+ *
+ * Conservative: only succeeds when `text` parses as JSON matching one of:
+ *   - `[{ name, parameters|arguments|args }]`
+ *   - `{ name, parameters|arguments|args }`
+ *   - a fenced ```json block wrapping either
+ *   - a bare object whose `payloadKey` is an array
+ * Anything else (prose, truncated JSON, a guessed shape) returns undefined.
+ * Callers MUST run the same schema validation they use for real tool calls.
+ */
+/** Leading/trailing ```json fence, linear in `raw.length` — no quantified-whitespace regex. */
+export function unwrapMarkdownFence(raw) {
+    let s = raw;
+    if (s.startsWith("```")) {
+        s = s.slice(3);
+        if (s.length >= 4 && s.slice(0, 4).toLowerCase() === "json")
+            s = s.slice(4);
+        s = s.trimStart();
+    }
+    if (s.endsWith("```"))
+        s = s.slice(0, -3).trimEnd();
+    return s.trim();
+}
+export function recoverToolArgsFromContent(text, opts) {
+    const raw = text?.trim();
+    if (!raw)
+        return undefined;
+    const stripped = unwrapMarkdownFence(raw);
+    const accepted = new Set(opts.toolNames);
+    const asPayload = (value) => {
+        if (!value || typeof value !== "object")
+            return undefined;
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                const hit = asPayload(item);
+                if (hit)
+                    return hit;
+            }
+            return undefined;
+        }
+        const obj = value;
+        const wrapped = typeof obj.name === "string" || "parameters" in obj || "arguments" in obj || "args" in obj;
+        if (wrapped) {
+            const name = typeof obj.name === "string" ? obj.name : "";
+            if (name && !accepted.has(name))
+                return undefined;
+            let params = obj.parameters ?? obj.arguments ?? obj.args;
+            if (typeof params === "string") {
+                try {
+                    params = JSON.parse(params);
+                }
+                catch {
+                    return undefined;
+                }
+            }
+            const hit = asPayload(params);
+            if (hit)
+                return hit;
+            // `{ name, nodes: [...] }` — payload at the same level as the wrapper.
+            if (Array.isArray(obj[opts.payloadKey]))
+                return obj;
+            return undefined;
+        }
+        if (Array.isArray(obj[opts.payloadKey]))
+            return obj;
+        return undefined;
+    };
+    try {
+        const hit = asPayload(JSON.parse(stripped));
+        if (hit)
+            return hit;
+    }
+    catch {
+        /* try a bracket slice below */
+    }
+    const objStart = stripped.indexOf("{");
+    const objEnd = stripped.lastIndexOf("}");
+    if (objStart >= 0 && objEnd > objStart) {
+        try {
+            const hit = asPayload(JSON.parse(stripped.slice(objStart, objEnd + 1)));
+            if (hit)
+                return hit;
+        }
+        catch {
+            /* try array slice */
+        }
+    }
+    const arrStart = stripped.indexOf("[");
+    const arrEnd = stripped.lastIndexOf("]");
+    if (arrStart >= 0 && arrEnd > arrStart) {
+        try {
+            return asPayload(JSON.parse(stripped.slice(arrStart, arrEnd + 1)));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}
+/** One stderr line when a structured op got neither a tool call nor recoverable JSON. */
+export function warnToolChoiceIgnored(op, reason) {
+    const detail = reason === "empty"
+        ? "model returned no tool call and no content (provider may ignore forced tool_choice)"
+        : "model did not honor tool_choice and content is not parseable tool-call JSON";
+    console.error(`⚠ ${op}: ${detail} — this batch is empty`);
+}
+//# sourceMappingURL=recover-tool.js.map

package/dist/ai/llm/recover-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recover-tool.js","sourceRoot":"","sources":["../../../src/ai/llm/recover-tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,+FAA+F;AAC/F,MAAM,UAAU,mBAAmB,CAAC,GAAW;IAC7C,IAAI,CAAC,GAAG,GAAG,CAAC;IACZ,IAAI,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QACxB,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QACf,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,KAAK,MAAM;YAAE,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAC5E,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,CAAC;IACpB,CAAC;IACD,IAAI,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;IACpD,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,0BAA0B,CACxC,IAAY,EACZ,IAA0D;IAE1D,MAAM,GAAG,GAAG,IAAI,EAAE,IAAI,EAAE,CAAC;IACzB,IAAI,CAAC,GAAG;QAAE,OAAO,SAAS,CAAC;IAC3B,MAAM,QAAQ,GAAG,mBAAmB,CAAC,GAAG,CAAC,CAAC;IAC1C,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAEzC,MAAM,SAAS,GAAG,CAAC,KAAc,EAAuC,EAAE;QACxE,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;QAC1D,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACzB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACzB,MAAM,GAAG,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;gBAC5B,IAAI,GAAG;oBAAE,OAAO,GAAG,CAAC;YACtB,CAAC;YACD,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,MAAM,GAAG,GAAG,KAAgC,CAAC;QAC7C,MAAM,OAAO,GACX,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,IAAI,YAAY,IAAI,GAAG,IAAI,WAAW,IAAI,GAAG,IAAI,MAAM,IAAI,GAAG,CAAC;QAC7F,IAAI,OAAO,EAAE,CAAC;YACZ,MAAM,IAAI,GAAG,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;YAC1D,IAAI,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC;gBAAE,OAAO,SAAS,CAAC;YAClD,IAAI,MAAM,GAAY,GAAG,CAAC,UAAU,IAAI,GAAG,CAAC,SAAS,IAAI,GAAG,CAAC,IAAI,CAAC;YAClE,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;gBAC/B,IAAI,CAAC;oBACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;gBAC9B,CAAC;gBAAC,MAAM,CAAC;oBACP,OAAO,SAAS,CAAC;gBACnB,CAAC;YACH,CAAC;YACD,MAAM,GAAG,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;YAC9B,IAAI,GAAG;gBAAE,OAAO,GAAG,CAAC;YACpB,uEAAuE;YACvE,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;gBAAE,OAAO,GAAG,CAAC;YACpD,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YAAE,OAAO,GAAG,CAAC;QACpD,OAAO,SAAS,CAAC;IACnB,CAAC,CAAC;IAEF,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC;QAC5C,IAAI,GAAG;YAAE,OAAO,GAAG,CAAC;IACtB,CAAC;IAAC,MAAM,CAAC;QACP,+BAA+B;IACjC,CAAC;IACD,MAAM,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACvC,MAAM,MAAM,GAAG,QAAQ,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACzC,IAAI,QAAQ,IAAI,CAAC,IAAI,MAAM,GAAG,QAAQ,EAAE,CAAC;QACvC,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;YACxE,IAAI,GAAG;gBAAE,OAAO,GAAG,CAAC;QACtB,CAAC;QAAC,MAAM,CAAC;YACP,qBAAqB;QACvB,CAAC;IACH,CAAC;IACD,MAAM,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACvC,MAAM,MAAM,GAAG,QAAQ,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACzC,IAAI,QAAQ,IAAI,CAAC,IAAI,MAAM,GAAG,QAAQ,EAAE,CAAC;QACvC,IAAI,CAAC;YACH,OAAO,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QACrE,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,qBAAqB,CAAC,EAAU,EAAE,MAA4B;IAC5E,MAAM,MAAM,GACV,MAAM,KAAK,OAAO;QAChB,CAAC,CAAC,qFAAqF;QACvF,CAAC,CAAC,6EAA6E,CAAC;IACpF,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,MAAM,wBAAwB,CAAC,CAAC;AAC5D,CAAC"}

package/dist/ai/llm/types.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Provider-neutral chat transport.
+ *
+ * Every LLM call in graft — the engine's single-shot summarize/synthesize/crux
+ * ops, and any multi-turn tool-use loop built on top — goes through one interface,
+ * {@link ChatModel}. Adapters translate this neutral shape to a concrete SDK
+ * (OpenAI-compatible or native Anthropic). Nothing above this layer knows which
+ * provider is in play, so adding a provider is a new adapter, never a change to
+ * a call site.
+ *
+ * The design carries three affordances that let a single interface serve the
+ * multi-turn loop as cleanly as a one-shot call:
+ *   - {@link ChatResponse.assistant} — a ready-to-append assistant message, so a
+ *     caller continues a conversation without touching provider shapes.
+ *   - {@link Message.providerRaw} — opaque verbatim replay of a message the same
+ *     adapter produced (preserves Anthropic thinking-block signatures, which must
+ *     be echoed back unchanged).
+ *   - {@link Usage} normalized to uncached-input, so token accounting is identical
+ *     across providers.
+ */
+/** A single tool invocation requested by the model. `args` is ALREADY parsed. */
+export interface ToolCall {
+    id: string;
+    name: string;
+    /** Parsed argument object. Adapters (de)serialize to their wire format. */
+    args: unknown;
+}
+/** One turn in a conversation, in provider-neutral form. */
+export interface Message {
+    role: "system" | "user" | "assistant" | "tool";
+    /** Plain-text content. Empty string when a turn is purely tool calls/results. */
+    content: string;
+    /** Assistant turns only: tool calls the model asked for. */
+    toolCalls?: ToolCall[];
+    /** Tool turns only: the id of the {@link ToolCall} this result answers. */
+    toolCallId?: string;
+    /**
+     * Request a provider cache marker (`cache_control: ephemeral`) on THIS message.
+     * The transport only understands this per-message flag; any sliding/rotation
+     * policy lives in the caller.
+     */
+    cacheBreakpoint?: boolean;
+    /**
+     * Opaque, provider-tagged payload from the adapter that produced this message.
+     * When the SAME adapter replays it, the original wire form is sent verbatim
+     * (preserving e.g. Anthropic thinking blocks + signatures). A different adapter
+     * ignores it and reconstructs from {@link content}/{@link toolCalls}.
+     */
+    providerRaw?: {
+        provider: string;
+        raw: unknown;
+    };
+}
+/** A tool the model may call. `parameters` is a JSON Schema object. */
+export interface ToolSpec {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}
+/**
+ * How the model must shape its reply:
+ *   - `text`  — free-form assistant text.
+ *   - `json`  — a JSON object (mapped to a forced synthetic tool on both providers,
+ *               since that is the one structured-output mechanism they share).
+ *   - `tool`  — force a call to the named tool (structured output with a schema).
+ */
+export type ResponseFormat = {
+    kind: "text";
+} | {
+    kind: "json";
+} | {
+    kind: "tool";
+    name: string;
+};
+/**
+ * Token accounting, normalized across providers. `input` is UNCACHED input only
+ * (OpenAI reports cached tokens inside `prompt_tokens`; Anthropic reports them
+ * separately — adapters reconcile so callers can sum these directly).
+ */
+export interface Usage {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheCreate: number;
+}
+export interface ChatRequest {
+    messages: Message[];
+    tools?: ToolSpec[];
+    /** Default: `{ kind: "text" }`. */
+    responseFormat?: ResponseFormat;
+    /** Providers that reject it (current Anthropic models) drop it in the adapter. */
+    temperature?: number;
+    /** Max output tokens. Required by Anthropic; adapters supply a default. */
+    maxTokens?: number;
+}
+export interface ChatResponse {
+    /** Concatenated assistant text (empty when the turn only made tool calls). */
+    text: string;
+    toolCalls: ToolCall[];
+    usage: Usage;
+    stopReason: string | null;
+    /** The assistant turn as a neutral message — push straight back into `messages`. */
+    assistant: Message;
+}
+/**
+ * A configured connection to one model. `label` is a stable `<provider>:<model>`
+ * string recorded in the graph manifest.
+ */
+export interface ChatModel {
+    readonly label: string;
+    create(req: ChatRequest): Promise<ChatResponse>;
+}
+/**
+ * How many times the transport retries a failed request before the error reaches
+ * the caller. Both SDKs retry only what is worth retrying (429 and 5xx, honouring
+ * `Retry-After`) with exponential backoff, so this is the knob that separates a
+ * transient rate limit from a real failure — #127 lost whole files to the first
+ * 429 a shared gateway threw. Env-overridable because a metered corporate gateway
+ * may want fewer, and a flaky local proxy more.
+ */
+export declare function transportRetries(): number;
+//# sourceMappingURL=types.d.ts.map

package/dist/ai/llm/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/ai/llm/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,iFAAiF;AACjF,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,IAAI,EAAE,OAAO,CAAC;CACf;AAED,4DAA4D;AAC5D,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC;IAC/C,iFAAiF;IACjF,OAAO,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAC;IACvB,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;;OAKG;IACH,WAAW,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,OAAO,CAAA;KAAE,CAAC;CAClD;AAED,uEAAuE;AACvE,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnC;;;;GAIG;AACH,MAAM,WAAW,KAAK;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,KAAK,CAAC,EAAE,QAAQ,EAAE,CAAC;IACnB,mCAAmC;IACnC,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,kFAAkF;IAClF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,KAAK,EAAE,KAAK,CAAC;IACb,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,oFAAoF;IACpF,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CACjD;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAGzC"}

package/dist/ai/llm/types.js

@@ -0,0 +1,33 @@
+/**
+ * Provider-neutral chat transport.
+ *
+ * Every LLM call in graft — the engine's single-shot summarize/synthesize/crux
+ * ops, and any multi-turn tool-use loop built on top — goes through one interface,
+ * {@link ChatModel}. Adapters translate this neutral shape to a concrete SDK
+ * (OpenAI-compatible or native Anthropic). Nothing above this layer knows which
+ * provider is in play, so adding a provider is a new adapter, never a change to
+ * a call site.
+ *
+ * The design carries three affordances that let a single interface serve the
+ * multi-turn loop as cleanly as a one-shot call:
+ *   - {@link ChatResponse.assistant} — a ready-to-append assistant message, so a
+ *     caller continues a conversation without touching provider shapes.
+ *   - {@link Message.providerRaw} — opaque verbatim replay of a message the same
+ *     adapter produced (preserves Anthropic thinking-block signatures, which must
+ *     be echoed back unchanged).
+ *   - {@link Usage} normalized to uncached-input, so token accounting is identical
+ *     across providers.
+ */
+/**
+ * How many times the transport retries a failed request before the error reaches
+ * the caller. Both SDKs retry only what is worth retrying (429 and 5xx, honouring
+ * `Retry-After`) with exponential backoff, so this is the knob that separates a
+ * transient rate limit from a real failure — #127 lost whole files to the first
+ * 429 a shared gateway threw. Env-overridable because a metered corporate gateway
+ * may want fewer, and a flaky local proxy more.
+ */
+export function transportRetries() {
+    const raw = Number(process.env.GRAFT_LLM_RETRIES);
+    return Number.isFinite(raw) && raw >= 0 ? Math.floor(raw) : 4;
+}
+//# sourceMappingURL=types.js.map

package/dist/ai/llm/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/ai/llm/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AA+FH;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB;IAC9B,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IAClD,OAAO,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAChE,CAAC"}

package/dist/ai/providers.d.ts

@@ -0,0 +1,59 @@
+import type { Summarizer } from "./summarize.js";
+import type { Synthesizer } from "./synthesize.js";
+import type { CruxSummarizer } from "./crux.js";
+import type { ChatModel } from "./llm/types.js";
+import type { ProviderKind } from "./llm/factory.js";
+/**
+ * User-facing configuration. Anything omitted falls back to environment
+ * variables and then to sensible defaults.
+ *
+ * graft is vendor-neutral: `provider` names only the WIRE FORMAT, not a company.
+ * `openai` speaks the OpenAI-compatible API — point `baseUrl` at OpenRouter,
+ * Fireworks, a LiteLLM proxy, Groq, a local server, or OpenAI itself, and pass
+ * your own key. `anthropic` speaks the native Messages API. Any LLM-backed
+ * operation needs an API key.
+ */
+export interface EngineConfig {
+    /** Where the graph lives. Env: GRAFT_DIR. Default: `<repo>/.context`. */
+    contextDir?: string;
+    /** Wire format / SDK. Env: GRAFT_PROVIDER. Default: `openai`. */
+    provider?: ProviderKind;
+    /** API key for the chosen provider. Env: GRAFT_API_KEY (legacy: OPENROUTER_API_KEY). */
+    apiKey?: string;
+    /** Model id. Env: GRAFT_MODEL. Provider-specific default. */
+    model?: string;
+    /** Base URL for OpenAI-compatible endpoints. Env: GRAFT_BASE_URL. */
+    baseUrl?: string;
+    /** Override the whole transport (skips provider/apiKey/baseUrl). */
+    chatModel?: ChatModel;
+    /** Override the synthesizer. */
+    synthesizer?: Synthesizer;
+    /** Override the code summarizer. */
+    summarizer?: Summarizer;
+    /** Override the per-symbol crux summarizer. */
+    cruxSummarizer?: CruxSummarizer;
+}
+/** Fully-resolved configuration with all defaults applied. */
+export interface ResolvedConfig {
+    contextDir?: string;
+    provider: ProviderKind;
+    apiKey?: string;
+    model: string;
+    baseUrl?: string;
+    headers?: Record<string, string>;
+    /** True when the key came from the deprecated OPENROUTER_* fallback. */
+    usedLegacyEnv: boolean;
+    chatModel?: ChatModel;
+    synthesizer?: Synthesizer;
+    summarizer?: Summarizer;
+    cruxSummarizer?: CruxSummarizer;
+}
+/** Per-provider default model. */
+export declare const DEFAULT_MODELS: Record<ProviderKind, string>;
+export declare const DEFAULTS: {
+    readonly provider: ProviderKind;
+    readonly model: string;
+};
+/** Merge user config with environment variables and defaults. */
+export declare function resolveConfig(config?: EngineConfig): ResolvedConfig;
+//# sourceMappingURL=providers.d.ts.map

package/dist/ai/providers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.d.ts","sourceRoot":"","sources":["../../src/ai/providers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY;IAC3B,yEAAyE;IACzE,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,wFAAwF;IACxF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC;IAGjB,oEAAoE;IACpE,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,gCAAgC;IAChC,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,oCAAoC;IACpC,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,+CAA+C;IAC/C,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAED,8DAA8D;AAC9D,MAAM,WAAW,cAAc;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,YAAY,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,wEAAwE;IACxE,aAAa,EAAE,OAAO,CAAC;IACvB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAKD,kCAAkC;AAClC,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,YAAY,EAAE,MAAM,CAOvD,CAAC;AAEF,eAAO,MAAM,QAAQ;uBACG,YAAY;;CAE1B,CAAC;AAEX,iEAAiE;AACjE,wBAAgB,aAAa,CAAC,MAAM,GAAE,YAAiB,GAAG,cAAc,CAyCvE"}

package/dist/ai/providers.js

@@ -0,0 +1,54 @@
+const OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1";
+const ORCAROUTER_BASE_URL = "https://api.orcarouter.ai/v1";
+/** Per-provider default model. */
+export const DEFAULT_MODELS = {
+    openai: "openai/gpt-4o-mini",
+    anthropic: "claude-sonnet-5",
+    // Provider-prefixed so the LiteLLM proxy routes it; override with GRAFT_MODEL.
+    litellm: "openai/gpt-4o-mini",
+    // Provider-prefixed so the OrcaRouter gateway routes it; override with GRAFT_MODEL.
+    orcarouter: "openai/gpt-4o-mini",
+};
+export const DEFAULTS = {
+    provider: "openai",
+    model: DEFAULT_MODELS.openai,
+};
+/** Merge user config with environment variables and defaults. */
+export function resolveConfig(config = {}) {
+    const env = process.env;
+    const provider = config.provider ?? env.GRAFT_PROVIDER ?? DEFAULTS.provider;
+    const explicitKey = config.apiKey ?? env.GRAFT_API_KEY;
+    const legacyKey = env.OPENROUTER_API_KEY;
+    const apiKey = explicitKey ?? legacyKey ?? env.ORCAROUTER_API_KEY;
+    const usedLegacyEnv = !explicitKey && !!legacyKey;
+    const model = config.model ??
+        env.GRAFT_MODEL ??
+        env.GRAFT_OPENROUTER_MODEL ??
+        env.ORCAROUTER_MODEL ??
+        DEFAULT_MODELS[provider];
+    let baseUrl = config.baseUrl ?? env.GRAFT_BASE_URL ?? env.OPENROUTER_BASE_URL ?? env.ORCAROUTER_BASE_URL;
+    // Back-compat: an existing setup with only OPENROUTER_API_KEY keeps hitting
+    // OpenRouter without any config change.
+    if (!baseUrl && provider === "openai" && usedLegacyEnv)
+        baseUrl = OPENROUTER_BASE_URL;
+    // The orcarouter provider points at the gateway unless a base URL is given.
+    if (!baseUrl && provider === "orcarouter")
+        baseUrl = ORCAROUTER_BASE_URL;
+    const headers = provider === "openai" && baseUrl?.includes("openrouter.ai")
+        ? { "X-Title": "graft" }
+        : undefined;
+    return {
+        contextDir: config.contextDir ?? env.GRAFT_DIR,
+        provider,
+        apiKey,
+        model,
+        baseUrl,
+        headers,
+        usedLegacyEnv,
+        chatModel: config.chatModel,
+        synthesizer: config.synthesizer,
+        summarizer: config.summarizer,
+        cruxSummarizer: config.cruxSummarizer,
+    };
+}
+//# sourceMappingURL=providers.js.map

package/dist/ai/providers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.js","sourceRoot":"","sources":["../../src/ai/providers.ts"],"names":[],"mappings":"AAwDA,MAAM,mBAAmB,GAAG,8BAA8B,CAAC;AAC3D,MAAM,mBAAmB,GAAG,8BAA8B,CAAC;AAE3D,kCAAkC;AAClC,MAAM,CAAC,MAAM,cAAc,GAAiC;IAC1D,MAAM,EAAE,oBAAoB;IAC5B,SAAS,EAAE,iBAAiB;IAC5B,+EAA+E;IAC/E,OAAO,EAAE,oBAAoB;IAC7B,oFAAoF;IACpF,UAAU,EAAE,oBAAoB;CACjC,CAAC;AAEF,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,QAAQ,EAAE,QAAwB;IAClC,KAAK,EAAE,cAAc,CAAC,MAAM;CACpB,CAAC;AAEX,iEAAiE;AACjE,MAAM,UAAU,aAAa,CAAC,SAAuB,EAAE;IACrD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;IACxB,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,IAAK,GAAG,CAAC,cAA2C,IAAI,QAAQ,CAAC,QAAQ,CAAC;IAE1G,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,aAAa,CAAC;IACvD,MAAM,SAAS,GAAG,GAAG,CAAC,kBAAkB,CAAC;IACzC,MAAM,MAAM,GAAG,WAAW,IAAI,SAAS,IAAI,GAAG,CAAC,kBAAkB,CAAC;IAClE,MAAM,aAAa,GAAG,CAAC,WAAW,IAAI,CAAC,CAAC,SAAS,CAAC;IAElD,MAAM,KAAK,GACT,MAAM,CAAC,KAAK;QACZ,GAAG,CAAC,WAAW;QACf,GAAG,CAAC,sBAAsB;QAC1B,GAAG,CAAC,gBAAgB;QACpB,cAAc,CAAC,QAAQ,CAAC,CAAC;IAE3B,IAAI,OAAO,GAAG,MAAM,CAAC,OAAO,IAAI,GAAG,CAAC,cAAc,IAAI,GAAG,CAAC,mBAAmB,IAAI,GAAG,CAAC,mBAAmB,CAAC;IACzG,4EAA4E;IAC5E,wCAAwC;IACxC,IAAI,CAAC,OAAO,IAAI,QAAQ,KAAK,QAAQ,IAAI,aAAa;QAAE,OAAO,GAAG,mBAAmB,CAAC;IACtF,4EAA4E;IAC5E,IAAI,CAAC,OAAO,IAAI,QAAQ,KAAK,YAAY;QAAE,OAAO,GAAG,mBAAmB,CAAC;IAEzE,MAAM,OAAO,GACX,QAAQ,KAAK,QAAQ,IAAI,OAAO,EAAE,QAAQ,CAAC,eAAe,CAAC;QACzD,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,EAAE;QACxB,CAAC,CAAC,SAAS,CAAC;IAEhB,OAAO;QACL,UAAU,EAAE,MAAM,CAAC,UAAU,IAAI,GAAG,CAAC,SAAS;QAC9C,QAAQ;QACR,MAAM;QACN,KAAK;QACL,OAAO;QACP,OAAO;QACP,aAAa;QACb,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,cAAc,EAAE,MAAM,CAAC,cAAc;KACtC,CAAC;AACJ,CAAC"}

package/dist/ai/summarize.d.ts

@@ -0,0 +1,25 @@
+import type { ChatModel } from "./llm/types.js";
+/**
+ * Turns one source-code file into a short prose summary for the knowledge graph.
+ *
+ * Code repos are deliberately NOT fed through the per-chunk entity extractor:
+ * static structure is better served by grep/tree-sitter in the consuming agent,
+ * and LLM extraction over raw code produces noisy, duplicated entities. Instead
+ * the repo ingest path summarizes each file into plain English (purpose, key
+ * exports, dependencies, design decisions) and ingests those summaries — prose
+ * the existing extraction pipeline is actually good at.
+ */
+export interface Summarizer {
+    summarize(code: string, opts: {
+        path: string;
+    }): Promise<string>;
+}
+/** Summarizer backed by any {@link ChatModel} (a plain-text completion). */
+export declare class ChatSummarizer implements Summarizer {
+    private model;
+    constructor(model: ChatModel);
+    summarize(code: string, opts: {
+        path: string;
+    }): Promise<string>;
+}
+//# sourceMappingURL=summarize.d.ts.map

package/dist/ai/summarize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"summarize.d.ts","sourceRoot":"","sources":["../../src/ai/summarize.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD;;;;;;;;;GASG;AACH,MAAM,WAAW,UAAU;IACzB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAClE;AAqBD,4EAA4E;AAC5E,qBAAa,cAAe,YAAW,UAAU;IACnC,OAAO,CAAC,KAAK;gBAAL,KAAK,EAAE,SAAS;IAE9B,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC;CAWvE"}

package/dist/ai/summarize.js

@@ -0,0 +1,34 @@
+const SYSTEM_PROMPT = `You document source code for a team knowledge base. Given one source file, write a compact plain-English summary covering:
+1. The purpose of the file — what it exists to do.
+2. The key exported functions/classes/types and what each is for.
+3. Important dependencies: internal modules it builds on, external libraries or services it talks to.
+4. Notable design decisions, constraints, or gotchas evident in the code.
+
+Write 3-8 sentences of flowing prose. Name concrete identifiers (modules, classes, services) so they can become graph entities. No code blocks, no line-by-line narration, no filler.`;
+/** Cap the code sent per file so a single giant file can't blow the context. */
+const MAX_CODE_CHARS = 24_000;
+function userContent(code, path) {
+    const clipped = code.length > MAX_CODE_CHARS
+        ? `${code.slice(0, MAX_CODE_CHARS)}\n… (truncated at ${MAX_CODE_CHARS} characters)`
+        : code;
+    return `File: ${path}\n\n${clipped}`;
+}
+/** Summarizer backed by any {@link ChatModel} (a plain-text completion). */
+export class ChatSummarizer {
+    model;
+    constructor(model) {
+        this.model = model;
+    }
+    async summarize(code, opts) {
+        const res = await this.model.create({
+            temperature: 0,
+            maxTokens: 2048,
+            messages: [
+                { role: "system", content: SYSTEM_PROMPT },
+                { role: "user", content: userContent(code, opts.path) },
+            ],
+        });
+        return res.text.trim();
+    }
+}
+//# sourceMappingURL=summarize.js.map

package/dist/ai/summarize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"summarize.js","sourceRoot":"","sources":["../../src/ai/summarize.ts"],"names":[],"mappings":"AAgBA,MAAM,aAAa,GAAG;;;;;;sLAMgK,CAAC;AAEvL,gFAAgF;AAChF,MAAM,cAAc,GAAG,MAAM,CAAC;AAE9B,SAAS,WAAW,CAAC,IAAY,EAAE,IAAY;IAC7C,MAAM,OAAO,GACX,IAAI,CAAC,MAAM,GAAG,cAAc;QAC1B,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,cAAc,CAAC,qBAAqB,cAAc,cAAc;QACnF,CAAC,CAAC,IAAI,CAAC;IACX,OAAO,SAAS,IAAI,OAAO,OAAO,EAAE,CAAC;AACvC,CAAC;AAED,4EAA4E;AAC5E,MAAM,OAAO,cAAc;IACL;IAApB,YAAoB,KAAgB;QAAhB,UAAK,GAAL,KAAK,CAAW;IAAG,CAAC;IAExC,KAAK,CAAC,SAAS,CAAC,IAAY,EAAE,IAAsB;QAClD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;YAClC,WAAW,EAAE,CAAC;YACd,SAAS,EAAE,IAAI;YACf,QAAQ,EAAE;gBACR,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,aAAa,EAAE;gBAC1C,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE;aACxD;SACF,CAAC,CAAC;QACH,OAAO,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;IACzB,CAAC;CACF"}

package/dist/ai/synthesize.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The synthesis step: turn per-file prose summaries into a CURATED set of graph
+ * nodes. This is where granularity is decided — the model groups related files
+ * into subsystem nodes, keeps a notable file as its own node when it deserves
+ * one, and adds cross-cutting concept nodes, instead of emitting one entity per
+ * incidental identifier. Each node is attributed to the source files it is
+ * grounded in, so provenance (and staleness) stays exact.
+ */
+import type { ChatModel } from "./llm/types.js";
+/** A directed edge to another node, by node name (resolved to a slug later). */
+export interface SynthLink {
+    to: string;
+    relation: string;
+    description?: string;
+}
+/** A node as proposed by the synthesizer, before it is written to disk. */
+export interface SynthNode {
+    name: string;
+    /** system | api | file | concept */
+    type: string;
+    summary: string;
+    /** Source file paths (from the provided set) this node is grounded in. */
+    sources: string[];
+    links: SynthLink[];
+}
+/** One labeled file summary fed into synthesis. */
+export interface FileSummary {
+    path: string;
+    summary: string;
+}
+export interface Synthesizer {
+    synthesize(files: FileSummary[]): Promise<SynthNode[]>;
+}
+/** Synthesizer backed by any {@link ChatModel} via forced tool calling. */
+export declare class ChatSynthesizer implements Synthesizer {
+    private model;
+    constructor(model: ChatModel);
+    synthesize(files: FileSummary[]): Promise<SynthNode[]>;
+}
+//# sourceMappingURL=synthesize.d.ts.map

package/dist/ai/synthesize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"synthesize.d.ts","sourceRoot":"","sources":["../../src/ai/synthesize.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAGhD,gFAAgF;AAChF,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,2EAA2E;AAC3E,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,EAAE,SAAS,EAAE,CAAC;CACpB;AAED,mDAAmD;AACnD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,UAAU,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;CACxD;AAmLD,2EAA2E;AAC3E,qBAAa,eAAgB,YAAW,WAAW;IACrC,OAAO,CAAC,KAAK;gBAAL,KAAK,EAAE,SAAS;IAE9B,UAAU,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;CAyB7D"}