dsh-synapse 0.4.0 → 0.4.1

package/docs/architecture.md

@@ -1,104 +1,104 @@
-# Architecture and runtime boundaries
-
-## Purpose
-
-`dsh-synapse` is a presentation and organization layer for DeepSeek Harness conversations. It turns existing DSH sessions, turns, and forks into a visual map without replacing the systems that own those conversations.
-
-## Web profile integration
-
-The package contributes `cordis.patch.yml`, which inserts the `dsh-synapse` service into the DSH `web` profile. It reuses the existing DSH Web server and client runtime.
-
-The plugin:
-
-- does not start a second HTTP server;
-- does not create a second model or agent runtime;
-- does not replace DSH authentication or permission checks;
-- does not support non-Web profiles unless those profiles explicitly add the plugin.
-
-## Conversation ownership
-
-DSH session logs remain the source of truth for conversation content and lifecycle. Native DSH operations own:
-
-- creating and opening sessions;
-- sending follow-up messages;
-- forking sessions;
-- archiving sessions;
-- model and tool execution;
-- permission and approval decisions.
-
-Synapse projects committed DSH events into cards and sends user actions back through the native DSH session bridge.
-
-## Canvas metadata
-
-By default, Synapse stores canvas metadata at:
-
-```text
-$DSH_HOME/synapse/workspaces.json
-```
-
-The file contains organizational state such as workspace mapping, card layout, and fork anchors. It does not replace session logs.
-
-Consequences:
-
-- deleting the file resets canvas organization but does not delete conversations;
-- uninstalling the plugin keeps the file, so reinstalling restores the canvas;
-- older schema versions migrate when loaded;
-- two processes sharing the same file can still produce last-writer-wins replacement despite locking and external-change warnings.
-
-Run one `dsh web` instance for each shared profile.
-
-## Projection model
-
-With `autoProjection` enabled, committed DSH session events are grouped by working directory and projected into the corresponding Synapse workspace.
-
-Each user question becomes a conversation card. The following assistant messages are folded into that turn, and the final assistant reply is shown as the answer. Forked sessions connect to the parent turn at the durable DSH seed boundary rather than at an arbitrary canvas coordinate.
-
-Projected card text is capped at 8000 characters. Longer messages receive a truncation marker in the card, while their complete content remains available from the conversation detail view.
-
-Projection writes are coalesced during event bursts, and live updates reuse cached Markdown and patch the active card instead of rebuilding the complete canvas. Card coordinates remain visual metadata only and never determine conversation lineage.
-
-## Tool process folding
-
-Live events pair tool calls and results by `callId` and render them inside the related assistant reply instead of as standalone conversation cards.
-
-Legacy v3 migrations did not always have durable call IDs. Those records pair each tool call with the next tool result by order during migration.
-
-## Browser-local state
-
-Some interaction state, such as dragged card positions and branch anchors, may be cached in browser local storage to keep the canvas responsive. Durable workspace metadata is still written through the Synapse service.
-
-Private-browsing restrictions or local-storage failures must not prevent DSH conversations from operating; they only reduce persistence of visual preferences.
-
-## Host validation
-
-The `/synapse` endpoint always accepts `localhost` and `127.0.0.1`. Additional LAN or proxy authorities must be listed in `trustedHosts` as a host or `host:port` value.
-
-This validation is part of the Web surface and does not replace broader network access controls.
-
-## Model and KV-cache impact
-
-Synapse reads session events only after DSH commits them. It does not add or modify:
-
-- system prompts;
-- user request content;
-- model request headers;
-- tool schemas or registries;
-- provider routing;
-- approval context.
-
-As a result, the plugin has no direct model-experience effect and does not invalidate an otherwise reusable KV-cache prefix.
-
-## Operational limitations
-
-- Only the `web` profile is supported by the bundled patch.
-- Canvas metadata and session content have different owners and backup requirements.
-- A single shared metadata file is not a multi-writer database.
-- Browser state can be cleared independently from DSH Home data.
-- Historical migrations may have less precise tool-call pairing than live projection.
-
-## Related documentation
-
-- [Chinese user guide](zh-CN/README.md)
-- [English user guide](en/README.md)
-- [Development and release guide](development.md)
-- [Project overview](../README.md)
+# Architecture and runtime boundaries
+
+## Purpose
+
+`dsh-synapse` is a presentation and organization layer for DeepSeek Harness conversations. It turns existing DSH sessions, turns, and forks into a visual map without replacing the systems that own those conversations.
+
+## Web profile integration
+
+The package contributes `cordis.patch.yml`, which inserts the `dsh-synapse` service into the DSH `web` profile. It reuses the existing DSH Web server and client runtime.
+
+The plugin:
+
+- does not start a second HTTP server;
+- does not create a second model or agent runtime;
+- does not replace DSH authentication or permission checks;
+- does not support non-Web profiles unless those profiles explicitly add the plugin.
+
+## Conversation ownership
+
+DSH session logs remain the source of truth for conversation content and lifecycle. Native DSH operations own:
+
+- creating and opening sessions;
+- sending follow-up messages;
+- forking sessions;
+- archiving sessions;
+- model and tool execution;
+- permission and approval decisions.
+
+Synapse projects committed DSH events into cards and sends user actions back through the native DSH session bridge.
+
+## Canvas metadata
+
+By default, Synapse stores canvas metadata at:
+
+```text
+$DSH_HOME/synapse/workspaces.json
+```
+
+The file contains organizational state such as workspace mapping, card layout, and fork anchors. It does not replace session logs.
+
+Consequences:
+
+- deleting the file resets canvas organization but does not delete conversations;
+- uninstalling the plugin keeps the file, so reinstalling restores the canvas;
+- older schema versions migrate when loaded;
+- two processes sharing the same file can still produce last-writer-wins replacement despite locking and external-change warnings.
+
+Run one `dsh web` instance for each shared profile.
+
+## Projection model
+
+With `autoProjection` enabled, committed DSH session events are grouped by working directory and projected into the corresponding Synapse workspace.
+
+Each user question becomes a conversation card. The following assistant messages are folded into that turn, and the final assistant reply is shown as the answer. Forked sessions connect to the parent turn at the durable DSH seed boundary rather than at an arbitrary canvas coordinate.
+
+Projected card text is capped at 8000 characters. Longer messages receive a truncation marker in the card, while their complete content remains available from the conversation detail view.
+
+Projection writes are coalesced during event bursts, and live updates reuse cached Markdown and patch the active card instead of rebuilding the complete canvas. Card coordinates remain visual metadata only and never determine conversation lineage.
+
+## Tool process folding
+
+Live events pair tool calls and results by `callId` and render them inside the related assistant reply instead of as standalone conversation cards.
+
+Legacy v3 migrations did not always have durable call IDs. Those records pair each tool call with the next tool result by order during migration.
+
+## Browser-local state
+
+Some interaction state, such as dragged card positions and branch anchors, may be cached in browser local storage to keep the canvas responsive. Durable workspace metadata is still written through the Synapse service.
+
+Private-browsing restrictions or local-storage failures must not prevent DSH conversations from operating; they only reduce persistence of visual preferences.
+
+## Host validation
+
+The `/synapse` endpoint always accepts `localhost` and `127.0.0.1`. Additional LAN or proxy authorities must be listed in `trustedHosts` as a host or `host:port` value.
+
+This validation is part of the Web surface and does not replace broader network access controls.
+
+## Model and KV-cache impact
+
+Synapse reads session events only after DSH commits them. It does not add or modify:
+
+- system prompts;
+- user request content;
+- model request headers;
+- tool schemas or registries;
+- provider routing;
+- approval context.
+
+As a result, the plugin has no direct model-experience effect and does not invalidate an otherwise reusable KV-cache prefix.
+
+## Operational limitations
+
+- Only the `web` profile is supported by the bundled patch.
+- Canvas metadata and session content have different owners and backup requirements.
+- A single shared metadata file is not a multi-writer database.
+- Browser state can be cleared independently from DSH Home data.
+- Historical migrations may have less precise tool-call pairing than live projection.
+
+## Related documentation
+
+- [Chinese user guide](zh-CN/README.md)
+- [English user guide](en/README.md)
+- [Development and release guide](development.md)
+- [Project overview](../README.md)

package/docs/development.md

@@ -1,137 +1,137 @@
-# Development and release guide
-
-This document covers local validation, package inspection, GitHub Actions, and npm release automation for maintainers.
-
-## Requirements
-
-- Node.js `>= 22.19.0`
-- pnpm through Corepack
-- A checkout of this repository
-
-## Local workflow
-
-Install with the lockfile:
-
-```powershell
-corepack pnpm install --frozen-lockfile
-```
-
-Validate JavaScript syntax:
-
-```powershell
-corepack pnpm run build
-```
-
-Run the full test suite:
-
-```powershell
-corepack pnpm test
-```
-
-Inspect the package archive:
-
-```powershell
-corepack pnpm pack
-npm pack --dry-run --json
-```
-
-The package has no generated build output. `build` runs `node --check` over `index.js`, `client.js`, and `app.js`.
-
-## GitHub Actions
-
-Three workflows live under `.github/workflows/`.
-
-### Pull request tests
-
-`pr-tests.yml` runs for pull requests targeting `main` when they are opened, reopened, updated, or marked ready for review.
-
-The workflow:
-
-1. Checks out the pull request revision.
-2. Installs pnpm 10 and Node.js 22.19.0.
-3. Runs `pnpm install --frozen-lockfile`.
-4. Runs `pnpm run build`.
-5. Runs `pnpm test`.
-
-A per-PR concurrency group cancels obsolete runs after a newer commit arrives.
-
-### Main branch tests
-
-`main-tests.yml` runs for every push to `main`, including direct commits and merged pull requests. It executes the same frozen installation, build validation, and full test suite.
-
-### npm publishing
-
-`npm-publish.yml` runs for pushed tags matching the broad GitHub pattern `v*.*.*`. The job then validates the tag strictly before publishing.
-
-Accepted forms include:
-
-```text
-v0.4.0
-v0.4.0-rc1
-v0.4.0-rc.2
-```
-
-The tag without the leading `v` must exactly equal `package.json.version`. A mismatch fails before installation or publication.
-
-| Version | Git tag | npm dist-tag |
-|---|---|---|
-| `0.4.0-rc1` | `v0.4.0-rc1` | `next` |
-| `0.4.0` | `v0.4.0` | `latest` |
-
-Every release tag reruns installation, build validation, and the complete test suite before calling `pnpm publish`.
-
-## Configure npm authentication
-
-Create a GitHub Actions repository secret named `NPM_TOKEN` in the repository where the tag workflow will run:
-
-```powershell
-gh secret set NPM_TOKEN --repo OWNER/dsh-synapse
-```
-
-The token's npm account must have permission to create or publish the public, unscoped `dsh-synapse` package. The workflow passes the secret to the publish step as `NODE_AUTH_TOKEN`; pull request and ordinary test workflows never receive it.
-
-## Release checklist
-
-1. Confirm the full test suite passes on `main`.
-2. Update `package.json.version` to the intended release version.
-3. Commit and merge the version change.
-4. Create a matching tag on that commit.
-5. Push the tag.
-6. Confirm the **Publish to npm** workflow passes.
-7. Verify the npm dist-tag:
-   - prerelease versions use `next`
-   - stable versions use `latest`
-
-Example stable release:
-
-```powershell
-# package.json already contains 0.4.0
-git tag v0.4.0
-git push origin v0.4.0
-```
-
-Example prerelease:
-
-```powershell
-# package.json already contains 0.4.0-rc1
-git tag v0.4.0-rc1
-git push origin v0.4.0-rc1
-```
-
-## Publication failure conditions
-
-The publish job stops without publishing when:
-
-- the tag is not a supported version form;
-- the tag and `package.json.version` differ;
-- frozen installation fails;
-- syntax validation or tests fail;
-- `NPM_TOKEN` is missing, expired, or lacks package permissions;
-- npm rejects the package name or an already-published version.
-
-## Documentation
-
-- [Chinese user guide](zh-CN/README.md)
-- [English user guide](en/README.md)
-- [Architecture and runtime boundaries](architecture.md)
-- [Project overview](../README.md)
+# Development and release guide
+
+This document covers local validation, package inspection, GitHub Actions, and npm release automation for maintainers.
+
+## Requirements
+
+- Node.js `>= 22.19.0`
+- pnpm through Corepack
+- A checkout of this repository
+
+## Local workflow
+
+Install with the lockfile:
+
+```powershell
+corepack pnpm install --frozen-lockfile
+```
+
+Validate JavaScript syntax:
+
+```powershell
+corepack pnpm run build
+```
+
+Run the full test suite:
+
+```powershell
+corepack pnpm test
+```
+
+Inspect the package archive:
+
+```powershell
+corepack pnpm pack
+npm pack --dry-run --json
+```
+
+The package has no generated build output. `build` runs `node --check` over `index.js`, `client.js`, and `app.js`.
+
+## GitHub Actions
+
+Three workflows live under `.github/workflows/`.
+
+### Pull request tests
+
+`pr-tests.yml` runs for pull requests targeting `main` when they are opened, reopened, updated, or marked ready for review.
+
+The workflow:
+
+1. Checks out the pull request revision.
+2. Installs pnpm 10 and Node.js 22.19.0.
+3. Runs `pnpm install --frozen-lockfile`.
+4. Runs `pnpm run build`.
+5. Runs `pnpm test`.
+
+A per-PR concurrency group cancels obsolete runs after a newer commit arrives.
+
+### Main branch tests
+
+`main-tests.yml` runs for every push to `main`, including direct commits and merged pull requests. It executes the same frozen installation, build validation, and full test suite.
+
+### npm publishing
+
+`npm-publish.yml` runs for pushed tags matching the broad GitHub pattern `v*.*.*`. The job then validates the tag strictly before publishing.
+
+Accepted forms include:
+
+```text
+v0.4.0
+v0.4.0-rc1
+v0.4.0-rc.2
+```
+
+The tag without the leading `v` must exactly equal `package.json.version`. A mismatch fails before installation or publication.
+
+| Version | Git tag | npm dist-tag |
+|---|---|---|
+| `0.4.0-rc1` | `v0.4.0-rc1` | `next` |
+| `0.4.0` | `v0.4.0` | `latest` |
+
+Every release tag reruns installation, build validation, and the complete test suite before calling `pnpm publish`.
+
+## Configure npm authentication
+
+Create a GitHub Actions repository secret named `NPM_TOKEN` in the repository where the tag workflow will run:
+
+```powershell
+gh secret set NPM_TOKEN --repo OWNER/dsh-synapse
+```
+
+The token's npm account must have permission to create or publish the public, unscoped `dsh-synapse` package. The workflow passes the secret to the publish step as `NODE_AUTH_TOKEN`; pull request and ordinary test workflows never receive it.
+
+## Release checklist
+
+1. Confirm the full test suite passes on `main`.
+2. Update `package.json.version` to the intended release version.
+3. Commit and merge the version change.
+4. Create a matching tag on that commit.
+5. Push the tag.
+6. Confirm the **Publish to npm** workflow passes.
+7. Verify the npm dist-tag:
+   - prerelease versions use `next`
+   - stable versions use `latest`
+
+Example stable release:
+
+```powershell
+# package.json already contains 0.4.0
+git tag v0.4.0
+git push origin v0.4.0
+```
+
+Example prerelease:
+
+```powershell
+# package.json already contains 0.4.0-rc1
+git tag v0.4.0-rc1
+git push origin v0.4.0-rc1
+```
+
+## Publication failure conditions
+
+The publish job stops without publishing when:
+
+- the tag is not a supported version form;
+- the tag and `package.json.version` differ;
+- frozen installation fails;
+- syntax validation or tests fail;
+- `NPM_TOKEN` is missing, expired, or lacks package permissions;
+- npm rejects the package name or an already-published version.
+
+## Documentation
+
+- [Chinese user guide](zh-CN/README.md)
+- [English user guide](en/README.md)
+- [Architecture and runtime boundaries](architecture.md)
+- [Project overview](../README.md)