@migor/agentia 0.10.4 → 0.10.5

package/dist/transport/http-shapes.d.ts

@@ -2,8 +2,9 @@ import type { Trace, SpanError } from '../core/trace.js';
 import type { RunStatus } from '../core/run.js';
 import type { TaskEvent } from '../core/run.js';
 import type { AgentRunResult, AgentStopReason } from '../engine/types.js';
-import type { RunInvocationOptions } from '../engine/spec.js';
 import type { ApprovalDecisions } from './async.js';
+import type { TaskRecord } from '../store/store.js';
+import type { ClientRunOptions } from './run-options.js';
 /**
  * Agentia —— HTTP 宿主的**出入站形状口径**（transport/http.ts 的拆分第一步）。
  *
@@ -26,14 +27,30 @@ export interface RunHttpResponse {
     finalText: string;
     /** 结构化结果（R2 起应用可携带；无则为 undefined，字段在场） */
     typed: unknown;
-    trace: Trace;
+    /** `responseMode:'public'` 时不出现在响应里 */
+    trace?: Trace;
     error: SpanError | undefined;
 }
+export type TaskHttpResponse = Omit<TaskRecord, 'result' | 'spec' | 'ownerId' | 'pendingEvents'> & {
+    spec?: TaskRecord['spec'] | undefined;
+    ownerId?: string | undefined;
+    pendingEvents?: TaskRecord['pendingEvents'] | undefined;
+    result?: (Omit<AgentRunResult, 'trace' | 'suspendedMessages'> & {
+        trace?: Trace;
+        suspendedMessages?: AgentRunResult['suspendedMessages'];
+    }) | undefined;
+};
 /** POST /tasks 的请求体形态 */
 export interface TaskSubmitBody {
     input: unknown;
     idempotencyKey?: string;
-    options?: RunInvocationOptions;
+    /**
+     * 客户端选项 —— **只接受白名单键**（`traceContext` / `maxCostUsd` / `maxTotalTokens`，
+     * 见 `run-options.ts`）。身份 / 租户走宿主的 `resolveRunOptions` 钩子，不从 body 来：
+     * 此前这里是 `RunInvocationOptions`（整套引擎旋钮）⇒ 任何能调它的人都能自填
+     * `blackboard.tenant`。未知键一律 400（不静默丢弃）。
+     */
+    options?: ClientRunOptions;
 }
 /** 把 app.run 的产物收成 HTTP 响应体（JSON 与 SSE 的 run.end 共用同一形状） */
 export declare function toHttpBody(out: {
@@ -42,7 +59,13 @@ export declare function toHttpBody(out: {
         status: RunStatus;
     };
     result: AgentRunResult;
+}, opts?: {
+    public?: boolean;
 }): RunHttpResponse;
+/** 任务记录的公共投影：不删状态/结果，只去掉消息正文、trace 与内部归属。 */
+export declare function toTaskHttpBody(rec: TaskRecord, opts?: {
+    public?: boolean;
+}): TaskHttpResponse;
 /**
  * `POST /tasks` 的 body 形状闸：必须是**纯对象**（`null` / 数组 / 标量都不算）。
  * 返回**同一个引用**（不是副本）—— 后续 `runner.submit` 拿到的就是请求里那个对象。

package/dist/transport/http-shapes.js

@@ -1,5 +1,5 @@
 /** 把 app.run 的产物收成 HTTP 响应体（JSON 与 SSE 的 run.end 共用同一形状） */
-export function toHttpBody(out) {
+export function toHttpBody(out, opts = {}) {
     return {
         runId: out.run.runId,
         // status 取 **run 状态机**的口径（它才知道 suspended 不是终态），
@@ -8,10 +8,20 @@ export function toHttpBody(out) {
         stopReason: out.result.stopReason,
         finalText: out.result.finalText,
         typed: out.result.typed,
-        trace: out.result.trace,
+        ...(opts.public ? {} : { trace: out.result.trace }),
         error: out.result.error,
     };
 }
+/** 任务记录的公共投影：不删状态/结果，只去掉消息正文、trace 与内部归属。 */
+export function toTaskHttpBody(rec, opts = {}) {
+    if (!opts.public)
+        return rec;
+    const { spec: _spec, ownerId: _ownerId, pendingEvents: _pendingEvents, ...rest } = rec;
+    if (!rec.result)
+        return rest;
+    const { trace: _trace, suspendedMessages: _suspendedMessages, ...result } = rec.result;
+    return { ...rest, result };
+}
 /**
  * `POST /tasks` 的 body 形状闸：必须是**纯对象**（`null` / 数组 / 标量都不算）。
  * 返回**同一个引用**（不是副本）—— 后续 `runner.submit` 拿到的就是请求里那个对象。

package/dist/transport/http-shapes.js.map

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

package/dist/transport/http.d.ts

@@ -1,6 +1,7 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import { AsyncRunner } from './async.js';
 import type { AppCallable } from './async.js';
+import type { ResolveRunOptionsHook } from './run-options.js';
 /**
  * Agentia —— HTTP 宿主（spec §6.6：换宿主不换语义，roadmap R3）。
  *
@@ -32,6 +33,15 @@ export type { RunHttpResponse, TaskSubmitBody } from './http-shapes.js';
  * 与上面两个形状类型同一个理由（`src/index.ts` 一行未改，公开面逐字不变）。
  */
 export type { HealthResponse } from './http-endpoints.js';
+export type HttpResponseMode = 'full' | 'public';
+export type TaskControlAction = 'poll' | 'approve' | 'cancel' | 'event' | 'stream';
+export type TaskAuthorizationHook = (req: IncomingMessage, info: {
+    action: TaskControlAction;
+    taskId: string;
+    task: import('../store/store.js').TaskRecord;
+    principal: unknown;
+}) => unknown | Promise<unknown>;
+export type ApprovalActorHook = (req: IncomingMessage, principal: unknown) => string | undefined | Promise<string | undefined>;
 export interface HttpHandlerOptions {
     /** 异步任务宿主；缺省 new AsyncRunner(app)（InMemoryTaskStore） */
     runner?: AsyncRunner;
@@ -61,8 +71,10 @@ export interface HttpHandlerOptions {
     /**
      * 入口鉴权钩子。请求进入时调用，**除 /healthz 与 /metrics 外所有路径**都过它，且**在读 body 之前**
      * （未通过就不接收 body，省资源）。/metrics 与 /healthz 同档不鉴权（见 `metrics` 选项）。
-     * - 正常返回（任意值）→ 视为通过。返回值框架不转交：要 per-request 上下文请在钩子自己的
-     *   闭包里存（避免为「暂时没有消费点」的东西发明传递通道）；
+     * - 正常返回 → 视为通过。**返回值不再丢弃**：它作为 `principal` 交给
+     *   `resolveRunOptions(req, { route, principal })`（2026-11-04 起；此前注释写的是
+     *   「返回值框架不转交，请存在钩子自己的闭包里」—— 那条路走不通：闭包与 run 之间
+     *   没有任何关联手段，runId 是 run 开始后才有的。身份入 run 的唯一可信通道就是这一条）。
      * - 抛出 `HttpException` → 按其 `status` / `body` 回响应（想回 403 就抛 `status: 403`）；
      * - 抛出其它错误 → 回 401 `{ error: '未通过鉴权' }`，原文只进服务端日志
      *   （与 `exposeErrors` 同理：不把内部拓扑回给未鉴权的调用方）。
@@ -72,6 +84,38 @@ export interface HttpHandlerOptions {
      * 而鉴权要拦的是 **run 入口**，且必须早于 body 读取。
      */
     authenticate?: (req: IncomingMessage) => unknown | Promise<unknown>;
+    /**
+     * 按请求给 run 选项（**身份 / 租户 / 配额封顶的唯一可信通道**）。与 `authenticate` 配对使用：
+     * 后者的返回值会作为 `principal` 传进来。
+     *
+     * 为什么需要它：`POST /tasks` 的 `body.options` 此前整体透传给引擎 —— 任何能调它的人都能
+     * 自填 `blackboard: { tenant: '别人的租户' }`（而 usage-guide §6.6 的多租户配方正是
+     * 「用黑板存 tenant」），于是配额记到别人头上。现在客户端选项走**白名单**
+     * （见 `run-options.ts`），身份只能从这里进，且服务端值**覆盖**客户端值。
+     *
+     * 两条口径：`blackboard` 整体替换、`labels` 按键盘合并（服务端胜）、预算与客户端值
+     * 取**更严者**（上限不能由叫价方抬高）。抛 `HttpException` 按其状态码回。
+     */
+    resolveRunOptions?: ResolveRunOptionsHook;
+    /**
+     * 任务控制面的对象级授权。`authenticate` 只回答「你是谁」，本钩子回答
+     * 「你能不能对这个 task 做这件事」。在读取审批/事件 body 之前执行；
+     * 返回 `false` 回 403，抛 `HttpException` 按其状态码回，其余异常走 500。
+     */
+    authorizeTask?: TaskAuthorizationHook;
+    /**
+     * 从认证结果生成可信审批人。配置后其返回值覆盖审批 body 的 `decidedBy`；
+     * 返回 `undefined` 表示不记审批人。空字符串是宿主配置错误，按 500 处理。
+     */
+    resolveApprovalActor?: ApprovalActorHook;
+    /**
+     * HTTP 响应暴露面。`full`（缺省）保留历史形状；`public` 去掉 run/task 响应里的
+     * trace、任务消息、挂起历史和内部 ownerId，并默认关闭 SSE 的 trace.event 帧。
+     * 它只影响 HTTP 输出，不影响 TaskStore 与 TraceSink 的完整记录。
+     */
+    responseMode?: HttpResponseMode;
+    /** 是否开放 `/run` 与 `/tasks/:id/stream` 的 trace 事件；缺省 = responseMode 为 full */
+    exposeTraceEvents?: boolean;
     /**
      * 指标出口（G4）：提供后 `GET /metrics` 输出其 `render()` 的文本。
      * 通常直接传 `metricsSink()`（它有 `render()`）。

package/dist/transport/http.js

@@ -86,8 +86,16 @@ export function createHttpHandler(app, opts = {}) {
         throw new Error(`maxConcurrentRuns 必须为正数（${zeroClauseOf('HttpHandlerOptions.maxConcurrentRuns')}），收到 ${opts.maxConcurrentRuns}`);
     }
     const exposeErrors = opts.exposeErrors ?? false;
+    const responseMode = opts.responseMode ?? 'full';
+    if (responseMode !== 'full' && responseMode !== 'public') {
+        throw new TypeError(`responseMode 只接受 'full' | 'public'，收到 ${String(opts.responseMode)}`);
+    }
+    const exposeTraceEvents = opts.exposeTraceEvents ?? responseMode === 'full';
     const sseMaxBufferedBytes = opts.sseMaxBufferedBytes;
     const authenticate = opts.authenticate;
+    const resolveRunOptions = opts.resolveRunOptions;
+    const authorizeTask = opts.authorizeTask;
+    const resolveApprovalActor = opts.resolveApprovalActor;
     const metrics = opts.metrics;
     const startedAt = Date.now();
     /**
@@ -169,41 +177,58 @@ export function createHttpHandler(app, opts = {}) {
         // 顺序陷阱写在那边的头注里，最要命的一条：免鉴权组（/healthz、/metrics）
         // 连同它们自己的 405 都在鉴权**之前**回，其余一律**先鉴权再判方法/路径**。
         const route = routeRequest(pathname, method, metrics !== undefined);
-        // 一个请求一份 ctx：`state` 按引用共享，其余是构造期已解析好的值（不再有 `?? 缺省`）
-        const ctx = {
-            req,
-            res,
-            pathname,
-            method,
-            route,
-            app,
-            runner,
-            state,
-            maxBodyBytes,
-            maxConcurrentRuns,
-            sseMaxBufferedBytes,
-            exposeErrors,
-            startedAt,
-            metrics,
-        };
         try {
             // 鉴权缝：必须在读 body 之前（未通过即断开，body 一个字节都不收）。
             // 写成**否定条件**（「不是免鉴权组才过闸」）而不是「先 if (免鉴权组) { 一大段应答 }」：
             // 这样 `handler` 里只剩「谁被豁免」这一处判据可读，而被豁免者**回什么**在端点表里 ——
             // 豁免名单只有一份真源（`http-route.ts` 的 `isPreAuthRoute`）。
+            let principal;
             if (!isPreAuthRoute(route) && authenticate) {
                 try {
-                    await authenticate(req);
+                    // 返回值**不再是丢弃的**：它就是 `principal`，交给 `resolveRunOptions`。
+                    // 身份 → run 只该有这一条路（见 `HttpHandlerOptions.authenticate` 的注释）。
+                    principal = await authenticate(req);
                 }
                 catch (e) {
                     sendUnauthorized(req, res, e, exposeErrors);
                     return;
                 }
             }
+            // 一个请求一份 ctx：`state` 按引用共享，其余是构造期已解析好的值（不再有 `?? 缺省`）。
+            // 放在鉴权之后建，是因为 `principal` 是 ctx 的字段（身份随请求走，不存闭包）。
+            const ctx = {
+                req,
+                res,
+                pathname,
+                method,
+                route,
+                app,
+                runner,
+                state,
+                maxBodyBytes,
+                maxConcurrentRuns,
+                sseMaxBufferedBytes,
+                exposeErrors,
+                startedAt,
+                metrics,
+                principal,
+                resolveRunOptions,
+                authorizeTask,
+                resolveApprovalActor,
+                responseMode,
+                exposeTraceEvents,
+            };
             // 至此路由已定、鉴权已过 —— 剩下的全是「走到这条路上做什么」，在 http-endpoints.ts
             await handleRoute(route, ctx);
         }
         catch (e) {
+            // 端点（或 `resolveRunOptions` 钩子）抛 `HttpException` ⇒ 它自带状态码与响应体。
+            // 认领点刻意放在**宿主**这一层：端点模块不 import 宿主的值（依赖方向单向，
+            // 见 http-endpoints.ts 文件头），而钩子的错误语义属于宿主契约。
+            if (e instanceof HttpException) {
+                sendJson(res, e.status, e.body);
+                return;
+            }
             sendInternalError(res, e, exposeErrors);
         }
     };

package/dist/transport/http.js.map

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

package/dist/transport/run-call-options.js

@@ -31,6 +31,8 @@ export function buildRunCallOptions(input) {
             : client !== undefined
                 ? { client }
                 : {}),
+        // 恢复段预算按整任务累计：此前各段的 trace 已在挂起/终态出口折进 usageTotal。
+        ...(isResume && rec.usageTotal !== undefined ? { usageOffset: rec.usageTotal } : {}),
         // HITL 恢复段：审批决定随任务落库，重跑时原样进引擎（进程重启不丢）
         ...(rec.approvals !== undefined ? { approvals: rec.approvals } : {}),
         // 事件投入口（2026-09-28 ref-run-event-input）：挂起期间投递的事件随记录进引擎，由它在
@@ -69,6 +71,7 @@ export function adoptSucceededOutcome(rec, existing) {
     rec.status = 'succeeded';
     rec.runId = existing.runId;
     rec.result = existing.result;
+    rec.usageTotal = existing.usageTotal;
     rec.error = existing.error;
     rec.finishedAt = Date.now();
     return true;

package/dist/transport/run-call-options.js.map

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

package/dist/transport/run-options.d.ts

@@ -0,0 +1,98 @@
+import type { IncomingMessage } from 'node:http';
+import type { RunInvocationOptions } from '../engine/spec.js';
+/**
+ * Agentia —— HTTP 入口的 **run 选项可信边界**（spec §10 2026-11-04 run-options-trust-boundary）。
+ *
+ * ## 这个文件解决的两个不对称
+ *
+ * `POST /tasks` 的 body 里有一个 `options`，此前**整体透传**给 `runner.submit`（`...body.options`），
+ * 而 `options` 是引擎的**全部旋钮**（`RunInvocationOptions`：`blackboard` / `tools` /
+ * `fallbacks` / `maxIterations` / `priceOverrides` …）。后果不是"繁琐"，是**能冒充**：
+ *
+ * - `blackboard: { tenant: '别人的租户' }` ⇒ 工具方法体里读到的就是别人的租户。
+ *   usage-guide §6.6 的多租户配额配方第一步正是「用黑板存 tenant」—— 照抄即被绕过；
+ * - `tools: [...]` ⇒ 客户端能把整个工具菜单换掉；
+ * - `priceOverrides: { '<模型>': { in: 0, out: 0 } }` ⇒ 成本恒 0，`maxCostUsd` 静默失效。
+ *
+ * 另一头，`POST /run` **完全不收 options**（连 `traceContext` 都只认 header）—— 需要身份的那条
+ * 拿不到，拿得到的那条不可信。这就是那个不对称。
+ *
+ * ## 两半各自的职责
+ *
+ * | 谁 | 管什么 | 为什么 |
+ * |---|---|---|
+ * | `pickClientRunOptions` | **白名单**：客户端只能设这几个键 | 外部输入不配拥有引擎旋钮（与 `parseEventBody` 的「多一个字段即拒」同一条纪律） |
+ * | `ResolveRunOptionsHook` | **可信注入**：宿主按请求给的 `blackboard` / `labels` / 预算封顶 | 身份只能来自宿主（鉴权结果），不能来自 body |
+ *
+ * 客户端**仍然可以**设 `maxCostUsd` / `maxTotalTokens`（给自己这单设个花钱上限是合理诉求），
+ * 但合取时取**更严的那一个** —— 「上限」不能由不受信的一方放宽。这不是策略，是「上限」的
+ * 定义本身：能被叫价方抬高的上限不叫上限。
+ */
+/**
+ * 客户端可自填的键（`POST /tasks` 的 `body.options`）。
+ *
+ * 加键的判据：**这个键被客户端设错时，损失只落在他自己这一单上**。
+ * - `traceContext`：链路关联（他愿意把自己的请求挂到哪棵树上是他的事）；
+ * - `maxCostUsd` / `maxTotalTokens`：愿意花多少。
+ *
+ * 反例（永远不该进来）：`blackboard`（身份）/ `labels`（归因与配额）/
+ * `tools`（换菜单）/ `model` + `fallbacks`（替服务端选厂商与价目）/
+ * `priceOverrides`（改账本口径 ⇒ 让预算闸失效）/ `client` / `signal`（进程内对象）。
+ */
+export declare const CLIENT_RUN_OPTION_KEYS: readonly ['traceContext', 'maxCostUsd', 'maxTotalTokens'];
+export type ClientRunOptionKey = (typeof CLIENT_RUN_OPTION_KEYS)[number];
+/**
+ * 客户端能设的那几个选项的**类型面**（`TaskSubmitBody.options`）。
+ *
+ * 它刻意是 `Pick` 出来的窄类型而不是 `RunInvocationOptions`：后者会让「写 `blackboard`
+ * 能通过编译、到运行期才 400」—— 把一次编译期就能说清的事推到线上。
+ */
+export type ClientRunOptions = Pick<RunInvocationOptions, ClientRunOptionKey>;
+/**
+ * 宿主按请求注入的选项（`HttpHandlerOptions.resolveRunOptions` 的返回值）。
+ *
+ * 刻意**窄**：只放「客户端不该有能力决定、而宿主一定知道」的三样。
+ * 想调 `model` / `tools` 这类就说明它该在应用配置里，不该跟着某个用户走。
+ */
+export interface RunOptionOverrides {
+    /** 请求身份 / 租户等（**整体替换**客户端的同名值 —— 客户端本来就设不了它） */
+    blackboard?: RunInvocationOptions['blackboard'];
+    /** 归因标签（与客户端同名键**合并**，服务端键胜出） */
+    labels?: Record<string, string>;
+    /** 服务端封顶：与客户端值取**更严**者（防止客户端把上限抬高） */
+    maxCostUsd?: number;
+    /** 同 `maxCostUsd` */
+    maxTotalTokens?: number;
+}
+/**
+ * per-request run 选项的来源（宿主给、框架透传）。与 `authenticate` 配对：
+ * 后者的返回值作为 `principal` 传进来 —— 身份只走这一条，别去读 body。
+ *
+ * 抛 `HttpException` ⇒ 按其 `status` / `body` 回响应（校验失败想回 403 就抛它）；
+ * 抛别的错误 ⇒ 走 500 路径（与其它内部异常同一个出口）。
+ */
+export type ResolveRunOptionsHook = (req: IncomingMessage, info: {
+    route: 'run' | 'tasks';
+    principal: unknown;
+}) => RunOptionOverrides | undefined | Promise<RunOptionOverrides | undefined>;
+export type ClientRunOptionsResult = {
+    ok: true;
+    options: RunInvocationOptions;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * 校验并取出客户端选项。**未知键即拒**（不是静默丢弃）：一个拼错的 `maxCostUSD`
+ * 被悄悄忽略，使用方会以为花销已被封顶 —— 静默降级比 400 危险。
+ */
+export declare function pickClientRunOptions(raw: unknown): ClientRunOptionsResult;
+/**
+ * 把宿主注入的选项叠加到（已过白名单的）客户端选项上。
+ *
+ * 三条合并语义各不相同，各有理由：
+ * - `blackboard`：**整体替换** —— 它是身份载体，允许客户端键与宿主键"合并"就等于允许覆盖；
+ * - `labels`：**按键盘合并、宿主胜** —— 归因是多维度的，宿主只想补自己关心的维度；
+ * - 预算：**取更严者** —— 见文件头「上限的定义」。
+ */
+export declare function mergeRunOptions(client: RunInvocationOptions, overrides: RunOptionOverrides | undefined): RunInvocationOptions;

package/dist/transport/run-options.js

@@ -0,0 +1,121 @@
+/**
+ * Agentia —— HTTP 入口的 **run 选项可信边界**（spec §10 2026-11-04 run-options-trust-boundary）。
+ *
+ * ## 这个文件解决的两个不对称
+ *
+ * `POST /tasks` 的 body 里有一个 `options`，此前**整体透传**给 `runner.submit`（`...body.options`），
+ * 而 `options` 是引擎的**全部旋钮**（`RunInvocationOptions`：`blackboard` / `tools` /
+ * `fallbacks` / `maxIterations` / `priceOverrides` …）。后果不是"繁琐"，是**能冒充**：
+ *
+ * - `blackboard: { tenant: '别人的租户' }` ⇒ 工具方法体里读到的就是别人的租户。
+ *   usage-guide §6.6 的多租户配额配方第一步正是「用黑板存 tenant」—— 照抄即被绕过；
+ * - `tools: [...]` ⇒ 客户端能把整个工具菜单换掉；
+ * - `priceOverrides: { '<模型>': { in: 0, out: 0 } }` ⇒ 成本恒 0，`maxCostUsd` 静默失效。
+ *
+ * 另一头，`POST /run` **完全不收 options**（连 `traceContext` 都只认 header）—— 需要身份的那条
+ * 拿不到，拿得到的那条不可信。这就是那个不对称。
+ *
+ * ## 两半各自的职责
+ *
+ * | 谁 | 管什么 | 为什么 |
+ * |---|---|---|
+ * | `pickClientRunOptions` | **白名单**：客户端只能设这几个键 | 外部输入不配拥有引擎旋钮（与 `parseEventBody` 的「多一个字段即拒」同一条纪律） |
+ * | `ResolveRunOptionsHook` | **可信注入**：宿主按请求给的 `blackboard` / `labels` / 预算封顶 | 身份只能来自宿主（鉴权结果），不能来自 body |
+ *
+ * 客户端**仍然可以**设 `maxCostUsd` / `maxTotalTokens`（给自己这单设个花钱上限是合理诉求），
+ * 但合取时取**更严的那一个** —— 「上限」不能由不受信的一方放宽。这不是策略，是「上限」的
+ * 定义本身：能被叫价方抬高的上限不叫上限。
+ */
+/**
+ * 客户端可自填的键（`POST /tasks` 的 `body.options`）。
+ *
+ * 加键的判据：**这个键被客户端设错时，损失只落在他自己这一单上**。
+ * - `traceContext`：链路关联（他愿意把自己的请求挂到哪棵树上是他的事）；
+ * - `maxCostUsd` / `maxTotalTokens`：愿意花多少。
+ *
+ * 反例（永远不该进来）：`blackboard`（身份）/ `labels`（归因与配额）/
+ * `tools`（换菜单）/ `model` + `fallbacks`（替服务端选厂商与价目）/
+ * `priceOverrides`（改账本口径 ⇒ 让预算闸失效）/ `client` / `signal`（进程内对象）。
+ */
+export const CLIENT_RUN_OPTION_KEYS = ['traceContext', 'maxCostUsd', 'maxTotalTokens'];
+const ALLOWED = CLIENT_RUN_OPTION_KEYS.join(' / ');
+/** 是不是「有限、非负」的数（`NaN` / `Infinity` / 负数都不是合法上限） */
+function isLimit(v) {
+    return typeof v === 'number' && Number.isFinite(v) && v >= 0;
+}
+/**
+ * 校验并取出客户端选项。**未知键即拒**（不是静默丢弃）：一个拼错的 `maxCostUSD`
+ * 被悄悄忽略，使用方会以为花销已被封顶 —— 静默降级比 400 危险。
+ */
+export function pickClientRunOptions(raw) {
+    if (raw === undefined || raw === null)
+        return { ok: true, options: {} };
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        return { ok: false, error: 'options 必须是对象' };
+    }
+    const o = raw;
+    for (const key of Object.keys(o)) {
+        if (!CLIENT_RUN_OPTION_KEYS.includes(key)) {
+            return { ok: false, error: `options 不接受 "${key}"（可用：${ALLOWED}）` };
+        }
+    }
+    const options = {};
+    if (o.maxCostUsd !== undefined) {
+        if (!isLimit(o.maxCostUsd))
+            return { ok: false, error: 'options.maxCostUsd 必须是非负有限数' };
+        options.maxCostUsd = o.maxCostUsd;
+    }
+    if (o.maxTotalTokens !== undefined) {
+        if (!isLimit(o.maxTotalTokens)) {
+            return { ok: false, error: 'options.maxTotalTokens 必须是非负有限数' };
+        }
+        options.maxTotalTokens = o.maxTotalTokens;
+    }
+    if (o.traceContext !== undefined) {
+        const t = o.traceContext;
+        if (!t || typeof t !== 'object' || Array.isArray(t)) {
+            return { ok: false, error: 'options.traceContext 必须是 { traceId, spanId? }' };
+        }
+        const { traceId, spanId } = t;
+        if (typeof traceId !== 'string' || traceId === '') {
+            return { ok: false, error: 'options.traceContext.traceId 必须是非空字符串' };
+        }
+        if (spanId !== undefined && (typeof spanId !== 'string' || spanId === '')) {
+            return { ok: false, error: 'options.traceContext.spanId 必须是非空字符串' };
+        }
+        options.traceContext = { traceId, ...(spanId !== undefined ? { spanId } : {}) };
+    }
+    return { ok: true, options };
+}
+/** 两个上限取更严者（缺席即「这边没设」，另一边说了算） */
+function tighter(a, b) {
+    if (a === undefined)
+        return b;
+    if (b === undefined)
+        return a;
+    return Math.min(a, b);
+}
+/**
+ * 把宿主注入的选项叠加到（已过白名单的）客户端选项上。
+ *
+ * 三条合并语义各不相同，各有理由：
+ * - `blackboard`：**整体替换** —— 它是身份载体，允许客户端键与宿主键"合并"就等于允许覆盖；
+ * - `labels`：**按键盘合并、宿主胜** —— 归因是多维度的，宿主只想补自己关心的维度；
+ * - 预算：**取更严者** —— 见文件头「上限的定义」。
+ */
+export function mergeRunOptions(client, overrides) {
+    if (!overrides)
+        return client;
+    const maxCostUsd = tighter(client.maxCostUsd, overrides.maxCostUsd);
+    const maxTotalTokens = tighter(client.maxTotalTokens, overrides.maxTotalTokens);
+    return {
+        ...client,
+        ...(overrides.blackboard !== undefined ? { blackboard: overrides.blackboard } : {}),
+        ...(overrides.labels !== undefined
+            ? { labels: { ...(client.labels ?? {}), ...overrides.labels } }
+            : {}),
+        ...(maxCostUsd !== undefined ? { maxCostUsd } : {}),
+        ...(maxTotalTokens !== undefined ? { maxTotalTokens } : {}),
+    };
+}
+//# sourceMappingURL=run-options.js.map

package/dist/transport/run-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-options.js","sourceRoot":"","sources":["../../src/transport/run-options.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,cAAc,EAAE,YAAY,EAAE,gBAAgB,CAAU,CAAC;AA6ChG,MAAM,OAAO,GAAG,sBAAsB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAEnD,mDAAmD;AACnD,SAAS,OAAO,CAAC,CAAU;IACzB,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC/D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAY;IAC/C,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;IACxE,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAClD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,eAAe,EAAE,CAAC;IAC/C,CAAC;IACD,MAAM,CAAC,GAAG,GAA8B,CAAC;IACzC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QACjC,IAAI,CAAE,sBAA4C,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YACjE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,gBAAgB,GAAG,QAAQ,OAAO,GAAG,EAAE,CAAC;QACrE,CAAC;IACH,CAAC;IACD,MAAM,OAAO,GAAyB,EAAE,CAAC;IACzC,IAAI,CAAC,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;QAC/B,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,6BAA6B,EAAE,CAAC;QACvF,OAAO,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CAAC;IACpC,CAAC;IACD,IAAI,CAAC,CAAC,cAAc,KAAK,SAAS,EAAE,CAAC;QACnC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,cAAc,CAAC,EAAE,CAAC;YAC/B,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,iCAAiC,EAAE,CAAC;QACjE,CAAC;QACD,OAAO,CAAC,cAAc,GAAG,CAAC,CAAC,cAAc,CAAC;IAC5C,CAAC;IACD,IAAI,CAAC,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QACjC,MAAM,CAAC,GAAG,CAAC,CAAC,YAAY,CAAC;QACzB,IAAI,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;YACpD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,+CAA+C,EAAE,CAAC;QAC/E,CAAC;QACD,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,CAA4C,CAAC;QACzE,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,EAAE,EAAE,CAAC;YAClD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,uCAAuC,EAAE,CAAC;QACvE,CAAC;QACD,IAAI,MAAM,KAAK,SAAS,IAAI,CAAC,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,EAAE,CAAC,EAAE,CAAC;YAC1E,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,sCAAsC,EAAE,CAAC;QACtE,CAAC;QACD,OAAO,CAAC,YAAY,GAAG,EAAE,OAAO,EAAE,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;IAClF,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AAC/B,CAAC;AAED,iCAAiC;AACjC,SAAS,OAAO,CAAC,CAAqB,EAAE,CAAqB;IAC3D,IAAI,CAAC,KAAK,SAAS;QAAE,OAAO,CAAC,CAAC;IAC9B,IAAI,CAAC,KAAK,SAAS;QAAE,OAAO,CAAC,CAAC;IAC9B,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AACxB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAC7B,MAA4B,EAC5B,SAAyC;IAEzC,IAAI,CAAC,SAAS;QAAE,OAAO,MAAM,CAAC;IAC9B,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,SAAS,CAAC,UAAU,CAAC,CAAC;IACpE,MAAM,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,cAAc,EAAE,SAAS,CAAC,cAAc,CAAC,CAAC;IAChF,OAAO;QACL,GAAG,MAAM;QACT,GAAG,CAAC,SAAS,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,SAAS,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnF,GAAG,CAAC,SAAS,CAAC,MAAM,KAAK,SAAS;YAChC,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,GAAG,CAAC,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,GAAG,SAAS,CAAC,MAAM,EAAE,EAAE;YAC/D,CAAC,CAAC,EAAE,CAAC;QACP,GAAG,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnD,GAAG,CAAC,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC5D,CAAC;AACJ,CAAC"}

package/dist/transport/run-outcome.js

@@ -44,6 +44,9 @@ export function applySuspendedOutcome(rec, result, suspendedMessages, ctx) {
     const snapshot = !ctx.isResume && rec.spec.options?.sessionId !== undefined && ctx.hasSessionStore
         ? rec.spec.messages
         : undefined;
+    // 快照同时进记录：内存 Map 只是本进程快路，重启后由它接着补写会话。
+    if (snapshot !== undefined)
+        rec.sessionInput = snapshot;
     // 扩展后的消息历史（末尾是含未决 tool_use 的 assistant 消息）与待决清单、挂起时刻一起落库
     // —— approve / 惰性超时 / 重启后都靠它们。
     rec.spec = { ...rec.spec, messages: suspendedMessages };

package/dist/transport/run-outcome.js.map

@@ -1 +1 @@
-{"version":3,"file":"run-outcome.js","sourceRoot":"","sources":["../../src/transport/run-outcome.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AA6CjD;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,KAAgB,EAChB,GAAe;IAEf,IAAI,CAAC;QACH,OAAO,CAAC,MAAM,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,GAAG,CAAC;IAC9C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAeD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,qBAAqB,CACnC,GAAe,EACf,MAAsB,EACtB,iBAAiC,EACjC,GAA4B;IAE5B,4DAA4D;IAC5D,mDAAmD;IACnD,GAAG,CAAC,MAAM,GAAG,WAAW,CAAC;IACzB,kEAAkE;IAClE,yDAAyD;IACzD,oDAAoD;IACpD,qCAAqC;IACrC,MAAM,QAAQ,GACZ,CAAC,GAAG,CAAC,QAAQ,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,SAAS,KAAK,SAAS,IAAI,GAAG,CAAC,eAAe;QAC/E,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ;QACnB,CAAC,CAAC,SAAS,CAAC;IAChB,yDAAyD;IACzD,+BAA+B;IAC/B,GAAG,CAAC,IAAI,GAAG,EAAE,GAAG,GAAG,CAAC,IAAI,EAAE,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IACxD,GAAG,CAAC,gBAAgB,GAAG,MAAM,CAAC,gBAAgB,CAAC;IAC/C,GAAG,CAAC,cAAc,GAAG,GAAG,CAAC,GAAG,CAAC;IAC7B,wDAAwD;IACxD,eAAe;IACf,GAAG,CAAC,eAAe,GAAG,MAAM,CAAC,eAAe,CAAC;IAC7C,mCAAmC;IACnC,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAC3B,+DAA+D;IAC/D,iDAAiD;IACjD,0CAA0C;IAC1C,sCAAsC;IACtC,IAAI,MAAM,CAAC,eAAe;QAAE,GAAG,CAAC,aAAa,GAAG,SAAS,CAAC;IAC1D,OAAO,QAAQ,CAAC;AAClB,CAAC;AAaD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,oBAAoB,CAClC,GAAe,EACf,GAAe,EACf,GAA2B;IAE3B,gEAAgE;IAChE,6BAA6B;IAC7B,GAAG,CAAC,MAAM,GAAG,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC;IAC1D,yDAAyD;IACzD,2DAA2D;IAC3D,iBAAiB;IACjB,IAAI,GAAG,CAAC,SAAS,IAAI,GAAG,CAAC,KAAK,KAAK,SAAS;QAAE,GAAG,CAAC,KAAK,GAAG,YAAY,EAAE,CAAC;IACzE,mCAAmC;IACnC,GAAG,CAAC,gBAAgB,GAAG,SAAS,CAAC;IACjC,GAAG,CAAC,cAAc,GAAG,SAAS,CAAC;IAC/B,GAAG,CAAC,eAAe,GAAG,SAAS,CAAC;IAChC,GAAG,CAAC,MAAM,GAAG,SAAS,CAAC;IACvB,kDAAkD;IAClD,kDAAkD;IAClD,mDAAmD;IACnD,2DAA2D;IAC3D,uDAAuD;IACvD,wDAAwD;IACxD,4BAA4B;IAC5B,GAAG,CAAC,aAAa,GAAG,SAAS,CAAC;IAC9B,OAAO,GAAG,CAAC,QAAQ,IAAI,GAAG,CAAC,GAAG,CAAC,MAAM,KAAK,WAAW,CAAC;AACxD,CAAC"}
+{"version":3,"file":"run-outcome.js","sourceRoot":"","sources":["../../src/transport/run-outcome.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AA6CjD;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,KAAgB,EAChB,GAAe;IAEf,IAAI,CAAC;QACH,OAAO,CAAC,MAAM,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,GAAG,CAAC;IAC9C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAeD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,qBAAqB,CACnC,GAAe,EACf,MAAsB,EACtB,iBAAiC,EACjC,GAA4B;IAE5B,4DAA4D;IAC5D,mDAAmD;IACnD,GAAG,CAAC,MAAM,GAAG,WAAW,CAAC;IACzB,kEAAkE;IAClE,yDAAyD;IACzD,oDAAoD;IACpD,qCAAqC;IACrC,MAAM,QAAQ,GACZ,CAAC,GAAG,CAAC,QAAQ,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,SAAS,KAAK,SAAS,IAAI,GAAG,CAAC,eAAe;QAC/E,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ;QACnB,CAAC,CAAC,SAAS,CAAC;IAChB,sCAAsC;IACtC,IAAI,QAAQ,KAAK,SAAS;QAAE,GAAG,CAAC,YAAY,GAAG,QAAQ,CAAC;IACxD,yDAAyD;IACzD,+BAA+B;IAC/B,GAAG,CAAC,IAAI,GAAG,EAAE,GAAG,GAAG,CAAC,IAAI,EAAE,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IACxD,GAAG,CAAC,gBAAgB,GAAG,MAAM,CAAC,gBAAgB,CAAC;IAC/C,GAAG,CAAC,cAAc,GAAG,GAAG,CAAC,GAAG,CAAC;IAC7B,wDAAwD;IACxD,eAAe;IACf,GAAG,CAAC,eAAe,GAAG,MAAM,CAAC,eAAe,CAAC;IAC7C,mCAAmC;IACnC,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAC3B,+DAA+D;IAC/D,iDAAiD;IACjD,0CAA0C;IAC1C,sCAAsC;IACtC,IAAI,MAAM,CAAC,eAAe;QAAE,GAAG,CAAC,aAAa,GAAG,SAAS,CAAC;IAC1D,OAAO,QAAQ,CAAC;AAClB,CAAC;AAaD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,oBAAoB,CAClC,GAAe,EACf,GAAe,EACf,GAA2B;IAE3B,gEAAgE;IAChE,6BAA6B;IAC7B,GAAG,CAAC,MAAM,GAAG,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC;IAC1D,yDAAyD;IACzD,2DAA2D;IAC3D,iBAAiB;IACjB,IAAI,GAAG,CAAC,SAAS,IAAI,GAAG,CAAC,KAAK,KAAK,SAAS;QAAE,GAAG,CAAC,KAAK,GAAG,YAAY,EAAE,CAAC;IACzE,mCAAmC;IACnC,GAAG,CAAC,gBAAgB,GAAG,SAAS,CAAC;IACjC,GAAG,CAAC,cAAc,GAAG,SAAS,CAAC;IAC/B,GAAG,CAAC,eAAe,GAAG,SAAS,CAAC;IAChC,GAAG,CAAC,MAAM,GAAG,SAAS,CAAC;IACvB,kDAAkD;IAClD,kDAAkD;IAClD,mDAAmD;IACnD,2DAA2D;IAC3D,uDAAuD;IACvD,wDAAwD;IACxD,4BAA4B;IAC5B,GAAG,CAAC,aAAa,GAAG,SAAS,CAAC;IAC9B,OAAO,GAAG,CAAC,QAAQ,IAAI,GAAG,CAAC,GAAG,CAAC,MAAM,KAAK,WAAW,CAAC;AACxD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@migor/agentia",
-  "version": "0.10.4",
+  "version": "0.10.5",
   "description": "Declarative agent service framework for TypeScript: decorators + DI declare four capability kinds, durable runs, and per-run traces, cost and metrics. Zero runtime dependencies.",
   "type": "module",
   "main": "dist/index.js",