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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/worker-bundle",
-  "version": "0.27.0-canary.0",
+  "version": "0.27.2-canary.0",
   "description": "OpenGeni worker entry and reusable embedded lifecycle, shipped with a release-coherent pre-bundled Temporal workflow artifact.",
   "license": "Apache-2.0",
   "repository": {
@@ -54,22 +54,22 @@
   },
   "dependencies": {
     "@llamaindex/liteparse": "2.14.2",
-    "@opengeni/agent-proto": "^0.5.1-canary.18",
-    "@opengeni/capabilities": "^0.3.3-canary.0",
-    "@opengeni/codemode": "^0.5.0-canary.0",
-    "@opengeni/codex": "^0.2.22-canary.0",
-    "@opengeni/config": "^1.0.1-canary.0",
-    "@opengeni/contracts": "^2.14.0-canary.0",
-    "@opengeni/core": "^2.8.0-canary.0",
-    "@opengeni/db": "^4.1.0-canary.0",
-    "@opengeni/documents": "^0.8.20-canary.0",
-    "@opengeni/events": "^0.4.18-canary.0",
-    "@opengeni/github": "^0.7.4-canary.0",
-    "@opengeni/network": "^0.3.1-canary.0",
-    "@opengeni/observability": "^0.8.20-canary.0",
-    "@opengeni/runtime": "^2.4.0-canary.0",
-    "@opengeni/storage": "^0.2.121-canary.0",
-    "@opengeni/xai-subscription": "^0.1.4-canary.0",
+    "@opengeni/agent-proto": "^0.5.1-canary.20",
+    "@opengeni/capabilities": "^0.3.3-canary.2",
+    "@opengeni/codemode": "^0.5.2-canary.0",
+    "@opengeni/codex": "^0.2.22-canary.2",
+    "@opengeni/config": "^1.0.3-canary.0",
+    "@opengeni/contracts": "^2.15.1-canary.0",
+    "@opengeni/core": "^2.8.2-canary.0",
+    "@opengeni/db": "^4.2.1-canary.0",
+    "@opengeni/documents": "^0.8.22-canary.0",
+    "@opengeni/events": "^0.4.20-canary.0",
+    "@opengeni/github": "^0.7.6-canary.0",
+    "@opengeni/network": "^0.3.1-canary.2",
+    "@opengeni/observability": "^0.8.22-canary.0",
+    "@opengeni/runtime": "^2.4.2-canary.0",
+    "@opengeni/storage": "^0.2.123-canary.0",
+    "@opengeni/xai-subscription": "^0.1.4-canary.2",
     "@temporalio/activity": "^1.17.0",
     "@temporalio/client": "^1.17.0",
     "@temporalio/worker": "^1.17.0",

package/src/activities/agent-turn/agent-build.ts

@@ -8,6 +8,7 @@ import {
   loadWorkspaceVercelAiGatewayCredentialLease,
 } from "@opengeni/db";
 import {
+  formatSkillCatalog,
   type AttemptConnectorActionBinding,
   type BuildAgentOptions,
   type ConnectorActionPolicyHooks,
@@ -34,10 +35,7 @@ import { VideoReferenceInputError } from "../video-reference-staging";
 import { rigProviderImageSourceImage } from "../packs";
 import type { TurnActivityServices as ActivityServices, RunAgentTurnInput } from "../types";
 import { recordTurnStartupPhase } from "../../observability-metrics";
-import {
-  modelVisibleCompanyBrainSkillActivations,
-  summarizeCompanyBrainContributions,
-} from "../../model-context-contributions";
+import { summarizeCompanyBrainContributions } from "../../model-context-contributions";
 import { createTurnCredentialLeases } from "./credential-leases";
 import { createTurnMediaArtifacts } from "./media-artifacts";
 import { executeGatewayImageGeneration } from "../gateway-image-generation";
@@ -75,6 +73,7 @@ import { resolveTurnSandboxAccess } from "./turn-sandbox-access";
 import { resolveVideoReferenceSandboxAccess } from "./video-reference-sandbox";
 
 export type BuildTurnAgentDeps = {
+  skillCatalog: NonNullable<BuildAgentOptions["skillCatalog"]>;
   input: RunAgentTurnInput;
   db: ActivityServices["db"];
   runtime: ActivityServices["runtime"];
@@ -109,8 +108,6 @@ export type BuildTurnAgentDeps = {
   workspaceMemory: GovernanceModelOk["workspaceMemory"];
   rigVersion: GovernanceModelOk["rigVersion"];
   rigName: GovernanceModelOk["rigName"];
-  packRuntime: GovernanceModelOk["packRuntime"];
-  installedSkillRuntime: GovernanceModelOk["installedSkillRuntime"];
   buildCompanyBrainContributionReceiptFor: GovernanceModelOk["buildCompanyBrainContributionReceiptFor"];
   promptCacheKey: CompactionPrepOk["promptCacheKey"];
   workspaceVariableSet: Awaited<ReturnType<typeof loadWorkspaceEnvironmentForRunWithCredentials>>;
@@ -170,8 +167,6 @@ export async function buildTurnAgent(deps: BuildTurnAgentDeps) {
     workspaceMemory,
     rigVersion,
     rigName,
-    packRuntime,
-    installedSkillRuntime,
     buildCompanyBrainContributionReceiptFor,
     promptCacheKey,
     workspaceVariableSet,
@@ -559,30 +554,10 @@ export async function buildTurnAgent(deps: BuildTurnAgentDeps) {
     turnExecutionPolicy.latencyMode,
   );
   const approvedToolCallId = approvedConnectorActionCallId(trigger);
-  const runtimeSkillActivations = [
-    ...installedSkillRuntime.activations,
-    ...packRuntime.skillActivations,
-    ...session.skills.map((skill) => ({
-      source: "session" as const,
-      id: `session:${session.id}:${skill.name}`,
-      artifact: {
-        name: skill.name,
-        description: skill.description ?? null,
-        files: skill.files.map((file) => ({
-          path: file.path,
-          content: file.content,
-        })),
-      },
-      reason: "attached to session",
-    })),
-  ];
-  const modelVisibleRuntimeSkillActivations = modelVisibleCompanyBrainSkillActivations(
-    eventing.modelRunSettings.sandboxBackend,
-    runtimeSkillActivations,
-  );
+  const modelVisibleSkillCatalogText = formatSkillCatalog(deps.skillCatalog);
   try {
     eventing.companyBrainContextContributions = summarizeCompanyBrainContributions(
-      buildCompanyBrainContributionReceiptFor(modelVisibleRuntimeSkillActivations),
+      buildCompanyBrainContributionReceiptFor(modelVisibleSkillCatalogText),
     );
   } catch {
     // Contribution telemetry must never change model execution semantics.
@@ -701,9 +676,8 @@ export async function buildTurnAgent(deps: BuildTurnAgentDeps) {
               promptCacheKey: input.sessionId,
             }),
         onRetainableSessionImageOutput: media.retainSessionImageAtToolBoundary,
-        ...(runtimeSkillActivations.length > 0
-          ? { skillActivations: runtimeSkillActivations }
-          : {}),
+        skillCatalog: deps.skillCatalog,
+        serverSkillReading: true,
         ...(!structuredWorkspacePolicyActive && workspaceAgentInstructions
           ? { instructionsTemplate: workspaceAgentInstructions }
           : {}),
@@ -772,7 +746,7 @@ export async function buildTurnAgent(deps: BuildTurnAgentDeps) {
   }
   return {
     agent,
-    modelVisibleRuntimeSkillActivations,
+    modelVisibleSkillCatalogText,
     postAgentPreparationStartedAt,
   };
 }

package/src/activities/agent-turn/errors.ts

@@ -24,6 +24,7 @@ import {
 } from "@opengeni/runtime/mcp-network";
 import { ApplicationFailure, CancelledFailure } from "@temporalio/activity";
 import { CODEX_USAGE_EXHAUSTED_PCT } from "../codex-rotation";
+import { RetainedAttachmentTransportLimitError } from "../run-input";
 import type { CodexAccountStatus } from "@opengeni/db";
 import {
   CodexReloginRequired,
@@ -870,6 +871,9 @@ export function agentRunFailurePayload(
   historyPersistenceStage?: MandatoryHistoryPersistenceStage;
   mcpTransportDiagnostic?: McpTransportRequestFailureDiagnostic;
 } {
+  if (error instanceof RetainedAttachmentTransportLimitError) {
+    return { error: error.message, code: "retained_attachment_transport_limit", retryable: false };
+  }
   if (error instanceof MandatoryHistoryPersistenceError) {
     const underlying = isSessionEventPersistenceError(error.cause)
       ? agentRunFailurePayload(error.cause, options)

package/src/activities/agent-turn/governance-model.ts

@@ -1,6 +1,7 @@
 import {
   materializeRigVersionForAttempt,
   getWorkspaceModelPolicy,
+  getFilesForSubject,
   getWorkspace,
   resolveCompanyBrainContextSelection,
   getGeneratedVideoArtifact,
@@ -22,11 +23,7 @@ import {
 import { settingsWithResolvedModelContext, type Settings } from "@opengeni/config";
 import { settingsWithSessionMcpServersForRun } from "../capabilities";
 import { resolveRigProviderImageForRun } from "@opengeni/core";
-import {
-  resolveWorkspacePackRuntime,
-  resolveWorkspaceInstalledSkillRuntime,
-  settingsWithPackSandboxImage,
-} from "../packs";
+import { resolveWorkspacePackRuntime, settingsWithPackSandboxImage } from "../packs";
 import { createModelHistoryAttachmentProjector } from "../run-input";
 import type {
   TurnActivityServices as ActivityServices,
@@ -88,7 +85,6 @@ export type GovernanceModelDeps = {
 export type GovernanceModelOk = {
   runtimePreparationStartedAt: number;
   packRuntime: Awaited<ReturnType<typeof resolveWorkspacePackRuntime>>;
-  installedSkillRuntime: Awaited<ReturnType<typeof resolveWorkspaceInstalledSkillRuntime>>;
   rigVersion:
     | NonNullable<Awaited<ReturnType<typeof materializeRigVersionForAttempt>>>["version"]
     | null;
@@ -99,9 +95,7 @@ export type GovernanceModelOk = {
   structuredWorkspacePolicyActive: boolean;
   workspaceMemory: string | null | undefined;
   buildCompanyBrainContributionReceiptFor: (
-    skillActivations: Parameters<
-      typeof buildCompanyBrainContributionReceipt
-    >[0]["skillActivations"],
+    skillCatalogText: string,
   ) => ReturnType<typeof buildCompanyBrainContributionReceipt>;
   logicalSandboxSettings: Settings;
   verifiedRigProviderImageId: string | undefined;
@@ -201,13 +195,11 @@ export async function prepareGovernanceAndModel(
   // snapshots below so its receipt stays exact.
   const [
     packRuntime,
-    installedSkillRuntime,
     rigMaterialization,
     [workspace, companyProfileSnapshot, instructionPolicySnapshot, preferenceSnapshot],
     workspaceModelPolicy,
   ] = await Promise.all([
     resolveWorkspacePackRuntime(db, input.workspaceId),
-    resolveWorkspaceInstalledSkillRuntime(db, input.workspaceId),
     session.rigId && session.rigVersionId
       ? (async () =>
           await materializeRigVersionForAttempt(db, {
@@ -254,16 +246,13 @@ export async function prepareGovernanceAndModel(
     },
     {
       includeCompanyProfile: companyProfileIncluded,
+      sharedSkillReader: true,
     },
   );
   const structuredWorkspacePolicyActive =
     hasActiveWorkspaceInstructionPolicy(instructionPolicySnapshot);
   const workspaceMemory = contextSelection.workspaceMemory;
-  const buildCompanyBrainContributionReceiptFor = (
-    skillActivations: Parameters<
-      typeof buildCompanyBrainContributionReceipt
-    >[0]["skillActivations"],
-  ) =>
+  const buildCompanyBrainContributionReceiptFor = (skillCatalogText: string) =>
     buildCompanyBrainContributionReceipt({
       contextSelectionReceiptId: contextSelection.receipt.id,
       attemptId: input.attemptId,
@@ -276,7 +265,8 @@ export async function prepareGovernanceAndModel(
       companyProfile: companyProfileSnapshot,
       companyProfileIncluded,
       workspaceMemory,
-      skillActivations,
+      skillActivations: [],
+      skillCatalogText,
     });
   try {
     // Portable operator compaction runs before tool/skill preparation, so its
@@ -284,7 +274,7 @@ export async function prepareGovernanceAndModel(
     // no runtime skill catalog. Later compaction paths replace this summary
     // after the complete skill activation set is resolved.
     eventing.companyBrainContextContributions = summarizeCompanyBrainContributions(
-      buildCompanyBrainContributionReceiptFor([]),
+      buildCompanyBrainContributionReceiptFor(""),
     );
   } catch {
     // Contribution telemetry must never change model execution semantics.
@@ -367,6 +357,13 @@ export async function prepareGovernanceAndModel(
           return object.bytes;
         }
       : undefined,
+    (fileIds) =>
+      getFilesForSubject(db, {
+        accountId: input.accountId,
+        workspaceId: input.workspaceId,
+        subjectId: fileAuthoritySubjectId,
+        fileIds,
+      }),
   );
   const modelHistoryProjector = async (
     items: Array<Record<string, unknown>>,
@@ -464,7 +461,6 @@ export async function prepareGovernanceAndModel(
     ok: {
       runtimePreparationStartedAt,
       packRuntime,
-      installedSkillRuntime,
       rigVersion,
       rigName,
       agentHumanInputEnabled,

package/src/activities/agent-turn/run.ts

@@ -479,7 +479,6 @@ export function createRunAgentTurnActivity(services: () => Promise<ActivityServi
       const {
         runtimePreparationStartedAt,
         packRuntime,
-        installedSkillRuntime,
         rigVersion,
         rigName,
         agentHumanInputEnabled,
@@ -1152,6 +1151,7 @@ export function createRunAgentTurnActivity(services: () => Promise<ActivityServi
         ).values(),
       ];
       const toolRuntime = await prepareTurnToolRuntime({
+        selectedSkillActivations: packRuntime.skillActivations,
         input,
         catalogSourceSettings,
         db,
@@ -1199,6 +1199,7 @@ export function createRunAgentTurnActivity(services: () => Promise<ActivityServi
       } = toolRuntime;
 
       const builtAgent = await buildTurnAgent({
+        skillCatalog: toolRuntime.skillCatalog,
         input,
         db,
         runtime,
@@ -1233,8 +1234,6 @@ export function createRunAgentTurnActivity(services: () => Promise<ActivityServi
         workspaceMemory,
         rigVersion,
         rigName,
-        packRuntime,
-        installedSkillRuntime,
         buildCompanyBrainContributionReceiptFor,
         promptCacheKey,
         workspaceVariableSet,
@@ -1256,8 +1255,7 @@ export function createRunAgentTurnActivity(services: () => Promise<ActivityServi
         postToolPreparationStartedAt,
         codexContext,
       });
-      const { agent, modelVisibleRuntimeSkillActivations, postAgentPreparationStartedAt } =
-        builtAgent;
+      const { agent, modelVisibleSkillCatalogText, postAgentPreparationStartedAt } = builtAgent;
 
       await bindLazySandboxProvisioner({
         ...sandboxRoute,
@@ -1313,7 +1311,7 @@ export function createRunAgentTurnActivity(services: () => Promise<ActivityServi
         companyBrainContributionReceiptRecorded = true;
         try {
           const companyBrainContributionReceipt = buildCompanyBrainContributionReceiptFor(
-            modelVisibleRuntimeSkillActivations,
+            modelVisibleSkillCatalogText,
           );
           eventing.companyBrainContextContributions = summarizeCompanyBrainContributions(
             companyBrainContributionReceipt,

package/src/activities/agent-turn/sandbox-provision.ts

@@ -361,6 +361,15 @@ export function classifySandboxLogicalProvisionFailure(
 
 export function isLazySandboxProvisionRetryable(error: unknown): boolean {
   const chain = sandboxProvisionErrorChain(error);
+  // Rotation resumes through the durable lifecycle wake. Retrying here holds
+  // a turn worker and can repeat the entire lease wait for every skill root.
+  if (
+    chain.some(
+      (value) =>
+        value instanceof SandboxLeaseTransitionError && value.reason === "rotation_in_progress",
+    )
+  )
+    return false;
   if (
     chain.some(
       (value) =>

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

@@ -0,0 +1,124 @@
+import type { AttemptToolDefinition } from "@opengeni/codemode";
+import type { SandboxChannelAService } from "@opengeni/runtime/sandbox";
+import type { SkillTextFile } from "@opengeni/runtime/skill-library";
+import { checkoutSkillDirectory, readSkillDirectory } from "./skill-transfer";
+import type { SkillSaveReceipt, SkillSaveRequest } from "./skill-save";
+
+type SkillFileSystem = Pick<SandboxChannelAService, "fsList" | "fsRead" | "fsWrite" | "fsMkdir">;
+
+export function createSkillCheckoutAttemptToolDefinition(input: {
+  authorize: () => Promise<void>;
+  load: (skill: string) => Promise<{
+    skillId: string;
+    revisionId: string | null;
+    scopeVersion: number | null;
+    files: readonly SkillTextFile[];
+  }>;
+  filesystem: () => Promise<SkillFileSystem>;
+}): AttemptToolDefinition {
+  return {
+    identity: { serverId: "opengeni", toolName: "skill_checkout" },
+    modelName: "skill_checkout",
+    codemodePath: ["opengeni", "skill_checkout"],
+    title: "Check out Skill files",
+    description:
+      "Copy a Skill to a fresh sandbox-relative directory for execution or larger edits. Starts the sandbox if needed. Never overwrites an existing directory and does not publish changes. Retain the returned revision and scope version for skill_publish. Use skill_read for ordinary reading without a sandbox.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        skill: { type: "string", minLength: 1, maxLength: 512 },
+        directory: { type: "string", minLength: 1, maxLength: 1024 },
+      },
+      required: ["skill", "directory"],
+      additionalProperties: false,
+    },
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: false,
+    },
+    source: "opengeni",
+    approval: "none",
+    execute: async (args) => {
+      await input.authorize();
+      const skill = await input.load(args.skill as string);
+      const copied = await checkoutSkillDirectory(
+        await input.filesystem(),
+        args.directory as string,
+        skill.files,
+      );
+      const output = {
+        ...copied,
+        skillId: skill.skillId,
+        revisionId: skill.revisionId,
+        scopeVersion: skill.scopeVersion,
+      };
+      return {
+        isError: false,
+        content: [{ type: "text", text: JSON.stringify(output) }],
+        structuredContent: output,
+      };
+    },
+  };
+}
+
+export function createSkillPublishAttemptToolDefinition(input: {
+  authorize: () => Promise<void>;
+  filesystem: () => Promise<SkillFileSystem>;
+  save: (request: SkillSaveRequest) => Promise<SkillSaveReceipt>;
+}): AttemptToolDefinition {
+  return {
+    identity: { serverId: "opengeni", toolName: "skill_publish" },
+    modelName: "skill_publish",
+    codemodePath: ["opengeni", "skill_publish"],
+    title: "Publish Skill directory",
+    description:
+      "Save a complete sandbox Skill directory through the same Learning-controlled service as skill_save. Reads UTF-8 text files directly; do not serialize the directory into arguments. Files missing from the directory are removed from the new revision. Supply the checkout revision and scope version; stale edits are refused. The result reports whether the change is live or pending approval.",
+    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 },
+        directory: { type: "string", minLength: 1, maxLength: 1024 },
+        reason: { type: "string", minLength: 1, maxLength: 2000 },
+      },
+      required: [
+        "operationId",
+        "skillId",
+        "expectedRevisionId",
+        "expectedScopeVersion",
+        "directory",
+        "reason",
+      ],
+      additionalProperties: false,
+    },
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
+    source: "opengeni",
+    approval: "none",
+    execute: async (args) => {
+      await input.authorize();
+      const artifact = await readSkillDirectory(await input.filesystem(), args.directory as string);
+      const output = await input.save({
+        operationId: args.operationId as string,
+        skillId: args.skillId as string,
+        expectedRevisionId: args.expectedRevisionId as string | null,
+        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-install.ts

@@ -0,0 +1,57 @@
+import type { AttemptToolDefinition } from "@opengeni/codemode";
+import type { SkillSaveReceipt } from "./skill-save";
+
+/** The installer resolves/pins bytes and persists them through the shared lifecycle. */
+export function createSkillInstallAttemptToolDefinition(input: {
+  authorize: () => Promise<void>;
+  install: (request: {
+    operationId: string;
+    source: string;
+    expectedInstallationVersion?: number;
+    reason: string;
+  }) => Promise<SkillSaveReceipt>;
+}): AttemptToolDefinition {
+  return {
+    identity: { serverId: "opengeni", toolName: "skill_install" },
+    modelName: "skill_install",
+    codemodePath: ["opengeni", "skill_install"],
+    title: "Install a Skill",
+    description:
+      "Install a Skill from a public skills.sh or GitHub URL, or library:<id> returned by skill_search. The server resolves and pins the source; no prior preview or invented hash is required. Learning mode controls activation. Replacing an existing installation requires its current installation version, and preserves workspace customizations.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        operationId: { type: "string", format: "uuid" },
+        source: { type: "string", minLength: 1, maxLength: 2048 },
+        expectedInstallationVersion: { type: "integer", minimum: 0 },
+        reason: { type: "string", minLength: 1, maxLength: 2000 },
+      },
+      required: ["operationId", "source", "reason"],
+      additionalProperties: false,
+    },
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true,
+    },
+    source: "opengeni",
+    approval: "none",
+    execute: async (args) => {
+      await input.authorize();
+      const output = await input.install({
+        operationId: args.operationId as string,
+        source: args.source as string,
+        ...(args.expectedInstallationVersion !== undefined
+          ? { expectedInstallationVersion: args.expectedInstallationVersion as number }
+          : {}),
+        reason: args.reason as string,
+      });
+      return {
+        isError: false,
+        content: [{ type: "text", text: JSON.stringify(output) }],
+        structuredContent: output,
+      };
+    },
+  };
+}

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

@@ -0,0 +1,117 @@
+import type { AttemptToolDefinition } from "@opengeni/codemode";
+import {
+  assertSkillRelativePath,
+  PORTABLE_SKILL_MAX_FILES,
+  readSkillFiles,
+  SKILL_READ_MAX_OUTPUT_BYTES,
+  SKILL_READ_MAX_PATHS,
+  type SkillTextFile,
+} from "@opengeni/runtime/skill-library";
+
+export const SKILL_READ_TOOL_NAME = "skill_read";
+
+export type SkillReadContent = Readonly<{
+  files: readonly SkillTextFile[];
+  skillId: string;
+  revisionId: string;
+  scopeVersion: number;
+  installationVersion?: number;
+}>;
+
+/** A first-party gateway definition, not a sandbox capability or second backend. */
+export function createSkillReadAttemptToolDefinition(input: {
+  authorize: () => Promise<void>;
+  load: (skill: string) => Promise<readonly SkillTextFile[] | SkillReadContent>;
+}): AttemptToolDefinition {
+  return {
+    identity: { serverId: "opengeni", toolName: SKILL_READ_TOOL_NAME },
+    modelName: SKILL_READ_TOOL_NAME,
+    codemodePath: ["opengeni", SKILL_READ_TOOL_NAME],
+    title: "Read Skill files",
+    description:
+      "Read Skill text without starting a sandbox. Omit paths to read SKILL.md; provide relative paths to read exactly those files, never implicitly adding SKILL.md. Set listFiles:true without paths to list relative paths and available revision identity only, with no file bodies. Use an id or name from the Skill index or skill_search. Management tools are lazy; when listed, opengeni-skills explains how to use them.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        skill: { type: "string", minLength: 1, maxLength: 512 },
+        listFiles: { type: "boolean" },
+        paths: {
+          type: "array",
+          minItems: 1,
+          maxItems: SKILL_READ_MAX_PATHS,
+          uniqueItems: true,
+          items: { type: "string", minLength: 1, maxLength: 1024 },
+        },
+      },
+      required: ["skill"],
+      additionalProperties: false,
+    },
+    annotations: {
+      title: "Read Skill files",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
+    source: "opengeni",
+    approval: "none",
+    execute: async (args) => {
+      if (
+        typeof args.skill !== "string" ||
+        !args.skill ||
+        (args.listFiles !== undefined && typeof args.listFiles !== "boolean") ||
+        (args.paths !== undefined &&
+          (!Array.isArray(args.paths) || args.paths.some((path) => typeof path !== "string")))
+      ) {
+        throw new Error("skill_read requires a Skill identifier and optional relative paths.");
+      }
+      if (args.listFiles === true && args.paths !== undefined) {
+        throw new Error("skill_read listFiles:true cannot be combined with paths.");
+      }
+      await input.authorize();
+      const loaded = await input.load(args.skill);
+      const metadata = "files" in loaded ? loaded : null;
+      const files = metadata ? metadata.files : (loaded as readonly SkillTextFile[]);
+      const selected =
+        args.listFiles === true
+          ? listSkillPaths(files)
+          : readSkillFiles(files, args.paths as string[] | undefined);
+      const output = {
+        ...(metadata
+          ? {
+              skillId: metadata.skillId,
+              revisionId: metadata.revisionId,
+              scopeVersion: metadata.scopeVersion,
+              ...(metadata.installationVersion !== undefined
+                ? { installationVersion: metadata.installationVersion }
+                : {}),
+            }
+          : {}),
+        ...selected,
+      };
+      return {
+        isError: false,
+        content: [{ type: "text", text: JSON.stringify(output) }],
+        structuredContent: output,
+      };
+    },
+  };
+}
+
+/** Inventory never reads or serializes file bodies, including the entry point. */
+function listSkillPaths(files: readonly SkillTextFile[]): { paths: string[] } {
+  if (files.length > PORTABLE_SKILL_MAX_FILES) {
+    throw new Error(`Skill inventory exceeds ${PORTABLE_SKILL_MAX_FILES} files.`);
+  }
+  const seen = new Set<string>();
+  for (const { path } of files) {
+    assertSkillRelativePath(path);
+    if (seen.has(path)) throw new Error(`Duplicate stored Skill path: ${path}`);
+    seen.add(path);
+  }
+  const result = { paths: [...seen].sort() };
+  if (Buffer.byteLength(JSON.stringify(result), "utf8") > SKILL_READ_MAX_OUTPUT_BYTES) {
+    throw new Error("Skill inventory exceeds the read output limit.");
+  }
+  return result;
+}