Integrate the observed master checkpoint 7ab215e23e5d977aae7eb5d4fb91782d39969dbb without rewriting the earlier published checkpoints. Master adds current-directory events, directory-aware consumers, and retained Git worktrees; its old subagent startup paths overlapped the unified activation implementation. Resolve directory selection within managed startup after acquiring parent ownership. Preserve the original Session origin while setting each new local child directory, retain persisted directory state on cold resume, and pass a required absolute cwd to external providers. Keep unified local/external ownership, full completion notices, parked-input host completion, SDK wait/error/shutdown behavior, and ACP cancellation semantics. Retain removal of the old in-process driver and continuation managers. Combine SDK wait with the new directory requests, preserve the new master directory/worktree fixtures, regenerate derived catalogs from the combined sources, and refresh only the four stale prompt/schema sidecars. Preserve every protected historical schema, archived note, catalog-v2 acknowledgement, and recorded predecessor input. Validation: full build; 59 CI static gates; 855 subagent tests with 100% coverage on changed core/external sources; affected consumer suites including 119 repaired-fixture tests; SDK 11 and headless 16 recorded scenarios; two local headless expected cases; six built nested SDK/ACP cases; lint, strict cast inventory, workspace constraints, and whitespace checks. Native Windows worker diagnostics remain additive and require the next CI run to classify the original crash.
392 lines
17 KiB
TypeScript
392 lines
17 KiB
TypeScript
/**
|
|
* JSON-RPC methods and notifications for out-of-process harness SDKs.
|
|
* The surrounding context owns plugins, persistence, and configured adapters.
|
|
*
|
|
* @module @deepseek-ai/dsh-sdk-jsonrpc-server/server
|
|
*/
|
|
|
|
import type { Context } from '@deepseek-ai/cordis'
|
|
import { resolve } from 'node:path'
|
|
import { brandString } from '@deepseek-ai/dsh-brand'
|
|
import type { Agent, AgentHandle } from '@deepseek-ai/dsh-agent'
|
|
import { admitEncodedImages, type EncodedImageAttachment, type ImageAttachmentRef } from '@deepseek-ai/dsh-attachment'
|
|
import { createUserMessage, ReasoningEffortId, type ContentBlock, type LlmRuntime } from '@deepseek-ai/dsh-llm'
|
|
import { carrierKeyOf, type Scoped } from '@deepseek-ai/dsh-scope'
|
|
import type { SessionId, SessionLogOffset } from '@deepseek-ai/dsh-session'
|
|
import type {} from '@deepseek-ai/dsh-working-directory'
|
|
import type SubagentRuntime from '@deepseek-ai/dsh-subagent'
|
|
import type { SubagentRunEndInfo } from '@deepseek-ai/dsh-subagent'
|
|
import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek-api-key'
|
|
import type {
|
|
InitializeParams,
|
|
InitializeResult,
|
|
JsonRpcTransportPeer,
|
|
SessionEventNotification,
|
|
SessionPromptParams,
|
|
SessionPromptResult,
|
|
SessionWaitParams,
|
|
SessionWorkingDirectoryParams,
|
|
SessionWorkingDirectorySetParams,
|
|
SessionWorkingDirectoryResult,
|
|
SdkEncodedImageBlock,
|
|
SubagentFinishedNotification,
|
|
SubagentStartedNotification,
|
|
} from '@deepseek-ai/dsh-sdk-protocol'
|
|
|
|
interface SessionRecord {
|
|
handle: AgentHandle
|
|
/** Latest live failure not superseded by a subsequently committed terminal. */
|
|
failure: { readonly error: unknown; readonly atOffset: SessionLogOffset } | undefined
|
|
}
|
|
|
|
function encodedImage(block: SessionPromptParams['contentBlocks'][number]): block is SdkEncodedImageBlock {
|
|
return block.type === 'image' && 'data' in block
|
|
}
|
|
|
|
async function durablePromptContent(ctx: Context, blocks: SessionPromptParams['contentBlocks']): Promise<ContentBlock[]> {
|
|
const images = blocks.filter(encodedImage)
|
|
if (images.length === 0) return blocks as ContentBlock[]
|
|
const attachments = ctx.get('attachments')
|
|
if (attachments === undefined) throw new Error('SDK image prompt requires an attachment store')
|
|
const refs = await admitEncodedImages(attachments, images.map((image): EncodedImageAttachment => ({
|
|
data: image.data,
|
|
mediaType: image.mimeType,
|
|
})))
|
|
let next = 0
|
|
return blocks.map(block => encodedImage(block)
|
|
? { type: 'image', attachment: refs[next++] as ImageAttachmentRef }
|
|
: block)
|
|
}
|
|
|
|
/** Recover the delegating parent from the service-owned scoped carrier. */
|
|
function subagentParentOf(carrier: Scoped<SubagentRuntime>): Agent {
|
|
return carrierKeyOf(carrier) as Agent
|
|
}
|
|
|
|
/** Deployment-specific status mapping for SDK turn and subagent outcomes. */
|
|
export interface HarnessSdkJsonRpcServerOptions {
|
|
/** Report max-token termination as an accepted result instead of an infrastructure error. */
|
|
maxTokensAsSuccess?: boolean
|
|
}
|
|
|
|
function successStatus(reason: string, options: HarnessSdkJsonRpcServerOptions): 'ok' | 'error' {
|
|
if (reason === 'completed') return 'ok'
|
|
return reason === 'max-tokens' && options.maxTokensAsSuccess === true ? 'ok' : 'error'
|
|
}
|
|
|
|
/**
|
|
* SDK server over one booted harness context and transport peer. Construction
|
|
* subscribes to session, agent, and subagent lifecycle events until shutdown;
|
|
* reinitialization is unsupported.
|
|
*/
|
|
export class HarnessSdkJsonRpcServer {
|
|
private cwd = process.cwd()
|
|
private provider = 'deepseek-official'
|
|
private model = 'deepseek-official'
|
|
private reasoningEffort: ReturnType<typeof ReasoningEffortId> | undefined
|
|
private maxTokens: number | undefined
|
|
private llmFiber: { dispose(): Promise<void> } | undefined
|
|
private readonly sessions = new Map<string, SessionRecord>()
|
|
private readonly sessionCreations = new Map<string, Promise<SessionRecord>>()
|
|
private readonly disposers: (() => void)[] = []
|
|
private shutdownTask: Promise<Record<string, never>> | undefined
|
|
private shuttingDown = false
|
|
private initialized = false
|
|
|
|
constructor(
|
|
private readonly ctx: Context,
|
|
private readonly transport: JsonRpcTransportPeer,
|
|
private readonly options: HarnessSdkJsonRpcServerOptions = {},
|
|
) {
|
|
const serverOptions = this.options
|
|
this.disposers.push(ctx.on('session/event', (session, event) => {
|
|
const record = this.sessions.get(session.id)
|
|
if (event.type === 'turn/end' && record?.handle.agent.session === session
|
|
&& record.failure !== undefined && event.seq >= record.failure.atOffset) {
|
|
record.failure = undefined
|
|
}
|
|
const payload: SessionEventNotification = { sessionId: String(session.id), event }
|
|
this.transport.notify('session.event', payload)
|
|
}))
|
|
this.disposers.push(ctx.on('agent/error', ({ agent, error }) => {
|
|
const record = this.sessions.get(agent.session.id)
|
|
if (record?.handle.agent !== agent) return
|
|
record.failure = { error, atOffset: agent.session.seq }
|
|
}))
|
|
this.disposers.push(ctx.on('agent/status', ({ agent, status }) => {
|
|
this.transport.notify('session.status', { sessionId: String(agent.session.id), status })
|
|
}))
|
|
this.disposers.push(ctx.on('session/created', (session) => {
|
|
const parentSession = session.header.parentSession
|
|
if (parentSession === undefined) return
|
|
const payload: SubagentStartedNotification = {
|
|
parentSessionId: String(parentSession),
|
|
childSessionId: String(session.id),
|
|
}
|
|
this.transport.notify('subagent.started', payload)
|
|
}))
|
|
this.disposers.push(ctx.on('subagent/end', function (this: Scoped<SubagentRuntime>, info: SubagentRunEndInfo) {
|
|
const parent = subagentParentOf(this)
|
|
// This protocol reports only in-process child sessions. The service
|
|
// snapshots the provider name and local flag through child disposal;
|
|
// matching ids or parent lineage alone never establishes locality.
|
|
if (!info.local) return
|
|
const payload: SubagentFinishedNotification = {
|
|
provider: info.provider,
|
|
agentId: String(info.id),
|
|
parentSessionId: String(parent.session.id),
|
|
childSessionId: String(info.id),
|
|
status: successStatus(info.stopReason, serverOptions),
|
|
stopReason: info.stopReason,
|
|
...(info.lastAssistantMessage === undefined
|
|
? {}
|
|
: { lastAssistantMessage: [...info.lastAssistantMessage] }),
|
|
}
|
|
transport.notify('subagent.finished', payload)
|
|
}))
|
|
}
|
|
|
|
/**
|
|
* Validate and configure the SDK route, mounting the DeepSeek fallback only when unowned.
|
|
* @param params - SDK handshake parameters.
|
|
* @returns server identity for the handshake.
|
|
*/
|
|
async initialize(params: InitializeParams): Promise<InitializeResult> {
|
|
if (params.reasoningEffort !== undefined
|
|
&& (typeof params.reasoningEffort !== 'string' || params.reasoningEffort.length === 0)) {
|
|
throw new TypeError('initialize reasoningEffort must be a non-empty string')
|
|
}
|
|
if (params.maxTokens !== undefined
|
|
&& (!Number.isSafeInteger(params.maxTokens) || params.maxTokens <= 0)) {
|
|
throw new TypeError('initialize maxTokens must be a positive safe integer')
|
|
}
|
|
const cwd = resolve(params.cwd)
|
|
const provider = params.provider
|
|
const model = params.model
|
|
const reasoningEffort = params.reasoningEffort === undefined
|
|
? undefined
|
|
: ReasoningEffortId(params.reasoningEffort)
|
|
if (!this.hasAdapterFor(provider)) {
|
|
if (provider !== 'deepseek-official') throw new Error(`no adapter registered for provider "${provider}"`)
|
|
this.llmFiber = await this.ctx.plugin(LlmDeepSeek)
|
|
}
|
|
// Adapter presence was read from this service above; a successful fallback mount also requires it.
|
|
const llm = this.ctx.get('llm') as LlmRuntime
|
|
await llm.resolveCallConfig({
|
|
provider,
|
|
model,
|
|
...reasoningEffort === undefined ? {} : { reasoningEffort },
|
|
...params.maxTokens === undefined ? {} : { maxTokens: params.maxTokens },
|
|
})
|
|
this.cwd = cwd
|
|
this.provider = provider
|
|
this.model = model
|
|
this.reasoningEffort = reasoningEffort
|
|
this.maxTokens = params.maxTokens
|
|
this.initialized = true
|
|
return { serverInfo: { name: 'deepseek-harness-sdk-runtime', version: '0.0.1' } }
|
|
}
|
|
|
|
/**
|
|
* Queue one identified prompt without assigning later activity to it.
|
|
* @param params - target session and user content.
|
|
* @returns the durable message identity.
|
|
*/
|
|
async prompt(params: SessionPromptParams): Promise<SessionPromptResult> {
|
|
if (!this.initialized) throw new Error('SDK server is not initialized')
|
|
const rec = await this.getOrCreateSession(params.sessionId)
|
|
// An agent-loop-only reload disposes the loop's agents while this record
|
|
// survives; a retained agent accepts followup() silently, so validate the
|
|
// record against the live registry before delivery.
|
|
this.assertLiveAgent(rec, params.sessionId)
|
|
const content = await durablePromptContent(this.ctx, params.contentBlocks)
|
|
// Attachment admission crosses an async boundary where shutdown or an
|
|
// agent-loop reload may detach the retained handle.
|
|
this.assertLiveAgent(rec, params.sessionId)
|
|
const message = createUserMessage({
|
|
content,
|
|
source: { kind: 'user' },
|
|
})
|
|
rec.handle.agent.followup(message)
|
|
return { messageId: message.id }
|
|
}
|
|
|
|
/**
|
|
* Wait for an existing owned Agent and its managed descendants to finish.
|
|
* The response follows all Session notifications emitted during the wait.
|
|
* Rejects a live Agent failure that has no subsequent durable terminal.
|
|
* @param params - the SDK-owned session to observe without creating one.
|
|
* @returns an empty result after the root stays idle across the descendant check.
|
|
*/
|
|
async wait(params: SessionWaitParams): Promise<Record<string, never>> {
|
|
if (!this.initialized) throw new Error('SDK server is not initialized')
|
|
const rec = this.sessions.get(params.sessionId)
|
|
if (rec === undefined) throw new Error(`unknown SDK session: ${params.sessionId}`)
|
|
const agent = rec.handle.agent
|
|
const subagents = this.ctx.get('subagents')
|
|
while (true) {
|
|
this.assertLiveAgent(rec, params.sessionId)
|
|
await agent.whenIdle()
|
|
const idleSeq = agent.session.seq
|
|
const children = await subagents?.waitForChildren(agent)
|
|
this.assertLiveAgent(rec, params.sessionId)
|
|
if (!children && agent.status === 'idle' && agent.session.seq === idleSeq) {
|
|
if (rec.failure !== undefined) throw rec.failure.error
|
|
return {}
|
|
}
|
|
}
|
|
}
|
|
|
|
private assertLiveAgent(rec: SessionRecord, sessionId: string): void {
|
|
if (this.ctx.agents.get(rec.handle.agent.id) !== rec.handle.agent) {
|
|
throw new Error(`session agent was disposed outside the server: ${sessionId}`)
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Read a Session's effective directory, recovering a missing directory to its origin.
|
|
* @param params - target Session; an unknown id creates it.
|
|
* @returns the absolute effective directory.
|
|
*/
|
|
async getWorkingDirectory(params: SessionWorkingDirectoryParams): Promise<SessionWorkingDirectoryResult> {
|
|
const agent = await this.workingDirectoryAgent(params.sessionId)
|
|
return { cwd: await this.ctx.workingDirectory.ensure(agent) }
|
|
}
|
|
|
|
/**
|
|
* Change a Session's directory and queue its model-visible transition.
|
|
* @param params - target Session and absolute or current-directory-relative path.
|
|
* @returns the validated absolute directory; origin and permissions are unchanged.
|
|
*/
|
|
async setWorkingDirectory(params: SessionWorkingDirectorySetParams): Promise<SessionWorkingDirectoryResult> {
|
|
const agent = await this.workingDirectoryAgent(params.sessionId)
|
|
return { cwd: await this.ctx.workingDirectory.set(agent, params.path) }
|
|
}
|
|
|
|
private async workingDirectoryAgent(sessionId: string): Promise<Agent> {
|
|
if (!this.initialized) throw new Error('SDK server is not initialized')
|
|
const rec = await this.getOrCreateSession(sessionId)
|
|
this.assertLiveAgent(rec, sessionId)
|
|
return rec.handle.agent
|
|
}
|
|
|
|
/**
|
|
* Dispose server-owned agents, adapter, and subscriptions to quiescence.
|
|
* Managed descendants drain before the root Agent handles and adapter are released.
|
|
* The surrounding context remains running.
|
|
* @returns empty JSON-RPC result.
|
|
*/
|
|
shutdown(): Promise<Record<string, never>> {
|
|
this.shutdownTask ??= this.performShutdown()
|
|
return this.shutdownTask
|
|
}
|
|
|
|
private async performShutdown(): Promise<Record<string, never>> {
|
|
this.shuttingDown = true
|
|
const pendingCreations = [...this.sessionCreations.values()]
|
|
await Promise.allSettled(pendingCreations)
|
|
this.sessionCreations.clear()
|
|
const records = [...this.sessions.values()]
|
|
this.sessions.clear()
|
|
const failures: unknown[] = []
|
|
while (this.disposers.length > 0) {
|
|
try {
|
|
this.disposers.pop()?.()
|
|
} catch (error) {
|
|
failures.push(error)
|
|
}
|
|
}
|
|
try {
|
|
await this.ctx.get('subagents')?.drainDescendants(records.map(rec => rec.handle.agent))
|
|
} catch (error: unknown) {
|
|
failures.push(error)
|
|
}
|
|
const teardownResults = await Promise.allSettled([
|
|
...records.map(rec => Promise.resolve().then(() => rec.handle.dispose())),
|
|
...(this.llmFiber === undefined ? [] : [Promise.resolve().then(() => this.llmFiber?.dispose())]),
|
|
])
|
|
this.llmFiber = undefined
|
|
failures.push(...teardownResults
|
|
.filter((result): result is PromiseRejectedResult => result.status === 'rejected')
|
|
.map(result => result.reason as unknown))
|
|
if (failures.length === 1) throw failures[0]
|
|
if (failures.length > 1) throw new AggregateError(failures, 'SDK server teardown failed')
|
|
return {}
|
|
}
|
|
|
|
/**
|
|
* Dispatch one incoming JSON-RPC request to its typed handler. Throws (→ a
|
|
* JSON-RPC error response) on an unknown method.
|
|
* @param method - the JSON-RPC method name.
|
|
* @param params - the raw params object from the wire.
|
|
* @returns the handler's result, to be serialized as the response.
|
|
*/
|
|
async handleRequest(method: string, params: Record<string, unknown> | undefined): Promise<unknown> {
|
|
switch (method) {
|
|
case 'initialize':
|
|
return this.initialize(params as unknown as InitializeParams)
|
|
case 'session/prompt':
|
|
return this.prompt(params as unknown as SessionPromptParams)
|
|
case 'session/wait': {
|
|
const sessionId = params?.sessionId
|
|
if (typeof sessionId !== 'string') throw new TypeError('session/wait requires a sessionId string')
|
|
return this.wait({ sessionId })
|
|
}
|
|
case 'session/working-directory/get':
|
|
case 'session/working-directory/set': {
|
|
if (typeof params?.sessionId !== 'string' || params.sessionId.length === 0) {
|
|
throw new TypeError('working-directory requests require a non-empty sessionId')
|
|
}
|
|
if (method === 'session/working-directory/get') {
|
|
return this.getWorkingDirectory({ sessionId: params.sessionId })
|
|
}
|
|
if (typeof params.path !== 'string') throw new TypeError('working-directory set requires a path string')
|
|
return this.setWorkingDirectory({ sessionId: params.sessionId, path: params.path })
|
|
}
|
|
case 'shutdown':
|
|
return this.shutdown()
|
|
default:
|
|
throw new Error(`unknown DeepSeek Harness SDK runtime method: ${method}`)
|
|
}
|
|
}
|
|
|
|
private async getOrCreateSession(sessionId: string): Promise<SessionRecord> {
|
|
if (this.shuttingDown) throw new Error('SDK server is shutting down')
|
|
const existing = this.sessions.get(sessionId)
|
|
if (existing) return existing
|
|
const pending = this.sessionCreations.get(sessionId)
|
|
if (pending) return pending
|
|
const creation = this.createSession(sessionId)
|
|
this.sessionCreations.set(sessionId, creation)
|
|
void creation.then(
|
|
() => { this.sessionCreations.delete(sessionId) },
|
|
() => { this.sessionCreations.delete(sessionId) },
|
|
)
|
|
return creation
|
|
}
|
|
|
|
private async createSession(sessionId: string): Promise<SessionRecord> {
|
|
// No preset composition: this server's compositions keep the model-facing
|
|
// rows in the host plane, so this agent reads them from the global layer. A
|
|
// deployment that configures a roster has to join one here first
|
|
// (@deepseek-ai/dsh-agent-preset-registry README, "Composing a child agent").
|
|
const handle = await this.ctx.agents.create({
|
|
sessionId: brandString<SessionId>(sessionId),
|
|
meta: { cwd: this.cwd },
|
|
agentOptions: {
|
|
provider: this.provider,
|
|
model: this.model,
|
|
...this.reasoningEffort === undefined ? {} : { reasoningEffort: this.reasoningEffort },
|
|
...this.maxTokens === undefined ? {} : { maxTokens: this.maxTokens },
|
|
},
|
|
})
|
|
const rec: SessionRecord = { handle, failure: undefined }
|
|
this.sessions.set(sessionId, rec)
|
|
return rec
|
|
}
|
|
|
|
private hasAdapterFor(provider: string): boolean {
|
|
return this.ctx.get('llm')?.listProviders().some(entry => entry.id === provider) ?? false
|
|
}
|
|
}
|