dsh-plugin-lcu 0.1.0

package/lib/index.js

@@ -0,0 +1,318 @@
+/**
+ * `dsh-plugin-lcu` — drive the desktop and Chrome from DeepSeek Harness.
+ *
+ * The plugin is one root-scoped row. It does not open anything at load time:
+ * LCU (and the CUA runtime behind it) starts only for an Agent whose preset is
+ * listed in `presets`, and stops when that Agent is disposed. That keeps a
+ * heavy, permission-bearing capability off every session that does not need it.
+ *
+ * Visibility is decided per Agent rather than by mounting rows inside a preset,
+ * because the server owns the tool schemas: they can only be fetched after the
+ * handshake, so the tools are registered into the Agent's own context once its
+ * connection is up.
+ *
+ * @module dsh-plugin-lcu
+ */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { approvalValueForLabel, isPreApprovedOrigin, nativeAppApproval, nativeAppApprovalResponse, normalizeOrigins, originApprovalOrigin } from "./approval.js";
+import { LcuConnection, LcuError, TURN_CLEANUP_TIMEOUT_CODE, resolveElicitation, } from "./connection.js";
+import { diag, describe } from "./diag.js";
+import { isAgentHostApp } from "./host-guard.js";
+import { registerLcuTools } from "./tool.js";
+export const name = 'lcu';
+export const inject = ['tools', 'systemPrompt'];
+/** Where the installer puts the launcher. */
+const DEFAULT_COMMAND = join(homedir(), '.local/share/lcu/current/bin/lcu');
+/** The section order of the injected instructions, after the tool guidance. */
+const DEFAULT_SECTION_ORDER = 0;
+/** The message shown for a browser-origin approval. */
+const ORIGIN_QUESTION = 'Allow computer use to access this site?';
+function resolveSettings(config) {
+    const args = [];
+    if (config.chrome === true)
+        args.push('--chrome');
+    if (config.audio === true)
+        args.push('--audio');
+    return {
+        command: config.command ?? DEFAULT_COMMAND,
+        args,
+        presets: config.presets ?? ['heavy'],
+        allowedOrigins: normalizeOrigins(config.allowedOrigins ?? []),
+        sectionOrder: config.sectionOrder ?? DEFAULT_SECTION_ORDER,
+    };
+}
+/**
+ * Mount the LCU capability.
+ *
+ * @param ctx - the host context this row mounts into.
+ * @param config - the row's configuration.
+ */
+export function apply(ctx, config) {
+    const settings = resolveSettings(config);
+    const connections = new Map();
+    diag(`apply: presets=${JSON.stringify(settings.presets)} command=${settings.command} args=${JSON.stringify(settings.args)}`);
+    diag(`  services: agentPresets=${describe(ctx.get('agentPresets'))} userQuestions=${describe(ctx.get('userQuestions'))} computerUse=${describe(ctx.get('computerUse'))} attachments=${describe(ctx.get('attachments'))} llm=${describe(ctx.get('llm'))}`);
+    // Reserve the deployment's computer-use provider slot when the seam exists.
+    // This is bookkeeping: the tools below are what the model actually calls.
+    ctx.effect(() => {
+        const computerUse = ctx.get('computerUse');
+        if (computerUse === undefined)
+            return () => { };
+        const release = computerUse.register(computerUseProviderName('lcu'));
+        ctx.logger.info('lcu: registered as the computer-use provider');
+        return () => { void release(); };
+    });
+    /**
+     * Present one approval to the user.
+     *
+     * The model cannot answer this: `userQuestions.ask` is the same surface the
+     * `ask_user_question` tool uses, and only a person can reply to it.
+     */
+    async function presentApproval(agent, request, signal) {
+        const questions = ctx.get('userQuestions');
+        const approval0 = nativeAppApproval(request);
+        diag(`approval: asked kind=${approval0 === undefined ? (originApprovalOrigin(request) === undefined ? 'unknown' : 'browser-origin') : 'native-app'} userQuestions=${describe(questions)}`);
+        if (questions === undefined) {
+            diag('  approval: no userQuestions service -> cancel (fail closed)');
+            return { action: 'cancel' };
+        }
+        const approval = approval0;
+        if (approval !== undefined) {
+            // Anti-self-approval: never let the agent approve its own host.
+            if (await isAgentHostApp(approval.resource)) {
+                diag(`  approval: REFUSED agent-host app ${approval.resource}`);
+                ctx.logger.warn(`lcu: refusing to approve the app hosting this agent (${approval.resource})`);
+                return { action: 'decline' };
+            }
+            try {
+                const answer = await questions.ask({
+                    agent,
+                    signal,
+                    questions: [{
+                            id: 'choice',
+                            header: 'Computer use approval',
+                            question: approval.message,
+                            detail: `Computer use will be able to see and control ${approval.resource}.`,
+                            options: approval.choices.map((choice) => ({ label: choice.label })),
+                        }],
+                });
+                // The answer carries the option LABEL; the response needs its VALUE.
+                const label = answer.answers.find((item) => item.id === 'choice')?.selected[0];
+                const value = approvalValueForLabel(approval, label);
+                diag(`  approval: user chose ${describe(label)} -> value ${describe(value)} for ${approval.resource}`);
+                return nativeAppApprovalResponse(request, value);
+            }
+            catch (error) {
+                ctx.logger.debug(`lcu: native-app approval ended without a choice (${String(error)})`);
+                return { action: 'cancel' };
+            }
+        }
+        const origin = originApprovalOrigin(request);
+        if (origin !== undefined) {
+            // LCU keeps no permission cache; an exact pre-approved origin is the only
+            // thing answered without asking. The log names every asked origin so a
+            // user can add the ones they keep approving to `allowedOrigins`.
+            const preApproved = isPreApprovedOrigin(request, settings.allowedOrigins);
+            diag(`  approval: site ${origin} ${preApproved ? 'pre-approved' : 'asking'} (add it to allowedOrigins to skip this)`);
+            if (preApproved)
+                return { action: 'accept', content: {} };
+            try {
+                const answer = await questions.ask({
+                    agent,
+                    signal,
+                    questions: [{
+                            id: 'choice',
+                            header: 'Computer use site approval',
+                            question: ORIGIN_QUESTION,
+                            detail: `The runtime asked to use ${origin}.`,
+                            options: [{ label: 'Allow' }, { label: 'Decline' }],
+                        }],
+                });
+                const selected = answer.answers.find((item) => item.id === 'choice')?.selected[0];
+                diag(`  approval: site ${origin} user chose ${describe(selected)}`);
+                if (selected === 'Allow')
+                    return { action: 'accept', content: {} };
+                return selected === 'Decline' ? { action: 'decline' } : { action: 'cancel' };
+            }
+            catch (error) {
+                ctx.logger.debug(`lcu: site approval ended without a choice (${String(error)})`);
+                return { action: 'cancel' };
+            }
+        }
+        // Anything else is a shape this host does not understand; cancelling keeps
+        // the fail-closed contract rather than silently granting access.
+        ctx.logger.warn('lcu: unrecognized approval request was cancelled');
+        return { action: 'cancel' };
+    }
+    /** Open and prepare one Agent's connection; never throws. */
+    async function attach(agent, signal) {
+        if (connections.has(agent))
+            return;
+        const connection = new LcuConnection({
+            command: settings.command,
+            args: settings.args,
+            onElicitation: (request, elicitSignal) => presentApproval(agent, request, elicitSignal),
+            onStderr: (line) => { ctx.logger.debug(`lcu: ${line}`); },
+        });
+        diag(`  attach: connecting ${settings.command}`);
+        try {
+            await connection.connect(signal);
+        }
+        catch (error) {
+            await connection.close();
+            // A missing or broken LCU must not fail the session: the preset simply
+            // runs without the desktop tools.
+            ctx.logger.warn(`lcu: could not start for this session (${error instanceof Error ? error.message : String(error)})`);
+            return;
+        }
+        diag(`  attach: connected, server=${describe(connection.serverInfo)} tools=${JSON.stringify(connection.allTools.map((t) => t.name))} instructions=${String(connection.instructions.length)}B`);
+        const state = { connection };
+        connections.set(agent, state);
+        // Everything below is agent-scoped: it unwinds when the Agent is disposed.
+        agent.ctx.effect(() => () => {
+            connections.delete(agent);
+            void connection.close();
+        });
+        try {
+            registerLcuTools(agent.ctx, connection, ctx, {
+                beforeCall: async () => {
+                    const pending = state.pendingCleanup;
+                    if (pending === undefined)
+                        return;
+                    // Retry the unfinished cleanup; only a settled one clears the gate.
+                    await connection.turnEnded(pending.sessionId, pending.turnId);
+                    state.pendingCleanup = undefined;
+                    diag('  cleanup gate: retry succeeded, calls unblocked');
+                },
+            });
+            diag('  attach: tools registered');
+        }
+        catch (error) {
+            diag(`  attach: TOOL REGISTRATION FAILED: ${error instanceof Error ? `${error.name}: ${error.message}` : String(error)}`);
+            throw error;
+        }
+        if (connection.instructions !== '') {
+            agent.ctx.systemPrompt.section({
+                name: 'lcu-instructions',
+                order: settings.sectionOrder,
+                text: connection.instructions,
+            });
+        }
+        ctx.logger.info(`lcu: ${connection.serverInfo.name ?? 'server'} attached for this session`);
+    }
+    /**
+     * Whether this session's Agent should hold an LCU connection.
+     *
+     * The registry is authoritative; the session header is only the value the
+     * session was created with, which the picker replaces afterwards.
+     */
+    function presetAllows(agent) {
+        const registry = ctx.get('agentPresets');
+        let composed;
+        let composeError;
+        try {
+            composed = registry?.composedPreset(agent.ctx);
+        }
+        catch (error) {
+            composeError = error instanceof Error ? error.message : String(error);
+        }
+        const header = agent.session.header.agentPreset;
+        diag(`decide id=${String(agent.id)} composed=${describe(composed)} header=${describe(header)} err=${describe(composeError)}`);
+        const preset = composed ?? header;
+        if (preset === undefined) {
+            diag('  -> skip: no preset');
+            return false;
+        }
+        const allowed = settings.presets.includes(preset);
+        diag(`  -> preset ${preset} ${allowed ? 'allowed' : 'not in allowlist'}`);
+        return allowed;
+    }
+    /**
+     * A session's committed preset choice.
+     *
+     * This is the event that matters: a new task is created with the deployment
+     * default and the picker's mode is applied afterwards, so `agent/created`
+     * alone sees the wrong composition.
+     */
+    ctx.on('agent-preset/selected', async (sessionId, agentPreset) => {
+        diag(`agent-preset/selected session=${String(sessionId)} preset=${describe(agentPreset)}`);
+        if (!settings.presets.includes(agentPreset))
+            return;
+        const agent = ctx.get('agents')?.get(String(sessionId));
+        if (agent === undefined) {
+            diag('  -> no live agent for that session');
+            return;
+        }
+        try {
+            await attach(agent);
+            diag(`  -> attached=${String(connections.has(agent))}`);
+        }
+        catch (error) {
+            diag(`  -> attach THREW: ${error instanceof Error ? `${error.name}: ${error.message}` : String(error)}`);
+        }
+    });
+    ctx.on('agent/created', async ({ agent, signal }) => {
+        // Ask the registry which preset this Agent actually uses. The session header
+        // records the deployment default at creation, which the new-task picker may
+        // replace afterwards — so the header is a fallback, never the authority.
+        diag(`agent/created id=${String(agent.id)} agentCtxTools=${describe(agent.ctx.tools)}`);
+        if (!presetAllows(agent))
+            return;
+        try {
+            await attach(agent, signal);
+        }
+        catch (error) {
+            diag(`  -> attach THREW: ${error instanceof Error ? `${error.name}: ${error.message}` : String(error)}`);
+            return;
+        }
+        diag(`  -> attach done, connections=${String(connections.size)}, tools=${JSON.stringify(agent.ctx.tools.schemas(agent).map((t) => t.name).slice(-4))}`);
+    });
+    // LCU's lifecycle contract: the runtime owns per-turn cleanup (native helper
+    // and Sky contexts on macOS, temporary Chrome tabs), and only the host knows
+    // when a turn really ended.
+    ctx.on('agent/turn-stopping', async ({ agent, turn, signal }) => {
+        const state = connections.get(agent);
+        diag(`agent/turn-stopping id=${String(agent.id)} turn=${String(turn)} aborted=${String(signal.aborted)} haveConnection=${String(state !== undefined)}`);
+        if (state === undefined)
+            return;
+        const sessionId = String(agent.id);
+        const turnId = String(turn);
+        try {
+            await state.connection.turnEnded(sessionId, turnId, signal.aborted ? 'Interrupt' : 'Stop');
+            state.pendingCleanup = undefined;
+        }
+        catch (error) {
+            const code = error instanceof LcuError ? error.code : undefined;
+            if (code === TURN_CLEANUP_TIMEOUT_CODE) {
+                // Expected on macOS when the signed helper is slow. The runtime keeps
+                // cleaning in the background; block the next call until it settles.
+                state.pendingCleanup = { sessionId, turnId };
+                diag('turn_ended: cleanup still running; LCU calls blocked until it settles');
+                ctx.logger.warn('lcu: turn cleanup is still running; computer-use calls are blocked until it settles');
+            }
+            else {
+                diag(`turn_ended FAILED: ${error instanceof Error ? error.message : String(error)}`);
+                ctx.logger.warn(`lcu: turn_ended failed (${error instanceof Error ? error.message : String(error)})`);
+            }
+        }
+    });
+    // Drain every connection if the plugin itself unloads.
+    ctx.effect(() => () => {
+        const live = [...connections.values()];
+        connections.clear();
+        for (const { connection } of live)
+            void connection.close();
+    });
+}
+/**
+ * The computer-use seam brands its provider name, but the brand is compile-time
+ * only: the runtime value is the plain string, and importing the seam's own
+ * helper would be a value import from a package this plugin only type-checks
+ * against.
+ */
+function computerUseProviderName(value) {
+    return value;
+}
+export { resolveElicitation };
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

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

package/lib/tool.js

@@ -0,0 +1,262 @@
+/**
+ * Model-facing tools for LCU.
+ *
+ * The server owns the tool contract: `js` carries a ~1.5 KB description that is
+ * the API manual, and the model is told to read documentation out of the first
+ * tool result. So the definitions here are the server's, passed through
+ * unchanged — this module only adapts the transport (canonical value, text
+ * fallback, durable images) and enforces the visibility rule that only `js` and
+ * `js_reset` may reach the model.
+ *
+ * @module dsh-plugin-lcu/tool
+ */
+import { isDeepStrictEqual } from 'node:util';
+import { MODEL_TOOL_NAMES, LcuError } from "./connection.js";
+/** Media types the attachment store admits. */
+const IMAGE_MEDIA_TYPES = ['image/png', 'image/jpeg', 'image/webp', 'image/gif'];
+/** Canonical base64: standard alphabet, padded, no embedded whitespace. */
+const CANONICAL_BASE64 = /^[A-Za-z0-9+/]*={0,2}$/;
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/**
+ * The model-facing text for one MCP result.
+ *
+ * LCU returns documentation and command output as text, and screenshots as
+ * separate image blocks, so joining the text blocks is the whole projection;
+ * images are appended by {@link prepareProjection}.
+ *
+ * @param content - the raw MCP content array.
+ * @param toolName - the tool, for the empty-result diagnostic.
+ * @returns text for the model, never empty.
+ */
+export function extractText(content, toolName) {
+    const texts = [];
+    let images = 0;
+    for (const block of content) {
+        if (!isRecord(block))
+            continue;
+        if (block.type === 'text' && typeof block.text === 'string')
+            texts.push(block.text);
+        else if (block.type === 'image')
+            images += 1;
+    }
+    if (texts.length > 0)
+        return texts.join('\n');
+    if (images > 0)
+        return `[${String(images)} image${images === 1 ? '' : 's'}]`;
+    return `[${toolName} returned no text content]`;
+}
+/**
+ * Decode one image block, rejecting anything the store would not accept.
+ *
+ * @param block - a declared MCP image block.
+ * @returns the decoded attachment payload.
+ * @throws {Error} when the media type is not admitted or the base64 is not canonical.
+ */
+export function decodeImage(block) {
+    if (!IMAGE_MEDIA_TYPES.includes(block.mimeType)) {
+        throw new Error('the declared media type is not PNG, JPEG, WebP, or GIF');
+    }
+    if (!CANONICAL_BASE64.test(block.data))
+        throw new Error('the image data is not canonical base64');
+    const data = Buffer.from(block.data, 'base64');
+    if (data.toString('base64') !== block.data)
+        throw new Error('the image data is not canonical base64');
+    return { data, mediaType: block.mimeType };
+}
+/** Stable diagnostic text for an image the host could not admit. */
+export function imageDiagnostic(block, reason) {
+    const mediaType = isRecord(block) && typeof block.mimeType === 'string' ? block.mimeType : 'unknown media type';
+    return `[image unavailable: ${mediaType}; ${reason}; the raw image stays available to programmatic callers]`;
+}
+/**
+ * Resolve the attachment store for this call, verifying the model can take images.
+ *
+ * @param ctx - the plugin context.
+ * @param exec - the in-flight call.
+ * @returns the attachment store.
+ * @throws {Error} with the reason the images cannot be delivered.
+ */
+async function resolveAttachments(ctx, exec) {
+    const attachments = ctx.get('attachments');
+    if (attachments === undefined)
+        throw new Error('no attachment store is mounted');
+    const routed = exec.agent?.session.requestHeader()?.config;
+    const provider = routed?.provider ?? exec.agent?.options.provider;
+    const model = routed?.model ?? exec.agent?.options.model;
+    const llm = ctx.get('llm');
+    if (provider === undefined || model === undefined || llm === undefined) {
+        throw new Error('the current model route could not be resolved');
+    }
+    let info;
+    try {
+        info = await llm.resolveModelInfo(provider, model, exec.signal);
+    }
+    catch {
+        throw new Error('the current model route could not be verified');
+    }
+    if (info.inputModalities === undefined || !info.inputModalities.includes('image')) {
+        throw new Error(`model "${model}" does not declare image input`);
+    }
+    if (exec.signal.aborted)
+        throw new Error('the tool call was canceled before image storage');
+    return attachments;
+}
+/**
+ * Build the ordered content blocks for one result: text and images interleaved
+ * exactly as the server emitted them, with any inadmissible image replaced by a
+ * diagnostic instead of failing the whole call.
+ */
+async function prepareProjection(ctx, exec, content, toolName) {
+    const decoded = [];
+    const indexes = [];
+    const failures = new Map();
+    content.forEach((block, index) => {
+        if (!isRecord(block) || block.type !== 'image')
+            return;
+        indexes.push(index);
+        try {
+            decoded.push(decodeImage(block));
+        }
+        catch (error) {
+            failures.set(index, error instanceof Error ? error.message : String(error));
+        }
+    });
+    if (failures.size > 0) {
+        return content.map((block, index) => isRecord(block) && block.type === 'image'
+            ? { type: 'text', text: imageDiagnostic(block, failures.get(index) ?? 'another image in the same result was invalid') }
+            : block);
+    }
+    let attachments;
+    try {
+        attachments = await resolveAttachments(ctx, exec);
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        return content.map((block) => isRecord(block) && block.type === 'image'
+            ? { type: 'text', text: imageDiagnostic(block, reason) }
+            : block);
+    }
+    try {
+        const refs = await attachments.saveImages(decoded);
+        const byIndex = new Map(indexes.map((index, offset) => [index, refs[offset]]));
+        return content.map((block, index) => {
+            if (!isRecord(block) || block.type !== 'image')
+                return block;
+            const ref = byIndex.get(index);
+            return ref === undefined
+                ? { type: 'text', text: imageDiagnostic(block, 'the attachment store returned no reference') }
+                : { type: 'image', attachment: ref };
+        });
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        return content.map((block) => isRecord(block) && block.type === 'image'
+            ? { type: 'text', text: imageDiagnostic(block, `the image could not be stored: ${reason}`) }
+            : block);
+    }
+}
+/**
+ * Build one model-facing tool from a server descriptor.
+ *
+ * @param descriptor - the tool as `tools/list` reported it.
+ * @param connection - the connection this agent's calls go through.
+ * @param ctx - the plugin context, used for the attachment store.
+ * @param options - host hooks around the call.
+ * @returns a registrable tool definition.
+ */
+export function createLcuTool(descriptor, connection, ctx, options = {}) {
+    const projections = new WeakMap();
+    const toolName = descriptor.name;
+    return {
+        name: toolName,
+        // The server's description is the API manual; never truncate or rewrite it.
+        description: descriptor.description,
+        parameters: descriptor.inputSchema,
+        output: {
+            schema: {
+                type: 'object',
+                properties: {
+                    content: { type: 'array', items: {} },
+                    structuredContent: {},
+                },
+                required: ['content'],
+                additionalProperties: false,
+            },
+            render(_args, value) {
+                const content = isRecord(value) && Array.isArray(value.content) ? value.content : [];
+                return [{ type: 'text', text: extractText(content, toolName) }];
+            },
+        },
+        async execute(args, exec) {
+            // Refuse to touch the desktop while a previous turn's cleanup is unsettled.
+            await options.beforeCall?.();
+            // The loop hands us parsed model arguments, which can be any JSON value if
+            // the model misbehaves; an empty object lets the server report the missing
+            // parameter specifically instead of us inventing an error.
+            const callArgs = isRecord(args) ? args : {};
+            const result = await connection.callTool(toolName, callArgs, { signal: exec.signal });
+            const content = result.content;
+            const text = extractText(content, toolName);
+            // MCP isError becomes a thrown error so the runtime records a failed call.
+            if (result.isError)
+                throw new Error(text);
+            const value = { content };
+            if (result.structuredContent !== undefined)
+                value.structuredContent = result.structuredContent;
+            if (content.some((block) => isRecord(block) && block.type === 'image')) {
+                const projected = await prepareProjection(ctx, exec, content, toolName);
+                projections.set(exec, { value, content: projected });
+            }
+            return value;
+        },
+        projectContent(exec, result) {
+            const projection = projections.get(exec);
+            if (projection === undefined)
+                return undefined;
+            projections.delete(exec);
+            if (result.isError === true)
+                return undefined;
+            // Policy may have replaced the value; only install our images when the
+            // canonical value is still the one we prepared them for.
+            if (!isDeepStrictEqual(result.value, projection.value))
+                return undefined;
+            return projection.content;
+        },
+    };
+}
+/**
+ * Build every model-facing tool for one agent's connection.
+ *
+ * @param connection - the connected LCU session.
+ * @param ctx - the plugin context.
+ * @returns tool definitions for `js` and `js_reset`, in server order.
+ * @throws {LcuError} when the server does not expose the model tools.
+ */
+export function buildLcuTools(connection, ctx, options = {}) {
+    const descriptors = connection.modelTools();
+    const missing = MODEL_TOOL_NAMES.filter((name) => !descriptors.some((tool) => tool.name === name));
+    if (missing.length > 0) {
+        throw new LcuError('tools/list', `the server does not expose ${missing.join(', ')}`);
+    }
+    return descriptors.map((descriptor) => createLcuTool(descriptor, connection, ctx, options));
+}
+/**
+ * Register the model-facing tools in one agent's scope.
+ *
+ * Registration is per agent rather than at plugin mount because the server owns
+ * the schemas: they can only be fetched after connecting, and an agent only
+ * needs the capability once it exists.
+ *
+ * @param agentCtx - the agent's own context; its registrations unwind on disposal.
+ * @param connection - the agent's connected LCU session.
+ * @param ctx - the plugin context.
+ * @returns a disposer that unregisters every tool.
+ */
+export function registerLcuTools(agentCtx, connection, ctx, options = {}) {
+    const disposers = buildLcuTools(connection, ctx, options).map((definition) => agentCtx.tools.register(definition));
+    return () => {
+        for (const dispose of disposers.reverse())
+            dispose();
+    };
+}
+//# sourceMappingURL=tool.js.map

package/lib/tool.js.map

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