refactor(agent): scope queue actions to edit and remove

packages/host/apiproxy/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/host/apiproxy/README.md
-README.md: c6f9ffae399b9d88b354b3312e36fe05b2d38a63
-README.zh.md: 59f31e521c5432dcf2ba64972b6b0d0e87988b23
+README.md: e4a29dc288d7279366c2a28ed43573792979aa92
+README.zh.md: 9f5eb0c4f84eb909d931dda8cbac764bf83aa2fe

packages/host/apiproxy/README.md

@@ -16,7 +16,7 @@ Session titles ride the generic projection pair like every other domain — the
 
 Session model routing is a session-domain contract. `session.models` returns the selected provider/model/reasoning target with provider-grouped advisory models, exact-route reasoning metadata, and provider-local lookup failures. `session.selectModel` validates the optional adapter-owned reasoning effort and replaces the complete target selected for the next prompt-assembly boundary. Catalog membership is not validation: an adapter may resolve an unlisted model, while an unavailable route or unsupported effort returns `model-unavailable`.
 
-Pending agent input is a live control-plane contract, not session history. The gateway mirrors complete `InboxItem` occurrences from `agent/inbox/*` and broadcasts authoritative `session/queue` snapshots on every change and reconnect. `session.updateQueue` addresses one `InboxItemId`: edit replaces pending content, remove discards it, and promote moves it to the front of its current FIFO while waking ordinary queued work. A driver claim wins races by retiring the address before admission; a later operation returns `queue-item-not-found`. The client never infers retirement from turn or status events.
+Pending queued input is a live control-plane contract, not session history. The gateway mirrors queued `InboxItem` occurrences from `agent/inbox/*` and broadcasts authoritative `session/queue` snapshots on every queued change and reconnect; pending steering stays outside this Web projection. `session.updateQueue` addresses one `InboxItemId`: edit replaces pending content and remove discards it. A driver claim wins races by retiring the address before admission; a later operation returns `queue-item-not-found`. The client never infers retirement from turn or status events.
 
 Workspace and Session lists are separate reconnect baselines. `workspace.create` creates a unique name or adopts an existing directory, `workspace.delete` removes only the Workspace registration, `session.create` accepts an optional preallocated Session id, and `host/workspace-changed`, `host/workspace-removed`, plus `host/session-added` carry committed increments in either arrival order. Registration deletion preserves the directory and session logs; its Sessions remain in `session.list` and become Ungrouped. `SessionSummary.blank` and the `host/session-added` frame carry the derived zero-events bit: clients hide blank sessions and reuse them per workspace, flip blank on the first `host/session-status(running:true)`, and treat `session.list` as the reconnect authority; cold summaries are never blank because lazy persistence keeps never-appended sessions out of `list()`.
 

packages/host/apiproxy/README.zh.md

@@ -16,7 +16,7 @@
 
 会话模型路由属于会话领域契约。`session.models` 返回选中的提供方／模型／推理（reasoning）目标，以及按提供方分组的建议性模型、精确路由推理元数据和逐提供方查询失败记录。`session.selectModel` 校验由适配器持有的可选推理强度，并替换将在下一提示词组装边界使用的完整目标。目录成员关系不构成校验：适配器可以解析未列出的模型，而不可用路由或不受支持的推理强度会返回 `model-unavailable`。
 
-待处理 agent 输入属于实时控制平面契约，而非会话历史。网关镜像来自 `agent/inbox/*` 的完整 `InboxItem` 单次入队项，并在每次变更和重连时广播权威的 `session/queue` 快照。`session.updateQueue` 通过 `InboxItemId` 寻址单个项：编辑会替换待处理内容，移除会将其丢弃，前移会把它移至当前 FIFO 的队首，并使普通 queued 工作能够唤醒驱动器。驱动器在接纳前退役寻址标识，因此认领会赢得竞态；之后的操作返回 `queue-item-not-found`。客户端绝不根据轮次或状态事件推断项已退役。
+待处理的 queued 输入属于实时控制平面契约，而非会话历史。网关镜像来自 `agent/inbox/*` 的 queued `InboxItem` 入队项，并在每次 queued 变更和重连时广播权威的 `session/queue` 快照；待处理 steering（中途引导）不进入此 Web 投影。`session.updateQueue` 通过 `InboxItemId` 寻址单个项：编辑会替换待处理内容，移除会将其丢弃。驱动器在接纳前退役寻址标识，因此认领会赢得竞态；之后的操作返回 `queue-item-not-found`。客户端绝不根据轮次或状态事件推断项已退役。
 
 Workspace 列表与 Session 列表是相互独立的重连基线。`workspace.create` 会创建唯一名称或接纳现有目录，`workspace.delete` 只移除 Workspace 注册记录，`session.create` 接受可选的预分配 Session id，`host/workspace-changed`、`host/workspace-removed` 与 `host/session-added` 则以任意到达顺序携带已提交的增量。删除注册记录会保留目录和会话日志；相关 Session 仍留在 `session.list` 中，并进入 Ungrouped。`SessionSummary.blank` 与 `host/session-added` 帧携带派生的零事件位：客户端隐藏空白会话并按 workspace 复用它们，在首个 `host/session-status(running:true)` 时翻转 blank，并以 `session.list` 作为重连权威；冷会话摘要永远不是空白：惰性持久化让从未追加过事件的会话根本不出现在 `list()` 中。
 

packages/host/apiproxy/src/api-proxy.ts

@@ -508,9 +508,9 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
   })
 
   /**
-   * Per-session inbox occurrence mirror serving the mux-open queue snapshot
+   * Per-session queued-occurrence mirror serving the mux-open queue snapshot
    * (the same refresh-recovery baseline as pending questions). Each terminal
-   * inbox event retires one matching occurrence, so repeated sends of the same
+   * queue event retires one matching occurrence, so repeated sends of the same
    * identified message remain visible until every occurrence is claimed.
    */
   const queuedMirror = new Map<SessionId, InboxItem[]>()
@@ -522,7 +522,6 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
       items: items.map(item => ({
         id: item.id,
         message: item.message,
-        placement: item.placement,
       })),
     })
   }
@@ -531,12 +530,14 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
       const entries = queuedMirror.get(agent.id)
       if (entries === undefined) return
       const index = entries.findIndex(entry => entry.id === item.id)
-      if (index !== -1) entries.splice(index, 1)
+      if (index === -1) return
+      entries.splice(index, 1)
       if (entries.length === 0) queuedMirror.delete(agent.id)
       publishQueue(agent.id)
     }
     const disposers = [
       ctx.on('agent/inbox/enqueue', (agent: Agent, item: InboxItem) => {
+        if (item.placement !== 'queued') return
         let entries = queuedMirror.get(agent.id)
         if (entries === undefined) {
           entries = []
@@ -545,18 +546,12 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
         entries.push(item)
         publishQueue(agent.id)
       }),
-      ctx.on('agent/inbox/update', (agent: Agent, item: InboxItem, action) => {
+      ctx.on('agent/inbox/update', (agent: Agent, item: InboxItem) => {
         const entries = queuedMirror.get(agent.id)
         if (entries === undefined) return
         const index = entries.findIndex(entry => entry.id === item.id)
         if (index === -1) return
-        entries.splice(index, 1)
-        if (action === 'promote') {
-          const first = entries.findIndex(entry => entry.placement === item.placement)
-          entries.splice(first === -1 ? entries.length : first, 0, item)
-        } else {
-          entries.splice(index, 0, item)
-        }
+        entries.splice(index, 1, item)
         publishQueue(agent.id)
       }),
       ctx.on('agent/inbox/dequeue', (agent: Agent, item: InboxItem) => {
@@ -567,6 +562,7 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
         if (entries === undefined) return
         const ids = new Set(items.map(item => item.id))
         const kept = entries.filter(entry => !ids.has(entry.id))
+        if (kept.length === entries.length) return
         if (kept.length === 0) queuedMirror.delete(agent.id)
         else queuedMirror.set(agent.id, kept)
         publishQueue(agent.id)
@@ -1540,7 +1536,6 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
             items: items.map(item => ({
               id: item.id,
               message: item.message,
-              placement: item.placement,
             })),
           }))
         }

packages/host/apiproxy/src/api/events.schema.ts

@@ -50,7 +50,6 @@ export const muxFrameSchema = z.discriminatedUnion('type', [
     items: z.array(z.object({
       id: inboxItemIdSchema,
       message: messageSchema,
-      placement: z.union([z.literal('queued'), z.literal('steering')]),
     })),
   }),
   // value stays wide: it already passed its unit's own schema on the host,

packages/host/apiproxy/src/api/events.ts

@@ -32,14 +32,12 @@ export type ToolEventView =
   | { for: 'call'; view: ToolCallView }
   | { for: 'result'; view: ToolResultView }
 
-/** One pending inbox occurrence in an authoritative queue snapshot. */
+/** One pending queued occurrence in an authoritative queue snapshot. */
 export interface QueuedInboxItem {
   /** Agent-owned occurrence identity used by queue mutations. */
   id: InboxItemId
   /** Complete pending message; it is not durable until the Agent claims it. */
   message: Message
-  /** Acceptance-time FIFO classification. */
-  placement: 'queued' | 'steering'
 }
 
 /** Streaming face of the contract: the two SSE stream openers (mux + host). */
@@ -73,10 +71,11 @@ export type MuxFrame =
   | { type: 'question/requested'; sessionId: SessionId; questions: AskUserQuestionItem[] }
   | { type: 'question/resolved'; sessionId: SessionId; questionRpcId: RpcId; outcome: 'answered' | 'cancelled' }
   /**
-   * Complete transient inbox state after every enqueue, mutation, claim, or
+   * Complete transient queue state after every enqueue, mutation, claim, or
    * discard. Pending work is not model-visible and therefore has no durable
-   * session event; the whole snapshot makes edit, reorder, deletion, cancel,
-   * and reconnect converge through one authoritative signal.
+   * session event; the whole snapshot makes edit, deletion, cancel, and
+   * reconnect converge through one authoritative signal. Pending steering is
+   * outside this Web queue projection.
    */
   | { type: 'session/queue'; sessionId: SessionId; items: QueuedInboxItem[] }
   /**

packages/host/apiproxy/src/api/sessions.schema.ts

@@ -225,7 +225,6 @@ export const sessionUpdateQueueRequestSchema = z.object({
   action: z.discriminatedUnion('kind', [
     z.object({ kind: z.literal('edit'), content: z.array(contentBlockSchema) }),
     z.object({ kind: z.literal('remove') }),
-    z.object({ kind: z.literal('promote') }),
   ]),
 }) as unknown as z.ZodType<RequestPayload<'session.updateQueue'>>
 

packages/host/apiproxy/src/api/sessions.ts

@@ -129,7 +129,6 @@ export interface SessionModels {
 export type QueueAction =
   | { kind: 'edit'; content: ContentBlock[] }
   | { kind: 'remove' }
-  | { kind: 'promote' }
 
 /** Session list entry (v1 builds no index: list does readdir+stat). */
 export interface SessionSummary {
@@ -237,9 +236,7 @@ export interface SessionsApi {
   Promise<RpcResponse<{ accepted: true; command?: { kind: 'success'; text?: string } }>>
 
   /**
-   * Edits, removes, or promotes one pending inbox occurrence. Promotion means
-   * first in its current FIFO; a queued item is also made waking, so an idle
-   * agent starts it and a running agent takes it as the next independent turn.
+   * Edits or removes one pending queued occurrence.
    */
   updateQueue(request: RpcRequest<{ sessionId: SessionId; itemId: InboxItemId; action: QueueAction }>):
   Promise<RpcResponse<{ accepted: true }>>

packages/host/apiproxy/tests/api-proxy-commands.spec.ts

@@ -295,7 +295,7 @@ describe('session.updateQueue', () => {
       payload: {
         sessionId: agent.id,
         itemId: InboxItemId('present'),
-        action: { kind: 'promote' },
+        action: { kind: 'edit', content: [{ type: 'text', text: 'edited' }] },
       },
     })
     expect(expectOk(applied)).toEqual({ accepted: true })
@@ -309,7 +309,7 @@ describe('session.updateQueue', () => {
     })
     expect(expectErr(missing)).toMatchObject({ code: 'queue-item-not-found' })
     expect(seen).toEqual([
-      { id: 'present', action: { kind: 'promote' } },
+      { id: 'present', action: { kind: 'edit', content: [{ type: 'text', text: 'edited' }] } },
       { id: 'claimed', action: { kind: 'remove' } },
     ])
   })
@@ -322,8 +322,8 @@ describe('session/queue frames', () => {
     const agent = stubAgent(ctx)
     const live = new AbortController()
     const liveStream = api.events.mux({ rpcId: RpcId('t-mux-live'), payload: {} }, live.signal)
-    // subscribed baseline + 2 queue snapshots
-    const liveCollected = collect<MuxFrame>(liveStream, 3, live)
+    // subscribed baseline + one queued snapshot; pending steering stays off this wire.
+    const liveCollected = collect<MuxFrame>(liveStream, 2, live)
 
     const queued = inboxItem('i-1', inboxMessage('m-1', 'queued prompt'), 'queued')
     const steering = inboxItem('i-2', inboxMessage('m-2', 'steering prompt'), 'steering')
@@ -332,40 +332,41 @@ describe('session/queue frames', () => {
 
     const liveFrames = (await liveCollected).filter(f => f.type === 'session/queue')
     expect(liveFrames).toEqual([
-      { type: 'session/queue', sessionId: agent.id, items: [queued] },
-      { type: 'session/queue', sessionId: agent.id, items: [queued, steering] },
+      {
+        type: 'session/queue',
+        sessionId: agent.id,
+        items: [{ id: queued.id, message: queued.message }],
+      },
     ])
 
     // A fresh mux connection replays only the current authoritative snapshot.
     const replay = new AbortController()
     const replayFrames = await collect<MuxFrame>(
       api.events.mux({ rpcId: RpcId('t-mux-replay'), payload: {} }, replay.signal), 2, replay)
-    expect(replayFrames.filter(f => f.type === 'session/queue')).toEqual([liveFrames[1]])
+    expect(replayFrames.filter(f => f.type === 'session/queue')).toEqual([liveFrames[0]])
   })
 
-  it('publishes edit and promotion in the authoritative order', async () => {
+  it('publishes edits in place in the authoritative order', async () => {
     const ctx = await harness()
     const api = createApiProxy(ctx, DEFAULTS)
     const agent = stubAgent(ctx)
     const abort = new AbortController()
     const collected = collect<MuxFrame>(
-      api.events.mux({ rpcId: RpcId('t-mux-updates'), payload: {} }, abort.signal), 6, abort)
+      api.events.mux({ rpcId: RpcId('t-mux-updates'), payload: {} }, abort.signal), 5, abort)
     const first = inboxItem('i-a', inboxMessage('m-a', 'a'), 'queued')
     const second = inboxItem('i-b', inboxMessage('m-b', 'b'), 'queued')
     const edited = inboxItem('i-b', inboxMessage('m-b', 'b edited'), 'queued')
     ctx.emit('agent/inbox/enqueue', agent, first)
     ctx.emit('agent/inbox/enqueue', agent, second)
-    ctx.emit('agent/inbox/update', agent, edited, 'edit')
-    ctx.emit('agent/inbox/update', agent, edited, 'promote')
+    ctx.emit('agent/inbox/update', agent, edited)
     ctx.emit('agent/inbox/dequeue', agent, edited)
 
     const frames = (await collected).filter(frame => frame.type === 'session/queue')
     expect(frames.map(frame => frame.items)).toEqual([
-      [first],
-      [first, second],
-      [first, edited],
-      [edited, first],
-      [first],
+      [{ id: first.id, message: first.message }],
+      [{ id: first.id, message: first.message }, { id: second.id, message: second.message }],
+      [{ id: first.id, message: first.message }, { id: edited.id, message: edited.message }],
+      [{ id: first.id, message: first.message }],
     ])
   })
 

packages/host/apiproxy/tests/rpc-schemas.spec.ts

@@ -232,7 +232,7 @@ describe('sessions domain schemas', () => {
       sessionId: 's1', itemId: 'i1', action: { kind: 'remove' },
     }).action.kind).toBe('remove')
     expect(() => sessionUpdateQueueRequestSchema.parse({
-      sessionId: 's1', itemId: '', action: { kind: 'promote' },
+      sessionId: 's1', itemId: 'i1', action: { kind: 'promote' },
     })).toThrow()
     expect(sessionCancelValueSchema.parse({ accepted: true }).accepted).toBe(true)
     expect(sessionUpdateQueueValueSchema.parse({ accepted: true }).accepted).toBe(true)
@@ -380,8 +380,7 @@ describe('events frame schemas', () => {
       { type: 'question/requested', sessionId: 's', questions: [{ id: 'q', question: 'Q?', options: [{ label: 'L' }], multiSelect: true }] },
       { type: 'question/resolved', sessionId: 's', questionRpcId: 'r', outcome: 'answered' },
       { type: 'session/queue', sessionId: 's', items: [
-        { id: 'i1', message: { id: 'm1', role: 'user', content: [{ type: 'text', text: 'queued prompt' }], source: { kind: 'user', rpcId: 'r9' } }, placement: 'queued' },
-        { id: 'i2', message: { id: 'm2', role: 'user', content: [{ type: 'text', text: 'steer' }], source: { kind: 'user' } }, placement: 'steering' },
+        { id: 'i1', message: { id: 'm1', role: 'user', content: [{ type: 'text', text: 'queued prompt' }], source: { kind: 'user', rpcId: 'r9' } } },
       ] },
       { type: 'session/projection', sessionId: 's', key: 'todos', value: [{ content: 'x', status: 'pending' }], seq: 7 },
       { type: 'stream/error', error: { code: 'internal', message: 'm', details: {} } },
@@ -402,8 +401,8 @@ describe('events frame schemas', () => {
 
   it('rejects a queue snapshot with malformed items', () => {
     expect(() => muxFrameSchema.parse({ type: 'session/queue', sessionId: 's', items: 'x' })).toThrow()
-    expect(() => muxFrameSchema.parse({ type: 'session/queue', sessionId: 's', items: [{ id: '', message: {}, placement: 'queued' }] })).toThrow()
-    expect(() => muxFrameSchema.parse({ type: 'session/queue', sessionId: 's', items: [{ id: 'i', message: { id: 'm', role: 'user', content: [], source: {} }, placement: 'later' }] })).toThrow()
+    expect(() => muxFrameSchema.parse({ type: 'session/queue', sessionId: 's', items: [{ id: '', message: {} }] })).toThrow()
+    expect(() => muxFrameSchema.parse({ type: 'session/queue', sessionId: 's', items: [{ id: 'i', message: { id: 'm', role: 'user', content: [], source: {} } }] })).toThrow()
   })
 
   it('accepts every host frame branch', () => {