Merge remote-tracking branch 'origin/master' into feature/shared-cli-config-foundation

# Conflicts:
#	docs/event-producer-consumer.md
#	packages/host/apiproxy/README.i18n.yaml
#	tsconfig.base.json

packages/core/agent-loop/src/agent.ts

@@ -8,13 +8,18 @@
  */
 
 import type { Context } from 'cordis'
-import { agentCarrier, assembleContextFor, emitAgentEvent } from '@deepseek-ai/dsh-agent'
+import { randomUUID } from 'node:crypto'
+import { agentCarrier, assembleContextFor, emitAgentEvent, InboxItemId } from '@deepseek-ai/dsh-agent'
 import { createScope } from '@deepseek-ai/dsh-scope'
 import type { Scope } from '@deepseek-ai/dsh-scope'
 import type {
   Agent,
   CancelOptions,
   AgentInterruptReason,
+  InboxAction,
+  InboxActionResult,
+  InboxItem,
+  InboxItemId as InboxItemIdType,
   InboxPlacement,
   AgentOptions,
   AgentStatus,
@@ -55,9 +60,9 @@ type StepOutcome =
  */
 export class ReactLoopAgent implements Agent {
   /** Prompts awaiting individual turns. */
-  private queued: { message: UserMessage; wakeup: boolean }[] = []
+  private queued: { item: InboxItem; wakeup: boolean }[] = []
   /** Input taken into the session log at step boundaries. */
-  private outbox: { message: UserMessage; steering: boolean }[] = []
+  private outbox: { message: UserMessage; steering: boolean; item?: InboxItem }[] = []
 
   /** Whether observers see a running interval; consecutive turns share it. */
   private busy = false
@@ -115,16 +120,52 @@ export class ReactLoopAgent implements Agent {
     }
 
     const placement: InboxPlacement = target === 'next-step' && this.acceptsNextStep ? 'steering' : 'queued'
+    const item: InboxItem = Object.freeze({
+      id: InboxItemId(randomUUID()),
+      message,
+      placement,
+    })
     if (placement === 'steering') {
-      this.outbox.push({ message, steering: true })
+      this.outbox.push({ message, steering: true, item })
     } else {
-      this.queued.push({ message, wakeup })
+      this.queued.push({ item, wakeup })
     }
     // Preserve the routing decision for every send in this synchronous caller
     // stack, while installing quiescence ownership before enqueue observers
     // can cancel or dispose.
     if (placement === 'queued' && wakeup) this.scheduleKick()
-    emitAgentEvent(this.loopCtx, this, 'agent/inbox/enqueue', message, placement)
+    emitAgentEvent(this.loopCtx, this, 'agent/inbox/enqueue', item)
+  }
+
+  /** Apply one synchronous mutation to a still-pending queued occurrence. */
+  updateInbox(id: InboxItemIdType, action: InboxAction): InboxActionResult {
+    const queuedIndex = this.queued.findIndex(candidate => candidate.item.id === id)
+    if (queuedIndex === -1) return 'not-found'
+
+    const pending = this.queued[queuedIndex]
+    /* v8 ignore next -- the index was resolved from this array without an async boundary. */
+    if (pending === undefined) throw new Error(`agent "${this.id}" queued item disappeared during update`)
+
+    /* v8 ignore next -- InboxAction is a closed discriminated union; all variants are covered below. */
+    switch (action.kind) {
+      case 'edit': {
+        const item: InboxItem = Object.freeze({
+          ...pending.item,
+          message: freezeMessage({ ...pending.item.message, content: action.content }),
+        })
+        this.queued[queuedIndex] = { ...pending, item }
+        emitAgentEvent(this.loopCtx, this, 'agent/inbox/update', item)
+        return 'applied'
+      }
+      case 'remove': {
+        this.queued.splice(queuedIndex, 1)
+        emitAgentEvent(this.loopCtx, this, 'agent/inbox/discard', [pending.item])
+        return 'applied'
+      }
+      default:
+        /* v8 ignore next -- InboxAction is a closed discriminated union. */
+        return assertNever(action)
+    }
   }
 
   /** Queue one ordinary prompt turn and wake the driver. */
@@ -169,9 +210,9 @@ export class ReactLoopAgent implements Agent {
       if (cause.kind !== 'disposed') emitAgentEvent(this.loopCtx, this, 'agent/cancel-requested', cause)
     }
     if (!options.keepInbox) {
-      const discarded = this.queued.map(item => item.message)
+      const discarded = this.queued.map(item => item.item)
       for (const item of this.outbox) {
-        if (item.steering) discarded.push(item.message)
+        if (item.steering && item.item !== undefined) discarded.push(item.item)
       }
       // Clear before abort observers run: replacement work belongs to the next turn.
       this.queued.length = 0
@@ -222,7 +263,8 @@ export class ReactLoopAgent implements Agent {
     // The some() guard above proves the queue is non-empty; the non-null
     // assertion expresses that invariant.
     // oxlint-disable-next-line typescript/no-non-null-assertion
-    const { message } = this.queued.shift()!
+    const { item } = this.queued.shift()!
+    const { message } = item
     const inheritedOutboxLength = this.outbox.length
 
     const admission = new AbortController()
@@ -293,7 +335,7 @@ export class ReactLoopAgent implements Agent {
     // Published only after the abort owner and pending done are installed: a
     // dequeue listener that cancels or disposes must find live cancellation
     // and quiescence ownership, not the previous activity's settled state.
-    emitAgentEvent(this.loopCtx, this, 'agent/inbox/dequeue', message, 'queued')
+    emitAgentEvent(this.loopCtx, this, 'agent/inbox/dequeue', item)
   }
 
   /**
@@ -643,7 +685,9 @@ export class ReactLoopAgent implements Agent {
     for (const item of this.outbox.splice(0, limit)) {
       if (item.steering) {
         steered = true
-        emitAgentEvent(this.loopCtx, this, 'agent/inbox/dequeue', item.message, 'steering')
+        /* v8 ignore next -- only inbox-backed steer entries carry steering:true. */
+        if (item.item === undefined) throw new Error(`agent "${this.id}" steering outbox item has no inbox identity`)
+        emitAgentEvent(this.loopCtx, this, 'agent/inbox/dequeue', item.item)
         this.session.append(
           'steering/message',
           { turn, message: item.message },