@armadra/agent 0.0.0-stage → 0.3.0

package/dist/ai/fake/fake-provider.js

@@ -0,0 +1,278 @@
+/**
+ * 脚本化供应商（设计 D16、§15）：供应商 id `fake`、协议 id `fake`，模型 `fake/echo`、
+ * `fake/reasoning`。无脚本时回显最后一条用户消息；有脚本时第 n 次调用（跨模型计数）按
+ * `responses[n]` 产出文本 / 思考 / 工具调用 / 429 / 溢出 / 断流 / 延迟。
+ *
+ * 事件形状与真实协议完全一致（同一个 BlockTracker），契约测试对两条协议与 fake 跑同一套断言。
+ *
+ * 用法：
+ * - 测试：`const fake = new FakeProvider([...])`，把 `fake.api` 注册进 ApiRegistry（或直接
+ *   `fake.api.stream(...)`），`fake.calls` 记录每次调用的上下文与选项；
+ * - CLI：`--provider fake`；`AMA_FAKE_SCRIPT=<path.json>` 指定脚本（首次调用时读取）。
+ * - 录制（第三波 §2.4，bundle 级缓存测试）：`AMA_FAKE_RECORD=<file>` 时每次请求向文件追加一行
+ *   JSON `{ index, purpose, model, system, tools, messagesCount }`——`system` 是折叠后的系统提示
+ *   原文，`tools` 是发给供应商的工具表（按注册顺序），与真实协议请求体的前缀同口径。
+ */
+import { appendFileSync } from "node:fs";
+import { AssistantEventStreamImpl } from "../event-stream.js";
+import { BlockTracker, createOutput, finishDone, finishError } from "../apis/shared.js";
+import { contentText, normalizeContext } from "../context.js";
+import { describeFakeError, loadFakeScript, parseFakeScript, } from "./fake-script.js";
+export const FAKE_PROVIDER_ID = "fake";
+export const FAKE_API_ID = "fake";
+export const FAKE_SCRIPT_ENV = "AMA_FAKE_SCRIPT";
+export const FAKE_RECORD_ENV = "AMA_FAKE_RECORD";
+const FAKE_MODEL_BASE = {
+    provider: FAKE_PROVIDER_ID,
+    api: FAKE_API_ID,
+    baseUrl: "fake://local",
+    input: ["text", "image"],
+    contextWindow: 200_000,
+    maxTokens: 8192,
+    cost: { input: 1, output: 2, cacheRead: 0.1, cacheWrite: 1.25 },
+    requiresApiKey: false,
+};
+export const FAKE_MODELS = [
+    { ...FAKE_MODEL_BASE, id: "echo", name: "Fake Echo", reasoning: false },
+    { ...FAKE_MODEL_BASE, id: "reasoning", name: "Fake Reasoning", reasoning: true },
+];
+export function fakeProviderData() {
+    return {
+        id: FAKE_PROVIDER_ID,
+        name: "Fake (scripted)",
+        api: FAKE_API_ID,
+        baseUrl: "fake://local",
+        envKeys: [],
+        models: FAKE_MODELS.map((model) => ({ ...model })),
+        requiresApiKey: false,
+        builtin: true,
+    };
+}
+function lastUserText(context) {
+    for (let i = context.messages.length - 1; i >= 0; i--) {
+        const message = context.messages[i];
+        if (message?.role === "user")
+            return contentText(message.content);
+    }
+    return "";
+}
+function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+function contextChars(context) {
+    let chars = 0;
+    for (const message of context.messages)
+        chars += JSON.stringify(message).length;
+    return chars;
+}
+function chunks(text, size) {
+    if (!size || size <= 0 || text.length <= size)
+        return text.length > 0 ? [text] : [];
+    const out = [];
+    for (let i = 0; i < text.length; i += size)
+        out.push(text.slice(i, i + size));
+    return out;
+}
+function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal.aborted || ms <= 0) {
+            setTimeout(resolve, 0);
+            return;
+        }
+        const timer = setTimeout(done, ms);
+        function done() {
+            clearTimeout(timer);
+            signal.removeEventListener("abort", done);
+            resolve();
+        }
+        signal.addEventListener("abort", done, { once: true });
+    });
+}
+/** 让出事件循环，abort 能在两个事件之间插入。 */
+function tick() {
+    return new Promise((resolve) => setImmediate(resolve));
+}
+class AbortedError extends Error {
+}
+export class FakeProvider {
+    calls = [];
+    script;
+    scriptLoader;
+    loaded = false;
+    recordFile;
+    constructor(script, options = {}) {
+        if (typeof script === "function")
+            this.scriptLoader = script;
+        else if (script !== undefined)
+            this.setScript(script);
+        const record = options.recordFile;
+        this.recordFile = typeof record === "function" ? record : () => record;
+    }
+    api = {
+        id: FAKE_API_ID,
+        stream: (model, context, options) => this.stream(model, context, options),
+    };
+    get callCount() {
+        return this.calls.length;
+    }
+    setScript(script) {
+        this.script = parseFakeScript(script);
+        this.loaded = true;
+    }
+    append(...responses) {
+        this.ensureLoaded();
+        this.script ??= { version: 1, responses: [] };
+        this.script.responses.push(...responses);
+    }
+    reset() {
+        this.calls.length = 0;
+    }
+    ensureLoaded() {
+        if (this.loaded)
+            return;
+        this.loaded = true;
+        this.script = this.scriptLoader?.();
+    }
+    /** 第 index 次调用的响应；undefined = 回显。 */
+    responseFor(index) {
+        this.ensureLoaded();
+        const script = this.script;
+        if (!script)
+            return undefined;
+        const direct = script.responses[index];
+        if (direct)
+            return direct;
+        const behavior = script.whenExhausted ?? "echo";
+        if (behavior === "repeat-last")
+            return script.responses[script.responses.length - 1];
+        if (behavior === "error") {
+            return { error: { kind: "custom", message: `fake script exhausted at call ${index + 1}` } };
+        }
+        return undefined;
+    }
+    stream(model, context, options) {
+        const index = this.calls.length;
+        const { signal: _s, onPayload: _p, onResponse: _r, ...rest } = options;
+        this.calls.push({ index, model, context, options: rest });
+        this.record(index, model, context, options);
+        const response = this.responseFor(index) ?? {
+            text: lastUserText(context) || "(no input)",
+        };
+        const events = new AssistantEventStreamImpl();
+        void this.run(events, model, context, options, response).finally(() => events.end());
+        return events;
+    }
+    /** 录制一行；写失败不影响请求（测试会因缺行而失败）。 */
+    record(index, model, context, options) {
+        const file = this.recordFile();
+        if (!file)
+            return;
+        const normalized = normalizeContext(context);
+        const line = {
+            index,
+            purpose: options.purpose ?? "turn",
+            model: `${model.provider}/${model.id}`,
+            system: normalized.systemPrompt,
+            tools: normalized.tools,
+            messagesCount: normalized.messages.length,
+        };
+        try {
+            appendFileSync(file, `${JSON.stringify(line)}\n`);
+        }
+        catch {
+            // 录制只服务测试；路径不可写时静默。
+        }
+    }
+    async run(stream, model, context, options, response) {
+        const tracker = new BlockTracker(stream, createOutput(model));
+        const { signal } = options;
+        const checkAbort = () => {
+            if (signal.aborted)
+                throw new AbortedError("aborted");
+        };
+        try {
+            options.onPayload?.({ fake: true, model: model.id, messages: context.messages.length });
+            if (response.delayMs)
+                await sleep(response.delayMs, signal);
+            checkAbort();
+            const error = response.error ? describeFakeError(response.error) : undefined;
+            if (error && response.error?.kind !== "disconnect") {
+                options.onResponse?.(error.status, new Headers());
+                throw new Error(error.message);
+            }
+            options.onResponse?.(200, new Headers({ "content-type": "text/event-stream" }));
+            if (options.thinkingLevel)
+                tracker.output.thinkingLevel = options.thinkingLevel;
+            stream.push({ type: "start", partial: tracker.output });
+            const steps = [...(response.steps ?? [])];
+            if (response.text !== undefined)
+                steps.push({ text: response.text });
+            let produced = "";
+            for (const step of steps) {
+                await tick();
+                checkAbort();
+                produced += await this.emitStep(step, tracker, signal);
+            }
+            await tick();
+            checkAbort();
+            const usage = tracker.output.usage;
+            usage.input = response.usage?.input ?? Math.ceil(contextChars(context) / 4);
+            usage.output = response.usage?.output ?? estimateTokens(produced);
+            usage.cacheRead = response.usage?.cacheRead ?? 0;
+            usage.cacheWrite = response.usage?.cacheWrite ?? 0;
+            if (error)
+                throw new Error(error.message);
+            const reason = response.stopReason ?? (tracker.hasToolCalls ? "toolUse" : "stop");
+            finishDone(stream, tracker, model, reason);
+        }
+        catch (error) {
+            finishError(stream, tracker, model, error, signal);
+        }
+    }
+    /** 产出一步，返回产出的文本（估算 output token 用）。 */
+    async emitStep(step, tracker, signal) {
+        if ("delayMs" in step) {
+            await sleep(step.delayMs, signal);
+            return "";
+        }
+        if ("text" in step) {
+            const index = tracker.startText();
+            for (const part of chunks(step.text, step.chunkSize)) {
+                tracker.appendText(index, part);
+                await tick();
+                if (signal.aborted)
+                    throw new AbortedError("aborted");
+            }
+            tracker.end(index);
+            return step.text;
+        }
+        if ("thinking" in step) {
+            const index = tracker.startThinking("", step.signature ?? "fake-signature");
+            for (const part of chunks(step.thinking, step.chunkSize)) {
+                tracker.appendThinking(index, part);
+                await tick();
+                if (signal.aborted)
+                    throw new AbortedError("aborted");
+            }
+            tracker.end(index);
+            return step.thinking;
+        }
+        const id = step.toolCall.id ?? `fake_call_${tracker.output.content.length}`;
+        const index = tracker.startToolCall(id, step.toolCall.name);
+        const json = JSON.stringify(step.toolCall.arguments ?? {});
+        for (const part of chunks(json, step.chunkSize)) {
+            tracker.appendToolArgs(index, part);
+            await tick();
+            if (signal.aborted)
+                throw new AbortedError("aborted");
+        }
+        tracker.end(index);
+        return json;
+    }
+}
+/** 进程级缺省实例（`--provider fake`）：脚本来自 AMA_FAKE_SCRIPT，录制到 AMA_FAKE_RECORD。 */
+export const defaultFakeProvider = new FakeProvider(() => {
+    const path = process.env[FAKE_SCRIPT_ENV];
+    return path ? loadFakeScript(path) : undefined;
+}, { recordFile: () => process.env[FAKE_RECORD_ENV] || undefined });
+export const fakeApi = defaultFakeProvider.api;

package/dist/ai/fake/fake-script.d.ts

@@ -0,0 +1,69 @@
+/**
+ * 脚本化供应商的脚本形状与加载（设计 §1.2 ai/fake/fake-script.ts、D16）。
+ *
+ * 第 n 次调用取 `responses[n]`；用完后按 `whenExhausted` 处理（缺省 echo：回显最后一条用户消息）。
+ *
+ * ```json
+ * { "version": 1, "responses": [
+ *   { "steps": [{ "thinking": "先看文件" }, { "toolCall": { "name": "read", "arguments": { "path": "a.ts" } } }] },
+ *   { "error": { "kind": "rate_limit" } },
+ *   { "text": "完成", "usage": { "input": 1200, "output": 30 } },
+ *   { "steps": [{ "text": "写到一半" }], "error": { "kind": "disconnect" } },
+ *   { "delayMs": 500, "text": "慢响应", "stopReason": "length" }
+ * ] }
+ * ```
+ *
+ * 错误种类与文案（与真实协议的 errorMessage 同形，便于会话层用同一套分类器）：
+ * rate_limit 429 / overloaded 529 / server 500 / auth 401 / overflow 400（溢出文案）/
+ * network（连接失败）/ disconnect（已有内容后断流）/ custom（自定义 message 与 status）。
+ * 除 disconnect 外都发生在 start 之前（与真实 HTTP 错误一致：只有一个 error 事件）。
+ */
+import type { Usage } from "../types.js";
+export type FakeStep = {
+    text: string;
+    chunkSize?: number;
+} | {
+    thinking: string;
+    signature?: string;
+    chunkSize?: number;
+} | {
+    toolCall: {
+        name: string;
+        arguments?: Record<string, unknown>;
+        id?: string;
+    };
+    chunkSize?: number;
+} | {
+    delayMs: number;
+};
+export type FakeErrorKind = "rate_limit" | "overloaded" | "server" | "auth" | "overflow" | "network" | "disconnect" | "custom";
+export interface FakeError {
+    kind: FakeErrorKind;
+    message?: string;
+    status?: number;
+}
+export interface FakeResponse {
+    /** 依次产出的块；与 `text` 简写二选一（都给时 text 在后）。 */
+    steps?: FakeStep[];
+    text?: string;
+    /** 缺省：有工具调用 → toolUse，否则 stop。 */
+    stopReason?: "stop" | "length" | "toolUse";
+    usage?: Partial<Pick<Usage, "input" | "output" | "cacheRead" | "cacheWrite">>;
+    error?: FakeError;
+    /** start 之前的延迟（毫秒，可被 abort 打断）。 */
+    delayMs?: number;
+}
+export type FakeExhaustedBehavior = "echo" | "repeat-last" | "error";
+export interface FakeScript {
+    version: 1;
+    responses: FakeResponse[];
+    whenExhausted?: FakeExhaustedBehavior;
+}
+/** 校验脚本；接受完整脚本对象或响应数组简写。 */
+export declare function parseFakeScript(value: unknown): FakeScript;
+export declare function loadFakeScript(path: string): FakeScript;
+/** 错误种类 → (HTTP 状态, errorMessage)。文案与 overflow.ts / 会话层重试分类器对齐。 */
+export declare function describeFakeError(error: FakeError): {
+    status: number;
+    message: string;
+};

package/dist/ai/fake/fake-script.js

@@ -0,0 +1,142 @@
+/**
+ * 脚本化供应商的脚本形状与加载（设计 §1.2 ai/fake/fake-script.ts、D16）。
+ *
+ * 第 n 次调用取 `responses[n]`；用完后按 `whenExhausted` 处理（缺省 echo：回显最后一条用户消息）。
+ *
+ * ```json
+ * { "version": 1, "responses": [
+ *   { "steps": [{ "thinking": "先看文件" }, { "toolCall": { "name": "read", "arguments": { "path": "a.ts" } } }] },
+ *   { "error": { "kind": "rate_limit" } },
+ *   { "text": "完成", "usage": { "input": 1200, "output": 30 } },
+ *   { "steps": [{ "text": "写到一半" }], "error": { "kind": "disconnect" } },
+ *   { "delayMs": 500, "text": "慢响应", "stopReason": "length" }
+ * ] }
+ * ```
+ *
+ * 错误种类与文案（与真实协议的 errorMessage 同形，便于会话层用同一套分类器）：
+ * rate_limit 429 / overloaded 529 / server 500 / auth 401 / overflow 400（溢出文案）/
+ * network（连接失败）/ disconnect（已有内容后断流）/ custom（自定义 message 与 status）。
+ * 除 disconnect 外都发生在 start 之前（与真实 HTTP 错误一致：只有一个 error 事件）。
+ */
+import { readFileSync } from "node:fs";
+import { AmaError } from "../../errors.js";
+const ERROR_KINDS = [
+    "rate_limit",
+    "overloaded",
+    "server",
+    "auth",
+    "overflow",
+    "network",
+    "disconnect",
+    "custom",
+];
+function fail(path, message) {
+    throw new AmaError("invalid_arguments", `fake script ${path}: ${message}`);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function checkStep(step, path) {
+    if (!isRecord(step))
+        fail(path, "step must be an object");
+    if (typeof step["text"] === "string")
+        return step;
+    if (typeof step["thinking"] === "string")
+        return step;
+    if (typeof step["delayMs"] === "number")
+        return step;
+    const call = step["toolCall"];
+    if (isRecord(call) && typeof call["name"] === "string") {
+        if (call["arguments"] !== undefined && !isRecord(call["arguments"])) {
+            fail(`${path}.toolCall.arguments`, "must be an object");
+        }
+        return step;
+    }
+    return fail(path, "expected one of text / thinking / toolCall / delayMs");
+}
+function checkResponse(value, path) {
+    if (!isRecord(value))
+        fail(path, "response must be an object");
+    if (value["steps"] !== undefined) {
+        if (!Array.isArray(value["steps"]))
+            fail(`${path}.steps`, "must be an array");
+        value["steps"].forEach((step, i) => checkStep(step, `${path}.steps[${i}]`));
+    }
+    if (value["text"] !== undefined && typeof value["text"] !== "string") {
+        fail(`${path}.text`, "must be a string");
+    }
+    const stop = value["stopReason"];
+    if (stop !== undefined && stop !== "stop" && stop !== "length" && stop !== "toolUse") {
+        fail(`${path}.stopReason`, "must be stop / length / toolUse");
+    }
+    const error = value["error"];
+    if (error !== undefined) {
+        if (!isRecord(error) || !ERROR_KINDS.includes(error["kind"])) {
+            fail(`${path}.error.kind`, `must be one of ${ERROR_KINDS.join(" / ")}`);
+        }
+    }
+    return value;
+}
+/** 校验脚本；接受完整脚本对象或响应数组简写。 */
+export function parseFakeScript(value) {
+    const script = Array.isArray(value) ? { version: 1, responses: value } : value;
+    if (!isRecord(script))
+        fail("$", "must be an object or an array of responses");
+    if (script["version"] !== 1)
+        fail("$.version", "must be 1");
+    if (!Array.isArray(script["responses"]))
+        fail("$.responses", "must be an array");
+    script["responses"].forEach((r, i) => checkResponse(r, `$.responses[${i}]`));
+    const exhausted = script["whenExhausted"];
+    if (exhausted !== undefined && !["echo", "repeat-last", "error"].includes(exhausted)) {
+        fail("$.whenExhausted", "must be echo / repeat-last / error");
+    }
+    return script;
+}
+export function loadFakeScript(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        throw new AmaError("invalid_arguments", `cannot read fake script ${path}`, { cause: error });
+    }
+    try {
+        return parseFakeScript(JSON.parse(raw));
+    }
+    catch (error) {
+        if (error instanceof AmaError)
+            throw error;
+        throw new AmaError("invalid_arguments", `fake script ${path} is not valid JSON`, {
+            cause: error,
+        });
+    }
+}
+/** 错误种类 → (HTTP 状态, errorMessage)。文案与 overflow.ts / 会话层重试分类器对齐。 */
+export function describeFakeError(error) {
+    const custom = (fallback) => error.message ?? fallback;
+    switch (error.kind) {
+        case "rate_limit":
+            return { status: 429, message: `429 rate_limit_error: ${custom("Rate limit exceeded")}` };
+        case "overloaded":
+            return { status: 529, message: `529 overloaded_error: ${custom("Overloaded")}` };
+        case "server":
+            return { status: 500, message: `500 api_error: ${custom("Internal server error")}` };
+        case "auth":
+            return {
+                status: 401,
+                message: `401 authentication_error: ${custom("invalid x-api-key")}`,
+            };
+        case "overflow":
+            return {
+                status: 400,
+                message: `400 invalid_request_error: ${custom("prompt is too long: 250000 tokens > 200000 maximum")}`,
+            };
+        case "network":
+            return { status: 0, message: `fetch failed: ${custom("ECONNRESET socket hang up")}` };
+        case "disconnect":
+            return { status: 200, message: custom("Stream ended before completion") };
+        case "custom":
+            return { status: error.status ?? 400, message: custom("fake error") };
+    }
+}

package/dist/ai/http.d.ts

@@ -0,0 +1,54 @@
+/**
+ * fetch 包装（设计 §1.2 ai/http.ts）：超时、头合并（值为 null 删除）、错误体读取。
+ *
+ * 代理：Node 的全局 fetch 缺省不读 HTTP(S)_PROXY。Node ≥ 24 设 `NODE_USE_ENV_PROXY=1`
+ * 即可让 fetch 走环境变量代理；Node 22 需在启动参数里加 `--use-env-proxy`（22.21+）。
+ * 本模块不自行实现代理，env 原样透传给运行时处理。
+ *
+ * 协议层自身**不重试**（重试在会话层，§3.6）。
+ */
+import type { AuthHeader } from "./types.js";
+export type HeaderSource = Readonly<Record<string, string | null | undefined>> | undefined;
+/** 大小写不敏感地合并头；后者覆盖前者；值为 null 表示删除该头。键保留最后一次出现的写法。 */
+export declare function mergeHeaders(...sources: HeaderSource[]): Record<string, string>;
+export declare function hasHeader(headers: HeaderSource, name: string): boolean;
+/** 头里已经带了鉴权（调用方自管 key）时，流函数不再要求 apiKey。 */
+export declare function hasAuthHeader(headers: HeaderSource): boolean;
+/** 按 AuthHeader 形状生成鉴权头；无 key 时返回空对象。 */
+export declare function authHeaders(apiKey: string | undefined, shape: AuthHeader | undefined, fallback: AuthHeader): Record<string, string>;
+export declare const USER_AGENT: string;
+/** baseUrl 与路径拼接（去掉多余斜杠）。 */
+export declare function joinUrl(baseUrl: string, path: string): string;
+/** 非 2xx 响应；`message` 已是可展示、可被 overflow / 重试分类器匹配的文本。 */
+export declare class HttpError extends Error {
+    readonly status: number;
+    readonly body: string;
+    readonly retryAfterMs: number | undefined;
+    constructor(status: number, message: string, body: string, retryAfterMs?: number);
+}
+export declare class RequestTimeoutError extends Error {
+    constructor(timeoutMs: number);
+}
+/**
+ * 从错误体提取文本：识别 `{error:{type,message,code}}`、`{error:"..."}`、`{message}`、
+ * `{detail}` 等常见形状；不是 JSON 则截断原文。结果形如 `429 rate_limit_error: ...`。
+ */
+export declare function formatErrorBody(status: number, statusText: string, body: string): string;
+/** 识别 JSON 错误体；无法识别返回 undefined。也用于 SSE 流内的 error 事件。 */
+export declare function describeErrorJson(value: unknown): string | undefined;
+export interface PostOptions {
+    headers: Record<string, string>;
+    body: unknown;
+    signal: AbortSignal;
+    timeoutMs?: number | undefined;
+    onResponse?: ((status: number, headers: Headers) => void) | undefined;
+}
+/**
+ * POST JSON 并返回 2xx 响应（body 是 SSE 字节流）。非 2xx → HttpError；超时 → RequestTimeoutError；
+ * 调用方的 signal 中止 → 原样抛 AbortError（调用方据 signal.aborted 判 aborted）。
+ * 超时只覆盖到拿到响应头为止，流式读取期间由调用方的 signal 控制。
+ */
+export declare function postJson(url: string, options: PostOptions): Promise<Response>;
+/** undici 的 `fetch failed` 把真正原因藏在 cause 里；拼出来便于重试分类与排错。 */
+export declare function normalizeNetworkError(error: unknown): unknown;
+export declare function errorText(error: unknown): string;