refactor(agent): expose resolved input acceptance

packages/core/agent-loop/README.md

@@ -52,7 +52,7 @@ Configured agents start automatically. A model call requires both `provider` and
 
 The concrete `ReactLoopAgent` adapter, its `Inbox`, `runLoop`, and instance-bound publication/start controls are package-internal. The package root exports only the plugin/service/config contract, and the package exports map exposes no `./src/*` escape hatch; lifecycle owners create agents through `ctx.agents` rather than naming, constructing, or starting driver internals. One prepared session can be claimed by only one concrete driver, and everything observable happens through session events and the `agent/*` event taxonomy.
 
-`ReactLoopAgent` maps the public `send()`/`queue()`/`steer()`/`inject()` intents onto native-private `#acceptInput`. Each public method resolves every optional field before the private mechanism receives mandatory content, source, contexts, metadata, target, and wakeup facts; no configurable delivery primitive crosses the package seam. `send()` and `queue()` join the ordinary FIFO, respectively waking or leaving an idle driver parked. If claimed, an ordinary item is the sole message in its turn, and its contexts are the prompt waterfall's default additional contexts that materialize only after admission. Absent or `separate` placement appends an independent injected `user/message`; `prompt-prefix` placement bakes the context, the stable `## My request:` delimiter, and effective request into one `user/message`, whose model-hidden envelope retains display content and context descriptors. The waterfall's returned allow is authoritative, so a listener wrapping `next()` preserves downstream `content` and `additionalContexts` unless it intentionally replaces them. A successor waits for the preceding ordinary turn's checkpoint to settle, while cancellation, disposal, a prompt block, or a pre-start failure may drop its contexts with the message. Running `steer()` enters the same record shape in the steering FIFO without dispatching `agent/prompt-submit`; its next checkpoint applies the same separate-or-prefix placement to `steering/message`, while policy can still stop before another step. Steering left after turn close and its checkpoint becomes later queued input with contexts intact unless terminal turn policy, cancellation, or disposal discards it. `inject()` accepts no attached contexts, bypasses both FIFOs, and appends durable context directly: an open-turn injection defers in a FIFO while the current step executes assistant tool calls (successful batches place it after all results, interrupted batches drain it before turn close), and an idle injection wraps a one-shot `injection` turn. Every FIFO enqueue publishes `agent/inbox/enqueue`; the driver's claims publish `agent/inbox/dequeue`, and `cancel()` without `keepInbox` publishes `agent/inbox/discard`. Malformed data throws before enqueue or append.
+`ReactLoopAgent.acceptInput()` implements the public fully resolved acceptance path. The `send()`/`queue()`/`steer()`/`inject()` helpers resolve every optional field before delegating to it; direct callers provide mandatory content, source, contexts, metadata, target, and wakeup facts through `ResolvedAgentInput`. `send()` and `queue()` join the ordinary FIFO, respectively waking or leaving an idle driver parked. If claimed, an ordinary item is the sole message in its turn, and its contexts are the prompt waterfall's default additional contexts that materialize only after admission. Absent or `separate` placement appends an independent injected `user/message`; `prompt-prefix` placement bakes the context, the stable `## My request:` delimiter, and effective request into one `user/message`, whose model-hidden envelope retains display content and context descriptors. The waterfall's returned allow is authoritative, so a listener wrapping `next()` preserves downstream `content` and `additionalContexts` unless it intentionally replaces them. A successor waits for the preceding ordinary turn's checkpoint to settle, while cancellation, disposal, a prompt block, or a pre-start failure may drop its contexts with the message. Running `steer()` or equivalent `acceptInput()` routing enters the same record shape in the steering FIFO without dispatching `agent/prompt-submit`; its next checkpoint applies the same separate-or-prefix placement to `steering/message`, while policy can still stop before another step. Steering left after turn close and its checkpoint becomes later queued input with contexts intact unless terminal turn policy, cancellation, or disposal discards it. `inject()` and non-waking next-step acceptance require an empty context tuple, bypass both FIFOs, and append durable context directly: an open-turn injection defers in a FIFO while the current step executes assistant tool calls (successful batches place it after all results, interrupted batches drain it before turn close), and an idle injection wraps a one-shot `injection` turn. Every FIFO enqueue publishes `agent/inbox/enqueue`; the driver's claims publish `agent/inbox/dequeue`, and `cancel()` without `keepInbox` publishes `agent/inbox/discard`. Malformed data throws before enqueue or append.
 
 ### Loop lifecycle (`loop.ts`)
 

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

@@ -17,11 +17,12 @@ import type {
   CancelOptions,
   HookContext,
   InjectOptions,
+  ResolvedAgentInput,
   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 JsonValue, type Session, type SessionId } from '@deepseek-ai/dsh-session'
+import type { ContentBlock } 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, agentMessage, type InboxMessage } from './inbox.ts'
 import { isTurnOpen, lastTurnNumber, runLoop } from './loop.ts'
@@ -41,17 +42,6 @@ const bindContext = Symbol('dsh.agent-loop.bind-context')
 /** Module-private publication marker. */
 const publishAgent = Symbol('dsh.agent-loop.publish-agent')
 
-/** Fully resolved input accepted only by the concrete driver's private delivery mechanism. */
-type ResolvedAgentInput = {
-  content: ContentBlock[]
-  source: MessageSource
-  meta: JsonValue | undefined
-} & (
-  | { target: 'next-turn'; wakeup: boolean; contexts: HookContext[] }
-  | { target: 'next-step'; wakeup: true; contexts: HookContext[] }
-  | { target: 'next-step'; wakeup: false; contexts: [] }
-)
-
 /** Factory-owned controls that can operate only on the agent created with them. */
 export interface PreparedReactLoopAgent {
   /** The unpublished concrete agent. */
@@ -241,8 +231,8 @@ export class ReactLoopAgent implements Agent {
     if (this._status === 'disposed') throw new Error(`agent "${this.id}" is disposed`)
   }
 
-  /** Accept one fully resolved agent input through the concrete driver's private routing matrix. */
-  #acceptInput(input: ResolvedAgentInput): AgentMessageId {
+  /** Accept one fully resolved agent input through the concrete driver's routing matrix. */
+  acceptInput(input: ResolvedAgentInput): AgentMessageId {
     this.assertNotDisposed()
     const id = AgentMessageId(randomUUID())
     const { target, wakeup } = input
@@ -262,7 +252,7 @@ export class ReactLoopAgent implements Agent {
   }
 
   send(content: ContentBlock[], options?: SendOptions): AgentMessageId {
-    return this.#acceptInput({
+    return this.acceptInput({
       content,
       target: 'next-turn',
       wakeup: true,
@@ -273,7 +263,7 @@ export class ReactLoopAgent implements Agent {
   }
 
   queue(content: ContentBlock[], options?: SendOptions): AgentMessageId {
-    return this.#acceptInput({
+    return this.acceptInput({
       content,
       target: 'next-turn',
       wakeup: false,
@@ -284,7 +274,7 @@ export class ReactLoopAgent implements Agent {
   }
 
   steer(content: ContentBlock[], options?: SendOptions): AgentMessageId {
-    return this.#acceptInput({
+    return this.acceptInput({
       content,
       target: 'next-step',
       wakeup: true,
@@ -295,7 +285,7 @@ export class ReactLoopAgent implements Agent {
   }
 
   inject(content: ContentBlock[], options?: InjectOptions): AgentMessageId {
-    return this.#acceptInput({
+    return this.acceptInput({
       content,
       target: 'next-step',
       wakeup: false,

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

@@ -83,6 +83,40 @@ describe('Agent', () => {
     await ctx.fiber.dispose()
   })
 
+  it('acceptInput exposes the fully resolved delivery path without applying helper defaults', async () => {
+    const adapter = new MockAdapter([textResponse('accepted')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const enqueued = Promise.withResolvers<{ id: string; source: unknown; wakeup: boolean }>()
+    ctx.on('agent/inbox/enqueue', (subject, message) => {
+      if (subject === agent) enqueued.resolve(message)
+    })
+
+    const id = agent.acceptInput({
+      content: [{ type: 'text', text: 'advanced input' }],
+      source: { kind: 'plugin', plugin: 'advanced-caller' },
+      contexts: [],
+      meta: { caller: 'advanced' },
+      target: 'next-turn',
+      wakeup: true,
+    })
+    await waitForIdle(ctx, agent)
+
+    expect(await enqueued.promise).toMatchObject({
+      id,
+      source: { kind: 'plugin', plugin: 'advanced-caller' },
+      wakeup: true,
+    })
+    expect(agent.session.events.find(event => event.type === 'user/message'))
+      .toMatchObject({
+        data: {
+          source: { kind: 'plugin', plugin: 'advanced-caller' },
+          meta: { caller: 'advanced' },
+        },
+      })
+    await ctx.fiber.dispose()
+  })
+
   it('send() throws after disposal', async () => {
     const adapter = new MockAdapter(['hang'])
     const ctx = await harness(adapter)