[Feature request] Request-only assistant prefill for agent/pre-step (header-logged, never a session message)

[royenheart]

Background

My plugin dsh-plugin-opencode-omo replicates opencode + omo over dsh seams. On the budget-limited last step, opencode ends the request with an assistant-role MAX_STEPS_PROMPT continuation (prompt.ts, llm.ts, max-steps.ts). The role is the feature: the text reads as "the assistant already speaking", so the model keeps writing and stops calling tools.

dsh cannot produce that message. agent/pre-step listeners may only return UserMessage[], the loop records the batch as user/message, and by the time agent/request runs the messages are already derived and frozen, so roles cannot be rewritten. The plugin's current workaround injects the same text as a synthetic user message — the role semantics change and the fidelity gap is observable.

Current state

PreStepDecision is user-only (runtime-types.ts):

export type PreStepDecision =
  | { kind: 'reject' }
  | { kind: 'enter'; messages: UserMessage[] }

The loop hardcodes the event role (agent.ts):

for (const message of decision.messages) {
  this.session.append('user/message', message, { surfaceOp: 'append' })
}

This mirrors the inbox, not an anti-assistant guard: the entered batch preserves the claimed UserMessages' id/source, and every feeding queue accepts complete UserMessages (core.md, claimed-pre-step note).

assistant/message exists but is the step's one assembled model response, not a free assistant-role append. Widening messages and appending assistant/message events therefore breaks consumers that depend on that invariant:

• session-stats closes the step boundary on the assembled response — a pre-step append would zero the step's llmMs/ttftMs/decodeMs/decodeTokens.
• web turn-tail treats assistant/message as the finalized stream, so the UI would end the step early.
• compaction-basic resets overflow recovery on any assistant/message — a prefill would fake a successful response.
• token-meter anchors usage on the assembled response and validates sourceEventSeqs against assistant/chunk; injected text has no chunk provenance.
• surface derivation would render the prefill as a visible assistant bubble.

The session-prefix note supplies the correct pattern: request-only, header-logged message material — the prefix never enters the surface, its durable record is the request/header, and the invariant companion recomputes it against every request. That note also dropped a request-only tail slot because an every-step after slot re-pays tokens and busts cache. This proposal reuses the pattern but bounds the cost: the tail exists only when a listener returns one (opencode returns it once, on the final step), and header participation keeps it accounted.

Proposal

1. Extend the enter variant (runtime-types.ts):

export type PreStepDecision =
  | { kind: 'reject' }
  | {
    kind: 'enter'
    messages: UserMessage[]
    /**
     * Optional request-only assistant continuation appended after the
     * derived history for this step. Logged on the request/header, never
     * appended as a session message. Omission preserves the historical
     * behavior.
     */
    assistantPrefill?: AssistantMessage
  }

2. In agent.ts, do not append it to the session; pass it through step() → buildRequest(). The canonical header records it and the request messages become [...boundaryMessages, assistantPrefill]:

const header = canonicalHeader({
  config,
  ...system ? { system } : {},
  ...tools.length > 0 ? { tools } : {},
  ...assistantPrefill === undefined ? {} : { assistantPrefill },
})
// ...
messages: assistantPrefill === undefined
  ? boundaryMessages
  : [...boundaryMessages, assistantPrefill],

3. Add assistantPrefill?: AssistantMessage to EpochHeader, include it in canonicalHeader/headerEquals, and make the loop's invariant companion expect derived messages + header.assistantPrefill. "Model-visible ⟺ durably referenced" then holds: the header is the durable non-history record, exactly as for the prefix seam.

4. Make the token-meter price the prefill from the header, and add a regression test: no assistant/message before the first assistant/chunk, prefill present at the request tail and in the logged header, and undefined keeps requests byte-for-byte unchanged.

Why this is safe:

• No session event is written, so session-stats, turn-tail, compaction, token-meter chunk anchoring, and the visible transcript are untouched.
• Reconstruction stays exact: the prefill's one durable record is the step's request/header, folded by the invariant companion.
• Backward compatible: the field is optional; undefined means identical behavior and headers.
• Cost is visible and bounded: only steps whose listener returns a prefill log a header change (opencode: one final step).
• General-purpose: user input/context goes through the inbox, system text through the system prompt, model output through the loop — a request-only assistant continuation is the only homeless shape, so one role-typed field covers the whole class. Future growth should widen this field (e.g. to a tail message list), never add sibling fields.

Appendix: patch

Have tested and checked in my plugin:

diff --git a/packages/core/agent/src/runtime-types.ts b/packages/core/agent/src/runtime-types.ts
@@
-import type { AgentCancelCause, Session, SessionId, UserMessage } from '@deepseek-ai/dsh-session'
+import type {
+  AgentCancelCause, AssistantMessage, Session, SessionId, UserMessage,
+} from '@deepseek-ai/dsh-session'
@@
 export type PreStepDecision =
   | { kind: 'reject' }
-  | { kind: 'enter'; messages: UserMessage[] }
+  | {
+    kind: 'enter'
+    messages: UserMessage[]
+    /**
+     * Optional request-only assistant continuation appended after the
+     * derived history for this step. Logged on the request/header, never
+     * appended as a session message. Omission preserves the historical
+     * behavior.
+     */
+    assistantPrefill?: AssistantMessage
+  }

diff --git a/packages/core/agent-loop/src/agent.ts b/packages/core/agent-loop/src/agent.ts
@@
-          const stepEnd = await this.step(decision.assembly)
+          const stepEnd = await this.step(decision.assembly, decision.assistantPrefill)
@@
-  private async step(assembly: PromptAssembly): Promise<StepEndReason | null> {
+  private async step(
+    assembly: PromptAssembly,
+    assistantPrefill?: AssistantMessage,
+  ): Promise<StepEndReason | null> {
@@
        const { request, preparedCall } = await this.buildRequest(
-        turn, step, assembly.tools, system, this.session.deriveMessages(), signal,
+        turn, step, assembly.tools, system, this.session.deriveMessages(), signal, assistantPrefill,
       )
@@
   private async buildRequest(
@@
     boundaryMessages: Message[],
     signal: AbortSignal,
+    assistantPrefill?: AssistantMessage,
   ): Promise<{ request: GenerateOptions; preparedCall?: PreparedLlmCall }> {
@@
     const header = canonicalHeader({
       config,
       ...preparedCall === undefined ? {} : { adapterDefaults: preparedCall.adapterDefaults },
       ...system ? { system } : {},
       ...tools.length > 0 ? { tools } : {},
+      ...assistantPrefill === undefined ? {} : { assistantPrefill },
     })
@@
     const request = markAgentLoopRequest(deepFreeze({
       ...header.config,
-      messages: boundaryMessages,
+      messages: assistantPrefill === undefined
+        ? boundaryMessages
+        : [...boundaryMessages, assistantPrefill],
       ...header.system !== undefined ? { system: header.system } : {},
       ...header.tools !== undefined ? { tools: header.tools } : {},
       sessionId: this.session.id,
       signal,
     }))

diff --git a/packages/core/session/src/types.ts b/packages/core/session/src/types.ts
@@
 export interface EpochHeader {
   config: LlmCallConfig
   adapterDefaults?: LlmCallConfigAdapterDefaults
   system?: string
   tools?: ToolSchema[]
+  /** Request-only assistant continuation appended after the derived history. */
+  assistantPrefill?: AssistantMessage
 }

Also required (same bookkeeping as the prefix seam): request-header.ts equality, the loop's invariant companion, token-meter header estimation, and the interception test from step 4.

Questions to confirm

1. Naming & vocabulary. Does assistantPrefill fit dsh's existing vocabulary (symmetric with session-prefix's messagePrefix), or would requestTail / messageSuffix better express "request tail, not a session message"?
2. Message source semantics. This text is plugin-provided but assistant-role. Reusing AssistantMessage stamps source.kind: 'model' on text the model did not produce, breaking source-as-provenance; should the channel define its own envelope type (minimal role/content/source) so the type boundary and source semantics are explicit?
3. Cardinality & ordering. Is the channel's contract one assistant message or an ordered tail list? If it starts singular, should future growth widen this same field (rather than adding sibling fields)? Is the tail's position fixed as "always appended after deriveMessages()"?
4. Durable record & cache envelope. Are EpochHeader.assistantPrefill + canonicalHeader/headerEquals the right durable home under reconstructable-requests? Beyond the invariant companion and token-meter, are there other request-envelope consumers (compaction / pressure / session export) that must fold in this tail?
5. Loop-level validation & scope. agent/pre-step currently passes messages through untouched. Should this tail likewise get only type-level validation (non-empty content, no tool-call blocks), or does the loop need any structural restriction — for reasons unrelated to any particular budget policy, is there a reason to limit it to a specific class of step?
6. Observability. Request-only means no session event and no transcript bubble. Is request/header sufficient as the only durable trace, or does dsh's UI/session export need a read-only marker (not a message bubble) for debugging and audit?

Related

• core.md, agent README, agent-loop README — inbox, pre-step, and step-boundary contracts.
• Agent Note: claimed pre-step inbox lifecycle — why the decision type is UserMessage[].
• Agent Note: reconstructable requests — why the prefill must be header-logged.
• Agent Note: session prefix (archived) — request-only/header-logged precedent and dropped tail-slot economics.
• session event types, surface derivation, session-stats, web turn-tail, compaction-basic, token-meter — why assistant/message must not be reused for injected prefill.
• opencode reference: prompt.ts, runner/llm.ts, max-steps.ts.
• Consumer patch: dsh-plugin-opencode-omo patches.
• no existing discussion found covering an assistant-role continuation for agent/pre-step.