@springbrand/agent-runtime 0.1.3-alpha.0 → 0.1.3-alpha.2

package/src/pi/tool/skill.ts

@@ -1,455 +1,147 @@
-import type {
-  AgentTool,
-  AgentToolResult,
-} from "@earendil-works/pi-agent-core";
-import { Type } from "@earendil-works/pi-ai";
 import {
   runner as createSkillScriptRunner,
-  type SkillContent,
-  type SkillResource,
+  SkillRegistry,
+  type SkillScriptRequest,
+  type SkillScriptRunner,
   type SkillSource,
 } from "agents/skills";
-import type { RuntimeSkillScriptPolicy } from "../../kernel/bindings";
+import { jsonSchema, type ToolSet } from "ai";
+import type {
+  RuntimeSkillScriptPolicy,
+  WorkspacePort,
+} from "../../kernel/bindings";
+import { aiToolToPi } from "./ai-adapter";
 import type { PiToolCandidate } from "./compiler";
 
-/**
- * 一个已经过 Host 授权、可以交给 Pi 使用的 Skill 绑定。
- *
- * Worker 的 Skill Plugin 负责创建它；调用方应让 `name`、`source` 和脚本权限
- * 来自同一份 Runtime 配置，避免工具目录与实际读取权限脱节。
- *
- * `Host`、`Pi` 与 `Runtime` 等核心术语见 `../../index.ts`。
- */
+/** An authorized Skill source and its script capabilities. */
 export interface PiSkillBinding {
-  /** Runtime 配置中启用的唯一 Skill 名称。 */
   readonly name: string;
-  /** 按名称延迟加载说明和资源的 Agents SDK Skill 来源。 */
   readonly source: SkillSource;
-  /**
-   * Isolated execution policy for this Skill's bundled scripts. Without it the
-   * binding contributes no `run_skill_script` capability.
-   */
   readonly script?: RuntimeSkillScriptPolicy;
 }
 
-/** 创建 Pi Skill 工具时可选的 Host 能力。 */
+/** Host capabilities available while creating Skill tools. */
 export interface SkillPiToolOptions {
-  /**
-   * Worker Loader used to sandbox Skill scripts. Omit it and
-   * `run_skill_script` is not contributed at all, which keeps the read-only
-   * Skill surface available to hosts that cannot run isolates.
-   */
   readonly loader?: WorkerLoader;
+  readonly workspace?: WorkspacePort;
+  readonly tools?: readonly PiToolCandidate[];
 }
 
-const activateParameters = Type.Object({
-  name: Type.String({
-    minLength: 1,
-    maxLength: 128,
-    description: "Name from the AUTHORIZED SKILLS catalog.",
-  }),
-});
-
-const readResourceParameters = Type.Object({
-  name: Type.String({
-    minLength: 1,
-    maxLength: 128,
-    description: "Name from the AUTHORIZED SKILLS catalog.",
-  }),
-  path: Type.String({
-    minLength: 1,
-    maxLength: 4_096,
-    description:
-      "Normalized relative resource path listed by activate_skill.",
-  }),
-});
-
-const runScriptParameters = Type.Object({
-  name: Type.String({
-    minLength: 1,
-    maxLength: 128,
-    description: "Name from the AUTHORIZED SKILLS catalog.",
-  }),
-  path: Type.String({
-    minLength: 1,
-    maxLength: 4_096,
-    description:
-      'Script resource path under "scripts/" as listed by activate_skill.',
-  }),
-  input: Type.Optional(
-    Type.Unknown({ description: "JSON input passed to the script." }),
-  ),
-});
-
-// 只接受已安装 Agents SDK runner 能识别的脚本扩展名。
-const SCRIPT_EXTENSIONS = new Set([
-  ".js",
-  ".mjs",
-  ".ts",
-  ".tsx",
-  ".py",
-  ".sh",
-  ".bash",
-]);
-
-// 作用：按模型给出的名称找到已启用的 Skill 绑定。
-// 调用：激活、读资源和运行脚本三个工具在访问 SkillSource 前调用。
-// 原因：先在本地授权列表中查找可以默认拒绝未知名称，
-// 不能让模型直接枚举或访问任意来源。
-function bindingFor(
-  bindings: readonly PiSkillBinding[],
-  name: string,
-): PiSkillBinding {
-  const binding = bindings.find((candidate) => candidate.name === name);
-  if (!binding) throw new Error(`Skill is not enabled: ${name}`);
-  return binding;
-}
-
-// 作用：确认 Skill 资源使用规范化的相对路径。
-// 调用：读取资源前后，以及脚本路径校验的第一步调用。
-// 原因：同时检查请求路径和 Source 回传路径，
-// 防止绝对路径、空段和父目录跳转越过 Skill 边界。
-function validateResourcePath(path: string): void {
-  if (
-    path.startsWith("/") ||
-    path.includes("\0") ||
-    path.split("/").some(
-      (part) => part === "" || part === "." || part === "..",
-    )
-  ) {
-    throw new Error(
-      `Skill resource path must be a normalized relative path: ${path}`,
-    );
-  }
-}
-
-// 作用：确认资源路径确实指向 runner 支持的 scripts 文件。
-// 调用：运行脚本前分别校验模型请求和 Source 回传的路径。
-// 原因：Agents SDK 的脚本执行是显式开启的能力，
-// 只允许当前 runner 已支持的 JavaScript、TypeScript、Python 和 Bash 扩展名。
-function validateScriptPath(path: string): void {
-  validateResourcePath(path);
-  if (!path.startsWith("scripts/")) {
-    throw new Error(
-      `Skill script path must start with "scripts/": ${path}`,
-    );
-  }
-  const dot = path.lastIndexOf(".");
-  const extension = dot === -1 ? "" : path.slice(dot).toLowerCase();
-  if (!SCRIPT_EXTENSIONS.has(extension)) {
-    throw new Error(
-      `Unsupported skill script extension "${
-        extension || "(none)"
-      }" for ${path}`,
-    );
-  }
-}
-
-// 作用：转义写入 Skill 结果标签属性的文本。
-// 调用：activationResult、resourceResult 和脚本结果包装名称与路径时调用。
-// 原因：这些值来自配置或资源描述，
-// 必须避免引号和尖括号破坏供模型扫读的标签边界。
-function attribute(value: string): string {
-  return value
-    .replaceAll("&", "&")
-    .replaceAll('"', """)
-    .replaceAll("<", "&lt;")
-    .replaceAll(">", "&gt;");
-}
-
-// 作用：把 Skill 的资源清单整理成人能直接扫读的列表。
-// 调用：activationResult 返回 Skill 正文时调用。
-// 原因：激活阶段只公布描述信息，不提前读取每个资源，
-// 保持 Agents SDK 的按需加载模型。
-function resourceList(skill: SkillContent): string {
-  if (!skill.resources?.length) return "No bundled resources.";
-  return skill.resources.map((resource) => {
-    const encoding = resource.encoding ?? "text";
-    const size = resource.size === undefined
-      ? ""
-      : `, ${resource.size} bytes`;
-    const mime = resource.mimeType ? `, ${resource.mimeType}` : "";
-    return `- ${resource.path} (${resource.kind}, ${encoding}${mime}${size})`;
-  }).join("\n");
+function scriptTools(
+  candidates: readonly PiToolCandidate[],
+  names: readonly string[],
+): ToolSet {
+  const byName = new Map(
+    candidates.map((candidate) => [candidate.tool.name, candidate.tool]),
+  );
+  return Object.fromEntries(names.flatMap((name) => {
+    const candidate = byName.get(name);
+    if (!candidate) return [];
+    return [[name, {
+      description: candidate.description,
+      inputSchema: jsonSchema(candidate.parameters as never),
+      execute: async (input: unknown) =>
+        (await candidate.execute(`skill-script:${name}`, input)).details,
+    }]];
+  })) as ToolSet;
 }
 
-// 作用：把已加载的 Skill 说明和资源清单包装成 Pi 工具结果。
-// 调用：activate_skill 成功加载且核对名称后调用。
-// 原因：正文给模型阅读，结构化 details 留给事件投影；
-// 两者共用同一 Skill 快照以免版本错位。
-function activationResult(
-  skill: SkillContent,
-): AgentToolResult<unknown> {
-  const version = skill.version
-    ? ` version="${attribute(skill.version)}"`
-    : "";
+// A binding authorizes one configured name even if its backing source happens
+// to contain more Skills. Source failures are also sanitized at this boundary.
+function authorizedSource(binding: PiSkillBinding): SkillSource {
+  const { name, source } = binding;
   return {
-    content: [{
-      type: "text",
-      text: [
-        `<skill_content name="${attribute(skill.name)}"${version}>`,
-        skill.body.trim(),
-        "</skill_content>",
-        "",
-        "Bundled resources:",
-        resourceList(skill),
-      ].join("\n"),
-    }],
-    details: {
-      name: skill.name,
-      ...(skill.version ? { version: skill.version } : {}),
-      resources: skill.resources ?? [],
+    id: `${source.id}:${name}`,
+    get fingerprint() {
+      return `${source.fingerprint}:${name}`;
     },
-  };
-}
-
-// 作用：把一个已读取的 Skill 资源包装成 Pi 工具结果。
-// 调用：read_skill_resource 完成路径和来源核对后调用。
-// 原因：显式保留种类、编码和 MIME 等元数据，
-// 避免模型从正文猜测资源格式。
-function resourceResult(
-  name: string,
-  resource: SkillResource,
-): AgentToolResult<unknown> {
-  const encoding = resource.encoding ?? "text";
-  const mime = resource.mimeType
-    ? ` mimeType="${attribute(resource.mimeType)}"`
-    : "";
-  return {
-    content: [{
-      type: "text",
-      text: [
-        `<skill_resource name="${attribute(name)}" path="${
-          attribute(resource.path)
-        }" kind="${resource.kind}" encoding="${encoding}"${mime}>`,
-        resource.content,
-        "</skill_resource>",
-      ].join("\n"),
-    }],
-    details: {
-      name,
-      path: resource.path,
-      kind: resource.kind,
-      encoding,
-      ...(resource.mimeType ? { mimeType: resource.mimeType } : {}),
-      ...(resource.size === undefined
-        ? {}
-        : { size: resource.size }),
+    async list() {
+      return (await source.list()).filter((skill) => skill.name === name);
     },
-  };
-}
-
-/**
- * 为已启用的 Skill 创建按需加载说明、资源和可选脚本的 Pi 候选工具。
- *
- * Worker 的 Skill Plugin 在贡献 Runtime 能力时调用它。调用方只传入已授权绑定；
- * 没有绑定时不公开工具，没有 Worker Loader 或脚本策略时不公开脚本执行工具。
- *
- * 这里的 “Skill” 是按需加载的任务说明包，“Source” 负责列出和读取包，“资源”
- * 是包内文件，“runner” 是 Agents SDK 借助 Worker Loader 创建的隔离脚本执行器。
- * 激活只读取说明和资源清单，资源正文继续按路径读取，避免把整个 Skill 库常驻
- * 系统上下文。脚本执行仍是显式、按绑定授权的高风险能力，不能降级成普通读取。
- * Agents SDK 目前仍把 Skill 脚本标为 experimental，升级依赖时要重新核对 runner
- * 的选项和请求结构，不能把当前形状当成稳定协议。
- *
- * `Host`、`Pi`、`Runtime Snapshot` 与“候选工具”见 `../../index.ts`。
- */
-export function skillPiToolCandidates(
-  bindings: readonly PiSkillBinding[],
-  options: SkillPiToolOptions = {},
-): PiToolCandidate[] {
-  if (bindings.length === 0) return [];
-
-  const activate: AgentTool<typeof activateParameters> = {
-    name: "activate_skill",
-    label: "Activate Skill",
-    description:
-      "Load the instructions and bundled-resource inventory for an enabled Skill. Use this when the user's task matches an AUTHORIZED SKILLS entry.",
-    parameters: activateParameters,
-    // 作用：按名称加载一个已启用 Skill 的说明和资源清单。
-    // 调用：Pi 在任务命中系统上下文里的 Skill 摘要后调用。
-    // 原因：先经过本地绑定授权，再隐藏 Source 原始异常，
-    // 防止私有存储细节进入模型错误消息。
-    async execute(_toolCallId, { name }, signal) {
-      signal?.throwIfAborted();
-      const binding = bindingFor(bindings, name);
-      let skill: SkillContent | null;
+    async load(requested) {
+      if (requested !== name) return null;
       try {
-        skill = await binding.source.load(name);
+        const skill = await source.load(requested);
+        return skill?.name === name ? skill : null;
       } catch (cause) {
         throw new Error(`Skill unavailable: ${name}`, { cause });
       }
-      if (!skill || skill.name !== name) {
-        throw new Error(`Skill not found: ${name}`);
-      }
-      return activationResult(skill);
     },
+    ...(source.readResource
+      ? {
+          async readResource(requested: string, path: string) {
+            if (requested !== name) return null;
+            try {
+              const resource = await source.readResource!(requested, path);
+              return resource?.path === path ? resource : null;
+            } catch (cause) {
+              throw new Error(
+                `Skill resource unavailable: ${name}/${path}`,
+                { cause },
+              );
+            }
+          },
+        }
+      : {}),
+    ...(source.refresh ? { refresh: () => source.refresh!() } : {}),
   };
+}
 
-  const read: AgentTool<typeof readResourceParameters> = {
-    name: "read_skill_resource",
-    label: "Read Skill resource",
-    description:
-      "Read one bundled file from an enabled Skill by the relative path returned by activate_skill.",
-    parameters: readResourceParameters,
-    // 作用：读取 activate_skill 清单中指定的一个 Skill 资源。
-    // 调用：Pi 需要模板、参考资料或其他包内文件时调用。
-    // 原因：请求和返回路径都重新校验，并把来源异常收口，
-    // 防止越界读取或泄漏底层凭据。
-    async execute(_toolCallId, { name, path }, signal) {
-      signal?.throwIfAborted();
-      validateResourcePath(path);
-      const binding = bindingFor(bindings, name);
-      if (!binding.source.readResource) {
-        throw new Error(`Skill has no readable resources: ${name}`);
-      }
-      let resource: SkillResource | null;
-      try {
-        resource = await binding.source.readResource(name, path);
-      } catch (cause) {
-        throw new Error(
-          `Skill resource unavailable: ${name}/${path}`,
-          { cause },
-        );
-      }
-      if (!resource || resource.path !== path) {
-        throw new Error(`Skill resource not found: ${name}/${path}`);
+function scriptRunner(
+  bindings: readonly PiSkillBinding[],
+  options: SkillPiToolOptions,
+): SkillScriptRunner | null {
+  if (!options.loader || !bindings.some((binding) => binding.script)) {
+    return null;
+  }
+  const byName = new Map(bindings.map((binding) => [binding.name, binding]));
+  return {
+    async run(request: SkillScriptRequest) {
+      const policy = byName.get(request.skill.name)?.script;
+      if (!policy) {
+        throw new Error(`Skill cannot run scripts: ${request.skill.name}`);
       }
-      validateResourcePath(resource.path);
-      return resourceResult(name, resource);
+      const workspace = policy.workspace !== "none" && options.workspace
+        ? policy.workspace
+        : "none";
+      return createSkillScriptRunner({
+        loader: options.loader!,
+        network: policy.network === "full",
+        workspace,
+        ...(workspace !== "none" && options.workspace
+          ? { workspaceInstance: options.workspace }
+          : {}),
+        tools: scriptTools(options.tools ?? [], policy.tools),
+      }).run(request);
     },
   };
+}
 
-  const candidates: PiToolCandidate[] = [
-    {
-      owner: "runtime-skill",
-      authorized: true,
-      requiredExecutionLevel: "safe",
-      tool: activate,
-    },
-    {
-      owner: "runtime-skill",
-      authorized: true,
-      requiredExecutionLevel: "safe",
-      tool: read,
-    },
-  ];
-
-  // Script execution needs both an isolate loader and at least one binding that
-  // declares a script policy. The upstream runner enforces the capability gates;
-  // this wrapper owns argument validation and throws on failure so the shared
-  // Tool governance keeps counting real errors.
-  const loader = options.loader;
-  const scriptable = bindings.some((binding) => binding.script);
-  if (loader && scriptable) {
-    const runScript: AgentTool<typeof runScriptParameters> = {
-      name: "run_skill_script",
-      label: "Run Skill script",
-      description:
-        "Run a bundled script from an enabled Skill. Use this only when the Skill's instructions tell you to run it.",
-      parameters: runScriptParameters,
-      // 作用：把一个已授权 Skill 自带的脚本交给 Agents SDK 隔离 runner 执行。
-      // 调用：Pi 只在 Skill 说明明确要求执行脚本时调用。
-      // 原因：加载器、绑定策略、资源描述和实际资源缺一不可，
-      // 逐层复核可避免把普通文件或未授权能力交给 runner。
-      async execute(_toolCallId, { name, path, input }, signal) {
-        signal?.throwIfAborted();
-        validateScriptPath(path);
-        const binding = bindingFor(bindings, name);
-        const policy = binding.script;
-        if (!policy) {
-          throw new Error(`Skill cannot run scripts: ${name}`);
-        }
-        if (!binding.source.readResource) {
-          throw new Error(`Skill has no readable resources: ${name}`);
-        }
-
-        let skill: SkillContent | null;
-        try {
-          skill = await binding.source.load(name);
-        } catch (cause) {
-          throw new Error(`Skill unavailable: ${name}`, { cause });
-        }
-        if (!skill || skill.name !== name) {
-          throw new Error(`Skill not found: ${name}`);
-        }
-
-        const descriptor = skill.resources?.find(
-          (resource) => resource.path === path,
-        );
-        if (!descriptor) {
-          throw new Error(`Skill script not found: ${name}/${path}`);
-        }
-        if (descriptor.kind !== "script") {
-          throw new Error(
-            `Skill resource is not a script: ${name}/${path}`,
-          );
-        }
-
-        let resource: SkillResource | null;
-        try {
-          resource = await binding.source.readResource(name, path);
-        } catch (cause) {
-          throw new Error(
-            `Skill script unavailable: ${name}/${path}`,
-            { cause },
-          );
-        }
-        if (!resource || resource.path !== path) {
-          throw new Error(`Skill script not found: ${name}/${path}`);
-        }
-        validateScriptPath(resource.path);
-        if ((resource.encoding ?? "text") !== "text") {
-          throw new Error(
-            `Skill script must be text, got ${resource.encoding}: ${name}/${path}`,
-          );
-        }
-
-        signal?.throwIfAborted();
-        // TODO(待确认)：agents@0.19.0 runner 需要 request.resources 才能识别
-        // precompiled 脚本并填充 ctx.files 或 /skill；这里只传了目标脚本资源。
-        // TODO(待确认)：策略允许 Workspace 时还需 workspaceInstance；当前只传
-        // workspace 权限；按已安装 runner 与官方文档，
-        // 读写能力可能仍不可用。
-        // TODO(待确认)：RuntimeSkillScriptPolicy.tools 已被保存，但这里没有把
-        // 对应工具集传给 runner；按官方文档，ctx.tools 可能始终为空。
-        const output = await createSkillScriptRunner({
-          loader,
-          network: policy.network === "full",
-          workspace: policy.workspace,
-        }).run({
-          skill,
-          path,
-          source: resource.content,
-          input: input ?? {},
-        });
+const SKILL_TOOL_LABELS: Readonly<Record<string, string>> = {
+  activate_skill: "Activate Skill",
+  read_skill_resource: "Read Skill resource",
+  run_skill_script: "Run Skill script",
+};
 
-        return {
-          content: [{
-            type: "text",
-            text: [
-              `<skill_script name="${attribute(name)}" path="${
-                attribute(path)
-              }">`,
-              typeof output === "string"
-                ? output
-                : JSON.stringify(output, null, 2) ?? "",
-              "</skill_script>",
-            ].join("\n"),
-          }],
-          details: { name, path, output },
-        };
-      },
-    };
-    candidates.push({
-      owner: "runtime-skill",
-      authorized: true,
-      // Scripts execute host-provided code in an isolate, so this is never a
-      // safe read like activate/read_resource.
-      requiredExecutionLevel: "high",
-      tool: runScript,
-    });
-  }
+/** Create Pi candidates from the official Agents SDK SkillRegistry tools. */
+export async function skillPiToolCandidates(
+  bindings: readonly PiSkillBinding[],
+  options: SkillPiToolOptions = {},
+): Promise<PiToolCandidate[]> {
+  if (bindings.length === 0) return [];
 
-  return candidates;
+  const registry = new SkillRegistry(
+    bindings.map(authorizedSource),
+    scriptRunner(bindings, options),
+  );
+  await registry.load();
+
+  return Object.entries(registry.tools()).map(([name, tool]) => ({
+    owner: "runtime-skill",
+    authorized: true,
+    requiredExecutionLevel: name === "run_skill_script" ? "high" : "safe",
+    tool: aiToolToPi(name, tool, {
+      label: SKILL_TOOL_LABELS[name] ?? name,
+    }),
+  }));
 }