@webskill/sdk 0.11.0 → 0.13.0

package/dist/{dist-qnlI2Iup.js → dist-GK6dtjRv.js}

@@ -1,5 +1,5 @@
 import { M as messageOf, P as parseSkillMarkdown, g as assertRemoteUrlAllowed, h as WebSkillError, k as isValidSkillName } from "./dist-Bev6i6Ip.js";
-import { f as DEFAULT_MAX_DATA_SOURCE_BYTES } from "./dist-B-cOu08W.js";
+import { f as DEFAULT_MAX_DATA_SOURCE_BYTES } from "./dist-ExSQky4C.js";
 
 //#region ../agent/dist/index.js
 const STATUSES = [
@@ -108,7 +108,7 @@ const TODO_SYSTEM_PROMPT = [
 	"2. `update` an item to `in-progress` right before you start it, and to `completed` right after it succeeds.",
 	"3. Only one item may be `in-progress`; the runtime demotes the others automatically, so never rely on marking several.",
 	"4. Never mark an item `completed` before its work actually succeeded. If a step fails, keep it `in-progress` and explain.",
-	"5. `clear` the list once the whole request is answered, or when the user abandons it.",
+	"5. Settle every remaining item first (rule 4 still applies), then `clear` the list once the whole request is answered, or when the user abandons it.",
 	"",
 	"Skip the list for single-step requests, plain questions and trivial lookups — it only adds noise there."
 ].join("\n");
@@ -259,6 +259,7 @@ function createTodoToolSource(options = {}) {
 			inputSchema: INPUT_SCHEMA$4
 		}]),
 		canHandle: (name) => name === MANAGE_TODO_TOOL,
+		argCaptureTrust: (name) => name === "manage_todo" ? { tier: "reviewed" } : void 0,
 		call
 	};
 }
@@ -313,6 +314,69 @@ function previewOf(draft) {
 	return sections.join("\n\n");
 }
 /**
+* 工具名硬校（FR-30.4 / AC-30.8）。
+*
+* 只做**集合包含**：不比次数、不比顺序（AC-30.9），也不比参数（AC-30.10）。
+* 模型把参数泛化成占位符是正常的技能写法，机械比对会把正确的技能判失败。
+* 代价见需求 §7：工具名对、参数编得不对的情形本层拦不住，由确认卡兜底。
+*/
+function assertStepsAreBackedByTrace(draft, records) {
+	const claimed = draft.steps ?? [];
+	if (claimed.length === 0) return;
+	const executed = new Set(records.map((r) => r.tool));
+	const unknown = [...new Set(claimed.map((s) => s.tool).filter((tool) => !executed.has(tool)))];
+	if (unknown.length === 0) return;
+	fail(`The skill claims tools that were never called in this session: ${unknown.join(", ")}. Tools actually called: ${executed.size === 0 ? "(none)" : [...executed].sort().join(", ")}. Rewrite the skill using only the tools above.`, {
+		claimed: unknown,
+		executed: [...executed].sort()
+	});
+}
+/**
+* 超限步骤拒收（FR-30.2 / AC-30.3）。
+*
+* 留存超过体积上限时 `args` 是空的，只剩一个工具名。放它过去等于产出一个
+* 「知道调了什么、不知道传了什么」的步骤——那比没有这一步更糟，因为它看起来是完整的。
+* 同名工具只要还有一条没超限的记录就不算超限：那条记录足以说明参数长什么样。
+*/
+function assertStepsAreNotTruncated(draft, records) {
+	const claimed = draft.steps ?? [];
+	if (claimed.length === 0) return;
+	const usable = new Set(records.filter((r) => r.truncated !== true).map((r) => r.tool));
+	const truncated = [...new Set(claimed.map((s) => s.tool).filter((tool) => !usable.has(tool)))];
+	if (truncated.length === 0) return;
+	fail(`The arguments of these tool calls were too large to record, so the skill cannot state them: ${truncated.join(", ")}. Rewrite the skill without these steps.`, { truncated });
+}
+/**
+* 确认卡证据（AC-30.12 / AC-30.13）：逐条列出模型**写进技能的**步骤，
+* 并标注它是否有轨迹背书。轨迹里有而模型没写的步骤不出现在这里，
+* 也不会被补进 `SKILL.md`——生成的是模型的技能，不是会话的录像（AC-30.11）。
+*
+* 校验通过后每一步都有背书，所以 `'model'` 只会出现在**轨迹读不到**时：
+* 那种情况下不能把存储故障当成「模型在撞骗」而拦截，但必须在卡上说清楚
+* 这些步骤一步都没背书，否则用户会把未校验的草稿当成已核实的。
+*/
+function buildTraceEvidence(draft, records) {
+	const claimed = draft.steps ?? [];
+	if (claimed.length === 0) return void 0;
+	const byTool = /* @__PURE__ */ new Map();
+	for (const record of records ?? []) {
+		if (record.truncated === true || byTool.has(record.tool)) continue;
+		byTool.set(record.tool, record);
+	}
+	return { steps: claimed.map((step) => {
+		const record = byTool.get(step.tool);
+		return {
+			tool: step.tool,
+			evidence: record === void 0 ? "model" : "trace",
+			...record !== void 0 ? {
+				traceArgs: record.args,
+				redacted: record.redacted
+			} : {},
+			...step.args !== void 0 ? { draftArgs: step.args } : {}
+		};
+	}) };
+}
+/**
 * 技能自动生成策略。生成动作是策略而不是内核：它不进入 `AgentLoop`，
 * 而是经既有的 `ExternalToolSource` 扩展点接入（设计 02 §0）。
 *
@@ -337,18 +401,27 @@ var SkillGenerator = class {
 		if (!sink) throw new WebSkillError("SKILL_GENERATION_DISABLED", "Skill generation is enabled but this host did not provide a candidate store");
 		if (this.#used >= this.#maxPerSession) throw new WebSkillError("SKILL_GENERATION_LIMIT_EXCEEDED", `This session already generated ${this.#maxPerSession} skills, which is the configured limit`);
 		validateDraft(draft);
+		const sessionId = this.#options.sessionId?.();
+		const trace = await this.#readSteps(sessionId);
+		if (trace.available && trace.records !== void 0) {
+			assertStepsAreBackedByTrace(draft, trace.records);
+			assertStepsAreNotTruncated(draft, trace.records);
+		}
 		this.#used += 1;
+		const evidence = trace.available ? buildTraceEvidence(draft, trace.records) : void 0;
 		this.#requestSeq += 1;
 		const response = await this.#options.ui.request({
 			type: "authorize",
 			id: `skill-generation-${this.#requestSeq}`,
 			capability: "confirm",
 			message: this.#options.messages?.confirmSkill?.(draft) ?? defaultConfirmSkill(draft),
-			details: { preview: previewOf(draft) }
+			details: {
+				preview: previewOf(draft),
+				...evidence !== void 0 ? { traceEvidence: evidence } : {}
+			}
 		});
 		if (response.cancelled === true || response.value === false) return { status: "declined" };
 		const confirmedAt = (this.#options.now?.() ?? /* @__PURE__ */ new Date()).toISOString();
-		const sessionId = this.#options.sessionId?.();
 		const { id } = await sink.submit({
 			draft,
 			confirmedAt,
@@ -360,6 +433,24 @@ var SkillGenerator = class {
 			name: draft.name
 		};
 	}
+	/**
+	* 读不到轨迹（存储故障 / 没有会话号）时 `records` 为 `undefined`，含义是**不校验**，
+	* 而不是空数组（= 全部判失败）：存储故障不该表现成「模型在撒谎」。
+	* 真正跑了零个工具的会话由 `[]` 表达，那种情况该拦就拦。
+	*/
+	async #readSteps(sessionId) {
+		const reader = this.#options.steps;
+		if (reader === void 0) return { available: false };
+		if (sessionId === void 0) return { available: true };
+		try {
+			return {
+				available: true,
+				records: await reader.listBySession(sessionId)
+			};
+		} catch {
+			return { available: true };
+		}
+	}
 };
 /**
 * 技能自动生成的系统提示词。默认不注册工具，因此这段提示词只在
@@ -419,6 +510,25 @@ const INPUT_SCHEMA$3 = {
 				required: ["path", "content"],
 				additionalProperties: false
 			}
+		},
+		steps: {
+			type: "array",
+			description: "The tool calls this skill performs, in the order the SKILL.md describes them",
+			items: {
+				type: "object",
+				properties: {
+					tool: {
+						type: "string",
+						description: "The exact tool name, as it appeared in this conversation"
+					},
+					args: {
+						type: "object",
+						description: "The arguments this step passes to the tool"
+					}
+				},
+				required: ["tool"],
+				additionalProperties: false
+			}
 		}
 	},
 	required: [
@@ -441,11 +551,14 @@ function toolError$3(code, message) {
 function readDraft(args) {
 	const { name, description, content } = args;
 	if (typeof name !== "string" || typeof description !== "string" || typeof content !== "string") return "The \"name\", \"description\" and \"content\" arguments are required and must be strings";
+	const steps = readSteps(args["steps"]);
+	if (typeof steps === "string") return steps;
 	const rawFiles = args["files"];
 	if (rawFiles === void 0) return {
 		name,
 		description,
-		content
+		content,
+		...steps
 	};
 	if (!Array.isArray(rawFiles)) return "The \"files\" argument must be an array";
 	const files = [];
@@ -462,9 +575,28 @@ function readDraft(args) {
 		name,
 		description,
 		content,
-		files
+		files,
+		...steps
 	};
 }
+function readSteps(raw) {
+	if (raw === void 0) return {};
+	if (!Array.isArray(raw)) return "The \"steps\" argument must be an array";
+	const steps = [];
+	for (const entry of raw) {
+		if (typeof entry !== "object" || entry === null) return "Every entry in \"steps\" must be an object";
+		const record = entry;
+		const tool = record["tool"];
+		if (typeof tool !== "string" || tool.trim() === "") return "Every step needs a non-empty \"tool\" name";
+		const stepArgs = record["args"];
+		if (stepArgs !== void 0 && (typeof stepArgs !== "object" || stepArgs === null || Array.isArray(stepArgs))) return "A step's \"args\" must be an object";
+		steps.push({
+			tool,
+			...stepArgs !== void 0 ? { args: stepArgs } : {}
+		});
+	}
+	return { steps };
+}
 /**
 * 把技能自动生成接到既有的工具协议上（设计 02 §1.3）。
 *
@@ -511,6 +643,7 @@ function createSkillGenerationToolSource(options) {
 			inputSchema: INPUT_SCHEMA$3
 		}]),
 		canHandle: (name) => name === GENERATE_SKILL_TOOL,
+		argCaptureTrust: (name) => name === "generate_skill" ? { tier: "reviewed" } : void 0,
 		call
 	};
 }
@@ -713,6 +846,7 @@ function createDelegationToolSource(options) {
 			inputSchema: INPUT_SCHEMA$2
 		}]),
 		canHandle: (name) => name === DELEGATE_TASK_TOOL,
+		argCaptureTrust: (name) => name === "delegate_task" ? { tier: "reviewed" } : void 0,
 		call
 	};
 }
@@ -741,6 +875,30 @@ function withDelegationOrigin(bridge, origin) {
 	};
 }
 /**
+* 帧指称的展示形式（分册 18 FR-18.2）。
+*
+* 感知与操作两侧各自声明自己的 scope 类型（那是刻意的，见各自 types.ts），
+* 但「一条帧路径写成给人看的字符串」只能有一份实现——
+* 两处各写一遍，审计里的帧名和确认卡里的帧名就会慢慢对不上。
+*/
+/**
+* 帧路径的稳定展示串：`'self'` / `'#a'` / `'#a >>> #b'`。
+*
+* `>>>` **只是展示分隔符**：CSS 选择器里可以合法出现任意字符，
+* 反向解析这个串取回路径是不成立的，实现层一律传原始形状（D-18-1）。
+* @experimental
+*/
+function frameLabel(frame) {
+	if (typeof frame === "string") return frame;
+	if (frame.length === 0) return "self";
+	return frame.join(" >>> ");
+}
+/** 把两种形状归一成逐层选择器数组；`'self'` 与空数组都归一成空数组 @experimental */
+function frameSteps(frame) {
+	if (typeof frame === "string") return frame === "self" ? [] : [frame];
+	return frame;
+}
+/**
 * 两种形状归一成帧列表；旧形状等价于一条 `frame:'self'`（FR-24.1）。
 *
 * **这是判别的单一来源。** 散在各处写 `'frames' in scope` 会让
@@ -803,7 +961,7 @@ var PagePerceptionPolicy = class {
 			at: this.#options.now?.() ?? (/* @__PURE__ */ new Date()).toISOString(),
 			include: frames.flatMap((frame) => [...frame.include]),
 			exclude: frames.flatMap((frame) => [...frame.exclude ?? []]),
-			...frames.length > 1 || frames[0]?.frame !== "self" ? { frames: frames.map((frame) => frame.frame) } : {},
+			...frames.length > 1 || frames[0] !== void 0 && frameLabel(frames[0].frame) !== "self" ? { frames: frames.map((frame) => frameLabel(frame.frame)) } : {},
 			nodeCount: nodes.length,
 			...capture?.images === true ? {
 				images: {
@@ -894,13 +1052,15 @@ function createPagePerceptionToolSource(options) {
 		}] : []),
 		systemPrompt: () => Promise.resolve(policy.enabled ? PERCEPTION_SYSTEM_PROMPT : void 0),
 		canHandle: (name) => name === PERCEIVE_PAGE_TOOL,
+		argCaptureTrust: (name) => name === "perceive_page" ? { tier: "reviewed" } : void 0,
 		call: async () => {
 			try {
 				const budget = await options.imageCapture?.();
 				const capture = {
 					images: budget?.enabled === true,
 					maxImageBytes: budget?.maxImageBytes ?? 0,
-					maxImages: budget?.maxImages ?? 0
+					maxImages: budget?.maxImages ?? 0,
+					minImageArea: budget?.minImageArea ?? 0
 				};
 				const { nodes, images, imagesOmitted, record } = await policy.perceive(capture);
 				const data = {
@@ -1082,6 +1242,8 @@ const PAGE_ACTION_KINDS = [
 	"attach"
 ];
 const declineReason = "Page action was declined by the user.";
+/** 目标记忆的上限；它在 `act()` 之后立刻就被读走，容量只为防无界增长 */
+const TARGET_MEMO_LIMIT = 200;
 /**
 * 页面操作策略（需求 23）。
 *
@@ -1093,6 +1255,7 @@ var PageActionPolicy = class {
 	#options;
 	#records = [];
 	#seq = 0;
+	#targetByRef = /* @__PURE__ */ new Map();
 	constructor(options) {
 		this.#options = options;
 	}
@@ -1107,6 +1270,35 @@ var PageActionPolicy = class {
 	get records() {
 		return this.#records;
 	}
+	/**
+	* 目标是不是密码类控件（分册 30）。与确认卡上把值打成掩码用的是**同一个判定**，
+	* 不另立一套敏感字段清单。
+	*
+	* 读的是 `act()` 当时记下的结论而不是事后重查：提交或重绘后句柄会失效，
+	* 重查就会把一次普通填写误判成敏感、把内容丢掉。没操作过的句柄才现查，
+	* 查不到按敏感：不知道就别留存。
+	*/
+	isSecretTarget(ref) {
+		const remembered = this.#targetByRef.get(ref);
+		if (remembered !== void 0) return remembered.secret === true;
+		const target = this.#options.executor.describe(ref);
+		return target === void 0 || target.secret === true;
+	}
+	/**
+	* `act()` 当时看到的目标身份（分册 30）。句柄只在本次感知内有效，
+	* 只留句柄等于留了一个换次运行就失效的引用；角色与可访问名才是可重放的那部分。
+	*/
+	rememberedTarget(ref) {
+		return this.#targetByRef.get(ref);
+	}
+	#rememberTarget(ref, target) {
+		this.#targetByRef.delete(ref);
+		this.#targetByRef.set(ref, target);
+		if (this.#targetByRef.size > TARGET_MEMO_LIMIT) {
+			const oldest = this.#targetByRef.keys().next();
+			if (oldest.done !== true) this.#targetByRef.delete(oldest.value);
+		}
+	}
 	async act(request) {
 		if (!this.enabled) throw new WebSkillError("PAGE_ACTION_OUT_OF_SCOPE", "Page actions are not enabled: the host declared no actionable regions.");
 		const target = this.#options.executor.describe(request.ref);
@@ -1120,6 +1312,7 @@ var PageActionPolicy = class {
 			}, false);
 			throw new WebSkillError("PAGE_ACTION_DECLINED", declineReason);
 		}
+		this.#rememberTarget(request.ref, target);
 		const outcome = await this.#options.executor.execute(request);
 		await this.#record(request, outcome, approved);
 		return outcome;
@@ -1242,6 +1435,26 @@ function createPageActionToolSource(options) {
 		}] : []),
 		systemPrompt: () => Promise.resolve(policy.enabled ? PAGE_ACTION_SYSTEM_PROMPT : void 0),
 		canHandle: (name) => name === PAGE_ACTION_TOOL,
+		argCaptureTrust: (name, args) => {
+			if (name !== "act_on_page") return void 0;
+			const ref = args["ref"];
+			if (typeof ref !== "string") return { tier: "untrusted" };
+			return policy.isSecretTarget(ref) ? { tier: "untrusted" } : { tier: "reviewed" };
+		},
+		captureArgs: (name, args) => {
+			if (name !== "act_on_page") return void 0;
+			const ref = args["ref"];
+			const target = typeof ref === "string" ? policy.rememberedTarget(ref) : void 0;
+			if (target === void 0) return void 0;
+			return {
+				...args,
+				target: {
+					role: target.role,
+					...target.name !== void 0 ? { name: target.name } : {},
+					...target.frame !== void 0 ? { frame: target.frame } : {}
+				}
+			};
+		},
 		call: async (_name, args) => {
 			const ref = args["ref"];
 			const action = args["action"];
@@ -1277,4 +1490,4 @@ function createPageActionToolSource(options) {
 }
 
 //#endregion
-export { createTodoToolSource as C, withDelegationOrigin as E, createSkillGenerationToolSource as S, toFrameScopes as T, TodoStore as _, GENERATE_SKILL_TOOL as a, createPageActionToolSource as b, PAGE_ACTION_SYSTEM_PROMPT as c, PERCEPTION_SYSTEM_PROMPT as d, PageActionPolicy as f, TODO_SYSTEM_PROMPT as g, SkillGenerator as h, DelegationOrchestrator as i, PAGE_ACTION_TOOL as l, SKILL_GENERATION_SYSTEM_PROMPT as m, DELEGATION_SYSTEM_PROMPT as n, MANAGE_TODO_TOOL as o, PagePerceptionPolicy as p, DataSourcePolicy as r, PAGE_ACTION_KINDS as s, DELEGATE_TASK_TOOL as t, PERCEIVE_PAGE_TOOL as u, createDelegationToolSource as v, toActionFrameScopes as w, createPagePerceptionToolSource as x, createHttpDataSourceTransport as y };
+export { createTodoToolSource as C, toFrameScopes as D, toActionFrameScopes as E, withDelegationOrigin as O, createSkillGenerationToolSource as S, frameSteps as T, TodoStore as _, GENERATE_SKILL_TOOL as a, createPageActionToolSource as b, PAGE_ACTION_SYSTEM_PROMPT as c, PERCEPTION_SYSTEM_PROMPT as d, PageActionPolicy as f, TODO_SYSTEM_PROMPT as g, SkillGenerator as h, DelegationOrchestrator as i, PAGE_ACTION_TOOL as l, SKILL_GENERATION_SYSTEM_PROMPT as m, DELEGATION_SYSTEM_PROMPT as n, MANAGE_TODO_TOOL as o, PagePerceptionPolicy as p, DataSourcePolicy as r, PAGE_ACTION_KINDS as s, DELEGATE_TASK_TOOL as t, PERCEIVE_PAGE_TOOL as u, createDelegationToolSource as v, frameLabel as w, createPagePerceptionToolSource as x, createHttpDataSourceTransport as y };