Merge master into fix/subagent-stack-end-result

packages/core/agent-loop/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/core/agent-loop/README.md
-README.md: f146ea3d2cc379303514286c5cfd2833397f23ed
-README.zh.md: 767fbd420709be05e9a8f85dc8ec6fe03ae6aa66
+README.md: 2ce85071c4b7408adb4ee05291c499ec642be114
+README.zh.md: bc78c02fc046f3bb5820f89bae5a90b26b5a8ced

packages/core/agent-loop/README.md

@@ -59,7 +59,7 @@ The unified `send()` primitive routes content and source by (`target` × `wakeup
 
 `steer()` attaches a one-shot admission receipt to its exact accepted message. After `agent/step` and asynchronous prompt assembly succeed, the loop commits a stable pending batch as `steering/message`, snapshots derived history, and opens `step/start`; only then does each receipt resolve `admitted` with that turn and step. Later arrivals remain pending. Idle steering enters the ordinary FIFO and uses the first request of its eventual turn as the same admission boundary. A turn-concluding tool result, broad cancellation, disposal, or a claimed idle-steering turn that never reaches a request resolves affected receipts `rejected`; `cancel(..., { keepInbox: true })` and non-terminal routing preserve pending delivery. Open-turn `inject()` still commits after all tool results, including accepted context finalized during an interrupted batch, while steering remains provisional until a request admits it.
 
-Every FIFO acceptance mints an `InboxItemId` and publishes `agent/inbox/enqueue` with the complete occurrence. `updateInbox()` owns the synchronous queued-item boundary: edit freezes replacement content without changing message identity or position, while remove publishes discard. Edit publishes `agent/inbox/update`; steering and claimed occurrences return `not-found`. Claim publishes `agent/inbox/dequeue` and irrevocably removes the live address before prompt admission, so a racing update cannot rewrite durable history; `cancel()` without `keepInbox` publishes `agent/inbox/discard`.
+Every FIFO acceptance mints an `InboxItemId` and publishes `agent/inbox/enqueue` with the complete occurrence. `updateInbox()` owns the synchronous queued-item boundary: edit freezes replacement content without changing message identity or position, remove publishes discard, and strict steer transfers the immutable message into an open next-step window as a new steering occurrence. A closed window returns `steer-unavailable` without mutation; pending steering and claimed occurrences return `not-found`. Claim publishes `agent/inbox/dequeue` and irrevocably removes the live address before prompt admission, so a racing update cannot rewrite durable history; `cancel()` without `keepInbox` publishes `agent/inbox/discard`.
 
 ### Loop lifecycle (`agent.ts`)
 

packages/core/agent-loop/README.zh.md

@@ -59,7 +59,7 @@ interface Config {
 
 `steer()` 会把一次性准入回执附着到其准确的已接收消息。`agent/step` 和异步提示词组装成功后，循环把稳定的待处理批次提交为 `steering/message`、捕获派生历史并开启 `step/start`；只有此时，每个回执才会解析为 `admitted`，并附带轮次与步骤。之后到达的消息继续待处理。空闲 steering 会进入普通 FIFO，并以其最终轮次的首次请求作为相同准入边界。结束轮次的工具结果、广义取消、dispose（资源释放），或已领取 idle-steering 消息却从未到达请求的轮次，会把受影响回执解析为 `rejected`；`cancel(..., { keepInbox: true })` 和非终止型路由会保留待处理投递。活跃轮次内的 `inject()` 仍会在所有工具结果后提交，包括被中断批次中已最终确认的上下文；steering 则保持待准入，直到请求接纳它。
 
-每次 FIFO 接受项时都会铸造一个 `InboxItemId`，并通过 `agent/inbox/enqueue` 发布完整的单次入队项。`updateInbox()` 持有同步 queued 项边界：编辑会冻结替换内容，但不改变消息标识或位置；移除会发布 discard。编辑会发布 `agent/inbox/update`；steering 项和已被认领的项会返回 `not-found`。认领操作会发布 `agent/inbox/dequeue`，并在提示词接纳前不可逆地移除实时寻址标识，因此竞态中的更新无法改写持久历史；`cancel()` 在不带 `keepInbox` 时会发布 `agent/inbox/discard`。
+每次 FIFO 接受项时都会铸造一个 `InboxItemId`，并通过 `agent/inbox/enqueue` 发布完整的单次入队项。`updateInbox()` 持有同步 queued 项边界：编辑会冻结替换内容，但不改变消息标识或位置；移除会发布 discard；严格 steering 会把不可变消息作为新的 steering 单次入队项转移到开放的 next-step 窗口。窗口关闭时返回 `steer-unavailable`，且不做任何变更；待处理 steering 和已被认领的项会返回 `not-found`。认领操作会发布 `agent/inbox/dequeue`，并在提示词接纳前不可逆地移除实时寻址标识，因此竞态中的更新无法改写持久历史；`cancel()` 在不带 `keepInbox` 时会发布 `agent/inbox/discard`。
 
 ### 循环生命周期（`agent.ts`）
 

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

@@ -256,6 +256,27 @@ export class ReactLoopAgent implements Agent {
         emitAgentEvent(this.loopCtx, this, 'agent/inbox/discard', [pending.item])
         return 'applied'
       }
+      case 'steer': {
+        if (!this.acceptsNextStep) return 'steer-unavailable'
+        this.queued.splice(queuedIndex, 1)
+        const item: InboxItem = Object.freeze({
+          id: InboxItemId(randomUUID()),
+          message: pending.item.message,
+          placement: 'steering',
+        })
+        this.outbox.push({
+          message: item.message,
+          steering: true,
+          item,
+          ...pending.delivery === undefined ? {} : { delivery: pending.delivery },
+        })
+        // Publish the replacement only after it is owned by the outbox. Its
+        // enqueue precedes the old occurrence's discard so reentrant
+        // cancellation can terminally account for both occurrences.
+        emitAgentEvent(this.loopCtx, this, 'agent/inbox/enqueue', item)
+        emitAgentEvent(this.loopCtx, this, 'agent/inbox/discard', [pending.item])
+        return 'applied'
+      }
       default:
         /* v8 ignore next -- InboxAction is a closed discriminated union. */
         return assertNever(action)

packages/core/agent-loop/tests/contract-regressions.spec.ts

@@ -156,6 +156,106 @@ describe('addressable inbox operations', () => {
         : ''))
       .toEqual(['keep me'])
   })
+
+  it('strictly transfers a queued occurrence into the open turn', async () => {
+    const adapter = new MockAdapter([textResponse('done')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(SessionId('queue-to-steer'), { provider: 'mock', model: 'mock' })
+    const entered = Promise.withResolvers<undefined>()
+    const decision = Promise.withResolvers<{ kind: 'allow' }>()
+    ctx.on('agent/prompt-submit', async () => {
+      entered.resolve(undefined)
+      return decision.promise
+    })
+
+    const enqueued: InboxItem[] = []
+    const discarded: InboxItem[] = []
+    ctx.on('agent/inbox/enqueue', (subject, item) => {
+      if (subject === agent) enqueued.push(item)
+    })
+    ctx.on('agent/inbox/discard', (subject, items) => {
+      if (subject === agent) discarded.push(...items)
+    })
+
+    const idle = waitForIdle(ctx, agent)
+    send(agent, 'open the turn')
+    const receipt = agent.steer(createUserMessage({
+      content: [{ type: 'text', text: 'steer this message' }],
+      source: { kind: 'user' },
+    }))
+    await entered.promise
+    const queued = enqueued.find(item => inboxText(item) === 'steer this message')!
+
+    expect(agent.updateInbox(queued.id, { kind: 'steer' })).toBe('applied')
+    const steering = enqueued.find(item => item.placement === 'steering')!
+    expect(steering.id).not.toBe(queued.id)
+    expect(steering.message).toBe(queued.message)
+    expect(discarded).toEqual([queued])
+
+    decision.resolve({ kind: 'allow' })
+    await idle
+    expect(agent.session.events.flatMap(event =>
+      event.type === 'steering/message' ? [event.data.message] : [],
+    )).toEqual([queued.message])
+    expect(await receipt.outcome).toEqual({ status: 'admitted', turn: 1, step: 1 })
+    expect(agent.updateInbox(queued.id, { kind: 'steer' })).toBe('not-found')
+  })
+
+  it('keeps a queued occurrence when the next-step window is closed', () => {
+    const ctx = new Context()
+    const session = new Session(SessionId('queue-to-steer-closed'))
+    const agent = new ReactLoopAgent(ctx, session.id, {}, session)
+    const enqueued: InboxItem[] = []
+    const discarded: InboxItem[] = []
+    ctx.on('agent/inbox/enqueue', (_subject, item) => { enqueued.push(item) })
+    ctx.on('agent/inbox/discard', (_subject, items) => { discarded.push(...items) })
+
+    agent.send(
+      createUserMessage({ content: [{ type: 'text', text: 'stay queued' }], source: { kind: 'user' } }),
+      { target: 'next-turn', wakeup: false },
+    )
+    const queued = enqueued[0]!
+    expect(agent.updateInbox(queued.id, { kind: 'steer' })).toBe('steer-unavailable')
+    expect(discarded).toEqual([])
+    expect(agent.updateInbox(queued.id, { kind: 'remove' })).toBe('applied')
+  })
+
+  it('accounts for both occurrences when steering enqueue cancels reentrantly', async () => {
+    const adapter = new MockAdapter([textResponse('unused')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(SessionId('queue-to-steer-cancel'), { provider: 'mock', model: 'mock' })
+    const entered = Promise.withResolvers<undefined>()
+    const decision = Promise.withResolvers<{ kind: 'allow' }>()
+    ctx.on('agent/prompt-submit', async () => {
+      entered.resolve(undefined)
+      return decision.promise
+    })
+
+    const enqueued: InboxItem[] = []
+    const discarded: InboxItem[] = []
+    ctx.on('agent/inbox/enqueue', (subject, item) => {
+      if (subject !== agent) return
+      enqueued.push(item)
+      if (item.placement === 'steering') agent.cancel({ kind: 'user' })
+    })
+    ctx.on('agent/inbox/discard', (subject, items) => {
+      if (subject === agent) discarded.push(...items)
+    })
+
+    const idle = waitForIdle(ctx, agent)
+    send(agent, 'open the turn')
+    await entered.promise
+    send(agent, 'cancel during conversion')
+    const queued = enqueued.find(item => inboxText(item) === 'cancel during conversion')!
+
+    expect(agent.updateInbox(queued.id, { kind: 'steer' })).toBe('applied')
+    const steering = enqueued.find(item => item.placement === 'steering')!
+    expect(discarded).toEqual([steering, queued])
+
+    decision.resolve({ kind: 'allow' })
+    await idle
+    expect(agent.session.events.some(event => event.type === 'steering/message')).toBe(false)
+  })
 })
 
 describe('assistant replay provenance', () => {