@deepseek-ai/dsh-client-runtime

@deepseek-ai/dsh-client-runtime

English | 中文

Client cordis boot and React-free object services: SlotRegistry wraps SlotCore and supplies renderer data sources; SessionRuntime owns Session objects, list and scope state, and the shared event window and history paging used by registered conversation view targets. WorkspaceRuntime depends on SessionRuntime and owns Workspace objects, list/actions, default-target derivation, and the New Session blank-reuse entry (connectWorkspace). The runtime fans the shared Host stream into Session and Workspace owners and hands each generic host/remote-event frame to ctx.remote.$dispatch; domain packages subscribe to their owner events through ctx.remote.$on and decide which caches or session rows they invalidate. Client sessions are always Host-born (Session+Agent+cwd in one session.create); the client holds no pre-entity session state — a session's Agent scope (the client mirror of host dsh-scope, keyed by the shared agent/session id) is born when its row enters the list mirror and dies with the prune. Contract: api-contracts v3 §4. Each Session holds a generic ProjectionValueStore seeded from the history-tail projections block and updated by session/projection frames under higher-seq-wins; domain keys (including todos) are read via projections.faceOf / useProjection, not via ConversationSnapshot. The store also publishes one reference-stable whole-value map through SessionSummary.projectionValues, allowing global list consumers to reuse the same projections without creating per-session subscriptions.

For each prompt that can reach a local root or continuable child Agent, the runtime samples the browser's current Intl.DateTimeFormat().resolvedOptions().timeZone and attaches it to that one Session or subagent prompt RPC. It is neither cached nor included in Session creation or fork state, so travel and concurrent tabs keep message-local provenance. A browser that cannot provide a non-empty zone fails the prompt locally instead of silently substituting deployment state.

bindSettingsScope is the browser mirror of the Host-side settings owner seam for one domain-owned namespace. It subscribes before starting a nonblocking initial read, publishes a uSES snapshot (status, section value, the composition base and raw user layers, revision, writability, host/memory mode), serializes set and unset writes with the latest known namespace revision, suppresses stale publications, recovers a rejected latest write from Host state, and reaches quiescence on plugin disposal. The default decoder validates each section against the namespace's own serialized wire schema (rehydrated through dsh-client-schema-form), so a domain adds a decoder only to narrow beyond that schema. Loopback pages use the Host settings API; remote pages stay in memory mode. A field is overridden when it is PRESENT in user — an override equal to the composition default is still an override, which comparing values could not see — and unset is how a form clears one back to base. Domain packages own the namespace schema, default, and live service rather than putting product policy in runtime.

Slot declaration injection

ctx.slots.inject(name, callback) makes a full SlotMap key the dependency for a contribution whose plugin can activate independently from the declaring entry. It runs callback synchronously when the declaration exists, otherwise waits; declaration collapse disposes the callback effect, and redeclaration reruns it. The controller belongs to the caller's plugin fiber, so unloading the contributor cancels either the wait or its active registrations. A direct slots.register() into an undeclared slot still throws.

The callback returns one synchronous disposer or an iterable of disposers. A generator can therefore yield several slots.register() calls as one transaction: setup failure rolls earlier yields back and teardown runs them in reverse order. Declaration lifetimes use a dedicated monotonic epoch, so a collapse and redeclaration batched into one renderer notification still restarts the callback, while ordinary entry changes do not. Declaration-bound teardown runs synchronously with the ledger mutation, releasing runtime resources before subsequent same-tick registrations. See the declaration-injection decision.

Workspace and Session lists

Workspace and Session lists have independent monotone pending → ready baseline phases and separate refresh activity/error state. Incremental upsert/removal/order frames and unary mutation echoes arriving during a list request replay over its response. Every successful Workspace baseline re-establishes Host-durable Workspace order so reconnects adopt changes committed while this client was offline. WorkspaceRuntime.insertBefore installs an optimistic order immediately; only the latest unary echo may replace it, a newer Host order frame outranks an older echo, and a latest rejected request restores the last Host-confirmed order rather than an earlier uncommitted drag. Removed Workspace ids retain process-local tombstones so late changed frames cannot resurrect them. Workspace recency is derived only after both baselines are ready and never changes Workspace list order.

SessionSummary.pendingInteraction classifies the live user action blocking a Session as approval, plan-review, or question. SessionManager tracks answerable requested/resolved mux frames by their stable request identities even before a Session object is instantiated; pre-instantiation buffering retains every live request, replaces replay duplicates, and removes resolved requests so the list status always has a matching answerable PendingWait when the Session is opened. The first pending question takes presentation priority over concurrent approvals to match composer routing, while only a request that satisfies the plan-review composer's binary rendering constraints keeps the distinct plan-review status. The state is connection-generation scoped: disconnect clears it, and mux-open replay restores only requests that remain pending.

WorkspaceRuntime.delete(workspaceId) removes the registration from the client projection after the successful unary response; the matching host/workspace-removed frame is idempotent and synchronizes other tabs. Session state and the current Session selection are independent, so accounted Sessions immediately project under Ungrouped after their Workspace disappears.

WorkspaceListState.archivedSessionIds mirrors the Host's registry-global archive set (a readonly SessionId[] in Host order, replaced only when membership changes; consumers needing O(1) lookups build a transient Set). It is full-snapshot state: the workspace.list baseline, the archiveSession unary echo, and the host/archived-sessions-changed frame each install the complete set. WorkspaceRuntime.archiveSession(sessionId) archives over the wire; the projection sweep clears the current selection into the New Session view state whenever it lands in the archive set — one rule covering the local echo, another tab's frame, and a reconnect baseline restoring a selection archived while this client was away. A set installed while a workspace.list request is in flight also supersedes that stale baseline's set. Grouping surfaces hide members everywhere while the session rows stay in the list store.

SlotRegistry gives the renderer separate bare observables for useSessions and useWorkspaces; web-react creates the hooks. Workspace business state does not enter SessionListState or an entry store.

indexSubagentDescendants() derives per-parent total and running descendant counts from the retained list mirror. It follows only uninterrupted origin: 'subagent' ancestry, so an ordinary fork starts a separate ownership subtree; cycles stop without throwing, and a missing parent remains a harmless key until its summary arrives.

SessionListState.jobsBySession mirrors the Host's session/jobs frames last-wins, keyed by session and needing no Session instance. An emptied set is stored as an absent key, so absence and [] are one representation and consumers never test a sentinel. Two clears keep it from outliving its truth: session/subscribed drops the session's mirror, because a fresh generation sends a baseline only for a non-empty set and a retained list would survive as a phantom, and host/session-removed drops it again, because owner disposal removed the records on the mux stream while the removal frame rides the host stream, leaving the two with no relative order.

SessionRuntime.search(query, signal) is a stateless one-shot action over the session.search RPC. It returns ranked session/snippet pairs without putting query, loading, or error state into the shared Session list, so each UI owner controls debounce, cancellation, stale-response suppression, and fallback presentation. searchResultLimit re-exposes SESSION_SEARCH_RESULT_LIMIT — the bound the response schema itself enforces — as injected presentation data, so client plugins do not duplicate it. It is a protocol constant rather than per-connection state, so the connection handle does not carry it.

New Session and the blank mirror

WorkspaceRuntime.connectWorkspace(workspaceId) resolves the session a New Session flow lands in: it reuses the workspace's existing blank session from the list mirror (blank && cwd == workspace.path && sessionIds.includes(id) — the host's own membership rule, never cwd alone, so a cwd-matching unaccounted blank session is never hijacked) or calls session.create({workspaceId}), returning the session id for the caller to open. The shared startSession action targets an explicit Workspace first, then the current Session's Workspace, then the derived recent Workspace; with no Workspace it clears into the blank New Session page. SessionSummary.blank mirrors the host's derived empty-log bit and only ever lowers on the client: seeded by session.list / the host/session-added frame, flipped false by the first ACCEPTED local prompt() (on the RPC success response — acceptance proves the user message is in the host log; a rejected first prompt keeps the session blank and reusable) and by any running: true status frame, re-aligned by every list re-pull. List surfaces hide blank rows; the store carries every row. SessionRuntime.create accepts an optional caller-preallocated SessionId and throws SessionCreateError (carrying requestedSessionId) on failure.

Session.composerPhase treats any visible non-command Chat Node as conversation content, so a client plugin can project durable human input without opening a turn while a window containing only generic command rows retains the Host blank posture. List hiding and blank-session reuse still follow the Host blank bit. A history window that lacks the plugin-owned input Node returns to that blank posture until an older page restores it.

Pending queue projection

ConversationSnapshot.queue is the Host's authoritative transient snapshot of agent.inbox.nextTurn; pending next-step steering stays outside this projection. Each row carries its MessageId, complete editable text when every content block is text, and a flattened preview. The Host derives whole session/queue snapshots from durable agent/inbox/spliced mutations and sends a baseline on reconnect; the message-local agent/inbox/inserted, claimed, and discarded notifications are not used to reconstruct this projection. Session.updateQueue() sends edit/remove operations through Host-side Inbox.splice() without optimistic client mutation, so the next Host snapshot is the sole visible commit and a claim race can surface queue-item-not-found.

Conversation assembly

Each Session gives its contiguous event window to a ConversationNodeAssembler. Plugins register business Definitions that map one event to a stable {kind, id}, create State at the unique start event, fold correlated updates, and build final nodes for registered view targets. The assembler owns the Context index, read-only predecessor lookup, and a reference-stable Turn/Step Location index. A live append evaluates each Definition once and updates only the matched Context; loading an older page preserves existing Context and node identities, matches only the newly prepended events, and replays Contexts whose predecessor or Location facts changed. Full replacement is reserved for open, resync, and gap repair.

Definition authors keep matching local to the current event, give every correlated event a stable business id, and make updates replayable by log seq; renderers consume final Node data and constrained Location values rather than scanning Session or Chat collections. The Conversation Node cookbook gives the complete registration and pagination path.

ui-conversation registers the built-in Chat Definitions and the keyed Chat snapshot builder. Append-origin user, assistant, and Tool results remain the human record; model-only replacement copies stay out, except that a compaction checkpoint becomes its own marker and resolves missing summary provenance when an older page supplies it. Durable inbox splice Contexts classify next-step user messages as steering without making inbox state a Session special case. Context messages retain producer provenance and form. StatsLine reads ConversationSnapshot.chat.legacy.nodes, while Session mirrors that legacy slice into the top-level nodes, partial, and runningCalls public compatibility fields without running a second business fold. ui-trajectory registers independent Definitions and a target builder over the same Session window; it preserves the existing stage-oriented view model without consuming the Chat compatibility fields or running another history fold.

The Chat builder keeps one mutable keyed store per Session. Content updates notify only the affected node key, structural changes rebuild order and Location membership, and a prepend adds rows without replacing existing keyed values. Assistant chunks update Definition State for every event but request at most one materialization per animation frame; final messages and Turn/Step closure publish immediately. See the client Tool presentation decision.

Trajectory request data

Trajectory Definitions assemble one chronological, purpose-discriminated provider-request stream. Assistant requests always carry their numeric turn and step; compaction requests carry step: 0 and a turn owner that may be null. That null owner means a manual compaction ran standalone between turns, not that it belongs to either adjacent turn. A session/end-seed boundary closes an unmatched compaction request as an error at the boundary time with Compaction was interrupted before completion.; a later start projects as an independent request instead of overwriting the orphan.

Code Mode child-call tree

Every ToolCallBlock recursively owns its children through subCalls, in start order. Chat's Tool Definition correlates root calls and results by call id, folds Code Dispatch start/settlement records into that root Context, and projects one keyed recursive tree; child calls never become independent Chat roots. When a start falls outside the loaded window, its settlement remains renderable with callTime: null. A child update copies only its ancestor path, so unchanged siblings retain object identity. Edges that introduce a cycle or exceed the fixed 256-call depth limit are consumed without mutating the tree. Trajectory's Tool Definition independently assembles the same nested data contract for its target.

Session title projection

`SessionManage