feat(agent): add addressable queue operations

packages/core/agent/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/README.md
-README.md: 9ca79f28506b133a555bd7d1e984386c715fd9d6
-README.zh.md: 165f71f1b395bdf0c229e2c4b1a30e89347b6be1
+README.md: e71d3454d22fa829af9617083c5e68586970c70a
+README.zh.md: 76bb63afa6cf0f3690094e4c020efd7dc68505ce

packages/core/agent/README.md

@@ -60,7 +60,8 @@ Turn and step boundaries and the model token stream are durable `session/event`
 
 The handle every plugin programs against:
 
-- `agent.send(message, options)` — the one delivery primitive over the (`target` × `wakeup`) matrix. `message` is an already identified, frozen `UserMessage`; callers normally create it with `createUserMessage()` before routing begins. `SendOptions` owns only the `target` and `wakeup` policy. The agent publishes or queues the complete value as-is without minting or replacing its identity. The message's `agent/inbox/enqueue`/`dequeue`/`discard` events carry it so callers can correlate a queued item with its lifecycle; enqueue and dequeue also carry the resolved `queued | steering` placement so repeated message identities retire from the correct FIFO. `target: 'next-turn'` queues one independent FIFO item that, if admitted, becomes the sole ordinary prompt in its turn. `target: 'next-step'` with `wakeup: true` submits steering, while `target: 'next-step'` with `wakeup: false` injects durable context without running the model. The [one-send-one-turn Agent Note](../../../.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md) owns the turn rationale.
+- `agent.send(message, options)` — the one delivery primitive over the (`target` × `wakeup`) matrix. `message` is an already identified, frozen `UserMessage`; callers normally create it with `createUserMessage()` before routing begins. `SendOptions` owns only the `target` and `wakeup` policy. Each accepted FIFO occurrence receives its own `InboxItemId`, even when callers reuse a `MessageId`; `agent/inbox/enqueue`/`update` and the terminal `dequeue` or `discard` carry that complete `InboxItem`. `target: 'next-turn'` queues one independent FIFO item that, if admitted, becomes the sole ordinary prompt in its turn. `target: 'next-step'` with `wakeup: true` submits steering, while `target: 'next-step'` with `wakeup: false` injects durable context without running the model. The [one-send-one-turn Agent Note](../../../.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md) owns the turn rationale.
+- `agent.updateInbox(itemId, action)` — synchronously edits, removes, or promotes one still-pending occurrence. Edit keeps its `MessageId`, `InboxItemId`, source, placement, and FIFO position while replacing frozen content. Remove emits the occurrence's terminal discard. Promote moves it to the front of its current FIFO and makes an ordinary queued item waking. A claimed item has crossed the ownership boundary and returns `not-found`.
 - `agent.followup(input)` — the `next-turn`/wakeup preset of `send()`: queue an ordinary follow-up turn and wake the driver.
 - `agent.steer(input)` — the `next-step`/wakeup preset: during prompt admission or an open turn, stage steering for the next safe boundary without dispatching `agent/prompt-submit`; outside that acceptance window, delegate to a woken follow-up. Admission failure leaves staged steering for retry or a later admitted prompt, while cancellation or disposal may discard it.
 - `agent.inject(input)` — the `next-step`/no-wakeup preset: append model-facing context without running the model; the next request sees a verbatim user-role message whose provenance is carried by the required `input.source`. During prompt admission or an open turn, injection waits in the outbox for the next safe boundary. Outside that acceptance window, it appends immediately without opening a turn; a context-only admission batch takes this fallback if admission closes without a turn, while context staged beside steering remains pending with it. Persistence reacts to `session/event` independently. Injection emits no `agent/inbox/*` event.

packages/core/agent/README.zh.md

@@ -60,7 +60,8 @@ Agent *创建* 由实现 `AgentFactory` 的插件（`dsh-agent-loop`）提供，
 
 每个插件面向的 handle：
 
-- `agent.send(message, options)`：覆盖（`target` × `wakeup`）矩阵的唯一投递原语。`message` 是已有标识且已冻结的 `UserMessage`；调用方通常会在开始路由前使用 `createUserMessage()` 创建它。`SendOptions` 只持有 `target` 与 `wakeup` 策略。agent 会原样发布或排队完整值，不会生成或替换其标识。该消息的 `agent/inbox/enqueue`/`dequeue`/`discard` 事件会携带完整消息，调用方可据此把排队项与其生命周期关联；入队与出队事件还会携带解析出的 `queued | steering` 路由归类，使重复出现的消息标识能在正确的 FIFO 中完成结算。`target: 'next-turn'` 排队一条独立 FIFO 项，获准后成为其轮次中唯一的普通提示词。`target: 'next-step'` 且 `wakeup: true` 提交 steering（中途引导），而 `target: 'next-step'` 且 `wakeup: false` 注入持久上下文，不运行模型。轮次原理由 [one-send-one-turn Agent Note](../../../.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md)拥有。
+- `agent.send(message, options)`：覆盖（`target` × `wakeup`）矩阵的唯一投递原语。`message` 是已有标识且已冻结的 `UserMessage`；调用方通常会在开始路由前使用 `createUserMessage()` 创建它。`SendOptions` 只持有 `target` 与 `wakeup` 策略。每次获准进入 FIFO 的项都会获得独立的 `InboxItemId`，即使调用方复用了同一个 `MessageId`；`agent/inbox/enqueue`／`update` 及终态 `dequeue` 或 `discard` 都会携带这一完整 `InboxItem`。`target: 'next-turn'` 排队一条独立 FIFO 项，获准后成为其轮次中唯一的普通提示词。`target: 'next-step'` 且 `wakeup: true` 提交 steering（中途引导），而 `target: 'next-step'` 且 `wakeup: false` 注入持久上下文，不运行模型。轮次原理由 [one-send-one-turn Agent Note](../../../.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md)拥有。
+- `agent.updateInbox(itemId, action)`：同步编辑、移除或前移一个仍处于待处理状态的项。编辑会替换已冻结的内容，同时保留其 `MessageId`、`InboxItemId`、来源、放置方式与 FIFO 位置。移除会发出该项的终态 discard。前移会把它移至当前 FIFO 的队首，并使普通 queued 项能够唤醒驱动器。已被认领的项已经跨越所有权边界，因此返回 `not-found`。
 - `agent.followup(input)`：`send()` 的 `next-turn`／wakeup 预设：排队一个普通后续轮次并唤醒驱动器。
 - `agent.steer(input)`：`next-step`／wakeup 预设：提示词接纳期间或轮次打开时，为下一个安全边界暂存 steering，且不分发 `agent/prompt-submit`；该接收窗口之外则委托给会唤醒的后续轮次。接纳失败会保留暂存的 steering，以供重试或之后获准的提示词使用，而取消或 dispose 可能丢弃它。
 - `agent.inject(input)`：`next-step`／不唤醒预设：追加面向模型的上下文而不运行模型；下一次请求会看到一条逐字的 user role 消息，其来源由必填的 `input.source` 携带。提示词接纳期间或轮次打开时，注入会在 outbox 中等待下一个安全边界。该接收窗口之外，它会立即追加而不开启轮次；如果接纳结束却未开启轮次，仅含上下文的接纳批次会采用这一回退，而与 steering 一同暂存的上下文则会随其继续待处理。持久化独立地响应 `session/event`。注入不发出 `agent/inbox/*` 事件。

packages/core/agent/package.json

@@ -15,12 +15,17 @@
       "types": "./lib/types/invariant.d.ts",
       "default": "./lib/invariant.js"
     },
+    "./brand": {
+      "types": "./lib/types/brand.d.ts",
+      "default": "./lib/types/brand.js"
+    },
     "./src/*": "./src/*",
     "./package.json": "./package.json"
   },
   "files": [
     "lib/index.js",
     "lib/invariant.js",
+    "lib/types/**/*.js",
     "lib/types/**/*.d.ts",
     "lib/types/**/*.d.ts.map",
     "src"

packages/core/agent/src/brand.ts

@@ -0,0 +1,23 @@
+/**
+ * dsh-agent's owned branded ids for live inbox occurrences.
+ *
+ * @module @deepseek-ai/dsh-agent/brand
+ */
+
+import type { Branded } from '@deepseek-ai/dsh-brand'
+
+/**
+ * Identifies one accepted occurrence in an agent inbox. Re-sending the same
+ * message creates a distinct item id, so pending work remains independently
+ * addressable.
+ */
+export type InboxItemId = Branded<'InboxItemId'>
+
+/**
+ * Brand a string as an {@link InboxItemId}.
+ * @param id - the agent-loop-minted occurrence identifier.
+ * @returns the same string, branded; no validation is performed.
+ */
+export function InboxItemId(id: string): InboxItemId {
+  return id as InboxItemId
+}

packages/core/agent/src/index.ts

@@ -15,6 +15,7 @@ import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session'
 import type { Agent, AgentOptions } from './types.ts'
 
 export * from './types.ts'
+export * from './brand.ts'
 export * from './llm-target.ts'
 export { agentCarrier, agentEvents, assembleContextFor, emitAgentEvent } from './dispatch.ts'
 export type { AgentEventDispatch, AgentSubjectEvent } from './dispatch.ts'

packages/core/agent/src/types.ts

@@ -9,6 +9,7 @@ import type { Context } from 'cordis'
 import type { Scoped } from '@deepseek-ai/dsh-scope'
 import type { ContentBlock, LlmCallConfig, LlmFailure, ResolvedRetryPolicy } from '@deepseek-ai/dsh-llm'
 import type { Session, SessionId, UserMessage } from '@deepseek-ai/dsh-session'
+import type { InboxItemId } from './brand.ts'
 import type {} from '@deepseek-ai/dsh-system-prompt'
 declare module '@deepseek-ai/dsh-system-prompt' {
   interface AssembleContext {
@@ -39,6 +40,25 @@ export type SendTarget = 'next-turn' | 'next-step'
 /** Resolved inbox placement reported when an accepted message is enqueued. */
 export type InboxPlacement = 'queued' | 'steering'
 
+/** One independently addressable accepted occurrence in an agent inbox. */
+export interface InboxItem {
+  /** Agent-loop-minted occurrence identity. */
+  readonly id: InboxItemId
+  /** Identified message delivered by the caller. */
+  readonly message: UserMessage
+  /** Acceptance-time FIFO classification. */
+  readonly placement: InboxPlacement
+}
+
+/** A user-requested mutation of one still-pending inbox item. */
+export type InboxAction =
+  | { readonly kind: 'edit'; readonly content: ContentBlock[] }
+  | { readonly kind: 'remove' }
+  | { readonly kind: 'promote' }
+
+/** Result of applying an inbox action at the synchronous ownership boundary. */
+export type InboxActionResult = 'applied' | 'not-found'
+
 /**
  * Options for the unified {@link Agent.send} primitive over the
  * (`target` × `wakeup`) matrix. Named presets: {@link Agent.followup}
@@ -156,6 +176,18 @@ export interface Agent {
    */
   send(message: UserMessage, options: SendOptions): void
 
+  /**
+   * Mutate one still-pending inbox occurrence synchronously. Editing preserves
+   * the message identity and queue position; removal publishes its terminal
+   * discard; promotion moves it to the front of its current FIFO and makes a
+   * queued item waking. A driver-claimed item is no longer pending and returns
+   * `not-found`.
+   * @param id - independently addressable inbox occurrence.
+   * @param action - edit, remove, or promote operation.
+   * @returns whether the pending occurrence was found and updated.
+   */
+  updateInbox(id: InboxItemId, action: InboxAction): InboxActionResult
+
   /**
    * Clear queued and steering work — unless `keepInbox` — and abort the active
    * turn. An effective call first emits `agent/cancel-requested` with the
@@ -239,29 +271,37 @@ declare module 'cordis' {
      * acceptance-time routing result; listeners must not reconstruct it from
      * later agent or session state.
      * @param agent - the owning agent.
-     * @param message - accepted content, source, and correlation identity.
-     * @param placement - resolved queued or steering placement.
+     * @param item - accepted occurrence, message, and resolved placement.
      * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
      * @mode emit
      */
-    'agent/inbox/enqueue'(this: Scoped<Agent>, agent: Agent, message: UserMessage, placement: InboxPlacement): void
+    'agent/inbox/enqueue'(this: Scoped<Agent>, agent: Agent, item: InboxItem): void
+    /**
+     * A still-pending inbox item changed content or position. The item id and
+     * placement remain stable; edit carries the replacement message, while
+     * promote makes this occurrence first in its current FIFO.
+     * @param agent - the owning agent.
+     * @param item - the complete post-update occurrence.
+     * @param action - the applied non-terminal operation.
+     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+     * @mode emit
+     */
+    'agent/inbox/update'(
+      this: Scoped<Agent>,
+      agent: Agent,
+      item: InboxItem,
+      action: 'edit' | 'promote',
+    ): void
     /**
      * The driver claimed one item out of the inbox: a queued item at a turn
      * boundary, or steering drained between steps. Fires after the item leaves
      * its FIFO and before it becomes a durable message.
      * @param agent - the agent whose inbox item was claimed.
-     * @param message - the claimed message.
-     * @param placement - the FIFO that claimed this occurrence; together with
-     *   `message.id`, it matches the earliest outstanding enqueue in that FIFO.
+     * @param item - the exact claimed occurrence.
      * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
      * @mode emit
      */
-    'agent/inbox/dequeue'(
-      this: Scoped<Agent>,
-      agent: Agent,
-      message: UserMessage,
-      placement: InboxPlacement,
-    ): void
+    'agent/inbox/dequeue'(this: Scoped<Agent>, agent: Agent, item: InboxItem): void
     /**
      * Pending inbox items were dropped without delivering them, so every
      * enqueue occurrence receives exactly one terminal `agent/inbox/dequeue` OR
@@ -269,11 +309,11 @@ declare module 'cordis' {
      * emits this after `agent/cancel-requested` when applicable and before
      * aborting the active work. Fires once per drop with every dropped item.
      * @param agent - the agent whose inbox items were dropped.
-     * @param messages - the discarded messages in FIFO order (queued then steering); never empty.
+     * @param items - the discarded occurrences in FIFO order (queued then steering); never empty.
      * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
      * @mode emit
      */
-    'agent/inbox/discard'(this: Scoped<Agent>, agent: Agent, messages: UserMessage[]): void
+    'agent/inbox/discard'(this: Scoped<Agent>, agent: Agent, items: InboxItem[]): void
     /**
      * Effective broad cancellation was requested, before queued/outbox work
      * is cleared or the active turn is aborted. This observe-only notification

packages/core/agent/tests/agent.spec.ts

@@ -24,6 +24,7 @@ function stubAgent(rawId: string, overrides: Partial<Agent> = {}): Agent {
     acceptsNextStep: false,
     ctx: new Context(),
     send: () => {},
+    updateInbox: () => 'not-found',
     followup: () => {},
     steer: () => {},
     inject: () => {},

packages/core/agent/tests/invariant.spec.ts

@@ -1,7 +1,7 @@
 import { freezeMessage, MessageId } from '@deepseek-ai/dsh-llm'
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
-import { type Agent } from '@deepseek-ai/dsh-agent'
+import { InboxItemId, type Agent, type InboxItem, type InboxPlacement } from '@deepseek-ai/dsh-agent'
 import * as AgentInvariant from '@deepseek-ai/dsh-agent/invariant'
 import { scopeTarget } from '@deepseek-ai/dsh-scope'
 import InvariantService from '@deepseek-ai/dsh-invariants'
@@ -46,11 +46,16 @@ describe('agent status invariants', () => {
 })
 
 describe('agent inbox invariants', () => {
-  const info = () => freezeMessage({
-    id: MessageId('m'),
-    role: 'user' as const,
-    content: [],
-    source: { kind: 'user' as const },
+  let nextItem = 0
+  const info = (placement: InboxPlacement = 'queued'): InboxItem => ({
+    id: InboxItemId(`i-${nextItem++}`),
+    message: freezeMessage({
+      id: MessageId('m'),
+      role: 'user' as const,
+      content: [],
+      source: { kind: 'user' as const },
+    }),
+    placement,
   })
 
   it('accepts a dequeue and a discard covered by prior enqueues', async () => {
@@ -58,9 +63,9 @@ describe('agent inbox invariants', () => {
     const agent = mockAgent('i1')
     const at = scopeTarget(agent, agent)
     expect(() => {
-      ctx.emit(at, 'agent/inbox/enqueue', agent, info(), 'queued')
-      ctx.emit(at, 'agent/inbox/enqueue', agent, info(), 'steering')
-      ctx.emit(at, 'agent/inbox/dequeue', agent, info(), 'queued')
+      ctx.emit(at, 'agent/inbox/enqueue', agent, info())
+      ctx.emit(at, 'agent/inbox/enqueue', agent, info('steering'))
+      ctx.emit(at, 'agent/inbox/dequeue', agent, info())
       ctx.emit(at, 'agent/inbox/discard', agent, [info()])
     }).not.toThrow()
   })
@@ -68,7 +73,7 @@ describe('agent inbox invariants', () => {
   it('rejects a dequeue with no outstanding item', async () => {
     const ctx = await setup()
     const agent = mockAgent('i2')
-    expect(() => { ctx.emit(scopeTarget(agent, agent), 'agent/inbox/dequeue', agent, info(), 'queued') })
+    expect(() => { ctx.emit(scopeTarget(agent, agent), 'agent/inbox/dequeue', agent, info()) })
       .toThrow(/without a matching prior enqueue/)
   })
 
@@ -76,7 +81,7 @@ describe('agent inbox invariants', () => {
     const ctx = await setup()
     const agent = mockAgent('i3')
     const at = scopeTarget(agent, agent)
-    ctx.emit(at, 'agent/inbox/enqueue', agent, info(), 'queued')
+    ctx.emit(at, 'agent/inbox/enqueue', agent, info())
     expect(() => { ctx.emit(at, 'agent/inbox/discard', agent, [info(), info()]) })
       .toThrow(/dropped 2 items but only 1 were outstanding/)
   })