@agentrouter-top/relay-dsh-plugin-codex 0.2.2-agentrouter.1

package/docs/reliability-spec.md

@@ -0,0 +1,305 @@
+# Codex Reliability Specification
+
+Status: Accepted for implementation
+
+This specification defines the user-visible and safety-critical behavior of
+`relay-dsh-plugin-codex`. The official DSH checkout remains unmodified.
+
+## App Server ownership and connection state
+
+The plugin Host process owns one Codex App Server child process. It starts the
+child while the DSH Host activates the plugin, before Codex models are used,
+and stops it when the plugin is disposed or DSH exits. The default launcher is
+the pinned `@openai/codex` package and its platform optional dependency. A
+global `codex` command is not required. `codexCommand` overrides
+`RELAY_CODEX_COMMAND`, which overrides the bundled launcher.
+
+The default launcher disables Codex `features.shell_snapshot`. Shell commands still
+receive the effective Codex child environment; Relay does not turn secret delivery
+into transcript text or strip variables merely because their names contain `KEY`,
+`SECRET`, or `TOKEN`. Disabling snapshots prevents Codex from serializing that complete
+effective environment into durable files under `CODEX_HOME/shell_snapshots`. Explicit
+operator-supplied App Server arguments remain an exact override and carry responsibility
+for any snapshot policy they enable.
+
+## Plugin Hook trust propagation
+
+Codex evaluates installed Plugin Hooks when each Thread is started, forked, or
+resumed. App Server launch arguments and Thread request configuration are separate
+configuration layers. Relay therefore mirrors an explicit standalone
+`--dangerously-bypass-hook-trust` launch argument into
+`config.bypass_hook_trust: true` on `thread/start`, `thread/fork`, and
+`thread/resume`, while preserving the operator's launch argument array exactly.
+
+This is an opt-in security exception. Relay never enables Hook trust bypass by
+default, never recognizes the flag as a substring of another argument, and never
+propagates unrelated launch configuration into Thread requests. Restarting without
+the exact flag removes the request-level override. Existing realtime, dynamic-tool,
+permission, resume, and fork settings remain unchanged.
+
+The observable state machine is:
+
+| State | Meaning | Required user behavior |
+| --- | --- | --- |
+| `not-started` | Plugin is loaded but start has not begun. | Wait for DSH startup. |
+| `starting` | Child spawn and App Server initialization are in progress. | Wait; do not create a Thread. |
+| `connected` | Initialize and model discovery succeeded. | Codex conversations may run. |
+| `connection-failed` | A child existed or was attempted, but protocol initialization, connection, or process lifetime failed. | Preserve bindings; show restart/authentication diagnostics. |
+| `unavailable` | The executable, bundled platform runtime, or supported platform is unavailable. | Show reinstall or absolute-path configuration guidance. |
+| `rebind-required` | A DSH fork could not establish its App Server child binding safely. | Preserve provenance and retry Fork from the original Session after fixing the condition. |
+
+User-facing status must never expose raw `spawn codex ENOENT`. Stable error
+codes include `CODEX_EXECUTABLE_NOT_FOUND`, `CODEX_RUNTIME_MISSING`,
+`CODEX_PLATFORM_UNSUPPORTED`, `CODEX_APP_SERVER_NOT_RUNNING`,
+`CODEX_APP_SERVER_CONNECTION_FAILED`, and `CODEX_REBIND_REQUIRED`.
+
+## Shell environment persistence
+
+A Host-only environment secret may be inherited by an intended shell consumer without
+appearing in DSH messages, Codex rollout events, plugin diagnostics, or regular Codex
+state files. The Relay default must create no shell snapshot at all, because name-based
+redaction cannot identify every secret and filtering the command environment would break
+legitimate consumers. Restart and resume preserve the Session/Thread binding without
+backfilling a snapshot for an earlier or later command.
+
+## Backend model selection
+
+For a blank DSH Session, the selected Agent preset determines the model
+provider group:
+
+- `relay-codex` selects `relay-codex` and its default model/default reasoning
+  effort;
+- `relay-claude` is never rewritten by the Codex coordinator;
+- leaving Codex for a native preset selects a provider group that is neither
+  Codex nor Claude.
+
+Only the newest preset generation may select a model. Model discovery may be
+retried with bounded delays while the App Server becomes ready. A non-blank
+Session is never rewritten by this synchronization.
+
+## Workspace Thread discovery and selective import
+
+The provider-neutral `relay-dsh-plugin-session-import` hub owns the sidebar
+footer's single **Import sessions...** entry. Codex contributes one explicit
+**Import from Codex** menu row through `relay.session-import.provider`; it owns
+no standalone footer trigger. Selecting that row presents a visible Workspace
+selector. The current Session owner,
+then the recent Workspace, is only an initial choice. The user may change it,
+and the plugin must not scan until the user invokes **Scan sessions**.
+
+The import scan lists only Codex Threads whose canonical `cwd` belongs to the
+explicitly selected DSH Workspace and whose binding state is `ready` or `recoverable`.
+Each candidate exposes its complete Codex Thread id, deterministic title, canonical
+path, App Server `updatedAt`, and binding status. Candidates are unique and ordered
+by source activity time, with Thread id as the deterministic tie-breaker. Already
+bound Threads remain part of aggregate counts but are never selectable; Threads
+from another Workspace are neither counted nor disclosed.
+
+The UI defaults to all eligible candidates and supports selecting one, several,
+all, or none. An empty selection cannot be submitted. The import request carries
+the exact selected Thread ids. Before creating or changing any DSH Session, the
+Host rescans the Workspace and validates the entire selection for non-empty unique
+ids, current Workspace membership, and unbound or recoverable state. Any unknown,
+duplicate, cross-Workspace, or newly-bound id rejects the whole request without a
+partial mutation. A request that omits `threadIds` retains the previous import-all
+Host API behavior for compatible clients; an explicit empty array is invalid.
+
+Recoverable imports remain idempotent. After a successful selective import, DSH
+refreshes Sessions before Workspace membership so the imported Session appears
+with the original Codex title and source activity ordering.
+
+## Thread binding and forks
+
+One DSH Session binds at most one Codex Thread, and one Codex Thread binds at
+most one DSH Session. A persisted binding is never deleted merely
+because `thread/resume` fails. Active-writer and transient failures retain the
+binding for retry. A missing Thread enters `rebind-required`.
+
+DSH forks inherit assistant messages and their Codex `replayState`. When an
+unbound child contains an original `threadId` and completed `turnId`, and that
+Thread is still owned by another DSH Session, the plugin calls App Server
+`thread/fork` with `threadId` and `lastTurnId`. It persists the returned new
+Thread as the child's one-to-one binding before starting the child Turn. It
+never writes the child continuation to the parent Thread.
+
+Missing Turn provenance, an unowned or rebind-required source, an in-progress
+Turn, an App Server rejection, or an invalid fork response enters
+`CODEX_REBIND_REQUIRED`. Diagnostics retain the original Thread and, when
+available, Turn and Item ids. These paths perform neither `thread/start` nor
+`turn/start`, and the plugin must not silently create a replacement Thread.
+Retrying the same provenance may retry `thread/fork`; it still cannot fall back
+to fresh Thread creation.
+
+## Approval provenance and reconnect
+
+Every App Server approval is owned by this tuple:
+
+`(DSH Session id, Codex Thread id, Turn id, Item id, App Server request id, binding epoch)`.
+
+The tuple is captured before asking DSH for approval and validated again after
+the user decision but before responding to Codex. Detach, rebind state, binding
+replacement, request identity change, or provenance mismatch makes the
+approval stale. A stale approval is rejected with `CODEX_STALE_APPROVAL`; it is
+never accepted or routed to another Thread. The diagnostic names the original
+Thread, Turn, and Item.
+
+DSH may replay the same still-pending approval rpc id after a browser
+disconnect. That replay is safe only while the ownership tuple remains valid.
+
+## Subagent interaction ownership
+
+A Codex subagent Thread does not receive an independent DSH Session binding. While
+the root Turn is active, App Server emits `subAgentActivity` items whose enclosing
+`threadId` is the parent and whose `agentThreadId` is the spawned child. The adapter
+records those observed edges with the root binding epoch. Thread inventory metadata
+is not treated as authorization because it may be absent before the interaction or
+outlive the Turn that created the child. Dynamic tools, approvals,
+and structured questions from a descendant may use the root DSH Agent only after the
+adapter proves an acyclic observed parent chain from the requesting
+Thread to the currently bound root Thread.
+
+Resolution never uses cwd, title, recency, or model as ownership evidence. An unknown
+Thread, missing parent, cycle, inconsistent shared Session, unbound root, disposed DSH
+Agent, changed binding epoch, or rebind-required root fails closed. A descendant uses
+only the DSH tool names captured for the owning root Turn; it cannot gain a capability
+that was absent from that Turn. Observed edges are released when the root Turn ends or
+the DSH Agent detaches. Conflicting observations permanently reject that child identity.
+
+## Reasoning summary presentation
+
+Business Turns request App Server reasoning summaries with `summary: auto`.
+When Codex supplies a summary, the adapter projects its public summary deltas as
+one DSH reasoning block that remains distinct from the final answer. It never
+projects encrypted or raw hidden reasoning content.
+
+An App Server reasoning item with no public summary produces no DSH reasoning
+block rather than an empty `Think` disclosure. Ephemeral title and compaction
+Turns explicitly use `summary: none`; their internal work is not added to the
+business conversation and does not incur a presentation-only summary.
+
+## Image projection and failure isolation
+
+Codex `imageView` and `imageGeneration` items are admitted according to their
+encoded byte signature, not a local filename extension or unverified data-URI
+declaration. PNG, JPEG, GIF, and WebP signatures map to the corresponding DSH
+media type. The DSH attachment store remains the authority for full decode,
+normalization, size, and pixel-limit validation.
+
+A filename such as `completed-clean.png` may therefore produce an
+`image/jpeg` attachment when its bytes are JPEG. Workspace and generated-image
+root checks still run before any local file is read; byte detection does not
+expand the allowed filesystem boundary.
+
+Image preview admission and storage are projection concerns. Failure of one
+image emits one terminal text placeholder and a Host warning containing only a
+stable reason code and the owning Thread, Turn, and Item identifiers. Raw
+storage errors and absolute paths are not projected or logged. Projection then
+continues through later Codex items and the source Turn's terminal status. It
+must not throw out of the adapter stream, mark an otherwise successful DSH Turn
+as failed, or interrupt the backing Codex Thread.
+
+A completed App Server `mcpToolCall` may carry standard MCP image entries in
+`result.content`. Each `type: image` entry is decoded independently in content order,
+limited to 25 MiB, and admitted only when its declared supported MIME exactly matches
+the encoded PNG, JPEG, GIF, or WebP signature. Text, resources, and
+`structuredContent` are not reinterpreted as images. Valid bytes are saved directly
+through the owning DSH attachment service with deterministic sanitized names; no
+temporary Workspace file is created.
+
+Malformed base64, unsupported or mismatched media, oversized data, and attachment
+storage rejection follow the same failure-isolation contract: one sanitized placeholder
+and stable warning reason per failed image, followed by the remaining MCP images and
+the source Turn's final answer. Raw base64, storage errors, and private paths are never
+logged or projected.
+
+## DSH image input transport
+
+DSH user image blocks normally contain a content-addressed attachment reference,
+not a local path. Before creating or resuming a Codex Thread, the adapter reads
+each image through DSH's attachment service, preserves message order, and verifies
+the encoded PNG, JPEG, GIF, or WebP signature. Encoded bytes are authoritative
+when stored metadata or the display name disagrees.
+
+Verified bytes are materialized outside the Workspace under
+`$CODEX_HOME/dsh-input-images` (or the default `~/.codex` equivalent). Files use
+their SHA-256 digest plus a signature-derived extension, directories are private,
+and writes are atomic without replacing an existing digest. Repeated immutable
+attachments reuse the same verified path. The Workspace is not modified.
+
+The resulting path is sent through App Server `turn/start` as native
+`localImage` input and attachment metadata. Multiple images retain DSH order and
+pure-image messages are valid. Existing trusted path-backed image blocks remain
+supported.
+
+Missing/corrupt attachments, unavailable attachment service, invalid bytes,
+oversized data, and cancellation fail before a Codex Thread or Turn starts. They
+use stable `CODEX_IMAGE_*` codes and never silently degrade an image-bearing user
+message to text-only input.
+
+## Turn interruption and process cleanup
+
+Stopping a DSH Codex Turn must stop both model generation and every active App
+Server background terminal owned by that Turn. Before sending `turn/interrupt`,
+the runtime identifies the Turn's in-progress `commandExecution` item ids and
+terminates only matching `thread/backgroundTerminals` process ids. It repeats
+discovery after interruption to close races and confirms that no matching
+terminal remains.
+
+Background terminals owned by another Turn are not terminated. The plugin must
+not use the thread-wide background-terminal cleanup operation for an ordinary
+Turn stop.
+
+The Turn is reported as aborted only after targeted cleanup and
+`turn/interrupt` succeed. If cleanup cannot be confirmed, the DSH Turn ends with
+`CODEX_TURN_INTERRUPT_CLEANUP_FAILED`, tells the user to check for late Workspace
+side effects, and logs only the stable code plus Thread and Turn identifiers.
+
+## Command output streaming
+
+App Server shell output belongs to the user-visible Codex response even though the
+command is executed inside Codex rather than by the DSH tool dispatcher. Code mode
+returns the first yielded bytes in a raw `custom_tool_call_output`, while later PTY
+bytes also arrive as native `item/commandExecution/outputDelta` notifications. New
+durable plugin-owned Threads opt into raw response items; ephemeral auxiliary Threads
+do not. The runtime never forwards a raw item: it correlates only `exec` call/output pairs, parses structured text results, and
+projects only a non-empty result containing `session_id`, `wall_time_seconds`, and
+`output`. Raw messages, prompts, reasoning, encrypted content, unrelated tools,
+malformed results, and completed results without a live `session_id` remain private.
+
+The adapter correlates the sanitized first yield and native command notifications by
+`session_id`/`processId`, then retains one reconciled activity output. Mirrored raw
+and native output is deduplicated while repeated native output remains repeated.
+It must not emit an executable DSH `tool-call` stream chunk, because doing so would
+ask the DSH Agent to execute the already-running command a second time. Instead,
+presentation-only calls/results use native persistence envelopes with the
+`relay_codex_activity` name and validated activity metadata.
+
+All deltas for one process share one buffer and retain App Server order. For
+native-only commands, the completed item's `aggregatedOutput` supplies the settled
+snapshot. Code-mode output also reconciles sanitized first yields with the native
+PTY side. A completed item with no preceding delta retains its non-empty aggregate.
+Empty output stays empty. Late deltas after completion are ignored. Cancellation
+also drains already-owned command notifications received during the interrupt RPC
+before settling any remaining activity as failed.
+
+Bounded command output is persisted in the native tool result's activity metadata,
+separate from assistant commentary and the final answer. The grouped presentation
+shows it as literal text in an expandable panel, never assistant Markdown. Native
+persistence vocabulary survives Session reload without introducing plugin-private
+mandatory event types. See [Execution presentation](spec/execution-presentation.md)
+for ordering, ownership, legacy fallback, and file-delivery acceptance.
+
+`experimentalRawEvents` is immutable App Server Thread creation state in the pinned
+runtime: resume, settings update, and fork cannot enable it for a Thread created by an
+older plugin version. Such Sessions continue to receive native command deltas, but
+complete first-yield streaming requires a new DSH Session created after this feature
+is installed. The plugin must not silently replace or summarize an existing Codex
+Thread because that would weaken its model-context continuity.
+
+## Platform contract
+
+The bundled launcher supports darwin, linux, and win32 on arm64 and x64 using
+the matching `@openai/codex-<platform>-<arch>` package. Commands are spawned
+directly with an argument array and never through a shell, so spaces and
+Windows backslashes remain literal. CI runs launcher, App Server client, and
+status/error tests on macOS, Windows, and Linux.

package/docs/spec/dsh-interaction-bridge.md

@@ -0,0 +1,168 @@
+# DSH Interaction Bridge Specification
+
+## Scope
+
+Codex App Server can pause a Turn to request approval for a command, file
+change, or permission profile, or to ask the user a structured question. The
+plugin routes those requests through the owning DSH Session so DSH remains the
+authority for human interaction and conversation continuity.
+
+## Composition contract
+
+`approval` and `userQuestions` are required Host injections. They are provided
+by sibling plugins in the official DSH composition, so listing them in the Host
+plugin's exported `inject` array binds them into the Codex consumer fiber and
+makes activation wait for both services.
+
+The bridge must not read either service as an undeclared context property. It
+must not make either dependency optional, and it must not bypass DSH approval or
+question handling when a service is missing, cancelled, or fails. Failure is
+closed: no App Server request is accepted and no protected operation executes.
+
+## Request ownership
+
+Every modern request carries a Codex `threadId`; legacy command and patch
+requests carry the same identity as `conversationId`. The adapter normalizes
+both forms and must resolve that id to one live DSH Session and Agent before
+invoking a DSH interaction service. Modern `itemId` and legacy `callId` are
+normalized into the same ownership slot.
+
+Subagent requests carry the descendant Thread id rather than the root Thread id.
+During the root Turn, the adapter observes `subAgentActivity.agentThreadId` as the
+child of the notification's enclosing `threadId` and records that edge with the
+current root binding epoch. App Server inventory can also identify the root through
+shared `sessionId` and each edge through `parentThreadId`, but that durable inventory
+is not authorization because it may be absent before the request or outlive the Turn.
+The adapter must prove the complete acyclic observed parent chain to a currently
+bound root before routing a descendant dynamic tool, approval, or question through
+that root's DSH Agent.
+Matching cwd, title, model, or recency is never sufficient ownership evidence.
+
+An observed edge is valid only for its root Turn and binding epoch. Turn completion,
+Agent detach, conflicting parent observations, a missing edge, or a root rebind makes
+the descendant fail closed without DSH tool execution.
+
+Approval ownership includes the DSH Session, Codex Thread, Turn, Item, App
+Server request id, and binding epoch. Unknown, stale, re-bound, or unowned
+requests are rejected without asking the user or executing the operation.
+
+## Approval mapping
+
+For command, file-change, and permission approval requests:
+
+| DSH outcome | App Server response |
+| --- | --- |
+| `allowed-once` | `accept` for the current request |
+| `rejected` | `decline` |
+| `cancelled` | `decline` |
+| `unavailable` | `decline` |
+
+The requested command or App Server reason is shown through DSH's approval
+service. The protected operation must not begin before `allowed-once` returns.
+Thrown service errors reject the pending App Server request and never become an
+implicit allow.
+
+## Question mapping
+
+For `item/tool/requestUserInput`, the bridge maps at most three Codex questions
+to DSH questions, waits for `userQuestions.ask()`, and maps selected and custom
+answers back to App Server. Cancellation or provider failure rejects the
+pending request. Unsupported interaction methods are rejected.
+
+## Activity presentation contract
+
+Official DSH conversation rendering remains unmodified. New Codex runtime
+activities use the official `assistant/message` (tool-call block), `tool/call`,
+and `tool/result` envelopes with the plugin-owned tool name
+`relay_codex_activity`. Versioned activity data travels in call arguments and
+result `meta.codexActivity`. The plugin renders that name through the official
+`tool.call.toolview` slot. This records work executed by Codex; it does not
+register or dispatch an additional DSH tool. Calls have matching result messages,
+carry the current DSH Turn/Step, and use Thread/Turn/Item-scoped call IDs.
+
+Compatibility was checked against official DSH commit
+`b150a551b8d465e31e418e1b2eaf5e79bbb7d28e`. Its persistence reader refuses unknown
+event types unless `ignorable: true` is on the envelope, but its public
+`Session.append()` does not accept that marker. Type declaration merging and
+client conversation registration do not extend the persistence vocabulary.
+New writes MUST NOT use `relay-codex/activity` or patch the official registry.
+
+The legacy `relay-codex-activity` chat node remains read-only compatibility for
+old logs. `scripts/repair-activity-history.mjs` defaults to dry-run; with DSH
+stopped, `--write` backs up the original bytes and atomically adds only the
+`ignorable: true` envelope marker to validated legacy activity events. It preserves
+all sequence numbers, timestamps, payloads, and other records, handles every zstd
+frame (with a separate header frame), is idempotent, and refuses malformed or
+torn input. No other unknown event is made ignorable. Backups stay beside the
+private session log, outside the repository.
+
+Recovery must audit the complete configured session root without a modification
+date or workspace filter. `--root <sessions-directory>` discovers canonical
+plaintext/zstd logs across workspaces, excluding backups and symlinks. Batch
+repair refuses to write if any log could not be inspected and rescans the root
+after applying fixes; acceptance requires no unmarked legacy activity events
+and no scan errors. Fixing only the first reported Session is not sufficient.
+
+Assistant-facing text and reasoning keep using DSH's native text and reasoning
+blocks. Command output, file changes, image views/generations, MCP tool calls,
+web searches, plans, and future non-message App Server items must not be
+serialized into assistant markdown. The adapter must append one started activity
+when an item starts and one completed activity when it settles. Unsettled calls
+are closed as failures when the stream terminates. Completed command
+activities carry bounded output in their event payload so the UI can show it in
+an expandable shell/detail panel without changing the assistant message body.
+Command activity labels distinguish running from completed work, prefer Codex's
+structured command actions (read/search/list), and retain the full command only
+in expandable details. Consecutive activities are grouped in presentation; naming
+each individual call `Ran commands` is not grouping. See
+[Execution presentation acceptance](execution-presentation.md).
+
+When App Server exposes duplicate command output through both legacy
+`codeModeShell/outputDelta` and modern `commandExecution/outputDelta`
+notifications, the adapter keeps a single reconciled activity output. Late
+output deltas after item completion are ignored.
+
+Unknown App Server item types that are not user, assistant, or reasoning items
+must also become activity rows. This fail-open-for-presentation rule prevents new
+Codex tool surfaces from falling back into MarkdownText while preserving DSH as
+the owner of conversation layout.
+
+## Verification contract
+
+1. A unit contract test fails when either required Host injection is absent.
+2. A Cordis composition test mounts interaction services as sibling providers,
+   mounts the Codex consumer with its exported `inject`, and completes one
+   approval plus one question request.
+3. Handler and runtime tests cover allow, deny, permission, answer, stale
+   ownership, unknown Session, and unsupported request mappings.
+4. An official DSH Web acceptance test uses two independent Codex Sessions.
+   Both request the same class of outside-Workspace write. Before either answer,
+   both target files are absent and the sentinel is unchanged. One-time allow
+   creates only the allow target with exact bytes. Reject leaves the deny target
+   absent. Both Sessions finish normally and remain usable.
+5. The historical pre-fix plugin commit must reproduce the missing approval UI
+   and automatic fail-closed response for the same request shape.
+6. Subagent tests emit App Server-shaped `subAgentActivity` notifications while the
+   root Turn remains live, cover direct and nested descendants plus duplicate,
+   conflicting, unbound, orphaned, cyclic, stale, expired, and cross-Session trees,
+   and assert rejected trees execute zero DSH tools. An official DSH Web regression
+   proves one child reads the exact oracle through the DSH tool bridge and returns it
+   to the owning parent without a parent-side read.
+7. Codex adapter tests prove command output, mixed file/image/MCP/search items,
+   duplicate legacy/native command streams, empty outputs, and late deltas are
+   emitted as bounded native tool events and never as assistant text deltas.
+8. Codex client tests prove the plugin registers the activity conversation
+   definition for legacy reads, injects the native keyed tool view, and renders collapsed
+   activity rows plus expandable shell/details without markdown interpretation.
+9. Real official JSONL persistence tests cover both plaintext and zstd: stream a
+   tool through the adapter, persist it, dispose the writer, load using a fresh
+   reader, and reopen twice. Assert exact event preservation, known event types,
+   call/result pairing, coordinates, output, and final assistant text.
+10. Legacy repair tests reproduce `SessionFormatUnsupportedError` before repair,
+    verify exact backup bytes, then cold-load through official persistence.
+    Verify dry-run, idempotence, malformed/torn refusal, and unchanged unrelated
+    unknown events. Component tests cover native running-to-settled updates,
+    result-only history pages, interruption, and malformed payload fallback.
+11. Root scan tests include an old-dated log, multiple workspaces, both physical
+    encodings, an already repaired log, backups, symlinks, and corrupt input.
+    No date or workspace selection may omit an affected canonical log.

package/docs/spec/execution-presentation.md

@@ -0,0 +1,103 @@
+# Codex Execution Presentation
+
+## Scope and baseline
+
+Plugin-only integration against immutable official DSH
+`b150a551b8d465e31e418e1b2eaf5e79bbb7d28e`. DSH continues to own navigation,
+composer, history, attachments, and execution controls. No official source edits,
+new mandatory persistence event types, PR, or private session logs in this repo.
+
+The supplied 2026-08-30 recording is the behavioral reference: readable progress
+paragraphs interleave with grouped tool activity; only the current activity is
+foregrounded while tools run; the process can collapse when the answer is ready.
+The current one-row-per-command implementation is not accepted as grouping.
+
+## Delivery slices and review gates
+
+1. Projection: reconstruct an ordered, turn-scoped presentation from native
+   chunks and native tool envelopes. Tool messages must not finalize or erase
+   streamed commentary. Keep text, reasoning, images, and tool data distinct.
+   Review ordering, incremental versus full replay, duplicates, and ownership.
+2. UI: group adjacent tool activities between text/image boundaries; expose one
+   summary/current action by default and all individual details on expansion.
+   Use stable keys, semantic labels, truthful status, bounded shell panels,
+   accessible disclosure controls, and existing DSH design primitives.
+   Review long labels, interrupted/error work, images, and foreign-provider views.
+3. Integration: build/typecheck/full tests plus official persistence round trips,
+   restart and history reload. Review loader compatibility and source cleanliness.
+4. Live acceptance: submit exactly `当前Relay项目还有哪些逻辑没有实现为DSH插件？`
+   in the Relay workspace using `gpt-5.6-sol` with `high` reasoning. Capture live,
+   expanded-detail, final-answer, and reopened-history screenshots. Record model
+   and actual outcome; do not substitute a synthetic preview for live evidence.
+
+Each slice needs its own test results and review before delivery. Synthetic tests
+cover nondeterministic branches; the real question is the final acceptance, not
+a speed comparison with an independent Codex App run.
+
+## Acceptance scenarios
+
+| ID | Scenario | Required observation |
+| --- | --- | --- |
+| EXEC-01 | Commentary, ten tools, commentary, more tools, answer | Commentary appears while running, in source order; two compact tool groups, not ten top-level rows |
+| EXEC-02 | Streaming commentary followed by native tool request | Tool-only assistant message cannot erase or freeze commentary |
+| EXEC-03 | Read/search/list, shell, edit, image and unknown tools | Semantic current label and category icon; unknown tool remains inspectable |
+| EXEC-04 | Open a group and child while new items arrive | Stable disclosure state; command/output retains newlines and is never Markdown |
+| EXEC-05 | Concurrent tools, nonzero exit, cancellation | Active count is truthful; error is not green success; unresolved calls settle on termination |
+| EXEC-06 | Final text-only answer and answer after tools | Answer remains visible; process collapses without losing history; reopenable process |
+| EXEC-07 | Images and consecutive file edits | Images use DSH attachment rendering; edits remain expandable and ordered |
+| EXEC-08 | Refresh/reopen/cold-load plaintext and multi-frame zstd | Same logical order and grouping, no duplicate text or unsupported event error |
+| EXEC-09 | Non-Codex session and mixed-provider history | Native rendering and controls unaffected; ownership is turn-scoped |
+| EXEC-10 | Desktop/narrow viewport, long path, keyboard disclosure | No horizontal overflow/overlap; Enter/Space disclosure works; status is not color-only |
+| EXEC-11 | Exact user question, Sol High | Real execution visibly meets live grouping and commentary criteria; retained screenshots |
+| EXEC-12 | Cancel after a command emitted partial output | Failed terminal result retains all buffered output within the existing output limit |
+| EXEC-13 | Imported native tools or foreign-provider steps between Codex paragraphs | Preserve native chronological rendering where a complete grouped projection is unavailable |
+| EXEC-14 | Generated image before final prose, or image-only completion | Deliverable remains visible after process collapse; viewing an image remains tool activity |
+| EXEC-15 | Closing answer references a known produced file | Preserve the native closing-turn resolver; completed structured Codex edits also resolve through the native DSH opener |
+| EXEC-16 | Replacement mount fails or plugin unloads | Native assistant and tool content remains available or is restored; no invisible conversation |
+| EXEC-17 | Pack and clean-install in isolated official DSH profile | Install the actual tarball, not a workspace link; execute its browser loader without missing modules; verify installed bundle identity |
+| EXEC-18 | Upgrade published 0.1.4 to candidate, restart | Existing native history stays readable, new grouped history reloads; installed client is the candidate, not stale same-version package content |
+| EXEC-19 | Native DSH, Codex-only, Claude-only and combined profiles | All selected loaders execute; native and Claude histories do not receive Codex process ownership |
+| EXEC-20 | Keyboard and real 390 x 844 viewport | Enter and Space toggle process/group/child disclosures; focus remains visible; no horizontal document overflow |
+| EXEC-21 | Real edit, image-view and produced-file workflow | Actual file content changes; edit and image categories render; final file reference opens via native DSH; viewed image bytes decode |
+| EXEC-22 | Browser failure/cancel, cold replay and image delivery | Explicit terminal states and retained partial output; no duplicate activities after reload; generated image output remains visible after collapse |
+
+Delivery evidence distinguishes real model execution, deterministic protocol
+fixtures, component tests, and manual-only checks. Fixture image delivery is not
+reported as a successful live image-generation service call. Tarballs, raw logs,
+isolated profiles and screenshots stay outside the repository. No publishing or
+PR creation is part of these acceptance commands.
+
+## Output and file contracts
+
+Cancellation preserves stdout already received by the adapter, including
+notifications queued while the interrupt RPC is pending. Only commands already
+owned by that turn may be settled; foreign turns, unknown commands and new prose
+are not admitted during cleanup. An immediate stop before the execution backend
+delivers stdout may legitimately have no output. The acceptance oracle examines
+persisted activity output, not text echoed in the command input.
+
+The pinned Codex runtime cannot enable first-yield raw notifications for a
+Thread created without them by an older plugin. Upgrade acceptance must preserve
+that Thread and its history, not silently replace it. First-yield cancellation
+acceptance uses a new post-upgrade Session; an old Thread can retain only output
+the backend actually delivers. See the compatibility contract in
+[Reliability](../reliability-spec.md#command-output-streaming).
+
+Synthetic Codex file activities do not have native DSH mutation presenters.
+Supplement the native file-mention resolver only with completed structured
+file-change records. Exact paths and unique basenames can open through DSH;
+ambiguous, failed, running, deleted, malformed and prose-only paths cannot.
+Renames replace the old path with the destination. Native resolution retains
+priority and is returned unchanged when there are no produced Codex files.
+
+Reasoning is secondary and collapsed, not mixed into assistant prose. Missing
+model commentary must not be invented. Partial history must fall back without
+discarding available content. Debug context remains available without dominating
+normal Codex process presentation. Model phase information may be used only when
+actually supplied; do not guess a final answer from its wording.
+
+Older text-only projections without presentation metadata remain native. A
+visible legacy activity between projected segments also disables takeover; its
+native row must not be crossed by moving later prose to the process anchor.
+Missing tool-call history, unrepresented tool types, and mixed providers likewise
+retain native presentation until the projection has sufficient evidence.

package/dsh-client-compat.d.mts

@@ -0,0 +1,4 @@
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-client-ui-model-selection/client'
+export function sessionPreset(session: { agentPreset?: string | null; projectionValues?: { agentPreset?: string | null } } | undefined): string | null | undefined
+export function modelDirectory(ctx: unknown, sessionId: string): Pick<ReturnType<Context['modelDirectories']['directoryFor']>, 'load' | 'select'>

package/dsh-client-compat.mjs

@@ -0,0 +1,26 @@
+// Public interface adapters shared by both supported DSH generations.
+export function sessionPreset(session) {
+  if (session?.projectionValues && Object.hasOwn(session.projectionValues, 'agentPreset')) {
+    return session.projectionValues.agentPreset;
+  }
+  return session?.agentPreset;
+}
+
+const service = (ctx, name) => typeof ctx.get === 'function' ? ctx.get(name) : ctx[name];
+export function modelDirectory(ctx, sessionId) {
+  const directories = service(ctx, 'modelDirectories');
+  if (directories) return directories.directoryFor(sessionId);
+  const sessions = service(ctx, 'connection')?.api?.sessions;
+  if (!sessions) throw new Error('DSH model selection interface is unavailable');
+  return {
+    async load() {
+      const response = await sessions.models({ sessionId });
+      if (!response.result.ok) throw new Error('DSH model discovery failed');
+      return response.result.value;
+    },
+    async select(selection) {
+      const response = await sessions.selectModel({ sessionId, ...selection });
+      if (!response.result.ok) throw new Error('DSH model selection failed');
+    },
+  };
+}