@cursor/bdk 0.2.26 → 0.2.27

package/dist/internal/session-engine.js

@@ -15,7 +15,7 @@ import { SlackAskDedupeStore, SlackNudgeStore } from "../channels/slack/nudge-st
 import { resolveDedicatedSlackHostBinding } from "../channels/slack/slack-channel.js";
 import { AGENT_SERVE_USER_STORE_FILES_SOURCE_ID, agentStoreKeys, DEPLOYMENT_STORE_MOUNT_PATH, USER_STORE_MOUNT_PATH, } from "../files.js";
 import { cursorHostedFiles, isCursorHostedFilesAvailable, isCursorUserStoreFilesAvailable, } from "../files-backends/cursor-hosted.js";
-import { isFileSystemToolAlias, isMutatingFileSystemTool, localFileSystem, resolveFileSystemTools, resolveHostHarnessToolOptions, tempFs, unionFs, writeWorkspaceFilesToRoot, } from "../filesystem.js";
+import { isFileNotFoundError, isFileSystemToolAlias, isMutatingFileSystemTool, localFileSystem, readOnlyFs, resolveFileSystemTools, resolveHostHarnessToolOptions, sessionFileSystem, writeWorkspaceFilesToRoot, } from "../filesystem.js";
 import { storageKeysForArchitecture } from "../storage.js";
 import { DEFAULT_MODEL, DIRECT_TOOL_CALL_CHANNEL_ID, isCursorAccountTransport, isHostOauthConnectionTransport, isSymbolicConnectionTransport, } from "../types.js";
 import { resolveAdvertisedTools } from "./advertise-tools.js";
@@ -67,7 +67,7 @@ import { TurnGovernor } from "./turn-governor.js";
 import { TurnLeaseStore } from "./turn-lease-store.js";
 import { TurnOutbox } from "./turn-outbox.js";
 import { isCursorManagedV2Hosting, resolveAgentV2Hosting } from "./v2-hosting.js";
-import { buildAgentsMdContent, buildCloudMemorySection, buildCloudSessionWorkspaceSection, buildCloudWorkspaceSection, ensureOwnGitRoot, isNestedInGitRepo, materializeWorkspace, SERVER_TOOLS_MCP_SERVER_NAME, withIdentityPreamble, } from "./workspace.js";
+import { buildAgentsMdContent, buildCloudMemorySection, buildCloudSessionWorkspaceSection, buildCloudWorkspaceSection, ensureOwnGitRoot, isNestedInGitRepo, materializeWorkspace, SERVER_TOOLS_MCP_SERVER_NAME, SKILLS_MOUNT_PATH, skillsFileSystem, withIdentityPreamble, } from "./workspace.js";
 import { syncSessionWorkspaceFiles, syncWorkspaceToStore, WorkspaceFileRefusal, wipeSessionWorkspace, } from "./workspace-sync.js";
 export const HTTP_CHANNEL_ID = "http";
 export { mergeChannelStateSkipNull } from "./channel-state.js";
@@ -266,11 +266,11 @@ export class SessionEngine {
         this.cloudUsageBackfillDone = new Set();
         /** Deduped in-flight cloud usage backfills, keyed by session id. */
         this.cloudUsageBackfill = new Map();
-        /** Per-session FileSystem handle cache (not a tree snapshot). */
+        /** Per-session authored `fs` and skills handles (not tree snapshots). */
         this.sessionRoots = new Map();
         /** In-flight factory resolves, so the first turn and a racing callTool share one handle. */
         this.sessionRootInflight = new Map();
-        /** Per-turn `unionFs({ "/": authored, "/tmp": tempFs() })`. Dropped at end of turn. */
+        /** Per-turn union of the authored tree, `/agent/skills`, and `/tmp`. Dropped at end of turn. */
         this.turnRoots = new Map();
         this.project = options.project;
         applyAgentContinuationDefaults(this.project);
@@ -1388,10 +1388,14 @@ export class SessionEngine {
         return this.interrupt(existing.sessionId);
     }
     hasRootOverride() {
-        return this.project.agent.root !== undefined;
+        return this.project.agent.fs !== undefined || this.project.agent.root !== undefined;
+    }
+    /** The field the author set, for messages. Discovery copies a lone `root` onto `fs`. */
+    authoredFsField() {
+        return this.project.agent.root === undefined ? "fs" : "root";
     }
     /**
-     * FileSystem for this turn or `callTool`. Authored `root` (static or
+     * FileSystem for this turn or `callTool`. Authored `fs` (static or
      * factory) is cached per session when `cache` is set; unscoped
      * `callTool` passes the invocation id and does not cache, so factories
      * cannot share one tree across callers. A static handle is used as
@@ -1400,20 +1404,21 @@ export class SessionEngine {
      * the Cursor SDK natives, always through the synthesized tools.
      */
     async resolveFileSystem(options) {
-        const authored = this.project.agent.root;
-        if (authored === undefined) {
+        if (!this.hasRootOverride()) {
             return localFileSystem({ cwd: options.cwd });
         }
-        const authoredRoot = await this.resolveAuthoredFileSystem(options);
+        const authored = await this.resolveAuthoredFileSystem(options);
         if (options.cache) {
             const existing = this.turnRoots.get(options.sessionId);
             if (existing !== undefined) {
                 return existing.root;
             }
         }
-        const root = unionFs({
-            "/": authoredRoot,
-            "/tmp": tempFs(),
+        const root = sessionFileSystem({
+            authored: authored.fs,
+            skills: authored.skills === undefined
+                ? undefined
+                : { path: SKILLS_MOUNT_PATH, fs: authored.skills },
         });
         if (options.cache && this.isTurnRunning(options.sessionId)) {
             this.turnRoots.set(options.sessionId, { root, cwd: options.cwd });
@@ -1421,9 +1426,10 @@ export class SessionEngine {
         return root;
     }
     async resolveAuthoredFileSystem(options) {
-        const authored = this.project.agent.root;
+        const agent = this.project.agent;
+        const authored = agent.fs ?? agent.root;
         if (authored === undefined) {
-            throw new Error("resolveAuthoredFileSystem requires an authored root");
+            throw new Error("resolveAuthoredFileSystem requires an authored fs");
         }
         if (options.cache) {
             const cached = this.sessionRoots.get(options.sessionId);
@@ -1435,14 +1441,14 @@ export class SessionEngine {
                 return inflight;
             }
         }
-        const resolve = async () => {
+        const resolveFs = async () => {
             if (typeof authored !== "function") {
                 return authored;
             }
             const host = this.hostForSession(options.cache ? options.sessionId : undefined);
             const ctx = {
                 sessionId: options.sessionId,
-                agentName: this.project.agent.name,
+                agentName: agent.name,
                 ...(options.continuationKey === undefined
                     ? {}
                     : { continuationKey: options.continuationKey }),
@@ -1450,6 +1456,37 @@ export class SessionEngine {
             };
             return await authored(ctx);
         };
+        const resolve = async () => {
+            const fs = await resolveFs();
+            if (agent.skillsMount === false) {
+                return { fs, skills: undefined };
+            }
+            let skillsOccupied = false;
+            try {
+                skillsOccupied = (await fs.stat(SKILLS_MOUNT_PATH)).kind !== "missing";
+            }
+            catch (error) {
+                if (!isFileNotFoundError(error)) {
+                    throw error;
+                }
+                skillsOccupied = false;
+            }
+            if (skillsOccupied) {
+                throw new Error(`Agent "${agent.name}" ${this.authoredFsField()} already has ${SKILLS_MOUNT_PATH}, where BDK mounts the agent's skills. Remove ${SKILLS_MOUNT_PATH} from ${this.authoredFsField()}, or set skills: false to keep yours.`);
+            }
+            const skills = await this.baseSkillsFileSystem();
+            if (agent.skillsMount === undefined) {
+                return { fs, skills };
+            }
+            return {
+                fs,
+                skills: readOnlyFs(await agent.skillsMount({
+                    skills,
+                    sessionId: options.sessionId,
+                    continuationKey: options.continuationKey,
+                })),
+            };
+        };
         if (!options.cache) {
             return resolve();
         }
@@ -1464,6 +1501,13 @@ export class SessionEngine {
             this.sessionRootInflight.delete(options.sessionId);
         }
     }
+    baseSkillsFileSystem() {
+        this.baseSkills ??= skillsFileSystem(this.project.agent.skills).catch((error) => {
+            this.baseSkills = undefined;
+            throw error;
+        });
+        return this.baseSkills;
+    }
     dropTurnFileSystem(sessionId) {
         this.turnRoots.delete(sessionId);
     }
@@ -2121,11 +2165,11 @@ export class SessionEngine {
         //
         // Factory roots omit `allowedTools` at discovery (the live handle is
         // resolved per session). The allowlist guard below therefore never
-        // fires for `defineAgent({ root: (ctx) => … })` with omitted `tools`,
+        // fires for `defineAgent({ fs: (ctx) => … })` with omitted `tools`,
         // and a per-send `cloud` attach would skip the virtual-root allowlist
-        // and run unrestricted on a VM. Any authored root refuses non-local turns.
+        // and run unrestricted on a VM. Any authored fs refuses non-local turns.
         if (runtime !== "local" && this.hasRootOverride()) {
-            throw new Error(`Agent "${agent.name}" declares root, which cannot be served on ${runtime} turns. Refusing the session rather than running it against the host VM.`);
+            throw new Error(`Agent "${agent.name}" declares ${this.authoredFsField()}, which cannot be served on ${runtime} turns. Refusing the session rather than running it against the host VM.`);
         }
         if (runtime !== "local" && agent.allowedTools !== undefined) {
             throw new Error(`Agent "${agent.name}" declares a built-in tool allowlist (tools), which cannot be enforced on ${runtime} turns. Refusing the session rather than running it unrestricted.`);
@@ -2252,7 +2296,7 @@ export class SessionEngine {
         // synthesized file tools and embedded script bodies.
         const localInstructions = runtime === "local"
             ? authoredRoot
-                ? buildAgentsMdContent({ ...instructionsAgent, tools: [...instructionsAgent.tools, ...synthesized] }, { includeScripts: true })
+                ? buildAgentsMdContent({ ...instructionsAgent, tools: [...instructionsAgent.tools, ...synthesized] }, { includeScripts: true, skillsIndex: agent.skillsMount !== false })
                 : buildAgentsMdContent(instructionsAgent, {
                     includeScripts: this.hasBorrowedWorkspace(record),
                 })

package/dist/internal/workspace.d.ts

@@ -8,6 +8,7 @@
  * deliver them as the harness system prompt ({@link buildAgentsMdContent}),
  * and cloud / grokbot harnesses never read the session workspace.
  */
+import { type FileSystem } from "../filesystem.js";
 import type { DiscoveredSkill, DiscoveredTool, ResolvedAgent } from "../types.js";
 export interface MaterializeWorkspaceOptions {
     agent: ResolvedAgent;
@@ -102,7 +103,16 @@ export declare function buildServerToolsCatalog(tools: DiscoveredTool[], options
 export declare function buildAgentsMdContent(agent: ResolvedAgent, options: {
     includeScripts: boolean;
     serverToolsMcpName?: string;
+    skillsIndex?: boolean;
 }): string;
+/** Where an authored `fs` sees {@link skillsFileSystem}. */
+export declare const SKILLS_MOUNT_PATH = "/agent/skills";
+export declare const FS_AND_ROOT_CONFLICT = "Set `fs` or `root`, not both; `root` is a deprecated alias of `fs`.";
+/**
+ * The discovered skills as a read-only tree: `/<name>/SKILL.md`, the same
+ * bytes {@link materializeSkill} writes, plus each skill's sibling files.
+ */
+export declare function skillsFileSystem(skills: readonly DiscoveredSkill[]): Promise<FileSystem>;
 /**
  * True when `dir` sits strictly inside a git repository (a `.git` exists in
  * an ancestor directory but not in `dir` itself). The Cursor harness resolves

package/dist/internal/workspace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../src/internal/workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAmBH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAMlF,MAAM,WAAW,2BAA2B;IAC1C,KAAK,EAAE,aAAa,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,IAAI,EAAE,OAAO,CAAC;IACd;;;;;;OAMG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAOjE;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAM9D;AAED;;;;GAIG;AACH,wBAAgB,iCAAiC,CAC/C,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,SAAS,MAAM,EAAE,GAC1B,MAAM,CAOR;AAED,+EAA+E;AAC/E,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,mBAAmB,CAAC;AAE7D;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAM1D;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,MAAM,GAAG,SAAS,CAapB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,GAAE;IAAE,cAAc,EAAE,OAAO,CAAA;CAA8B,GAC/D,MAAM,CA8CR;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,EAAE;IAAE,aAAa,EAAE,MAAM,CAAA;CAAE,GACjC,MAAM,CA6BR;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,aAAa,EACpB,OAAO,EAAE;IAAE,cAAc,EAAE,OAAO,CAAC;IAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAAE,GAChE,MAAM,CAeR;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAcrE;AAED,6DAA6D;AAC7D,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAUpE;AAED,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,2BAA2B,GAAG,OAAO,CAAC,IAAI,CAAC,CA4B9F;AAyFD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAO3D;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,GACtF,OAAO,CAAC,IAAI,CAAC,CAYf"}
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../src/internal/workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAmBH,OAAO,EAAE,KAAK,UAAU,EAAsB,MAAM,kBAAkB,CAAC;AAEvE,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAMlF,MAAM,WAAW,2BAA2B;IAC1C,KAAK,EAAE,aAAa,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,IAAI,EAAE,OAAO,CAAC;IACd;;;;;;OAMG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAOjE;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAM9D;AAED;;;;GAIG;AACH,wBAAgB,iCAAiC,CAC/C,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,SAAS,MAAM,EAAE,GAC1B,MAAM,CAOR;AAED,+EAA+E;AAC/E,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,mBAAmB,CAAC;AAE7D;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAM1D;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,MAAM,GAAG,SAAS,CAapB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,GAAE;IAAE,cAAc,EAAE,OAAO,CAAA;CAA8B,GAC/D,MAAM,CA8CR;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,EAAE;IAAE,aAAa,EAAE,MAAM,CAAA;CAAE,GACjC,MAAM,CA6BR;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,aAAa,EACpB,OAAO,EAAE;IAAE,cAAc,EAAE,OAAO,CAAC;IAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,OAAO,CAAA;CAAE,GACvF,MAAM,CAgBR;AAED,4DAA4D;AAC5D,eAAO,MAAM,iBAAiB,kBAAkB,CAAC;AAEjD,eAAO,MAAM,oBAAoB,wEACsC,CAAC;AAmCxE;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,GAAG,OAAO,CAAC,UAAU,CAAC,CAU9F;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAcrE;AAED,6DAA6D;AAC7D,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAUpE;AAED,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,2BAA2B,GAAG,OAAO,CAAC,IAAI,CAAC,CA4B9F;AAyFD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAO3D;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,GACtF,OAAO,CAAC,IAAI,CAAC,CAYf"}

package/dist/internal/workspace.js

@@ -9,11 +9,12 @@
  * and cloud / grokbot harnesses never read the session workspace.
  */
 import { execFile } from "node:child_process";
-import { chmod, copyFile, lstat, mkdir, readlink, rm, stat, symlink, writeFile, } from "node:fs/promises";
+import { chmod, copyFile, lstat, mkdir, readFile, readlink, rm, stat, symlink, writeFile, } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join, parse, relative, resolve, sep } from "node:path";
 import { promisify } from "node:util";
 import { agentStoreKeys, DEPLOYMENT_STORE_MOUNT_PATH } from "../files.js";
+import { readOnlyFs, tempFs } from "../filesystem.js";
 import { MEMORY_DIR_NAME } from "./memory-dir.js";
 import { parseFrontmatter, serializeFrontmatter } from "./frontmatter.js";
 import { buildIdentitySection } from "./prompt-context.js";
@@ -209,10 +210,55 @@ export function buildAgentsMdContent(agent, options) {
         buildAgentToolsCatalog(agent.tools, {
             includeScripts: options.includeScripts,
         }),
+        options.skillsIndex === true ? buildSkillsIndex(agent.skills) : "",
     ]
         .filter((part) => part !== "")
         .join("\n\n");
 }
+/** Where an authored `fs` sees {@link skillsFileSystem}. */
+export const SKILLS_MOUNT_PATH = "/agent/skills";
+export const FS_AND_ROOT_CONFLICT = "Set `fs` or `root`, not both; `root` is a deprecated alias of `fs`.";
+/**
+ * Index of the discovered skills under {@link SKILLS_MOUNT_PATH}. An `fs`
+ * agent has no `.cursor/skills/` for the harness to discover, so the
+ * instructions name each SKILL.md instead.
+ */
+function buildSkillsIndex(skills) {
+    if (skills.length === 0) {
+        return "";
+    }
+    return [
+        "## Skills",
+        "",
+        `Skills are on-demand procedures under \`${SKILLS_MOUNT_PATH}\`. When a task matches a skill's description, read its \`SKILL.md\` before acting on that part of the task and follow it.`,
+        "",
+        ...skills.map((skill) => `- \`${skill.name}\` (\`${SKILLS_MOUNT_PATH}/${skill.name}/SKILL.md\`): ${skill.description.trim()}`),
+    ].join("\n");
+}
+function skillFilePath(skillName, relativePath) {
+    const parts = relativePath.split("/");
+    if (relativePath.includes("\0") ||
+        relativePath.startsWith("/") ||
+        parts.some((part) => part === "" || part === "..")) {
+        throw new Error(`Skill "${skillName}" file "${relativePath}" escapes its directory.`);
+    }
+    return `/${skillName}/${relativePath}`;
+}
+/**
+ * The discovered skills as a read-only tree: `/<name>/SKILL.md`, the same
+ * bytes {@link materializeSkill} writes, plus each skill's sibling files.
+ */
+export async function skillsFileSystem(skills) {
+    const files = {};
+    for (const skill of skills) {
+        files[`/${skill.name}/SKILL.md`] = buildSkillMd(skill);
+        for (const [relativePath, source] of Object.entries(skill.files)) {
+            files[skillFilePath(skill.name, relativePath)] =
+                "contents" in source ? source.contents : await readFile(source.sourcePath);
+        }
+    }
+    return readOnlyFs(tempFs(files));
+}
 /**
  * True when `dir` sits strictly inside a git repository (a `.git` exists in
  * an ancestor directory but not in `dir` itself). The Cursor harness resolves