@cursor/july 0.1.1 → 0.1.2

package/dist/internal/deploy-client.js

@@ -0,0 +1,375 @@
+/**
+ * Thin client for the Agent Serve deployment management API
+ * (`/internal/agent-serve/deployments` on the Cursor backend). Pure
+ * request/response + error mapping — no console I/O, no polling loops;
+ * rendering lives in `cli-deploy.ts`.
+ *
+ * Auth is the user API key sent directly as the bearer (the routes are
+ * `wrapUserApiRoute` on the backend); there is no token exchange here.
+ * The endpoints are gated on the `agent_serve_mvp` Statsig gate and 404
+ * when it is off — the error mapping says so instead of "not found".
+ */
+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 { z } from "zod";
+import { MAX_SECRET_VALUE_BYTES, MAX_SECRETS, validateEgressDomain, validateSettableSecretName, } from "./hosting.js";
+export const TERMINAL_DEPLOY_STATUSES = new Set([
+    "running",
+    "degraded",
+    "failed",
+    "stopped",
+]);
+const SLUG_PATTERN = /^[a-z0-9_-]{1,64}$/;
+/** Returns a human error message, or undefined when the slug is valid. */
+export function validateDeploymentSlug(slug) {
+    if (SLUG_PATTERN.test(slug)) {
+        return undefined;
+    }
+    return `Invalid slug ${JSON.stringify(slug)}: use lowercase letters, digits, '-' or '_' (max 64 chars)`;
+}
+/** Derive a valid slug from a directory name, or undefined if impossible. */
+export function slugFromDirectoryName(name) {
+    const slug = name
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 64);
+    return SLUG_PATTERN.test(slug) ? slug : undefined;
+}
+export class DeployApiError extends Error {
+    constructor(message, status, 
+    /** Seconds to wait before retrying (from `Retry-After` on 429s). */
+    retryAfterSeconds) {
+        super(message);
+        this.status = status;
+        this.retryAfterSeconds = retryAfterSeconds;
+        this.name = "DeployApiError";
+    }
+}
+// All response schemas are `.passthrough()`: the backend keeps growing the
+// deployment payload (serviceAccountId, egressAllowedDomains, secret
+// metadata, ...) and unknown fields must flow through untouched — both so
+// parsing never breaks on a newer backend and so `--json` output stays
+// faithful to the API instead of silently dropping fields.
+const deployAcceptedSchema = z
+    .object({
+    id: z.number(),
+    slug: z.string(),
+    teamId: z.number(),
+    status: z.string(),
+    generation: z.number(),
+    deploymentKind: z.string(),
+    engineAlias: z.string(),
+    aliasToken: z.string().optional(),
+})
+    .passthrough();
+const deploymentSchema = z.object({
+    id: z.number(),
+    slug: z.string(),
+    teamId: z.number(),
+    deploymentKind: z.string(),
+    gitRepoUrl: z.string().nullable().optional(),
+    gitRef: z.string().optional(),
+    agentPath: z.string().optional(),
+    desiredState: z.string().optional(),
+    status: z.enum([
+        "pending",
+        "deploying",
+        "running",
+        "degraded",
+        "failed",
+        "stopping",
+        "stopped",
+    ]),
+    generation: z.number(),
+    observedGeneration: z.number().nullable().optional(),
+    engineGeneration: z.number().nullable().optional(),
+    publicId: z.string().optional(),
+    engineUrl: z.string().nullable().optional(),
+    lastError: z.string().nullable().optional(),
+    engineAlias: z.string(),
+    desiredUpdatedAt: z.string().optional(),
+    lastReconciledAt: z.string().nullable().optional(),
+    cursorEventRepos: z.array(z.string()).optional(),
+    egressAllowedDomains: z.array(z.string()).optional(),
+    // Null on legacy rows that predate service-account-backed deploys.
+    serviceAccountId: z.number().nullable().optional(),
+    podCredentialMaskedKey: z.string().nullable().optional(),
+    secretNames: z.array(z.string()).optional(),
+});
+const deploymentListItemSchema = deploymentSchema.passthrough();
+const deploymentDetailSchema = deploymentSchema
+    .extend({
+    engineAccess: z
+        .object({
+        url: z.string(),
+        headers: z.record(z.string()),
+        expiresAt: z.string(),
+    })
+        .nullable()
+        .optional(),
+})
+    .passthrough();
+const listResponseSchema = z.object({
+    deployments: z.array(deploymentListItemSchema),
+});
+const stopAcceptedSchema = z
+    .object({
+    id: z.number(),
+    status: z.string(),
+})
+    .passthrough();
+const rotateResponseSchema = z
+    .object({
+    aliasToken: z.string().min(1),
+})
+    .passthrough();
+const rotatePodCredentialResponseSchema = z
+    .object({
+    podCredentialMaskedKey: z.string().min(1),
+})
+    .passthrough();
+const setSecretsResponseSchema = z
+    .object({
+    secretNames: z.array(z.string()),
+})
+    .passthrough();
+const listSecretsResponseSchema = z
+    .object({
+    secrets: z.array(z.object({ name: z.string(), createdAt: z.string() }).passthrough()),
+})
+    .passthrough();
+export class AgentServeDeployClient {
+    constructor(options) {
+        var _a;
+        this.backendUrl = options.backendUrl.endsWith("/")
+            ? options.backendUrl.slice(0, -1)
+            : options.backendUrl;
+        this.apiKey = options.apiKey;
+        this.fetchImpl = (_a = options.fetchImpl) !== null && _a !== void 0 ? _a : fetch;
+    }
+    /** Create or redeploy; 202 means accepted, not running (poll status). */
+    deploy(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const slugError = validateDeploymentSlug(args.slug);
+            if (slugError !== undefined) {
+                throw new DeployApiError(slugError, 400);
+            }
+            for (const domain of (_a = args.source.egressAllowedDomains) !== null && _a !== void 0 ? _a : []) {
+                const domainError = validateEgressDomain(domain);
+                if (domainError !== undefined) {
+                    throw new DeployApiError(domainError, 400);
+                }
+            }
+            // Only the git-ref member exists today; a future artifact member would
+            // upload the build first and post a different body from this branch.
+            const body = Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ teamId: args.teamId, slug: args.slug }, (args.source.gitRepoUrl === undefined
+                ? {}
+                : { gitRepoUrl: args.source.gitRepoUrl })), (args.source.gitRef === undefined
+                ? {}
+                : { gitRef: args.source.gitRef })), (args.source.agentPath === undefined
+                ? {}
+                : { agentPath: args.source.agentPath })), (args.source.cursorEventRepos === undefined
+                ? {}
+                : { cursorEventRepos: args.source.cursorEventRepos })), (args.source.egressAllowedDomains === undefined
+                ? {}
+                : { egressAllowedDomains: args.source.egressAllowedDomains }));
+            const raw = yield this.request({
+                method: "POST",
+                path: "/internal/agent-serve/deployments",
+                body,
+                context: { verb: "deploy", slug: args.slug },
+            });
+            return deployAcceptedSchema.parse(raw);
+        });
+    }
+    listDeployments(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const raw = yield this.request({
+                method: "GET",
+                path: `/internal/agent-serve/deployments?teamId=${args.teamId}`,
+                context: { verb: "list deployments" },
+            });
+            return listResponseSchema.parse(raw).deployments;
+        });
+    }
+    getDeployment(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const raw = yield this.request({
+                method: "GET",
+                path: `/internal/agent-serve/deployments/${encodeURIComponent(args.slug)}?teamId=${args.teamId}`,
+                context: { verb: "get deployment", slug: args.slug },
+            });
+            return deploymentDetailSchema.parse(raw);
+        });
+    }
+    stopDeployment(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const raw = yield this.request({
+                method: "POST",
+                path: `/internal/agent-serve/deployments/${encodeURIComponent(args.slug)}/stop?teamId=${args.teamId}`,
+                context: { verb: "stop", slug: args.slug },
+            });
+            return stopAcceptedSchema.parse(raw);
+        });
+    }
+    /** Returns the new alias token exactly once; the old one dies now. */
+    rotateAliasToken(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const raw = yield this.request({
+                method: "POST",
+                path: `/internal/agent-serve/deployments/${encodeURIComponent(args.slug)}/rotate-alias-token?teamId=${args.teamId}`,
+                context: { verb: "rotate alias token", slug: args.slug },
+            });
+            return rotateResponseSchema.parse(raw).aliasToken;
+        });
+    }
+    /**
+     * Upsert secrets by name (unlisted names stay untouched). Returns the
+     * post-write union of secret names, sorted. Validates names and value
+     * sizes client-side with the backend's grammar before any network call.
+     */
+    setSecrets(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            for (const { name, value } of args.secrets) {
+                const nameError = validateSettableSecretName(name);
+                if (nameError !== undefined) {
+                    throw new DeployApiError(nameError, 400);
+                }
+                if (Buffer.byteLength(value, "utf8") > MAX_SECRET_VALUE_BYTES) {
+                    throw new DeployApiError(`The value for ${name} is too large (max ${MAX_SECRET_VALUE_BYTES} bytes).`, 400);
+                }
+            }
+            if (args.secrets.length > MAX_SECRETS) {
+                throw new DeployApiError(`Too many secrets in one request (${args.secrets.length}); deployments hold at most ${MAX_SECRETS}.`, 400);
+            }
+            const raw = yield this.request({
+                method: "PUT",
+                path: `/internal/agent-serve/deployments/${encodeURIComponent(args.slug)}/secrets`,
+                body: { teamId: args.teamId, secrets: args.secrets },
+                context: { verb: "set secrets", slug: args.slug },
+            });
+            return setSecretsResponseSchema.parse(raw).secretNames;
+        });
+    }
+    /** Secret names + creation times; values are never returned. */
+    listSecrets(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const raw = yield this.request({
+                method: "GET",
+                path: `/internal/agent-serve/deployments/${encodeURIComponent(args.slug)}/secrets?teamId=${args.teamId}`,
+                context: { verb: "list secrets", slug: args.slug },
+            });
+            return listSecretsResponseSchema.parse(raw).secrets;
+        });
+    }
+    /** Remove one secret by name; 404 when it is not set. */
+    deleteSecret(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const nameError = validateSettableSecretName(args.name);
+            if (nameError !== undefined) {
+                throw new DeployApiError(nameError, 400);
+            }
+            yield this.request({
+                method: "DELETE",
+                path: `/internal/agent-serve/deployments/${encodeURIComponent(args.slug)}/secrets/${encodeURIComponent(args.name)}?teamId=${args.teamId}`,
+                context: { verb: "unset secret", slug: args.slug },
+            });
+        });
+    }
+    /**
+     * Rotate the deployment's pod credential. Returns the masked new key —
+     * the raw key is injected into the pod on the next deploy, never
+     * returned to clients.
+     */
+    rotatePodCredential(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const raw = yield this.request({
+                method: "POST",
+                path: `/internal/agent-serve/deployments/${encodeURIComponent(args.slug)}/rotate-pod-credential?teamId=${args.teamId}`,
+                context: { verb: "rotate pod credential", slug: args.slug },
+            });
+            return rotatePodCredentialResponseSchema.parse(raw).podCredentialMaskedKey;
+        });
+    }
+    /** Full URL of the stable engine alias for a deployment. */
+    aliasUrl(engineAlias) {
+        return `${this.backendUrl}${engineAlias}`;
+    }
+    request(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            let response;
+            try {
+                response = yield this.fetchImpl(`${this.backendUrl}${args.path}`, Object.assign(Object.assign({ method: args.method, headers: Object.assign({ accept: "application/json", authorization: `Bearer ${this.apiKey}` }, (args.body === undefined
+                        ? {}
+                        : { "content-type": "application/json" })) }, (args.body === undefined ? {} : { body: JSON.stringify(args.body) })), { signal: AbortSignal.timeout(60000) }));
+            }
+            catch (error) {
+                throw new DeployApiError(`Could not reach the Cursor backend at ${this.backendUrl}: ${error instanceof Error ? error.message : String(error)}`, 0);
+            }
+            const text = yield response.text();
+            if (!response.ok) {
+                throw mapErrorResponse(response, text, args.context);
+            }
+            try {
+                return JSON.parse(text);
+            }
+            catch (_a) {
+                throw new DeployApiError(`The Cursor backend returned a non-JSON response to ${args.context.verb}.`, response.status);
+            }
+        });
+    }
+}
+// ============================================================================
+// Error mapping (HTTP → actionable human messages)
+// ============================================================================
+function serverErrorText(bodyText) {
+    try {
+        const parsed = JSON.parse(bodyText);
+        if (typeof parsed.error === "string" && parsed.error !== "") {
+            return parsed.error;
+        }
+    }
+    catch (_a) {
+        // Non-JSON body — fall through.
+    }
+    return undefined;
+}
+function mapErrorResponse(response, bodyText, context) {
+    var _a;
+    const serverError = serverErrorText(bodyText);
+    const slugPart = context.slug === undefined ? "" : ` "${context.slug}"`;
+    switch (response.status) {
+        case 400:
+            return new DeployApiError(serverError !== null && serverError !== void 0 ? serverError : `The ${context.verb} request was rejected as invalid.`, 400);
+        case 401:
+            return new DeployApiError("The Cursor API key was rejected. Run `agentkit login` again or update CURSOR_API_KEY.", 401);
+        case 403:
+            return new DeployApiError(`${serverError !== null && serverError !== void 0 ? serverError : "Not authorized"} — deploying needs team-admin permission and the cloud-agent entitlement on that team.`, 403);
+        case 404:
+            return new DeployApiError(context.slug === undefined
+                ? `Not found — the agent_serve_mvp feature gate may not be enabled for your team.`
+                : `Deployment${slugPart} was not found — check the slug and --team, or the agent_serve_mvp feature gate may not be enabled for your team.`, 404);
+        case 409:
+            return new DeployApiError(`A concurrent deploy or stop is changing deployment${slugPart}; retry in a moment.`, 409);
+        case 429: {
+            const retryAfterHeader = response.headers.get("retry-after");
+            const retryAfterSeconds = retryAfterHeader !== null && /^\d+$/.test(retryAfterHeader)
+                ? Number(retryAfterHeader)
+                : undefined;
+            return new DeployApiError(`${serverError !== null && serverError !== void 0 ? serverError : "Rate limited"}${retryAfterSeconds === undefined
+                ? ""
+                : ` — retry in ${retryAfterSeconds}s`}`, 429, retryAfterSeconds);
+        }
+        default:
+            return new DeployApiError(`The ${context.verb} request failed (${response.status}): ${(_a = serverError !== null && serverError !== void 0 ? serverError : bodyText.slice(0, 300)) !== null && _a !== void 0 ? _a : "(empty body)"}`, response.status);
+    }
+}

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

@@ -1 +1 @@
-{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../src/internal/discovery.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAeH,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,gBAAgB,EAKrB,KAAK,UAAU,EAmBhB,MAAM,aAAa,CAAC;AAarB,MAAM,WAAW,uBAAuB;IACtC,sDAAsD;IACtD,YAAY,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC3E;AAmBD;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CASrE;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,YAAY,CAAA;CAAE,CAAC,CAAC,CAiCzD;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,uBAAuB,GAAG;IACjC,IAAI,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;CACtB,GACL,OAAO,CAAC,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,YAAY,CAAA;CAAE,CAAC,CAAC,CAgBzD;AAWD,iFAAiF;AACjF,eAAO,MAAM,cAAc,EAAE,GAAG,CAAC,MAAM,CAIrC,CAAC;AAEH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,YAAY,CAAC,CA4DvB;AAED,qEAAqE;AACrE,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAElE;AAED,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,UAAU,EAAE,GAAG,MAAM,CAOnE;AAwgBD;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAiB3E;AAujBD,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,gBAAgB,CA6HnE"}
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../src/internal/discovery.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAgBH,OAAO,EAGL,KAAK,YAAY,EACjB,KAAK,gBAAgB,EAKrB,KAAK,UAAU,EAmBhB,MAAM,aAAa,CAAC;AAmBrB,MAAM,WAAW,uBAAuB;IACtC,sDAAsD;IACtD,YAAY,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC3E;AAmBD;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CASrE;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,YAAY,CAAA;CAAE,CAAC,CAAC,CAiCzD;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,uBAAuB,GAAG;IACjC,IAAI,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;CACtB,GACL,OAAO,CAAC,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,YAAY,CAAA;CAAE,CAAC,CAAC,CAgBzD;AAWD,iFAAiF;AACjF,eAAO,MAAM,cAAc,EAAE,GAAG,CAAC,MAAM,CAIrC,CAAC;AAEH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,YAAY,CAAC,CA8DvB;AAED,qEAAqE;AACrE,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAElE;AAED,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,UAAU,EAAE,GAAG,MAAM,CAOnE;AA+jBD;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAiB3E;AAukBD,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,gBAAgB,CAkInE"}

package/dist/internal/discovery.js

@@ -35,6 +35,7 @@ import { registerAuthoredModuleLoaders } from "./authored-loaders.js";
 import { getDefinitionKind } from "./brand.js";
 import { isValidCron } from "./cron.js";
 import { parseFrontmatter } from "./frontmatter.js";
+import { isReservedSecretName, MAX_EGRESS_DOMAINS, validateEgressDomain, validateSecretName, } from "./hosting.js";
 import { toolInputJsonSchema } from "./json-schema.js";
 import { MCP_ENDPOINT_PATH, mcpEndpointToolNames } from "./mcp-endpoint.js";
 const MODULE_EXTENSIONS = new Set([".ts", ".mts", ".js", ".mjs"]);
@@ -176,14 +177,24 @@ export function loadAgentProject(dir_1) {
         const hooks = yield loadHooks(ctx, join(agentDir, "hooks"));
         const abs = yield loadABs(ctx, agentDir);
         const abConfig = yield loadABConfig(ctx, agentDir);
+        const storage = yield loadStorage(ctx, agentDir);
         if (agentDir !== rootDir) {
             yield warnUnknownSlots(ctx, agentDir);
         }
-        return Object.assign(Object.assign({ rootDir,
-            agentDir, name: agent.name, agent, httpChannel: httpChannelDefinition !== null && httpChannelDefinition !== void 0 ? httpChannelDefinition : httpChannel(), channels,
+        return {
+            rootDir,
+            agentDir,
+            name: agent.name,
+            agent,
+            httpChannel: httpChannelDefinition !== null && httpChannelDefinition !== void 0 ? httpChannelDefinition : httpChannel(),
+            channels,
             schedules,
             hooks,
-            abs }, (abConfig === undefined ? {} : { abConfig })), { diagnostics });
+            abs,
+            abConfig,
+            storage,
+            diagnostics,
+        };
     });
 }
 /** True when the project has diagnostics that must block serving. */
@@ -231,6 +242,7 @@ function loadAgent(ctx, agentDir, options) {
             : {
                 cwd: localCwd,
             };
+        const hosting = resolveHosting(ctx, agentDir, config === null || config === void 0 ? void 0 : config.hosting);
         if (runtime === "cloud") {
             warnCloudRuntimeLimitations(ctx, agentDir, {
                 serverTools: tools.filter((tool) => tool.execution === "server").length,
@@ -249,6 +261,7 @@ function loadAgent(ctx, agentDir, options) {
             runtime,
             cloud,
             local,
+            hosting,
             tools,
             skills,
             connections,
@@ -268,6 +281,46 @@ function resolveAgentCwd(ctx, authored) {
     }
     return isAbsolute(trimmed) ? trimmed : resolve(ctx.rootDir, trimmed);
 }
+/**
+ * Validate the authored `hosting` block against the same grammar the
+ * backend enforces on deploy. Violations are warning diagnostics (reported
+ * by `agentkit validate`), not hard failures: the backend stays
+ * authoritative and `agentkit deploy` re-checks before any network call.
+ */
+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-reserved (CURSOR_*) and injected automatically; it cannot be set with \`secrets set\`.`);
+        }
+    }
+    return Object.assign(Object.assign({}, (hosting.egressDomains === undefined
+        ? {}
+        : { egressDomains: [...hosting.egressDomains] })), (hosting.secretNames === undefined
+        ? {}
+        : { secretNames: [...hosting.secretNames] }));
+}
 function loadAgentConfig(ctx, agentDir, isRoot) {
     return __awaiter(this, void 0, void 0, function* () {
         const configPath = yield findModuleFile(agentDir, "agent");
@@ -1088,6 +1141,19 @@ function loadABConfig(ctx, agentDir) {
         }
     });
 }
+// ============================================================================
+// Storage (agent/storage.ts)
+// ============================================================================
+function loadStorage(ctx, agentDir) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const path = yield findModuleFile(agentDir, "storage");
+        if (path === undefined) {
+            return undefined;
+        }
+        const definition = yield importDefault(ctx, path, "storage");
+        return definition;
+    });
+}
 function resolveABName(definition, fallback) {
     if (typeof definition === "object" &&
         definition !== null &&
@@ -1161,7 +1227,7 @@ export function projectInfo(project) {
             url: "/v1/session/:sessionId/approvals/:callId",
         },
     ];
-    return Object.assign(Object.assign({ name: project.name, model: agent.model, runtime: agent.runtime, cloud: agent.cloud === undefined ? undefined : toPublicCloudInfo(agent.cloud), local: agent.local, mcp: { path: MCP_ENDPOINT_PATH, tools: mcpEndpointToolNames(project) }, instructions: agent.instructions === undefined
+    return Object.assign(Object.assign({ name: project.name, model: agent.model, runtime: agent.runtime, cloud: agent.cloud === undefined ? undefined : toPublicCloudInfo(agent.cloud), local: agent.local, hosting: agent.hosting, mcp: { path: MCP_ENDPOINT_PATH, tools: mcpEndpointToolNames(project) }, instructions: agent.instructions === undefined
             ? undefined
             : {
                 chars: agent.instructions.length,
@@ -1232,7 +1298,9 @@ export function projectInfo(project) {
                 durableSamples: ((_b = project.abConfig) === null || _b === void 0 ? void 0 : _b.persistSamples) !== undefined,
                 durableSnapshots: ((_c = project.abConfig) === null || _c === void 0 ? void 0 : _c.persistSnapshots) !== undefined,
             },
-        })), { diagnostics: project.diagnostics });
+        })), { storage: project.storage === undefined
+            ? undefined
+            : { name: project.storage.name }, diagnostics: project.diagnostics });
 }
 // ============================================================================
 // Shared helpers

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

@@ -1 +1 @@
-{"version":3,"file":"distribution.d.ts","sourceRoot":"","sources":["../../src/internal/distribution.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,qEAAqE;AACrE,eAAO,MAAM,YAAY,iBAAiB,CAAC;AAE3C,6EAA6E;AAC7E,eAAO,MAAM,mBAAmB,2BAA2B,CAAC;AAE5D;;;GAGG;AACH,eAAO,MAAM,qBAAqB,qBAAqB,CAAC;AAExD;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAA+B,CAAC;AAc/D;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,OAAO,CAGhD;AAED;;;GAGG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED,kEAAkE;AAClE,wBAAgB,cAAc,IAAI,MAAM,CAOvC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,EAAE,aAAa,CAC/C,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,CAczC,CAAC"}
+{"version":3,"file":"distribution.d.ts","sourceRoot":"","sources":["../../src/internal/distribution.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,qEAAqE;AACrE,eAAO,MAAM,YAAY,iBAAiB,CAAC;AAE3C,6EAA6E;AAC7E,eAAO,MAAM,mBAAmB,2BAA2B,CAAC;AAE5D;;;GAGG;AACH,eAAO,MAAM,qBAAqB,qBAAqB,CAAC;AAExD;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAA+B,CAAC;AAc/D;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,OAAO,CAGhD;AAED;;;GAGG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED,kEAAkE;AAClE,wBAAgB,cAAc,IAAI,MAAM,CAOvC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,EAAE,aAAa,CAC/C,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,CAezC,CAAC"}

package/dist/internal/distribution.js

@@ -79,4 +79,5 @@ export const AUTHORING_ENTRY_FILES = [
     ["hooks", "hooks.js"],
     ["evals", "evals.js"],
     ["ab", "ab.js"],
+    ["storage", "storage.js"],
 ];

package/dist/internal/eval-run-store.d.ts

@@ -6,7 +6,7 @@
  * Runs against the live mount's loopback URL so case sessions appear in
  * the playground session list.
  */
-import { type EvalRunSnapshot } from "../evals.js";
+import { type EvalRunPersistence, type EvalRunSnapshot } from "../evals.js";
 export type { EvalBatchStatus, EvalCaseRunStatus as EvalCaseStatus, EvalCaseSnapshot, EvalRunSnapshot, } from "../evals.js";
 export interface StartEvalRunInput {
     filterIds?: string[];
@@ -24,6 +24,11 @@ export type EvalListConfig = {
 export declare class EvalRunStore {
     private readonly projectRoot;
     private readonly logger;
+    /**
+     * Project-wide sink from `agent/storage.ts` (`defineStorage`),
+     * used when `evals.config.ts` sets no `persistRuns` of its own.
+     */
+    private readonly fallbackPersistence?;
     private readonly runs;
     private activeRunId;
     private hydratePromise;
@@ -32,7 +37,14 @@ export declare class EvalRunStore {
     private readonly persistChains;
     /** Filled after listen — e.g. `http://127.0.0.1:3000/weather-agent`. */
     loopbackUrl: string | undefined;
-    constructor(projectRoot: string, logger: (line: string) => void);
+    constructor(projectRoot: string, logger: (line: string) => void, 
+    /**
+     * Project-wide sink from `agent/storage.ts` (`defineStorage`),
+     * used when `evals.config.ts` sets no `persistRuns` of its own.
+     */
+    fallbackPersistence?: EvalRunPersistence | undefined);
+    /** `evals.config.ts` `persistRuns` wins; `defineStorage` is fallback. */
+    private resolvePersist;
     list(): Promise<{
         evals: Array<{
             id: string;
@@ -57,7 +69,14 @@ export declare class EvalRunStore {
     getActiveRunId(): string | undefined;
     start(input?: StartEvalRunInput): Promise<EvalRunSnapshot>;
     private sortedRuns;
-    private ensureHydrated;
+    /**
+     * Hydrate playground eval history from durable persistence
+     * (`evals.config.ts` `persistRuns`, else the `defineStorage`
+     * fallback). Called eagerly from the serve startup restore step —
+     * alongside session restore — and lazily as a safety net by every read.
+     * Idempotent; concurrent callers share one pass.
+     */
+    hydrate(): Promise<void>;
     private hydrateFromPersistence;
     private pruneOldRuns;
     /**

package/dist/internal/eval-run-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"eval-run-store.d.ts","sourceRoot":"","sources":["../../src/internal/eval-run-store.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,aAAa,CAAC;AASrB,YAAY,EACV,eAAe,EACf,iBAAiB,IAAI,cAAc,EACnC,gBAAgB,EAChB,eAAe,GAChB,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,iBAAiB;IAChC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,qDAAqD;IACrD,WAAW,EAAE,OAAO,CAAC;CACtB,CAAC;AAOF,qBAAa,YAAY;IAWrB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,MAAM;IAXzB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAsC;IAC3D,OAAO,CAAC,WAAW,CAAqB;IACxC,OAAO,CAAC,cAAc,CAA4B;IAClD,OAAO,CAAC,QAAQ,CAAS;IACzB,wFAAwF;IACxF,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAoC;IAClE,wEAAwE;IACxE,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAEhC,YACmB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,EAC7C;IAEE,IAAI,IAAI,OAAO,CAAC;QACpB,KAAK,EAAE,KAAK,CAAC;YACX,EAAE,EAAE,MAAM,CAAC;YACX,MAAM,EAAE,MAAM,CAAC;YACf,WAAW,CAAC,EAAE,MAAM,CAAC;YACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;SACjB,CAAC,CAAC;QACH,MAAM,EAAE,cAAc,CAAC;KACxB,CAAC,CAcD;IAEK,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CAG7D;IAED,+EAA+E;IACzE,QAAQ,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC,CAG3C;IAED;;;;OAIG;IACG,kBAAkB,IAAI,OAAO,CAAC;QAClC,IAAI,EAAE,eAAe,EAAE,CAAC;QACxB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC,CAOD;IAED,cAAc,IAAI,MAAM,GAAG,SAAS,CAEnC;IAEK,KAAK,CAAC,KAAK,GAAE,iBAAsB,GAAG,OAAO,CAAC,eAAe,CAAC,CA4DnE;IAED,OAAO,CAAC,UAAU;YAMJ,cAAc;YAUd,sBAAsB;YAkDtB,YAAY;IAe1B;;;;OAIG;IACH,OAAO,CAAC,cAAc;YAgBR,WAAW;YAcX,aAAa;YAiBb,OAAO;IAmGrB,OAAO,CAAC,eAAe;CAqCxB;AAoDD,qBAAa,oBAAqB,SAAQ,KAAK;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM;IAAxC,YAAqB,WAAW,EAAE,MAAM,EAGvC;CACF;AAED,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,cAGC;CACF"}
+{"version":3,"file":"eval-run-store.d.ts","sourceRoot":"","sources":["../../src/internal/eval-run-store.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAGL,KAAK,kBAAkB,EACvB,KAAK,eAAe,EAErB,MAAM,aAAa,CAAC;AASrB,YAAY,EACV,eAAe,EACf,iBAAiB,IAAI,cAAc,EACnC,gBAAgB,EAChB,eAAe,GAChB,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,iBAAiB;IAChC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,qDAAqD;IACrD,WAAW,EAAE,OAAO,CAAC;CACtB,CAAC;AAOF,qBAAa,YAAY;IAWrB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAC;IAhBvC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAsC;IAC3D,OAAO,CAAC,WAAW,CAAqB;IACxC,OAAO,CAAC,cAAc,CAA4B;IAClD,OAAO,CAAC,QAAQ,CAAS;IACzB,wFAAwF;IACxF,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAoC;IAClE,wEAAwE;IACxE,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAEhC,YACmB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI;IAC/C;;;OAGG;IACc,mBAAmB,CAAC,EAAE,kBAAkB,YAAA,EACvD;IAEJ,yEAAyE;IACzE,OAAO,CAAC,cAAc;IAMhB,IAAI,IAAI,OAAO,CAAC;QACpB,KAAK,EAAE,KAAK,CAAC;YACX,EAAE,EAAE,MAAM,CAAC;YACX,MAAM,EAAE,MAAM,CAAC;YACf,WAAW,CAAC,EAAE,MAAM,CAAC;YACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;SACjB,CAAC,CAAC;QACH,MAAM,EAAE,cAAc,CAAC;KACxB,CAAC,CAiBD;IAEK,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CAG7D;IAED,+EAA+E;IACzE,QAAQ,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC,CAG3C;IAED;;;;OAIG;IACG,kBAAkB,IAAI,OAAO,CAAC;QAClC,IAAI,EAAE,eAAe,EAAE,CAAC;QACxB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC,CAOD;IAED,cAAc,IAAI,MAAM,GAAG,SAAS,CAEnC;IAEK,KAAK,CAAC,KAAK,GAAE,iBAAsB,GAAG,OAAO,CAAC,eAAe,CAAC,CA+DnE;IAED,OAAO,CAAC,UAAU;IAMlB;;;;;;OAMG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAQ7B;YAEa,sBAAsB;YAkDtB,YAAY;IAe1B;;;;OAIG;IACH,OAAO,CAAC,cAAc;YAgBR,WAAW;YAcX,aAAa;YAiBb,OAAO;IAmGrB,OAAO,CAAC,eAAe;CAqCxB;AAwDD,qBAAa,oBAAqB,SAAQ,KAAK;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM;IAAxC,YAAqB,WAAW,EAAE,MAAM,EAGvC;CACF;AAED,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,cAGC;CACF"}