@aragon-agent/core 0.2.23 → 0.2.24

package/CHANGELOG.md

@@ -7,7 +7,14 @@ were written.
 
 ## Unreleased
 
-### Added
+### Added
+
+- **Steering 精确接收回执。** `Agent.steer(text, id?)` 兼容原单参数调用，
+  历史接收后发出 `steering_accepted`，只确认当前批次的 ID；新增类型
+  `SteeringMessage` 和 `SteeringAcceptedEvent`，无新增运行时导出。
+  `drainSteeringItems()` 与原 `drainSteering()` 共用一个队列。
+  接收早于异步压缩，未执行工具先补齐 skipped 结果；无工具响应在结束前再次检查
+  steering，避免流式输出期间提交的消息滞留。回执仅代表历史接收，不代表回答完成。
 
 - **Tail relief — the last rung of the compaction ladder.** `relieveTail` joins
   the root barrel with `TailReliefOptions` and `TailReliefResult` (85 → 86

package/dist/engine/accept-steering.d.ts

@@ -0,0 +1,3 @@
+import type { AgentLoopContext } from './agent-loop.js';
+/** Accept one batch atomically with respect to async work and receipt listeners. */
+export declare function acceptSteering(ctx: AgentLoopContext): void;

package/dist/engine/accept-steering.js

@@ -0,0 +1,15 @@
+/** Accept one batch atomically with respect to async work and receipt listeners. */
+export function acceptSteering(ctx) {
+    if (ctx.signal.aborted)
+        return;
+    const items = ctx.messageQueueManager.drainSteeringItems();
+    const ids = [];
+    for (const item of items) {
+        ctx.messageManager.push({ role: 'user', content: item.text, timestamp: Date.now() });
+        if (item.id !== undefined)
+            ids.push(item.id);
+    }
+    // The entire batch must be in history before listeners can abort or enqueue more work.
+    if (ids.length > 0)
+        ctx.emit({ type: 'steering_accepted', ids });
+}

package/dist/engine/agent-loop.js

@@ -6,6 +6,7 @@
  * block detection and execution.
  */
 import { validateHistory } from './compaction.js';
+import { acceptSteering } from './accept-steering.js';
 import { estimatePromptTokens } from '../llm/output-limits.js';
 // ---------------------------------------------------------------------------
 // Compaction checkpoint (context-auto-compaction §3.3)
@@ -239,6 +240,21 @@ function getAssistantText(message) {
 function getToolCalls(message) {
     return message.content.filter((b) => b.type === 'tool_call');
 }
+/** Close the outstanding tool batch before steering creates the next user turn. */
+function acceptToolSteering(ctx, remainingCalls) {
+    if (ctx.signal.aborted || !ctx.messageQueueManager.hasSteering())
+        return false;
+    for (const skipped of remainingCalls) {
+        ctx.messageManager.push({
+            role: 'tool_result',
+            toolCallId: skipped.toolCallId,
+            content: 'Tool execution skipped due to steering interrupt.',
+            isError: true,
+        });
+    }
+    acceptSteering(ctx);
+    return true;
+}
 // ---------------------------------------------------------------------------
 // runAgentLoop
 // ---------------------------------------------------------------------------
@@ -263,14 +279,7 @@ export async function runAgentLoop(ctx) {
     let overflowRecovered = false;
     while (!ctx.signal.aborted) {
         // ----- Steering checkpoint (before LLM call) -----
-        if (ctx.messageQueueManager.hasSteering()) {
-            const steeringMessages = ctx.messageQueueManager.drainSteering();
-            for (const text of steeringMessages) {
-                const userMsg = { role: 'user', content: text, timestamp: Date.now() };
-                ctx.messageManager.push(userMsg);
-            }
-            // Continue to LLM call with injected steering messages.
-        }
+        acceptSteering(ctx);
         turnIndex += 1;
         // ----- Context pressure checkpoint (context-auto-compaction §3.3) -----
         //
@@ -375,6 +384,8 @@ export async function runAgentLoop(ctx) {
         lastUsage = usage;
         overflowRecovered = false;
         ctx.messageManager.push(assistantMessage);
+        if (ctx.signal.aborted)
+            break;
         // ----- Process tool calls -----
         const toolCalls = getToolCalls(assistantMessage);
         const hasToolCalls = toolCalls.length > 0;
@@ -382,12 +393,7 @@ export async function runAgentLoop(ctx) {
         if (hasToolCalls) {
             // Steering checkpoint: if steering arrived during the LLM call,
             // skip tool execution and inject steering messages instead.
-            if (ctx.messageQueueManager.hasSteering()) {
-                const steeringMessages = ctx.messageQueueManager.drainSteering();
-                for (const text of steeringMessages) {
-                    const userMsg = { role: 'user', content: text, timestamp: Date.now() };
-                    ctx.messageManager.push(userMsg);
-                }
+            if (acceptToolSteering(ctx, toolCalls)) {
                 // Loop continues — LLM will see the steering messages.
                 continue;
             }
@@ -396,23 +402,7 @@ export async function runAgentLoop(ctx) {
                 if (ctx.signal.aborted)
                     break;
                 // Check steering between individual tool executions.
-                if (ctx.messageQueueManager.hasSteering()) {
-                    // Inject remaining tool results as errors so LLM knows they were skipped.
-                    const remainingCalls = toolCalls.slice(toolCalls.indexOf(toolCall));
-                    for (const skipped of remainingCalls) {
-                        ctx.messageManager.push({
-                            role: 'tool_result',
-                            toolCallId: skipped.toolCallId,
-                            content: 'Tool execution skipped due to steering interrupt.',
-                            isError: true,
-                        });
-                    }
-                    // Inject steering messages.
-                    const steeringMessages = ctx.messageQueueManager.drainSteering();
-                    for (const text of steeringMessages) {
-                        const userMsg = { role: 'user', content: text, timestamp: Date.now() };
-                        ctx.messageManager.push(userMsg);
-                    }
+                if (acceptToolSteering(ctx, toolCalls.slice(toolCalls.indexOf(toolCall)))) {
                     steeringInterrupted = true;
                     break;
                 }
@@ -508,7 +498,9 @@ export async function runAgentLoop(ctx) {
         }
         // ----- Exit or follow-up checkpoint -----
         if (!hasToolCalls && !hasCodeBlocks) {
-            // No tools and no code blocks — check for follow-up messages.
+            // Give streaming and turn_end steering priority over follow-up and normal exit.
+            if (ctx.messageQueueManager.hasSteering())
+                continue;
             if (ctx.messageQueueManager.hasFollowUp()) {
                 const followUpMessages = ctx.messageQueueManager.drainFollowUp();
                 for (const text of followUpMessages) {

package/dist/engine/agent.d.ts

@@ -128,8 +128,8 @@ export declare class Agent {
      * @returns An unsubscribe function.
      */
     subscribe(listener: AgentEventListener): () => void;
-    /** Inject a high-priority steering message (interrupts tool execution). */
-    steer(message: string): void;
+    /** Queue high-priority text; an optional ID is echoed only after history acceptance. */
+    steer(message: string, id?: string): void;
     /** Queue a low-priority follow-up message (consumed after end_turn). */
     followUp(message: string): void;
     setModel(model: ModelRef): void;

package/dist/engine/agent.js

@@ -156,9 +156,9 @@ export class Agent {
     // =========================================================================
     // Message queues
     // =========================================================================
-    /** Inject a high-priority steering message (interrupts tool execution). */
-    steer(message) {
-        this.messageQueueManager.pushSteering(message);
+    /** Queue high-priority text; an optional ID is echoed only after history acceptance. */
+    steer(message, id) {
+        this.messageQueueManager.pushSteering(message, id);
     }
     /** Queue a low-priority follow-up message (consumed after end_turn). */
     followUp(message) {

package/dist/engine/steering.d.ts

@@ -7,13 +7,20 @@
  * Follow-up messages have low priority: they are consumed only when the
  * Agent loop would otherwise exit (end_turn with no pending work).
  */
+/** Queued text with an optional host-supplied opaque receipt identifier. */
+export interface SteeringMessage {
+    readonly text: string;
+    readonly id?: string;
+}
 export declare class MessageQueueManager {
     private readonly steeringQueue;
     private readonly followUpQueue;
     /** Enqueue a high-priority steering message. */
-    pushSteering(message: string): void;
+    pushSteering(message: string, id?: string): void;
     /** Drain and return all pending steering messages (empties the queue). */
     drainSteering(): string[];
+    /** Drain all pending envelopes in FIFO order (empties the same queue). */
+    drainSteeringItems(): SteeringMessage[];
     /** Whether there are pending steering messages. */
     hasSteering(): boolean;
     /** Enqueue a low-priority follow-up message. */

package/dist/engine/steering.js

@@ -14,11 +14,15 @@ export class MessageQueueManager {
     // Steering
     // -----------------------------------------------------------------------
     /** Enqueue a high-priority steering message. */
-    pushSteering(message) {
-        this.steeringQueue.push(message);
+    pushSteering(message, id) {
+        this.steeringQueue.push({ text: message, ...(id !== undefined ? { id } : {}) });
     }
     /** Drain and return all pending steering messages (empties the queue). */
     drainSteering() {
+        return this.drainSteeringItems().map((item) => item.text);
+    }
+    /** Drain all pending envelopes in FIFO order (empties the same queue). */
+    drainSteeringItems() {
         return this.steeringQueue.splice(0);
     }
     /** Whether there are pending steering messages. */

package/dist/index.d.ts

@@ -41,13 +41,14 @@ export { createSkillFindTool } from './skills/skill-find-tool.js';
 export { computeToolPolicy, evaluateToolCall } from './skills/tool-policy.js';
 export { SKILL_CATALOG_MAX_BYTES, SKILL_BODY_MAX_BYTES, SKILL_RESULT_MAX_BYTES, ALWAYS_SKILLS_MAX_BYTES, SKILL_MD_MAX_BYTES, SKILL_DESC_LINE_MAX, SKILL_FILES_MAX, SKILL_FIND_MAX_BYTES, SKILL_NAME_PATTERN, } from './skills/constants.js';
 export type { SkillScope, SkillActivation, SkillFrontmatter, SkillRecord, SkillFileRef, SkillHost, SkillManifest, SkillValidationIssue, SkillCatalogOptions, SkillBodyOptions, SkillFindOptions, SkillIntegrity, SkillUsageStat, SkillUsageMap, SkillInvocationOptions, SkillPlatform, SkillPolicyView, SkillToolPolicyMode, ToolPolicyDecision, ToolPolicyInput, ToolPolicySource, ToolPolicyVerdict, } from './skills/types.js';
-export type { AgentEvent, AgentEventListener, AgentStartEvent, AgentEndEvent, TurnStartEvent, TurnEndEvent, MessageUpdateEvent, ToolExecutionStartEvent, ToolExecutionEndEvent, CodeExecutionStartEvent, CodeExecutionEndEvent, CompactionStartEvent, CompactionEndEvent, } from './types.js';
+export type { AgentEvent, AgentEventListener, AgentStartEvent, AgentEndEvent, TurnStartEvent, SteeringAcceptedEvent, TurnEndEvent, MessageUpdateEvent, ToolExecutionStartEvent, ToolExecutionEndEvent, CodeExecutionStartEvent, CodeExecutionEndEvent, CompactionStartEvent, CompactionEndEvent, } from './types.js';
 export { Agent } from './engine/agent.js';
 export type { AgentConfig, AgentState } from './engine/agent.js';
 export type { ModelRef } from './engine/agent-loop.js';
 export type { CodeActSandbox, CodeActResult } from './engine/agent-loop.js';
 export { MessageManager } from './engine/message-manager.js';
 export { MessageQueueManager } from './engine/steering.js';
+export type { SteeringMessage } from './engine/steering.js';
 export { IdleWatchdog } from './engine/watchdog.js';
 export { findSafeCutIndices, planCompaction, relieveTail, validateHistory, } from './engine/compaction.js';
 export type { CompactionPlan, HistoryCheck, PlanCompactionOptions, TailReliefOptions, TailReliefResult, ValidateHistoryOptions, } from './engine/compaction.js';

package/dist/types.d.ts

@@ -17,6 +17,11 @@ export interface AgentEndEvent {
 export interface TurnStartEvent {
     type: 'turn_start';
 }
+/** Text for these opaque IDs has entered history, not necessarily reached the model. */
+export interface SteeringAcceptedEvent {
+    type: 'steering_accepted';
+    ids: readonly string[];
+}
 export interface TurnEndEvent {
     type: 'turn_end';
     message: AssistantMessage;
@@ -107,6 +112,6 @@ export interface CompactionEndEvent {
     durationMs: number;
 }
 /** Union of all events emitted by the Agent engine. */
-export type AgentEvent = AgentStartEvent | AgentEndEvent | TurnStartEvent | TurnEndEvent | MessageUpdateEvent | ToolExecutionStartEvent | ToolExecutionEndEvent | CodeExecutionStartEvent | CodeExecutionEndEvent | CompactionStartEvent | CompactionEndEvent;
+export type AgentEvent = AgentStartEvent | AgentEndEvent | TurnStartEvent | SteeringAcceptedEvent | TurnEndEvent | MessageUpdateEvent | ToolExecutionStartEvent | ToolExecutionEndEvent | CodeExecutionStartEvent | CodeExecutionEndEvent | CompactionStartEvent | CompactionEndEvent;
 /** Callback signature for Agent event listeners. */
 export type AgentEventListener = (event: AgentEvent) => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aragon-agent/core",
-  "version": "0.2.23",
+  "version": "0.2.24",
   "description": "AragonAgent core engine — LLM provider adapters, streaming, tool registry/execution, steering, idle watchdog, and an optional isolated-vm sandbox.",
   "license": "MIT",
   "author": "AragonAgent contributors",