Merge branch 'master' into feat/session-completed-dot

packages/client/runtime/src/client/index.ts

@@ -48,11 +48,14 @@ export type {
   AssistantTiming, CodeSubCall, CommandNode, CompactionSummaryNode, ComposerPhase,
   ContextMessageNode, ConversationNode, ConversationSnapshot, ModelRetryNode, QueuedMessage,
   RunningToolCall,
-  TodoItem, ToolResultNode, TurnErrorNode, UnknownSurfaceNode, UserMessageNode,
+  SteeringMessageNode, TodoItem, ToolResultNode, TurnErrorNode, UnknownSurfaceNode, UserMessageNode,
 } from './sessions/conversation.ts'
 export type {
   ConversationContext, ConversationContextOriginKind,
 } from './sessions/conversation-context.ts'
+export type {
+  ContextProvenanceView, ContextRole, KnownContextForm,
+} from './sessions/context-provenance.ts'
 export type {
   ConversationPromptSnapshot, RequestInspectionSnapshot, RequestPromptChange, RequestView,
 } from './sessions/request-inspection.ts'

packages/client/runtime/src/client/session-history/history-fold.ts

@@ -11,6 +11,8 @@ import type {
   PartialAssistant, RunningToolCall,
 } from '../sessions/conversation.ts'
 import { toAssistantBlocks } from '../sessions/conversation.ts'
+import { contextForm, contextProvenance } from '../sessions/context-provenance.ts'
+import { SteeringHistory } from '../sessions/steering-history.ts'
 import type {
   ConversationContext, ConversationContextOriginKind,
 } from '../sessions/conversation-context.ts'
@@ -126,6 +128,7 @@ function materializeNode(
   resultView: ToolResultView | null,
   assistantTiming: AssistantTiming | undefined,
   requestConfig: AssistantRequestConfig | undefined,
+  steering: boolean,
 ): ConversationNode {
   switch (event.type) {
     case 'user/message':
@@ -133,6 +136,15 @@ function materializeNode(
         return {
           kind: 'context', seq: event.seq, time: event.time,
           content: event.data.content, source: event.data.source,
+          provenance: contextProvenance(event.data.source),
+          form: contextForm(event.data.source),
+        }
+      }
+      if (steering) {
+        return {
+          kind: 'steering', messageId: event.data.id,
+          seq: event.seq, time: event.time,
+          content: event.data.content, source: event.data.source,
         }
       }
       return {
@@ -332,6 +344,11 @@ export function projectConversationHistory(
   entries: readonly HistoryEntry[],
 ): ConversationHistoryProjection {
   const events = entries.map(entry => entry.event)
+  const steeringHistory = new SteeringHistory()
+  const steeringSeqs = new Set<number>()
+  for (const event of events) {
+    if (steeringHistory.apply(event)) steeringSeqs.add(event.seq)
+  }
   const baseSeq = events[0]?.seq ?? 0
   const eventsBySeq = new Map(events.map(event => [event.seq, event]))
   const callIndex = new Map<string, CallIndexEntry>()
@@ -392,6 +409,7 @@ export function projectConversationHistory(
       resultViews.get(seq) ?? null,
       assistantTimings.get(seq),
       assistantRequestConfigs.get(seq),
+      steeringSeqs.has(seq),
     )
     nodeCache.set(seq, node)
     return node

packages/client/runtime/src/client/sessions/context-provenance.ts

@@ -0,0 +1,116 @@
+// Context provenance projection: the role and the human-facing producer name
+// of one logged non-user `user/message`, read from its durable `source` alone.
+// The client keeps no table of known plugin ids — a renamed or newly mounted
+// producer must never need a client release to stay identifiable, and a resumed
+// or foreign log must project the same way as a live one.
+
+/**
+ * Which model-facing role a logged non-user message plays.
+ *
+ * `recall` marks material lifted out of another session's log; `inject` marks
+ * every other producer-supplied context. Mid-turn steering is the third role
+ * the transcript distinguishes, but it has its own event and node kind
+ * (`steering/message` / `SteeringMessageNode`) and never reaches here.
+ */
+export type ContextRole = 'inject' | 'recall'
+
+/** Role and producer name presented for one logged non-user message. */
+export interface ContextProvenanceView {
+  /** The role this context plays in the model-facing conversation. */
+  role: ContextRole
+  /**
+   * Producer name for the row header, taken from the durable source: the
+   * instruction paths, the referenced session titles, the plugin id, or the
+   * bare source kind for a producer this UI version does not know. Null only
+   * when the source carries no readable kind at all.
+   */
+  label: string | null
+}
+
+/** One durable source narrowed to the readable-record shape; null for anything else. */
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : null
+}
+
+/** A record field read as a non-empty string, or null. */
+function readString(record: Record<string, unknown>, key: string): string | null {
+  const value = record[key]
+  return typeof value === 'string' && value.length > 0 ? value : null
+}
+
+/** Distinct non-empty `field` values of an array-valued source member, in first-seen order. */
+function collect(source: Record<string, unknown>, member: string, field: string): string[] {
+  const list = source[member]
+  if (!Array.isArray(list)) return []
+  const seen: string[] = []
+  for (const entry of list) {
+    const record = asRecord(entry)
+    const value = record === null ? null : readString(record, field)
+    if (value !== null && !seen.includes(value)) seen.push(value)
+  }
+  return seen
+}
+
+/** A collected name list rendered as one label; null when the list is empty. */
+function joined(names: string[]): string | null {
+  return names.length > 0 ? names.join(', ') : null
+}
+
+/**
+ * Project one durable message source onto its transcript role and producer name.
+ *
+ * The source arrives over the wire as opaque JSON (`MessageSource` is
+ * merge-extensible, so no client-side union can be exhaustive), and a durable
+ * log may predate or postdate this UI; every unreadable shape therefore
+ * degrades to `inject` with whatever name the record still carries.
+ * @param source - the logged `user/message` source, exactly as recorded.
+ * @returns the role and producer name to present for this context.
+ */
+export function contextProvenance(source: unknown): ContextProvenanceView {
+  const record = asRecord(source)
+  const kind = record === null ? null : readString(record, 'kind')
+  if (record === null || kind === null) return { role: 'inject', label: null }
+  switch (kind) {
+    // Cross-session snapshots are the one durable source that carries another
+    // session's material; its references name the sessions they were read from.
+    case 'session-reference':
+      return { role: 'recall', label: joined(collect(record, 'references', 'label')) ?? kind }
+    // Workspace instructions name the files they were reconciled from, which
+    // identifies the producer far better than the plugin id would.
+    case 'workspace-instructions':
+      return { role: 'inject', label: joined(collect(record, 'changes', 'path')) ?? kind }
+    case 'plugin':
+      return { role: 'inject', label: readString(record, 'plugin') ?? kind }
+    // Documented default arm of the merge-extensible source map: an unknown
+    // producer still identifies itself by its own durable kind.
+    default:
+      return { role: 'inject', label: kind }
+  }
+}
+
+/**
+ * Context forms this UI version renders with a dedicated presentation. The
+ * durable vocabulary (`ContextForm` in `dsh-llm`) may already be wider — an
+ * unrecognized or absent value degrades to the opaque presentation rather than
+ * dropping the row, so a log written by a newer or foreign producer still
+ * renders.
+ */
+const KNOWN_FORMS = ['instructions', 'catalog', 'snapshot', 'notice', 'relay', 'recall'] as const
+
+/** One durable context form this UI version knows how to present. */
+export type KnownContextForm = typeof KNOWN_FORMS[number]
+
+/**
+ * Read the producer-declared form off one durable message source.
+ * @param source - the logged `user/message` source, exactly as recorded.
+ * @returns the form when this UI version presents it, otherwise null (opaque).
+ */
+export function contextForm(source: unknown): KnownContextForm | null {
+  const record = asRecord(source)
+  const form = record === null ? null : readString(record, 'form')
+  return form !== null && (KNOWN_FORMS as readonly string[]).includes(form)
+    ? form as KnownContextForm
+    : null
+}

packages/client/runtime/src/client/sessions/conversation.ts

@@ -12,6 +12,7 @@ import type {
   RpcError, SessionId, SubagentAddress, ToolCallView, ToolResultView,
 } from '@deepseek-ai/dsh-client-connection/client'
 import type { PendingInteraction } from './pending.ts'
+import type { ContextProvenanceView, KnownContextForm } from './context-provenance.ts'
 export type { TodoItem }
 
 /** Request configuration recorded for one provider call. */
@@ -102,6 +103,18 @@ export interface AssistantMessageNode {
   interrupted?: true
 }
 
+/** A human message admitted from the next-step inbox while a turn was running. */
+export interface SteeringMessageNode {
+  kind: 'steering'
+  /** Stable message identity shared with its pre-admission inbox occurrence. */
+  messageId: MessageId
+  seq: number
+  /** Unix epoch ms from the source session event. */
+  time: number
+  content: readonly ContentBlock[]
+  source: unknown
+}
+
 /** A context/system injection surfaced in the flow. */
 export interface ContextMessageNode {
   kind: 'context'
@@ -110,6 +123,10 @@ export interface ContextMessageNode {
   time: number
   content: readonly ContentBlock[]
   source: unknown
+  /** Role and producer name projected from `source` ({@link contextProvenance}). */
+  provenance: ContextProvenanceView
+  /** Producer-declared information form ({@link contextForm}); null presents as opaque. */
+  form: KnownContextForm | null
 }
 
 /** Durable notice that a closed failed step is waiting for a model-request retry. */
@@ -223,6 +240,7 @@ export interface CommandNode {
 export type ConversationNode =
   | UserMessageNode
   | AssistantMessageNode
+  | SteeringMessageNode
   | ContextMessageNode
   | ModelRetryNode
   | TurnErrorNode

packages/client/runtime/src/client/sessions/steering-history.ts

@@ -0,0 +1,65 @@
+/** Reconstruct durable steering identity from the event-sourced agent inbox. */
+
+import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
+
+type InboxTarget = 'next-turn' | 'next-step'
+
+/** Minimal pending identity retained while replaying durable inbox splices. */
+interface PendingIdentity {
+  readonly id: string
+}
+
+/** Client-side structural view of the host-owned inbox event. */
+interface InboxSplice {
+  readonly target: InboxTarget
+  readonly start: number
+  readonly removedCount?: number
+  readonly inserted: readonly PendingIdentity[]
+  readonly outcome?: 'canceled'
+}
+
+/**
+ * Incrementally identifies `user/message` events claimed from the next-step
+ * inbox. The agent loop records all admitted input as `user/message`; the
+ * preceding `agent/inbox/spliced` events preserve whether it came from the
+ * queued-turn list or the next-step list.
+ */
+export class SteeringHistory {
+  private readonly inbox: Record<InboxTarget, PendingIdentity[]> = {
+    'next-turn': [],
+    'next-step': [],
+  }
+
+  private readonly claimedNextStep = new Set<string>()
+
+  /** Clear all replay state before rebuilding a history window. */
+  reset(): void {
+    this.inbox['next-turn'] = []
+    this.inbox['next-step'] = []
+    this.claimedNextStep.clear()
+  }
+
+  /**
+   * Apply one event and report whether it is a durable human steering message.
+   * @param event - next raw session event in sequence order.
+   * @returns true only for a user-origin message previously claimed from `next-step`.
+   */
+  apply(event: SessionEvent): boolean {
+    if ((event.type as string) === 'agent/inbox/spliced') {
+      this.applySplice(event.data as unknown as InboxSplice)
+      return false
+    }
+    if (event.type !== 'user/message') return false
+    const id = event.data.id
+    if (!this.claimedNextStep.delete(id)) return false
+    return event.data.source.kind === 'user'
+  }
+
+  /** Replay one host-validated inbox splice. */
+  private applySplice({ target, start, removedCount = 0, inserted, outcome }: InboxSplice): void {
+    const removed = this.inbox[target].splice(start, removedCount, ...inserted)
+    for (const identity of inserted) this.claimedNextStep.delete(identity.id)
+    if (target !== 'next-step' || outcome === 'canceled') return
+    for (const identity of removed) this.claimedNextStep.add(identity.id)
+  }
+}

packages/client/runtime/src/client/sessions/transcript-adapter.ts

@@ -22,6 +22,8 @@ import type { COMPACT_CHECKPOINT_SOURCE } from '@deepseek-ai/dsh-compact/checkpo
 import type { ToolCallView, ToolEventView, ToolResultView } from '@deepseek-ai/dsh-client-connection/client'
 import type { CommandNode, CompactionSummaryNode, ConversationNode } from './conversation.ts'
 import { toAssistantBlocks } from './conversation.ts'
+import { contextForm, contextProvenance } from './context-provenance.ts'
+import { SteeringHistory } from './steering-history.ts'
 import type { AssistantStepMetadata } from './assistant-timing.ts'
 import { indexAssistantStepTiming, settledAssistantTiming } from './assistant-timing.ts'
 
@@ -46,11 +48,12 @@ interface CallIndexEntry {
   callView: ToolCallView | null
 }
 
-/** One event -> UI node (pure function; the eight-variant ConversationNode union). */
+/** One event -> UI node (pure function; the ten-variant ConversationNode union). */
 function materializeNode(
   event: SessionEvent,
   callIndex: ReadonlyMap<string, CallIndexEntry>,
   resultView: ToolResultView | null,
+  steering: boolean,
   stepTimings: ReadonlyMap<string, AssistantStepMetadata>,
 ): ConversationNode {
   switch (event.type) {
@@ -62,6 +65,15 @@ function materializeNode(
         return {
           kind: 'context', seq: event.seq, time: event.time,
           content: event.data.content, source: event.data.source,
+          provenance: contextProvenance(event.data.source),
+          form: contextForm(event.data.source),
+        }
+      }
+      if (steering) {
+        return {
+          kind: 'steering', messageId: event.data.id,
+          seq: event.seq, time: event.time,
+          content: event.data.content, source: event.data.source,
         }
       }
       return {
@@ -178,6 +190,8 @@ export class TranscriptAdapter {
   private stepTimings = new Map<string, AssistantStepMetadata>()
   /** Wire result views keyed by the tool/result event's seq (views ride the envelope, not the event). */
   private resultViews = new Map<number, ToolResultView>()
+  /** Durable inbox replay used to distinguish next-step human input from queued prompts. */
+  private readonly steeringHistory = new SteeringHistory()
   /**
    * Command lifecycle nodes by commandId (insertion = run order). The
    * `command/run`/`command/done` pair is log-only, so it is not a surface
@@ -206,6 +220,8 @@ export class TranscriptAdapter {
     this.callIdx = new Map()
     this.resultViews.clear()
     this.commandIdx = new Map()
+    this.steeringHistory.reset()
+    const steeringSeqs = new Set<number>()
     this.stepTimings = new Map()
     for (let i = 0; i < events.length; i++) {
       const event = events[i]
@@ -214,13 +230,14 @@ export class TranscriptAdapter {
       this.eventIndex.set(event.seq, event)
       this.indexCall(event, views?.[i])
       this.indexCommand(event)
+      if (this.steeringHistory.apply(event)) steeringSeqs.add(event.seq)
       indexAssistantStepTiming(this.stepTimings, event)
     }
     // Indexes first, then project: a tool/result materializes against the
     // complete call index, and a checkpoint against the complete event index.
     const projected: ConversationNode[] = []
     for (const event of events) {
-      if (isTranscriptEvent(event)) projected.push(this.materialize(event))
+      if (isTranscriptEvent(event)) projected.push(this.materialize(event, steeringSeqs.has(event.seq)))
     }
     this.projected = projected
   }
@@ -237,10 +254,11 @@ export class TranscriptAdapter {
   append(event: SessionEvent, view?: ToolEventView): void {
     this.eventIndex.set(event.seq, event)
     this.indexCall(event, view)
+    const steering = this.steeringHistory.apply(event)
     indexAssistantStepTiming(this.stepTimings, event)
     if (this.indexCommand(event)) this.rev++
     if (!isTranscriptEvent(event)) return
-    this.projected = [...this.projected, this.materialize(event)]
+    this.projected = [...this.projected, this.materialize(event, steering)]
     this.rev++
   }
 
@@ -273,10 +291,16 @@ export class TranscriptAdapter {
   }
 
   /** Materialize one transcript event against the complete current indexes. */
-  private materialize(event: SessionEvent): ConversationNode {
+  private materialize(event: SessionEvent, steering: boolean): ConversationNode {
     return isCompactCheckpoint(event)
       ? materializeCompaction(event, this.eventIndex)
-      : materializeNode(event, this.callIdx, this.resultViews.get(event.seq) ?? null, this.stepTimings)
+      : materializeNode(
+        event,
+        this.callIdx,
+        this.resultViews.get(event.seq) ?? null,
+        steering,
+        this.stepTimings,
+      )
   }
 
   /**