@webskill/sdk 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chunhui Mo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,85 @@
+# @webskill/sdk
+
+WebSkill is an agent skill runtime for Node.js and the browser. Skills are
+self-contained directories (`SKILL.md` + `scripts/` + `references/` + `assets/`)
+that an LLM agent discovers, reads, and executes through a multi-turn agent loop
+with human-in-the-loop interaction, artifacts, tracing, MCP integration, and
+governance.
+
+## Features
+
+- **Skill protocol** — Agent Skills compatible discovery, validation, cataloging
+  (JSON / XML), and safe per-skill file access.
+- **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.
+- **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.
+
+## Installation
+
+```bash
+npm install @webskill/sdk
+```
+
+React/Vue integrations require their respective peer dependencies
+(`react` + `react-dom`, or `vue`), which are optional.
+
+## 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' }),
+});
+
+// Discover skills and render the catalog
+const { entries, issues } = await runtime.discover();
+console.log(entries.map((e) => e.name), issues);
+
+// Run the agent loop
+const { output, run } = await runtime.run('Use the calculator skill to compute 2+3.');
+console.log(output, run.status, run.trace.length);
+```
+
+## 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 |
+
+## Requirements
+
+- Node.js >= 22.18 (native type stripping for `.ts` skill scripts)
+- Modern browsers for the browser host (OPFS, Web Workers, ES modules)
+
+## License
+
+MIT

package/dist/browser.d.ts

@@ -0,0 +1,219 @@
+import { C as InteractionRequest, M as LlmResponse, Mt as FileSystemProvider, N as LlmStreamEvent, S as InteractionPolicy, X as RenderResultRequest, _t as bridgeError, ct as ToolResult, d as BridgeResponse, it as ScriptExecutor, jt as FileStat, k as LlmClient, l as BridgeCapabilities, m as ExternalToolSource, ot as ToolDefinition, p as ExternalSkillProvider, pt as UiBridge, rt as ScriptExecutionContext, u as BridgeRequest, w as InteractionResponse, wt as parseBridgeRequest } from "./index-88KNOnbr.js";
+//#region ../browser/dist/index.d.ts
+//#region src/fs/featureDetection.d.ts
+/** 检测当前环境是否可用 OPFS（navigator.storage.getDirectory） */
+declare function isOpfsAvailable(globalScope?: unknown): boolean;
+//#endregion
+//#region src/fs/opfsProvider.d.ts
+/** 基于 navigator.storage.getDirectory() 的 FileSystemProvider（路径一律 POSIX 风格） */
+declare class OpfsProvider implements FileSystemProvider {
+  #private;
+  readonly kind = "opfs";
+  constructor(deps?: {
+    rootName?: string;
+  });
+  readText(p: string): Promise<string>;
+  writeText(p: string, content: string): Promise<void>;
+  readBinary(p: string): Promise<Uint8Array>;
+  writeBinary(p: string, content: Uint8Array): Promise<void>;
+  exists(p: string): Promise<boolean>;
+  stat(p: string): Promise<FileStat>;
+  list(p: string): Promise<FileStat[]>;
+  mkdir(p: string): Promise<void>;
+  remove(p: string, options?: {
+    recursive?: boolean;
+  }): Promise<void>;
+}
+//#endregion
+//#region src/executor/workerBootstrap.d.ts
+/**
+ * Worker 引导源码（字符串 → Blob URL → new Worker(url, {type:'module'})）。
+ * 注意：内容为纯 JS，不能含反引号与 ${ 占位（外层用模板字符串内嵌）。
+ *
+ * 协议（宿主 ↔ Worker）：
+ * - 宿主 → Worker：{type:'load', id, source} 请求加载脚本定义
+ * - 宿主 → Worker：{type:'execute', id, skillName, runId, source, args} 请求执行
+ * - Worker → 宿主：{type:'load-result', id, ok, definition?, error?}
+ * - Worker → 宿主：{type:'execute-result', id, ok, value?, stdout, stderr, error?}
+ * - Worker → 宿主：{type:'bridge', request} 能力桥 RPC（readReference/writeArtifact/confirm）
+ * - 宿主 → Worker：{type:'bridge-response', response}
+ *
+ * .js 源码经 data: URL 动态 import；主线程从不 import 技能脚本。
+ */
+declare const WORKER_BOOTSTRAP_SOURCE: string;
+//#endregion
+//#region src/executor/workerScriptExecutor.d.ts
+/** 主线程持有的 Worker 最小接口（vitest 可用 loopback 替身） */
+interface WorkerLike {
+  postMessage(data: unknown): void;
+  addEventListener(type: 'message', listener: (event: {
+    data: unknown;
+  }) => void): void;
+  terminate(): void;
+}
+type WorkerFactory = () => WorkerLike;
+/**
+ * Web Worker 脚本沙箱执行器：loadDefinition 与 execute 都在 Worker 内完成，
+ * 主线程从不 import 技能脚本；每次执行独立 Worker；超时 terminate 强杀。
+ */
+declare class BrowserWorkerScriptExecutor implements ScriptExecutor {
+  #private;
+  constructor(deps: {
+    fs: FileSystemProvider;
+    workerFactory?: WorkerFactory;
+    capabilities?: BridgeCapabilities;
+  });
+  loadDefinition(skillRoot: string, scriptName: string): Promise<ToolDefinition>;
+  execute(input: {
+    skillRoot: string;
+    scriptName: string;
+    args: Record<string, unknown>;
+    context: ScriptExecutionContext;
+    timeoutMs: number;
+  }): Promise<ToolResult>;
+}
+//#endregion
+//#region src/host/protocol.d.ts
+/** 主线程 → Worker 的 LLM 配置；mockResponses 供 E2E/测试注入确定性 Mock */
+interface LlmClientConfig {
+  baseUrl?: string;
+  apiKey?: string;
+  model?: string;
+  mockResponses?: Array<LlmResponse | {
+    stream: LlmStreamEvent[];
+  }>;
+  /** Mock 流式开关（E2E 流式场景） */
+  mockStreaming?: boolean;
+}
+type WorkerRequest = {
+  type: 'init';
+  id: string;
+  config: {
+    llm: LlmClientConfig;
+    interaction?: InteractionPolicy;
+    roots?: string[];
+    /** OPFS 根目录名（默认 'webskill'）；测试隔离用 */
+    opfsRootName?: string;
+  };
+} | {
+  type: 'run';
+  id: string;
+  prompt: string;
+  runId?: string;
+} | {
+  type: 'cancel';
+  id: string;
+  runId: string;
+} | {
+  type: 'status';
+  id: string;
+  runId: string;
+};
+/** 主线程 → Worker 的交互应答 */
+interface InteractionResponseMessage {
+  type: 'interaction-response';
+  workerMessageId: string;
+  response: InteractionResponse;
+}
+type MainToWorkerMessage = WorkerRequest | InteractionResponseMessage;
+interface SerializedError {
+  code: string;
+  message: string;
+}
+/** Worker → 主线程 */
+type WorkerEvent = {
+  type: 'ready';
+  id: string;
+} | {
+  type: 'result';
+  id: string;
+  result?: unknown;
+  error?: SerializedError;
+} | {
+  type: 'interaction';
+  id: string;
+  workerMessageId: string;
+  request: InteractionRequest;
+} | {
+  type: 'render-result';
+  request: RenderResultRequest;
+} | {
+  type: 'text-delta';
+  runId: string;
+  delta: string;
+};
+/** Worker 内全局作用域最小接口（postMessage + 消息监听） */
+interface WorkerScopeLike {
+  postMessage(data: unknown): void;
+  addEventListener(type: 'message', listener: (event: {
+    data: unknown;
+  }) => void): void;
+}
+/** Worker 侧入站校验：非法消息返回 undefined（忽略） */
+declare function parseMainMessage(data: unknown): MainToWorkerMessage | undefined;
+/** 主线程侧入站校验 */
+declare function parseWorkerEvent(data: unknown): WorkerEvent | undefined;
+//#endregion
+//#region src/host/workerRuntimeHost.d.ts
+interface WorkerRuntimeHostOverrides {
+  /** 测试注入（loopback 用 MemoryFS）；缺省 OpfsProvider */
+  fs?: FileSystemProvider;
+  /** 测试注入确定性 LLM；缺省按 config 构造 OpenAiCompatibleClient/MockLlmClient */
+  createLlm?: (config: LlmClientConfig) => LlmClient;
+  /** 脚本沙箱 Worker 工厂（测试可注入 loopback 替身） */
+  workerFactory?: WorkerFactory;
+  /** 外部工具来源（MCP 插件等） */
+  externalTools?: ExternalToolSource[];
+  /** 外部技能提供者（页面动态技能等） */
+  skillProviders?: ExternalSkillProvider[];
+}
+/**
+ * Worker 内宿主（engine-in-worker）：
+ * 组合 fs + FsArtifactStore/FsMemoryStore + LlmClient + AgentLoop + 沙箱执行器；
+ * UiBridge 经 interaction/interaction-response 消息桥接主线程。
+ */
+declare function startWorkerRuntimeHost(scope: WorkerScopeLike, overrides?: WorkerRuntimeHostOverrides): void;
+//#endregion
+//#region src/host/workerClient.d.ts
+interface WorkerRuntimeClientDeps {
+  worker: WorkerLike;
+  /** 主线程真实 UiBridge：Worker 内 interaction 消息转发到这里 */
+  uiBridge?: UiBridge;
+  /** 单次请求超时（默认 120_000ms）；超时返回结构化 error 响应（不 reject） */
+  timeoutMs?: number;
+}
+/** 主线程客户端：init/run/cancel/status/dispose 的 Promise API + 交互转发 */
+declare class WorkerRuntimeClient {
+  #private;
+  constructor(deps: WorkerRuntimeClientDeps);
+  init(config: {
+    llm: LlmClientConfig;
+    interaction?: InteractionPolicy;
+    roots?: string[];
+    opfsRootName?: string;
+  }): Promise<WorkerEvent>;
+  run(prompt: string, runId?: string): Promise<WorkerEvent>;
+  status(runId: string): Promise<WorkerEvent>;
+  cancel(runId: string): Promise<WorkerEvent>;
+  dispose(): void;
+}
+//#endregion
+//#region src/ui/workerUiBridge.d.ts
+/**
+ * Worker 内 UiBridge：request → 'interaction' 消息到主线程，
+ * 挂起等待 'interaction-response' → resolve（行内 await 跨线程成立）。
+ * renderResult 为单向通知（'render-result' 消息，主线程页面桥消费）。
+ */
+declare class WorkerUiBridge implements UiBridge {
+  #private;
+  constructor(scope: WorkerScopeLike);
+  /** 宿主转发主线程的 interaction-response */
+  handleInteractionResponse(workerMessageId: string, response: InteractionResponse): void;
+  /** 取消全部挂起请求（cancel 语义：视为用户取消） */
+  cancelAll(): void;
+  request(input: InteractionRequest): Promise<InteractionResponse>;
+  renderResult(input: RenderResultRequest): Promise<void>;
+  onTextDelta(runId: string, delta: string): Promise<void>;
+}
+//#endregion
+export { type BridgeCapabilities, type BridgeRequest, type BridgeResponse, BrowserWorkerScriptExecutor, type LlmClientConfig, type MainToWorkerMessage, OpfsProvider, type SerializedError, WORKER_BOOTSTRAP_SOURCE, type WorkerEvent, type WorkerFactory, type WorkerLike, type WorkerRequest, WorkerRuntimeClient, type WorkerRuntimeClientDeps, type WorkerRuntimeHostOverrides, type WorkerScopeLike, WorkerUiBridge, bridgeError, isOpfsAvailable, parseBridgeRequest, parseMainMessage, parseWorkerEvent, startWorkerRuntimeHost };