@modesto_ma/dsh-channels 0.0.0-stage → 0.1.0

package/src/host/agent.ts

@@ -0,0 +1,181 @@
+/**
+ * Host bridge, agent surface: creation/resume options, the live Agent and its
+ * scoped context, the agent registry, and the agent-preset roster.
+ *
+ * @module dsh-channels/host/agent
+ */
+
+import type { CommandRuntime } from './commands.ts'
+import type { Session, SessionId, UserMessage } from './core.ts'
+
+// ---- Agent surface ------------------------------------------------------
+
+/** Cancellation causes accepted by `agent.cancel()`. */
+export type AgentCancelCause =
+  | { readonly kind: 'user' }
+  | { readonly kind: 'parent' }
+  | { readonly kind: 'hook'; readonly reason: string }
+  | { readonly kind: 'disposed' }
+
+export interface AgentOptions {
+  provider?: string
+  model?: string
+  maxTokens?: number
+}
+
+/** Exact model-call configuration exposed by the Agent-scoped request waterfall. */
+export interface AgentRequestConfig {
+  provider: string
+  model: string
+  reasoningEffort?: string
+  maxTokens?: number
+  [key: string]: unknown
+}
+
+/** Agent-scoped request override installed before the first prompt assembly. */
+export type AgentRequestListener = (
+  payload: { turn: number; step: number; signal: AbortSignal },
+  next: () => Promise<AgentRequestConfig>,
+) => Promise<AgentRequestConfig>
+
+/** Cordis listener placement used to make an explicit channel override outermost. */
+export interface AgentRequestListenerOptions {
+  prepend?: boolean
+}
+
+
+/** One ordered system-prompt section the plugin contributes to an Agent scope. */
+export interface PromptSection {
+  readonly name: string
+  readonly order: number
+  readonly text: string
+  readonly interpolate?: boolean
+  readonly complete?: boolean
+}
+
+/** The Agent-scoped slice of the host `systemPrompt` registry. */
+export interface SystemPromptRuntime {
+  section(section: PromptSection): () => void
+}
+
+export interface AgentContext {
+  commands: CommandRuntime
+  /** Present inside a setup scope that injected `systemPrompt`. */
+  systemPrompt?: SystemPromptRuntime
+  /** Register an Agent-scoped model-call override. */
+  on(
+    event: 'agent/request',
+    listener: AgentRequestListener,
+    options?: boolean | AgentRequestListenerOptions,
+  ): () => boolean
+  /** Mount a child plugin only after its declared Host services are available. */
+  inject(
+    dependencies: readonly string[],
+    callback: (ctx: AgentContext) => void,
+  ): PromiseLike<unknown>
+}
+
+export interface Agent {
+  readonly id: SessionId
+  readonly options: AgentOptions
+  readonly session: Session
+  readonly status: 'idle' | 'running'
+  readonly inbox: {
+    readonly nextTurn: readonly unknown[]
+    readonly nextStep: readonly unknown[]
+  }
+  readonly ctx: AgentContext
+  followup(message: UserMessage): void
+  /** Abort the active turn (and pending input unless `keepInbox`). */
+  cancel?(cause: AgentCancelCause, options?: { keepInbox?: boolean }): void
+}
+
+export interface AgentHandle {
+  agent: Agent
+  dispose(): Promise<void>
+}
+
+/**
+ * Compose one unpublished agent's scoped world before publication. The host
+ * factory awaits it after minting the agent context and before announcing the
+ * session/agent, so everything registered there (preset tools, prompt
+ * sections, listeners) exists before the first prompt assembly; a rejection
+ * rolls the creation back. The plugin only returns `void` — the synchronous
+ * `AgentSetupCommit` flavor is never produced here.
+ */
+export type AgentSetup = (agentCtx: AgentContext) => Promise<void> | void
+
+export interface CreateAgentOptions {
+  readonly sessionId: SessionId
+  readonly meta?: { readonly cwd?: string; readonly agentPreset?: string }
+  readonly agentOptions?: AgentOptions
+  readonly setup?: AgentSetup
+}
+
+export interface ResumeAgentOptions {
+  readonly resumeSessionId: SessionId
+  readonly agentOptions?: AgentOptions
+  readonly setup?: AgentSetup
+}
+
+export interface AgentRegistry {
+  create(options: CreateAgentOptions): Promise<AgentHandle>
+  resume(options: ResumeAgentOptions): Promise<AgentHandle>
+  /**
+   * Synchronous live-registry lookup (host parity with `ctx.agents.get`):
+   * the published agent for a session id when one is live, regardless of
+   * which owner published it. The plugin uses this to BORROW a live agent
+   * instead of cold-resuming a session another owner already holds (the
+   * persistence layer rejects `resume` on a live session).
+   */
+  get(id: SessionId): Agent | undefined
+}
+
+
+// ---- Agent-preset surface ------------------------------------------------
+
+/** One resolvable preset identity on the host's preset roster. */
+export interface AgentPreset {
+  readonly id: string
+  readonly path?: string
+  /** Display metadata published by a user-authored preset declaration. */
+  readonly name?: string
+  readonly description?: string
+  readonly order?: number
+  /** Why this preset cannot compose a session; absent when it can. */
+  readonly broken?: string
+}
+
+/**
+ * The host agent-preset roster (`@deepseek-ai/dsh-agent-presets`). In
+ * web-profile deployments the model-facing tools live BEHIND agent presets
+ * (the host disables the tool rows at the host layer) and `agents.create()`
+ * applies none on its own — the caller composes the agent's world through
+ * `setup`, which is where a preset is mounted. The plugin reads the roster
+ * through `ctx.get('agentPresets')` because deployments without one compose
+ * their tools at the host layer instead, and direct property access on a
+ * cordis context throws for services that were not injected.
+ */
+export interface AgentPresets {
+  /**
+   * Default preset id for a session that names none. Absent on roster
+   * implementations that do not publish their default.
+   */
+  readonly defaultId?: string
+  /**
+   * Resolve one preset by id; `undefined` resolves the roster default.
+   * Resolves BEFORE the session exists so the header meta can record it.
+   * @throws when no configured root supplies that id.
+   */
+  resolve(id?: string): Promise<AgentPreset>
+  /**
+   * Compose one agent from a preset (standing mount + scope parent bind).
+   * Call from the agent factory's `setup`; a rejection there rolls the
+   * agent creation back. `id` defaults to the roster default.
+   * @returns the composed preset.
+   */
+  mount(agentCtx: AgentContext, id?: string): Promise<AgentPreset>
+  /** Every declared preset, including activation diagnostics, when exposed. */
+  list?(): Promise<readonly AgentPreset[]>
+}
+

package/src/host/commands.ts

@@ -0,0 +1,63 @@
+/**
+ * Host bridge, human-command surface (`ctx.commands`).
+ *
+ * @module dsh-channels/host/commands
+ */
+
+import type { Agent } from './agent.ts'
+import type { CommandId } from './core.ts'
+
+// ---- Human-command surface ---------------------------------------------
+
+export interface CommandInputDescriptor {
+  readonly hint: string
+}
+
+export type CommandResult =
+  | { readonly kind: 'success'; readonly text?: string; readonly sourceEventSeq?: number }
+  | { readonly kind: 'error'; readonly text: string }
+
+export interface CommandExecution {
+  readonly commandId: CommandId
+  readonly result: CommandResult
+}
+
+export interface CommandDescriptor {
+  readonly name: string
+  readonly description: string
+  readonly input?: CommandInputDescriptor
+}
+
+export interface CommandInvocation {
+  readonly commandId: CommandId
+  readonly agent: Agent
+  readonly rawInput: string
+  readonly signal: AbortSignal
+}
+
+export interface CommandDefinition extends CommandDescriptor {
+  readonly recordInput?: boolean
+  readonly handler: (invocation: CommandInvocation) => CommandResult | Promise<CommandResult>
+}
+
+/** Exact wire image input accepted by the Host command runtime. */
+export interface EncodedImageAttachment {
+  readonly mediaType: 'image/png' | 'image/jpeg' | 'image/webp' | 'image/gif'
+  readonly data: string
+  readonly name?: string
+}
+
+/** Minimal structural bridge to `@deepseek-ai/dsh-commands`' runtime. */
+export interface CommandRuntime {
+  register(definition: CommandDefinition): () => void
+  list(agent: Agent): readonly CommandDescriptor[]
+  find(agent: Agent, name: string): CommandDefinition | undefined
+  execute(
+    agent: Agent,
+    line: string,
+    images: readonly EncodedImageAttachment[],
+    signal: AbortSignal,
+  ): Promise<CommandExecution | undefined>
+}
+
+/** Agent-scoped Cordis context slice used to register scoped commands. */

package/src/host/core.ts

@@ -0,0 +1,345 @@
+/**
+ * Host bridge, core surface: identities, LLM message/stream vocabulary, the
+ * durable Session log, and the session-event union this plugin folds.
+ *
+ * Split from the former single `dsh-types.ts`; `src/dsh-types.ts` remains the
+ * public barrel so consumers keep one import specifier.
+ *
+ * @module dsh-channels/host/core
+ */
+
+import type { Agent } from './agent.ts'
+
+/** Branded session identity (runtime value is a plain string). */
+export type SessionId = string & { readonly __sessionId: never }
+/** Branded message identity (runtime value is a plain string). */
+export type MessageId = string & { readonly __messageId: never }
+/** Branded command-execution identity (runtime value is a plain string). */
+export type CommandId = string & { readonly __commandId: never }
+
+// ---- LLM surface --------------------------------------------------------
+
+export interface TextBlock {
+  type: 'text'
+  text: string
+}
+
+export interface ReasoningBlock {
+  type: 'reasoning'
+  text: string
+}
+
+/** Per-message model-facing blocks (plugin only ever produces plain text). */
+export type ContentBlock =
+  | TextBlock
+  | ReasoningBlock
+  | { type: string; [key: string]: unknown }
+
+/** Provider usage buckets; input/output/cache fields are disjoint. */
+export interface TokenUsage {
+  inputTokens: number
+  outputTokens: number
+  reasoningTokens?: number
+  cacheReadTokens?: number
+  cacheWriteTokens?: number
+}
+
+export interface UserMessage {
+  id: MessageId
+  role: 'user'
+  content: ContentBlock[]
+  source: { kind: string }
+}
+
+/** The chunk vocabulary consumed from live assistant-stream frames. */
+export type StreamChunk =
+  | { type: 'block-start'; index: number; blockType: string }
+  | { type: 'text-delta'; index: number; text: string }
+  | { type: 'reasoning-delta'; index: number; text: string }
+  | { type: 'tool-call-delta'; index: number; argumentsDelta: string; id?: string; name?: string }
+  | { type: 'block-end'; index: number; block: { type: string; text?: string } }
+  | { type: 'usage'; usage: TokenUsage }
+  | { type: 'finish'; [key: string]: unknown }
+  | { type: string; [key: string]: unknown }
+
+/** Compacted durable stream record embedded in `assistant/message.stream`. */
+export type AssistantStreamRecord = { readonly type: string; readonly [key: string]: unknown }
+
+/**
+ * One process-local live assistant streaming publication
+ * (`agent/assistant-stream`, DSH `packages/core/agent/src/runtime-types.ts`).
+ *
+ * DSH stopped emitting the durable `assistant/chunk` session event in commit
+ * `f99b06eaed` (2026-09-02, "feat(session)!: embed assistant streams in format
+ * v2"), so this transient event is the only live delta source; the durable
+ * `assistant/message.stream` records are the replay-safe counterpart.
+ */
+export type AssistantStreamFrame =
+  | {
+    readonly type: 'start'
+    readonly attemptId: string
+    readonly revision: number
+    readonly turn: number
+    readonly step: number
+  }
+  | {
+    readonly type: 'chunk'
+    readonly attemptId: string
+    readonly revision: number
+    readonly index: number
+    readonly time: number
+    readonly chunk: StreamChunk
+  }
+  | {
+    readonly type: 'end'
+    readonly attemptId: string
+    readonly revision: number
+    readonly index: number
+    readonly outcome:
+      | { readonly kind: 'committed'; readonly eventType: 'assistant/message' | 'assistant/attempt'; readonly seq: number }
+      | { readonly kind: 'abandoned' }
+  }
+
+export interface AssistantStreamPayload {
+  readonly agent: Agent
+  readonly frame: AssistantStreamFrame
+}
+
+// ---- Session surface ----------------------------------------------------
+
+export interface SessionHeader {
+  readonly version: number
+  readonly id: SessionId
+  readonly createdAt: number
+  readonly cwd?: string
+  /**
+   * The session this one was forked/derived from — for a subagent child this
+   * is the calling parent session's id (the link the streamer uses to fold
+   * child progress into the parent's card).
+   */
+  readonly parentSession?: SessionId
+  /** Coarse product classification (`'subagent'` for subagent children). */
+  readonly origin?: string
+  /** Delegation depth: 1 for a direct subagent child. */
+  readonly delegationDepth?: number
+  /** Preset used to compose this Session's agent, when the host uses presets. */
+  readonly agentPreset?: string
+}
+
+/**
+ * The live session object (durable event log + header).
+ *
+ * DSH removed the synchronous whole-log `events` getter (commit 5660f44d29,
+ * 2026-08-28) in favor of `eventAt()` / `snapshotEvents()` / `ownEvents()`;
+ * all three are `@deprecated` as of 2026-09-09 in favor of session
+ * projections plus explicit paged reads. This bridge keeps only the range
+ * reader (the narrowest replacement that preserves existing folds) and the
+ * request-header fold; new state should come from `ctx.sessionProjections`
+ * or `ctx.sessionQuery` instead of a fresh whole-log read.
+ */
+export interface Session {
+  readonly id: SessionId
+  readonly header: SessionHeader
+  readonly firstLiveSeq: number
+  /** Immutable snapshot of a half-open event range (defaults to the whole log). */
+  snapshotEvents(fromSeq?: number, toSeqExclusive?: number): readonly SessionEvent[]
+  /** Latest folded request header, when the session has produced one. */
+  requestHeader?(): { config?: { provider?: string; model?: string; reasoningEffort?: string } } | undefined
+}
+
+export interface SessionEventEnvelope {
+  readonly seq: number
+  /** Unix epoch milliseconds recorded by the Session append boundary. */
+  readonly time?: number
+  readonly ignorable?: boolean
+}
+
+export interface AssistantMessageEvent extends SessionEventEnvelope {
+  type: 'assistant/message'
+  data: {
+    turn: number
+    step: number
+    message: unknown
+    /** Compacted durable stream records (v2 format); replays the exact deltas. */
+    stream?: readonly AssistantStreamRecord[]
+    usage?: TokenUsage
+    /** Set when a cancelled turn finalized its delivered prefix as this message. */
+    interrupted?: true
+  }
+}
+
+export interface StepStartEvent extends SessionEventEnvelope {
+  type: 'step/start'
+  data: { turn: number; step: number }
+}
+
+export interface StepEndEvent extends SessionEventEnvelope {
+  type: 'step/end'
+  data: { turn: number; step: number }
+}
+
+/** Serializable model failure carried by a failed Harness turn. */
+export interface TurnFailure {
+  message: string
+  code: string
+  [key: string]: unknown
+}
+
+/**
+ * Why a Harness turn ended. String reasons remain accepted for compatibility
+ * with older persisted fixtures; current Harness emits the structured union.
+ */
+export type TurnEndReason =
+  | string
+  | { kind: 'completed' }
+  | { kind: 'aborted'; reason: unknown }
+  | { kind: 'blocked' }
+  | { kind: 'error'; error: TurnFailure }
+  | { kind: 'max-tokens' }
+  | { kind: 'interrupted' }
+
+export interface TurnEndEvent extends SessionEventEnvelope {
+  type: 'turn/end'
+  data: { turn: number; reason: TurnEndReason }
+}
+
+export interface RequestHeaderEvent extends SessionEventEnvelope {
+  type: 'request/header'
+  data: {
+    header: {
+      config: {
+        provider?: string
+        model?: string
+        reasoningEffort?: string
+        [key: string]: unknown
+      }
+      [key: string]: unknown
+    }
+  }
+}
+
+export interface ToolCallEvent extends SessionEventEnvelope {
+  type: 'tool/call'
+  data: {
+    turn: number
+    step: number
+    callId: string
+    /** Model-facing tool name (e.g. `bash`, `subagent`, `workflow`). */
+    name: string
+    /** Raw arguments JSON exactly as the model produced it (unparsed). */
+    arguments: string
+  }
+}
+
+export interface ToolResultEvent extends SessionEventEnvelope {
+  type: 'tool/result'
+  data: {
+    turn: number
+    step: number
+    message: {
+      /** Message-level source is the authoritative call correlation. */
+      source?: { kind?: string; callId?: string; [key: string]: unknown }
+      /** Message-level failure flag; authoritative when no `error` object is attached. */
+      isError?: boolean
+      content?: ReadonlyArray<{
+        type: string
+        toolCallId?: string
+        isError?: boolean
+        [key: string]: unknown
+      }>
+      [key: string]: unknown
+    }
+    error?: { name: string; code: string }
+    meta?: unknown
+  }
+}
+
+export interface CommandRunEvent extends SessionEventEnvelope {
+  type: 'command/run'
+  data: {
+    commandId: CommandId
+    name: string
+    args?: string
+    source: { kind: string }
+  }
+}
+
+export interface CommandDoneEvent extends SessionEventEnvelope {
+  type: 'command/done'
+  data: {
+    commandId: CommandId
+    kind: 'success' | 'error'
+    text?: string
+    sourceEventSeq?: number
+  }
+}
+
+/** Durable workflow-run progress record projected into the calling session's log. */
+export interface ToolWorkflowRunStartEvent extends SessionEventEnvelope {
+  type: 'tool-workflow/run-start'
+  data: { runId: string; name: string }
+}
+
+export interface ToolWorkflowAgentStartEvent extends SessionEventEnvelope {
+  type: 'tool-workflow/agent-start'
+  data: { runId: string; seq: number; label: string; phase?: string; childId: string }
+}
+
+export interface ToolWorkflowAgentEndEvent extends SessionEventEnvelope {
+  type: 'tool-workflow/agent-end'
+  data: { runId: string; seq: number; outcome: 'completed' | 'failed' | 'cancelled' }
+}
+
+export interface ToolWorkflowRunEndEvent extends SessionEventEnvelope {
+  type: 'tool-workflow/run-end'
+  data: { runId: string; stopReason: 'completed' | 'cancelled' | 'error' }
+}
+
+/**
+ * Durable subagent identity appended to the CHILD session's own log at
+ * creation (in-process drivers). The `label` is the delegating model's short
+ * description — what the parent card displays while the child runs.
+ */
+export interface SubagentDescriptorEvent extends SessionEventEnvelope {
+  type: 'subagent/descriptor'
+  data: {
+    version: number
+    mode: 'one-shot' | 'continuable'
+    provider: string
+    label?: string
+    [key: string]: unknown
+  }
+}
+
+/** Runtime preset switches are durable and define the currently composed preset. */
+export interface AgentPresetSelectedEvent extends SessionEventEnvelope {
+  type: 'agent-preset/selected'
+  data: { agentPreset: string }
+}
+
+export interface OtherSessionEvent extends SessionEventEnvelope {
+  /** Unknown/extension event types are ignored by the folds. */
+  type: Exclude<string, 'assistant/message' | 'step/start' | 'turn/end' | 'request/header'
+    | 'tool/call' | 'tool/result' | 'subagent/descriptor'
+    | 'command/run' | 'command/done'
+    | 'tool-workflow/run-start' | 'tool-workflow/agent-start' | 'tool-workflow/agent-end' | 'tool-workflow/run-end'>
+  data: unknown
+}
+
+export type SessionEvent =
+  | AssistantMessageEvent
+  | StepStartEvent
+  | StepEndEvent
+  | TurnEndEvent
+  | RequestHeaderEvent
+  | ToolCallEvent
+  | ToolResultEvent
+  | CommandRunEvent
+  | CommandDoneEvent
+  | AgentPresetSelectedEvent
+  | SubagentDescriptorEvent
+  | ToolWorkflowRunStartEvent
+  | ToolWorkflowAgentStartEvent
+  | ToolWorkflowAgentEndEvent
+  | ToolWorkflowRunEndEvent
+

package/src/host/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Host bridge barrel: the exact DSH surface this plugin consumes, grouped by
+ * domain. Everything is type-only (no runtime dependency on DSH internals).
+ *
+ * @module dsh-channels/host
+ */
+
+export * from './core.ts'
+export * from './agent.ts'
+export * from './commands.ts'
+export * from './interaction.ts'
+export * from './services.ts'

package/src/host/interaction.ts

@@ -0,0 +1,101 @@
+/**
+ * Host bridge, human-interaction surface: the `approval/request` waterfall
+ * (HITL approvals) and the `user-questions/request` waterfall
+ * (`ask_user_question`).
+ *
+ * @module dsh-channels/host/interaction
+ */
+
+import type { Agent } from './agent.ts'
+
+// ---- Approval (HITL) surface --------------------------------------------
+
+/**
+ * Closed approval outcomes, mirrored from
+ * `@deepseek-ai/dsh-user-approval/types`: a one-shot grant, explicit
+ * rejection, withdrawn request, or unavailable answerer. Callers fail closed
+ * on anything but `allowed-once`; a missing answerer yields `unavailable`.
+ */
+export type ApprovalOutcome = 'allowed-once' | 'rejected' | 'cancelled' | 'unavailable'
+
+/**
+ * Readonly same-process permission question (the payload of the host's
+ * `approval/request` waterfall event). `callId` links to an already-presented
+ * tool call; the plugin only renders `toolName` + `reason` on its decision
+ * card and does not duplicate tool arguments.
+ */
+export interface ApprovalRequest {
+  /** The agent on whose behalf the question is asked (routes + audit). */
+  readonly agent: Agent
+  /** The tool the question is about (model-facing name, e.g. `bash`). */
+  readonly toolName: string
+  /** The exact tool call being decided, when the asker has one. */
+  readonly callId?: string
+  /** The asker's human-readable explanation of WHY it is asking. */
+  readonly reason?: string
+  /**
+   * Localized presentation-only text (DSH 0.2.0). Preferred over `reason`
+   * when rendering; never part of the durable audit trail.
+   */
+  readonly displayReason?: { readonly en: string; readonly [locale: string]: string }
+  /**
+   * Aborting withdraws the question: the request settles `'cancelled'` and a
+   * late answer is discarded.
+   */
+  readonly signal?: AbortSignal
+}
+
+/**
+ * One `approval/request` waterfall listener: return an outcome to claim the
+ * request, or delegate by returning `next()`. The first claim occupies the
+ * single decision slot.
+ */
+export type ApprovalAnswererListener = (
+  req: ApprovalRequest,
+  next: () => Promise<ApprovalOutcome>,
+) => Promise<ApprovalOutcome>
+
+
+// ---- Structured user questions -------------------------------------------
+
+/** One selectable answer offered by `ask_user_question`. */
+export interface AskUserQuestionOption {
+  label: string
+  description?: string
+}
+
+/** One question in a `user-questions/request` waterfall payload. */
+export interface AskUserQuestionItem {
+  id: string
+  question: string
+  detail?: string
+  header?: string
+  options?: AskUserQuestionOption[]
+  multiSelect?: boolean
+  intent?: { kind: 'plan-review'; approve: string; callId?: string }
+}
+
+export interface AskUserQuestionRequestEvent {
+  questions: AskUserQuestionItem[]
+  /** Owner agent; present for every agent-originated ask. */
+  agent?: Agent
+  signal?: AbortSignal
+  wait?: { callId: string; timed?: boolean }
+}
+
+export interface AskUserQuestionAnswerItem {
+  id: string
+  selected: string[]
+  custom?: string
+}
+
+export interface AskUserQuestionAnswer {
+  answers: AskUserQuestionAnswerItem[]
+}
+
+export type UserQuestionAnswererListener = (
+  request: AskUserQuestionRequestEvent,
+  next: () => Promise<AskUserQuestionAnswer>,
+) => Promise<AskUserQuestionAnswer>
+
+