dsh-plugin-lcu 0.1.0

package/lib/connection.js

@@ -0,0 +1,384 @@
+/**
+ * The LCU MCP client.
+ *
+ * Why not `@modelcontextprotocol/sdk` or the host's `@modelcontextprotocol/client`:
+ * the harness's own MCP bridge declares `capabilities: {}` and therefore cannot
+ * answer elicitation, which is how LCU asks for per-app approval; and pulling a
+ * second SDK into a profile plugin would pin a version the host does not own.
+ * MCP over stdio is newline-delimited JSON-RPC, so the wire is small enough to
+ * own here and keeps this plugin dependency-free at runtime.
+ *
+ * Contract kept from `amontlabs/lcu`:
+ * - declare `capabilities.elicitation` and answer `elicitation/create`
+ * - expose only `js` and `js_reset` to the model; `turn_ended` and
+ *   `js_add_node_module_dir` are host-only
+ * - inject the server's `initialize.instructions` into model context
+ * - fail closed: an elicitation with no handler, or any unknown shape, cancels
+ * - approvals never time out; a pending approval freezes the call deadline
+ *
+ * @module dsh-plugin-lcu/connection
+ */
+/** Tools the model may see. Everything else is host-only. */
+export const MODEL_TOOL_NAMES = ['js', 'js_reset'];
+/** Host-only tools, named so a mistake is loud rather than silent. */
+export const HOST_ONLY_TOOL_NAMES = ['turn_ended', 'js_add_node_module_dir'];
+/** MCP protocol revision this client asks for; the server negotiates. */
+const PROTOCOL_VERSION = '2025-06-18';
+/** LCU's own approval timeout: effectively "never expire a pending approval". */
+const NO_APPROVAL_TIMEOUT_MS = 2 ** 31 - 1;
+const DEFAULT_CALL_TIMEOUT_MS = 120_000;
+const DEFAULT_TURN_END_TIMEOUT_MS = 120_000;
+const CONNECT_TIMEOUT_MS = 120_000;
+/**
+ * Code for the turn-cleanup timeout: the original host stopped waiting for its
+ * per-turn cleanup. The cleanup keeps running in the worker and the runtime
+ * retries it before the next action, so this is a warning the caller should
+ * surface rather than a reason to abort the session.
+ */
+export const TURN_CLEANUP_TIMEOUT_CODE = 'LCU_TURN_CLEANUP_TIMEOUT';
+/** A failure that names the protocol stage it happened at. */
+export class LcuError extends Error {
+    stage;
+    /** Stable machine-readable classification, when one applies. */
+    code;
+    constructor(stage, message, cause, code) {
+        super(message, cause === undefined ? undefined : { cause });
+        this.name = 'LcuError';
+        this.stage = stage;
+        if (code !== undefined)
+            this.code = code;
+    }
+}
+/**
+ * Classify a failed `turn_ended` call.
+ *
+ * The runtime reports its own cleanup timeout as an ordinary error result with a
+ * recognizable detail. Missing it would let a stalled cleanup look like a
+ * healthy turn, which is exactly what LCU's contract asks a host not to do.
+ *
+ * @param result - the failed call's result.
+ * @returns the classified error, or `undefined` when the call succeeded.
+ */
+export function classifyTurnEndFailure(result) {
+    if (!result.isError)
+        return undefined;
+    const detail = result.content
+        .filter((block) => block.type === 'text' && typeof block.text === 'string')
+        .map((block) => block.text)
+        .join('\n');
+    if (/turn-ended handlers timed out/i.test(detail)) {
+        return new LcuError('turn_ended', "the CUA turn cleanup did not finish within the host's wait; it may still be finishing in the background "
+            + 'and the runtime retries it before the next action', undefined, TURN_CLEANUP_TIMEOUT_CODE);
+    }
+    return new LcuError('turn_ended', `turn cleanup failed: ${detail === '' ? 'unknown error' : detail}`);
+}
+/**
+ * Answer one elicitation, failing closed on every unexpected shape.
+ *
+ * LCU requires this exact discipline: a host that cannot present the request,
+ * a handler that throws, or an answer that is not one of the three actions must
+ * all end as `cancel`, because anything else would silently grant desktop access.
+ *
+ * @param handler - the host's presenter, or `undefined` when there is none.
+ * @param request - the server's elicitation params.
+ * @param activeCalls - signals of in-flight tool calls; aborting one cancels.
+ * @returns an answer the server accepts; never rejects.
+ */
+export async function resolveElicitation(handler, request, activeCalls = new Set()) {
+    if (handler === undefined)
+        return { action: 'cancel' };
+    const abort = new AbortController();
+    const signal = AbortSignal.any([abort.signal, ...activeCalls]);
+    const dismissed = new Promise((resolve) => {
+        if (signal.aborted)
+            resolve({ action: 'cancel' });
+        else
+            signal.addEventListener('abort', () => resolve({ action: 'cancel' }), { once: true });
+    });
+    let answer;
+    try {
+        answer = await Promise.race([handler(request, signal), dismissed]);
+    }
+    catch {
+        return { action: 'cancel' };
+    }
+    if (answer?.action === 'accept' || answer?.action === 'decline' || answer?.action === 'cancel')
+        return answer;
+    return { action: 'cancel' };
+}
+/**
+ * One long-lived connection to the `lcu` MCP server.
+ *
+ * The connection is per Agent/Session: LCU carries a persistent JavaScript
+ * session on its side, and its approvals are scoped to a real host session and
+ * turn, so sharing one connection across agents would interleave both.
+ */
+export class LcuConnection {
+    #options;
+    #child;
+    #nextId = 1;
+    #pending = new Map();
+    #tools = [];
+    #instructions = '';
+    #serverInfo = {};
+    #closed = false;
+    #stderrBuffer = '';
+    #activeCalls = new Set();
+    constructor(options) {
+        this.#options = options;
+    }
+    /** The server's `initialize.instructions`, injected into model context. */
+    get instructions() {
+        return this.#instructions;
+    }
+    /** Server identity, for diagnostics. */
+    get serverInfo() {
+        return this.#serverInfo;
+    }
+    /** Everything the server advertised, including host-only tools. */
+    get allTools() {
+        return this.#tools;
+    }
+    /** The tools the model may see, in server order. */
+    modelTools() {
+        return this.#tools.filter((tool) => MODEL_TOOL_NAMES.includes(tool.name));
+    }
+    /**
+     * Spawn `lcu`, complete the MCP handshake, and discover tools.
+     *
+     * @throws {LcuError} when the process cannot start or the handshake fails.
+     */
+    async connect(signal) {
+        const { spawn } = await import('node:child_process');
+        let child;
+        try {
+            child = spawn(this.#options.command, [...this.#options.args ?? []], {
+                cwd: this.#options.cwd,
+                env: { ...process.env, ...this.#options.env },
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+        }
+        catch (error) {
+            throw new LcuError('spawn', `could not start ${this.#options.command}`, error);
+        }
+        this.#child = child;
+        child.stderr?.on('data', (chunk) => this.#consumeStderr(chunk.toString()));
+        child.on('exit', (code, signalName) => {
+            const detail = signalName === null ? `exit ${String(code)}` : `signal ${signalName}`;
+            this.#failAll(new LcuError('spawn', `lcu ${detail}`));
+            this.#closed = true;
+        });
+        const { createInterface } = await import('node:readline');
+        createInterface({ input: child.stdout }).on('line', (line) => {
+            this.#onLine(line);
+        });
+        const result = await this.#request('initialize', {
+            protocolVersion: PROTOCOL_VERSION,
+            capabilities: { elicitation: {} },
+            clientInfo: { name: 'dsh-plugin-lcu', version: '0.0.1' },
+        }, CONNECT_TIMEOUT_MS, 'initialize', signal);
+        this.#instructions = typeof result.instructions === 'string' ? result.instructions : '';
+        const info = result.serverInfo;
+        this.#serverInfo = info !== null && typeof info === 'object' && !Array.isArray(info)
+            ? info
+            : {};
+        this.#notify('notifications/initialized');
+        await this.#refreshTools(signal);
+    }
+    /**
+     * Call one tool. `js_reset` and `js` are the model-facing ones; the host-only
+     * tools are reachable here too because the lifecycle needs `turn_ended`.
+     *
+     * Requests carry no client-side deadline by default: a pause for a human
+     * approval must not look like a hung call.
+     */
+    async callTool(name, args, options = {}) {
+        const result = await this.#request('tools/call', { name, arguments: args }, options.timeoutMs ?? DEFAULT_CALL_TIMEOUT_MS, 'tools/call', options.signal);
+        const content = Array.isArray(result.content) ? result.content : [];
+        return {
+            content,
+            isError: result.isError === true,
+            ...(result.structuredContent === undefined ? {} : { structuredContent: result.structuredContent }),
+        };
+    }
+    /**
+     * Tell the server a host turn ended, so its per-turn cleanup runs.
+     *
+     * @param sessionId - the real host session id, and nothing synthetic.
+     * @param turnId - the real host turn id.
+     * @param event - `Stop`, `Interrupt`, or `SubagentStop`.
+     */
+    async turnEnded(sessionId, turnId, event = 'Stop') {
+        if (sessionId === '' || turnId === '') {
+            throw new LcuError('turn_ended', 'turn_ended requires a real session id and turn id');
+        }
+        const result = await this.callTool('turn_ended', {
+            hook_event_name: event,
+            session_id: sessionId,
+            turn_id: turnId,
+        }, { timeoutMs: DEFAULT_TURN_END_TIMEOUT_MS });
+        const failure = classifyTurnEndFailure(result);
+        if (failure !== undefined)
+            throw failure;
+    }
+    /** Close the connection, terminating the child process. */
+    async close() {
+        this.#closed = true;
+        this.#failAll(new LcuError('spawn', 'connection closed'));
+        const child = this.#child;
+        this.#child = undefined;
+        if (child === undefined || child.exitCode !== null)
+            return;
+        child.kill('SIGTERM');
+        await new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                child.kill('SIGKILL');
+                resolve();
+            }, 3_000);
+            child.once('exit', () => {
+                clearTimeout(timer);
+                resolve();
+            });
+        });
+    }
+    // -------------------------------------------------------------------------
+    // Wire
+    // -------------------------------------------------------------------------
+    #consumeStderr(text) {
+        this.#stderrBuffer += text;
+        const lines = this.#stderrBuffer.split('\n');
+        this.#stderrBuffer = lines.pop() ?? '';
+        for (const line of lines)
+            if (line.trim() !== '')
+                this.#options.onStderr?.(line);
+    }
+    #onLine(line) {
+        if (line.trim() === '')
+            return;
+        let message;
+        try {
+            message = JSON.parse(line);
+        }
+        catch {
+            return; // non-protocol chatter on stdout is not ours to interpret
+        }
+        if (message.method !== undefined) {
+            void this.#onServerMessage(message);
+            return;
+        }
+        if (typeof message.id !== 'number')
+            return;
+        const entry = this.#pending.get(message.id);
+        if (entry === undefined)
+            return;
+        this.#pending.delete(message.id);
+        entry.cleanup();
+        if (message.error !== undefined) {
+            entry.reject(new LcuError('tools/call', message.error.message ?? 'server error'));
+            return;
+        }
+        entry.resolve(message.result ?? {});
+    }
+    async #onServerMessage(message) {
+        const id = message.id;
+        if (message.method === 'notifications/tools/list_changed') {
+            try {
+                await this.#refreshTools();
+            }
+            catch {
+                // A failed refresh keeps the previous tool set, matching the host bridge.
+            }
+            return;
+        }
+        // Requests from the server are the elicitation surface; answer or cancel.
+        if (id === undefined)
+            return;
+        if (message.method === 'elicitation/create') {
+            const request = (message.params ?? {});
+            const response = await this.#answerElicitation(request);
+            this.#respond(id, response);
+            return;
+        }
+        // Unknown server requests fail closed rather than hanging the child.
+        this.#respondError(id, -32601, `unsupported server request: ${message.method}`);
+    }
+    async #answerElicitation(request) {
+        return await resolveElicitation(this.#options.onElicitation, request, this.#activeCalls);
+    }
+    async #refreshTools(signal) {
+        const result = await this.#request('tools/list', {}, CONNECT_TIMEOUT_MS, 'tools/list', signal);
+        const listed = Array.isArray(result.tools) ? result.tools : [];
+        const missing = MODEL_TOOL_NAMES.filter((name) => !listed.some((tool) => tool.name === name));
+        if (missing.length > 0) {
+            throw new LcuError('tools/list', `server does not expose ${missing.join(', ')}`);
+        }
+        this.#tools = listed;
+        this.#options.onToolsChanged?.(listed);
+    }
+    #write(message) {
+        const child = this.#child;
+        if (child === undefined || child.stdin === null || this.#closed) {
+            throw new LcuError('spawn', 'lcu is not connected');
+        }
+        child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', ...message })}\n`);
+    }
+    #notify(method, params) {
+        this.#write(params === undefined ? { method } : { method, params });
+    }
+    #respond(id, result) {
+        this.#write({ id, result });
+    }
+    #respondError(id, code, message) {
+        this.#write({ id, error: { code, message } });
+    }
+    #request(method, params, timeoutMs, stage, signal) {
+        if (signal !== undefined)
+            this.#activeCalls.add(signal);
+        const id = this.#nextId++;
+        return new Promise((resolve, reject) => {
+            const onAbort = () => {
+                this.#pending.delete(id);
+                reject(new LcuError(stage, `${method} was aborted`));
+            };
+            const timer = timeoutMs >= NO_APPROVAL_TIMEOUT_MS
+                ? undefined
+                : setTimeout(() => {
+                    this.#pending.delete(id);
+                    signal?.removeEventListener('abort', onAbort);
+                    reject(new LcuError(stage, `${method} timed out after ${String(timeoutMs)}ms`));
+                }, timeoutMs);
+            const cleanup = () => {
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                signal?.removeEventListener('abort', onAbort);
+                if (signal !== undefined)
+                    this.#activeCalls.delete(signal);
+            };
+            if (signal?.aborted === true) {
+                cleanup();
+                reject(new LcuError(stage, `${method} was aborted`));
+                return;
+            }
+            signal?.addEventListener('abort', onAbort, { once: true });
+            this.#pending.set(id, {
+                resolve: (value) => { cleanup(); resolve(value); },
+                reject: (error) => { cleanup(); reject(error); },
+                cleanup,
+            });
+            try {
+                this.#write({ id, method, params });
+            }
+            catch (error) {
+                cleanup();
+                this.#pending.delete(id);
+                reject(error instanceof Error ? error : new LcuError(stage, String(error)));
+            }
+        });
+    }
+    #failAll(error) {
+        for (const entry of this.#pending.values())
+            entry.reject(error);
+        this.#pending.clear();
+    }
+}
+//# sourceMappingURL=connection.js.map

package/lib/connection.js.map

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

package/lib/diag.js

@@ -0,0 +1,52 @@
+/**
+ * Best-effort diagnostic log for the LCU attach path.
+ *
+ * The harness exposes plugin logs only through surfaces a running session
+ * cannot read, and a failing `agent/created` listener is swallowed silently. So
+ * the attach decision writes here: one line per branch, including the errors
+ * that would otherwise vanish. It never throws and never changes behavior.
+ *
+ * Set `LCU_DIAG=0` to disable. The file is `~/.dsh/lcu-diag.log`.
+ *
+ * @module dsh-plugin-lcu/diag
+ */
+import { appendFileSync, rmSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const LOG_PATH = join(process.env.DSH_HOME ?? join(homedir(), '.dsh'), 'lcu-diag.log');
+/** Rotate rather than grow without bound: the log records one line per decision. */
+const MAX_BYTES = 1_048_576;
+/** Append one diagnostic line; silently does nothing if the file cannot be written. */
+export function diag(message) {
+    if (process.env.LCU_DIAG === '0')
+        return;
+    try {
+        // Start over once the file is full; this is a rolling support aid, not a log
+        // of record, and truncating keeps it bounded without a rotation scheme.
+        if ((statSync(LOG_PATH, { throwIfNoEntry: false })?.size ?? 0) > MAX_BYTES)
+            rmSync(LOG_PATH, { force: true });
+        appendFileSync(LOG_PATH, `${new Date().toISOString()} ${message}\n`);
+    }
+    catch {
+        // Diagnostics must never affect the capability they describe.
+    }
+}
+/** Describe a value for the log without dumping unbounded data. */
+export function describe(value) {
+    if (value === undefined)
+        return 'undefined';
+    if (value === null)
+        return 'null';
+    if (typeof value === 'string')
+        return JSON.stringify(value);
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    if (typeof value === 'function')
+        return 'function';
+    if (Array.isArray(value))
+        return `array(${String(value.length)})`;
+    if (typeof value === 'object')
+        return `object{${Object.keys(value).slice(0, 8).join(',')}}`;
+    return typeof value;
+}
+//# sourceMappingURL=diag.js.map

package/lib/diag.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diag.js","sourceRoot":"","sources":["../src/diag.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAC1D,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAEhC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,MAAM,CAAC,EAAE,cAAc,CAAC,CAAA;AAEtF,oFAAoF;AACpF,MAAM,SAAS,GAAG,SAAS,CAAA;AAE3B,uFAAuF;AACvF,MAAM,UAAU,IAAI,CAAC,OAAe;IAClC,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,GAAG;QAAE,OAAM;IACxC,IAAI,CAAC;QACH,6EAA6E;QAC7E,wEAAwE;QACxE,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,IAAI,CAAC,CAAC,GAAG,SAAS;YAAE,MAAM,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;QAC7G,cAAc,CAAC,QAAQ,EAAE,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,IAAI,OAAO,IAAI,CAAC,CAAA;IACtE,CAAC;IAAC,MAAM,CAAC;QACP,8DAA8D;IAChE,CAAC;AACH,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,WAAW,CAAA;IAC3C,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,MAAM,CAAA;IACjC,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAA;IAC3D,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAA;IACjF,IAAI,OAAO,KAAK,KAAK,UAAU;QAAE,OAAO,UAAU,CAAA;IAClD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,SAAS,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAA;IACjE,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,UAAU,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAA;IAC3F,OAAO,OAAO,KAAK,CAAA;AACrB,CAAC"}

package/lib/host-guard.js

@@ -0,0 +1,137 @@
+/**
+ * The agent-host guard.
+ *
+ * LCU refuses to approve the application that is hosting the agent, because
+ * computer use can click anything an approved app shows — including the very
+ * approval prompt — so approving the host would let the agent approve itself.
+ *
+ * LCU's own shared client does this; a host that replaces that client owns the
+ * rule. This is the DSH implementation: the agent's own process ancestry plus a
+ * static list of dedicated agent hosts and terminals.
+ *
+ * A failed or unavailable process lookup falls back to the static list, so the
+ * guard degrades to "known hosts are refused" rather than "nothing is refused".
+ *
+ * @module dsh-plugin-lcu/host-guard
+ */
+import { execFile } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+/**
+ * Dedicated agent hosts, terminals, and this harness.
+ *
+ * Editors and IDEs are deliberately absent: they are common computer-use
+ * targets, and when an editor hosts the agent its bundle is an ancestor of this
+ * process, which the dynamic check already refuses.
+ */
+export const STATIC_HOST_BUNDLE_IDS = [
+    'com.deepseek.dsh',
+    'com.anthropic.claudefordesktop',
+    'com.anthropic.claude-code',
+    'com.openai.codex',
+    'com.apple.Terminal',
+    'com.googlecode.iterm2',
+    'com.mitchellh.ghostty',
+    'dev.warp.Warp-Stable',
+    'com.github.wez.wezterm',
+    'io.alacritty',
+    'net.kovidgoyal.kitty',
+    'co.zeit.hyper',
+    'com.raphaelamorim.rio',
+    'dev.commandline.wave',
+];
+/** Set `LCU_ALLOW_AGENT_HOST_APPROVAL=1` to disable the guard for testing only. */
+const OVERRIDE_ENV = 'LCU_ALLOW_AGENT_HOST_APPROVAL';
+let cachedAncestorBundles;
+/** Run a command, resolving to its trimmed stdout or `undefined` on any failure. */
+function tryExec(command, args) {
+    return new Promise((resolvePromise) => {
+        execFile(command, [...args], { timeout: 5_000 }, (error, stdout) => {
+            resolvePromise(error === null ? stdout.trim() : undefined);
+        });
+    });
+}
+/** The enclosing `.app` bundle of an executable path, if any. */
+export function enclosingAppBundle(executablePath) {
+    let current = resolve(executablePath);
+    for (;;) {
+        if (current.endsWith('.app'))
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+}
+/** Read one bundle identifier, preferring the modern plist helper. */
+async function bundleIdentifier(appPath) {
+    const plist = join(appPath, 'Contents', 'Info.plist');
+    if (!existsSync(plist))
+        return undefined;
+    const value = await tryExec('plutil', ['-extract', 'CFBundleIdentifier', 'raw', '-o', '-', plist]);
+    return value !== undefined && value !== '' ? value : undefined;
+}
+/**
+ * The bundle identifiers of every `.app` on this process's ancestry.
+ *
+ * This is the dynamic half of the guard: whatever application actually launched
+ * DSH — a terminal, an editor, a launcher — is refused by construction, even
+ * when it is not on the static list.
+ *
+ * @returns the ancestor bundle identifiers; empty when the lookup fails.
+ */
+export async function ancestorBundleIds() {
+    cachedAncestorBundles ??= (async () => {
+        const found = new Set();
+        let pid = process.pid;
+        for (let depth = 0; depth < 24; depth += 1) {
+            const parentText = await tryExec('ps', ['-o', 'ppid=', '-p', String(pid)]);
+            const executable = await tryExec('ps', ['-o', 'comm=', '-p', String(pid)]);
+            if (executable !== undefined) {
+                const bundle = enclosingAppBundle(executable);
+                if (bundle !== undefined) {
+                    const id = await bundleIdentifier(bundle);
+                    if (id !== undefined)
+                        found.add(id);
+                }
+            }
+            const parent = Number(parentText);
+            if (!Number.isInteger(parent) || parent <= 1)
+                break;
+            pid = parent;
+        }
+        return found;
+    })();
+    return await cachedAncestorBundles;
+}
+/**
+ * Whether an approval would grant the agent control of its own host.
+ *
+ * @param app - the app the runtime is asking about: a display name, bundle id, or path.
+ * @returns `true` when the request must be declined without asking the user.
+ */
+export async function isAgentHostApp(app) {
+    if (process.env[OVERRIDE_ENV] === '1')
+        return false;
+    const candidate = app.trim();
+    if (candidate === '')
+        return false;
+    // A path is decided by its own bundle, not by the ancestor set.
+    if (candidate.includes('/')) {
+        const bundle = enclosingAppBundle(candidate);
+        const id = bundle === undefined ? undefined : await bundleIdentifier(bundle);
+        if (id !== undefined && STATIC_HOST_BUNDLE_IDS.includes(id))
+            return true;
+        const ancestors = await ancestorBundleIds();
+        return id !== undefined && ancestors.has(id);
+    }
+    if (STATIC_HOST_BUNDLE_IDS.includes(candidate))
+        return true;
+    const ancestors = await ancestorBundleIds();
+    return ancestors.has(candidate);
+}
+/** Reset the memoized ancestry; for tests only. */
+export function resetAncestorCache() {
+    cachedAncestorBundles = undefined;
+}
+//# sourceMappingURL=host-guard.js.map

package/lib/host-guard.js.map

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