@zleap-ai/dsh-sag 0.1.0

package/lib/local/mcp-probe.d.ts

@@ -0,0 +1,27 @@
+import type { SagConnectionDescriptor } from '../connection/types.js';
+/** Successful MCP compatibility result; no MCP tools are registered in dsh. */
+export interface McpProbeResult {
+    readonly tools: readonly string[];
+    readonly readTool?: 'read' | 'get_chunk';
+}
+/** One temporary MCP connection, injectable so lifecycle behavior is observable. */
+export interface McpProbeSession {
+    connect(signal: AbortSignal): Promise<void>;
+    listTools(signal: AbortSignal): Promise<readonly string[]>;
+    close(): Promise<void>;
+}
+/** Factory for a temporary MCP probe session. */
+export type McpProbeSessionFactory = (descriptor: SagConnectionDescriptor) => McpProbeSession;
+/** A reachable MCP endpoint whose advertised tools do not satisfy dsh-sag. */
+export declare class McpProbeIncompatibleError extends Error {
+    /** @param message - redacted compatibility failure. */
+    constructor(message: string);
+}
+/** A temporary transport, initialization, listing, or closure failure. */
+export declare class McpProbeUnreachableError extends Error {
+    /** @param message - redacted connection failure. */
+    constructor(message: string);
+}
+/** Initialize SAG MCP, verify retrieval tools, and require successful temporary-session closure. */
+export declare function probeMcp(descriptor: SagConnectionDescriptor, signal: AbortSignal, factory?: McpProbeSessionFactory, advertisedCapabilities?: readonly string[]): Promise<McpProbeResult>;
+//# sourceMappingURL=mcp-probe.d.ts.map

package/lib/local/mcp-probe.js

@@ -0,0 +1,92 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+/** A reachable MCP endpoint whose advertised tools do not satisfy dsh-sag. */
+export class McpProbeIncompatibleError extends Error {
+    /** @param message - redacted compatibility failure. */
+    constructor(message) {
+        super(`dsh-sag: SAG MCP is incompatible: ${message}`);
+        this.name = 'McpProbeIncompatibleError';
+    }
+}
+/** A temporary transport, initialization, listing, or closure failure. */
+export class McpProbeUnreachableError extends Error {
+    /** @param message - redacted connection failure. */
+    constructor(message) {
+        super(`dsh-sag: SAG MCP is unreachable: ${message}`);
+        this.name = 'McpProbeUnreachableError';
+    }
+}
+function redacted(error, token) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.split(token).join('<redacted>');
+}
+function productionSession(descriptor) {
+    const client = new Client({ name: 'dsh-sag-probe', version: '1.0.0' });
+    const transport = new StreamableHTTPClientTransport(new URL(descriptor.mcpUrl), {
+        requestInit: { headers: { Authorization: `Bearer ${descriptor.accessToken}` } },
+    });
+    let connected = false;
+    return {
+        async connect(signal) {
+            await client.connect(transport, { signal });
+            connected = true;
+        },
+        async listTools(signal) {
+            const response = await client.listTools({}, { signal });
+            return response.tools.map(tool => tool.name);
+        },
+        async close() {
+            if (connected)
+                await client.close();
+            else
+                await transport.close();
+        },
+    };
+}
+function compatible(names, advertisedCapabilities) {
+    const tools = [...names].sort();
+    const required = advertisedCapabilities === undefined ? ['list_sources', 'search'] : [
+        ...(advertisedCapabilities.includes('knowledge.search') ? ['search'] : []),
+    ];
+    for (const tool of required)
+        if (!tools.includes(tool))
+            throw new McpProbeIncompatibleError(`required tool ${tool} is missing`);
+    const readTool = tools.includes('read') ? 'read' : tools.includes('get_chunk') ? 'get_chunk' : undefined;
+    if ((advertisedCapabilities === undefined || advertisedCapabilities.includes('knowledge.read')) && readTool === undefined) {
+        throw new McpProbeIncompatibleError('required tool read or get_chunk is missing');
+    }
+    return { tools, ...(readTool === undefined ? {} : { readTool }) };
+}
+/** Initialize SAG MCP, verify retrieval tools, and require successful temporary-session closure. */
+export async function probeMcp(descriptor, signal, factory = productionSession, advertisedCapabilities) {
+    if (signal.aborted)
+        throw signal.reason;
+    const session = factory(descriptor);
+    let result;
+    let failure;
+    try {
+        await session.connect(signal);
+        result = compatible(await session.listTools(signal), advertisedCapabilities);
+    }
+    catch (error) {
+        failure = error instanceof McpProbeIncompatibleError
+            ? error
+            : new McpProbeUnreachableError(redacted(error, descriptor.accessToken));
+    }
+    try {
+        await session.close();
+    }
+    catch (error) {
+        const closeFailure = new McpProbeUnreachableError(`close failed: ${redacted(error, descriptor.accessToken)}`);
+        if (failure === undefined)
+            failure = closeFailure;
+    }
+    if (signal.aborted)
+        throw signal.reason;
+    if (failure !== undefined)
+        throw failure;
+    if (result === undefined)
+        throw new McpProbeUnreachableError('probe completed without a result');
+    return result;
+}
+//# sourceMappingURL=mcp-probe.js.map

package/lib/presentation.d.ts

@@ -0,0 +1,8 @@
+import type { ToolCallView } from '@deepseek-ai/dsh-tools/presentation';
+export declare function presentSearchCall(args: {
+    readonly query: string;
+}): ToolCallView;
+export declare function presentReadCall(args: {
+    readonly evidence_ref: string;
+}): ToolCallView;
+//# sourceMappingURL=presentation.d.ts.map

package/lib/presentation.js

@@ -0,0 +1,7 @@
+export function presentSearchCall(args) {
+    return { card: 'generic', title: 'Search SAG knowledge', kind: 'search', rawInput: args.query };
+}
+export function presentReadCall(args) {
+    return { card: 'generic', title: 'Read SAG evidence', kind: 'read', rawInput: args.evidence_ref };
+}
+//# sourceMappingURL=presentation.js.map

package/lib/runtime/client.d.ts

@@ -0,0 +1,22 @@
+import type { Readable, Writable } from 'node:stream';
+import { type RpcResult } from './protocol.js';
+/** Structured rejection returned by the Python runtime. */
+export declare class SagRuntimeError extends Error {
+    readonly name = "SagRuntimeError";
+    readonly code: string;
+    readonly data: Readonly<Record<string, unknown>>;
+    constructor(message: string, code: string, data: Readonly<Record<string, unknown>>);
+}
+/** Correlated JSON-RPC client over one managed sidecar's stdio streams. */
+export declare class SagRuntimeClient {
+    #private;
+    constructor(stdin: Writable, stdout: Readable, done: Promise<{
+        readonly exitCode: number | null;
+        readonly signal: NodeJS.Signals | null;
+    }>);
+    /** Send one request; cancellation remains live until the sidecar settles it. */
+    request(method: 'initialize' | 'search' | 'read' | 'shutdown', params: Readonly<Record<string, unknown>>, signal?: AbortSignal): Promise<RpcResult>;
+    /** Stop admission and close the protocol input. */
+    closeInput(): void;
+}
+//# sourceMappingURL=client.d.ts.map

package/lib/runtime/client.js

@@ -0,0 +1,117 @@
+import { SagProtocolError, decodeResponse, encodeRequest, } from './protocol.js';
+/** Structured rejection returned by the Python runtime. */
+export class SagRuntimeError extends Error {
+    name = 'SagRuntimeError';
+    code;
+    data;
+    constructor(message, code, data) {
+        super(message);
+        this.code = code;
+        this.data = data;
+    }
+}
+/** Correlated JSON-RPC client over one managed sidecar's stdio streams. */
+export class SagRuntimeClient {
+    #stdin;
+    #stdout;
+    #pending = new Map();
+    #decoder = new TextDecoder('utf-8', { fatal: true });
+    #buffer = '';
+    #nextId = 1;
+    #closedError;
+    constructor(stdin, stdout, done) {
+        this.#stdin = stdin;
+        this.#stdout = stdout;
+        stdout.on('data', (chunk) => this.#consume(chunk));
+        stdout.on('error', error => this.#failProtocol(error));
+        stdin.on('error', error => this.#failProtocol(error));
+        void done.then(outcome => this.#close(new Error(`SAG runtime exited (code=${outcome.exitCode ?? 'null'}, signal=${outcome.signal ?? 'null'})`)), error => this.#close(error instanceof Error ? error : new Error('SAG runtime spawn failed')));
+    }
+    /** Send one request; cancellation remains live until the sidecar settles it. */
+    request(method, params, signal) {
+        if (this.#closedError)
+            return Promise.reject(new Error(`SAG runtime client is closed: ${this.#closedError.message}`));
+        if (this.#nextId > Number.MAX_SAFE_INTEGER) {
+            this.#close(new Error('SAG runtime request id space exhausted'));
+            return Promise.reject(this.#closedError);
+        }
+        const id = this.#nextId++;
+        return new Promise((resolve, reject) => {
+            let cancelled = false;
+            const onAbort = () => {
+                if (cancelled || this.#closedError)
+                    return;
+                cancelled = true;
+                this.#stdin.write(encodeRequest({ jsonrpc: '2.0', method: '$/cancelRequest', params: { id } }));
+            };
+            const removeAbort = signal
+                ? () => signal.removeEventListener('abort', onAbort)
+                : undefined;
+            this.#pending.set(id, { resolve, reject, ...(removeAbort ? { removeAbort } : {}) });
+            if (signal) {
+                signal.addEventListener('abort', onAbort, { once: true });
+            }
+            const request = { jsonrpc: '2.0', id, method, params };
+            this.#stdin.write(encodeRequest(request));
+            if (signal?.aborted)
+                onAbort();
+        });
+    }
+    /** Stop admission and close the protocol input. */
+    closeInput() {
+        this.#stdin.end();
+    }
+    #consume(chunk) {
+        if (this.#closedError)
+            return;
+        try {
+            this.#buffer += typeof chunk === 'string'
+                ? chunk
+                : this.#decoder.decode(chunk, { stream: true });
+            let newline = this.#buffer.indexOf('\n');
+            while (newline >= 0) {
+                const line = this.#buffer.slice(0, newline).replace(/\r$/, '');
+                this.#buffer = this.#buffer.slice(newline + 1);
+                if (line)
+                    this.#acceptLine(line);
+                newline = this.#buffer.indexOf('\n');
+            }
+            if (Buffer.byteLength(this.#buffer, 'utf8') > 8 * 1024 * 1024) {
+                throw new SagProtocolError('response frame exceeds 8 MiB');
+            }
+        }
+        catch (error) {
+            this.#failProtocol(error);
+        }
+    }
+    #acceptLine(line) {
+        const response = decodeResponse(line);
+        const pending = this.#pending.get(response.id);
+        if (!pending)
+            throw new SagProtocolError(`response id ${response.id} is not live`);
+        this.#pending.delete(response.id);
+        pending.removeAbort?.();
+        if ('error' in response) {
+            const data = response.error.data ?? { code: 'RUNTIME_ERROR' };
+            pending.reject(new SagRuntimeError(response.error.message, data.code, data));
+        }
+        else {
+            pending.resolve(response.result);
+        }
+    }
+    #failProtocol(error) {
+        const message = error instanceof Error ? error.message : String(error);
+        this.#close(new SagProtocolError(`SAG runtime protocol failure: ${message}`));
+    }
+    #close(error) {
+        if (this.#closedError)
+            return;
+        this.#closedError = error;
+        for (const pending of this.#pending.values()) {
+            pending.removeAbort?.();
+            pending.reject(error);
+        }
+        this.#pending.clear();
+    }
+}
+//# sourceMappingURL=client.js.map

package/lib/runtime/protocol.d.ts

@@ -0,0 +1,113 @@
+import type { SagEvidenceRef, SagNamespaceId } from '../brand.ts';
+export declare const RPC_PROTOCOL_VERSION: "1.0";
+export declare const REQUIRED_ENGINE_VERSION: "0.10.0";
+export declare const MAX_FRAME_BYTES: number;
+export type RpcId = number;
+export type SearchMode = 'fast' | 'precise';
+export interface InitializeResult {
+    readonly protocolVersion: string;
+    readonly engineVersion: string;
+    readonly health: 'available' | 'degraded' | 'unavailable';
+    readonly evidenceRead: boolean;
+    readonly namespaces: readonly string[];
+}
+export interface SearchEvidence {
+    readonly evidenceRef: SagEvidenceRef;
+    readonly namespaceId: SagNamespaceId;
+    readonly sourceId: string;
+    readonly title: string;
+    readonly excerpt: string;
+    readonly score?: number;
+}
+export interface SearchResult {
+    readonly query: string;
+    readonly evidences: readonly SearchEvidence[];
+}
+export interface ReadEvent {
+    readonly id?: string;
+    readonly title?: string;
+    readonly summary?: string;
+    readonly category?: string;
+    readonly rank?: number;
+}
+export interface ReadResult {
+    readonly title: string;
+    readonly content: string;
+    readonly offset: number;
+    readonly nextOffset?: number;
+    readonly totalChars: number;
+    readonly events?: readonly ReadEvent[];
+}
+export interface RpcErrorData {
+    readonly code: string;
+    readonly operation?: string;
+    readonly stage?: string;
+    readonly retryable?: boolean;
+    readonly provider?: string;
+    readonly itemId?: string;
+    readonly message?: string;
+    readonly details?: Readonly<Record<string, unknown>>;
+}
+export interface RpcError {
+    readonly code: number;
+    readonly message: string;
+    readonly data?: RpcErrorData;
+}
+export type RpcResult = InitializeResult | SearchResult | ReadResult | Readonly<Record<string, never>>;
+export type RpcResponse = {
+    readonly jsonrpc: '2.0';
+    readonly id: RpcId;
+    readonly result: RpcResult;
+} | {
+    readonly jsonrpc: '2.0';
+    readonly id: RpcId;
+    readonly error: RpcError;
+};
+export type RpcRequest = {
+    readonly jsonrpc: '2.0';
+    readonly id: RpcId;
+    readonly method: 'initialize';
+    readonly params: {
+        readonly protocolVersion: '1.0';
+    };
+} | {
+    readonly jsonrpc: '2.0';
+    readonly id: RpcId;
+    readonly method: 'search';
+    readonly params: {
+        readonly query: string;
+        readonly namespaces: readonly string[];
+        readonly mode: SearchMode;
+        readonly limit: number;
+    };
+} | {
+    readonly jsonrpc: '2.0';
+    readonly id: RpcId;
+    readonly method: 'read';
+    readonly params: {
+        readonly evidenceRef: string;
+        readonly offset: number;
+        readonly maxChars: number;
+        readonly includeEvents: boolean;
+    };
+} | {
+    readonly jsonrpc: '2.0';
+    readonly id: RpcId;
+    readonly method: 'shutdown';
+    readonly params: Readonly<Record<string, never>>;
+} | {
+    readonly jsonrpc: '2.0';
+    readonly method: '$/cancelRequest';
+    readonly params: {
+        readonly id: RpcId;
+    };
+};
+/** A safe protocol failure that identifies only the frame correlation point. */
+export declare class SagProtocolError extends Error {
+    readonly name = "SagProtocolError";
+}
+/** Decode and validate one JSON-RPC response frame from the Python process. */
+export declare function decodeResponse(line: string): RpcResponse;
+/** Encode one validated request as a single NDJSON frame. */
+export declare function encodeRequest(request: RpcRequest): string;
+//# sourceMappingURL=protocol.d.ts.map

package/lib/runtime/protocol.js

@@ -0,0 +1,118 @@
+import { Buffer } from 'node:buffer';
+export const RPC_PROTOCOL_VERSION = '1.0';
+export const REQUIRED_ENGINE_VERSION = '0.10.0';
+export const MAX_FRAME_BYTES = 8 * 1024 * 1024;
+/** A safe protocol failure that identifies only the frame correlation point. */
+export class SagProtocolError extends Error {
+    name = 'SagProtocolError';
+}
+function object(value, label) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new SagProtocolError(`${label} must be an object`);
+    }
+    return value;
+}
+function exactKeys(value, required, optional, label) {
+    const allowed = new Set([...required, ...optional]);
+    if (required.some(key => !(key in value)) || Object.keys(value).some(key => !allowed.has(key))) {
+        throw new SagProtocolError(`${label} contains invalid fields`);
+    }
+}
+function validId(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+function validateResult(value, id) {
+    const result = object(value, `response id ${id} result`);
+    const keys = Object.keys(result);
+    if (keys.length === 0)
+        return {};
+    if ('protocolVersion' in result) {
+        exactKeys(result, ['protocolVersion', 'engineVersion', 'health', 'evidenceRead', 'namespaces'], [], `response id ${id} initialize result`);
+        if (typeof result.protocolVersion !== 'string' || typeof result.engineVersion !== 'string'
+            || !['available', 'degraded', 'unavailable'].includes(String(result.health))
+            || typeof result.evidenceRead !== 'boolean'
+            || !Array.isArray(result.namespaces) || !result.namespaces.every(item => typeof item === 'string')) {
+            throw new SagProtocolError(`response id ${id} initialize result is invalid`);
+        }
+        return result;
+    }
+    if ('evidences' in result) {
+        exactKeys(result, ['query', 'evidences'], [], `response id ${id} search result`);
+        if (typeof result.query !== 'string' || !Array.isArray(result.evidences)) {
+            throw new SagProtocolError(`response id ${id} search result is invalid`);
+        }
+        for (const raw of result.evidences) {
+            const evidence = object(raw, `response id ${id} evidence`);
+            exactKeys(evidence, ['evidenceRef', 'namespaceId', 'sourceId', 'title', 'excerpt'], ['score'], `response id ${id} evidence`);
+            if (['evidenceRef', 'namespaceId', 'sourceId', 'title', 'excerpt'].some(key => typeof evidence[key] !== 'string')
+                || ('score' in evidence && typeof evidence.score !== 'number')) {
+                throw new SagProtocolError(`response id ${id} evidence is invalid`);
+            }
+        }
+        return result;
+    }
+    if ('content' in result) {
+        exactKeys(result, ['title', 'content', 'offset', 'totalChars'], ['nextOffset', 'events'], `response id ${id} read result`);
+        if (typeof result.title !== 'string' || typeof result.content !== 'string'
+            || !Number.isSafeInteger(result.offset) || result.offset < 0
+            || !Number.isSafeInteger(result.totalChars) || result.totalChars < 0
+            || ('nextOffset' in result && (!Number.isSafeInteger(result.nextOffset) || result.nextOffset < 0))
+            || ('events' in result && !Array.isArray(result.events))) {
+            throw new SagProtocolError(`response id ${id} read result is invalid`);
+        }
+        return result;
+    }
+    throw new SagProtocolError(`response id ${id} result contains invalid fields`);
+}
+/** Decode and validate one JSON-RPC response frame from the Python process. */
+export function decodeResponse(line) {
+    if (Buffer.byteLength(line, 'utf8') > MAX_FRAME_BYTES) {
+        throw new SagProtocolError('response frame exceeds 8 MiB');
+    }
+    let raw;
+    try {
+        raw = JSON.parse(line);
+    }
+    catch {
+        throw new SagProtocolError('response frame is not valid JSON');
+    }
+    const response = object(raw, 'response');
+    const idLabel = validId(response.id) ? ` id ${response.id}` : '';
+    exactKeys(response, ['jsonrpc', 'id'], ['result', 'error'], `response${idLabel}`);
+    if (response.jsonrpc !== '2.0' || !validId(response.id)) {
+        throw new SagProtocolError(`response${idLabel} has invalid JSON-RPC metadata`);
+    }
+    if (('result' in response) === ('error' in response)) {
+        throw new SagProtocolError(`response id ${response.id} must contain exactly one of result or error`);
+    }
+    if ('result' in response) {
+        return { jsonrpc: '2.0', id: response.id, result: validateResult(response.result, response.id) };
+    }
+    const error = object(response.error, `response id ${response.id} error`);
+    exactKeys(error, ['code', 'message'], ['data'], `response id ${response.id} error`);
+    if (!Number.isInteger(error.code) || typeof error.message !== 'string') {
+        throw new SagProtocolError(`response id ${response.id} error is invalid`);
+    }
+    let data;
+    if ('data' in error) {
+        const rawData = object(error.data, `response id ${response.id} error data`);
+        exactKeys(rawData, ['code'], ['operation', 'stage', 'retryable', 'provider', 'itemId', 'message', 'details'], `response id ${response.id} error data`);
+        if (typeof rawData.code !== 'string')
+            throw new SagProtocolError(`response id ${response.id} error data is invalid`);
+        data = rawData;
+    }
+    return {
+        jsonrpc: '2.0',
+        id: response.id,
+        error: { code: error.code, message: error.message, ...(data ? { data } : {}) },
+    };
+}
+/** Encode one validated request as a single NDJSON frame. */
+export function encodeRequest(request) {
+    const line = `${JSON.stringify(request)}\n`;
+    if (Buffer.byteLength(line, 'utf8') > MAX_FRAME_BYTES) {
+        throw new SagProtocolError('request frame exceeds 8 MiB');
+    }
+    return line;
+}
+//# sourceMappingURL=protocol.js.map

package/lib/runtime/supervisor.d.ts

@@ -0,0 +1,30 @@
+import type { SubprocessRuntime } from '@deepseek-ai/dsh-subprocess';
+import { SagRuntimeClient } from './client.js';
+export interface SupervisorConfig {
+    readonly pythonCommand: string;
+    readonly envFile: string;
+    readonly cwd: string;
+    readonly namespaces: readonly {
+        readonly id: string;
+        readonly label: string;
+    }[];
+    readonly maxReadEngines: number;
+    readonly maxResults: number;
+    readonly maxSnippetChars: number;
+    readonly maxReadChars: number;
+    readonly shutdownGraceMs: number;
+    readonly allowDegraded: boolean;
+}
+type RuntimeLauncher = Pick<SubprocessRuntime, 'resolveExecutable' | 'spawn'>;
+/** Owns one Python sidecar from executable resolution through tree quiescence. */
+export declare class SagRuntimeSupervisor {
+    #private;
+    readonly client: SagRuntimeClient;
+    private constructor();
+    /** Spawn and verify a sidecar before exposing its client to tool registration. */
+    static start(runtime: RuntimeLauncher, config: SupervisorConfig): Promise<SagRuntimeSupervisor>;
+    /** Gracefully stop admission, then escalate through the managed process seam. */
+    dispose(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=supervisor.d.ts.map

package/lib/runtime/supervisor.js

@@ -0,0 +1,107 @@
+import { SagRuntimeClient } from './client.js';
+import { REQUIRED_ENGINE_VERSION, RPC_PROTOCOL_VERSION, } from './protocol.js';
+function initializeResult(result) {
+    if (!('protocolVersion' in result) || !('engineVersion' in result) || !('namespaces' in result)) {
+        throw new Error('SAG runtime initialize returned the wrong result type');
+    }
+    return result;
+}
+/** Owns one Python sidecar from executable resolution through tree quiescence. */
+export class SagRuntimeSupervisor {
+    client;
+    #handle;
+    #graceMs;
+    #disposed = false;
+    constructor(handle, client, graceMs) {
+        this.#handle = handle;
+        this.client = client;
+        this.#graceMs = graceMs;
+    }
+    /** Spawn and verify a sidecar before exposing its client to tool registration. */
+    static async start(runtime, config) {
+        const python = await runtime.resolveExecutable(config.pythonCommand, { PYTHONUNBUFFERED: '1' });
+        const namespaceArgs = config.namespaces.flatMap(namespace => ['--namespace', namespace.id]);
+        const handle = runtime.spawn({
+            argv: [
+                python,
+                '-m',
+                'dsh_sag_runtime',
+                '--env-file',
+                config.envFile,
+                ...namespaceArgs,
+                '--max-read-engines',
+                String(config.maxReadEngines),
+                '--max-results',
+                String(config.maxResults),
+                '--max-excerpt-chars',
+                String(config.maxSnippetChars),
+                '--max-read-chars',
+                String(config.maxReadChars),
+            ],
+            cwd: config.cwd,
+            stdio: {
+                stdin: 'pipe',
+                stdout: 'pipe',
+                stderr: { maxBytes: 64 * 1024 },
+            },
+            graceMs: config.shutdownGraceMs,
+            env: { PYTHONUNBUFFERED: '1' },
+        });
+        if (!handle.stdin || !handle.stdout) {
+            handle.terminate();
+            throw new Error('SAG runtime did not expose piped stdin/stdout');
+        }
+        const client = new SagRuntimeClient(handle.stdin, handle.stdout, handle.done);
+        const supervisor = new SagRuntimeSupervisor(handle, client, config.shutdownGraceMs);
+        try {
+            const ready = initializeResult(await client.request('initialize', { protocolVersion: RPC_PROTOCOL_VERSION }));
+            if (ready.protocolVersion !== RPC_PROTOCOL_VERSION) {
+                throw new Error(`SAG runtime protocol ${RPC_PROTOCOL_VERSION} is required`);
+            }
+            if (ready.engineVersion !== REQUIRED_ENGINE_VERSION) {
+                throw new Error(`zleap-sag ${REQUIRED_ENGINE_VERSION} is required; sidecar reported ${ready.engineVersion}`);
+            }
+            if (!ready.evidenceRead)
+                throw new Error('SAG runtime does not support evidence reads');
+            const expectedNamespaces = config.namespaces.map(namespace => namespace.id);
+            if (JSON.stringify(ready.namespaces) !== JSON.stringify(expectedNamespaces)) {
+                throw new Error('SAG runtime namespace handshake does not match plugin configuration');
+            }
+            if (ready.health === 'unavailable' || (ready.health === 'degraded' && !config.allowDegraded)) {
+                throw new Error(`SAG runtime health is ${ready.health}`);
+            }
+            return supervisor;
+        }
+        catch (error) {
+            handle.terminate();
+            client.closeInput();
+            await handle.waitForExit();
+            throw error;
+        }
+    }
+    /** Gracefully stop admission, then escalate through the managed process seam. */
+    async dispose() {
+        if (this.#disposed)
+            return;
+        this.#disposed = true;
+        let timer;
+        const timeout = new Promise(resolve => {
+            timer = setTimeout(() => resolve('timeout'), this.#graceMs);
+        });
+        const shutdown = this.client.request('shutdown', {}).then(() => 'shutdown');
+        const outcome = await Promise.race([shutdown, timeout]).catch(() => 'failure');
+        if (timer)
+            clearTimeout(timer);
+        this.client.closeInput();
+        if (outcome !== 'shutdown')
+            this.#handle.terminate();
+        const signal = AbortSignal.timeout(this.#graceMs);
+        const exited = await this.#handle.waitForExit(signal);
+        if (!exited) {
+            this.#handle.terminate();
+            await this.#handle.waitForExit();
+        }
+        await this.#handle.done;
+    }
+}
+//# sourceMappingURL=supervisor.js.map

package/lib/tools/documents.d.ts

@@ -0,0 +1,8 @@
+import type { ToolExecution, PreToolDecision } from '@deepseek-ai/dsh-tools';
+import type { ResolvedLocalConfig } from '../config.js';
+import { type ConnectionManager } from './local.js';
+/** Require user approval for irreversible SAG document deletion. */
+export declare function sagDeleteApprovalGate(exec: Pick<ToolExecution, 'name'>, next: () => Promise<PreToolDecision>): Promise<PreToolDecision>;
+/** Build local SAG document inspection, reprocessing, and deletion tools. */
+export declare function createDocumentTools(manager: ConnectionManager, config: ResolvedLocalConfig): readonly [import("@deepseek-ai/dsh-tools").ToolDefinition, import("@deepseek-ai/dsh-tools").ToolDefinition, import("@deepseek-ai/dsh-tools").ToolDefinition, import("@deepseek-ai/dsh-tools").ToolDefinition];
+//# sourceMappingURL=documents.d.ts.map