dsh-plugin-lcu 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kanner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,316 @@
+# dsh-plugin-lcu
+
+English | [中文](docs/README.zh.md)
+
+Drive the desktop and Chrome from [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) by
+plugging in [LCU](https://github.com/amontlabs/lcu) — *Codex computer use, decoupled from the app*.
+
+LCU exposes the computer-use runtime that ships inside the ChatGPT desktop app as an MCP server.
+This plugin makes that runtime a first-class DSH capability: an Agent in an enabled mode gets a `js`
+tool that can read and operate real application windows and real Chrome tabs. **No Codex
+authentication is involved** — the runtime comes from your local ChatGPT installation, and LCU never
+downloads, installs, authenticates, or rewrites it.
+
+## Table of Contents
+
+- [What you get](#what-you-get)
+- [Requirements](#requirements)
+- [Install](#install)
+- [Use](#use)
+- [Configuration](#configuration)
+- [Approvals and the security model](#approvals-and-the-security-model)
+- [Understand the implementation](#understand-the-implementation)
+- [Troubleshooting](#troubleshooting)
+- [Companion tools](#companion-tools)
+- [Known limitations and deferred work](#known-limitations-and-deferred-work)
+- [Development](#development)
+- [License](#license)
+
+## What you get
+
+Two model-facing tools, exactly as LCU defines them — this plugin does not invent a schema:
+
+| Tool | What it does |
+|---|---|
+| `js` | Run one JavaScript program against the `cua` desktop/browser API. The first call returns the API documentation, and app or tab selection returns the initial UI state. |
+| `js_reset` | Discard the persistent JavaScript session and start a fresh runtime. |
+
+Two host-only tools stay reachable by the plugin and are **never** shown to the model:
+`turn_ended` (per-turn cleanup) and `js_add_node_module_dir`.
+
+Screenshots arrive as durable images through DSH's attachment store, so a model route that declares
+image input can actually look at the screen.
+
+## Requirements
+
+| | |
+|---|---|
+| OS | macOS on Apple Silicon. LCU supports Linux too, but this plugin is developed and verified on macOS. |
+| ChatGPT desktop app | Installed and signed by OpenAI. It supplies the runtime and the instructions. |
+| Python | 3.12 or newer, on `PATH` or in `/opt/homebrew/bin`, `/usr/local/bin`, `/usr/bin`. |
+| LCU | Installed separately — see below. |
+| DSH | A profile you can install a bundle into. |
+
+The plugin targets **macOS**; the `host-guard` uses `ps`/`plutil` and the lifecycle uses LCU's macOS
+path. Linux would need those two pieces revisited.
+
+## Install
+
+### 1. Install LCU
+
+Download the release archive for your platform, verify its checksum, and run its installer. Do **not**
+register another harness: this plugin is your harness.
+
+```sh
+TAG=v0.9.6
+TARGET=darwin-arm64
+curl -fLO "https://github.com/amontlabs/lcu/releases/download/$TAG/lcu-${TAG#v}-$TARGET.tar.gz"
+curl -fLO "https://github.com/amontlabs/lcu/releases/download/$TAG/lcu-${TAG#v}-$TARGET.tar.gz.sha256"
+shasum -a 256 -c "lcu-${TAG#v}-$TARGET.tar.gz.sha256"   # must print OK
+tar -xzf "lcu-${TAG#v}-$TARGET.tar.gz" && cd "lcu-${TAG#v}-$TARGET"
+./scripts/install.sh --runtime-only --yes
+```
+
+Then confirm the runtime loads:
+
+```sh
+~/.local/share/lcu/current/bin/lcu doctor --non-interactive
+```
+
+You want `Original Mac provider loaded; app listing and app-state methods are available`. Privacy
+permissions are granted on first use, not here.
+
+### 2. Install the plugin into a profile
+
+Installing makes the plugin's one row — an LCU host — active in that profile. It opens nothing at load
+time.
+
+```sh
+dsh plugin --profile <profile> add dsh-plugin-lcu
+```
+
+For the **desktop** app's managed profile, the CLI refuses; install it through the app's plugin
+manager (Settings ▸ Plugins) instead, which runs the same pnpm operation.
+
+### 3. Generate the presets
+
+DSH agent presets have **no inheritance**: a preset's `config.plugins` is its complete plugin list, and
+a patch replaces a whole entry rather than merging into it. So a custom preset must restate its base.
+Rather than hand-copying that list, generate it from the preset that is actually installed:
+
+```sh
+node node_modules/dsh-plugin-lcu/scripts/gen-presets.mjs --profile ~/.dsh/profiles/<profile>
+```
+
+This writes a marked block into that profile's `cordis.patch.yml` containing two presets:
+
+| Preset | Base | Adds |
+|---|---|---|
+| `daily` | the shipped `ptc` preset | `subagent_codex` enabled |
+| `heavy` | the same, with `tool-presentation: both` | everything above, and this plugin attaches |
+
+Re-run it after a DSH upgrade so the copies keep up. `--with-heavy` is implied; `--dry-run` prints
+without writing, and `--out FILE` writes somewhere else.
+
+> `heavy` sets the tool presentation to `both` on purpose. In pure `ptc` presentation the model only
+> sees `run_code`, so `js` would have to be nested as a JavaScript string inside another JavaScript
+> program. `both` keeps `js` directly callable.
+
+### 4. Configure which modes get the capability
+
+The plugin is one root row with a `presets` allowlist. Edit the installed
+`cordis.patch.yml` (or the profile patch) to match the preset ids you generated:
+
+```yaml
+- id: lcu
+  name: 'dsh-plugin-lcu'
+  config:
+    presets:
+      - heavy
+```
+
+### 5. Restart, then make one call
+
+Restart the harness — plugin **code and configuration changes are not hot-reloaded**. Then start a
+task in the `heavy` mode (displayed as **重活**) and ask it to do something harmless:
+
+> Use the `js` tool to run `await cua.getState();` and tell me which apps are running.
+
+The first time an app is touched, the runtime asks for approval. See below.
+
+### Optional: enable Chrome
+
+```yaml
+config:
+  chrome: true
+```
+
+Then:
+
+```sh
+~/.local/share/lcu/current/bin/lcu browser install
+```
+
+Enable the official ChatGPT extension in the Chrome profile you want to drive, and restart Chrome (or
+toggle the extension at `chrome://extensions`) so it reconnects through LCU's relay rather than Codex's.
+`lcu browser status` reports whether the connector points at this installation. Sites stay
+exact-origin approvals.
+
+### Optional: pre-approve sites
+
+Every site the runtime wants to use asks once. To skip the prompt for origins you trust, list exact
+origins — the message must round-trip through `new URL(...).origin` unchanged:
+
+```yaml
+config:
+  allowedOrigins:
+    - http://localhost:3000
+```
+
+The diagnostic log names every origin that was asked, which is the easiest way to discover them.
+
+## Use
+
+Pick an enabled mode when you start a task. The tools are attached per Agent: a session in any other
+mode never sees them, and never spawns the runtime.
+
+Typical asks:
+
+```
+Take a screenshot of the Finder window and tell me its resolution.
+List my current Chrome tabs.
+Open Safari, go to example.com and read the page title.
+```
+
+## Configuration
+
+| Field | Default | Meaning |
+|---|---|---|
+| `command` | `~/.local/share/lcu/current/bin/lcu` | LCU launcher. Set it for a custom `--prefix`. |
+| `chrome` | `false` | Pass `--chrome` to enable the browser surface. |
+| `audio` | `false` | Pass `--audio` to enable the runtime's computer-audio API. |
+| `presets` | `["heavy"]` | Agent preset ids whose sessions get the tools. |
+| `allowedOrigins` | `[]` | Exact HTTP(S) origins answered without asking. Invalid entries are dropped, never widened. |
+| `sectionOrder` | `0` | Prompt section order for the injected LCU instructions. |
+
+## Approvals and the security model
+
+The model cannot approve anything. Every decision is a person's:
+
+- **Per-app approval.** The runtime asks before it uses an app. The plugin renders its own choices —
+  *Allow once*, *Allow for this session* and *Always allow* when the runtime offers them, and
+  *Decline* — through DSH's question surface. An answer is mapped back to exactly what was offered; a
+  scope the runtime did not offer cannot be granted.
+- **Site approval.** Browser access asks per exact origin. `allowedOrigins` only ever matches an exact
+  origin; a trailing slash, a path, or different case is a different origin and is asked, not granted.
+- **The agent's own host is never approvable.** Computer use can click anything an approved app shows,
+  including the approval prompt itself. The guard refuses the application hosting the agent — its
+  process ancestry and a list of agent hosts and terminals — before any question is asked.
+- **Fail closed.** No question surface, a dismissed prompt, an unrecognized request shape, or an
+  aborted call all end as *cancel*, which the runtime treats as a refusal.
+
+LCU keeps no permission cache of its own; `Always allow` is remembered by the runtime, per app.
+
+## Understand the implementation
+
+```
+src/connection.ts   the MCP client: handshake, tool discovery, calls, elicitation, lifecycle
+src/approval.ts     approval-shape recognition and label→value mapping
+src/host-guard.ts   the anti-self-approval guard
+src/tool.ts         tool definitions, text projection, durable screenshots
+src/index.ts        the plugin: per-Agent attach, instructions, turn_ended, approvals
+src/diag.ts         the attach/approval diagnostic log
+```
+
+**No MCP SDK dependency.** The harness's own MCP bridge declares `capabilities: {}` and therefore
+cannot answer elicitation — which is exactly how LCU asks for 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 owned here. Together with type-only imports of the DSH packages, the plugin has **no
+runtime dependencies at all**.
+
+**Tools are registered per Agent, not at mount.** The server owns the tool schemas, so they can only be
+fetched after the handshake. An Agent's connection is opened when the Agent is created or when it
+commits a preset choice, and everything the plugin contributes is registered into that Agent's own
+context, so it unwinds on disposal.
+
+**Both preset timings are handled.** A new task is created with the deployment default and the picker's
+choice is applied afterwards, so `agent/created` alone would see the wrong composition; the registry
+re-emits `agent-preset/selected`, and the plugin reacts to that too.
+
+**Lazy by construction.** Nothing starts at load time. No enabled session, no `lcu` process.
+
+**Instructions are injected.** The server's `initialize.instructions` becomes a prompt section on the
+Agent. It is short by design — the API manual lives in the `js` tool description and in the first tool
+result.
+
+## Troubleshooting
+
+Everything the plugin decides about attaching and approving is appended to:
+
+```
+~/.dsh/lcu-diag.log
+```
+
+It rotates by starting over past 1 MB. `LCU_DIAG=0` disables it. This is the first place to look: the
+harness has no plugin-log surface a running session can read, and a failing `agent/created` listener is
+otherwise swallowed silently.
+
+| Symptom | Cause and fix |
+|---|---|
+| Tools never appear in an enabled mode | Check the log for `decide … composed=`. If the composed preset is not in `presets`, fix the allowlist. If there is no `agent-preset/selected` line, the mode was never committed. |
+| `no userQuestions service -> cancel (fail closed)` | The approval surface is not mounted in this profile. |
+| `refusing to approve the app hosting this agent` | Working as designed; ask for a different app. |
+| Calls blocked after a turn | The runtime's turn cleanup had not settled; the plugin retries it before the next call and refuses until it does. |
+| `lcu doctor` reports a socket-path error | The signed helper binds under your home folder and refuses a path over 103 bytes. Use an account with a shorter home path. |
+| Attach fails with a spawn error | Run `~/.local/share/lcu/current/bin/lcu doctor` directly, then check `command` in the config. |
+
+`node scripts/probe-lcu.mjs` talks to LCU with no harness involved and prints the protocol version,
+server identity, instructions length and the tool list — useful to separate a plugin problem from an
+LCU problem.
+
+## Companion tools
+
+`scripts/` also ships two tools for the sibling Codex subagent bundle, because the same profile
+usually wants both:
+
+- **`update-codex.mjs`** — keeps the profile's `@openai/codex` on the newest release that still passes
+  three gates (handshake, protocol-schema assertions, and a real turn), rolling back automatically when
+  one fails. The published `@deepseek-ai/dsh-subagent-codex` pins `0.153.4`, which does not serve every
+  current ChatGPT-account model; this bumps it through a profile-level, scoped pnpm override. See
+  `node scripts/update-codex.mjs --help` for `--check`, `--verify-only`, `--to` and `--rollback`.
+- **`codex-baseline.json`** — the last version that passed all three gates.
+
+## Known limitations and deferred work
+
+- **A delegated child cannot be asked for approval.** DSH only accepts a human answer for a live
+  runtime root, so a subagent's LCU approval fails closed. Subagents can perform read-only work that
+  needs no approval; anything that needs one must be driven from the top-level session.
+- **macOS turn cleanup can outlive the host's wait.** The signed helper occasionally answers the
+  `turn-ended` step slowly. The runtime keeps cleaning in the background and retries; the plugin blocks
+  the next call until it settles rather than acting on a half-torn-down desktop.
+- **One LCU connection per Agent.** LCU's JavaScript session is per connection and its approvals are
+  bound to a real session and turn, so sharing one connection across Agents would interleave both.
+- **`chrome` needs the extension.** Enabling the flag without the official ChatGPT extension, or without
+  `lcu browser install`, yields no browser surface.
+- **Not verified on Linux.** See [Requirements](#requirements).
+
+## Development
+
+```sh
+npm install
+npm run typecheck     # strict, noUncheckedIndexedAccess, exactOptionalPropertyTypes
+npm run build         # emits lib/
+npm test              # node --test, no build step
+```
+
+The connection suite talks to the **real** installed `lcu` and skips itself when none is present, so
+`npm test` is meaningful locally and still passes on CI. The approval, projection and guard suites are
+pure and always run.
+
+Plugin code and configuration are **not hot-reloaded** by the harness: a running process keeps the
+module it loaded. Rebuild and restart to see a change.
+
+## License
+
+MIT. LCU is MIT (Amont Labs); the ChatGPT application and its instructions remain under their own
+terms and are used from your local installation.

package/cordis.patch.yml

@@ -0,0 +1,23 @@
+# The dsh-plugin-lcu bundle patch.
+#
+# One row. The plugin owns every LCU connection and registers the model-facing
+# computer-use tools per Agent; it starts nothing at load time, so a session pays
+# for the CUA runtime only when its Agent preset is listed here.
+#
+# `presets` is an explicit allowlist rather than a capability the preset
+# declares, because the server owns the tool schemas: they can only be fetched
+# after the MCP handshake, which happens once a matching Agent is created.
+#
+# `chrome: true` enables LCU's browser surface (`lcu --chrome`). It also needs
+# the official ChatGPT extension enabled in the Chrome profile and
+# `lcu browser install`; sites stay exact-origin approvals.
+
+- insert:
+    - id: lcu
+      name: 'dsh-plugin-lcu'
+      config:
+        presets:
+          - heavy
+        chrome: true
+        # allowedOrigins:
+        #   - http://localhost:3000

package/dev-types/dsh.d.ts

@@ -0,0 +1,292 @@
+/**
+ * Development-only declarations for the harness packages this plugin consumes.
+ *
+ * Transcription of the surfaces actually used, from the running harness's own
+ * inspection output. Deliberately not published: the host supplies the real
+ * packages at runtime and every import of them here is type-only, so nothing in
+ * this file reaches the built plugin.
+ */
+
+// ---------------------------------------------------------------------------
+// @deepseek-ai/dsh-agent
+// ---------------------------------------------------------------------------
+
+declare module '@deepseek-ai/dsh-agent' {
+  import type { Context } from '@deepseek-ai/cordis'
+
+  export type SessionId = string & { readonly __brand?: 'SessionId' }
+
+  /** The live session an agent drives; its log is the durable source of truth. */
+  export interface AgentSession {
+    readonly header: {
+      readonly cwd?: string
+      /** Id of the agent preset this session's agent was composed from. */
+      readonly agentPreset?: string
+    }
+    requestHeader(): { readonly config?: { readonly provider?: string; readonly model?: string } } | undefined
+  }
+
+  export interface Agent {
+    readonly id: SessionId
+    readonly options: { readonly provider?: string; readonly model?: string }
+    readonly session: AgentSession
+    /** Agent-scoped context: contributions unwind on disposal. */
+    readonly ctx: Context
+  }
+}
+
+// ---------------------------------------------------------------------------
+// @deepseek-ai/dsh-tools
+// ---------------------------------------------------------------------------
+
+declare module '@deepseek-ai/dsh-tools' {
+  import type { Agent } from '@deepseek-ai/dsh-agent'
+
+  /** A model-facing tool schema, as assembly projects it. */
+  export interface ToolSchema {
+    readonly name: string
+    readonly description: string
+    readonly parameters: Record<string, unknown>
+  }
+
+  /** One model-facing content block. */
+  export type ContentBlock =
+    | { readonly type: 'text'; readonly text: string }
+    | { readonly type: 'image'; readonly attachment: ImageAttachmentRef }
+    | { readonly type: string; readonly [key: string]: unknown }
+
+  /** A durable image reference minted by the attachment store. */
+  export interface ImageAttachmentRef {
+    readonly attachmentId: string
+    readonly mediaType: string
+    readonly bytes: number
+    readonly width: number
+    readonly height: number
+    readonly name?: string
+  }
+
+  /** Immutable identity plus cooperation surface for one call. */
+  export interface ToolRunContext {
+    readonly callId: string
+    readonly name: string
+    readonly arguments: unknown
+    readonly agent?: Agent
+    readonly signal: AbortSignal
+  }
+
+  /** Normalized outcome handed to post-execute policy and projection. */
+  export interface ToolExecutionResult {
+    readonly value: unknown
+    readonly content: readonly ContentBlock[]
+    readonly isError?: boolean
+  }
+
+  /** The execution identity a projection callback receives. */
+  export interface ToolExecution extends ToolRunContext {}
+
+  /** Declares the tool's canonical JSON value and its text fallback. */
+  export interface ToolOutputDefinition {
+    readonly schema: Record<string, unknown>
+    render(args: unknown, value: never): ContentBlock[]
+  }
+
+  /** A complete tool contribution. */
+  export interface ToolDefinition extends ToolSchema {
+    readonly output: ToolOutputDefinition
+    execute(args: never, exec: ToolRunContext): Promise<unknown>
+    projectContent?(exec: Readonly<ToolExecution>, result: Readonly<ToolExecutionResult>): ContentBlock[] | undefined
+    finalizeContent?(exec: Readonly<ToolExecution>, result: Readonly<ToolExecutionResult>): ContentBlock[] | undefined
+    readonly timeoutMs?: number
+  }
+
+  /** The tool registry a context exposes. */
+  export interface ToolRegistry {
+    register(definition: ToolDefinition): () => void
+    schemas(agent?: Agent): readonly ToolSchema[]
+  }
+}
+
+// ---------------------------------------------------------------------------
+// @deepseek-ai/dsh-system-prompt
+// ---------------------------------------------------------------------------
+
+declare module '@deepseek-ai/dsh-system-prompt' {
+  /** One ordered prompt section. */
+  export interface PromptSection {
+    readonly name: string
+    readonly order: number
+    readonly text: string | ((context: unknown) => string)
+    readonly interpolate?: boolean
+    readonly complete?: boolean
+  }
+
+  export interface SystemPromptRegistry {
+    section(section: PromptSection): () => void
+    context(context: { readonly name: string; readonly order: number; readonly text: string | ((context: unknown) => string) }): () => void
+  }
+}
+
+// ---------------------------------------------------------------------------
+// @deepseek-ai/dsh-attachment
+// ---------------------------------------------------------------------------
+
+declare module '@deepseek-ai/dsh-attachment' {
+  import type { ImageAttachmentRef } from '@deepseek-ai/dsh-tools'
+
+  /** One decoded image ready for durable storage. */
+  export interface SaveImageAttachment {
+    readonly data: Buffer
+    readonly mediaType: string
+  }
+
+  export interface AttachmentStore {
+    saveImages(images: readonly SaveImageAttachment[]): Promise<readonly ImageAttachmentRef[]>
+  }
+}
+
+// ---------------------------------------------------------------------------
+// @deepseek-ai/dsh-llm
+// ---------------------------------------------------------------------------
+
+declare module '@deepseek-ai/dsh-llm' {
+  export interface ModelInfo {
+    readonly inputModalities?: readonly string[]
+  }
+
+  export interface LlmService {
+    resolveModelInfo(provider: string, model: string, signal: AbortSignal): Promise<ModelInfo>
+  }
+}
+
+// ---------------------------------------------------------------------------
+// @deepseek-ai/dsh-user-questions
+// ---------------------------------------------------------------------------
+
+declare module '@deepseek-ai/dsh-user-questions' {
+  import type { Agent } from '@deepseek-ai/dsh-agent'
+
+  export interface AskUserQuestionOption {
+    readonly label: string
+    readonly description?: string
+  }
+
+  export interface AskUserQuestionItem {
+    readonly id: string
+    readonly question: string
+    readonly detail?: string
+    readonly header?: string
+    readonly options?: readonly AskUserQuestionOption[]
+    readonly multiSelect?: boolean
+  }
+
+  export interface AskUserQuestionAnswer {
+    readonly answers: readonly {
+      readonly id: string
+      readonly selected: readonly string[]
+      readonly custom?: string
+    }[]
+  }
+
+  export interface UserQuestionsService {
+    ask(request: {
+      readonly questions: readonly AskUserQuestionItem[]
+      readonly agent?: Agent
+      readonly signal?: AbortSignal
+    }): Promise<AskUserQuestionAnswer>
+  }
+}
+
+// ---------------------------------------------------------------------------
+// @deepseek-ai/dsh-computer-use
+// ---------------------------------------------------------------------------
+
+declare module '@deepseek-ai/dsh-computer-use' {
+  export type ComputerUseProviderName = string & { readonly __brand?: 'ComputerUseProviderName' }
+
+  export interface ComputerUseRegistry {
+    /** Reserves the sole provider slot; a second registration fails. */
+    register(name: ComputerUseProviderName): () => Promise<void>
+    readonly providerName?: ComputerUseProviderName
+  }
+
+  export function ComputerUseProviderName(name: string): ComputerUseProviderName
+}
+
+// ---------------------------------------------------------------------------
+// @deepseek-ai/dsh-agent-preset-registry
+// ---------------------------------------------------------------------------
+
+declare module '@deepseek-ai/dsh-agent-preset-registry' {
+  import type { Context } from '@deepseek-ai/cordis'
+
+  export interface AgentPresetsService {
+    /**
+     * Read the preset a live Agent actually uses.
+     *
+     * This is the authoritative answer: the session header records the
+     * deployment default at creation, which the new-task picker may replace
+     * afterwards.
+     */
+    composedPreset(agentCtx: Context): string | undefined
+  }
+}
+
+// ---------------------------------------------------------------------------
+// @deepseek-ai/cordis
+// ---------------------------------------------------------------------------
+
+declare module '@deepseek-ai/cordis' {
+  import type { Agent } from '@deepseek-ai/dsh-agent'
+  import type { AttachmentStore } from '@deepseek-ai/dsh-attachment'
+  import type { ComputerUseRegistry } from '@deepseek-ai/dsh-computer-use'
+  import type { LlmService } from '@deepseek-ai/dsh-llm'
+  import type { SystemPromptRegistry } from '@deepseek-ai/dsh-system-prompt'
+  import type { ToolRegistry } from '@deepseek-ai/dsh-tools'
+  import type { UserQuestionsService } from '@deepseek-ai/dsh-user-questions'
+  import type { AgentPresetsService } from '@deepseek-ai/dsh-agent-preset-registry'
+
+  /** The live-Agent registry, keyed by session id. */
+  export interface AgentRegistry {
+    get(id: string): Agent | undefined
+  }
+
+  export interface Logger {
+    debug(message: string): void
+    info(message: string): void
+    warn(message: string): void
+    error(message: string): void
+  }
+
+  /**
+   * The plugin context, narrowed to the services this plugin consumes.
+   *
+   * Optional services are read with `get()` so a composition without them still
+   * activates everything else.
+   */
+  export interface Context {
+    readonly tools: ToolRegistry
+    readonly systemPrompt: SystemPromptRegistry
+    readonly logger: Logger
+    get(name: 'attachments'): AttachmentStore | undefined
+    get(name: 'llm'): LlmService | undefined
+    get(name: 'userQuestions'): UserQuestionsService | undefined
+    get(name: 'computerUse'): ComputerUseRegistry | undefined
+    get(name: 'agentPresets'): AgentPresetsService | undefined
+    get(name: 'agents'): AgentRegistry | undefined
+    get(name: string): unknown
+    effect(callback: () => (() => void | Promise<void>)): () => void
+    on(event: 'agent/created', listener: (payload: { agent: Agent; signal?: AbortSignal }) => void | Promise<void>): () => void
+    on(
+      event: 'agent/turn-stopping',
+      listener: (payload: { agent: Agent; turn: number; signal: AbortSignal }) => void | Promise<void>,
+    ): () => void
+    /**
+     * The registry re-emits a session's committed preset choice. This fires
+     * AFTER `agent/created`: a new task is created with the deployment default
+     * and the picker's choice is applied on this event, so it is the only
+     * reliable moment to react to the preset a session will actually use.
+     */
+    on(event: 'agent-preset/selected', listener: (sessionId: string, agentPreset: string) => void | Promise<void>): () => void
+    on(event: string, listener: (...args: never[]) => unknown): () => void
+  }
+}