工具总线 + Agent 开环:声明式工具、人类工具与 LLM 五件系统内化(Mastra tool 形状)

用户定:Agent 调用工具一律**声明式**;人类工具与 LLM 工具要系统内化;
工具总线基于 Mastra tool 设计。

**声明面**(`toolbox/internal/domain/tool-bus.ts`,纯逻辑零框架):
`compileToolBus(声明 × 目录) → 一张清单` —— 编译期定死这一单能调什么,
清单之外结构上调不到(白名单在缝里再把一次关);缺件/停用如实报不静默。
三路同一形状:
  · `function` 功能工具:按活动白名单查目录,带出效应(read/write)
  · `human` **人类工具**(系统内化、零声明即得):调人 = 发工单 + 立监听听人 ——
    这是 Harness 给的能力,不进目录、不需白名单,每个活动天然可以调人
  · `llm` **LLM 五件**(系统内化):extract/classify/summarize/judge/rewrite,
    各有入参出参契约、经模型网关一缝;**仅当活动声明了模型用途名才上总线**
    (没声明却会问模型 = 越权,用量也无从归因);提示词归系统,活动改不了

**装配面**(`app/tool-bus.ts`,Mastra `createTool`):清单 → 可调用工具,
JSON Schema 现译 zod(模型照它填参,填错当场被拦);三路各穿各的缝:
写类工具**过程中一律不落地**,只登记动作意向(骗 Agent 说已执行是最坏选项);
调人把卡号记进 trace,引擎据此把这一拍挂起。

**Agent 开环**(`app/mastra-agent-runner.ts`,M5-2 第二实现,用户选的路线):
Mastra `Agent` + 工具总线,拍内自主连环调工具,拍末交回结构化结论。
放开的是工具循环不是规矩:写类不落地、终局唯放行、调人即挂起(新增
`AgentAction.asked` 型 —— 卡已由总线发出,引擎只收尾,不重复发卡)、
用量按 usage 计入预算。`JCAI_AGENT_OPEN_LOOP=1` 开启,缺省仍是单拍版。
`ModelGateway.resolve` 新增:名 → 四元(密钥当场解出,只给 app 层装配用)。

代价如实记 debt M5-2:开环下模型**逐轮**调用不经录制回放(tool-calling 往返
`generate` 的 text-in/text-out 承载不了)—— 凭证隔离与工具调用一缝完整。

测试:tool-bus 六例(白名单/缺件/停用/人类工具恒在/LLM 按声明/五件契约);
四闸(typecheck/lint/depcruise/test)全过;spike 目录排除出 lint(验证性原型)。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KeDBx2PHLavbURXB8LJJ7m

api-report/apps/api/src/modules/llm/contract.d.ts

@@ -63,12 +63,26 @@ export type ModelResult = {
     };
     readonly mode: GatewayMode;
 };
+/** 解好的模型端点(四元 + 明文密钥)—— app 层装配专用,见 ModelGateway.resolve */
+export type ResolvedEndpoint = {
+    readonly provider: LlmProvider;
+    readonly baseUrl: string;
+    readonly model: string;
+    readonly apiKey: string;
+};
 /**
  * 模型网关 —— 活动基座六件里的「LLM 调用」。
  * 活动只见自定义模型名;解析、凭证、录制回放全在此。
  */
 export type ModelGateway = {
     readonly mode: GatewayMode;
+    /**
+     * 解绑定:名 → 四元(含当场解出的密钥)—— **只给 app 层装配用**:
+     * Mastra Agent 那类需要真模型对象做 tool-calling 往返的场合,
+     * `generate` 的 text-in/text-out 抽象承载不了。
+     * 密钥与 endpoint 仍不入 domain、不入包、不入留痕明文(OS 7.3 凭证隔离)。
+     */
+    resolve(modelName: string): Promise<ResolvedEndpoint>;
     generate(call: ModelCall): Promise<ModelResult>;
     /** 换模式的网关 —— 回放审用 replay 模式重跑引擎(§7.3) */
     withMode(mode: GatewayMode): ModelGateway;

api-report/apps/api/src/modules/llm/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * module: llm —— 唯一出口。只做 re-export,不写逻辑(编码规范 §10.1)。
  */
-export type { BindingViolation, GatewayMode, LlmInstanceView, LlmProvider, LlmService, ModelBinding, ModelCall, ModelGateway, ModelResult, ModelUsage, UpsertLlmInstance, } from './contract.ts';
+export type { BindingViolation, GatewayMode, LlmInstanceView, LlmProvider, LlmService, ModelBinding, ModelCall, ModelGateway, ResolvedEndpoint, ModelResult, ModelUsage, UpsertLlmInstance, } from './contract.ts';
 export { GATEWAY_MODES, ModelDisabledError, ModelNotBoundError, ReplayMissError } from './contract.ts';
 export type { Clock, IdGenerator, LlmInstanceRepository, ProviderInvoker, ReplayRecord, ReplayStore, SecretBox, } from './port.ts';
 export type { LlmServiceDeps } from './internal/usecase/llm-service.ts';

api-report/apps/api/src/modules/loop-engine/contract.d.ts

@@ -70,6 +70,16 @@ export type AgentAction =
  | {
     readonly kind: 'submit';
     readonly rationale: string;
+}
+/**
+ * 本回合**已在工具循环里调过人**:卡已发、监听已立(工具总线执行的)。
+ * 引擎只收尾把这一拍置 awaiting —— 不能再发一张,否则负责人工位上堆两张同样的卡。
+ * 开环模式(Mastra Agent 自主连环调工具)专用;单拍模式给不出这一型。
+ */
+ | {
+    readonly kind: 'asked';
+    readonly cardId: string;
+    readonly rationale: string;
 };
 export type TurnOutcome = {
     readonly runtime: CaseRuntime;

api-report/apps/api/src/modules/toolbox/index.d.ts

@@ -9,6 +9,8 @@ export { createToolInvoker, toolReplayKey } from './internal/usecase/tool-invoke
 export type { ToolboxServiceDeps } from './internal/usecase/toolbox-service.ts';
 export { createToolboxService } from './internal/usecase/toolbox-service.ts';
 export { checkEvolution, dispositionOf, EFFECT_LEVEL_LABEL, EFFECT_LEVELS } from './internal/domain/tool-contract.ts';
+export type { BusTool, CatalogEntry, ToolBusInput, ToolBusReport } from './internal/domain/tool-bus.ts';
+export { compileToolBus, HUMAN_TOOL, LLM_TOOLS } from './internal/domain/tool-bus.ts';
 export { auditPassed, staticAudit } from './internal/domain/registration-audit.ts';
 export type { ToolHandler } from './internal/adapter/toolbox-store.ts';
 export { createSchemaValidator, createToolRegistry, createToolReplayStore, createToolRuntime, isAllowed, } from './internal/adapter/toolbox-store.ts';