@webskill/sdk 0.0.1

package/dist/index-88KNOnbr.d.ts

@@ -0,0 +1,955 @@
+//#region ../core/dist/index.d.ts
+//#region src/errors.d.ts
+type WebSkillErrorCode = 'FS_NOT_FOUND' | 'FS_PATH_OUTSIDE_ROOT' | 'SKILL_NOT_FOUND' | 'SKILL_INVALID_METADATA' | 'SKILL_INVALID_NAME' | 'SKILL_DUPLICATE_NAME' | 'SKILL_UNSUPPORTED_SCRIPT' | 'VALIDATION_FAILED' | 'TOOL_NOT_FOUND' | 'TOOL_EXECUTION_FAILED' | 'TOOL_UNSUPPORTED' | 'TOOL_SCHEMA_UNAVAILABLE' | 'RUN_TIMEOUT' | 'RUN_MAX_TURNS_EXCEEDED' | 'RUN_FAILED' | 'RUN_CANCELLED' | 'RUN_INTERACTION_TIMEOUT' | 'UI_UNAVAILABLE' | 'LLM_UNAVAILABLE' | 'LLM_REQUEST_FAILED' | 'INSTALL_FAILED' | 'UNINSTALL_FAILED' | 'EXPORT_FAILED' | 'INTEGRITY_FAILED' | 'FS_PERMISSION_DENIED' | 'MCP_ENDPOINT_UNAVAILABLE' | 'MCP_TOOL_NOT_FOUND' | 'CANDIDATE_INVALID' | 'APPROVAL_REQUIRED' | 'SKILL_QUARANTINED' | 'SKILL_DISABLED' | 'GOVERNANCE_FAILED';
+/** 所有公开 API 抛出的结构化错误，code 供上层可编程处理 */
+declare class WebSkillError extends Error {
+  readonly code: WebSkillErrorCode;
+  readonly details?: unknown;
+  constructor(code: WebSkillErrorCode, message: string, details?: unknown);
+}
+//#endregion
+//#region src/contracts/jsonSchema.d.ts
+/**
+ * 宽松 JSON Schema：覆盖工具 inputSchema 的常见字段，
+ * 索引签名允许透传规范内的其他关键字。供 tools 与后续 UI 复用。
+ */
+interface JsonSchema {
+  type?: string;
+  properties?: Record<string, JsonSchema>;
+  required?: string[];
+  items?: JsonSchema;
+  enum?: unknown[];
+  description?: string;
+  default?: unknown;
+  [key: string]: unknown;
+}
+//#endregion
+//#region src/fs/types.d.ts
+interface FileStat {
+  path: string;
+  type: 'file' | 'directory';
+  size?: number;
+  mtimeMs?: number;
+}
+/**
+ * 文件系统抽象：core 只依赖此接口，Node/浏览器各自提供实现。
+ * 路径一律使用 `/` 分隔的 POSIX 风格。
+ */
+interface FileSystemProvider {
+  readonly kind: string;
+  readText(path: string): Promise<string>;
+  writeText(path: string, content: string): Promise<void>;
+  readBinary(path: string): Promise<Uint8Array>;
+  writeBinary(path: string, content: Uint8Array): Promise<void>;
+  exists(path: string): Promise<boolean>;
+  stat(path: string): Promise<FileStat>;
+  list(path: string): Promise<FileStat[]>;
+  mkdir(path: string): Promise<void>;
+  remove(path: string, options?: {
+    recursive?: boolean;
+  }): Promise<void>;
+}
+//#endregion
+//#region src/fs/memoryFs.d.ts
+/** 内存文件系统：路径一律规范化为 `/` 分隔，写入自动创建父目录 */
+declare class MemoryFS implements FileSystemProvider {
+  #private;
+  readonly kind = "memory";
+  constructor();
+  readText(path: string): Promise<string>;
+  writeText(path: string, content: string): Promise<void>;
+  readBinary(path: string): Promise<Uint8Array>;
+  writeBinary(path: string, content: Uint8Array): Promise<void>;
+  exists(path: string): Promise<boolean>;
+  stat(path: string): Promise<FileStat>;
+  list(path: string): Promise<FileStat[]>;
+  mkdir(path: string): Promise<void>;
+  remove(path: string, options?: {
+    recursive?: boolean;
+  }): Promise<void>;
+}
+//#endregion
+//#region src/fs/pathSecurity.d.ts
+/** 统一分隔符为 `/`，去除 `.` 段与重复分隔符（不解析 `..`） */
+declare function normalizePath(path: string): string;
+/**
+ * 将相对路径安全地解析到 root 之内。
+ * 拒绝空路径、绝对路径（`/`、`\\`、`C:\` 形式）与任何 `..` 段。
+ */
+declare function resolveInsideRoot(root: string, relativePath: string): string;
+//#endregion
+//#region src/skill/types.d.ts
+type SkillSource = 'local' | 'mcp' | 'generated' | 'installed';
+/** SKILL.md frontmatter 元数据；未知字段原样透传 */
+interface SkillMetadata {
+  name: string;
+  description: string;
+  license?: string;
+  version?: string;
+  [key: string]: unknown;
+}
+interface SkillLocation {
+  skillRoot: string;
+  skillMdPath: string;
+  source: SkillSource;
+}
+interface SkillDocument {
+  metadata: SkillMetadata;
+  body: string;
+  location: SkillLocation;
+}
+/** Catalog 条目：渐进披露第一层，只含元数据摘要与标记位 */
+interface SkillCatalogEntry {
+  name: string;
+  description: string;
+  version?: string;
+  license?: string;
+  root: string;
+  source: SkillSource;
+  hasScripts: boolean;
+  hasReferences: boolean;
+  hasAssets: boolean;
+}
+interface SkillCatalog {
+  skills: SkillCatalogEntry[];
+}
+//#endregion
+//#region src/skill/parser.d.ts
+declare function parseSkillMarkdown(raw: string): {
+  metadata: SkillMetadata;
+  body: string;
+};
+//#endregion
+//#region src/skill/naming.d.ts
+declare const SKILL_NAME_MAX_LENGTH = 64;
+/** Agent Skills 官方命名规范：小写字母/数字/连字符，不允许首尾或连续连字符 */
+declare const SKILL_NAME_PATTERN: RegExp;
+declare function isValidSkillName(name: string): boolean;
+//#endregion
+//#region src/skill/rules.d.ts
+interface SkillIssue {
+  /** 与 WebSkillErrorCode 对齐 */
+  code: string;
+  severity: 'info' | 'warning' | 'error';
+  message: string;
+  path?: string;
+}
+/**
+ * 技能合规规则的唯一实现。SkillDiscovery 与 validateSkills 都必须调用本函数，
+ * 禁止各自重复实现规则（避免两套规则漂移）。
+ */
+declare function checkSkillRules(input: {
+  dirName: string;
+  hasSkillMd: boolean;
+  metadata?: SkillMetadata;
+  parseError?: WebSkillError;
+  scriptFileNames?: string[];
+  existingNames?: Set<string>;
+}): SkillIssue[];
+//#endregion
+//#region src/skill/discovery.d.ts
+interface DiscoveryResult {
+  entries: SkillCatalogEntry[];
+  issues: SkillIssue[];
+}
+declare class SkillDiscovery {
+  #private;
+  constructor(fs: FileSystemProvider, roots: string[]);
+  discover(): Promise<DiscoveryResult>;
+  catalog(): Promise<{
+    catalog: SkillCatalog;
+    issues: SkillIssue[];
+  }>;
+  /** 按需加载技能完整文档；技能不存在时抛 SKILL_NOT_FOUND */
+  loadDocument(skillName: string): Promise<SkillDocument>;
+}
+//#endregion
+//#region src/skill/validator.d.ts
+interface ValidationReport {
+  /** 无 error 级 issue 即 true */
+  ok: boolean;
+  issues: SkillIssue[];
+}
+/**
+ * 合规校验。内部直接复用 SkillDiscovery 的扫描逻辑，
+ * 规则判定同样落在 checkSkillRules 单一来源上。
+ */
+declare function validateSkills(fs: FileSystemProvider, roots: string[]): Promise<ValidationReport>;
+//#endregion
+//#region src/skill/reader.d.ts
+/** 按技能名读取技能根目录内的文件，全部读取强制经过路径安全检查 */
+declare class SkillReader {
+  #private;
+  constructor(fs: FileSystemProvider, index: Map<string, string>);
+  readSkillMarkdown(skillName: string): Promise<string>;
+  readSkillFile(skillName: string, relativePath: string): Promise<string>;
+  readSkillBinary(skillName: string, relativePath: string): Promise<Uint8Array>;
+}
+//#endregion
+//#region src/skill/catalog.d.ts
+/** 由条目列表构建 Catalog，保证按名称排序 */
+declare function buildCatalog(entries: SkillCatalogEntry[]): SkillCatalog;
+//#endregion
+//#region src/render/types.d.ts
+/** 可插拔的 Catalog 渲染器 */
+interface CatalogRenderer {
+  readonly format: string;
+  render(catalog: SkillCatalog): string;
+}
+//#endregion
+//#region src/render/jsonRenderer.d.ts
+declare function renderCatalogJson(catalog: SkillCatalog): string;
+declare const jsonRenderer: CatalogRenderer;
+//#endregion
+//#region src/render/xmlRenderer.d.ts
+/** 转义 XML 五个特殊字符：& < > " ' */
+declare function escapeXml(text: string): string;
+declare function renderAvailableSkillsXml(catalog: SkillCatalog): string;
+declare const xmlRenderer: CatalogRenderer;
+//#endregion
+//#region ../runtime/dist/index.d.ts
+//#region src/llm/streamTypes.d.ts
+/** 流式 LLM 事件（OpenAI SSE / Vercel fullStream 统一映射） */
+type LlmStreamEvent = {
+  type: 'text-delta';
+  delta: string;
+} | {
+  type: 'tool-calls';
+  toolCalls: LlmToolCall[];
+} | {
+  type: 'done';
+  content?: string;
+};
+//#endregion
+//#region src/llm/types.d.ts
+interface LlmMessage {
+  role: 'system' | 'user' | 'assistant' | 'tool';
+  content: string;
+  /** role=tool 时必填 */
+  toolCallId?: string;
+  /** role=assistant 发起工具调用时携带 */
+  toolCalls?: LlmToolCall[];
+}
+interface LlmToolSpec {
+  name: string;
+  description?: string;
+  inputSchema: JsonSchema;
+}
+interface LlmToolCall {
+  id: string;
+  name: string;
+  arguments: Record<string, unknown>;
+}
+interface LlmResponse {
+  content?: string;
+  toolCalls?: LlmToolCall[];
+  raw?: unknown;
+}
+interface LlmCompleteInput {
+  model?: string;
+  messages: LlmMessage[];
+  tools?: LlmToolSpec[];
+  temperature?: number;
+  signal?: AbortSignal;
+}
+interface LlmClient {
+  complete(input: LlmCompleteInput): Promise<LlmResponse>;
+  /** 可选流式接口；实现后 AgentLoop 默认走流式（text-delta 增量 + 最终组装） */
+  stream?(input: LlmCompleteInput): AsyncIterable<LlmStreamEvent>;
+}
+//#endregion
+//#region src/llm/mockLlmClient.d.ts
+type MockLlmHandler = (input: LlmCompleteInput) => LlmResponse | Promise<LlmResponse>;
+type MockLlmQueueItem = LlmResponse | MockLlmHandler | {
+  stream: LlmStreamEvent[] | ((input: LlmCompleteInput) => LlmStreamEvent[]);
+};
+/**
+ * 预设响应序列的确定性 LlmClient；handler 形式可按会话状态动态应答。
+ * 默认不含 stream（存量行为）；构造传 { streaming: true } 启用流式：
+ * 队列项 { stream: [...] } 按预设 delta 序列产出，LlmResponse 项自动合成增量。
+ */
+declare class MockLlmClient implements LlmClient {
+  #private;
+  readonly calls: LlmCompleteInput[];
+  readonly stream?: (input: LlmCompleteInput) => AsyncIterable<LlmStreamEvent>;
+  constructor(responses: MockLlmQueueItem[], options?: {
+    streaming?: boolean;
+  });
+  complete(input: LlmCompleteInput): Promise<LlmResponse>;
+}
+//#endregion
+//#region src/llm/openAiCompatibleClient.d.ts
+interface OpenAiCompatibleClientConfig {
+  baseUrl?: string;
+  apiKey?: string;
+  model?: string;
+  /** 可注入 fetch（测试用 mock）；缺省用全局 fetch */
+  fetchImpl?: typeof fetch;
+  /** 单次请求超时（覆盖 fetch 默认 300s；生成大输出的本地模型需要更长时间） */
+  requestTimeoutMs?: number;
+}
+/** OpenAI chat completions 协议客户端（兼容端点通用） */
+declare class OpenAiCompatibleClient implements LlmClient {
+  #private;
+  constructor(config: OpenAiCompatibleClientConfig);
+  complete(input: LlmCompleteInput): Promise<LlmResponse>;
+  /** SSE 流式：fetch + ReadableStream 按行解析 data: 帧（Node/浏览器通用） */
+  stream(input: LlmCompleteInput): AsyncIterable<LlmStreamEvent>;
+  /** 轻量探测（GET /models），集成测试据此决定 skip */
+  checkAvailability(): Promise<boolean>;
+}
+//#endregion
+//#region src/llm/vercelAiAdapter.d.ts
+/**
+ * Vercel AI SDK 适配层：纯数据转换，不 import SDK。
+ * duck-type 兼容 SDK 各版本字段差异（inputSchema/parameters、input/args）。
+ */
+interface VercelToolSpec {
+  description?: string;
+  inputSchema: JsonSchema;
+}
+declare function toVercelToolSpecs(tools: LlmToolSpec[]): Record<string, VercelToolSpec>;
+/** 接受 generateText 的返回值形状：{ text?, toolCalls?: [{ toolCallId, toolName, input|args }] } */
+declare function fromVercelResult(result: unknown): LlmResponse;
+/**
+ * Vercel streamText fullStream 片段 → LlmStreamEvent 映射。
+ * 未知片段类型返回 undefined（调用方跳过）。
+ */
+declare function fromVercelStreamPart(part: unknown): LlmStreamEvent | undefined;
+//#endregion
+//#region src/routing/types.d.ts
+interface RouteResult {
+  strategy: 'progressive' | 'full-disclosure' | string;
+  catalog: SkillCatalog;
+  systemPrompt: string;
+}
+interface SkillRouter {
+  route(catalog: SkillCatalog): Promise<RouteResult>;
+}
+//#endregion
+//#region src/routing/progressiveRouter.d.ts
+/** 渐进披露路由（默认）：system prompt 只注入 Catalog 元数据 + 工具使用说明 */
+declare class ProgressiveRouter implements SkillRouter {
+  route(catalog: SkillCatalog): Promise<RouteResult>;
+}
+//#endregion
+//#region src/routing/fullDisclosureRouter.d.ts
+/** 全量披露路由（对照用）：注入每个技能的完整 SKILL.md 正文 */
+declare class FullDisclosureRouter implements SkillRouter {
+  #private;
+  constructor(discovery: SkillDiscovery);
+  route(catalog: SkillCatalog): Promise<RouteResult>;
+}
+//#endregion
+//#region src/artifacts/types.d.ts
+interface Artifact {
+  id: string;
+  runId: string;
+  path: string;
+  type: 'text' | 'binary';
+  mimeType?: string;
+  size: number;
+  createdAt: string;
+  metadata?: Record<string, unknown>;
+}
+interface ArtifactStore {
+  createTextArtifact(input: {
+    runId: string;
+    path: string;
+    content: string;
+    mimeType?: string;
+    metadata?: Record<string, unknown>;
+  }): Promise<Artifact>;
+  createBinaryArtifact(input: {
+    runId: string;
+    path: string;
+    content: Uint8Array;
+    mimeType?: string;
+    metadata?: Record<string, unknown>;
+  }): Promise<Artifact>;
+  listArtifacts(runId: string): Promise<Artifact[]>;
+}
+//#endregion
+//#region src/tools/types.d.ts
+interface ToolDefinition {
+  /** LLM 可见名：脚本工具为 `${skillName}__${scriptName}` */
+  name: string;
+  description?: string;
+  /** 缺省即 schemaUnavailable 标记（推导见 deferred-items D2） */
+  inputSchema?: JsonSchema;
+  source: 'script' | 'mcp' | 'webmcp' | 'builtin';
+  skillName?: string;
+}
+interface ToolResult {
+  ok: boolean;
+  content: Array<{
+    type: 'text' | 'json';
+    text?: string;
+    data?: unknown;
+  }>;
+  error?: {
+    code: string;
+    message: string;
+  };
+  artifacts?: Artifact[];
+}
+interface ScriptExecutionContext {
+  skillName: string;
+  runId: string;
+  readReference(relativePath: string): Promise<string>;
+  writeArtifact(path: string, content: string | Uint8Array, options?: {
+    mimeType?: string;
+  }): Promise<Artifact>;
+  /** 脚本主动请求人在环确认；策略见 InteractionPolicy.confirmations */
+  confirm?(message: string): Promise<boolean>;
+}
+interface ScriptExecutor {
+  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/tools/toolResolver.d.ts
+type ToolResolution = {
+  kind: 'script';
+  skillName: string;
+  scriptName: string;
+} | {
+  kind: 'unsupported';
+  code: 'TOOL_UNSUPPORTED';
+  message: string;
+} | {
+  kind: 'not-found';
+  code: 'TOOL_NOT_FOUND';
+  message: string;
+};
+/**
+ * 工具名解析规则（单一实现，Agent 循环使用）：
+ * 1. `<skillName>__<scriptName>` 且前缀是已激活技能 → 本地脚本
+ * 2. `endpoint:` 前缀 → TOOL_UNSUPPORTED（MCP 阶段实现）
+ * 3. `mcp#` 前缀 → TOOL_UNSUPPORTED（WebMCP 阶段实现）
+ * 4. 其余 → TOOL_NOT_FOUND
+ */
+declare function resolveToolName(name: string, activatedSkills: ReadonlySet<string>): ToolResolution;
+/** ToolDefinition → LLM 工具 spec；缺 schema 时用宽松 object 兜底并在描述中标记 */
+declare function toLlmToolSpec(tool: ToolDefinition): LlmToolSpec;
+//#endregion
+//#region src/tools/normalizeContent.d.ts
+/**
+ * 脚本返回值归一到 MCP content 格式：数组沿用（逐项归一），
+ * 字符串包装为 text，其他值序列化包装。Node/浏览器执行器共享。
+ */
+declare function normalizeToolContent(value: unknown): ToolResult['content'];
+//#endregion
+//#region src/tools/readSkillFileTool.d.ts
+declare const READ_SKILL_FILE_TOOL_NAME = "read_skill_file";
+declare const READ_SKILL_FILE_INPUT_SCHEMA: JsonSchema;
+/** 内置工具：读取技能文件（读 SKILL.md 是技能激活的入口） */
+declare const READ_SKILL_FILE_TOOL: ToolDefinition;
+//#endregion
+//#region src/tools/askUserTool.d.ts
+declare const ASK_USER_TOOL_NAME = "ask_user";
+declare const ASK_USER_INPUT_SCHEMA: JsonSchema;
+/** 内建工具：LLM 信息不足时主动向用户提问；仅当配置了 UiBridge 时注册 */
+declare const ASK_USER_TOOL: ToolDefinition;
+//#endregion
+//#region src/tools/scriptContext.d.ts
+/**
+ * 脚本执行上下文：只暴露 readReference / writeArtifact 两个显式能力，
+ * 不暴露 fs 本体（沙箱语义，对齐 deferred-items D1）。
+ */
+declare function createScriptContext(deps: {
+  fs: FileSystemProvider;
+  artifactStore: ArtifactStore;
+  skillName: string;
+  skillRoot: string;
+  runId: string;
+  /** 提供时暴露 context.confirm（由引擎按交互策略实现） */
+  confirm?: (message: string) => Promise<boolean>;
+}): ScriptExecutionContext;
+//#endregion
+//#region src/interaction/types.d.ts
+type InteractionRequest = {
+  type: 'ask';
+  id: string;
+  message: string;
+  schema?: JsonSchema;
+} | {
+  type: 'confirm';
+  id: string;
+  message: string;
+  defaultValue?: boolean;
+} | {
+  type: 'form';
+  id: string;
+  title?: string;
+  fields: FormField[];
+} | {
+  type: 'select';
+  id: string;
+  message: string;
+  options: Array<{
+    label: string;
+    value: unknown;
+  }>;
+};
+interface InteractionResponse {
+  id: string;
+  value?: unknown;
+  cancelled?: boolean;
+}
+type RenderBlock = {
+  type: 'markdown';
+  text: string;
+} | {
+  type: 'json';
+  data: unknown;
+} | {
+  type: 'table';
+  columns: string[];
+  rows: unknown[][];
+} | {
+  type: 'image';
+  url: string;
+  alt?: string;
+} | {
+  type: 'file';
+  path: string;
+  mimeType?: string;
+  size?: number;
+};
+interface RenderResultRequest {
+  runId: string;
+  title?: string;
+  summary?: string;
+  blocks: RenderBlock[];
+  artifacts?: Artifact[];
+}
+interface UiBridge {
+  request(input: InteractionRequest): Promise<InteractionResponse>;
+  progress?(input: {
+    runId: string;
+    message: string;
+    value?: number;
+  }): Promise<void>;
+  /** 定义即可，阶段 7 消费 */
+  renderResult?(input: RenderResultRequest): Promise<void>;
+  /** 流式文本增量（流式 LLM 路径下由 AgentLoop 转发） */
+  onTextDelta?(runId: string, delta: string): Promise<void> | void;
+}
+interface FormField {
+  name: string;
+  label: string;
+  type: 'text' | 'number' | 'boolean' | 'select' | 'textarea';
+  required?: boolean;
+  description?: string;
+  defaultValue?: unknown;
+  options?: Array<{
+    label: string;
+    value: unknown;
+  }>;
+}
+interface InteractionPolicy {
+  /** 缺必填参数策略：默认 'user'（表单问用户），'llm' 回喂自愈 */
+  missingParams?: 'user' | 'llm';
+  /** context.confirm 策略：默认 'required'（真实询问） */
+  confirmations?: 'required' | 'auto-approve';
+  /** 交互超时，默认 300_000ms */
+  interactionTimeoutMs?: number;
+}
+//#endregion
+//#region src/lifecycle/types.d.ts
+type RuntimePhase = 'discover' | 'route' | 'activate' | 'prepare' | 'execute' | 'observe' | 'interact' | 'complete' | 'fail';
+interface LifecycleEvent {
+  phase: RuntimePhase;
+  runId: string;
+  sessionId: string;
+  ts: string;
+  data?: Record<string, unknown>;
+}
+interface LifecycleHookContext {
+  event: LifecycleEvent;
+  run: RuntimeRun;
+}
+type LifecycleHook = (ctx: LifecycleHookContext) => Promise<void | {
+  metadata?: Record<string, unknown>;
+}>;
+//#endregion
+//#region src/trace/types.d.ts
+type TraceEventType = 'skill.routed' | 'skill.activated' | 'llm.request' | 'llm.response' | 'tool.started' | 'tool.completed' | 'tool.failed' | 'artifact.created' | 'ui.requested' | 'ui.resumed' | 'ui.rendered' | 'run.warning' | 'run.completed' | 'run.cancelled' | 'run.failed';
+interface TraceEvent {
+  id: string;
+  runId: string;
+  ts: string;
+  type: TraceEventType;
+  message?: string;
+  data?: Record<string, unknown>;
+}
+//#endregion
+//#region src/engine/types.d.ts
+interface AgentLoopConfig {
+  /** 默认 10 */
+  maxTurns?: number;
+  /** 默认 120_000 */
+  totalTimeoutMs?: number;
+  /** 默认 30_000 */
+  toolTimeoutMs?: number;
+  temperature?: number;
+  /** 设为 'off' 时完成 run 不调用 uiBridge.renderResult */
+  renderResult?: 'off';
+}
+interface RuntimeSession {
+  id: string;
+  createdAt: string;
+}
+type RunTerminationReason = 'final-answer' | 'max-turns' | 'timeout' | 'llm-error' | 'interaction-timeout' | 'user-cancelled' | 'hook-error';
+interface RuntimeRun {
+  id: string;
+  sessionId: string;
+  status: 'running' | 'interrupted' | 'completed' | 'failed' | 'cancelled';
+  phase: RuntimePhase;
+  userPrompt: string;
+  startedAt: string;
+  endedAt?: string;
+  terminationReason?: RunTerminationReason;
+  /** interrupted 状态下的交互过期时间 */
+  interruptExpiresAt?: string;
+  activeSkillNames: string[];
+  artifacts: Artifact[];
+  trace: TraceEvent[];
+}
+interface RunResult {
+  output: string;
+  run: RuntimeRun;
+}
+//#endregion
+//#region src/interaction/renderResult.d.ts
+/**
+ * 默认的结果渲染构造：LLM 最终输出 → markdown block，
+ * run.artifacts → file blocks；summary 取 terminationReason。
+ */
+declare function buildRenderResult(run: RuntimeRun, output: string): RenderResultRequest;
+//#endregion
+//#region src/interaction/schemaToForm.d.ts
+/**
+ * JsonSchema → 表单模型：按 properties 生成字段，required 标记必填；
+ * providedArgs 已有的值作为 defaultValue 预填（表单只为补齐缺失项服务）。
+ * type 映射：string→text、number/integer→number、boolean→boolean、enum→select、其余→textarea。
+ */
+declare function schemaToForm(schema: JsonSchema, providedArgs?: Record<string, unknown>): FormField[];
+//#endregion
+//#region src/interaction/mockUiBridge.d.ts
+type MockUiAnswer = InteractionResponse | ((request: InteractionRequest) => InteractionResponse | Promise<InteractionResponse>);
+/**
+ * 测试用 UiBridge：按请求 id 或类型预设应答（永不 resolve 的 handler 可模拟超时）；
+ * 记录全部请求供断言。
+ */
+declare class MockUiBridge implements UiBridge {
+  #private;
+  readonly requests: InteractionRequest[];
+  /** key 为请求 id 或请求类型（'ask' | 'confirm' | 'form' | 'select'） */
+  respondTo(key: string, answer: MockUiAnswer): this;
+  setFallback(answer: MockUiAnswer): this;
+  request(input: InteractionRequest): Promise<InteractionResponse>;
+}
+//#endregion
+//#region src/lifecycle/eventBus.d.ts
+type LifecycleListener = (event: LifecycleEvent) => void;
+/** 生命周期事件总线：只读观测，支持按阶段或通配订阅 */
+declare class EventBus {
+  #private;
+  /** 返回取消订阅函数 */
+  on(phase: RuntimePhase | '*', listener: LifecycleListener): () => void;
+  /** 当前订阅者数量（流式 delta 零订阅零开销判断用） */
+  listenerCount(): number;
+  emit(event: LifecycleEvent): void;
+}
+//#endregion
+//#region src/lifecycle/hooks.d.ts
+interface HookRunnerOptions {
+  /** 单钩子超时，默认 5000ms；超时降级为 warning 继续 */
+  timeoutMs?: number;
+  /** true 时钩子异常终止 run（RUN_FAILED）；默认隔离记 warning */
+  failOnHookError?: boolean;
+  /** 降级 warning 出口（引擎接线到 trace） */
+  onWarning?: (message: string) => void;
+}
+/** 受控钩子执行器：逐个执行，超时/异常默认降级为 warning，可切严格模式 */
+declare class HookRunner {
+  #private;
+  readonly timeoutMs: number;
+  readonly failOnHookError: boolean;
+  onWarning?: (message: string) => void;
+  constructor(options?: HookRunnerOptions);
+  register(phase: RuntimePhase | '*', hook: LifecycleHook): this;
+  run(phase: RuntimePhase, ctx: LifecycleHookContext): Promise<void>;
+}
+//#endregion
+//#region src/memory/types.d.ts
+/** scope/key 两级记忆存储；scope 约定：session:{id} / skill:{name} / user:{id} */
+interface MemoryStore {
+  get(scope: string, key: string): Promise<unknown>;
+  set(scope: string, key: string, value: unknown): Promise<void>;
+  delete(scope: string, key: string): Promise<void>;
+  list(scope: string): Promise<Array<{
+    key: string;
+    value: unknown;
+  }>>;
+  clear(scope?: string): Promise<void>;
+}
+//#endregion
+//#region src/memory/inMemoryStore.d.ts
+/** 内存 MemoryStore：测试与浏览器降级用 */
+declare class InMemoryStore implements MemoryStore {
+  #private;
+  get(scope: string, key: string): Promise<unknown>;
+  set(scope: string, key: string, value: unknown): Promise<void>;
+  delete(scope: string, key: string): Promise<void>;
+  list(scope: string): Promise<Array<{
+    key: string;
+    value: unknown;
+  }>>;
+  clear(scope?: string): Promise<void>;
+}
+//#endregion
+//#region src/memory/fsMemoryStore.d.ts
+/**
+ * 基于 FileSystemProvider 的 MemoryStore：
+ * <root>/<encodeURIComponent(scope)>/<encodeURIComponent(key)>.json
+ * scope/key 全部编码防路径穿越；环境无关，构造必须显式传 fs。
+ */
+declare class FsMemoryStore implements MemoryStore {
+  #private;
+  constructor(deps: {
+    root: string;
+    fs: FileSystemProvider;
+  });
+  get(scope: string, key: string): Promise<unknown>;
+  set(scope: string, key: string, value: unknown): Promise<void>;
+  delete(scope: string, key: string): Promise<void>;
+  list(scope: string): Promise<Array<{
+    key: string;
+    value: unknown;
+  }>>;
+  clear(scope?: string): Promise<void>;
+}
+//#endregion
+//#region src/artifacts/memoryArtifactStore.d.ts
+/** 内存 ArtifactStore：测试与浏览器降级用；索引随进程生命周期存在 */
+declare class MemoryArtifactStore implements ArtifactStore {
+  #private;
+  createTextArtifact(input: {
+    runId: string;
+    path: string;
+    content: string;
+    mimeType?: string;
+    metadata?: Record<string, unknown>;
+  }): Promise<Artifact>;
+  createBinaryArtifact(input: {
+    runId: string;
+    path: string;
+    content: Uint8Array;
+    mimeType?: string;
+    metadata?: Record<string, unknown>;
+  }): Promise<Artifact>;
+  listArtifacts(runId: string): Promise<Artifact[]>;
+}
+//#endregion
+//#region src/artifacts/fsArtifactStore.d.ts
+/**
+ * 基于 FileSystemProvider 的 ArtifactStore：产物落盘 <root>/<runId>/<path>，
+ * 每次写入同步更新 <root>/<runId>/index.json，新实例可凭索引恢复列表。
+ * 环境无关（OPFS/Node 均可），构造必须显式传 fs。
+ */
+declare class FsArtifactStore implements ArtifactStore {
+  #private;
+  constructor(deps: {
+    root: string;
+    fs: FileSystemProvider;
+  });
+  createTextArtifact(input: {
+    runId: string;
+    path: string;
+    content: string;
+    mimeType?: string;
+    metadata?: Record<string, unknown>;
+  }): Promise<Artifact>;
+  createBinaryArtifact(input: {
+    runId: string;
+    path: string;
+    content: Uint8Array;
+    mimeType?: string;
+    metadata?: Record<string, unknown>;
+  }): Promise<Artifact>;
+  listArtifacts(runId: string): Promise<Artifact[]>;
+}
+//#endregion
+//#region src/sandbox/bridgeProtocol.d.ts
+/** 能力桥 RPC 消息类型 + 入站校验（Worker 沙箱 ↔ 宿主；browser/node 共用单一来源） */
+type BridgeRequest = {
+  kind: 'readReference';
+  id: string;
+  path: string;
+} | {
+  kind: 'writeArtifact';
+  id: string;
+  path: string;
+  content: string | number[];
+  mimeType?: string;
+} | {
+  kind: 'confirm';
+  id: string;
+  message: string;
+};
+interface BridgeResponse {
+  id: string;
+  ok: boolean;
+  value?: unknown;
+  error?: {
+    code: string;
+    message: string;
+  };
+}
+/** 三能力独立开关；缺省全开，显式 false 即关闭（TOOL_UNSUPPORTED） */
+interface BridgeCapabilities {
+  readReference?: boolean;
+  writeArtifact?: boolean;
+  confirm?: boolean;
+}
+/** 入站校验：非法 kind / 缺 id / 缺字段 → undefined（调用方忽略并记 warning） */
+declare function parseBridgeRequest(data: unknown): BridgeRequest | undefined;
+declare function bridgeError(id: string, code: string, message: string): BridgeResponse;
+//#endregion
+//#region src/trace/traceRecorder.d.ts
+interface TraceClock {
+  now?: () => string;
+  createId?: () => string;
+}
+/** 结构化 trace 记录器；时钟与 id 工厂可注入（golden trace 用固定值保证确定性） */
+declare class TraceRecorder {
+  #private;
+  constructor(runId: string, clock?: TraceClock);
+  record(type: TraceEventType, opts?: {
+    message?: string;
+    data?: Record<string, unknown>;
+  }): TraceEvent;
+  list(): TraceEvent[];
+}
+//#endregion
+//#region src/engine/external.d.ts
+/**
+ * 外部工具来源（runtime 扩展点，mcp 包实现并插入）。
+ * LLM 可见名为已消毒名（如 endpoint__greet / mcp__search）。
+ */
+interface ExternalToolSource {
+  readonly kind: string;
+  listToolSpecs(): Promise<LlmToolSpec[]>;
+  canHandle(llmToolName: string): boolean;
+  call(llmToolName: string, args: Record<string, unknown>): Promise<ToolResult>;
+}
+/** 外部技能提供者（页面动态技能等；技能随来源生灭，不持久化） */
+interface ExternalSkillProvider {
+  listSkills(): Promise<SkillCatalogEntry[]>;
+  loadSkill(name: string): Promise<SkillDocument>;
+  readFile?(name: string, relativePath: string): Promise<string>;
+}
+/**
+ * Catalog 合并：同名本地优先；外部条目的 mcp:// 根 URI 保留，
+ * 调用方可凭 URI 强制选择外部技能（绕过本地优先）。
+ */
+declare function mergeCatalogEntries(localEntries: SkillCatalogEntry[], providerEntries: SkillCatalogEntry[]): SkillCatalogEntry[];
+//#endregion
+//#region src/engine/agentLoop.d.ts
+interface AgentLoopDeps {
+  llm: LlmClient;
+  executor: ScriptExecutor;
+  artifactStore: ArtifactStore;
+  fs: FileSystemProvider;
+  /** name → skillRoot（来自发现结果） */
+  skillIndex: Map<string, string>;
+  model?: string;
+  /** 时钟与 id 工厂注入点（golden trace 用固定值） */
+  clock?: TraceClock;
+  uiBridge?: UiBridge;
+  interaction?: InteractionPolicy;
+  memory?: MemoryStore;
+  hooks?: HookRunner;
+  eventBus?: EventBus;
+  /** 长期记忆（user scope）；默认关闭，关闭时零持久化写入 */
+  longTerm?: {
+    enabled: true;
+    userId: string;
+  };
+  /** 外部工具来源（mcp 插件等）；specs 在 run 开始时并入每轮 tools */
+  externalTools?: ExternalToolSource[];
+  /** 外部技能提供者（页面动态技能等） */
+  skillProviders?: ExternalSkillProvider[];
+  /** Catalog 过滤钩子（治理状态拦截路由，如 quarantined/deprecated 过滤） */
+  catalogFilter?: (entries: SkillCatalogEntry[]) => SkillCatalogEntry[] | Promise<SkillCatalogEntry[]>;
+}
+/**
+ * 多轮 Agent 循环。
+ * 工具失败一律转为 ToolResult{ok:false} 回喂 LLM 继续循环；
+ * 缺参/确认/提问经 UiBridge 行内 await 暂停恢复；取消/超时/LLM 异常/护栏超限才终止 run。
+ */
+declare class AgentLoop {
+  #private;
+  constructor(deps: AgentLoopDeps, config?: AgentLoopConfig);
+  run(input: {
+    sessionId: string;
+    userPrompt: string;
+    route: RouteResult;
+    runId?: string;
+  }): Promise<RunResult>;
+}
+//#endregion
+//#region src/engine/runtime.d.ts
+interface WebSkillRuntimeDeps {
+  fs: FileSystemProvider;
+  roots: string[];
+  llm: LlmClient;
+  /** 缺省 ProgressiveRouter */
+  router?: SkillRouter;
+  executor: ScriptExecutor;
+  artifactStore: ArtifactStore;
+  config?: AgentLoopConfig;
+  model?: string;
+  uiBridge?: UiBridge;
+  interaction?: InteractionPolicy;
+  memory?: MemoryStore;
+  hooks?: HookRunner;
+  eventBus?: EventBus;
+  /** 长期记忆（user scope）；默认关闭 */
+  longTerm?: {
+    enabled: true;
+    userId: string;
+  };
+  /** 外部工具来源（mcp 插件等） */
+  externalTools?: ExternalToolSource[];
+  /** 外部技能提供者（页面动态技能等）；Catalog 合并同名本地优先 */
+  skillProviders?: ExternalSkillProvider[];
+  /** Catalog 过滤钩子（治理状态拦截路由） */
+  catalogFilter?: (entries: SkillCatalogEntry[]) => SkillCatalogEntry[] | Promise<SkillCatalogEntry[]>;
+  /** opt-in：run 完成且未激活任何技能时回调（默认关闭，fire-and-forget） */
+  onSkillMiss?: (input: {
+    prompt: string;
+    run: RunResult['run'];
+  }) => Promise<void>;
+}
+/** runtime 门面：组合 discovery / router / agent loop / lifecycle */
+declare class WebSkillRuntime {
+  #private;
+  constructor(deps: WebSkillRuntimeDeps);
+  get session(): RuntimeSession;
+  /** 生命周期事件总线（只读观测） */
+  get events(): EventBus;
+  discover(): Promise<DiscoveryResult>;
+  run(userPrompt: string): Promise<RunResult>;
+}
+//#endregion
+export { RunTerminationReason as $, jsonRenderer as $t, LlmCompleteInput as A, DiscoveryResult as At, MockLlmQueueItem as B, SkillDocument as Bt, InteractionRequest as C, normalizeToolContent as Ct, LifecycleHookContext as D, toLlmToolSpec as Dt, LifecycleHook as E, schemaToForm as Et, LlmToolSpec as F, SKILL_NAME_MAX_LENGTH as Ft, ProgressiveRouter as G, SkillSource as Gt, MockUiBridge as H, SkillLocation as Ht, MemoryArtifactStore as I, SKILL_NAME_PATTERN as It, READ_SKILL_FILE_TOOL_NAME as J, WebSkillErrorCode as Jt, READ_SKILL_FILE_INPUT_SCHEMA as K, ValidationReport as Kt, MemoryStore as L, SkillCatalog as Lt, LlmResponse as M, FileSystemProvider as Mt, LlmStreamEvent as N, JsonSchema as Nt, LifecycleListener as O, toVercelToolSpecs as Ot, LlmToolCall as P, MemoryFS as Pt, RunResult as Q, isValidSkillName as Qt, MockLlmClient as R, SkillCatalogEntry as Rt, InteractionPolicy as S, mergeCatalogEntries as St, LifecycleEvent as T, resolveToolName as Tt, OpenAiCompatibleClient as U, SkillMetadata as Ut, MockUiAnswer as V, SkillIssue as Vt, OpenAiCompatibleClientConfig as W, SkillReader as Wt, RenderResultRequest as X, checkSkillRules as Xt, RenderBlock as Y, buildCatalog as Yt, RouteResult as Z, escapeXml as Zt, FsMemoryStore as _, bridgeError as _t, AgentLoopConfig as a, validateSkills as an, SkillRouter as at, HookRunnerOptions as b, fromVercelResult as bt, ArtifactStore as c, ToolResult as ct, BridgeResponse as d, TraceEventType as dt, normalizePath as en, RuntimePhase as et, EventBus as f, TraceRecorder as ft, FsArtifactStore as g, WebSkillRuntimeDeps as gt, FormField as h, WebSkillRuntime as ht, AgentLoop as i, resolveInsideRoot as in, ScriptExecutor as it, LlmMessage as j, FileStat as jt, LlmClient as k, CatalogRenderer as kt, BridgeCapabilities as l, TraceClock as lt, ExternalToolSource as m, VercelToolSpec as mt, ASK_USER_TOOL as n, renderAvailableSkillsXml as nn, RuntimeSession as nt, AgentLoopDeps as o, xmlRenderer as on, ToolDefinition as ot, ExternalSkillProvider as p, UiBridge as pt, READ_SKILL_FILE_TOOL as q, WebSkillError as qt, ASK_USER_TOOL_NAME as r, renderCatalogJson as rn, ScriptExecutionContext as rt, Artifact as s, ToolResolution as st, ASK_USER_INPUT_SCHEMA as t, parseSkillMarkdown as tn, RuntimeRun as tt, BridgeRequest as u, TraceEvent as ut, FullDisclosureRouter as v, buildRenderResult as vt, InteractionResponse as w, parseBridgeRequest as wt, InMemoryStore as x, fromVercelStreamPart as xt, HookRunner as y, createScriptContext as yt, MockLlmHandler as z, SkillDiscovery as zt };