@askdkc/dsh-cli 0.11.7 → 0.12.0

package/node_modules/dsh-working-activity/src/compat/assistant-stream.ts

@@ -0,0 +1,209 @@
+/**
+ * Live `agent/assistant-stream` frame → {@link ActivityEvent} normalization.
+ *
+ * This is the realtime half of the plugin's input. On the current host line the
+ * durable `assistant/chunk` event no longer exists (it is absent from
+ * `SessionEventMap` and from `KNOWN_SESSION_EVENT_TYPES`) and streamed output
+ * arrives as transient frames published on the agent scope instead, so without
+ * this module the line has no first-token promotion, no `⏵` narration and no
+ * tok/s estimate — it only moves when durable tool events arrive.
+ *
+ * Measured frame shape (`@deepseek-ai/dsh-agent@0.1.7-rc.2`,
+ * `lib/types/runtime-types.d.ts`):
+ *
+ * ```text
+ * start { attemptId, revision, turn, step }
+ * chunk { attemptId, revision, index, time, chunk }   chunk: StreamChunk
+ * end   { attemptId, revision, index, outcome }       outcome: committed{eventType,seq} | abandoned
+ * ```
+ *
+ * The fields stay read tolerantly rather than through a host type import: the
+ * package still compiles against `@deepseek-ai/dsh-agent@0.1.0-rc.6`, which has
+ * no `AssistantStreamFrame` declaration at all. Reading structurally is also
+ * what keeps the next reshape a one-file fix here.
+ *
+ * ## Why the cursor is keyed by the agent, not by the session
+ * `revision` is documented as "monotone within one attached Agent lifecycle;
+ * replacement restarts at 1". A single counter would therefore drop every frame
+ * of a replacement agent (`1 <= 100`) and silence the line forever, so the
+ * cursor lives in a `WeakMap` keyed by the emitting agent — a new agent is a new
+ * key and starts at its own revision 1 with no explicit reset anywhere.
+ * @module @deepseek-ai/dsh-working-activity/compat/assistant-stream
+ */
+
+import type { ActivityEvent, ActivityStreamKind } from '../activity-event.js'
+
+/** Identity of one agent lifecycle. Frames of different owners never share a cursor. */
+export type StreamOwner = object
+
+/** Frame types this adapter understands. */
+const FRAME_TYPES: readonly string[] = ['start', 'chunk', 'end']
+
+/** Per-owner live-stream cursor, dropped with the owner. */
+interface StreamCursor {
+  /** Highest accepted revision; `undefined` until a revision-carrying frame arrives. */
+  revision?: number
+  /** Attempt currently streaming, when one was opened or adopted. */
+  attemptId?: string
+}
+
+const cursors = new WeakMap<StreamOwner, StreamCursor>()
+
+/** The cursor for one agent lifecycle, created on first use. */
+function cursorFor(owner: StreamOwner): StreamCursor {
+  let cursor = cursors.get(owner)
+  if (cursor === undefined) {
+    cursor = {}
+    cursors.set(owner, cursor)
+  }
+  return cursor
+}
+
+/**
+ * Whether one frame is new for its owner's cursor, updating the cursor.
+ *
+ * Ordering is enforced only when both sides carry a usable revision: a host
+ * that stops timestamping frames must degrade to "accept" rather than "drop
+ * everything", because a silently frozen line is the exact failure this module
+ * exists to prevent. Duplicate delivery in that degraded mode costs a repeated
+ * delta, which the narration buffer tolerates.
+ */
+function accept(cursor: StreamCursor, revision: unknown): boolean {
+  if (typeof revision !== 'number' || !Number.isFinite(revision)) return true
+  if (cursor.revision !== undefined && revision <= cursor.revision) return false
+  cursor.revision = revision
+  return true
+}
+
+/** Narrow `unknown` to a plain record: objects only, never `null`, never an array. */
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return undefined
+  return value as Record<string, unknown>
+}
+
+/** A usable attempt id: a non-empty string, returned verbatim. */
+function asAttemptId(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim().length > 0 ? value : undefined
+}
+
+/** A frame timestamp, falling back to the wall clock when the host omits one. */
+function frameTime(frame: Record<string, unknown>): number {
+  const time = frame.time
+  return typeof time === 'number' && Number.isFinite(time) ? time : Date.now()
+}
+
+/**
+ * Normalize one live frame for the agent that published it.
+ *
+ * Returns zero events for anything the tracker does not model: unknown frame
+ * types, non-delta chunks (block boundaries, tool-call deltas, usage, finish),
+ * empty delta text, and any frame the owner's revision cursor has already seen.
+ *
+ * @param owner - The agent lifecycle that published the frame (cursor key).
+ * @param frame - Raw `agent/assistant-stream` frame, or any host payload.
+ * @returns the domain events this frame carries, in order.
+ */
+export function frameToActivityEvents(owner: StreamOwner, frame: unknown): readonly ActivityEvent[] {
+  const record = asRecord(frame)
+  if (record === undefined) return []
+  const type = typeof record.type === 'string' ? record.type : undefined
+  if (type === undefined || !FRAME_TYPES.includes(type)) return []
+
+  const cursor = cursorFor(owner)
+  if (!accept(cursor, record.revision)) return []
+
+  if (type === 'start') {
+    const attemptId = asAttemptId(record.attemptId)
+    cursor.attemptId = attemptId
+    return [{
+      kind: 'stream-start',
+      at: frameTime(record),
+      ...(attemptId === undefined ? {} : { attemptId }),
+    }]
+  }
+
+  if (type === 'chunk') return chunkEvents(cursor, record)
+
+  return endEvents(cursor, record)
+}
+
+/**
+ * One `chunk` frame: open the attempt first when the frame announces one the
+ * cursor has not seen, then the delta itself.
+ *
+ * Adoption matters after a reattach/resume, where the stream is joined
+ * mid-attempt and no `start` frame is redelivered: the first chunk a plugin
+ * sees would otherwise be unusable. Safety comes from the revision cursor
+ * instead — a late chunk of a superseded attempt carries a lower revision and
+ * never reaches this point.
+ */
+function chunkEvents(cursor: StreamCursor, frame: Record<string, unknown>): readonly ActivityEvent[] {
+  const at = frameTime(frame)
+  const attempts = asAttemptId(frame.attemptId)
+  const events: ActivityEvent[] = []
+  if (attempts !== undefined && attempts !== cursor.attemptId) {
+    cursor.attemptId = attempts
+    events.push({ kind: 'stream-start', at, attemptId: attempts })
+  }
+  const chunk = asRecord(frame.chunk)
+  const delta = deltaOf(chunk)
+  if (delta !== undefined && delta.text.length > 0) {
+    events.push({ kind: 'stream-delta', at, stream: delta.stream, text: delta.text })
+  }
+  return events
+}
+
+/**
+ * One `end` frame. Both terminal outcomes clear the cursor's attempt, but only
+ * the ones whose committed output can differ from what was streamed ask the
+ * tracker to drop its provisional state:
+ *
+ * - `abandoned` — no settlement at all, so the provisional narration is wrong;
+ * - `committed` + `assistant/attempt` — a PARTIAL settlement, so the streamed
+ *   text may exceed what was committed. This is not an abandonment and is not
+ *   reported as one;
+ * - `committed` + `assistant/message` — the streamed text IS the committed
+ *   message, so its narration may keep its freshness window (the durable
+ *   settlement already carried the same content);
+ * - an unrecognized outcome — cleared, but no reset event, so a future terminal
+ *   kind cannot accidentally discard narration it did commit.
+ */
+function endEvents(cursor: StreamCursor, frame: Record<string, unknown>): readonly ActivityEvent[] {
+  const at = frameTime(frame)
+  cursor.attemptId = undefined
+  const outcome = asRecord(frame.outcome)
+  const kind = typeof outcome?.kind === 'string' ? outcome.kind : undefined
+  if (kind === 'abandoned') return [{ kind: 'stream-reset', at, reason: 'abandoned' }]
+  const eventType = typeof outcome?.eventType === 'string' ? outcome.eventType : undefined
+  if (kind === 'committed' && eventType === 'assistant/attempt') {
+    return [{ kind: 'stream-reset', at, reason: 'attempt-settled' }]
+  }
+  return []
+}
+
+/** The stream kind and text of one chunk, when it is a displayable delta. */
+function deltaOf(chunk: Record<string, unknown> | undefined): { stream: ActivityStreamKind; text: string } | undefined {
+  if (chunk === undefined) return undefined
+  const text = chunk.text
+  if (typeof text !== 'string') return undefined
+  if (chunk.type === 'text-delta') return { stream: 'text', text }
+  if (chunk.type === 'reasoning-delta') return { stream: 'reasoning', text }
+  return undefined
+}
+
+/**
+ * Feed one live frame into any domain-event consumer.
+ *
+ * Kept as a free function so the tracker never learns a host type: the plugin
+ * subscribes to `agent/assistant-stream` and calls this.
+ * @param tracker - Consumer of normalized events.
+ * @param owner - The agent lifecycle that published the frame.
+ * @param frame - Raw frame payload.
+ */
+export function feedStreamFrame(
+  tracker: { onEvent(event: ActivityEvent): void },
+  owner: StreamOwner,
+  frame: unknown,
+): void {
+  for (const activityEvent of frameToActivityEvents(owner, frame)) tracker.onEvent(activityEvent)
+}

package/node_modules/dsh-working-activity/src/compat/session-events.ts

@@ -0,0 +1,201 @@
+/**
+ * Durable `SessionEvent` → {@link ActivityEvent} normalization.
+ *
+ * Every host-shape guess for the durable log lives here (plus
+ * `./tool-result.ts` for the tool-result payload), so a host-line change stays
+ * a one-file fix and the state machine keeps consuming meaning only.
+ *
+ * Measured on the DSH `0.1.7-rc.2` line: `assistant/chunk` no longer exists in
+ * `SessionEventMap` or in `KNOWN_SESSION_EVENT_TYPES` (live deltas arrive as
+ * transient `agent/assistant-stream` frames instead), so the mapping below is
+ * the legacy path kept for replaying older logs. It must stay: sessions
+ * written by pre-0.1.5 hosts still carry those events, and replaying them is
+ * the only way a resuming user sees the same line they would have seen live.
+ * @module @deepseek-ai/dsh-working-activity/compat/session-events
+ */
+
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
+import type { ActivityEvent, ActivityUsage } from '../activity-event.js'
+import { resultCallId, resultFailed } from './tool-result.js'
+
+/** Turn-end reason kinds that mean "the user stopped this turn". */
+const INTERRUPTED_REASONS: readonly string[] = ['aborted', 'interrupted']
+
+/**
+ * Normalize one durable session event.
+ *
+ * Returns zero events for anything the tracker does not model (including a
+ * tool result whose call id cannot be resolved — an unpaired result is
+ * dropped, never guessed at).
+ * @param event - Raw durable session event.
+ * @returns the domain events this host event carries, in order.
+ */
+export function toActivityEvents(event: SessionEvent): readonly ActivityEvent[] {
+  // `assistant/attempt` exists on the 0.1.5+ host lines only, and this package
+  // still compiles against `@deepseek-ai/dsh-session@0.1.0-rc.6`, where the
+  // member is absent from `SessionEventMap` — a literal `case` for it would not
+  // typecheck there (TS2367, no overlap). Comparing the widened string keeps one
+  // adapter serving every corridor.
+  const eventType: string = event.type
+  if (eventType === 'assistant/attempt') {
+    // A PARTIAL settlement: the durable text may be shorter than what was
+    // streamed, so provisional narration must go. The live `end` frame reports
+    // the same outcome; folding the durable event too keeps replay of logs
+    // written before (or without) frames correct. This is not an abandonment.
+    return [{ kind: 'stream-reset', at: event.time, reason: 'attempt-settled' }]
+  }
+  if (eventType === 'model/selection') {
+    // The selection the host validated for subsequent prompt assembly. Declared
+    // by the session controller's module merge, so it is absent from the
+    // rc.6-era `SessionEventMap` this package compiles against — compared as a
+    // widened string for the same reason `assistant/attempt` is.
+    //
+    // A selection without a usable model id says nothing about the route, and
+    // the tracker deduplicates repeats, so every selection is forwarded here.
+    const model = (event.data as { model?: unknown }).model
+    if (typeof model !== 'string' || model === '') return []
+    return [{ kind: 'route-change', at: event.time, model }]
+  }
+  if (eventType === 'user/message') {
+    // A compaction replaces the context with a checkpoint message; its source
+    // kind is the durable marker. The source carries no overflow flag (only the
+    // compaction id and the initiating command), so a finished compaction is
+    // all this signal can prove.
+    const data = event.data as {
+      source?: { kind?: unknown }
+      content?: unknown
+      message?: { source?: { kind?: unknown }; content?: unknown }
+    }
+    const source = data.source ?? data.message?.source
+    if (source?.kind === 'compact-checkpoint') return [{ kind: 'compaction', at: event.time }]
+    if (source?.kind !== 'user') return []
+    const content = data.content ?? data.message?.content
+    if (!Array.isArray(content)) return []
+    const first = content.find(block => block !== null && typeof block === 'object' && block.type === 'text')
+    return typeof first?.text === 'string' && first.text.trim() !== ''
+      ? [{ kind: 'user-prompt', at: event.time, text: first.text }]
+      : []
+  }
+  // The stall vocabulary (0.1.7-rc.2 `KNOWN_SESSION_EVENT_TYPES`; widened
+  // strings because the rc.6-era `SessionEventMap` this package compiles
+  // against predates them). Without these the line cannot tell "waiting on the
+  // model" from "the model is waiting on YOU".
+  if (eventType === 'llm/retry' || eventType === 'llm/retry-started') {
+    // The provider pushed back (rate limit / transient error); the host backs
+    // off before another attempt.
+    return [{ kind: 'waiting-reason', at: event.time, reason: 'retry' }]
+  }
+  if (eventType === 'approval/asked') {
+    // A tool is parked on the user's decision.
+    return [{ kind: 'waiting-reason', at: event.time, reason: 'approval' }]
+  }
+  if (eventType === 'approval/decided') {
+    return [{ kind: 'waiting-cleared', at: event.time }]
+  }
+  if (eventType === 'compaction/start') {
+    return [{ kind: 'waiting-reason', at: event.time, reason: 'compaction' }]
+  }
+  if (eventType === 'assistant/chunk') {
+    // This legacy member is absent from the current host's type union.
+    const legacy = event as unknown as { time: number; data: { chunk?: { type?: string; text?: string } } }
+    const chunk = legacy.data.chunk
+    if (chunk?.type !== 'text-delta' && chunk?.type !== 'reasoning-delta') return []
+    if (typeof chunk.text !== 'string' || chunk.text.length === 0) return []
+    return [{
+      kind: 'stream-delta',
+      at: legacy.time,
+      stream: chunk.type === 'text-delta' ? 'text' : 'reasoning',
+      text: chunk.text,
+    }]
+  }
+  switch (event.type) {
+    case 'turn/start':
+      return [{ kind: 'turn-start', at: event.time }]
+    case 'step/start':
+      return [{ kind: 'step-start', at: event.time }]
+    case 'assistant/message': {
+      const usage = event.data.usage
+      const normalized = usage === undefined ? undefined : normalizeUsage(usage)
+      const text = settledText(event.data.message)
+      return [{
+        kind: 'assistant-settled',
+        at: event.time,
+        ...(normalized === undefined ? {} : { usage: normalized }),
+        ...(text === '' ? {} : { text }),
+      }]
+    }
+    case 'tool/call':
+      return [{
+        kind: 'tool-start',
+        at: event.time,
+        callId: event.data.callId,
+        name: event.data.name,
+        arguments: event.data.arguments,
+      }]
+    case 'tool/result': {
+      const callId = resultCallId(event)
+      if (callId === undefined) return []
+      return [{ kind: 'tool-end', at: event.time, callId, failed: resultFailed(event) }]
+    }
+    case 'turn/end': {
+      const reason = event.data.reason as { kind?: unknown } | undefined
+      const interrupted = typeof reason?.kind === 'string' && INTERRUPTED_REASONS.includes(reason.kind)
+      return [{ kind: 'turn-end', at: event.time, interrupted }]
+    }
+    default:
+      return []
+  }
+}
+
+/**
+ * Feed one durable session event into any domain-event consumer.
+ *
+ * Kept as a free function so the tracker itself never learns a host type: the
+ * published `onSessionEvent` method delegates here.
+ * @param tracker - Consumer of normalized events.
+ * @param event - Raw durable session event.
+ */
+export function feedSessionEvent(
+  tracker: { onEvent(event: ActivityEvent): void },
+  event: SessionEvent,
+): void {
+  for (const activityEvent of toActivityEvents(event)) tracker.onEvent(activityEvent)
+}
+
+/** Copy the host's usage counters into the plugin's own shape. */
+function normalizeUsage(usage: {
+  inputTokens: number
+  outputTokens: number
+  cacheReadTokens?: number
+  cacheWriteTokens?: number
+}): ActivityUsage {
+  return {
+    inputTokens: usage.inputTokens,
+    outputTokens: usage.outputTokens,
+    ...(usage.cacheReadTokens === undefined ? {} : { cacheReadTokens: usage.cacheReadTokens }),
+    ...(usage.cacheWriteTokens === undefined ? {} : { cacheWriteTokens: usage.cacheWriteTokens }),
+  }
+}
+
+/**
+ * The text of a settled assistant message, concatenated from its text blocks.
+ *
+ * Structural readers only: the message shape is host data, and a message with a
+ * different shape yields '' rather than throwing (the tracker then simply has no
+ * narration for it).
+ * @param message - The event's message payload, of unknown shape.
+ * @returns the message text, or '' when it carries none.
+ */
+function settledText(message: unknown): string {
+  if (message === null || typeof message !== 'object') return ''
+  const content = (message as { content?: unknown }).content
+  if (!Array.isArray(content)) return ''
+  let text = ''
+  for (const block of content) {
+    if (block === null || typeof block !== 'object') continue
+    const record = block as { type?: unknown; text?: unknown }
+    if (record.type !== 'text' || typeof record.text !== 'string') continue
+    text += record.text
+  }
+  return text
+}

package/node_modules/dsh-working-activity/src/compat/tool-result.ts

@@ -0,0 +1,132 @@
+/**
+ * Host-payload readers for `tool/result` events — the one place allowed to know
+ * how the DSH host spells a tool-call id or a tool failure.
+ *
+ * The tracker pairs every `tool/result` with the `tool/call` that opened it by
+ * exact call-id equality, so a payload shape drift does not throw: it silently
+ * resolves no id, and the UI keeps a running tool card that never settles. That
+ * is why every shape guess lives in `src/compat/*` — a drift stays a one-file
+ * fix here — and why the state machine (`src/status.ts`) must never reach into
+ * `event.data` itself. Both readers accept `unknown` and never throw, because
+ * the caller hands over raw host events.
+ *
+ * Measured on the DSH 0.1.7-rc.2 host line over 1290 real `tool/result` events
+ * (`data.message` carries `role`, `source: { kind: 'tool', callId }`,
+ * `toolCallId`, `content`, `isError`, `id`):
+ *
+ * | id source               | present   |
+ * | ----------------------- | --------- |
+ * | `message.source.callId` | 1290/1290 |
+ * | `message.toolCallId`    | 1290/1290 |
+ * | `content[0].toolCallId` | 0/1290    |
+ *
+ * The two modern fields were equal in all 1290 events, yet both stay read: the
+ * legacy logs this plugin must still replay carry neither and put the id on the
+ * content block, which is why {@link resultCallId} keeps a third tier instead
+ * of trusting the newest shape alone.
+ *
+ * Failure signalling on the same corpus is NOT one field: `data.error` was
+ * present in 15 events and `message.isError === true` in 17, with neither set
+ * containing the other — and legacy logs used a content-block `isError`. Do not
+ * "simplify" {@link resultFailed} down to a single signal.
+ *
+ * @module @deepseek-ai/dsh-working-activity/compat/tool-result
+ */
+
+/**
+ * The call id a `tool/result` reports, or `undefined` when the payload carries
+ * no usable id. Strict precedence, never the other way round:
+ *
+ * 1. `message.source.callId` — only while `source.kind === 'tool'`, so a source
+ *    written by another producer (or an unknown future kind) never donates its
+ *    id;
+ * 2. `message.toolCallId` — the echo the measured host line writes beside it;
+ * 3. the first `content[]` block with a usable `toolCallId` — the legacy shape,
+ *    kept last so a lower tier can never override a modern one.
+ *
+ * Ids that are empty, whitespace-only, or not strings are rejected at every
+ * tier: a truthy-but-wrong id would mis-pair a result just as silently as no id
+ * at all.
+ *
+ * @param event - Raw `tool/result` event data (or any host payload).
+ * @returns the paired call id, or `undefined` when none is usable.
+ */
+export function resultCallId(event: unknown): string | undefined {
+  const message = resultMessage(event)
+  if (message === undefined) return undefined
+  const source = asRecord(message.source)
+  if (source?.kind === 'tool') {
+    const fromSource = asCallId(source.callId)
+    if (fromSource !== undefined) return fromSource
+  }
+  const fromMessage = asCallId(message.toolCallId)
+  if (fromMessage !== undefined) return fromMessage
+  for (const block of asArray(message.content) ?? []) {
+    const fromBlock = asCallId(asRecord(block)?.toolCallId)
+    if (fromBlock !== undefined) return fromBlock
+  }
+  return undefined
+}
+
+/**
+ * Whether a `tool/result` reports a failed tool.
+ *
+ * Three independent signals, OR-ed on purpose (measured 15 vs 17 events on the
+ * same corpus, and neither set contains the other — see the module header):
+ *
+ * - `data.error` present at all — presence, not truthiness, so an explicitly
+ *   `undefined` field does not count as a failure;
+ * - `message.isError === true`;
+ * - any `content[]` block with `isError === true` (the legacy signal).
+ *
+ * A payload that cannot be read is reported as healthy: a missing failure flag
+ * costs a wrong badge, while treating unreadable data as failure would flag
+ * every successful tool on a shape the host has moved on from.
+ *
+ * @param event - Raw `tool/result` event data (or any host payload).
+ * @returns true when any signal fired, false for a clean or unreadable payload.
+ */
+export function resultFailed(event: unknown): boolean {
+  const data = resultData(event)
+  if (data === undefined) return false
+  if (data.error !== undefined) return true
+  const message = asRecord(data.message)
+  if (message === undefined) return false
+  if (message.isError === true) return true
+  for (const block of asArray(message.content) ?? []) {
+    if (asRecord(block)?.isError === true) return true
+  }
+  return false
+}
+
+/** The `data` record of a host event, or `undefined` for any other shape. */
+function resultData(event: unknown): Record<string, unknown> | undefined {
+  return asRecord(asRecord(event)?.data)
+}
+
+/** The `data.message` record of a `tool/result` event, when the payload has one. */
+function resultMessage(event: unknown): Record<string, unknown> | undefined {
+  return asRecord(resultData(event)?.message)
+}
+
+/** Narrow `unknown` to a plain record: objects only, never `null`, never an array. */
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return undefined
+  return value as Record<string, unknown>
+}
+
+/** Narrow `unknown` to an array, or `undefined` for every non-array value. */
+function asArray(value: unknown): readonly unknown[] | undefined {
+  return Array.isArray(value) ? (value as readonly unknown[]) : undefined
+}
+
+/**
+ * A usable call id: a string holding at least one non-whitespace character,
+ * returned verbatim (trimming would break exact pairing against the
+ * `tool/call` id). Empty and whitespace-only strings are rejected so a junk
+ * value can never shadow a real id in a lower tier.
+ */
+function asCallId(value: unknown): string | undefined {
+  if (typeof value !== 'string') return undefined
+  return value.trim().length > 0 ? value : undefined
+}