@cursor/july 0.1.1 → 0.1.3

package/dist/internal/deploy-client.js

@@ -0,0 +1,395 @@
+/**
+ * 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",
+    ]),
+    progress: z
+        .enum([
+        "queued",
+        "preparing",
+        "building",
+        "finalizing",
+        "running",
+        "failed",
+        "stopping",
+        "stopped",
+        "degraded",
+    ])
+        .optional(),
+    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(),
+    // String ids (`sa_…`) in prod; older mocks/fixtures used numbers. Null on
+    // legacy rows that predate service-account-backed deploys.
+    serviceAccountId: z.union([z.string(), 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: {
+            // Fastify's route-not-found envelope means we hit the wrong host
+            // (api2 vs api.cursor.com), not a missing deployment / closed gate.
+            if (/Route \S+ not found/i.test(bodyText)) {
+                return new DeployApiError(`Agent Serve deploy API not found on this host — use the default api.cursor.com (unset CURSOR_API_BASE_URL), or point CURSOR_API_BASE_URL at a backend that mounts /internal/agent-serve/*.`, 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/deploy-source.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Infer `agentkit deploy` git source fields from a local checkout.
+ *
+ * From an agent directory inside a git repo with an `origin` remote, the
+ * CLI can fill `--repo` / `--ref` / `--path` so `agentkit deploy` (no
+ * flags) is enough. Explicit flags always win.
+ */
+/** Injectable git runner (cwd + args → stdout, or undefined on failure). */
+export type GitRunner = (args: readonly string[], cwd: string) => Promise<string | undefined>;
+export interface InferredDeploySource {
+    gitRepoUrl?: string;
+    gitRef?: string;
+    /** Agent directory relative to the repo root (posix). Omitted at root. */
+    agentPath?: string;
+}
+/**
+ * Normalize a git remote URL to the https form the control plane accepts
+ * (`https://host/owner/repo`, no `.git` suffix). Returns undefined for
+ * unrecognized shapes.
+ */
+export declare function httpsGitRepoUrlFromRemote(remote: string): string | undefined;
+/**
+ * Path of `dir` relative to `gitRoot`, using `/` separators. Undefined when
+ * `dir` is outside the root; omitted (undefined) when `dir` *is* the root
+ * so the control plane treats the agent as living at the repo root.
+ */
+export declare function agentPathRelativeToGitRoot(dir: string, gitRoot: string): string | undefined;
+/**
+ * Probe the git checkout containing `dir` for deploy source fields.
+ * Missing pieces stay undefined (static deploy / server defaults).
+ */
+export declare function inferDeployGitSource(dir: string, options?: {
+    git?: GitRunner;
+}): Promise<InferredDeploySource>;
+//# sourceMappingURL=deploy-source.d.ts.map

package/dist/internal/deploy-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deploy-source.d.ts","sourceRoot":"","sources":["../../src/internal/deploy-source.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAQH,4EAA4E;AAC5E,MAAM,MAAM,SAAS,GAAG,CACtB,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,GAAG,EAAE,MAAM,KACR,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;AAEjC,MAAM,WAAW,oBAAoB;IACnC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAYD;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CA6B5E;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,GACd,MAAM,GAAG,SAAS,CAYpB;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,SAAS,CAAA;CAAE,GAC5B,OAAO,CAAC,oBAAoB,CAAC,CA8B/B"}

package/dist/internal/deploy-source.js

@@ -0,0 +1,118 @@
+/**
+ * Infer `agentkit deploy` git source fields from a local checkout.
+ *
+ * From an agent directory inside a git repo with an `origin` remote, the
+ * CLI can fill `--repo` / `--ref` / `--path` so `agentkit deploy` (no
+ * flags) is enough. Explicit flags always win.
+ */
+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 { execFile } from "node:child_process";
+import { relative, resolve, sep } from "node:path";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+const defaultGitRunner = (args, cwd) => __awaiter(void 0, void 0, void 0, function* () {
+    try {
+        const { stdout } = yield execFileAsync("git", [...args], { cwd });
+        const trimmed = stdout.trim();
+        return trimmed === "" ? undefined : trimmed;
+    }
+    catch (_a) {
+        return undefined;
+    }
+});
+/**
+ * Normalize a git remote URL to the https form the control plane accepts
+ * (`https://host/owner/repo`, no `.git` suffix). Returns undefined for
+ * unrecognized shapes.
+ */
+export function httpsGitRepoUrlFromRemote(remote) {
+    let url = remote.trim();
+    if (url === "") {
+        return undefined;
+    }
+    if (url.startsWith("git@")) {
+        // git@host:owner/repo.git → https://host/owner/repo.git
+        url = `https://${url.slice("git@".length).replace(":", "/")}`;
+    }
+    else if (url.startsWith("ssh://git@")) {
+        url = `https://${url.slice("ssh://git@".length)}`;
+    }
+    else if (!/^https?:\/\//i.test(url)) {
+        return undefined;
+    }
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch (_a) {
+        return undefined;
+    }
+    const path = parsed.pathname
+        .replace(/\.git$/i, "")
+        .replace(/\/+$/, "")
+        .replace(/^\/+/, "");
+    if (path === "" || !path.includes("/")) {
+        return undefined;
+    }
+    // Use hostname (not host) so ssh://git@github.com:22/… does not keep :22.
+    return `https://${parsed.hostname}/${path}`;
+}
+/**
+ * Path of `dir` relative to `gitRoot`, using `/` separators. Undefined when
+ * `dir` is outside the root; omitted (undefined) when `dir` *is* the root
+ * so the control plane treats the agent as living at the repo root.
+ */
+export function agentPathRelativeToGitRoot(dir, gitRoot) {
+    const absDir = resolve(dir);
+    const absRoot = resolve(gitRoot);
+    const rel = relative(absRoot, absDir);
+    if (rel === "") {
+        return undefined;
+    }
+    // Outside the repo (or a Windows drive mismatch) → cannot infer.
+    if (rel.startsWith("..") || rel.split(sep).includes("..")) {
+        return undefined;
+    }
+    return rel.split(sep).join("/");
+}
+/**
+ * Probe the git checkout containing `dir` for deploy source fields.
+ * Missing pieces stay undefined (static deploy / server defaults).
+ */
+export function inferDeployGitSource(dir, options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const git = (_a = options === null || options === void 0 ? void 0 : options.git) !== null && _a !== void 0 ? _a : defaultGitRunner;
+        const absDir = resolve(dir);
+        const gitRoot = yield git(["rev-parse", "--show-toplevel"], absDir);
+        if (gitRoot === undefined) {
+            return {};
+        }
+        const remote = yield git(["remote", "get-url", "origin"], gitRoot);
+        const gitRepoUrl = remote === undefined ? undefined : httpsGitRepoUrlFromRemote(remote);
+        const branch = yield git(["rev-parse", "--abbrev-ref", "HEAD"], gitRoot);
+        let gitRef;
+        if (branch !== undefined && branch !== "HEAD") {
+            gitRef = branch;
+        }
+        else {
+            // Detached HEAD — pin the exact commit so the control plane still
+            // has something concrete to build.
+            gitRef = yield git(["rev-parse", "HEAD"], gitRoot);
+        }
+        const agentPath = agentPathRelativeToGitRoot(absDir, gitRoot);
+        return {
+            gitRepoUrl,
+            gitRef,
+            agentPath,
+        };
+    });
+}

package/dist/internal/discovery.d.ts

@@ -16,6 +16,17 @@ export interface LoadAgentProjectOptions {
  * inside it.
  */
 export declare function isAgentProjectDir(dir: string): Promise<boolean>;
+/** One immediate child agent directory under a multi-agent parent. */
+export interface ChildAgentDir {
+    slug: string;
+    dir: string;
+}
+/**
+ * List agent projects directly under `rootDir` (one level deep) without
+ * loading them. Empty when the path is missing or has no child agents.
+ * Slug rules match {@link loadAgentProjects} / multi-agent serve.
+ */
+export declare function listChildAgentDirs(rootDir: string): Promise<ChildAgentDir[]>;
 /**
  * Discover the agent projects directly under `rootDir` (one level deep):
  * each immediate child directory that is itself an agent project becomes a

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;AAoBrB,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,sEAAsE;AACtE,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,aAAa,EAAE,CAAC,CA2B1B;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,CAoBzD;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;AAskBD;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAiB3E;AAukBD,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,gBAAgB,CAkInE"}