Merge remote-tracking branch 'origin/master' into codex/invariant-service-seam

packages/core/agent/src/types.ts

@@ -8,7 +8,7 @@
 import type { Context } from 'cordis'
 import type { Scoped } from '@deepseek-ai/dsh-scope'
 import type { ContentBlock, LlmCallConfig, Message, MessageSource } from '@deepseek-ai/dsh-llm'
-import type { ContextEnvelope, JsonValue, Session, SessionId } from '@deepseek-ai/dsh-session'
+import type { JsonValue, Session, SessionId } from '@deepseek-ai/dsh-session'
 import type {} from '@deepseek-ai/dsh-system-prompt'
 declare module '@deepseek-ai/dsh-system-prompt' {
   interface AssembleContext {
@@ -32,17 +32,15 @@ export interface SendOptions {
 
 /** Options specific to durable synthetic context injection. */
 export interface InjectOptions extends SendOptions {
-  /** Keep the canonical context tag, or send caller-owned framing verbatim. */
-  envelope?: ContextEnvelope
   /** Opaque JSON state retained in the session event but hidden from the model. */
   meta?: JsonValue
 }
 
 /**
  * An agent's lifecycle state, emitted on every transition as `agent/status`:
- * `idle` (parked, waiting for queued work), `running` (a turn is in progress),
- * `disposed` (terminal — no transition leaves it, and `send`/`steer`/`inject`
- * throw).
+ * `idle` (parked, waiting for queued work), `running` (the driver is draining
+ * work and may be closing or checkpointing a turn), `disposed` (terminal — no
+ * transition leaves it, and `send`/`steer`/`inject` throw).
  */
 export type AgentStatus = 'idle' | 'running' | 'disposed'
 
@@ -50,16 +48,15 @@ export type AgentStatus = 'idle' | 'running' | 'disposed'
 export interface HookContext {
   content: ContentBlock[]
   source: MessageSource
-  /** Keep the canonical context tag, or use caller-owned framing verbatim. */
-  envelope?: ContextEnvelope
   /** Opaque JSON state retained in the session event but hidden from the model. */
   meta?: JsonValue
 }
 
 /**
  * Prompt interception result. `allow.content` replaces the prompt and each
- * `additionalContexts` entry becomes a separate context message. `block` records a
- * durable `prompt/blocked`; an all-blocked batch ends a zero-step rejected turn.
+ * `additionalContexts` entry becomes a separate context message. `block`
+ * records a durable `prompt/blocked` and ends the claimed prompt's zero-step
+ * turn as rejected.
  */
 export type PromptDecision =
   | { kind: 'allow'; content?: ContentBlock[]; additionalContexts?: HookContext[] }
@@ -97,15 +94,20 @@ export interface Agent {
   readonly ctx: Context
 
   /**
-   * Queue detached, frozen lossless-JSON input; starts a turn when idle.
+   * Queue one detached, frozen lossless-JSON item. If claimed, it is the sole
+   * ordinary message in its FIFO-ordered turn; the next claimed item waits for
+   * that turn's checkpoint.
    * Invalid input throws synchronously before notification or enqueue.
    */
   send(content: ContentBlock[], options?: SendOptions): void
 
   /**
-   * Steer a running turn: content is injected between steps of the current
-   * turn. Uses the same owned-value and synchronous-validation boundary as
-   * {@link send}; when idle, behaves exactly like that method.
+   * Submit steering while the agent is `running`. An open turn records it at
+   * the next steering checkpoint before a request or continuation decision;
+   * policy may stop before another step. After turn close and its checkpoint,
+   * any remainder is queued for a later turn; terminal `agent/turn-stop`,
+   * cancellation, or disposal may discard it. Uses the same synchronous
+   * snapshot-and-validation boundary as {@link send}; when idle, delegates to it.
    */
   steer(content: ContentBlock[], options?: SendOptions): void
 
@@ -119,10 +121,11 @@ export interface Agent {
   inject(content: ContentBlock[], options?: InjectOptions): void
 
   /**
-   * Clear queued and steering work, including work waiting to start, and abort
-   * the active step. The supplied reason is preserved across pre-step and active
-   * cancellation windows, and `whenIdle()` resolves after cancellation reaches
-   * quiescence. Idle cancellation is a no-op and does not arm a later cancel.
+   * Clear all queued and steering work, including items waiting to start, and
+   * abort the active step. The supplied reason is preserved across pre-step
+   * and active cancellation windows, and `whenIdle()` resolves after
+   * cancellation reaches quiescence. Idle cancellation is a no-op and does not
+   * arm a later cancel.
    */
   cancel(reason?: string): void
 
@@ -203,10 +206,10 @@ declare module 'cordis' {
      */
     'agent/pre-step'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, signal: AbortSignal): Promise<void> | void
     /**
-     * Allow, rewrite, or block one drained prompt before it becomes a user
+     * Allow, rewrite, or block one claimed prompt before it becomes a user
      * message. Call `next()` for the unchanged default.
-     * @param agent - the agent draining its inbox.
-     * @param content - the drained message's blocks, as queued.
+     * @param agent - the agent whose turn claimed the message.
+     * @param content - the claimed message's blocks, as queued.
      * @param source - the message's resolved source.
      * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
      * @mode waterfall