@cursor/bdk 0.2.1

package/dist/internal/discovery/fs.js

@@ -0,0 +1,115 @@
+/**
+ * Filesystem primitives discovery walks with: module-file detection, directory listing, and project-root markers.
+ */
+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 { readdir, readFile, stat } from "node:fs/promises";
+import { extname, join } from "node:path";
+const MODULE_EXTENSIONS = new Set([".ts", ".mts", ".js", ".mjs"]);
+export function findModuleFile(dir, stem) {
+    return __awaiter(this, void 0, void 0, function* () {
+        for (const extension of [".ts", ".mts", ".js", ".mjs"]) {
+            const candidate = join(dir, `${stem}${extension}`);
+            if (yield isFile(candidate)) {
+                return candidate;
+            }
+        }
+        return undefined;
+    });
+}
+export function isModuleFile(fileName) {
+    if (fileName.endsWith(".d.ts") || fileName.startsWith(".")) {
+        return false;
+    }
+    if (!MODULE_EXTENSIONS.has(extname(fileName))) {
+        return false;
+    }
+    // Colocated unit tests (Vitest/Jest convention) are not definitions.
+    // Without this, `channels/slack.test.ts` is scanned as a channel named
+    // "slack.test", fails NAME_PATTERN, and the whole agent refuses to serve.
+    const stem = moduleStem(fileName);
+    return !stem.endsWith(".test") && !stem.endsWith(".spec");
+}
+export function moduleStem(fileName) {
+    return fileName.slice(0, -extname(fileName).length);
+}
+export function sortedEntries(dir) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const entries = yield readdir(dir, { withFileTypes: true });
+        return entries.sort((a, b) => a.name.localeCompare(b.name));
+    });
+}
+export function walkFiles(dir) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const files = [];
+        for (const entry of yield sortedEntries(dir)) {
+            if (entry.name.startsWith(".")) {
+                continue;
+            }
+            const entryPath = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                files.push(...(yield walkFiles(entryPath)));
+            }
+            else if (entry.isFile()) {
+                files.push(entryPath);
+            }
+        }
+        return files;
+    });
+}
+export function isDirectory(path) {
+    return __awaiter(this, void 0, void 0, function* () {
+        try {
+            return (yield stat(path)).isDirectory();
+        }
+        catch (_a) {
+            return false;
+        }
+    });
+}
+export function isFile(path) {
+    return __awaiter(this, void 0, void 0, function* () {
+        try {
+            return (yield stat(path)).isFile();
+        }
+        catch (_a) {
+            return false;
+        }
+    });
+}
+export function toPosix(path) {
+    return path.split("\\").join("/");
+}
+export function hasFlatLayoutMarkers(rootDir) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (yield isFile(join(rootDir, "instructions.md"))) {
+            return true;
+        }
+        return (yield findModuleFile(rootDir, "agent")) !== undefined;
+    });
+}
+export function readPackageName(rootDir) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const packageJsonPath = join(rootDir, "package.json");
+        if (!(yield isFile(packageJsonPath))) {
+            return undefined;
+        }
+        try {
+            const parsed = JSON.parse(yield readFile(packageJsonPath, "utf8"));
+            if (typeof parsed.name === "string" && parsed.name !== "") {
+                return parsed.name;
+            }
+        }
+        catch (_a) {
+            // Malformed package.json falls back to the directory name.
+        }
+        return undefined;
+    });
+}

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

@@ -0,0 +1,7 @@
+/**
+ * `agent/hooks/*.ts`: observe-only event subscribers.
+ */
+import type { DiscoveredHook } from "../../types.js";
+import { type DiscoveryContext } from "./context.js";
+export declare function loadHooks(ctx: DiscoveryContext, hooksDir: string, onDisable?: (name: string, path: string) => void): Promise<DiscoveredHook[]>;
+//# sourceMappingURL=hooks.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../../src/internal/discovery/hooks.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAkB,MAAM,gBAAgB,CAAC;AAErE,OAAO,EAAE,KAAK,gBAAgB,EAAe,MAAM,cAAc,CAAC;AAIlE,wBAAsB,SAAS,CAC7B,GAAG,EAAE,gBAAgB,EACrB,QAAQ,EAAE,MAAM,EAChB,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,GAC/C,OAAO,CAAC,cAAc,EAAE,CAAC,CA+C3B"}

package/dist/internal/discovery/hooks.js

@@ -0,0 +1,61 @@
+/**
+ * `agent/hooks/*.ts`: observe-only event subscribers.
+ */
+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 { basename, extname, relative } from "node:path";
+import { getDefinitionKind } from "../brand.js";
+import { displayPath } from "./context.js";
+import { isDirectory, isModuleFile, toPosix, walkFiles } from "./fs.js";
+import { importDefault } from "./modules.js";
+export function loadHooks(ctx, hooksDir, onDisable) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (!(yield isDirectory(hooksDir))) {
+            return [];
+        }
+        const hooks = [];
+        for (const filePath of yield walkFiles(hooksDir)) {
+            if (!isModuleFile(basename(filePath))) {
+                continue;
+            }
+            const rel = toPosix(relative(hooksDir, filePath));
+            const name = rel.slice(0, -extname(rel).length);
+            if (name.includes("__")) {
+                ctx.diagnostics.push({
+                    severity: "error",
+                    path: displayPath(ctx, filePath),
+                    message: `Hook name "${name}" may not contain "__"; it is reserved for extension contributions (\`<ns>__<name>\`).`,
+                });
+                continue;
+            }
+            const definition = yield importDefault(ctx, filePath, onDisable === undefined ? "hook" : ["hook", "disabled"]);
+            if (definition === undefined) {
+                continue;
+            }
+            if (getDefinitionKind(definition) === "disabled") {
+                onDisable === null || onDisable === void 0 ? void 0 : onDisable(name, filePath);
+                continue;
+            }
+            const hook = definition;
+            if (typeof hook.events !== "object" ||
+                hook.events === null ||
+                Object.keys(hook.events).length === 0) {
+                ctx.diagnostics.push({
+                    severity: "warning",
+                    path: displayPath(ctx, filePath),
+                    message: "Hook declares no event handlers.",
+                });
+                continue;
+            }
+            hooks.push({ name, definition: hook });
+        }
+        return hooks;
+    });
+}

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

@@ -0,0 +1,6 @@
+/**
+ * The `info` / `GET /v1/info` projection of an {@link AgentProject}.
+ */
+import { type AgentProject, type AgentProjectInfo } from "../../types.js";
+export declare function projectInfo(project: AgentProject): AgentProjectInfo;
+//# sourceMappingURL=info.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"info.d.ts","sourceRoot":"","sources":["../../../src/internal/discovery/info.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,gBAAgB,EAAqB,MAAM,gBAAgB,CAAC;AAK7F,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,gBAAgB,CAmKnE"}

package/dist/internal/discovery/info.js

@@ -0,0 +1,168 @@
+/**
+ * The `info` / `GET /v1/info` projection of an {@link AgentProject}.
+ */
+import { resolveArtifactsMax } from "../../artifacts.js";
+import { toPublicCloudInfo } from "../../types.js";
+import { toolInputJsonSchema } from "../json-schema.js";
+import { MCP_ENDPOINT_PATH, mcpEndpointToolNames } from "../mcp-endpoint.js";
+import { connectionTransportLabel } from "./connections.js";
+export function projectInfo(project) {
+    var _a, _b, _c, _d;
+    const agent = project.agent;
+    const httpRoutes = [
+        { method: "POST", path: "/v1/session", url: "/v1/session" },
+        {
+            method: "POST",
+            path: "/v1/session/:sessionId",
+            url: "/v1/session/:sessionId",
+        },
+        {
+            method: "POST",
+            path: "/v1/session/:sessionId/stop",
+            url: "/v1/session/:sessionId/stop",
+        },
+        {
+            method: "GET",
+            path: "/v1/session/:sessionId/stream",
+            url: "/v1/session/:sessionId/stream",
+        },
+        {
+            method: "GET",
+            path: "/v1/session/:sessionId/approvals",
+            url: "/v1/session/:sessionId/approvals",
+        },
+        {
+            method: "POST",
+            path: "/v1/session/:sessionId/approvals/:callId",
+            url: "/v1/session/:sessionId/approvals/:callId",
+        },
+    ];
+    return {
+        name: project.name,
+        description: agent.description,
+        model: agent.model,
+        runtime: agent.runtime,
+        cloud: agent.cloud === undefined ? undefined : toPublicCloudInfo(agent.cloud),
+        local: agent.local,
+        hosting: agent.hosting,
+        concurrency: agent.concurrency,
+        mcp: { path: MCP_ENDPOINT_PATH, tools: mcpEndpointToolNames(project) },
+        instructions: agent.instructions === undefined
+            ? undefined
+            : {
+                chars: agent.instructions.length,
+                preview: agent.instructions.length > 280
+                    ? `${agent.instructions.slice(0, 277)}...`
+                    : agent.instructions,
+            },
+        tools: agent.tools.map(tool => ({
+            name: tool.name,
+            description: tool.description,
+            execution: tool.execution,
+            needsApproval: tool.needsApproval,
+            effect: tool.effect,
+            inputSchema: tool.inputSchema,
+        })),
+        skills: agent.skills.map(skill => ({
+            name: skill.name,
+            description: skill.description,
+        })),
+        extensions: (_a = agent.extensions) !== null && _a !== void 0 ? _a : [],
+        connections: agent.connections.map(connection => { var _a; return ({
+            name: connection.name,
+            transport: connectionTransportLabel(connection.transport),
+            advertiseTools: connection.advertiseTools,
+            optional: connection.optional,
+            effects: connection.effects,
+            tools: connection.tools,
+            disallowedTools: connection.disallowedTools,
+            cursorAccountServers: "cursorAccount" in connection.transport ? ((_a = connection.transport.servers) !== null && _a !== void 0 ? _a : "*") : undefined,
+        }); }),
+        subagents: agent.subagents.map(subagent => ({
+            name: subagent.name,
+            description: subagent.description,
+            model: subagent.model,
+        })),
+        channels: [
+            { id: "http", routes: httpRoutes },
+            ...project.channels.map(channel => {
+                var _a;
+                const info = {
+                    id: channel.id,
+                    routes: ((_a = channel.definition.routes) !== null && _a !== void 0 ? _a : []).map(r => {
+                        const routeInfo = {
+                            method: r.method,
+                            path: r.path,
+                            url: `/v1/channels/${channel.id}${r.path}`,
+                        };
+                        if (r.description !== undefined) {
+                            routeInfo.description = r.description;
+                        }
+                        if (r.bodySchema !== undefined) {
+                            routeInfo.bodySchema = toolInputJsonSchema(r.bodySchema);
+                        }
+                        if (r.querySchema !== undefined) {
+                            routeInfo.querySchema = toolInputJsonSchema(r.querySchema);
+                        }
+                        return routeInfo;
+                    }),
+                };
+                const meta = channel.definition.meta;
+                if ((meta === null || meta === void 0 ? void 0 : meta.kind) !== undefined) {
+                    info.kind = meta.kind;
+                }
+                if ((meta === null || meta === void 0 ? void 0 : meta.githubWebhookEvents) !== undefined) {
+                    info.githubWebhookEvents = meta.githubWebhookEvents;
+                }
+                if ((meta === null || meta === void 0 ? void 0 : meta.originWebhookEvents) !== undefined) {
+                    info.originWebhookEvents = meta.originWebhookEvents;
+                }
+                if ((meta === null || meta === void 0 ? void 0 : meta.gitlabWebhookEvents) !== undefined) {
+                    info.gitlabWebhookEvents = meta.gitlabWebhookEvents;
+                }
+                if ((meta === null || meta === void 0 ? void 0 : meta.bitbucketWebhookEvents) !== undefined) {
+                    info.bitbucketWebhookEvents = meta.bitbucketWebhookEvents;
+                }
+                if ((meta === null || meta === void 0 ? void 0 : meta.deploymentEventTypes) !== undefined) {
+                    info.deploymentEventTypes = meta.deploymentEventTypes;
+                }
+                if ((meta === null || meta === void 0 ? void 0 : meta.factoryEventTypes) !== undefined) {
+                    info.factoryEventTypes = meta.factoryEventTypes;
+                }
+                if ((meta === null || meta === void 0 ? void 0 : meta.slackEventTypes) !== undefined) {
+                    info.slackEventTypes = meta.slackEventTypes;
+                }
+                if ((meta === null || meta === void 0 ? void 0 : meta.slackChannelPosts) !== undefined) {
+                    info.slackChannelPosts = meta.slackChannelPosts;
+                }
+                return info;
+            }),
+        ],
+        schedules: project.schedules.map(schedule => ({
+            name: schedule.name,
+            cron: schedule.cron,
+            kind: schedule.kind,
+        })),
+        reminders: ((_b = project.reminders) !== null && _b !== void 0 ? _b : []).length === 0
+            ? undefined
+            : ((_c = project.reminders) !== null && _c !== void 0 ? _c : []).map(reminder => ({
+                name: reminder.name,
+            })),
+        hooks: project.hooks.map(hook => hook.name),
+        storage: project.storage === undefined ? undefined : { name: project.storage.name },
+        artifacts: project.artifacts === undefined
+            ? undefined
+            : {
+                kinds: Object.keys((_d = project.artifacts.kinds) !== null && _d !== void 0 ? _d : {}),
+                agentTool: project.artifacts.agentTool === true,
+                max: resolveArtifactsMax(project.artifacts),
+            },
+        otel: project.otel === undefined
+            ? undefined
+            : {
+                enabled: true,
+                serviceName: project.otel.serviceName,
+            },
+        diagnostics: project.diagnostics,
+    };
+}

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

@@ -0,0 +1,7 @@
+/**
+ * `agent/instructions.md` (or `.ts`, or a directory): the always-on system prompt.
+ */
+import type { AgentConfigDefinition } from "../../types.js";
+import { type DiscoveryContext } from "./context.js";
+export declare function loadInstructions(ctx: DiscoveryContext, agentDir: string, config: AgentConfigDefinition | undefined, isRoot: boolean): Promise<string | undefined>;
+//# sourceMappingURL=instructions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.d.ts","sourceRoot":"","sources":["../../../src/internal/discovery/instructions.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,qBAAqB,EAA0B,MAAM,gBAAgB,CAAC;AAEpF,OAAO,EAAE,KAAK,gBAAgB,EAAsC,MAAM,cAAc,CAAC;AAGzF,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,gBAAgB,EACrB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,qBAAqB,GAAG,SAAS,EACzC,MAAM,EAAE,OAAO,GACd,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAkD7B"}

package/dist/internal/discovery/instructions.js

@@ -0,0 +1,95 @@
+/**
+ * `agent/instructions.md` (or `.ts`, or a directory): the always-on system prompt.
+ */
+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 } from "node:path";
+import { getDefinitionKind } from "../brand.js";
+import { displayPath, errorMessage, isBlank } from "./context.js";
+import { findModuleFile, isDirectory, isFile, isModuleFile, sortedEntries } from "./fs.js";
+export function loadInstructions(ctx, agentDir, config, isRoot) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const parts = [];
+        const markdownPath = join(agentDir, "instructions.md");
+        if (yield isFile(markdownPath)) {
+            parts.push((yield readFile(markdownPath, "utf8")).trim());
+        }
+        const modulePath = yield findModuleFile(agentDir, "instructions");
+        if (modulePath !== undefined) {
+            const loaded = yield loadInstructionsModule(ctx, modulePath);
+            if (loaded !== undefined) {
+                parts.push(loaded);
+            }
+        }
+        const instructionsDir = join(agentDir, "instructions");
+        if (yield isDirectory(instructionsDir)) {
+            for (const entry of yield sortedEntries(instructionsDir)) {
+                if (!entry.isFile()) {
+                    continue;
+                }
+                const entryPath = join(instructionsDir, entry.name);
+                if (entry.name.endsWith(".md")) {
+                    parts.push((yield readFile(entryPath, "utf8")).trim());
+                }
+                else if (isModuleFile(entry.name)) {
+                    const loaded = yield loadInstructionsModule(ctx, entryPath);
+                    if (loaded !== undefined) {
+                        parts.push(loaded);
+                    }
+                }
+            }
+        }
+        if ((config === null || config === void 0 ? void 0 : config.instructions) !== undefined && !isBlank(config.instructions)) {
+            parts.push(config.instructions.trim());
+        }
+        const combined = parts.filter(part => part !== "").join("\n\n");
+        if (combined === "") {
+            if (isRoot) {
+                ctx.diagnostics.push({
+                    severity: "error",
+                    path: displayPath(ctx, markdownPath),
+                    message: "instructions.md is required on the root agent (the always-on system prompt).",
+                });
+            }
+            return undefined;
+        }
+        return combined;
+    });
+}
+function loadInstructionsModule(ctx, modulePath) {
+    return __awaiter(this, void 0, void 0, function* () {
+        let mod;
+        try {
+            mod = yield ctx.importModule(modulePath);
+        }
+        catch (error) {
+            ctx.diagnostics.push({
+                severity: "error",
+                path: displayPath(ctx, modulePath),
+                message: `Failed to load module: ${errorMessage(error)}`,
+            });
+            return undefined;
+        }
+        const value = mod.default;
+        if (typeof value === "string") {
+            return value.trim();
+        }
+        if (getDefinitionKind(value) === "instructions") {
+            return value.markdown.trim();
+        }
+        ctx.diagnostics.push({
+            severity: "error",
+            path: displayPath(ctx, modulePath),
+            message: "Instructions modules must default-export a string or defineInstructions({ markdown }).",
+        });
+        return undefined;
+    });
+}

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

@@ -0,0 +1,20 @@
+/**
+ * Walk a slot's module files, import one, and check that its default export carries an expected definition brand.
+ */
+import type { DefinitionKind } from "../../types.js";
+import { type DiscoveryContext } from "./context.js";
+type ImportableKind = Exclude<DefinitionKind, "instructions" | "eval">;
+/** The module files of a slot directory whose filenames are valid names. */
+export declare function moduleEntries(ctx: DiscoveryContext, dir: string, kind: "tool" | "connection"): Promise<Array<{
+    name: string;
+    path: string;
+}>>;
+/**
+ * The module's default export when it carries one of the expected brands;
+ * a diagnostic and `undefined` otherwise.
+ */
+export declare function importDefault(ctx: DiscoveryContext, modulePath: string, expected: ImportableKind | readonly ImportableKind[]): Promise<unknown>;
+/** How a definition of `kind` is authored: `defineTool({ ... })`, `disableTool()`. */
+export declare function helperCall(kind: ImportableKind): string;
+export {};
+//# sourceMappingURL=modules.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"modules.d.ts","sourceRoot":"","sources":["../../../src/internal/discovery/modules.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD,OAAO,EAAE,KAAK,gBAAgB,EAA6B,MAAM,cAAc,CAAC;AAIhF,KAAK,cAAc,GAAG,OAAO,CAAC,cAAc,EAAE,cAAc,GAAG,MAAM,CAAC,CAAC;AAEvE,4EAA4E;AAC5E,wBAAsB,aAAa,CACjC,GAAG,EAAE,gBAAgB,EACrB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,GAAG,YAAY,GAC1B,OAAO,CAAC,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAwBhD;AAED;;;GAGG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,gBAAgB,EACrB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,cAAc,GAAG,SAAS,cAAc,EAAE,GACnD,OAAO,CAAC,OAAO,CAAC,CA6BlB;AAED,sFAAsF;AACtF,wBAAgB,UAAU,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAGvD"}

package/dist/internal/discovery/modules.js

@@ -0,0 +1,104 @@
+/**
+ * Walk a slot's module files, import one, and check that its default export carries an expected definition brand.
+ */
+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 { getDefinitionKind } from "../brand.js";
+import { displayPath, errorMessage } from "./context.js";
+import { isDirectory, isModuleFile, moduleStem, sortedEntries } from "./fs.js";
+import { validateName } from "./names.js";
+/** The module files of a slot directory whose filenames are valid names. */
+export function moduleEntries(ctx, dir, kind) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (!(yield isDirectory(dir))) {
+            return [];
+        }
+        const entries = [];
+        for (const entry of yield sortedEntries(dir)) {
+            const path = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                ctx.diagnostics.push({
+                    severity: "warning",
+                    path: displayPath(ctx, path),
+                    message: `Nested ${kind} directories are not supported; ignoring.`,
+                });
+                continue;
+            }
+            if (!entry.isFile() || !isModuleFile(entry.name)) {
+                continue;
+            }
+            const name = moduleStem(entry.name);
+            if (validateName(ctx, kind, name, path)) {
+                entries.push({ name, path });
+            }
+        }
+        return entries;
+    });
+}
+/**
+ * The module's default export when it carries one of the expected brands;
+ * a diagnostic and `undefined` otherwise.
+ */
+export function importDefault(ctx, modulePath, expected) {
+    return __awaiter(this, void 0, void 0, function* () {
+        let mod;
+        try {
+            mod = yield ctx.importModule(modulePath);
+        }
+        catch (error) {
+            ctx.diagnostics.push({
+                severity: "error",
+                path: displayPath(ctx, modulePath),
+                message: `Failed to load module: ${errorMessage(error)}`,
+            });
+            return undefined;
+        }
+        const kinds = typeof expected === "string" ? [expected] : expected;
+        const kind = getDefinitionKind(mod.default);
+        if (kind !== undefined && kinds.includes(kind)) {
+            return mod.default;
+        }
+        const helpers = kinds.map(helperCall).join(" or ");
+        const expectedKinds = kinds.join(" or ");
+        const article = /^[aeiou]/.test(expectedKinds) ? "an" : "a";
+        ctx.diagnostics.push({
+            severity: "error",
+            path: displayPath(ctx, modulePath),
+            message: kind === undefined
+                ? `Module must default-export ${helpers}.`
+                : `Expected ${article} ${expectedKinds} definition but found "${kind}" (wrong authored slot?).`,
+        });
+        return undefined;
+    });
+}
+/** How a definition of `kind` is authored: `defineTool({ ... })`, `disableTool()`. */
+export function helperCall(kind) {
+    const name = DEFINE_HELPER_NAME[kind];
+    return kind === "disabled" || kind.startsWith("disabled-") ? `${name}()` : `${name}({ ... })`;
+}
+const DEFINE_HELPER_NAME = {
+    agent: "defineAgent",
+    tool: "defineTool",
+    skill: "defineSkill",
+    extension: "defineExtension",
+    "disabled-tool": "disableTool",
+    "disabled-connection": "disableConnection",
+    disabled: "disable",
+    connection: "defineConnection",
+    channel: "defineChannel",
+    "http-channel": "httpChannel",
+    schedule: "defineSchedule",
+    reminder: "defineReminder",
+    hook: "defineHook",
+    storage: "defineStorage",
+    artifacts: "defineArtifacts",
+    otel: "defineOtel",
+};

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

@@ -0,0 +1,12 @@
+/**
+ * The path-derived naming rule: filenames become the names the model sees.
+ */
+import { type DiscoveryContext } from "./context.js";
+export declare const NAME_PATTERN: RegExp;
+/**
+ * Filenames become the names the model sees. `__` is reserved: it joins an
+ * extension's namespace to its contribution (`ci__failed_jobs`), so no
+ * authored name may carry it.
+ */
+export declare function validateName(ctx: DiscoveryContext, kind: "skill" | "tool" | "extension" | "connection" | "subagent" | "channel", name: string, entryPath: string): boolean;
+//# sourceMappingURL=names.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"names.d.ts","sourceRoot":"","sources":["../../../src/internal/discovery/names.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,KAAK,gBAAgB,EAAe,MAAM,cAAc,CAAC;AAElE,eAAO,MAAM,YAAY,EAAE,MAAsC,CAAC;AAElE;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,gBAAgB,EACrB,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,WAAW,GAAG,YAAY,GAAG,UAAU,GAAG,SAAS,EAC5E,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GAChB,OAAO,CA0BT"}

package/dist/internal/discovery/names.js

@@ -0,0 +1,37 @@
+/**
+ * The path-derived naming rule: filenames become the names the model sees.
+ */
+import { displayPath } from "./context.js";
+export const NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+/**
+ * Filenames become the names the model sees. `__` is reserved: it joins an
+ * extension's namespace to its contribution (`ci__failed_jobs`), so no
+ * authored name may carry it.
+ */
+export function validateName(ctx, kind, name, entryPath) {
+    const label = {
+        skill: "Skill",
+        tool: "Tool",
+        extension: "Extension",
+        connection: "MCP connection",
+        subagent: "Subagent",
+        channel: "Channel",
+    }[kind];
+    if (!NAME_PATTERN.test(name)) {
+        ctx.diagnostics.push({
+            severity: "error",
+            path: displayPath(ctx, entryPath),
+            message: `${label} name "${name}" must match ${NAME_PATTERN}.`,
+        });
+        return false;
+    }
+    if (name.includes("__")) {
+        ctx.diagnostics.push({
+            severity: "error",
+            path: displayPath(ctx, entryPath),
+            message: `${label} name "${name}" may not contain "__"; it is reserved for extension contributions (\`<ns>__<name>\`).`,
+        });
+        return false;
+    }
+    return true;
+}