refactor(agent): require complete send options

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

@@ -127,12 +127,13 @@ export class ReactLoopAgent extends Agent {
   }
 
   /** Accept and route one unified send item. */
-  send(content: ContentBlock[], options: SendOptions = {}): AgentMessageIdType {
+  send(
+    content: ContentBlock[],
+    options: SendOptions = { target: 'next-turn', wakeup: true, source: { kind: 'user' } },
+  ): AgentMessageIdType {
     const id = AgentMessageId(randomUUID())
-    const target = options.target ?? 'next-turn'
-    const wakeup = options.wakeup ?? true
+    const { target, wakeup, source } = options
     if (target === 'next-step' && !wakeup) {
-      const source = options.source ?? { kind: 'plugin', plugin: '' }
       if (this.turnOpen) {
         this.outbox.push({ content, source })
         return id
@@ -150,7 +151,7 @@ export class ReactLoopAgent extends Agent {
     const message: PendingMessage = {
       id,
       content,
-      source: options.source ?? { kind: 'user' },
+      source,
       wakeup,
     }
     if (steering) {

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

@@ -106,7 +106,11 @@ describe('Agent.cancel()', () => {
     ctx.on('agent/inbox/discard', (subject, items) => { if (subject === agent) discards.push(items) })
 
     // Queue a turn WITHOUT waking the driver, so it sits in the inbox.
-    agent.send([{ type: 'text', text: 'preserved' }], { target: 'next-turn', wakeup: false })
+    agent.send([{ type: 'text', text: 'preserved' }], {
+      target: 'next-turn',
+      wakeup: false,
+      source: { kind: 'user' },
+    })
     // keepInbox cancel: no active turn, work preserved, no discard event.
     agent.cancel({ kind: 'user' }, { keepInbox: true })
     expect(discards).toEqual([])
@@ -124,7 +128,11 @@ describe('Agent.cancel()', () => {
 
     // A quiet item alone must NOT wake the driver: no turn runs and whenIdle
     // resolves (the agent is quiescent), leaving the item queued.
-    agent.send([{ type: 'text', text: 'quiet' }], { target: 'next-turn', wakeup: false })
+    agent.send([{ type: 'text', text: 'quiet' }], {
+      target: 'next-turn',
+      wakeup: false,
+      source: { kind: 'user' },
+    })
     await agent.whenIdle()
     expect(agent.status).toBe('idle')
     expect(agent.session.events.some(e => e.type === 'turn/start')).toBe(false)
@@ -140,7 +148,11 @@ describe('Agent.cancel()', () => {
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
-    agent.send([{ type: 'text', text: 'quiet' }], { target: 'next-turn', wakeup: false })
+    agent.send([{ type: 'text', text: 'quiet' }], {
+      target: 'next-turn',
+      wakeup: false,
+      source: { kind: 'user' },
+    })
     const idle = agent.whenIdle()
     // Cancel reaches quiescence with no status transition and no waking send;
     // whenIdle must still resolve (previously it hung until the next send).

packages/core/agent-loop/tests/config-session-id.spec.ts

@@ -98,7 +98,7 @@ describe('config-driven session id', () => {
       first = ctx.agents.get(SessionId('config-exact-reload'))
     }
     expect(first).toBeDefined()
-    first!.send([{ type: 'text', text: 'remember me' }], { source: { kind: 'user' } })
+    first!.followup([{ type: 'text', text: 'remember me' }], { source: { kind: 'user' } })
     await waitForIdle(ctx, first!)
     await firstLoop.dispose()
 
@@ -110,7 +110,7 @@ describe('config-driven session id', () => {
     }
     expect(second).toBeDefined()
     expect(JSON.stringify(second!.session.deriveMessages())).toContain('remember me')
-    second!.send([{ type: 'text', text: 'continue' }], { source: { kind: 'user' } })
+    second!.followup([{ type: 'text', text: 'continue' }], { source: { kind: 'user' } })
     await waitForIdle(ctx, second!)
     await ctx.sessions.flush(second!.session)
     const loaded = await ctx.sessionPersistence.load(SessionId('config-exact-reload'))
@@ -335,7 +335,7 @@ describe('config-driven session id', () => {
     expect(a1.id).toBe(a1.session.id)
     expect(a1.session.id).toMatch(idPattern)
     expect(ctx1.agents.get(SessionId('cfg'))).toBeUndefined()
-    a1.send([{ type: 'text', text: 'q' }], { source: { kind: 'user' } })
+    a1.followup([{ type: 'text', text: 'q' }], { source: { kind: 'user' } })
     await waitForIdle(ctx1, a1)
     await ctx1.fiber.dispose()
 
@@ -354,7 +354,7 @@ describe('config-driven session id', () => {
     expect(a2.id).toBe(a2.session.id)
     expect(a2.session.id).toMatch(idPattern)
     expect(a2.session.id).not.toBe(a1.session.id)
-    a2.send([{ type: 'text', text: 'q2' }], { source: { kind: 'user' } })
+    a2.followup([{ type: 'text', text: 'q2' }], { source: { kind: 'user' } })
     await waitForIdle(ctx2, a2)
     await ctx2.fiber.dispose()
   })
@@ -375,7 +375,7 @@ describe('config-driven session id', () => {
     await ctx1.plugin(SessionPersistenceJsonl, { root })
     ctx1.llm.registerAdapter(['mock'], new MockAdapter([textResponse('first')]))
     const a1 = (await ctx1.agents.create({ sessionId: SessionId('sticky-1') })).agent
-    a1.send([{ type: 'text', text: 'remember me' }], { source: { kind: 'user' } })
+    a1.followup([{ type: 'text', text: 'remember me' }], { source: { kind: 'user' } })
     await waitForIdle(ctx1, a1)
     await ctx1.fiber.dispose()
 

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

@@ -807,7 +807,7 @@ describe('adapter registration, routing, and accepted-input ownership', () => {
       notifiedSource = info.source
     })
 
-    agent.send(content, { source })
+    agent.followup(content, { source })
     content[0]!.text = 'caller-mutated-send'
     source.plugin = 'caller-mutated-source'
     await waitForIdle(ctx, agent)

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

@@ -53,7 +53,11 @@ describe('inbox acceptance', () => {
       agent.send([{ type: 'text', text: 'first', bad: 1n } as never])
     }).toThrow(/losslessly JSON-serializable/)
     expect(() => {
-      agent.send([{ type: 'text', text: 'first' }], { source: { kind: 'plugin', plugin: 'p', bad: 1n } as never })
+      agent.send([{ type: 'text', text: 'first' }], {
+        target: 'next-turn',
+        wakeup: true,
+        source: { kind: 'plugin', plugin: 'p', bad: 1n } as never,
+      })
     }).toThrow(/losslessly JSON-serializable/)
     expect(queued).toBe(0)
     expect(agent.session.events).toHaveLength(0)

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

@@ -125,7 +125,7 @@ describe('the session-persistence Agent Note: AgentLoop factory create/resume',
     const adapter1 = new MockAdapter([textResponse('a')])
     const { ctx: ctx1, root } = await persistentHarness(adapter1)
     const a1 = (await ctx1.agents.create({ sessionId: SessionId('nocwd-sess') })).agent
-    a1.send([{ type: 'text', text: 'q' }], { source: { kind: 'user' } })
+    a1.followup([{ type: 'text', text: 'q' }], { source: { kind: 'user' } })
     await waitForIdle(ctx1, a1)
     await ctx1.fiber.dispose()
 
@@ -153,7 +153,7 @@ describe('the session-persistence Agent Note: AgentLoop factory create/resume',
     ctx1.on('agent/session-start', (_agent, source) => void sources1.push(source))
     const a1 = (await ctx1.agents.create({ sessionId: SessionId('start-sess') })).agent
     expect(sources1).toEqual(['startup'])
-    a1.send([{ type: 'text', text: 'q' }], { source: { kind: 'user' } })
+    a1.followup([{ type: 'text', text: 'q' }], { source: { kind: 'user' } })
     await waitForIdle(ctx1, a1)
     await ctx1.fiber.dispose()
 
@@ -459,7 +459,7 @@ describe('the session-persistence Agent Note: AgentLoop factory create/resume',
     const adapter1 = new MockAdapter([textResponse('answer')])
     const { ctx: ctx1, root } = await persistentHarness(adapter1)
     const a1 = (await ctx1.agents.create({ sessionId: SessionId('inject-sess'), meta: { cwd: '/w' } })).agent
-    a1.send([{ type: 'text', text: 'q' }], { source: { kind: 'user' } })
+    a1.followup([{ type: 'text', text: 'q' }], { source: { kind: 'user' } })
     await waitForIdle(ctx1, a1)
     a1.inject([{ type: 'text', text: 'background task 42 finished' }], { source: { kind: 'plugin', plugin: 'tool-bash' } })
     await a1.whenIdle()
@@ -479,7 +479,7 @@ describe('the session-persistence Agent Note: AgentLoop factory create/resume',
     const adapter1 = new MockAdapter([textResponse('answer')])
     const { ctx: ctx1, root } = await persistentHarness(adapter1)
     const a1 = (await ctx1.agents.create({ sessionId: SessionId('inject-sess'), meta: { cwd: '/w' } })).agent
-    a1.send([{ type: 'text', text: 'q' }], { source: { kind: 'user' } })
+    a1.followup([{ type: 'text', text: 'q' }], { source: { kind: 'user' } })
     await waitForIdle(ctx1, a1)
     a1.inject([{ type: 'text', text: 'background task 42 finished' }], { source: { kind: 'plugin', plugin: 'tool-bash' } })
     await a1.whenIdle()
@@ -507,7 +507,7 @@ describe('the session-persistence Agent Note: AgentLoop factory create/resume',
     const adapter1 = new MockAdapter([textResponse('first answer')])
     const { ctx: ctx1, root } = await persistentHarness(adapter1)
     const a1 = (await ctx1.agents.create({ sessionId: SessionId('sess-resume'), meta: { cwd: '/w' } })).agent
-    a1.send([{ type: 'text', text: 'first question' }], { source: { kind: 'user' } })
+    a1.followup([{ type: 'text', text: 'first question' }], { source: { kind: 'user' } })
     await waitForIdle(ctx1, a1)
     const events1 = [...a1.session.events]
     const seqs1 = events1.map(e => e.seq)
@@ -534,7 +534,7 @@ describe('the session-persistence Agent Note: AgentLoop factory create/resume',
     expect(a2.session.deriveMessages()).toEqual(replay.deriveMessages())
 
     // …and a new turn continues numbering (turn 2) with contiguous seqs.
-    a2.send([{ type: 'text', text: 'second question' }], { source: { kind: 'user' } })
+    a2.followup([{ type: 'text', text: 'second question' }], { source: { kind: 'user' } })
     await waitForIdle(ctx2, a2)
     const allSeqs = a2.session.events.map(e => e.seq)
     expect(allSeqs).toEqual(allSeqs.map((_, i) => i)) // 0..N contiguous, no duplicates

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. 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 admitted, becomes the sole ordinary prompt 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. 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. Omitting the whole options object selects `{ target: 'next-turn', wakeup: true, source: { kind: 'user' } }`; a supplied `SendOptions` must provide all three fields. `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.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 a turn is open, stage steering for its next safe boundary without dispatching `agent/prompt-submit`; when idle, delegate to a woken follow-up. Cancellation or disposal may discard pending steering.
 - `agent.inject(content, options?)` — 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 `source`. While a turn is open, injection waits in the outbox for the next safe boundary. While idle, it appends immediately and starts a durability flush without opening a turn; `whenIdle()` and disposal await that flush. Injection emits no `agent/inbox/*` event.

packages/core/agent/src/types.ts

@@ -57,25 +57,29 @@ export type SendTarget = 'next-turn' | 'next-step'
  * (`next-turn`/wakeup), {@link Agent.steer} (`next-step`/wakeup), and
  * {@link Agent.inject} (`next-step`/no-wakeup).
  *
- * An omitted source attests direct human input as `{ kind: 'user' }` and may
- * authorize policy consumers, so non-human producers must label their content.
+ * Omitting the whole options object selects the ordinary user-message preset.
+ * A supplied object is complete so its routing and provenance are explicit.
  */
 export interface SendOptions {
-  /** Queue the item joins; defaults to `next-turn`. */
-  target?: SendTarget
+  /** Queue the item joins. */
+  target: SendTarget
   /**
    * Whether this item makes the model run: wake a parked driver (`next-turn`)
-   * or force a continuation step (`next-step` while running). Defaults to
-   * `true`. A `false` `next-turn` item queues without waking; a `false`
+   * or force a continuation step (`next-step` while running). A `false`
+   * `next-turn` item queues without waking; a `false`
    * `next-step` item attaches durable context without forcing another step
    * (the injection preset).
    */
-  wakeup?: boolean
-  source?: MessageSource
+  wakeup: boolean
+  /** Producer provenance; direct human input uses `{ kind: 'user' }`. */
+  source: MessageSource
 }
 
 /** Options accepted by the fixed-preset aliases, which own `target` and `wakeup`. */
-export type AliasSendOptions = Omit<SendOptions, 'target' | 'wakeup'>
+export interface AliasSendOptions {
+  /** Producer provenance; each alias supplies its documented default when omitted. */
+  source?: MessageSource
+}
 
 /**
  * Opaque id assigned to one accepted {@link Agent.send} message; returned by
@@ -225,7 +229,11 @@ export abstract class Agent {
    * @returns the accepted message's {@link AgentMessageId}.
    */
   followup(content: ContentBlock[], options?: AliasSendOptions): AgentMessageId {
-    return this.send(content, { ...options, target: 'next-turn', wakeup: true })
+    return this.send(content, {
+      target: 'next-turn',
+      wakeup: true,
+      source: options?.source ?? { kind: 'user' },
+    })
   }
 
   /**
@@ -240,7 +248,11 @@ export abstract class Agent {
    * @returns the accepted message's {@link AgentMessageId}.
    */
   steer(content: ContentBlock[], options?: AliasSendOptions): AgentMessageId {
-    return this.send(content, { ...options, target: 'next-step', wakeup: true })
+    return this.send(content, {
+      target: 'next-step',
+      wakeup: true,
+      source: options?.source ?? { kind: 'user' },
+    })
   }
 
   /**
@@ -254,7 +266,11 @@ export abstract class Agent {
    * @returns the accepted message's {@link AgentMessageId}.
    */
   inject(content: ContentBlock[], options?: AliasSendOptions): AgentMessageId {
-    return this.send(content, { ...options, target: 'next-step', wakeup: false })
+    return this.send(content, {
+      target: 'next-step',
+      wakeup: false,
+      source: options?.source ?? { kind: 'plugin', plugin: '' },
+    })
   }
 
   /**

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

@@ -9,7 +9,14 @@ import AgentRegistry, {
   agentInterruptReasonOf,
 } from '@deepseek-ai/dsh-agent'
 
-import type { AgentCancelCause, AgentFactory, ContinuationStop, CreateAgentOptions, ResumeAgentOptions } from '@deepseek-ai/dsh-agent'
+import type {
+  AgentCancelCause,
+  AgentFactory,
+  ContinuationStop,
+  CreateAgentOptions,
+  ResumeAgentOptions,
+  SendOptions,
+} from '@deepseek-ai/dsh-agent'
 
 function stubAgent(rawId: string, overrides: Partial<Agent> = {}): Agent {
   const id = SessionId(rawId)
@@ -28,6 +35,28 @@ function stubAgent(rawId: string, overrides: Partial<Agent> = {}): Agent {
   })
 }
 
+describe('Agent delivery aliases', () => {
+  it('materializes complete SendOptions for every preset', () => {
+    const calls: SendOptions[] = []
+    const agent = stubAgent('aliases', {
+      send(_content, options) {
+        if (options !== undefined) calls.push(options)
+        return AgentMessageId('stub')
+      },
+    })
+
+    agent.followup([])
+    agent.steer([])
+    agent.inject([])
+
+    expect(calls).toEqual([
+      { target: 'next-turn', wakeup: true, source: { kind: 'user' } },
+      { target: 'next-step', wakeup: true, source: { kind: 'user' } },
+      { target: 'next-step', wakeup: false, source: { kind: 'plugin', plugin: '' } },
+    ])
+  })
+})
+
 describe('AgentRegistry', () => {
   it('allows terminal stop policy to cooperate asynchronously with turn cancellation', () => {
     type TurnStopListener = Events['agent/turn-stop']