dsh-edge 0.27.2 → 0.28.0

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # last confirmed-consistent state. Both languages carry equal authority.
 # After editing either side, update both and re-record every pair with:
 #   pnpm run doc-pairs -- --write
-README.md: dd52e225c3209bad68a929ad6da4bb1c19fb6bfe
-README.zh.md: 4c51097508ec42329c9dcba6efe0d9df6f220110
+README.md: cba77797c0921233282e3f52174c53a1bde912c8
+README.zh.md: 275ab4e24b908cc244ed57e4da19a9fa37b5794f

package/README.md

@@ -36,7 +36,7 @@ The browser also remains upstream-owned:
 
 The owner Durable Object admits one live main session at a time. Ordinary inputs are durably queued before acknowledgement; each residency admits one ordinary input, then returns that session to the ready queue's tail after the upstream loop becomes idle and cleanup completes. Other tabs can submit and observe the same queue. Explicit steering still targets the current run. The Edge browser binds steering/cancellation to the canonical turn it observed, so a delayed control cannot affect a newer run; legacy API callers can opt in with `x-dsh-edge-turn-seq`.
 
-The queue accepts up to 128 unsettled inputs and 2 MiB of serialized input data per owner. Capacity exhaustion returns HTTP 429 (`QUEUE_FULL`) or RPC `agent-busy`; retry after pending work drains. Browser RPC retries reuse `requestId` (legacy callers reuse `rpcId`); raw SSE callers can supply an `Idempotency-Key` (up to 128 characters). Reusing an identity with different content fails. Concurrent steering retries share the admission result; a rejected steer remains rejected on retry, including after restart. If an inbox mutation was accepted but its persistence barrier fails, model consumption is blocked and steering capacity is released; a promoted input retains its original accepted receipt. Raw SSE starts with a receipt comment and returns `x-dsh-edge-input-id`; disconnecting a stream does not cancel the queued input. Remove a queued input through `session.updateQueue`.
+The queue accepts up to 128 unsettled inputs and 2 MiB of serialized input data per owner. Capacity exhaustion returns HTTP 429 (`QUEUE_FULL`) or RPC `session/agent-busy`; retry after pending work drains. Browser RPC retries reuse `requestId` (legacy callers reuse `rpcId`); raw SSE callers can supply an `Idempotency-Key` (up to 128 characters). Reusing an identity with different content fails. Concurrent steering retries share the admission result; a rejected steer remains rejected on retry, including after restart. If an inbox mutation was accepted but its persistence barrier fails, model consumption is blocked and steering capacity is released; a promoted input retains its original accepted receipt. Raw SSE starts with a receipt comment and returns `x-dsh-edge-input-id`; disconnecting a stream does not cancel the queued input. Remove a queued input through `session.updateQueue`.
 
 Actual tool dispatch shares two permits, at most 32 waiters, a 30-second queue deadline and a 60-second cooperative execution deadline. The pool deadline is an additional ceiling: a longer configured bash timeout does not extend it, and interactive `ask_user_question` / `exit_plan_mode` calls must also settle within it. A cancelled execution retains its permit until cleanup settles. Upstream parallel/exclusive classifications remain authoritative; nested dispatch inherits the root budget. Background title streams have a separate bounded single permit and retain their upstream timeout. These limits do not make synchronous unbounded code interruptible or give each tool its own memory allocation.
 
@@ -143,7 +143,7 @@ This reference separates code that runs natively in Workers, code adapted at an
 | Provider attribution | Package version loaded with Node `createRequire` | Reused after portability fix | Import package metadata statically so bundlers preserve the same version source without requiring `import.meta.url` at runtime. |
 | LLM protocol | DSH messages, content blocks, stream chunks, tool calls, usage, and finish reasons | Reused | Let upstream `LlmRuntime` and `ReactLoopAgent` assemble, stream, and log the model exchange. DeepSeek is served by `dsh-llm-deepseek-api-key` (`llm-deepseek`). Other providers are added on the Settings → Models page as upstream does it, through `dsh-llm-pi-ai` (`llm-pi-ai`): OpenAI chat completions, OpenAI responses, or Anthropic messages, any HTTP(S) Base URL without credentials, a query, or a fragment (OpenRouter, Cloudflare Workers AI or AI Gateway, a self-hosted gateway), and model discovery from the endpoint. A saved route serves turns without a restart and can be picked in the model menu, as a new-session default, and for subagents. Providers that sign in through a local login or read local credential files (GitHub Copilot, OpenAI Codex, and Amazon Bedrock or Google Vertex through local credentials) are not offered. |
 | Agent loop | Cordis-composed `ReactLoopAgent` with hooks, guards, sessions, and tools | Reused | Create and cold-resume agents through `AgentRegistry`. Context compaction, token metering, tool-result pruning, automatic session title generation, the repeated-tool-call reminder (after 3, 5, and 8 identical consecutive calls), model-request retry (a rate limit, server error, timeout, transport error, or empty response is retried up to five times within the turn, with 0.5–10 s backoff or the provider's `Retry-After`), and durability checkpoints (the session log is stored before each model request, each top-level tool call, and each step) run as upstream cordis plugins. The upstream `/compact` command (`dsh-command-compact`) compacts the session's history on request. |
-| Bash tool | Node subprocess, sandbox, terminal, and job services | Adapted at the native tool seam | Register an upstream `ToolDefinition`, but execute its body through the configured Computer workspace backend and just-bash. The default direct backend runs inside the owner Durable Object with hardened interpreter limits and no network command; adding a `LOADER` binding selects Computer's isolated Worker Shell backend. Native tool cancellation sends `SIGINT` through the Computer execution handle. Deployment configuration supplies an explicit default timeout and caller-selectable ceiling, while `timedOut` reports the deadline independently from exit and cancellation status. Native binaries, background processes, PTYs, and arbitrary Linux behavior are unavailable. |
+| Bash tool | Node subprocess, sandbox, terminal, and job services | Adapted at the native tool seam | Register an upstream `ToolDefinition`, but execute its body through the configured Computer workspace backend and just-bash. The default direct backend runs inside the owner Durable Object with hardened interpreter limits and no network command; adding a `LOADER` binding selects Computer's isolated Worker Shell backend. Native tool cancellation sends `SIGINT` through the Computer execution handle. Deployment configuration supplies an explicit default timeout and caller-selectable ceiling, while `timedOut` reports the deadline independently from exit and cancellation status. Native binaries, background processes, PTYs, and arbitrary Linux behavior are unavailable. The bash tool has no `run_in_background` and never moves a long command to a background job. |
 | Workspace filesystem | Local filesystem services and host paths | Adapted | Store `/workspace` in the owner's SQLite-backed Durable Object VFS. |
 | Session persistence | `SessionPersistence` service, `PersistenceCoordinator`, and local JSONL/SQLite backends | Native backend adaptation | Reuse the upstream service and coordinator ownership. Implement storage primitives over Durable Object SQL with the upstream header/event mapping. One Edge-only table retains empty session headers across transparent hibernation and is removed when canonical rows materialize; no Edge turn or message schema exists. Internal coordinator helpers validate the bounded replay loader and abandon a failed unmaterialized creation before disposal. |
 | Settings and credentials | File-backed settings, launch environment, and credential services | Writable with DO storage | The upstream `dsh-settings` plugin persists user sections in Durable Object KV via `DurableObjectSettingsProvider`. The upstream `dsh-llm-deepseek` cordis plugin is installed directly, auto-registering the `llm-deepseek` settings namespace and configurable provider entry; the Settings → Models page can read and modify provider configuration (base URL, model catalog, API key reference, reasoning effort) at runtime without redeployment. `EdgeCredentialProvider` resolves credentials from DO KV first, then falls back to Worker environment secrets; `set`/`unset` persist through the upstream seam. Deployment defaults (maxTokens 256,000, reasoningEffort high) are aligned with the upstream plugin so unset deployment variables match upstream behavior. Settings → Built-in plugins also has a Settings tab with upstream's agent-loop and web-search cards: the Edge registers their `agent-loop` (parallel tool calls) and `web-search-deepseek` (searches per request, endpoint, and the DeepSeek key the search uses) namespaces, applies a saved value to the running plugin, and refuses an endpoint that `DEEPSEEK_SEARCH_BASE_URL` would refuse. Upstream's Subagent card edits the subagent runtime's `subagent` namespace: maximum recursion depth (default 1) and the parallelism limit for resident subagents (default 8); its models section edits `subagent-model-selection-settings`: off by default, as upstream; when on, a new session records the allowed models once (a `subagent/model-selection-policy` event), and its `subagent` tool gains `list_subagent_models` and may run a child on one of them. Edge sessions are resumed on first use, so the Edge records the setting on a root session that has not run a turn yet, where upstream records it on a session never seeded. `subagent_fork` children keep the parent's model. Upstream's plugin manager page, which hosts these cards upstream, is not shipped, because it installs and removes plugins through a runtime Loader the Edge does not have. |
@@ -153,8 +153,8 @@ This reference separates code that runs natively in Workers, code adapted at an
 | Directory picker | `ctx.directoryPicker` seam with the `-native` OS chooser or the `-browse` filesystem backend, chosen at boot by `dsh-host-directory-picker-auto`, plus the Web browse dialog | Reused with an Edge browse backend | Install the upstream seam and pin the upstream `dsh-client-ui-directory-picker-browse` dialog in the Web roster; Edge answers the `browse` capability from the `/workspace` Computer VFS one level per call, rooted at `/workspace` with the upstream hidden, bound, and failure vocabulary, so the upstream `DirectoryPickerController` serves `directoryPicker/list` and `createDirectory` and refuses the native `pick`. |
 | Conversation file links | `session/openWorkspacePath` hands a clicked path to the Host desktop opener through `dsh-native-command`; `session/canOpenWorkspacePath` gates the affordance | Adapted at the upstream `SessionControllerInternals` seam plus a Web download fallback | Compose `SessionController` with Edge internals so the native probe answers false and an open attempt fails with a readable reason instead of a `child_process` error. The V3 Web client opens file links in its right-sidebar preview. Edge composes the upstream `workspaceFiles` controller over request-scoped VFS reads, including bounded text/byte windows and metadata subscriptions. The legacy `ctx.remote.session.openWorkspacePath` fallback and owner-authenticated `GET /api/workspace/file` download remain available. |
 | Existing Web UI | Runtime-loaded shell and `dsh.client` plugin graph | Reused with generic composition fallbacks | Assemble the upstream shell and supported upstream client bundles as Worker assets. Shared slot-occupancy rules hide actions whose provider is absent; Cloudflare serves ordinary assets directly, while `/`, `/login`, and `/api/*` enter the Worker for owner access control. The assembled asset policy prevents every direct or SPA-fallback shell alias from being framed. |
-| Other tools | Web Search, filesystem editor tools, MCP, skills, workflows, jobs, and subagents | Search, file, glob/grep, goal, todo, skill, subagent, and MCP tools ported; workflow and run_code ported for the isolated build | Reuse upstream DeepSeek Web Search with its 30-second tool-call timeout. The web search card's "Use the new Web Search API" switch (off by default) moves search and fetch to the DeepSeek Search and Fetch APIs (`dsh-web-deepseek-api`): DeepSeek fetches the page, so the Worker reads no third-party page itself, and no auxiliary model request is made. They use the DeepSeek API key the Models page stores (the key name may not be another Edge feature's credential, and a literal key is refused in settings), their API base must be an HTTP(S) URL without credentials, a query, or a fragment, a redirect is refused, and the account sign-in route is not offered. The Search and Fetch APIs may bill separately from model tokens. The upstream `workflow` tool is offered only by the Dynamic Worker runtime (the isolated, Paid-plan build); the Direct build does not register it. Each run loads its script into its own Dynamic Worker with no outbound network and a 30-second Worker Loader `cpuMs` limit (enforced by the Cloudflare runtime, not by local development), because workerd forbids in-process `eval`/`new Function`/`node:vm`; `agent()`, `phase()`, and `log()` cross an RPC bridge to the Durable Object, which enforces the caps: at most 4 children run at once (below the Workers six-connection limit) and one run starts at most 100 children to bound child-session row writes. The upstream `run_code` tool (`dsh-tools` PTC mode) is offered by the same runtime, but only to sessions started in the upstream `ptc` agent preset (PTC mode), which isolated deployments offer under its upstream id so the Web client shows its built-in bilingual name. That preset presents every tool through the generated SDK and, as upstream does, does not offer `workflow`, because `run_code` is its only orchestration surface. The default upstream `standard` preset (Standard mode; sessions recorded under the earlier `dsh-edge` id read as `standard`) presents tools natively and keeps `workflow`. As upstream, Settings → Agent presets writes `selectedDefault` in the `agent-preset-registry` settings namespace to choose which offered preset new sessions start on; a default saved by an earlier release under `agent-presets` moves there on start. In PTC mode, each program is type-stripped with sucrase and runs in its own Dynamic Worker with a 30-second `cpuMs` limit and no outbound network; its `tools.*` calls cross an RPC bridge where the Durable Object caps them at 200 per run (each is a nested tool dispatch with its own session events), 256 KiB of arguments, and 2 MiB per result, and nested calls stay approval-gated. File tools (read/write/edit/read_image) adapted via `EdgeFileSystem` backed by Computer VFS. `glob` and `grep` keep upstream `dsh-tool-fs-search`'s names, schemas, result text, search cards, and spill of results over 100 paths or 250 matches, but Workers cannot spawn its ripgrep binary, so Edge runs them over the VFS: both skip VCS metadata, `grep` also skips hidden files, binary files, and files over 4 MiB, and neither applies `.gitignore`. `grep` patterns use RE2 syntax (no lookaround or backreferences) through re2js, which matches in linear time, so a pathological pattern cannot stall the Durable Object. A search walks at most 20,000 entries, and `grep` collects at most 20,000 matching lines or 20 MB of their text; past a cap it fails and asks for a narrower path or pattern. Glob syntax that ripgrep 15 rejects (an unclosed `[` or `{`, a reversed range such as `[z-a]`, a dangling `\`) fails as an invalid pattern; nested alternates such as `a{b,{c,d}}` work. A search checks for cancellation before and after each directory listing, so the 30-second tool timeout stops a long walk. As upstream, the file observation policy (`dsh-fs-observation-policy`) guards them: `write` may not overwrite a file the session has not read, `edit` requires a prior read, and a file changed since it was read (by `bash` or the Linux container, for example) fails as stale until it is read again; a restarted session starts with no reads recorded. Goal tools (`ToolGoal`) composed directly with `GoalService` as upstream cordis plugins. Subagents follow upstream's standard composition: `subagent` starts a fresh child and `subagent_fork` one that starts from the parent's completed turns (`dsh-subagent-spawn-in-process`, `dsh-subagent-fork-in-process`). Both run the child in the background by default as a continuable subagent, and the parent continues it with `send_message`, stops its current turn with `interrupt_agent`, and finds it with `list_agents` (`dsh-tool-subagent-control`). A child keeps working after the parent's turn ends, and its closing message wakes the parent for another turn; as upstream, Stop on the parent does not stop running children. A child that is not running resumes from storage when messaged, also after a restart. The upstream `todo_write` tool (`dsh-tool-todo`) keeps the session's task list, with several tasks allowed in progress as in upstream's composition; its `todos` projection drives the Web client's todo dock. The upstream `present` tool (`dsh-tool-present`) declares workspace files as a turn's deliverables, which the Web client shows as file cards with a sidebar preview; the Edge has no desktop, so it answers the cards' Host check (`/api/present.host`) as unavailable and they offer no native opening. As upstream, `dsh-agent-instructions` loads `AGENTS.md` and `CLAUDE.md` (and their `.local.md` overlays) from the project root (the nearest ancestor directory containing `.git`, or else the session's working directory) down to the working directory, through the workspace VFS, into a 64 KiB baseline message before the first request; a `read`, `write`, or `edit` that reaches a deeper directory adds its instructions to the next request. Workers have no home directory, so the user-global files are `/.dsh/AGENTS.md` and the shared agent root's `/.agents/AGENTS.md` (the Edge sets `DSH_HOME` and `DSH_AGENTS_HOME` itself, because the plugin reads its homes only from those variables). The `working_directory` tool (`dsh-tool-working-directory`) reads the session's working directory or changes it to an existing directory; the change is a durable `working-directory/change` event that a downgrade to a release before this one cannot read, and the Edge always offers `/workspace` as an existing directory. Skill tool via `SkillRegistry`. As upstream `dsh-skill-filesystem`, skills are `<name>/SKILL.md` or `<name>.md` files with `name` and `description` frontmatter under the project's `.dsh/skills` and `.agents/skills` and the user roots `/.dsh/skills` and `/.agents/skills` (Workers have no home directory), read through the workspace VFS, up to 100 entries per root and 64 KiB per skill file; an added or edited skill applies from the next turn, and the `/` menu of a session opened after the change lists it; as upstream, the Web client keeps an open session's `/` list until the page reloads. Skills stored through the owner API `GET/PUT/DELETE /api/skills` (`EdgeSkillProvider`, DO KV) rank below them. MCP client (`dsh-mcp-client`) installed; Streamable HTTP transport only (stdio unavailable on Workers). Configure servers in Settings → DSH Edge → MCP Servers; tools appear as `mcp__<serverName>__<tool>`. Add the remaining tools individually against Worker-compatible capabilities; do not advertise unavailable host behavior. |
-| Attachments | Local attachment storage, upstream image references, composer, gallery, lightbox, and provider conversion | Adapted at the native storage seam | Reuse upstream `AttachmentStore`, admission, protocol, authorization, UI, and DeepSeek conversion unchanged. Store immutable PNG/JPEG bytes under their SHA-256 identities in a 64 MiB, 512 KiB-chunked DO backend for new and pre-attachment deployments, or in private R2 for deployments already pinned to it; session events retain only upstream refs. The first backend is pinned per owner instance so claiming or upgrading cannot strand existing references. |
+| Other tools | Web Search, filesystem editor tools, MCP, skills, workflows, jobs, and subagents | Search, file, glob/grep, goal, todo, skill, subagent, and MCP tools ported; workflow and run_code ported for the isolated build | Reuse upstream DeepSeek Web Search with its 30-second tool-call timeout. The web search card's "Use the new Web Search API" switch (off by default) moves search and fetch to the DeepSeek Search and Fetch APIs (`dsh-web-deepseek-api`): DeepSeek fetches the page, so the Worker reads no third-party page itself, and no auxiliary model request is made. They use the DeepSeek API key the Models page stores (the key name may not be another Edge feature's credential, and a literal key is refused in settings), their API base must be an HTTP(S) URL without credentials, a query, or a fragment, a redirect is refused, and the account sign-in route is not offered. The Search and Fetch APIs may bill separately from model tokens. The upstream `workflow` tool is offered only by the Dynamic Worker runtime (the isolated, Paid-plan build); the Direct build does not register it. Each run loads its script into its own Dynamic Worker with no outbound network and a 30-second Worker Loader `cpuMs` limit (enforced by the Cloudflare runtime, not by local development), because workerd forbids in-process `eval`/`new Function`/`node:vm`; `agent()`, `phase()`, and `log()` cross an RPC bridge to the Durable Object, which enforces the caps: at most 4 children run at once (below the Workers six-connection limit) and one run starts at most 100 children to bound child-session row writes. The upstream `run_code` tool (`dsh-tools` PTC mode) is offered by the same runtime, but only to sessions started in the upstream `ptc` agent preset (PTC mode), which isolated deployments offer under its upstream id so the Web client shows its built-in bilingual name. That preset presents every tool through the generated SDK and, as upstream does, does not offer `workflow`, because `run_code` is its only orchestration surface. The default upstream `standard` preset (Standard mode; sessions recorded under the earlier `dsh-edge` id read as `standard`) presents tools natively and keeps `workflow`. As upstream, Settings → Agent presets writes `selectedDefault` in the `agent-preset-registry` settings namespace to choose which offered preset new sessions start on; a default saved by an earlier release under `agent-presets` moves there on start. In PTC mode, each program is type-stripped with sucrase and runs in its own Dynamic Worker with a 30-second `cpuMs` limit and no outbound network; its `tools.*` calls cross an RPC bridge where the Durable Object caps them at 200 per run (each is a nested tool dispatch with its own session events), 256 KiB of arguments, and 2 MiB per result, and nested calls stay approval-gated. File tools (read/write/edit/read_image) adapted via `EdgeFileSystem` backed by Computer VFS. `glob` and `grep` keep upstream `dsh-tool-fs-search`'s names, schemas, result text, search cards, and spill of results over 100 paths or 250 matches, but Workers cannot spawn its ripgrep binary, so Edge runs them over the VFS: both skip VCS metadata, `grep` also skips hidden files, binary files, and files over 4 MiB, and neither applies `.gitignore`. `grep` patterns use RE2 syntax (no lookaround or backreferences) through re2js, which matches in linear time, so a pathological pattern cannot stall the Durable Object. A search walks at most 20,000 entries, and `grep` collects at most 20,000 matching lines or 20 MB of their text; past a cap it fails and asks for a narrower path or pattern. Glob syntax that ripgrep 15 rejects (an unclosed `[` or `{`, a reversed range such as `[z-a]`, a dangling `\`) fails as an invalid pattern; nested alternates such as `a{b,{c,d}}` work. A search checks for cancellation before and after each directory listing, so the 30-second tool timeout stops a long walk. As upstream, the file observation policy (`dsh-fs-observation-policy`) guards them: `write` may not overwrite a file the session has not read, `edit` requires a prior read, and a file changed since it was read (by `bash` or the Linux container, for example) fails as stale until it is read again; a restarted session starts with no reads recorded. Goal tools (`ToolGoal`) composed directly with `GoalService` as upstream cordis plugins. Subagents follow upstream's standard composition: `subagent` starts a fresh child and `subagent_fork` one that starts from the parent's completed turns (`dsh-subagent-spawn-in-process`, `dsh-subagent-fork-in-process`). Both run the child in the background by default as a continuable subagent, and the parent continues it with `send_message`, stops its current turn with `interrupt_agent`, and finds it with `list_agents` (`dsh-tool-subagent-control`). A child keeps working after the parent's turn ends, and its closing message wakes the parent for another turn; as upstream, Stop on the parent does not stop running children. A child that is not running resumes from storage when messaged, also after a restart. The upstream `todo_write` tool (`dsh-tool-todo`) keeps the session's task list, with several tasks allowed in progress as in upstream's composition; its `todos` projection drives the Web client's todo dock. The upstream `present` tool (`dsh-tool-present`) declares workspace files as a turn's deliverables, which the Web client shows as file cards with a sidebar preview; the Edge has no desktop, so it answers the cards' Host check (`/api/present.host`) as unavailable and they offer no native opening. As upstream, `dsh-agent-instructions` loads `AGENTS.md` and `CLAUDE.md` (and their `.local.md` overlays) from the project root (the nearest ancestor directory containing `.git`, or else the session's working directory) down to the working directory, through the workspace VFS, into a 64 KiB baseline message before the first request; a `read`, `write`, or `edit` that reaches a deeper directory adds its instructions to the next request. Workers have no home directory, so the user-global files are `/.dsh/AGENTS.md` and the shared agent root's `/.agents/AGENTS.md` (the Edge sets `DSH_HOME` and `DSH_AGENTS_HOME` itself, because the plugin reads its homes only from those variables). The `working_directory` tool (`dsh-tool-working-directory`) reads the session's working directory or changes it to an existing directory; the change is a durable `working-directory/change` event that a downgrade to a release before this one cannot read, and the Edge always offers `/workspace` as an existing directory. Skill tool via `SkillRegistry`. As upstream `dsh-skill-filesystem`, skills are `<name>/SKILL.md` or `<name>.md` files with `name` and `description` frontmatter under the project's `.dsh/skills` and `.agents/skills` and the user roots `/.dsh/skills` and `/.agents/skills` (Workers have no home directory), read through the workspace VFS, up to 100 entries per root and 64 KiB per skill file; an added or edited skill applies from the next turn, and the `/` menu of a session opened after the change lists it; as upstream, the Web client keeps an open session's `/` list until the page reloads. Skills stored through the owner API `GET/PUT/DELETE /api/skills` (`EdgeSkillProvider`, DO KV) rank below them. MCP runs on the Edge's own client (`edge-mcp-client.ts`; upstream `dsh-mcp-client` is not mounted): Streamable HTTP only (stdio is unavailable on Workers), one connection per call, and tools only, so MCP resources are not offered yet. Configure servers in Settings → DSH Edge → MCP Servers; tools appear as `mcp__<serverName>__<tool>`. Add the remaining tools individually against Worker-compatible capabilities; do not advertise unavailable host behavior. |
+| Attachments | Local attachment storage, upstream image references, composer, gallery, lightbox, and provider conversion | Adapted at the native storage seam | Reuse upstream `AttachmentStore`, admission, protocol, authorization, UI, and DeepSeek conversion unchanged. Store immutable PNG/JPEG bytes under their SHA-256 identities in a 64 MiB, 512 KiB-chunked DO backend for new and pre-attachment deployments, or in private R2 for deployments already pinned to it; session events retain only upstream refs. The first backend is pinned per owner instance so claiming or upgrading cannot strand existing references. Images are PNG or JPEG, at most 3.5 MiB each and 4 per message. Other files stream through upstream's upload route and are kept verbatim, at most 64 MiB each (an upload must declare its length, so a larger one is refused before any byte is stored), in the workspace VFS at upstream's `files/<prefix>/<digest>/<name>` layout below `/.dsh/attachments/v1`, the path the model is told; its file tools and the lightweight shell read them there, but commands routed to a Linux Container do not see them. |
 | Goal tracking | `GoalService` with create/edit/pause/resume/complete/clear mutations and GoalBar UI | Reused | Install upstream `GoalService` and `ToolGoal` as cordis plugins (direct composition). Browser GoalBar mutations route through `TypertGatewayService` at `/api/goals/<method>`. `SessionProjectionCache` persists goal state across DO restart. The upstream `/goal` command (`dsh-command-goal`) shows, sets, edits, pauses, resumes, or clears the session's goal. Every goal round runs inside an Edge turn, with its workspace, deadline, and live events: a turn stays open while upstream's round driver queues the next round, and a call that arms a goal outside a turn (`/goal`, GoalBar Resume) runs inside a new one. |
 | Context compaction | Token metering, automatic compaction, and session title generation | Reused | Install upstream cordis plugins directly. Context compaction, token metering, tool-result pruning, and automatic session title generation run unchanged. Upstream image offload (`dsh-compaction-image-offload`) keeps a turn going when its images exceed the route's budget (600 images per request by default): it marks the oldest occurrences offloaded with an `image/offload` session event and the request is retried. |
 | Session projection | Real-time derived state push to connected clients | Reused with Edge bridge | Upstream `onChanged` callback pushes title, model, goal, and session-stats projection frames to connected WebSocket clients. Upstream `dsh-session-stats` (whole-session turn and step counts and model, tool, and first-token times) feeds the Web chat view. `SessionProjectionCache` caches projections in DO KV for cold-session recovery. |
@@ -348,7 +348,7 @@ SQLite `DELETE` operations consume the daily row-write allowance too. During for
 - `GET /api/workspace/file?path=/workspace/...` reads a UTF-8 file.
 - `DELETE /api/workspace/file?path=/workspace/...` removes a file.
 - `POST /api/workspace/exec` accepts `{ "command": "...", "cwd": "/workspace/..." }`; `cwd` defaults to `/workspace`, every execution receives the deployment default timeout, `timedOut` reports whether that deadline elapsed, and `outputTruncated` reports whether the retention bound was crossed.
-- `POST /api/sessions` creates a persistent session with a required `title`, recorded as a standard user-sourced `session/title` event before the API returns. If the session is durable but its Workspace attachment fails, the 500 response uses `workspace-attach-failed` and includes the complete created `session`, so callers can recover its id instead of creating a duplicate.
+- `POST /api/sessions` creates a persistent session with a required `title`, recorded as a standard user-sourced `session/title` event before the API returns. If the session is durable but its Workspace attachment fails, the 500 response uses `session/workspace-attach-failed` and includes the complete created `session`, so callers can recover its id instead of creating a duplicate.
 - `GET /api/sessions?after=...&limit=...` lists one bounded summary page; `GET /api/sessions/:sessionId` reads one. Session deletion is not exposed because the upstream persistence service does not define destructive deletion.
 - `POST /api/sessions/:sessionId/turn` accepts `{ "message": "..." }` and streams persisted SSE events.
 - `GET /api/sessions/:sessionId/events?after=...&limit=...` replays a bounded event page and returns continuation headers.
@@ -356,7 +356,7 @@ SQLite `DELETE` operations consume the daily row-write allowance too. During for
 
 ### Session and Workspace behavior
 
-- Session creation and fork return `workspace-attach-failed` with the published session and Workspace ids when publication succeeds but Workspace attachment fails. The diagnostic route returns the same code plus the complete created session.
+- Session creation and fork return `session/workspace-attach-failed` with the published session and Workspace ids when publication succeeds but Workspace attachment fails. The diagnostic route returns the same code plus the complete created session.
 - Prompt and queue-edit text share a 64 KiB semantic limit. Their 10 MiB RPC carrier leaves room for a 7 MiB raw-image batch after base64 and envelope overhead.
 - Because Edge has no directory-flow provider, the upstream browser hides Delete on its sole Workspace and exposes it again whenever restoration remains possible.
 - `@file` completion serves the upstream `fileReferences/list` Remote from the Computer VFS one directory at a time: the session working directory for a bare fragment, or the directory a trailing slash names. There is no recursive fuzzy index because every listing is a Computer call. `@session` mentions and their pre-step snapshots come from the upstream session-reference service unchanged; its candidate discovery and either agent-scoped Remote resume a cold session through the upstream controller and keep it resident until the Durable Object is evicted.

package/README.zh.md

@@ -36,7 +36,7 @@
 
 owner Durable Object 同一时间只准入一个活跃主会话。普通输入先持久排队再确认收到；每次驻留准入一条普通输入，上游 loop 空闲且清理完成后，有待处理输入的会话回到就绪队尾。其他 tab 可以提交并观察同一份队列。显式 steer 仍指向当前运行。Edge 浏览器把 steer/取消绑定到它观察到的 canonical turn，防止延迟操作影响新运行；旧 API 客户端可通过 `x-dsh-edge-turn-seq` 启用同样的校验。
 
-每个 owner 最多接受 128 条未收尾输入和 2 MiB 的序列化输入数据。容量耗尽返回 HTTP 429（`QUEUE_FULL`）或 RPC `agent-busy`；待积压任务减少后重试。浏览器 RPC 重试复用 `requestId`（旧客户端复用 `rpcId`）；原始 SSE 调用可提供最长 128 字符的 `Idempotency-Key`。同一身份携带不同内容会失败。并发 steer 重试共享准入结果；被拒绝的 steer 再次重试仍返回拒绝，重启后也一样。若收件箱已接受变更但持久化屏障失败，则阻止模型消费并释放 steering 容量；从队列提升的输入保留原先已接受的收件状态。原始 SSE 先发送收件注释，并返回 `x-dsh-edge-input-id`；断开流不会取消排队输入，可通过 `session.updateQueue` 移除。
+每个 owner 最多接受 128 条未收尾输入和 2 MiB 的序列化输入数据。容量耗尽返回 HTTP 429（`QUEUE_FULL`）或 RPC `session/agent-busy`；待积压任务减少后重试。浏览器 RPC 重试复用 `requestId`（旧客户端复用 `rpcId`）；原始 SSE 调用可提供最长 128 字符的 `Idempotency-Key`。同一身份携带不同内容会失败。并发 steer 重试共享准入结果；被拒绝的 steer 再次重试仍返回拒绝，重启后也一样。若收件箱已接受变更但持久化屏障失败，则阻止模型消费并释放 steering 容量；从队列提升的输入保留原先已接受的收件状态。原始 SSE 先发送收件注释，并返回 `x-dsh-edge-input-id`；断开流不会取消排队输入，可通过 `session.updateQueue` 移除。
 
 实际工具执行共享两个许可，最多等待 32 项，排队期限 30 秒，合作式执行期限 60 秒。工具池期限是额外的上限：bash 配置更长的超时不会延长它，交互式 `ask_user_question` / `exit_plan_mode` 也必须在此期限内结束。取消后必须等清理结束才归还许可。上游的并行/独占分类继续有效；嵌套调用继承根执行预算。后台标题流单独使用一个有界许可，保留上游超时。这些限制不能中断无界同步代码，也不会为每个工具分配独立内存。
 
@@ -143,7 +143,7 @@ curl -b /tmp/dsh-edge-cookie -N -X POST -H 'content-type: application/json' \
 | Provider attribution | 用 Node `createRequire` 加载 package version | 完成可移植修复后复用 | 静态导入 package metadata，让 bundler 保留同一个版本来源，运行时不再依赖 `import.meta.url`。 |
 | LLM protocol | DSH messages、content blocks、stream chunks、tool calls、usage 和 finish reasons | 复用 | 由上游 `LlmRuntime` 和 `ReactLoopAgent` 组装、流式处理并记录 model exchange。 DeepSeek 由 `dsh-llm-deepseek-api-key`（`llm-deepseek`）提供。其他服务商与上游一样在"设置 → Models"页面添加，通过 `dsh-llm-pi-ai`（`llm-pi-ai`）接入：支持 OpenAI chat completions、OpenAI responses 和 Anthropic messages 协议，Base URL 可以是任意不带账号密码、查询参数或片段的 HTTP(S) 地址（OpenRouter、Cloudflare Workers AI 或 AI Gateway、自建网关），并可从端点发现模型。保存的路由无需重启即可用于对话，可以在模型菜单中选择，可以作为新会话的默认模型，也可以给子 agent 使用。依赖本地登录或读取本地凭据文件的服务商（GitHub Copilot、OpenAI Codex，以及通过本地凭据使用的 Amazon Bedrock 或 Google Vertex）不提供。 |
 | Agent loop | 由 Cordis 组合、带 hooks、guards、sessions 和 tools 的 `ReactLoopAgent` | 复用 | 通过 `AgentRegistry` 创建和冷恢复 agent。上下文压缩、token 计量、工具结果修剪、自动 session 标题生成、重复工具调用提醒（连续 3、5、8 次完全相同的调用时提醒）、模型请求重试（遇到限流、服务端错误、超时、网络错误或空响应时，在同一轮内最多重试 5 次，等待 0.5–10 秒，或按服务端的 `Retry-After`），以及持久化检查点（每次模型请求、每次顶层工具调用和每一步之前先保存 session 日志），作为上游 cordis 插件运行。上游的 `/compact` 命令（`dsh-command-compact`）按需压缩会话历史。 |
-| Bash tool | Node subprocess、sandbox、terminal 和 job services | 在原生 tool seam 上适配 | 注册上游 `ToolDefinition`，但通过配置的 Computer workspace backend 和 just-bash 执行其 body。默认 direct backend 在 owner Durable Object 内运行，启用 hardened interpreter limits 且不提供网络命令；添加 `LOADER` binding 后会选择 Computer 的 isolated Worker Shell backend。原生 tool cancellation 会通过 Computer execution handle 发送 `SIGINT`。部署配置提供明确的默认 timeout 与调用方可选值上限，`timedOut` 则独立于 exit 与 cancellation status 报告 deadline。不支持原生二进制、后台进程、PTY 和任意 Linux 行为。 |
+| Bash tool | Node subprocess、sandbox、terminal 和 job services | 在原生 tool seam 上适配 | 注册上游 `ToolDefinition`，但通过配置的 Computer workspace backend 和 just-bash 执行其 body。默认 direct backend 在 owner Durable Object 内运行，启用 hardened interpreter limits 且不提供网络命令；添加 `LOADER` binding 后会选择 Computer 的 isolated Worker Shell backend。原生 tool cancellation 会通过 Computer execution handle 发送 `SIGINT`。部署配置提供明确的默认 timeout 与调用方可选值上限，`timedOut` 则独立于 exit 与 cancellation status 报告 deadline。不支持原生二进制、后台进程、PTY 和任意 Linux 行为。bash 工具没有 `run_in_background`，也不会把耗时命令转为后台任务。 |
 | Workspace filesystem | 本地 filesystem services 和 host paths | 适配 | 在 owner 基于 SQLite 的 Durable Object VFS 中保存 `/workspace`。 |
 | Session persistence | `SessionPersistence` service、`PersistenceCoordinator` 及本地 JSONL/SQLite backends | 原生 backend 适配 | 复用上游 service 及 coordinator 的职责划分，在 Durable Object SQL 上实现存储原语，并使用上游 header/event 映射。一个 Edge 独有表会在透明休眠期间保留 empty session header，并在 canonical rows 物化时删除；Edge 不定义 turn 或 message schema。内部 coordinator helper 负责校验有界 replay loader，并在 disposal 前放弃失败且尚未物化的创建。 |
 | Settings and credentials | 基于文件的 settings、launch environment 和 credential services | 可写，使用 DO 存储 | 上游 `dsh-settings` 插件通过 `DurableObjectSettingsProvider` 把 user section 持久化到 Durable Object KV。上游 `dsh-llm-deepseek` cordis 插件直接安装，自动注册 `llm-deepseek` Settings 命名空间和可配置 Provider 条目；Settings → Models 页面可在运行时读取和修改 Provider 配置（base URL、model catalog、API key reference、reasoning effort），无需重新部署。`EdgeCredentialProvider` 先从 DO KV 解析凭证，然后降级到 Worker 环境变量 secret；`set`/`unset` 通过上游接缝持久化。部署默认值（maxTokens 256,000，reasoningEffort high）与上游插件对齐，未设置部署变量时与上游行为一致。 Settings → 内置插件还有一个“设置”标签页，提供上游的 Agent 循环和网页搜索两张卡片：Edge 注册它们的 `agent-loop`（并行工具调用数）和 `web-search-deepseek`（每次请求的搜索次数、接口地址，以及搜索使用的 DeepSeek Key）命名空间，把保存的值应用到正在运行的插件，并拒绝 `DEEPSEEK_SEARCH_BASE_URL` 同样会拒绝的接口地址。上游的子 agent 卡片编辑子 agent 运行时的 `subagent` 命名空间：最大递归深度（默认 1）和常驻子 agent 的并行上限（默认 8）；卡片的选模型部分编辑 `subagent-model-selection-settings`：与上游一样默认关闭；开启后，新会话会记录一次允许的模型（一条 `subagent/model-selection-policy` 事件），其 `subagent` 工具会多出 `list_subagent_models`，并可让子 agent 使用其中的模型运行。Edge 的会话在首次使用时恢复，所以 Edge 在尚未运行过 turn 的根会话上记录该设置，而上游在从未加种子的会话上记录。`subagent_fork` 的子 agent 沿用父 agent 的模型。上游承载这些卡片的插件管理器页面没有提供，因为它通过 Edge 没有的运行时 Loader 安装和卸载插件。 |
@@ -153,8 +153,8 @@ curl -b /tmp/dsh-edge-cookie -N -X POST -H 'content-type: application/json' \
 | Directory picker | `ctx.directoryPicker` seam，由 `dsh-host-directory-picker-auto` 在启动时选择 `-native` OS 选择器或 `-browse` 文件系统 backend，加 Web browse 对话框 | 复用并提供 Edge browse backend | 安装上游 seam，并把上游 `dsh-client-ui-directory-picker-browse` 对话框固定进 Web roster；Edge 从 `/workspace` Computer VFS 按每次一层回答 `browse` capability，以 `/workspace` 为根并沿用上游的 hidden、bound 与失败词汇，因此上游 `DirectoryPickerController` 提供 `directoryPicker/list` 与 `createDirectory`，并拒绝原生 `pick`。 |
 | 对话文件链接 | `session/openWorkspacePath` 经 `dsh-native-command` 把点击的路径交给宿主桌面打开器；`session/canOpenWorkspacePath` 决定是否展示该入口 | 在上游 `SessionControllerInternals` seam 适配，加 Web 端下载回退 | 用 Edge internals 组合 `SessionController`，让原生探测返回 false、打开尝试以可读原因失败而不是 `child_process` 错误。V3 Web 客户端在右侧栏预览文件链接。Edge 将上游 `workspaceFiles` 控制器接入请求作用域内的 VFS 读取，支持有界文本/字节分页和元数据订阅。旧版 `ctx.remote.session.openWorkspacePath` 回退以及经 owner 鉴权的 `GET /api/workspace/file` 下载仍然可用。 |
 | Existing Web UI | 运行时加载的 shell 和 `dsh.client` 插件 graph | 复用并采用通用 composition fallback | 把上游 shell 和受支持的上游客户端包组装成 Worker 静态资源；共享的 slot occupancy 规则会隐藏缺少 provider 的 action。Cloudflare 直接提供普通资源，`/`、`/login` 与 `/api/*` 则进入 Worker 执行 owner access control。组装后的 asset policy 会阻止所有直接或 SPA-fallback shell alias 被嵌入 frame。 |
-| Other tools | Web Search、filesystem editor tools、MCP、skills、workflows、jobs 和 subagents | Search、文件、glob/grep、goal、todo、skill、subagent 和 MCP 工具已移植；workflow 与 run_code 已在 isolated 构建中移植 | 复用上游 DeepSeek Web Search 及其 30 秒 tool-call timeout。网页搜索卡片里的“Use the new Web Search API”开关（默认关闭）会把搜索和抓取切换到 DeepSeek Search and Fetch API（`dsh-web-deepseek-api`）：页面由 DeepSeek 抓取，Worker 自己不读取任何第三方页面，也不产生辅助模型请求。它们使用 Models 页面保存的 DeepSeek API key（key 名称不能是其他 Edge 功能的凭据，设置里不接受明文 key），API 地址必须是不含凭据、查询或片段的 HTTP(S) URL，重定向会被拒绝，也不提供账号登录路径。Search and Fetch API 可能与模型 token 分开计费。上游 `workflow` 工具仅由 Dynamic Worker 运行时提供（isolated、Paid 计划构建）；Direct 构建不注册该工具。由于 workerd 禁止在进程内使用 `eval`/`new Function`/`node:vm`，每次运行都会把脚本加载到独立的 Dynamic Worker 中执行，该 Worker 无出站网络，并受 30 秒 Worker Loader `cpuMs` 上限约束（由 Cloudflare 运行时强制执行，本地开发环境不执行）；`agent()`、`phase()`、`log()` 经 RPC 桥回到 Durable Object，由其执行各项上限：同时最多运行 4 个子 agent（低于 Workers 六连接上限），单次运行最多启动 100 个子 agent，以限制子会话的行写入。上游 `run_code` 工具（`dsh-tools` PTC 模式）由同一运行时提供，但只提供给以上游 `ptc` agent 预设（PTC 模式）开始的会话。isolated 部署沿用上游 id 提供该预设，因此 Web 客户端显示其内置的双语名称。该预设通过生成的 SDK 呈现全部工具，并与上游一样不提供 `workflow`，因为 `run_code` 是它唯一的编排方式。默认使用上游的 `standard` 预设（标准模式；以早先 `dsh-edge` id 记录的会话按 `standard` 读取），以原生方式呈现工具，并保留 `workflow`。与上游一致，Settings → Agent presets 写入 `agent-preset-registry` 设置命名空间的 `selectedDefault`，从可用预设中选择新会话的起始预设；早期版本保存在 `agent-presets` 下的默认值会在启动时迁移过来。在 PTC 模式下，每个程序先用 sucrase 去除类型，再在独立 Dynamic Worker 中运行，受 30 秒 `cpuMs` 上限约束且无出站网络；其中的 `tools.*` 调用经 RPC 桥回到 Durable Object，由其限制为每次运行最多 200 次（每次都是一次写入 session 事件的嵌套工具派发）、参数最多 256 KiB、单次结果最多 2 MiB，嵌套调用仍走审批。文件工具（read/write/edit/read_image）通过 `EdgeFileSystem` 适配 Computer VFS。`glob` 和 `grep` 保持上游 `dsh-tool-fs-search` 的工具名、参数结构、结果文本、搜索卡片，以及超过 100 条路径或 250 条匹配时把完整结果另存为文件；但 Workers 无法启动它所需的 ripgrep 程序，所以 Edge 在 VFS 上运行它们：两者都跳过版本控制元数据目录，`grep` 还跳过隐藏文件、二进制文件和超过 4 MiB 的文件，两者都不应用 `.gitignore`。`grep` 的正则使用 RE2 语法（不支持环视和反向引用），由 re2js 以线性时间匹配，所以病态正则不会卡住 Durable Object。一次搜索最多遍历 20,000 个条目，`grep` 最多收集 20,000 行匹配或 20 MB 文本；超出上限时会失败，并提示缩小路径或模式。ripgrep 15 会拒绝的 glob 语法（未闭合的 `[` 或 `{`、`[z-a]` 这样的反向范围、末尾悬空的 `\`）会作为无效模式报错；`a{b,{c,d}}` 这样的嵌套分组可以使用。搜索在每次列出目录前后检查是否已取消，所以 30 秒的工具超时能中止耗时的遍历。与上游一致，文件观察策略（`dsh-fs-observation-policy`）为它们把关：`write` 不能覆盖本会话尚未读过的文件，`edit` 必须先读过目标文件，读取之后被改动过的文件（例如被 `bash` 或 Linux 容器改动）在重新读取之前会作为过期而失败；会话重启后不保留读取记录。Goal 工具（`ToolGoal`）作为上游 cordis 插件直接与 `GoalService` 组合。子 agent 沿用上游标准组合：`subagent` 启动一个全新的子 agent，`subagent_fork` 启动一个从父 agent 已完成的 turn 开始的子 agent（`dsh-subagent-spawn-in-process`、`dsh-subagent-fork-in-process`）。两者默认都在后台以可续接子 agent 运行，父 agent 用 `send_message` 继续它、用 `interrupt_agent` 停止它当前的 turn、用 `list_agents` 找到它（`dsh-tool-subagent-control`）。父 agent 的 turn 结束后子 agent 仍继续工作，它的结束消息会唤醒父 agent 再跑一个 turn；与上游一致，停止父 agent 不会停止正在运行的子 agent。未在运行的子 agent 收到消息时会从存储恢复，重启后也一样。上游 `todo_write` 工具（`dsh-tool-todo`）维护会话的任务列表，与上游的组合一样允许多个任务同时进行；它的 `todos` projection 驱动 Web 客户端的待办面板。上游 `present` 工具（`dsh-tool-present`）把工作区文件声明为本 turn 的交付物，Web 客户端将其显示为可在侧边栏预览的文件卡片；Edge 没有桌面，所以对卡片的 Host 检查（`/api/present.host`）回答不可用，卡片不提供用本机应用打开。与上游一样，`dsh-agent-instructions` 在第一次请求前，通过工作区 VFS 从项目根目录（最近一个包含 `.git` 的上级目录，没有则为会话工作目录）到工作目录逐级加载 `AGENTS.md` 和 `CLAUDE.md`（以及它们的 `.local.md` 覆盖文件），合成一条不超过 64 KiB 的基线消息；`read`、`write` 或 `edit` 进入更深的目录时，下一次请求会加入该目录的说明。Workers 没有用户主目录，所以用户全局文件是 `/.dsh/AGENTS.md` 和共享 agent 根目录下的 `/.agents/AGENTS.md`（Edge 自己设置 `DSH_HOME` 和 `DSH_AGENTS_HOME`，因为该插件只从这两个变量读取主目录）。`working_directory` 工具（`dsh-tool-working-directory`）读取会话的工作目录，或把它切换到一个已存在的目录；切换是一条持久化的 `working-directory/change` 事件，早于本版本的发布无法读取它，降级后无法打开已写入该事件的会话，Edge 始终把 `/workspace` 视为已存在的目录。Skill 工具通过 `SkillRegistry` 提供。与上游 `dsh-skill-filesystem` 一致，skill 是带 `name` 和 `description` frontmatter 的 `<name>/SKILL.md` 或 `<name>.md` 文件，位于项目的 `.dsh/skills`、`.agents/skills`，以及用户目录 `/.dsh/skills`、`/.agents/skills`（Workers 没有用户主目录），通过工作区 VFS 读取，每个目录最多读取 100 个条目，每个 skill 文件不超过 64 KiB；新增或修改的 skill 从下一个 turn 起生效，变更后打开的会话的 `/` 菜单也会列出它；与上游一致，Web 客户端在页面刷新前保留已打开会话的 `/` 列表。通过 owner 接口 `GET/PUT/DELETE /api/skills` 存储的 skill（`EdgeSkillProvider`，DO KV）优先级低于它们。MCP client（`dsh-mcp-client`）已安装；仅支持 Streamable HTTP transport（Workers 上不可用 stdio）。在 Settings → DSH Edge → MCP Servers 中配置服务器；工具名格式为 `mcp__<serverName>__<tool>`。逐个针对 Worker-compatible capabilities 增加其余工具，不宣称不可用的 host 行为。 |
-| Attachments | 本地 attachment storage、上游 image reference、composer、gallery、lightbox 与 provider conversion | 在原生 storage seam 上适配 | 原样复用上游 `AttachmentStore`、admission、协议、授权、UI 与 DeepSeek conversion。PNG/JPEG 不可变字节按 SHA-256 identity 存入新部署与 pre-attachment 部署使用的 64 MiB、按 512 KiB 分块的 DO backend，或存入已固定使用私有 R2 的部署的 R2；session event 只保留上游 ref。每个 owner instance 首次选择的 backend 会被固定，认领或升级不会让既有引用失联。 |
+| Other tools | Web Search、filesystem editor tools、MCP、skills、workflows、jobs 和 subagents | Search、文件、glob/grep、goal、todo、skill、subagent 和 MCP 工具已移植；workflow 与 run_code 已在 isolated 构建中移植 | 复用上游 DeepSeek Web Search 及其 30 秒 tool-call timeout。网页搜索卡片里的“Use the new Web Search API”开关（默认关闭）会把搜索和抓取切换到 DeepSeek Search and Fetch API（`dsh-web-deepseek-api`）：页面由 DeepSeek 抓取，Worker 自己不读取任何第三方页面，也不产生辅助模型请求。它们使用 Models 页面保存的 DeepSeek API key（key 名称不能是其他 Edge 功能的凭据，设置里不接受明文 key），API 地址必须是不含凭据、查询或片段的 HTTP(S) URL，重定向会被拒绝，也不提供账号登录路径。Search and Fetch API 可能与模型 token 分开计费。上游 `workflow` 工具仅由 Dynamic Worker 运行时提供（isolated、Paid 计划构建）；Direct 构建不注册该工具。由于 workerd 禁止在进程内使用 `eval`/`new Function`/`node:vm`，每次运行都会把脚本加载到独立的 Dynamic Worker 中执行，该 Worker 无出站网络，并受 30 秒 Worker Loader `cpuMs` 上限约束（由 Cloudflare 运行时强制执行，本地开发环境不执行）；`agent()`、`phase()`、`log()` 经 RPC 桥回到 Durable Object，由其执行各项上限：同时最多运行 4 个子 agent（低于 Workers 六连接上限），单次运行最多启动 100 个子 agent，以限制子会话的行写入。上游 `run_code` 工具（`dsh-tools` PTC 模式）由同一运行时提供，但只提供给以上游 `ptc` agent 预设（PTC 模式）开始的会话。isolated 部署沿用上游 id 提供该预设，因此 Web 客户端显示其内置的双语名称。该预设通过生成的 SDK 呈现全部工具，并与上游一样不提供 `workflow`，因为 `run_code` 是它唯一的编排方式。默认使用上游的 `standard` 预设（标准模式；以早先 `dsh-edge` id 记录的会话按 `standard` 读取），以原生方式呈现工具，并保留 `workflow`。与上游一致，Settings → Agent presets 写入 `agent-preset-registry` 设置命名空间的 `selectedDefault`，从可用预设中选择新会话的起始预设；早期版本保存在 `agent-presets` 下的默认值会在启动时迁移过来。在 PTC 模式下，每个程序先用 sucrase 去除类型，再在独立 Dynamic Worker 中运行，受 30 秒 `cpuMs` 上限约束且无出站网络；其中的 `tools.*` 调用经 RPC 桥回到 Durable Object，由其限制为每次运行最多 200 次（每次都是一次写入 session 事件的嵌套工具派发）、参数最多 256 KiB、单次结果最多 2 MiB，嵌套调用仍走审批。文件工具（read/write/edit/read_image）通过 `EdgeFileSystem` 适配 Computer VFS。`glob` 和 `grep` 保持上游 `dsh-tool-fs-search` 的工具名、参数结构、结果文本、搜索卡片，以及超过 100 条路径或 250 条匹配时把完整结果另存为文件；但 Workers 无法启动它所需的 ripgrep 程序，所以 Edge 在 VFS 上运行它们：两者都跳过版本控制元数据目录，`grep` 还跳过隐藏文件、二进制文件和超过 4 MiB 的文件，两者都不应用 `.gitignore`。`grep` 的正则使用 RE2 语法（不支持环视和反向引用），由 re2js 以线性时间匹配，所以病态正则不会卡住 Durable Object。一次搜索最多遍历 20,000 个条目，`grep` 最多收集 20,000 行匹配或 20 MB 文本；超出上限时会失败，并提示缩小路径或模式。ripgrep 15 会拒绝的 glob 语法（未闭合的 `[` 或 `{`、`[z-a]` 这样的反向范围、末尾悬空的 `\`）会作为无效模式报错；`a{b,{c,d}}` 这样的嵌套分组可以使用。搜索在每次列出目录前后检查是否已取消，所以 30 秒的工具超时能中止耗时的遍历。与上游一致，文件观察策略（`dsh-fs-observation-policy`）为它们把关：`write` 不能覆盖本会话尚未读过的文件，`edit` 必须先读过目标文件，读取之后被改动过的文件（例如被 `bash` 或 Linux 容器改动）在重新读取之前会作为过期而失败；会话重启后不保留读取记录。Goal 工具（`ToolGoal`）作为上游 cordis 插件直接与 `GoalService` 组合。子 agent 沿用上游标准组合：`subagent` 启动一个全新的子 agent，`subagent_fork` 启动一个从父 agent 已完成的 turn 开始的子 agent（`dsh-subagent-spawn-in-process`、`dsh-subagent-fork-in-process`）。两者默认都在后台以可续接子 agent 运行，父 agent 用 `send_message` 继续它、用 `interrupt_agent` 停止它当前的 turn、用 `list_agents` 找到它（`dsh-tool-subagent-control`）。父 agent 的 turn 结束后子 agent 仍继续工作，它的结束消息会唤醒父 agent 再跑一个 turn；与上游一致，停止父 agent 不会停止正在运行的子 agent。未在运行的子 agent 收到消息时会从存储恢复，重启后也一样。上游 `todo_write` 工具（`dsh-tool-todo`）维护会话的任务列表，与上游的组合一样允许多个任务同时进行；它的 `todos` projection 驱动 Web 客户端的待办面板。上游 `present` 工具（`dsh-tool-present`）把工作区文件声明为本 turn 的交付物，Web 客户端将其显示为可在侧边栏预览的文件卡片；Edge 没有桌面，所以对卡片的 Host 检查（`/api/present.host`）回答不可用，卡片不提供用本机应用打开。与上游一样，`dsh-agent-instructions` 在第一次请求前，通过工作区 VFS 从项目根目录（最近一个包含 `.git` 的上级目录，没有则为会话工作目录）到工作目录逐级加载 `AGENTS.md` 和 `CLAUDE.md`（以及它们的 `.local.md` 覆盖文件），合成一条不超过 64 KiB 的基线消息；`read`、`write` 或 `edit` 进入更深的目录时，下一次请求会加入该目录的说明。Workers 没有用户主目录，所以用户全局文件是 `/.dsh/AGENTS.md` 和共享 agent 根目录下的 `/.agents/AGENTS.md`（Edge 自己设置 `DSH_HOME` 和 `DSH_AGENTS_HOME`，因为该插件只从这两个变量读取主目录）。`working_directory` 工具（`dsh-tool-working-directory`）读取会话的工作目录，或把它切换到一个已存在的目录；切换是一条持久化的 `working-directory/change` 事件，早于本版本的发布无法读取它，降级后无法打开已写入该事件的会话，Edge 始终把 `/workspace` 视为已存在的目录。Skill 工具通过 `SkillRegistry` 提供。与上游 `dsh-skill-filesystem` 一致，skill 是带 `name` 和 `description` frontmatter 的 `<name>/SKILL.md` 或 `<name>.md` 文件，位于项目的 `.dsh/skills`、`.agents/skills`，以及用户目录 `/.dsh/skills`、`/.agents/skills`（Workers 没有用户主目录），通过工作区 VFS 读取，每个目录最多读取 100 个条目，每个 skill 文件不超过 64 KiB；新增或修改的 skill 从下一个 turn 起生效，变更后打开的会话的 `/` 菜单也会列出它；与上游一致，Web 客户端在页面刷新前保留已打开会话的 `/` 列表。通过 owner 接口 `GET/PUT/DELETE /api/skills` 存储的 skill（`EdgeSkillProvider`，DO KV）优先级低于它们。MCP 使用 Edge 自己的客户端（`edge-mcp-client.ts`；未挂载上游 `dsh-mcp-client`）：仅支持 Streamable HTTP（Workers 上不可用 stdio），每次调用单独建立连接，并且只提供工具，暂不提供 MCP 资源。在 Settings → DSH Edge → MCP Servers 中配置服务器；工具名格式为 `mcp__<serverName>__<tool>`。逐个针对 Worker-compatible capabilities 增加其余工具，不宣称不可用的 host 行为。 |
+| Attachments | 本地 attachment storage、上游 image reference、composer、gallery、lightbox 与 provider conversion | 在原生 storage seam 上适配 | 原样复用上游 `AttachmentStore`、admission、协议、授权、UI 与 DeepSeek conversion。PNG/JPEG 不可变字节按 SHA-256 identity 存入新部署与 pre-attachment 部署使用的 64 MiB、按 512 KiB 分块的 DO backend，或存入已固定使用私有 R2 的部署的 R2；session event 只保留上游 ref。每个 owner instance 首次选择的 backend 会被固定，认领或升级不会让既有引用失联。图片为 PNG 或 JPEG，每张最多 3.5 MiB，每条消息最多 4 张。其他文件经上游上传路由流式写入，按上游 `files/<prefix>/<digest>/<name>` 布局原样保存在工作区 VFS 的 `/.dsh/attachments/v1` 下，每个最多 64 MiB（上传必须声明长度，超限的在写入任何字节前即被拒绝），告知模型的就是这个路径；模型的文件工具与轻量 shell 可在此读取，但路由到 Linux Container 的命令看不到这些文件。 |
 | Goal tracking | `GoalService` 提供 create/edit/pause/resume/complete/clear mutation 与 GoalBar UI | 复用 | 作为 cordis 插件安装上游 `GoalService` 和 `ToolGoal`（直接组合）。浏览器 GoalBar mutation 通过 `TypertGatewayService` 路由到 `/api/goals/<method>`。`SessionProjectionCache` 在 DO 重启后持久化 goal 状态。上游的 `/goal` 命令（`dsh-command-goal`）可以查看、设定、编辑、暂停、恢复或清除会话的目标。每一轮目标都在 Edge 的 turn 内运行，带有工作区、时限和实时事件：上游的轮次驱动排入下一轮期间，turn 保持打开；在 turn 之外启用目标的调用（`/goal`、GoalBar 的恢复）在一个新的 turn 内运行。 |
 | Context compaction | Token 计量、自动压缩和 session 标题生成 | 复用 | 直接安装上游 cordis 插件。上下文压缩、token 计量、工具结果修剪和自动 session 标题生成原样运行。上游的图片卸载（`dsh-compaction-image-offload`）在请求中的图片超出路由预算（默认每个请求 600 张）时让 turn 继续：它用一条 `image/offload` 会话事件把最早的图片标记为已卸载，然后重试请求。 |
 | Session projection | 向已连接客户端实时推送派生状态 | 复用并添加 Edge bridge | 上游 `onChanged` 回调向已连接 WebSocket 客户端推送 title、model、goal 和会话统计 projection frame。上游 `dsh-session-stats`（整个会话的 turn 数和 step 数，以及模型、工具和首 token 耗时）为 Web 聊天视图提供数据。`SessionProjectionCache` 在 DO KV 中缓存 projection，用于冷 session 恢复。 |
@@ -348,7 +348,7 @@ SQLite 的 `DELETE` 操作也会消耗每日行写入额度。迁移格式时，
 - `GET /api/workspace/file?path=/workspace/...` 读取 UTF-8 文件。
 - `DELETE /api/workspace/file?path=/workspace/...` 删除文件。
 - `POST /api/workspace/exec` 接受 `{ "command": "...", "cwd": "/workspace/..." }`，`cwd` 默认为 `/workspace`；每次执行都会收到部署级默认 timeout，`timedOut` 会报告该 deadline 是否已过，输出超过保留边界时，`outputTruncated` 会报告这一状态。
-- `POST /api/sessions` 使用必填 `title` 创建持久 session；API 返回前，标题会写成标准、用户来源的 `session/title` 事件。如果 session 已持久化但 Workspace attachment 失败，500 响应会使用 `workspace-attach-failed` 并携带完整的已创建 `session`，调用方可以恢复其 id，而不会创建重复 session。
+- `POST /api/sessions` 使用必填 `title` 创建持久 session；API 返回前，标题会写成标准、用户来源的 `session/title` 事件。如果 session 已持久化但 Workspace attachment 失败，500 响应会使用 `session/workspace-attach-failed` 并携带完整的已创建 `session`，调用方可以恢复其 id，而不会创建重复 session。
 - `GET /api/sessions?after=...&limit=...` 列出一个有界 summary page；`GET /api/sessions/:sessionId` 读取一个 session。上游 persistence service 没有定义破坏性删除，因此这里不暴露 session deletion。
 - `POST /api/sessions/:sessionId/turn` 接受 `{ "message": "..." }` 并流式返回持久 SSE events。
 - `GET /api/sessions/:sessionId/events?after=...&limit=...` 重放一个有界 event page，并返回 continuation headers。
@@ -356,7 +356,7 @@ SQLite 的 `DELETE` 操作也会消耗每日行写入额度。迁移格式时，
 
 ### Session 与 Workspace 行为
 
-- Session 创建与 fork 在发布成功但 Workspace attachment 失败时返回 `workspace-attach-failed`，并携带已发布的 session 与 Workspace id。诊断路由返回相同 code 及完整的已创建 session。
+- Session 创建与 fork 在发布成功但 Workspace attachment 失败时返回 `session/workspace-attach-failed`，并携带已发布的 session 与 Workspace id。诊断路由返回相同 code 及完整的已创建 session。
 - Prompt 和 queue-edit 文本共用 64 KiB 语义上限。10 MiB RPC 载体为 7 MiB 原始图片在 base64 与 envelope 膨胀后留出空间。
 - Edge 没有目录流 provider，因此上游浏览器会在仅剩一个 Workspace 时隐藏 Delete，并在仍有恢复路径时重新显示。
 - `@file` 补全通过 Computer VFS 为上游 `fileReferences/list` Remote 每次只列出一个目录：裸片段对应会话工作目录，末尾斜杠对应它命名的目录。每次列目录都是一次 Computer 调用，因此没有递归模糊索引。`@session` 提及及其 pre-step 快照原样来自上游 session-reference 服务；它的候选发现以及任一 agent 作用域 Remote 都会通过上游 controller 恢复冷 session，并使其常驻直到 Durable Object 被驱逐。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-edge",
-  "version": "0.27.2",
+  "version": "0.28.0",
   "description": "Your DeepSeek Harness, anywhere — deploy a persistent personal coding agent to Cloudflare Workers in one command",
   "author": "pawaca",
   "license": "MIT",
@@ -75,6 +75,7 @@
     "@deepseek-ai/dsh-attachment": "0.2.1-rc.2",
     "@deepseek-ai/dsh-brand": "0.2.1-rc.2",
     "@deepseek-ai/dsh-client-connection": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-client-file-upload": "0.2.1-rc.2",
     "@deepseek-ai/dsh-client-locale": "0.2.1-rc.2",
     "@deepseek-ai/dsh-client-store": "0.2.1-rc.2",
     "@deepseek-ai/dsh-client-ui-chat": "0.2.1-rc.2",