@cursor/bdk 0.2.1

package/dist/internal/run-client.js

@@ -0,0 +1,239 @@
+/**
+ * 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.
+ */
+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 { mergeRequestHeaders } from "./request-headers.js";
+import { buildTrajectory } from "./trajectory.js";
+/** Thrown when a turn stream exceeds `timeoutMs`; carries the session id. */
+export class RunSessionTimeoutError extends Error {
+    constructor(message, sessionId) {
+        super(message);
+        this.sessionId = sessionId;
+        this.name = "RunSessionTimeoutError";
+    }
+}
+const TERMINAL_TYPES = new Set(["session.waiting", "session.completed", "session.failed"]);
+/**
+ * Run one or more messages against a live agent-serve base URL
+ * (e.g. `http://127.0.0.1:3000/weather-agent`).
+ */
+export function runSession(options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        if (options.messages.length === 0) {
+            throw new Error("runSession requires at least one message");
+        }
+        const baseUrl = options.baseUrl.replace(/\/$/, "");
+        let sessionId = options.sessionId;
+        let continuationToken = options.continuationToken;
+        const allEvents = [];
+        let nextEventIndex = (_a = options.startIndex) !== null && _a !== void 0 ? _a : 0;
+        const auth = {
+            bearerToken: options.bearerToken,
+            headers: options.headers,
+        };
+        for (const message of options.messages) {
+            const turn = yield runOneTurn({
+                baseUrl,
+                message,
+                sessionId,
+                continuationToken,
+                startIndex: sessionId === undefined ? 0 : nextEventIndex,
+                auth,
+                timeoutMs: options.timeoutMs,
+                signal: options.signal,
+                onEvent: options.onEvent,
+                purpose: sessionId === undefined ? options.purpose : undefined,
+                workspaceDir: sessionId === undefined ? options.workspaceDir : undefined,
+                workspaceFiles: sessionId === undefined ? options.workspaceFiles : undefined,
+                cloud: sessionId === undefined ? options.cloud : undefined,
+            });
+            sessionId = turn.sessionId;
+            continuationToken = turn.continuationToken;
+            allEvents.push(...turn.events);
+            if (turn.events.length > 0) {
+                const last = turn.events[turn.events.length - 1];
+                nextEventIndex = last.index + 1;
+            }
+            if (!turn.ok) {
+                break;
+            }
+        }
+        if (sessionId === undefined) {
+            throw new Error("server did not return a session id");
+        }
+        const trajectory = buildTrajectory(allEvents);
+        return Object.assign(Object.assign({ sessionId }, (continuationToken === undefined ? {} : { continuationToken })), { baseUrl, events: allEvents, trajectory, ok: trajectory.ok, nextEventIndex: allEvents.length === 0 ? undefined : nextEventIndex });
+    });
+}
+function runOneTurn(args) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c, _d, _e;
+        let sessionId = args.sessionId;
+        let continuationToken = args.continuationToken;
+        if (sessionId === undefined) {
+            const body = { message: args.message };
+            if (args.purpose !== undefined) {
+                body.purpose = args.purpose;
+            }
+            if (args.workspaceDir !== undefined) {
+                body.workspaceDir = args.workspaceDir;
+            }
+            if (args.workspaceFiles !== undefined) {
+                body.workspaceFiles = args.workspaceFiles;
+            }
+            if (args.cloud !== undefined) {
+                body.cloud = args.cloud;
+            }
+            const created = yield postJson(args.baseUrl, "/v1/session", body, args.auth);
+            if (created.status >= 400 || created.body.ok === false) {
+                throw new Error(`POST /v1/session failed: ${(_a = str(created.body.error)) !== null && _a !== void 0 ? _a : created.status} ${(_b = str(created.body.message)) !== null && _b !== void 0 ? _b : ""}`.trim());
+            }
+            sessionId = str(created.body.sessionId);
+            continuationToken = str(created.body.continuationToken);
+        }
+        else {
+            const resp = yield postJson(args.baseUrl, `/v1/session/${sessionId}`, { message: args.message, continuationToken }, args.auth);
+            if (resp.status >= 400 || resp.body.ok === false) {
+                throw new Error(`follow-up failed: ${(_c = str(resp.body.error)) !== null && _c !== void 0 ? _c : resp.status}: ${(_d = str(resp.body.message)) !== null && _d !== void 0 ? _d : ""}`.trim());
+            }
+            continuationToken = (_e = str(resp.body.continuationToken)) !== null && _e !== void 0 ? _e : continuationToken;
+        }
+        if (sessionId === undefined) {
+            throw new Error("server did not return a session id");
+        }
+        const events = yield collectStream({
+            baseUrl: args.baseUrl,
+            sessionId,
+            startIndex: args.startIndex,
+            auth: args.auth,
+            timeoutMs: args.timeoutMs,
+            signal: args.signal,
+            onEvent: args.onEvent,
+        });
+        const turnFailed = events.some(e => e.type === "turn.failed");
+        const sessionFailed = events.some(e => e.type === "session.failed");
+        return Object.assign(Object.assign({ sessionId }, (continuationToken === undefined ? {} : { continuationToken })), { events, ok: !turnFailed && !sessionFailed });
+    });
+}
+function collectStream(args) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c;
+        var _d, _e;
+        const controller = new AbortController();
+        const onExternalAbort = () => {
+            controller.abort();
+        };
+        if (args.signal !== undefined) {
+            if (args.signal.aborted) {
+                controller.abort();
+            }
+            else {
+                args.signal.addEventListener("abort", onExternalAbort, { once: true });
+            }
+        }
+        const timer = args.timeoutMs === undefined ? undefined : setTimeout(() => controller.abort(), args.timeoutMs);
+        try {
+            const resp = yield fetch(`${args.baseUrl}/v1/session/${args.sessionId}/stream?startIndex=${args.startIndex}`, {
+                headers: mergeRequestHeaders(args.auth),
+                signal: controller.signal,
+            });
+            if (!resp.ok || resp.body === null) {
+                throw new Error(`stream failed (${resp.status})`);
+            }
+            const reader = resp.body.getReader();
+            const decoder = new TextDecoder();
+            let buffer = "";
+            const events = [];
+            for (;;) {
+                const chunk = yield reader.read();
+                if (chunk.done) {
+                    break;
+                }
+                buffer += decoder.decode(chunk.value, { stream: true });
+                const lines = buffer.split("\n");
+                buffer = (_d = lines.pop()) !== null && _d !== void 0 ? _d : "";
+                let stop = false;
+                for (const line of lines) {
+                    if (line.trim() === "") {
+                        continue;
+                    }
+                    let event;
+                    try {
+                        event = JSON.parse(line);
+                    }
+                    catch (_f) {
+                        continue;
+                    }
+                    events.push(event);
+                    (_a = args.onEvent) === null || _a === void 0 ? void 0 : _a.call(args, event);
+                    if (TERMINAL_TYPES.has(event.type)) {
+                        stop = true;
+                        break;
+                    }
+                }
+                if (stop) {
+                    break;
+                }
+            }
+            yield reader.cancel().catch(() => { });
+            return events;
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === "AbortError") {
+                if ((_b = args.signal) === null || _b === void 0 ? void 0 : _b.aborted) {
+                    throw new Error("cancelled");
+                }
+                throw new RunSessionTimeoutError(`turn timed out after ${(_e = args.timeoutMs) !== null && _e !== void 0 ? _e : "?"}ms (session ${args.sessionId})`, args.sessionId);
+            }
+            throw error;
+        }
+        finally {
+            (_c = args.signal) === null || _c === void 0 ? void 0 : _c.removeEventListener("abort", onExternalAbort);
+            if (timer !== undefined) {
+                clearTimeout(timer);
+            }
+        }
+    });
+}
+function postJson(baseUrl, path, body, auth) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const resp = yield fetch(`${baseUrl}${path}`, {
+            method: "POST",
+            headers: Object.assign({ "content-type": "application/json" }, mergeRequestHeaders(auth)),
+            body: JSON.stringify(body),
+        });
+        const text = yield resp.text();
+        let parsed = {};
+        if (text) {
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch (_a) {
+                parsed = { message: text };
+            }
+        }
+        const anyrunReason = resp.headers.get("x-anyrun-failure-reason");
+        if (anyrunReason !== null &&
+            anyrunReason !== "" &&
+            (parsed.message === undefined || parsed.message === "")) {
+            parsed.message = anyrunReason;
+        }
+        return { status: resp.status, body: parsed };
+    });
+}
+function str(value) {
+    return typeof value === "string" ? value : undefined;
+}

package/dist/internal/runtime-dispatch-runner.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Routes each turn to the runner that owns its runtime: local and cloud
+ * turns stay on the Cursor SDK runner, grokbot turns go to the Grok Bot
+ * remote client (`internal/grokbot/runner.ts`), which drives the hosted
+ * Grok Bot (Sand) harness through the public `/v0/grokbot` session API.
+ */
+import type { RunnerTurnRequest, TurnOutcome } from "../types.js";
+import type { AgentRunner, PrewarmOutcome, RunnerPrewarmRequest, SteerAckOutcome } from "./sdk-runner.js";
+export interface RuntimeDispatchingRunnerOptions {
+    sdkRunner: AgentRunner;
+    grokbot: AgentRunner;
+}
+export declare class RuntimeDispatchingRunner implements AgentRunner {
+    private readonly options;
+    constructor(options: RuntimeDispatchingRunnerOptions);
+    runTurn(request: RunnerTurnRequest): Promise<TurnOutcome>;
+    steer(request: {
+        sessionId: string;
+        text: string;
+    }): Promise<SteerAckOutcome>;
+    prewarm(request: RunnerPrewarmRequest): Promise<PrewarmOutcome>;
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=runtime-dispatch-runner.d.ts.map

package/dist/internal/runtime-dispatch-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-dispatch-runner.d.ts","sourceRoot":"","sources":["../../src/internal/runtime-dispatch-runner.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,KAAK,EACV,WAAW,EACX,cAAc,EACd,oBAAoB,EACpB,eAAe,EAChB,MAAM,iBAAiB,CAAC;AAEzB,MAAM,WAAW,+BAA+B;IAC9C,SAAS,EAAE,WAAW,CAAC;IACvB,OAAO,EAAE,WAAW,CAAC;CACtB;AAED,qBAAa,wBAAyB,YAAW,WAAW;IAC9C,OAAO,CAAC,QAAQ,CAAC,OAAO;IAApC,YAA6B,OAAO,EAAE,+BAA+B,EAAI;IAEnE,OAAO,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,CAAC,CAK9D;IAEK,KAAK,CAAC,OAAO,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,eAAe,CAAC,CAElF;IAEK,OAAO,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,cAAc,CAAC,CASpE;IAEK,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAG7B;CACF"}

package/dist/internal/runtime-dispatch-runner.js

@@ -0,0 +1,54 @@
+/**
+ * Routes each turn to the runner that owns its runtime: local and cloud
+ * turns stay on the Cursor SDK runner, grokbot turns go to the Grok Bot
+ * remote client (`internal/grokbot/runner.ts`), which drives the hosted
+ * Grok Bot (Sand) harness through the public `/v0/grokbot` session API.
+ */
+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());
+    });
+};
+export class RuntimeDispatchingRunner {
+    constructor(options) {
+        this.options = options;
+    }
+    runTurn(request) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (request.runtime === "grokbot") {
+                return this.options.grokbot.runTurn(request);
+            }
+            return this.options.sdkRunner.runTurn(request);
+        });
+    }
+    steer(request) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            var _c;
+            return (_c = (yield (_b = (_a = this.options.sdkRunner).steer) === null || _b === void 0 ? void 0 : _b.call(_a, request))) !== null && _c !== void 0 ? _c : "revert_to_followup";
+        });
+    }
+    prewarm(request) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            var _c;
+            // Prewarming is a local-harness concern; the engine only calls it for
+            // local-runtime agents.
+            return ((_c = (_b = (_a = this.options.sdkRunner).prewarm) === null || _b === void 0 ? void 0 : _b.call(_a, request)) !== null && _c !== void 0 ? _c : {
+                warmed: false,
+                reason: "the Cursor SDK runner does not support prewarming",
+            });
+        });
+    }
+    dispose() {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c, _d;
+            yield (_b = (_a = this.options.sdkRunner).dispose) === null || _b === void 0 ? void 0 : _b.call(_a);
+            yield (_d = (_c = this.options.grokbot).dispose) === null || _d === void 0 ? void 0 : _d.call(_c);
+        });
+    }
+}

package/dist/internal/sanitize-mcp-tool-name.d.ts

@@ -0,0 +1,20 @@
+/**
+ * MCP tool-name sanitization shared by the Cursor-account bridge
+ * (`account-mcp.ts`) and advertised connections (`advertise-tools.ts`).
+ *
+ * Connector display names — and the aggregate `/v1/agent/mcp` names minted
+ * from them (`<serverIdentifier>-<tool>`) — can contain spaces, dots, and
+ * other characters that are illegal as the tool name a model sees.
+ *
+ * Character class matches `packages/agent` `normalizeMcpToolName`
+ * (`[^a-zA-Z0-9_-]` → `_`). Length cap and the empty fallback match the
+ * account bridge (MCP clients commonly enforce `^[a-zA-Z0-9_-]{1,128}$`).
+ * Callers that talk to the backend keep the original advertised name.
+ */
+/** MCP clients commonly enforce `^[a-zA-Z0-9_-]{1,128}$` for tool names. */
+export declare const MAX_MCP_TOOL_NAME_LENGTH = 128;
+/** Connector display names can contain anything (spaces, dots, emoji). */
+export declare function sanitizeMcpToolName(name: string): string;
+/** `base` for the first claimant, `base_2` / `base_3` … for colliders. */
+export declare function suffixMcpToolName(base: string, index: number): string;
+//# sourceMappingURL=sanitize-mcp-tool-name.d.ts.map

package/dist/internal/sanitize-mcp-tool-name.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitize-mcp-tool-name.d.ts","sourceRoot":"","sources":["../../src/internal/sanitize-mcp-tool-name.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,4EAA4E;AAC5E,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAE5C,0EAA0E;AAC1E,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGxD;AAED,0EAA0E;AAC1E,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAMrE"}

package/dist/internal/sanitize-mcp-tool-name.js

@@ -0,0 +1,28 @@
+/**
+ * MCP tool-name sanitization shared by the Cursor-account bridge
+ * (`account-mcp.ts`) and advertised connections (`advertise-tools.ts`).
+ *
+ * Connector display names — and the aggregate `/v1/agent/mcp` names minted
+ * from them (`<serverIdentifier>-<tool>`) — can contain spaces, dots, and
+ * other characters that are illegal as the tool name a model sees.
+ *
+ * Character class matches `packages/agent` `normalizeMcpToolName`
+ * (`[^a-zA-Z0-9_-]` → `_`). Length cap and the empty fallback match the
+ * account bridge (MCP clients commonly enforce `^[a-zA-Z0-9_-]{1,128}$`).
+ * Callers that talk to the backend keep the original advertised name.
+ */
+/** MCP clients commonly enforce `^[a-zA-Z0-9_-]{1,128}$` for tool names. */
+export const MAX_MCP_TOOL_NAME_LENGTH = 128;
+/** Connector display names can contain anything (spaces, dots, emoji). */
+export function sanitizeMcpToolName(name) {
+    const cleaned = name.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, MAX_MCP_TOOL_NAME_LENGTH);
+    return cleaned === "" ? "tool" : cleaned;
+}
+/** `base` for the first claimant, `base_2` / `base_3` … for colliders. */
+export function suffixMcpToolName(base, index) {
+    if (index === 0) {
+        return base;
+    }
+    const suffix = `_${index + 1}`;
+    return `${base.slice(0, MAX_MCP_TOOL_NAME_LENGTH - suffix.length)}${suffix}`;
+}

package/dist/internal/schedule-runner.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Cron dispatch for `agent/schedules/`. In production mode a minute-aligned
+ * ticker fires matching schedules (UTC evaluation); in dev mode nothing
+ * fires automatically and `POST /v1/dev/schedules/:scheduleId` dispatches a
+ * schedule by hand, exactly once, through the same path.
+ */
+import type { AgentProject, AuthContext } from "../types.js";
+import { type SessionEngine } from "./session-engine.js";
+export declare const APP_AUTH: AuthContext;
+export declare class UnknownScheduleError extends Error {
+    readonly availableScheduleIds: string[];
+    constructor(scheduleId: string, availableScheduleIds: string[]);
+}
+export declare class ScheduleRunner {
+    private readonly engine;
+    private readonly logger;
+    private readonly schedules;
+    private timer;
+    private lastFiredMinute;
+    constructor(engine: SessionEngine, project: AgentProject, logger?: (line: string) => void);
+    get scheduleIds(): string[];
+    start(): void;
+    stop(): void;
+    private arm;
+    private tick;
+    /** Fire a schedule by name, exactly once. Returns the started sessions. */
+    dispatch(scheduleId: string): Promise<{
+        sessionIds: string[];
+    }>;
+}
+//# sourceMappingURL=schedule-runner.d.ts.map

package/dist/internal/schedule-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schedule-runner.d.ts","sourceRoot":"","sources":["../../src/internal/schedule-runner.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAgC,MAAM,aAAa,CAAC;AAE3F,OAAO,EAA2B,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAElF,eAAO,MAAM,QAAQ,EAAE,WAItB,CAAC;AAEF,qBAAa,oBAAqB,SAAQ,KAAK;IAG3C,QAAQ,CAAC,oBAAoB,EAAE,MAAM,EAAE;IAFzC,YACE,UAAU,EAAE,MAAM,EACT,oBAAoB,EAAE,MAAM,EAAE,EAIxC;CACF;AAQD,qBAAa,cAAc;IAMvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAEvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAPzB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;IAC/C,OAAO,CAAC,KAAK,CAA6B;IAC1C,OAAO,CAAC,eAAe,CAAM;IAE7B,YACmB,MAAM,EAAE,aAAa,EACtC,OAAO,EAAE,YAAY,EACJ,MAAM,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAe,EAO3D;IAED,IAAI,WAAW,IAAI,MAAM,EAAE,CAE1B;IAED,KAAK,IAAI,IAAI,CAKZ;IAED,IAAI,IAAI,IAAI,CAKX;IAED,OAAO,CAAC,GAAG;IAOX,OAAO,CAAC,IAAI;IAoBZ,2EAA2E;IACrE,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAwDpE;CACF"}

package/dist/internal/schedule-runner.js

@@ -0,0 +1,127 @@
+/**
+ * Cron dispatch for `agent/schedules/`. In production mode a minute-aligned
+ * ticker fires matching schedules (UTC evaluation); in dev mode nothing
+ * fires automatically and `POST /v1/dev/schedules/:scheduleId` dispatches a
+ * schedule by hand, exactly once, through the same path.
+ */
+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 { parseCron } from "./cron.js";
+import { SCHEDULE_CHANNEL_PREFIX } from "./session-engine.js";
+export const APP_AUTH = {
+    authenticator: "app",
+    principalId: "agent-serve:app",
+    principalType: "runtime",
+};
+export class UnknownScheduleError extends Error {
+    constructor(scheduleId, availableScheduleIds) {
+        super(`Unknown schedule "${scheduleId}"`);
+        this.availableScheduleIds = availableScheduleIds;
+        this.name = "UnknownScheduleError";
+    }
+}
+export class ScheduleRunner {
+    constructor(engine, project, logger = () => { }) {
+        this.engine = engine;
+        this.logger = logger;
+        this.lastFiredMinute = -1;
+        this.schedules = project.schedules.map(schedule => ({
+            name: schedule.name,
+            cron: parseCron(schedule.cron),
+            discovered: schedule,
+        }));
+    }
+    get scheduleIds() {
+        return this.schedules.map(schedule => schedule.name);
+    }
+    start() {
+        if (this.timer !== undefined || this.schedules.length === 0) {
+            return;
+        }
+        this.arm();
+    }
+    stop() {
+        if (this.timer !== undefined) {
+            clearTimeout(this.timer);
+            this.timer = undefined;
+        }
+    }
+    arm() {
+        var _a, _b;
+        const now = Date.now();
+        const nextMinute = (Math.floor(now / 60000) + 1) * 60000;
+        this.timer = setTimeout(() => this.tick(), nextMinute - now + 250);
+        (_b = (_a = this.timer).unref) === null || _b === void 0 ? void 0 : _b.call(_a);
+    }
+    tick() {
+        const now = new Date();
+        const minute = Math.floor(now.getTime() / 60000);
+        if (minute !== this.lastFiredMinute) {
+            this.lastFiredMinute = minute;
+            for (const schedule of this.schedules) {
+                if (schedule.cron.matches(now)) {
+                    void this.dispatch(schedule.name).catch(error => {
+                        this.logger(`[agent-sdk] schedule "${schedule.name}" dispatch failed: ${error instanceof Error ? error.message : String(error)}`);
+                    });
+                }
+            }
+        }
+        this.arm();
+    }
+    /** Fire a schedule by name, exactly once. Returns the started sessions. */
+    dispatch(scheduleId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const schedule = this.schedules.find(s => s.name === scheduleId);
+            if (schedule === undefined) {
+                throw new UnknownScheduleError(scheduleId, this.scheduleIds);
+            }
+            const definition = schedule.discovered.definition;
+            const channelId = `${SCHEDULE_CHANNEL_PREFIX}${schedule.name}`;
+            if (definition.markdown !== undefined) {
+                const { sessionId, done } = yield this.engine.runTask({
+                    channelId,
+                    prompt: definition.markdown,
+                    auth: APP_AUTH,
+                    title: `Schedule ${schedule.name}`,
+                });
+                this.engine.trackBackground(done);
+                return { sessionIds: [sessionId] };
+            }
+            if (definition.run === undefined) {
+                throw new Error(`Schedule "${scheduleId}" has no markdown or run form`);
+            }
+            const sessionIds = [];
+            const receivePromises = [];
+            const receive = (channel, input) => {
+                const promise = this.engine.receive(channel, input).then(session => {
+                    sessionIds.push(session.id);
+                    return session;
+                });
+                receivePromises.push(promise.catch(() => { }));
+                return promise;
+            };
+            yield definition.run({
+                receive,
+                callTool: (toolName, input, callOptions) => this.engine.callTool(toolName, input, Object.assign({ auth: APP_AUTH }, callOptions)),
+                waitUntil: promise => {
+                    this.engine.trackBackground(promise);
+                },
+                appAuth: APP_AUTH,
+                host: this.engine.host,
+                artifacts: this.engine.artifacts,
+            });
+            // Collect ids from receive() calls the handler chose not to await
+            // (commonly wrapped in waitUntil); receive resolves at message accept,
+            // not turn completion, so this settles fast.
+            yield Promise.allSettled(receivePromises);
+            return { sessionIds };
+        });
+    }
+}

package/dist/internal/scm/pr-url.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Provider-neutral PR URL parse. GitHub.com plus the Origin page shapes
+ * humans paste: cursor.com/codebase (canonical), origin.cursor.com, and the
+ * retired review-host shape that older links and stored PR records still
+ * carry.
+ *
+ * {@link parseScmPrUrl} is the wider parse the review seams use: it also
+ * recognizes GitLab merge requests (`/-/merge_requests/<iid>` on any host),
+ * Bitbucket Cloud / Data Center pull requests, and GitHub Enterprise Server
+ * (`/<owner>/<repo>/pull/<n>` on a host that is none of the above). The
+ * narrow {@link parsePrUrl} keeps its github.com + Origin contract for the
+ * free-text callers (Slack `pr-ref`) where "any host with /pull/N" would be
+ * too eager.
+ */
+export type PrProvider = "github" | "origin";
+/** Every SCM the review seams can address. */
+export type ScmPrProvider = PrProvider | "gitlab" | "bitbucket";
+export type ParsedPrUrl = {
+    provider: PrProvider;
+    owner: string;
+    repo: string;
+    number: number;
+    url: string;
+};
+export type ParsedScmPrUrl = {
+    provider: ScmPrProvider;
+    /**
+     * Namespace half of the repo: GitHub owner, GitLab group path (nested
+     * groups joined with `/`), Bitbucket workspace / project key (`~user`
+     * for Data Center personal repos).
+     */
+    owner: string;
+    repo: string;
+    number: number;
+    /** Canonical PR page URL. */
+    url: string;
+    /**
+     * Hostname the PR lives on (lowercase). `github.com` for dotcom, the
+     * GHES hostname for GitHub Enterprise, `gitlab.com` or the self-managed
+     * host for GitLab, `bitbucket.org` or the Data Center host for Bitbucket.
+     * Origin PRs report the Origin page host.
+     */
+    host: string;
+};
+/** github.com and Origin only — the contract free-text PR references use. */
+export declare function parsePrUrl(raw: string): ParsedPrUrl | undefined;
+/**
+ * Every provider shape, including GitHub Enterprise Server. The GitLab and
+ * Bitbucket path shapes are unambiguous on any host; a plain
+ * `/<owner>/<repo>/pull/<n>` on a host that is not github.com, Origin,
+ * GitLab, or Bitbucket is taken as GHES (the only remaining forge with that
+ * route). Callers that must not accept arbitrary hosts use
+ * {@link parsePrUrl}.
+ */
+export declare function parseScmPrUrl(raw: string): ParsedScmPrUrl | undefined;
+//# sourceMappingURL=pr-url.d.ts.map

package/dist/internal/scm/pr-url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pr-url.d.ts","sourceRoot":"","sources":["../../../src/internal/scm/pr-url.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE7C,8CAA8C;AAC9C,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,QAAQ,GAAG,WAAW,CAAC;AAEhE,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,EAAE,UAAU,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;CACb,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,EAAE,aAAa,CAAC;IACxB;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,6BAA6B;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AA2DF,6EAA6E;AAC7E,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAY/D;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAmHrE"}