@webskill/sdk 0.0.6 → 0.1.1

package/README.md

@@ -9,22 +9,25 @@ governance.
 ## Features
 
 - **Skill protocol** — Agent Skills compatible discovery, validation, cataloging
-  (JSON / XML), and safe per-skill file access.
+  (JSON / XML), declarative `dependencies` and `allowed-tools`, skill packs
+  (multi-skill zip export/import with integrity digests).
 - **Agent loop** — multi-turn tool calling with structured errors fed back to
-  the LLM, guardrails, lifecycle events, memory, and human interaction
-  (missing-parameter forms, confirmations, ask-user).
-- **Script sandbox** — in-process Node executor plus a `worker_threads` sandbox;
-  Web Worker sandbox for the browser. Timeouts kill runaway scripts.
-- **Streaming** — OpenAI-compatible SSE streaming end to end, with incremental
-  UI updates.
+  the LLM, guardrails, lifecycle events, memory, human interaction
+  (missing-parameter forms, confirmations, authorization prompts), and
+  resumable interrupted runs.
+- **Script sandbox** — `worker_threads` sandbox for Node, Web Worker sandbox for
+  the browser. Deny-by-default network policy, per-capability forced approval,
+  timeouts kill runaway scripts.
+- **`navigator.webskill`** — a browser facade (`discover` / `read` / `validate` /
+  `run` / `install` / `uninstall`) assembled explicitly in one call.
 - **MCP** — call page-provided tools and consume page-declared dynamic skills
   over standard MCP transports (MessageChannel).
 - **Governance** — LLM-generated skill candidates with mandatory review,
   approval workflows, audit log, versioning/rollback, quarantine, evaluation,
   and scoring.
-- **UI** — framework-agnostic web forms, result rendering, generative UI
-  adapters (Vercel AI SDK, OpenUI, A2UI), plus React and Vue component
-  primitives.
+- **UI** — framework-agnostic forms, result rendering (markdown, tables, SVG
+  charts), generative UI adapters (Vercel AI SDK, OpenUI, A2UI), plus React and
+  Vue component primitives.
 
 ## Installation
 
@@ -35,53 +38,184 @@ npm install @webskill/sdk
 React/Vue integrations require their respective peer dependencies
 (`react` + `react-dom`, or `vue`), which are optional.
 
+## Requirements
+
+- Node.js >= 22.18 (native type stripping for `.ts` skill scripts)
+- Modern browsers for the browser host (OPFS, Web Workers, ES modules)
+
 ## Quick start (Node)
 
-```ts
-import { OpenAiCompatibleClient, WebSkillRuntime } from '@webskill/sdk';
-import { NodeFS, NodeScriptExecutor, FileArtifactStore } from '@webskill/sdk/node';
-
-const runtime = new WebSkillRuntime({
-  fs: new NodeFS(),
-  roots: ['./skills'],
-  llm: new OpenAiCompatibleClient({
-    baseUrl: 'https://your-llm-endpoint/v1',
-    apiKey: process.env.LLM_API_KEY!,
-    model: 'your-model'
-  }),
-  executor: new NodeScriptExecutor(new NodeFS()),
-  artifactStore: new FileArtifactStore({ root: './.webskill/artifacts' })
-});
+Runs as-is with the bundled mock LLM — see
+[`examples/quickstart-node`](../examples/quickstart-node) for the full project.
+
+```js
+import { WebSkillRuntime } from '@webskill/sdk';
+import { NodeFS, SandboxedScriptExecutor } from '@webskill/sdk/node';
+import { MockLlmClient } from '@webskill/sdk/testing';
+
+const fs = new NodeFS();
+const llm = new MockLlmClient([
+  { toolCalls: [{ id: 'c1', name: 'read_skill_file', arguments: { skillName: 'greeter' } }] },
+  { toolCalls: [{ id: 'c2', name: 'greeter__greet', arguments: { text: 'world' } }] },
+  { content: 'Greeted the world.' }
+]);
 
-// Discover skills and render the catalog
-const { entries, issues } = await runtime.discover();
-console.log(
-  entries.map((e) => e.name),
-  issues
-);
+const runtime = new WebSkillRuntime({ fs, roots: ['./skills'], llm, executor: new SandboxedScriptExecutor(fs) });
 
-// Run the agent loop
-const { output, run } = await runtime.run('Use the calculator skill to compute 2+3.');
+const catalog = await runtime.discover();
+console.log(catalog.entries.map((e) => e.name));
+
+const { output, run } = await runtime.run('Greet the world.');
 console.log(output, run.status, run.trace.length);
 ```
 
+For a real LLM, replace the mock with `OpenAiCompatibleClient`:
+
+```js
+import { OpenAiCompatibleClient } from '@webskill/sdk';
+
+const llm = new OpenAiCompatibleClient({
+  baseUrl: 'https://your-llm-endpoint/v1',
+  apiKey: process.env.LLM_API_KEY,
+  model: 'your-model'
+});
+```
+
 ## Subpath exports
 
-| Subpath                    | Contents                                                                                                             |
-| -------------------------- | -------------------------------------------------------------------------------------------------------------------- |
-| `@webskill/sdk`            | Core protocol + runtime engine (discovery, agent loop, LLM clients, routing, interaction, memory, artifacts, trace)  |
-| `@webskill/sdk/node`       | Node host: NodeFS, script executors (in-process + sandboxed), file stores, skill manager, CLI UI bridge, env helpers |
-| `@webskill/sdk/browser`    | Browser host: OPFS provider, Web Worker script sandbox, worker runtime host/client                                   |
-| `@webskill/sdk/mcp`        | MCP transports, endpoint registry, tool resolver, temporary skills, WebMCP adapter, runtime plugin                   |
-| `@webskill/sdk/ui`         | Framework-agnostic forms, result rendering, mini markdown, Vercel/OpenUI/A2UI adapters, A2UI Lit runtime             |
-| `@webskill/sdk/ui-react`   | React bridge state + InteractionForm/ResultBlocks/StreamingText components                                           |
-| `@webskill/sdk/ui-vue`     | Vue bridge state + equivalent components                                                                             |
-| `@webskill/sdk/governance` | Candidates, approval, audit, versioning, state policy, evaluation, scoring, documents                                |
+### `@webskill/sdk` (main entry)
 
-## Requirements
+Core protocol + runtime engine: discovery, catalog, validation, agent loop, LLM
+clients, routing, interaction types, memory, artifacts, tracing, network policy,
+capability approval, and the environment-agnostic `createWebSkillApi` facade.
 
-- Node.js >= 22.18 (native type stripping for `.ts` skill scripts)
-- Modern browsers for the browser host (OPFS, Web Workers, ES modules)
+```js
+import { SkillDiscovery, validateSkills, createWebSkillApi } from '@webskill/sdk';
+
+const api = createWebSkillApi({ fs, roots: ['./skills'], llm, skillManager });
+const report = await api.validate('./skills');
+const run = await api.run('Summarize the references of skill greeter.');
+```
+
+### `@webskill/sdk/node`
+
+Node host: `NodeFS`, script executors (in-process + `worker_threads` sandbox),
+file-backed stores, `SkillManager` (install/export incl. multi-skill packs),
+CLI UI bridge, schema inference.
+
+```js
+import { NodeFS, SkillManager } from '@webskill/sdk/node';
+
+const manager = new SkillManager({ managedRoot: './.webskill/skills' });
+await manager.install({ type: 'http', url: 'https://example.com/greeter.zip' });
+await manager.exportPack(['greeter', 'calculator'], { outPath: './pack.zip' });
+console.log((await manager.verifyIntegrity('greeter')).ok);
+```
+
+### `@webskill/sdk/browser`
+
+Browser host: OPFS provider, Web Worker script sandbox (deny-by-default network
+policy), worker runtime host/client, `BrowserSkillManager`, and the
+`navigator.webskill` assembler. See
+[`examples/quickstart-browser`](../examples/quickstart-browser).
+
+```js
+import { installWebSkillNavigator } from '@webskill/browser';
+
+const api = installWebSkillNavigator({ roots: ['/skills'], llm });
+const catalog = await navigator.webskill.discover('/skills');
+const run = await navigator.webskill.run('Greet the world.');
+```
+
+### `@webskill/sdk/mcp`
+
+MCP integration: MessageChannel transport, endpoint registry, tool resolver,
+temporary (page-declared) skills, WebMCP adapter, runtime plugin.
+
+```js
+import { MessageChannelTransport, serveSkillAsMcp } from '@webskill/sdk/mcp';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+const server = new McpServer({ name: 'page', version: '0.1.0' });
+serveSkillAsMcp(server, { name: 'greeter', description: 'Greet someone', body: '# Greeter' });
+await server.connect(new MessageChannelTransport(port));
+```
+
+### `@webskill/sdk/ui`
+
+Framework-agnostic UI: form models + `WebFormBridge`, result rendering
+(markdown / table / mini-chart SVG), mini markdown, generative UI adapters
+(Vercel AI SDK, OpenUI, A2UI).
+
+```js
+import { WebFormBridge } from '@webskill/sdk/ui';
+
+const bridge = new WebFormBridge({ mount: document.querySelector('#ui') });
+// pass as uiBridge to the runtime: forms, confirmations, and authorization
+// prompts render as real DOM, results (incl. charts) render on completion.
+```
+
+### `@webskill/sdk/ui-react`
+
+React bridge state + `InteractionForm` / `ResultBlocks` / `StreamingText`
+components (requires `react` + `react-dom`).
+
+```jsx
+import { ReactBridgeState, InteractionForm, ResultBlocks } from '@webskill/sdk/ui-react';
+
+const bridge = new ReactBridgeState();
+// <InteractionForm bridge={bridge} /> <ResultBlocks bridge={bridge} />
+```
+
+### `@webskill/sdk/ui-vue`
+
+Vue bridge state + equivalent components (requires `vue`).
+
+```js
+import { VueBridgeState, InteractionForm, ResultBlocks } from '@webskill/sdk/ui-vue';
+
+const bridge = new VueBridgeState();
+// <InteractionForm :bridge="bridge" /> <ResultBlocks :bridge="bridge" />
+```
+
+### `@webskill/sdk/governance`
+
+Governance: skill candidates with mandatory review, approval workflows, audit
+log, versioning/rollback, quarantine, evaluation, scoring, dependency graph.
+
+```js
+import { DependencyGraph } from '@webskill/sdk/governance';
+
+const graph = DependencyGraph.buildFromCatalog(catalog.entries, documents);
+console.log(graph.dependenciesOf('greeter'));
+```
+
+### `@webskill/sdk/testing`
+
+Test facilities (moved out of the main entry in 0.1.0): `MockLlmClient`,
+`MockUiBridge`, `InMemoryStore`, `MemoryArtifactStore`.
+
+```js
+import { MockLlmClient, MockUiBridge, InMemoryStore, MemoryArtifactStore } from '@webskill/sdk/testing';
+
+const llm = new MockLlmClient([{ content: 'deterministic answer' }]);
+```
+
+## Stability
+
+This package follows semver starting at 0.1.0. Public symbols carry JSDoc
+stability tags:
+
+- **`@stable`** — covered by the semver contract: bug fixes ship in patch,
+  backwards-compatible capabilities in minor, breaking changes only in major
+  (with release notes).
+- **`@experimental`** — may change in minor/patch releases. Currently:
+  `ExperimentalWebMcpAdapter`, `resumeRun` and the `RunSnapshot` format,
+  the A2UI/OpenUI adapters, and the `authorize` interaction type.
+
+The public API surface of every subpath is pinned by checked-in `.d.ts`
+snapshots (`api-snapshots/`); any intentional change requires
+`pnpm api:update` and is reviewable in the diff.
 
 ## License
 

package/dist/browser.d.ts

@@ -1,4 +1,5 @@
-import { A as InteractionPolicy, B as LlmResponse, Et as UiBridge, Ht as parseBridgeRequest, L as LlmClient, M as InteractionResponse, Ot as WebSkillApi, V as LlmStreamEvent, Xt as FileSystemProvider, Yt as FileStat, Z as NetworkPolicy, _t as ScriptExecutor, b as ExternalToolSource, c as ApprovalScope, cn as SkillInstallSource, d as BridgeCapabilities, dn as SkillManifest, gn as SkillsLockfile, gt as ScriptExecutionContext, j as InteractionRequest, jt as bridgeError, m as BridgeResponse, ot as RenderResultRequest, p as BridgeRequest, vn as VerifyResult, xt as ToolResult, y as ExternalSkillProvider, yt as ToolDefinition } from "./index-DCifjtJx.js";
+import { H as SkillsLockfile, L as SkillManifest, P as SkillInstallSource, S as FileSystemProvider, W as VerifyResult, _ as RenderResultRequest, a as InteractionPolicy, c as LlmClient, d as LlmResponse, f as LlmStreamEvent, o as InteractionRequest, s as InteractionResponse, v as UiBridge, x as FileStat } from "./types-CgNC-oQu-Dq_A1yA-.js";
+import { K as ScriptExecutionContext, Y as ToolDefinition, Z as ToolResult, _ as ExternalToolSource, _t as parseBridgeRequest, c as ApprovalScope, d as BridgeRequest, f as BridgeResponse, g as ExternalSkillProvider, k as NetworkPolicy, l as BridgeCapabilities, ot as bridgeError, q as ScriptExecutor, rt as WebSkillApi } from "./index-oG5Nzgb9.js";
 //#region ../browser/dist/index.d.ts
 //#region src/fs/featureDetection.d.ts
 /** 检测当前环境是否可用 OPFS（navigator.storage.getDirectory） */
@@ -74,6 +75,7 @@ declare class TsTranspiler {
  * D5：浏览器技能安装（http(s) zip / ArrayBuffer；tar/git/npm → TOOL_UNSUPPORTED）。
  * 流程与 Node 对齐：staging → 解析 name → validateSkills（失败零残留）→ managed root →
  * manifest（WebCrypto sha256）→ skills.lock.json；zip-slip 防护；manifest/lockfile 与 Node 同格式。
+ * @stable
  */
 declare class BrowserSkillManager {
   #private;
@@ -119,6 +121,7 @@ type WorkerFactory = () => WorkerLike;
 /**
  * Web Worker 脚本沙箱执行器：loadDefinition 与 execute 都在 Worker 内完成，
  * 主线程从不 import 技能脚本；每次执行独立 Worker；超时 terminate 强杀。
+ * @stable
  */
 declare class BrowserWorkerScriptExecutor implements ScriptExecutor {
   #private;
@@ -157,6 +160,7 @@ declare global {
  * BrowserSkillManager → createWebSkillApi；target 提供时挂 target.navigator
  * （缺失则补空对象），否则挂真实 navigator.webskill。
  * target 可注入（测试）；返回值即门面本体（挂载只是副作用）。
+ * @stable
  */
 declare function installWebSkillNavigator(config: {
   roots?: string[];

package/dist/browser.js

@@ -1,4 +1,6 @@
-import { D as createWebSkillApi, F as parseBridgeRequest, G as SKILL_PACK_FILE, H as SKILL_MANIFEST_FILE, J as WebSkillError, K as SkillDiscovery, M as mergeCatalogEntries, N as networkUrlHost, P as normalizeToolContent, V as SKILLS_LOCKFILE, X as buildManifest, Y as buildCatalog, _ as ProgressiveRouter, a as CapabilityApproval, at as parseSkillMarkdown, c as FsMemoryStore, dt as verifyManifest, g as OpenAiCompatibleClient, i as AgentLoop, j as isNetworkAllowed, l as FsRunSnapshotStore, lt as resolveInsideRoot, m as MockLlmClient, nt as isValidSkillName, ot as parseSkillPackManifest, s as FsArtifactStore, tt as exportSkills, ut as validateSkills, w as bridgeError, x as RUN_SNAPSHOT_SCHEMA_VERSION } from "./dist-nXiR40hi.js";
+import { D as verifyManifest, E as validateSkills, S as parseSkillPackManifest, T as resolveInsideRoot, _ as exportSkills, c as SkillDiscovery, d as buildCatalog, f as buildManifest, i as SKILL_MANIFEST_FILE, r as SKILLS_LOCKFILE, s as SKILL_PACK_FILE, u as WebSkillError, v as isValidSkillName, x as parseSkillMarkdown } from "./memoryArtifactStore-C9lFVqPF-U8nXvqL9.js";
+import { A as normalizeToolContent, C as createWebSkillApi, D as isNetworkAllowed, O as mergeCatalogEntries, _ as RUN_SNAPSHOT_SCHEMA_VERSION, a as CapabilityApproval, b as bridgeError, c as FsMemoryStore, f as OpenAiCompatibleClient, i as AgentLoop, j as parseBridgeRequest, k as networkUrlHost, l as FsRunSnapshotStore, p as ProgressiveRouter, s as FsArtifactStore } from "./dist-D5fsiETF.js";
+import { n as MockLlmClient } from "./testing-pn3NhXSV.js";
 import { unzipSync } from "fflate";
 
 //#region ../browser/dist/index.js
@@ -442,6 +444,7 @@ const lockfilePath = (root) => `${root}/${SKILLS_LOCKFILE}`;
 * D5：浏览器技能安装（http(s) zip / ArrayBuffer；tar/git/npm → TOOL_UNSUPPORTED）。
 * 流程与 Node 对齐：staging → 解析 name → validateSkills（失败零残留）→ managed root →
 * manifest（WebCrypto sha256）→ skills.lock.json；zip-slip 防护；manifest/lockfile 与 Node 同格式。
+* @stable
 */
 var BrowserSkillManager = class {
 	#fs;
@@ -496,6 +499,7 @@ var BrowserSkillManager = class {
 			} catch (e) {
 				throw new WebSkillError("INSTALL_FAILED", `Failed to read skill name from SKILL.md: ${messageOf$1(e)}`, e);
 			}
+			if (!isValidSkillName(name)) throw new WebSkillError("INSTALL_FAILED", `Invalid skill name in SKILL.md (path traversal rejected): ${JSON.stringify(name)}`);
 			const finalRoot = `${stagingRoot}/final`;
 			const finalDir = `${finalRoot}/${name}`;
 			await copyDir(fs, skillDir, finalDir);
@@ -537,6 +541,7 @@ var BrowserSkillManager = class {
 		try {
 			const versions = /* @__PURE__ */ new Map();
 			for (const entry of pack.manifest.skills) {
+				if (!isValidSkillName(entry.name)) throw new WebSkillError("INSTALL_FAILED", `Invalid skill name in skill pack manifest (path traversal rejected): ${JSON.stringify(entry.name)}`);
 				const skillDir = `${pack.contentDir}/${entry.name}`;
 				if (!await fs.exists(`${skillDir}/SKILL.md`)) throw new WebSkillError("INSTALL_FAILED", `Skill pack is missing a directory for skill "${entry.name}"`);
 				let name;
@@ -685,6 +690,7 @@ const messageOf = (e) => e instanceof Error ? e.message : String(e);
 /**
 * Web Worker 脚本沙箱执行器：loadDefinition 与 execute 都在 Worker 内完成，
 * 主线程从不 import 技能脚本；每次执行独立 Worker；超时 terminate 强杀。
+* @stable
 */
 var BrowserWorkerScriptExecutor = class {
 	#fs;
@@ -910,6 +916,7 @@ var BrowserWorkerScriptExecutor = class {
 * BrowserSkillManager → createWebSkillApi；target 提供时挂 target.navigator
 * （缺失则补空对象），否则挂真实 navigator.webskill。
 * target 可注入（测试）；返回值即门面本体（挂载只是副作用）。
+* @stable
 */
 function installWebSkillNavigator(config) {
 	const roots = config.roots ?? ["/skills"];
@@ -1132,7 +1139,7 @@ function startWorkerRuntimeHost(scope, overrides = {}) {
 					return [];
 				}
 			}))).flat();
-			const catalog = providerEntries.length > 0 ? { skills: mergeCatalogEntries(buildCatalog(entries).skills, providerEntries) } : buildCatalog(entries);
+			const catalog = providerEntries.length > 0 ? { entries: mergeCatalogEntries(buildCatalog(entries).entries, providerEntries) } : buildCatalog(entries);
 			const route = await new ProgressiveRouter().route(catalog);
 			const uiBridge = new WorkerUiBridge(scope);
 			activeUiBridge = uiBridge;

package/dist/{dist-33_zuOCm.js → dist-Cc3Mqi3_.js}

@@ -1,4 +1,5 @@
-import { F as parseBridgeRequest, G as SKILL_PACK_FILE, H as SKILL_MANIFEST_FILE, J as WebSkillError, N as networkUrlHost, P as normalizeToolContent, V as SKILLS_LOCKFILE, X as buildManifest, a as CapabilityApproval, at as parseSkillMarkdown, c as FsMemoryStore, dt as verifyManifest, j as isNetworkAllowed, lt as resolveInsideRoot, nt as isValidSkillName, ot as parseSkillPackManifest, s as FsArtifactStore, tt as exportSkills, ut as validateSkills, w as bridgeError } from "./dist-nXiR40hi.js";
+import { D as verifyManifest, E as validateSkills, S as parseSkillPackManifest, T as resolveInsideRoot, _ as exportSkills, f as buildManifest, i as SKILL_MANIFEST_FILE, r as SKILLS_LOCKFILE, s as SKILL_PACK_FILE, u as WebSkillError, v as isValidSkillName, x as parseSkillMarkdown } from "./memoryArtifactStore-C9lFVqPF-U8nXvqL9.js";
+import { A as normalizeToolContent, D as isNetworkAllowed, a as CapabilityApproval, b as bridgeError, c as FsMemoryStore, j as parseBridgeRequest, k as networkUrlHost, s as FsArtifactStore } from "./dist-D5fsiETF.js";
 import { unzipSync, zipSync } from "fflate";
 import { existsSync, promises, readFileSync } from "node:fs";
 import path from "node:path";
@@ -1126,6 +1127,7 @@ const asInstallFailed = (e) => e instanceof WebSkillError && e.code === "INSTALL
 /**
 * 技能管理门面：统一安装管线（staging → 解析 name → 校验 → 拷贝 → manifest → lockfile），
 * 任何失败清理现场抛 INSTALL_FAILED。
+* @stable
 */
 var SkillManager = class {
 	#managedRoot;
@@ -1176,6 +1178,7 @@ var SkillManager = class {
 			} catch (e) {
 				throw new WebSkillError("INSTALL_FAILED", `Failed to read skill name from SKILL.md: ${messageOf(e)}`, e);
 			}
+			if (!isValidSkillName(name)) throw new WebSkillError("INSTALL_FAILED", `Invalid skill name in SKILL.md (path traversal rejected): ${JSON.stringify(name)}`);
 			const finalRoot = `${stagingRoot}/final`;
 			const finalDir = `${finalRoot}/${name}`;
 			await copyDir(fs, staged.skillDir, finalDir);
@@ -1219,6 +1222,7 @@ var SkillManager = class {
 		try {
 			const versions = /* @__PURE__ */ new Map();
 			for (const entry of pack.manifest.skills) {
+				if (!isValidSkillName(entry.name)) throw new WebSkillError("INSTALL_FAILED", `Invalid skill name in skill pack manifest (path traversal rejected): ${JSON.stringify(entry.name)}`);
 				const skillDir = `${pack.contentDir}/${entry.name}`;
 				if (!await fs.exists(`${skillDir}/SKILL.md`)) throw new WebSkillError("INSTALL_FAILED", `Skill pack is missing a directory for skill "${entry.name}"`);
 				let name;