@opengeni/worker-bundle 0.27.0-canary.0 → 0.27.2-canary.0

package/src/activities/agent-turn/skill-save.ts

@@ -0,0 +1,124 @@
+import type { AttemptToolDefinition } from "@opengeni/codemode";
+import {
+  applySkillFileChanges,
+  buildPortableSkillArtifact,
+  PORTABLE_SKILL_MAX_FILES,
+  type SkillTextFile,
+} from "@opengeni/runtime/skill-library";
+
+export type SkillSaveRequest = {
+  operationId: string;
+  skillId: string;
+  expectedRevisionId: string | null;
+  expectedScopeVersion: number;
+  files: readonly SkillTextFile[];
+  reason: string;
+};
+
+export type SkillSaveReceipt = {
+  operationId: string;
+  skillId: string;
+  revisionId: string;
+  outcome: "applied" | "pending" | "preserved";
+  replayed: boolean;
+};
+
+/** Persistence owns mode enforcement, replay, and the final compare-and-swap. */
+export function createSkillSaveAttemptToolDefinition(input: {
+  authorize: () => Promise<void>;
+  load: (
+    skillId: string,
+    revisionId: string,
+  ) => Promise<{
+    revisionId: string;
+    files: readonly SkillTextFile[];
+  }>;
+  save: (request: SkillSaveRequest) => Promise<SkillSaveReceipt>;
+}): AttemptToolDefinition {
+  return {
+    identity: { serverId: "opengeni", toolName: "skill_save" },
+    modelName: "skill_save",
+    codemodePath: ["opengeni", "skill_save"],
+    title: "Save Skill text",
+    description:
+      "Create or edit a workspace Skill without a sandbox. Supply only changed UTF-8 text files and explicit deletions; omitted files are preserved. Use the revision and scope version returned by Skill discovery for stale-write protection. For creation choose a new UUID, set expectedRevisionId to null and expectedScopeVersion to 1. Learning mode determines whether the change is live, pending approval, or refused. If humanInput is returned, call request_human_input verbatim, Save activates the exact reviewed revision as the answer is accepted. Do not ask for a second review or call a separate activation tool.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        operationId: { type: "string", format: "uuid" },
+        skillId: { type: "string", format: "uuid" },
+        expectedRevisionId: { type: ["string", "null"], format: "uuid" },
+        expectedScopeVersion: { type: "integer", minimum: 0 },
+        files: {
+          type: "array",
+          maxItems: PORTABLE_SKILL_MAX_FILES,
+          items: {
+            type: "object",
+            properties: {
+              path: { type: "string", minLength: 1, maxLength: 1024 },
+              content: { type: "string" },
+            },
+            required: ["path", "content"],
+            additionalProperties: false,
+          },
+        },
+        deletions: {
+          type: "array",
+          maxItems: PORTABLE_SKILL_MAX_FILES,
+          uniqueItems: true,
+          items: { type: "string", minLength: 1, maxLength: 1024 },
+        },
+        reason: { type: "string", minLength: 1, maxLength: 2000 },
+      },
+      required: [
+        "operationId",
+        "skillId",
+        "expectedRevisionId",
+        "expectedScopeVersion",
+        "files",
+        "reason",
+      ],
+      additionalProperties: false,
+    },
+    annotations: {
+      title: "Save Skill text",
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
+    source: "opengeni",
+    approval: "none",
+    execute: async (args) => {
+      await input.authorize();
+      const skillId = args.skillId as string;
+      const expectedRevisionId = args.expectedRevisionId as string | null;
+      // Expand the edit against its immutable base, not today's head. The
+      // lifecycle can then replay an already committed operation before CAS.
+      const current =
+        expectedRevisionId === null ? null : await input.load(skillId, expectedRevisionId);
+      if (current && current.revisionId !== expectedRevisionId) {
+        throw new Error("Skill edit base did not match the requested revision.");
+      }
+      const files = applySkillFileChanges(
+        current?.files ?? [],
+        args.files as SkillTextFile[],
+        (args.deletions ?? []) as string[],
+      );
+      const artifact = buildPortableSkillArtifact(files);
+      const output = await input.save({
+        operationId: args.operationId as string,
+        skillId,
+        expectedRevisionId,
+        expectedScopeVersion: args.expectedScopeVersion as number,
+        files: artifact.files,
+        reason: args.reason as string,
+      });
+      return {
+        isError: false,
+        content: [{ type: "text", text: JSON.stringify(output) }],
+        structuredContent: output,
+      };
+    },
+  };
+}

package/src/activities/agent-turn/skill-search.ts

@@ -0,0 +1,110 @@
+import type { AttemptToolDefinition } from "@opengeni/codemode";
+import { PublicSkillSearchError, type PublicSkillSearchClient } from "@opengeni/core";
+import { listSkillLibraryEntries } from "@opengeni/runtime/skill-library";
+
+export type WorkspaceSkillSearchEntry = Readonly<{
+  id: string;
+  name: string;
+  description: string;
+  revisionId?: string;
+  scopeVersion?: number;
+  installationVersion?: number;
+  source?: "workspace" | "builtin" | "session" | "pack";
+}>;
+
+export function createSkillSearchAttemptToolDefinition(input: {
+  authorize: () => Promise<void>;
+  listWorkspace: () => Promise<readonly WorkspaceSkillSearchEntry[]>;
+  publicSearch: PublicSkillSearchClient;
+}): AttemptToolDefinition {
+  return {
+    identity: { serverId: "opengeni", toolName: "skill_search" },
+    modelName: "skill_search",
+    codemodePath: ["opengeni", "skill_search"],
+    title: "Search Skills",
+    description:
+      "Find installed workspace Skills or available curated and public Skills. Returns identifiers and install sources, not file contents. Search never installs or starts a sandbox. Scope defaults to all; use installed to avoid external search.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", minLength: 2, maxLength: 200 },
+        scope: { type: "string", enum: ["installed", "catalog", "all"] },
+        limit: { type: "integer", minimum: 1, maximum: 20 },
+      },
+      required: ["query"],
+      additionalProperties: false,
+    },
+    annotations: {
+      title: "Search Skills",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true,
+    },
+    source: "opengeni",
+    approval: "none",
+    execute: async (args) => {
+      await input.authorize();
+      const query = String(args.query).trim();
+      const scope = args.scope ?? "all";
+      const limit = typeof args.limit === "number" ? args.limit : 20;
+      const searchText = query.toLowerCase();
+      const matches = (entry: { name: string; description: string }) =>
+        `${entry.name}\n${entry.description}`.toLowerCase().includes(searchText);
+      const installed = scope === "catalog" ? [] : await input.listWorkspace();
+      const workspaceHits = installed
+        .filter(matches)
+        .slice(0, limit)
+        .map((entry) => ({
+          ...entry,
+          source: entry.source ?? "workspace",
+          installed: !entry.source || entry.source === "workspace",
+        }));
+      const libraryHits =
+        scope === "installed"
+          ? []
+          : listSkillLibraryEntries()
+              .filter(matches)
+              .slice(0, limit)
+              .map((entry) => ({
+                id: `library:${entry.id}`,
+                name: entry.name,
+                description: entry.description,
+                source: "library" as const,
+                libraryId: entry.id,
+              }));
+      let publicResult: Awaited<ReturnType<PublicSkillSearchClient["search"]>> | null = null;
+      let publicError: {
+        source: "skills_sh";
+        code: string;
+        retryAfterSeconds: number | null;
+      } | null = null;
+      if (scope !== "installed") {
+        try {
+          publicResult = await input.publicSearch.search({ query, limit });
+        } catch (error) {
+          if (!(error instanceof PublicSkillSearchError)) throw error;
+          publicError = {
+            source: "skills_sh",
+            code: error.code,
+            retryAfterSeconds: error.retryAfterSeconds,
+          };
+        }
+      }
+      const output = {
+        workspace: workspaceHits,
+        library: libraryHits,
+        public: publicResult?.items.map((entry) => ({ ...entry })) ?? [],
+        // A provider outage is not an empty search. Keep local results useful
+        // and expose partial failure explicitly, without leaking network details.
+        partial: publicError !== null,
+        errors: publicError ? [publicError] : [],
+      };
+      return {
+        isError: false,
+        content: [{ type: "text", text: JSON.stringify(output) }],
+        structuredContent: output,
+      };
+    },
+  };
+}

package/src/activities/agent-turn/skill-selection.ts

@@ -0,0 +1,53 @@
+import { loadNativeToolSkillArtifacts } from "@opengeni/runtime";
+import { loadSkillManagementSkill } from "@opengeni/runtime/skill-library";
+import type { BundledSkillId } from "@opengeni/contracts";
+
+export type BundledSkillConfiguration = {
+  /** Already resolved names, not discovered schemas or an attempt catalog. */
+  firstPartyTools: readonly string[];
+  videoGenerationEnabled: boolean;
+  bundledSkillIds?: readonly BundledSkillId[] | undefined;
+};
+
+/** Individual ordinary-code defaults, evaluated without async tool preparation. */
+export function configuredBundledSkillNames(context: BundledSkillConfiguration): string[] {
+  const tools = new Set(context.firstPartyTools);
+  const artifacts = () => tools.has("editable_artifact_list") && tools.has("editable_artifact_get");
+  const definitions = [
+    { name: "opengeni-skills", include: () => true },
+    { name: "opengeni-projects", include: () => true },
+    { name: "opengeni-documents", include: artifacts },
+    { name: "opengeni-spreadsheets", include: artifacts },
+    { name: "opengeni-presentations", include: artifacts },
+    {
+      name: "opengeni-sites",
+      include: () => tools.has("artifacts_create") && tools.has("artifacts_publish"),
+    },
+    { name: "opengeni-video-generation", include: () => context.videoGenerationEnabled },
+  ];
+  return definitions
+    .filter(
+      (definition) =>
+        definition.include() &&
+        (context.bundledSkillIds === undefined ||
+          context.bundledSkillIds.includes(`builtin:${definition.name}` as BundledSkillId)),
+    )
+    .map((definition) => definition.name);
+}
+
+export function loadConfiguredBundledSkills(context: BundledSkillConfiguration) {
+  const names = new Set(configuredBundledSkillNames(context));
+  const artifacts = loadNativeToolSkillArtifacts({
+    projects: names.has("opengeni-projects"),
+    editableArtifacts: [
+      "opengeni-documents",
+      "opengeni-spreadsheets",
+      "opengeni-presentations",
+    ].some((name) => names.has(name)),
+    sites: names.has("opengeni-sites"),
+    videoGeneration: names.has("opengeni-video-generation"),
+  });
+  return [...artifacts, ...(names.has("opengeni-skills") ? [loadSkillManagementSkill()] : [])]
+    .filter((artifact) => names.has(artifact.name))
+    .map((artifact) => ({ id: `builtin:${artifact.name}`, artifact }));
+}

package/src/activities/agent-turn/skill-tools.ts

@@ -0,0 +1,268 @@
+import { createHash } from "node:crypto";
+import type { Settings } from "@opengeni/config";
+import {
+  skillReviewHumanInput,
+  type SkillActor,
+  type SkillWriteReceipt,
+} from "@opengeni/contracts";
+import {
+  assertSkillReadAttempt,
+  skillReviewResolution,
+  installPortableSkill,
+  replayPortableSkillInstall,
+  listSkillDescriptors,
+  type Database,
+  type InstallPortableSkillInput,
+} from "@opengeni/db";
+import {
+  createGitHubSkillSourceClient,
+  createPublicSkillSearchClient,
+  portableSkillCapabilityId,
+  portableSkillPluginKey,
+  readSkill,
+  resolveSkillImport,
+  saveSkill,
+} from "@opengeni/core";
+import {
+  buildPortableSkillArtifact,
+  loadSkillLibrarySkill,
+  skillLibraryRepositoryUrl,
+  type SkillTextFile,
+} from "@opengeni/runtime/skill-library";
+import type { RuntimeSkillArtifact } from "@opengeni/runtime";
+import type { SandboxChannelAService } from "@opengeni/runtime/sandbox";
+import { createSkillReadAttemptToolDefinition, type SkillReadContent } from "./skill-read";
+import { createSkillSearchAttemptToolDefinition } from "./skill-search";
+import { createSkillSaveAttemptToolDefinition, type SkillSaveRequest } from "./skill-save";
+import { createSkillInstallAttemptToolDefinition } from "./skill-install";
+import {
+  createSkillCheckoutAttemptToolDefinition,
+  createSkillPublishAttemptToolDefinition,
+} from "./skill-checkout";
+
+export function createWorkspaceSkillTools(input: {
+  db: Database;
+  settings: Settings;
+  accountId: string;
+  workspaceId: string;
+  subjectId?: string;
+  actor: Extract<SkillActor, { kind: "agent" }>;
+  selected: readonly { id: string; artifact: RuntimeSkillArtifact }[];
+  filesystem: () => Promise<
+    Pick<SandboxChannelAService, "fsList" | "fsRead" | "fsWrite" | "fsMkdir">
+  >;
+}) {
+  const context = {
+    accountId: input.accountId,
+    workspaceId: input.workspaceId,
+    ...(input.subjectId ? { subjectId: input.subjectId } : {}),
+  };
+  const authorize = () => assertSkillReadAttempt(input.db, { ...context, actor: input.actor });
+  const selected = new Map(input.selected.map((entry) => [entry.id, entry.artifact]));
+  const list = async () =>
+    (await listSkillDescriptors(input.db, context)).filter(
+      (entry) => entry.activationMode === "workspace_managed",
+    );
+  // Both text reads and inventory resolve through this same authorized source.
+  // Selected artifacts have no ledger revision identity; never synthesize one.
+  const load = async (identifier: string): Promise<readonly SkillTextFile[] | SkillReadContent> => {
+    const exact = selected.get(identifier);
+    if (exact) return exact.files;
+    const descriptors = await list();
+    const exactWorkspace = descriptors.find((entry) => entry.id === identifier);
+    const matches = exactWorkspace
+      ? [exactWorkspace]
+      : descriptors.filter((entry) => entry.title === identifier || entry.stableKey === identifier);
+    const selectedMatches = [...selected.entries()].filter(
+      ([, artifact]) => artifact.name === identifier,
+    );
+    if (!exactWorkspace && matches.length + selectedMatches.length > 1)
+      throw new Error(
+        "Multiple Skills match that name. Use the Skill id from the index or search.",
+      );
+    if (!matches.length && selectedMatches.length === 1) return selectedMatches[0]![1].files;
+    const match = matches[0];
+    if (!match) throw new Error("Skill is not available in this session.");
+    const record = await readSkill(input.db, context, match.id);
+    if (
+      !record ||
+      record.status !== "active" ||
+      !record.activeRevisionId ||
+      record.revisionId !== record.activeRevisionId
+    )
+      throw new Error("Skill is no longer active. Search again for current Skills.");
+    return {
+      skillId: record.id,
+      revisionId: record.activeRevisionId,
+      scopeVersion: record.scopeVersion,
+      ...(match.installationVersion !== null
+        ? { installationVersion: match.installationVersion }
+        : {}),
+      files: record.files,
+    };
+  };
+  const withConfirmation = async (receipt: SkillWriteReceipt) => {
+    const reviewResolution = receipt.skillReview
+      ? await skillReviewResolution(input.db, context, receipt.skillReview)
+      : undefined;
+    return {
+      ...receipt,
+      ...(reviewResolution ? { reviewResolution } : {}),
+      ...(receipt.skillReview && reviewResolution === "pending"
+        ? { humanInput: skillReviewHumanInput(receipt.skillReview) }
+        : {}),
+    };
+  };
+  const save = async (request: SkillSaveRequest) => {
+    const artifact = buildPortableSkillArtifact(request.files);
+    const base = request.expectedRevisionId
+      ? await readSkill(input.db, context, request.skillId, request.expectedRevisionId)
+      : null;
+    return withConfirmation(
+      await saveSkill(input.db, {
+        ...context,
+        ...request,
+        actor: input.actor,
+        files: [...artifact.files],
+        stableKey: base?.stableKey ?? `authored-${request.skillId.replaceAll("-", "")}`,
+      }),
+    );
+  };
+  return [
+    createSkillReadAttemptToolDefinition({ authorize, load }),
+    createSkillSearchAttemptToolDefinition({
+      authorize,
+      listWorkspace: async () => [
+        ...(await list()).map((entry) => ({
+          id: entry.id,
+          name: entry.title,
+          description: entry.description,
+          revisionId: entry.revisionId,
+          scopeVersion: entry.scopeVersion,
+          ...(entry.installationVersion !== null
+            ? { installationVersion: entry.installationVersion }
+            : {}),
+        })),
+        ...input.selected.map((entry) => ({
+          id: entry.id,
+          name: entry.artifact.name,
+          description: entry.artifact.description || entry.artifact.name,
+          source: entry.id.startsWith("builtin:")
+            ? ("builtin" as const)
+            : entry.id.startsWith("session:")
+              ? ("session" as const)
+              : ("pack" as const),
+        })),
+      ],
+      publicSearch: createPublicSkillSearchClient(input.settings),
+    }),
+    createSkillSaveAttemptToolDefinition({
+      authorize,
+      save,
+      load: async (skillId, revisionId) => {
+        const record = await readSkill(input.db, context, skillId, revisionId);
+        if (!record?.revisionId) throw new Error("Skill edit base is unavailable.");
+        return { revisionId: record.revisionId, files: record.files };
+      },
+    }),
+    createSkillInstallAttemptToolDefinition({
+      authorize,
+      install: async (request) => {
+        const requestIdentity = {
+          operation: "skill_install",
+          source: request.source,
+          expectedInstallationVersion: request.expectedInstallationVersion ?? null,
+          reason: request.reason,
+          owner: "direct",
+        };
+        const replay = await replayPortableSkillInstall(input.db, {
+          ...context,
+          actor: input.actor,
+          operationId: request.operationId,
+          requestIdentity,
+        });
+        if (replay) return withConfirmation(replay.skillReceipt);
+        let source: Omit<InstallPortableSkillInput, "accountId" | "workspaceId" | "subjectId">;
+        if (request.source.startsWith("library:")) {
+          const loaded = loadSkillLibrarySkill(request.source.slice("library:".length));
+          source = {
+            capabilityId: `skill:${loaded.entry.id}`,
+            pluginKey: `skill/library/${loaded.entry.id}`,
+            source: "library",
+            sourceUrl: loaded.entry.sourceUrl,
+            repositoryUrl: skillLibraryRepositoryUrl(loaded.entry.sourceUrl),
+            version: loaded.entry.version,
+            sourceCommit: loaded.entry.sourceCommit,
+            sourcePath: loaded.entry.relativePath,
+            name: loaded.entry.name,
+            description: loaded.entry.description,
+            contentSha256: loaded.entry.contentSha256,
+            totalBytes: loaded.skill.files.reduce(
+              (total, file) => total + Buffer.byteLength(file.content),
+              0,
+            ),
+            files: fileMetadata(loaded.skill.files),
+            provenance: "platform",
+            sourceProvenance: loaded.entry.provenance,
+            category: loaded.entry.category,
+            tags: [...loaded.entry.tags],
+            license: loaded.entry.license,
+          };
+        } else {
+          const resolved = await resolveSkillImport(
+            request.source,
+            createGitHubSkillSourceClient(input.settings),
+          );
+          source = {
+            capabilityId: portableSkillCapabilityId(resolved.preview),
+            pluginKey: portableSkillPluginKey(resolved.preview),
+            source: resolved.preview.source,
+            sourceUrl: resolved.preview.sourceUrl,
+            repositoryUrl: resolved.preview.repositoryUrl,
+            version: resolved.preview.sourceCommit,
+            sourceCommit: resolved.preview.sourceCommit,
+            sourcePath: resolved.preview.sourcePath,
+            name: resolved.preview.name,
+            description: resolved.preview.description,
+            contentSha256: resolved.preview.contentSha256,
+            totalBytes: resolved.preview.totalBytes,
+            files: fileMetadata(resolved.files),
+          };
+        }
+        const installed = await installPortableSkill(input.db, {
+          ...context,
+          ...source,
+          subjectId: `service:skill-attempt:${input.actor.attemptId}`,
+          skillActor: input.actor,
+          skillOperationId: request.operationId,
+          skillRequestIdentity: requestIdentity,
+          ...(request.expectedInstallationVersion !== undefined
+            ? {
+                expectedInstallationVersion: request.expectedInstallationVersion,
+              }
+            : {}),
+        });
+        return withConfirmation(installed.skillReceipt);
+      },
+    }),
+    createSkillCheckoutAttemptToolDefinition({
+      authorize,
+      filesystem: input.filesystem,
+      load: async (skill) => {
+        const content = await load(skill);
+        if (!("files" in content))
+          return { skillId: skill, revisionId: null, scopeVersion: null, files: content };
+        return content;
+      },
+    }),
+    createSkillPublishAttemptToolDefinition({ authorize, filesystem: input.filesystem, save }),
+  ];
+}
+
+function fileMetadata(files: readonly SkillTextFile[]) {
+  return files.map((file) => ({
+    ...file,
+    byteSize: Buffer.byteLength(file.content),
+    contentSha256: createHash("sha256").update(file.content, "utf8").digest("hex"),
+  }));
+}

package/src/activities/agent-turn/skill-transfer.ts

@@ -0,0 +1,137 @@
+import { posix } from "node:path";
+import type { SandboxChannelAService } from "@opengeni/runtime/sandbox";
+import {
+  assertSkillRelativePath,
+  buildPortableSkillArtifact,
+  PORTABLE_SKILL_MAX_FILES,
+  PORTABLE_SKILL_MAX_FILE_BYTES,
+  PORTABLE_SKILL_MAX_TOTAL_BYTES,
+  type SkillTextFile,
+} from "@opengeni/runtime/skill-library";
+
+type SkillFileSystem = Pick<SandboxChannelAService, "fsList" | "fsRead" | "fsWrite" | "fsMkdir">;
+const maxTraversalEntries = 1024;
+
+/** Reuse the host's cancellation and workspace-mutation authority for each filesystem operation. */
+export function guardSkillFilesystem(
+  fs: SkillFileSystem,
+  authority: {
+    assertActive: () => void;
+    runMutation: <T>(operation: () => Promise<T>) => Promise<T>;
+  },
+): SkillFileSystem {
+  const read = <T>(operation: () => Promise<T>): Promise<T> => {
+    authority.assertActive();
+    return operation();
+  };
+  const write = <T>(operation: () => Promise<T>): Promise<T> => {
+    authority.assertActive();
+    return authority.runMutation(() => read(operation));
+  };
+  return {
+    fsList: (request) => read(() => fs.fsList(request)),
+    fsRead: (request) => read(() => fs.fsRead(request)),
+    fsWrite: (request) => write(() => fs.fsWrite(request)),
+    fsMkdir: (request) => write(() => fs.fsMkdir(request)),
+  };
+}
+
+/** Caller supplies an authorized live filesystem and a fresh workspace-relative target. */
+export async function checkoutSkillDirectory(
+  fs: SkillFileSystem,
+  directory: string,
+  files: readonly SkillTextFile[],
+): Promise<{ directory: string; fileCount: number }> {
+  assertSkillRelativePath(directory);
+  const artifact = buildPortableSkillArtifact(files);
+  const parent = posix.dirname(directory);
+  if (parent !== ".") await fs.fsMkdir({ path: parent, recursive: true });
+  // Never overwrite an earlier checkout (which may now contain the user's edits).
+  await fs.fsMkdir({ path: directory, recursive: false });
+  for (const file of artifact.files) {
+    const result = await fs.fsWrite({
+      path: `${directory}/${file.path}`,
+      content: file.content,
+      encoding: "utf8",
+      overwrite: false,
+      createParents: true,
+    });
+    if (result.sizeBytes !== new TextEncoder().encode(file.content).byteLength) {
+      throw new Error(`Skill checkout wrote an unexpected byte count: ${file.path}`);
+    }
+  }
+  return { directory, fileCount: artifact.files.length };
+}
+
+/**
+ * Read a folder through existing structured filesystem services, never via model
+ * arguments. The caller owns workspace confinement and the final governed save.
+ * This operation does not execute scripts or activate the resulting artifact.
+ */
+export async function readSkillDirectory(fs: SkillFileSystem, directory: string) {
+  assertSkillRelativePath(directory);
+  const pending = [directory];
+  const seen = new Set<string>(pending);
+  const files: SkillTextFile[] = [];
+  let entries = 0;
+  let totalBytes = 0;
+  while (pending.length) {
+    const current = pending.shift()!;
+    const listing = await fs.fsList({
+      path: current,
+      depth: 1,
+      maxEntries: maxTraversalEntries + 1,
+      includeHidden: true,
+    });
+    if (listing.root.type !== "dir" || listing.root.path !== current) {
+      throw new Error(`Expected a real Skill directory: ${current}`);
+    }
+    if (listing.truncated || listing.root.truncated || !listing.root.children) {
+      throw new Error(`Skill directory listing is incomplete: ${current}`);
+    }
+    for (const entry of listing.root.children) {
+      assertSkillRelativePath(entry.path);
+      if (posix.dirname(entry.path) !== current || posix.basename(entry.path) !== entry.name) {
+        throw new Error("Skill directory listing returned a path outside the requested directory.");
+      }
+      if (seen.has(entry.path)) throw new Error(`Duplicate Skill directory entry: ${entry.path}`);
+      seen.add(entry.path);
+      if (++entries > maxTraversalEntries) throw new Error("Skill directory has too many entries.");
+      if (entry.type === "dir") {
+        pending.push(entry.path);
+        continue;
+      }
+      if (entry.type !== "file") throw new Error(`Unsupported Skill file type: ${entry.path}`);
+      if (files.length >= PORTABLE_SKILL_MAX_FILES) throw new Error("Skill has too many files.");
+      if (entry.sizeBytes !== null && entry.sizeBytes > PORTABLE_SKILL_MAX_FILE_BYTES) {
+        throw new Error(`Skill file exceeds the size limit: ${entry.path}`);
+      }
+      const read = await fs.fsRead({
+        path: entry.path,
+        encoding: "base64",
+        maxBytes: PORTABLE_SKILL_MAX_FILE_BYTES + 1,
+      });
+      if (read.truncated || read.sizeBytes > PORTABLE_SKILL_MAX_FILE_BYTES) {
+        throw new Error(`Skill file exceeds the size limit: ${entry.path}`);
+      }
+      if (read.encoding !== "base64" || read.path !== entry.path) {
+        throw new Error(`Invalid Skill file read response: ${entry.path}`);
+      }
+      const bytes = Buffer.from(read.content, "base64");
+      if (bytes.byteLength !== read.sizeBytes) {
+        throw new Error(`Invalid Skill file byte count: ${entry.path}`);
+      }
+      totalBytes += bytes.byteLength;
+      if (totalBytes > PORTABLE_SKILL_MAX_TOTAL_BYTES)
+        throw new Error("Skill exceeds the total size limit.");
+      let content: string;
+      try {
+        content = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+      } catch {
+        throw new Error(`Skill file is not valid UTF-8 text: ${entry.path}`);
+      }
+      files.push({ path: entry.path.slice(directory.length + 1), content });
+    }
+  }
+  return buildPortableSkillArtifact(files);
+}