ai-runtime-engine 1.3.0 → 2.7.0

package/dist/mcp/transport.js

@@ -0,0 +1,383 @@
+/**
+ * MCP transports (Phase 3.2) — zero-dependency, injectable, offline-testable.
+ *
+ * `StdioTransport` spawns a server process and frames JSON-RPC as newline-delimited JSON over stdin/
+ * stdout (stderr is captured, redacted, and ring-buffered for diagnostics). `HttpTransport` speaks
+ * streamable HTTP: it POSTs JSON-RPC and accepts either a single JSON response or an SSE stream, reusing
+ * the `data:`-line parsing approach already proven in `providers/httpClient.callHttpStream`, and carries
+ * the `Mcp-Session-Id` handed out at initialize. `InProcessTransport` is the test seam.
+ *
+ * SECURITY: a request URL or spawn command NEVER appears in a thrown error (undici embeds the URL in its
+ * message, and a URL can carry a token) — only the error NAME. Credentials arrive already resolved from
+ * an env-var NAME via `Credential`, are used solely to build a header (or a single env var for stdio),
+ * and are never stored on the transport, logged, or serialized.
+ */
+import { spawn } from 'node:child_process';
+import { AIError } from '../core/fallback/errors.js';
+import { redactString } from '../security/redact.js';
+import { safeEnv } from '../tools/runner.js';
+import { clampText } from './protocol.js';
+const DIAG_LIMIT = 20;
+/**
+ * ONE process-exit hook for every stdio child, not one per transport — `process` warns past ten
+ * listeners on an event, and a user with a dozen MCP servers would see that warning on stderr. The
+ * handler must be synchronous ('exit' cannot await); the graceful SIGTERM escalation lives in `close()`.
+ */
+const liveChildren = new Set();
+let exitHookInstalled = false;
+function trackChild(child) {
+    liveChildren.add(child);
+    if (exitHookInstalled)
+        return;
+    exitHookInstalled = true;
+    process.once('exit', () => {
+        for (const c of liveChildren) {
+            try {
+                if (c.exitCode === null)
+                    c.kill('SIGKILL');
+            }
+            catch {
+                /* already gone */
+            }
+        }
+        liveChildren.clear();
+    });
+}
+/**
+ * Push a diagnostic into a bounded ring: redacted, then FLATTENED and clamped. A child's stderr is
+ * server-controlled multi-line text that ends up in `mcp <id>` output, so an unflattened line can forge
+ * additional rows in that report.
+ */
+function pushDiag(ring, line) {
+    const clean = clampText(redactString(line), 200);
+    if (!clean)
+        return;
+    ring.push(clean);
+    while (ring.length > DIAG_LIMIT)
+        ring.shift();
+}
+/** Inbound framing bounds: a server must not be able to grow our heap with one unterminated line. */
+const MAX_LINE_BYTES = 1024 * 1024;
+const MAX_BODY_BYTES = 8 * 1024 * 1024;
+export class StdioTransport {
+    opts;
+    child;
+    handler;
+    buffer = '';
+    diag = [];
+    closed = false;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    async start() {
+        // A minimal, secret-free environment (the shell tool's rule) plus ONLY the one credential the
+        // server was configured to receive, by env-var name.
+        const env = { ...safeEnv(this.opts.env ?? process.env) };
+        if (this.opts.tokenEnvName && this.opts.tokenValue)
+            env[this.opts.tokenEnvName] = this.opts.tokenValue;
+        let child;
+        try {
+            child = spawn(this.opts.command, this.opts.args ?? [], {
+                cwd: this.opts.cwd,
+                env,
+                stdio: ['pipe', 'pipe', 'pipe'],
+                detached: process.platform !== 'win32', // own process group so close() can kill the tree
+            });
+        }
+        catch (e) {
+            // Never echo the command line — it can carry paths/args the operator considers sensitive.
+            throw new AIError(`MCP stdio server failed to start (${e instanceof Error ? e.name : 'Error'})`, { category: 'NETWORK', retryable: false });
+        }
+        this.child = child;
+        child.stdout.setEncoding('utf8');
+        child.stdout.on('data', (chunk) => this.onChunk(chunk));
+        child.stderr.setEncoding('utf8');
+        child.stderr.on('data', (chunk) => pushDiag(this.diag, String(chunk)));
+        child.on('error', (e) => pushDiag(this.diag, `process error (${e.name})`));
+        // A stream error on a dying child (EPIPE when we write into a process that just exited, ECONNRESET
+        // on a Windows named pipe) is EXPECTED during teardown. Unhandled, a stream 'error' is an uncaught
+        // exception that would take down the host process, so each pipe gets a handler that just records it.
+        for (const [name, stream] of [['stdin', child.stdin], ['stdout', child.stdout], ['stderr', child.stderr]]) {
+            stream.on('error', (e) => pushDiag(this.diag, `${name} error (${e.name})`));
+        }
+        // A `close()` we never got to (crash, uncaught throw, process.exit) must not leave an orphan.
+        trackChild(child);
+        child.on('exit', (code, signal) => {
+            liveChildren.delete(child);
+            if (!this.closed)
+                pushDiag(this.diag, `server exited (code=${code ?? 'null'} signal=${signal ?? 'null'})`);
+        });
+        // `spawn()` reports a missing executable ASYNCHRONOUSLY, so without this the handshake would be
+        // written into a dead pipe and the caller would wait out the whole request timeout (30s by default)
+        // to learn the command does not exist. Racing 'spawn' against 'error' turns that into an immediate,
+        // accurate failure — and the command line still never reaches the message.
+        await new Promise((resolve, reject) => {
+            child.once('spawn', resolve);
+            child.once('error', (e) => reject(new AIError(`MCP stdio server failed to start (${e instanceof Error ? e.name : 'Error'})`, { category: 'NETWORK', retryable: false })));
+        });
+    }
+    onChunk(chunk) {
+        this.buffer += chunk;
+        if (this.buffer.length > MAX_LINE_BYTES) {
+            // An unterminated megabyte is not a JSON-RPC frame; drop it rather than grow without bound.
+            this.buffer = '';
+            pushDiag(this.diag, 'server wrote an oversized line (dropped)');
+            return;
+        }
+        let nl;
+        while ((nl = this.buffer.indexOf('\n')) >= 0) {
+            const line = this.buffer.slice(0, nl).trim();
+            this.buffer = this.buffer.slice(nl + 1);
+            if (!line)
+                continue;
+            try {
+                this.handler?.(JSON.parse(line));
+            }
+            catch {
+                pushDiag(this.diag, 'server wrote a non-JSON line');
+            }
+        }
+    }
+    async send(msg) {
+        const child = this.child;
+        // `killed` only reflects OUR kill(); a server that crashed on its own has exitCode set instead, and
+        // writing into it succeeds silently — the caller would then stall for the full timeout.
+        if (!child || child.killed || child.exitCode !== null || child.signalCode !== null || !child.stdin.writable) {
+            throw new AIError('MCP stdio server is not running', { category: 'NETWORK', retryable: true });
+        }
+        child.stdin.write(`${JSON.stringify(msg)}\n`);
+    }
+    onMessage(cb) {
+        this.handler = cb;
+    }
+    /** SIGTERM, then a process-group SIGKILL — the same escalation the shell runner uses. */
+    async close() {
+        this.closed = true;
+        const child = this.child;
+        this.child = undefined;
+        if (child)
+            liveChildren.delete(child);
+        if (!child || child.exitCode !== null)
+            return;
+        try {
+            child.stdin.end();
+        }
+        catch {
+            /* already gone */
+        }
+        try {
+            child.kill('SIGTERM');
+        }
+        catch {
+            /* already gone */
+        }
+        await new Promise((res) => {
+            const t = setTimeout(() => {
+                try {
+                    if (child.pid && process.platform !== 'win32')
+                        process.kill(-child.pid, 'SIGKILL');
+                    else
+                        child.kill('SIGKILL');
+                }
+                catch {
+                    /* already gone */
+                }
+                res();
+            }, 300);
+            if (typeof t.unref === 'function')
+                t.unref();
+            child.once('exit', () => {
+                clearTimeout(t);
+                res();
+            });
+        });
+        // The process is gone; drop its pipes so no handle can keep our own event loop alive.
+        for (const stream of [child.stdin, child.stdout, child.stderr]) {
+            try {
+                stream.destroy();
+            }
+            catch {
+                /* already destroyed */
+            }
+        }
+    }
+    diagnostics() {
+        return [...this.diag];
+    }
+}
+export class HttpTransport {
+    opts;
+    handler;
+    sessionId;
+    /** Set once the handshake settles; the spec requires it on every subsequent request. */
+    negotiatedVersion;
+    diag = [];
+    fetchImpl;
+    constructor(opts) {
+        this.opts = opts;
+        this.fetchImpl = opts.fetchImpl ?? fetch;
+    }
+    async start() {
+        /* HTTP is connectionless here: `initialize` is the first POST. */
+    }
+    onMessage(cb) {
+        this.handler = cb;
+    }
+    /**
+     * Whether the session was invalidated (HTTP 404 on a session-bearing request). The manager reads this
+     * to force a full reconnect instead of retrying against a session the server has forgotten.
+     */
+    sessionExpired = false;
+    /** Record the version the handshake settled on so later requests can carry the required header. */
+    setProtocolVersion(version) {
+        this.negotiatedVersion = version;
+    }
+    async send(msg) {
+        const headers = { 'content-type': 'application/json', accept: 'application/json, text/event-stream' };
+        if (this.opts.token)
+            headers.authorization = `Bearer ${this.opts.token}`;
+        if (this.sessionId)
+            headers['mcp-session-id'] = this.sessionId;
+        if (this.negotiatedVersion)
+            headers['mcp-protocol-version'] = this.negotiatedVersion;
+        let res;
+        try {
+            res = await this.fetchImpl(this.opts.url, { method: 'POST', headers, body: JSON.stringify(msg), signal: AbortSignal.timeout(this.opts.timeoutMs ?? 30_000) });
+        }
+        catch (e) {
+            const name = e instanceof Error ? e.name : 'Error';
+            const isTimeout = name === 'TimeoutError' || name === 'AbortError';
+            // Only the error NAME — the URL must never reach the message.
+            throw new AIError(`MCP request failed (${name})`, { category: isTimeout ? 'TIMEOUT' : 'NETWORK', retryable: true });
+        }
+        const session = res.headers.get('mcp-session-id');
+        if (session)
+            this.sessionId = session;
+        // A 404 on a session-bearing request means the server dropped our session — re-initialize.
+        if (res.status === 404 && this.sessionId) {
+            this.sessionId = undefined;
+            this.sessionExpired = true;
+            throw new AIError('MCP session expired (HTTP 404) — reconnecting', { category: 'NETWORK', retryable: true });
+        }
+        if (!res.ok) {
+            const category = res.status === 401 || res.status === 403 ? 'AUTHENTICATION' : 'NETWORK';
+            throw new AIError(`MCP endpoint returned HTTP ${res.status}`, { category, status: res.status, retryable: category === 'NETWORK' });
+        }
+        if (res.status === 202)
+            return; // accepted notification, no body
+        const contentType = res.headers.get('content-type') ?? '';
+        if (contentType.includes('text/event-stream'))
+            await this.readSse(res);
+        else
+            await this.readJson(res);
+    }
+    async readJson(res) {
+        const text = await res.text();
+        if (text.length > MAX_BODY_BYTES)
+            throw new AIError('MCP endpoint returned an oversized body', { category: 'RESPONSE_VALIDATION', retryable: false });
+        if (!text.trim())
+            return;
+        try {
+            const parsed = JSON.parse(text);
+            for (const m of Array.isArray(parsed) ? parsed : [parsed])
+                this.handler?.(m);
+        }
+        catch {
+            pushDiag(this.diag, 'endpoint returned a non-JSON body');
+            throw new AIError('MCP endpoint returned a non-JSON body', { category: 'RESPONSE_VALIDATION', retryable: false });
+        }
+    }
+    /**
+     * Consume an SSE body. Events are separated by a BLANK line and a single event may carry several
+     * `data:` lines that concatenate with newlines — parsing each line on its own loses any multi-line
+     * event, and treating a lone CR as no separator makes a CR-only stream unparseable. Both are handled
+     * here. We stop once the frame we are waiting for arrives: a RESPONSE (an id plus result/error and no
+     * method), not merely anything carrying an id — a server-initiated request would otherwise abandon the
+     * stream before our own reply showed up.
+     */
+    async readSse(res) {
+        if (!res.body)
+            return;
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        let sawResponse = false;
+        try {
+            for (;;) {
+                const { value, done } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true }).replace(/\r\n?/g, '\n');
+                if (buffer.length > MAX_BODY_BYTES)
+                    throw new AIError('MCP endpoint streamed an oversized body', { category: 'RESPONSE_VALIDATION', retryable: false });
+                let sep;
+                while ((sep = buffer.indexOf('\n\n')) >= 0) {
+                    const event = buffer.slice(0, sep);
+                    buffer = buffer.slice(sep + 2);
+                    if (this.dispatchSseEvent(event))
+                        sawResponse = true;
+                }
+                if (sawResponse)
+                    break; // our reply arrived; do not hold the stream open
+            }
+            // A body that ends without a trailing blank line still carries a complete final event.
+            if (!sawResponse && buffer.trim())
+                this.dispatchSseEvent(buffer);
+        }
+        finally {
+            await reader.cancel().catch(() => { });
+        }
+    }
+    /** Parse one SSE event block; returns true when it carried a JSON-RPC RESPONSE to one of our requests. */
+    dispatchSseEvent(block) {
+        const data = block
+            .split('\n')
+            .filter((l) => l.startsWith('data:'))
+            .map((l) => l.slice(5).replace(/^ /, ''))
+            .join('\n')
+            .trim();
+        if (!data || data === '[DONE]')
+            return false;
+        try {
+            const msg = JSON.parse(data);
+            this.handler?.(msg);
+            const m = msg;
+            return m.id !== undefined && m.id !== null && typeof m.method !== 'string' && (m.result !== undefined || m.error !== undefined);
+        }
+        catch {
+            pushDiag(this.diag, 'stream carried a non-JSON event');
+            return false;
+        }
+    }
+    async close() {
+        this.sessionId = undefined;
+        this.negotiatedVersion = undefined;
+    }
+    diagnostics() {
+        return [...this.diag];
+    }
+}
+// ── in-process (tests) ───────────────────────────────────────────────────────
+/** A scripted server for offline tests: a plain function from request to response. */
+export class InProcessTransport {
+    server;
+    handler;
+    constructor(server) {
+        this.server = server;
+    }
+    async start() { }
+    onMessage(cb) {
+        this.handler = cb;
+    }
+    async send(msg) {
+        if (!('id' in msg))
+            return; // notification
+        const reply = await this.server(msg);
+        if (reply)
+            this.handler?.(reply);
+    }
+    async close() { }
+    diagnostics() {
+        return [];
+    }
+}

package/dist/memory/embedders/hash.d.ts

@@ -0,0 +1,12 @@
+/**
+ * HashEmbedder — a deterministic, zero-dependency, offline embedding via the hashing trick (Phase 14).
+ * It maps each token to a bucket in a fixed-dimension vector and L2-normalizes, so cosine similarity
+ * tracks token overlap. It is not a learned semantic model, but it is deterministic and needs no network
+ * — the local default (config `embedding: { provider: 'local' }`) and the offline test backbone for the
+ * whole semantic path. Swap in a real `HttpEmbedder` for learned embeddings.
+ */
+import type { EmbeddingProvider } from '../memory.js';
+export declare class HashEmbedder implements EmbeddingProvider {
+    readonly id = "local-hash";
+    embed(texts: string[]): Promise<number[][]>;
+}

package/dist/memory/embedders/hash.js

@@ -0,0 +1,31 @@
+/**
+ * HashEmbedder — a deterministic, zero-dependency, offline embedding via the hashing trick (Phase 14).
+ * It maps each token to a bucket in a fixed-dimension vector and L2-normalizes, so cosine similarity
+ * tracks token overlap. It is not a learned semantic model, but it is deterministic and needs no network
+ * — the local default (config `embedding: { provider: 'local' }`) and the offline test backbone for the
+ * whole semantic path. Swap in a real `HttpEmbedder` for learned embeddings.
+ */
+import { tokenize } from '../bm25.js';
+const DIM = 256;
+/** FNV-1a hash of a token → a bucket in [0, DIM). */
+function bucket(token) {
+    let h = 2166136261;
+    for (let i = 0; i < token.length; i += 1) {
+        h ^= token.charCodeAt(i);
+        h = Math.imul(h, 16777619);
+    }
+    return (h >>> 0) % DIM;
+}
+function embedOne(text) {
+    const v = new Array(DIM).fill(0);
+    for (const tok of tokenize(text))
+        v[bucket(tok)] += 1;
+    const norm = Math.sqrt(v.reduce((s, x) => s + x * x, 0)) || 1;
+    return v.map((x) => x / norm);
+}
+export class HashEmbedder {
+    id = 'local-hash';
+    async embed(texts) {
+        return texts.map(embedOne);
+    }
+}

package/dist/memory/embedders/http.d.ts

@@ -0,0 +1,25 @@
+/**
+ * HttpEmbedder — an OpenAI-compatible embeddings adapter (Phase 14): `POST {baseUrl}/embeddings` with
+ * `{ model, input: texts }`, Bearer auth from a `Credential` (env-var name only, never a raw key). Parses
+ * `{ data: [{ embedding: number[] }] }`. `fetch` is injectable for offline tests.
+ *
+ * SECURITY: the request URL is never placed in a thrown error (undici embeds it, and it can carry a
+ * key-in-query); the key lives only in the header. A failure here surfaces as a thrown error, which the
+ * caller (MemoryStore.searchSemantic) turns into a BM25 fallback — retrieval never breaks the run.
+ */
+import type { EmbeddingProvider } from '../memory.js';
+import type { FetchLike } from '../../providers/httpClient.js';
+import type { Credential } from '../../security/credentials.js';
+export interface HttpEmbedderConfig {
+    baseUrl: string;
+    model: string;
+    credential: Credential;
+    fetchImpl?: FetchLike;
+    timeoutMs?: number;
+}
+export declare class HttpEmbedder implements EmbeddingProvider {
+    private readonly cfg;
+    readonly id: string;
+    constructor(cfg: HttpEmbedderConfig);
+    embed(texts: string[]): Promise<number[][]>;
+}

package/dist/memory/embedders/http.js

@@ -0,0 +1,48 @@
+/**
+ * HttpEmbedder — an OpenAI-compatible embeddings adapter (Phase 14): `POST {baseUrl}/embeddings` with
+ * `{ model, input: texts }`, Bearer auth from a `Credential` (env-var name only, never a raw key). Parses
+ * `{ data: [{ embedding: number[] }] }`. `fetch` is injectable for offline tests.
+ *
+ * SECURITY: the request URL is never placed in a thrown error (undici embeds it, and it can carry a
+ * key-in-query); the key lives only in the header. A failure here surfaces as a thrown error, which the
+ * caller (MemoryStore.searchSemantic) turns into a BM25 fallback — retrieval never breaks the run.
+ */
+export class HttpEmbedder {
+    cfg;
+    id;
+    constructor(cfg) {
+        this.cfg = cfg;
+        this.id = `http:${cfg.model}`;
+    }
+    async embed(texts) {
+        if (texts.length === 0)
+            return [];
+        const fetchImpl = this.cfg.fetchImpl ?? fetch;
+        const url = `${String(this.cfg.baseUrl).replace(/\/+$/, '')}/embeddings`;
+        const headers = { 'content-type': 'application/json' };
+        const key = this.cfg.credential.use();
+        if (key)
+            headers.authorization = `Bearer ${key}`;
+        let res;
+        try {
+            res = await fetchImpl(url, { method: 'POST', headers, body: JSON.stringify({ model: this.cfg.model, input: texts }), signal: AbortSignal.timeout(this.cfg.timeoutMs ?? 30_000) });
+        }
+        catch (e) {
+            // undici embeds the full URL in the message — use only the error NAME.
+            throw new Error(`embedding request failed (${e instanceof Error ? e.name : 'Error'})`);
+        }
+        if (!res.ok)
+            throw new Error(`embedding endpoint returned HTTP ${res.status}`);
+        const json = (await res.json());
+        const data = json.data ?? [];
+        if (data.length !== texts.length)
+            throw new Error(`embedding count mismatch (got ${data.length}, want ${texts.length})`);
+        return data.map((d, i) => {
+            const vec = d.embedding;
+            // A valid embedding is a non-empty numeric vector; reject a degenerate one so the caller falls back to BM25.
+            if (!Array.isArray(vec) || vec.length === 0)
+                throw new Error(`embedding ${i} is not a valid vector`);
+            return vec;
+        });
+    }
+}

package/dist/memory/memory.d.ts

@@ -7,7 +7,7 @@
  */
 import type { Clock } from '../util/clock.js';
 import type { RuntimeStore } from '../store/store.js';
-export type MemoryScope = 'user' | 'project' | 'repository' | 'domain' | 'skill' | 'execution';
+export type MemoryScope = 'user' | 'project' | 'repository' | 'organization' | 'domain' | 'skill' | 'execution';
 export type MemorySource = 'explicit' | 'observed' | 'inferred' | 'imported';
 export interface MemoryRecord {
     id: string;
@@ -56,11 +56,17 @@ export interface EmbeddingProvider {
 }
 export declare class MemoryStore {
     private readonly store;
+    private readonly embedder?;
     private readonly clock;
     private counter;
-    constructor(store: RuntimeStore, clock?: Clock);
+    /** Per-instance cache of fact-text → vector, so a stable fact isn't re-embedded on every query. */
+    private readonly vecCache;
+    constructor(store: RuntimeStore, clock?: Clock, embedder?: EmbeddingProvider | undefined);
     get enabled(): boolean;
     private area;
+    /** Physical scopes to traverse for reads/cascades — includes `organization` only when one is configured,
+     *  so search/delete/supersession/purge cover it for free without leaking it into org-less stores. */
+    private physicalScopes;
     private nextId;
     /** Store a fact. Redacts text, resolves conflicts (supersedes prior same-group facts). */
     remember(input: RememberInput): MemoryRecord;
@@ -70,7 +76,18 @@ export declare class MemoryStore {
     /** Every stored record across scopes (including superseded/expired). A corrupt file is skipped. */
     all(): MemoryRecord[];
     /** Retrieval: filter (scope/domain/confidence/temporal/superseded) → BM25 rank → top-N. */
+    /** The filter stage shared by BM25 and semantic search: expiry, active-supersession, confidence, scope, domain. */
+    private filteredCandidates;
+    private rankBm25;
+    /** Retrieve facts by BM25 keyword relevance (the offline default; sync, unchanged since 1.0). */
     search(query: string, opts?: SearchOptions): MemoryRecord[];
+    /**
+     * Retrieve facts by SEMANTIC (vector) relevance when an embedder is configured, else exactly BM25
+     * (Phase 14). Same filter stage, same `{scope/confidence/temporal}` semantics, same return shape. Any
+     * embedder failure falls back to BM25 — retrieval must never break the run. Candidate vectors are cached
+     * per fact text so a stable fact is embedded at most once per session.
+     */
+    searchSemantic(query: string, opts?: SearchOptions): Promise<MemoryRecord[]>;
     /** Delete a record and cascade (strip references, heal supersession chains), under the lock. */
     delete(id: string): DeletionAudit;
     /** The cascade itself (assumes the caller holds the lock). Heals A→B→C when B is removed. */