dsh-acp-replay 0.1.0

package/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+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.
+
+---
+
+This repository vendors @deepseek-ai/dsh-acp (tag dsh-v0.1.5-rc.1) and adds the
+session/load capability, the loadSession handler, and src/replay.ts. Those
+additions are released under the same MIT terms.

package/README.md

@@ -0,0 +1,126 @@
+# dsh-acp-replay
+
+A community ACP bridge for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) that answers `session/load`, so a client can rebuild a session transcript after its own restart.
+
+**Status: prototype.** It works end to end on `dsh 0.1.5-rc.1`, but it is a vendored fork of `@deepseek-ai/dsh-acp` and needs a rebase whenever that package changes.
+
+## Why this exists
+
+`dsh-acp` is an automation-only bridge: its `initialize` advertises `sessionCapabilities: { close, list, resume }` and no `loadSession`, and `session/resume` restores a session *without replaying its updates*. ACP defines `session/load` as the call where the agent "streams the entire conversation history back to the client via notifications", and clients that treat the agent as the durable transcript authority — Paseo, for one — call exactly that method to rebuild a timeline after restarting.
+
+Without it, that model of client shows an empty conversation next to an agent that still remembers everything, because the harness keeps the transcript and the client has no way to read it. This bridge closes that gap; the discussion tracking the missing upstream feature is [deepseek-ai/deepseek-harness#6324](https://github.com/deepseek-ai/deepseek-harness/discussions/6324).
+
+## What it adds
+
+Two changes over `@deepseek-ai/dsh-acp@0.1.5-rc.1`:
+
+- `initialize` advertises `loadSession: true`.
+- `session/load` is implemented: it opens the stored session with a read-only persistence handle (`ctx.sessionPersistence.open(id, 'read')`), resumes the session exactly as `session/resume` does, then replays the snapshot through the existing update mapping in `src/updates.ts` before returning.
+
+`src/replay.ts` maps stored events to protocol updates:
+
+| Stored event | ACP update |
+| --- | --- |
+| `user/message` with `source.kind === 'user'` | `user_message_chunk` |
+| `assistant/message` | `agent_thought_chunk`, `agent_message_chunk`, `usage_update` |
+| `tool/call` | `tool_call` |
+| `tool/result` | `tool_call_update` |
+
+Injected context (the runtime snapshot, skill lists, file-change notices) shares the `user/message` event type but is not something a user said, so it stays off the wire.
+
+## Fail-fast guard
+
+The bridge needs the persistence handle API (`ctx.sessionPersistence.open(id, 'read')`, then `read(0)`) that `0.1.5-rc.1` introduced; `0.1.2-rc.1` read logs with `load`/`inspect` on the service instead. When the mounted harness does not offer what the bridge calls, `src/compat.ts` refuses to mount and prints the missing requirement, the alternative bridge, and this repository:
+
+```
+dsh-acp-replay cannot serve session/load in this harness (harness 0.1.6):
+  - needs ctx.sessionPersistence.open(), but the mounted sessionPersistence service exposes inspect, list, load, stat
+This plugin vendors @deepseek-ai/dsh-acp@0.1.5-rc.1 and needs the persistence handle API it introduced.
+Use the shipped bridge instead ("dsh --profile acp"), or update this plugin for the installed harness.
+https://github.com/zheng1/dsh-acp-replay
+```
+
+Run `node test/selfcheck.mjs` after a harness upgrade to get that answer without a full client.
+
+## Use it
+
+The bridge replaces the shipped `acp` row in a profile. Two ways:
+
+**Install into an existing profile.** Add the package to the profile and append to its `cordis.patch.yml`:
+
+Published on npm as [`dsh-acp-replay`](https://www.npmjs.com/package/dsh-acp-replay):
+
+```bash
+dsh plugin --profile acp-replay add dsh-acp-replay   # installs it into that profile
+```
+
+The same package also works installed globally (`npm install -g dsh-acp-replay`) or copied from a checkout (put `lib/` and `package.json` in `$DSH_HOME/profiles/node_modules/dsh-acp-replay/`).
+
+```yaml
+- id: acp
+  disabled: true
+
+- insert:
+    - id: acp-replay
+      name: 'dsh-acp-replay'
+      inject: [acpAppStartup]
+      config:
+        provider: deepseek-official
+        model: deepseek-flash
+```
+
+Then point the client at `dsh --profile acp-replay` instead of `dsh --profile acp`. In Paseo that is the provider's `command`:
+
+```json
+{
+  "agents": {
+    "providers": {
+      "dsh": {
+        "extends": "acp",
+        "label": "DeepSeek Harness",
+        "command": ["dsh", "--profile", "acp-replay"]
+      }
+    }
+  }
+}
+```
+
+**Or use it as a bundle.** The package declares `dsh.bundle.patch`, so adding `dsh-acp-replay` to a profile's `dsh.profile.bundles` composes the same rows.
+
+## Build
+
+```bash
+npm install --legacy-peer-deps   # the 0.1.5 peer graph has an rc.1/rc.2 skew
+npm run build                    # tsc -> lib/
+npm test                         # guard behaviour (node:test)
+```
+
+## Verified
+
+Against `dsh 0.1.5-rc.1`, a scratch `DSH_HOME`, and a real API key:
+
+- `initialize` reports `loadSession: true`.
+- A session with two prompts runs normally through the bridge (`session/new`, `session/prompt`, `session/close`).
+- A **new process** calling `session/load` for that session id receives `user_message_chunk ×2` and `agent_message_chunk ×2` carrying the original prompts and answers, plus `usage_update ×2`.
+
+`test/replay-check.mjs` runs both phases (`record` then `load <session-id>`); `test/selfcheck.mjs` only performs `initialize` and reports whether `loadSession` is advertised.
+
+**End to end through a client** (Paseo 0.7.2 daemon, `dsh 0.1.5-rc.1`, two DSH providers on one daemon so only the bridge differs). Each agent ran one prompt, then the daemon was restarted — the event that used to erase the visible conversation:
+
+| Provider | Before restart | After restart |
+| --- | --- | --- |
+| `dsh-replay` (this bridge, advertises `loadSession`) | user prompt, assistant answer, reasoning row | **all three rows restored** |
+| `dsh` (shipped bridge, no `loadSession`) | user prompt, assistant answer | `No activity to display.` |
+
+Paseo's ACP adapter takes the `loadSession` branch only when the agent advertises the capability, primes its timeline from `streamHistory()`, and needed no change for this to work.
+
+## Not verified / known limits
+
+- Tool-call replay is mapped but not exercised by the test above.
+- An older host (`dsh 0.1.2-rc.1`) exposes a different persistence API (`load`/`inspect` instead of `open`/`read`), so this fork targets `0.1.5-rc.1` and newer only.
+- Replayed history is delivered before `session/load` returns, one notification at a time; a very long session makes that call proportionally long.
+- The profile's own help text still reads `--profile acp` (it comes from the bundled `dsh-acp-app` command provider, not from this package).
+
+## License
+
+MIT, matching the upstream package it vendors. `src/*.ts` except `src/replay.ts` are copied from [`@deepseek-ai/dsh-acp`](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/acp/acp) at tag `dsh-v0.1.5-rc.1`; the additions are the `loadSession` capability, the `loadSession` handler in `src/index.ts`, and `src/replay.ts`.

package/cordis.patch.yml

@@ -0,0 +1,10 @@
+# Replace the shipped automation bridge with this one, which also answers
+# `session/load` so a client can rebuild a transcript after its own restart.
+
+- id: acp
+  disabled: true
+
+- insert:
+    - id: acp-replay
+      name: 'dsh-acp-replay'
+      inject: [acpAppStartup]

package/lib/codec.js

@@ -0,0 +1,30 @@
+/**
+ * Pure translation between the harness lifecycle and the automation-only ACP wire.
+ * @module @deepseek-ai/dsh-acp/codec
+ */
+/**
+ * Map a harness turn ending to ACP's terminal reason vocabulary.
+ * @param reason - harness turn outcome.
+ * @returns the closest legal ACP stop reason.
+ */
+export function turnEndToStopReason(reason) {
+    switch (reason.kind) {
+        case 'completed':
+            return 'end_turn';
+        case 'max-tokens':
+            return 'max_tokens';
+        // `cancelled` is reserved for explicit client cancellation (`session/cancel`)
+        // and disposal, both settled out of band; a turn aborted by a hook or
+        // another owner is ordinary quiescence and reports `end_turn`.
+        case 'aborted':
+            return 'end_turn';
+        case 'interrupted':
+            return 'cancelled';
+        case 'blocked':
+        case 'error':
+            return 'end_turn';
+        /* v8 ignore next 2 -- TurnEndReason is closed and every member is handled above */
+        default:
+            return 'end_turn';
+    }
+}

package/lib/compat.js

@@ -0,0 +1,70 @@
+/**
+ * Fail loudly when the harness this profile booted into cannot serve
+ * `session/load`.
+ *
+ * This bridge vendors `@deepseek-ai/dsh-acp@0.1.5-rc.1` and reads a persisted
+ * log through the persistence handle API that release introduced. A harness
+ * upgrade can move that API again (`0.1.2-rc.1` exposed `load`/`inspect`
+ * directly on the service), and a silent mismatch would surface much later as
+ * "the provider will not start" or as an empty transcript. Checking once at
+ * mount turns that into one sentence naming the fix.
+ *
+ * @module dsh-acp-replay/compat
+ */
+/** Persistence methods this bridge calls on the injected service. */
+const REQUIRED_PERSISTENCE_METHODS = ['open', 'stat'];
+const HOMEPAGE = 'https://github.com/zheng1/dsh-acp-replay';
+function hasFunction(value, key) {
+    return typeof value?.[key] === 'function';
+}
+function describeService(value) {
+    if (value === null || value === undefined)
+        return 'not mounted';
+    const keys = Object.keys(value).filter((key) => hasFunction(value, key));
+    return keys.length > 0 ? keys.sort().join(', ') : 'no callable methods';
+}
+/**
+ * Report every requirement this bridge does not find in its host.
+ * @param support - the injected persistence service and ACP method constant.
+ * @returns one entry per unmet requirement; empty when the host is usable.
+ */
+export function replayHostProblems(support) {
+    const problems = [];
+    for (const method of REQUIRED_PERSISTENCE_METHODS) {
+        if (!hasFunction(support.persistence, method)) {
+            problems.push({
+                requirement: `ctx.sessionPersistence.${method}()`,
+                detail: `the mounted sessionPersistence service exposes ${describeService(support.persistence)}`,
+            });
+        }
+    }
+    if (support.sessionLoadMethod === undefined || support.sessionLoadMethod === null) {
+        problems.push({
+            requirement: 'the ACP SDK session/load method constant',
+            detail: 'this @agentclientprotocol/sdk version does not expose methods.agent.session.load',
+        });
+    }
+    return problems;
+}
+/**
+ * Refuse to mount when the host cannot serve a replayed transcript.
+ * @param support - the injected persistence service and ACP method constant.
+ * @throws when any requirement is unmet; the message names the requirement, the
+ *   alternative bridge, and where to update this plugin.
+ */
+export function assertReplayHostSupport(support) {
+    const problems = replayHostProblems(support);
+    if (problems.length === 0)
+        return;
+    const harness = support.harnessVersion === undefined ? '' : ` (harness ${support.harnessVersion})`;
+    const lines = [
+        `dsh-acp-replay cannot serve session/load in this harness${harness}:`,
+        ...problems.map((problem) => `  - needs ${problem.requirement}, but ${problem.detail}`),
+        `This plugin vendors @deepseek-ai/dsh-acp@0.1.5-rc.1 and needs the persistence handle API it introduced.`,
+        `Use the shipped bridge instead ("dsh --profile acp"), or update this plugin for the installed harness.`,
+        HOMEPAGE,
+    ];
+    const error = new Error(lines.join('\n'));
+    error.name = 'ReplayHostUnsupportedError';
+    throw error;
+}

package/lib/content.js

@@ -0,0 +1,212 @@
+/** ACP wire-content admission and projection owned by the ACP adapter. @module */
+import { isImageAdmissionError } from '@deepseek-ai/dsh-attachment';
+/** Raster formats shared by ACP image blocks and the core attachment vocabulary. */
+const IMAGE_MEDIA_TYPES = [
+    'image/png',
+    'image/jpeg',
+    'image/webp',
+    'image/gif',
+];
+/** Canonical RFC 4648 base64, excluding whitespace and URL-safe aliases. */
+const CANONICAL_BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+/** Error with a stable ACP request-failure category and no raw binary payload. */
+export class AcpContentError extends Error {
+    /** Whether the bridge should report invalid params or an internal failure. */
+    kind;
+    /**
+     * @param message - safe protocol-facing detail without inline binary data.
+     * @param kind - request-failure category.
+     * @param options - optional causal chain for diagnostics.
+     */
+    constructor(message, kind, options) {
+        super(message, options);
+        this.name = 'AcpContentError';
+        this.kind = kind;
+    }
+}
+/** Narrow a wire MIME string to the durable raster vocabulary. */
+function imageMediaType(value) {
+    return IMAGE_MEDIA_TYPES.includes(value) ? value : undefined;
+}
+/** Strictly decode one ACP inline image without accepting base64 aliases. */
+function decodeImage(block) {
+    const mediaType = imageMediaType(block.mimeType);
+    if (mediaType === undefined) {
+        throw new AcpContentError('image mimeType must be image/png, image/jpeg, image/webp, or image/gif', 'invalid');
+    }
+    if (!CANONICAL_BASE64.test(block.data)) {
+        throw new AcpContentError('image data must be canonical base64', 'invalid');
+    }
+    const data = Buffer.from(block.data, 'base64');
+    if (data.toString('base64') !== block.data) {
+        throw new AcpContentError('image data must be canonical base64', 'invalid');
+    }
+    return { data, mediaType };
+}
+/** Resolve the exact current route and require explicit image input support. */
+async function assertImageRoute(ctx, route, signal) {
+    const provider = route?.provider;
+    const model = route?.model;
+    const llm = ctx.get('llm');
+    if (provider === undefined || model === undefined || llm === undefined) {
+        throw new AcpContentError('the current model route could not be resolved for image input', 'invalid');
+    }
+    let info;
+    try {
+        info = await llm.resolveModelInfo(provider, model, signal);
+    }
+    catch (error) {
+        throw new AcpContentError('the current model route could not be verified for image input', 'internal', { cause: error });
+    }
+    if (info.inputModalities === undefined || !info.inputModalities.includes('image')) {
+        throw new AcpContentError(`model "${model}" does not declare image input`, 'invalid');
+    }
+}
+/**
+ * Determine whether initialization may truthfully advertise inline image prompts.
+ * Unknown service, route, capability, or deployment media support is negative.
+ * @param ctx - bridge context carrying optional attachment and model services.
+ * @param provider - configured provider route used for newly created sessions.
+ * @param model - configured exact model id used for newly created sessions.
+ * @returns whether this bridge can admit images at initialization time.
+ */
+export async function supportsAcpImagePrompts(ctx, provider, model) {
+    const attachments = ctx.get('attachments');
+    const llm = ctx.get('llm');
+    if (attachments === undefined || llm === undefined || provider === undefined || model === undefined)
+        return false;
+    if (!attachments.imageLimits.mediaTypes.some(mediaType => IMAGE_MEDIA_TYPES.includes(mediaType)))
+        return false;
+    try {
+        const info = await llm.resolveModelInfo(provider, model);
+        return info.inputModalities?.includes('image') === true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Render one baseline resource link into the core's current text vocabulary. */
+function resourceLinkText(block) {
+    return `\n[resource_link name=${JSON.stringify(block.name)} uri=${JSON.stringify(block.uri)}]\n`;
+}
+/**
+ * Admit one ACP prompt into ordered durable core content.
+ * Every wire block and image is validated before the ordered image batch starts
+ * writing; cancellation after a successful content-addressed write may leave an
+ * unreachable object but never queues a late user message.
+ * @param ctx - bridge context carrying attachment and model services.
+ * @param route - selection pinned to the accepted prompt.
+ * @param prompt - untrusted ACP prompt blocks in wire order.
+ * @param imageEnabled - capability result advertised during initialization.
+ * @param signal - admission cancellation signal.
+ * @returns core content with durable image references in wire order.
+ */
+export async function admitAcpPrompt(ctx, route, prompt, imageEnabled, signal) {
+    const images = [];
+    for (const block of prompt) {
+        switch (block.type) {
+            case 'text':
+            case 'resource_link':
+                break;
+            case 'image':
+                if (!imageEnabled)
+                    throw new AcpContentError('inline image prompts were not advertised by this connection', 'invalid');
+                images.push(decodeImage(block));
+                break;
+            case 'audio':
+                throw new AcpContentError('audio prompt content is not supported', 'invalid');
+            case 'resource':
+                throw new AcpContentError('embedded resource prompt content is not supported', 'invalid');
+            /* v8 ignore next 2 -- ACP ContentBlock is a closed generated union. */
+            default:
+                throw new AcpContentError('unsupported ACP prompt content', 'invalid');
+        }
+    }
+    let refs = [];
+    if (images.length > 0) {
+        const attachments = ctx.get('attachments');
+        if (attachments === undefined)
+            throw new AcpContentError('no attachment store is mounted', 'invalid');
+        await assertImageRoute(ctx, route, signal);
+        signal.throwIfAborted();
+        try {
+            refs = await attachments.saveImages(images);
+        }
+        catch (error) {
+            if (isImageAdmissionError(error)) {
+                throw new AcpContentError(error.message, 'invalid', { cause: error });
+            }
+            throw new AcpContentError('unable to persist the prompt image batch', 'internal', { cause: error });
+        }
+        signal.throwIfAborted();
+    }
+    const content = [];
+    let pendingText = '';
+    let imageIndex = 0;
+    const flushText = () => {
+        if (pendingText.length === 0)
+            return;
+        content.push({ type: 'text', text: pendingText });
+        pendingText = '';
+    };
+    for (const block of prompt) {
+        switch (block.type) {
+            case 'text':
+                pendingText += block.text;
+                break;
+            case 'resource_link':
+                pendingText += resourceLinkText(block);
+                break;
+            case 'image': {
+                flushText();
+                const ref = refs[imageIndex++];
+                content.push({ type: 'image', attachment: ref });
+                break;
+            }
+            /* v8 ignore start -- the validation pass above rejects both tags before reconstruction. */
+            case 'audio':
+            case 'resource':
+                break;
+            /* v8 ignore stop */
+            /* v8 ignore next 2 -- validated by the first closed-union switch. */
+            default:
+                break;
+        }
+    }
+    flushText();
+    if (!content.some(block => block.type === 'image' || (block.type === 'text' && block.text.trim().length > 0))) {
+        throw new AcpContentError('empty prompt', 'invalid');
+    }
+    return content;
+}
+/**
+ * Translate one committed assistant block to ACP wire content.
+ * Images are re-read and integrity-verified before inline base64 delivery;
+ * unsupported core output blocks stay off the automation wire.
+ * @param ctx - bridge context carrying the authoritative attachment store.
+ * @param block - committed core assistant block.
+ * @returns ACP text/image content, or undefined for non-output blocks.
+ */
+export async function assistantBlockToAcp(ctx, block) {
+    if (block.type === 'text') {
+        return block.text.length === 0 ? undefined : { type: 'text', text: block.text };
+    }
+    if (block.type !== 'image')
+        return undefined;
+    const attachments = ctx.get('attachments');
+    if (attachments === undefined) {
+        throw new AcpContentError('cannot deliver assistant image: no attachment store is mounted', 'internal');
+    }
+    let stored;
+    try {
+        stored = await attachments.readImage(block.attachment);
+    }
+    catch (error) {
+        throw new AcpContentError('cannot deliver assistant image: the attachment is unavailable or corrupt', 'internal', { cause: error });
+    }
+    return {
+        type: 'image',
+        data: Buffer.from(stored.data).toString('base64'),
+        mimeType: stored.ref.mediaType,
+    };
+}