@hyperspaceng/neural-agent-core 0.64.1 → 0.65.3

package/dist/agent.js

@@ -1,306 +1,366 @@
-/**
- * Agent class that uses the agent-loop directly.
- * No transport abstraction - calls streamSimple via the loop.
- */
-import { getModel, streamSimple, } from "@hyperspaceng/neural-ai";
+import { streamSimple, } from "@hyperspaceng/neural-ai";
 import { runAgentLoop, runAgentLoopContinue } from "./agent-loop.js";
-/**
- * Default convertToLlm: Keep only LLM-compatible messages, convert attachments.
- */
 function defaultConvertToLlm(messages) {
-    return messages.filter((m) => m.role === "user" || m.role === "assistant" || m.role === "toolResult");
+    return messages.filter((message) => message.role === "user" || message.role === "assistant" || message.role === "toolResult");
 }
-export class Agent {
-    _state = {
-        systemPrompt: "",
-        model: getModel("google", "gemini-2.5-flash-lite-preview-06-17"),
-        thinkingLevel: "off",
-        tools: [],
-        messages: [],
+const EMPTY_USAGE = {
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    totalTokens: 0,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+};
+const DEFAULT_MODEL = {
+    id: "unknown",
+    name: "unknown",
+    api: "unknown",
+    provider: "unknown",
+    baseUrl: "",
+    reasoning: false,
+    input: [],
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 0,
+    maxTokens: 0,
+};
+function createMutableAgentState(initialState) {
+    let tools = initialState?.tools?.slice() ?? [];
+    let messages = initialState?.messages?.slice() ?? [];
+    return {
+        systemPrompt: initialState?.systemPrompt ?? "",
+        model: initialState?.model ?? DEFAULT_MODEL,
+        thinkingLevel: initialState?.thinkingLevel ?? "off",
+        get tools() {
+            return tools;
+        },
+        set tools(nextTools) {
+            tools = nextTools.slice();
+        },
+        get messages() {
+            return messages;
+        },
+        set messages(nextMessages) {
+            messages = nextMessages.slice();
+        },
         isStreaming: false,
-        streamMessage: null,
+        streamingMessage: undefined,
         pendingToolCalls: new Set(),
-        error: undefined,
+        errorMessage: undefined,
     };
+}
+class PendingMessageQueue {
+    mode;
+    messages = [];
+    constructor(mode) {
+        this.mode = mode;
+    }
+    enqueue(message) {
+        this.messages.push(message);
+    }
+    hasItems() {
+        return this.messages.length > 0;
+    }
+    drain() {
+        if (this.mode === "all") {
+            const drained = this.messages.slice();
+            this.messages = [];
+            return drained;
+        }
+        const first = this.messages[0];
+        if (!first) {
+            return [];
+        }
+        this.messages = this.messages.slice(1);
+        return [first];
+    }
+    clear() {
+        this.messages = [];
+    }
+}
+/**
+ * Stateful wrapper around the low-level agent loop.
+ *
+ * `Agent` owns the current transcript, emits lifecycle events, executes tools,
+ * and exposes queueing APIs for steering and follow-up messages.
+ */
+export class Agent {
+    _state;
     listeners = new Set();
-    abortController;
+    steeringQueue;
+    followUpQueue;
     convertToLlm;
     transformContext;
-    steeringQueue = [];
-    followUpQueue = [];
-    steeringMode;
-    followUpMode;
     streamFn;
-    _sessionId;
     getApiKey;
-    _onPayload;
-    runningPrompt;
-    resolveRunningPrompt;
-    _thinkingBudgets;
-    _transport;
-    _maxRetryDelayMs;
-    _toolExecution;
-    _beforeToolCall;
-    _afterToolCall;
-    constructor(opts = {}) {
-        this._state = { ...this._state, ...opts.initialState };
-        this.convertToLlm = opts.convertToLlm || defaultConvertToLlm;
-        this.transformContext = opts.transformContext;
-        this.steeringMode = opts.steeringMode || "one-at-a-time";
-        this.followUpMode = opts.followUpMode || "one-at-a-time";
-        this.streamFn = opts.streamFn || streamSimple;
-        this._sessionId = opts.sessionId;
-        this.getApiKey = opts.getApiKey;
-        this._onPayload = opts.onPayload;
-        this._thinkingBudgets = opts.thinkingBudgets;
-        this._transport = opts.transport ?? "sse";
-        this._maxRetryDelayMs = opts.maxRetryDelayMs;
-        this._toolExecution = opts.toolExecution ?? "parallel";
-        this._beforeToolCall = opts.beforeToolCall;
-        this._afterToolCall = opts.afterToolCall;
-    }
-    /**
-     * Get the current session ID used for provider caching.
-     */
-    get sessionId() {
-        return this._sessionId;
-    }
-    /**
-     * Set the session ID for provider caching.
-     * Call this when switching sessions (new session, branch, resume).
-     */
-    set sessionId(value) {
-        this._sessionId = value;
-    }
-    /**
-     * Get the current thinking budgets.
-     */
-    get thinkingBudgets() {
-        return this._thinkingBudgets;
-    }
-    /**
-     * Set custom thinking budgets for token-based providers.
-     */
-    set thinkingBudgets(value) {
-        this._thinkingBudgets = value;
-    }
-    /**
-     * Get the current preferred transport.
-     */
-    get transport() {
-        return this._transport;
-    }
-    /**
-     * Set the preferred transport.
-     */
-    setTransport(value) {
-        this._transport = value;
+    onPayload;
+    beforeToolCall;
+    afterToolCall;
+    activeRun;
+    /** Session identifier forwarded to providers for cache-aware backends. */
+    sessionId;
+    /** Optional per-level thinking token budgets forwarded to the stream function. */
+    thinkingBudgets;
+    /** Preferred transport forwarded to the stream function. */
+    transport;
+    /** Optional cap for provider-requested retry delays. */
+    maxRetryDelayMs;
+    /** Tool execution strategy for assistant messages that contain multiple tool calls. */
+    toolExecution;
+    constructor(options = {}) {
+        this._state = createMutableAgentState(options.initialState);
+        this.convertToLlm = options.convertToLlm ?? defaultConvertToLlm;
+        this.transformContext = options.transformContext;
+        this.streamFn = options.streamFn ?? streamSimple;
+        this.getApiKey = options.getApiKey;
+        this.onPayload = options.onPayload;
+        this.beforeToolCall = options.beforeToolCall;
+        this.afterToolCall = options.afterToolCall;
+        this.steeringQueue = new PendingMessageQueue(options.steeringMode ?? "one-at-a-time");
+        this.followUpQueue = new PendingMessageQueue(options.followUpMode ?? "one-at-a-time");
+        this.sessionId = options.sessionId;
+        this.thinkingBudgets = options.thinkingBudgets;
+        this.transport = options.transport ?? "sse";
+        this.maxRetryDelayMs = options.maxRetryDelayMs;
+        this.toolExecution = options.toolExecution ?? "parallel";
     }
     /**
-     * Get the current max retry delay in milliseconds.
+     * Subscribe to agent lifecycle events.
+     *
+     * Listener promises are awaited in subscription order and are included in
+     * the current run's settlement. Listeners also receive the active abort
+     * signal for the current run.
+     *
+     * `agent_end` is the final emitted event for a run, but the agent does not
+     * become idle until all awaited listeners for that event have settled.
      */
-    get maxRetryDelayMs() {
-        return this._maxRetryDelayMs;
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
     }
     /**
-     * Set the maximum delay to wait for server-requested retries.
-     * Set to 0 to disable the cap.
+     * Current agent state.
+     *
+     * Assigning `state.tools` or `state.messages` copies the provided top-level array.
      */
-    set maxRetryDelayMs(value) {
-        this._maxRetryDelayMs = value;
-    }
-    get toolExecution() {
-        return this._toolExecution;
-    }
-    setToolExecution(value) {
-        this._toolExecution = value;
-    }
-    setBeforeToolCall(value) {
-        this._beforeToolCall = value;
-    }
-    setAfterToolCall(value) {
-        this._afterToolCall = value;
-    }
     get state() {
         return this._state;
     }
-    subscribe(fn) {
-        this.listeners.add(fn);
-        return () => this.listeners.delete(fn);
-    }
-    // State mutators
-    setSystemPrompt(v) {
-        this._state.systemPrompt = v;
-    }
-    setModel(m) {
-        this._state.model = m;
-    }
-    setThinkingLevel(l) {
-        this._state.thinkingLevel = l;
-    }
-    setSteeringMode(mode) {
-        this.steeringMode = mode;
+    /** Controls how queued steering messages are drained. */
+    set steeringMode(mode) {
+        this.steeringQueue.mode = mode;
     }
-    getSteeringMode() {
-        return this.steeringMode;
+    get steeringMode() {
+        return this.steeringQueue.mode;
     }
-    setFollowUpMode(mode) {
-        this.followUpMode = mode;
+    /** Controls how queued follow-up messages are drained. */
+    set followUpMode(mode) {
+        this.followUpQueue.mode = mode;
     }
-    getFollowUpMode() {
-        return this.followUpMode;
+    get followUpMode() {
+        return this.followUpQueue.mode;
     }
-    setTools(t) {
-        this._state.tools = t;
+    /** Queue a message to be injected after the current assistant turn finishes. */
+    steer(message) {
+        this.steeringQueue.enqueue(message);
     }
-    replaceMessages(ms) {
-        this._state.messages = ms.slice();
-    }
-    appendMessage(m) {
-        this._state.messages = [...this._state.messages, m];
-    }
-    /**
-     * Queue a steering message while the agent is running.
-     * Delivered after the current assistant turn finishes executing its tool calls,
-     * before the next LLM call.
-     */
-    steer(m) {
-        this.steeringQueue.push(m);
-    }
-    /**
-     * Queue a follow-up message to be processed after the agent finishes.
-     * Delivered only when agent has no more tool calls or steering messages.
-     */
-    followUp(m) {
-        this.followUpQueue.push(m);
+    /** Queue a message to run only after the agent would otherwise stop. */
+    followUp(message) {
+        this.followUpQueue.enqueue(message);
     }
+    /** Remove all queued steering messages. */
     clearSteeringQueue() {
-        this.steeringQueue = [];
+        this.steeringQueue.clear();
     }
+    /** Remove all queued follow-up messages. */
     clearFollowUpQueue() {
-        this.followUpQueue = [];
+        this.followUpQueue.clear();
     }
+    /** Remove all queued steering and follow-up messages. */
     clearAllQueues() {
-        this.steeringQueue = [];
-        this.followUpQueue = [];
+        this.clearSteeringQueue();
+        this.clearFollowUpQueue();
     }
+    /** Returns true when either queue still contains pending messages. */
     hasQueuedMessages() {
-        return this.steeringQueue.length > 0 || this.followUpQueue.length > 0;
-    }
-    dequeueSteeringMessages() {
-        if (this.steeringMode === "one-at-a-time") {
-            if (this.steeringQueue.length > 0) {
-                const first = this.steeringQueue[0];
-                this.steeringQueue = this.steeringQueue.slice(1);
-                return [first];
-            }
-            return [];
-        }
-        const steering = this.steeringQueue.slice();
-        this.steeringQueue = [];
-        return steering;
-    }
-    dequeueFollowUpMessages() {
-        if (this.followUpMode === "one-at-a-time") {
-            if (this.followUpQueue.length > 0) {
-                const first = this.followUpQueue[0];
-                this.followUpQueue = this.followUpQueue.slice(1);
-                return [first];
-            }
-            return [];
-        }
-        const followUp = this.followUpQueue.slice();
-        this.followUpQueue = [];
-        return followUp;
-    }
-    clearMessages() {
-        this._state.messages = [];
+        return this.steeringQueue.hasItems() || this.followUpQueue.hasItems();
     }
-    /** The current abort signal, or undefined when the agent is not streaming. */
+    /** Active abort signal for the current run, if any. */
     get signal() {
-        return this.abortController?.signal;
+        return this.activeRun?.abortController.signal;
     }
+    /** Abort the current run, if one is active. */
     abort() {
-        this.abortController?.abort();
+        this.activeRun?.abortController.abort();
     }
+    /**
+     * Resolve when the current run and all awaited event listeners have finished.
+     *
+     * This resolves after `agent_end` listeners settle.
+     */
     waitForIdle() {
-        return this.runningPrompt ?? Promise.resolve();
+        return this.activeRun?.promise ?? Promise.resolve();
     }
+    /** Clear transcript state, runtime state, and queued messages. */
     reset() {
         this._state.messages = [];
         this._state.isStreaming = false;
-        this._state.streamMessage = null;
+        this._state.streamingMessage = undefined;
         this._state.pendingToolCalls = new Set();
-        this._state.error = undefined;
-        this.steeringQueue = [];
-        this.followUpQueue = [];
+        this._state.errorMessage = undefined;
+        this.clearFollowUpQueue();
+        this.clearSteeringQueue();
     }
     async prompt(input, images) {
-        if (this._state.isStreaming) {
+        if (this.activeRun) {
             throw new Error("Agent is already processing a prompt. Use steer() or followUp() to queue messages, or wait for completion.");
         }
-        const model = this._state.model;
-        if (!model)
-            throw new Error("No model configured");
-        let msgs;
-        if (Array.isArray(input)) {
-            msgs = input;
-        }
-        else if (typeof input === "string") {
-            const content = [{ type: "text", text: input }];
-            if (images && images.length > 0) {
-                content.push(...images);
-            }
-            msgs = [
-                {
-                    role: "user",
-                    content,
-                    timestamp: Date.now(),
-                },
-            ];
-        }
-        else {
-            msgs = [input];
-        }
-        await this._runLoop(msgs);
+        const messages = this.normalizePromptInput(input, images);
+        await this.runPromptMessages(messages);
     }
-    /**
-     * Continue from current context (used for retries and resuming queued messages).
-     */
+    /** Continue from the current transcript. The last message must be a user or tool-result message. */
     async continue() {
-        if (this._state.isStreaming) {
+        if (this.activeRun) {
             throw new Error("Agent is already processing. Wait for completion before continuing.");
         }
-        const messages = this._state.messages;
-        if (messages.length === 0) {
+        const lastMessage = this._state.messages[this._state.messages.length - 1];
+        if (!lastMessage) {
             throw new Error("No messages to continue from");
         }
-        if (messages[messages.length - 1].role === "assistant") {
-            const queuedSteering = this.dequeueSteeringMessages();
+        if (lastMessage.role === "assistant") {
+            const queuedSteering = this.steeringQueue.drain();
             if (queuedSteering.length > 0) {
-                await this._runLoop(queuedSteering, { skipInitialSteeringPoll: true });
+                await this.runPromptMessages(queuedSteering, { skipInitialSteeringPoll: true });
                 return;
             }
-            const queuedFollowUp = this.dequeueFollowUpMessages();
-            if (queuedFollowUp.length > 0) {
-                await this._runLoop(queuedFollowUp);
+            const queuedFollowUps = this.followUpQueue.drain();
+            if (queuedFollowUps.length > 0) {
+                await this.runPromptMessages(queuedFollowUps);
                 return;
             }
             throw new Error("Cannot continue from message role: assistant");
         }
-        await this._runLoop(undefined);
+        await this.runContinuation();
     }
-    _processLoopEvent(event) {
+    normalizePromptInput(input, images) {
+        if (Array.isArray(input)) {
+            return input;
+        }
+        if (typeof input !== "string") {
+            return [input];
+        }
+        const content = [{ type: "text", text: input }];
+        if (images && images.length > 0) {
+            content.push(...images);
+        }
+        return [{ role: "user", content, timestamp: Date.now() }];
+    }
+    async runPromptMessages(messages, options = {}) {
+        await this.runWithLifecycle(async (signal) => {
+            await runAgentLoop(messages, this.createContextSnapshot(), this.createLoopConfig(options), (event) => this.processEvents(event), signal, this.streamFn);
+        });
+    }
+    async runContinuation() {
+        await this.runWithLifecycle(async (signal) => {
+            await runAgentLoopContinue(this.createContextSnapshot(), this.createLoopConfig(), (event) => this.processEvents(event), signal, this.streamFn);
+        });
+    }
+    createContextSnapshot() {
+        return {
+            systemPrompt: this._state.systemPrompt,
+            messages: this._state.messages.slice(),
+            tools: this._state.tools.slice(),
+        };
+    }
+    createLoopConfig(options = {}) {
+        let skipInitialSteeringPoll = options.skipInitialSteeringPoll === true;
+        return {
+            model: this._state.model,
+            reasoning: this._state.thinkingLevel === "off" ? undefined : this._state.thinkingLevel,
+            sessionId: this.sessionId,
+            onPayload: this.onPayload,
+            transport: this.transport,
+            thinkingBudgets: this.thinkingBudgets,
+            maxRetryDelayMs: this.maxRetryDelayMs,
+            toolExecution: this.toolExecution,
+            beforeToolCall: this.beforeToolCall,
+            afterToolCall: this.afterToolCall,
+            convertToLlm: this.convertToLlm,
+            transformContext: this.transformContext,
+            getApiKey: this.getApiKey,
+            getSteeringMessages: async () => {
+                if (skipInitialSteeringPoll) {
+                    skipInitialSteeringPoll = false;
+                    return [];
+                }
+                return this.steeringQueue.drain();
+            },
+            getFollowUpMessages: async () => this.followUpQueue.drain(),
+        };
+    }
+    async runWithLifecycle(executor) {
+        if (this.activeRun) {
+            throw new Error("Agent is already processing.");
+        }
+        const abortController = new AbortController();
+        let resolvePromise = () => { };
+        const promise = new Promise((resolve) => {
+            resolvePromise = resolve;
+        });
+        this.activeRun = { promise, resolve: resolvePromise, abortController };
+        this._state.isStreaming = true;
+        this._state.streamingMessage = undefined;
+        this._state.errorMessage = undefined;
+        try {
+            await executor(abortController.signal);
+        }
+        catch (error) {
+            await this.handleRunFailure(error, abortController.signal.aborted);
+        }
+        finally {
+            this.finishRun();
+        }
+    }
+    async handleRunFailure(error, aborted) {
+        const failureMessage = {
+            role: "assistant",
+            content: [{ type: "text", text: "" }],
+            api: this._state.model.api,
+            provider: this._state.model.provider,
+            model: this._state.model.id,
+            usage: EMPTY_USAGE,
+            stopReason: aborted ? "aborted" : "error",
+            errorMessage: error instanceof Error ? error.message : String(error),
+            timestamp: Date.now(),
+        };
+        this._state.messages.push(failureMessage);
+        this._state.errorMessage = failureMessage.errorMessage;
+        await this.processEvents({ type: "agent_end", messages: [failureMessage] });
+    }
+    finishRun() {
+        this._state.isStreaming = false;
+        this._state.streamingMessage = undefined;
+        this._state.pendingToolCalls = new Set();
+        this.activeRun?.resolve();
+        this.activeRun = undefined;
+    }
+    /**
+     * Reduce internal state for a loop event, then await listeners.
+     *
+     * `agent_end` only means no further loop events will be emitted. The run is
+     * considered idle later, after all awaited listeners for `agent_end` finish
+     * and `finishRun()` clears runtime-owned state.
+     */
+    async processEvents(event) {
         switch (event.type) {
             case "message_start":
-                this._state.streamMessage = event.message;
+                this._state.streamingMessage = event.message;
                 break;
             case "message_update":
-                this._state.streamMessage = event.message;
+                this._state.streamingMessage = event.message;
                 break;
             case "message_end":
-                this._state.streamMessage = null;
-                this.appendMessage(event.message);
+                this._state.streamingMessage = undefined;
+                this._state.messages.push(event.message);
                 break;
             case "tool_execution_start": {
                 const pendingToolCalls = new Set(this._state.pendingToolCalls);
@@ -316,106 +376,19 @@ export class Agent {
             }
             case "turn_end":
                 if (event.message.role === "assistant" && event.message.errorMessage) {
-                    this._state.error = event.message.errorMessage;
+                    this._state.errorMessage = event.message.errorMessage;
                 }
                 break;
             case "agent_end":
-                this._state.isStreaming = false;
-                this._state.streamMessage = null;
+                this._state.streamingMessage = undefined;
                 break;
         }
-        this.emit(event);
-    }
-    /**
-     * Run the agent loop.
-     * If messages are provided, starts a new conversation turn with those messages.
-     * Otherwise, continues from existing context.
-     */
-    async _runLoop(messages, options) {
-        const model = this._state.model;
-        if (!model)
-            throw new Error("No model configured");
-        this.runningPrompt = new Promise((resolve) => {
-            this.resolveRunningPrompt = resolve;
-        });
-        this.abortController = new AbortController();
-        this._state.isStreaming = true;
-        this._state.streamMessage = null;
-        this._state.error = undefined;
-        const reasoning = this._state.thinkingLevel === "off" ? undefined : this._state.thinkingLevel;
-        const context = {
-            systemPrompt: this._state.systemPrompt,
-            messages: this._state.messages.slice(),
-            tools: this._state.tools,
-        };
-        let skipInitialSteeringPoll = options?.skipInitialSteeringPoll === true;
-        const config = {
-            model,
-            reasoning,
-            sessionId: this._sessionId,
-            onPayload: this._onPayload,
-            transport: this._transport,
-            thinkingBudgets: this._thinkingBudgets,
-            maxRetryDelayMs: this._maxRetryDelayMs,
-            toolExecution: this._toolExecution,
-            beforeToolCall: this._beforeToolCall,
-            afterToolCall: this._afterToolCall,
-            convertToLlm: this.convertToLlm,
-            transformContext: this.transformContext,
-            getApiKey: this.getApiKey,
-            getSteeringMessages: async () => {
-                if (skipInitialSteeringPoll) {
-                    skipInitialSteeringPoll = false;
-                    return [];
-                }
-                return this.dequeueSteeringMessages();
-            },
-            getFollowUpMessages: async () => this.dequeueFollowUpMessages(),
-        };
-        try {
-            if (messages) {
-                await runAgentLoop(messages, context, config, async (event) => this._processLoopEvent(event), this.abortController.signal, this.streamFn);
-            }
-            else {
-                await runAgentLoopContinue(context, config, async (event) => this._processLoopEvent(event), this.abortController.signal, this.streamFn);
-            }
-        }
-        catch (err) {
-            const errorMsg = {
-                role: "assistant",
-                content: [{ type: "text", text: "" }],
-                api: model.api,
-                provider: model.provider,
-                model: model.id,
-                usage: {
-                    input: 0,
-                    output: 0,
-                    cacheRead: 0,
-                    cacheWrite: 0,
-                    totalTokens: 0,
-                    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
-                },
-                stopReason: this.abortController?.signal.aborted ? "aborted" : "error",
-                errorMessage: err?.message || String(err),
-                timestamp: Date.now(),
-            };
-            this.appendMessage(errorMsg);
-            this._state.error = err?.message || String(err);
-            this.emit({ type: "agent_end", messages: [errorMsg] });
-        }
-        finally {
-            this._state.isStreaming = false;
-            this._state.streamMessage = null;
-            this._state.pendingToolCalls = new Set();
-            this.abortController = undefined;
-            this.resolveRunningPrompt?.();
-            this.runningPrompt = undefined;
-            this.resolveRunningPrompt = undefined;
+        const signal = this.activeRun?.abortController.signal;
+        if (!signal) {
+            throw new Error("Agent listener invoked outside active run");
         }
-    }
-    emit(e) {
         for (const listener of this.listeners) {
-            listener(e);
+            await listener(event, signal);
         }
     }
 }