@code-yeongyu/senpi-agent-core 2026.10.18-1 → 2026.10.19

package/dist/agent-loop.js

@@ -105,19 +105,29 @@ async function runLoop(initialContext, newMessages, initialConfig, signal, emit,
     let explicitContinuation = false;
     // Messages from `prepareNextTurn`, appended before the next provider request.
     let preparedMessages = [];
+    // Which queue the current pendingMessages were drained from, so consumption is committed against it.
+    let pendingSource = "steering";
+    const drainSteering = async () => {
+        pendingSource = "steering";
+        return (await config.getSteeringMessages?.()) || [];
+    };
+    const drainFollowUp = async () => {
+        pendingSource = "followUp";
+        return (await config.getFollowUpMessages?.()) || [];
+    };
     const refreshTerminatingQueueDrain = async () => {
         if (!drainedTerminatingQueue || !config.restorePendingMessages)
             return;
         await config.restorePendingMessages(drainedTerminatingQueue, pendingMessages);
-        pendingMessages = (await config.getSteeringMessages?.()) || [];
+        pendingMessages = await drainSteering();
         drainedTerminatingQueue = pendingMessages.length > 0 ? "steering" : undefined;
         if (pendingMessages.length === 0) {
-            pendingMessages = (await config.getFollowUpMessages?.()) || [];
+            pendingMessages = await drainFollowUp();
             drainedTerminatingQueue = pendingMessages.length > 0 ? "followUp" : undefined;
         }
     };
     // Check for steering messages at start (user may have typed while waiting)
-    let pendingMessages = (await config.getSteeringMessages?.()) || [];
+    let pendingMessages = await drainSteering();
     // Outer loop: continues when queued follow-up messages arrive after agent would stop
     while (true) {
         let hasMoreToolCalls = true;
@@ -140,6 +150,17 @@ async function runLoop(initialContext, newMessages, initialConfig, signal, emit,
                 }
                 drainedTerminatingQueue = undefined;
             }
+            // Commit the queued messages' consumption before any of them reaches the context or a provider;
+            // a rejected commit restores them and fails this attempt.
+            if (pendingMessages.length > 0 && config.commitQueuedConsumption) {
+                try {
+                    await config.commitQueuedConsumption(pendingSource, pendingMessages);
+                }
+                catch (error) {
+                    await config.restorePendingMessages?.(pendingSource, pendingMessages);
+                    throw error;
+                }
+            }
             // Process prepared and queued messages before the next assistant response.
             for (const message of declareToolChanges(currentContext, [...preparedMessages, ...pendingMessages], config.model)) {
                 await emit({ type: "message_start", message });
@@ -224,11 +245,11 @@ async function runLoop(initialContext, newMessages, initialConfig, signal, emit,
             }
             explicitContinuation = decision?.action === "continue";
             if (toolBatchTerminated) {
-                pendingMessages = (await config.getSteeringMessages?.()) || [];
+                pendingMessages = await drainSteering();
                 if (pendingMessages.length > 0)
                     drainedTerminatingQueue = "steering";
                 if (pendingMessages.length === 0) {
-                    pendingMessages = (await config.getFollowUpMessages?.()) || [];
+                    pendingMessages = await drainFollowUp();
                     if (pendingMessages.length > 0)
                         drainedTerminatingQueue = "followUp";
                 }
@@ -272,14 +293,14 @@ async function runLoop(initialContext, newMessages, initialConfig, signal, emit,
                 drainedTerminatingQueue = undefined;
             }
             if (!toolBatchTerminated) {
-                pendingMessages = (await config.getSteeringMessages?.()) || [];
+                pendingMessages = await drainSteering();
             }
             if (hasMoreToolCalls || pendingMessages.length > 0) {
                 explicitContinuation = false;
             }
         }
         // Agent would stop here. Check for follow-up messages.
-        const followUpMessages = (await config.getFollowUpMessages?.()) || [];
+        const followUpMessages = await drainFollowUp();
         if (followUpMessages.length > 0) {
             // Set as pending so inner loop processes them
             explicitContinuation = false;

package/dist/agent.d.ts

@@ -24,6 +24,8 @@ export interface AgentOptions {
     prepareNextTurnWithContext?: (context: PrepareNextTurnContext, signal?: AbortSignal) => Promise<AgentLoopTurnUpdate | undefined> | AgentLoopTurnUpdate | undefined;
     steeringMode?: QueueMode;
     followUpMode?: QueueMode;
+    /** Lets the owner of queued input commit its consumption before the loop sends it (senpi#3549). */
+    queuedInputPort?: QueuedInputPort;
     sessionId?: string;
     thinkingBudgets?: ThinkingBudgets;
     transport?: Transport;
@@ -37,6 +39,26 @@ export interface AgentOptions {
     /** Cursor exec-channel tool handlers; see {@link AgentLoopConfig.cursorExecHandlers}. */
     cursorExecHandlers?: AgentLoopConfig["cursorExecHandlers"];
 }
+/**
+ * Claimed messages going back to their queue. Both answers are false once a clear landed after the claim:
+ * `restorable` asks before anything is recorded, `restore` puts the messages back only while that still holds.
+ */
+export interface QueuedGiveBack {
+    restorable(): boolean;
+    restore(): boolean;
+}
+/** The owner side of the steering and follow-up queues; every drain, restore and consumption goes through it. */
+export interface QueuedInputPort {
+    /** Runs `drain` (the native queue's drain) under the owner's gate and returns what it may hand to a turn. */
+    claim(queue: "steering" | "followUp", drain: () => AgentMessage[]): Promise<AgentMessage[]>;
+    /** Gives claimed messages back under the owner's gate; a clear that landed after the claim wins. */
+    release(queue: "steering" | "followUp", messages: AgentMessage[], giveBack: QueuedGiveBack): Promise<void>;
+    /**
+     * Called with drained queued messages before any of them enters the context or a provider request.
+     * Resolve once their consumption is durable; a rejection restores them and fails this attempt.
+     */
+    commitConsumption(queue: "steering" | "followUp", messages: AgentMessage[]): Promise<void>;
+}
 export interface AgentContinuationOptions {
     /** Keep queued steering and follow-up input out of the continuation's first provider request only. */
     deferQueuedMessages?: boolean;
@@ -66,6 +88,7 @@ export declare class Agent {
     beforeToolCall?: (context: BeforeToolCallContext, signal?: AbortSignal) => Promise<BeforeToolCallResult | undefined>;
     afterToolCall?: (context: AfterToolCallContext, signal?: AbortSignal) => Promise<AfterToolCallResult | undefined>;
     finishTurn?: FinishTurn;
+    queuedInputPort?: QueuedInputPort;
     prepareRequest?: PrepareRequest;
     prepareNextTurn?: (signal?: AbortSignal) => Promise<AgentLoopTurnUpdate | undefined> | AgentLoopTurnUpdate | undefined;
     prepareNextTurnWithContext?: (context: PrepareNextTurnContext, signal?: AbortSignal) => Promise<AgentLoopTurnUpdate | undefined> | AgentLoopTurnUpdate | undefined;
@@ -173,6 +196,18 @@ export declare class Agent {
     continue(options?: AgentContinuationOptions): Promise<void>;
     private normalizePromptInput;
     private runPromptMessages;
+    /**
+     * Starts a run from one queue. Without a port the queue is drained now, as before; with one, the drain is
+     * claimed and its consumption committed inside the run, before any of it reaches the context.
+     */
+    private runQueuedMessages;
+    /**
+     * Takes one queue's messages for a run: a plain drain without a port; with one, a claim whose consumption is
+     * committed before the caller puts anything into the context, released again if that commit fails.
+     */
+    private takeQueuedMessages;
+    /** The one give-back every queue exit uses: a clear since `generation` (read at the claim) wins. */
+    private giveBack;
     private runContinuation;
     private createContextSnapshot;
     private createLoopConfig;

package/dist/agent.js

@@ -148,6 +148,7 @@ export class Agent {
         this.beforeToolCall = runtimeOptions.beforeToolCall;
         this.afterToolCall = runtimeOptions.afterToolCall;
         this.finishTurn = runtimeOptions.finishTurn;
+        this.queuedInputPort = runtimeOptions.queuedInputPort;
         this.prepareRequest = runtimeOptions.prepareRequest;
         this.prepareNextTurn = runtimeOptions.prepareNextTurn;
         this.prepareNextTurnWithContext = runtimeOptions.prepareNextTurnWithContext;
@@ -303,18 +304,16 @@ export class Agent {
             await this.continue(options);
             return;
         }
-        const queuedSteering = this.steeringQueue.drain();
-        if (queuedSteering.length > 0) {
-            await this.runPromptMessages(queuedSteering, {
+        if (this.steeringQueue.hasItems()) {
+            await this.runQueuedMessages("steering", {
                 skipInitialSteeringPoll: true,
                 initialRequestTimeoutMs: options.timeoutMs,
                 initialRequestStreamStartTimeoutMs: options.streamStartTimeoutMs,
             });
             return;
         }
-        const queuedFollowUps = this.followUpQueue.drain();
-        if (queuedFollowUps.length > 0) {
-            await this.runPromptMessages(queuedFollowUps, {
+        if (this.followUpQueue.hasItems()) {
+            await this.runQueuedMessages("followUp", {
                 initialRequestTimeoutMs: options.timeoutMs,
                 initialRequestStreamStartTimeoutMs: options.streamStartTimeoutMs,
             });
@@ -336,18 +335,16 @@ export class Agent {
             throw new Error("No messages to continue from");
         }
         if (lastMessage.role === "assistant") {
-            const queuedSteering = this.steeringQueue.drain();
-            if (queuedSteering.length > 0) {
-                await this.runPromptMessages(queuedSteering, {
+            if (this.steeringQueue.hasItems()) {
+                await this.runQueuedMessages("steering", {
                     skipInitialSteeringPoll: true,
                     initialRequestTimeoutMs: options.timeoutMs,
                     initialRequestStreamStartTimeoutMs: options.streamStartTimeoutMs,
                 });
                 return;
             }
-            const queuedFollowUps = this.followUpQueue.drain();
-            if (queuedFollowUps.length > 0) {
-                await this.runPromptMessages(queuedFollowUps, {
+            if (this.followUpQueue.hasItems()) {
+                await this.runQueuedMessages("followUp", {
                     initialRequestTimeoutMs: options.timeoutMs,
                     initialRequestStreamStartTimeoutMs: options.streamStartTimeoutMs,
                 });
@@ -375,6 +372,63 @@ export class Agent {
             await runAgentLoop(messages, this.createContextSnapshot(), this.createLoopConfig(options), (event) => this.processEvents(event), signal, this.streamFunction);
         });
     }
+    /**
+     * Starts a run from one queue. Without a port the queue is drained now, as before; with one, the drain is
+     * claimed and its consumption committed inside the run, before any of it reaches the context.
+     */
+    async runQueuedMessages(queue, options) {
+        const pendingQueue = queue === "steering" ? this.steeringQueue : this.followUpQueue;
+        const port = this.queuedInputPort;
+        if (!port) {
+            await this.runPromptMessages(pendingQueue.drain(), options);
+            return;
+        }
+        await this.runWithLifecycle(async (signal) => {
+            const messages = await this.takeQueuedMessages(queue);
+            if (messages.length === 0)
+                return;
+            await runAgentLoop(messages, this.createContextSnapshot(), this.createLoopConfig(options), (event) => this.processEvents(event), signal, this.streamFunction);
+        });
+    }
+    /**
+     * Takes one queue's messages for a run: a plain drain without a port; with one, a claim whose consumption is
+     * committed before the caller puts anything into the context, released again if that commit fails.
+     */
+    async takeQueuedMessages(queue) {
+        const pendingQueue = queue === "steering" ? this.steeringQueue : this.followUpQueue;
+        const port = this.queuedInputPort;
+        if (!port)
+            return pendingQueue.drain();
+        let generation = pendingQueue.getClearGeneration();
+        const messages = await port.claim(queue, () => {
+            generation = pendingQueue.getClearGeneration();
+            return pendingQueue.drain();
+        });
+        if (messages.length === 0)
+            return messages;
+        try {
+            await port.commitConsumption(queue, messages);
+        }
+        catch (error) {
+            await port.release(queue, messages, this.giveBack(queue, messages, generation));
+            throw error;
+        }
+        return messages;
+    }
+    /** The one give-back every queue exit uses: a clear since `generation` (read at the claim) wins. */
+    giveBack(queue, messages, generation) {
+        const pendingQueue = queue === "steering" ? this.steeringQueue : this.followUpQueue;
+        const restorable = () => pendingQueue.getClearGeneration() === generation;
+        return {
+            restorable,
+            restore: () => {
+                if (!restorable())
+                    return false;
+                pendingQueue.prepend(messages);
+                return true;
+            },
+        };
+    }
     async runContinuation(options = {}) {
         await this.runWithLifecycle(async (signal) => {
             await runAgentLoopContinue(this.createContextSnapshot(), this.createLoopConfig({
@@ -397,6 +451,8 @@ export class Agent {
         let steeringQueueGeneration = this.steeringQueue.getClearGeneration();
         let followUpQueueGeneration = this.followUpQueue.getClearGeneration();
         const finishTurn = this.finishTurn;
+        const queuedInputPort = this.queuedInputPort;
+        const giveBack = (queue, messages) => this.giveBack(queue, messages, queue === "steering" ? steeringQueueGeneration : followUpQueueGeneration);
         const reasoning = this._state.reasoningBaseline ?? this._state.thinkingLevel;
         return {
             model: this._state.model,
@@ -447,23 +503,27 @@ export class Agent {
                     skipInitialSteeringPoll = false;
                     return [];
                 }
-                steeringQueueGeneration = this.steeringQueue.getClearGeneration();
-                return this.steeringQueue.drain();
+                const drain = () => {
+                    steeringQueueGeneration = this.steeringQueue.getClearGeneration();
+                    return this.steeringQueue.drain();
+                };
+                return queuedInputPort ? queuedInputPort.claim("steering", drain) : drain();
             },
             getFollowUpMessages: async () => {
-                followUpQueueGeneration = this.followUpQueue.getClearGeneration();
-                return this.followUpQueue.drain();
+                const drain = () => {
+                    followUpQueueGeneration = this.followUpQueue.getClearGeneration();
+                    return this.followUpQueue.drain();
+                };
+                return queuedInputPort ? queuedInputPort.claim("followUp", drain) : drain();
             },
-            restorePendingMessages: (queue, messages) => {
-                if (queue === "steering") {
-                    if (this.steeringQueue.getClearGeneration() !== steeringQueueGeneration)
-                        return;
-                    this.steeringQueue.prepend(messages);
-                    return;
-                }
-                if (this.followUpQueue.getClearGeneration() !== followUpQueueGeneration)
-                    return;
-                this.followUpQueue.prepend(messages);
+            commitQueuedConsumption: queuedInputPort
+                ? (queue, messages) => queuedInputPort.commitConsumption(queue, messages)
+                : undefined,
+            restorePendingMessages: async (queue, messages) => {
+                if (queuedInputPort)
+                    await queuedInputPort.release(queue, messages, giveBack(queue, messages));
+                else
+                    giveBack(queue, messages).restore();
             },
         };
     }
@@ -506,12 +566,12 @@ export class Agent {
             (lastMessage.stopReason !== "error" && lastMessage.stopReason !== "aborted"));
     }
     async runQueuedMessagesAfterAgentEnd(signal) {
-        const queuedSteering = this.steeringQueue.drain();
+        const queuedSteering = this.steeringQueue.hasItems() ? await this.takeQueuedMessages("steering") : [];
         if (queuedSteering.length > 0) {
             await runAgentLoop(queuedSteering, this.createContextSnapshot(), this.createLoopConfig({ skipInitialSteeringPoll: true }), (event) => this.processEvents(event), signal, this.streamFunction);
             return;
         }
-        const queuedFollowUps = this.followUpQueue.drain();
+        const queuedFollowUps = this.followUpQueue.hasItems() ? await this.takeQueuedMessages("followUp") : [];
         if (queuedFollowUps.length === 0) {
             return;
         }

package/dist/types.d.ts

@@ -299,6 +299,12 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * Restored messages must be placed before messages queued after the drain.
      */
     restorePendingMessages?: (queue: "steering" | "followUp", messages: AgentMessage[]) => Promise<void> | void;
+    /**
+     * Called with the queued messages the loop is about to put into the context, after they were drained and
+     * before any of them is inserted or sent. A rejection keeps them out of this turn (they are restored), so a
+     * message is never seen by a provider without its consumption committed first (senpi#3549).
+     */
+    commitQueuedConsumption?: (queue: "steering" | "followUp", messages: AgentMessage[]) => Promise<void>;
     /**
      * Tool execution mode.
      * - "sequential": execute tool calls one by one

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@code-yeongyu/senpi-agent-core",
-	"version": "2026.10.18-1",
+	"version": "2026.10.19",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
 	"type": "module",
 	"main": "./dist/index.js",
@@ -62,8 +62,8 @@
 	},
 	"dependencies": {
 		"@earendil-works/chord": "0.99.1",
-		"@earendil-works/pi-ai": "npm:@code-yeongyu/senpi-ai@2026.10.18-1",
-		"@earendil-works/pi-telemetry": "npm:@code-yeongyu/senpi-telemetry@2026.10.18-1",
+		"@earendil-works/pi-ai": "npm:@code-yeongyu/senpi-ai@2026.10.19",
+		"@earendil-works/pi-telemetry": "npm:@code-yeongyu/senpi-telemetry@2026.10.19",
 		"diff": "9.0.0",
 		"ignore": "7.0.9",
 		"typebox": "1.3.34",