dsh-plugin-lcu 0.1.0

package/lib/types/approval.d.ts

@@ -0,0 +1,71 @@
+/**
+ * LCU approval shapes.
+ *
+ * LCU's original runtime asks the host before it touches an app, and the request
+ * is a specific `elicitation/create` form. This ports the recognition and
+ * mapping rules from LCU's own shared client so a DSH host presents exactly the
+ * choices the runtime offered — no more (granting an unoffered persistence scope
+ * would let the agent keep desktop access the runtime meant to bound) and no
+ * fewer (dropping `always` would nag the user every turn).
+ *
+ * @module dsh-plugin-lcu/approval
+ */
+import type { LcuElicitationRequest, LcuElicitationResponse } from './connection.ts';
+/** One choice a native-app approval may offer. */
+export interface ApprovalChoice {
+    readonly value: 'once' | 'session' | 'always' | 'decline';
+    readonly label: string;
+}
+/** A recognized native-app approval request. */
+export interface NativeAppApproval {
+    readonly message: string;
+    readonly resource: string;
+    readonly choices: readonly ApprovalChoice[];
+}
+/**
+ * Recognize the runtime's native-app approval request.
+ *
+ * The shape is deliberately narrow: an empty-schema form whose `_meta` names the
+ * computer-use connector and a concrete app. Every other elicitation the server
+ * may send is *not* this, and must be handled elsewhere or cancelled.
+ *
+ * @param request - one `elicitation/create` payload.
+ * @returns the recognized request, or `undefined` when it is a different shape.
+ */
+export declare function nativeAppApproval(request: LcuElicitationRequest): NativeAppApproval | undefined;
+/**
+ * Map the user's choice back to the response the runtime accepts.
+ *
+ * @param request - the same payload the choices came from.
+ * @param value - the chosen value, or `'cancel'` for a dismissed prompt.
+ * @returns an accept/decline/cancel answer; anything unrecognized cancels.
+ */
+export declare function nativeAppApprovalResponse(request: LcuElicitationRequest, value: string): LcuElicitationResponse;
+/**
+ * Map a presented option label back to the value the runtime accepts.
+ *
+ * These are different strings: the question surface answers with the option's
+ * LABEL (`"Always allow"`), while the elicitation response needs the choice
+ * VALUE (`"always"`). Passing the label straight through looks up nothing and
+ * silently cancels a choice the user actually made.
+ *
+ * @param approval - the request the labels were presented for.
+ * @param label - the label the user selected, or `undefined` when dismissed.
+ * @returns the choice value, or `'cancel'` when the label matches no option.
+ */
+export declare function approvalValueForLabel(approval: NativeAppApproval, label: string | undefined): string;
+/** The exact origin a browser-site approval names, when it names one. */
+export declare function originApprovalOrigin(request: LcuElicitationRequest): string | undefined;
+/** Whether the request names an already-authorized exact origin. */
+export declare function isPreApprovedOrigin(request: LcuElicitationRequest, allowedOrigins: ReadonlySet<string>): boolean;
+/**
+ * Normalize a set of user-configured origins.
+ *
+ * Only exact HTTP(S) origins are accepted; anything else is dropped rather than
+ * widened, because a relaxed match here is a site the user never approved.
+ *
+ * @param values - raw origin strings from configuration.
+ * @returns the accepted origins.
+ */
+export declare function normalizeOrigins(values: readonly string[]): Set<string>;
+//# sourceMappingURL=approval.d.ts.map

package/lib/types/approval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval.d.ts","sourceRoot":"","sources":["../../src/approval.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAA;AAEpF,kDAAkD;AAClD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAA;IACzD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAED,gDAAgD;AAChD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,CAAA;CAC5C;AAgBD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,qBAAqB,GAAG,iBAAiB,GAAG,SAAS,CAsB/F;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,qBAAqB,EAC9B,KAAK,EAAE,MAAM,GACZ,sBAAsB,CAYxB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,iBAAiB,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAGpG;AAED,yEAAyE;AACzE,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,qBAAqB,GAAG,MAAM,GAAG,SAAS,CAWvF;AAED,oEAAoE;AACpE,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,qBAAqB,EAC9B,cAAc,EAAE,WAAW,CAAC,MAAM,CAAC,GAClC,OAAO,CAGT;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC,CAavE"}

package/lib/types/connection.d.ts

@@ -0,0 +1,178 @@
+/**
+ * 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
+ */
+/** One tool as the server describes it. */
+export interface LcuTool {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: Record<string, unknown>;
+}
+/** A single MCP content block, text or image. */
+export type LcuContentBlock = {
+    readonly type: 'text';
+    readonly text: string;
+} | {
+    readonly type: 'image';
+    readonly data: string;
+    readonly mimeType: string;
+} | {
+    readonly type: string;
+    readonly [key: string]: unknown;
+};
+/** The result of one `tools/call`. */
+export interface LcuCallResult {
+    readonly content: readonly LcuContentBlock[];
+    readonly isError: boolean;
+    readonly structuredContent?: unknown;
+}
+/** An `elicitation/create` request as the server sends it. */
+export interface LcuElicitationRequest {
+    readonly message?: string;
+    readonly mode?: string;
+    readonly requestedSchema?: unknown;
+    readonly _meta?: Record<string, unknown>;
+    readonly [key: string]: unknown;
+}
+/** What a host may answer. Anything else is normalized to `cancel`. */
+export type LcuElicitationResponse = {
+    readonly action: 'accept';
+    readonly content?: Record<string, unknown>;
+    readonly _meta?: Record<string, unknown>;
+} | {
+    readonly action: 'decline';
+} | {
+    readonly action: 'cancel';
+};
+/** Tools the model may see. Everything else is host-only. */
+export declare const MODEL_TOOL_NAMES: readonly string[];
+/** Host-only tools, named so a mistake is loud rather than silent. */
+export declare const HOST_ONLY_TOOL_NAMES: readonly string[];
+/** Lifecycle events the server accepts for `turn_ended`. */
+export type LcuTurnEndEvent = 'Stop' | 'Interrupt' | 'SubagentStop';
+/** Connection options. */
+export interface LcuConnectionOptions {
+    /** Executable to spawn; defaults to the installed `lcu` launcher. */
+    readonly command: string;
+    /** Extra arguments, e.g. `['--chrome']` to enable the browser surface. */
+    readonly args?: readonly string[];
+    /** Extra environment layered over the current process environment. */
+    readonly env?: Readonly<Record<string, string>>;
+    /** Working directory for the child process. */
+    readonly cwd?: string;
+    /**
+     * Answer one elicitation. Omit to fail closed: every approval then cancels,
+     * which is what LCU expects from a host that cannot present the request.
+     */
+    readonly onElicitation?: (request: LcuElicitationRequest, signal: AbortSignal) => Promise<LcuElicitationResponse>;
+    /** Called whenever the server's tool list changes. */
+    readonly onToolsChanged?: (tools: readonly LcuTool[]) => void;
+    /** Receives child-process stderr lines; never model-visible. */
+    readonly onStderr?: (line: string) => void;
+}
+/** Where a request is in its lifecycle, for a diagnostic that names the stage. */
+export type LcuStage = 'spawn' | 'initialize' | 'tools/list' | 'tools/call' | 'turn_ended';
+/**
+ * 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 declare const TURN_CLEANUP_TIMEOUT_CODE = "LCU_TURN_CLEANUP_TIMEOUT";
+/** A failure that names the protocol stage it happened at. */
+export declare class LcuError extends Error {
+    readonly stage: LcuStage;
+    /** Stable machine-readable classification, when one applies. */
+    readonly code?: string;
+    constructor(stage: LcuStage, message: string, cause?: unknown, code?: string);
+}
+/**
+ * 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 declare function classifyTurnEndFailure(result: LcuCallResult): LcuError | undefined;
+/**
+ * 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 declare function resolveElicitation(handler: LcuConnectionOptions['onElicitation'], request: LcuElicitationRequest, activeCalls?: ReadonlySet<AbortSignal>): Promise<LcuElicitationResponse>;
+/**
+ * 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 declare class LcuConnection {
+    #private;
+    constructor(options: LcuConnectionOptions);
+    /** The server's `initialize.instructions`, injected into model context. */
+    get instructions(): string;
+    /** Server identity, for diagnostics. */
+    get serverInfo(): {
+        name?: string;
+        version?: string;
+    };
+    /** Everything the server advertised, including host-only tools. */
+    get allTools(): readonly LcuTool[];
+    /** The tools the model may see, in server order. */
+    modelTools(): LcuTool[];
+    /**
+     * Spawn `lcu`, complete the MCP handshake, and discover tools.
+     *
+     * @throws {LcuError} when the process cannot start or the handshake fails.
+     */
+    connect(signal?: AbortSignal): Promise<void>;
+    /**
+     * 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.
+     */
+    callTool(name: string, args: Readonly<Record<string, unknown>>, options?: {
+        readonly timeoutMs?: number;
+        readonly signal?: AbortSignal;
+    }): Promise<LcuCallResult>;
+    /**
+     * 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`.
+     */
+    turnEnded(sessionId: string, turnId: string, event?: LcuTurnEndEvent): Promise<void>;
+    /** Close the connection, terminating the child process. */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=connection.d.ts.map

package/lib/types/connection.d.ts.map

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

package/lib/types/diag.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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
+ */
+/** Append one diagnostic line; silently does nothing if the file cannot be written. */
+export declare function diag(message: string): void;
+/** Describe a value for the log without dumping unbounded data. */
+export declare function describe(value: unknown): string;
+//# sourceMappingURL=diag.d.ts.map

package/lib/types/diag.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diag.d.ts","sourceRoot":"","sources":["../../src/diag.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAWH,uFAAuF;AACvF,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAU1C;AAED,mEAAmE;AACnE,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAS/C"}

package/lib/types/host-guard.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 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
+ */
+/**
+ * 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 declare const STATIC_HOST_BUNDLE_IDS: readonly string[];
+/** The enclosing `.app` bundle of an executable path, if any. */
+export declare function enclosingAppBundle(executablePath: string): string | 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 declare function ancestorBundleIds(): Promise<ReadonlySet<string>>;
+/**
+ * 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 declare function isAgentHostApp(app: string): Promise<boolean>;
+/** Reset the memoized ancestry; for tests only. */
+export declare function resetAncestorCache(): void;
+//# sourceMappingURL=host-guard.d.ts.map

package/lib/types/host-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-guard.d.ts","sourceRoot":"","sources":["../../src/host-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAMH;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,MAAM,EAenD,CAAA;AAgBD,iEAAiE;AACjE,wBAAgB,kBAAkB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAQ7E;AAUD;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAqBtE;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAiBlE;AAED,mDAAmD;AACnD,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC"}

package/lib/types/index.d.ts

@@ -0,0 +1,49 @@
+/**
+ * `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 type { Context } from '@deepseek-ai/cordis';
+import { resolveElicitation } from './connection.ts';
+export declare const name = "lcu";
+export declare const inject: string[];
+/** Plugin configuration. */
+export interface Config {
+    /** LCU launcher; defaults to the installed path, overridable for a custom prefix. */
+    command?: string;
+    /** Enable the Chrome surface (`lcu --chrome`); needs the extension and site approvals. */
+    chrome?: boolean;
+    /** Enable the original computer-audio recording API (`lcu --audio`). */
+    audio?: boolean;
+    /**
+     * Agent preset ids whose sessions get the tools.
+     *
+     * Presets are independent compositions, so this is an explicit list rather
+     * than a capability the preset itself declares; `heavy` is the preset the
+     * generator script builds for this plugin.
+     */
+    presets?: string[];
+    /** Exact HTTP(S) origins pre-approved for browser access, never widened. */
+    allowedOrigins?: string[];
+    /** Prompt section order for the injected LCU instructions. */
+    sectionOrder?: number;
+}
+/**
+ * Mount the LCU capability.
+ *
+ * @param ctx - the host context this row mounts into.
+ * @param config - the row's configuration.
+ */
+export declare function apply(ctx: Context, config: Config): void;
+export { resolveElicitation };
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAKlD,OAAO,EAC+C,kBAAkB,EAEvE,MAAM,iBAAiB,CAAA;AAKxB,eAAO,MAAM,IAAI,QAAQ,CAAA;AACzB,eAAO,MAAM,MAAM,UAA4B,CAAA;AAQ/C,4BAA4B;AAC5B,MAAM,WAAW,MAAM;IACrB,qFAAqF;IACrF,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,0FAA0F;IAC1F,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,wEAAwE;IACxE,KAAK,CAAC,EAAE,OAAO,CAAA;IACf;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB,4EAA4E;IAC5E,cAAc,CAAC,EAAE,MAAM,EAAE,CAAA;IACzB,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AA2BD;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAiQxD;AAYD,OAAO,EAAE,kBAAkB,EAAE,CAAA"}

package/lib/types/tool.d.ts

@@ -0,0 +1,90 @@
+/**
+ * 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 type { Context } from '@deepseek-ai/cordis';
+import type { ToolDefinition } from '@deepseek-ai/dsh-tools';
+import type { LcuConnection, LcuContentBlock, LcuTool } from './connection.ts';
+interface ImageBlock {
+    readonly type: 'image';
+    readonly data: string;
+    readonly mimeType: string;
+}
+/**
+ * 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 declare function extractText(content: readonly LcuContentBlock[], toolName: string): string;
+/**
+ * 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 declare function decodeImage(block: ImageBlock): {
+    data: Buffer;
+    mediaType: string;
+};
+/** Stable diagnostic text for an image the host could not admit. */
+export declare function imageDiagnostic(block: unknown, reason: string): string;
+/** Host-owned hooks around one call. */
+export interface LcuToolOptions {
+    /**
+     * Awaited before every call, and its rejection fails the call.
+     *
+     * The runtime's per-turn cleanup is asynchronous: when it outlives the host's
+     * wait, acting on the desktop before it finishes is unsafe. This is where the
+     * host retries it and refuses the call if it still has not settled.
+     */
+    readonly beforeCall?: () => Promise<void>;
+}
+/**
+ * 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 declare function createLcuTool(descriptor: LcuTool, connection: LcuConnection, ctx: Context, options?: LcuToolOptions): ToolDefinition;
+/**
+ * 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 declare function buildLcuTools(connection: LcuConnection, ctx: Context, options?: LcuToolOptions): ToolDefinition[];
+/**
+ * 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 declare function registerLcuTools(agentCtx: Context, connection: LcuConnection, ctx: Context, options?: LcuToolOptions): () => void;
+export {};
+//# sourceMappingURL=tool.d.ts.map

package/lib/types/tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../src/tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAGlD,OAAO,KAAK,EAAE,cAAc,EAAsD,MAAM,wBAAwB,CAAA;AAEhH,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAA;AAS9E,UAAU,UAAU;IAClB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAC1B;AAUD;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAWzF;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAQlF;AAED,oEAAoE;AACpE,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAGtE;AAgGD,wCAAwC;AACxC,MAAM,WAAW,cAAc;IAC7B;;;;;;OAMG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1C;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,OAAO,EACnB,UAAU,EAAE,aAAa,EACzB,GAAG,EAAE,OAAO,EACZ,OAAO,GAAE,cAAmB,GAC3B,cAAc,CAuDhB;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,aAAa,EACzB,GAAG,EAAE,OAAO,EACZ,OAAO,GAAE,cAAmB,GAC3B,cAAc,EAAE,CAOlB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,OAAO,EACjB,UAAU,EAAE,aAAa,EACzB,GAAG,EAAE,OAAO,EACZ,OAAO,GAAE,cAAmB,GAC3B,MAAM,IAAI,CAKZ"}

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "dsh-plugin-lcu",
+  "version": "0.1.0",
+  "description": "Drive the desktop and Chrome from DeepSeek Harness through LCU (Codex computer use, decoupled from the app).",
+  "keywords": [
+    "dsh-plugin",
+    "deepseek-harness",
+    "dsh",
+    "computer-use",
+    "browser-use",
+    "lcu",
+    "codex",
+    "cua"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "Kanner",
+    "email": "kanner.chen@gmail.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ckanner/dsh-plugin-lcu.git"
+  },
+  "homepage": "https://github.com/ckanner/dsh-plugin-lcu#readme",
+  "bugs": {
+    "url": "https://github.com/ckanner/dsh-plugin-lcu/issues"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "scripts",
+    "dev-types",
+    "docs/README.zh.md"
+  ],
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test \"tests/*.spec.ts\"",
+    "prepare": "npm run build",
+    "presets": "node scripts/gen-presets.mjs",
+    "probe": "node scripts/probe-lcu.mjs",
+    "update-codex": "node scripts/update-codex.mjs"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": ">=0.0.1-rc.1 <0.3.0",
+    "@deepseek-ai/dsh-tools": ">=0.0.1-rc.1 <0.3.0",
+    "@deepseek-ai/dsh-system-prompt": ">=0.0.1-rc.1 <0.3.0"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": { "optional": true },
+    "@deepseek-ai/dsh-tools": { "optional": true },
+    "@deepseek-ai/dsh-system-prompt": { "optional": true }
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "typescript": "^5.9.0"
+  }
+}

package/scripts/codex-baseline.json

@@ -0,0 +1,10 @@
+{
+  "codex": "0.160.1",
+  "verifiedAt": "2026-10-07T09:56:24.427Z",
+  "previous": "0.160.1",
+  "gates": {
+    "handshake": "ok",
+    "schema": "ok",
+    "turn": "ok"
+  }
+}