@yss123/cage-ai 0.0.0-stage → 0.3.1

package/dist/query.js

@@ -0,0 +1,82 @@
+/**
+ * 把模型提交的有限查询计划编译到已授权聚合的 safe 视图。
+ * 由助理查询工具调用，字段来自注册表、值使用参数绑定；不接受任意 SQL、关联表或隐藏字段，结果在审计成功后才交给模型。
+ */
+import { cageError, snake, isRelation, canUnmask } from '@yss123/cage-kernel';
+import { queryPlanSchema } from '@yss123/cage-ai-protocol';
+import { sql } from 'kysely';
+import { parse } from './security.js';
+/** NL2Query 编译到有限查询计划；标识符来自注册表，值永远参数化，执行账号只能读 safe。 */
+/**
+ * 验证查询计划与聚合 read 能力，并构造受限投影、过滤、排序和分组指标。
+ * 隐藏字段、关系和 JSON 不参与计划；对敏感字段做过滤/排序/汇总要求解掩码能力，sum/avg 仅支持数值字段。
+ * 在安全只读事务内设置 5 秒语句超时，取 limit+1 行判断截断；随后可靠写入用途审计，审计失败不交付已查询数据。
+ * 返回来源、前 limit 行与 truncated 标记；结果受当前租户/范围约束，不能把截断页当作完整统计。
+ */
+export async function queryPlan(kernel, ctx, input) {
+    const plan = parse(queryPlanSchema, input), agg = kernel.registry.aggregate(plan.aggregate);
+    if (!agg || !ctx.capabilities.has(`${agg.name}.read`))
+        throw cageError('FORBIDDEN');
+    const system = { id: 'id', status: 'status', version: 'version', createdAt: 'created_at', updatedAt: 'updated_at' };
+    // 标识符只从系统字段和注册字段映射；对敏感值做过滤/排序/汇总可能泄漏信息，因此 operation 额外要求解掩码权。
+    const field = (name, operation = false) => {
+        if (Object.hasOwn(system, name))
+            return system[name];
+        const f = agg.fields[name];
+        if (!f || f.isHidden || isRelation(f) || f.sql === 'jsonb')
+            throw cageError('INVALID_INPUT', '字段不支持查询计划');
+        if (operation && f.sensitiveKind && !canUnmask(ctx, agg.name, f.sensitiveKind))
+            throw cageError('FORBIDDEN');
+        return snake(name);
+    };
+    if (plan.metrics.length && plan.select?.some(n => !plan.groupBy.includes(n)))
+        throw cageError('INVALID_INPUT', '汇总查询只能选择分组字段和指标');
+    if (plan.groupBy.length && !plan.metrics.length)
+        throw cageError('INVALID_INPUT', '分组必须包含指标');
+    const selected = plan.select ?? (plan.metrics.length ? plan.groupBy : ['id', 'status', 'version']);
+    const aliases = new Set(selected);
+    const projections = selected.map(n => sql.ref(field(n, plan.metrics.length > 0)).as(n));
+    for (const metric of plan.metrics) {
+        if (aliases.has(metric.as))
+            throw cageError('INVALID_INPUT', '指标名称重复');
+        aliases.add(metric.as);
+        const ref = metric.field ? sql.ref(field(metric.field, true)) : sql.raw('*');
+        if (metric.op !== 'count' && !metric.field)
+            throw cageError('INVALID_INPUT', '该指标需要字段');
+        if (['sum', 'avg'].includes(metric.op) && !['int', 'number', 'money'].includes(agg.fields[metric.field]?.kind))
+            throw cageError('INVALID_INPUT', '汇总需要数值字段');
+        const expr = metric.op === 'count' ? sql `count(${ref})` : metric.op === 'sum' ? sql `sum(${ref})` : metric.op === 'avg' ? sql `avg(${ref})` : metric.op === 'min' ? sql `min(${ref})` : sql `max(${ref})`;
+        projections.push(expr.as(metric.as));
+    }
+    if (!projections.length)
+        throw cageError('INVALID_INPUT', '必须选择字段或指标');
+    const rows = await kernel.read.tx(ctx, async (tx) => {
+        await sql `select set_config('statement_timeout', '5000', true)`.execute(tx);
+        let query = tx.selectFrom(`safe.${agg.table.name}`).select(projections).where('status', '<>', 'deleted');
+        const ops = { eq: '=', ne: '<>', gt: '>', gte: '>=', lt: '<', lte: '<=', in: 'in' };
+        for (const where of plan.where) {
+            const column = field(where.field, true), f = agg.fields[where.field];
+            const values = where.op === 'in' ? where.value : [where.value];
+            if (!Array.isArray(values) || !values.length || values.length > 100 || values.some(v => v === null || typeof v === 'object'))
+                throw cageError('INVALID_INPUT', '过滤值必须是有界标量');
+            if (f)
+                for (const value of values)
+                    parse(f.base, value);
+            query = query.where(sql.ref(column), ops[where.op], where.value);
+        }
+        for (const group of plan.groupBy)
+            query = query.groupBy(sql.ref(field(group, true)));
+        if (plan.orderBy) {
+            if (plan.metrics.length && !aliases.has(plan.orderBy.field))
+                throw cageError('INVALID_INPUT', '只能按所选字段排序');
+            query = query.orderBy(sql.ref(plan.metrics.length && aliases.has(plan.orderBy.field) ? plan.orderBy.field : field(plan.orderBy.field, true)), plan.orderBy.direction);
+        }
+        return query.limit(plan.limit + 1).execute();
+    });
+    // 计划可能读取敏感明文；审计失败时不向模型交付结果。
+    await kernel.writeAudit(kernel.app, { tenantId: ctx.tenantId, actor: ctx.actor.id, actorKind: ctx.actor.kind, source: ctx.source,
+        kind: 'read', capability: `${agg.name}.read`, aggregate: agg.name, result: 'ok', requestId: ctx.requestId,
+        diff: { purpose: 'ai.queryPlan', fields: selected, metrics: plan.metrics, rows: rows.length } });
+    return { source: `aggregate:${agg.name}`, rows: rows.slice(0, plan.limit), truncated: rows.length > plan.limit, limit: plan.limit };
+}
+//# sourceMappingURL=query.js.map

package/dist/query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.js","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"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"}

package/dist/request-plan.d.ts

@@ -0,0 +1,59 @@
+import { type ModelBudget } from './budget.js';
+import { type RemoteHistory, type ToolPlan } from './state.js';
+import { type Tool } from './tools.js';
+import type { AiContextOptions, Execution, ModelMessage, ModelProvider } from './types.js';
+/**
+ * 可被运行时原子记录的单次模型请求计划。
+ * 所有字段来自同一 provider 和预算快照，避免请求参数、预留用量及后续工具加载使用不同配置。
+ */
+export interface ModelPlan {
+    /**
+     * 最终模型消息，可能包含明确的上下文展开引用。
+     */
+    messages: ModelMessage[];
+    /**
+     * 本轮完整可执行工具对象；发送协议时只提取公开 schema。
+     */
+    tools: Tool[];
+    /**
+     * 实际装载的业务命令/查询本体 key，不包括基础工具。
+     */
+    keys: string[];
+    /**
+     * 本轮全量/发现模式及可复用的工具预算。
+     */
+    selection: ToolPlan;
+    /**
+     * 已核对配置键和历史游标的远端状态；null 表示本地重建。
+     */
+    remote: RemoteHistory | null;
+    /**
+     * 本轮输入加已知远端历史的 Token 估算值。
+     */
+    estimatedInput: number;
+    /**
+     * 不超过模型输出配置及本轮剩余累计预算的输出 Token 上限。
+     */
+    outputLimit: number;
+    /**
+     * 本次请求是否省略或缩小资料，需要向模型明示。
+     */
+    reduced: boolean;
+    /**
+     * 本次请求共用的窗口、累计消耗及工具容量快照。
+     */
+    budget: ModelBudget;
+}
+/** 只装配请求，不执行模型或更改状态。一次规划共享模型配置和预算快照。 */
+/**
+ * 核验轮数、尝试次数及累计 Token 预算，再选择全量工具或助理发现模式。
+ * 有效远端接续先扣除已知历史成本，不能因为启用压缩就假定窗口变小；接续装不下时从本地历史重新规划。
+ * 审批不能降级为工具发现；当容量不足实际来自累计预算而非模型窗口时，映射为 AI_BUDGET_EXCEEDED，便于区分配置与本次运行耗尽。
+ */
+export declare function planModelRequest(execution: Execution, provider: ModelProvider, options?: AiContextOptions): ModelPlan;
+/** 搜索加载与显式加载共用同一容量规则；返回值与 tool_keys 在动作回执事务中一起保存。 */
+/**
+ * 依据上轮已持久化的 tool_plan 装载搜索或显式请求的工具。
+ * 显式加载要求所有完整定义都装下，否则拒绝并提示减少数量；搜索加载允许预算内部分命中。返回的 keys 由调用方与动作回执同事务保存，不在此更改运行状态。
+ */
+export declare function discoveredToolKeys(execution: Execution, requested: string[], explicit: boolean): string[];

package/dist/request-plan.js

@@ -0,0 +1,168 @@
+/**
+ * 将运行快照、模型配置、授权工具和上下文预算组装为单次模型请求计划。
+ * 由运行时在发起外部请求前调用，发现工具也复用同一容量规则；这里只规划，不发网络请求、不修改运行记录，持久化由租约事务完成。
+ */
+import { cageError } from '@yss123/cage-kernel';
+import { modelBudget, checkModelBudget } from './budget.js';
+import { SYSTEM_PROMPT, ONTOLOGY_PROMPT, DISCOVERY_PROMPT } from './context.js';
+import { personalityPrompt } from './personalities.js';
+import { packPrompt, toolTokens } from './prompt.js';
+import { remoteHistory } from './state.js';
+import { authorizedToolKeys, candidateToolKeys } from './tool-catalog.js';
+import { toolsFor } from './tools.js';
+/**
+ * 按运行模式组合系统指令。
+ * 审批仅加入节点策略与审核工具约束，不使用助理性格；助理加入本体发现、业务指令与表达资料，工具是否已全量加载决定发现提示。
+ */
+function instructions(execution, discovery) {
+    const { run } = execution;
+    if (run.mode === 'approval')
+        return `${SYSTEM_PROMPT}\n仅使用本审批节点的审核策略、已声明查询和 review_decide；资料不足应继续取证或转人工。\n${run.instructions}`;
+    const toolGuide = discovery
+        ? DISCOVERY_PROMPT
+        : '本轮已装载当前主体可调用的全部业务命令和查询。需要系统规则仍应查询本体；不能编造未提供的工具。';
+    return [
+        SYSTEM_PROMPT,
+        ONTOLOGY_PROMPT,
+        toolGuide,
+        run.instructions,
+        run.personality ? personalityPrompt(run.personality) : '',
+    ].join('\n');
+}
+/**
+ * 按候选先后顺序去重并装入完整工具定义，分别约束数量与 Token。
+ * 基础工具本身放不下立即失败；单个候选过大则跳过继续尝试后续候选，不裁剪工具参数 schema。返回真正装载的 key 和工具列表。
+ */
+function fitCandidates(base, business, candidates, selection) {
+    const tools = [...base], keys = [];
+    if (tools.length > selection.maxTools || toolTokens(tools) > selection.tokenBudget)
+        throw new Error('AI_CONTEXT_TOO_LARGE');
+    for (const key of new Set(candidates)) {
+        const tool = business.get(key);
+        if (!tool)
+            continue;
+        if (tools.length === selection.maxTools)
+            break;
+        if (toolTokens([...tools, tool]) > selection.tokenBudget)
+            continue;
+        tools.push(tool);
+        keys.push(key);
+    }
+    return { keys, tools };
+}
+/** 只装配请求，不执行模型或更改状态。一次规划共享模型配置和预算快照。 */
+/**
+ * 核验轮数、尝试次数及累计 Token 预算，再选择全量工具或助理发现模式。
+ * 有效远端接续先扣除已知历史成本，不能因为启用压缩就假定窗口变小；接续装不下时从本地历史重新规划。
+ * 审批不能降级为工具发现；当容量不足实际来自累计预算而非模型窗口时，映射为 AI_BUDGET_EXCEEDED，便于区分配置与本次运行耗尽。
+ */
+export function planModelRequest(execution, provider, options = {}) {
+    const { run } = execution;
+    const budget = modelBudget(provider, run.limits, run.tokens, options);
+    checkModelBudget(run.limits, run.steps, run.model_attempts, budget);
+    const key = provider.continuation?.key;
+    const remote = run.continuation_disabled_key === key ? null : remoteHistory(run.model_state, key, run.history.length);
+    const allKeys = run.mode === 'assistant' ? authorizedToolKeys(execution) : [];
+    const full = toolsFor(execution, { keys: allKeys, discovery: false });
+    // 单次装配可尝试远端接续或本地历史；两条路径共用已解析 provider 和预算，失败才切换，避免参数快照漂移。
+    function assemble(state) {
+        // 没有实际压缩结果的用量不能凭开关假定缩小。接续超预算时使用本地完整交互重新装配。
+        const chainTokens = state?.contextTokens ?? 0;
+        const inputLimit = budget.inputLimit - chainTokens;
+        if (run.mode === 'approval' && full.length > budget.maxTools)
+            throw new Error('AI_CONTEXT_TOO_LARGE');
+        const pack = (tools, discovery) => packPrompt({
+            instructions: instructions(execution, discovery),
+            context: run.context,
+            tools,
+            history: state ? run.history.slice(state.historyLength) : run.history,
+            historyOmitted: !state && run.history_omitted,
+            continuation: !!state,
+            stateKey: key,
+            maxInputTokens: inputLimit,
+        });
+        let keys = allKeys, tools = full;
+        const baseAll = full.filter((tool) => !tool.key);
+        const baselineAll = pack(baseAll, false);
+        const allAvailable = inputLimit - (baselineAll.estimatedInput - toolTokens(baseAll));
+        const defaultAllowance = Math.max(budget.toolTokens, toolTokens(baseAll));
+        let selection = {
+            mode: 'all',
+            tokenBudget: Math.min(options.maxToolTokens ?? defaultAllowance, allAvailable),
+            maxTools: budget.maxTools,
+        };
+        let packed;
+        if (run.mode === 'approval' || (full.length <= budget.maxTools && toolTokens(full) <= selection.tokenBudget)) {
+            try {
+                packed = pack(full, false);
+            }
+            catch (error) {
+                if (!(error instanceof Error) || error.message !== 'AI_CONTEXT_TOO_LARGE')
+                    throw error;
+            }
+        }
+        if (!packed) {
+            if (run.mode === 'approval')
+                throw new Error('AI_CONTEXT_TOO_LARGE');
+            const base = toolsFor(execution, { keys: [], discovery: true });
+            const baseline = pack(base, true);
+            const available = inputLimit - (baseline.estimatedInput - toolTokens(base));
+            selection = {
+                mode: 'discovery',
+                tokenBudget: Math.min(options.maxToolTokens ?? Math.max(budget.toolTokens, toolTokens(base)), available),
+                maxTools: budget.maxTools,
+            };
+            const business = new Map(full.filter((tool) => tool.key).map((tool) => [tool.key, tool]));
+            ({ keys, tools } = fitCandidates(base, business, candidateToolKeys(execution), selection));
+            packed = pack(tools, true);
+        }
+        const estimatedInput = packed.estimatedInput + chainTokens;
+        return {
+            ...packed,
+            tools,
+            keys,
+            selection,
+            remote: state,
+            estimatedInput,
+            budget,
+            outputLimit: Math.min(budget.outputLimit, budget.remaining - estimatedInput),
+        };
+    }
+    try {
+        if (remote) {
+            try {
+                return assemble(remote);
+            }
+            catch (error) {
+                if (!(error instanceof Error) || error.message !== 'AI_CONTEXT_TOO_LARGE')
+                    throw error;
+            }
+        }
+        return assemble(null);
+    }
+    catch (error) {
+        if (error instanceof Error &&
+            error.message === 'AI_CONTEXT_TOO_LARGE' &&
+            budget.inputLimit < budget.windowInputLimit)
+            throw new Error('AI_BUDGET_EXCEEDED');
+        throw error;
+    }
+}
+/** 搜索加载与显式加载共用同一容量规则；返回值与 tool_keys 在动作回执事务中一起保存。 */
+/**
+ * 依据上轮已持久化的 tool_plan 装载搜索或显式请求的工具。
+ * 显式加载要求所有完整定义都装下，否则拒绝并提示减少数量；搜索加载允许预算内部分命中。返回的 keys 由调用方与动作回执同事务保存，不在此更改运行状态。
+ */
+export function discoveredToolKeys(execution, requested, explicit) {
+    const selection = execution.run.tool_plan;
+    if (!selection)
+        throw cageError('CONFLICT', '工具预算尚未装配，请重新发起任务');
+    const full = toolsFor(execution, { keys: requested, discovery: false });
+    const business = new Map(full.filter((tool) => tool.key).map((tool) => [tool.key, tool]));
+    const base = toolsFor(execution, { keys: [], discovery: true });
+    const { keys } = fitCandidates(base, business, requested, selection);
+    if (explicit && keys.length !== requested.length)
+        throw cageError('INVALID_INPUT', '工具完整定义超出本轮上下文预算，请减少加载数量或配置更大的窗口');
+    return keys;
+}
+//# sourceMappingURL=request-plan.js.map

package/dist/request-plan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-plan.js","sourceRoot":"","sources":["../src/request-plan.ts"],"names":[],"mappings":"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"}

package/dist/responses.d.ts

@@ -0,0 +1,29 @@
+import { type ChatModelOptions } from './model.js';
+import type { ModelProvider } from './types.js';
+/**
+ * Responses 配置复用模型主机、凭据与窗口设置，并可显式启用厂商上下文压缩。
+ * 压缩是协议能力声明，不会自动验证网关支持；不启用自动截断来静默丢弃业务历史。
+ */
+export interface ResponsesModelOptions extends ChatModelOptions {
+    /** 只在服务支持 context_management 时启用；不使用自动丢弃历史的 truncation。 */
+    compaction?: boolean;
+}
+/**
+ * 通知运行时从本地持久历史重建请求的内部异常。
+ * 仅用于尚未向用户输出文本的远端历史失效或网关不支持接续；它不是模型业务结论，也不是任意网络失败的重试许可。
+ */
+export declare class ResponseHistoryExpired extends Error {
+    readonly reason: 'expired' | 'unsupported';
+    /**
+     * 创建接续失效信号；expired 允许以后继续使用有效远端历史，unsupported 由运行时记录该配置不支持接续。
+     */
+    constructor(reason?: 'expired' | 'unsupported');
+}
+/** Responses 与 Chat 共用连接器边界；接续 ID、工具回执和每次重发的指令由框架组装。 */
+/**
+ * 构造 Responses provider；声明 spec 的摘要作为远端历史配置键。
+ * 每次请求重新发送系统指令，关闭自动 truncation，并显式使用非 strict 工具 schema 以保留合法可选参数。
+ * 只接受唯一 completed 终态，核对创建/结束响应 ID 和流式/最终文本；函数调用之外只保留 reasoning、compaction 项，其他工具类型拒绝执行。
+ * 404 或不支持 previous_response_id 且尚无文本时抛恢复信号；已有文本的失败直接上抛，避免静默重放造成重复输出。
+ */
+export declare function responsesModel(name: string, options: ResponsesModelOptions): ModelProvider;

package/dist/responses.js

@@ -0,0 +1,134 @@
+/**
+ * 适配 Responses 流式协议及远端会话接续。
+ * 与 Chat provider 共用连接器安全边界，保留同配置的 provider 原始输出以恢复推理/压缩项；远端历史不可用时向运行时发恢复信号，不直接重放业务工具。
+ */
+import { connector, ConnectorError, stage, streamJson } from '@yss123/cage-connectors';
+import { validateModelResult } from './model.js';
+import { digest } from './security.js';
+import { ModelResponseError, parseModelJson, providerErrorCode } from './model-failure.js';
+/**
+ * 通知运行时从本地持久历史重建请求的内部异常。
+ * 仅用于尚未向用户输出文本的远端历史失效或网关不支持接续；它不是模型业务结论，也不是任意网络失败的重试许可。
+ */
+export class ResponseHistoryExpired extends Error {
+    reason;
+    /**
+     * 创建接续失效信号；expired 允许以后继续使用有效远端历史，unsupported 由运行时记录该配置不支持接续。
+     */
+    constructor(reason = 'expired') {
+        super('RESPONSES_HISTORY_EXPIRED');
+        this.reason = reason;
+    }
+}
+/**
+ * 将统一消息映射为 Responses input 项。
+ * 系统指令由调用方单独重发；工具回执保留 call_id，只有 providerItems 的配置 key 相等时才复用原始项，防止不同模型配置的私有状态混用。
+ */
+function inputItems(messages, key) {
+    const items = [];
+    for (const message of messages) {
+        if (message.role === 'system')
+            continue;
+        if (message.role === 'tool')
+            items.push({ type: 'function_call_output', call_id: message.toolCallId, output: message.content });
+        else if (message.role === 'assistant' && message.providerItems && message.providerItems.key === key)
+            items.push(...message.providerItems.items);
+        else {
+            if (message.content)
+                items.push({ role: message.role, content: message.content });
+            for (const call of message.toolCalls ?? [])
+                items.push({ type: 'function_call', call_id: call.id, name: call.name, arguments: JSON.stringify(call.arguments) });
+        }
+    }
+    return items;
+}
+/** Responses 与 Chat 共用连接器边界；接续 ID、工具回执和每次重发的指令由框架组装。 */
+/**
+ * 构造 Responses provider；声明 spec 的摘要作为远端历史配置键。
+ * 每次请求重新发送系统指令，关闭自动 truncation，并显式使用非 strict 工具 schema 以保留合法可选参数。
+ * 只接受唯一 completed 终态，核对创建/结束响应 ID 和流式/最终文本；函数调用之外只保留 reasoning、compaction 项，其他工具类型拒绝执行。
+ * 404 或不支持 previous_response_id 且尚无文本时抛恢复信号；已有文本的失败直接上抛，避免静默重放造成重复输出。
+ */
+export function responsesModel(name, options) {
+    const transport = connector(name, { hosts: options.hosts, secret: options.secret, timeoutMs: options.timeoutMs ?? 90_000,
+        rateLimit: options.rateLimit, operations: {} });
+    const path = options.path ?? '/v1/responses', window = options.contextWindowTokens ?? 32768;
+    const spec = { kind: 'responses', name, model: options.model, hosts: options.hosts, secret: options.secret, path,
+        timeoutMs: transport.timeoutMs, environment: options.environment, protocol: options.protocol, contextWindowTokens: window, compaction: !!options.compaction };
+    const key = digest(spec);
+    return { spec, contextWindowTokens: window, continuation: { key, compaction: !!options.compaction },
+        async generate(request) {
+            const environment = options.environment ?? stage();
+            if (environment === 'fake') {
+                if (!options.fake)
+                    throw new Error('模型未配置 fake；真实联调需显式选择 test/prod 阶段');
+                return validateModelResult(await options.fake(request));
+            }
+            let final, streamed = '', responseId;
+            const body = { model: options.model, stream: true, store: true, truncation: 'disabled', max_output_tokens: request.maxOutputTokens,
+                include: ['reasoning.encrypted_content'],
+                instructions: request.messages.filter(m => m.role === 'system').map(m => m.content).join('\n\n'),
+                input: inputItems(request.messages, request.stateKey ?? key),
+                ...(request.previousResponseId ? { previous_response_id: request.previousResponseId } : {}),
+                ...(options.compaction ? { context_management: [{ type: 'compaction', compact_threshold: Math.floor(window * .6) }] } : {}),
+                // Cage 输入存在合法可选字段；不能让 Responses 默认 strict 转换将其变成必填。
+                ...(request.tools.length ? { tools: request.tools.map(t => ({ type: 'function', name: t.name, description: t.description, parameters: t.input, strict: false })) } : {}),
+            };
+            try {
+                await streamJson(transport, path, body, request.signal, async (data) => {
+                    if (data === '[DONE]')
+                        return;
+                    const event = parseModelJson(data, 'invalid_json');
+                    if (!event || typeof event !== 'object')
+                        throw new ModelResponseError('invalid_output');
+                    if (['error', 'response.failed', 'response.incomplete'].includes(event.type)) {
+                        const stopReason = providerErrorCode(event.response?.incomplete_details?.reason);
+                        const reason = event.type === 'response.incomplete'
+                            ? stopReason === 'max_output_tokens' ? 'output_limit' : 'incomplete' : 'provider_error';
+                        throw new ModelResponseError(reason, { stopReason, providerCode: providerErrorCode(event.code ?? event.error?.code ?? event.response?.error?.code) });
+                    }
+                    if (event.type === 'response.created')
+                        responseId = event.response?.id;
+                    if (event.type === 'response.output_text.delta' && typeof event.delta === 'string') {
+                        streamed += event.delta;
+                        await request.onText?.(event.delta);
+                    }
+                    if (event.type === 'response.completed') {
+                        if (final || event.response?.status !== 'completed')
+                            throw new ModelResponseError('invalid_terminal');
+                        final = event.response;
+                    }
+                }, { environment, protocol: options.protocol, credential: options.credential });
+            }
+            catch (error) {
+                // 缺失的远端会话可从本地记录恢复；有文本输出的失败不能重放而产生重复流。
+                const unavailable = error instanceof ConnectorError && (error.status === 404 || error.providerCode === 'PREVIOUS_RESPONSE_ID_UNSUPPORTED');
+                if (request.previousResponseId && !streamed && unavailable)
+                    throw new ResponseHistoryExpired(error instanceof ConnectorError && error.providerCode === 'PREVIOUS_RESPONSE_ID_UNSUPPORTED' ? 'unsupported' : 'expired');
+                throw error;
+            }
+            if (!final || !Array.isArray(final.output) || !final.id || (responseId && responseId !== final.id))
+                throw new ModelResponseError('incomplete');
+            let text = '';
+            const calls = [];
+            for (const item of final.output) {
+                if (item.type === 'message') {
+                    for (const content of item.content ?? [])
+                        if (content.type === 'output_text')
+                            text += content.text;
+                        else if (content.type === 'refusal')
+                            text += content.refusal;
+                }
+                else if (item.type === 'function_call')
+                    calls.push({ id: item.call_id, name: item.name, arguments: parseModelJson(item.arguments, 'invalid_arguments') });
+                else if (!['reasoning', 'compaction'].includes(item.type))
+                    throw new ModelResponseError('unexpected_tool');
+            }
+            if (streamed && streamed !== text)
+                throw new ModelResponseError('text_mismatch');
+            return validateModelResult({ text, calls, responseId: final.id, outputItems: final.output,
+                ...(final.usage ? { usage: { inputTokens: final.usage.input_tokens, outputTokens: final.usage.output_tokens } } : {}) });
+        },
+    };
+}
+//# sourceMappingURL=responses.js.map

package/dist/responses.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"responses.js","sourceRoot":"","sources":["../src/responses.ts"],"names":[],"mappings":"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"}