@lamplitisles/dsh-companion

Readme

# dsh-companion

`@lamplitisles/dsh-companion` is a small, one-to-one Svelte surface for DeepSeek Harness (DSH). It keeps DSH's durable Workspace/Session contracts and adds a calm chat presentation at `/companion/`.

The package is published from the `LamplitIsles/dsh-companion` repository as a
public npm package. Its optional voice integration is provided by the separately
installed [Kepos Speech](https://github.com/LamplitIsles/kepos-speech) plugin.

## Install and build

This repository uses Bun:

```sh
bun install
bun run typecheck
bun run test
bun run build
```

The publishable package contains the Host bundle, the browser bundle, the Cordis patch, declarations, and this README. To install a local build into a disposable or real DSH profile, pack it and use DSH's plugin manager:

```sh
bun run build
npm pack --pack-destination .
dsh plugin --profile web add ./lamplitisles-dsh-companion-0.1.0.tgz
```

The package is pinned to the published DSH `0.1.2-rc.1` contract family (Cordis `4.0.2`). It is intentionally not a compatibility layer for other DSH releases. Session-derived behavior reads the rc.1 snapshot API; older eager event-array contracts are not supported.

## Two surfaces

- `/` remains the stock DSH Web UI, including advanced navigation, ordinary Tool views, Kepos ImageGen's React view, and plugin settings.
- `/companion/` selects the lower-priority Companion root. It shows one configured Workspace and one remembered/recent Session, human and assistant chat, allowlisted ImageGen images, and finalized Kepos Speech voice messages. A small **高级 DSH** link returns to `/` with a full-page navigation so the two compositions do not leak into one another.

Typing `/compact` as the complete Companion input invokes DSH's Session command channel and keeps the continuity checkpoint invisible; other slash-prefixed text remains an ordinary message.

Messages sent during a reply use DSH's durable FIFO queue and remain separate turns. With an empty draft, the composer action stops the current reply without clearing queued messages; DSH resumes those messages in order after cancellation settles.

The ordinary-send optimistic echo, request/RPC identity model, Session-to-Chat handoff, failure restoration, image ownership, and regression strategy are documented in [Optimistic message sending and visual continuity](docs/optimistic-message-sending.md).

DSH continues to stream and persist model output internally, while Companion shows assistant text only after its message is finalized. The typing bubble gains a slowly rotating, non-repeating companion note after a 12-second wait; stopping or completing the reply clears that transient timer state.

While ImageGen is running, its image skeleton and “正在画一张图…” status replace the generic typing bubble. If the agent resumes text generation after the image settles, the typing indicator returns with a fresh long-wait timer.

The Companion deliberately does not include a Workspace picker, session list/new-chat flow, model or preset controls, permissions/approvals, reasoning, Trajectory, generic Tool cards, prompt-injection inspection, generic file upload, notifications, or multi-contact UI. It supports image messages through DSH's Session attachment contract and one short voice-input control in the composer.

## Configuration and recovery

Open the native DSH plugin settings page on `/` and configure:

- one stable Workspace id;
- Companion and user display names;
- an optional bounded local avatar for each identity (PNG/JPEG/WebP/GIF, at most 5 MB, decoded dimensions at most 4096 px);
- the user's preferred form of address; and
- the default affinity for a new or explicitly reset relationship (integer 0–100).

The configured Workspace is resolved by id and the live Session cwd. A missing id, stale Session, failed open, send rejection, or lost connection is shown as a recovery state; the Companion never silently selects another Workspace. The settings card keeps staged edits after a rejected/conflicted write and provides native Discard/Save actions. Editing the default affinity does not rewrite an established relationship.

Mood, affinity, and signature are Host-owned state stored as append-only records under the configured Workspace at `.dsh/dsh-companion/state.jsonl`. Each successful change adds one timestamped complete state; the newest record drives the UI and Agent context, while earlier notes and per-field reasons remain available as relationship history. Session logs are not the runtime state authority. Tests use only test-owned state and never mutate a live Workspace. The Host validates and bounds every load and mutation. The Companion exposes only a read-only relationship RPC to the browser; the agent's `companion_update_relationship` Tool atomically changes mood, affinity, or both, while `companion_set_signature` independently changes its durable signature. `companion_read_history` deliberately validates the full bounded JSONL and returns 1–20 recent records newest first without mutation; history is never injected automatically into every turn. All three Tools remain hidden from the chat timeline. Cross-field and numeric bounds are enforced by Host TypeScript rather than advanced provider-facing JSON Schema. Affinity movement is clamped to ±10 net per accepted turn, and the dynamic prompt context is bounded descriptive metadata—not instructions, permissions, or a score to maximize.

For Sessions in that configured Workspace only, the package replaces DSH basic compaction's final instruction with its fixed companion continuity checkpoint. Other Sessions and LLM calls are unchanged. A request that is otherwise eligible but no longer has DSH basic compaction's expected final message fails visibly, rather than applying the companion prompt to an unknown backend; the runtime instruction is the single source of truth for its wording.

The execution posture is fixed to `workspace-write` with escalation disabled. Operations requiring broader authority fail; no approval or permission picker is presented.

## Media dependencies

Images use the selected DSH Session attachment contract. Only assistant structured image blocks and successful/running/failed `kepos_image_generate` results are projected; unrelated Tool output is hidden. Object URLs are page-owned and revoked when replaced or unloaded. The stock `/` ImageGen renderer remains untouched.

Voice rows recognize exactly one finalized `[[tts:text]]...[[/tts:text]]` passage (fenced code and malformed/multiple passages are ignored; normalized text is limited to 240 Unicode code points). Synthesis calls the already-installed Kepos Speech `synthesize` RPC on `/kepos-speech` with the live Session id. The returned audio URL must remain on the same-origin `/kepos-speech/audio/` route. A page-local cache shares preparation by Session and normalized text, requires user activation for playback, and always leaves a transcript fallback. Install Kepos Speech alongside Companion when voice output or input is needed.

The composer microphone sits immediately left of the context-capacity circle. Click **开始录音** to request microphone access and click **结束录音** to stop; the browser stops automatically at five minutes or before the provider's complete `data:<mediaType>;base64,...` payload reaches its 10 MiB bound. The exact raw-byte ceiling depends on the normalized emitted media type (its prefix is part of that bound). Voice input requires a secure browser context, `MediaRecorder`, the installed Kepos Speech plugin's optional `keposSpeech.transcribe` Host capability, and its shared DashScope credential (`KEPOS_SPEECH_DASHSCOPE_API_KEY`). The recording is held only long enough to send its Base64 bytes through Companion's authenticated Host RPC, is transcribed, and is then discarded: Companion writes no `localStorage` entry, workspace file, audio cache, player, attachment, or provider credential. A successful transcript is submitted as one ordinary Session text turn prefixed with `🎙️ `; when Kepos Speech supplies a recognized expression label, only its raw bracketed form (for example `[sad]`) is appended. Missing or unknown labels are omitted. The marker and bracketed label are model-readable voice metadata, not transcript content or a claim about the speaker's inner state. Typed sending remains available while **正在转写语音…** is shown, and a failed or empty attempt creates no turn.

## Themes and device target

DSH's effective appearance is the only theme authority: light maps to the authored **Sticker Messenger** palette and dark maps to **Night Voyage**. The root updates in place on `theme/change`; it does not write a second preference or remount the timeline. Tailwind Preflight is omitted, utilities/components are prefixed, and Companion selectors are rooted at `#dsh-companion`, leaving `/` untouched.

The committed fixture and Playwright project cover desktop and Pixel 7a-sized Chromium geometry (412×915 CSS px, DPR 2.625, mobile UA/touch), including reduced-height composer behavior, IME/newline handling, scroll anchoring, overlays/Back, media states, both themes, and reduced motion. This is a **Pixel 7a-sized Chromium behavior** claim, not exhaustive physical-device certification.

## Verification

The local acceptance commands are:

```sh
bun run typecheck
bun run test
bunx playwright test --config=playwright.config.ts --workers=1
bun run pack:check
DSH_CLI=/absolute/path/to/dsh bun run test:dsh-link
```

`pack:check` builds and inspects the publishable tarball. `test:dsh-link` uses the explicitly supplied rc.1 CLI to add this source tree through `file:` in a test-owned `DSH_HOME`, then verifies the composed bundle and client registration. It does not start DSH Web, a browser, or touch a live profile. Update the host-local linked web profile with `just deploy-local`; packaged or Kosmos deployment and production cutover remain outside local acceptance.

## Publishing releases

Releases are tag-gated by `.github/workflows/release.yml`. The workflow runs on
`v<semver>` tags only and checks that the tag exactly matches the package
version before it creates the publishable tarball. Stable tags such as
`v0.1.0` use npm's `latest` channel; prereleases such as `v0.1.0-beta.1` use
`beta`.

Tags use strict SemVer prerelease identifiers: every purely numeric segment is
`0` or has no leading zero (`v1.2.3-0` is valid, while `v1.2.3-01` and
`v1.2.3-alpha.01` are invalid). Mixed identifiers containing letters, such as
`v1.2.3-alpha01`, remain valid, as does build metadata such as
`v1.2.3+build.1`.

### First-time bootstrap and Trusted Publishing

Bootstrap the package with a prerelease version that has never been published.
For the first release, set `package.json` to `0.1.0-beta.0`, run the local
checks, and then publish that exact prerelease once with the maintainer's local
npm authentication:

```sh
bun install --frozen-lockfile
bun run typecheck
bun run test
bun run build
bun run pack:check
GITHUB_REF_NAME=v0.1.0-beta.0 bun run release:check
npm publish --access public --tag beta
```

This bootstrap prerelease is deliberately distinct from the first stable
`0.1.0`; never manually publish or reuse `0.1.0` for bootstrap. Each npm
version must be new and unpublished before a release.

After the bootstrap succeeds, configure Trusted Publishing for the exact
`@lamplitisles/dsh-companion` package in npm: add the `LamplitIsles` GitHub
owner, repository `dsh-companion`, workflow
`.github/workflows/release.yml`, and environment `npm` as the trusted
publisher. Create a protected GitHub environment named `npm` with the
maintainers or deployment rules required for release approval.

### First stable OIDC release

Push the intended release commit. The supported tag command is
`og tag [<version> | --bump <major|minor|patch>]` (see `og tag --help`); it
creates and pushes the tag. CI synchronizes its disposable release manifest
from that tag before checks and publication. Create the first stable tag with:

```sh
og tag v0.1.0
```

The verification job must finish before the protected publish job can publish.
For each subsequent release, choose an unpublished tag version, push the
intended change, and create its tag with the same supported operation (for
example, `og tag v0.2.0-beta.1`). Stable tags use npm's `latest` channel; tags
containing a prerelease identifier use `beta`.

Trusted Publishing is the only automated release authentication path. Do not
add `NPM_TOKEN`, `NODE_AUTH_TOKEN`, or a provider credential to the workflow;
the protected publish job receives an OIDC identity and records npm
provenance for the verified tarball. The one-time bootstrap publication uses
the maintainer's local npm authentication only.