@armadra/agent 0.0.0-stage → 0.2.1

package/dist/agent/agent.js

@@ -0,0 +1,129 @@
+/**
+ * 有状态 Agent（设计 §4.1–§4.3）：持有上下文消息、两条队列、当前 run，发 agent_start / agent_end。[B2]
+ *
+ * - `run(prompts)`：运行中再调用 → `AmaError{code:"busy"}`；空 prompts = continue（末条须能转成
+ *   user / toolResult）。返回 RunOutcome；`agent_end.willRetry` 由 `onRunEnd` 决定（会话层重试 /
+ *   溢出恢复在 agent_end 之前就要知道是否会重试）。
+ * - 监听器按订阅顺序被 await，计入本 run 的收尾；监听器抛错只记录不中断。
+ * - `abort()` 只中断当前 run（不清队列）；`waitForIdle()` 在 run 与 agent_end 监听器都结束后 resolve。
+ * - 消息在 `message_end` 时进入 `messages`；会话层可在 run 之间（或 run 中、请求之前）整体替换。
+ */
+import { AmaError } from "../errors.js";
+import { failureMessage, runLoop, } from "./loop.js";
+import { PendingMessageQueue } from "./queue.js";
+export class Agent {
+    messages;
+    steeringQueue;
+    followUpQueue;
+    listeners = new Set();
+    options;
+    active;
+    constructor(options) {
+        this.options = options;
+        this.messages = options.messages?.slice() ?? [];
+        this.steeringQueue = new PendingMessageQueue(options.steeringMode ?? "one-at-a-time");
+        this.followUpQueue = new PendingMessageQueue(options.followUpMode ?? "one-at-a-time");
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    get isRunning() {
+        return this.active !== undefined;
+    }
+    get signal() {
+        return this.active?.controller.signal;
+    }
+    steer(message) {
+        this.steeringQueue.enqueue(message);
+    }
+    followUp(message) {
+        this.followUpQueue.enqueue(message);
+    }
+    abort() {
+        this.active?.controller.abort();
+    }
+    waitForIdle() {
+        return this.active?.promise ?? Promise.resolve();
+    }
+    async emit(event) {
+        if (event.type === "message_end")
+            this.messages.push(event.message);
+        for (const listener of this.listeners) {
+            try {
+                await listener(event);
+            }
+            catch (error) {
+                this.options.onListenerError?.(error, event);
+            }
+        }
+    }
+    async run(prompts, runOptions = {}) {
+        if (this.active !== undefined) {
+            throw new AmaError("busy", "agent is already running; use steer() or followUp()");
+        }
+        const controller = new AbortController();
+        const parent = runOptions.signal;
+        const onParentAbort = () => controller.abort();
+        if (parent !== undefined) {
+            if (parent.aborted)
+                controller.abort();
+            else
+                parent.addEventListener("abort", onParentAbort, { once: true });
+        }
+        let resolveIdle = () => { };
+        const promise = new Promise((resolve) => {
+            resolveIdle = resolve;
+        });
+        this.active = { controller, promise };
+        const options = this.options;
+        const emit = (event) => this.emit(event);
+        let outcome;
+        try {
+            await emit({ type: "agent_start" });
+            try {
+                const loopOptions = runOptions.skipInitialSteering === true ? { skipInitialSteering: true } : {};
+                const config = {
+                    hooks: options.hooks,
+                    getSteeringMessages: () => this.steeringQueue.drain(),
+                    getFollowUpMessages: () => this.followUpQueue.drain(),
+                    getMessages: () => this.messages,
+                    getModel: options.getModel,
+                    getThinkingLevel: options.getThinkingLevel,
+                    stream: options.stream,
+                    tools: options.tools,
+                    emit,
+                    ...(options.streamOptions === undefined ? {} : { streamOptions: options.streamOptions }),
+                    ...(options.beforeRequest === undefined ? {} : { beforeRequest: options.beforeRequest }),
+                };
+                outcome = await runLoop(prompts, config, controller.signal, loopOptions);
+            }
+            catch (error) {
+                const aborted = controller.signal.aborted;
+                const message = failureMessage(options.getModel(), aborted ? "aborted" : "error", error instanceof Error ? error.message : String(error));
+                await emit({ type: "message_start", message });
+                await emit({ type: "message_end", message });
+                await emit({ type: "turn_end", message, toolResults: [] });
+                outcome = {
+                    lastAssistant: message,
+                    stopReason: message.stopReason,
+                    newMessages: [message],
+                };
+            }
+            let willRetry = false;
+            try {
+                willRetry = (await runOptions.onRunEnd?.(outcome)) ?? false;
+            }
+            catch {
+                willRetry = false;
+            }
+            await emit({ type: "agent_end", stopReason: outcome.stopReason, willRetry });
+            return outcome;
+        }
+        finally {
+            parent?.removeEventListener("abort", onParentAbort);
+            this.active = undefined;
+            resolveIdle();
+        }
+    }
+}

package/dist/agent/loop.d.ts

@@ -0,0 +1,51 @@
+/**
+ * runLoop 状态机（设计 §4.1）。[B2]
+ *
+ * ```text
+ * turn_start → 投递 prompts / steer → beforeRequest（system 补丁、首次落盘）→ 流式请求
+ *   ├─ error / aborted：补齐悬空 tool_call 的结果 → finishTurn → turn_end → 返回
+ *   ├─ length 且有 tool_call：整批判失败
+ *   └─ 有 tool_call：tool-runner 执行，结果按原序入转录
+ * finishTurn → turn_end → abort? → 收 steer（投递点 = 本轮工具全部结束、下一次模型调用前）
+ * 内层结束（无 tool_call 且 steer 空）→ 收 followUp（有则继续外层）→ 返回
+ * ```
+ *
+ * 循环不发 agent_start / agent_end（由 Agent 发，以便带上 willRetry）；上下文每次请求前从
+ * `getMessages()` 现取（压缩 / context_edit 会替换 Agent 的消息数组）。
+ */
+import type { AssistantMessage, Model, ModelThinkingLevel, StreamOptions, Usage } from "../ai/types.js";
+import type { StreamFn } from "../compaction/summarize-tier.js";
+import type { AgentMessage } from "../session/types.js";
+import { type LoopEmit, type ToolRunnerOptions } from "./tool-runner.js";
+import type { LoopHooks } from "./types.js";
+export type { StreamFn } from "../compaction/summarize-tier.js";
+export type LoopCallbacks = Omit<LoopHooks, "getSteeringMessages" | "getFollowUpMessages">;
+export interface LoopConfig {
+    hooks: LoopCallbacks;
+    getSteeringMessages(): AgentMessage[];
+    getFollowUpMessages(): AgentMessage[];
+    getMessages(): readonly AgentMessage[];
+    getModel(): Model;
+    getThinkingLevel(): ModelThinkingLevel;
+    stream: StreamFn;
+    /** 每次请求的额外选项（apiKey、sessionId 等）；signal / thinkingLevel 由循环填。 */
+    streamOptions?(model: Model): Promise<Partial<StreamOptions>> | Partial<StreamOptions>;
+    /** 每次模型请求前：system 补丁、首次落盘、阈值检查等。 */
+    beforeRequest?(signal: AbortSignal): Promise<void>;
+    tools: ToolRunnerOptions;
+    emit: LoopEmit;
+}
+export interface RunOutcome {
+    /** 最后一条助手消息（本 run 未产生则 undefined）。 */
+    lastAssistant: AssistantMessage | undefined;
+    /** 最后一条助手消息的 stopReason；工具执行中被中断为 "aborted"。 */
+    stopReason: string;
+    newMessages: AgentMessage[];
+}
+export declare const ZERO_USAGE: Usage;
+export declare function failureMessage(model: Model, stopReason: "error" | "aborted", errorMessage: string): AssistantMessage;
+export interface RunLoopOptions {
+    /** continue 场景：开头不收 steer（调用方已把 steer 作为 prompts 传入）。 */
+    skipInitialSteering?: boolean;
+}
+export declare function runLoop(prompts: readonly AgentMessage[], config: LoopConfig, signal: AbortSignal, options?: RunLoopOptions): Promise<RunOutcome>;

package/dist/agent/loop.js

@@ -0,0 +1,158 @@
+/**
+ * runLoop 状态机（设计 §4.1）。[B2]
+ *
+ * ```text
+ * turn_start → 投递 prompts / steer → beforeRequest（system 补丁、首次落盘）→ 流式请求
+ *   ├─ error / aborted：补齐悬空 tool_call 的结果 → finishTurn → turn_end → 返回
+ *   ├─ length 且有 tool_call：整批判失败
+ *   └─ 有 tool_call：tool-runner 执行，结果按原序入转录
+ * finishTurn → turn_end → abort? → 收 steer（投递点 = 本轮工具全部结束、下一次模型调用前）
+ * 内层结束（无 tool_call 且 steer 空）→ 收 followUp（有则继续外层）→ 返回
+ * ```
+ *
+ * 循环不发 agent_start / agent_end（由 Agent 发，以便带上 willRetry）；上下文每次请求前从
+ * `getMessages()` 现取（压缩 / context_edit 会替换 Agent 的消息数组）。
+ */
+import { closeDanglingCalls, failTruncatedBatch, runToolBatch, toolCallsOf, } from "./tool-runner.js";
+export const ZERO_USAGE = {
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    totalTokens: 0,
+};
+export function failureMessage(model, stopReason, errorMessage) {
+    return {
+        role: "assistant",
+        content: [],
+        api: model.api,
+        provider: model.provider,
+        model: model.id,
+        usage: { ...ZERO_USAGE },
+        stopReason,
+        errorMessage,
+        timestamp: Date.now(),
+    };
+}
+async function streamAssistant(request, config, signal) {
+    const { model, thinkingLevel } = request;
+    const emit = config.emit;
+    let started = false;
+    const finish = async (message) => {
+        const final = message.thinkingLevel === undefined ? { ...message, thinkingLevel } : message;
+        if (!started)
+            await emit({ type: "message_start", message: final });
+        await emit({ type: "message_end", message: final });
+        return final;
+    };
+    try {
+        const extra = (await config.streamOptions?.(model)) ?? {};
+        const options = { ...extra, signal, thinkingLevel };
+        const stream = config.stream(model, request.context, options);
+        for await (const event of stream) {
+            switch (event.type) {
+                case "start":
+                    started = true;
+                    await emit({ type: "message_start", message: { ...event.partial } });
+                    break;
+                case "done":
+                case "error":
+                    return finish(await stream.result());
+                default:
+                    if (started) {
+                        await emit({
+                            type: "message_update",
+                            message: { ...event.partial },
+                            assistantMessageEvent: event,
+                        });
+                    }
+            }
+        }
+        return finish(await stream.result());
+    }
+    catch (error) {
+        const text = error instanceof Error ? error.message : String(error);
+        return finish(failureMessage(model, signal.aborted ? "aborted" : "error", text));
+    }
+}
+async function deliver(messages, emit, out) {
+    for (const message of messages) {
+        await emit({ type: "message_start", message });
+        await emit({ type: "message_end", message });
+        out.push(message);
+    }
+}
+export async function runLoop(prompts, config, signal, options = {}) {
+    const { hooks, emit } = config;
+    const newMessages = [];
+    let lastAssistant;
+    let lastTurn;
+    const outcome = (stopReason) => ({ lastAssistant, stopReason, newMessages });
+    await emit({ type: "turn_start" });
+    await deliver(prompts, emit, newMessages);
+    let pending = options.skipInitialSteering === true ? [] : config.getSteeringMessages();
+    for (;;) {
+        let hasMoreToolCalls = true;
+        while (hasMoreToolCalls || pending.length > 0) {
+            if (lastTurn !== undefined) {
+                await hooks.prepareNextTurn?.(lastTurn);
+                if (pending.length === 0)
+                    pending = config.getSteeringMessages();
+                await emit({ type: "turn_start" });
+            }
+            await deliver(pending, emit, newMessages);
+            pending = [];
+            await config.beforeRequest?.(signal);
+            if (signal.aborted)
+                return outcome("aborted");
+            let messages = [...config.getMessages()];
+            if (hooks.transformContext !== undefined)
+                messages = await hooks.transformContext(messages, signal);
+            let request = {
+                context: { messages: hooks.convertToLlm(messages) },
+                model: config.getModel(),
+                thinkingLevel: config.getThinkingLevel(),
+            };
+            if (hooks.prepareRequest !== undefined)
+                request = await hooks.prepareRequest(request);
+            const assistant = await streamAssistant(request, config, signal);
+            lastAssistant = assistant;
+            newMessages.push(assistant);
+            if (assistant.stopReason === "error" || assistant.stopReason === "aborted") {
+                const closed = await closeDanglingCalls(assistant, emit);
+                newMessages.push(...closed);
+                lastTurn = { assistant, toolResults: closed };
+                await hooks.finishTurn?.(lastTurn);
+                await emit({ type: "turn_end", message: assistant, toolResults: closed });
+                return outcome(assistant.stopReason);
+            }
+            const calls = toolCallsOf(assistant);
+            hasMoreToolCalls = false;
+            let toolResults = [];
+            if (calls.length > 0) {
+                const batch = assistant.stopReason === "length"
+                    ? await failTruncatedBatch(assistant, emit)
+                    : await runToolBatch(assistant, config.tools, signal, emit);
+                toolResults = batch.messages;
+                newMessages.push(...toolResults);
+                hasMoreToolCalls = !batch.terminate;
+            }
+            lastTurn = { assistant, toolResults };
+            const decision = await hooks.finishTurn?.(lastTurn);
+            await emit({ type: "turn_end", message: assistant, toolResults });
+            if (signal.aborted)
+                return outcome("aborted");
+            // length 且无工具调用：输出被截断，交给会话层的溢出恢复，不投递 steer / followUp。
+            if (assistant.stopReason === "length" && calls.length === 0)
+                return outcome("length");
+            if (decision === "end")
+                return outcome(assistant.stopReason);
+            pending = config.getSteeringMessages();
+        }
+        const followUps = config.getFollowUpMessages();
+        if (followUps.length === 0)
+            break;
+        pending = followUps;
+    }
+    return outcome(lastAssistant?.stopReason ?? "stop");
+}

package/dist/agent/queue.d.ts

@@ -0,0 +1,25 @@
+/**
+ * PendingMessageQueue（设计 §4.3）：steer / followUp 两条队列共用。[B2]
+ *
+ * `one-at-a-time`：每个投递点只取一条；`all`：一次取空。abort 不清队列。
+ */
+import type { QueueMode } from "./types.js";
+import type { AgentMessage } from "../session/types.js";
+export declare class PendingMessageQueue {
+    private items;
+    mode: QueueMode;
+    constructor(mode?: QueueMode);
+    get size(): number;
+    enqueue(message: AgentMessage): void;
+    hasItems(): boolean;
+    /** 下一个投递点会取走的消息（不消费）。 */
+    peek(): AgentMessage[];
+    drain(): AgentMessage[];
+    /** 取走全部（clearQueue）。 */
+    clear(): AgentMessage[];
+    /** 取走最后一条（Alt+Up 取回）。 */
+    popLast(): AgentMessage | undefined;
+    snapshot(): readonly AgentMessage[];
+}
+/** 队列消息的显示文本（queue_update 事件用）。 */
+export declare function queuedText(message: AgentMessage): string;

package/dist/agent/queue.js

@@ -0,0 +1,55 @@
+/**
+ * PendingMessageQueue（设计 §4.3）：steer / followUp 两条队列共用。[B2]
+ *
+ * `one-at-a-time`：每个投递点只取一条；`all`：一次取空。abort 不清队列。
+ */
+export class PendingMessageQueue {
+    items = [];
+    mode;
+    constructor(mode = "one-at-a-time") {
+        this.mode = mode;
+    }
+    get size() {
+        return this.items.length;
+    }
+    enqueue(message) {
+        this.items.push(message);
+    }
+    hasItems() {
+        return this.items.length > 0;
+    }
+    /** 下一个投递点会取走的消息（不消费）。 */
+    peek() {
+        if (this.mode === "all")
+            return this.items.slice();
+        const first = this.items[0];
+        return first === undefined ? [] : [first];
+    }
+    drain() {
+        const drained = this.peek();
+        this.items = this.items.slice(drained.length);
+        return drained;
+    }
+    /** 取走全部（clearQueue）。 */
+    clear() {
+        const all = this.items;
+        this.items = [];
+        return all;
+    }
+    /** 取走最后一条（Alt+Up 取回）。 */
+    popLast() {
+        return this.items.pop();
+    }
+    snapshot() {
+        return this.items.slice();
+    }
+}
+/** 队列消息的显示文本（queue_update 事件用）。 */
+export function queuedText(message) {
+    if (message.role !== "user" && message.role !== "custom")
+        return "";
+    const { content } = message;
+    if (typeof content === "string")
+        return content;
+    return content.map((block) => (block.type === "text" ? block.text : "[image]")).join("");
+}

package/dist/agent/retry.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 会话层重试（设计 §3.6「重试」「溢出」）。[B2]
+ *
+ * 判定顺序：上下文溢出（不重试，走压缩）→ 不可重试（配额 / 计费 / key / 401 / 403，快速失败）→
+ * 可重试（429、5xx、overloaded、网络错误、断流）→ 其它（不重试）。
+ * 延迟 `baseDelayMs × 2^(attempt−1)`，上限 `maxDelayMs`；`sleep` 可被 abort 打断。
+ * 协议层自身不重试。溢出文案识别只有一份：ai/overflow.ts 的 `isOverflowErrorText`（缺省），可注入替换。
+ */
+import type { AssistantMessage } from "../ai/types.js";
+import type { RetrySettings } from "./types.js";
+export declare const DEFAULT_RETRY_SETTINGS: RetrySettings;
+export type FailureKind = "overflow" | "fatal" | "retryable" | "other";
+export interface ClassifyOptions {
+    isContextOverflow?: (errorMessage: string) => boolean;
+}
+/** 对 `stopReason: "error"` 的助手消息分类；`length` 且无工具调用也算 overflow。 */
+export declare function classifyFailure(message: AssistantMessage, options?: ClassifyOptions): FailureKind;
+export declare function resolveRetrySettings(partial?: Partial<RetrySettings>): RetrySettings;
+/** 第 attempt 次重试（1 起）前的等待。 */
+export declare function retryDelayMs(attempt: number, settings: RetrySettings): number;
+/** 可被 abort 打断的等待；被打断时抛 AmaError{code:"aborted"}。 */
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;

package/dist/agent/retry.js

@@ -0,0 +1,92 @@
+/**
+ * 会话层重试（设计 §3.6「重试」「溢出」）。[B2]
+ *
+ * 判定顺序：上下文溢出（不重试，走压缩）→ 不可重试（配额 / 计费 / key / 401 / 403，快速失败）→
+ * 可重试（429、5xx、overloaded、网络错误、断流）→ 其它（不重试）。
+ * 延迟 `baseDelayMs × 2^(attempt−1)`，上限 `maxDelayMs`；`sleep` 可被 abort 打断。
+ * 协议层自身不重试。溢出文案识别只有一份：ai/overflow.ts 的 `isOverflowErrorText`（缺省），可注入替换。
+ */
+import { isOverflowErrorText } from "../ai/overflow.js";
+import { AmaError } from "../errors.js";
+export const DEFAULT_RETRY_SETTINGS = {
+    enabled: true,
+    maxRetries: 3,
+    baseDelayMs: 2000,
+    maxDelayMs: 60_000,
+};
+const FATAL_PATTERNS = [
+    /insufficient[_ ]quota/i,
+    /quota exceeded/i,
+    /billing/i,
+    /monthly usage limit/i,
+    /invalid[_ ]api[_ ]key/i,
+    /incorrect api key/i,
+    /no[_ ]api[_ ]key/i,
+    /\b(?:401|403)\b/,
+    /unauthori[sz]ed/i,
+    /permission denied/i,
+    /authentication/i,
+];
+const RETRYABLE_PATTERNS = [
+    /\b429\b/,
+    /rate[_ ]?limit/i,
+    /too many requests/i,
+    /\b5\d\d\b/,
+    /overloaded/i,
+    /server error/i,
+    /service unavailable/i,
+    /bad gateway/i,
+    /gateway timeout/i,
+    /timed? ?out/i,
+    /network/i,
+    /fetch failed/i,
+    /ECONNRESET|ECONNREFUSED|ENOTFOUND|EAI_AGAIN|ETIMEDOUT|EPIPE/,
+    /socket hang up/i,
+    /stream (?:ended|closed|terminated)/i,
+    /premature (?:close|end)/i,
+    /terminated/i,
+    /connection (?:reset|closed|error)/i,
+];
+/** 对 `stopReason: "error"` 的助手消息分类；`length` 且无工具调用也算 overflow。 */
+export function classifyFailure(message, options = {}) {
+    if (message.stopReason === "length") {
+        return message.content.some((block) => block.type === "toolCall") ? "other" : "overflow";
+    }
+    if (message.stopReason !== "error")
+        return "other";
+    const text = message.errorMessage ?? "";
+    const isOverflow = options.isContextOverflow ?? isOverflowErrorText;
+    if (isOverflow(text))
+        return "overflow";
+    if (FATAL_PATTERNS.some((pattern) => pattern.test(text)))
+        return "fatal";
+    if (RETRYABLE_PATTERNS.some((pattern) => pattern.test(text)))
+        return "retryable";
+    return "other";
+}
+export function resolveRetrySettings(partial = {}) {
+    return { ...DEFAULT_RETRY_SETTINGS, ...partial };
+}
+/** 第 attempt 次重试（1 起）前的等待。 */
+export function retryDelayMs(attempt, settings) {
+    const raw = settings.baseDelayMs * 2 ** Math.max(0, attempt - 1);
+    return Math.min(raw, settings.maxDelayMs);
+}
+/** 可被 abort 打断的等待；被打断时抛 AmaError{code:"aborted"}。 */
+export function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted === true) {
+            reject(new AmaError("aborted", "aborted"));
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, Math.max(0, ms));
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(new AmaError("aborted", "aborted"));
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}

package/dist/agent/schema.d.ts

@@ -0,0 +1,27 @@
+/**
+ * JSON Schema 子集校验（设计 §2、§5.1）。[B0] 所有。
+ *
+ * 子集：type（object / string / number / integer / boolean / array）、properties、required、
+ * additionalProperties（布尔）、items、enum（原始值）、description / title / default（只做注释）。
+ *
+ * - `validateSchema(schema, value)` 返回错误列表；空数组 = 通过。路径形如 `$.edits[0].oldText`，
+ *   非标识符键用 `$["a b"]`。
+ * - `checkSchemaSubset(schema)` 检查 schema 本身只用了子集关键字（工具注册时调用）。
+ * - 不做类型强转（"1" 不会当作 1），不填 default。
+ */
+import type { JsonSchema } from "../ai/types.js";
+export type { JsonSchema, JsonSchemaType } from "../ai/types.js";
+export type SchemaErrorKeyword = "type" | "required" | "additionalProperties" | "enum";
+export interface SchemaError {
+    /** `$` 为根。 */
+    path: string;
+    keyword: SchemaErrorKeyword;
+    message: string;
+}
+export declare function joinPath(base: string, key: string | number): string;
+/** 校验 value；返回全部错误（不在第一处停下）。 */
+export declare function validateSchema(schema: JsonSchema, value: unknown): SchemaError[];
+/** 把错误列表格式化成给模型看的多行文本。 */
+export declare function formatSchemaErrors(errors: readonly SchemaError[]): string;
+/** 检查 schema 只用了子集关键字；返回问题列表，空数组 = 合规。 */
+export declare function checkSchemaSubset(schema: unknown): string[];