dsh-agy-cli 0.0.0-stage → 0.12.0

package/lib/index.js

@@ -0,0 +1,256 @@
+import { appendFileSync } from 'node:fs';
+import { AgyAdapter } from './provider/agy.js';
+import { BundleConfig, Config as ConfigSchema, createConfigSchema, } from './provider/config.js';
+import { MockAdapter } from './provider/mock.js';
+import { AgyModelDiscovery } from './agy/models.js';
+import { appendAgyDiagnosticRecord, AGY_DIAGNOSTIC_LOG_PATH } from './agy/log.js';
+import { configuredModels, readConfigFlag } from './provider/config.js';
+import { SessionRegistry } from './session/store.js';
+import { FileSessionStore, resolveSessionStorePath } from './session/file-store.js';
+export const name = 'dsh-agy-cli';
+export const inject = ['llm', 'sessions', 'workspaceRegistry', 'sandboxPolicy', 'permissionPresets', 'approval'];
+/** Programmatic library default: enabled=false, toolPolicy=reject. */
+export const Config = ConfigSchema;
+export { AgyAdapter, MockAdapter };
+export { AgyModelDiscovery, mergeModelCatalog, parseAgyModels } from './agy/models.js';
+export { diagnoseAgy } from './agy/diagnostics.js';
+export { diagnoseProvider } from './diagnostics.js';
+export { DshContextError, diagnoseDshContext, readDshContextServices, resolveDshContext } from './dsh/context.js';
+export { appendToolProtocolPrompt, createStructuredToolProtocol, parseStructuredEnvelope, renderToolProtocolPrompt, StructuredResponseAccumulator, ToolProtocolError, TOOL_PROTOCOL_LIMITS, } from './provider/tool-protocol.js';
+export { stageToolSchema } from './provider/tool-schema-file.js';
+export { diagnoseProfile, runDoctor } from './doctor.js';
+export { AgyImageBridgeError, DEFAULT_IMAGE_MAX_BYTES, DEFAULT_IMAGE_MAX_COUNT, IMAGE_MEDIA_TYPES, prepareAgyPrompts, } from './provider/image-bridge.js';
+import { startDshMcpBridge, } from './mcp/bridge.js';
+import { noteRegistration, setupWebRoutes } from './web/router.js';
+import { findMissingAgentTemplates, } from './agent-installer.js';
+import { agentTemplatesForRequest } from './agent-presets.js';
+import { AGENT_PRESET_IDS, getAgentPreset, listAgentPresets, readAgentPresetTemplate, requireAgentPreset, } from './agent-presets.js';
+export { AGENT_PRESET_IDS, agentTemplatesForRequest, getAgentPreset, listAgentPresets, readAgentPresetTemplate, requireAgentPreset, };
+export { DEFAULT_AGENT_DIRECTORY, AgentInstallError, describeAgentPresets, findMissingAgentTemplates, installAgentPreset, isAgentPreset, } from './agent-installer.js';
+export { formatAgentsHelp, runAgentsCli } from './agents-cli.js';
+export { BundleConfig, ConfigSchema, createConfigSchema };
+function resolveSettingsConfig(ctx, config) {
+    // DSH 0.2.0 removed SettingsProvider.register(): the harness's SettingsForms
+    // projects the plugin's exported `Config` schema automatically, and `config`
+    // already is the live merged value. Direct library callers compose the LLM
+    // service alone, which keeps working unchanged.
+    void ctx;
+    return config;
+}
+export function apply(ctx, config) {
+    const activeConfig = resolveSettingsConfig(ctx, config);
+    const modelDiscovery = activeConfig.modelDiscovery === 'off' ? undefined : new AgyModelDiscovery({
+        ...(activeConfig.agyPath?.trim() ? { executable: activeConfig.agyPath.trim() } : {}),
+        ...(activeConfig.modelDiscoveryTtlMs === undefined ? {} : { ttlMs: activeConfig.modelDiscoveryTtlMs }),
+        ...(activeConfig.modelDiscoveryTimeoutMs === undefined ? {} : { timeoutMs: activeConfig.modelDiscoveryTimeoutMs }),
+    });
+    // Settings panel: expose the local AGY CLI as the Antigravity CLI provider.
+    // The namespace is the plugin name; settingsPath [] means the whole section is the profile.
+    //
+    // The outcome is recorded, not discarded: the Models page attaches the AGY
+    // card only to a directory row whose `settingsNs` is exactly this string, and
+    // a refused registration (DUPLICATE_DIRECTORY when this profile mounts the
+    // plugin twice) used to be swallowed — which made "no card on the Models page"
+    // indistinguishable from "card rendered empty". `/plugins/agy-cli/diagnose`
+    // now reports both the refusal and the directory it actually has.
+    const registerProviderDirectory = () => {
+        try {
+            ctx.llm.registerConfigurableProviders([{
+                    provider: 'agy',
+                    displayName: 'Antigravity CLI',
+                    settingsNs: 'dsh-agy-cli',
+                    settingsPath: [],
+                }]);
+            noteRegistration('configurableProviders', 'ok');
+            return true;
+        }
+        catch (error) {
+            noteRegistration('configurableProviders', error instanceof Error ? error.message : String(error));
+            return false;
+        }
+    };
+    if (!registerProviderDirectory()) {
+        // Why a retry: a refused registration means another mount of this plugin
+        // already holds the `agy` entry. If that mount is disposed afterwards (the
+        // bundle mount being replaced by the patch override), the directory loses the
+        // entry and the Models page keeps listing the provider with an EMPTY
+        // settingsNs — a row that renders no card. Retrying once after the loader
+        // settles repairs that order dependence without a host restart.
+        ctx.effect(() => {
+            const timers = [3_000, 10_000].map((delay) => {
+                const timer = setTimeout(() => { registerProviderDirectory(); }, delay);
+                if (typeof timer.unref === 'function')
+                    timer.unref();
+                return timer;
+            });
+            return () => { for (const timer of timers)
+                clearTimeout(timer); };
+        });
+    }
+    try {
+        ctx.llm.registerModelDiscovery('dsh-agy-cli', async (request) => {
+            // If editing an existing agy route, prefer our already-known catalog; otherwise discover via AGY CLI.
+            // request.provider being 'agy' or undefined both mean this plugin owns the draft.
+            if (request.provider !== undefined && request.provider !== 'agy')
+                return [];
+            const configured = configuredModels(activeConfig);
+            const result = activeConfig.modelDiscovery === 'off'
+                ? { models: configured, source: 'static', stale: false }
+                : await modelDiscovery.discover(configured);
+            return result.models.map(m => ({
+                id: m.id,
+                ...(m.name === undefined ? {} : { name: m.name }),
+                ...(m.contextWindow === undefined ? {} : { contextWindow: m.contextWindow }),
+            }));
+        });
+        noteRegistration('modelDiscovery', 'ok');
+    }
+    catch (error) {
+        noteRegistration('modelDiscovery', error instanceof Error ? error.message : String(error));
+    }
+    // Mount web HTTP routes for GUI control panel & status polling (/plugins/agy-cli/*)
+    try {
+        setupWebRoutes(ctx, activeConfig, modelDiscovery);
+        noteRegistration('webRoutes', 'ok');
+    }
+    catch (error) {
+        noteRegistration('webRoutes', error instanceof Error ? error.message : String(error));
+    }
+    // Settings are resolved before the enabled check, so disabled profiles can
+    // still be edited from the configuration surface.
+    if (!readConfigFlag(activeConfig.enabled))
+        return;
+    const provider = activeConfig.provider ?? 'agy';
+    if (provider === 'agy-mock') {
+        ctx.llm.registerAdapter([provider], new MockAdapter(activeConfig));
+        return;
+    }
+    const logger = ctx.logger('dsh-agy-cli');
+    // AGY exits with `unknown agent "<name>" (available: ...)` *before* it reads
+    // any input when the profile named on the command line has no template on
+    // disk. The child then dies while its stdin is being written, and the adapter
+    // reports that as AGY_INPUT_FAILED — an error naming the wrong component.
+    // Report the real cause once, at startup, naming the exact missing files.
+    // This only warns: installing templates is a deliberate user action, and
+    // writing into another application's config directory unprompted is not
+    // something a provider should do.
+    ctx.effect(() => {
+        let cancelled = false;
+        void (async () => {
+            try {
+                const wanted = agentTemplatesForRequest({
+                    toolPolicy: activeConfig.toolPolicy === 'agy-owned'
+                        ? 'agy-owned'
+                        : activeConfig.toolPolicy === 'dsh-owned' ? 'dsh-owned' : 'reject',
+                    agentPreset: activeConfig.agentPreset,
+                    agent: activeConfig.agent,
+                    imageInput: activeConfig.imageInput === 'experimental' ? 'experimental' : 'off',
+                });
+                const missing = (await Promise.all(wanted.map(async (entry) => {
+                    if (entry.preset === undefined)
+                        return undefined;
+                    const absent = await findMissingAgentTemplates([entry.preset]);
+                    return absent.length === 0 ? undefined : absent[0];
+                }))).filter((entry) => entry !== undefined);
+                if (cancelled || missing.length === 0)
+                    return;
+                logger.warn('AGY agent template(s) missing: %s. AGY rejects an unknown agent before reading any input, '
+                    + 'which surfaces as AGY_INPUT_FAILED. Install them with: npx dsh-agy-cli agents install %s --apply', missing.map(entry => `${entry.agentName} (${entry.targetPath})`).join(', '), missing.map(entry => entry.preset).join(' '));
+            }
+            catch (error) {
+                logger.warn('could not check AGY agent templates: %s', error instanceof Error ? error.message : String(error));
+            }
+        })();
+        return () => {
+            cancelled = true;
+        };
+    });
+    // AttachmentStore is optional for the text-only path. Use the reflection
+    // lookup instead of reading ctx.attachments directly: Cordis requires every
+    // direct service property access to be declared in `inject`.
+    // The MCP tool bridge hands DSH tools to AGY out of band (so their schemas
+    // never enter the prompt) and routes every execution back through the host's
+    // own tool pipeline. It starts as an effect so the registration is removed
+    // again when this fiber unloads.
+    let toolBridge;
+    let toolBridgeError;
+    const wantsBridge = activeConfig.mcpBridge !== false
+        && activeConfig.toolPolicy === 'dsh-owned';
+    if (wantsBridge) {
+        ctx.effect(() => {
+            let cancelled = false;
+            void (async () => {
+                const bridge = await startDshMcpBridge({
+                    webServer: ctx.get('webServer'),
+                    tools: ctx.get('tools'),
+                    // Late-bound on purpose: this plugin loads before the Session
+                    // controller bundle finishes mounting, and a value captured here
+                    // stays undefined for the life of the host.
+                    sessionControllerLookup: () => ctx.get('sessionController'),
+                    ...((activeConfig.mcpToolAllowlist ?? []).length > 0 ? { toolAllowlist: activeConfig.mcpToolAllowlist } : {}),
+                    serverVersion: '0.0.0',
+                    logger: message => {
+                        logger.info(message);
+                        // The host logger has no file sink, so a bridge that silently loses
+                        // the session agent leaves no evidence. Mirror into the diagnostic
+                        // log the rest of this provider already writes.
+                        try {
+                            appendFileSync(AGY_DIAGNOSTIC_LOG_PATH, `${JSON.stringify({ event: 'bridge.log', at: Date.now(), message })}\n`, 'utf8');
+                        }
+                        catch {
+                            // Diagnostics must never break the bridge.
+                        }
+                    },
+                });
+                if (cancelled) {
+                    await bridge.dispose();
+                    return;
+                }
+                toolBridge = bridge;
+                if (!bridge.active) {
+                    toolBridgeError = bridge.inactiveReason;
+                    logger.warn('dsh mcp bridge inactive: %s', bridge.inactiveReason ?? 'unknown reason');
+                }
+            })().catch(error => {
+                toolBridgeError = error instanceof Error ? error.message : String(error);
+                logger.warn('dsh mcp bridge failed to start: %s', toolBridgeError);
+            });
+            return async () => {
+                cancelled = true;
+                const bridge = toolBridge;
+                toolBridge = undefined;
+                await bridge?.dispose();
+            };
+        });
+    }
+    ctx.llm.registerAdapter([provider], new AgyAdapter(activeConfig, {
+        logger: record => {
+            try {
+                logger.info('%s', JSON.stringify(record));
+            }
+            finally {
+                appendAgyDiagnosticRecord(record);
+            }
+        },
+        // With sessionMode 'resume' the sessionId -> conversationId map must outlive
+        // the plugin: AGY keeps every conversation on disk, so a durable map turns
+        // the first turn after a host restart from a full-history re-serialization
+        // (pinned at the input limit, missing the upstream prompt cache) into an
+        // incremental one. 'full' never reads the map, so it stays in memory.
+        ...(activeConfig.sessionMode === 'resume'
+            ? { sessionRegistry: new SessionRegistry(new FileSessionStore({ path: resolveSessionStorePath(activeConfig.sessionStorePath) })) }
+            : {}),
+        // Resolve lazily because attachments is optional and can be composed after
+        // this plugin. Text-only requests remain independent of the service.
+        resolveAttachmentStore: () => ctx.get('attachments'),
+        resolveToolBridge: () => {
+            if (!wantsBridge)
+                return undefined;
+            if (toolBridge?.active === true)
+                return toolBridge;
+            return undefined;
+        },
+        dshContext: ctx,
+    }));
+}
+//# sourceMappingURL=index.js.map

package/lib/mcp/agy-registration.d.ts

@@ -0,0 +1,70 @@
+/** The MCP server name AGY shows for this bridge. */
+export declare const AGY_MCP_SERVER_NAME = "dsh";
+export interface AgyMcpEntry {
+    readonly url: string;
+    readonly token: string;
+    /** Exposed tool names, used to scope the AGY-side allow rules. */
+    readonly toolNames?: readonly string[];
+}
+export interface AgyMcpConfigFile {
+    readonly path: string;
+    readonly root: Record<string, unknown>;
+}
+export interface AgyMcpRegistrationOptions {
+    /** Overrides the AGY MCP-config root; tests pass a temporary directory. */
+    readonly configRoot?: string;
+    /**
+     * Overrides the AGY settings root. Settings and MCP config live one level
+     * apart, so this is a separate knob; defaulting it to `configRoot` keeps
+     * single-directory test fixtures working.
+     */
+    readonly settingsRoot?: string;
+    readonly logger?: (message: string) => void;
+}
+/**
+ * The directory AGY reads `mcp_config.json` and `agents/` from.
+ *
+ * It is the `gemini-root-config` child of the CLI data directory. `agy mcp
+ * list`, `agy agents`, and `agy mcp add` all read and write this nested root —
+ * verified by adding a server with the CLI and watching only the nested copy
+ * change on disk.
+ *
+ * `HOME`/`USERPROFILE` overrides do not relocate this either: the CLI resolves
+ * it through the Windows known-folder API, so tests must pass `configRoot`
+ * rather than trying to sandbox the process environment.
+ */
+export declare function agyConfigRoot(): string;
+/**
+ * The directory AGY reads `settings.json` from.
+ *
+ * Settings live one level *above* the MCP config, not beside it. Measured with
+ * a signed probe rule: a rule added to the nested `settings.json` never reaches
+ * the `Allow:[...]` table AGY logs at startup, while the same rule added to the
+ * outer file shows up immediately. Only the outer file is ever loaded.
+ *
+ * Getting this wrong is silent in the worst way: the nested file looks correct
+ * on disk, and every MCP tool call is then auto-denied in headless mode. AGY
+ * logs the real table as `CLI settings initialized: permissions=&{Allow:[...]}`,
+ * which is the fastest way to confirm which file won.
+ */
+export declare function agySettingsRoot(): string;
+/** True when the entry was written by this plugin. */
+export declare function isOwnedEntry(value: unknown): boolean;
+/**
+ * The single allow rule this plugin needs: the server-scoped wildcard. AGY
+ * matches `mcp(<server>/*)` (the syntax its own binary documents, e.g.
+ * `mcp(chrome_devtools/*)`), so every DSH tool the bridge reports is granted
+ * without enumerating names — and a DSH tool added later needs no config edit.
+ */
+export declare function agyAllowRule(_toolName?: string): string;
+/**
+ * Write (or replace) this plugin's AGY MCP server entry. Returns the config
+ * path so callers can report it. Foreign entries are preserved untouched.
+ */
+export declare function registerAgyMcpServer(entry: AgyMcpEntry, options?: AgyMcpRegistrationOptions): Promise<AgyMcpConfigFile>;
+/**
+ * Remove this plugin's AGY MCP server entry, leaving every other entry alone.
+ * Returns true when an entry was actually removed.
+ */
+export declare function unregisterAgyMcpServer(options?: AgyMcpRegistrationOptions): Promise<boolean>;
+//# sourceMappingURL=agy-registration.d.ts.map

package/lib/mcp/agy-registration.js

@@ -0,0 +1,245 @@
+/**
+ * Register the DSH tool bridge as an MCP server inside the AGY CLI.
+ *
+ * AGY keeps its MCP server table in its own config root
+ * (`~/.gemini/antigravity-cli/gemini-root-config/`, see {@link agyConfigRoot})
+ * and its settings one level above that root (see {@link agySettingsRoot}), so
+ * this is the one place where the plugin writes outside the DSH profile.
+ * Three rules keep that honest:
+ *
+ * 1. every write is attributed — the entry is named and tagged by this plugin,
+ *    so it can be identified again on the next start;
+ * 2. registration is bound to the plugin lifecycle: the entry is written when
+ *    the provider becomes active and removed when it stops, so uninstalling or
+ *    disabling the plugin does not leave a live endpoint behind;
+ * 3. an allow rule is written alongside the entry, because headless AGY cannot
+ *    prompt for the `mcp` permission and auto-denies every MCP call without one
+ *    (stderr: `a tool required the "mcp" permission that headless mode cannot
+ *    prompt for, so it was auto-denied`). The rule is the server-scoped
+ *    wildcard `mcp(<server>/*)` — the syntax AGY itself documents for its
+ *    bundled servers (`mcp(chrome_devtools/*)` appears in the CLI binary).
+ *    `mcp(<server>)` alone does not match, and the bare `mcp(*)` would hand
+ *    AGY every MCP server on the machine. Enumerating one rule per tool was
+ *    the original approach and is what forced this plugin to rewrite the file
+ *    every time DSH changed its tool set; the wildcard makes DSH-side grants
+ *    the only control point.
+ *
+ * The edit is a read-modify-write of the AGY config with a backup, matching
+ * what the AGY CLI itself does for `agy mcp add`. The AGY CLI is used only to
+ * locate the config root, never to mutate it: `agy mcp add` cannot express the
+ * "replace my previous entry" semantics this needs, and it has no equivalent
+ * for the permission rules.
+ */
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+/** The MCP server name AGY shows for this bridge. */
+export const AGY_MCP_SERVER_NAME = 'dsh';
+/** Marks an entry as owned by this plugin so cleanup never touches foreign servers. */
+const OWNER_TAG = 'dsh-agy-cli';
+/**
+ * The directory AGY reads `mcp_config.json` and `agents/` from.
+ *
+ * It is the `gemini-root-config` child of the CLI data directory. `agy mcp
+ * list`, `agy agents`, and `agy mcp add` all read and write this nested root —
+ * verified by adding a server with the CLI and watching only the nested copy
+ * change on disk.
+ *
+ * `HOME`/`USERPROFILE` overrides do not relocate this either: the CLI resolves
+ * it through the Windows known-folder API, so tests must pass `configRoot`
+ * rather than trying to sandbox the process environment.
+ */
+export function agyConfigRoot() {
+    const explicit = process.env.DSH_AGY_CONFIG_ROOT;
+    if (typeof explicit === 'string' && explicit.trim().length > 0)
+        return explicit.trim();
+    return join(homedir(), '.gemini', 'antigravity-cli', 'gemini-root-config');
+}
+/**
+ * The directory AGY reads `settings.json` from.
+ *
+ * Settings live one level *above* the MCP config, not beside it. Measured with
+ * a signed probe rule: a rule added to the nested `settings.json` never reaches
+ * the `Allow:[...]` table AGY logs at startup, while the same rule added to the
+ * outer file shows up immediately. Only the outer file is ever loaded.
+ *
+ * Getting this wrong is silent in the worst way: the nested file looks correct
+ * on disk, and every MCP tool call is then auto-denied in headless mode. AGY
+ * logs the real table as `CLI settings initialized: permissions=&{Allow:[...]}`,
+ * which is the fastest way to confirm which file won.
+ */
+export function agySettingsRoot() {
+    const explicit = process.env.DSH_AGY_SETTINGS_ROOT;
+    if (typeof explicit === 'string' && explicit.trim().length > 0)
+        return explicit.trim();
+    return join(homedir(), '.gemini', 'antigravity-cli');
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function mcpConfigPath(options) {
+    return join(options.configRoot ?? agyConfigRoot(), 'mcp_config.json');
+}
+function settingsPath(options) {
+    return join(options.settingsRoot ?? options.configRoot ?? agyConfigRoot(), 'settings.json');
+}
+async function readConfig(path) {
+    if (!existsSync(path))
+        return { mcpServers: {} };
+    try {
+        const parsed = JSON.parse(await readFile(path, 'utf8'));
+        if (!isRecord(parsed))
+            return { mcpServers: {} };
+        const servers = parsed.mcpServers;
+        return { ...parsed, mcpServers: isRecord(servers) ? { ...servers } : {} };
+    }
+    catch (error) {
+        // Never overwrite a config that exists but cannot be parsed: that file is
+        // the user's, and silently replacing it would drop their other servers.
+        throw new Error(`AGY MCP config at ${path} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/** True when the entry was written by this plugin. */
+export function isOwnedEntry(value) {
+    if (!isRecord(value))
+        return false;
+    const headers = value.headers;
+    if (!isRecord(headers))
+        return false;
+    return headers['x-dsh-owner'] === OWNER_TAG;
+}
+function entryFor(entry) {
+    return {
+        type: 'http',
+        url: entry.url,
+        headers: {
+            'x-dsh-owner': OWNER_TAG,
+            authorization: `Bearer ${entry.token}`,
+        },
+    };
+}
+async function writeConfig(path, root) {
+    await mkdir(dirname(path), { recursive: true });
+    const backup = `${path}.dsh-agy-cli.bak`;
+    if (existsSync(path) && !existsSync(backup)) {
+        await writeFile(backup, await readFile(path), { encoding: 'utf8' });
+    }
+    const temporary = `${path}.dsh-agy-cli.tmp`;
+    await writeFile(temporary, `${JSON.stringify(root, null, 2)}\n`, { encoding: 'utf8' });
+    await rename(temporary, path);
+}
+/**
+ * The single allow rule this plugin needs: the server-scoped wildcard. AGY
+ * matches `mcp(<server>/*)` (the syntax its own binary documents, e.g.
+ * `mcp(chrome_devtools/*)`), so every DSH tool the bridge reports is granted
+ * without enumerating names — and a DSH tool added later needs no config edit.
+ */
+export function agyAllowRule(_toolName) {
+    return `mcp(${AGY_MCP_SERVER_NAME}/*)`;
+}
+function isAllowRuleForThisBridge(rule) {
+    return rule.startsWith(`mcp(${AGY_MCP_SERVER_NAME}/`);
+}
+/**
+ * Read the AGY settings file. A file that exists but cannot be parsed is an
+ * error rather than an empty document: overwriting it would drop the user's
+ * trusted workspaces and unrelated permission rules.
+ */
+async function readSettings(path) {
+    if (!existsSync(path))
+        return {};
+    try {
+        const parsed = JSON.parse(await readFile(path, 'utf8'));
+        return isRecord(parsed) ? { ...parsed } : {};
+    }
+    catch (error) {
+        throw new Error(`AGY settings at ${path} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Add this bridge's allow rules to the AGY settings, replacing any rules left
+ * by a previous run and preserving every other entry verbatim.
+ */
+async function writeAllowRules(rules, options) {
+    const path = settingsPath(options);
+    const root = await readSettings(path);
+    const permissions = isRecord(root.permissions) ? { ...root.permissions } : {};
+    const existing = Array.isArray(permissions.allow) ? permissions.allow : [];
+    const foreign = existing.filter((rule) => typeof rule === 'string' && !isAllowRuleForThisBridge(rule));
+    if (rules.length === 0 && foreign.length === existing.length)
+        return path;
+    permissions.allow = [...foreign, ...rules];
+    await writeConfig(path, { ...root, permissions });
+    options.logger?.(`allowed ${rules.length} AGY MCP tool(s) in ${path}`);
+    return path;
+}
+/** Drop this bridge's allow rules, leaving foreign rules untouched. */
+async function clearAllowRules(options) {
+    const path = settingsPath(options);
+    if (!existsSync(path))
+        return false;
+    const root = await readSettings(path);
+    if (!isRecord(root.permissions))
+        return false;
+    const permissions = { ...root.permissions };
+    const existing = Array.isArray(permissions.allow) ? permissions.allow : [];
+    const foreign = existing.filter((rule) => typeof rule === 'string' && !isAllowRuleForThisBridge(rule));
+    if (foreign.length === existing.length)
+        return false;
+    if (foreign.length === 0)
+        delete permissions.allow;
+    else
+        permissions.allow = foreign;
+    if (Object.keys(permissions).length === 0)
+        delete root.permissions;
+    else
+        root.permissions = permissions;
+    await writeConfig(path, root);
+    options.logger?.(`removed this plugin's AGY allow rules from ${path}`);
+    return true;
+}
+/**
+ * Write (or replace) this plugin's AGY MCP server entry. Returns the config
+ * path so callers can report it. Foreign entries are preserved untouched.
+ */
+export async function registerAgyMcpServer(entry, options = {}) {
+    const path = mcpConfigPath(options);
+    const root = await readConfig(path);
+    const servers = root.mcpServers;
+    servers[AGY_MCP_SERVER_NAME] = entryFor(entry);
+    await writeConfig(path, { ...root, mcpServers: servers });
+    options.logger?.(`registered AGY MCP server "${AGY_MCP_SERVER_NAME}" at ${path}`);
+    await writeAllowRules([agyAllowRule()], options);
+    return { path, root };
+}
+/**
+ * Remove this plugin's AGY MCP server entry, leaving every other entry alone.
+ * Returns true when an entry was actually removed.
+ */
+export async function unregisterAgyMcpServer(options = {}) {
+    const path = mcpConfigPath(options);
+    if (!existsSync(path))
+        return false;
+    const root = await readConfig(path);
+    const servers = root.mcpServers;
+    const current = servers[AGY_MCP_SERVER_NAME];
+    if (current === undefined) {
+        // The entry can be gone while the allow rules survive a crashed session;
+        // clearing them is still this plugin's job.
+        await clearAllowRules(options).catch(() => false);
+        return false;
+    }
+    // Only remove an entry this plugin wrote; a user-managed server that happens
+    // to be named "dsh" is theirs to keep.
+    if (!isOwnedEntry(current)) {
+        options.logger?.(`AGY MCP server "${AGY_MCP_SERVER_NAME}" is not owned by this plugin; leaving it in place`);
+        return false;
+    }
+    delete servers[AGY_MCP_SERVER_NAME];
+    await writeConfig(path, { ...root, mcpServers: servers });
+    options.logger?.(`removed AGY MCP server "${AGY_MCP_SERVER_NAME}" from ${path}`);
+    await clearAllowRules(options).catch(() => false);
+    return true;
+}
+//# sourceMappingURL=agy-registration.js.map

package/lib/mcp/bridge.d.ts

@@ -0,0 +1,73 @@
+import { type DshWebServerLike, type McpEndpoint } from './endpoint.js';
+export type { DshWebServerLike, McpEndpoint };
+import { agyConfigRoot, agySettingsRoot, AGY_MCP_SERVER_NAME } from './agy-registration.js';
+import { type DshToolRegistryLike } from './tool-projection.js';
+/** The subset of the DSH tool registry this bridge uses. */
+export interface DshToolRuntimeLike extends DshToolRegistryLike {
+    execute(execution: {
+        readonly callId: unknown;
+        readonly name: string;
+        readonly arguments: unknown;
+        readonly agent?: unknown;
+        readonly signal: AbortSignal;
+    }): Promise<DshToolExecutionResultLike>;
+}
+export interface DshToolExecutionResultLike {
+    readonly isError: boolean;
+    readonly error?: {
+        readonly message?: unknown;
+    } | undefined;
+    readonly value?: unknown;
+    readonly content?: readonly unknown[];
+}
+/** The host service that resolves a session id to its live Agent. */
+export interface DshSessionControllerLike {
+    resolveAgent(sessionId: unknown): Promise<unknown>;
+}
+export interface DshMcpBridgeOptions {
+    readonly webServer: DshWebServerLike;
+    readonly tools: DshToolRuntimeLike;
+    readonly sessionController?: DshSessionControllerLike | undefined;
+    /**
+     * Late-bound `sessionController` lookup.
+     *
+     * The bridge starts while this plugin loads, and the Session controller is
+     * mounted by a different bundle: reading the service once at start can pin
+     * `undefined` for the whole host lifetime, which silently degrades every
+     * scoped query to the global tool view (the file and shell tools live on the
+     * agent plane). Resolving per turn removes the load-order dependency.
+     */
+    readonly sessionControllerLookup?: (() => DshSessionControllerLike | undefined) | undefined;
+    /** Optional allowlist of DSH tool names exposed to AGY. */
+    readonly toolAllowlist?: readonly string[] | undefined;
+    readonly serverVersion: string;
+    /** Overrides the AGY MCP-config root; tests pass a temporary directory. */
+    readonly agyConfigRoot?: string | undefined;
+    /**
+     * Overrides the AGY settings root. `agySettingsRoot()` is the production
+     * default (the outer directory); this knob only exists so a test can
+     * keep both files in one temporary directory.
+     */
+    readonly agySettingsRoot?: string | undefined;
+    readonly logger?: (message: string) => void;
+}
+export interface DshMcpBridge {
+    /** The bridge is live: endpoint mounted and AGY config entry written. */
+    readonly active: boolean;
+    /** Why the bridge is not active, when it is not. */
+    readonly inactiveReason: string | undefined;
+    readonly endpoint: McpEndpoint | undefined;
+    /** URL AGY reaches the bridge on; undefined until the bridge is live. */
+    readonly url: string | undefined;
+    /** Point the bridge at the DSH session owning the next AGY turn. */
+    readonly setSession: (sessionId: string) => void;
+    readonly dispose: () => Promise<void>;
+}
+/**
+ * Bring the bridge up. Every failure mode resolves to `active: false` with a
+ * reason instead of throwing, so the provider can fall back to the prompt
+ * contract path when the carrier or the tool registry is not available.
+ */
+export declare function startDshMcpBridge(options: DshMcpBridgeOptions): Promise<DshMcpBridge>;
+export { AGY_MCP_SERVER_NAME, agyConfigRoot, agySettingsRoot };
+//# sourceMappingURL=bridge.d.ts.map