feat(agent): rename InboxItemInfo to AgentMessage with an id; send returns it

Add a branded AgentMessageId assigned to each accepted send message and
returned from send/followup/steer/inject (was void). Rename the inbox
event payload InboxItemInfo to AgentMessage, carrying that id so a caller
can correlate a queued item with its enqueue/dequeue/discard events.

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

@@ -6,15 +6,16 @@
  * @module dsh-agent-loop/agent
  */
 
+import { randomUUID } from 'node:crypto'
 import type { Context } from 'cordis'
-import { agentEvents } from '@deepseek-ai/dsh-agent'
+import { agentEvents, AgentMessageId } from '@deepseek-ai/dsh-agent'
 import { Agent } from '@deepseek-ai/dsh-agent'
 import type { AgentCancelCause, AgentOptions, AgentStatus, CancelOptions, HookContext, SendOptions } from '@deepseek-ai/dsh-agent'
 import { deepFreeze, errorChain } from '@deepseek-ai/dsh-llm'
 import type { ContentBlock, MessageSource } from '@deepseek-ai/dsh-llm'
 import { snapshotJsonValue, type Session, type SessionId } from '@deepseek-ai/dsh-session'
 import { DISPOSED_INTERRUPT_REASON, TurnCancellation } from './cancellation.ts'
-import { Inbox, inboxInfo, type InboxMessage } from './inbox.ts'
+import { Inbox, agentMessage, type InboxMessage } from './inbox.ts'
 import { isTurnOpen, lastTurnNumber, runLoop } from './loop.ts'
 
 /** Sessions already claimed by a concrete driver construction. */
@@ -196,9 +197,11 @@ export class ReactLoopAgent extends Agent {
    * materialization reads every nested field once; deep freeze prevents later
    * caller mutation before an inbox or deferred-injection queue drains it.
    */
-  private acceptMessage(content: ContentBlock[], source: MessageSource, wakeup: boolean, options?: SendOptions): InboxMessage {
+  private acceptMessage(
+    id: AgentMessageId, content: ContentBlock[], source: MessageSource, wakeup: boolean, options?: SendOptions,
+  ): InboxMessage {
     const contexts = options?.contexts ?? []
-    const accepted = snapshotJsonValue({ content, source, contexts, wakeup })
+    const accepted = snapshotJsonValue({ id, content, source, contexts, wakeup })
     if (accepted === undefined) {
       throw new TypeError('agent message content, source, and contexts must be losslessly JSON-serializable')
     }
@@ -219,23 +222,25 @@ export class ReactLoopAgent extends Agent {
     if (this._status === 'disposed') throw new Error(`agent "${this.id}" is disposed`)
   }
 
-  send(content: ContentBlock[], options?: SendOptions): void {
+  send(content: ContentBlock[], options?: SendOptions): AgentMessageId {
     this.assertNotDisposed()
+    const id = AgentMessageId(randomUUID())
     const target = options?.target ?? 'next-turn'
     const wakeup = options?.wakeup ?? true
     // next-step/no-wakeup is injection: durable context without running the model.
-    if (target === 'next-step' && !wakeup) { this.injectContext(content, options); return }
+    if (target === 'next-step' && !wakeup) { this.injectContext(content, options); return id }
     // next-step/wakeup is steering into the running turn; idle falls back to a
     // woken follow-up turn (there is no active turn to attach to).
     const steering = target === 'next-step' && this._status === 'running'
     const source = options?.source ?? { kind: 'user' }
-    const accepted = this.acceptMessage(content, source, wakeup, options)
+    const accepted = this.acceptMessage(id, content, source, wakeup, options)
     if (steering) {
       this.#inbox.steer(accepted)
     } else {
       this.#inbox.enqueue(accepted, wakeup)
     }
-    agentEvents(this.loopCtx, this).emit('agent/inbox/enqueue', inboxInfo(accepted, steering))
+    agentEvents(this.loopCtx, this).emit('agent/inbox/enqueue', agentMessage(accepted, steering))
+    return id
   }
 
   /** The `next-step`/no-wakeup injection path: durable context, no FIFO, no run. */
@@ -346,7 +351,7 @@ export class ReactLoopAgent extends Agent {
       // Clear work already present before abort observers run.
       this.#inbox.clear()
       if (discarded.length > 0) {
-        const items = discarded.map(({ message, steering }) => inboxInfo(message, steering))
+        const items = discarded.map(({ message, steering }) => agentMessage(message, steering))
         agentEvents(this.loopCtx, this).emit('agent/inbox/discard', items)
       }
     }

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

@@ -7,10 +7,11 @@
  */
 
 import type { ContentBlock, MessageSource } from '@deepseek-ai/dsh-llm'
-import type { HookContext, InboxItemInfo } from '@deepseek-ai/dsh-agent'
+import type { AgentMessage, AgentMessageId, HookContext } from '@deepseek-ai/dsh-agent'
 
-/** One message waiting in an agent's inbox. */
+/** One message waiting in an agent's inbox; `id` is the value `send` returned. */
 export interface InboxMessage {
+  id: AgentMessageId
   content: ContentBlock[]
   source: MessageSource
   contexts: HookContext[]
@@ -22,10 +23,10 @@ export interface InboxMessage {
  * Build the `agent/inbox/*` event payload for one inbox item.
  * @param message - the accepted inbox record.
  * @param steering - whether the item is in the steering FIFO (`next-step`).
- * @returns the live-event facts for enqueue/dequeue/discard.
+ * @returns the live-event message for enqueue/dequeue/discard.
  */
-export function inboxInfo(message: InboxMessage, steering: boolean): InboxItemInfo {
-  return { content: message.content, source: message.source, contexts: message.contexts, steering, wakeup: message.wakeup }
+export function agentMessage(message: InboxMessage, steering: boolean): AgentMessage {
+  return { id: message.id, content: message.content, source: message.source, contexts: message.contexts, steering, wakeup: message.wakeup }
 }
 
 /**

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

@@ -5,11 +5,12 @@
  * @module dsh-agent-loop/loop
  */
 
+import { randomUUID } from 'node:crypto'
 import type { Context } from 'cordis'
 import type { ContentBlock, FinishReason, GenerateOptions, LlmCallConfig, LlmFailure, Message } from '@deepseek-ai/dsh-llm'
 import { isDeepStrictEqual } from 'node:util'
 import { BlockAssembler, HarnessError, LlmError, assertNever, deepFreeze, errorChain, llmFailureOf, markAgentLoopRequest } from '@deepseek-ai/dsh-llm'
-import { agentEvents, agentInterruptReasonOf, assembleContextFor } from '@deepseek-ai/dsh-agent'
+import { agentEvents, agentInterruptReasonOf, assembleContextFor, AgentMessageId } from '@deepseek-ai/dsh-agent'
 import type { AgentEventDispatch, ContinuationDecision, HookContext, PromptDecision, RequestError, RequestErrorDecision } from '@deepseek-ai/dsh-agent'
 import { canonicalHeader } from '@deepseek-ai/dsh-session'
 import type { PromptMessageData, Session, TurnEndReason, TurnTrigger } from '@deepseek-ai/dsh-session'
@@ -19,7 +20,7 @@ import { renderPrompt } from '@deepseek-ai/dsh-system-prompt'
 import type { PromptAssembly } from '@deepseek-ai/dsh-system-prompt'
 import type {} from '@deepseek-ai/dsh-tools'
 import { executeToolCalls } from './tool-calls.ts'
-import { inboxInfo, type Inbox, type InboxMessage } from './inbox.ts'
+import { agentMessage, type Inbox, type InboxMessage } from './inbox.ts'
 import type { TurnCancellation } from './cancellation.ts'
 
 /** Normalize thrown values while preserving an existing error code. */
@@ -279,7 +280,7 @@ async function runTurn(
   const drainSteering = (): boolean => {
     const messages = handle.inbox.drainSteering()
     for (const message of messages) {
-      events.emit('agent/inbox/dequeue', inboxInfo(message, true))
+      events.emit('agent/inbox/dequeue', agentMessage(message, true))
       const prepared = preparePromptMessage(message.content, message.source, message.contexts)
       session.append('steering/message', { turn, ...prepared.data }, { surfaceOp: 'append' })
       for (const context of prepared.separateContexts) {
@@ -297,7 +298,7 @@ async function runTurn(
   const message = handle.inbox.dequeueQueued()
   /* v8 ignore next 3 -- invariant guard: runLoop only calls runTurn when hasQueued */
   if (!message) throw new Error('runTurn invariant violated: no queued message at turn start')
-  events.emit('agent/inbox/dequeue', inboxInfo(message, false))
+  events.emit('agent/inbox/dequeue', agentMessage(message, false))
   const trigger: TurnTrigger = { kind: 'message', source: message.source }
 
   let reason: TurnEndReason = { kind: 'completed' }
@@ -542,9 +543,12 @@ async function runTurn(
       // enqueue event a public steer would, so the inbox ledger stays balanced
       // (every FIFO entry has a matching enqueue before its dequeue/discard).
       if (decision.action === 'continue' && decision.reason) {
-        const item: InboxMessage = { content: decision.reason.content, source: decision.reason.source, contexts: [], wakeup: true }
+        const item: InboxMessage = {
+          id: AgentMessageId(randomUUID()), content: decision.reason.content,
+          source: decision.reason.source, contexts: [], wakeup: true,
+        }
         handle.inbox.steer(item)
-        events.emit('agent/inbox/enqueue', inboxInfo(item, true))
+        events.emit('agent/inbox/enqueue', agentMessage(item, true))
       }
       let shouldContinue = decision.action === 'continue'
 

packages/core/agent-loop/tests/inbox.spec.ts

@@ -1,8 +1,9 @@
 import { describe, expect, it } from 'vitest'
+import { AgentMessageId } from '@deepseek-ai/dsh-agent'
 import { Inbox } from '../src/inbox.ts'
 
 function message(text: string) {
-  return { content: [{ type: 'text' as const, text }], source: { kind: 'user' as const }, contexts: [], wakeup: true }
+  return { id: AgentMessageId(text), content: [{ type: 'text' as const, text }], source: { kind: 'user' as const }, contexts: [], wakeup: true }
 }
 
 function resolverPair() {

packages/core/agent/README.md

@@ -56,7 +56,7 @@ Turn and step boundaries and the model token stream are durable `session/event`
 
 The handle every plugin programs against:
 
-- `agent.send(content, options?)` — the one delivery primitive over the (`target` × `wakeup`) matrix; `Agent` is an abstract class whose `followup`/`steer`/`inject` aliases are fixed-preset delegates to it. `target: 'next-turn'` (default) queues one independent FIFO item that, if claimed, becomes the sole ordinary message in its turn; `wakeup` (default `true`) wakes a parked driver, while `wakeup: false` queues without waking. `target: 'next-step'` with `wakeup: true` submits steering, and with `wakeup: false` injects durable context without running the model. Omitting `options.source` attests direct human input as `{ kind: 'user' }` (injection defaults to `{ kind: 'plugin', plugin: '' }`) and may authorize policy consumers, so plugins, schedulers, and other non-human producers provide their own source. Content, resolved source, and `options.contexts` become one detached, deeply frozen lossless-JSON record before `agent/inbox/enqueue` and enqueue; invalid data throws synchronously, and caller or notification-listener in-place mutation cannot change the log or model input. After admission, separate contexts become injected `user/message` events, while prompt-prefix contexts are baked before the effective request in the same `user/message`; a block or replacement of the default additional-context decision can discard them. 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(content, options?)` — the one delivery primitive over the (`target` × `wakeup`) matrix; `Agent` is an abstract class whose `followup`/`steer`/`inject` aliases are fixed-preset delegates to it. It returns the accepted message's opaque `AgentMessageId`, which the message's `agent/inbox/enqueue`/`dequeue`/`discard` events carry so a caller can correlate a queued item with its lifecycle. `target: 'next-turn'` (default) queues one independent FIFO item that, if claimed, becomes the sole ordinary message in its turn; `wakeup` (default `true`) wakes a parked driver, while `wakeup: false` queues without waking. `target: 'next-step'` with `wakeup: true` submits steering, and with `wakeup: false` injects durable context without running the model. Omitting `options.source` attests direct human input as `{ kind: 'user' }` (injection defaults to `{ kind: 'plugin', plugin: '' }`) and may authorize policy consumers, so plugins, schedulers, and other non-human producers provide their own source. Content, resolved source, and `options.contexts` become one detached, deeply frozen lossless-JSON record before `agent/inbox/enqueue` and enqueue; invalid data throws synchronously, and caller or notification-listener in-place mutation cannot change the log or model input. After admission, separate contexts become injected `user/message` events, while prompt-prefix contexts are baked before the effective request in the same `user/message`; a block or replacement of the default additional-context decision can discard them. The [one-send-one-turn Agent Note](../../../.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md) owns the turn rationale.
 - `agent.followup(content, options?)` — the `next-turn`/wakeup preset of `send()`: queue an ordinary follow-up turn and wake the driver.
 - `agent.steer(content, options?)` — the `next-step`/wakeup preset: while running, queue steering for the next checkpoint without dispatching `agent/prompt-submit`; when idle, delegate to a woken follow-up. Attached contexts remain in the same frozen record; separate contexts append immediately after the steering event, while prompt-prefix contexts are baked into that steering event. Both survive late-steering conversion to queued input and disappear with their message on cancellation or terminal discard. Policy can still stop before another step; after turn close and its checkpoint, remaining steering becomes later queued input unless terminal turn policy, cancellation, or disposal discards it.
 - `agent.inject(content, options?)` — the `next-step`/no-wakeup preset: accept detached in-session context without running the model; the next request sees its `user/message` (default plugin source) with `content` rendered verbatim as a user-role message. `options.meta` persists opaque JSON state without rendering it. While a turn is open it joins that turn, deferring FIFO while the current tool batch executes and draining before turn close if execution is interrupted; while idle it is wrapped in a one-shot `injection` turn and durability checkpoint ([the turn-enclosure invariant](../../../.agents/notes/implemented/architecture/2026-06-15-turn-enclosure-invariant.md)). Injection bypasses the FIFOs and emits no `agent/inbox/*` event.

packages/core/agent/src/types.ts

@@ -6,6 +6,7 @@
  */
 
 import type { Context } from 'cordis'
+import type { Branded } from '@deepseek-ai/dsh-brand'
 import type { Scoped } from '@deepseek-ai/dsh-scope'
 import type { ContentBlock, LlmCallConfig, LlmFailure, Message, MessageSource } from '@deepseek-ai/dsh-llm'
 import type { JsonValue, Session, SessionId } from '@deepseek-ai/dsh-session'
@@ -68,12 +69,31 @@ export interface SendOptions {
 export type AliasSendOptions = Omit<SendOptions, 'target' | 'wakeup'>
 
 /**
- * The resolved facts of one inbox FIFO item, carried by the `agent/inbox/*`
- * live events. Source defaults are already applied, so these are the exact
- * values the item was accepted with. `steering` is true for a `next-step`
- * item drained between steps; a `next-turn` item is claimed at a turn boundary.
+ * Opaque id assigned to one accepted {@link Agent.send} message; returned by
+ * `send` and carried on its `agent/inbox/*` events for correlation.
  */
-export interface InboxItemInfo {
+export type AgentMessageId = Branded<'AgentMessageId'>
+
+/**
+ * Brand a string as an {@link AgentMessageId}.
+ * @param id - the generated message id.
+ * @returns the same string, branded; no validation is performed.
+ */
+export function AgentMessageId(id: string): AgentMessageId {
+  return id as AgentMessageId
+}
+
+/**
+ * One accepted {@link Agent.send} message, carried by the `agent/inbox/*` live
+ * events. `id` is the value `send` returned to the caller, stable across this
+ * message's enqueue, dequeue, and discard events. Source defaults are already
+ * applied, so these are the exact values the item was accepted with. `steering`
+ * is true for a `next-step` item drained between steps; a `next-turn` item is
+ * claimed at a turn boundary.
+ */
+export interface AgentMessage {
+  /** The id `send` returned for this message. */
+  id: AgentMessageId
   content: ContentBlock[]
   source: MessageSource
   contexts: HookContext[]
@@ -194,8 +214,9 @@ export abstract class Agent {
    * input throws synchronously before any notification, enqueue, or append.
    * @param content - the model-facing content blocks to deliver.
    * @param options - target queue, wakeup decision, source, contexts, and meta.
+   * @returns the accepted message's {@link AgentMessageId}, stable across its `agent/inbox/*` events.
    */
-  abstract send(content: ContentBlock[], options?: SendOptions): void
+  abstract send(content: ContentBlock[], options?: SendOptions): AgentMessageId
 
   /**
    * Clear queued and steering work — unless `keepInbox` — and abort the active
@@ -218,9 +239,10 @@ export abstract class Agent {
    * ordinary message of its own turn.
    * @param content - the prompt content blocks.
    * @param options - source and attached contexts.
+   * @returns the accepted message's {@link AgentMessageId}.
    */
-  followup(content: ContentBlock[], options?: AliasSendOptions): void {
-    this.send(content, { ...options, target: 'next-turn', wakeup: true })
+  followup(content: ContentBlock[], options?: AliasSendOptions): AgentMessageId {
+    return this.send(content, { ...options, target: 'next-turn', wakeup: true })
   }
 
   /**
@@ -232,9 +254,10 @@ export abstract class Agent {
    * Idle steering falls back to a woken follow-up turn.
    * @param content - the steering content blocks.
    * @param options - source and attached contexts.
+   * @returns the accepted message's {@link AgentMessageId}.
    */
-  steer(content: ContentBlock[], options?: AliasSendOptions): void {
-    this.send(content, { ...options, target: 'next-step', wakeup: true })
+  steer(content: ContentBlock[], options?: AliasSendOptions): AgentMessageId {
+    return this.send(content, { ...options, target: 'next-step', wakeup: true })
   }
 
   /**
@@ -247,9 +270,10 @@ export abstract class Agent {
    * `agent/error`. An omitted source defaults to `{ kind: 'plugin', plugin: '' }`.
    * @param content - the injected context content blocks.
    * @param options - source and durable model-hidden meta.
+   * @returns the accepted message's {@link AgentMessageId}.
    */
-  inject(content: ContentBlock[], options?: AliasSendOptions): void {
-    this.send(content, { ...options, target: 'next-step', wakeup: false })
+  inject(content: ContentBlock[], options?: AliasSendOptions): AgentMessageId {
+    return this.send(content, { ...options, target: 'next-step', wakeup: false })
   }
 }
 
@@ -292,31 +316,31 @@ declare module 'cordis' {
      * is the eventual `user/message`/`steering/message`. Injection
      * (`next-step`/no-wakeup) bypasses the FIFOs and does not emit this.
      * @param agent - the agent whose inbox received the item.
-     * @param info - the accepted content, source, contexts, steering, and wakeup facts.
+     * @param message - the accepted message (its returned `id`, content, source, contexts, steering, and wakeup facts).
      * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
      * @mode emit
      */
-    'agent/inbox/enqueue'(this: Scoped<Agent>, agent: Agent, info: InboxItemInfo): void
+    'agent/inbox/enqueue'(this: Scoped<Agent>, agent: Agent, message: AgentMessage): 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 info - the claimed item's accepted content, source, contexts, steering, and wakeup facts.
+     * @param message - the claimed message (matching the `id` from its `agent/inbox/enqueue`).
      * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
      * @mode emit
      */
-    'agent/inbox/dequeue'(this: Scoped<Agent>, agent: Agent, info: InboxItemInfo): void
+    'agent/inbox/dequeue'(this: Scoped<Agent>, agent: Agent, message: AgentMessage): void
     /**
      * `cancel()` (without `keepInbox`) dropped pending inbox items without
      * delivering them. Fires once per effective clearing call with every
      * discarded item, after `agent/cancel-requested` and before the abort.
      * @param agent - the agent whose inbox was cleared.
-     * @param items - the discarded items in FIFO order (queued then steering); empty when nothing was pending.
+     * @param messages - the discarded messages in FIFO order (queued then steering); empty when nothing was pending.
      * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
      * @mode emit
      */
-    'agent/inbox/discard'(this: Scoped<Agent>, agent: Agent, items: InboxItemInfo[]): void
+    'agent/inbox/discard'(this: Scoped<Agent>, agent: Agent, messages: AgentMessage[]): void
     /**
      * Effective broad cancellation was requested, before queued/steering work
      * is cleared or the active turn is aborted. This observe-only notification

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

@@ -4,6 +4,7 @@ import type { Events } from 'cordis'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
 import AgentRegistry, {
   Agent,
+  AgentMessageId,
   agentEvents,
   agentInterruptReasonOf,
 } from '@deepseek-ai/dsh-agent'
@@ -20,7 +21,7 @@ function stubAgent(rawId: string, overrides: Partial<Agent> = {}): Agent {
     session: new Session(id),
     status: 'idle',
     ctx: new Context(),
-    send() {},
+    send: () => AgentMessageId('stub'),
     cancel() {},
     whenIdle() { return Promise.resolve() },
     ...overrides,

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

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
-import type { Agent } from '@deepseek-ai/dsh-agent'
+import { AgentMessageId, type Agent } 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'
@@ -58,7 +58,7 @@ describe('agent status invariants', () => {
 })
 
 describe('agent inbox invariants', () => {
-  const info = (steering: boolean) => ({ content: [], source: { kind: 'user' as const }, contexts: [], steering, wakeup: true })
+  const info = (steering: boolean) => ({ id: AgentMessageId('m'), content: [], source: { kind: 'user' as const }, contexts: [], steering, wakeup: true })
 
   it('accepts a dequeue and a discard covered by prior enqueues', async () => {
     const ctx = await setup()

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

@@ -1,7 +1,7 @@
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import type { Events } from 'cordis'
-import type { Agent } from '@deepseek-ai/dsh-agent'
+import { AgentMessageId, type Agent } from '@deepseek-ai/dsh-agent'
 import { scopeTarget } from '@deepseek-ai/dsh-scope'
 import * as ScopeInvariant from '@deepseek-ai/dsh-scope/invariant'
 import InvariantService from '@deepseek-ai/dsh-invariants'
@@ -42,8 +42,8 @@ describe('scoped-dispatch invariants', () => {
       'agent/created': [agent],
       'agent/disposed': [agent],
       'agent/status': [agent, 'idle'],
-      'agent/inbox/enqueue': [agent, { content: [], source: { kind: 'user' }, contexts: [], steering: false, wakeup: true }],
-      'agent/inbox/dequeue': [agent, { content: [], source: { kind: 'user' }, contexts: [], steering: false, wakeup: true }],
+      'agent/inbox/enqueue': [agent, { id: AgentMessageId('m'), content: [], source: { kind: 'user' }, contexts: [], steering: false, wakeup: true }],
+      'agent/inbox/dequeue': [agent, { id: AgentMessageId('m'), content: [], source: { kind: 'user' }, contexts: [], steering: false, wakeup: true }],
       'agent/inbox/discard': [agent, []],
       'agent/cancel-requested': [agent, { kind: 'user' }],
       'agent/session-start': [agent, 'startup'],