dsh-agy-cli 0.0.0-stage → 0.12.0

package/lib/mcp/protocol.js

@@ -0,0 +1,197 @@
+/**
+ * Minimal MCP (Model Context Protocol) server-side JSON-RPC layer.
+ *
+ * DSH ships `@modelcontextprotocol/core`, but that package exports only Zod
+ * schemas — it has no `Server` class and no transport. The framing and the
+ * three methods AGY actually needs are implemented here, deliberately small:
+ * a session-based server (one session per AGY conversation) over newline
+ * delimited JSON-RPC 2.0.
+ *
+ * Wire compatibility notes learned from AGY 1.3.2:
+ * - the negotiated protocol version is echoed back from the client, because
+ *   AGY rejects a server that answers with a version it did not offer;
+ * - a JSON-RPC *notification* (no `id`) must never be answered;
+ * - tool failures travel as a normal `tools/call` result with `isError: true`
+ *   so the model can react to them instead of seeing a transport error.
+ */
+export const MCP_PROTOCOL_VERSION = '2025-06-18';
+export const MCP_SUPPORTED_PROTOCOL_VERSIONS = ['2025-06-18', '2025-03-26', '2024-11-05'];
+export const MCP_ERROR_CODES = Object.freeze({
+    parseError: -32700,
+    invalidRequest: -32600,
+    methodNotFound: -32601,
+    invalidParams: -32602,
+    internalError: -32603,
+});
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** Pick the highest protocol version both sides understand. */
+export function negotiateProtocolVersion(requested) {
+    if (typeof requested === 'string' && MCP_SUPPORTED_PROTOCOL_VERSIONS.includes(requested)) {
+        return requested;
+    }
+    return MCP_PROTOCOL_VERSION;
+}
+/**
+ * One MCP server instance. It is transport agnostic: `handleMessage` takes one
+ * decoded JSON-RPC message and returns the response to write back, or
+ * `undefined` for notifications.
+ */
+export class McpServerSession {
+    handlers;
+    initialized = false;
+    clientInfo;
+    sessionHandle = '';
+    constructor(handlers) {
+        this.handlers = handlers;
+    }
+    get isInitialized() {
+        return this.initialized;
+    }
+    get client() {
+        return this.clientInfo;
+    }
+    async handleMessage(raw, sessionHandle = '') {
+        this.sessionHandle = sessionHandle;
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            // JSON-RPC 2.0: an unparseable body has no recoverable id, so the answer
+            // carries `id: null`, not a fabricated 0.
+            return {
+                jsonrpc: '2.0',
+                id: null,
+                error: { code: MCP_ERROR_CODES.parseError, message: 'Parse error: body is not valid JSON' },
+            };
+        }
+        if (!isRecord(parsed) || parsed.jsonrpc !== '2.0' || typeof parsed.method !== 'string') {
+            return {
+                jsonrpc: '2.0',
+                id: isRecord(parsed) && (typeof parsed.id === 'string' || typeof parsed.id === 'number') ? parsed.id : null,
+                error: { code: MCP_ERROR_CODES.invalidRequest, message: 'Invalid Request' },
+            };
+        }
+        const id = parsed.id;
+        const isRequest = typeof id === 'string' || typeof id === 'number';
+        try {
+            const result = await this.dispatch(parsed.method, isRecord(parsed.params) ? parsed.params : {});
+            // Notifications carry no id and must not be answered.
+            if (!isRequest)
+                return undefined;
+            if (result === NOTIFICATION)
+                return undefined;
+            return { jsonrpc: '2.0', id, result };
+        }
+        catch (error) {
+            if (!isRequest)
+                return undefined;
+            if (error instanceof McpRpcError) {
+                return { jsonrpc: '2.0', id, error: { code: error.code, message: error.message, ...(error.data === undefined ? {} : { data: error.data }) } };
+            }
+            return {
+                jsonrpc: '2.0',
+                id,
+                error: { code: MCP_ERROR_CODES.internalError, message: errorMessage(error) },
+            };
+        }
+    }
+    async dispatch(method, params) {
+        switch (method) {
+            case 'initialize':
+                return this.initialize(params);
+            case 'notifications/initialized':
+            case 'notifications/cancelled':
+            case 'notifications/roots/list_changed':
+                return NOTIFICATION;
+            case 'ping':
+                return {};
+            case 'tools/list':
+                return { tools: await this.handlers.listTools(this.resolveSession(params)) };
+            case 'tools/call':
+                return this.callTool(params);
+            default:
+                throw new McpRpcError(MCP_ERROR_CODES.methodNotFound, `Method not found: ${method}`);
+        }
+    }
+    initialize(params) {
+        this.initialized = true;
+        const clientInfo = params.clientInfo;
+        this.clientInfo = isRecord(clientInfo)
+            ? {
+                ...(typeof clientInfo.name === 'string' ? { name: clientInfo.name } : {}),
+                ...(typeof clientInfo.version === 'string' ? { version: clientInfo.version } : {}),
+            }
+            : undefined;
+        return {
+            protocolVersion: negotiateProtocolVersion(params.protocolVersion),
+            capabilities: { tools: { listChanged: false } },
+            serverInfo: { name: this.handlers.serverName, version: this.handlers.serverVersion },
+            instructions: this.handlers.instructions,
+        };
+    }
+    async callTool(params) {
+        const name = params.name;
+        if (typeof name !== 'string' || name.length === 0) {
+            throw new McpRpcError(MCP_ERROR_CODES.invalidParams, 'tools/call requires a tool name');
+        }
+        const rawArguments = params.arguments;
+        if (rawArguments !== undefined && !isRecord(rawArguments)) {
+            throw new McpRpcError(MCP_ERROR_CODES.invalidParams, 'tools/call arguments must be an object');
+        }
+        try {
+            return await this.handlers.callTool(this.resolveSession(params), name, rawArguments ?? {});
+        }
+        catch (error) {
+            // A failing DSH tool is an expected outcome, not a protocol error: the
+            // model has to see the failure text to decide what to do next.
+            return { content: [{ type: 'text', text: errorMessage(error) }], isError: true };
+        }
+    }
+    /**
+     * Resolve which AGY conversation a request belongs to. The transport-level
+     * handle (the secret path segment) wins, because it is what the endpoint
+     * minted for this bridge; `_meta.sessionId` is the client's own hint and is
+     * used only when the transport supplies nothing.
+     */
+    resolveSession(params) {
+        if (this.sessionHandle.length > 0)
+            return this.sessionHandle;
+        return sessionOf(params);
+    }
+}
+const NOTIFICATION = Symbol('mcp-notification');
+export class McpRpcError extends Error {
+    code;
+    data;
+    constructor(code, message, data) {
+        super(message);
+        this.name = 'McpRpcError';
+        this.code = code;
+        this.data = data;
+    }
+}
+/**
+ * AGY passes its own session handle as `_meta.sessionId` on every request; the
+ * HTTP route also carries it in the path. Both are read here so one server can
+ * serve several concurrent AGY conversations.
+ */
+function sessionOf(params) {
+    const meta = params._meta;
+    if (isRecord(meta)) {
+        const sessionId = meta.sessionId ?? meta.session_id;
+        if (typeof sessionId === 'string' && sessionId.length > 0)
+            return sessionId;
+    }
+    return '';
+}
+/** Serialize one response as a single newline-terminated JSON-RPC frame. */
+export function encodeMcpFrame(response) {
+    return `${JSON.stringify(response)}\n`;
+}
+//# sourceMappingURL=protocol.js.map

package/lib/mcp/tool-projection.d.ts

@@ -0,0 +1,64 @@
+import type { McpToolDescriptor } from './protocol.js';
+/** The subset of `ctx.tools` this module needs. */
+export interface DshToolRegistryLike {
+    schemas(scope?: unknown): readonly unknown[];
+}
+export interface DshToolSchemaLike {
+    readonly name?: unknown;
+    readonly description?: unknown;
+    readonly parameters?: unknown;
+}
+export interface ToolProjectionOptions {
+    /** Restrict the projection to these tool names (empty/absent = every tool). */
+    readonly allowlist?: readonly string[];
+    /** Upper bound on projected tools; guards a pathological registry. */
+    readonly maxTools?: number;
+    /**
+     * The viewing scope, i.e. the live agent of the DSH session the bridge serves.
+     * This is load-bearing: `ctx.tools.schemas()` with no scope answers with the
+     * GLOBAL view, and `read`/`write`/`grep`/`pwsh` are no longer in the global
+     * layer — the official presets moved them onto the agent plane, so they reach
+     * a scope only as ancestor contributions. A scope-less projection therefore
+     * hands AGY the UI/memory tools and silently drops every file and shell tool.
+     */
+    readonly scope?: unknown;
+}
+export interface ToolProjectionResult {
+    readonly tools: readonly McpToolDescriptor[];
+    /**
+     * Names dropped by the allowlist, the built-in exclusions, or the cap. The
+     * caller cannot tell those three apart from this list alone, which is why the
+     * bridge filters the built-ins out before it reports what the model is
+     * missing: a cap overflow has to be visible in the log, and for two rounds it
+     * was not.
+     */
+    readonly excluded: readonly string[];
+}
+/**
+ * Tools that must never be projected to AGY. These are either DSH-internal
+ * controls that would let AGY steer its own host, or tools whose execution
+ * requires a DSH agent identity that an MCP-originated call does not carry.
+ *
+ * Exported so the bridge can tell "dropped on purpose" apart from "dropped by
+ * the cap" when it reports what the model is missing.
+ */
+export declare const NEVER_PROJECTED_TOOLS: ReadonlySet<string>;
+/**
+ * Project the registry. `listChanged: false` is advertised to AGY, so the set
+ * is snapshotted per request rather than pushed; a profile change simply takes
+ * effect on the next turn.
+ */
+/**
+ * Check a call's arguments against the projected schema, mechanically.
+ *
+ * AGY does not honour `required` and sometimes sends the wrong primitive
+ * (`{"query":123}` for a string field, `{}` for a call that needs one). Left
+ * unchecked, every such call still walks the host guard chain and the approval
+ * service before the schema layer rejects it — so the bridge answers first, with
+ * the same wording the host uses. Anything this function cannot decide
+ * (unknown property, no declared type) is left to DSH: a bridge that guesses
+ * would be a second, weaker validator pretending to be the real one.
+ */
+export declare function validateToolArguments(schema: unknown, args: unknown): string[];
+export declare function projectDshTools(registry: DshToolRegistryLike | undefined, options?: ToolProjectionOptions): ToolProjectionResult;
+//# sourceMappingURL=tool-projection.d.ts.map

package/lib/mcp/tool-projection.js

@@ -0,0 +1,168 @@
+/**
+ * Project the live DSH tool registry into MCP tool descriptors.
+ *
+ * This is the replacement for the old DSH-owned prompt contract: instead of
+ * serializing every tool schema into the prompt (58 KB on a stock profile with
+ * 18 bundles, which the 56 KiB prompt budget could not hold), the same schemas
+ * travel over MCP and cost zero prompt bytes.
+ *
+ * The schemas are sanitized by `sanitizeSchema` from the structured tool
+ * protocol, so MCP exposure and the legacy envelope agree on exactly which
+ * JSON Schema keywords are allowed to leave the host.
+ */
+import { sanitizeSchema, TOOL_PROTOCOL_LIMITS } from '../provider/tool-protocol.js';
+/**
+ * Tools that must never be projected to AGY. These are either DSH-internal
+ * controls that would let AGY steer its own host, or tools whose execution
+ * requires a DSH agent identity that an MCP-originated call does not carry.
+ *
+ * Exported so the bridge can tell "dropped on purpose" apart from "dropped by
+ * the cap" when it reports what the model is missing.
+ */
+export const NEVER_PROJECTED_TOOLS = new Set([
+    'compress',
+    'decompress',
+    'search_context',
+    'acp_status',
+    'acp_cache',
+]);
+const FALLBACK_SCHEMA = Object.freeze({
+    type: 'object',
+    properties: {},
+    additionalProperties: false,
+});
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function readSchemaName(value) {
+    if (!isRecord(value))
+        return undefined;
+    const name = value.name;
+    return typeof name === 'string' && name.length > 0 ? name : undefined;
+}
+/**
+ * Project the registry. `listChanged: false` is advertised to AGY, so the set
+ * is snapshotted per request rather than pushed; a profile change simply takes
+ * effect on the next turn.
+ */
+/**
+ * Check a call's arguments against the projected schema, mechanically.
+ *
+ * AGY does not honour `required` and sometimes sends the wrong primitive
+ * (`{"query":123}` for a string field, `{}` for a call that needs one). Left
+ * unchecked, every such call still walks the host guard chain and the approval
+ * service before the schema layer rejects it — so the bridge answers first, with
+ * the same wording the host uses. Anything this function cannot decide
+ * (unknown property, no declared type) is left to DSH: a bridge that guesses
+ * would be a second, weaker validator pretending to be the real one.
+ */
+export function validateToolArguments(schema, args) {
+    if (!isRecord(schema) || schema.type !== 'object')
+        return [];
+    const problems = [];
+    const given = isRecord(args) ? args : undefined;
+    if (given === undefined) {
+        return [`arguments must be an object, got ${Array.isArray(args) ? 'array' : typeof args}`];
+    }
+    const required = Array.isArray(schema.required) ? schema.required : [];
+    for (const key of required) {
+        if (typeof key !== 'string')
+            continue;
+        if (given[key] === undefined)
+            problems.push(`missing required property "${key}"`);
+    }
+    const properties = isRecord(schema.properties) ? schema.properties : undefined;
+    if (properties !== undefined) {
+        for (const [key, value] of Object.entries(given)) {
+            const declared = properties[key];
+            if (!isRecord(declared) || value === undefined || value === null)
+                continue;
+            const expected = declared.type;
+            if (typeof expected !== 'string')
+                continue;
+            if (!matchesJsonType(value, expected)) {
+                problems.push(`"${key}" must be ${expectedDescriptionOf(expected)}, got ${typeof value}`);
+            }
+        }
+    }
+    return problems;
+}
+function matchesJsonType(value, expected) {
+    switch (expected) {
+        case 'string': return typeof value === 'string';
+        case 'number': return typeof value === 'number';
+        case 'integer': return typeof value === 'number' && Number.isInteger(value);
+        case 'boolean': return typeof value === 'boolean';
+        case 'array': return Array.isArray(value);
+        case 'object': return isRecord(value);
+        default: return true;
+    }
+}
+function expectedDescriptionOf(expected) {
+    switch (expected) {
+        case 'integer': return 'an integer';
+        case 'array': return 'an array';
+        default: return `a ${expected}`;
+    }
+}
+export function projectDshTools(registry, options = {}) {
+    const excluded = [];
+    const maxTools = options.maxTools ?? TOOL_PROTOCOL_LIMITS.maxTools;
+    if (registry === undefined || typeof registry.schemas !== 'function') {
+        return { tools: [], excluded };
+    }
+    let raw;
+    try {
+        raw = registry.schemas(options.scope) ?? [];
+    }
+    catch {
+        return { tools: [], excluded };
+    }
+    const allow = options.allowlist === undefined || options.allowlist.length === 0
+        ? undefined
+        : new Set(options.allowlist);
+    const seen = new Set();
+    const tools = [];
+    for (const entry of raw) {
+        const name = readSchemaName(entry);
+        if (name === undefined)
+            continue;
+        if (seen.has(name))
+            continue;
+        seen.add(name);
+        if (NEVER_PROJECTED_TOOLS.has(name)) {
+            excluded.push(name);
+            continue;
+        }
+        if (allow !== undefined && !allow.has(name)) {
+            excluded.push(name);
+            continue;
+        }
+        if (tools.length >= maxTools) {
+            excluded.push(name);
+            continue;
+        }
+        const source = entry;
+        let parameters;
+        try {
+            const sanitized = sanitizeSchema(source.parameters, 0, `tool ${name}.parameters`);
+            parameters = isRecord(sanitized) && sanitized.type === 'object' ? sanitized : { ...FALLBACK_SCHEMA };
+        }
+        catch {
+            // An unsupported keyword must not remove a working tool from the model's
+            // view; fall back to an open object and let DSH validate the arguments.
+            parameters = { ...FALLBACK_SCHEMA };
+        }
+        const description = typeof source.description === 'string' ? source.description : '';
+        tools.push({
+            name,
+            description: description.length > TOOL_PROTOCOL_LIMITS.maxDescriptionLength
+                ? description.slice(0, TOOL_PROTOCOL_LIMITS.maxDescriptionLength)
+                : description,
+            inputSchema: parameters,
+        });
+    }
+    tools.sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0));
+    return { tools, excluded };
+}
+//# sourceMappingURL=tool-projection.js.map

package/lib/provider/agy.d.ts

@@ -0,0 +1,153 @@
+import type { AttachmentStore } from '@deepseek-ai/dsh-attachment';
+import { LlmAdapter } from '@deepseek-ai/dsh-llm';
+import type { GenerateOptions, LlmModelInfo, LlmProviderInfo, LlmResolvedModelInfo, StreamChunk, TokenUsage, ResolvedRetryPolicy } from '@deepseek-ai/dsh-llm';
+import { type PersistentTransportResult } from '../agy/persistent-transport.js';
+import { type AgyReasoningEffort, type AgyRequest, type ProcessResult } from '../agy/process.js';
+import { type AgyModelDiscoveryCommand, type AgyModelDiscoveryResult } from '../agy/models.js';
+import { type AgyDiagnosticResult } from '../agy/diagnostics.js';
+import { AgyConcurrencyLimiter } from '../agy/limiter.js';
+import { type AgyLogger } from '../agy/log.js';
+import { type Config, type ModelConfig } from './config.js';
+import { SessionRegistry, type SessionRecord } from '../session/store.js';
+import { type DshContextLookup } from '../dsh/context.js';
+export type AgyProcessRunner = (request: AgyRequest) => Promise<ProcessResult>;
+export interface AgyAdapterDependencies {
+    /** Injectable seam for deterministic tests; production uses `runAgyProcess`. */
+    runAgyProcess?: AgyProcessRunner;
+    /** Injectable quota-free `agy models` command for deterministic tests. */
+    runModelDiscovery?: AgyModelDiscoveryCommand;
+    /** Injectable session mapping; production uses the durable file-backed store. */
+    sessionRegistry?: SessionRegistry;
+    /** Optional structured logger; logging failures never affect the request. */
+    logger?: AgyLogger;
+    /** Injectable process limiter for deterministic concurrency tests. */
+    concurrencyLimiter?: AgyConcurrencyLimiter;
+    /** Optional DSH AttachmentStore; text-only requests do not require it. */
+    attachmentStore?: Pick<AttachmentStore, 'readImage'>;
+    /** Lazy resolver for runtimes that compose the optional store after this plugin. */
+    resolveAttachmentStore?: () => Pick<AttachmentStore, 'readImage'> | undefined;
+    /**
+     * Injectable seam for deterministic tests of the persistent path; production
+     * leaves it undefined and the transport is built from the resolved AGY
+     * executable.
+     */
+    persistentTransport?: PersistentTransportLike;
+    /** Optional Cordis reflection seam for the DSH-owned capability context. */
+    dshContext?: DshContextLookup;
+    /**
+     * Resolves the live MCP tool bridge, if the composition has one. Lazy
+     * because the bridge is mounted on the host webServer and its fiber may
+     * start after this adapter is constructed.
+     */
+    resolveToolBridge?: () => DshToolBridgeHandle | undefined;
+}
+/**
+ * The slice of the persistent transport the adapter needs. Declared
+ * structurally so tests can drive the streaming path without a real AGY
+ * worker process.
+ */
+export interface PersistentTransportLike {
+    request(input: {
+        readonly sessionId: string;
+        readonly text: string;
+        readonly signal?: AbortSignal;
+        readonly timeoutMs?: number;
+        readonly idleTimeoutMs?: number;
+        readonly maxOutputBytes?: number;
+        readonly onEvent?: (payload: unknown) => void;
+        readonly agent?: string;
+        readonly model?: string;
+        readonly reasoningEffort?: AgyReasoningEffort;
+        readonly conversation?: string;
+        readonly extraArgs?: readonly string[];
+    }): Promise<PersistentTransportResult>;
+}
+/**
+ * The slice of the MCP tool bridge the adapter needs. Declared structurally so
+ * the provider never imports the bridge module's host-service types.
+ */
+export interface DshToolBridgeHandle {
+    readonly active: boolean;
+    readonly inactiveReason: string | undefined;
+    /** Point the bridge at the DSH session owning the next AGY turn. */
+    readonly setSession: (sessionId: string) => void;
+    /** URL AGY reaches the bridge on; undefined until the bridge is live. */
+    readonly url: string | undefined;
+}
+/** Convert AGY's observed snake/camel-case usage variants to DSH accounting. */
+export declare function mapAgyUsage(raw: Record<string, unknown>): TokenUsage;
+export declare const __effortOverrideCacheForTest: {
+    at: number;
+    value: AgyReasoningEffort | undefined;
+};
+/** DSH text-only adapter backed by the locally authenticated AGY CLI. */
+export declare class AgyAdapter extends LlmAdapter {
+    private readonly model;
+    private readonly models;
+    private readonly agent;
+    private readonly workspaceRoot;
+    private readonly addDirs;
+    private readonly mode;
+    private readonly disableSlashCommands;
+    private readonly toolPolicy;
+    private readonly dshContext;
+    private readonly agyPath;
+    private readonly timeoutMs;
+    private readonly idleTimeoutMs;
+    private readonly stdinMode;
+    private readonly run;
+    private readonly sessionMode;
+    private readonly sessions;
+    private readonly minimumAgyVersion;
+    private readonly limiter;
+    private readonly logger;
+    private readonly maxOutputBytes;
+    private readonly maxEventLineLength;
+    private readonly inputFrameLimitBytes;
+    private readonly maxSingleToolResultBytes;
+    private readonly maxHistoricalToolResultBytes;
+    private readonly toolProtocolRepairRetries;
+    private readonly toolProtocolPlainTextFallback;
+    private readonly retryPolicy;
+    private readonly purposeRoutes;
+    private readonly transport;
+    private readonly persistentIdleTtlMs;
+    private readonly persistentReadyTimeoutMs;
+    private readonly persistentFallback;
+    private readonly persistentTransport;
+    private readonly imageInput;
+    private readonly imageAgent;
+    private readonly resolveAttachmentStore;
+    private readonly resolveToolBridge;
+    private readonly mcpBridgeEnabled;
+    private readonly discovery;
+    private readonly visibleModels;
+    private currentModels;
+    private modelDiscoveryResult;
+    constructor(config?: Config, dependencies?: AgyAdapterDependencies);
+    private preparePrompt;
+    /** Remove the in-memory AGY mapping; the next call sends complete DSH history. */
+    clearSession(sessionId: string): boolean;
+    /** Inspect the detached mapping for diagnostics and tests. */
+    getSession(sessionId: string): SessionRecord | undefined;
+    /** Return process-slot state without exposing prompts, paths, or credentials. */
+    getConcurrencyStats(): import("../agy/limiter.js").AgyConcurrencyStats;
+    /** Check AGY path, version, and configured Agent without spending model quota. */
+    diagnose(): Promise<AgyDiagnosticResult>;
+    providerInfo(provider: string): LlmProviderInfo;
+    providerRetryPolicy(_provider: string): ResolvedRetryPolicy;
+    listModels(provider: string): Promise<readonly LlmModelInfo[]>;
+    /** Expose safe discovery state for diagnostics and integration tests. */
+    getModelDiscoveryStatus(): AgyModelDiscoveryResult | {
+        source: 'static';
+        stale: false;
+        models: readonly ModelConfig[];
+    };
+    resolveModel(provider: string, model: string, _signal?: AbortSignal): Promise<LlmResolvedModelInfo>;
+    private shouldUsePersistent;
+    private streamPersistentAttempt;
+    private effectiveModels;
+    stream(options: GenerateOptions): AsyncGenerator<StreamChunk, void, void>;
+    private streamAttempt;
+}
+//# sourceMappingURL=agy.d.ts.map