@archships/dim-agent-sdk 0.0.4 → 0.0.5

package/README.md

@@ -34,8 +34,16 @@ const session = await agent.createSession({
   systemPrompt: 'You are a coding agent. Use tools when needed.',
 })
 
-const message = await session.send('Create hello.txt in the current directory and write hello world into it.')
-console.log(message.content)
+const itemId = session.send('Create hello.txt in the current directory and write hello world into it.')
+
+for await (const event of session.receive()) {
+  if (event.itemId !== itemId)
+    continue
+  if (event.type === 'text_delta')
+    process.stdout.write(event.delta)
+  if (event.type === 'done')
+    console.log(event.message.content)
+}
 ```
 
 ## Manual
@@ -48,7 +56,8 @@ console.log(message.content)
 
 - Canonical content / message / tool / model / state contracts
 - `createAgent()` -> `Agent` -> `Session`
-- Session stream events: `text_delta`, optional `thinking_delta`, `tool_call`, `plugin_event`, `tool_result`, `done`
+- Queue-first session flow: `send()`, `sendBatch()`, `steer()`, `receive()`, `getQueueStatus()`
+- Session events: `text_delta`, optional `thinking_delta`, `tool_call`, `plugin_event`, `tool_result`, `done`, `error`
 - Provider adapters: `openai-compatible`, `openai-responses`, `anthropic`, `gemini`, `zenmux`, `aihubmix`, `aihubmix-responses`, `moonshotai`, `deepseek`, `xai`, `xai-responses`
 - Builtin tools: `read`, `write`, `edit`, `exec`
 - Hook-first plugin integration

package/dist/dim-agent-sdk/src/agent-core/agent-types.d.ts

@@ -1,5 +1,5 @@
 import type { DimPlugin } from '@archships/dim-plugin-api';
-import type { CompactionOptions, Message, MessageContentInput, ModelClient, Tool } from '../contracts';
+import type { CompactionOptions, Message, MessageContentInput, MessageQueueConfig, ModelClient, Tool } from '../contracts';
 import type { ContextManager } from '../context';
 import type { StateStore } from '../persistence/store';
 import type { PermissionSpec } from '../services';
@@ -26,4 +26,5 @@ export interface CreateSessionOptions {
     metadata?: Record<string, unknown>;
     messages?: Message[];
     systemPrompt?: MessageContentInput;
+    messageQueueConfig?: Partial<MessageQueueConfig>;
 }

package/dist/dim-agent-sdk/src/agent-core/loop-runner.d.ts

@@ -19,6 +19,7 @@ export interface LoopRunnerDependencies {
 export interface LoopRunnerRunOptions {
     signal?: AbortSignal;
     onDone?: (message: AssistantMessage) => Promise<void> | void;
+    persistentPromptSegments?: string[];
 }
 export declare class LoopRunner {
     private readonly messageFactory;

package/dist/dim-agent-sdk/src/agent-core/session-state.d.ts

@@ -1,4 +1,4 @@
-import type { CompactionOptions, CompactionState, Message, ModelClient, ModelRef, PluginSessionStateEntry, Usage } from '../contracts';
+import type { CompactionOptions, CompactionState, Message, MessageQueueSnapshot, ModelClient, ModelRef, PluginSessionStateEntry, Usage } from '../contracts';
 import type { ToolRegistry } from '../tools/tool-registry';
 export interface RuntimeSessionState {
     id: string;
@@ -13,6 +13,7 @@ export interface RuntimeSessionState {
     usage: Usage;
     compaction: CompactionState;
     pluginState: Record<string, PluginSessionStateEntry>;
+    messageQueue: MessageQueueSnapshot;
     compactionOptions?: CompactionOptions;
     createdAt: number;
     updatedAt: number;

package/dist/dim-agent-sdk/src/agent-core/session.d.ts

@@ -1,4 +1,4 @@
-import type { AssistantMessage, CompactionOptions, CompactionState, CompactionUpdate, Message, MessageContentInput, ModelClient, ModelRef, PluginSessionStateEntry, SessionStatus, SessionSnapshot, SessionStreamEvent, Usage } from '../contracts';
+import type { CompactionOptions, CompactionState, CompactionUpdate, Message, MessageContentInput, MessageQueueConfig, MessageQueueSnapshot, MessageQueueStatus, PendingMessageKind, ModelClient, ModelRef, PluginSessionStateEntry, SessionStatus, SessionSnapshot, SessionStreamEvent, Usage } from '../contracts';
 import type { ContextManager } from '../context';
 import type { StateStore } from '../persistence/store';
 import type { PluginHost } from '../plugin-host/plugin-host';
@@ -22,6 +22,8 @@ export interface SessionOptions {
     usage?: Usage;
     compaction?: CompactionState;
     pluginState?: Record<string, PluginSessionStateEntry>;
+    messageQueue?: MessageQueueSnapshot;
+    messageQueueConfig?: Partial<MessageQueueConfig>;
     compactionOptions?: CompactionOptions;
     createdAt?: number;
     updatedAt?: number;
@@ -33,6 +35,15 @@ export interface SessionOptions {
     compactionService: DefaultCompactionService;
     pluginStateService: DefaultPluginStateService;
 }
+interface SessionQueueSendOptions {
+    priority?: number;
+}
+interface SessionReceiveOptions {
+    signal?: AbortSignal;
+}
+interface ClearQueueFilter {
+    kind?: PendingMessageKind;
+}
 export declare class Session {
     readonly id: string;
     readonly createdAt: number;
@@ -46,7 +57,14 @@ export declare class Session {
     private readonly compactionService;
     private readonly pluginStateService;
     private readonly pluginControllers;
+    private readonly bufferedEvents;
+    private readonly stateChangeWaiters;
     private activeRunCount;
+    private processingPromise;
+    private receiveActive;
+    private activeReceiveSignal?;
+    private haltProcessingUntilReceive;
+    private saveChain;
     constructor(options: SessionOptions);
     get messages(): Message[];
     get usage(): Usage;
@@ -58,16 +76,37 @@ export declare class Session {
     get updatedAt(): number;
     getCwd(): string | undefined;
     setCwd(cwd: string): void;
+    send(input: MessageContentInput, options?: SessionQueueSendOptions): string;
+    sendBatch(items: Array<{
+        input: MessageContentInput;
+        options?: SessionQueueSendOptions;
+    }>): string[];
+    steer(input: MessageContentInput, options?: SessionQueueSendOptions): string;
+    cancelQueuedItem(itemId: string): boolean;
+    getQueueStatus(): MessageQueueStatus;
+    clearQueue(filter?: ClearQueueFilter): number;
+    receive(options?: SessionReceiveOptions): AsyncGenerator<SessionStreamEvent, void, void>;
     compact(update: CompactionUpdate): Promise<void>;
     save(): Promise<void>;
+    private writeSnapshot;
     toSnapshot(): SessionSnapshot;
-    send(input: MessageContentInput, options?: {
-        signal?: AbortSignal;
-    }): Promise<AssistantMessage>;
-    stream(input: MessageContentInput, options?: {
-        signal?: AbortSignal;
-    }): AsyncGenerator<SessionStreamEvent, AssistantMessage, void>;
+    private enqueueItem;
+    private onQueueMutated;
+    private hasRunnableItems;
+    private ensureQueueProcessing;
+    private processQueue;
+    private dequeueNextRunnableItem;
+    private processQueuedItem;
+    private attachQueueContext;
+    private createErrorEvent;
+    private pushBufferedEvent;
+    private scheduleSave;
+    private persistStateQuietly;
+    private enqueueSave;
+    private waitForStateChange;
+    private notifyStateChange;
     private createLoopRunner;
     private readEstimatedInputTokens;
     private createHookContext;
 }
+export {};

package/dist/dim-agent-sdk/src/contracts/event.d.ts

@@ -1,6 +1,12 @@
 import type { SessionErrorPayload, Usage } from './common';
 import type { AssistantMessage } from './message';
+import type { PendingMessageKind } from './state';
 import type { CallToolResult, ToolCall } from './tool';
+export interface SessionQueueEventContext {
+    itemId?: string;
+    itemKind?: PendingMessageKind;
+    priority?: number;
+}
 export interface SessionPluginEvent {
     type: 'plugin_event';
     sessionId: string;
@@ -8,30 +14,30 @@ export interface SessionPluginEvent {
     event: string;
     data?: Record<string, unknown>;
 }
-export type SessionStreamEvent = {
+export type SessionStreamEvent = ({
     type: 'text_delta';
     sessionId: string;
     delta: string;
-} | {
+} & SessionQueueEventContext) | ({
     type: 'thinking_delta';
     sessionId: string;
     delta: string;
-} | {
+} & SessionQueueEventContext) | ({
     type: 'tool_call';
     sessionId: string;
     toolCall: ToolCall;
-} | {
+} & SessionQueueEventContext) | ({
     type: 'tool_result';
     sessionId: string;
     toolCallId: string;
     result: CallToolResult;
-} | SessionPluginEvent | {
+} & SessionQueueEventContext) | (SessionPluginEvent & SessionQueueEventContext) | ({
     type: 'done';
     sessionId: string;
     message: AssistantMessage;
     usage?: Usage;
-} | {
+} & SessionQueueEventContext) | ({
     type: 'error';
     sessionId: string;
     error: SessionErrorPayload;
-};
+} & SessionQueueEventContext);

package/dist/dim-agent-sdk/src/contracts/state.d.ts

@@ -1,10 +1,40 @@
 import type { CompactionState } from './compaction';
+import type { MessageContentInput } from './content';
 import type { PluginSessionStateEntry } from './plugin-state';
 import type { Usage } from './common';
 import type { Message } from './message';
 import type { ModelRef } from './model';
+export interface MessageQueueConfig {
+    autoProcessQueue: boolean;
+    maxQueueSize?: number;
+}
+export type PendingMessageKind = 'user' | 'steer';
+export interface PendingMessage {
+    id: string;
+    input: MessageContentInput;
+    kind: PendingMessageKind;
+    priority: number;
+    enqueuedAt: number;
+}
+export interface MessageQueueSnapshot {
+    items: PendingMessage[];
+    config: MessageQueueConfig;
+}
+export interface MessageQueueStatusItem {
+    id: string;
+    kind: PendingMessageKind;
+    priority: number;
+    enqueuedAt: number;
+    preview: string;
+}
+export interface MessageQueueStatus {
+    length: number;
+    items: MessageQueueStatusItem[];
+    isProcessing: boolean;
+    config: MessageQueueConfig;
+}
 export interface SessionSnapshot {
-    schemaVersion: 1;
+    schemaVersion: 1 | 2;
     sessionId: string;
     model?: ModelRef;
     cwd?: string;
@@ -15,6 +45,7 @@ export interface SessionSnapshot {
     createdAt: number;
     updatedAt: number;
     metadata?: Record<string, unknown>;
+    messageQueue?: MessageQueueSnapshot;
 }
 export interface SessionStatus {
     sessionId: string;

package/dist/dim-agent-sdk/src/index.d.ts

@@ -1,4 +1,4 @@
-export type { CallToolResult, CompactionBudgetInfo, CompactionCheckpoint, CompactionEstimator, CompactionEstimatorInput, CompactionOptions, CompactionService, CompactionState, CompactionTriggerReason, CompactionUpdate, ContentBlock, Message, MessageContentInput, ModelAdapter, ModelClient, ModelRequest, ModelStreamEvent, ModelStopReason, ModelRef, PluginSessionStateEntry, PluginStateService, SessionStatus, SessionPluginEvent, SessionSnapshot, SessionStreamEvent, Tool, ToolCall, ToolDefinition, ToolExecutionContext, ToolExecutionPluginEvent, ToolInputSchema, Usage, } from './contracts';
+export type { CallToolResult, CompactionBudgetInfo, CompactionCheckpoint, CompactionEstimator, CompactionEstimatorInput, CompactionOptions, CompactionService, CompactionState, CompactionTriggerReason, CompactionUpdate, ContentBlock, Message, MessageContentInput, MessageQueueConfig, MessageQueueSnapshot, MessageQueueStatus, ModelAdapter, ModelClient, ModelRequest, ModelStreamEvent, ModelStopReason, ModelRef, PluginSessionStateEntry, PendingMessage, PendingMessageKind, PluginStateService, SessionStatus, SessionPluginEvent, SessionSnapshot, SessionStreamEvent, Tool, ToolCall, ToolDefinition, ToolExecutionContext, ToolExecutionPluginEvent, ToolInputSchema, Usage, } from './contracts';
 export { normalizeContent } from './contracts/content-normalize';
 export { Agent, createAgent } from './agent-core/agent';
 export type { CreateAgentOptions } from './agent-core/agent';

package/dist/dim-agent-sdk/src/persistence/snapshot-codec.d.ts

@@ -1,4 +1,4 @@
-import type { CompactionState, Message, ModelRef, PluginSessionStateEntry, SessionSnapshot, Usage } from '../contracts';
+import type { CompactionState, Message, MessageQueueSnapshot, ModelRef, PluginSessionStateEntry, SessionSnapshot, Usage } from '../contracts';
 export interface SnapshotCodecInput {
     sessionId: string;
     model?: ModelRef;
@@ -10,6 +10,7 @@ export interface SnapshotCodecInput {
     createdAt: number;
     updatedAt: number;
     metadata?: Record<string, unknown>;
+    messageQueue?: MessageQueueSnapshot;
 }
 export interface SnapshotCodec {
     encode(input: SnapshotCodecInput): SessionSnapshot;

package/dist/dim-plugin-api/src/index.d.ts

@@ -279,8 +279,24 @@ export interface Tool {
     readonly definition: ToolDefinition;
     execute(args: Record<string, unknown>, context: ToolExecutionContext): Promise<CallToolResult>;
 }
+export interface MessageQueueConfig {
+    autoProcessQueue: boolean;
+    maxQueueSize?: number;
+}
+export type PendingMessageKind = 'user' | 'steer';
+export interface PendingMessage {
+    id: string;
+    input: MessageContentInput;
+    kind: PendingMessageKind;
+    priority: number;
+    enqueuedAt: number;
+}
+export interface MessageQueueSnapshot {
+    items: PendingMessage[];
+    config: MessageQueueConfig;
+}
 export interface SessionSnapshot {
-    schemaVersion: 1;
+    schemaVersion: 1 | 2;
     sessionId: string;
     model?: ModelRef;
     cwd?: string;
@@ -291,6 +307,7 @@ export interface SessionSnapshot {
     createdAt: number;
     updatedAt: number;
     metadata?: Record<string, unknown>;
+    messageQueue?: MessageQueueSnapshot;
 }
 export interface SessionStatus {
     sessionId: string;

package/dist/src/index.js

@@ -3257,7 +3257,7 @@ class DefaultNotificationBus {
 class JsonSnapshotCodec {
   encode(input) {
     return structuredClone({
-      schemaVersion: 1,
+      schemaVersion: 2,
       sessionId: input.sessionId,
       model: input.model,
       cwd: input.cwd,
@@ -3267,14 +3267,15 @@ class JsonSnapshotCodec {
       pluginState: input.pluginState,
       createdAt: input.createdAt,
       updatedAt: input.updatedAt,
-      metadata: input.metadata
+      metadata: input.metadata,
+      messageQueue: input.messageQueue
     });
   }
   decode(value) {
     if (!value || typeof value !== "object")
       throw new TypeError("Session snapshot must be an object");
     const snapshot = value;
-    if (snapshot.schemaVersion !== 1)
+    if (snapshot.schemaVersion !== 1 && snapshot.schemaVersion !== 2)
       throw new TypeError("Unsupported session snapshot schemaVersion");
     if (typeof snapshot.sessionId !== "string")
       throw new TypeError("Session snapshot sessionId is required");
@@ -3282,6 +3283,12 @@ class JsonSnapshotCodec {
       throw new TypeError("Session snapshot messages must be an array");
     if (typeof snapshot.createdAt !== "number" || typeof snapshot.updatedAt !== "number")
       throw new TypeError("Session snapshot timestamps are required");
+    if (snapshot.schemaVersion === 1) {
+      return structuredClone({
+        ...snapshot,
+        schemaVersion: 1
+      });
+    }
     return structuredClone(snapshot);
   }
 }
@@ -3305,6 +3312,25 @@ function addUsage(left, right) {
   };
 }
 
+// src/agent-core/errors.ts
+class SessionExecutionError extends Error {
+  payload;
+  payloadSummary;
+  constructor(payload) {
+    super(payload.message);
+    this.name = "SessionExecutionError";
+    this.payload = payload;
+    this.payloadSummary = stringifyPayload(payload);
+  }
+}
+function stringifyPayload(payload) {
+  try {
+    return JSON.stringify(payload, null, 2);
+  } catch {
+    return String(payload);
+  }
+}
+
 // src/agent-core/tool-call.ts
 function startToolCall(callId, toolName) {
   if (!callId.trim())
@@ -3337,25 +3363,6 @@ function finalizeToolCall(draft) {
   };
 }
 
-// src/agent-core/errors.ts
-class SessionExecutionError extends Error {
-  payload;
-  payloadSummary;
-  constructor(payload) {
-    super(payload.message);
-    this.name = "SessionExecutionError";
-    this.payload = payload;
-    this.payloadSummary = stringifyPayload(payload);
-  }
-}
-function stringifyPayload(payload) {
-  try {
-    return JSON.stringify(payload, null, 2);
-  } catch {
-    return String(payload);
-  }
-}
-
 // src/agent-core/model-turn-collector.ts
 class DefaultModelTurnCollector {
   async* collect(options) {
@@ -3536,6 +3543,7 @@ class LoopRunner {
           cwd: state.cwd
         }) ?? [];
         const promptSegments = [
+          ...options.persistentPromptSegments ?? [],
           ...pendingContextSegments,
           ...this.contextManager.format(effectiveContext),
           ...pluginPromptSegments
@@ -3977,6 +3985,10 @@ class DefaultToolExecutor {
 }
 
 // src/agent-core/session.ts
+var DEFAULT_MESSAGE_QUEUE_CONFIG = {
+  autoProcessQueue: true
+};
+
 class Session {
   id;
   createdAt;
@@ -3990,7 +4002,14 @@ class Session {
   compactionService;
   pluginStateService;
   pluginControllers;
+  bufferedEvents = [];
+  stateChangeWaiters = [];
   activeRunCount = 0;
+  processingPromise = null;
+  receiveActive = false;
+  activeReceiveSignal;
+  haltProcessingUntilReceive = false;
+  saveChain = Promise.resolve();
   constructor(options) {
     const now = Date.now();
     this.id = options.id ?? createId("session");
@@ -4016,10 +4035,16 @@ class Session {
       usage: options.usage ? { ...options.usage } : createEmptyUsage(),
       compaction: cloneCompactionState(options.compaction ?? createEmptyCompactionState()),
       pluginState: clonePluginStateMap(options.pluginState),
+      messageQueue: cloneMessageQueueSnapshot(options.messageQueue ?? {
+        items: [],
+        config: createMessageQueueConfig(options.messageQueueConfig)
+      }),
       compactionOptions: options.compactionOptions,
       createdAt: this.createdAt,
       updatedAt: options.updatedAt ?? now
     };
+    if (options.messageQueueConfig)
+      this.state.messageQueue.config = createMessageQueueConfig(options.messageQueueConfig, this.state.messageQueue.config);
     this.compactionService.registerSession(this.state);
     this.pluginStateService.registerSession(this.state);
     this.pluginControllers = this.pluginHost?.createSessionControllers({
@@ -4061,6 +4086,91 @@ class Session {
     this.state.cwd = cwd;
     touchRuntimeSessionState(this.state);
   }
+  send(input, options = {}) {
+    return this.enqueueItem("user", input, options);
+  }
+  sendBatch(items) {
+    const maxQueueSize = this.state.messageQueue.config.maxQueueSize;
+    if (maxQueueSize !== undefined && this.state.messageQueue.items.length + items.length > maxQueueSize)
+      throw new SessionExecutionError(createQueueError("DIM_QUEUE_FULL", `Session queue is full (max ${maxQueueSize})`));
+    const prepared = items.map(({ input, options }) => prepareQueueItem("user", input, options));
+    for (const item of prepared)
+      this.state.messageQueue.items.push(item);
+    if (prepared.length > 0)
+      this.onQueueMutated();
+    return prepared.map((item) => item.id);
+  }
+  steer(input, options = {}) {
+    return this.enqueueItem("steer", input, options);
+  }
+  cancelQueuedItem(itemId) {
+    const index = this.state.messageQueue.items.findIndex((item) => item.id === itemId);
+    if (index < 0)
+      return false;
+    this.state.messageQueue.items.splice(index, 1);
+    this.onQueueMutated();
+    return true;
+  }
+  getQueueStatus() {
+    const items = [...this.state.messageQueue.items].sort(compareQueueItems).map((item) => ({
+      id: item.id,
+      kind: item.kind,
+      priority: item.priority,
+      enqueuedAt: item.enqueuedAt,
+      preview: createQueuePreview(item.input)
+    }));
+    return {
+      length: items.length,
+      items,
+      isProcessing: this.processingPromise !== null,
+      config: cloneMessageQueueConfig(this.state.messageQueue.config)
+    };
+  }
+  clearQueue(filter = {}) {
+    const before = this.state.messageQueue.items.length;
+    if (!filter.kind) {
+      this.state.messageQueue.items = [];
+    } else {
+      this.state.messageQueue.items = this.state.messageQueue.items.filter((item) => item.kind !== filter.kind);
+    }
+    const cleared = before - this.state.messageQueue.items.length;
+    if (cleared > 0)
+      this.onQueueMutated();
+    return cleared;
+  }
+  async* receive(options = {}) {
+    if (this.receiveActive)
+      throw new SessionExecutionError(createQueueError("DIM_QUEUE_BUSY", "Only one receive() call can be active for a session"));
+    this.receiveActive = true;
+    this.activeReceiveSignal = options.signal;
+    this.haltProcessingUntilReceive = false;
+    let deliveredEvent = null;
+    try {
+      while (true) {
+        if (deliveredEvent) {
+          deliveredEvent.ack();
+          deliveredEvent = null;
+        }
+        this.ensureQueueProcessing("receive");
+        const nextBufferedEvent = this.bufferedEvents.shift();
+        if (nextBufferedEvent) {
+          deliveredEvent = nextBufferedEvent;
+          yield nextBufferedEvent.event;
+          continue;
+        }
+        if (!this.processingPromise && !this.hasRunnableItems())
+          return;
+        await this.waitForStateChange(options.signal);
+      }
+    } finally {
+      if (deliveredEvent)
+        deliveredEvent.ack();
+      this.receiveActive = false;
+      if (this.activeReceiveSignal === options.signal)
+        this.activeReceiveSignal = undefined;
+      this.notifyStateChange();
+    }
+  }
   async compact(update) {
     const beforeState = this.getCompactionState();
     const estimatedInputTokens = await this.readEstimatedInputTokens();
@@ -4109,6 +4219,9 @@ class Session {
     });
   }
   async save() {
+    return this.enqueueSave();
+  }
+  async writeSnapshot() {
     if (!this.stateStore)
       return;
     let snapshot = this.toSnapshot();
@@ -4143,37 +4256,181 @@ class Session {
       pluginState: this.listPluginStates(),
       createdAt: this.createdAt,
       updatedAt: this.updatedAt,
-      metadata: this.state.metadata ? { ...this.state.metadata } : undefined
+      metadata: this.state.metadata ? { ...this.state.metadata } : undefined,
+      messageQueue: cloneMessageQueueSnapshot(this.state.messageQueue)
     });
   }
-  async send(input, options) {
-    const stream = this.stream(input, options);
-    let doneMessage;
+  enqueueItem(kind, input, options) {
+    const maxQueueSize = this.state.messageQueue.config.maxQueueSize;
+    if (maxQueueSize !== undefined && this.state.messageQueue.items.length >= maxQueueSize)
+      throw new SessionExecutionError(createQueueError("DIM_QUEUE_FULL", `Session queue is full (max ${maxQueueSize})`));
+    const item = prepareQueueItem(kind, input, options);
+    this.state.messageQueue.items.push(item);
+    this.onQueueMutated();
+    return item.id;
+  }
+  onQueueMutated() {
+    touchRuntimeSessionState(this.state);
+    this.notifyStateChange();
+    this.scheduleSave();
+    this.ensureQueueProcessing("auto");
+  }
+  hasRunnableItems() {
+    return this.state.messageQueue.items.some((item) => item.kind === "user");
+  }
+  ensureQueueProcessing(source) {
+    if (this.processingPromise)
+      return;
+    if (!this.hasRunnableItems())
+      return;
+    if (this.haltProcessingUntilReceive && source !== "receive")
+      return;
+    const signal = source === "receive" ? this.activeReceiveSignal : undefined;
+    this.processingPromise = this.processQueue(signal).finally(() => {
+      this.processingPromise = null;
+      this.notifyStateChange();
+      if (!this.haltProcessingUntilReceive && this.state.messageQueue.config.autoProcessQueue)
+        this.ensureQueueProcessing("auto");
+    });
+    this.notifyStateChange();
+  }
+  async processQueue(signal) {
     while (true) {
-      const next = await stream.next();
-      if (next.done) {
-        doneMessage = next.value;
-        break;
+      const nextItem = this.dequeueNextRunnableItem();
+      if (!nextItem)
+        return;
+      const completed = await this.processQueuedItem(nextItem, signal);
+      await this.persistStateQuietly();
+      if (!completed) {
+        this.haltProcessingUntilReceive = true;
+        return;
       }
     }
-    if (!doneMessage)
-      throw new Error("Session completed without a final assistant message");
-    return doneMessage;
   }
-  async* stream(input, options) {
+  dequeueNextRunnableItem() {
+    const rankedItems = [...this.state.messageQueue.items].sort(compareQueueItems);
+    const userIndex = rankedItems.findIndex((item) => item.kind === "user");
+    if (userIndex < 0)
+      return null;
+    const userItem = rankedItems[userIndex];
+    const steerItems = rankedItems.slice(0, userIndex).filter((item) => item.kind === "steer");
+    const consumedIds = new Set([userItem.id, ...steerItems.map((item) => item.id)]);
+    this.state.messageQueue.items = this.state.messageQueue.items.filter((item) => !consumedIds.has(item.id));
+    touchRuntimeSessionState(this.state);
+    this.notifyStateChange();
+    return {
+      item: userItem,
+      steerSegments: steerItems.map((item) => contentToText(normalizeContent(item.input)).trim()).filter((segment) => segment.length > 0)
+    };
+  }
+  async processQueuedItem(input, signal) {
     const runner = this.createLoopRunner();
+    let emittedError = false;
     this.activeRunCount += 1;
     try {
-      return yield* runner.run(this.state, input, {
-        signal: options?.signal,
-        onDone: async () => {
-          await this.save();
-        }
+      const iterator = runner.run(this.state, input.item.input, {
+        signal,
+        persistentPromptSegments: input.steerSegments
       });
+      while (true) {
+        const next = await iterator.next();
+        if (next.done)
+          return true;
+        const queuedEvent = this.attachQueueContext(next.value, input.item);
+        if (queuedEvent.type === "error")
+          emittedError = true;
+        await this.pushBufferedEvent(queuedEvent);
+      }
+    } catch (error) {
+      if (!emittedError)
+        await this.pushBufferedEvent(this.createErrorEvent(input.item, error));
+      return false;
     } finally {
       this.activeRunCount = Math.max(0, this.activeRunCount - 1);
+      this.notifyStateChange();
     }
   }
+  attachQueueContext(event, item) {
+    return {
+      ...event,
+      itemId: item.id,
+      itemKind: item.kind,
+      priority: item.priority
+    };
+  }
+  createErrorEvent(item, error) {
+    const payload = error instanceof SessionExecutionError ? error.payload : {
+      code: "runtime_error",
+      message: error instanceof Error ? error.message : String(error)
+    };
+    return {
+      type: "error",
+      sessionId: this.id,
+      error: payload,
+      itemId: item.id,
+      itemKind: item.kind,
+      priority: item.priority
+    };
+  }
+  async pushBufferedEvent(event) {
+    let resolved = false;
+    const ack = () => {
+      if (resolved)
+        return;
+      resolved = true;
+      this.notifyStateChange();
+    };
+    this.bufferedEvents.push({ event, ack });
+    this.notifyStateChange();
+    while (!resolved)
+      await this.waitForStateChange();
+  }
+  scheduleSave() {
+    if (!this.stateStore)
+      return;
+    this.enqueueSave().catch(() => {
+      return;
+    });
+  }
+  async persistStateQuietly() {
+    try {
+      await this.enqueueSave();
+    } catch {}
+  }
+  enqueueSave() {
+    if (!this.stateStore)
+      return Promise.resolve();
+    this.saveChain = this.saveChain.catch(() => {
+      return;
+    }).then(() => this.writeSnapshot());
+    return this.saveChain;
+  }
+  waitForStateChange(signal) {
+    if (signal?.aborted)
+      return Promise.reject(new SessionExecutionError(createQueueError("session_receive_aborted", "Session receive aborted")));
+    return new Promise((resolve, reject) => {
+      const onAbort = () => {
+        cleanup();
+        reject(new SessionExecutionError(createQueueError("session_receive_aborted", "Session receive aborted")));
+      };
+      const resume = () => {
+        cleanup();
+        resolve();
+      };
+      const cleanup = () => {
+        const index = this.stateChangeWaiters.indexOf(resume);
+        if (index >= 0)
+          this.stateChangeWaiters.splice(index, 1);
+        signal?.removeEventListener("abort", onAbort);
+      };
+      this.stateChangeWaiters.push(resume);
+      signal?.addEventListener("abort", onAbort, { once: true });
+    });
+  }
+  notifyStateChange() {
+    while (this.stateChangeWaiters.length > 0)
+      this.stateChangeWaiters.shift()?.();
+  }
   createLoopRunner() {
     return new LoopRunner({
       messageFactory: new DefaultMessageFactory,
@@ -4221,6 +4478,63 @@ class Session {
     };
   }
 }
+function createMessageQueueConfig(overrides, base = DEFAULT_MESSAGE_QUEUE_CONFIG) {
+  return {
+    autoProcessQueue: overrides?.autoProcessQueue ?? base.autoProcessQueue,
+    maxQueueSize: overrides?.maxQueueSize ?? base.maxQueueSize
+  };
+}
+function cloneMessageQueueConfig(config) {
+  return {
+    autoProcessQueue: config.autoProcessQueue,
+    maxQueueSize: config.maxQueueSize
+  };
+}
+function clonePendingMessage(item) {
+  return {
+    id: item.id,
+    input: structuredClone(item.input),
+    kind: item.kind,
+    priority: item.priority,
+    enqueuedAt: item.enqueuedAt
+  };
+}
+function cloneMessageQueueSnapshot(snapshot) {
+  return {
+    items: snapshot.items.map(clonePendingMessage),
+    config: cloneMessageQueueConfig(snapshot.config)
+  };
+}
+function prepareQueueItem(kind, input, options = {}) {
+  const normalizedInput = normalizeContent(input);
+  if (kind === "steer" && contentToText(normalizedInput).trim().length === 0)
+    throw new TypeError("Steer content must contain text");
+  return {
+    id: createId("item"),
+    input: structuredClone(input),
+    kind,
+    priority: options.priority ?? 0,
+    enqueuedAt: Date.now()
+  };
+}
+function compareQueueItems(left, right) {
+  if (left.priority !== right.priority)
+    return right.priority - left.priority;
+  if (left.enqueuedAt !== right.enqueuedAt)
+    return left.enqueuedAt - right.enqueuedAt;
+  return left.id.localeCompare(right.id);
+}
+function createQueuePreview(input) {
+  const text = contentToText(normalizeContent(input)).trim();
+  if (text.length === 0)
+    return "[non-text content]";
+  if (text.length <= 80)
+    return text;
+  return `${text.slice(0, 77)}...`;
+}
+function createQueueError(code, message) {
+  return { code, message };
+}
 
 // src/agent-core/agent.ts
 class Agent {
@@ -4292,6 +4606,7 @@ class Agent {
       metadata: options.metadata ?? this.options.metadata,
       reasoning: this.options.reasoning,
       compactionOptions: this.options.compaction,
+      messageQueueConfig: options.messageQueueConfig,
       messages,
       pluginHost: this.pluginHost,
       contextManager: this.contextManager,
@@ -4325,6 +4640,7 @@ class Agent {
       usage: snapshot.usage,
       compaction: snapshot.compaction,
       pluginState: snapshot.pluginState,
+      messageQueue: snapshot.messageQueue,
       compactionOptions: this.options.compaction,
       createdAt: snapshot.createdAt,
       updatedAt: snapshot.updatedAt,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@archships/dim-agent-sdk",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "description": "An agent-first TypeScript SDK with provider adapters, sessions, hooks, plugins, and runtime gateways.",
   "type": "module",
   "exports": {