@opengeni/runtime 0.13.13 → 0.14.1

package/dist/sandbox/index.js

@@ -170,7 +170,7 @@ import {
   withToolspaceTokenClient,
   withToolspaceTokenEnvironment,
   withToolspaceTokenSession
-} from "../chunk-3NUSY22C.js";
+} from "../chunk-HHWIZHQM.js";
 import "../chunk-4YJ5Z52Z.js";
 import "../chunk-K4V4QYCL.js";
 import "../chunk-PZ5AY32C.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/runtime",
-  "version": "0.13.13",
+  "version": "0.14.1",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -50,8 +50,8 @@
     "@openai/agents-extensions": "0.13.3",
     "@opengeni/agent-proto": "^0.3.0",
     "@opengeni/codex": "^0.2.7",
-    "@opengeni/config": "^0.7.8",
-    "@opengeni/contracts": "^0.20.1",
+    "@opengeni/config": "^0.7.11",
+    "@opengeni/contracts": "^0.22.0",
     "@opengeni/network": "^0.1.1",
     "debug": "4.4.3",
     "modal": "0.7.6",

package/src/context-compaction.ts

@@ -100,11 +100,6 @@ export function isCompactionSummary(item: unknown): boolean {
   );
 }
 
-/** Platform-authored system context exists for one inference and is never persisted. */
-export function isEphemeralInternalContext(item: unknown): boolean {
-  return itemType(item) === "message" && itemRole(item) === "system";
-}
-
 /**
  * Conservative tokenizer-independent text estimate used for every local input
  * budget. Preserve the stable ASCII `chars / 4` heuristic, but never discount

package/src/index.ts

@@ -15,6 +15,7 @@ import {
   approvalIdentifier,
   CAPABILITY_DESCRIPTORS,
   DEFAULT_FIRST_PARTY_MCP_PERMISSIONS,
+  DEFAULT_FIRST_PARTY_MCP_TOOLS,
   assertUniqueResourceMountPaths,
   gitCredentialBindingIdForRepository,
   gitCredentialProviderForRepository,
@@ -33,6 +34,7 @@ import {
   type HumanInputResponse,
   type McpServerConnectionRef,
   type Permission,
+  type FirstPartyMcpToolName,
   type ReasoningEffort,
   type ResourceRef,
   type SessionEventType,
@@ -177,6 +179,7 @@ import {
   type RunCredentialSessionReady,
 } from "./sandbox";
 import { runWithToolCallCorrelation } from "./sandbox/op-correlation";
+import { shellToolspacePath } from "./sandbox/toolspace-token";
 import {
   createTurnToolCancellationController,
   TurnSandboxCommandCancelledError,
@@ -187,6 +190,7 @@ import {
 } from "./sandbox/turn-tool-cancellation";
 import { computerUse, type ComputerToolMode } from "./sandbox-computer";
 import type { RuntimeMetricsHooks } from "./metrics";
+import { workspaceSkills, type WorkspaceSkillSearchPath } from "./workspace-skills";
 
 // The Agents SDK's debug namespaces can otherwise serialize complete model
 // inputs/outputs and tool arguments/results. These getters read process.env on
@@ -295,7 +299,6 @@ export {
   MAX_COMPACTION_THRESHOLD_RATIO,
   SUMMARY_BUFFER_TOKENS,
   SUMMARY_PREFIX,
-  isEphemeralInternalContext,
   USER_MESSAGE_TRUNCATION_MARKER,
 } from "./context-compaction";
 export type {
@@ -1260,7 +1263,7 @@ export type ToolspaceTokenWriterSession = SandboxSessionLike;
 export type EffectiveSkillSelection = Readonly<{
   id: string;
   name: string;
-  source: "bundled" | "library" | "pack";
+  source: "bundled" | "library" | "pack" | "session";
   version: string | null;
   contentSha256: string | null;
   reason: string;
@@ -1430,6 +1433,9 @@ export type BuildAgentOptions = {
   // skills in the sandbox skill index (mounted under .agents/) so
   // skills/<name> references resolve like any other indexed skill.
   packSkills?: PackSkill[];
+  // Inline skills fixed onto this session at creation. They use the SDK's lazy
+  // skill source and are materialized only when the model loads one.
+  sessionSkills?: PackSkill[];
   // Explicitly selected, immutable curated-library skill content. These are
   // separate from packSkills so repository-local/pack compatibility does not
   // turn a curated entry into a mutable override.
@@ -1460,7 +1466,7 @@ export type PackSkillFile = {
 
 export type PackSkill = {
   name: string;
-  description?: string | null;
+  description?: string | null | undefined;
   files: PackSkillFile[];
 };
 
@@ -1903,6 +1909,8 @@ export function buildOpenGeniAgent(
       ...(options.skillLibrarySkills?.length
         ? { skillLibrarySkills: options.skillLibrarySkills }
         : {}),
+      ...(options.sessionSkills?.length ? { sessionSkills: options.sessionSkills } : {}),
+      ...repositoryWorkspaceSkillPathsOption(resources),
       ...(options.structuredToolTransport !== undefined
         ? { structuredToolTransport: options.structuredToolTransport }
         : {}),
@@ -1925,6 +1933,7 @@ export function buildOpenGeniAgent(
         options.skillLibrarySelections ?? [],
         options.skillLibrarySkills ?? [],
         options.packSkills ?? [],
+        options.sessionSkills ?? [],
       ).map((selection) => Object.freeze(selection)),
     ),
   );
@@ -2240,6 +2249,8 @@ export function buildAgentCapabilities(
   packSkills: PackSkill[],
   options: {
     skillLibrarySkills?: PackSkill[];
+    sessionSkills?: PackSkill[];
+    workspaceSkillPaths?: readonly WorkspaceSkillSearchPath[];
     structuredToolTransport?: boolean;
     // EXPLICIT computer-use transport (see BuildAgentOptions.computerToolMode). When
     // present, computerUse() is handed the mode directly and its tools() obeys it
@@ -2276,11 +2287,29 @@ export function buildAgentCapabilities(
     filesystemCapability,
     shell({ ...(toolCancellation ? {} : { configureTools: withExecOpCorrelation }) }),
   ];
+  const sessionSkills = sessionSkillsForMaterialization(
+    packSkills,
+    options.skillLibrarySkills ?? [],
+    options.sessionSkills ?? [],
+  );
   caps.push(
     skills({
-      lazyFrom: lazySkillSourceWithPackSkills(packSkills, options.skillLibrarySkills ?? []),
+      lazyFrom: lazySkillSourceWithPackSkills(
+        [...packSkills, ...sessionSkills],
+        options.skillLibrarySkills ?? [],
+      ),
     }),
   );
+  if (options.workspaceSkillPaths?.length) {
+    caps.push(
+      workspaceSkills(options.workspaceSkillPaths, [
+        ...bundledSkillDirNames(bundledSkillsDir()),
+        ...(options.skillLibrarySkills ?? []).map((skill) => skill.name),
+        ...packSkills.map((skill) => skill.name),
+        ...sessionSkills.map((skill) => skill.name),
+      ]),
+    );
+  }
   // P4.3 computer-use: the agent drives the SAME :0 humans watch (xdotool/XTEST +
   // scrot), but only when the desktop tier is ON, computer-use is enabled, and the
   // backend is one whose image carries the X stack (descriptorgate — honest about
@@ -2373,10 +2402,16 @@ export type PrepareToolsOptions = {
   executionGeneration?: number;
   subjectId?: string;
   subjectLabel?: string;
+  // Immutable human authority used only for subject-owned connection lookup.
+  // This is intentionally separate from the worker's first-party MCP identity.
+  credentialSubjectId?: string;
   // Overrides the fixed first-party MCP permission set for this session's
   // delegated token (manager-style sessions). The caller is responsible for
   // having validated the set against the session creator's grant.
   firstPartyPermissions?: Permission[];
+  // Exact model-visible catalog selection for the broad first-party server.
+  // Permissions are signed separately and remain the authorization boundary.
+  firstPartyTools?: FirstPartyMcpToolName[];
   resolveCredential?: (
     input: ResolveConnectionCredentialInput,
   ) => Promise<ResolveConnectionCredentialResult>;
@@ -2465,6 +2500,14 @@ export async function prepareAgentTools(
     return { mcpServers: [], close: async () => {}, codexConnectorNamespaces };
   }
   const registry = new Map(settings.mcpServers.map((server) => [server.id, server]));
+  const subjectOwnedTool = tools.find(
+    (tool) => registry.get(tool.id)?.connectionRef?.subjectScope === "subject",
+  );
+  if (subjectOwnedTool && !options.credentialSubjectId) {
+    throw new Error(
+      `subject-owned connection for MCP server ${subjectOwnedTool.id} requires a human turn initiator`,
+    );
+  }
   const aggregateToolBudget = new McpAggregateToolListBudget();
   // npm Undici's dispatcher transport can hang indefinitely under Bun even
   // after an AbortSignal fires. Bun's native fetch is the supported runtime
@@ -2738,7 +2781,7 @@ async function resolveConnectionForRequest(
     destinationUrl,
     forceRefresh,
     ...(toolName ? { toolName } : {}),
-    ...(options.subjectId ? { subjectId: options.subjectId } : {}),
+    ...(options.credentialSubjectId ? { subjectId: options.credentialSubjectId } : {}),
   };
   try {
     return await options.resolveCredential(request);
@@ -3125,6 +3168,7 @@ async function signFirstPartyDelegatedBearer(
     subjectId: options.subjectId ?? "worker:first-party-mcp",
     ...(options.subjectLabel ? { subjectLabel: options.subjectLabel } : {}),
     permissions: options.firstPartyPermissions ?? [...DEFAULT_FIRST_PARTY_MCP_PERMISSIONS],
+    firstPartyMcpTools: options.firstPartyTools ?? [...DEFAULT_FIRST_PARTY_MCP_TOOLS],
     ...(options.sessionId ? { sessionId: options.sessionId } : {}),
     ...(options.turnId ? { turnId: options.turnId } : {}),
     ...(options.attemptId ? { attemptId: options.attemptId } : {}),
@@ -5278,6 +5322,32 @@ export function buildManifest(
   });
 }
 
+export function repositoryWorkspaceSkillPathsOption(resources: readonly ResourceRef[]): {
+  workspaceSkillPaths?: readonly WorkspaceSkillSearchPath[];
+} {
+  const repositories = resources.filter(
+    (resource): resource is Extract<ResourceRef, { kind: "repository" }> =>
+      resource.kind === "repository",
+  );
+  if (repositories.length === 0) return {};
+
+  const paths = new Map<string, WorkspaceSkillSearchPath>();
+  const add = (path: string, source: string): void => {
+    if (!paths.has(path)) paths.set(path, { path, source });
+  };
+  // A Connected Machine maps /workspace to its configured working directory,
+  // which may itself be the selected repository. Managed sandboxes normally use
+  // the repository mount paths below. Checking both keeps the rule portable.
+  add(".agents/skills", "workspace .agents/skills");
+  add(".claude/skills", "workspace .claude/skills");
+  for (const repository of repositories) {
+    const mountPath = resourceMountPath(repository);
+    add(`${mountPath}/.agents/skills`, `${mountPath}/.agents/skills`);
+    add(`${mountPath}/.claude/skills`, `${mountPath}/.claude/skills`);
+  }
+  return { workspaceSkillPaths: [...paths.values()] };
+}
+
 function sandboxDownloadDirectory(download: SandboxFileDownload, mountPath: string): any {
   if (download.mountPath !== mountPath) {
     throw new Error(
@@ -6748,10 +6818,10 @@ export function toolspaceTokenSeedCommand(
     '  seed_umask="$(umask)"',
     "  umask 077",
     options.tokenFile
-      ? `  token_file=${shellQuote(options.tokenFile)}`
+      ? `  token_file=${shellToolspacePath(options.tokenFile)}`
       : '  token_file="${OPENGENI_TOOLSPACE_TOKEN_FILE:-$HOME/.opengeni/toolspace-token}"',
     options.legacyTokenFile
-      ? `  legacy_token_file=${shellQuote(options.legacyTokenFile)}`
+      ? `  legacy_token_file=${shellToolspacePath(options.legacyTokenFile)}`
       : '  legacy_token_file=""',
     '  mkdir -p "$(dirname "$token_file")"',
     '  printf \'%s\' "$OPENGENI_TOOLSPACE_TOKEN_SEED" > "$token_file.tmp.$$"',
@@ -7331,6 +7401,7 @@ function effectiveSkillSelections(
   librarySelections: readonly EffectiveSkillSelection[],
   librarySkills: readonly PackSkill[],
   packSkills: readonly PackSkill[],
+  sessionSkills: readonly PackSkill[],
 ): readonly EffectiveSkillSelection[] {
   const defaultSelections = bundledSkillDirNames(bundledSkillsDir()).map((name) => ({
     id: `bundled:${name}`,
@@ -7342,6 +7413,12 @@ function effectiveSkillSelections(
   }));
   const libraryNameKeys = new Set(librarySkills.map((skill) => skill.name.toLowerCase()));
   const packNameKeys = new Set(packSkills.map((skill) => skill.name.toLowerCase()));
+  const effectiveSessionSkills = sessionSkillsForMaterialization(
+    packSkills,
+    librarySkills,
+    sessionSkills,
+  );
+  const sessionNameKeys = new Set(effectiveSessionSkills.map((skill) => skill.name.toLowerCase()));
   const selected = librarySelections.filter((selection) =>
     libraryNameKeys.has(selection.name.toLowerCase()),
   );
@@ -7349,9 +7426,14 @@ function effectiveSkillSelections(
     ...defaultSelections.filter(
       (selection) =>
         !libraryNameKeys.has(selection.name.toLowerCase()) &&
-        !packNameKeys.has(selection.name.toLowerCase()),
+        !packNameKeys.has(selection.name.toLowerCase()) &&
+        !sessionNameKeys.has(selection.name.toLowerCase()),
+    ),
+    ...selected.filter(
+      (selection) =>
+        !packNameKeys.has(selection.name.toLowerCase()) &&
+        !sessionNameKeys.has(selection.name.toLowerCase()),
     ),
-    ...selected.filter((selection) => !packNameKeys.has(selection.name.toLowerCase())),
     ...packSkills.map((skill) => ({
       id: `pack:${skill.name}`,
       name: skill.name,
@@ -7360,9 +7442,56 @@ function effectiveSkillSelections(
       contentSha256: null,
       reason: "enabled capability pack",
     })),
+    ...effectiveSessionSkills.map((skill) => ({
+      id: `session:${skill.name}`,
+      name: skill.name,
+      source: "session" as const,
+      version: null,
+      contentSha256: null,
+      reason: "attached to session",
+    })),
   ];
 }
 
+function sessionSkillsForMaterialization(
+  packSkills: readonly PackSkill[],
+  librarySkills: readonly PackSkill[],
+  sessionSkills: readonly PackSkill[],
+): PackSkill[] {
+  const configured = new Map<string, PackSkill>();
+  for (const skill of [...librarySkills, ...packSkills]) {
+    configured.set(skill.name.toLowerCase(), skill);
+  }
+  const bundledNames = new Set(
+    bundledSkillDirNames(bundledSkillsDir()).map((name) => name.toLowerCase()),
+  );
+  const selected = new Map<string, PackSkill>();
+  for (const skill of sessionSkills) {
+    assertSafePackSkillName(skill.name);
+    const key = skill.name.toLowerCase();
+    if (bundledNames.has(key)) {
+      throw new Error(`Session skill "${skill.name}" conflicts with a bundled skill`);
+    }
+    const existing = selected.get(key) ?? configured.get(key);
+    if (existing) {
+      if (skillFingerprint(existing) !== skillFingerprint(skill)) {
+        throw new Error(`Conflicting skill definitions for "${skill.name}"`);
+      }
+      continue;
+    }
+    selected.set(key, skill);
+  }
+  return [...selected.values()];
+}
+
+function skillFingerprint(skill: PackSkill): string {
+  return JSON.stringify(
+    [...skill.files]
+      .sort((left, right) => left.path.localeCompare(right.path))
+      .map(({ path, content }) => ({ path, content })),
+  );
+}
+
 function removeSkillChildByNameKey(children: Record<string, Entry>, nameKey: string): void {
   for (const name of Object.keys(children)) {
     if (name.toLowerCase() === nameKey) {

package/src/sandbox/toolspace-token.ts

@@ -9,6 +9,7 @@ import type {
 } from "@openai/agents/sandbox";
 
 const MAX_TOOLSPACE_SESSION_ID_BYTES = 512;
+const HOME_RELATIVE_TOOLSPACE_PREFIX = "$HOME/";
 
 export class ToolspaceTokenPathError extends Error {
   constructor(message: string) {
@@ -33,6 +34,36 @@ function assertToolspaceSessionId(sessionId: string): string {
   return sessionId;
 }
 
+function isHomeRelativeToolspacePath(value: string): boolean {
+  if (!value.startsWith(HOME_RELATIVE_TOOLSPACE_PREFIX)) return false;
+  const relative = value.slice(HOME_RELATIVE_TOOLSPACE_PREFIX.length);
+  const segments = relative.split("/");
+  return (
+    relative.length > 0 &&
+    !relative.includes("\0") &&
+    segments.every(
+      (segment) => segment !== "." && segment !== ".." && /^[A-Za-z0-9._-]+$/.test(segment),
+    ) &&
+    posixPath.normalize(relative) === relative
+  );
+}
+
+function assertToolspaceFilePath(value: string, label: string): string {
+  if (
+    !value ||
+    value.includes("\0") ||
+    (!posixPath.isAbsolute(value) && !isHomeRelativeToolspacePath(value))
+  ) {
+    throw new ToolspaceTokenPathError(`${label} must be absolute or use the trusted $HOME/ prefix`);
+  }
+  return posixPath.isAbsolute(value) ? posixPath.normalize(value) : value;
+}
+
+export function shellToolspacePath(value: string): string {
+  const validated = assertToolspaceFilePath(value, "Toolspace token file");
+  return isHomeRelativeToolspacePath(validated) ? `"${validated}"` : shellQuote(validated);
+}
+
 /**
  * Derive the per-session token file beside the legacy manifest pointer.
  *
@@ -44,14 +75,10 @@ function assertToolspaceSessionId(sessionId: string): string {
  * authority boundary for Toolspace calls.
  */
 export function toolspaceTokenFileForSession(manifestTokenFile: string, sessionId: string): string {
-  if (
-    !manifestTokenFile ||
-    manifestTokenFile.includes("\0") ||
-    !posixPath.isAbsolute(manifestTokenFile)
-  ) {
-    throw new ToolspaceTokenPathError("Toolspace manifest token file must be absolute");
-  }
-  const normalizedManifestFile = posixPath.normalize(manifestTokenFile);
+  const normalizedManifestFile = assertToolspaceFilePath(
+    manifestTokenFile,
+    "Toolspace manifest token file",
+  );
   const digest = createHash("sha256").update(assertToolspaceSessionId(sessionId)).digest("hex");
   return posixPath.join(posixPath.dirname(normalizedManifestFile), "toolspace-tokens", digest);
 }
@@ -68,10 +95,7 @@ export function toolspaceTokenFileFromEnvironment(
 
 /** Prefix one sandbox command with its session-specific Toolspace pointer. */
 export function withToolspaceTokenEnvironment(cmd: string, tokenFile: string): string {
-  if (!tokenFile || tokenFile.includes("\0") || !posixPath.isAbsolute(tokenFile)) {
-    throw new ToolspaceTokenPathError("Toolspace token file must be absolute");
-  }
-  return [`export OPENGENI_TOOLSPACE_TOKEN_FILE=${shellQuote(tokenFile)}`, cmd].join("\n");
+  return [`export OPENGENI_TOOLSPACE_TOKEN_FILE=${shellToolspacePath(tokenFile)}`, cmd].join("\n");
 }
 
 /** Preserve provider identity/capabilities while decorating command creation. */

package/src/workspace-skills.ts

@@ -0,0 +1,235 @@
+import { createHash } from "node:crypto";
+
+import { Capability, type SandboxSessionLike } from "@openai/agents/sandbox";
+
+const SKILL_FILE = "SKILL.md";
+const MAX_DISCOVERED_SKILLS = 256;
+const MAX_SKILL_ENTRIES = 1_024;
+const MAX_SKILL_BYTES = 32 * 1024 * 1024;
+const SAFE_SKILL_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+export type WorkspaceSkillSearchPath = Readonly<{
+  path: string;
+  source: string;
+}>;
+
+type WorkspaceSkill = Readonly<{
+  name: string;
+  description: string;
+  path: string;
+  fingerprint: string;
+  source: string;
+}>;
+
+/**
+ * Index skills that already exist in the live workspace.
+ *
+ * Unlike the SDK's `skills({ from })` and `skills({ lazyFrom })` sources, this
+ * capability deliberately contributes no manifest entries and materializes
+ * nothing. Repository resources and Connected Machines already own these
+ * files; the bound sandbox session is the one portable way to inspect them.
+ */
+export class WorkspaceSkillsCapability extends Capability {
+  readonly type = "workspace-skills";
+  private discovery?: Promise<readonly WorkspaceSkill[]>;
+
+  constructor(
+    private readonly searchPaths: readonly WorkspaceSkillSearchPath[],
+    private readonly reservedNames: ReadonlySet<string> = new Set(),
+  ) {
+    super();
+  }
+
+  override async instructions(): Promise<string | null> {
+    const session = requireWorkspaceSkillSession(this._session);
+    this.discovery ??= discoverWorkspaceSkills(
+      session,
+      this.searchPaths,
+      this.reservedNames,
+      this._runAs,
+    );
+    const skills = await this.discovery;
+    if (skills.length === 0) return null;
+
+    const available = skills
+      .map((skill) => `- ${skill.name}: ${skill.description} (file: ${skill.path})`)
+      .join("\n");
+    return `## Repository skills
+
+Repository skills are instructions already present in the live workspace. They do not need to be loaded or copied.
+
+### Available repository skills
+${available}
+
+### How to use repository skills
+- If the user names a skill, or the task clearly matches a skill description, read its complete SKILL.md before acting.
+- Resolve referenced scripts, references, assets, and templates relative to that skill directory.
+- Use only the minimum relevant skills for the turn, and say briefly which ones you are using.
+- Do not assume a skill remains applicable on later turns; evaluate the current request again.`;
+  }
+}
+
+export function workspaceSkills(
+  searchPaths: readonly WorkspaceSkillSearchPath[],
+  reservedNames: Iterable<string> = [],
+): WorkspaceSkillsCapability {
+  return new WorkspaceSkillsCapability(
+    searchPaths,
+    new Set([...reservedNames].map((name) => name.toLowerCase())),
+  );
+}
+
+export async function discoverWorkspaceSkills(
+  session: SandboxSessionLike,
+  searchPaths: readonly WorkspaceSkillSearchPath[],
+  reservedNames: ReadonlySet<string> = new Set(),
+  runAs?: string,
+): Promise<readonly WorkspaceSkill[]> {
+  if (!session.listDir || !session.readFile) {
+    throw new Error("Workspace skill discovery requires sandbox listDir() and readFile() support");
+  }
+  const discovered = new Map<string, WorkspaceSkill>();
+  let candidates = 0;
+  for (const searchPath of searchPaths) {
+    let entries;
+    try {
+      entries = await session.listDir({ path: searchPath.path, ...(runAs ? { runAs } : {}) });
+    } catch {
+      continue;
+    }
+    for (const entry of [...entries].sort((left, right) => left.name.localeCompare(right.name))) {
+      if (entry.type !== "dir") continue;
+      candidates += 1;
+      if (candidates > MAX_DISCOVERED_SKILLS) {
+        throw new Error(`Repository skill discovery exceeds ${MAX_DISCOVERED_SKILLS} directories`);
+      }
+      const skillMarkdownPath = joinWorkspacePath(entry.path, SKILL_FILE);
+      let markdown: string;
+      try {
+        const content = await session.readFile({
+          path: skillMarkdownPath,
+          ...(runAs ? { runAs } : {}),
+        });
+        markdown = typeof content === "string" ? content : new TextDecoder().decode(content);
+      } catch {
+        continue;
+      }
+      const frontmatter = parseSkillFrontmatter(markdown);
+      const name = frontmatter.name?.trim() || entry.name;
+      if (name.length > 64 || !SAFE_SKILL_NAME.test(name)) {
+        throw new Error(`Repository skill has an invalid name: ${name.slice(0, 64)}`);
+      }
+      const description = frontmatter.description?.trim() || "No description provided.";
+      if (description.length > 2_048 || /[\r\n]/.test(description)) {
+        throw new Error(`Repository skill "${name}" has an invalid description`);
+      }
+      const key = name.toLowerCase();
+      if (reservedNames.has(key)) {
+        throw new Error(`Workspace skill "${name}" conflicts with a configured OpenGeni skill`);
+      }
+      const candidate: WorkspaceSkill = {
+        name,
+        description,
+        path: skillMarkdownPath,
+        fingerprint: await fingerprintWorkspaceDirectory(session, entry.path, runAs),
+        source: searchPath.source,
+      };
+      const existing = discovered.get(key);
+      if (!existing) {
+        discovered.set(key, candidate);
+        continue;
+      }
+      if (existing.fingerprint !== candidate.fingerprint) {
+        throw new Error(
+          `Workspace skill "${name}" has conflicting definitions in ${existing.source} and ${candidate.source}`,
+        );
+      }
+    }
+  }
+  return [...discovered.values()].sort((left, right) => left.name.localeCompare(right.name));
+}
+
+async function fingerprintWorkspaceDirectory(
+  session: SandboxSessionLike,
+  root: string,
+  runAs?: string,
+): Promise<string> {
+  const hash = createHash("sha256");
+  let entryCount = 0;
+  let byteCount = 0;
+
+  async function visit(path: string, relativePath: string): Promise<void> {
+    const entries = await session.listDir!({ path, ...(runAs ? { runAs } : {}) });
+    for (const entry of [...entries].sort((left, right) => left.name.localeCompare(right.name))) {
+      entryCount += 1;
+      if (entryCount > MAX_SKILL_ENTRIES) {
+        throw new Error(`Workspace skill exceeds ${MAX_SKILL_ENTRIES} filesystem entries`);
+      }
+      const childRelativePath = relativePath ? `${relativePath}/${entry.name}` : entry.name;
+      hash.update(entry.type);
+      hash.update("\0");
+      hash.update(childRelativePath);
+      hash.update("\0");
+      if (entry.type === "dir") {
+        await visit(entry.path, childRelativePath);
+        continue;
+      }
+      if (entry.type !== "file") continue;
+      const content = await session.readFile!({
+        path: entry.path,
+        ...(runAs ? { runAs } : {}),
+      });
+      const bytes = typeof content === "string" ? new TextEncoder().encode(content) : content;
+      byteCount += bytes.byteLength;
+      if (byteCount > MAX_SKILL_BYTES) {
+        throw new Error(`Workspace skill exceeds ${MAX_SKILL_BYTES} bytes`);
+      }
+      hash.update(bytes);
+      hash.update("\0");
+    }
+  }
+
+  await visit(root, "");
+  return hash.digest("hex");
+}
+
+function parseSkillFrontmatter(markdown: string): {
+  name?: string;
+  description?: string;
+} {
+  const lines = markdown.split(/\r?\n/);
+  if (lines[0]?.trim() !== "---") return {};
+  const end = lines.findIndex((line, index) => index > 0 && line.trim() === "---");
+  if (end === -1) return {};
+  const values: Record<string, string> = {};
+  for (const line of lines.slice(1, end)) {
+    const separator = line.indexOf(":");
+    if (separator === -1) continue;
+    const key = line.slice(0, separator).trim();
+    if (key !== "name" && key !== "description") continue;
+    values[key] = unquote(line.slice(separator + 1).trim());
+  }
+  return values;
+}
+
+function unquote(value: string): string {
+  if (
+    value.length >= 2 &&
+    value[0] === value[value.length - 1] &&
+    (value[0] === '"' || value[0] === "'")
+  ) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+
+function joinWorkspacePath(parent: string, child: string): string {
+  return `${parent.replace(/\/+$/, "")}/${child}`;
+}
+
+function requireWorkspaceSkillSession(session: SandboxSessionLike | undefined): SandboxSessionLike {
+  if (!session) {
+    throw new Error('capability "workspace-skills" used before bind(session)');
+  }
+  return session;
+}