@cursor/bdk 0.2.1

package/dist/internal/resolve-prod-target.js

@@ -0,0 +1,259 @@
+/**
+ * Resolve a hosted (managed) agent-sdk deployment into a base URL +
+ * request headers for chat/run/call/eval `--prod`.
+ *
+ * Uses short-lived `engineAccess` from the deployment status route
+ * (Cursor API key on the management API; `X-Anyrun-Port-Token` on the
+ * engine). Alias tokens are out of scope here.
+ */
+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, resolve } from "node:path";
+import { resolveDeployAuth } from "./cli-deploy.js";
+import { cursorWebsiteUrl } from "./cursor/credentials.js";
+import { DeployApiError, slugFromDirectoryName, validateDeploymentSlug, } from "./deploy-client.js";
+import { CLI_COMMAND_NAME as CLI } from "./distribution.js";
+import { deploymentArchitecture, rejectV2ForLegacyCommand } from "./legacy-command-guard.js";
+import { sleep as defaultSleep } from "./sleep.js";
+import { stderrPalette } from "./terminal-style.js";
+/**
+ * Interactive CLI keep-alive for hosted engines. Without these, a hibernated
+ * Anyrun pod returns 417 `pod_hibernated` and never wakes. Matches the
+ * cloud-agent interactive keep-alive shape (lower ≤ upper, seconds).
+ */
+export const PROD_ENGINE_WAKE_HEADERS = {
+    "x-anyrun-hibernation-lower-bound-s": "1800",
+    "x-anyrun-hibernation-upper-bound-s": "3600",
+};
+/**
+ * Thrown when a hosted deployment cannot be resolved. `notFound` is true
+ * when the deployment does not exist, so callers can suggest deploying
+ * (or running locally) instead of surfacing a bare API error.
+ */
+export class ProdTargetError extends Error {
+    constructor(message, options = { slug: "" }) {
+        super(message);
+        this.options = options;
+        this.name = "ProdTargetError";
+    }
+    get slug() {
+        return this.options.slug;
+    }
+    get notFound() {
+        return this.options.notFound === true;
+    }
+}
+/**
+ * Look up a running deployment and return its engineAccess URL/headers.
+ * Throws {@link Error} with a CLI-ready message on failure.
+ */
+export function resolveProdTarget(options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b;
+        const err = (_a = options.err) !== null && _a !== void 0 ? _a : ((text) => void process.stderr.write(text));
+        const slug = resolveProdSlug(options);
+        const auth = yield resolveDeployAuth({
+            team: options.team,
+            apiKey: options.apiKey,
+            fetchImpl: options.fetchImpl,
+            err,
+        });
+        if (typeof auth === "number") {
+            // Not "--prod": `eval` resolves the hosted deployment by default,
+            // without any flag.
+            throw new Error(`Could not resolve Cursor credentials/team for the hosted deployment (see above).`);
+        }
+        if (options.skipLegacyArchitectureCheck !== true) {
+            yield rejectV2ForLegacyCommand({
+                client: auth.client,
+                teamId: auth.teamId,
+                slug,
+            });
+        }
+        // A hibernated engine can briefly omit engineAccess while getPod fails
+        // during wake. Retry a few times before surfacing "not reachable yet".
+        const maxReachabilityAttempts = 5;
+        const sleep = (_b = options.sleep) !== null && _b !== void 0 ? _b : defaultSleep;
+        let detail;
+        for (let attempt = 0; attempt < maxReachabilityAttempts; attempt++) {
+            try {
+                detail = yield auth.client.getDeployment({
+                    teamId: auth.teamId,
+                    slug,
+                });
+            }
+            catch (error) {
+                if (error instanceof DeployApiError) {
+                    throw new ProdTargetError(`Deployment "${slug}" (team ${auth.teamId}): ${error.message}`, {
+                        slug,
+                        notFound: error.status === 404,
+                    });
+                }
+                throw error;
+            }
+            // `degraded` still serves the previous ACTIVE engine; allow runtime access
+            // when the control plane minted engineAccess for it.
+            const statusOk = detail.status === "running" || detail.status === "degraded";
+            if (!statusOk) {
+                const lastError = detail.lastError === null || detail.lastError === undefined
+                    ? ""
+                    : ` ${sanitizeCustomerFacingDetail(detail.lastError)}`;
+                throw new Error(`Deployment "${slug}" is ${detail.status}, not running.${lastError}\n` +
+                    `Deploy or wait: \`${CLI} deploy --slug ${slug}\` / \`${CLI} deployment ${slug}\``);
+            }
+            if (detail.engineAccess !== null && detail.engineAccess !== undefined) {
+                break;
+            }
+            if (attempt + 1 < maxReachabilityAttempts) {
+                if (attempt === 0) {
+                    err(`${stderrPalette().dim(`Deployment "${slug}" is waking; waiting for engine access…`)}\n`);
+                }
+                yield sleep(1000 * (attempt + 1));
+            }
+        }
+        if (detail === undefined) {
+            throw new Error(`Deployment "${slug}" lookup failed.`);
+        }
+        const access = detail.engineAccess;
+        if (access === null || access === undefined) {
+            throw new Error(`Deployment "${slug}" is ${detail.status} but is not reachable yet. ` +
+                `Try \`${CLI} deployment ${slug}\` or redeploy.`);
+        }
+        err(`${stderrPalette().dim(`Using hosted deployment "${slug}".`)}\n`);
+        return {
+            agentUrl: access.url.replace(/\/$/, ""),
+            headers: Object.assign(Object.assign({}, access.headers), PROD_ENGINE_WAKE_HEADERS),
+            slug,
+            expiresAt: access.expiresAt,
+        };
+    });
+}
+export function resolveProdPlaygroundUrl(options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        var _b;
+        const err = (_b = options.err) !== null && _b !== void 0 ? _b : ((text) => void process.stderr.write(text));
+        const slug = resolveProdSlug(options);
+        const auth = yield resolveDeployAuth({
+            team: options.team,
+            apiKey: options.apiKey,
+            fetchImpl: options.fetchImpl,
+            err,
+        });
+        if (typeof auth === "number") {
+            throw new Error(`Could not resolve Cursor credentials/team for the hosted deployment (see above).`);
+        }
+        const architecture = yield deploymentArchitecture({
+            client: auth.client,
+            teamId: auth.teamId,
+            slug,
+        });
+        if (architecture === "v2") {
+            const playgroundUrl = new URL(`/dashboard/deployed-agents/${encodeURIComponent(slug)}/playground`, cursorWebsiteUrl());
+            const sessionId = (_a = options.sessionId) === null || _a === void 0 ? void 0 : _a.trim();
+            if (sessionId !== undefined && sessionId !== "") {
+                playgroundUrl.searchParams.set("sessionId", sessionId);
+            }
+            err(`${stderrPalette().dim(`Using hosted deployment "${slug}".`)}\n`);
+            return {
+                playgroundUrl: playgroundUrl.toString(),
+                slug,
+                architecture,
+            };
+        }
+        const resolved = yield resolveProdAliasPlaygroundUrlWithAuth(options, auth, slug, err);
+        return Object.assign(Object.assign({}, resolved), { architecture });
+    });
+}
+/**
+ * Look up a running deployment and return its stable alias playground URL.
+ * Does not mint `engineAccess` — the browser signs in with the alias token.
+ * Throws {@link Error} with a CLI-ready message on failure.
+ */
+export function resolveProdAliasPlaygroundUrl(options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const err = (_a = options.err) !== null && _a !== void 0 ? _a : ((text) => void process.stderr.write(text));
+        const slug = resolveProdSlug(options);
+        const auth = yield resolveDeployAuth({
+            team: options.team,
+            apiKey: options.apiKey,
+            fetchImpl: options.fetchImpl,
+            err,
+        });
+        if (typeof auth === "number") {
+            throw new Error(`Could not resolve Cursor credentials/team for the hosted deployment (see above).`);
+        }
+        yield rejectV2ForLegacyCommand({
+            client: auth.client,
+            teamId: auth.teamId,
+            slug,
+        });
+        return resolveProdAliasPlaygroundUrlWithAuth(options, auth, slug, err);
+    });
+}
+function resolveProdAliasPlaygroundUrlWithAuth(options, auth, slug, err) {
+    return __awaiter(this, void 0, void 0, function* () {
+        let detail;
+        try {
+            detail = yield auth.client.getDeployment({
+                teamId: auth.teamId,
+                slug,
+            });
+        }
+        catch (error) {
+            if (error instanceof DeployApiError) {
+                throw new Error(`Deployment "${slug}" (team ${auth.teamId}): ${error.message}`);
+            }
+            throw error;
+        }
+        const statusOk = detail.status === "running" || detail.status === "degraded";
+        if (!statusOk) {
+            const lastError = detail.lastError === null || detail.lastError === undefined
+                ? ""
+                : ` ${sanitizeCustomerFacingDetail(detail.lastError)}`;
+            throw new Error(`Deployment "${slug}" is ${detail.status}, not running.${lastError}\n` +
+                `Deploy or wait: \`${CLI} deploy --slug ${slug}\` / \`${CLI} deployment ${slug}\``);
+        }
+        const aliasBase = auth.client.aliasUrl(detail.engineAlias).replace(/\/$/, "");
+        const base = `${aliasBase}/playground`;
+        const sessionId = options.sessionId !== undefined && options.sessionId.trim() !== ""
+            ? options.sessionId.trim()
+            : undefined;
+        const playgroundUrl = sessionId === undefined ? base : `${base}?sessionId=${encodeURIComponent(sessionId)}`;
+        err(`${stderrPalette().dim(`Using hosted deployment "${slug}".`)}\n`);
+        return { playgroundUrl, slug };
+    });
+}
+/** Strip obvious hosting internals from customer-facing error fragments. */
+function sanitizeCustomerFacingDetail(message) {
+    return message
+        .replace(/https?:\/\/\S+/gi, "[url]")
+        .replace(/\bpod-[a-z0-9]+\b/gi, "[runtime]")
+        .replace(/\banyrun\b/gi, "runtime")
+        .replace(/\bcursorvm\.com\b/gi, "host");
+}
+/** Resolve the deployment slug the same way `deploy` does for a single dir. */
+export function resolveProdSlug(options) {
+    var _a;
+    if (options.slug !== undefined && options.slug !== "") {
+        const slugError = validateDeploymentSlug(options.slug);
+        if (slugError !== undefined) {
+            throw new Error(slugError);
+        }
+        return options.slug;
+    }
+    const dir = resolve((_a = options.cwd) !== null && _a !== void 0 ? _a : process.cwd(), options.dir);
+    const derived = slugFromDirectoryName(basename(dir));
+    if (derived === undefined) {
+        throw new Error(`Could not derive a deployment slug from the directory name ${JSON.stringify(basename(dir))}; pass --slug.`);
+    }
+    return derived;
+}

package/dist/internal/resolved-connections.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Serve-time connection resolution for one mounted agent: once the host is
+ * listening (port known), symbolic transports — peers and the Cursor
+ * account bridge — resolve to concrete URLs and join the engine's
+ * resolved-connection set. Local turns call both over loopback; cloud
+ * turns use the serve `publicUrl` for peers and the account's native
+ * connectors instead of the bridge.
+ */
+import { type AgentProject } from "../types.js";
+import { type CursorAccountConnectionRef, type CursorAccountMcpBridge } from "./cursor/account-mcp.js";
+import { type PeerConnectionRef } from "./peer-connections.js";
+import type { EngineResolvedConnection } from "./session-engine.js";
+/** Fail fast before listen when static cloud config cannot honor `servers`. */
+export declare function validateMountConnectionsConfig(args: {
+    slug: string;
+    project: AgentProject;
+    accountRefs?: CursorAccountConnectionRef[];
+    publicUrl?: string;
+    /**
+     * True when serve has a cloud tools URL (`--cloud-tools-url`, always set on
+     * managed hosting): cloud turns then reach filtered account connections
+     * through the host connection bridge on the tool MCP endpoint, so the
+     * filter is honored host-side and no `--public-url` is needed.
+     */
+    cloudToolsBridge?: boolean;
+}): void;
+/** Fail closed when a cloud turn cannot honor a `servers` filter. */
+export declare function assertCloudCanHonorAccountServersFilters(args: {
+    runtime: "local" | "cloud";
+    resolvedConnections: readonly EngineResolvedConnection[];
+    /**
+     * Connection names this cloud turn reaches through the host connection
+     * bridge (tool MCP endpoint). The filter is honored on the serve host
+     * there, so a missing `cloudUrl` is not a fail-open.
+     */
+    bridgedNames?: ReadonlySet<string>;
+}): void;
+/** Fail closed when anonymous HTTP admission would expose account connectors. */
+export declare function assertAccountConnectionsNotAnonymous(args: {
+    allowAnonymous?: boolean;
+    /**
+     * Opt in when every admitted caller is already trusted (e.g. behind an
+     * authenticating proxy / hosted alias token). Same trust model as
+     * `--allow-anonymous-cursor-github`.
+     */
+    allowAnonymousCursorAccountMcp?: boolean;
+    hasAccountConnections: boolean;
+}): void;
+export declare function resolveMountConnections(args: {
+    slug: string;
+    project: AgentProject;
+    serverUrl: string;
+    peerRefs?: PeerConnectionRef[];
+    accountRefs?: CursorAccountConnectionRef[];
+    accountBridge?: CursorAccountMcpBridge;
+    publicUrl?: string;
+    authToken?: string;
+    /** See {@link validateMountConnectionsConfig}. */
+    cloudToolsBridge?: boolean;
+    logger: (line: string) => void;
+}): EngineResolvedConnection[];
+//# sourceMappingURL=resolved-connections.d.ts.map

package/dist/internal/resolved-connections.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolved-connections.d.ts","sourceRoot":"","sources":["../../src/internal/resolved-connections.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,KAAK,YAAY,EAAkC,MAAM,aAAa,CAAC;AAChF,OAAO,EACL,KAAK,0BAA0B,EAC/B,KAAK,sBAAsB,EAE5B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,KAAK,iBAAiB,EAA0B,MAAM,uBAAuB,CAAC;AACvF,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAEpE,+EAA+E;AAC/E,wBAAgB,8BAA8B,CAAC,IAAI,EAAE;IACnD,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,YAAY,CAAC;IACtB,WAAW,CAAC,EAAE,0BAA0B,EAAE,CAAC;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,GAAG,IAAI,CA0BP;AAED,qEAAqE;AACrE,wBAAgB,wCAAwC,CAAC,IAAI,EAAE;IAC7D,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC;IAC3B,mBAAmB,EAAE,SAAS,wBAAwB,EAAE,CAAC;IACzD;;;;OAIG;IACH,YAAY,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACpC,GAAG,IAAI,CAoBP;AAED,iFAAiF;AACjF,wBAAgB,oCAAoC,CAAC,IAAI,EAAE;IACzD,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;OAIG;IACH,8BAA8B,CAAC,EAAE,OAAO,CAAC;IACzC,qBAAqB,EAAE,OAAO,CAAC;CAChC,GAAG,IAAI,CAUP;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,YAAY,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAC/B,WAAW,CAAC,EAAE,0BAA0B,EAAE,CAAC;IAC3C,aAAa,CAAC,EAAE,sBAAsB,CAAC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC,GAAG,wBAAwB,EAAE,CAgE7B"}

package/dist/internal/resolved-connections.js

@@ -0,0 +1,93 @@
+/**
+ * Serve-time connection resolution for one mounted agent: once the host is
+ * listening (port known), symbolic transports — peers and the Cursor
+ * account bridge — resolve to concrete URLs and join the engine's
+ * resolved-connection set. Local turns call both over loopback; cloud
+ * turns use the serve `publicUrl` for peers and the account's native
+ * connectors instead of the bridge.
+ */
+import { isHostOauthConnectionTransport } from "../types.js";
+import { resolveCursorAccountConnections, } from "./cursor/account-mcp.js";
+import { resolvePeerConnections } from "./peer-connections.js";
+/** Fail fast before listen when static cloud config cannot honor `servers`. */
+export function validateMountConnectionsConfig(args) {
+    var _a;
+    if (args.accountRefs === undefined || args.accountRefs.length === 0) {
+        return;
+    }
+    const agent = args.project.agent;
+    const cloudCapable = agent.runtime === "cloud" || agent.cloud !== undefined;
+    if (!cloudCapable || args.publicUrl !== undefined || args.cloudToolsBridge === true) {
+        return;
+    }
+    const label = args.slug === "" ? args.project.name : args.slug;
+    const hostConnectionNames = new Set(((_a = args.project.agent.hostConnections) !== null && _a !== void 0 ? _a : []).map(connection => connection.name));
+    const filteredRefs = args.accountRefs.filter(ref => ref.servers !== undefined && !hostConnectionNames.has(ref.name));
+    if (filteredRefs.length === 0) {
+        return;
+    }
+    throw new Error(`[agent-sdk] agent "${label}" has Cursor account MCP connections with \`servers\` filters (${filteredRefs
+        .map(ref => ref.name)
+        .join(", ")}) but no --public-url; cloud-runtime turns cannot honor those filters without a public bridge URL. Set --public-url or remove the \`servers\` filter.`);
+}
+/** Fail closed when a cloud turn cannot honor a `servers` filter. */
+export function assertCloudCanHonorAccountServersFilters(args) {
+    if (args.runtime !== "cloud") {
+        return;
+    }
+    const blocked = args.resolvedConnections.filter(connection => { var _a; return connection.accountServersFilter !== undefined &&
+        connection.cloudUrl === undefined &&
+        ((_a = args.bridgedNames) === null || _a === void 0 ? void 0 : _a.has(connection.name)) !== true; });
+    if (blocked.length === 0) {
+        return;
+    }
+    throw new Error(`[agent-sdk] cloud turn cannot honor Cursor account \`servers\` filters (${blocked
+        .map(connection => connection.name)
+        .join(", ")}) without --public-url; set --public-url so cloud turns reach the filtered account bridge instead of falling back to native connectors.`);
+}
+/** Fail closed when anonymous HTTP admission would expose account connectors. */
+export function assertAccountConnectionsNotAnonymous(args) {
+    if (args.allowAnonymous !== true || !args.hasAccountConnections) {
+        return;
+    }
+    if (args.allowAnonymousCursorAccountMcp === true) {
+        return;
+    }
+    throw new Error("[agent-sdk] --allow-anonymous cannot be used with Cursor account MCP connections (defineConnection({ cursorAccount: true })); use --bearer-token, or opt in with --allow-anonymous-cursor-account-mcp behind a trusted boundary.");
+}
+export function resolveMountConnections(args) {
+    const agent = args.project.agent;
+    const cloudCapable = agent.runtime === "cloud" || agent.cloud !== undefined;
+    const label = args.slug === "" ? args.project.name : args.slug;
+    const resolved = [];
+    if (cloudCapable) {
+        const hostOauthNames = agent.connections
+            .filter(connection => isHostOauthConnectionTransport(connection.transport))
+            .map(connection => connection.name);
+        if (hostOauthNames.length > 0) {
+            args.logger(args.cloudToolsBridge === true
+                ? `[agent-sdk] agent "${label}": host-OAuth MCP connections (${hostOauthNames.join(", ")}) reach cloud turns through the host connection bridge; their tokens stay on this serve host.`
+                : `[agent-sdk] warning: agent "${label}" has host-OAuth MCP connections (${hostOauthNames.join(", ")}) whose tokens live on this serve host; cloud-runtime turns omit them. Serve with a cloud tools URL so they reach turns through the host connection bridge, or drop \`oauth\` and authorize the server another way.`);
+        }
+    }
+    if (args.peerRefs !== undefined && args.peerRefs.length > 0) {
+        const peers = resolvePeerConnections(Object.assign(Object.assign({ refs: args.peerRefs, serverUrl: args.serverUrl }, (args.publicUrl === undefined ? {} : { publicUrl: args.publicUrl })), (args.authToken === undefined ? {} : { authToken: args.authToken })));
+        resolved.push(...peers);
+        if (cloudCapable && args.publicUrl === undefined) {
+            args.logger(`[agent-sdk] warning: agent "${label}" has peer MCP connections (${peers
+                .map(peer => peer.name)
+                .join(", ")}) but no --public-url; cloud-runtime turns cannot reach this host's loopback address, so peers are omitted from cloud turns.`);
+        }
+    }
+    if (args.accountRefs !== undefined && args.accountBridge !== undefined) {
+        resolved.push(...resolveCursorAccountConnections(Object.assign({ refs: args.accountRefs, serverUrl: args.serverUrl, basePath: args.slug === "" ? "" : `/${args.slug}`, bridgeSecret: args.accountBridge.secret }, (args.publicUrl === undefined ? {} : { publicUrl: args.publicUrl }))));
+        // Non-blocking startup DX: connector statuses land in the serve log.
+        args.accountBridge.logPreflight(args.accountRefs);
+        if (cloudCapable && args.publicUrl === undefined) {
+            args.logger(args.cloudToolsBridge === true
+                ? `[agent-sdk] agent "${label}": cloud-runtime turns reach filtered account connections through the host connection bridge (unfiltered ones fall back to the account's native connectors).`
+                : `[agent-sdk] agent "${label}": cloud-runtime turns omit the account bridge without --public-url (cloud agents fall back to the account's native connectors).`);
+        }
+    }
+    return resolved;
+}

package/dist/internal/router.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Tiny path router: literal segments, `:param` captures, and a trailing
+ * `*param` catch-all, compiled once at server startup.
+ */
+import type { AuthContext, AuthPolicy, RouteMethod } from "../types.js";
+export interface ServerRouteContext {
+    params: Record<string, string>;
+    requestIp: string | null;
+    /** Resolved by the route's auth chain ("none" routes see null). */
+    auth: AuthContext | null;
+}
+export type ServerRouteHandler = (request: Request, ctx: ServerRouteContext) => Response | Promise<Response>;
+export interface ServerRoute {
+    method: RouteMethod;
+    /** Path pattern, e.g. `/v1/session/:sessionId/stream`. */
+    pattern: string;
+    /** Auth chain for the route; "none" mounts the route unauthenticated. */
+    auth: AuthPolicy[] | "none";
+    handler: ServerRouteHandler;
+}
+export interface RouteMatch {
+    route: ServerRoute;
+    params: Record<string, string>;
+}
+export declare class Router {
+    private readonly routes;
+    add(route: ServerRoute): void;
+    match(method: string, pathname: string): RouteMatch | undefined;
+    private matchExact;
+    /** True when the path matches some route with a different method. */
+    hasPath(pathname: string): boolean;
+}
+//# sourceMappingURL=router.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../src/internal/router.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAExE,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,mEAAmE;IACnE,IAAI,EAAE,WAAW,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,MAAM,kBAAkB,GAAG,CAC/B,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,kBAAkB,KACpB,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;AAElC,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,WAAW,CAAC;IACpB,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,IAAI,EAAE,UAAU,EAAE,GAAG,MAAM,CAAC;IAC5B,OAAO,EAAE,kBAAkB,CAAC;CAC7B;AAaD,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,WAAW,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED,qBAAa,MAAM;IACjB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuB;IAE9C,GAAG,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAE5B;IAED,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAW9D;IAED,OAAO,CAAC,UAAU;IAclB,qEAAqE;IACrE,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAGjC;CACF"}

package/dist/internal/router.js

@@ -0,0 +1,93 @@
+/**
+ * Tiny path router: literal segments, `:param` captures, and a trailing
+ * `*param` catch-all, compiled once at server startup.
+ */
+export class Router {
+    constructor() {
+        this.routes = [];
+    }
+    add(route) {
+        this.routes.push({ route, segments: compilePattern(route.pattern) });
+    }
+    match(method, pathname) {
+        const direct = this.matchExact(method, pathname);
+        if (direct !== undefined) {
+            return direct;
+        }
+        // HTTP: HEAD may be served by the corresponding GET handler (wget --spider,
+        // some load-balancer probes). Without this, GET-only routes return 405.
+        if (method === "HEAD") {
+            return this.matchExact("GET", pathname);
+        }
+        return undefined;
+    }
+    matchExact(method, pathname) {
+        const pathSegments = splitPath(pathname);
+        for (const { route, segments } of this.routes) {
+            if (route.method !== method) {
+                continue;
+            }
+            const params = matchSegments(segments, pathSegments);
+            if (params !== undefined) {
+                return { route, params };
+            }
+        }
+        return undefined;
+    }
+    /** True when the path matches some route with a different method. */
+    hasPath(pathname) {
+        const pathSegments = splitPath(pathname);
+        return this.routes.some(({ segments }) => matchSegments(segments, pathSegments) !== undefined);
+    }
+}
+function compilePattern(pattern) {
+    const segments = splitPath(pattern).map(part => part.startsWith(":")
+        ? { kind: "param", name: part.slice(1) }
+        : part.startsWith("*")
+            ? { kind: "rest", name: part.slice(1) }
+            : { kind: "literal", value: part });
+    const restIndex = segments.findIndex(segment => segment.kind === "rest");
+    if (restIndex !== -1 && restIndex !== segments.length - 1) {
+        throw new Error(`Route pattern "${pattern}" may only use a catch-all (*name) as the last segment.`);
+    }
+    return segments;
+}
+function splitPath(path) {
+    return path.split("/").filter(part => part !== "");
+}
+function matchSegments(segments, pathSegments) {
+    const last = segments[segments.length - 1];
+    const hasRest = last !== undefined && last.kind === "rest";
+    if (hasRest) {
+        if (pathSegments.length < segments.length - 1) {
+            return undefined;
+        }
+    }
+    else if (segments.length !== pathSegments.length) {
+        return undefined;
+    }
+    const params = {};
+    const fixedCount = hasRest ? segments.length - 1 : segments.length;
+    for (let i = 0; i < fixedCount; i++) {
+        const segment = segments[i];
+        const value = pathSegments[i];
+        if (segment === undefined || value === undefined) {
+            return undefined;
+        }
+        if (segment.kind === "literal") {
+            if (segment.value !== value) {
+                return undefined;
+            }
+        }
+        else if (segment.kind === "param") {
+            params[segment.name] = decodeURIComponent(value);
+        }
+    }
+    if (hasRest) {
+        params[last.name] = pathSegments
+            .slice(fixedCount)
+            .map(value => decodeURIComponent(value))
+            .join("/");
+    }
+    return params;
+}

package/dist/internal/run-client.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Programmatic HTTP client for agent-sdk sessions.
+ *
+ * Used by `agent-sdk run` and `chat --json`: create/follow a
+ * session, collect the NDJSON stream until the turn parks, and return a
+ * compact {@link Trajectory} plus the continuation token for follow-ups.
+ */
+import type { AgentCloudOptions, SessionEvent, SessionPurpose } from "../types.js";
+import { type RequestAuth } from "./request-headers.js";
+import { type Trajectory } from "./trajectory.js";
+/** Thrown when a turn stream exceeds `timeoutMs`; carries the session id. */
+export declare class RunSessionTimeoutError extends Error {
+    readonly sessionId: string;
+    constructor(message: string, sessionId: string);
+}
+export interface RunClientOptions extends RequestAuth {
+    baseUrl: string;
+    /** Abort a hung turn. */
+    timeoutMs?: number;
+    /** External cancel (combined with {@link timeoutMs} when both are set). */
+    signal?: AbortSignal;
+    /** Called for each stream event as it arrives (for CLI progress). */
+    onEvent?: (event: SessionEvent) => void;
+    /**
+     * Create-time session purpose. Pass `"eval"` from the eval harness so
+     * the session is marked as regression traffic. Default `"live"`.
+     */
+    purpose?: SessionPurpose;
+}
+export interface RunSessionResult {
+    sessionId: string;
+    continuationToken?: string;
+    baseUrl: string;
+    events: SessionEvent[];
+    trajectory: Trajectory;
+    ok: boolean;
+    /**
+     * Index to pass as `startIndex` on the next call for this session. Undefined
+     * when the turn streamed nothing, in which case reuse the previous value.
+     */
+    nextEventIndex?: number;
+}
+/**
+ * Run one or more messages against a live agent-serve base URL
+ * (e.g. `http://127.0.0.1:3000/weather-agent`).
+ */
+export declare function runSession(options: RunClientOptions & {
+    messages: string[];
+    sessionId?: string;
+    continuationToken?: string;
+    /**
+     * First event index to read when resuming an existing session.
+     *
+     * The stream replays from `startIndex` and this client stops at the first
+     * terminal event, so a caller that sends several turns across separate
+     * `runSession` calls **must** pass the index after its last consumed event
+     * (see {@link RunSessionResult.nextEventIndex}). Omitting it replays the
+     * earlier turn and returns those stale events instead of the new turn's.
+     */
+    startIndex?: number;
+    /** Applied only when creating a new session (first message). */
+    workspaceDir?: string;
+    /** Applied only when creating a new session (first message). */
+    workspaceFiles?: Record<string, string>;
+    /** Applied only when creating a new session (first message). */
+    cloud?: AgentCloudOptions;
+}): Promise<RunSessionResult>;
+//# sourceMappingURL=run-client.d.ts.map

package/dist/internal/run-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-client.d.ts","sourceRoot":"","sources":["../../src/internal/run-client.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACnF,OAAO,EAAuB,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAC7E,OAAO,EAAmB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAEnE,6EAA6E;AAC7E,qBAAa,sBAAuB,SAAQ,KAAK;IAG7C,QAAQ,CAAC,SAAS,EAAE,MAAM;IAF5B,YACE,OAAO,EAAE,MAAM,EACN,SAAS,EAAE,MAAM,EAI3B;CACF;AACD,MAAM,WAAW,gBAAiB,SAAQ,WAAW;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,yBAAyB;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,qEAAqE;IACrE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;IACxC;;;OAGG;IACH,OAAO,CAAC,EAAE,cAAc,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,UAAU,EAAE,UAAU,CAAC;IACvB,EAAE,EAAE,OAAO,CAAC;IACZ;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAID;;;GAGG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,gBAAgB,GAAG;IAC1B,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gEAAgE;IAChE,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,gEAAgE;IAChE,KAAK,CAAC,EAAE,iBAAiB,CAAC;CAC3B,GACA,OAAO,CAAC,gBAAgB,CAAC,CAyD3B"}