Files
deepseek-harness/packages/api/session-controller/src/client/transport.ts
T
imccyu 2f2caf88b3 feat(session): split history, state and web controllers
History, State and Web become ordinary classes sharing the Session scope.
Subscribe-before-read removes the tail repair, events and page expose the
cursor-bearing history read, observeEvent keeps a pure event subscription,
and follow stays passive unless activate is requested.
2026-10-25 18:14:18 +08:00

248 lines
8.5 KiB
TypeScript

/** Session-specific adapters for Gateway-owned Remote stream lifecycles. */
import type {} from '@deepseek-ai/dsh-api-session-controller/remote'
import { RemoteError } from '@deepseek-ai/dsh-typert-protocol'
import {
RemoteJournalStream,
RemoteSnapshotStream,
RemoteStreamCarrierError,
type ClientRemote,
type RemoteJournalChange,
type RemoteJournalFrame,
} from '@deepseek-ai/dsh-api-gateway/client'
import type {
SessionAddress,
SessionAssistantStreamBaseline,
SessionAssistantStreamFrame,
SessionControlFrame,
SessionHistoryRecord,
SessionPage,
SessionPageRequest,
SessionProjectionBaseline,
} from '../types.ts'
import {
historyEntries,
historyRecordFirstSeq,
historyRecordLastSeq,
} from './sessions/history-records.ts'
import type { SessionEventLikeEntry, SessionLiveEventEntry } from './contract/events.ts'
import type { SessionRemotes } from './sessions/remotes.ts'
import { assertSessionWireEvent } from './session-wire-event.ts'
export {
SESSION_SEARCH_RESULT_LIMIT,
SESSION_SEARCH_SNIPPET_MAX_CODE_POINTS,
} from '../types.ts'
/** Pagination fields bound to an already-addressed Session journal. */
export type ClientSessionPageRequest = Omit<SessionPageRequest, 'address' | 'throughSeq'>
/** Complete generated `ctx.remote.session` namespace. */
export type SessionRemote = ClientRemote['session']
/** Opening metadata carried only by a follow snapshot, never by loadOlder pages. */
interface SessionJournalPage extends SessionPage {
readonly projections?: SessionProjectionBaseline
readonly assistantStream?: SessionAssistantStreamBaseline
}
/** One complete publication from the Session journal stream. */
export type SessionJournalChange =
| {
readonly type: 'replace' | 'prepend'
readonly page: SessionJournalPage
readonly entries: readonly SessionEventLikeEntry[]
readonly hasMore: boolean
}
| { readonly type: 'append'; readonly entry: SessionLiveEventEntry }
| { readonly type: 'assistant-stream'; readonly frame: SessionAssistantStreamFrame }
function toSessionJournalChange(
change: RemoteJournalChange<
SessionJournalPage, SessionHistoryRecord, SessionAssistantStreamFrame
>,
): SessionJournalChange {
switch (change.type) {
case 'replace':
case 'prepend':
return { ...change, entries: historyEntries(change.entries) }
case 'append': {
return {
type: 'append',
entry: change.entry as unknown as SessionLiveEventEntry,
}
}
case 'notification':
return { type: 'assistant-stream', frame: change.notification }
}
}
type SessionControlBaselineFrame = Extract<SessionControlFrame, { type: 'baseline' }>
type SessionControlDeltaFrame = Exclude<SessionControlFrame, SessionControlBaselineFrame>
/** Gateway-owned control snapshot stream configured for Session frames. */
export type SessionControlStream = RemoteSnapshotStream<
SessionControlBaselineFrame,
SessionControlDeltaFrame
>
/** Domain sinks used by the Host-wide Session control stream. */
export interface SessionControlStreamOptions {
/** Apply a complete baseline or one later update. */
readonly accept: (frame: SessionControlFrame) => void
/** Observe a retryable carrier loss before reconnection. */
readonly carrierFailed?: (error: RemoteStreamCarrierError) => void
/** Publish a terminal business or protocol failure. */
readonly failed: (error: unknown) => void
}
/** Domain sinks used by one addressed Session event journal. */
export interface SessionEventStreamOptions {
/** Apply one complete event-window change. */
readonly publish: (change: SessionJournalChange) => void
/** Observe a retryable carrier loss before reconnection. */
readonly carrierFailed?: (error: RemoteStreamCarrierError) => void
/** Publish a terminal stream, page, or protocol failure after opening. */
readonly failed: (error: unknown) => void
}
/**
* Create the Host-wide Session control snapshot stream.
* @param remote - generated Session namespace and Gateway stream factory.
* @param options - Session state destinations.
* @returns an unstarted stream owned by the Client Session runtime.
*/
export function createSessionControlStream(
remote: SessionRemotes,
options: SessionControlStreamOptions,
): SessionControlStream {
const stream = remote.$stream<SessionControlFrame>({
name: 'session control stream',
open: signal => remote.session.control(signal),
ended: accepted => accepted
? new RemoteStreamCarrierError('session control stream ended without a terminal result')
: new Error('session control stream ended before its opening snapshot'),
...(options.carrierFailed === undefined ? {} : { carrierFailed: options.carrierFailed }),
})
return new RemoteSnapshotStream(stream, {
name: 'session control stream',
isSnapshot: (frame): frame is SessionControlBaselineFrame => frame.type === 'baseline',
replace: options.accept,
update: options.accept,
failed: options.failed,
})
}
/** Gateway-owned event journal bound to one ordinary or direct-subagent Session address. */
export class SessionEventStream extends RemoteJournalStream<
SessionJournalPage,
SessionHistoryRecord,
number,
ClientSessionPageRequest,
SessionAssistantStreamFrame
> {
/**
* @param remote - generated Session namespace and Gateway stream factory.
* @param address - durable ordinary-Session or direct-subagent address.
* @param options - Session event-window destinations.
*/
constructor(
private readonly remote: SessionRemotes,
private readonly address: SessionAddress,
options: SessionEventStreamOptions,
) {
super(remote, {
name: 'session event stream',
emptyCursor: -1,
entries: page => page.records,
hasMore: page => page.hasMore,
first: historyRecordFirstSeq,
last: historyRecordLastSeq,
compare: (left, right) => left - right,
follows: (left, right) => right === left + 1,
publish: (change) => { options.publish(toSessionJournalChange(change)) },
...(options.carrierFailed === undefined
? {}
: { carrierFailed: options.carrierFailed }),
failed: options.failed,
})
}
/** @inheritdoc */
protected override async * follow(
request: ClientSessionPageRequest,
signal: AbortSignal,
): AsyncIterable<RemoteJournalFrame<
SessionHistoryRecord, number, SessionJournalPage, SessionAssistantStreamFrame
>> {
let assistantRevision: number | undefined
for await (const frame of this.remote.session.follow({
address: this.address,
activate: true,
assistantStream: true,
...this.repairRequest(request),
}, signal)) {
if (frame.type === 'snapshot') {
for (const record of frame.records) assertSessionWireEvent(record.event)
if (frame.assistantStream === undefined) {
throw new RemoteError(
'gateway/internal',
'session assistant stream omitted its opted-in opening baseline',
{},
)
}
assistantRevision = frame.assistantStream.revision
yield {
type: 'opened',
cursor: frame.cursor,
page: {
records: frame.records,
hasMore: frame.hasMore,
projections: frame.projections,
assistantStream: frame.assistantStream,
},
}
continue
}
if (frame.type === 'assistant-stream') {
const expected = (assistantRevision ?? 0) + 1
if (frame.frame.revision !== expected) {
throw new RemoteStreamCarrierError(
`session assistant stream skipped revision ${String(expected)}`,
)
}
assistantRevision = frame.frame.revision
yield { type: 'notification', notification: frame.frame }
continue
}
assertSessionWireEvent(frame.event)
yield { type: 'entry', entry: frame }
}
}
/** @inheritdoc */
protected override async readPage(
request: ClientSessionPageRequest,
throughSeq: number,
signal: AbortSignal,
): Promise<SessionJournalPage> {
const result = await this.remote.session.page(
{ address: this.address, throughSeq, ...request },
signal,
)
if (!result.ok) throw result.error
for (const record of result.value.records) assertSessionWireEvent(record.event)
return result.value
}
/** @inheritdoc */
protected override repairRequest(
request: ClientSessionPageRequest,
): ClientSessionPageRequest {
return {
...(request.maxMessages === undefined ? {} : { maxMessages: request.maxMessages }),
...(request.turnWindow === undefined ? {} : { turnWindow: request.turnWindow }),
}
}
}