@cursor/july 0.1.100 → 0.1.102

package/dist/internal/discovery/runtime.js

@@ -0,0 +1,98 @@
+/**
+ * Runtime resolution and the limitations each runtime imposes on the authored surface.
+ */
+import { join } from "node:path";
+import { builtinTools } from "../builtin-tools/index.js";
+import { displayPath } from "./context.js";
+/**
+ * Validate the authored runtime. An unrecognized value is an error
+ * diagnostic and falls back to local — a typo must not silently pick a
+ * different harness for every turn.
+ */
+export function resolveRuntime(ctx, agentDir, runtime) {
+    if (runtime === undefined ||
+        runtime === "local" ||
+        runtime === "cloud" ||
+        runtime === "grokbot") {
+        return runtime !== null && runtime !== void 0 ? runtime : "local";
+    }
+    ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, join(agentDir, "agent.ts")),
+        message: `runtime must be "local", "cloud", or "grokbot"; got ${JSON.stringify(runtime)}.`,
+    });
+    return "local";
+}
+/**
+ * Grok Bot turns run on the Sand harness with its own toolset: authored
+ * server tools, MCP connections, and subagents have no path onto that
+ * toolset yet, so an agent declaring them must fail at serve start rather
+ * than run with capabilities silently missing.
+ */
+export function checkGrokBotRuntimeLimitations(ctx, agentDir, counts) {
+    const agentPath = displayPath(ctx, join(agentDir, "agent.ts"));
+    const error = (path, message) => {
+        ctx.diagnostics.push({ severity: "error", path, message });
+    };
+    const warn = (path, message) => {
+        ctx.diagnostics.push({ severity: "warning", path, message });
+    };
+    if (counts.serverTools > 0) {
+        error(displayPath(ctx, join(agentDir, "tools")), 'Server tools (execution: "server", including opted-in builtinTools) are not reachable from grokbot turns yet. Remove them or run the agent on the local runtime.');
+    }
+    if (counts.connections > 0) {
+        error(displayPath(ctx, agentDir), "MCP connections (agent/mcp-connections/ or agent/host-connections/) are not wired into grokbot turns yet. Remove them or run the agent on the local runtime.");
+    }
+    if (counts.subagents > 0) {
+        error(displayPath(ctx, join(agentDir, "subagents")), "Authored subagents are not available on grokbot turns (the Grok Bot harness runs its own subagent set). Remove them or run the agent on the local runtime.");
+    }
+    // The remaining declarations mirror the cloud runtime's warnings: the
+    // turn runs on a hosted machine (the account's box), so local-workspace
+    // materialization never reaches it.
+    if (counts.agentTools > 0) {
+        warn(displayPath(ctx, join(agentDir, "tools")), 'Agent tools (execution: "agent") are described in the hosted session\'s instructions (with script bodies); they are not written onto the box filesystem automatically.');
+    }
+    if (counts.skills > 0) {
+        warn(displayPath(ctx, join(agentDir, "skills")), "Authored skills are materialized into the local session workspace only; the hosted Grok Bot box does not see them.");
+    }
+    if (counts.seedFiles > 0) {
+        warn(displayPath(ctx, join(agentDir, "sandbox")), "sandbox/workspace seed files apply to the local session workspace only; grokbot turns run on the account's hosted box.");
+    }
+    if (counts.hasCloudOptions) {
+        warn(agentPath, 'The `cloud` block is unused on runtime: "grokbot", and grokbot sessions refuse per-session cloud attach.');
+    }
+    if (counts.hasLocalSandbox) {
+        warn(agentPath, 'local.sandbox does not apply to runtime: "grokbot"; the box is the account\'s Cursor-hosted computer.');
+    }
+}
+export function warnCloudRuntimeLimitations(ctx, agentDir, counts) {
+    const agentPath = displayPath(ctx, join(agentDir, "agent.ts"));
+    if (!counts.hasCloudOptions) {
+        ctx.diagnostics.push({
+            severity: "warning",
+            path: agentPath,
+            message: 'runtime: "cloud" usually needs a `cloud` block (e.g. repos / env). Without it the Cursor cloud API may reject create.',
+        });
+    }
+    if (counts.agentTools > 0) {
+        ctx.diagnostics.push({
+            severity: "warning",
+            path: displayPath(ctx, join(agentDir, "tools")),
+            message: 'Agent tools (execution: "agent") are described on the first cloud prompt (with script bodies); they are not written into the cloud VM filesystem automatically.',
+        });
+    }
+    if (counts.skills > 0) {
+        ctx.diagnostics.push({
+            severity: "warning",
+            path: displayPath(ctx, join(agentDir, "skills")),
+            message: "Authored skills reach cloud agents through native store discovery: hosted deployments write the deployment store's skills/ directory; local serve/run with a personal API key writes agent-serve/<agent>/skills/ on the USER store. Without a reachable store, only skills already in the cloud repo are visible.",
+        });
+    }
+    if (counts.seedFiles > 0) {
+        ctx.diagnostics.push({
+            severity: "warning",
+            path: displayPath(ctx, join(agentDir, "sandbox")),
+            message: "sandbox/workspace seed files apply to the local session workspace only; cloud agents use the configured cloud repos.",
+        });
+    }
+}

package/dist/internal/discovery/schedules.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `agent/schedules/*.ts`: cron-driven runs.
+ */
+import type { DiscoveredSchedule } from "../../types.js";
+import { type DiscoveryContext } from "./context.js";
+export declare function loadSchedules(ctx: DiscoveryContext, schedulesDir: string): Promise<DiscoveredSchedule[]>;
+//# sourceMappingURL=schedules.d.ts.map

package/dist/internal/discovery/schedules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schedules.d.ts","sourceRoot":"","sources":["../../../src/internal/discovery/schedules.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,kBAAkB,EAAsB,MAAM,gBAAgB,CAAC;AAG7E,OAAO,EAAE,KAAK,gBAAgB,EAAe,MAAM,cAAc,CAAC;AAIlE,wBAAsB,aAAa,CACjC,GAAG,EAAE,gBAAgB,EACrB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,kBAAkB,EAAE,CAAC,CA6E/B"}

package/dist/internal/discovery/schedules.js

@@ -0,0 +1,97 @@
+/**
+ * `agent/schedules/*.ts`: cron-driven runs.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { readFile } from "node:fs/promises";
+import { basename, extname, relative } from "node:path";
+import { isValidCron } from "../cron.js";
+import { parseFrontmatter } from "../frontmatter.js";
+import { displayPath } from "./context.js";
+import { isDirectory, isModuleFile, toPosix, walkFiles } from "./fs.js";
+import { importDefault } from "./modules.js";
+export function loadSchedules(ctx, schedulesDir) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (!(yield isDirectory(schedulesDir))) {
+            return [];
+        }
+        const schedules = [];
+        for (const filePath of yield walkFiles(schedulesDir)) {
+            const rel = toPosix(relative(schedulesDir, filePath));
+            if (rel.endsWith(".md")) {
+                const name = rel.slice(0, -".md".length);
+                const { data, body } = parseFrontmatter(yield readFile(filePath, "utf8"));
+                const cron = data.cron;
+                if (cron === undefined || !isValidCron(cron)) {
+                    ctx.diagnostics.push({
+                        severity: "error",
+                        path: displayPath(ctx, filePath),
+                        message: cron === undefined
+                            ? "Markdown schedules require `cron` frontmatter."
+                            : `Invalid cron expression: "${cron}".`,
+                    });
+                    continue;
+                }
+                const markdown = body.trim();
+                if (markdown === "") {
+                    ctx.diagnostics.push({
+                        severity: "error",
+                        path: displayPath(ctx, filePath),
+                        message: "Markdown schedules require a non-empty prompt body.",
+                    });
+                    continue;
+                }
+                schedules.push({
+                    name,
+                    cron,
+                    kind: "markdown",
+                    definition: {
+                        __agentServe: "schedule",
+                        cron,
+                        markdown,
+                    },
+                });
+                continue;
+            }
+            if (!isModuleFile(basename(filePath))) {
+                continue;
+            }
+            const name = rel.slice(0, -extname(rel).length);
+            const definition = yield importDefault(ctx, filePath, "schedule");
+            if (definition === undefined) {
+                continue;
+            }
+            const schedule = definition;
+            if ((schedule.markdown === undefined) === (schedule.run === undefined)) {
+                ctx.diagnostics.push({
+                    severity: "error",
+                    path: displayPath(ctx, filePath),
+                    message: "Schedules require exactly one of `markdown` or `run`.",
+                });
+                continue;
+            }
+            if (!isValidCron(schedule.cron)) {
+                ctx.diagnostics.push({
+                    severity: "error",
+                    path: displayPath(ctx, filePath),
+                    message: `Invalid cron expression: "${schedule.cron}".`,
+                });
+                continue;
+            }
+            schedules.push({
+                name,
+                cron: schedule.cron,
+                kind: schedule.run === undefined ? "markdown" : "run",
+                definition: schedule,
+            });
+        }
+        return schedules;
+    });
+}

package/dist/internal/discovery/seed-files.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `agent/sandbox/workspace/**`: files seeded into each local session workspace.
+ */
+import type { SeedFile } from "../../types.js";
+import { type DiscoveryContext } from "./context.js";
+export declare function loadSeedFiles(ctx: DiscoveryContext, agentDir: string): Promise<SeedFile[]>;
+//# sourceMappingURL=seed-files.d.ts.map

package/dist/internal/discovery/seed-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed-files.d.ts","sourceRoot":"","sources":["../../../src/internal/discovery/seed-files.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,KAAK,gBAAgB,EAAe,MAAM,cAAc,CAAC;AAGlE,wBAAsB,aAAa,CACjC,GAAG,EAAE,gBAAgB,EACrB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,QAAQ,EAAE,CAAC,CAwBrB"}

package/dist/internal/discovery/seed-files.js

@@ -0,0 +1,41 @@
+/**
+ * `agent/sandbox/workspace/**`: files seeded into each local session workspace.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { join, relative } from "node:path";
+import { displayPath } from "./context.js";
+import { isDirectory, isFile, toPosix, walkFiles } from "./fs.js";
+export function loadSeedFiles(ctx, agentDir) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const sandboxDir = join(agentDir, "sandbox");
+        for (const candidate of ["sandbox.ts", join("sandbox", "sandbox.ts")]) {
+            if (yield isFile(join(agentDir, candidate))) {
+                ctx.diagnostics.push({
+                    severity: "warning",
+                    path: displayPath(ctx, join(agentDir, candidate)),
+                    message: "Custom sandbox backends are not supported; the agent runs in the session workspace directory. Ignoring.",
+                });
+            }
+        }
+        const workspaceDir = join(sandboxDir, "workspace");
+        if (!(yield isDirectory(workspaceDir))) {
+            return [];
+        }
+        const seedFiles = [];
+        for (const filePath of yield walkFiles(workspaceDir)) {
+            seedFiles.push({
+                relativePath: toPosix(relative(workspaceDir, filePath)),
+                sourcePath: filePath,
+            });
+        }
+        return seedFiles;
+    });
+}

package/dist/internal/discovery/services.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `agent/storage.ts`, `agent/otel.ts`, `agent/artifacts.ts`: host services the agent configures.
+ */
+import type { OtelDefinition } from "../../otel.js";
+import type { StorageDefinition } from "../../storage.js";
+import type { AgentArchitecture, ArtifactsDefinition, ResolvedAgent } from "../../types.js";
+import { type DiscoveryContext } from "./context.js";
+export declare function loadStorage(ctx: DiscoveryContext, agentDir: string, architecture: AgentArchitecture | undefined): Promise<StorageDefinition | undefined>;
+export declare function loadOtel(ctx: DiscoveryContext, agentDir: string): Promise<OtelDefinition | undefined>;
+export declare function loadArtifacts(ctx: DiscoveryContext, agentDir: string): Promise<ArtifactsDefinition | undefined>;
+/**
+ * Materialize the `tag_artifact` built-in when `defineArtifacts` set
+ * `agentTool: true`. Appended after `loadAgent` because the tool is
+ * generated from the artifacts kinds registry, not `AgentConfig.builtinTools`.
+ */
+export declare function appendArtifactTool(ctx: DiscoveryContext, agentDir: string, agent: ResolvedAgent, artifacts: ArtifactsDefinition | undefined): Promise<void>;
+//# sourceMappingURL=services.d.ts.map

package/dist/internal/discovery/services.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"services.d.ts","sourceRoot":"","sources":["../../../src/internal/discovery/services.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,KAAK,EACV,iBAAiB,EACjB,mBAAmB,EACnB,aAAa,EACd,MAAM,gBAAgB,CAAC;AAKxB,OAAO,EAAE,KAAK,gBAAgB,EAAe,MAAM,cAAc,CAAC;AAIlE,wBAAsB,WAAW,CAC/B,GAAG,EAAE,gBAAgB,EACrB,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,iBAAiB,GAAG,SAAS,GAC1C,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CA6BxC;AAED,wBAAsB,QAAQ,CAC5B,GAAG,EAAE,gBAAgB,EACrB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAOrC;AAED,wBAAsB,aAAa,CACjC,GAAG,EAAE,gBAAgB,EACrB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC,CAsB1C;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,gBAAgB,EACrB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,aAAa,EACpB,SAAS,EAAE,mBAAmB,GAAG,SAAS,GACzC,OAAO,CAAC,IAAI,CAAC,CAmBf"}

package/dist/internal/discovery/services.js

@@ -0,0 +1,104 @@
+/**
+ * `agent/storage.ts`, `agent/otel.ts`, `agent/artifacts.ts`: host services the agent configures.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { join } from "node:path";
+import { artifactBuiltinTool, TAG_ARTIFACT_TOOL_NAME, } from "../builtin-tools/index.js";
+import { displayPath } from "./context.js";
+import { findModuleFile } from "./fs.js";
+import { importDefault } from "./modules.js";
+export function loadStorage(ctx, agentDir, architecture) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const path = yield findModuleFile(agentDir, "storage");
+        if (path === undefined) {
+            return undefined;
+        }
+        if (architecture === "v2") {
+            // Storage is a hosting-mode decision on v2, made by
+            // framework-storage-selection.ts: the state root when self-hosted,
+            // Cursor-managed storage on Cursor hosting. Fail early (error
+            // diagnostics refuse serve and deploy) rather than silently running
+            // with storage the author believes they configured. Not imported.
+            ctx.diagnostics.push({
+                severity: "error",
+                path: displayPath(ctx, path),
+                message: 'agent/storage.ts is not supported on architecture "v2": the platform selects storage (the local state root when self-hosted; Cursor-managed storage on Cursor hosting). Delete the file.',
+            });
+            return undefined;
+        }
+        // v1 keeps loading the authored sink, with notice: defineStorage is going
+        // away with the v1 control plane.
+        ctx.diagnostics.push({
+            severity: "warning",
+            path: displayPath(ctx, path),
+            message: 'agent/storage.ts (defineStorage) is deprecated and going away: architecture "v2" selects storage automatically (the local state root when self-hosted; Cursor-managed storage on Cursor hosting). Still honored on v1.',
+        });
+        const definition = yield importDefault(ctx, path, "storage");
+        return definition;
+    });
+}
+export function loadOtel(ctx, agentDir) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const path = yield findModuleFile(agentDir, "otel");
+        if (path === undefined) {
+            return undefined;
+        }
+        const definition = yield importDefault(ctx, path, "otel");
+        return definition;
+    });
+}
+export function loadArtifacts(ctx, agentDir) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const path = yield findModuleFile(agentDir, "artifacts");
+        if (path === undefined) {
+            return undefined;
+        }
+        const imported = yield importDefault(ctx, path, "artifacts");
+        if (imported === undefined) {
+            return undefined;
+        }
+        const definition = imported;
+        if (definition.agentTool === true &&
+            Object.keys((_a = definition.kinds) !== null && _a !== void 0 ? _a : {}).length === 0) {
+            ctx.diagnostics.push({
+                severity: "error",
+                path: displayPath(ctx, path),
+                message: "artifacts.agentTool requires kinds: the tag_artifact tool needs at least one declared kind; its descriptions are the tool prompt.",
+            });
+        }
+        return definition;
+    });
+}
+/**
+ * Materialize the `tag_artifact` built-in when `defineArtifacts` set
+ * `agentTool: true`. Appended after `loadAgent` because the tool is
+ * generated from the artifacts kinds registry, not `AgentConfig.builtinTools`.
+ */
+export function appendArtifactTool(ctx, agentDir, agent, artifacts) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const tool = artifactBuiltinTool(artifacts);
+        if (tool === undefined) {
+            return;
+        }
+        const artifactsPath = displayPath(ctx, (_a = (yield findModuleFile(agentDir, "artifacts"))) !== null && _a !== void 0 ? _a : join(agentDir, "artifacts.ts"));
+        if (agent.tools.some((t) => t.name === TAG_ARTIFACT_TOOL_NAME)) {
+            ctx.diagnostics.push({
+                severity: "warning",
+                path: artifactsPath,
+                message: `Authored tool "${TAG_ARTIFACT_TOOL_NAME}" shadows the built-in tool of the same name; the authored tool wins.`,
+            });
+            return;
+        }
+        agent.tools.push(tool);
+    });
+}

package/dist/internal/discovery/skills.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `agent/skills/*`: markdown, packaged, and `defineSkill` skills.
+ */
+import type { DiscoveredSkill, SkillFileSource } from "../../types.js";
+import { type DiscoveryContext } from "./context.js";
+/** Declared frontmatter, else the body's first line, else a generic line. */
+export declare function skillDescription(name: string, declared: string | undefined, body: string): string;
+/** A packaged skill's sibling files, keyed by path relative to the skill dir. */
+export declare function skillFiles(skillDir: string): Promise<Record<string, SkillFileSource>>;
+export declare function loadSkills(ctx: DiscoveryContext, skillsDir: string): Promise<DiscoveredSkill[]>;
+/**
+ * Advertise the first non-empty, non-code-fence line of the body, with any
+ * leading `#`, `>`, `*`, or `-` markers stripped.
+ */
+export declare function deriveSkillDescription(markdown: string): string | undefined;
+//# sourceMappingURL=skills.d.ts.map

package/dist/internal/discovery/skills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../../src/internal/discovery/skills.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EACV,eAAe,EAGf,eAAe,EAChB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,KAAK,gBAAgB,EAAwB,MAAM,cAAc,CAAC;AAa3E,6EAA6E;AAC7E,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,IAAI,EAAE,MAAM,GACX,MAAM,CAMR;AAED,iFAAiF;AACjF,wBAAsB,UAAU,CAC9B,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAS1C;AAED,wBAAsB,UAAU,CAC9B,GAAG,EAAE,gBAAgB,EACrB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,eAAe,EAAE,CAAC,CA8C5B;AAoDD;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAiB3E"}

package/dist/internal/discovery/skills.js

@@ -0,0 +1,151 @@
+/**
+ * `agent/skills/*`: markdown, packaged, and `defineSkill` skills.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { readFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { parseFrontmatter } from "../frontmatter.js";
+import { displayPath, isBlank } from "./context.js";
+import { isDirectory, isFile, isModuleFile, moduleStem, sortedEntries, toPosix, walkFiles, } from "./fs.js";
+import { importDefault } from "./modules.js";
+import { validateName } from "./names.js";
+/** Declared frontmatter, else the body's first line, else a generic line. */
+export function skillDescription(name, declared, body) {
+    var _a;
+    return ((_a = declared !== null && declared !== void 0 ? declared : deriveSkillDescription(body)) !== null && _a !== void 0 ? _a : `Instructions for the ${name} skill.`);
+}
+/** A packaged skill's sibling files, keyed by path relative to the skill dir. */
+export function skillFiles(skillDir) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const files = {};
+        for (const filePath of yield walkFiles(skillDir)) {
+            const rel = toPosix(relative(skillDir, filePath));
+            if (rel !== "SKILL.md") {
+                files[rel] = { sourcePath: filePath };
+            }
+        }
+        return files;
+    });
+}
+export function loadSkills(ctx, skillsDir) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (!(yield isDirectory(skillsDir))) {
+            return [];
+        }
+        const skills = [];
+        for (const entry of yield sortedEntries(skillsDir)) {
+            const entryPath = join(skillsDir, entry.name);
+            if (entry.isDirectory()) {
+                const skill = yield loadPackagedSkill(ctx, entryPath, entry.name);
+                if (skill !== undefined) {
+                    skills.push(skill);
+                }
+                continue;
+            }
+            if (!entry.isFile()) {
+                continue;
+            }
+            if (entry.name.endsWith(".md")) {
+                const name = entry.name.slice(0, -".md".length);
+                if (!validateName(ctx, "skill", name, entryPath)) {
+                    continue;
+                }
+                const { data, body } = parseFrontmatter(yield readFile(entryPath, "utf8"));
+                skills.push({
+                    name,
+                    description: skillDescription(name, data.description, body),
+                    markdown: body.trim(),
+                    files: {},
+                });
+                continue;
+            }
+            if (isModuleFile(entry.name)) {
+                const name = moduleStem(entry.name);
+                if (!validateName(ctx, "skill", name, entryPath)) {
+                    continue;
+                }
+                const definition = yield importDefault(ctx, entryPath, "skill");
+                if (definition === undefined) {
+                    continue;
+                }
+                skills.push(compileSkill(name, definition));
+            }
+        }
+        return skills;
+    });
+}
+/** A skill whose body and sibling files are in memory (`defineSkill`, extensions). */
+function compileSkill(name, skill) {
+    var _a;
+    const files = {};
+    for (const [rel, contents] of Object.entries((_a = skill.files) !== null && _a !== void 0 ? _a : {})) {
+        files[rel] = { contents };
+    }
+    return {
+        name,
+        description: skillDescription(name, skill.description, skill.markdown),
+        markdown: skill.markdown.trim(),
+        files,
+    };
+}
+function loadPackagedSkill(ctx, skillDir, name) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const skillMdPath = join(skillDir, "SKILL.md");
+        if (!(yield isFile(skillMdPath))) {
+            ctx.diagnostics.push({
+                severity: "warning",
+                path: displayPath(ctx, skillDir),
+                message: "Skill directories must contain a SKILL.md; ignoring.",
+            });
+            return undefined;
+        }
+        if (!validateName(ctx, "skill", name, skillDir)) {
+            return undefined;
+        }
+        const { data, body } = parseFrontmatter(yield readFile(skillMdPath, "utf8"));
+        if (data.description === undefined || isBlank(data.description)) {
+            ctx.diagnostics.push({
+                severity: "error",
+                path: displayPath(ctx, skillMdPath),
+                message: "Packaged skills require `description` frontmatter in SKILL.md (there is no filename slug to fall back on).",
+            });
+            return undefined;
+        }
+        return {
+            name,
+            description: data.description,
+            markdown: body.trim(),
+            files: yield skillFiles(skillDir),
+        };
+    });
+}
+/**
+ * Advertise the first non-empty, non-code-fence line of the body, with any
+ * leading `#`, `>`, `*`, or `-` markers stripped.
+ */
+export function deriveSkillDescription(markdown) {
+    let inFence = false;
+    for (const rawLine of markdown.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (line.startsWith("```")) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence || line === "") {
+            continue;
+        }
+        const stripped = line.replace(/^[#>*\s-]+/, "").trim();
+        if (stripped !== "") {
+            return stripped.length > 200 ? `${stripped.slice(0, 197)}...` : stripped;
+        }
+    }
+    return undefined;
+}

package/dist/internal/discovery/subagent.d.ts

@@ -0,0 +1,13 @@
+/**
+ * A subagent as the Cursor harness runs it: description, model, and prompt. Its other slots are inert.
+ */
+import type { ModelSetting, ResolvedAgent } from "../../types.js";
+interface SubagentFields {
+    description?: string;
+    model?: ModelSetting;
+    /** Authored prompt; the identity preamble is prepended. */
+    prompt?: string;
+}
+export declare function subagent(name: string, fields: SubagentFields): ResolvedAgent;
+export {};
+//# sourceMappingURL=subagent.d.ts.map

package/dist/internal/discovery/subagent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent.d.ts","sourceRoot":"","sources":["../../../src/internal/discovery/subagent.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAGlE,UAAU,cAAc;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,aAAa,CAc5E"}

package/dist/internal/discovery/subagent.js

@@ -0,0 +1,19 @@
+/**
+ * A subagent as the Cursor harness runs it: description, model, and prompt. Its other slots are inert.
+ */
+import { withIdentityPreamble } from "../workspace.js";
+export function subagent(name, fields) {
+    return {
+        name,
+        description: fields.description,
+        model: fields.model,
+        instructions: withIdentityPreamble(name, fields.prompt),
+        runtime: "local",
+        tools: [],
+        skills: [],
+        connections: [],
+        hostConnections: [],
+        subagents: [],
+        seedFiles: [],
+    };
+}

package/dist/internal/discovery/tools.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `agent/tools/*.ts`: typed tools and the built-in tools appended after them.
+ */
+import type { BuiltinToolsConfig, DiscoveredTool, ToolDefinition } from "../../types.js";
+import { type DiscoveryContext } from "./context.js";
+export declare function loadTools(ctx: DiscoveryContext, toolsDir: string): Promise<DiscoveredTool[]>;
+/**
+ * Validate one tool definition against the tool contract and convert its
+ * schemas. Diagnostics point at `entryPath` (the authored file, or the
+ * extension mount that contributed the tool).
+ */
+export declare function compileTool(ctx: DiscoveryContext, entryPath: string, name: string, tool: ToolDefinition): DiscoveredTool | undefined;
+/**
+ * Append enabled built-in tools after authored tools. Authored tools with
+ * the same name win.
+ */
+export declare function appendBuiltinTools(ctx: DiscoveryContext, agentDir: string, tools: DiscoveredTool[], config: BuiltinToolsConfig | undefined): void;
+//# sourceMappingURL=tools.d.ts.map

package/dist/internal/discovery/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/internal/discovery/tools.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EACV,kBAAkB,EAClB,cAAc,EACd,cAAc,EAEf,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACL,KAAK,gBAAgB,EAItB,MAAM,cAAc,CAAC;AAGtB,wBAAsB,SAAS,CAC7B,GAAG,EAAE,gBAAgB,EACrB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,cAAc,EAAE,CAAC,CAa3B;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,GAAG,EAAE,gBAAgB,EACrB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,cAAc,GACnB,cAAc,GAAG,SAAS,CAkF5B;AAmBD;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,gBAAgB,EACrB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,cAAc,EAAE,EACvB,MAAM,EAAE,kBAAkB,GAAG,SAAS,GACrC,IAAI,CAsBN"}