@onco-foundry/agent-template 0.1.0

package/dist/agent_template.d.ts

@@ -0,0 +1,112 @@
+import { type AgentSpec, type ModelClient } 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 Tracer } from '@onco-foundry/trace-port';
+/**
+ * 版本化 prompt 资源的 manifest 形状：结构版本号与内容版本号分开，
+ * systemPrompt 是指向版本目录内文件的引用（含 sha256，加载时校验完整性）。
+ * 模板侧创建版本目录与加载生效版本共用这一个 schema。
+ */
+export declare const promptManifestSchema: z.ZodObject<{
+    schemaVersion: z.ZodString;
+    promptVersion: z.ZodString;
+    provenance: z.ZodString;
+    systemPrompt: z.ZodObject<{
+        file: z.ZodString;
+        sha256: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/**
+ * 思考预算钳制：思考与工具调用共享 maxTokens 输出预算，
+ * budgetTokens 必须小于 maxTokens，否则 API 直接报错。maxTokens 至少为 2。
+ */
+export declare const clampThinkingBudgetTokens: (requestedBudgetTokens: number, maxTokens: number) => number;
+/** 能力名片：名字、种类、一句话职责、输入输出契约。版本不在名片上——版本归场景（ADR-10），由 createCapability 落定。 */
+export type AgentTemplateCard<I = unknown, O = unknown> = {
+    readonly name: string;
+    readonly kind: 'agent';
+    readonly summary: string;
+    readonly input: z.ZodType<I>;
+    readonly output: z.ZodType<O>;
+};
+export type AgentTemplateDeclaration<I, O> = {
+    /** kebab-case：能力名片名；spec 名由它派生（kebab→snake，id.replaceAll('-', '_')）。 */
+    id: string;
+    /** 一句话职责：名片 summary，也是 typed 工具菜单文案的缺省。 */
+    summary: string;
+    /** 输入契约（zod）。 */
+    input: z.ZodType<I>;
+    /** submit 交付契约（zod）：名片 output = spec 的 outputSchema（SDK 据此注入 submit_output）。 */
+    output: z.ZodType<O>;
+    /**
+     * mapInput 话术：把校验后的 typed 入参投影成子级 prompt。sync——需要
+     * per-call 异步预处理（取图、缩放）的模板不适用本声明件，维持自建工厂。
+     */
+    task: (input: I) => string;
+    /**
+     * 版本化 prompt 资源根（含 current.json 指针）：
+     * new URL('./resources/prompts/', import.meta.url)。生效版本解析归模板，编排方零感知。
+     */
+    promptDir: URL;
+    /**
+     * 可选限额。缺省：maxTokens 16384、maxTurns 10、thinking 关闭；
+     * thinkingBudgetTokens 给了才开 thinking（按 clampThinkingBudgetTokens 钳制到 maxTokens 以内）。
+     */
+    limits?: {
+        maxTokens?: number;
+        maxTurns?: number;
+        thinkingBudgetTokens?: number;
+    };
+};
+export type CreateTemplateAgentOptions = {
+    model: {
+        model: string;
+        baseURL?: string;
+        apiKey?: string;
+    };
+    /** 测试注入缝：替换真实模型客户端，不碰网络。 */
+    modelClient?: ModelClient;
+    /** 缺省 noop tracer；prompt 版本加载后 setVersions({ prompt }) 回填。 */
+    tracer?: Tracer;
+    /** prompt 版本覆盖缝：指定版本目录名则跳过 current.json 指针，试跑/对照工具用。 */
+    promptVersion?: string;
+};
+export type AgentTemplate<I, O> = {
+    /** 能力名片：{ name: id, kind: 'agent', summary, input, output }，无 version（版本归场景，ADR-10）。 */
+    readonly card: AgentTemplateCard<I, O>;
+    /**
+     * 加载生效版本 prompt（或 promptVersion 指定版本）：返回 { systemPrompt, promptVersion }。
+     * 资源缺文件当场抛错。
+     */
+    loadPrompt(options?: {
+        promptVersion?: string;
+    }): Promise<{
+        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>;
+    /**
+     * 完整能力：defineCapability({ ...card, version: version ?? promptVersion, run })。
+     * run 由库提供：parse 入参 → spec.spawn().prompt(task(input)) → is_error 抛错
+     * → structuredResult 缺失抛错 → output.parse 后返回。
+     */
+    createCapability(options: CreateTemplateAgentOptions & {
+        version?: string;
+    }): Promise<Capability<I, O>>;
+};
+/**
+ * 智能体模板声明件：同构简单模板（submit 交付过 schema 即可、无工具、无 loop 外组装）
+ * 的生产侧形状。一次声明吐出四个出口：名片 / loadPrompt / spec / delegation / capability。
+ *
+ * 版本绑定口径：声明件模板的交付 payload = 纯业务契约，版本绑定不进 payload——
+ * SDK submit_output 形态下模型交不出版本字段，且 agentTool 要求 outputSchema 与
+ * target 声明一致。版本链走三处：capability.version（缺省 promptVersion）、
+ * ToolDefinition.metadata（createTypedAgentTool 投射时写入）、createCapability
+ * 返回能力的 describe()。这与 knowledge-gatekeeper（自定义 submit 工具把版本注入
+ * payload）是两派实现，不要混用。
+ */
+export declare const defineAgentTemplate: <I, O>(declaration: AgentTemplateDeclaration<I, O>) => AgentTemplate<I, O>;

package/dist/agent_template.js

@@ -0,0 +1,126 @@
+import { defineAgent } from 'agent-lattice';
+import { z } from 'zod';
+import { defineCapability } from '@onco-foundry/capability-registry';
+import { loadActiveVersionedResource, resourceFileReferenceSchema, versionedManifestBaseShape, } from '@onco-foundry/resource-versioning';
+import { createTracer } from '@onco-foundry/trace-port';
+import { AppError } from '@onco-foundry/errors';
+/**
+ * 版本化 prompt 资源的 manifest 形状：结构版本号与内容版本号分开，
+ * systemPrompt 是指向版本目录内文件的引用（含 sha256，加载时校验完整性）。
+ * 模板侧创建版本目录与加载生效版本共用这一个 schema。
+ */
+export const promptManifestSchema = z.object({
+    ...versionedManifestBaseShape,
+    promptVersion: z.string().min(1),
+    provenance: z.string().min(1),
+    systemPrompt: resourceFileReferenceSchema,
+});
+/** 缺省输出预算：无工具的问答/判定类交付，16k 足够。 */
+const DEFAULT_MAX_TOKENS = 16_384;
+/** 缺省轮次上限：无工具模板一次 loop 典型路径是读入即交付。 */
+const DEFAULT_MAX_TURNS = 10;
+/**
+ * 思考预算钳制：思考与工具调用共享 maxTokens 输出预算，
+ * budgetTokens 必须小于 maxTokens，否则 API 直接报错。maxTokens 至少为 2。
+ */
+export const clampThinkingBudgetTokens = (requestedBudgetTokens, maxTokens) => Math.min(requestedBudgetTokens, Math.max(maxTokens, 2) - 1);
+const kebabCasePattern = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+/**
+ * 智能体模板声明件：同构简单模板（submit 交付过 schema 即可、无工具、无 loop 外组装）
+ * 的生产侧形状。一次声明吐出四个出口：名片 / loadPrompt / spec / delegation / capability。
+ *
+ * 版本绑定口径：声明件模板的交付 payload = 纯业务契约，版本绑定不进 payload——
+ * SDK submit_output 形态下模型交不出版本字段，且 agentTool 要求 outputSchema 与
+ * target 声明一致。版本链走三处：capability.version（缺省 promptVersion）、
+ * ToolDefinition.metadata（createTypedAgentTool 投射时写入）、createCapability
+ * 返回能力的 describe()。这与 knowledge-gatekeeper（自定义 submit 工具把版本注入
+ * payload）是两派实现，不要混用。
+ */
+export const defineAgentTemplate = (declaration) => {
+    if (!kebabCasePattern.test(declaration.id)) {
+        throw new AppError(`模板 id 必须是 kebab-case（小写字母数字与连字符）：${declaration.id}`);
+    }
+    const { id } = declaration;
+    const card = {
+        name: id,
+        kind: 'agent',
+        summary: declaration.summary,
+        input: declaration.input,
+        output: declaration.output,
+    };
+    const loadPrompt = async (loadOptions) => {
+        const promptResource = await loadActiveVersionedResource({
+            baseDir: declaration.promptDir,
+            manifestSchema: promptManifestSchema,
+            ...(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}`);
+        }
+        return { systemPrompt, promptVersion: promptResource.manifest.promptVersion };
+    };
+    /** 四个出口共用同一份 spec 构建：prompt 加载、限额、tracer 回填完全一致。 */
+    const buildSpec = async (options) => {
+        const { systemPrompt, promptVersion } = await loadPrompt(options.promptVersion === undefined ? undefined : { promptVersion: options.promptVersion });
+        // 调用方不传 tracer 时用 noop：追踪摘掉后模板照常运行。
+        const tracer = options.tracer ?? createTracer({ kind: 'noop' });
+        // prompt 版本在装配处还不知道，加载完版本化资源后回填进版本链。
+        tracer.setVersions({ prompt: promptVersion });
+        const maxTokens = declaration.limits?.maxTokens ?? DEFAULT_MAX_TOKENS;
+        const maxTurns = declaration.limits?.maxTurns ?? DEFAULT_MAX_TURNS;
+        const thinkingBudgetTokens = declaration.limits?.thinkingBudgetTokens;
+        // workspace: false = 裸会话：不装内建工作区工具，同构简单模板不需要文件/Bash 权限面。
+        // spec 每次委派生成全新会话，历史不互串、并发不互踩。
+        const spec = defineAgent({
+            name: id.replaceAll('-', '_'),
+            model: options.model.model,
+            baseURL: options.model.baseURL,
+            apiKey: options.model.apiKey,
+            modelClient: options.modelClient,
+            systemPrompt,
+            maxTokens,
+            maxTurns,
+            thinkingConfig: thinkingBudgetTokens === undefined
+                ? { type: 'disabled' }
+                : { type: 'enabled', budgetTokens: clampThinkingBudgetTokens(thinkingBudgetTokens, maxTokens) },
+            // 无领域校验要过，交付契约直接交给 SDK：声明 outputSchema 后 SDK 注入
+            // submit_output 工具，没提交就收尾会以 error_missing_output 失败。
+            outputSchema: declaration.output,
+            tracer,
+            workspace: false,
+        });
+        return { spec, promptVersion };
+    };
+    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) };
+        },
+        createCapability: async (options) => {
+            const { spec, promptVersion } = await buildSpec(options);
+            const run = async (rawInput) => {
+                // 运行期边界：typed 参数挡不住 any 与强转，这次 parse 是真实校验，不可删。
+                const input = declaration.input.parse(rawInput);
+                const response = await spec.spawn().prompt(declaration.task(input));
+                if (response.is_error) {
+                    throw response.error ?? new Error(`模板 ${id} 运行失败：${response.subtype}`);
+                }
+                if (response.structuredResult === undefined) {
+                    throw new Error(`模板 ${id} 的模型未提交结构化交付，本次运行不算完成`);
+                }
+                return declaration.output.parse(response.structuredResult);
+            };
+            return defineCapability({
+                ...card,
+                version: options.version ?? promptVersion,
+                run,
+            });
+        },
+    };
+};

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1 @@
+export { clampThinkingBudgetTokens, defineAgentTemplate, promptManifestSchema, } from './agent_template.js';

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@onco-foundry/agent-template",
+  "version": "0.1.0",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "agent-lattice": "0.23.0",
+    "zod": "^4.4.3",
+    "@onco-foundry/errors": "0.1.1",
+    "@onco-foundry/capability-registry": "0.1.1",
+    "@onco-foundry/resource-versioning": "0.1.1",
+    "@onco-foundry/agent-runtime": "0.2.0",
+    "@onco-foundry/trace-port": "0.3.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json"
+  },
+  "types": "./dist/index.d.ts"
+}