README.md 4.7 KB
description: "Host and Client session control: create, resume, prompt, follow history, and project live session state."
kind: "package-reference"
Session Controller
English | 中文
Summary
@deepseek-ai/dsh-api-session-controller owns the Host ctx.sessionController service and the generated Client ctx.remote.session namespace. It serves Session list, search, creation, model selection, rename, fork, prompt, attachment, queue, cancellation, message-aligned history, live log following, and Host-wide control state. Use it through API Gateway when a Client needs these Session operations.
Table of Contents
Use this package
History pages and follow opening snapshots carry a discriminated SessionHistoryRecord. Both variants use { type, event }: type: 'event' carries one raw SessionWireEvent, while type: 'chunks' carries one lossless ChunkRowEvent for consecutive same-block assistant/chunk deltas. Both inner values expose type, seq, time, and data, so the Client retains each accepted record as one SessionEventLikeEntry without record-by-record conversion. A packed event's seq and time identify its first member, and data retains the fragment and timestamp-gap arrays. Live follow frames remain individual event records. Tool arguments, result content, failures, and tool/result.data.meta pass through unchanged; the controller does not resolve a Tool definition, run a presenter, or attach UI data.
Each endpoint states its activation policy. List, search, attachment, history pages, and log following can inspect persistence without activating an Agent; cancellation requires the corresponding live Agent; queue mutation, model, rename, and prompt commands may explicitly resume an ordinary Session. Create and fork are the only operations that create a new Agent. The service applies one preset-aware resume policy and subagent ownership fence to its own methods and to the Typert Agent and Session lookups used by other Remote namespaces.
session.updateQueue resolves the ordinary Session's Agent before locating the addressed MessageId, so an edit or removal can mutate a pending row reconstructed from the durable Inbox projection after a Host restart. A missing durable Session, including a Host without persistence, maps to queue-item-not-found; other resume failures retain their typed error, and subagent-owned identities remain fenced. Successful mutations append the standard agent/inbox/spliced event through the Agent's Inbox.
The Client adapter exposes SessionEventStream, a Gateway RemoteJournalStream bound to one ordinary or direct-subagent address. It opens follow before the initial page, publishes only contiguous replace, prepend, and append changes, and repairs reconnect or sequence gaps through a tail page. Ordinary records cover [event.seq, event.seq]; packed rows cover [event.seq, event.seq + memberCount - 1]. A business, persistence, or unresolved continuity failure terminates the stream, while only physical carrier loss selects automatic resumption. SessionControlStream is a Gateway RemoteSnapshotStream; every generation opens with a complete process-local baseline, so reconnect replaces jobs and projection state instead of treating transient values as durable events. The generic projection carrier delivers the domain-owned inbox value for live Agents and cold persisted Sessions; it has no dedicated queue frame or live-Agent queue mirror.
Configuration
| Field | Default | Meaning |
|---|---|---|
coldBlankProbeMaxBytes |
1,024 |
Maximum physical size of a cold Session artifact eligible for blankness verification; 0 disables probes |
The generated configuration catalog is the exhaustive source for accepted fields and their JSDoc.
Model Experience
None, as invoked Agent commands own any model-visible effect.
KV Cache effect
No direct effect; model requests remain owned by the Agent and LLM packages.
Known Limitations and Deferred Work
- Control baselines represent process-local state and therefore cannot reconstruct jobs after a Host restart.
- A failed follow resumption remains visible to the caller instead of retrying indefinitely.