@cursor/july 0.1.100 → 0.1.102

package/dist/internal/discovery/ab.js

@@ -0,0 +1,101 @@
+/**
+ * `agent/ab.ts` or `agent/ab/*.ts` plus `agent/ab.config.ts`: live A/B experiments.
+ */
+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, join, relative } from "node:path";
+import { displayPath } from "./context.js";
+import { findModuleFile, isDirectory, isModuleFile, toPosix, walkFiles, } from "./fs.js";
+import { importDefault } from "./modules.js";
+export function loadABs(ctx, agentDir) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const abs = [];
+        const seen = new Set();
+        const single = yield findModuleFile(agentDir, "ab");
+        if (single !== undefined) {
+            const definition = yield importDefault(ctx, single, "ab");
+            if (definition !== undefined) {
+                const name = resolveABName(definition, "ab");
+                seen.add(name);
+                abs.push({
+                    name,
+                    definition: definition,
+                });
+            }
+        }
+        const absDir = join(agentDir, "ab");
+        if (yield isDirectory(absDir)) {
+            for (const filePath of yield walkFiles(absDir)) {
+                if (!isModuleFile(basename(filePath))) {
+                    continue;
+                }
+                const rel = toPosix(relative(absDir, filePath));
+                const stem = rel.slice(0, -extname(rel).length);
+                const definition = yield importDefault(ctx, filePath, "ab");
+                if (definition === undefined) {
+                    continue;
+                }
+                const name = resolveABName(definition, stem);
+                if (seen.has(name)) {
+                    ctx.diagnostics.push({
+                        severity: "error",
+                        path: displayPath(ctx, filePath),
+                        message: `Duplicate A/B experiment name ${JSON.stringify(name)}.`,
+                    });
+                    continue;
+                }
+                seen.add(name);
+                abs.push({
+                    name,
+                    definition: definition,
+                });
+            }
+        }
+        return abs;
+    });
+}
+export function loadABConfig(ctx, agentDir) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const path = yield findModuleFile(agentDir, "ab.config");
+        if (path === undefined) {
+            return undefined;
+        }
+        try {
+            const mod = yield ctx.importModule(path);
+            if (mod.default === null || typeof mod.default !== "object") {
+                ctx.diagnostics.push({
+                    severity: "error",
+                    path: displayPath(ctx, path),
+                    message: "ab.config.ts must default-export defineABConfig({ ... }) from @cursor/july/ab.",
+                });
+                return undefined;
+            }
+            return mod.default;
+        }
+        catch (error) {
+            ctx.diagnostics.push({
+                severity: "error",
+                path: displayPath(ctx, path),
+                message: `Failed to load ab.config: ${error instanceof Error ? error.message : String(error)}`,
+            });
+            return undefined;
+        }
+    });
+}
+function resolveABName(definition, fallback) {
+    if (typeof definition === "object" &&
+        definition !== null &&
+        "name" in definition &&
+        typeof definition.name === "string" &&
+        definition.name.length > 0) {
+        return definition.name;
+    }
+    return fallback;
+}

package/dist/internal/discovery/agent-config.d.ts

@@ -0,0 +1,35 @@
+/**
+ * `agent/agent.ts`: model, runtime architecture, working directory, hosting, and concurrency.
+ */
+import { type AgentArchitecture, type AgentConcurrencyOptions, type AgentConfigDefinition, type AgentHostingOptions, type AgentRuntime, type ModelSetting } from "../../types.js";
+import { type DiscoveryContext } from "./context.js";
+export declare function runtimeArchitectureCompatibilityError(agent: {
+    runtime: AgentRuntime;
+    architecture?: AgentArchitecture;
+}): string | undefined;
+export declare function resolveArchitecture(ctx: DiscoveryContext, agentDir: string, architecture: AgentArchitecture | undefined): AgentArchitecture | undefined;
+/** Absolute harness cwd parent, or undefined when unset / blank. */
+export declare function resolveAgentCwd(ctx: DiscoveryContext, authored: string | undefined): string | undefined;
+/**
+ * Nested git checkouts inherit ancestor AGENTS.md / .cursor rules and MCP.
+ * Point those harnesses at ~/.cache/agent-serve/<dir> unless the agent
+ * already set cwd or workspaceDir.
+ */
+export declare function resolveLocalCwd(ctx: DiscoveryContext, authoredCwd: string | undefined, authoredWorkspaceDir: string | undefined): Promise<string | undefined>;
+/**
+ * Validate the authored `hosting` block against the same grammar the
+ * backend enforces on deploy. Violations are warning diagnostics (reported
+ * by `agent-sdk validate`), not hard failures: the backend stays
+ * authoritative and `agent-sdk deploy` re-checks before any network call.
+ */
+export declare function resolveHosting(ctx: DiscoveryContext, agentDir: string, hosting: AgentHostingOptions | undefined): AgentHostingOptions | undefined;
+/**
+ * Validate the authored `concurrency` block. Invalid values are **error**
+ * diagnostics (serve refuses to start): silently dropping a turn ceiling
+ * would fail open to unlimited parallelism, the opposite of what the
+ * author asked for.
+ */
+export declare function resolveConcurrency(ctx: DiscoveryContext, agentDir: string, concurrency: AgentConcurrencyOptions | undefined): AgentConcurrencyOptions | undefined;
+export declare function loadAgentConfig(ctx: DiscoveryContext, agentDir: string, isRoot: boolean): Promise<AgentConfigDefinition | undefined>;
+export declare function isValidModelSetting(model: unknown): model is ModelSetting;
+//# sourceMappingURL=agent-config.d.ts.map

package/dist/internal/discovery/agent-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-config.d.ts","sourceRoot":"","sources":["../../../src/internal/discovery/agent-config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,YAAY,EAEjB,KAAK,YAAY,EAClB,MAAM,gBAAgB,CAAC;AASxB,OAAO,EAAE,KAAK,gBAAgB,EAAwB,MAAM,cAAc,CAAC;AAI3E,wBAAgB,qCAAqC,CAAC,KAAK,EAAE;IAC3D,OAAO,EAAE,YAAY,CAAC;IACtB,YAAY,CAAC,EAAE,iBAAiB,CAAC;CAClC,GAAG,MAAM,GAAG,SAAS,CAIrB;AAED,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,gBAAgB,EACrB,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,iBAAiB,GAAG,SAAS,GAC1C,iBAAiB,GAAG,SAAS,CAc/B;AAED,oEAAoE;AACpE,wBAAgB,eAAe,CAC7B,GAAG,EAAE,gBAAgB,EACrB,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC3B,MAAM,GAAG,SAAS,CASpB;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,gBAAgB,EACrB,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,oBAAoB,EAAE,MAAM,GAAG,SAAS,GACvC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAY7B;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,gBAAgB,EACrB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,mBAAmB,GAAG,SAAS,GACvC,mBAAmB,GAAG,SAAS,CAyCjC;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,gBAAgB,EACrB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,uBAAuB,GAAG,SAAS,GAC/C,uBAAuB,GAAG,SAAS,CAmBrC;AAED,wBAAsB,eAAe,CACnC,GAAG,EAAE,gBAAgB,EACrB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,OAAO,GACd,OAAO,CAAC,qBAAqB,GAAG,SAAS,CAAC,CA4B5C;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAUzE"}

package/dist/internal/discovery/agent-config.js

@@ -0,0 +1,173 @@
+/**
+ * `agent/agent.ts`: model, runtime architecture, working directory, hosting, and concurrency.
+ */
+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, isAbsolute, join, resolve } from "node:path";
+import { MAX_RUNNING_TURNS_LIMIT, } from "../../types.js";
+import { normalizePositiveInt } from "../bounded-int.js";
+import { isReservedSecretName, MAX_EGRESS_DOMAINS, validateEgressDomain, validateSecretName, } from "../hosting.js";
+import { defaultLocalHarnessCwd, isNestedInGitRepo } from "../workspace.js";
+import { displayPath, isBlank } from "./context.js";
+import { findModuleFile } from "./fs.js";
+import { importDefault } from "./modules.js";
+export function runtimeArchitectureCompatibilityError(agent) {
+    return agent.architecture === "v2" && agent.runtime === "grokbot"
+        ? 'architecture: "v2" cannot use runtime: "grokbot": the grokbot runtime executes through the signed-in account\'s hosted /v0/grokbot box, not a deployment-scoped v2 runtime.'
+        : undefined;
+}
+export function resolveArchitecture(ctx, agentDir, architecture) {
+    if (architecture === undefined ||
+        architecture === "v1" ||
+        architecture === "v2") {
+        return architecture;
+    }
+    ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, join(agentDir, "agent.ts")),
+        message: `architecture must be "v1" or "v2"; got ${JSON.stringify(architecture)}.`,
+    });
+    return undefined;
+}
+/** Absolute harness cwd parent, or undefined when unset / blank. */
+export function resolveAgentCwd(ctx, authored) {
+    if (authored === undefined) {
+        return undefined;
+    }
+    const trimmed = authored.trim();
+    if (trimmed === "") {
+        return undefined;
+    }
+    return isAbsolute(trimmed) ? trimmed : resolve(ctx.rootDir, trimmed);
+}
+/**
+ * Nested git checkouts inherit ancestor AGENTS.md / .cursor rules and MCP.
+ * Point those harnesses at ~/.cache/agent-serve/<dir> unless the agent
+ * already set cwd or workspaceDir.
+ */
+export function resolveLocalCwd(ctx, authoredCwd, authoredWorkspaceDir) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const cwd = resolveAgentCwd(ctx, authoredCwd);
+        if (cwd !== undefined) {
+            return cwd;
+        }
+        if (resolveAgentCwd(ctx, authoredWorkspaceDir) !== undefined) {
+            return undefined;
+        }
+        if (!(yield isNestedInGitRepo(ctx.rootDir))) {
+            return undefined;
+        }
+        return defaultLocalHarnessCwd(basename(ctx.rootDir));
+    });
+}
+/**
+ * Validate the authored `hosting` block against the same grammar the
+ * backend enforces on deploy. Violations are warning diagnostics (reported
+ * by `agent-sdk validate`), not hard failures: the backend stays
+ * authoritative and `agent-sdk deploy` re-checks before any network call.
+ */
+export function resolveHosting(ctx, agentDir, hosting) {
+    var _a, _b;
+    if (hosting === undefined) {
+        return undefined;
+    }
+    const agentPath = displayPath(ctx, join(agentDir, "agent.ts"));
+    const warn = (message) => {
+        ctx.diagnostics.push({ severity: "warning", path: agentPath, message });
+    };
+    const egressDomains = (_a = hosting.egressDomains) !== null && _a !== void 0 ? _a : [];
+    for (const domain of egressDomains) {
+        const domainError = validateEgressDomain(domain);
+        if (domainError !== undefined) {
+            warn(`hosting.egressDomains: ${domainError}`);
+        }
+    }
+    if (egressDomains.length > MAX_EGRESS_DOMAINS) {
+        warn(`hosting.egressDomains lists ${egressDomains.length} domains; deploys are capped at ${MAX_EGRESS_DOMAINS}.`);
+    }
+    for (const name of (_b = hosting.secretNames) !== null && _b !== void 0 ? _b : []) {
+        const nameError = validateSecretName(name);
+        if (nameError !== undefined) {
+            warn(`hosting.secretNames: ${nameError}`);
+        }
+        else if (isReservedSecretName(name)) {
+            warn(`hosting.secretNames: ${JSON.stringify(name)} is platform-managed (CURSOR_* / reserved hosted-storage names); omit it from secretNames.`);
+        }
+    }
+    return Object.assign(Object.assign({}, (hosting.egressDomains === undefined
+        ? {}
+        : { egressDomains: [...hosting.egressDomains] })), (hosting.secretNames === undefined
+        ? {}
+        : { secretNames: [...hosting.secretNames] }));
+}
+/**
+ * Validate the authored `concurrency` block. Invalid values are **error**
+ * diagnostics (serve refuses to start): silently dropping a turn ceiling
+ * would fail open to unlimited parallelism, the opposite of what the
+ * author asked for.
+ */
+export function resolveConcurrency(ctx, agentDir, concurrency) {
+    if (concurrency === undefined || concurrency.maxRunningTurns === undefined) {
+        return undefined;
+    }
+    try {
+        return {
+            maxRunningTurns: normalizePositiveInt(concurrency.maxRunningTurns, {
+                label: "concurrency.maxRunningTurns",
+                max: MAX_RUNNING_TURNS_LIMIT,
+            }),
+        };
+    }
+    catch (error) {
+        ctx.diagnostics.push({
+            severity: "error",
+            path: displayPath(ctx, join(agentDir, "agent.ts")),
+            message: error instanceof Error ? error.message : String(error),
+        });
+        return undefined;
+    }
+}
+export function loadAgentConfig(ctx, agentDir, isRoot) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const configPath = yield findModuleFile(agentDir, "agent");
+        if (configPath === undefined) {
+            ctx.diagnostics.push({
+                severity: "error",
+                path: displayPath(ctx, join(agentDir, "agent.ts")),
+                message: isRoot
+                    ? "agent.ts is required on the root agent: default-export defineAgent({ ... })"
+                    : "agent.ts is required on a subagent: default-export defineAgent({ description: ... })",
+            });
+            return undefined;
+        }
+        const definition = yield importDefault(ctx, configPath, "agent");
+        if (definition === undefined) {
+            return undefined;
+        }
+        const config = definition;
+        if (!isRoot && isBlank(config.description)) {
+            ctx.diagnostics.push({
+                severity: "error",
+                path: displayPath(ctx, configPath),
+                message: "Subagents require a description; the parent model reads it to decide when to delegate.",
+            });
+        }
+        return config;
+    });
+}
+export function isValidModelSetting(model) {
+    if (typeof model === "string") {
+        return model.trim() !== "";
+    }
+    return (typeof model === "object" &&
+        model !== null &&
+        typeof model.id === "string" &&
+        model.id.trim() !== "");
+}

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

@@ -0,0 +1,11 @@
+/**
+ * Compile one `agent/` directory (and its subagents) into a {@link ResolvedAgent}.
+ */
+import { type ResolvedAgent } from "../../types.js";
+import { type DiscoveryContext } from "./context.js";
+export declare function loadAgent(ctx: DiscoveryContext, agentDir: string, options: {
+    name: string;
+    isRoot: boolean;
+}): Promise<ResolvedAgent>;
+export declare function warnUnknownSlots(ctx: DiscoveryContext, agentDir: string): Promise<void>;
+//# sourceMappingURL=agent.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../../src/internal/discovery/agent.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAiB,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAkBnE,OAAO,EAAE,KAAK,gBAAgB,EAAe,MAAM,cAAc,CAAC;AAelE,wBAAsB,SAAS,CAC7B,GAAG,EAAE,gBAAgB,EACrB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GACzC,OAAO,CAAC,aAAa,CAAC,CAyNxB;AAqDD,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,gBAAgB,EACrB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CA4Cf"}

package/dist/internal/discovery/agent.js

@@ -0,0 +1,306 @@
+/**
+ * Compile one `agent/` directory (and its subagents) into a {@link ResolvedAgent}.
+ */
+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 { DEFAULT_MODEL } from "../../types.js";
+import { builtinTools } from "../builtin-tools/index.js";
+import { withIdentityPreamble } from "../workspace.js";
+import { isValidModelSetting, loadAgentConfig, resolveAgentCwd, resolveArchitecture, resolveConcurrency, resolveHosting, resolveLocalCwd, runtimeArchitectureCompatibilityError, } from "./agent-config.js";
+import { loadConnections, loadHostConnections, resolveMcpConnectionsDir, } from "./connections.js";
+import { displayPath } from "./context.js";
+import { appendExtensions } from "./extensions.js";
+import { findModuleFile, isDirectory, sortedEntries } from "./fs.js";
+import { loadInstructions } from "./instructions.js";
+import { validateName } from "./names.js";
+import { checkGrokBotRuntimeLimitations, resolveRuntime, warnCloudRuntimeLimitations, } from "./runtime.js";
+import { loadSeedFiles } from "./seed-files.js";
+import { loadSkills } from "./skills.js";
+import { subagent } from "./subagent.js";
+import { appendBuiltinTools, loadTools } from "./tools.js";
+export function loadAgent(ctx, agentDir, options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c, _d;
+        var _e;
+        const config = yield loadAgentConfig(ctx, agentDir, options.isRoot);
+        const name = (_e = config === null || config === void 0 ? void 0 : config.name) !== null && _e !== void 0 ? _e : options.name;
+        const authoredInstructions = yield loadInstructions(ctx, agentDir, config, options.isRoot);
+        // Subagents run as Cursor SDK custom subagents (prompt + description +
+        // model); their other slots are inert today, so don't load them — just
+        // warn that they exist.
+        if (!options.isRoot) {
+            yield warnUnsupportedSubagentSlots(ctx, agentDir);
+            if ((config === null || config === void 0 ? void 0 : config.builtinTools) !== undefined) {
+                ctx.diagnostics.push({
+                    severity: "warning",
+                    path: displayPath(ctx, join(agentDir, "agent.ts")),
+                    message: "builtinTools is not supported on subagents; ignoring.",
+                });
+            }
+            if ((config === null || config === void 0 ? void 0 : config.tools) !== undefined) {
+                ctx.diagnostics.push({
+                    severity: "warning",
+                    path: displayPath(ctx, join(agentDir, "agent.ts")),
+                    message: "tools is not supported on subagents (they keep the harness task-tool toolset); ignoring.",
+                });
+            }
+            if ((config === null || config === void 0 ? void 0 : config.architecture) !== undefined) {
+                ctx.diagnostics.push({
+                    severity: "warning",
+                    path: displayPath(ctx, join(agentDir, "agent.ts")),
+                    message: "architecture is not supported on subagents; ignoring.",
+                });
+            }
+            const artifactsPath = yield findModuleFile(agentDir, "artifacts");
+            if (artifactsPath !== undefined) {
+                ctx.diagnostics.push({
+                    severity: "warning",
+                    path: displayPath(ctx, artifactsPath),
+                    message: "artifacts are not supported on subagents; ignoring.",
+                });
+            }
+            return subagent(name, {
+                description: config === null || config === void 0 ? void 0 : config.description,
+                model: config === null || config === void 0 ? void 0 : config.model,
+                prompt: authoredInstructions,
+            });
+        }
+        // Root agents without authored instructions stay undefined (diagnostic
+        // already recorded).
+        const instructions = authoredInstructions === undefined
+            ? undefined
+            : withIdentityPreamble(name, authoredInstructions);
+        const tools = yield loadTools(ctx, join(agentDir, "tools"));
+        const skills = yield loadSkills(ctx, join(agentDir, "skills"));
+        const connections = yield loadConnections(ctx, yield resolveMcpConnectionsDir(ctx, agentDir));
+        const subagents = yield loadSubagents(ctx, join(agentDir, "subagents"));
+        const extensions = yield appendExtensions(ctx, join(agentDir, "extensions"), {
+            tools,
+            skills,
+            connections,
+            subagents,
+        });
+        const hostConnections = yield loadHostConnections(ctx, agentDir, connections);
+        const seedFiles = yield loadSeedFiles(ctx, agentDir);
+        const runtime = resolveRuntime(ctx, agentDir, config === null || config === void 0 ? void 0 : config.runtime);
+        // Keep authored `cloud` even when default runtime is local — per-session
+        // `send({ cloud })` merges it under cloudOverride for handoff sessions.
+        const cloud = config === null || config === void 0 ? void 0 : config.cloud;
+        const localWorkspaceDir = resolveAgentCwd(ctx, (_a = config === null || config === void 0 ? void 0 : config.local) === null || _a === void 0 ? void 0 : _a.workspaceDir);
+        const localCwd = yield resolveLocalCwd(ctx, (_b = config === null || config === void 0 ? void 0 : config.local) === null || _b === void 0 ? void 0 : _b.cwd, (_c = config === null || config === void 0 ? void 0 : config.local) === null || _c === void 0 ? void 0 : _c.workspaceDir);
+        const localSandbox = ((_d = config === null || config === void 0 ? void 0 : config.local) === null || _d === void 0 ? void 0 : _d.sandbox) === true;
+        // Built-in tool allowlist (top-level `tools`). `[]` is meaningful (no
+        // native built-in tools), so presence is keyed on the field, not on
+        // emptiness. "mcp" is always granted alongside a configured allowlist:
+        // it is transport, not capability — this kit's own server tools ride the
+        // SDK custom-tool MCP path, so omitting it silently breaks
+        // `agent/tools/`, and what MCP actually exposes stays controlled by the
+        // second layer (authored tools, mcp-connections, the harness cwd's
+        // ambient config).
+        const authoredAllowlist = config === null || config === void 0 ? void 0 : config.tools;
+        const allowedTools = authoredAllowlist === undefined || authoredAllowlist.includes("mcp")
+            ? authoredAllowlist
+            : [...authoredAllowlist, "mcp"];
+        // The allowlist states runtime-agnostic intent, but only the local
+        // harness can enforce it (the Cursor SDK rejects tool restrictions on
+        // cloud agents, and the Grok Bot harness has its own fixed toolset) — a
+        // non-local agent that declares one must fail at serve start, never run
+        // unrestricted. (Hybrid per-send cloud sessions fail closed in the
+        // session engine.)
+        if (allowedTools !== undefined && runtime !== "local") {
+            ctx.diagnostics.push({
+                severity: "error",
+                path: displayPath(ctx, join(agentDir, "agent.ts")),
+                message: `tools cannot be enforced on runtime: "${runtime}". Remove \`tools\` or run the agent on the local runtime.`,
+            });
+        }
+        // Per-session connection features (defineConnection auth/advertiseTools)
+        // only run on local turns: advertised tools are in-process server tools,
+        // and per-session headers cannot reach a cloud VM's MCP config. A
+        // non-local agent that declares them must fail at serve start — never
+        // run without the connection's tools or identity. (Hybrid per-send
+        // cloud sessions fail closed in the session engine.)
+        const perSessionConnection = connections.find((connection) => connection.advertiseTools === true || connection.auth !== undefined);
+        if (perSessionConnection !== undefined && runtime !== "local") {
+            ctx.diagnostics.push({
+                severity: "error",
+                path: displayPath(ctx, join(agentDir, "agent.ts")),
+                message: `MCP connection "${perSessionConnection.name}" uses advertiseTools/auth, which only run on runtime: "local". Remove them or run the agent on the local runtime.`,
+            });
+        }
+        // `execution: "agent"` tool scripts run through the shell tool. Shell is
+        // a real capability, so it is never injected — but an allowlist that
+        // strands authored scripts deserves a loud diagnostic, not silence.
+        if (allowedTools !== undefined &&
+            !allowedTools.includes("shell") &&
+            tools.some((tool) => tool.execution === "agent")) {
+            ctx.diagnostics.push({
+                severity: "warning",
+                path: displayPath(ctx, join(agentDir, "agent.ts")),
+                message: '`tools` omits "shell" but this agent has execution: "agent" tools, which run as shell scripts; the model will not be able to run them.',
+            });
+        }
+        if (localCwd !== undefined && localWorkspaceDir !== undefined) {
+            ctx.diagnostics.push({
+                severity: "warning",
+                path: displayPath(ctx, join(agentDir, "agent.ts")),
+                message: "local.workspaceDir pins every session to one directory, so local.cwd is unused. Drop one of them.",
+            });
+        }
+        const local = localCwd === undefined && localWorkspaceDir === undefined && !localSandbox
+            ? undefined
+            : {
+                cwd: localCwd,
+                workspaceDir: localWorkspaceDir,
+                sandbox: localSandbox,
+            };
+        const hosting = resolveHosting(ctx, agentDir, config === null || config === void 0 ? void 0 : config.hosting);
+        const concurrency = resolveConcurrency(ctx, agentDir, config === null || config === void 0 ? void 0 : config.concurrency);
+        const architecture = resolveArchitecture(ctx, agentDir, config === null || config === void 0 ? void 0 : config.architecture);
+        const runtimeArchitectureError = runtimeArchitectureCompatibilityError({
+            runtime,
+            architecture,
+        });
+        if (runtimeArchitectureError !== undefined) {
+            ctx.diagnostics.push({
+                severity: "error",
+                path: displayPath(ctx, join(agentDir, "agent.ts")),
+                message: runtimeArchitectureError,
+            });
+        }
+        if (runtime === "cloud") {
+            warnCloudRuntimeLimitations(ctx, agentDir, {
+                agentTools: tools.filter((tool) => tool.execution === "agent").length,
+                skills: skills.length,
+                seedFiles: seedFiles.length,
+                hasCloudOptions: cloud !== undefined,
+            });
+        }
+        appendBuiltinTools(ctx, agentDir, tools, config === null || config === void 0 ? void 0 : config.builtinTools);
+        // After appendBuiltinTools so opted-in built-ins (server-executed) count.
+        if (runtime === "grokbot") {
+            checkGrokBotRuntimeLimitations(ctx, agentDir, {
+                serverTools: tools.filter((tool) => tool.execution === "server").length,
+                agentTools: tools.filter((tool) => tool.execution === "agent").length,
+                skills: skills.length,
+                seedFiles: seedFiles.length,
+                connections: connections.length + hostConnections.length,
+                subagents: subagents.length,
+                hasCloudOptions: cloud !== undefined,
+                hasLocalSandbox: localSandbox,
+            });
+        }
+        return Object.assign(Object.assign(Object.assign(Object.assign({ name, description: config === null || config === void 0 ? void 0 : config.description, 
+            // Root agents always get a concrete model: authored value or DEFAULT_MODEL.
+            model: isValidModelSetting(config === null || config === void 0 ? void 0 : config.model) ? config.model : DEFAULT_MODEL, instructions,
+            runtime,
+            cloud,
+            local }, (allowedTools === undefined ? {} : { allowedTools })), { hosting,
+            concurrency }), (architecture === undefined ? {} : { architecture })), { tools,
+            skills,
+            extensions,
+            connections,
+            hostConnections,
+            subagents,
+            seedFiles });
+    });
+}
+function loadSubagents(ctx, subagentsDir) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (!(yield isDirectory(subagentsDir))) {
+            return [];
+        }
+        const subagents = [];
+        for (const entry of yield sortedEntries(subagentsDir)) {
+            if (!entry.isDirectory()) {
+                continue;
+            }
+            const subagentDir = join(subagentsDir, entry.name);
+            if (!validateName(ctx, "subagent", entry.name, subagentDir)) {
+                continue;
+            }
+            subagents.push(yield loadAgent(ctx, subagentDir, { name: entry.name, isRoot: false }));
+        }
+        return subagents;
+    });
+}
+function warnUnsupportedSubagentSlots(ctx, subagentDir) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const unsupported = [
+            ["tools", "tools"],
+            ["skills", "skills"],
+            ["extensions", "extensions"],
+            ["mcp-connections", "MCP connections"],
+            ["host-connections", "host MCP connections"],
+            ["connections", "MCP connections"],
+            ["subagents", "nested subagents"],
+            ["channels", "channels"],
+            ["schedules", "schedules"],
+            ["hooks", "hooks"],
+            ["sandbox", "sandbox files"],
+        ];
+        for (const [slot, label] of unsupported) {
+            if (yield isDirectory(join(subagentDir, slot))) {
+                ctx.diagnostics.push({
+                    severity: "warning",
+                    path: displayPath(ctx, join(subagentDir, slot)),
+                    message: `Subagent ${label} are not supported on the Cursor harness yet; the subagent runs with the parent's execution surface. Ignoring.`,
+                });
+            }
+        }
+    });
+}
+export function warnUnknownSlots(ctx, agentDir) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const known = new Set([
+            "agent",
+            "instructions",
+            "tools",
+            "skills",
+            "extensions",
+            "mcp-connections",
+            "host-connections",
+            // Legacy slot name; resolveMcpConnectionsDir warns and still loads it.
+            "connections",
+            "subagents",
+            "channels",
+            "schedules",
+            "hooks",
+            "ab",
+            "sandbox",
+            "lib",
+            // Vite playground custom tool chips (agent/playground/tools).
+            "playground",
+        ]);
+        for (const entry of yield sortedEntries(agentDir)) {
+            if (!entry.isDirectory() || entry.name.startsWith(".")) {
+                continue;
+            }
+            if (entry.name === "node_modules" || known.has(entry.name)) {
+                continue;
+            }
+            // Footgun: evals live at project-root `evals/`, not under `agent/`.
+            if (entry.name === "evals") {
+                ctx.diagnostics.push({
+                    severity: "warning",
+                    path: displayPath(ctx, join(agentDir, entry.name)),
+                    message: 'Directory "evals" under agent/ is ignored — put defineEval files at project-root evals/ instead.',
+                });
+                continue;
+            }
+            ctx.diagnostics.push({
+                severity: "warning",
+                path: displayPath(ctx, join(agentDir, entry.name)),
+                message: `Unrecognized directory "${entry.name}" under agent/ (not an authored slot; use lib/ for shared code).`,
+            });
+        }
+    });
+}

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

@@ -0,0 +1,10 @@
+/**
+ * `agent/channels/*.ts`: HTTP surfaces beyond the session API.
+ */
+import type { DiscoveredChannel, HttpChannelDefinition } from "../../types.js";
+import { type DiscoveryContext } from "./context.js";
+export declare function loadChannels(ctx: DiscoveryContext, channelsDir: string): Promise<{
+    channels: DiscoveredChannel[];
+    httpChannelDefinition: HttpChannelDefinition | undefined;
+}>;
+//# sourceMappingURL=channels.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"channels.d.ts","sourceRoot":"","sources":["../../../src/internal/discovery/channels.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAEV,iBAAiB,EACjB,qBAAqB,EACtB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,KAAK,gBAAgB,EAA6B,MAAM,cAAc,CAAC;AAIhF,wBAAsB,YAAY,CAChC,GAAG,EAAE,gBAAgB,EACrB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC;IACT,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,qBAAqB,EAAE,qBAAqB,GAAG,SAAS,CAAC;CAC1D,CAAC,CAgFD"}