@ai-agent-forge/plugin-sdk 0.88.13 → 0.88.15

package/dist/agent-task-scheduler.d.ts

@@ -0,0 +1,154 @@
+/**
+ * 公共 agent-task 调度器能力契约（联网检索设计 §5.6，P1b）。
+ *
+ * 本文件只放**可序列化**的请求/响应词汇与校验入口，不 import 任何运行时实现
+ * （`SubagentRuntime` 属于 `plugins/subagent-delegate`，不进 SDK）。提供方把
+ * one-shot 的 submit/status/result/cancel/drain 经能力目录暴露为
+ * `agent-forge.agent-task-scheduler@1`；跨能力目录统一是异步 request/response，
+ * 设计文档里的同步方法签名只是提供方内部语义。
+ *
+ * 线上词汇（本文件是权威定义，与 `docs/design/联网检索设计.md` §5.6 同步）：
+ * - `status` 返回 `{version, action:"status", status}` 信封，状态词取
+ *   {@link AgentTaskSchedulerStatusSnapshotV1}：在途原样（queued/admitted/running），
+ *   终态走与 result 相同的投影（drain_timeout→timed_out、runner_lost→failed）；
+ *   任务不存在或越界一律 `"unknown"`（同型拒绝，不区分二者）。
+ * - `result` 未命中（未知/越界 taskId）返回不带 `result` 字段的信封。
+ * - `cancel`/`drain` 对未知 taskId 明确失败（抛错冒泡），不同于 status/result 的
+ *   同型未命中——取消与等待都要求调用方先拿到 submit 返回的 taskId。
+ * - requester 作用域由提供方绑定自己的会话，请求里没有 owner/session 字段。
+ */
+import type { PluginErrorV1 } from "./operation.ts";
+import { type AgentTaskChildProfileV1 } from "./public-api.ts";
+/** 能力目录里的声明 id；提供方 manifest 的 `provides` 必须与其一致。 */
+export declare const AGENT_TASK_SCHEDULER_CAPABILITY_ID: "agent-forge.agent-task-scheduler";
+/** 能力契约版本（exact match）。 */
+export declare const AGENT_TASK_SCHEDULER_CAPABILITY_VERSION: 1;
+/**
+ * submit prompt 的 UTF-8 字节上限。The host runtime accepts the same ceiling;
+ * callers may impose a smaller per-task budget.
+ */
+export declare const AGENT_TASK_SCHEDULER_MAX_PROMPT_BYTES: number;
+/** 结果 text 投影的 UTF-8 字节上限（容纳 dossier JSON，不是 200 字符摘要）。 */
+export declare const AGENT_TASK_SCHEDULER_MAX_TEXT_BYTES: number;
+/** 子会话执行模式（与 child profile 的 mode 同词汇）。 */
+export type AgentTaskSchedulerRunModeV1 = "readonly" | "full-control";
+/**
+ * 子任务的可核验事实（设计 §5.6）：由宿主 adapter 在子会话创建后读取。
+ * `getActiveTools` 不可用时整个 facts 省略（消费方验收失败），绝不伪造；
+ * `model` 在宿主不暴露 `getModel` 时省略。
+ */
+export interface AgentTaskSchedulerFactsV1 {
+    readonly tools: readonly string[];
+    readonly model?: string;
+    readonly mode: AgentTaskSchedulerRunModeV1;
+}
+/**
+ * Provider-native web-search citation carried by the terminal result. Only the
+ * URL and title are provider-attested; page content was not fetched.
+ */
+export interface AgentTaskSchedulerCitationV1 {
+    readonly url: string;
+    readonly title?: string;
+}
+/** one-shot 任务提交请求。 */
+export interface AgentTaskSchedulerSubmitV1 {
+    readonly version: 1;
+    /** 任务提示词，非空，UTF-8 ≤ {@link AGENT_TASK_SCHEDULER_MAX_PROMPT_BYTES}。 */
+    readonly prompt: string;
+    /** 子任务档案（收窄语义），经公共解析器校验。 */
+    readonly profile: AgentTaskChildProfileV1;
+    /** 绝对 epoch ms 死线；对齐 SubagentRuntime 的 deadline 语义（tick 强制 timed_out）。 */
+    readonly deadlineAt?: number;
+    /** 附加 metadata（JSON 可序列化对象）；提供方注入契约键时不覆盖这里已带的其他键。 */
+    readonly metadata?: Record<string, unknown>;
+}
+/** 终态词汇（result/drain 投影后）。 */
+export type AgentTaskSchedulerResultStatusV1 = "succeeded" | "failed" | "cancelled" | "timed_out";
+/** 终态投影（跨能力目录的公开形状，设计 §5.6 状态表）。 */
+export interface AgentTaskSchedulerResultV1 {
+    readonly version: 1;
+    readonly taskId: string;
+    readonly status: AgentTaskSchedulerResultStatusV1;
+    /** 最后一条带文本 assistant 消息，UTF-8 ≤ {@link AGENT_TASK_SCHEDULER_MAX_TEXT_BYTES}；无文本省略。 */
+    readonly text?: string;
+    readonly messageCount: number;
+    /** 子会话自身的 sessionId（审计用；P1/P1.5 不用于跨轮 resume）。 */
+    readonly sessionId?: string;
+    /** 子任务档案落地后的可核验事实；宿主不可核验时省略。 */
+    readonly facts?: AgentTaskSchedulerFactsV1;
+    /** Provider-native web-search citations from the same terminal assistant message; absent when none. */
+    readonly citations?: readonly AgentTaskSchedulerCitationV1[];
+    /** 失败/超时的结构化错误（保留 reasonCode/reason）；cancelled 无原因文本时省略。 */
+    readonly error?: PluginErrorV1;
+}
+/**
+ * status 快照词汇：在途状态原样暴露；终态与 result 同投影（drain_timeout→timed_out、
+ * runner_lost→failed）；未知/越界 taskId 返回 `"unknown"`。
+ */
+export type AgentTaskSchedulerStatusSnapshotV1 = "queued" | "admitted" | "running" | AgentTaskSchedulerResultStatusV1 | "unknown";
+/** 能力目录请求 union（全部 version:1，按 action 判别）。 */
+export type AgentTaskSchedulerRequestV1 = {
+    readonly version: 1;
+    readonly action: "submit";
+    readonly request: AgentTaskSchedulerSubmitV1;
+} | {
+    readonly version: 1;
+    readonly action: "status";
+    readonly taskId: string;
+} | {
+    readonly version: 1;
+    readonly action: "result";
+    readonly taskId: string;
+} | {
+    readonly version: 1;
+    readonly action: "cancel";
+    readonly taskId: string;
+    readonly reason?: string;
+} | {
+    readonly version: 1;
+    readonly action: "drain";
+    readonly taskId: string;
+    readonly timeoutMs?: number;
+};
+/** 能力目录响应 union（与请求同 action 判别；全部 JSON 可序列化）。 */
+export type AgentTaskSchedulerResponseV1 = {
+    readonly version: 1;
+    readonly action: "submit";
+    readonly taskId: string;
+} | {
+    readonly version: 1;
+    readonly action: "status";
+    readonly status: AgentTaskSchedulerStatusSnapshotV1;
+} | {
+    readonly version: 1;
+    readonly action: "result";
+    readonly result?: AgentTaskSchedulerResultV1;
+} | {
+    readonly version: 1;
+    readonly action: "cancel";
+} | {
+    readonly version: 1;
+    readonly action: "drain";
+    readonly result: AgentTaskSchedulerResultV1;
+};
+/** 校验结果：合法给规范化副本，否则给可直接回给调用方的原因。 */
+export type AgentTaskSchedulerParseResultV1<TValue> = {
+    readonly ok: true;
+    readonly value: TValue;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/**
+ * 校验一份 submit 请求（设计 §5.6 的入口契约）：profile 交公共解析器；prompt 非空且
+ * UTF-8 ≤ 256 KiB；deadlineAt 非空时必须是安全整数；metadata 非空时必须是 JSON 可
+ * 序列化对象。返回冻结的规范化副本。
+ */
+export declare function parseAgentTaskSchedulerSubmitV1(value: unknown): AgentTaskSchedulerParseResultV1<AgentTaskSchedulerSubmitV1>;
+/**
+ * 校验一份能力目录请求（按 action 判别）：version 必须 1、action 必须在词汇表内；
+ * submit 递归走 {@link parseAgentTaskSchedulerSubmitV1}；taskId 必须是非空字符串；
+ * cancel.reason 是可选字符串、drain.timeoutMs 是可选正安全整数。返回冻结的规范化副本。
+ */
+export declare function parseAgentTaskSchedulerRequestV1(value: unknown): AgentTaskSchedulerParseResultV1<AgentTaskSchedulerRequestV1>;
+//# sourceMappingURL=agent-task-scheduler.d.ts.map

package/dist/agent-task-scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-task-scheduler.d.ts","sourceRoot":"","sources":["../src/agent-task-scheduler.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * 公共 agent-task 调度器能力契约（联网检索设计 §5.6，P1b）。\n *\n * 本文件只放**可序列化**的请求/响应词汇与校验入口，不 import 任何运行时实现\n * （`SubagentRuntime` 属于 `plugins/subagent-delegate`，不进 SDK）。提供方把\n * one-shot 的 submit/status/result/cancel/drain 经能力目录暴露为\n * `agent-forge.agent-task-scheduler@1`；跨能力目录统一是异步 request/response，\n * 设计文档里的同步方法签名只是提供方内部语义。\n *\n * 线上词汇（本文件是权威定义，与 `docs/design/联网检索设计.md` §5.6 同步）：\n * - `status` 返回 `{version, action:\"status\", status}` 信封，状态词取\n *   {@link AgentTaskSchedulerStatusSnapshotV1}：在途原样（queued/admitted/running），\n *   终态走与 result 相同的投影（drain_timeout→timed_out、runner_lost→failed）；\n *   任务不存在或越界一律 `\"unknown\"`（同型拒绝，不区分二者）。\n * - `result` 未命中（未知/越界 taskId）返回不带 `result` 字段的信封。\n * - `cancel`/`drain` 对未知 taskId 明确失败（抛错冒泡），不同于 status/result 的\n *   同型未命中——取消与等待都要求调用方先拿到 submit 返回的 taskId。\n * - requester 作用域由提供方绑定自己的会话，请求里没有 owner/session 字段。\n */\n\nimport type { PluginErrorV1 } from \"./operation.ts\";\nimport { type AgentTaskChildProfileV1, parseAgentTaskChildProfileV1 } from \"./public-api.ts\";\n\n/** 能力目录里的声明 id；提供方 manifest 的 `provides` 必须与其一致。 */\nexport const AGENT_TASK_SCHEDULER_CAPABILITY_ID = \"agent-forge.agent-task-scheduler\" as const;\n\n/** 能力契约版本（exact match）。 */\nexport const AGENT_TASK_SCHEDULER_CAPABILITY_VERSION = 1 as const;\n\n/**\n * submit prompt 的 UTF-8 字节上限。The host runtime accepts the same ceiling;\n * callers may impose a smaller per-task budget.\n */\nexport const AGENT_TASK_SCHEDULER_MAX_PROMPT_BYTES = 48 * 1024;\n\n/** 结果 text 投影的 UTF-8 字节上限（容纳 dossier JSON，不是 200 字符摘要）。 */\nexport const AGENT_TASK_SCHEDULER_MAX_TEXT_BYTES = 32 * 1024;\n\n/** 子会话执行模式（与 child profile 的 mode 同词汇）。 */\nexport type AgentTaskSchedulerRunModeV1 = \"readonly\" | \"full-control\";\n\n/**\n * 子任务的可核验事实（设计 §5.6）：由宿主 adapter 在子会话创建后读取。\n * `getActiveTools` 不可用时整个 facts 省略（消费方验收失败），绝不伪造；\n * `model` 在宿主不暴露 `getModel` 时省略。\n */\nexport interface AgentTaskSchedulerFactsV1 {\n\treadonly tools: readonly string[];\n\treadonly model?: string;\n\treadonly mode: AgentTaskSchedulerRunModeV1;\n}\n\n/**\n * Provider-native web-search citation carried by the terminal result. Only the\n * URL and title are provider-attested; page content was not fetched.\n */\nexport interface AgentTaskSchedulerCitationV1 {\n\treadonly url: string;\n\treadonly title?: string;\n}\n\n/** one-shot 任务提交请求。 */\nexport interface AgentTaskSchedulerSubmitV1 {\n\treadonly version: 1;\n\t/** 任务提示词，非空，UTF-8 ≤ {@link AGENT_TASK_SCHEDULER_MAX_PROMPT_BYTES}。 */\n\treadonly prompt: string;\n\t/** 子任务档案（收窄语义），经公共解析器校验。 */\n\treadonly profile: AgentTaskChildProfileV1;\n\t/** 绝对 epoch ms 死线；对齐 SubagentRuntime 的 deadline 语义（tick 强制 timed_out）。 */\n\treadonly deadlineAt?: number;\n\t/** 附加 metadata（JSON 可序列化对象）；提供方注入契约键时不覆盖这里已带的其他键。 */\n\treadonly metadata?: Record<string, unknown>;\n}\n\n/** 终态词汇（result/drain 投影后）。 */\nexport type AgentTaskSchedulerResultStatusV1 = \"succeeded\" | \"failed\" | \"cancelled\" | \"timed_out\";\n\n/** 终态投影（跨能力目录的公开形状，设计 §5.6 状态表）。 */\nexport interface AgentTaskSchedulerResultV1 {\n\treadonly version: 1;\n\treadonly taskId: string;\n\treadonly status: AgentTaskSchedulerResultStatusV1;\n\t/** 最后一条带文本 assistant 消息，UTF-8 ≤ {@link AGENT_TASK_SCHEDULER_MAX_TEXT_BYTES}；无文本省略。 */\n\treadonly text?: string;\n\treadonly messageCount: number;\n\t/** 子会话自身的 sessionId（审计用；P1/P1.5 不用于跨轮 resume）。 */\n\treadonly sessionId?: string;\n\t/** 子任务档案落地后的可核验事实；宿主不可核验时省略。 */\n\treadonly facts?: AgentTaskSchedulerFactsV1;\n\t/** Provider-native web-search citations from the same terminal assistant message; absent when none. */\n\treadonly citations?: readonly AgentTaskSchedulerCitationV1[];\n\t/** 失败/超时的结构化错误（保留 reasonCode/reason）；cancelled 无原因文本时省略。 */\n\treadonly error?: PluginErrorV1;\n}\n\n/**\n * status 快照词汇：在途状态原样暴露；终态与 result 同投影（drain_timeout→timed_out、\n * runner_lost→failed）；未知/越界 taskId 返回 `\"unknown\"`。\n */\nexport type AgentTaskSchedulerStatusSnapshotV1 =\n\t| \"queued\"\n\t| \"admitted\"\n\t| \"running\"\n\t| AgentTaskSchedulerResultStatusV1\n\t| \"unknown\";\n\n/** 能力目录请求 union（全部 version:1，按 action 判别）。 */\nexport type AgentTaskSchedulerRequestV1 =\n\t| { readonly version: 1; readonly action: \"submit\"; readonly request: AgentTaskSchedulerSubmitV1 }\n\t| { readonly version: 1; readonly action: \"status\"; readonly taskId: string }\n\t| { readonly version: 1; readonly action: \"result\"; readonly taskId: string }\n\t| { readonly version: 1; readonly action: \"cancel\"; readonly taskId: string; readonly reason?: string }\n\t| { readonly version: 1; readonly action: \"drain\"; readonly taskId: string; readonly timeoutMs?: number };\n\n/** 能力目录响应 union（与请求同 action 判别；全部 JSON 可序列化）。 */\nexport type AgentTaskSchedulerResponseV1 =\n\t| { readonly version: 1; readonly action: \"submit\"; readonly taskId: string }\n\t| { readonly version: 1; readonly action: \"status\"; readonly status: AgentTaskSchedulerStatusSnapshotV1 }\n\t| { readonly version: 1; readonly action: \"result\"; readonly result?: AgentTaskSchedulerResultV1 }\n\t| { readonly version: 1; readonly action: \"cancel\" }\n\t| { readonly version: 1; readonly action: \"drain\"; readonly result: AgentTaskSchedulerResultV1 };\n\n/** 校验结果：合法给规范化副本，否则给可直接回给调用方的原因。 */\nexport type AgentTaskSchedulerParseResultV1<TValue> =\n\t| { readonly ok: true; readonly value: TValue }\n\t| { readonly ok: false; readonly message: string };\n\nfunction isPlainRecord(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nconst textEncoder = new TextEncoder();\n\nfunction utf8ByteLength(value: string): number {\n\treturn textEncoder.encode(value).length;\n}\n\nconst SUBMIT_KEYS: ReadonlySet<string> = new Set([\"version\", \"prompt\", \"profile\", \"deadlineAt\", \"metadata\"]);\nconst REQUEST_ACTIONS: readonly string[] = [\"submit\", \"status\", \"result\", \"cancel\", \"drain\"];\n\n/**\n * 校验一份 submit 请求（设计 §5.6 的入口契约）：profile 交公共解析器；prompt 非空且\n * UTF-8 ≤ 256 KiB；deadlineAt 非空时必须是安全整数；metadata 非空时必须是 JSON 可\n * 序列化对象。返回冻结的规范化副本。\n */\nexport function parseAgentTaskSchedulerSubmitV1(\n\tvalue: unknown,\n): AgentTaskSchedulerParseResultV1<AgentTaskSchedulerSubmitV1> {\n\tif (!isPlainRecord(value)) return { ok: false, message: \"agent-task-scheduler submit must be an object\" };\n\tfor (const key of Object.keys(value)) {\n\t\tif (!SUBMIT_KEYS.has(key)) {\n\t\t\treturn { ok: false, message: `agent-task-scheduler submit has unknown key ${JSON.stringify(key)}` };\n\t\t}\n\t}\n\tif (value.version !== 1) {\n\t\treturn {\n\t\t\tok: false,\n\t\t\tmessage: `agent-task-scheduler submit version must be 1, found ${JSON.stringify(value.version)}`,\n\t\t};\n\t}\n\tconst prompt = value.prompt;\n\tif (typeof prompt !== \"string\" || prompt.trim() === \"\") {\n\t\treturn { ok: false, message: \"agent-task-scheduler submit prompt must be a non-empty string\" };\n\t}\n\tconst promptBytes = utf8ByteLength(prompt);\n\tif (promptBytes > AGENT_TASK_SCHEDULER_MAX_PROMPT_BYTES) {\n\t\treturn {\n\t\t\tok: false,\n\t\t\tmessage:\n\t\t\t\t`agent-task-scheduler submit prompt of ${promptBytes} UTF-8 bytes exceeds the ` +\n\t\t\t\t`${AGENT_TASK_SCHEDULER_MAX_PROMPT_BYTES}-byte limit`,\n\t\t};\n\t}\n\tconst parsedProfile = parseAgentTaskChildProfileV1(value.profile);\n\tif (!parsedProfile.ok)\n\t\treturn { ok: false, message: `agent-task-scheduler submit profile: ${parsedProfile.message}` };\n\tconst rawDeadlineAt = value.deadlineAt;\n\tif (rawDeadlineAt !== undefined && !Number.isSafeInteger(rawDeadlineAt)) {\n\t\treturn { ok: false, message: \"agent-task-scheduler submit deadlineAt must be a safe integer (epoch ms)\" };\n\t}\n\tlet metadata: Record<string, unknown> | undefined;\n\tconst rawMetadata = value.metadata;\n\tif (rawMetadata !== undefined) {\n\t\tif (!isPlainRecord(rawMetadata)) {\n\t\t\treturn { ok: false, message: \"agent-task-scheduler submit metadata must be an object\" };\n\t\t}\n\t\ttry {\n\t\t\tconst serialized = JSON.stringify(rawMetadata);\n\t\t\tif (serialized === undefined) {\n\t\t\t\treturn { ok: false, message: \"agent-task-scheduler submit metadata must be JSON-serializable\" };\n\t\t\t}\n\t\t} catch {\n\t\t\treturn { ok: false, message: \"agent-task-scheduler submit metadata must be JSON-serializable\" };\n\t\t}\n\t\tmetadata = rawMetadata;\n\t}\n\treturn {\n\t\tok: true,\n\t\tvalue: Object.freeze({\n\t\t\tversion: 1 as const,\n\t\t\tprompt,\n\t\t\tprofile: parsedProfile.profile,\n\t\t\t...(rawDeadlineAt === undefined ? {} : { deadlineAt: rawDeadlineAt as number }),\n\t\t\t...(metadata === undefined ? {} : { metadata }),\n\t\t}),\n\t};\n}\n\n/** 非空 taskId 的公共校验文本（status/result/cancel/drain 共用）。 */\nfunction parseTaskId(value: unknown): string | undefined {\n\tif (typeof value !== \"string\" || value.length === 0) return undefined;\n\treturn value;\n}\n\n/**\n * 校验一份能力目录请求（按 action 判别）：version 必须 1、action 必须在词汇表内；\n * submit 递归走 {@link parseAgentTaskSchedulerSubmitV1}；taskId 必须是非空字符串；\n * cancel.reason 是可选字符串、drain.timeoutMs 是可选正安全整数。返回冻结的规范化副本。\n */\nexport function parseAgentTaskSchedulerRequestV1(\n\tvalue: unknown,\n): AgentTaskSchedulerParseResultV1<AgentTaskSchedulerRequestV1> {\n\tif (!isPlainRecord(value)) return { ok: false, message: \"agent-task-scheduler request must be an object\" };\n\tif (value.version !== 1) {\n\t\treturn {\n\t\t\tok: false,\n\t\t\tmessage: `agent-task-scheduler request version must be 1, found ${JSON.stringify(value.version)}`,\n\t\t};\n\t}\n\tconst action = value.action;\n\tif (typeof action !== \"string\" || !REQUEST_ACTIONS.includes(action)) {\n\t\treturn {\n\t\t\tok: false,\n\t\t\tmessage: `agent-task-scheduler request action must be one of ${REQUEST_ACTIONS.join(\", \")}, found ${JSON.stringify(action)}`,\n\t\t};\n\t}\n\tif (action === \"submit\") {\n\t\tconst parsed = parseAgentTaskSchedulerSubmitV1(value.request);\n\t\tif (!parsed.ok) return parsed;\n\t\treturn {\n\t\t\tok: true,\n\t\t\tvalue: Object.freeze({ version: 1 as const, action: \"submit\" as const, request: parsed.value }),\n\t\t};\n\t}\n\tconst taskId = parseTaskId(value.taskId);\n\tif (taskId === undefined) {\n\t\treturn { ok: false, message: `agent-task-scheduler ${action} requires a non-empty taskId string` };\n\t}\n\tif (action === \"status\") {\n\t\treturn { ok: true, value: Object.freeze({ version: 1 as const, action: \"status\" as const, taskId }) };\n\t}\n\tif (action === \"result\") {\n\t\treturn { ok: true, value: Object.freeze({ version: 1 as const, action: \"result\" as const, taskId }) };\n\t}\n\tif (action === \"cancel\") {\n\t\tconst reason = value.reason;\n\t\tif (reason !== undefined && typeof reason !== \"string\") {\n\t\t\treturn { ok: false, message: \"agent-task-scheduler cancel reason must be a string when present\" };\n\t\t}\n\t\treturn {\n\t\t\tok: true,\n\t\t\tvalue: Object.freeze({\n\t\t\t\tversion: 1 as const,\n\t\t\t\taction: \"cancel\" as const,\n\t\t\t\ttaskId,\n\t\t\t\t...(reason === undefined ? {} : { reason }),\n\t\t\t}),\n\t\t};\n\t}\n\tconst timeoutMs = value.timeoutMs;\n\tif (\n\t\ttimeoutMs !== undefined &&\n\t\t!(typeof timeoutMs === \"number\" && Number.isSafeInteger(timeoutMs) && timeoutMs > 0)\n\t) {\n\t\treturn {\n\t\t\tok: false,\n\t\t\tmessage: \"agent-task-scheduler drain timeoutMs must be a positive safe integer when present\",\n\t\t};\n\t}\n\treturn {\n\t\tok: true,\n\t\tvalue: Object.freeze({\n\t\t\tversion: 1 as const,\n\t\t\taction: \"drain\" as const,\n\t\t\ttaskId,\n\t\t\t...(timeoutMs === undefined ? {} : { timeoutMs }),\n\t\t}),\n\t};\n}\n"]}

package/dist/agent-task-scheduler.js

@@ -0,0 +1,186 @@
+/**
+ * 公共 agent-task 调度器能力契约（联网检索设计 §5.6，P1b）。
+ *
+ * 本文件只放**可序列化**的请求/响应词汇与校验入口，不 import 任何运行时实现
+ * （`SubagentRuntime` 属于 `plugins/subagent-delegate`，不进 SDK）。提供方把
+ * one-shot 的 submit/status/result/cancel/drain 经能力目录暴露为
+ * `agent-forge.agent-task-scheduler@1`；跨能力目录统一是异步 request/response，
+ * 设计文档里的同步方法签名只是提供方内部语义。
+ *
+ * 线上词汇（本文件是权威定义，与 `docs/design/联网检索设计.md` §5.6 同步）：
+ * - `status` 返回 `{version, action:"status", status}` 信封，状态词取
+ *   {@link AgentTaskSchedulerStatusSnapshotV1}：在途原样（queued/admitted/running），
+ *   终态走与 result 相同的投影（drain_timeout→timed_out、runner_lost→failed）；
+ *   任务不存在或越界一律 `"unknown"`（同型拒绝，不区分二者）。
+ * - `result` 未命中（未知/越界 taskId）返回不带 `result` 字段的信封。
+ * - `cancel`/`drain` 对未知 taskId 明确失败（抛错冒泡），不同于 status/result 的
+ *   同型未命中——取消与等待都要求调用方先拿到 submit 返回的 taskId。
+ * - requester 作用域由提供方绑定自己的会话，请求里没有 owner/session 字段。
+ */
+import { parseAgentTaskChildProfileV1 } from "./public-api.js";
+/** 能力目录里的声明 id；提供方 manifest 的 `provides` 必须与其一致。 */
+export const AGENT_TASK_SCHEDULER_CAPABILITY_ID = "agent-forge.agent-task-scheduler";
+/** 能力契约版本（exact match）。 */
+export const AGENT_TASK_SCHEDULER_CAPABILITY_VERSION = 1;
+/**
+ * submit prompt 的 UTF-8 字节上限。The host runtime accepts the same ceiling;
+ * callers may impose a smaller per-task budget.
+ */
+export const AGENT_TASK_SCHEDULER_MAX_PROMPT_BYTES = 48 * 1024;
+/** 结果 text 投影的 UTF-8 字节上限（容纳 dossier JSON，不是 200 字符摘要）。 */
+export const AGENT_TASK_SCHEDULER_MAX_TEXT_BYTES = 32 * 1024;
+function isPlainRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+const textEncoder = new TextEncoder();
+function utf8ByteLength(value) {
+    return textEncoder.encode(value).length;
+}
+const SUBMIT_KEYS = new Set(["version", "prompt", "profile", "deadlineAt", "metadata"]);
+const REQUEST_ACTIONS = ["submit", "status", "result", "cancel", "drain"];
+/**
+ * 校验一份 submit 请求（设计 §5.6 的入口契约）：profile 交公共解析器；prompt 非空且
+ * UTF-8 ≤ 256 KiB；deadlineAt 非空时必须是安全整数；metadata 非空时必须是 JSON 可
+ * 序列化对象。返回冻结的规范化副本。
+ */
+export function parseAgentTaskSchedulerSubmitV1(value) {
+    if (!isPlainRecord(value))
+        return { ok: false, message: "agent-task-scheduler submit must be an object" };
+    for (const key of Object.keys(value)) {
+        if (!SUBMIT_KEYS.has(key)) {
+            return { ok: false, message: `agent-task-scheduler submit has unknown key ${JSON.stringify(key)}` };
+        }
+    }
+    if (value.version !== 1) {
+        return {
+            ok: false,
+            message: `agent-task-scheduler submit version must be 1, found ${JSON.stringify(value.version)}`,
+        };
+    }
+    const prompt = value.prompt;
+    if (typeof prompt !== "string" || prompt.trim() === "") {
+        return { ok: false, message: "agent-task-scheduler submit prompt must be a non-empty string" };
+    }
+    const promptBytes = utf8ByteLength(prompt);
+    if (promptBytes > AGENT_TASK_SCHEDULER_MAX_PROMPT_BYTES) {
+        return {
+            ok: false,
+            message: `agent-task-scheduler submit prompt of ${promptBytes} UTF-8 bytes exceeds the ` +
+                `${AGENT_TASK_SCHEDULER_MAX_PROMPT_BYTES}-byte limit`,
+        };
+    }
+    const parsedProfile = parseAgentTaskChildProfileV1(value.profile);
+    if (!parsedProfile.ok)
+        return { ok: false, message: `agent-task-scheduler submit profile: ${parsedProfile.message}` };
+    const rawDeadlineAt = value.deadlineAt;
+    if (rawDeadlineAt !== undefined && !Number.isSafeInteger(rawDeadlineAt)) {
+        return { ok: false, message: "agent-task-scheduler submit deadlineAt must be a safe integer (epoch ms)" };
+    }
+    let metadata;
+    const rawMetadata = value.metadata;
+    if (rawMetadata !== undefined) {
+        if (!isPlainRecord(rawMetadata)) {
+            return { ok: false, message: "agent-task-scheduler submit metadata must be an object" };
+        }
+        try {
+            const serialized = JSON.stringify(rawMetadata);
+            if (serialized === undefined) {
+                return { ok: false, message: "agent-task-scheduler submit metadata must be JSON-serializable" };
+            }
+        }
+        catch {
+            return { ok: false, message: "agent-task-scheduler submit metadata must be JSON-serializable" };
+        }
+        metadata = rawMetadata;
+    }
+    return {
+        ok: true,
+        value: Object.freeze({
+            version: 1,
+            prompt,
+            profile: parsedProfile.profile,
+            ...(rawDeadlineAt === undefined ? {} : { deadlineAt: rawDeadlineAt }),
+            ...(metadata === undefined ? {} : { metadata }),
+        }),
+    };
+}
+/** 非空 taskId 的公共校验文本（status/result/cancel/drain 共用）。 */
+function parseTaskId(value) {
+    if (typeof value !== "string" || value.length === 0)
+        return undefined;
+    return value;
+}
+/**
+ * 校验一份能力目录请求（按 action 判别）：version 必须 1、action 必须在词汇表内；
+ * submit 递归走 {@link parseAgentTaskSchedulerSubmitV1}；taskId 必须是非空字符串；
+ * cancel.reason 是可选字符串、drain.timeoutMs 是可选正安全整数。返回冻结的规范化副本。
+ */
+export function parseAgentTaskSchedulerRequestV1(value) {
+    if (!isPlainRecord(value))
+        return { ok: false, message: "agent-task-scheduler request must be an object" };
+    if (value.version !== 1) {
+        return {
+            ok: false,
+            message: `agent-task-scheduler request version must be 1, found ${JSON.stringify(value.version)}`,
+        };
+    }
+    const action = value.action;
+    if (typeof action !== "string" || !REQUEST_ACTIONS.includes(action)) {
+        return {
+            ok: false,
+            message: `agent-task-scheduler request action must be one of ${REQUEST_ACTIONS.join(", ")}, found ${JSON.stringify(action)}`,
+        };
+    }
+    if (action === "submit") {
+        const parsed = parseAgentTaskSchedulerSubmitV1(value.request);
+        if (!parsed.ok)
+            return parsed;
+        return {
+            ok: true,
+            value: Object.freeze({ version: 1, action: "submit", request: parsed.value }),
+        };
+    }
+    const taskId = parseTaskId(value.taskId);
+    if (taskId === undefined) {
+        return { ok: false, message: `agent-task-scheduler ${action} requires a non-empty taskId string` };
+    }
+    if (action === "status") {
+        return { ok: true, value: Object.freeze({ version: 1, action: "status", taskId }) };
+    }
+    if (action === "result") {
+        return { ok: true, value: Object.freeze({ version: 1, action: "result", taskId }) };
+    }
+    if (action === "cancel") {
+        const reason = value.reason;
+        if (reason !== undefined && typeof reason !== "string") {
+            return { ok: false, message: "agent-task-scheduler cancel reason must be a string when present" };
+        }
+        return {
+            ok: true,
+            value: Object.freeze({
+                version: 1,
+                action: "cancel",
+                taskId,
+                ...(reason === undefined ? {} : { reason }),
+            }),
+        };
+    }
+    const timeoutMs = value.timeoutMs;
+    if (timeoutMs !== undefined &&
+        !(typeof timeoutMs === "number" && Number.isSafeInteger(timeoutMs) && timeoutMs > 0)) {
+        return {
+            ok: false,
+            message: "agent-task-scheduler drain timeoutMs must be a positive safe integer when present",
+        };
+    }
+    return {
+        ok: true,
+        value: Object.freeze({
+            version: 1,
+            action: "drain",
+            taskId,
+            ...(timeoutMs === undefined ? {} : { timeoutMs }),
+        }),
+    };
+}
+//# sourceMappingURL=agent-task-scheduler.js.map

package/dist/agent-task-scheduler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-task-scheduler.js","sourceRoot":"","sources":["../src/agent-task-scheduler.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * 公共 agent-task 调度器能力契约（联网检索设计 §5.6，P1b）。\n *\n * 本文件只放**可序列化**的请求/响应词汇与校验入口，不 import 任何运行时实现\n * （`SubagentRuntime` 属于 `plugins/subagent-delegate`，不进 SDK）。提供方把\n * one-shot 的 submit/status/result/cancel/drain 经能力目录暴露为\n * `agent-forge.agent-task-scheduler@1`；跨能力目录统一是异步 request/response，\n * 设计文档里的同步方法签名只是提供方内部语义。\n *\n * 线上词汇（本文件是权威定义，与 `docs/design/联网检索设计.md` §5.6 同步）：\n * - `status` 返回 `{version, action:\"status\", status}` 信封，状态词取\n *   {@link AgentTaskSchedulerStatusSnapshotV1}：在途原样（queued/admitted/running），\n *   终态走与 result 相同的投影（drain_timeout→timed_out、runner_lost→failed）；\n *   任务不存在或越界一律 `\"unknown\"`（同型拒绝，不区分二者）。\n * - `result` 未命中（未知/越界 taskId）返回不带 `result` 字段的信封。\n * - `cancel`/`drain` 对未知 taskId 明确失败（抛错冒泡），不同于 status/result 的\n *   同型未命中——取消与等待都要求调用方先拿到 submit 返回的 taskId。\n * - requester 作用域由提供方绑定自己的会话，请求里没有 owner/session 字段。\n */\n\nimport type { PluginErrorV1 } from \"./operation.ts\";\nimport { type AgentTaskChildProfileV1, parseAgentTaskChildProfileV1 } from \"./public-api.ts\";\n\n/** 能力目录里的声明 id；提供方 manifest 的 `provides` 必须与其一致。 */\nexport const AGENT_TASK_SCHEDULER_CAPABILITY_ID = \"agent-forge.agent-task-scheduler\" as const;\n\n/** 能力契约版本（exact match）。 */\nexport const AGENT_TASK_SCHEDULER_CAPABILITY_VERSION = 1 as const;\n\n/**\n * submit prompt 的 UTF-8 字节上限。The host runtime accepts the same ceiling;\n * callers may impose a smaller per-task budget.\n */\nexport const AGENT_TASK_SCHEDULER_MAX_PROMPT_BYTES = 48 * 1024;\n\n/** 结果 text 投影的 UTF-8 字节上限（容纳 dossier JSON，不是 200 字符摘要）。 */\nexport const AGENT_TASK_SCHEDULER_MAX_TEXT_BYTES = 32 * 1024;\n\n/** 子会话执行模式（与 child profile 的 mode 同词汇）。 */\nexport type AgentTaskSchedulerRunModeV1 = \"readonly\" | \"full-control\";\n\n/**\n * 子任务的可核验事实（设计 §5.6）：由宿主 adapter 在子会话创建后读取。\n * `getActiveTools` 不可用时整个 facts 省略（消费方验收失败），绝不伪造；\n * `model` 在宿主不暴露 `getModel` 时省略。\n */\nexport interface AgentTaskSchedulerFactsV1 {\n\treadonly tools: readonly string[];\n\treadonly model?: string;\n\treadonly mode: AgentTaskSchedulerRunModeV1;\n}\n\n/**\n * Provider-native web-search citation carried by the terminal result. Only the\n * URL and title are provider-attested; page content was not fetched.\n */\nexport interface AgentTaskSchedulerCitationV1 {\n\treadonly url: string;\n\treadonly title?: string;\n}\n\n/** one-shot 任务提交请求。 */\nexport interface AgentTaskSchedulerSubmitV1 {\n\treadonly version: 1;\n\t/** 任务提示词，非空，UTF-8 ≤ {@link AGENT_TASK_SCHEDULER_MAX_PROMPT_BYTES}。 */\n\treadonly prompt: string;\n\t/** 子任务档案（收窄语义），经公共解析器校验。 */\n\treadonly profile: AgentTaskChildProfileV1;\n\t/** 绝对 epoch ms 死线；对齐 SubagentRuntime 的 deadline 语义（tick 强制 timed_out）。 */\n\treadonly deadlineAt?: number;\n\t/** 附加 metadata（JSON 可序列化对象）；提供方注入契约键时不覆盖这里已带的其他键。 */\n\treadonly metadata?: Record<string, unknown>;\n}\n\n/** 终态词汇（result/drain 投影后）。 */\nexport type AgentTaskSchedulerResultStatusV1 = \"succeeded\" | \"failed\" | \"cancelled\" | \"timed_out\";\n\n/** 终态投影（跨能力目录的公开形状，设计 §5.6 状态表）。 */\nexport interface AgentTaskSchedulerResultV1 {\n\treadonly version: 1;\n\treadonly taskId: string;\n\treadonly status: AgentTaskSchedulerResultStatusV1;\n\t/** 最后一条带文本 assistant 消息，UTF-8 ≤ {@link AGENT_TASK_SCHEDULER_MAX_TEXT_BYTES}；无文本省略。 */\n\treadonly text?: string;\n\treadonly messageCount: number;\n\t/** 子会话自身的 sessionId（审计用；P1/P1.5 不用于跨轮 resume）。 */\n\treadonly sessionId?: string;\n\t/** 子任务档案落地后的可核验事实；宿主不可核验时省略。 */\n\treadonly facts?: AgentTaskSchedulerFactsV1;\n\t/** Provider-native web-search citations from the same terminal assistant message; absent when none. */\n\treadonly citations?: readonly AgentTaskSchedulerCitationV1[];\n\t/** 失败/超时的结构化错误（保留 reasonCode/reason）；cancelled 无原因文本时省略。 */\n\treadonly error?: PluginErrorV1;\n}\n\n/**\n * status 快照词汇：在途状态原样暴露；终态与 result 同投影（drain_timeout→timed_out、\n * runner_lost→failed）；未知/越界 taskId 返回 `\"unknown\"`。\n */\nexport type AgentTaskSchedulerStatusSnapshotV1 =\n\t| \"queued\"\n\t| \"admitted\"\n\t| \"running\"\n\t| AgentTaskSchedulerResultStatusV1\n\t| \"unknown\";\n\n/** 能力目录请求 union（全部 version:1，按 action 判别）。 */\nexport type AgentTaskSchedulerRequestV1 =\n\t| { readonly version: 1; readonly action: \"submit\"; readonly request: AgentTaskSchedulerSubmitV1 }\n\t| { readonly version: 1; readonly action: \"status\"; readonly taskId: string }\n\t| { readonly version: 1; readonly action: \"result\"; readonly taskId: string }\n\t| { readonly version: 1; readonly action: \"cancel\"; readonly taskId: string; readonly reason?: string }\n\t| { readonly version: 1; readonly action: \"drain\"; readonly taskId: string; readonly timeoutMs?: number };\n\n/** 能力目录响应 union（与请求同 action 判别；全部 JSON 可序列化）。 */\nexport type AgentTaskSchedulerResponseV1 =\n\t| { readonly version: 1; readonly action: \"submit\"; readonly taskId: string }\n\t| { readonly version: 1; readonly action: \"status\"; readonly status: AgentTaskSchedulerStatusSnapshotV1 }\n\t| { readonly version: 1; readonly action: \"result\"; readonly result?: AgentTaskSchedulerResultV1 }\n\t| { readonly version: 1; readonly action: \"cancel\" }\n\t| { readonly version: 1; readonly action: \"drain\"; readonly result: AgentTaskSchedulerResultV1 };\n\n/** 校验结果：合法给规范化副本，否则给可直接回给调用方的原因。 */\nexport type AgentTaskSchedulerParseResultV1<TValue> =\n\t| { readonly ok: true; readonly value: TValue }\n\t| { readonly ok: false; readonly message: string };\n\nfunction isPlainRecord(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nconst textEncoder = new TextEncoder();\n\nfunction utf8ByteLength(value: string): number {\n\treturn textEncoder.encode(value).length;\n}\n\nconst SUBMIT_KEYS: ReadonlySet<string> = new Set([\"version\", \"prompt\", \"profile\", \"deadlineAt\", \"metadata\"]);\nconst REQUEST_ACTIONS: readonly string[] = [\"submit\", \"status\", \"result\", \"cancel\", \"drain\"];\n\n/**\n * 校验一份 submit 请求（设计 §5.6 的入口契约）：profile 交公共解析器；prompt 非空且\n * UTF-8 ≤ 256 KiB；deadlineAt 非空时必须是安全整数；metadata 非空时必须是 JSON 可\n * 序列化对象。返回冻结的规范化副本。\n */\nexport function parseAgentTaskSchedulerSubmitV1(\n\tvalue: unknown,\n): AgentTaskSchedulerParseResultV1<AgentTaskSchedulerSubmitV1> {\n\tif (!isPlainRecord(value)) return { ok: false, message: \"agent-task-scheduler submit must be an object\" };\n\tfor (const key of Object.keys(value)) {\n\t\tif (!SUBMIT_KEYS.has(key)) {\n\t\t\treturn { ok: false, message: `agent-task-scheduler submit has unknown key ${JSON.stringify(key)}` };\n\t\t}\n\t}\n\tif (value.version !== 1) {\n\t\treturn {\n\t\t\tok: false,\n\t\t\tmessage: `agent-task-scheduler submit version must be 1, found ${JSON.stringify(value.version)}`,\n\t\t};\n\t}\n\tconst prompt = value.prompt;\n\tif (typeof prompt !== \"string\" || prompt.trim() === \"\") {\n\t\treturn { ok: false, message: \"agent-task-scheduler submit prompt must be a non-empty string\" };\n\t}\n\tconst promptBytes = utf8ByteLength(prompt);\n\tif (promptBytes > AGENT_TASK_SCHEDULER_MAX_PROMPT_BYTES) {\n\t\treturn {\n\t\t\tok: false,\n\t\t\tmessage:\n\t\t\t\t`agent-task-scheduler submit prompt of ${promptBytes} UTF-8 bytes exceeds the ` +\n\t\t\t\t`${AGENT_TASK_SCHEDULER_MAX_PROMPT_BYTES}-byte limit`,\n\t\t};\n\t}\n\tconst parsedProfile = parseAgentTaskChildProfileV1(value.profile);\n\tif (!parsedProfile.ok)\n\t\treturn { ok: false, message: `agent-task-scheduler submit profile: ${parsedProfile.message}` };\n\tconst rawDeadlineAt = value.deadlineAt;\n\tif (rawDeadlineAt !== undefined && !Number.isSafeInteger(rawDeadlineAt)) {\n\t\treturn { ok: false, message: \"agent-task-scheduler submit deadlineAt must be a safe integer (epoch ms)\" };\n\t}\n\tlet metadata: Record<string, unknown> | undefined;\n\tconst rawMetadata = value.metadata;\n\tif (rawMetadata !== undefined) {\n\t\tif (!isPlainRecord(rawMetadata)) {\n\t\t\treturn { ok: false, message: \"agent-task-scheduler submit metadata must be an object\" };\n\t\t}\n\t\ttry {\n\t\t\tconst serialized = JSON.stringify(rawMetadata);\n\t\t\tif (serialized === undefined) {\n\t\t\t\treturn { ok: false, message: \"agent-task-scheduler submit metadata must be JSON-serializable\" };\n\t\t\t}\n\t\t} catch {\n\t\t\treturn { ok: false, message: \"agent-task-scheduler submit metadata must be JSON-serializable\" };\n\t\t}\n\t\tmetadata = rawMetadata;\n\t}\n\treturn {\n\t\tok: true,\n\t\tvalue: Object.freeze({\n\t\t\tversion: 1 as const,\n\t\t\tprompt,\n\t\t\tprofile: parsedProfile.profile,\n\t\t\t...(rawDeadlineAt === undefined ? {} : { deadlineAt: rawDeadlineAt as number }),\n\t\t\t...(metadata === undefined ? {} : { metadata }),\n\t\t}),\n\t};\n}\n\n/** 非空 taskId 的公共校验文本（status/result/cancel/drain 共用）。 */\nfunction parseTaskId(value: unknown): string | undefined {\n\tif (typeof value !== \"string\" || value.length === 0) return undefined;\n\treturn value;\n}\n\n/**\n * 校验一份能力目录请求（按 action 判别）：version 必须 1、action 必须在词汇表内；\n * submit 递归走 {@link parseAgentTaskSchedulerSubmitV1}；taskId 必须是非空字符串；\n * cancel.reason 是可选字符串、drain.timeoutMs 是可选正安全整数。返回冻结的规范化副本。\n */\nexport function parseAgentTaskSchedulerRequestV1(\n\tvalue: unknown,\n): AgentTaskSchedulerParseResultV1<AgentTaskSchedulerRequestV1> {\n\tif (!isPlainRecord(value)) return { ok: false, message: \"agent-task-scheduler request must be an object\" };\n\tif (value.version !== 1) {\n\t\treturn {\n\t\t\tok: false,\n\t\t\tmessage: `agent-task-scheduler request version must be 1, found ${JSON.stringify(value.version)}`,\n\t\t};\n\t}\n\tconst action = value.action;\n\tif (typeof action !== \"string\" || !REQUEST_ACTIONS.includes(action)) {\n\t\treturn {\n\t\t\tok: false,\n\t\t\tmessage: `agent-task-scheduler request action must be one of ${REQUEST_ACTIONS.join(\", \")}, found ${JSON.stringify(action)}`,\n\t\t};\n\t}\n\tif (action === \"submit\") {\n\t\tconst parsed = parseAgentTaskSchedulerSubmitV1(value.request);\n\t\tif (!parsed.ok) return parsed;\n\t\treturn {\n\t\t\tok: true,\n\t\t\tvalue: Object.freeze({ version: 1 as const, action: \"submit\" as const, request: parsed.value }),\n\t\t};\n\t}\n\tconst taskId = parseTaskId(value.taskId);\n\tif (taskId === undefined) {\n\t\treturn { ok: false, message: `agent-task-scheduler ${action} requires a non-empty taskId string` };\n\t}\n\tif (action === \"status\") {\n\t\treturn { ok: true, value: Object.freeze({ version: 1 as const, action: \"status\" as const, taskId }) };\n\t}\n\tif (action === \"result\") {\n\t\treturn { ok: true, value: Object.freeze({ version: 1 as const, action: \"result\" as const, taskId }) };\n\t}\n\tif (action === \"cancel\") {\n\t\tconst reason = value.reason;\n\t\tif (reason !== undefined && typeof reason !== \"string\") {\n\t\t\treturn { ok: false, message: \"agent-task-scheduler cancel reason must be a string when present\" };\n\t\t}\n\t\treturn {\n\t\t\tok: true,\n\t\t\tvalue: Object.freeze({\n\t\t\t\tversion: 1 as const,\n\t\t\t\taction: \"cancel\" as const,\n\t\t\t\ttaskId,\n\t\t\t\t...(reason === undefined ? {} : { reason }),\n\t\t\t}),\n\t\t};\n\t}\n\tconst timeoutMs = value.timeoutMs;\n\tif (\n\t\ttimeoutMs !== undefined &&\n\t\t!(typeof timeoutMs === \"number\" && Number.isSafeInteger(timeoutMs) && timeoutMs > 0)\n\t) {\n\t\treturn {\n\t\t\tok: false,\n\t\t\tmessage: \"agent-task-scheduler drain timeoutMs must be a positive safe integer when present\",\n\t\t};\n\t}\n\treturn {\n\t\tok: true,\n\t\tvalue: Object.freeze({\n\t\t\tversion: 1 as const,\n\t\t\taction: \"drain\" as const,\n\t\t\ttaskId,\n\t\t\t...(timeoutMs === undefined ? {} : { timeoutMs }),\n\t\t}),\n\t};\n}\n"]}

package/dist/browser-fetch.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Browser-fetch capability contract（联网检索设计 §5.9, P1.5）.
+ *
+ * `agent-forge.browser.fetch@1` is a plugin-to-plugin service: a consumer asks
+ * `browser-playwright` to load a page with the shared browser profile and
+ * return bounded visible text. The capability never returns cookies,
+ * localStorage or auth files; profile storage stays inside the browser plugin.
+ *
+ * The request/result payloads are the public design contract. The capability
+ * response wraps them in an explicit `ok` union so a provider can report
+ * structured failures (`browser_profile_busy`, `browser_login_required`, …)
+ * without inventing an Error subclass that would not survive the capability
+ * boundary.
+ */
+export declare const BROWSER_FETCH_CAPABILITY_ID = "agent-forge.browser.fetch";
+export declare const BROWSER_FETCH_VERSION_V1 = 1;
+export declare const BROWSER_FETCH_MAX_TEXT_CHARS: number;
+export declare const BROWSER_FETCH_DEFAULT_TIMEOUT_MS = 30000;
+export declare const BROWSER_FETCH_MIN_TIMEOUT_MS = 1000;
+export declare const BROWSER_FETCH_MAX_TIMEOUT_MS = 120000;
+export declare const BROWSER_FETCH_MAX_TITLE_CHARS = 512;
+export declare const BROWSER_FETCH_MAX_ERROR_CHARS = 2048;
+export declare const BROWSER_PROFILE_NAME_MAX_CHARS = 64;
+export type BrowserFetchErrorCodeV1 = "browser_unavailable" | "browser_cancelled" | "browser_timeout" | "browser_fetch_failed" | "browser_profile_busy" | "browser_profile_invalid" | "browser_profile_missing" | "browser_login_required";
+export interface BrowserFetchRequestV1 {
+    readonly version: 1;
+    readonly url: string;
+    /** Named profile; default "default". Never a filesystem path. */
+    readonly profile?: string;
+    readonly timeoutMs?: number;
+}
+export interface BrowserFetchResultV1 {
+    readonly version: 1;
+    readonly finalUrl: string;
+    readonly title?: string;
+    /** Visible page text, bounded to {@link BROWSER_FETCH_MAX_TEXT_CHARS}. */
+    readonly text: string;
+    readonly truncated: boolean;
+}
+export interface BrowserFetchErrorV1 {
+    readonly code: BrowserFetchErrorCodeV1;
+    readonly message: string;
+}
+export type BrowserFetchCapabilityResponseV1 = {
+    readonly version: 1;
+    readonly ok: true;
+    readonly result: BrowserFetchResultV1;
+} | {
+    readonly version: 1;
+    readonly ok: false;
+    readonly error: BrowserFetchErrorV1;
+};
+/** Profile names are directory segments, never paths: no separators or dots-only names. */
+export declare function isValidBrowserProfileNameV1(value: unknown): value is string;
+export declare function parseBrowserFetchRequestV1(value: unknown): BrowserFetchRequestV1;
+export declare function parseBrowserFetchResultV1(value: unknown): BrowserFetchResultV1;
+export declare function parseBrowserFetchCapabilityResponseV1(value: unknown): BrowserFetchCapabilityResponseV1;
+//# sourceMappingURL=browser-fetch.d.ts.map

package/dist/browser-fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-fetch.d.ts","sourceRoot":"","sources":["../src/browser-fetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,eAAO,MAAM,2BAA2B,8BAA8B,CAAC;AACvE,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAC1C,eAAO,MAAM,4BAA4B,QAAY,CAAC;AACtD,eAAO,MAAM,gCAAgC,QAAS,CAAC;AACvD,eAAO,MAAM,4BAA4B,OAAQ,CAAC;AAClD,eAAO,MAAM,4BAA4B,SAAU,CAAC;AACpD,eAAO,MAAM,6BAA6B,MAAM,CAAC;AACjD,eAAO,MAAM,6BAA6B,OAAO,CAAC;AAClD,eAAO,MAAM,8BAA8B,KAAK,CAAC;AAajD,MAAM,MAAM,uBAAuB,GAChC,qBAAqB,GACrB,mBAAmB,GACnB,iBAAiB,GACjB,sBAAsB,GACtB,sBAAsB,GACtB,yBAAyB,GACzB,yBAAyB,GACzB,wBAAwB,CAAC;AAE5B,MAAM,WAAW,qBAAqB;IACrC,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,oBAAoB;IACpC,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,MAAM,gCAAgC,GACzC;IAAE,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAA;CAAE,GACjF;IAAE,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAA;CAAE,CAAC;AAepF,2FAA2F;AAC3F,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAS3E;AAED,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,GAAG,qBAAqB,CA8BhF;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,oBAAoB,CA2B9E;AAED,wBAAgB,qCAAqC,CAAC,KAAK,EAAE,OAAO,GAAG,gCAAgC,CA8BtG","sourcesContent":["/**\n * Browser-fetch capability contract（联网检索设计 §5.9, P1.5）.\n *\n * `agent-forge.browser.fetch@1` is a plugin-to-plugin service: a consumer asks\n * `browser-playwright` to load a page with the shared browser profile and\n * return bounded visible text. The capability never returns cookies,\n * localStorage or auth files; profile storage stays inside the browser plugin.\n *\n * The request/result payloads are the public design contract. The capability\n * response wraps them in an explicit `ok` union so a provider can report\n * structured failures (`browser_profile_busy`, `browser_login_required`, …)\n * without inventing an Error subclass that would not survive the capability\n * boundary.\n */\n\nexport const BROWSER_FETCH_CAPABILITY_ID = \"agent-forge.browser.fetch\";\nexport const BROWSER_FETCH_VERSION_V1 = 1;\nexport const BROWSER_FETCH_MAX_TEXT_CHARS = 16 * 1024;\nexport const BROWSER_FETCH_DEFAULT_TIMEOUT_MS = 30_000;\nexport const BROWSER_FETCH_MIN_TIMEOUT_MS = 1_000;\nexport const BROWSER_FETCH_MAX_TIMEOUT_MS = 120_000;\nexport const BROWSER_FETCH_MAX_TITLE_CHARS = 512;\nexport const BROWSER_FETCH_MAX_ERROR_CHARS = 2048;\nexport const BROWSER_PROFILE_NAME_MAX_CHARS = 64;\n\nconst BROWSER_FETCH_ERROR_CODES: ReadonlySet<string> = new Set<string>([\n\t\"browser_unavailable\",\n\t\"browser_cancelled\",\n\t\"browser_timeout\",\n\t\"browser_fetch_failed\",\n\t\"browser_profile_busy\",\n\t\"browser_profile_invalid\",\n\t\"browser_profile_missing\",\n\t\"browser_login_required\",\n]);\n\nexport type BrowserFetchErrorCodeV1 =\n\t| \"browser_unavailable\"\n\t| \"browser_cancelled\"\n\t| \"browser_timeout\"\n\t| \"browser_fetch_failed\"\n\t| \"browser_profile_busy\"\n\t| \"browser_profile_invalid\"\n\t| \"browser_profile_missing\"\n\t| \"browser_login_required\";\n\nexport interface BrowserFetchRequestV1 {\n\treadonly version: 1;\n\treadonly url: string;\n\t/** Named profile; default \"default\". Never a filesystem path. */\n\treadonly profile?: string;\n\treadonly timeoutMs?: number;\n}\n\nexport interface BrowserFetchResultV1 {\n\treadonly version: 1;\n\treadonly finalUrl: string;\n\treadonly title?: string;\n\t/** Visible page text, bounded to {@link BROWSER_FETCH_MAX_TEXT_CHARS}. */\n\treadonly text: string;\n\treadonly truncated: boolean;\n}\n\nexport interface BrowserFetchErrorV1 {\n\treadonly code: BrowserFetchErrorCodeV1;\n\treadonly message: string;\n}\n\nexport type BrowserFetchCapabilityResponseV1 =\n\t| { readonly version: 1; readonly ok: true; readonly result: BrowserFetchResultV1 }\n\t| { readonly version: 1; readonly ok: false; readonly error: BrowserFetchErrorV1 };\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction isHttpUrl(value: string): boolean {\n\ttry {\n\t\tconst url = new URL(value);\n\t\treturn url.protocol === \"http:\" || url.protocol === \"https:\";\n\t} catch {\n\t\treturn false;\n\t}\n}\n\n/** Profile names are directory segments, never paths: no separators or dots-only names. */\nexport function isValidBrowserProfileNameV1(value: unknown): value is string {\n\treturn (\n\t\ttypeof value === \"string\" &&\n\t\tvalue.length > 0 &&\n\t\tvalue.length <= BROWSER_PROFILE_NAME_MAX_CHARS &&\n\t\t/^[a-z0-9][a-z0-9._-]*$/.test(value) &&\n\t\tvalue !== \".\" &&\n\t\tvalue !== \"..\"\n\t);\n}\n\nexport function parseBrowserFetchRequestV1(value: unknown): BrowserFetchRequestV1 {\n\tif (!isRecord(value)) throw new TypeError(\"browser.fetch request must be an object\");\n\tfor (const key of Object.keys(value)) {\n\t\tif (key !== \"version\" && key !== \"url\" && key !== \"profile\" && key !== \"timeoutMs\") {\n\t\t\tthrow new TypeError(`browser.fetch request has unknown key ${JSON.stringify(key)}`);\n\t\t}\n\t}\n\tif (value.version !== 1)\n\t\tthrow new TypeError(`browser.fetch request version must be 1, got ${String(value.version)}`);\n\tif (typeof value.url !== \"string\" || value.url.length === 0 || value.url.length > 2048 || !isHttpUrl(value.url)) {\n\t\tthrow new TypeError(\"browser.fetch request url must be an http(s) URL of at most 2048 characters\");\n\t}\n\tconst profile = value.profile === undefined ? \"default\" : value.profile;\n\tif (!isValidBrowserProfileNameV1(profile)) {\n\t\tthrow new TypeError(\n\t\t\t`browser.fetch request profile must match [a-z0-9][a-z0-9._-]* and be at most ${BROWSER_PROFILE_NAME_MAX_CHARS} characters`,\n\t\t);\n\t}\n\tconst timeoutMs = value.timeoutMs === undefined ? BROWSER_FETCH_DEFAULT_TIMEOUT_MS : value.timeoutMs;\n\tif (\n\t\ttypeof timeoutMs !== \"number\" ||\n\t\t!Number.isInteger(timeoutMs) ||\n\t\ttimeoutMs < BROWSER_FETCH_MIN_TIMEOUT_MS ||\n\t\ttimeoutMs > BROWSER_FETCH_MAX_TIMEOUT_MS\n\t) {\n\t\tthrow new TypeError(\n\t\t\t`browser.fetch request timeoutMs must be an integer between ${BROWSER_FETCH_MIN_TIMEOUT_MS} and ${BROWSER_FETCH_MAX_TIMEOUT_MS}`,\n\t\t);\n\t}\n\treturn { version: 1, url: value.url, profile, timeoutMs };\n}\n\nexport function parseBrowserFetchResultV1(value: unknown): BrowserFetchResultV1 {\n\tif (!isRecord(value)) throw new TypeError(\"browser.fetch result must be an object\");\n\tif (value.version !== 1) throw new TypeError(`browser.fetch result version must be 1, got ${String(value.version)}`);\n\tif (typeof value.finalUrl !== \"string\" || !isHttpUrl(value.finalUrl)) {\n\t\tthrow new TypeError(\"browser.fetch result finalUrl must be an http(s) URL\");\n\t}\n\tif (\n\t\tvalue.title !== undefined &&\n\t\t(typeof value.title !== \"string\" || value.title.length > BROWSER_FETCH_MAX_TITLE_CHARS)\n\t) {\n\t\tthrow new TypeError(\n\t\t\t`browser.fetch result title must be a string of at most ${BROWSER_FETCH_MAX_TITLE_CHARS} characters`,\n\t\t);\n\t}\n\tif (typeof value.text !== \"string\" || value.text.length > BROWSER_FETCH_MAX_TEXT_CHARS) {\n\t\tthrow new TypeError(\n\t\t\t`browser.fetch result text must be a string of at most ${BROWSER_FETCH_MAX_TEXT_CHARS} characters`,\n\t\t);\n\t}\n\tif (typeof value.truncated !== \"boolean\") throw new TypeError(\"browser.fetch result truncated must be a boolean\");\n\treturn {\n\t\tversion: 1,\n\t\tfinalUrl: value.finalUrl,\n\t\t...(value.title === undefined ? {} : { title: value.title }),\n\t\ttext: value.text,\n\t\ttruncated: value.truncated,\n\t};\n}\n\nexport function parseBrowserFetchCapabilityResponseV1(value: unknown): BrowserFetchCapabilityResponseV1 {\n\tif (!isRecord(value)) throw new TypeError(\"browser.fetch capability response must be an object\");\n\tif (value.version !== 1) {\n\t\tthrow new TypeError(`browser.fetch capability response version must be 1, got ${String(value.version)}`);\n\t}\n\tif (value.ok === true) {\n\t\treturn { version: 1, ok: true, result: parseBrowserFetchResultV1(value.result) };\n\t}\n\tif (value.ok === false) {\n\t\tconst error = value.error;\n\t\tif (!isRecord(error)) throw new TypeError(\"browser.fetch capability error must be an object\");\n\t\tif (typeof error.code !== \"string\" || !BROWSER_FETCH_ERROR_CODES.has(error.code)) {\n\t\t\tthrow new TypeError(`browser.fetch capability error has an unknown code ${JSON.stringify(error.code)}`);\n\t\t}\n\t\tif (\n\t\t\ttypeof error.message !== \"string\" ||\n\t\t\terror.message.length === 0 ||\n\t\t\terror.message.length > BROWSER_FETCH_MAX_ERROR_CHARS\n\t\t) {\n\t\t\tthrow new TypeError(\n\t\t\t\t`browser.fetch capability error message must be 1..${BROWSER_FETCH_MAX_ERROR_CHARS} characters`,\n\t\t\t);\n\t\t}\n\t\treturn {\n\t\t\tversion: 1,\n\t\t\tok: false,\n\t\t\terror: { code: error.code as BrowserFetchErrorCodeV1, message: error.message },\n\t\t};\n\t}\n\tthrow new TypeError(\"browser.fetch capability response ok must be a boolean\");\n}\n"]}

package/dist/browser-fetch.js

@@ -0,0 +1,135 @@
+/**
+ * Browser-fetch capability contract（联网检索设计 §5.9, P1.5）.
+ *
+ * `agent-forge.browser.fetch@1` is a plugin-to-plugin service: a consumer asks
+ * `browser-playwright` to load a page with the shared browser profile and
+ * return bounded visible text. The capability never returns cookies,
+ * localStorage or auth files; profile storage stays inside the browser plugin.
+ *
+ * The request/result payloads are the public design contract. The capability
+ * response wraps them in an explicit `ok` union so a provider can report
+ * structured failures (`browser_profile_busy`, `browser_login_required`, …)
+ * without inventing an Error subclass that would not survive the capability
+ * boundary.
+ */
+export const BROWSER_FETCH_CAPABILITY_ID = "agent-forge.browser.fetch";
+export const BROWSER_FETCH_VERSION_V1 = 1;
+export const BROWSER_FETCH_MAX_TEXT_CHARS = 16 * 1024;
+export const BROWSER_FETCH_DEFAULT_TIMEOUT_MS = 30_000;
+export const BROWSER_FETCH_MIN_TIMEOUT_MS = 1_000;
+export const BROWSER_FETCH_MAX_TIMEOUT_MS = 120_000;
+export const BROWSER_FETCH_MAX_TITLE_CHARS = 512;
+export const BROWSER_FETCH_MAX_ERROR_CHARS = 2048;
+export const BROWSER_PROFILE_NAME_MAX_CHARS = 64;
+const BROWSER_FETCH_ERROR_CODES = new Set([
+    "browser_unavailable",
+    "browser_cancelled",
+    "browser_timeout",
+    "browser_fetch_failed",
+    "browser_profile_busy",
+    "browser_profile_invalid",
+    "browser_profile_missing",
+    "browser_login_required",
+]);
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isHttpUrl(value) {
+    try {
+        const url = new URL(value);
+        return url.protocol === "http:" || url.protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}
+/** Profile names are directory segments, never paths: no separators or dots-only names. */
+export function isValidBrowserProfileNameV1(value) {
+    return (typeof value === "string" &&
+        value.length > 0 &&
+        value.length <= BROWSER_PROFILE_NAME_MAX_CHARS &&
+        /^[a-z0-9][a-z0-9._-]*$/.test(value) &&
+        value !== "." &&
+        value !== "..");
+}
+export function parseBrowserFetchRequestV1(value) {
+    if (!isRecord(value))
+        throw new TypeError("browser.fetch request must be an object");
+    for (const key of Object.keys(value)) {
+        if (key !== "version" && key !== "url" && key !== "profile" && key !== "timeoutMs") {
+            throw new TypeError(`browser.fetch request has unknown key ${JSON.stringify(key)}`);
+        }
+    }
+    if (value.version !== 1)
+        throw new TypeError(`browser.fetch request version must be 1, got ${String(value.version)}`);
+    if (typeof value.url !== "string" || value.url.length === 0 || value.url.length > 2048 || !isHttpUrl(value.url)) {
+        throw new TypeError("browser.fetch request url must be an http(s) URL of at most 2048 characters");
+    }
+    const profile = value.profile === undefined ? "default" : value.profile;
+    if (!isValidBrowserProfileNameV1(profile)) {
+        throw new TypeError(`browser.fetch request profile must match [a-z0-9][a-z0-9._-]* and be at most ${BROWSER_PROFILE_NAME_MAX_CHARS} characters`);
+    }
+    const timeoutMs = value.timeoutMs === undefined ? BROWSER_FETCH_DEFAULT_TIMEOUT_MS : value.timeoutMs;
+    if (typeof timeoutMs !== "number" ||
+        !Number.isInteger(timeoutMs) ||
+        timeoutMs < BROWSER_FETCH_MIN_TIMEOUT_MS ||
+        timeoutMs > BROWSER_FETCH_MAX_TIMEOUT_MS) {
+        throw new TypeError(`browser.fetch request timeoutMs must be an integer between ${BROWSER_FETCH_MIN_TIMEOUT_MS} and ${BROWSER_FETCH_MAX_TIMEOUT_MS}`);
+    }
+    return { version: 1, url: value.url, profile, timeoutMs };
+}
+export function parseBrowserFetchResultV1(value) {
+    if (!isRecord(value))
+        throw new TypeError("browser.fetch result must be an object");
+    if (value.version !== 1)
+        throw new TypeError(`browser.fetch result version must be 1, got ${String(value.version)}`);
+    if (typeof value.finalUrl !== "string" || !isHttpUrl(value.finalUrl)) {
+        throw new TypeError("browser.fetch result finalUrl must be an http(s) URL");
+    }
+    if (value.title !== undefined &&
+        (typeof value.title !== "string" || value.title.length > BROWSER_FETCH_MAX_TITLE_CHARS)) {
+        throw new TypeError(`browser.fetch result title must be a string of at most ${BROWSER_FETCH_MAX_TITLE_CHARS} characters`);
+    }
+    if (typeof value.text !== "string" || value.text.length > BROWSER_FETCH_MAX_TEXT_CHARS) {
+        throw new TypeError(`browser.fetch result text must be a string of at most ${BROWSER_FETCH_MAX_TEXT_CHARS} characters`);
+    }
+    if (typeof value.truncated !== "boolean")
+        throw new TypeError("browser.fetch result truncated must be a boolean");
+    return {
+        version: 1,
+        finalUrl: value.finalUrl,
+        ...(value.title === undefined ? {} : { title: value.title }),
+        text: value.text,
+        truncated: value.truncated,
+    };
+}
+export function parseBrowserFetchCapabilityResponseV1(value) {
+    if (!isRecord(value))
+        throw new TypeError("browser.fetch capability response must be an object");
+    if (value.version !== 1) {
+        throw new TypeError(`browser.fetch capability response version must be 1, got ${String(value.version)}`);
+    }
+    if (value.ok === true) {
+        return { version: 1, ok: true, result: parseBrowserFetchResultV1(value.result) };
+    }
+    if (value.ok === false) {
+        const error = value.error;
+        if (!isRecord(error))
+            throw new TypeError("browser.fetch capability error must be an object");
+        if (typeof error.code !== "string" || !BROWSER_FETCH_ERROR_CODES.has(error.code)) {
+            throw new TypeError(`browser.fetch capability error has an unknown code ${JSON.stringify(error.code)}`);
+        }
+        if (typeof error.message !== "string" ||
+            error.message.length === 0 ||
+            error.message.length > BROWSER_FETCH_MAX_ERROR_CHARS) {
+            throw new TypeError(`browser.fetch capability error message must be 1..${BROWSER_FETCH_MAX_ERROR_CHARS} characters`);
+        }
+        return {
+            version: 1,
+            ok: false,
+            error: { code: error.code, message: error.message },
+        };
+    }
+    throw new TypeError("browser.fetch capability response ok must be a boolean");
+}
+//# sourceMappingURL=browser-fetch.js.map