DSH contracts
The core package supports DSH >=0.2.0-rc.2 <0.3.0. Most integration uses public Cordis services and slots. One deliberate exception is child composition for per-agent scoped tools; it is guarded by contract tests and must be reviewed during every DSH upgrade.
Chat and workspace lifecycle
All roleplay chats share one DSH workspace rooted at the roleplay data directory. A chat id is derived as session-<roleplay-session-uuid>; the roleplay database remains the source of truth. Opening a missing chat recreates it. Archiving or deleting a roleplay session stops and hides its DSH chat before touching the session directory.
The opening message is persisted as a complete first turn before the live agent is created. Its stored header must contain the workspace's canonical path and the roleplay preset. Appending an opening to an already constructed live loop causes turn-number conflicts and is not supported.
The browser resolves uiWorkspace when an action is used. Do not add it to the client injection list merely to open a chat; doing so prevents the roleplay panel from rendering in profiles where that service is not present at initial composition.
Services and ownership
Use sessionController for create/adopt/rename, workspaceRegistry for the roleplay workspace and archive operations, sessionPersistence for stored opening events, agent/subagent services for model execution, tool registries for validated calls, and the user-approval service for authoring mutations. Resolve optional services lazily through the context.
Every listener, HTTP route, timer, client slot, and service must be registered on ctx; use ctx.effect when an API returns a manual disposer. A reload must leave no duplicate route, tool, timer, or listener.
runChild uses DSH composition helpers to attach a child to its parent while giving the child a private tool scope. Preset tools are filtered out; tools registered on the child remain available. If DSH changes these helpers, port this layer rather than weakening character isolation or exposing tools globally.
Rendering and approval
The roleplay renderer recognises the <roleplay-output> protocol emitted through the narrate tool result. Protocol markers, JSON fields, and stored event ordering are compatibility surfaces. User-facing prose may be localised; protocol vocabulary may not.
World-authoring edits use DSH approval. Approval applies to the proposed mutation, not to a broad session capability. A rejected call must leave files unchanged and the conversation able to continue with a revised proposal.
Upgrade audit
Before widening the DSH version range, verify package exports and composition helpers, opening-message adoption, session naming, workspace association, archive/stop behaviour, user approval and follow-up, client slots, rendering, compaction, cancellation, and hot reload. Run the DSH contract test against the installed target version and perform a live start → play → rewind → branch → reopen cycle.
The DSH API contract lists each concrete host and browser API, its owner in this repository, and the version-sensitive composition boundary.