Yichen Jiang
8f3103b511
- session.killJob maps job-not-found from the lookup only: jobs.get gates the same synchronous span, so a producer-cancel throw now propagates per the registry contract (job state unchanged) instead of masquerading as a lookup failure (threads r3860226021, r3860226047). - session.killJob applies the service-wide subagent ownership fence exactly as cancel does; a subagent-owned live session rejects with the ownership error and the child-owned job stays running (thread r3860226041). - The stop control stays pending on an admitted kill: the unary response and the jobs frames have no cross-carrier ordering, so only the authoritative frame (the row leaving the killable set) releases the button, closing the duplicate-kill window (thread r3860226028). - One-line comment on the killReason assignment stating last-writer-wins is intended, beside the first-claim-wins reported handling (thread r3860225999). Host spec pins the producer-throw propagation and the fence; the component spec pins pending-until-frame; the Agent Note records both refinements.
description, kind
| description | kind |
|---|---|
| Host and Client session control: create, resume, prompt, follow history, and project live session state. | 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, human background-job kill, 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; queue mutation, cancellation, and background-job kill require the corresponding live state (the job kill leaves the terminal report unclaimed so the owning agent still receives its completion notice); 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.
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 queue, jobs, and projection state instead of treating transient values as durable events.
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.
Dev Note
Working context for maintainers — click to expand
None.