dsh-plugin-lcu 0.3.7 → 0.4.0

package/lib/types/ptc.d.ts

@@ -0,0 +1,85 @@
+/**
+ * The PTC-facing LCU surface.
+ *
+ * The ChatGPT application's CUA runtime is a JavaScript REPL (`js`). PTC
+ * programs cannot call that REPL's `cua` object directly, so this module exposes
+ * one ordinary tool, `cua`, whose binding is a small RPC: a program calls a
+ * method, the host runs it inside the persistent CUA REPL, and app/tab/window
+ * objects come back as opaque handles.
+ *
+ * The model never sees the `js` tool. It sees the generated SDK's `tools.cua`
+ * binding and the `connectCua` prelude in {@link ptcBridgeInstructions}.
+ *
+ * @module dsh-plugin-lcu/ptc
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { ToolDefinition } from '@deepseek-ai/dsh-tools';
+import type { RuntimeConnection } from './session.ts';
+/** The single model-facing tool of the PTC surface. */
+export declare const CUA_TOOL_NAME = "cua";
+/** Marker printed by the in-REPL bridge so the host can find structured output. */
+export declare const CUA_RESULT_MARKER = "__DSH_LCU_RESULT__";
+/**
+ * The in-REPL half of the bridge.
+ *
+ * It is deliberately installed with `??=` so a persistent PTC runtime (or a
+ * persistent CUA REPL) can call it many times without replacing live handles.
+ * Values that expose methods are remembered and returned as opaque handles;
+ * plain JSON is passed through unchanged.
+ */
+export declare const CUA_PRELUDE: string;
+/** Host-owned hooks around one bridge call. */
+export interface CuaToolOptions {
+    /** Awaited before every call; a rejection fails the call. */
+    readonly beforeCall?: () => Promise<void>;
+    /** The Agent's active turn identity, used for runtime approvals and cleanup. */
+    readonly currentTurn?: () => string | undefined;
+}
+/** One validated bridge request. */
+export interface CuaRequest {
+    readonly target?: string;
+    readonly method: string;
+    readonly args: readonly unknown[];
+}
+/**
+ * Validate the model's arguments.
+ *
+ * The tool is intentionally generic; the method name and positional arguments
+ * are checked here so the in-REPL bridge never receives a non-string method or
+ * a non-array argument list.
+ *
+ * @param value - parsed tool arguments.
+ * @returns the normalized request.
+ * @throws {Error} when the request shape is not usable.
+ */
+export declare function readCuaRequest(value: unknown): CuaRequest;
+/**
+ * Build the one model-facing PTC tool.
+ *
+ * @param connection - the Agent's LCU connection.
+ * @param ctx - the plugin context, kept for the screenshot/attachment projection.
+ * @param options - host hooks.
+ * @returns a registrable tool definition.
+ */
+export declare function createCuaTool(connection: RuntimeConnection, ctx: Context, options?: CuaToolOptions): ToolDefinition;
+/**
+ * Register the PTC surface in one Agent's scope.
+ *
+ * @param agentCtx - the Agent's own context; registrations unwind on disposal.
+ * @param connection - the Agent's connected LCU session.
+ * @param ctx - the plugin context.
+ * @param options - host hooks.
+ * @returns a disposer that unregisters the tool.
+ */
+export declare function registerCuaTool(agentCtx: Context, connection: RuntimeConnection, ctx: Context, options?: CuaToolOptions): () => void;
+/**
+ * Model-facing PTC instructions.
+ *
+ * The generated SDK already declares `tools.cua`; this section teaches the model
+ * how to turn it into the same `cua` object the native REPL used to expose.
+ *
+ * @param bridgeUrl - absolute `file:` URL of the compiled `bridge.js`.
+ * @returns the prompt section text.
+ */
+export declare function ptcBridgeInstructions(bridgeUrl: string): string;
+//# sourceMappingURL=ptc.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ptc.d.ts","sourceRoot":"","sources":["../../src/ptc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAIlD,OAAO,KAAK,EAAE,cAAc,EAAsD,MAAM,wBAAwB,CAAA;AAGhH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAGrD,uDAAuD;AACvD,eAAO,MAAM,aAAa,QAAQ,CAAA;AAElC,mFAAmF;AACnF,eAAO,MAAM,iBAAiB,uBAAuB,CAAA;AASrD;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,QAyDvB,CAAA;AAED,+CAA+C;AAC/C,MAAM,WAAW,cAAc;IAC7B,6DAA6D;IAC7D,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IACzC,gFAAgF;IAChF,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAA;CAChD;AAED,oCAAoC;AACpC,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,SAAS,OAAO,EAAE,CAAA;CAClC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU,CAiBzD;AAqHD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,iBAAiB,EAC7B,GAAG,EAAE,OAAO,EACZ,OAAO,GAAE,cAAmB,GAC3B,cAAc,CAqFhB;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,OAAO,EACjB,UAAU,EAAE,iBAAiB,EAC7B,GAAG,EAAE,OAAO,EACZ,OAAO,GAAE,cAAmB,GAC3B,MAAM,IAAI,CAEZ;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAwB/D"}

package/lib/types/tool.d.ts

@@ -1,17 +1,14 @@
 /**
  * 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.
+ * These builders predate the PTC surface and remain for the internal `js`
+ * transport plus the tests that cover it. The model-facing registration in
+ * `index.ts` now uses `ptc.ts`: PTC programs see `cua`, never `js`.
  *
  * @module dsh-plugin-lcu/tool
  */
 import type { Context } from '@deepseek-ai/cordis';
-import type { ToolDefinition } from '@deepseek-ai/dsh-tools';
+import type { ToolDefinition, ToolRunContext } from '@deepseek-ai/dsh-tools';
 import type { LcuContentBlock, LcuTool } from './connection.ts';
 import type { RuntimeConnection } from './session.ts';
 interface ImageBlock {
@@ -19,6 +16,13 @@ interface ImageBlock {
     readonly data: string;
     readonly mimeType: string;
 }
+interface PreparedProjection {
+    readonly value: unknown;
+    readonly content: readonly {
+        readonly type: string;
+        readonly [key: string]: unknown;
+    }[];
+}
 /**
  * The model-facing text for one MCP result.
  *
@@ -44,6 +48,12 @@ export declare function decodeImage(block: ImageBlock): {
 };
 /** Stable diagnostic text for an image the host could not admit. */
 export declare function imageDiagnostic(block: unknown, reason: string): string;
+/**
+ * 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.
+ */
+export declare function prepareProjection(ctx: Context, exec: ToolRunContext, content: readonly LcuContentBlock[], toolName: string): Promise<PreparedProjection['content']>;
 /** Host-owned hooks around one call. */
 export interface LcuToolOptions {
     /**
@@ -99,7 +109,7 @@ export declare function stuckStopHint(text: string): string | undefined;
  */
 export declare function createLcuTool(descriptor: LcuTool, connection: RuntimeConnection, ctx: Context, options?: LcuToolOptions): ToolDefinition;
 /**
- * Build every model-facing tool for one agent's connection.
+ * Build the legacy native tools for one agent's connection.
  *
  * @param connection - the connected LCU session.
  * @param ctx - the plugin context.

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

@@ -1 +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,eAAe,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAA;AAC/D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAUrD,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;AA2GD,wCAAwC;AACxC,MAAM,WAAW,cAAc;IAC7B;;;;;;OAMG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IACzC;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAA;CAChD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS,CAO5E;AAWD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAWtE;AAcD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAO9D;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,OAAO,EACnB,UAAU,EAAE,iBAAiB,EAC7B,GAAG,EAAE,OAAO,EACZ,OAAO,GAAE,cAAmB,GAC3B,cAAc,CA+DhB;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,iBAAiB,EAC7B,GAAG,EAAE,OAAO,EACZ,OAAO,GAAE,cAAmB,GAC3B,cAAc,EAAE,CAOlB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,iBAAiB,EAC7B,WAAW,EAAE,MAAM,MAAM,GAAG,SAAS,GACpC,cAAc,CAsEhB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,OAAO,EACjB,UAAU,EAAE,iBAAiB,EAC7B,GAAG,EAAE,OAAO,EACZ,OAAO,GAAE,cAAmB,GAC3B,MAAM,IAAI,CASZ"}
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../src/tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAGlD,OAAO,KAAK,EAAE,cAAc,EAAsC,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAEhH,OAAO,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAA;AAC/D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAUrD,UAAU,UAAU;IAClB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAC1B;AAED,UAAU,kBAAkB;IAC1B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB,QAAQ,CAAC,OAAO,EAAE,SAAS;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,EAAE,CAAA;CACxF;AAKD;;;;;;;;;;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;AAiCD;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,cAAc,EACpB,OAAO,EAAE,SAAS,eAAe,EAAE,EACnC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,kBAAkB,CAAC,SAAS,CAAC,CAAC,CA8DxC;AAED,wCAAwC;AACxC,MAAM,WAAW,cAAc;IAC7B;;;;;;OAMG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IACzC;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAA;CAChD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS,CAO5E;AAWD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAWtE;AAcD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAO9D;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,OAAO,EACnB,UAAU,EAAE,iBAAiB,EAC7B,GAAG,EAAE,OAAO,EACZ,OAAO,GAAE,cAAmB,GAC3B,cAAc,CA+DhB;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,iBAAiB,EAC7B,GAAG,EAAE,OAAO,EACZ,OAAO,GAAE,cAAmB,GAC3B,cAAc,EAAE,CAOlB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,iBAAiB,EAC7B,WAAW,EAAE,MAAM,MAAM,GAAG,SAAS,GACpC,cAAc,CAsEhB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,OAAO,EACjB,UAAU,EAAE,iBAAiB,EAC7B,GAAG,EAAE,OAAO,EACZ,OAAO,GAAE,cAAmB,GAC3B,MAAM,IAAI,CASZ"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-plugin-lcu",
-  "version": "0.3.7",
-  "description": "Drive the desktop and Chrome from DeepSeek Harness using the computer-use runtime inside the ChatGPT desktop application.",
+  "version": "0.4.0",
+  "description": "PTC Computer/Browser CUA for DeepSeek Harness, backed by the runtime inside the ChatGPT desktop application.",
   "keywords": [
     "dsh-plugin",
     "deepseek-harness",

package/scripts/codex-baseline.json

@@ -1,7 +1,7 @@
 {
-  "codex": "0.160.1",
-  "verifiedAt": "2026-10-07T09:56:24.427Z",
-  "previous": "0.160.1",
+  "codex": "0.165.0",
+  "verifiedAt": "2026-10-29T08:37:59.144Z",
+  "previous": "0.164.0",
   "gates": {
     "handshake": "ok",
     "schema": "ok",

package/scripts/update-codex.mjs

@@ -55,7 +55,16 @@ const CODEX_ENTRY = 'node_modules/@openai/codex/bin/codex.js'
 // fetch every OS/arch payload (~275 MB each).
 const OVERRIDE_KEY = '"@deepseek-ai/dsh-subagent-codex>@openai/codex"'
 const OVERRIDE_RE = /^\s*"@deepseek-ai\/dsh-subagent-codex>@openai\/codex":.*$/m
-const APP_PNPM = '/Applications/DeepSeek Harness.app/Contents/Resources/runtime/pnpm/bin/pnpm.cjs'
+// The Desktop app bundles the pnpm the profile was installed with, and that
+// payload moves between releases: 0.2.1-rc.3 keeps it under primary-runtime,
+// while older builds used runtime/pnpm. Resolve the first one that exists —
+// a PATH pnpm is only a last resort, because a different pnpm may refuse this
+// profile's node_modules without a TTY.
+const APP_PNPM_CANDIDATES = [
+  '/Applications/DeepSeek Harness.app/Contents/Resources/runtime/primary-runtime/dependencies/pnpm/bin/pnpm.mjs',
+  '/Applications/DeepSeek Harness.app/Contents/Resources/runtime/pnpm/bin/pnpm.cjs',
+]
+const APP_PNPM = APP_PNPM_CANDIDATES.find((path) => existsSync(path))
 
 /**
  * The protocol surface dsh-subagent-codex/src/wire.ts actually uses.
@@ -129,7 +138,11 @@ function readOverride(text) {
 function writeOverride(text, version, key = OVERRIDE_KEY) {
   const line = `  ${key}: "${version}"`
   if (OVERRIDE_RE.test(text)) {
-    return text.replace(OVERRIDE_RE, line.trimStart())
+    // Keep the two-space indent: the replacement line lands inside the
+    // `overrides:` mapping. Dropping it (a previous bug) turned the key into a
+    // top-level entry, so pnpm silently ignored the override and installed the
+    // dependency's own pin instead.
+    return text.replace(OVERRIDE_RE, line)
   }
   if (/^overrides:/m.test(text)) {
     return text.replace(/^overrides:\s*$/m, `overrides:\n${line}`)
@@ -399,12 +412,15 @@ function install(profile, runner) {
     env: { ...process.env, CI: 'true' },
   })
   if (result.status !== 0) {
-    const detail = `${result.stdout ?? ''}\n${result.stderr ?? ''}`
+    // spawnSync reports a failure to start (missing executable, EACCES) as a
+    // null status plus `error`; without it the message would be empty.
+    const spawnFailure = result.error === undefined ? '' : `${result.error.message}\n`
+    const detail = `${spawnFailure}${result.stdout ?? ''}\n${result.stderr ?? ''}`
       .split('\n')
       .filter((line) => line.trim() !== '' && !line.includes('NPM_TOKEN'))
       .slice(-25)
       .join('\n')
-    throw new Error(`pnpm install failed (${result.status}):\n${detail}`)
+    throw new Error(`pnpm install failed (${String(result.status)}):\n${detail}`)
   }
 }
 
@@ -417,7 +433,7 @@ function install(profile, runner) {
  */
 function resolvePnpm(explicit) {
   if (explicit !== undefined) return [explicit]
-  if (existsSync(APP_PNPM)) return [process.execPath, APP_PNPM]
+  if (APP_PNPM !== undefined) return [process.execPath, APP_PNPM]
   return ['pnpm']
 }