@migor/agentia 0.2.1 → 0.3.0

package/dist/toolkit/skill.js

@@ -1,7 +1,8 @@
-import { scanDecoratedMethods, unitName } from './collect.js';
+import { assertMethodTarget, scanDecoratedMethods, capabilityName } from './collect.js';
+import { isSuccessStopReason } from '../engine/types.js';
 import { runAgentScoped } from '../engine/loop.js';
 import { classifyError } from '../engine/errors.js';
-import { SystemPrompt } from '../run/systemPrompt.js';
+import { SystemPrompt } from '../runtime/systemPrompt.js';
 /** 方法函数 → spec（与 @Tool 同款 WeakMap 注册表，零反射） */
 const skillSpecs = new WeakMap();
 const EMPTY_SCHEMA = {
@@ -11,48 +12,49 @@ const EMPTY_SCHEMA = {
 };
 /** 方法装饰器：登记 skill spec。被装饰方法体由运行时以 (input, skillCtx) 调用。 */
 export function Skill(spec) {
-    return function (value, context) {
-        if (context.kind !== 'method') {
-            throw new Error(`@Skill 只能修饰类方法，收到 kind=${String(context.kind)}`);
-        }
+    return (value, context) => {
+        assertMethodTarget(context, '@Skill');
         skillSpecs.set(value, spec);
     };
 }
-/** 把容器实例上所有 @Skill 方法收集成 SkillUnit[]（沿原型链）。 */
+/** 把容器实例上所有 @Skill 方法收集成 SkillCapability[]（沿原型链）。 */
 export function collectSkills(instance) {
-    return scanDecoratedMethods(instance, skillSpecs).map(({ key, fn, spec }) => ({
-        name: unitName(spec, key, '@Skill'),
+    // 动态查表而非捕获 fn：子类「未装饰地 override」时 spec 继承自父类，
+    // 实现必须取实例上的（与 @Tool 的 run 同款），否则子类 override 被静默绕过。
+    const inst = instance;
+    return scanDecoratedMethods(instance, skillSpecs).map(({ key, spec }) => ({
+        name: capabilityName(spec, key, '@Skill'),
         description: spec.description,
         inputSchema: spec.schema ?? EMPTY_SCHEMA,
         spec,
-        invoke: (input, skillCtx) => Reflect.apply(fn, instance, [input, skillCtx]),
+        invoke: (input, skillCtx) => Reflect.apply(inst[key], instance, [input, skillCtx]),
     }));
 }
 /**
- * 把 SkillUnit 变成主 agent 菜单里的 AgentTool。
+ * 把 SkillCapability 变成主 agent 菜单里的 AgentTool。
  * run(input, ctx) 需要 ToolRunContext（engine 调用时必有）；手动直调会抛错提示。
- * 开 `unit` span → 构造 SkillContext（llm 闭包挂 unit 下）→ 执行方法体 →
- * 返回值字符串化交回；抛错关 unit error 后重抛（引擎包成 is_error，不中断 run）。
+ * 开 `capability` span → 构造 SkillContext（llm 闭包挂 capability 下）→ 执行方法体 →
+ * 返回值字符串化交回；抛错关 capability error 后重抛（引擎包成 is_error，不中断 run）。
  */
-export function skillToTool(unit, resolveTools) {
-    const { name, spec } = unit;
+export function skillToTool(capability, resolveTools) {
+    const { name, spec } = capability;
     return {
         name,
         description: spec.description,
-        inputSchema: unit.inputSchema,
+        inputSchema: capability.inputSchema,
         run: async (input, ctx) => {
             if (!ctx) {
                 throw new Error(`skill "${name}" 只能在主 agent 运行中被调用（engine 会注入 ToolRunContext）`);
             }
             const recorder = ctx.recorder;
-            const unitId = recorder.begin('unit', name, ctx.parentSpanId);
-            recorder.setAttribute(unitId, 'skill', name);
+            const capabilityId = recorder.begin('capability', name, ctx.parentSpanId);
+            recorder.setAttribute(capabilityId, 'skill', name);
             let closed = false;
             const close = (patch) => {
                 if (closed)
                     return;
                 closed = true;
-                recorder.end(unitId, patch);
+                recorder.end(capabilityId, patch);
             };
             const skillCtx = {
                 model: spec.model,
@@ -63,9 +65,7 @@ export function skillToTool(unit, resolveTools) {
                     if (messages.length === 0) {
                         throw new Error(`skill "${name}".llm 需要 prompt 或 messages`);
                     }
-                    const system = opts.system instanceof SystemPrompt
-                        ? opts.system.build({ cache: true })
-                        : opts.system;
+                    const system = opts.system instanceof SystemPrompt ? opts.system.build({ cache: true }) : opts.system;
                     const loop = await runAgentScoped({
                         client: ctx.client,
                         model: opts.model ?? spec.model,
@@ -75,22 +75,29 @@ export function skillToTool(unit, resolveTools) {
                         messages,
                         tools: spec.tools?.length ? resolveTools() : [],
                         recorder,
-                        parentSpanId: unitId,
+                        parentSpanId: capabilityId,
+                        signal: ctx.signal,
+                        // 价格覆盖透传（F1）：子循环用同一模型也要能算成本
+                        priceOverrides: ctx.priceOverrides,
                     });
-                    if (loop.stopReason !== 'end_turn') {
+                    if (!isSuccessStopReason(loop.stopReason)) {
                         const report = `skill "${name}".llm ${loop.stopReason}: ${(loop.finalText || loop.error?.message || '').slice(0, 2000)}`;
                         const error = loop.error ?? {
                             type: 'agent_error',
                             message: report,
                             retryable: true,
                         };
+                        // 先把丰富错误挂到 capability span（loop.error 的 type/retryable 比新造的
+                        // Error 信息量大），再抛出走外层 catch 的通用收尾 —— 外层 close 幂等，
+                        // 不会覆盖这里写的 error（与 subagent.ts 同款）。
+                        close({ status: 'error', error });
                         throw new Error(report);
                     }
                     return { text: loop.finalText, stopReason: loop.stopReason };
                 },
             };
             try {
-                const out = await unit.invoke(input ?? {}, skillCtx);
+                const out = await capability.invoke(input ?? {}, skillCtx);
                 close({ status: 'ok' });
                 return out;
             }

package/dist/toolkit/skill.js.map

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

package/dist/toolkit/subagent.d.ts

@@ -1,8 +1,9 @@
+import type { CapabilityDecoratorContext } from './collect.js';
 import type { AgentTool, JsonSchema } from '../core/tool.js';
 import type { SystemParam } from '../engine/types.js';
-import { SystemPrompt } from '../run/systemPrompt.js';
+import { SystemPrompt } from '../runtime/systemPrompt.js';
 /**
- * Agentia —— 子 agent 单元（spec §3/§5：独立 agent 循环 + 裁剪上下文 + 隔离报告）。
+ * Agentia —— 子 agent 能力（spec §3/§5：独立 agent 循环 + 裁剪上下文 + 隔离报告）。
  *
  * 语义（spec §5）：
  * - 子 agent = **完整独立循环**：自己的 system（role）、自己的工具、自己的 model；
@@ -11,7 +12,7 @@ import { SystemPrompt } from '../run/systemPrompt.js';
  * - **隔离报告**：它的中间往返全部不进主上下文，唯一回流主 agent 的是
  *   stop_reason=end_turn 的最终文本 —— 以 tool_result 交回（非 end_turn 则抛错 → is_error）。
  *
- * trace：子 agent 是主 trace 里的一个 `unit` span（挂在发起它的 llm.turn 下），
+ * trace：子 agent 是主 trace 里的一个 `capability` span（挂在发起它的 llm.turn 下），
  * 其内部 llm.turn 递归成它的子孙 —— 见 engine/loop.ts 的 runAgentScoped。
  */
 export interface SubAgentSpec {
@@ -39,22 +40,19 @@ export interface SubAgentSpec {
      */
     resultSchema?: JsonSchema;
 }
-export interface SubAgentUnit {
+export interface SubAgentCapability {
     name: string;
     description: string;
     inputSchema: JsonSchema;
     spec: SubAgentSpec;
 }
 /** 方法装饰器：登记子 agent spec。被装饰方法体不执行 —— 运行时拉起独立循环。 */
-export declare function SubAgent(spec: SubAgentSpec): (value: Function, context: {
-    kind: string;
-    name: string | symbol;
-}) => void;
-/** 把容器实例上所有 @SubAgent 方法收集成 SubAgentUnit[]（沿原型链）。 */
-export declare function collectSubAgents(instance: object): SubAgentUnit[];
+export declare function SubAgent(spec: SubAgentSpec): (value: Function, context: CapabilityDecoratorContext) => void;
+/** 把容器实例上所有 @SubAgent 方法收集成 SubAgentCapability[]（沿原型链）。 */
+export declare function collectSubAgents(instance: object): SubAgentCapability[];
 /**
- * 把 SubAgentUnit 变成主 agent 菜单里的 AgentTool。
+ * 把 SubAgentCapability 变成主 agent 菜单里的 AgentTool。
  * run(input, ctx) 需要 ToolRunContext（engine 调用时必有）；手动直调会抛错提示。
  * tools token 列表 → resolveTools() 由装配层给出（该 token 的 @Tool 菜单）。
  */
-export declare function subagentToTool(unit: SubAgentUnit, resolveTools: () => AgentTool[]): AgentTool;
+export declare function subagentToTool(capability: SubAgentCapability, resolveTools: () => AgentTool[]): AgentTool;

package/dist/toolkit/subagent.js

@@ -1,22 +1,21 @@
-import { scanDecoratedMethods, unitName } from './collect.js';
+import { assertMethodTarget, scanDecoratedMethods, capabilityName } from './collect.js';
+import { isSuccessStopReason } from '../engine/types.js';
 import { runAgentScoped } from '../engine/loop.js';
 import { classifyError } from '../engine/errors.js';
-import { SystemPrompt } from '../run/systemPrompt.js';
+import { SystemPrompt } from '../runtime/systemPrompt.js';
 /** 方法函数 → spec（与 @Tool 同款 WeakMap 注册表，零反射） */
 const subAgentSpecs = new WeakMap();
 /** 方法装饰器：登记子 agent spec。被装饰方法体不执行 —— 运行时拉起独立循环。 */
 export function SubAgent(spec) {
-    return function (value, context) {
-        if (context.kind !== 'method') {
-            throw new Error(`@SubAgent 只能修饰类方法，收到 kind=${String(context.kind)}`);
-        }
+    return (value, context) => {
+        assertMethodTarget(context, '@SubAgent');
         subAgentSpecs.set(value, spec);
     };
 }
-/** 把容器实例上所有 @SubAgent 方法收集成 SubAgentUnit[]（沿原型链）。 */
+/** 把容器实例上所有 @SubAgent 方法收集成 SubAgentCapability[]（沿原型链）。 */
 export function collectSubAgents(instance) {
     return scanDecoratedMethods(instance, subAgentSpecs).map(({ key, spec }) => ({
-        name: unitName(spec, key, '@SubAgent'),
+        name: capabilityName(spec, key, '@SubAgent'),
         description: spec.description,
         inputSchema: spec.schema,
         spec,
@@ -34,29 +33,29 @@ async function resolveSubSystem(spec, task) {
     return `${spec}\n\n${REPORT_HINT}`;
 }
 /**
- * 把 SubAgentUnit 变成主 agent 菜单里的 AgentTool。
+ * 把 SubAgentCapability 变成主 agent 菜单里的 AgentTool。
  * run(input, ctx) 需要 ToolRunContext（engine 调用时必有）；手动直调会抛错提示。
  * tools token 列表 → resolveTools() 由装配层给出（该 token 的 @Tool 菜单）。
  */
-export function subagentToTool(unit, resolveTools) {
-    const { name, spec } = unit;
+export function subagentToTool(capability, resolveTools) {
+    const { name, spec } = capability;
     return {
-        name: unit.name,
-        description: unit.description,
-        inputSchema: unit.inputSchema,
+        name: capability.name,
+        description: capability.description,
+        inputSchema: capability.inputSchema,
         run: async (input, ctx) => {
             if (!ctx) {
                 throw new Error(`subagent "${name}" 只能在主 agent 运行中被调用（engine 会注入 ToolRunContext）`);
             }
             const recorder = ctx.recorder;
-            const unitId = recorder.begin('unit', name, ctx.parentSpanId);
-            recorder.setAttribute(unitId, 'subagent', name);
+            const capabilityId = recorder.begin('capability', name, ctx.parentSpanId);
+            recorder.setAttribute(capabilityId, 'subagent', name);
             let closed = false;
             const close = (patch) => {
                 if (closed)
                     return;
                 closed = true;
-                recorder.end(unitId, patch);
+                recorder.end(capabilityId, patch);
             };
             try {
                 const raw = input ?? {};
@@ -72,11 +71,14 @@ export function subagentToTool(unit, resolveTools) {
                     messages: [{ role: 'user', content: JSON.stringify(task) }],
                     tools,
                     recorder,
-                    parentSpanId: unitId,
+                    parentSpanId: capabilityId,
+                    signal: ctx.signal,
                     resultSchema: spec.resultSchema,
+                    // 价格覆盖透传（F1）：子 agent 用同一模型也要能算成本
+                    priceOverrides: ctx.priceOverrides,
                 });
-                recorder.setAttribute(unitId, 'stop_reason', loop.stopReason);
-                if (loop.stopReason === 'end_turn') {
+                recorder.setAttribute(capabilityId, 'stop_reason', loop.stopReason);
+                if (isSuccessStopReason(loop.stopReason)) {
                     close({ status: 'ok' });
                     // 隔离报告：默认只回最终文本。子 agent 提交了结构化结果（resultSchema +
                     // submit_result 校验通过）时，连同报告以结构化 tool_result 交回 —— engine 会把
@@ -98,7 +100,7 @@ export function subagentToTool(unit, resolveTools) {
                 throw new Error(report);
             }
             catch (e) {
-                // runAgentScoped 抛出的请求级异常（此前 unit 未关）在此兜底标记
+                // runAgentScoped 抛出的请求级异常（此前 capability 未关）在此兜底标记
                 close({ status: 'error', error: classifyError(e) });
                 throw e;
             }

package/dist/toolkit/subagent.js.map

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

package/dist/toolkit/tool.d.ts

@@ -1,4 +1,5 @@
-import type { AgentTool, JsonSchema } from '../core/tool.js';
+import type { AgentTool, JsonSchema, SchemaInput } from '../core/tool.js';
+import type { CapabilityDecoratorContext } from './collect.js';
 /**
  * Agentia —— 声明式工具层（spec §4：标准装饰器 + 显式 DI，无 param 反射）。
  *
@@ -12,25 +13,32 @@ import type { AgentTool, JsonSchema } from '../core/tool.js';
  * 与 tsgo/esbuild 均兼容。当前 run 作用域经 AsyncLocalStorage 传播，
  * 方法体内可随时 `RunContext.current()` 读 blackboard/runId。
  */
-export interface ToolSpec {
+export interface ToolSpec<S extends JsonSchema = JsonSchema> {
     /** 模型可见工具名；缺省取被装饰方法名 */
     name?: string;
     description: string;
-    /** input_schema：v1 用裸 JSON Schema（对应 engine/core 的 JsonSchema） */
-    schema: JsonSchema;
-    /** strict 参数校验：需 additionalProperties:false + required 齐全 */
+    /**
+     * input_schema：v1 用裸 JSON Schema（对应 engine/core 的 JsonSchema）。
+     *
+     * 传 `fromZod<T>(...)`（TypedSchema<T>）时，被装饰方法的**入参类型会被自动校验**：
+     * 签名与 T 不一致直接编译期报错（不用手写 `@Tool<I, O>` 泛型）。
+     * 传裸 JsonSchema 时回落 any —— 不校验（旧行为）。
+     */
+    schema: S;
+    /** strict 参数校验（透传给 Anthropic 的 strict 模式） */
     strict?: boolean;
 }
 /**
  * 方法装饰器：登记 spec。被装饰方法入参即结构化 tool input，
  * 返回值（或 Promise）即 tool_result。抛错由 engine 包成 is_error，不中断 run。
  *
- * 泛型 <I, O> 可把方法签名与编译期类型绑定（`@Tool<{city:string}, string>({...})`），
- * 挡住签名笔误；缺省 any 保持宽松。schema 与 I 的一致性仍由开发者保证（已知边界）。
+ * 类型检查由 **schema 驱动**：
+ * - `schema: fromZod<T>(…)`（TypedSchema<T>）→ 方法入参必须是 `T`，签名与 schema
+ *   不一致直接编译期报错 —— schema 即单一事实来源，不用两处双写；
+ * - `schema: {…}`（裸 JsonSchema）→ 入参回落 `any`，不校验（宽松旧行为）。
+ *
+ * 第二个泛型 `O` 用于显式约束返回值（缺省 `any`，不校验）。
  */
-export declare function Tool<I = any, O = any>(spec: ToolSpec): (value: (input: I) => O | Promise<O>, context: {
-    kind: string;
-    name: string | symbol;
-}) => void;
+export declare function Tool<S extends JsonSchema = JsonSchema, O = any>(spec: ToolSpec<S>): (value: (input: SchemaInput<S>) => O | Promise<O>, context: CapabilityDecoratorContext) => void;
 /** 把容器实例上所有 @Tool 方法收集成 AgentTool[]（沿原型链，含继承的父类工具）。 */
 export declare function collectTools(instance: object): AgentTool[];

package/dist/toolkit/tool.js

@@ -1,18 +1,21 @@
-import { scanDecoratedMethods, unitName } from './collect.js';
+import { assertMethodTarget, scanDecoratedMethods, capabilityName } from './collect.js';
 /** 方法函数 → spec。WeakMap 不阻碍 GC，也不要求 globalThis 注册表。 */
 const toolSpecs = new WeakMap();
 /**
  * 方法装饰器：登记 spec。被装饰方法入参即结构化 tool input，
  * 返回值（或 Promise）即 tool_result。抛错由 engine 包成 is_error，不中断 run。
  *
- * 泛型 <I, O> 可把方法签名与编译期类型绑定（`@Tool<{city:string}, string>({...})`），
- * 挡住签名笔误；缺省 any 保持宽松。schema 与 I 的一致性仍由开发者保证（已知边界）。
+ * 类型检查由 **schema 驱动**：
+ * - `schema: fromZod<T>(…)`（TypedSchema<T>）→ 方法入参必须是 `T`，签名与 schema
+ *   不一致直接编译期报错 —— schema 即单一事实来源，不用两处双写；
+ * - `schema: {…}`（裸 JsonSchema）→ 入参回落 `any`，不校验（宽松旧行为）。
+ *
+ * 第二个泛型 `O` 用于显式约束返回值（缺省 `any`，不校验）。
  */
 export function Tool(spec) {
-    return function (value, context) {
-        if (context.kind !== 'method') {
-            throw new Error(`@Tool 只能修饰类方法，收到 kind=${String(context.kind)}`);
-        }
+    return (value, context) => {
+        assertMethodTarget(context, '@Tool');
+        // spec 的 schema 在类型上更精确（S），登记表按擦除后的形态存（与 collect 一致）
         toolSpecs.set(value, spec);
     };
 }
@@ -22,7 +25,7 @@ export function collectTools(instance) {
 }
 function buildTool(instance, key, spec) {
     return {
-        name: unitName(spec, key, '@Tool'),
+        name: capabilityName(spec, key, '@Tool'),
         description: spec.description,
         inputSchema: spec.schema,
         ...(spec.strict ? { strict: true } : {}),

package/dist/toolkit/tool.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool.js","sourceRoot":"","sources":["../../src/toolkit/tool.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAyB9D,sDAAsD;AACtD,MAAM,SAAS,GAAG,IAAI,OAAO,EAAsB,CAAC;AAEpD;;;;;;GAMG;AACH,MAAM,UAAU,IAAI,CAAmB,IAAc;IACnD,OAAO,UACL,KAAmC,EACnC,OAAgD;QAEhD,IAAI,OAAO,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC9B,MAAM,IAAI,KAAK,CAAC,yBAAyB,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACnE,CAAC;QACD,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAC7B,CAAC,CAAC;AACJ,CAAC;AAED,uDAAuD;AACvD,MAAM,UAAU,YAAY,CAAC,QAAgB;IAC3C,OAAO,oBAAoB,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,EAAE,CACrE,SAAS,CAAC,QAAQ,EAAE,GAAG,EAAE,IAAI,CAAC,CAC/B,CAAC;AACJ,CAAC;AAED,SAAS,SAAS,CAAC,QAAgB,EAAE,GAAoB,EAAE,IAAc;IACvE,OAAO;QACL,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,CAAC;QAClC,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,WAAW,EAAE,IAAI,CAAC,MAAM;QACxB,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACxC,GAAG,EAAE,CAAC,KAAc,EAAE,EAAE,CACtB,OAAO,CAAC,KAAK,CACV,QAAqE,CAAC,GAAG,CAAC,EAC3E,QAAQ,EACR,CAAC,KAAK,CAAC,CACR;KACJ,CAAC;AACJ,CAAC"}
+{"version":3,"file":"tool.js","sourceRoot":"","sources":["../../src/toolkit/tool.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAgCxF,sDAAsD;AACtD,MAAM,SAAS,GAAG,IAAI,OAAO,EAAsB,CAAC;AAEpD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,IAAI,CAA6C,IAAiB;IAChF,OAAO,CACL,KAAgD,EAChD,OAAmC,EAC7B,EAAE;QACR,kBAAkB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACrC,qDAAqD;QACrD,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,IAAgB,CAAC,CAAC;IACzC,CAAC,CAAC;AACJ,CAAC;AAED,uDAAuD;AACvD,MAAM,UAAU,YAAY,CAAC,QAAgB;IAC3C,OAAO,oBAAoB,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,EAAE,CACrE,SAAS,CAAC,QAAQ,EAAE,GAAG,EAAE,IAAI,CAAC,CAC/B,CAAC;AACJ,CAAC;AAED,SAAS,SAAS,CAAC,QAAgB,EAAE,GAAoB,EAAE,IAAc;IACvE,OAAO;QACL,IAAI,EAAE,cAAc,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,CAAC;QACxC,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,WAAW,EAAE,IAAI,CAAC,MAAM;QACxB,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACxC,GAAG,EAAE,CAAC,KAAc,EAAE,EAAE,CACtB,OAAO,CAAC,KAAK,CACV,QAAqE,CAAC,GAAG,CAAC,EAC3E,QAAQ,EACR,CAAC,KAAK,CAAC,CACR;KACJ,CAAC;AACJ,CAAC"}

package/dist/toolkit/zod.d.ts

@@ -1,4 +1,4 @@
-import type { JsonSchema } from '../core/tool.js';
+import type { JsonSchema, TypedSchema } from '../core/tool.js';
 /**
  * Agentia —— zod 可选接入（R2，duck-typed，框架永不 import zod）。
  *
@@ -14,7 +14,8 @@ import type { JsonSchema } from '../core/tool.js';
  * class WeatherTools {
  *   @Tool({
  *     description: '查天气',
- *     schema: fromZod(z.toJSONSchema(Weather) as JsonSchema, Weather),
+ *     // 显式给出结果类型 → 方法入参必须与之一致（不一致直接编译期报错）
+ *     schema: fromZod<z.infer<typeof Weather>>(z.toJSONSchema(Weather) as JsonSchema, Weather),
  *   })
  *   get(input: { city: string; days: number }) { ... }
  * }
@@ -23,4 +24,4 @@ import type { JsonSchema } from '../core/tool.js';
  * @param jsonSchema 由 zod 推导的 JSON Schema（发给模型 / 走 JSON Schema 子集校验）
  * @param zod zod schema 本体（只需带 safeParse），其校验结果优先于 JSON Schema 子集
  */
-export declare function fromZod(jsonSchema: JsonSchema, zod: unknown): JsonSchema;
+export declare function fromZod<T = unknown>(jsonSchema: JsonSchema, zod: unknown): TypedSchema<T>;

package/dist/toolkit/zod.js

@@ -13,7 +13,8 @@
  * class WeatherTools {
  *   @Tool({
  *     description: '查天气',
- *     schema: fromZod(z.toJSONSchema(Weather) as JsonSchema, Weather),
+ *     // 显式给出结果类型 → 方法入参必须与之一致（不一致直接编译期报错）
+ *     schema: fromZod<z.infer<typeof Weather>>(z.toJSONSchema(Weather) as JsonSchema, Weather),
  *   })
  *   get(input: { city: string; days: number }) { ... }
  * }

package/dist/toolkit/zod.js.map

@@ -1 +1 @@
-{"version":3,"file":"zod.js","sourceRoot":"","sources":["../../src/toolkit/zod.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,OAAO,CAAC,UAAsB,EAAE,GAAY;IAC1D,MAAM,EAAE,GAAG,GAKV,CAAC;IACF,IAAI,OAAO,EAAE,EAAE,SAAS,KAAK,UAAU,EAAE,CAAC;QACxC,MAAM,IAAI,KAAK,CAAC,8DAA8D,CAAC,CAAC;IAClF,CAAC;IACD,kDAAkD;IAClD,OAAO;QACL,GAAG,UAAU;QACb,aAAa,EAAE,CAAC,KAAc,EAAiB,EAAE;YAC/C,MAAM,CAAC,GAAG,EAAE,CAAC,SAAU,CAAC,KAAK,CAAC,CAAC;YAC/B,IAAI,CAAC,CAAC,OAAO;gBAAE,OAAO,IAAI,CAAC;YAC3B,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC;YACnC,IAAI,CAAC,KAAK;gBAAE,OAAO,UAAU,CAAC;YAC9B,MAAM,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACtD,OAAO,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,IAAI,UAAU,CAAC,CAAC;QAC5E,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"zod.js","sourceRoot":"","sources":["../../src/toolkit/zod.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,OAAO,CAAc,UAAsB,EAAE,GAAY;IACvE,MAAM,EAAE,GAAG,GAKV,CAAC;IACF,IAAI,OAAO,EAAE,EAAE,SAAS,KAAK,UAAU,EAAE,CAAC;QACxC,MAAM,IAAI,KAAK,CACb,8DAA8D,CAC/D,CAAC;IACJ,CAAC;IACD,kDAAkD;IAClD,OAAO;QACL,GAAG,UAAU;QACb,aAAa,EAAE,CAAC,KAAc,EAAiB,EAAE;YAC/C,MAAM,CAAC,GAAG,EAAE,CAAC,SAAU,CAAC,KAAK,CAAC,CAAC;YAC/B,IAAI,CAAC,CAAC,OAAO;gBAAE,OAAO,IAAI,CAAC;YAC3B,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC;YACnC,IAAI,CAAC,KAAK;gBAAE,OAAO,UAAU,CAAC;YAC9B,MAAM,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACtD,OAAO,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,IAAI,UAAU,CAAC,CAAC;QAC5E,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/transport/async.d.ts

@@ -0,0 +1,133 @@
+import type Anthropic from '@anthropic-ai/sdk';
+import type { ModelClient } from '../core/tool.js';
+import type { AgentRunResult } from '../engine/types.js';
+import type { RunStatus } from '../core/run.js';
+import type { RunInvocationOptions } from '../engine/spec.js';
+import type { MaybePromise, TaskRecord, TaskStore } from '../store/store.js';
+/**
+ * Agentia —— 异步任务宿主（spec §6.3 异步 / §6.5 确定性 / §6.6 换宿主不换语义）。
+ *
+ * - submit 即回（queued），后台驱动状态机 queued → running → succeeded/failed；
+ * - **at-least-once 去重**：同一 idempotencyKey 重复 submit，若上一任务仍在
+ *   queued/running/succeeded 则直接返回既有记录，不重复执行（失败可重试新任务）；
+ * - run 记录落 TaskStore（v1 InMemoryTaskStore），trace 随 result 一同保留；
+ *   DB/队列宿主只需实现 TaskStore。
+ *
+ * 异步 TaskStore（R6，TaskStore 方法返回 MaybePromise）：
+ * - 内部执行路径（#execute / awaitTask / resumePending）全部 await 化，两种 store 通吃；
+ * - submit/poll/byIdempotency/list 是**同步门面**，为同步 store 保持原有用法与返回类型
+ *   （http/scheduler/既有调用方零改动）。接异步 store 时：submit 的即时去重无法进行
+ *   （推迟到 #execute：同键已有 succeeded 记录则采纳其结果、不重复执行），poll 等
+ *   返回 Promise 需调用方自行 await。
+ */
+/**
+ * 任务完成回调（C5）。任务达终态、记录已落库后调用。
+ * **抛错被吞**，绝不影响任务状态（与 trace sink / memory 回写同款防护）。
+ *
+ * webhook 故意**不做进框架**：用本接口 + 你自己的 `fetch` 就能搭（含签名与重试策略），
+ * 而那会引入「出站请求 + 重试 + 签名」一整套复杂度。
+ */
+export interface TaskSink {
+    onFinished(rec: TaskRecord): void | Promise<void>;
+}
+export interface AsyncRunnerOptions {
+    client?: ModelClient;
+    store?: TaskStore;
+    /** 同时执行的任务上限；缺省不限。超出部分排队等槽位（状态保持 queued） */
+    concurrency?: number;
+    /** 任务完成回调（进程内）；见 TaskSink */
+    taskSinks?: TaskSink[];
+    /**
+     * 单任务执行超时（毫秒）；缺省 0 = 不限。
+     *
+     * **超时即中止**：到点会 abort 本次 run 的 signal —— 对尊重 signal 的模型客户端
+     * （框架自带的 Anthropic / OpenAI 适配器都转发 signal）是**真中止**，token 不再继续烧；
+     * 不尊重 signal 的自定义 client 则仍等价于「放弃等待」（run 在后台跑完、产物丢弃）。
+     * 槽位无论如何立即回收；被放弃且仍在跑的任务会让实际并发短暂高于 concurrency。
+     */
+    runTimeoutMs?: number;
+}
+/** resumePending 的启动扫描选项 */
+export interface ResumePendingOptions {
+    /**
+     * 他进程任务的「保鲜期」（毫秒）；缺省 0 = 不判断，一律重派（重启即续跑）。
+     * > 0 时跳过 startedAt/createdAt 距今不足该值的他进程记录 —— 那些任务大概
+     * 正在别的进程里跑着，抢过来会重复执行。0 适合单进程部署（旧语义）。
+     */
+    staleAfterMs?: number;
+}
+/** 应用最小调用面（agent 装配无关，避免 run 层向上依赖 toolkit） */
+export interface AppCallable {
+    readonly name: string;
+    run(messages: Anthropic.MessageParam[], opts?: RunInvocationOptions): Promise<{
+        run: {
+            runId: string;
+            status: RunStatus;
+        };
+        result: AgentRunResult;
+    }>;
+}
+export declare class AsyncRunner {
+    #private;
+    private readonly app;
+    readonly store: TaskStore;
+    /** 本进程标识：写进认领的 TaskRecord.ownerId，供 resumePending 区分他我 */
+    readonly ownerId: string;
+    private readonly client?;
+    private readonly concurrency;
+    private readonly runTimeoutMs;
+    private running;
+    private readonly waitQueue;
+    /** 已受理但未达终态的任务数（queued + running）—— /healthz 与 drain 共用 */
+    private active;
+    private draining;
+    private readonly drainWaiters;
+    private readonly taskSinks;
+    constructor(app: AppCallable, opts?: AsyncRunnerOptions);
+    /**
+     * 提交一次异步任务。入参可为 string / messages / {prompt|text|messages}。
+     * 幂等键存在且上一任务未失败 → 直接返回既有记录（去重）；失败的同键可产生新任务。
+     * 同步门面：同步 store 下立即去重并返回快照；异步 store 下 save 在后台完成、
+     * 去重推迟到执行前（见 #execute），返回新建任务的提交时刻快照。
+     */
+    submit(input: unknown, opts?: {
+        idempotencyKey?: string;
+        source?: string;
+        options?: RunInvocationOptions;
+    }): TaskRecord;
+    /** 查任务当前记录（异步 store 下返回 Promise，调用方 await） */
+    poll(taskId: string): MaybePromise<TaskRecord | undefined>;
+    byIdempotency(key: string): MaybePromise<TaskRecord | undefined>;
+    list(): MaybePromise<TaskRecord[]>;
+    /** 已受理但未达终态的任务数（queued + running）—— 健康检查与 drain 共用同一口径 */
+    get inFlight(): number;
+    /** 是否已进入优雅停机（drain 之后为 true）—— HTTP 宿主据此对新单回 503 */
+    get isDraining(): boolean;
+    /**
+     * 优雅停机：停止接单（此后 `submit` 抛错），等待已受理任务排空（或超时）。
+     *
+     * 返回是否排空干净：超时仍返回 `false`，**未完成的任务留在 store 里**，下次启动由
+     * `resumePending` 续跑（所以 drain 不是「丢弃」，是「不再往前推」）。
+     * - `timeoutMs` 缺省 0 = 一直等。
+     * - 等待的是**所有已受理**的任务（queued 的也在内），不只是正在占槽位的那些。
+     */
+    drain(opts?: {
+        timeoutMs?: number;
+    }): Promise<boolean>;
+    /** 等到任务终态；超时抛错。 */
+    awaitTask(taskId: string, opts?: {
+        timeoutMs?: number;
+        intervalMs?: number;
+    }): Promise<TaskRecord>;
+    /**
+     * 宿主重启续跑：把 store 里 queued | running 的记录重新派发执行
+     * （running 视为进程中断）。返回重派数量（异步 store 下返回 Promise<number>）。
+     * 幂等键去重照常生效。
+     *
+     * 多进程共用一个 store 时靠 `ownerId` 区分他我：
+     * - 本进程的记录一律跳过（它还在本进程内存里跑，重派 = 跑两遍）；
+     * - `staleAfterMs > 0` 时，startedAt/createdAt 距今不足该值的他进程记录也跳过
+     *   （大概正被那个进程执行）。缺省 0 = 不判断、一律重派（单进程旧语义）。
+     */
+    resumePending(opts?: ResumePendingOptions): number | Promise<number>;
+}