patchwork-os 0.2.0-beta.9.canary.93 → 1.1.0-beta.1

package/dist/drivers/openai/index.js

@@ -1,3 +1,4 @@
+import { truncateToBytes, truncateUtf8Bytes } from "../outputCap.js";
 const OUTPUT_CAP = 50 * 1024;
 /**
  * OpenAI API driver — streams via chat.completions.create.
@@ -43,6 +44,16 @@ export class OpenAIApiDriver {
         const opts = input.providerOptions ?? {};
         const maxTokens = typeof opts.maxTokens === "number" ? opts.maxTokens : 4096;
         const temperature = typeof opts.temperature === "number" ? opts.temperature : undefined;
+        // Structured-output passthrough (audit 2026-06-09): when a caller sets
+        // providerOptions.responseFormat (e.g. { type: "json_object" } or
+        // { type: "json_schema", json_schema: {...} }), forward it to the API so
+        // OpenAI-compatible servers that support constrained decoding (vLLM/XGrammar,
+        // llama.cpp, LM Studio) enforce valid structured output at the token level.
+        // Endpoints that don't support it simply ignore the field. Foundation for
+        // hardening the judge→refine verdict JSON on local models.
+        const responseFormat = opts.responseFormat && typeof opts.responseFormat === "object"
+            ? opts.responseFormat
+            : undefined;
         const contextNote = input.contextFiles && input.contextFiles.length > 0
             ? `\n\n--- BEGIN CONTEXT FILE LIST ---\n${input.contextFiles
                 .map((f) => f.slice(0, 500).replace(/[\x00-\x1f\x7f]/g, ""))
@@ -65,7 +76,10 @@ export class OpenAIApiDriver {
         const model = input.model ?? this.opts.defaultModel ?? "gpt-4o";
         this.log(`[${this.name}] streaming: model=${model} workspace=${input.workspace}`);
         let text = "";
+        let outputBytesSent = 0;
         let firstChunkAt;
+        let promptTokens;
+        let completionTokens;
         try {
             // biome-ignore lint/suspicious/noExplicitAny: dynamic import shape
             const stream = await client.chat.completions.create({
@@ -74,21 +88,60 @@ export class OpenAIApiDriver {
                 ...(temperature !== undefined ? { temperature } : {}),
                 messages,
                 stream: true,
+                ...(responseFormat ? { response_format: responseFormat } : {}),
+                // Ask the API to emit a final usage chunk (prompt/completion token
+                // counts) so RunBudget can enforce a real token/USD budget instead
+                // of failing open. Compliant OpenAI-style endpoints return it; an
+                // endpoint that ignores the option simply omits usage and we fail
+                // open (providerMeta carries no tokens).
+                stream_options: { include_usage: true },
             }, { signal: input.signal });
             // biome-ignore lint/suspicious/noExplicitAny: stream shape from dynamic import
             for await (const chunk of stream) {
+                // The include_usage final chunk carries an empty `choices` array and a
+                // `usage` object; capture it whenever present (so it works even if an
+                // endpoint attaches usage to a content-bearing chunk).
+                if (chunk.usage) {
+                    if (typeof chunk.usage.prompt_tokens === "number")
+                        promptTokens = chunk.usage.prompt_tokens;
+                    if (typeof chunk.usage.completion_tokens === "number")
+                        completionTokens = chunk.usage.completion_tokens;
+                }
                 const delta = chunk.choices?.[0]?.delta?.content ?? "";
                 if (delta) {
                     if (firstChunkAt === undefined)
                         firstChunkAt = Date.now();
-                    if (text.length < OUTPUT_CAP) {
+                    if (outputBytesSent < OUTPUT_CAP) {
                         // Cap accumulation in-loop to bound memory under runaway streams
                         // (e.g. local LLMs that loop). Once we hit the cap, stop appending
                         // and abort the upstream stream so sockets and decoder buffers
-                        // are released. onChunk is gated by the same cap so partial
-                        // listeners stop receiving deltas.
-                        text += delta;
-                        input.onChunk?.(delta);
+                        // are released.
+                        //
+                        // LOW #19 audit 2026-06-03: use truncateToBytes so the chunk sent
+                        // to onChunk is always the SAME bytes as what lands in result.text.
+                        // The previous pattern appended the full `delta` to `text` then
+                        // called `onChunk(delta)`, but `truncateUtf8Bytes(text, OUTPUT_CAP)`
+                        // at the end could cut the last delta — so onChunk sum > result.text.
+                        const remaining = OUTPUT_CAP - outputBytesSent;
+                        const { send, bytes } = truncateToBytes(delta, remaining);
+                        text += send;
+                        outputBytesSent += bytes;
+                        if (send)
+                            input.onChunk?.(send);
+                        if (bytes < Buffer.byteLength(delta, "utf8")) {
+                            // We've hit the cap mid-delta — abort the stream.
+                            // biome-ignore lint/suspicious/noExplicitAny: stream shape
+                            const ctrl = stream.controller;
+                            if (ctrl && typeof ctrl.abort === "function") {
+                                try {
+                                    ctrl.abort();
+                                }
+                                catch {
+                                    /* best effort */
+                                }
+                            }
+                            break;
+                        }
                     }
                     else {
                         // biome-ignore lint/suspicious/noExplicitAny: stream shape
@@ -111,23 +164,30 @@ export class OpenAIApiDriver {
                 input.signal.aborted;
             if (isAbort) {
                 return {
-                    text: text.slice(0, OUTPUT_CAP),
+                    text: truncateUtf8Bytes(text, OUTPUT_CAP),
                     durationMs: Date.now() - start,
                     wasAborted: true,
                     startupMs: firstChunkAt !== undefined ? firstChunkAt - start : undefined,
                 };
             }
             return {
-                text: text.slice(0, OUTPUT_CAP),
+                text: truncateUtf8Bytes(text, OUTPUT_CAP),
                 durationMs: Date.now() - start,
                 errorMessage: err instanceof Error ? err.message : String(err),
             };
         }
         return {
-            text: text.slice(0, OUTPUT_CAP),
+            text: truncateUtf8Bytes(text, OUTPUT_CAP),
             durationMs: Date.now() - start,
             startupMs: firstChunkAt !== undefined ? firstChunkAt - start : undefined,
-            providerMeta: { model },
+            providerMeta: {
+                model,
+                // Present only when the endpoint returned a usage chunk. Both fields
+                // together or neither — a half-populated count would mislead budgets.
+                ...(promptTokens !== undefined && completionTokens !== undefined
+                    ? { inputTokens: promptTokens, outputTokens: completionTokens }
+                    : {}),
+            },
         };
     }
     /** Override in subclasses to use a different env var. */

package/dist/drivers/openai/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/drivers/openai/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/drivers/openai/index.ts"],"names":[],"mappings":"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"}

package/dist/drivers/outputCap.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared UTF-8-aware output truncation for driver results.
+ *
+ * Audit 2026-06-03 (MEDIUM #30): the API drivers (claude/api, openai, gemini)
+ * capped output with `text.slice(0, OUTPUT_CAP)`, which counts UTF-16 code
+ * units — so a 50K "byte" cap could emit ~200KB of UTF-8 wire bytes for CJK /
+ * emoji content and could leave a lone surrogate at the boundary. These
+ * helpers (previously private to claude/subprocess.ts) measure and cut by
+ * UTF-8 bytes. Shared so every driver path uses one implementation.
+ */
+/**
+ * Truncate `text` to at most `cap` UTF-8 bytes without splitting a multi-byte
+ * codepoint. `String.slice(0, cap)` counts UTF-16 code units, so a 50K cap can
+ * emit ~200KB of UTF-8 wire bytes for CJK / emoji content; this cuts by bytes
+ * at a codepoint boundary.
+ */
+export declare function truncateUtf8Bytes(text: string, cap: number): string;
+/**
+ * Truncate `text` so it adds at most `remaining` UTF-8 bytes to a stream and
+ * never splits a multi-byte codepoint. Returns the safely-truncated slice plus
+ * its actual byte length so a running byte total can be advanced correctly
+ * (used by the streaming accumulators).
+ */
+export declare function truncateToBytes(text: string, remaining: number): {
+    send: string;
+    bytes: number;
+};

package/dist/drivers/outputCap.js

@@ -0,0 +1,50 @@
+/**
+ * Shared UTF-8-aware output truncation for driver results.
+ *
+ * Audit 2026-06-03 (MEDIUM #30): the API drivers (claude/api, openai, gemini)
+ * capped output with `text.slice(0, OUTPUT_CAP)`, which counts UTF-16 code
+ * units — so a 50K "byte" cap could emit ~200KB of UTF-8 wire bytes for CJK /
+ * emoji content and could leave a lone surrogate at the boundary. These
+ * helpers (previously private to claude/subprocess.ts) measure and cut by
+ * UTF-8 bytes. Shared so every driver path uses one implementation.
+ */
+/**
+ * Largest byte length ≤ `cap` that ends on a UTF-8 codepoint boundary. UTF-8
+ * continuation bytes match `0b10xxxxxx`; if the byte at the cut is one, we're
+ * mid-sequence, so back off to the preceding lead byte. This drops a partial
+ * trailing codepoint cleanly (no U+FFFD, no lone surrogate, never over `cap`).
+ */
+function codepointBoundary(buf, cap) {
+    let end = cap;
+    while (end > 0 && (buf[end] & 0xc0) === 0x80)
+        end--;
+    return end;
+}
+/**
+ * Truncate `text` to at most `cap` UTF-8 bytes without splitting a multi-byte
+ * codepoint. `String.slice(0, cap)` counts UTF-16 code units, so a 50K cap can
+ * emit ~200KB of UTF-8 wire bytes for CJK / emoji content; this cuts by bytes
+ * at a codepoint boundary.
+ */
+export function truncateUtf8Bytes(text, cap) {
+    const buf = Buffer.from(text, "utf8");
+    if (buf.length <= cap)
+        return text;
+    return buf.subarray(0, codepointBoundary(buf, cap)).toString("utf8");
+}
+/**
+ * Truncate `text` so it adds at most `remaining` UTF-8 bytes to a stream and
+ * never splits a multi-byte codepoint. Returns the safely-truncated slice plus
+ * its actual byte length so a running byte total can be advanced correctly
+ * (used by the streaming accumulators).
+ */
+export function truncateToBytes(text, remaining) {
+    const buf = Buffer.from(text, "utf8");
+    if (buf.length <= remaining)
+        return { send: text, bytes: buf.length };
+    const send = buf
+        .subarray(0, codepointBoundary(buf, remaining))
+        .toString("utf8");
+    return { send, bytes: Buffer.byteLength(send, "utf8") };
+}
+//# sourceMappingURL=outputCap.js.map

package/dist/drivers/outputCap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outputCap.js","sourceRoot":"","sources":["../../src/drivers/outputCap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;GAKG;AACH,SAAS,iBAAiB,CAAC,GAAW,EAAE,GAAW;IACjD,IAAI,GAAG,GAAG,GAAG,CAAC;IACd,OAAO,GAAG,GAAG,CAAC,IAAI,CAAE,GAAG,CAAC,GAAG,CAAY,GAAG,IAAI,CAAC,KAAK,IAAI;QAAE,GAAG,EAAE,CAAC;IAChE,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY,EAAE,GAAW;IACzD,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACtC,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG;QAAE,OAAO,IAAI,CAAC;IACnC,OAAO,GAAG,CAAC,QAAQ,CAAC,CAAC,EAAE,iBAAiB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AACvE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAC7B,IAAY,EACZ,SAAiB;IAEjB,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACtC,IAAI,GAAG,CAAC,MAAM,IAAI,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC;IACtE,MAAM,IAAI,GAAG,GAAG;SACb,QAAQ,CAAC,CAAC,EAAE,iBAAiB,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;SAC9C,QAAQ,CAAC,MAAM,CAAC,CAAC;IACpB,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC;AAC1D,CAAC"}

package/dist/embeddings/cosine.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Pure, zero-dependency vector math. No imports — keep it that way so it can
+ * be reused anywhere (ranking, dedup, semantic search) without pulling in
+ * network / config / driver dependencies.
+ */
+/**
+ * Cosine similarity = dot(a, b) / (|a| * |b|).
+ *
+ * Returns `0` (never `NaN`, never throws) on:
+ *   - length mismatch between `a` and `b`
+ *   - either vector being zero-magnitude
+ *   - empty vectors
+ *
+ * Identical vectors → 1, orthogonal → 0, opposite → -1.
+ */
+export declare function cosineSimilarity(a: number[], b: number[]): number;
+/**
+ * Return the `k` highest-scoring items, sorted score-descending. Stable for
+ * ties — items with equal score keep their original relative order.
+ *
+ * `k` larger than the list returns all items (sorted). `k <= 0` returns `[]`.
+ */
+export declare function topK<T>(items: T[], scoreOf: (item: T) => number, k: number): T[];

package/dist/embeddings/cosine.js

@@ -0,0 +1,59 @@
+/**
+ * Pure, zero-dependency vector math. No imports — keep it that way so it can
+ * be reused anywhere (ranking, dedup, semantic search) without pulling in
+ * network / config / driver dependencies.
+ */
+/**
+ * Cosine similarity = dot(a, b) / (|a| * |b|).
+ *
+ * Returns `0` (never `NaN`, never throws) on:
+ *   - length mismatch between `a` and `b`
+ *   - either vector being zero-magnitude
+ *   - empty vectors
+ *
+ * Identical vectors → 1, orthogonal → 0, opposite → -1.
+ */
+export function cosineSimilarity(a, b) {
+    if (a.length !== b.length || a.length === 0)
+        return 0;
+    let dot = 0;
+    let magA = 0;
+    let magB = 0;
+    for (let i = 0; i < a.length; i++) {
+        // Bounds-safe: i < a.length === b.length (checked above).
+        const av = a[i];
+        const bv = b[i];
+        dot += av * bv;
+        magA += av * av;
+        magB += bv * bv;
+    }
+    if (magA === 0 || magB === 0)
+        return 0;
+    const denom = Math.sqrt(magA) * Math.sqrt(magB);
+    if (denom === 0)
+        return 0;
+    return dot / denom;
+}
+/**
+ * Return the `k` highest-scoring items, sorted score-descending. Stable for
+ * ties — items with equal score keep their original relative order.
+ *
+ * `k` larger than the list returns all items (sorted). `k <= 0` returns `[]`.
+ */
+export function topK(items, scoreOf, k) {
+    if (k <= 0)
+        return [];
+    // Decorate with original index to make the sort stable across ties.
+    const decorated = items.map((item, index) => ({
+        item,
+        index,
+        score: scoreOf(item),
+    }));
+    decorated.sort((x, y) => {
+        if (y.score !== x.score)
+            return y.score - x.score;
+        return x.index - y.index;
+    });
+    return decorated.slice(0, k).map((d) => d.item);
+}
+//# sourceMappingURL=cosine.js.map

package/dist/embeddings/cosine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cosine.js","sourceRoot":"","sources":["../../src/embeddings/cosine.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAAC,CAAW,EAAE,CAAW;IACvD,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IACtD,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAClC,0DAA0D;QAC1D,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAW,CAAC;QAC1B,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAW,CAAC;QAC1B,GAAG,IAAI,EAAE,GAAG,EAAE,CAAC;QACf,IAAI,IAAI,EAAE,GAAG,EAAE,CAAC;QAChB,IAAI,IAAI,EAAE,GAAG,EAAE,CAAC;IAClB,CAAC;IACD,IAAI,IAAI,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IACvC,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAChD,IAAI,KAAK,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IAC1B,OAAO,GAAG,GAAG,KAAK,CAAC;AACrB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,IAAI,CAClB,KAAU,EACV,OAA4B,EAC5B,CAAS;IAET,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IACtB,oEAAoE;IACpE,MAAM,SAAS,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;QAC5C,IAAI;QACJ,KAAK;QACL,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC;KACrB,CAAC,CAAC,CAAC;IACJ,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACtB,IAAI,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,KAAK;YAAE,OAAO,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC;QAClD,OAAO,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC;IAC3B,CAAC,CAAC,CAAC;IACH,OAAO,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;AAClD,CAAC"}

package/dist/embeddings/index.d.ts

@@ -0,0 +1,19 @@
+import type { EmbeddingsProvider, EmbeddingsProviderOpts } from "./types.js";
+export { cosineSimilarity, topK } from "./cosine.js";
+export { LocalEmbeddingsProvider } from "./localEmbeddings.js";
+export type { EmbeddingsProvider, EmbeddingsProviderOpts } from "./types.js";
+/**
+ * Build an embeddings provider, or `null` when no endpoint is configured
+ * (neither `opts.endpoint` nor `LOCAL_EMBEDDINGS_ENDPOINT` nor
+ * `LOCAL_ENDPOINT`). Returning `null` lets callers fail soft.
+ */
+export declare function createEmbeddingsProvider(opts?: EmbeddingsProviderOpts): EmbeddingsProvider | null;
+/**
+ * Resolve a bound embed function for the configured local provider, or
+ * `undefined` when embeddings are unconfigured. Wired into tool registration
+ * sites — `createCtxQueryTracesTool({ ..., embedFn: getLocalEmbedFn() })` — so
+ * the opt-in semantic ranking path activates only when a local endpoint is set
+ * and stays byte-identical to substring search otherwise. Binds `embed` so
+ * callers can pass the function value directly without losing `this`.
+ */
+export declare function getLocalEmbedFn(opts?: EmbeddingsProviderOpts): ((texts: string[]) => Promise<number[][] | null>) | undefined;

package/dist/embeddings/index.js

@@ -0,0 +1,35 @@
+/**
+ * Embeddings module — internal, NOT an MCP tool (no outputSchema, not
+ * registered in src/tools/index.ts).
+ *
+ * The factory is the fail-soft hinge: {@link createEmbeddingsProvider} returns
+ * `null` when no endpoint is configured at all, so every consumer can detect
+ * "embeddings unavailable" and fall back to existing behavior.
+ */
+import { LocalEmbeddingsProvider } from "./localEmbeddings.js";
+import { resolveEmbeddingsEndpoint } from "./localEndpoints.js";
+export { cosineSimilarity, topK } from "./cosine.js";
+export { LocalEmbeddingsProvider } from "./localEmbeddings.js";
+/**
+ * Build an embeddings provider, or `null` when no endpoint is configured
+ * (neither `opts.endpoint` nor `LOCAL_EMBEDDINGS_ENDPOINT` nor
+ * `LOCAL_ENDPOINT`). Returning `null` lets callers fail soft.
+ */
+export function createEmbeddingsProvider(opts = {}) {
+    if (!resolveEmbeddingsEndpoint(opts))
+        return null;
+    return new LocalEmbeddingsProvider(opts);
+}
+/**
+ * Resolve a bound embed function for the configured local provider, or
+ * `undefined` when embeddings are unconfigured. Wired into tool registration
+ * sites — `createCtxQueryTracesTool({ ..., embedFn: getLocalEmbedFn() })` — so
+ * the opt-in semantic ranking path activates only when a local endpoint is set
+ * and stays byte-identical to substring search otherwise. Binds `embed` so
+ * callers can pass the function value directly without losing `this`.
+ */
+export function getLocalEmbedFn(opts = {}) {
+    const provider = createEmbeddingsProvider(opts);
+    return provider ? (texts) => provider.embed(texts) : undefined;
+}
+//# sourceMappingURL=index.js.map

package/dist/embeddings/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/embeddings/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAGhE,OAAO,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAG/D;;;;GAIG;AACH,MAAM,UAAU,wBAAwB,CACtC,OAA+B,EAAE;IAEjC,IAAI,CAAC,yBAAyB,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAClD,OAAO,IAAI,uBAAuB,CAAC,IAAI,CAAC,CAAC;AAC3C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAC7B,OAA+B,EAAE;IAEjC,MAAM,QAAQ,GAAG,wBAAwB,CAAC,IAAI,CAAC,CAAC;IAChD,OAAO,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAe,EAAE,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC3E,CAAC"}

package/dist/embeddings/localEmbeddings.d.ts

@@ -0,0 +1,29 @@
+import type { EmbeddingsProvider, EmbeddingsProviderOpts } from "./types.js";
+/**
+ * OpenAI-compatible embeddings client (Ollama / MLX / mlx-embeddings / vLLM).
+ *
+ * POSTs `{ model, input }` to `${endpoint}/embeddings` and parses the OpenAI
+ * shape `{ data: [{ embedding: number[] }, ...] }`.
+ *
+ * Fail-soft contract — `embed()` returns `null` (never throws) on:
+ *   - a public/non-loopback endpoint when LOCAL_ENDPOINT_ALLOW_REMOTE !== "1"
+ *     (anti-exfiltration — the texts we send are prompts/context)
+ *   - non-ok HTTP status
+ *   - JSON parse / unexpected shape
+ *   - any network throw inside fetch
+ *
+ * Configuration precedence (see {@link resolveEmbeddingsEndpoint} /
+ * {@link resolveEmbeddingsModel}):
+ *   endpoint: opts.endpoint ?? LOCAL_EMBEDDINGS_ENDPOINT ?? LOCAL_ENDPOINT
+ *   model:    opts.model ?? LOCAL_EMBEDDINGS_MODEL ?? LOCAL_MODEL ?? nomic-embed-text
+ *   apiKey:   opts.apiKey ?? LOCAL_API_KEY ?? "ollama"
+ */
+export declare class LocalEmbeddingsProvider implements EmbeddingsProvider {
+    private readonly endpoint;
+    private readonly model;
+    private readonly apiKey;
+    private readonly fetchImpl;
+    private readonly log;
+    constructor(opts?: EmbeddingsProviderOpts);
+    embed(texts: string[]): Promise<number[][] | null>;
+}

package/dist/embeddings/localEmbeddings.js

@@ -0,0 +1,103 @@
+import { isLoopbackOrPrivateEndpoint } from "../localEndpointGuard.js";
+import { resolveEmbeddingsEndpoint, resolveEmbeddingsModel, } from "./localEndpoints.js";
+/**
+ * OpenAI-compatible embeddings client (Ollama / MLX / mlx-embeddings / vLLM).
+ *
+ * POSTs `{ model, input }` to `${endpoint}/embeddings` and parses the OpenAI
+ * shape `{ data: [{ embedding: number[] }, ...] }`.
+ *
+ * Fail-soft contract — `embed()` returns `null` (never throws) on:
+ *   - a public/non-loopback endpoint when LOCAL_ENDPOINT_ALLOW_REMOTE !== "1"
+ *     (anti-exfiltration — the texts we send are prompts/context)
+ *   - non-ok HTTP status
+ *   - JSON parse / unexpected shape
+ *   - any network throw inside fetch
+ *
+ * Configuration precedence (see {@link resolveEmbeddingsEndpoint} /
+ * {@link resolveEmbeddingsModel}):
+ *   endpoint: opts.endpoint ?? LOCAL_EMBEDDINGS_ENDPOINT ?? LOCAL_ENDPOINT
+ *   model:    opts.model ?? LOCAL_EMBEDDINGS_MODEL ?? LOCAL_MODEL ?? nomic-embed-text
+ *   apiKey:   opts.apiKey ?? LOCAL_API_KEY ?? "ollama"
+ */
+export class LocalEmbeddingsProvider {
+    endpoint;
+    model;
+    apiKey;
+    fetchImpl;
+    log;
+    constructor(opts = {}) {
+        this.endpoint = resolveEmbeddingsEndpoint(opts);
+        this.model = resolveEmbeddingsModel(opts);
+        this.apiKey = opts.apiKey ?? process.env.LOCAL_API_KEY ?? "ollama";
+        this.fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+        this.log = opts.log ?? (() => { });
+    }
+    async embed(texts) {
+        const endpoint = this.endpoint;
+        if (!endpoint) {
+            this.log("embeddings: no endpoint configured — returning null");
+            return null;
+        }
+        // Anti-exfiltration guard. The texts we POST are prompts/context — a
+        // public host would leak them. Mirror src/drivers/local/index.ts, but
+        // fail SOFT (return null) instead of throwing.
+        if (process.env.LOCAL_ENDPOINT_ALLOW_REMOTE !== "1" &&
+            !isLoopbackOrPrivateEndpoint(endpoint)) {
+            this.log(`embeddings: endpoint="${endpoint}" is not loopback/private — refusing ` +
+                `to send prompt/context (set LOCAL_ENDPOINT_ALLOW_REMOTE=1 to override)`);
+            return null;
+        }
+        if (texts.length === 0)
+            return [];
+        const url = `${endpoint.replace(/\/$/, "")}/embeddings`;
+        try {
+            const res = await this.fetchImpl(url, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${this.apiKey}`,
+                },
+                body: JSON.stringify({ model: this.model, input: texts }),
+            });
+            if (!res.ok) {
+                this.log(`embeddings: non-ok status ${res.status} from ${url}`);
+                return null;
+            }
+            const body = (await res.json());
+            const vectors = parseEmbeddings(body);
+            if (!vectors) {
+                this.log(`embeddings: unexpected response shape from ${url}`);
+                return null;
+            }
+            return vectors;
+        }
+        catch (err) {
+            this.log(`embeddings: request failed — ${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        }
+    }
+}
+/**
+ * Parse the OpenAI embeddings response shape `{ data: [{ embedding: [...] }] }`.
+ * Returns `null` on any structural mismatch (so the caller can fail soft).
+ */
+function parseEmbeddings(body) {
+    if (typeof body !== "object" || body === null)
+        return null;
+    const data = body.data;
+    if (!Array.isArray(data))
+        return null;
+    const out = [];
+    for (const row of data) {
+        if (typeof row !== "object" || row === null)
+            return null;
+        const embedding = row.embedding;
+        if (!Array.isArray(embedding))
+            return null;
+        if (!embedding.every((n) => typeof n === "number"))
+            return null;
+        out.push(embedding);
+    }
+    return out;
+}
+//# sourceMappingURL=localEmbeddings.js.map

package/dist/embeddings/localEmbeddings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"localEmbeddings.js","sourceRoot":"","sources":["../../src/embeddings/localEmbeddings.ts"],"names":[],"mappings":"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"}

package/dist/embeddings/localEndpoints.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Shared endpoint/model precedence resolution for the embeddings module.
+ * Kept tiny + import-free (besides env reads) so both the factory
+ * (`index.ts`) and the provider (`localEmbeddings.ts`) agree on exactly the
+ * same precedence chain.
+ */
+import type { EmbeddingsProviderOpts } from "./types.js";
+/**
+ * Resolve the embeddings endpoint, honoring (in order):
+ *   1. `opts.endpoint`
+ *   2. `LOCAL_EMBEDDINGS_ENDPOINT` env
+ *   3. `LOCAL_ENDPOINT` env (reuse the chat endpoint when a dedicated
+ *      embeddings endpoint isn't configured)
+ * Returns `undefined` when none is set — the fail-soft hinge.
+ */
+export declare function resolveEmbeddingsEndpoint(opts?: EmbeddingsProviderOpts): string | undefined;
+/**
+ * Resolve the embeddings model, honoring (in order):
+ *   1. `opts.model`
+ *   2. `LOCAL_EMBEDDINGS_MODEL` env
+ *   3. `LOCAL_MODEL` env
+ *   4. `nomic-embed-text` (sensible Ollama default)
+ */
+export declare function resolveEmbeddingsModel(opts?: EmbeddingsProviderOpts): string;

package/dist/embeddings/localEndpoints.js

@@ -0,0 +1,37 @@
+/**
+ * Treat empty / whitespace-only values as "unset" so the precedence chain is
+ * not shadowed by a stale `export LOCAL_EMBEDDINGS_ENDPOINT=` or a blank
+ * dashboard field — `??` alone would let `""` win over a real fallback. Also
+ * trims, avoiding `http://host /embeddings`-style trailing-space URL bugs.
+ */
+function clean(v) {
+    const t = v?.trim();
+    return t ? t : undefined;
+}
+/**
+ * Resolve the embeddings endpoint, honoring (in order):
+ *   1. `opts.endpoint`
+ *   2. `LOCAL_EMBEDDINGS_ENDPOINT` env
+ *   3. `LOCAL_ENDPOINT` env (reuse the chat endpoint when a dedicated
+ *      embeddings endpoint isn't configured)
+ * Returns `undefined` when none is set — the fail-soft hinge.
+ */
+export function resolveEmbeddingsEndpoint(opts) {
+    return (clean(opts?.endpoint) ??
+        clean(process.env.LOCAL_EMBEDDINGS_ENDPOINT) ??
+        clean(process.env.LOCAL_ENDPOINT));
+}
+/**
+ * Resolve the embeddings model, honoring (in order):
+ *   1. `opts.model`
+ *   2. `LOCAL_EMBEDDINGS_MODEL` env
+ *   3. `LOCAL_MODEL` env
+ *   4. `nomic-embed-text` (sensible Ollama default)
+ */
+export function resolveEmbeddingsModel(opts) {
+    return (clean(opts?.model) ??
+        clean(process.env.LOCAL_EMBEDDINGS_MODEL) ??
+        clean(process.env.LOCAL_MODEL) ??
+        "nomic-embed-text");
+}
+//# sourceMappingURL=localEndpoints.js.map

package/dist/embeddings/localEndpoints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"localEndpoints.js","sourceRoot":"","sources":["../../src/embeddings/localEndpoints.ts"],"names":[],"mappings":"AAQA;;;;;GAKG;AACH,SAAS,KAAK,CAAC,CAAqB;IAClC,MAAM,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,CAAC;IACpB,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC3B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,yBAAyB,CACvC,IAA6B;IAE7B,OAAO,CACL,KAAK,CAAC,IAAI,EAAE,QAAQ,CAAC;QACrB,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,yBAAyB,CAAC;QAC5C,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,CAClC,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CAAC,IAA6B;IAClE,OAAO,CACL,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC;QAClB,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,sBAAsB,CAAC;QACzC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC;QAC9B,kBAAkB,CACnB,CAAC;AACJ,CAAC"}

package/dist/embeddings/types.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Internal embeddings module — NOT an MCP tool.
+ *
+ * Turns text into vectors via an OpenAI-compatible /v1/embeddings endpoint
+ * (Ollama, MLX, mlx-embeddings, vLLM, llama.cpp, LM Studio, etc.). Every
+ * consumer is expected to fail soft: the factory returns `null` when no
+ * endpoint is configured, and `embed()` returns `null` on any failure
+ * (network / parse / non-ok / SSRF-rejected) rather than throwing — mirroring
+ * the driver `run()`-never-rejects convention.
+ */
+/** A provider that turns text into embedding vectors. */
+export interface EmbeddingsProvider {
+    /**
+     * Embed a batch of texts. Returns one vector per input (in order), or `null`
+     * on ANY failure (network error, non-ok HTTP status, parse error,
+     * SSRF-rejected endpoint). Never throws.
+     */
+    embed(texts: string[]): Promise<number[][] | null>;
+}
+/** Construction options for a {@link EmbeddingsProvider}. */
+export interface EmbeddingsProviderOpts {
+    /** OpenAI-compatible base URL, e.g. `http://localhost:11434/v1`. */
+    endpoint?: string;
+    /** Model id, e.g. `nomic-embed-text`. */
+    model?: string;
+    /** Bearer token for `Authorization`. Defaults to the `ollama` placeholder. */
+    apiKey?: string;
+    /** Injected fetch (for tests). Defaults to `globalThis.fetch`. */
+    fetchImpl?: typeof fetch;
+    /** Optional logger for fail-soft diagnostics. */
+    log?: (msg: string) => void;
+}

package/dist/embeddings/types.js

@@ -0,0 +1,12 @@
+/**
+ * Internal embeddings module — NOT an MCP tool.
+ *
+ * Turns text into vectors via an OpenAI-compatible /v1/embeddings endpoint
+ * (Ollama, MLX, mlx-embeddings, vLLM, llama.cpp, LM Studio, etc.). Every
+ * consumer is expected to fail soft: the factory returns `null` when no
+ * endpoint is configured, and `embed()` returns `null` on any failure
+ * (network / parse / non-ok / SSRF-rejected) rather than throwing — mirroring
+ * the driver `run()`-never-rejects convention.
+ */
+export {};
+//# sourceMappingURL=types.js.map