@webskill/sdk 0.2.7 → 0.3.0

package/README.md

@@ -49,6 +49,12 @@ npm install @webskill/sdk
 React/Vue integrations require their respective peer dependencies
 (`react` + `react-dom`, or `vue`), which are optional.
 
+`zod` ships as a direct dependency: the `@webskill/sdk/ui` catalog references it
+in its static import graph and in its public types, so declaring it optional
+would misrepresent the artifact. Hosts do not need to install it themselves.
+`tar`, `oxc-parser` and `@modelcontextprotocol/sdk` remain optional peers —
+they are loaded lazily and only when the corresponding API is called.
+
 ## Requirements
 
 - Node.js >= 22.18 (native type stripping for `.ts` skill scripts)
@@ -214,6 +220,42 @@ import { MockLlmClient, MockUiBridge, InMemoryStore, MemoryArtifactStore } from
 const llm = new MockLlmClient([{ content: 'deterministic answer' }]);
 ```
 
+## `allowed-tools`
+
+A skill may narrow the tool surface it needs by declaring `allowed-tools` in its
+`SKILL.md` frontmatter. Three kinds of tools can be listed:
+
+```yaml
+allowed-tools:
+  - render # a script of this skill (scripts/render.ts)
+  - endpoint:github/create_issue # one tool of an MCP endpoint
+  - endpoint:github/* # every tool of an MCP endpoint
+  - mcp#read_file # one page-provided (WebMCP) tool
+```
+
+Matching rules:
+
+- Only whole-entry matches and a trailing `/*` are supported. Wildcards in any
+  other position are not, and a bare `endpoint:github` is **not** a prefix
+  wildcard — it simply matches nothing.
+- A bare identifier means a script of the declaring skill only. It never grants
+  access to another skill's script of the same name.
+
+When several skills are active at the same time:
+
+| Situation                                | Result                                                                                                   |
+| ---------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| No active skill declares `allowed-tools` | Unrestricted                                                                                             |
+| At least one active skill declares it    | A tool is allowed if it matches any declaring skill's list, **or** if some active skill declares nothing |
+
+Enforcement level differs per tool kind in 0.3.0:
+
+- **Scripts** — enforced since 0.0.5: a script outside the list is not
+  registered, and calling it by name returns `TOOL_NOT_FOUND`.
+- **MCP / WebMCP tools** — 0.3.0 only records a `run.warning` naming the tool
+  and the entry to add, and still allows the call. This becomes a rejection in
+  0.4.0, so treat the warning as a build error in your own pipeline.
+
 ## Stability
 
 This package follows semver starting at 0.1.0. Public symbols carry JSDoc

package/dist/browser.d.ts

@@ -1,5 +1,5 @@
-import { K as SkillInstallSource, M as FileStat, N as FileSystemProvider, O as ArchiveLimits, Y as SkillManifest, _ as RenderResultRequest, a as InteractionPolicy, c as LlmClient, d as LlmResponse, et as SkillsLockfile, f as LlmStreamEvent, nt as VerifyResult, o as InteractionRequest, s as InteractionResponse, v as UiBridge } from "./types-7fnqDVrf-BnRQjVU3.js";
-import { Dt as parseBridgeRequest, N as NetworkPolicy, Q as ScriptExecutor, Z as ScriptExecutionContext, d as BridgeCapabilities, it as ToolResult, m as BridgeResponse, nt as ToolDefinition, p as BridgeRequest, pt as bridgeError, u as ApprovalScope, ut as WebSkillApi, v as ExternalSkillProvider, y as ExternalToolSource } from "./index-BpIK7tJM.js";
+import { $ as SkillInstallSource, N as FileStat, O as ArchiveLimits, P as FileSystemProvider, _ as RenderResultRequest, a as InteractionPolicy, c as LlmClient, d as LlmResponse, f as LlmStreamEvent, lt as SkillsLockfile, mt as VerifyResult, o as InteractionRequest, rt as SkillManifest, s as InteractionResponse, v as UiBridge } from "./types-AmKCKJn_-VGabeXK4.js";
+import { Ct as WebSkillApi, Et as bridgeError, F as NetworkPolicy, Vt as parseBridgeRequest, _t as ToolResult, ct as ScriptExecutor, d as BridgeCapabilities, ht as ToolDefinition, m as BridgeResponse, p as BridgeRequest, st as ScriptExecutionContext, u as ApprovalScope, v as ExternalSkillProvider, y as ExternalToolSource } from "./index-8d-oEDww.js";
 //#region ../browser/dist/index.d.ts
 //#region src/fs/featureDetection.d.ts
 /** 检测当前环境是否可用 OPFS（navigator.storage.getDirectory） */
@@ -32,8 +32,9 @@ declare class OpfsProvider implements FileSystemProvider {
 /**
  * Worker 引导源码（字符串 → Blob URL → new Worker(url, {type:'module'})）。
  * 注意：内容为纯 JS，不能含反引号与 ${ 占位（外层用模板字符串内嵌）；
- * isNetworkAllowed/networkUrlHost 经函数源码注入（匹配逻辑单一来源在
- * runtime/sandbox/networkPolicy.ts，此处禁止复制实现）。
+ * isNetworkAllowed/networkUrlHost 经 networkPolicyLibSource() 注入（匹配逻辑单一来源在
+ * runtime/sandbox/networkPolicy.ts，此处禁止复制实现）。该辅助把函数源码绑定到固定变量名，
+ * 消费方生产构建压缩改名后仍可调用（0.2.8 C4）。
  *
  * 协议（宿主 ↔ Worker）：
  * - 宿主 → Worker：{type:'load', id, source, networkPolicy?} 请求加载脚本定义
@@ -296,6 +297,12 @@ type WorkerEvent = {
   type: 'text-delta';
   runId: string;
   delta: string;
+} |
+/** 不阻断 run 但宿主应当知晓的降级（如外部技能提供者报错导致技能缺失） */
+{
+  type: 'host-warning';
+  runId: string;
+  message: string;
 };
 /** Worker 内全局作用域最小接口（postMessage + 消息监听） */
 interface WorkerScopeLike {
@@ -336,6 +343,8 @@ interface WorkerRuntimeClientDeps {
   uiBridge?: UiBridge;
   /** 单次请求超时（默认 120_000ms）；超时返回结构化 error 响应（不 reject） */
   timeoutMs?: number;
+  /** 不阻断 run 的降级告警出口（默认 console.warn） */
+  onWarning?(runId: string, message: string): void;
 }
 /** 主线程客户端：init/run/cancel/status/dispose 的 Promise API + 交互转发 */
 declare class WorkerRuntimeClient {

package/dist/browser.js

@@ -1,6 +1,6 @@
-import { C as messageOf, D as readResponseWithLimit, E as parseSkillPackManifest, M as unzipWithLimits, N as validateSkills, P as verifyManifest, T as parseSkillMarkdown, b as exportSkills, c as SkillDiscovery, d as assertRemoteUrlAllowed, h as buildManifest, i as SKILL_MANIFEST_FILE, j as resolveInsideRoot, m as buildCatalog, p as atomicWriteText, r as SKILLS_LOCKFILE, s as SKILL_PACK_FILE, u as WebSkillError, x as isValidSkillName } from "./dist-BQzncxXg.js";
-import { C as bridgeError, E as createWebSkillApi, F as normalizeToolContent, I as normalizeToolError, L as parseBridgeRequest, M as mergeCatalogEntries, N as networkUrlHost, c as FsArtifactStore, h as ProgressiveRouter, i as AgentLoop, j as isNetworkAllowed, l as FsMemoryStore, m as OpenAiCompatibleClient, o as CapabilityApproval, u as FsRunSnapshotStore, y as RUN_SNAPSHOT_SCHEMA_VERSION } from "./dist-BdOW8N4V.js";
-import { n as MockLlmClient } from "./testing-BUoXvm1u.js";
+import { A as parseSkillMarkdown, B as unzipWithLimits, H as verifyManifest, L as resolveInsideRoot, M as readResponseWithLimit, O as messageOf, T as isValidSkillName, V as validateSkills, _ as atomicWriteText, f as SkillDiscovery, h as assertRemoteUrlAllowed, j as parseSkillPackManifest, m as WebSkillError, o as SKILLS_LOCKFILE, r as MANIFEST_EXCLUDED_FILES, s as SKILL_MANIFEST_FILE, u as SKILL_PACK_FILE, v as buildCatalog, w as exportSkills, y as buildManifest } from "./dist-8oQRa8Xz.js";
+import { A as createWebSkillApi, B as normalizeToolContent, D as bridgeError, H as parseBridgeRequest, I as mergeCatalogEntries, L as networkPolicyLibSource, V as normalizeToolError, _ as ProgressiveRouter, c as FsArtifactStore, g as OpenAiCompatibleClient, i as AgentLoop, l as FsMemoryStore, o as CapabilityApproval, u as FsRunSnapshotStore, x as RUN_SNAPSHOT_SCHEMA_VERSION } from "./dist-rorEJsNi.js";
+import { n as MockLlmClient } from "./testing-CsrG3XLz.js";
 
 //#region ../browser/dist/index.js
 /** 检测当前环境是否可用 OPFS（navigator.storage.getDirectory） */
@@ -157,8 +157,9 @@ var OpfsProvider = class {
 /**
 * Worker 引导源码（字符串 → Blob URL → new Worker(url, {type:'module'})）。
 * 注意：内容为纯 JS，不能含反引号与 ${ 占位（外层用模板字符串内嵌）；
-* isNetworkAllowed/networkUrlHost 经函数源码注入（匹配逻辑单一来源在
-* runtime/sandbox/networkPolicy.ts，此处禁止复制实现）。
+* isNetworkAllowed/networkUrlHost 经 networkPolicyLibSource() 注入（匹配逻辑单一来源在
+* runtime/sandbox/networkPolicy.ts，此处禁止复制实现）。该辅助把函数源码绑定到固定变量名，
+* 消费方生产构建压缩改名后仍可调用（0.2.8 C4）。
 *
 * 协议（宿主 ↔ Worker）：
 * - 宿主 → Worker：{type:'load', id, source, networkPolicy?} 请求加载脚本定义
@@ -180,9 +181,7 @@ var pending = new Map();
 var bridgeSeq = 0;
 var networkPolicy = 'deny-all';
 
-${isNetworkAllowed.toString()}
-
-${networkUrlHost.toString()}
+${networkPolicyLibSource()}
 
 function resolveUrl(raw) {
   try {
@@ -703,10 +702,9 @@ var BrowserSkillManager = class {
 		}
 	}
 	async #createManifest(skillRoot, input) {
-		const excluded = /* @__PURE__ */ new Set([SKILL_MANIFEST_FILE, SKILLS_LOCKFILE]);
 		const files = [];
 		for (const rel of (await listFiles(this.#fs, skillRoot)).sort()) {
-			if (excluded.has(rel.split("/").pop() ?? "")) continue;
+			if (MANIFEST_EXCLUDED_FILES.has(rel.split("/").pop() ?? "")) continue;
 			const content = await this.#fs.readBinary(`${skillRoot}/${rel}`);
 			files.push({
 				path: rel,
@@ -1180,6 +1178,11 @@ function parseWorkerEvent(data) {
 		runId: data["runId"],
 		delta: data["delta"]
 	} : void 0;
+	if (data["type"] === "host-warning") return isNonEmptyString(data["runId"]) && isNonEmptyString(data["message"]) ? {
+		type: "host-warning",
+		runId: data["runId"],
+		message: data["message"]
+	} : void 0;
 	if (!isNonEmptyString(data["id"])) return;
 	switch (data["type"]) {
 		case "ready": return {
@@ -1499,10 +1502,12 @@ var WorkerRuntimeClient = class {
 	#timeoutMs;
 	#pending = /* @__PURE__ */ new Map();
 	#seq = 0;
+	#onWarning;
 	constructor(deps) {
 		this.#worker = deps.worker;
 		this.#uiBridge = deps.uiBridge;
 		this.#timeoutMs = deps.timeoutMs ?? 12e4;
+		this.#onWarning = deps.onWarning ?? ((runId, message) => console.warn(`[webskill] run ${runId}: ${message}`));
 		this.#worker.addEventListener("message", (event) => {
 			this.#onMessage(event.data);
 		});
@@ -1623,6 +1628,10 @@ var WorkerRuntimeClient = class {
 			await this.#uiBridge?.onTextDelta?.(event.runId, event.delta);
 			return;
 		}
+		if (event.type === "host-warning") {
+			this.#onWarning(event.runId, event.message);
+			return;
+		}
 		const pending = this.#pending.get(event.id);
 		if (pending) {
 			this.#pending.delete(event.id);