@onco-foundry/agent-template 0.1.1 → 0.2.0

package/dist/agent_template.d.ts

@@ -1,7 +1,8 @@
-import { type AgentSpec, type ModelClient } from 'agent-lattice';
+import { type AgentSpec, type ModelClient, type ToolDefinition } from 'agent-lattice';
 import { z } from 'zod';
 import { type Capability } from '@onco-foundry/capability-registry';
 import type { CapabilityDelegation } from '@onco-foundry/agent-runtime';
+import { type VersionedResource } from '@onco-foundry/resource-versioning';
 import { type Tracer } from '@onco-foundry/trace-port';
 /**
  * 版本化 prompt 资源的 manifest 形状：结构版本号与内容版本号分开，
@@ -30,7 +31,21 @@ export type AgentTemplateCard<I = unknown, O = unknown> = {
     readonly input: z.ZodType<I>;
     readonly output: z.ZodType<O>;
 };
-export type AgentTemplateDeclaration<I, O> = {
+/**
+ * prompt 资源形状适配：资源目录不是平台 prompt manifest 形状（promptManifestSchema）
+ * 时注入。manifestSchema 传给 loadActiveVersionedResource 做校验（文件引用照常做
+ * 路径防穿越与 sha256 比对）；resolve 从加载结果里取出 systemPrompt 文本与
+ * promptVersion。resolve 返回空 systemPrompt 与缺文件同等抛错——空 prompt 不进模型。
+ * manifest 的业务字段形状由注入方自定，库内只能按 any 过手。
+ */
+export type PromptManifestAdapter = {
+    readonly manifestSchema: z.ZodType<any>;
+    readonly resolve: (loaded: VersionedResource<any>) => {
+        systemPrompt: string;
+        promptVersion: string;
+    };
+};
+export type AgentTemplateDeclaration<I, O, C = undefined> = {
     /** kebab-case：能力名片名；spec 名由它派生（kebab→snake，id.replaceAll('-', '_')）。 */
     id: string;
     /** 一句话职责：名片 summary，也是 typed 工具菜单文案的缺省。 */
@@ -40,10 +55,22 @@ export type AgentTemplateDeclaration<I, O> = {
     /** submit 交付契约（zod）：名片 output = spec 的 outputSchema（SDK 据此注入 submit_output）。 */
     output: z.ZodType<O>;
     /**
-     * mapInput 话术：把校验后的 typed 入参投影成子级 prompt。sync——需要
-     * per-call 异步预处理（取图、缩放）的模板不适用本声明件，维持自建工厂。
+     * mapInput 话术：把校验后的 typed 入参投影成子级 prompt。第二个参数是会话级
+     * 上下文（见 createXxx 的 context 参数）；C=undefined 时只传 input 的现有写法
+     * 保持可赋值，向后兼容。sync——需要 per-call 异步预处理（取图、缩放）的模板
+     * 不适用本声明件，维持自建工厂。
      */
-    task: (input: I) => string;
+    task: (input: I, context: C) => string;
+    /**
+     * 业务工具槽位（可选）：按 context 构建工具，依赖（上下文身份、存储端口、
+     * logger 等）经 context 在创建时绑定。工具与 SDK 注入的 submit_output 并存。
+     */
+    tools?: (context: C) => ToolDefinition[];
+    /**
+     * prompt 资源形状适配（可选）：资源目录不是平台 prompt manifest 形状时注入。
+     * 缺省 = 平台形状（versionedManifestBaseShape + promptVersion/provenance/systemPrompt 引用），现状不变。
+     */
+    promptManifest?: PromptManifestAdapter;
     /**
      * 版本化 prompt 资源根（含 current.json 指针）：
      * new URL('./resources/prompts/', import.meta.url)。生效版本解析归模板，编排方零感知。
@@ -72,12 +99,12 @@ export type CreateTemplateAgentOptions = {
     /** prompt 版本覆盖缝：指定版本目录名则跳过 current.json 指针，试跑/对照工具用。 */
     promptVersion?: string;
 };
-export type AgentTemplate<I, O> = {
+export type AgentTemplate<I, O, C = undefined> = {
     /** 能力名片：{ name: id, kind: 'agent', summary, input, output }，无 version（版本归场景，ADR-10）。 */
     readonly card: AgentTemplateCard<I, O>;
     /**
      * 加载生效版本 prompt（或 promptVersion 指定版本）：返回 { systemPrompt, promptVersion }。
-     * 资源缺文件当场抛错。
+     * 资源缺文件当场抛错；promptManifest 注入时 resolve 出空 systemPrompt 同等抛错。
      */
     loadPrompt(options?: {
         promptVersion?: string;
@@ -85,21 +112,25 @@ export type AgentTemplate<I, O> = {
         systemPrompt: string;
         promptVersion: string;
     }>;
-    /** 构建 AgentSpec：加载 prompt + defineAgent（裸会话 workspace:false，outputSchema 交给 SDK 注入 submit_output）。 */
-    createSpec(options: CreateTemplateAgentOptions): Promise<AgentSpec>;
-    /** typed 委派两块料：{ spec, mapInput: task }。async——prompt 加载是 IO。 */
-    createDelegation(options: CreateTemplateAgentOptions): Promise<CapabilityDelegation>;
+    /**
+     * 构建 AgentSpec：加载 prompt + defineAgent（裸会话 workspace:false，outputSchema 交给
+     * SDK 注入 submit_output）。context 是会话级数据与端口（本次任务对象 id、存储、logger），
+     * 会随任务变的走它；声明了 tools 槽位时按 context 构建工具挂进 spec。
+     */
+    createSpec(options: CreateTemplateAgentOptions, context?: C): Promise<AgentSpec>;
+    /** typed 委派两块料：{ spec, mapInput }。mapInput 闭包 context。async——prompt 加载是 IO。 */
+    createDelegation(options: CreateTemplateAgentOptions, context?: C): Promise<CapabilityDelegation>;
     /**
      * 完整能力：defineCapability({ ...card, version: version ?? promptVersion, run })。
-     * run 由库提供：parse 入参 → spec.spawn().prompt(task(input)) → is_error 抛错
+     * run 由库提供：parse 入参 → spec.spawn().prompt(task(input, context)) → is_error 抛错
      * → structuredResult 缺失抛错 → output.parse 后返回。
      */
     createCapability(options: CreateTemplateAgentOptions & {
         version?: string;
-    }): Promise<Capability<I, O>>;
+    }, context?: C): Promise<Capability<I, O>>;
 };
 /**
- * 智能体模板声明件：同构简单模板（submit 交付过 schema 即可、无工具、无 loop 外组装）
+ * 智能体模板声明件：同构简单模板（submit 交付过 schema 即可、交付物不在 loop 外组装）
  * 的生产侧形状。一次声明吐出四个出口：名片 / loadPrompt / spec / delegation / capability。
  *
  * 版本绑定口径：声明件模板的交付 payload = 纯业务契约，版本绑定不进 payload——
@@ -108,5 +139,12 @@ export type AgentTemplate<I, O> = {
  * ToolDefinition.metadata（createTypedAgentTool 投射时写入）、createCapability
  * 返回能力的 describe()。这与 knowledge-gatekeeper（自定义 submit 工具把版本注入
  * payload）是两派实现，不要混用。
+ *
+ * options vs context 的分工：options（CreateTemplateAgentOptions）是静态装配——
+ * model、tracer、promptVersion 覆盖缝；context（泛型 C）是会话级数据与端口——
+ * 本次任务对象 id、存储端口、logger 等会随任务变的东西。SDK 的 TContext 通道
+ * （QueryOptions.context → ToolExecutionContext）穿不过 agentTool 的 typed 委派
+ * 边界（agentTool spawn 子会话时不转发父级 context），所以 context 在工厂调用时
+ * 绑定：task 的第二个参数、tools 槽位的构建参数都从它取值。
  */
-export declare const defineAgentTemplate: <I, O>(declaration: AgentTemplateDeclaration<I, O>) => AgentTemplate<I, O>;
+export declare const defineAgentTemplate: <I, O, C = undefined>(declaration: AgentTemplateDeclaration<I, O, C>) => AgentTemplate<I, O, C>;

package/dist/agent_template.js

@@ -26,7 +26,7 @@ const DEFAULT_MAX_TURNS = 10;
 export const clampThinkingBudgetTokens = (requestedBudgetTokens, maxTokens) => Math.min(requestedBudgetTokens, Math.max(maxTokens, 2) - 1);
 const kebabCasePattern = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 /**
- * 智能体模板声明件：同构简单模板（submit 交付过 schema 即可、无工具、无 loop 外组装）
+ * 智能体模板声明件：同构简单模板（submit 交付过 schema 即可、交付物不在 loop 外组装）
  * 的生产侧形状。一次声明吐出四个出口：名片 / loadPrompt / spec / delegation / capability。
  *
  * 版本绑定口径：声明件模板的交付 payload = 纯业务契约，版本绑定不进 payload——
@@ -35,6 +35,13 @@ const kebabCasePattern = /^[a-z0-9]+(-[a-z0-9]+)*$/;
  * ToolDefinition.metadata（createTypedAgentTool 投射时写入）、createCapability
  * 返回能力的 describe()。这与 knowledge-gatekeeper（自定义 submit 工具把版本注入
  * payload）是两派实现，不要混用。
+ *
+ * options vs context 的分工：options（CreateTemplateAgentOptions）是静态装配——
+ * model、tracer、promptVersion 覆盖缝；context（泛型 C）是会话级数据与端口——
+ * 本次任务对象 id、存储端口、logger 等会随任务变的东西。SDK 的 TContext 通道
+ * （QueryOptions.context → ToolExecutionContext）穿不过 agentTool 的 typed 委派
+ * 边界（agentTool spawn 子会话时不转发父级 context），所以 context 在工厂调用时
+ * 绑定：task 的第二个参数、tools 槽位的构建参数都从它取值。
  */
 export const defineAgentTemplate = (declaration) => {
     if (!kebabCasePattern.test(declaration.id)) {
@@ -48,22 +55,35 @@ export const defineAgentTemplate = (declaration) => {
         input: declaration.input,
         output: declaration.output,
     };
+    /** 缺省适配：平台 prompt manifest 形状，取 systemPrompt 文件，缺文件当场抛错。 */
+    const defaultPromptManifest = {
+        manifestSchema: promptManifestSchema,
+        resolve: (loaded) => {
+            const manifest = loaded.manifest;
+            const systemPrompt = loaded.files.get(manifest.systemPrompt.file);
+            if (systemPrompt === undefined) {
+                throw new Error(`模板 ${id} 的 prompt 资源缺少文件：${manifest.systemPrompt.file}`);
+            }
+            return { systemPrompt, promptVersion: manifest.promptVersion };
+        },
+    };
     const loadPrompt = async (loadOptions) => {
+        const adapter = declaration.promptManifest ?? defaultPromptManifest;
         const promptResource = await loadActiveVersionedResource({
             baseDir: declaration.promptDir,
-            manifestSchema: promptManifestSchema,
+            manifestSchema: adapter.manifestSchema,
             ...(loadOptions?.promptVersion !== undefined
                 ? { versionOverride: loadOptions.promptVersion }
                 : {}),
         });
-        const systemPrompt = promptResource.files.get(promptResource.manifest.systemPrompt.file);
-        if (systemPrompt === undefined) {
-            throw new Error(`模板 ${id} 的 prompt 资源缺少文件：${promptResource.manifest.systemPrompt.file}`);
+        const resolved = adapter.resolve(promptResource);
+        if (resolved.systemPrompt === '') {
+            throw new Error(`模板 ${id} 的 prompt 资源解析出空 systemPrompt，与缺文件同等处理`);
         }
-        return { systemPrompt, promptVersion: promptResource.manifest.promptVersion };
+        return resolved;
     };
     /** 四个出口共用同一份 spec 构建：prompt 加载、限额、tracer 回填完全一致。 */
-    const buildSpec = async (options) => {
+    const buildSpec = async (options, context) => {
         const { systemPrompt, promptVersion } = await loadPrompt(options.promptVersion === undefined ? undefined : { promptVersion: options.promptVersion });
         // 调用方不传 tracer 时用 noop：追踪摘掉后模板照常运行。
         const tracer = options.tracer ?? createTracer({ kind: 'noop' });
@@ -89,6 +109,8 @@ export const defineAgentTemplate = (declaration) => {
             // 无领域校验要过，交付契约直接交给 SDK：声明 outputSchema 后 SDK 注入
             // submit_output 工具，没提交就收尾会以 error_missing_output 失败。
             outputSchema: declaration.output,
+            // 业务工具槽位：声明了才构建，依赖经 context 在创建时绑定；与 submit_output 并存。
+            ...(declaration.tools === undefined ? {} : { tools: declaration.tools(context) }),
             tracer,
             workspace: false,
         });
@@ -97,17 +119,17 @@ export const defineAgentTemplate = (declaration) => {
     return {
         card,
         loadPrompt,
-        createSpec: async (options) => (await buildSpec(options)).spec,
-        createDelegation: async (options) => {
-            const { spec } = await buildSpec(options);
-            return { spec, mapInput: (input) => declaration.task(input) };
+        createSpec: async (options, context) => (await buildSpec(options, context)).spec,
+        createDelegation: async (options, context) => {
+            const { spec } = await buildSpec(options, context);
+            return { spec, mapInput: (input) => declaration.task(input, context) };
         },
-        createCapability: async (options) => {
-            const { spec, promptVersion } = await buildSpec(options);
+        createCapability: async (options, context) => {
+            const { spec, promptVersion } = await buildSpec(options, context);
             const run = async (rawInput) => {
                 // 运行期边界：typed 参数挡不住 any 与强转，这次 parse 是真实校验，不可删。
                 const input = declaration.input.parse(rawInput);
-                const response = await spec.spawn().prompt(declaration.task(input));
+                const response = await spec.spawn().prompt(declaration.task(input, context));
                 if (response.is_error) {
                     throw response.error ?? new Error(`模板 ${id} 运行失败：${response.subtype}`);
                 }

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { clampThinkingBudgetTokens, defineAgentTemplate, promptManifestSchema, type AgentTemplate, type AgentTemplateCard, type AgentTemplateDeclaration, type CreateTemplateAgentOptions, } from './agent_template.ts';
+export { clampThinkingBudgetTokens, defineAgentTemplate, promptManifestSchema, type AgentTemplate, type AgentTemplateCard, type AgentTemplateDeclaration, type CreateTemplateAgentOptions, type PromptManifestAdapter, } from './agent_template.ts';
 export type { CapabilityDelegation } from '@onco-foundry/agent-runtime';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onco-foundry/agent-template",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "type": "module",
   "files": [
     "dist"
@@ -16,8 +16,8 @@
     "zod": "^4.4.3",
     "@onco-foundry/agent-runtime": "0.2.1",
     "@onco-foundry/capability-registry": "0.1.1",
-    "@onco-foundry/resource-versioning": "0.1.1",
     "@onco-foundry/errors": "0.1.1",
+    "@onco-foundry/resource-versioning": "0.1.1",
     "@onco-foundry/trace-port": "0.3.1"
   },
   "publishConfig": {