@migor/agentia 0.2.0 → 0.2.2

package/dist/toolkit/asset.d.ts

@@ -1,11 +1,11 @@
 /**
- * Agentia —— 文本资产加载（units/<name>/ 目录约定的配套 helper）。
+ * Agentia —— 文本资产加载（capabilities/<name>/ 目录约定的配套 helper）。
  *
- * 一单元一文件夹时，长文本（prompt 模板、子 agent 的 system）放在单元目录里的
- * .md 文件，单元代码里 `asset(import.meta.url, './system.md')` 直读：
+ * 一能力一文件夹时，长文本（prompt 模板、子 agent 的 system）放在能力目录里的
+ * .md 文件，能力代码里 `asset(import.meta.url, './system.md')` 直读：
  *
  * ```ts
- * // units/reviewer/index.ts
+ * // capabilities/reviewer/index.ts
  * import { SubAgent, asset } from 'agentia';
  * export default class Reviewer {
  *   @SubAgent({ description: '…', schema: {...}, system: asset(import.meta.url, './system.md') })
@@ -13,8 +13,9 @@
  * }
  * ```
  *
- * 每次调用现读、不缓存：@Prompt 的 volatile 语义（每次调用重算）要求资产新鲜；
- * 文本文件读取开销可忽略。要在模块加载期固化，就在模块顶层调用一次存常量。
+ * 读取时机：本函数在**调用处**读文件。把 `asset(...)` 直接当装饰器 spec 值（下面的例子）
+ * 是**模块加载期读一次**并固化；要「每次调用重算」（@Prompt 的 volatile 语义），应把
+ * `asset(...)` 写在方法体内返回。文本文件读取开销可忽略。
  *
  * @param base 调用方模块的 import.meta.url（相对它解析 rel）
  * @param rel  相对资产路径（'./system.md'）

package/dist/toolkit/asset.js

@@ -1,12 +1,12 @@
 import { readFileSync } from 'node:fs';
 /**
- * Agentia —— 文本资产加载（units/<name>/ 目录约定的配套 helper）。
+ * Agentia —— 文本资产加载（capabilities/<name>/ 目录约定的配套 helper）。
  *
- * 一单元一文件夹时，长文本（prompt 模板、子 agent 的 system）放在单元目录里的
- * .md 文件，单元代码里 `asset(import.meta.url, './system.md')` 直读：
+ * 一能力一文件夹时，长文本（prompt 模板、子 agent 的 system）放在能力目录里的
+ * .md 文件，能力代码里 `asset(import.meta.url, './system.md')` 直读：
  *
  * ```ts
- * // units/reviewer/index.ts
+ * // capabilities/reviewer/index.ts
  * import { SubAgent, asset } from 'agentia';
  * export default class Reviewer {
  *   @SubAgent({ description: '…', schema: {...}, system: asset(import.meta.url, './system.md') })
@@ -14,8 +14,9 @@ import { readFileSync } from 'node:fs';
  * }
  * ```
  *
- * 每次调用现读、不缓存：@Prompt 的 volatile 语义（每次调用重算）要求资产新鲜；
- * 文本文件读取开销可忽略。要在模块加载期固化，就在模块顶层调用一次存常量。
+ * 读取时机：本函数在**调用处**读文件。把 `asset(...)` 直接当装饰器 spec 值（下面的例子）
+ * 是**模块加载期读一次**并固化；要「每次调用重算」（@Prompt 的 volatile 语义），应把
+ * `asset(...)` 写在方法体内返回。文本文件读取开销可忽略。
  *
  * @param base 调用方模块的 import.meta.url（相对它解析 rel）
  * @param rel  相对资产路径（'./system.md'）

package/dist/toolkit/asset.js.map

@@ -1 +1 @@
-{"version":3,"file":"asset.js","sourceRoot":"","sources":["../../src/toolkit/asset.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,KAAK,CAAC,IAAkB,EAAE,GAAW;IACnD,OAAO,YAAY,CAAC,IAAI,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC;AAClD,CAAC"}
+{"version":3,"file":"asset.js","sourceRoot":"","sources":["../../src/toolkit/asset.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,KAAK,CAAC,IAAkB,EAAE,GAAW;IACnD,OAAO,YAAY,CAAC,IAAI,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC;AAClD,CAAC"}

package/dist/toolkit/collect.d.ts

@@ -1,14 +1,13 @@
 /**
- * Agentia —— 单元收集器共用内核。
+ * Agentia —— 能力收集器共用内核。
  *
- * 四类单元（tool/skill/subagent/prompt）的装饰器都只把「方法函数 → spec」登记进
+ * 四类能力（tool/skill/subagent/prompt）的装饰器都只把「方法函数 → spec」登记进
  * 各自的 WeakMap；收集器在容器实例解析后沿原型链扫描出被装饰的方法。
- * 本模块是这一扫描的唯一实现，四个 collect* 只做各自单元形态的组装。
+ * 本模块是这一扫描的唯一实现，四个 collect* 只做各自能力形态的组装。
  */
-/** 一次扫描命中：方法 key、原型上的方法函数、登记的 spec。 */
+/** 一次扫描命中：方法 key、登记的 spec。 */
 export interface DecoratedMethod<S> {
     key: string | symbol;
-    fn: Function;
     spec: S;
 }
 /**
@@ -17,7 +16,21 @@ export interface DecoratedMethod<S> {
  * 父类的 spec（spec 沿原型链继承，调用仍走实例上的子类实现）。
  */
 export declare function scanDecoratedMethods<S>(instance: object, registry: WeakMap<Function, S>): DecoratedMethod<S>[];
-/** 单元名解析：spec.name 缺省取方法名；私有符号方法名必须显式给 name。 */
-export declare function unitName(spec: {
+/** 装饰器收到的标准 context 子集（本框架只用到这三个字段） */
+export interface CapabilityDecoratorContext {
+    kind: string;
+    name: string | symbol;
+    /** 标准装饰器 context 的私有方法标记（`#method` 的 kind 同样是 'method'） */
+    private?: boolean;
+}
+/**
+ * 四类能力装饰器共用的目标守卫：只接类方法，且**拒绝私有方法**。
+ *
+ * 收集走 `Reflect.ownKeys`，私有名（#method）在其中不可见 —— 不拦的话能力会
+ * 静默从菜单里消失，作者只能靠「模型说没有这个工具」反推。
+ */
+export declare function assertMethodTarget(context: CapabilityDecoratorContext, kind: string): void;
+/** 能力名解析：spec.name 缺省取方法名；私有符号方法名必须显式给 name。 */
+export declare function capabilityName(spec: {
     name?: string;
 }, key: string | symbol, kind: string): string;

package/dist/toolkit/collect.js

@@ -1,9 +1,9 @@
 /**
- * Agentia —— 单元收集器共用内核。
+ * Agentia —— 能力收集器共用内核。
  *
- * 四类单元（tool/skill/subagent/prompt）的装饰器都只把「方法函数 → spec」登记进
+ * 四类能力（tool/skill/subagent/prompt）的装饰器都只把「方法函数 → spec」登记进
  * 各自的 WeakMap；收集器在容器实例解析后沿原型链扫描出被装饰的方法。
- * 本模块是这一扫描的唯一实现，四个 collect* 只做各自单元形态的组装。
+ * 本模块是这一扫描的唯一实现，四个 collect* 只做各自能力形态的组装。
  */
 /**
  * 沿实例原型链扫描被装饰的方法（子类 → 父类）。
@@ -16,7 +16,7 @@ export function scanDecoratedMethods(instance, registry) {
     let proto = Object.getPrototypeOf(instance);
     while (proto && proto !== Object.prototype) {
         // Reflect.ownKeys 含 symbol key：symbol 命名的装饰方法也会被找到，
-        // 无显式 name 时由 unitName 抛出提示（而非静默忽略）
+        // 无显式 name 时由 capabilityName 抛出提示（而非静默忽略）
         for (const key of Reflect.ownKeys(proto)) {
             if (seen.has(key))
                 continue;
@@ -27,14 +27,28 @@ export function scanDecoratedMethods(instance, registry) {
             if (!spec)
                 continue; // 未装饰的 override 不标 seen，父类 spec 继续生效
             seen.add(key);
-            found.push({ key, fn: desc.value, spec });
+            found.push({ key, spec });
         }
         proto = Object.getPrototypeOf(proto);
     }
     return found;
 }
-/** 单元名解析：spec.name 缺省取方法名；私有符号方法名必须显式给 name。 */
-export function unitName(spec, key, kind) {
+/**
+ * 四类能力装饰器共用的目标守卫：只接类方法，且**拒绝私有方法**。
+ *
+ * 收集走 `Reflect.ownKeys`，私有名（#method）在其中不可见 —— 不拦的话能力会
+ * 静默从菜单里消失，作者只能靠「模型说没有这个工具」反推。
+ */
+export function assertMethodTarget(context, kind) {
+    if (context.kind !== 'method') {
+        throw new Error(`${kind} 只能修饰类方法，收到 kind=${String(context.kind)}`);
+    }
+    if (context.private) {
+        throw new Error(`${kind} 不支持私有方法（#method）：收集用 Reflect.ownKeys，私有名不可见`);
+    }
+}
+/** 能力名解析：spec.name 缺省取方法名；私有符号方法名必须显式给 name。 */
+export function capabilityName(spec, key, kind) {
     if (typeof spec.name === 'string')
         return spec.name;
     if (typeof key !== 'string') {

package/dist/toolkit/collect.js.map

@@ -1 +1 @@
-{"version":3,"file":"collect.js","sourceRoot":"","sources":["../../src/toolkit/collect.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AASH;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAClC,QAAgB,EAChB,QAA8B;IAE9B,MAAM,KAAK,GAAyB,EAAE,CAAC;IACvC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAmB,CAAC;IAExC,IAAI,KAAK,GAAkB,MAAM,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC;IAC3D,OAAO,KAAK,IAAI,KAAK,KAAK,MAAM,CAAC,SAAS,EAAE,CAAC;QAC3C,oDAAoD;QACpD,oCAAoC;QACpC,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACzC,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;gBAAE,SAAS;YAC5B,MAAM,IAAI,GAAG,MAAM,CAAC,wBAAwB,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;YACzD,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,CAAC,KAAK,KAAK,UAAU;gBAAE,SAAS;YACxD,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,KAAiB,CAAC,CAAC;YAClD,IAAI,CAAC,IAAI;gBAAE,SAAS,CAAC,qCAAqC;YAC1D,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACd,KAAK,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,IAAI,CAAC,KAAiB,EAAE,IAAI,EAAE,CAAC,CAAC;QACxD,CAAC;QACD,KAAK,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IACvC,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,gDAAgD;AAChD,MAAM,UAAU,QAAQ,CAAC,IAAuB,EAAE,GAAoB,EAAE,IAAY;IAClF,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,IAAI,CAAC;IACpD,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,uBAAuB,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAChE,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}
+{"version":3,"file":"collect.js","sourceRoot":"","sources":["../../src/toolkit/collect.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAQH;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAClC,QAAgB,EAChB,QAA8B;IAE9B,MAAM,KAAK,GAAyB,EAAE,CAAC;IACvC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAmB,CAAC;IAExC,IAAI,KAAK,GAAkB,MAAM,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC;IAC3D,OAAO,KAAK,IAAI,KAAK,KAAK,MAAM,CAAC,SAAS,EAAE,CAAC;QAC3C,oDAAoD;QACpD,0CAA0C;QAC1C,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACzC,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;gBAAE,SAAS;YAC5B,MAAM,IAAI,GAAG,MAAM,CAAC,wBAAwB,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;YACzD,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,CAAC,KAAK,KAAK,UAAU;gBAAE,SAAS;YACxD,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,KAAiB,CAAC,CAAC;YAClD,IAAI,CAAC,IAAI;gBAAE,SAAS,CAAC,qCAAqC;YAC1D,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACd,KAAK,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC;QAC5B,CAAC;QACD,KAAK,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IACvC,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAUD;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAmC,EAAE,IAAY;IAClF,IAAI,OAAO,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,oBAAoB,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACrE,CAAC;IACD,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,8CAA8C,CAAC,CAAC;IACzE,CAAC;AACH,CAAC;AAED,gDAAgD;AAChD,MAAM,UAAU,cAAc,CAC5B,IAAuB,EACvB,GAAoB,EACpB,IAAY;IAEZ,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,IAAI,CAAC;IACpD,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,uBAAuB,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAChE,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/toolkit/discover.d.ts

@@ -1,2 +1,22 @@
 import type { Provider } from '../container/container.js';
-export declare function discoverProviders(dir: string): Promise<Provider[]>;
+/**
+ * Agentia —— 能力目录发现（`<目录>/<name>/index.ts` 约定，spec §7 静态校验仍由装配层统一做）。
+ *
+ * 入参给**一个目录**或**一组目录**：数组拼成一条搜索路径，**顺序即装配顺序**
+ * （典型布局是四分类目录 `src/tools` / `src/skills` / `src/prompts` / `src/subagents`）。
+ *
+ * 约定（对每个目录各自成立）：
+ * - 每个子目录 = 一个能力文件夹，入口为 index.ts / index.mts / index.js / index.mjs（按序取先存在者）；
+ * - 入口 default export 支持三种形态：
+ *   1. 类                → { provide: <文件夹名>, useClass: 该类 }
+ *   2. Provider 对象      → 原样使用（可用 useFactory/useValue 自定义 token）
+ *   3. Provider 数组      → 展开（一个文件夹暴露多个 provider）
+ * - DI token 缺省 = 文件夹名（kebab-case 文件夹即 kebab-case token，能力引用照写）。
+ *
+ * 与手动 providers 可混用：createApp({ providers, discover }) 合并注册，
+ * 重名/引用校验在装配期统一进行（AgentApp 构造函数）。
+ *
+ * 动态 import 决定本函数是异步的 —— createApp 带 discover 时同样返回 Promise。
+ */
+export declare const ENTRY_CANDIDATES: string[];
+export declare function discoverProviders(dir: string | string[]): Promise<Provider[]>;

package/dist/toolkit/discover.js

@@ -1,50 +1,97 @@
-import { existsSync, readdirSync } from 'node:fs';
+import { existsSync, readdirSync, statSync } from 'node:fs';
 import { isAbsolute, join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { isProvider } from '../container/container.js';
 /**
- * Agentia —— 单元目录发现（units/<name>/ 目录约定，spec §7 静态校验仍由装配层统一做）。
+ * Agentia —— 能力目录发现（`<目录>/<name>/index.ts` 约定，spec §7 静态校验仍由装配层统一做）。
  *
- * 约定：
- * - 每个子目录 = 一个单元文件夹，入口为 index.ts / index.mts / index.js / index.mjs（按序取先存在者）；
+ * 入参给**一个目录**或**一组目录**：数组拼成一条搜索路径，**顺序即装配顺序**
+ * （典型布局是四分类目录 `src/tools` / `src/skills` / `src/prompts` / `src/subagents`）。
+ *
+ * 约定（对每个目录各自成立）：
+ * - 每个子目录 = 一个能力文件夹，入口为 index.ts / index.mts / index.js / index.mjs（按序取先存在者）；
  * - 入口 default export 支持三种形态：
  *   1. 类                → { provide: <文件夹名>, useClass: 该类 }
  *   2. Provider 对象      → 原样使用（可用 useFactory/useValue 自定义 token）
  *   3. Provider 数组      → 展开（一个文件夹暴露多个 provider）
- * - DI token 缺省 = 文件夹名（kebab-case 文件夹即 kebab-case token，单元引用照写）。
+ * - DI token 缺省 = 文件夹名（kebab-case 文件夹即 kebab-case token，能力引用照写）。
  *
  * 与手动 providers 可混用：createApp({ providers, discover }) 合并注册，
  * 重名/引用校验在装配期统一进行（AgentApp 构造函数）。
  *
  * 动态 import 决定本函数是异步的 —— createApp 带 discover 时同样返回 Promise。
  */
-const ENTRY_CANDIDATES = ['index.ts', 'index.mts', 'index.js', 'index.mjs'];
+export const ENTRY_CANDIDATES = ['index.ts', 'index.mts', 'index.js', 'index.mjs'];
 export async function discoverProviders(dir) {
+    const dirs = Array.isArray(dir) ? dir : [dir];
+    const providers = [];
+    /** 跨目录的重名 token 记账：四个分类目录下同名文件夹会撞 token，装配期后者静默覆盖 —— 留痕 */
+    const seen = new Map();
+    for (const d of dirs) {
+        for (const p of await discoverOne(d)) {
+            const token = String(p.provide);
+            const prev = seen.get(token);
+            if (prev !== undefined && prev !== d) {
+                console.warn(`[agentia:discover] 重名能力 ${token}：先在 ${prev}，后在 ${d} —— 装配期后者覆盖前者，菜单里只剩一个`);
+            }
+            seen.set(token, d);
+            providers.push(p);
+        }
+    }
+    return providers;
+}
+/** 扫描单个目录（缺目录即报错：显式给出的搜索路径不该静默落空） */
+async function discoverOne(dir) {
     const root = isAbsolute(dir) ? dir : resolve(process.cwd(), dir);
     if (!existsSync(root)) {
-        throw new Error(`单元目录不存在: ${root}（先创建或用 CLI: agentia g <type> <name>）`);
+        throw new Error(`能力目录不存在: ${root}（先创建或用 CLI: agentia g <type> <name>）`);
+    }
+    if (!statSync(root).isDirectory()) {
+        // 存在但是普通文件：readdirSync 会抛原始 ENOTDIR，信息量低且不像配置错误
+        throw new Error(`能力目录不是文件夹: ${root}`);
     }
     const providers = [];
     const entries = readdirSync(root, { withFileTypes: true })
-        .filter((e) => e.isDirectory())
+        .filter((e) => isDirLike(join(root, e.name), e))
         .map((e) => e.name)
         .sort(); // 排序保证装配顺序稳定（菜单顺序 = 目录名序，可复现）
     for (const name of entries) {
         const entry = ENTRY_CANDIDATES.map((f) => join(root, name, f)).find(existsSync);
-        if (!entry)
-            continue; // 无入口的目录视为非单元目录（如 assets/），跳过
+        if (!entry) {
+            // 静默跳过过一次（无入口的目录视为非能力目录，如 assets/）：
+            // 但「菜单莫名少一个能力」需要留痕，否则只能靠猜
+            console.warn(`[agentia:discover] 跳过 ${name}/：无 ${ENTRY_CANDIDATES.join(' / ')} 入口`);
+            continue;
+        }
         let mod;
         try {
             mod = await import(pathToFileURL(entry).href);
         }
         catch (e) {
-            throw new Error(`单元 ${name} 入口加载失败（${entry}）: ${e instanceof Error ? e.message : String(e)}`, { cause: e });
+            throw new Error(`能力 ${name} 入口加载失败（${entry}）: ${e instanceof Error ? e.message : String(e)}`, { cause: e });
         }
         const exported = mod.default;
         providers.push(...normalizeExport(name, exported, entry));
     }
     return providers;
 }
+/**
+ * 目录判定：**软链目录**（pnpm store / monorepo 里 `src/tools/foo` 常是软链）的
+ * `isDirectory()` 为 false，直接用会把真能力目录静默漏掉、菜单空着却不报错 ——
+ * 软链要 stat 解引用后再判。悬空软链按非目录处理。
+ */
+function isDirLike(full, e) {
+    if (e.isDirectory())
+        return true;
+    if (!e.isSymbolicLink())
+        return false;
+    try {
+        return statSync(full).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
 function normalizeExport(name, exported, entry) {
     if (typeof exported === 'function') {
         return [{ provide: name, useClass: exported }];
@@ -55,7 +102,7 @@ function normalizeExport(name, exported, entry) {
     if (Array.isArray(exported) && exported.every(isProvider)) {
         return exported;
     }
-    throw new Error(`单元入口 ${entry} 的 default export 形态非法：应为「类 / Provider / Provider[]」，实际 ${describe(exported)}`);
+    throw new Error(`能力入口 ${entry} 的 default export 形态非法：应为「类 / Provider / Provider[]」，实际 ${describe(exported)}`);
 }
 function describe(x) {
     if (x === undefined)

package/dist/toolkit/discover.js.map

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

package/dist/toolkit/middleware.d.ts

@@ -1,27 +1,27 @@
 import type { AgentTool, ToolRunContext } from '../core/tool.js';
 /**
- * Agentia —— 单元调用中间件（拦截器链，roadmap R1）。
+ * Agentia —— 能力调用中间件（拦截器链，roadmap R1）。
  *
- * 挂在每一次单元（tool/skill/subagent/prompt）调用的前后：鉴权、限流、结果缓存、
- * 审计日志、超时包装等横切关注点都走这里，不进业务单元。
+ * 挂在每一次能力（tool/skill/subagent/prompt）调用的前后：鉴权、限流、结果缓存、
+ * 审计日志、超时包装等横切关注点都走这里，不进业务能力。
  *
  * 语义：
  * - 链序 = 注册顺序（洋葱模型：先注册的最外层）；
  * - `next()` 放行（可用 `next(newInput)` 改写入参）；不调 next 即短路（结果缓存等）；
- * - 抛错按单元失败处理（engine 包成 is_error 回给模型，不中断 run）。
+ * - 抛错按能力失败处理（engine 包成 is_error 回给模型，不中断 run）。
  *
  * 装配期包裹（AgentApp 构造函数），对 engine 零侵入。
  */
-export interface UnitCall {
-    /** 被调用的单元（name/description/inputSchema 可读） */
-    readonly unit: AgentTool;
+export interface CapabilityCall {
+    /** 被调用的能力（name/description/inputSchema 可读） */
+    readonly capability: AgentTool;
     /** 模型给出的结构化入参（schema 校验已过） */
     readonly input: unknown;
     /** engine 注入的执行上下文（recorder/parentSpanId/client），同步宿主下可用 */
     readonly ctx?: ToolRunContext;
 }
 /** 放行到下一层；`next(newInput)` 可改写入参，缺省沿用当前 input */
-export type UnitNext = (input?: unknown) => unknown;
-export type UnitMiddleware = (call: UnitCall, next: UnitNext) => unknown;
+export type CapabilityNext = (input?: unknown) => unknown;
+export type CapabilityMiddleware = (call: CapabilityCall, next: CapabilityNext) => unknown;
 /** 用中间件链包裹工具菜单（链为空时原样返回，零开销）。 */
-export declare function applyMiddleware(tools: AgentTool[], middleware: UnitMiddleware[]): AgentTool[];
+export declare function applyMiddleware(tools: AgentTool[], middleware: CapabilityMiddleware[]): AgentTool[];

package/dist/toolkit/middleware.js

@@ -5,10 +5,23 @@ export function applyMiddleware(tools, middleware) {
     return tools.map((tool) => ({
         ...tool,
         run: (input, ctx) => {
-            const invoke = (i, inp) => i >= middleware.length
-                ? tool.run(inp, ctx)
-                : middleware[i]({ unit: tool, input: inp, ctx }, (nextInput = inp) => invoke(i + 1, nextInput));
-            return invoke(0, input);
+            const step = (i, inp) => {
+                if (i >= middleware.length)
+                    return tool.run(inp, ctx);
+                let passed = false;
+                return middleware[i]({ capability: tool, input: inp, ctx }, 
+                // rest 形参而非默认值：`next(undefined)` 是「把入参改写成 undefined」，
+                // 与 `next()`（沿用当前入参）语义不同，默认值写法分不开这两者。
+                // 连调两次会让能力体跑两遍（有副作用的能力尤其危险）——直接报错。
+                (...a) => {
+                    if (passed) {
+                        throw new Error(`中间件链上 next() 被重复调用（能力 ${tool.name}）：一次调用只能放行一次`);
+                    }
+                    passed = true;
+                    return step(i + 1, a.length > 0 ? a[0] : inp);
+                });
+            };
+            return step(0, input);
         },
     }));
 }

package/dist/toolkit/middleware.js.map

@@ -1 +1 @@
-{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../../src/toolkit/middleware.ts"],"names":[],"mappings":"AA6BA,iCAAiC;AACjC,MAAM,UAAU,eAAe,CAAC,KAAkB,EAAE,UAA4B;IAC9E,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC1C,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAC1B,GAAG,IAAI;QACP,GAAG,EAAE,CAAC,KAAc,EAAE,GAAoB,EAAE,EAAE;YAC5C,MAAM,MAAM,GAAG,CAAC,CAAS,EAAE,GAAY,EAAW,EAAE,CAClD,CAAC,IAAI,UAAU,CAAC,MAAM;gBACpB,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC;gBACpB,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CACX,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,EAC/B,CAAC,SAAS,GAAY,GAAG,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,EAAE,SAAS,CAAC,CACvD,CAAC;YACR,OAAO,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;QAC1B,CAAC;KACF,CAAC,CAAC,CAAC;AACN,CAAC"}
+{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../../src/toolkit/middleware.ts"],"names":[],"mappings":"AA6BA,iCAAiC;AACjC,MAAM,UAAU,eAAe,CAC7B,KAAkB,EAClB,UAAkC;IAElC,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC1C,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAC1B,GAAG,IAAI;QACP,GAAG,EAAE,CAAC,KAAc,EAAE,GAAoB,EAAE,EAAE;YAC5C,MAAM,IAAI,GAAG,CAAC,CAAS,EAAE,GAAY,EAAW,EAAE;gBAChD,IAAI,CAAC,IAAI,UAAU,CAAC,MAAM;oBAAE,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;gBACtD,IAAI,MAAM,GAAG,KAAK,CAAC;gBACnB,OAAO,UAAU,CAAC,CAAC,CAAC,CAClB,EAAE,UAAU,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE;gBACrC,sDAAsD;gBACtD,sCAAsC;gBACtC,mCAAmC;gBACnC,CAAC,GAAG,CAAY,EAAE,EAAE;oBAClB,IAAI,MAAM,EAAE,CAAC;wBACX,MAAM,IAAI,KAAK,CACb,yBAAyB,IAAI,CAAC,IAAI,cAAc,CACjD,CAAC;oBACJ,CAAC;oBACD,MAAM,GAAG,IAAI,CAAC;oBACd,OAAO,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;gBAChD,CAAC,CACF,CAAC;YACJ,CAAC,CAAC;YACF,OAAO,IAAI,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;QACxB,CAAC;KACF,CAAC,CAAC,CAAC;AACN,CAAC"}

package/dist/toolkit/module.d.ts

@@ -1,36 +1,31 @@
 import type Anthropic from '@anthropic-ai/sdk';
-import type { AgentTool } from '../core/tool.js';
+import type { AgentTool, JsonSchema, ModelPricing, SchemaType } from '../core/tool.js';
 import type { SystemParam } from '../engine/types.js';
-import { SystemPrompt } from '../run/systemPrompt.js';
-import type { RunInvocationOptions } from '../run/spec.js';
+import { SystemPrompt } from '../runtime/systemPrompt.js';
+import type { RunInvocationOptions } from '../engine/spec.js';
+import type { SessionStore } from '../runtime/session.js';
 import type { AgentRunResult } from '../engine/types.js';
+import type { TraceSink } from '../core/trace.js';
 import { Container } from '../container/container.js';
 import type { Provider, Token } from '../container/container.js';
-import type { UnitMiddleware } from './middleware.js';
+import type { CapabilityMiddleware } from './middleware.js';
 import type { ContextPolicy } from '../engine/types.js';
+import type { RetryOptions } from '../engine/retry.js';
 /**
- * Agentia —— 应用装配（spec §4/§6：主 agent + 可调工具菜单）。
- *
- * createApp 组装：DI 容器注册 providers（手动和/或 discover 目录发现）→
- * 从容器实例自动扫描 @Tool / @SubAgent / @Skill / @Prompt 收集成本 app 的工具菜单
- * → agent.run(messages) 带着菜单走 executeRun。装配期统一静态校验（§7）：
- * 菜单查重、tools 引用存在性、toolSources 指向。
- * 主 agent 的 system 可由 SystemPrompt 实例给出（内部 build({cache:true})
- * 打稳定前缀 breakpoint），也接受已拼好的 SystemParam 原样透传。
- */
-/**
- * 能力包（roadmap R5）：第三方包把「单元 providers + 中间件」打包成 AgentModule 分发，
+ * 能力包（roadmap R5）：第三方包把「能力 providers + 中间件」打包成 AgentModule 分发，
  * 应用侧经 AppOptions.modules 一次性装配。模块的 providers 先于应用级 providers 注册
  *（同 token 应用级覆盖模块级）；中间件拼接顺序同样模块在前。
  */
 export interface AgentModule {
-    /** 模块携带的 DI providers（单元类 / 值 / 工厂） */
+    /** 模块携带的 DI providers（能力类 / 值 / 工厂） */
     providers: Provider[];
-    /** 模块级单元调用中间件（拼在应用级 middleware 之前，即更外层） */
-    middleware?: UnitMiddleware[];
+    /** 模块级能力调用中间件（拼在应用级 middleware 之前，即更外层） */
+    middleware?: CapabilityMiddleware[];
 }
 /** 定义能力包：identity 函数，仅给第三方包一个类型锚点与导出约定 */
 export declare function defineModule(m: AgentModule): AgentModule;
+/** 注册全局默认 trace sink（观测 / dev 工具用）。createApp 构造期快照合并，已建应用不受后续注册影响。 */
+export declare function registerDefaultTraceSink(sink: TraceSink): void;
 export interface AppOptions {
     /** 应用名；同时作为 run 名写入 trace */
     name?: string;
@@ -39,11 +34,12 @@ export interface AppOptions {
     /** 能力包：providers 并入（在 providers 之前注册）、middleware 拼接（在 middleware 之前） */
     modules?: AgentModule[];
     /**
-     * 单元目录发现：units/<name>/ 目录约定（一单元一文件夹，index.ts 入口）。
-     * 给目录路径（相对 cwd）即启动期扫描装配；因动态 import，带 discover 的
-     * createApp 返回 Promise<AgentApp>。
+     * 能力目录发现：`<目录>/<name>/index.ts` 约定（一能力一文件夹）。
+     * 给**一个目录**或**一组目录**（数组顺序即装配顺序）——典型布局是四分类目录
+     * `src/tools` / `src/skills` / `src/prompts` / `src/subagents`。
+     * 启动期扫描装配；因动态 import，带 discover 的 createApp 返回 Promise<AgentApp>。
      */
-    discover?: string;
+    discover?: string | string[];
     /** 主 agent system：SystemPrompt 实例（自动打缓存）或拼好的 SystemParam */
     system: SystemPrompt | SystemParam;
     /** 缺省模型；不给则走 engine 默认（claude-opus-5） */
@@ -54,39 +50,109 @@ export interface AppOptions {
     maxIterations?: number;
     /** 缺省上下文预算策略（compaction / context editing） */
     contextPolicy?: ContextPolicy;
+    /** 缺省模型请求重试策略（可被单次 run 覆盖）；见 RunAgentOptions.retry */
+    retry?: RetryOptions | false;
+    /** 缺省成本硬管控：整条 run 累计 token 上限（可被单次 run 覆盖） */
+    maxTotalTokens?: number;
+    /** 缺省成本硬管控：累计成本（美元）上限（可被单次 run 覆盖） */
+    maxCostUsd?: number;
+    /**
+     * 价格表覆盖/追加（$/1M tokens，可被单次 run 覆盖）；见 `RunAgentOptions.priceOverrides`。
+     * 给非 Anthropic 端点（DeepSeek / 自建）定价，否则 `maxCostUsd` 会静默不生效。
+     */
+    priceOverrides?: Record<string, ModelPricing>;
+    /** 未定价模型回调（可被单次 run 覆盖）；见 `RunAgentOptions.onUnpricedModel` */
+    onUnpricedModel?: (info: {
+        model: string;
+        spanId: string;
+    }) => void;
+    /** 缺省单个工具执行超时（毫秒，可被单次 run 覆盖）；0/不设 = 不限 */
+    toolTimeoutMs?: number;
+    /** 缺省同回合并行工具上限（可被单次 run 覆盖）；不设 = 不限 */
+    maxToolConcurrency?: number;
     /** 只扫这些 token 的 provider 上的 @Tool；缺省扫全部 providers */
     toolSources?: Token[];
-    /** 单元调用中间件（洋葱模型，链序 = 注册顺序）；装配期包裹整个菜单 */
-    middleware?: UnitMiddleware[];
+    /**
+     * 直接追加到主菜单的**裸工具**（`AgentTool[]`）—— 给「构造期才知道有哪些工具」的场景
+     * （典型：MCP 桥 `mcpTools()` 的返回值，见 integrations/mcp.ts）。
+     *
+     * 与装饰器收集来的能力**完全同等**：同样过中间件链、同样进重名查重、同样受
+     * `toolSources` 之外的一切装配规则约束（不受 `toolSources` 收窄影响 —— 这是显式追加）。
+     * 不经装饰器、不进 DI 容器（它没有 provider token，也不是任何能力的 tools 引用目标）。
+     */
+    tools?: AgentTool[];
+    /** 能力调用中间件（洋葱模型，链序 = 注册顺序）；装配期包裹整个菜单 */
+    middleware?: CapabilityMiddleware[];
+    /** trace 出口（观测）：每次 run 收尾投递；与全局默认 sink 合并（本字段在前） */
+    sinks?: TraceSink[];
 }
 /** 单次调用参数 = 通用调用参数 + 单次可覆盖 system（spec.ts 的 RunInvocationOptions 为单源） */
-export interface RunAppOptions extends RunInvocationOptions {
+export interface RunAppOptions<S extends JsonSchema = JsonSchema> extends RunInvocationOptions {
     /** 单次覆盖 system（volatile 段建议每 run 重建以拾取最新值） */
     system?: SystemPrompt | SystemParam;
+    /**
+     * 结构化结果 schema（R2）：语义同 `RunAgentOptions.resultSchema`（engine 追加隐藏
+     * submit_result 工具，校验通过的结果写入 `result.typed`）。
+     * 传 `fromZod<T>(...)` 时 `app.run` 的返回类型自动带上 `typed: T | undefined`。
+     */
+    resultSchema?: S;
+    /**
+     * 会话持久化（C4）：语义同 `ExecuteRunOptions.session` —— run 开始把历史拼在传入
+     * messages 之前，成功收尾把本轮消息 + 回复追加回去。与 `blackboard`（键值黑板）正交。
+     *
+     * 只在程序内直接 `app.run` 时可用（store 实例不可序列化，因此**不在**
+     * transport 的 `RunInvocationOptions` 里 —— 异步宿主不会替你传它）。
+     */
+    session?: {
+        store: SessionStore;
+        id: string;
+    };
+    /**
+     * 未定价模型回调（单次覆盖应用级）；见 `RunAgentOptions.onUnpricedModel`。
+     * 是函数，因此**不在** transport 的 `RunInvocationOptions` 里（异步宿主不替你传）。
+     */
+    onUnpricedModel?: (info: {
+        model: string;
+        spanId: string;
+    }) => void;
 }
-export interface AgentRunOutput {
-    run: import('../run/run.js').Run;
-    result: AgentRunResult;
+export interface AgentRunOutput<T = unknown> {
+    run: import('../runtime/run.js').Run;
+    result: AgentRunResult<T>;
 }
+/**
+ * Agentia —— 应用装配（spec §4/§6：主 agent + 可调工具菜单）。
+ *
+ * createApp 组装：DI 容器注册 providers（手动和/或 discover 目录发现）→
+ * 从容器实例自动扫描 @Tool / @SubAgent / @Skill / @Prompt 收集成本 app 的工具菜单
+ * → agent.run(messages) 带着菜单走 executeRun。装配期统一静态校验（§7）：
+ * 菜单查重、tools 引用存在性、toolSources 指向。
+ * 主 agent 的 system 可由 SystemPrompt 实例给出（内部 build({cache:true})
+ * 打稳定前缀 breakpoint），也接受已拼好的 SystemParam 原样透传。
+ */
 export declare class AgentApp {
     readonly name: string;
     private readonly di;
     private readonly system;
     private readonly base;
-    private _tools?;
+    private _tools;
+    private readonly sinks;
     constructor(opts: AppOptions);
     /** app 已装配好的工具菜单（构建期即从容器解析，静态稳定） */
     get tools(): AgentTool[];
-    /** 容器访问点（后续 trace 拦截器/生命周期回调可用） */
+    /** 容器访问点 */
     get container(): Container;
-    /** 执行一次主 agent run。system 每 run 从 SystemPrompt 重建，保证 volatile 新鲜。 */
-    run(messages: Anthropic.MessageParam[], opts?: RunAppOptions): Promise<AgentRunOutput>;
+    /**
+     * 执行一次主 agent run。system 每 run 从 SystemPrompt 重建，保证 volatile 新鲜。
+     * 传 `resultSchema: fromZod<T>(...)` 时返回值 `result.typed` 为 `T | undefined`。
+     */
+    run<S extends JsonSchema = JsonSchema>(messages: Anthropic.MessageParam[], opts?: RunAppOptions<S>): Promise<AgentRunOutput<SchemaType<S>>>;
 }
 /**
- * 装配应用。不带 discover 时同步返回 AgentApp；带 discover（单元目录路径）时
+ * 装配应用。不带 discover 时同步返回 AgentApp；带 discover（能力目录路径，一个或一组）时
  * 先扫描装配，返回 Promise<AgentApp>（动态 import 决定）。
  */
 export declare function createApp(opts: AppOptions & {
-    discover: string;
+    discover: string | string[];
 }): Promise<AgentApp>;
 export declare function createApp(opts: AppOptions): AgentApp;