@cursor/bdk 0.2.1

package/dist/internal/legacy-command-guard.js

@@ -0,0 +1,51 @@
+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 { DeployApiError } from "./deploy-client.js";
+/**
+ * Classify a hosted slug by probing the v2 control plane.
+ *
+ * Only HTTP 404 means “not v2.” Auth, 5xx, and transport errors fail closed
+ * so a v2 slug cannot fall through to `/internal/agent-serve`. That probe
+ * shares the factory microlith path used by secrets; a factory outage will
+ * also block legacy `--prod` until it recovers.
+ */
+export function deploymentArchitecture(args) {
+    return __awaiter(this, void 0, void 0, function* () {
+        try {
+            yield args.client.getAgentkitDeploy({
+                teamId: args.teamId,
+                slug: args.slug,
+            });
+            return "v2";
+        }
+        catch (error) {
+            if (error instanceof DeployApiError && error.status === 404) {
+                return "v1";
+            }
+            throw error;
+        }
+    });
+}
+export function unsupportedV2LegacyCommandError(slug) {
+    return new DeployApiError(`This command is not supported for architecture v2 deployment "${slug}". The command stopped before calling the legacy v1 deployment API.`, 409);
+}
+export function isUnsupportedV2LegacyCommandError(error) {
+    return (error instanceof DeployApiError &&
+        error.status === 409 &&
+        error.message.includes("not supported for architecture v2"));
+}
+export function rejectV2ForLegacyCommand(args) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const architecture = yield deploymentArchitecture(args);
+        if (architecture === "v2") {
+            throw unsupportedV2LegacyCommandError(args.slug);
+        }
+    });
+}

package/dist/internal/listen-port.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Bind an HTTP server to a port, with a clear next-port path when 3000 (or
+ * whatever was requested) is already taken — a common onboarding failure.
+ */
+import type { Server } from "node:http";
+/** Default listen port for `serve` / `dev` when `--port` is omitted. */
+export declare const DEFAULT_SERVE_PORT = 3000;
+export declare function isAddrInUse(error: unknown): boolean;
+export declare function formatPortInUseHint(port: number): string;
+/**
+ * `server.listen` with fallback when the caller used the default port.
+ * Explicit `--port N` (including `0`) fails immediately with a next-port hint.
+ */
+export declare function listenHttpServer(args: {
+    server: Server;
+    host: string;
+    port: number;
+    /** True when the caller passed `port` (including 0); skip fallback. */
+    portWasExplicit: boolean;
+    logger: (line: string) => void;
+}): Promise<number>;
+//# sourceMappingURL=listen-port.d.ts.map

package/dist/internal/listen-port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"listen-port.d.ts","sourceRoot":"","sources":["../../src/internal/listen-port.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAGxC,wEAAwE;AACxE,eAAO,MAAM,kBAAkB,OAAO,CAAC;AAKvC,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAOnD;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMxD;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,eAAe,EAAE,OAAO,CAAC;IACzB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC,GAAG,OAAO,CAAC,MAAM,CAAC,CAyClB"}

package/dist/internal/listen-port.js

@@ -0,0 +1,77 @@
+/**
+ * Bind an HTTP server to a port, with a clear next-port path when 3000 (or
+ * whatever was requested) is already taken — a common onboarding failure.
+ */
+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 { once } from "node:events";
+import { CLI_COMMAND_NAME } from "./distribution.js";
+/** Default listen port for `serve` / `dev` when `--port` is omitted. */
+export const DEFAULT_SERVE_PORT = 3000;
+/** How many ports above the default to try when the default is taken. */
+const DEFAULT_PORT_FALLBACK_SPAN = 20;
+export function isAddrInUse(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === "EADDRINUSE");
+}
+export function formatPortInUseHint(port) {
+    const next = port === 0 ? 3001 : port + 1;
+    return (`port ${port} is already in use. ` +
+        `Try \`${CLI_COMMAND_NAME} dev --port ${next}\` or \`--port 0\` for any free port.`);
+}
+/**
+ * `server.listen` with fallback when the caller used the default port.
+ * Explicit `--port N` (including `0`) fails immediately with a next-port hint.
+ */
+export function listenHttpServer(args) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const { server, host, logger } = args;
+        const startPort = args.port;
+        if (args.portWasExplicit || startPort === 0) {
+            try {
+                server.listen(startPort, host);
+                yield once(server, "listening");
+            }
+            catch (error) {
+                if (isAddrInUse(error)) {
+                    throw new Error(formatPortInUseHint(startPort));
+                }
+                throw error;
+            }
+            const address = server.address();
+            if (address === null || typeof address === "string") {
+                throw new Error("server listening without an address");
+            }
+            return address.port;
+        }
+        const last = startPort + DEFAULT_PORT_FALLBACK_SPAN;
+        for (let port = startPort; port <= last; port++) {
+            try {
+                server.listen(port, host);
+                yield once(server, "listening");
+                if (port !== startPort) {
+                    logger(`[agent-sdk] port ${startPort} in use; listening on ${port} instead (pass --port to pick)`);
+                }
+                return port;
+            }
+            catch (error) {
+                if (!isAddrInUse(error)) {
+                    throw error;
+                }
+                if (port === last) {
+                    throw new Error(formatPortInUseHint(port));
+                }
+            }
+        }
+        throw new Error(formatPortInUseHint(last));
+    });
+}

package/dist/internal/local-control-plane.d.ts

@@ -0,0 +1,59 @@
+/**
+ * In-process control plane started with local `serve`. Owns schedule clocks
+ * and reminder documents + clocks, then fires into the kit the same way the
+ * Cursor backend does over HTTP when `--no-control-plane` is set.
+ *
+ * Reminder lifecycle (protocol v1): CP assigns id, arms timers, claims a due
+ * fire once, invokes a guest executor with an immutable descriptor, and
+ * applies the outcome with generation/fireCount CAS. Cancel/rekey racing an
+ * in-flight execution bumps generation so a stale outcome cannot resurrect
+ * the reminder. Legacy `fireReminder(id, fireCount)` remains for v1 runners.
+ *
+ * v2 ingest lives here: `routeContinuation` stamps the mailbox (July twin
+ * of hosted `routeVerifiedIngressContinuation`), and `attachScmEvents`
+ * owns the `/v0/scm-events` long poll. v1 keeps engine-side scm-events.
+ * Hosted `--no-control-plane` v2 skips that poll — the hosted CP delivers.
+ */
+import { type LocalIngressContinuation, type RouteLocalIngressContinuationInput } from "./local-ingress.js";
+import type { PlatformTimers } from "./platform-timers.js";
+import { type ReminderControlPlane, type ReminderGuestExecutor } from "./reminder-control-plane-protocol.js";
+export interface LocalControlPlane extends PlatformTimers, ReminderControlPlane {
+    /**
+     * Stamp a v2 mailbox from the channel selector + live payload. Same
+     * contract as hosted verified ingress. `/v1` is a no-op.
+     */
+    routeContinuation(input: RouteLocalIngressContinuationInput): LocalIngressContinuation;
+    /**
+     * Take ownership of the v2 `/v0/scm-events` long poll. Starts the relay.
+     * v1 scm-events stay on the engine serve path.
+     */
+    attachScmEvents(relay: {
+        start(): void;
+        stop(): Promise<void>;
+    }): void;
+    /** Arm persisted reminder clocks after the kit fire callback is live. */
+    startClocks(): void;
+    stop(): void;
+}
+export declare function createLocalControlPlane(opts: {
+    fireSchedule: (name: string) => Promise<unknown>;
+    /**
+     * Legacy v1 path: CP calls this with (id, fireCount) and the runner mutates
+     * authoritative state. Prefer {@link executeReminder} for architecture v2.
+     */
+    fireReminder?: (id: string, fireCount: number) => Promise<unknown>;
+    /**
+     * Protocol guest executor. When set, due timers claim once, invoke this
+     * with an immutable descriptor, and apply the returned outcome via CAS.
+     */
+    executeReminder?: ReminderGuestExecutor;
+    /**
+     * Persist reminder documents under `<stateDir>/reminders`. Local serve
+     * passes `<stateRoot>/control-plane`.
+     */
+    stateDir?: string;
+    /** Arm deadline timers. Off in `--dev`. Defaults to true. */
+    armReminderClocks?: boolean;
+    logger?: (line: string) => void;
+}): Promise<LocalControlPlane>;
+//# sourceMappingURL=local-control-plane.d.ts.map

package/dist/internal/local-control-plane.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-control-plane.d.ts","sourceRoot":"","sources":["../../src/internal/local-control-plane.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,EACL,KAAK,wBAAwB,EAC7B,KAAK,kCAAkC,EAExC,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EAKL,KAAK,oBAAoB,EAIzB,KAAK,qBAAqB,EAI3B,MAAM,sCAAsC,CAAC;AAI9C,MAAM,WAAW,iBAAkB,SAAQ,cAAc,EAAE,oBAAoB;IAC7E;;;OAGG;IACH,iBAAiB,CAAC,KAAK,EAAE,kCAAkC,GAAG,wBAAwB,CAAC;IACvF;;;OAGG;IACH,eAAe,CAAC,KAAK,EAAE;QAAE,KAAK,IAAI,IAAI,CAAC;QAAC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,GAAG,IAAI,CAAC;IACvE,yEAAyE;IACzE,WAAW,IAAI,IAAI,CAAC;IACpB,IAAI,IAAI,IAAI,CAAC;CACd;AAED,wBAAsB,uBAAuB,CAAC,IAAI,EAAE;IAClD,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACjD;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACnE;;;OAGG;IACH,eAAe,CAAC,EAAE,qBAAqB,CAAC;IACxC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA2W7B"}

package/dist/internal/local-control-plane.js

@@ -0,0 +1,351 @@
+/**
+ * In-process control plane started with local `serve`. Owns schedule clocks
+ * and reminder documents + clocks, then fires into the kit the same way the
+ * Cursor backend does over HTTP when `--no-control-plane` is set.
+ *
+ * Reminder lifecycle (protocol v1): CP assigns id, arms timers, claims a due
+ * fire once, invokes a guest executor with an immutable descriptor, and
+ * applies the outcome with generation/fireCount CAS. Cancel/rekey racing an
+ * in-flight execution bumps generation so a stale outcome cannot resurrect
+ * the reminder. Legacy `fireReminder(id, fireCount)` remains for v1 runners.
+ *
+ * v2 ingest lives here: `routeContinuation` stamps the mailbox (July twin
+ * of hosted `routeVerifiedIngressContinuation`), and `attachScmEvents`
+ * owns the `/v0/scm-events` long poll. v1 keeps engine-side scm-events.
+ * Hosted `--no-control-plane` v2 skips that poll — the hosted CP delivers.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { join } from "node:path";
+import { parseCron } from "./cron.js";
+import { routeLocalIngressContinuation, } from "./local-ingress.js";
+import { applyOutcomeToRecord, claimFromDescriptor, intentToNewRecord, REMINDER_CP_PROTOCOL_VERSION, recordGeneration, toFireDescriptor, } from "./reminder-control-plane-protocol.js";
+import { MAX_TIMER_MS } from "./reminder-schedule.js";
+import { ReminderStore } from "./reminder-store.js";
+export function createLocalControlPlane(opts) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b;
+        if (opts.fireReminder === undefined && opts.executeReminder === undefined) {
+            throw new Error("createLocalControlPlane requires fireReminder and/or executeReminder");
+        }
+        const logger = (_a = opts.logger) !== null && _a !== void 0 ? _a : (() => { });
+        const armReminderClocks = opts.armReminderClocks !== false;
+        const store = opts.stateDir === undefined ? undefined : new ReminderStore(join(opts.stateDir, "reminders"));
+        const schedules = new Map();
+        const reminderTimers = new Map();
+        const reminders = new Map(((_b = (yield store === null || store === void 0 ? void 0 : store.list())) !== null && _b !== void 0 ? _b : []).map(record => { var _a; return [
+            record.id,
+            Object.assign(Object.assign({}, record), { generation: (_a = record.generation) !== null && _a !== void 0 ? _a : 0 }),
+        ]; }));
+        /** In-flight claims keyed by reminder id (single-flight per id). */
+        const inflight = new Map();
+        let scheduleTimer;
+        let lastFiredMinute = -1;
+        let scmRelay;
+        function persist(record) {
+            return __awaiter(this, void 0, void 0, function* () {
+                reminders.set(record.id, record);
+                yield store === null || store === void 0 ? void 0 : store.save(record);
+            });
+        }
+        function armScheduleTicker() {
+            var _a;
+            if (scheduleTimer !== undefined || schedules.size === 0) {
+                return;
+            }
+            const now = Date.now();
+            const nextMinute = (Math.floor(now / 60000) + 1) * 60000;
+            scheduleTimer = setTimeout(() => tickSchedules(), nextMinute - now + 250);
+            (_a = scheduleTimer.unref) === null || _a === void 0 ? void 0 : _a.call(scheduleTimer);
+        }
+        function stopScheduleTicker() {
+            if (scheduleTimer === undefined) {
+                return;
+            }
+            clearTimeout(scheduleTimer);
+            scheduleTimer = undefined;
+        }
+        function tickSchedules() {
+            scheduleTimer = undefined;
+            const now = new Date();
+            const minute = Math.floor(now.getTime() / 60000);
+            if (minute !== lastFiredMinute) {
+                lastFiredMinute = minute;
+                for (const [name, cron] of schedules) {
+                    if (!cron.matches(now)) {
+                        continue;
+                    }
+                    void opts.fireSchedule(name).catch(error => {
+                        logger(`[agent-sdk] schedule "${name}" dispatch failed: ${error instanceof Error ? error.message : String(error)}`);
+                    });
+                }
+            }
+            armScheduleTicker();
+        }
+        function clearReminderTimer(id) {
+            const timer = reminderTimers.get(id);
+            if (timer !== undefined) {
+                clearTimeout(timer);
+                reminderTimers.delete(id);
+            }
+        }
+        function armReminder(record) {
+            var _a;
+            clearReminderTimer(record.id);
+            if (record.status !== "armed") {
+                return;
+            }
+            const delay = Math.min(MAX_TIMER_MS, Math.max(0, record.nextFireAtMs - Date.now()));
+            const timer = setTimeout(() => {
+                reminderTimers.delete(record.id);
+                void onReminderDue(record.id).catch(error => {
+                    logger(`[agent-sdk] reminder "${record.id}" dispatch failed: ${error instanceof Error ? error.message : String(error)}`);
+                });
+            }, delay);
+            (_a = timer.unref) === null || _a === void 0 ? void 0 : _a.call(timer);
+            reminderTimers.set(record.id, timer);
+        }
+        function claimDue(id) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const current = reminders.get(id);
+                if (current === undefined || current.status !== "armed") {
+                    return undefined;
+                }
+                if (current.nextFireAtMs > Date.now() + 50) {
+                    armReminder(current);
+                    return undefined;
+                }
+                if (inflight.has(id)) {
+                    return undefined;
+                }
+                const claimed = Object.assign(Object.assign({}, current), { status: "firing", generation: recordGeneration(current), updatedAt: new Date().toISOString() });
+                yield persist(claimed);
+                inflight.set(id, {
+                    id: claimed.id,
+                    fireCount: claimed.fireCount,
+                    generation: recordGeneration(claimed),
+                });
+                return claimed;
+            });
+        }
+        function applyReminderOutcome(claim, outcome) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const current = reminders.get(claim.id);
+                if (current === undefined) {
+                    inflight.delete(claim.id);
+                    return { applied: false, reason: "missing" };
+                }
+                const result = applyOutcomeToRecord(current, claim, outcome);
+                inflight.delete(claim.id);
+                if (!result.applied) {
+                    if (current.status === "armed" && armReminderClocks) {
+                        armReminder(current);
+                    }
+                    return result;
+                }
+                yield persist(result.record);
+                if (armReminderClocks && result.record.status === "armed") {
+                    armReminder(result.record);
+                }
+                else {
+                    clearReminderTimer(result.record.id);
+                }
+                return result;
+            });
+        }
+        function onReminderDue(id) {
+            return __awaiter(this, void 0, void 0, function* () {
+                // Protocol path: claim → guest execute → CAS apply.
+                if (opts.executeReminder !== undefined) {
+                    const claimed = yield claimDue(id);
+                    if (claimed === undefined) {
+                        return;
+                    }
+                    const descriptor = toFireDescriptor(claimed, Date.now());
+                    let outcome;
+                    try {
+                        outcome = yield opts.executeReminder(descriptor);
+                    }
+                    catch (error) {
+                        logger(`[agent-sdk] reminder "${id}" guest execution failed: ${error instanceof Error ? error.message : String(error)}`);
+                        outcome = {
+                            kind: "retry",
+                            delayMs: 1000,
+                            reason: "guest_error",
+                        };
+                    }
+                    const result = yield applyReminderOutcome(claimFromDescriptor(descriptor), outcome);
+                    if (!result.applied) {
+                        logger(`[agent-sdk] reminder "${id}" outcome not applied: ${result.reason}`);
+                    }
+                    return;
+                }
+                // Legacy v1: do not claim/firing — runner mutates via putReminder after fire.
+                const current = reminders.get(id);
+                if (current === undefined || current.status !== "armed") {
+                    return;
+                }
+                if (current.nextFireAtMs > Date.now() + 50) {
+                    armReminder(current);
+                    return;
+                }
+                try {
+                    yield opts.fireReminder(current.id, current.fireCount);
+                }
+                catch (error) {
+                    logger(`[agent-sdk] reminder "${id}" dispatch failed: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            });
+        }
+        return {
+            protocolVersion: REMINDER_CP_PROTOCOL_VERSION,
+            routeContinuation: routeLocalIngressContinuation,
+            attachScmEvents(relay) {
+                scmRelay = relay;
+                relay.start();
+                logger("[agent-sdk] cursor-events: control-plane ingest started");
+            },
+            upsertSchedule(input) {
+                return __awaiter(this, void 0, void 0, function* () {
+                    schedules.set(input.name, parseCron(input.cron));
+                    armScheduleTicker();
+                });
+            },
+            deleteSchedule(name) {
+                return __awaiter(this, void 0, void 0, function* () {
+                    schedules.delete(name);
+                    if (schedules.size === 0) {
+                        stopScheduleTicker();
+                    }
+                });
+            },
+            putReminder(record) {
+                return __awaiter(this, void 0, void 0, function* () {
+                    var _a;
+                    const normalized = Object.assign(Object.assign({}, record), { generation: (_a = record.generation) !== null && _a !== void 0 ? _a : 0 });
+                    yield persist(normalized);
+                    if (armReminderClocks && normalized.status === "armed") {
+                        armReminder(normalized);
+                        return;
+                    }
+                    clearReminderTimer(normalized.id);
+                    if (normalized.status !== "firing") {
+                        inflight.delete(normalized.id);
+                    }
+                });
+            },
+            getReminder(id) {
+                return __awaiter(this, void 0, void 0, function* () {
+                    return reminders.get(id);
+                });
+            },
+            listReminders() {
+                return __awaiter(this, void 0, void 0, function* () {
+                    return [...reminders.values()];
+                });
+            },
+            deleteReminder(id) {
+                return __awaiter(this, void 0, void 0, function* () {
+                    clearReminderTimer(id);
+                    inflight.delete(id);
+                    reminders.delete(id);
+                    yield store === null || store === void 0 ? void 0 : store.delete(id);
+                });
+            },
+            createReminder(intent) {
+                return __awaiter(this, void 0, void 0, function* () {
+                    if (intent.protocolVersion !== REMINDER_CP_PROTOCOL_VERSION) {
+                        throw new Error(`Unsupported reminder CP protocol version ${String(intent.protocolVersion)}`);
+                    }
+                    const record = intentToNewRecord(intent);
+                    yield persist(record);
+                    if (armReminderClocks && record.status === "armed") {
+                        armReminder(record);
+                    }
+                    return record;
+                });
+            },
+            cancelReminder(id_1) {
+                return __awaiter(this, arguments, void 0, function* (id, reason = "explicit_cancel") {
+                    const current = reminders.get(id);
+                    if (current === undefined) {
+                        return undefined;
+                    }
+                    if (current.status === "completed" ||
+                        current.status === "cancelled" ||
+                        current.status === "disarmed") {
+                        return current;
+                    }
+                    clearReminderTimer(id);
+                    inflight.delete(id);
+                    const updated = Object.assign(Object.assign({}, current), { status: "cancelled", disarmReason: reason, generation: recordGeneration(current) + 1, updatedAt: new Date().toISOString() });
+                    yield persist(updated);
+                    return updated;
+                });
+            },
+            rekeyReminders(channelId, oldToken, newToken) {
+                return __awaiter(this, void 0, void 0, function* () {
+                    let n = 0;
+                    for (const record of [...reminders.values()]) {
+                        if (record.channelId !== channelId || record.continuationToken !== oldToken) {
+                            continue;
+                        }
+                        if (record.status !== "armed" && record.status !== "firing") {
+                            continue;
+                        }
+                        const wasInflight = inflight.has(record.id);
+                        inflight.delete(record.id);
+                        let updated = Object.assign(Object.assign({}, record), { continuationToken: newToken, status: "armed", generation: recordGeneration(record) + 1, updatedAt: new Date().toISOString() });
+                        // Interrupted in-flight fire: retry the same fireCount soon.
+                        if (wasInflight) {
+                            updated = Object.assign(Object.assign({}, updated), { nextFireAtMs: Math.min(updated.nextFireAtMs, Date.now()) });
+                        }
+                        yield persist(updated);
+                        if (armReminderClocks) {
+                            armReminder(updated);
+                        }
+                        n += 1;
+                    }
+                    return n;
+                });
+            },
+            applyReminderOutcome,
+            startClocks() {
+                for (const record of reminders.values()) {
+                    if (record.status === "firing") {
+                        // Restart hydration: treat interrupted fires as armed for retry
+                        // even when clocks are not armed (status must still recover).
+                        const restored = Object.assign(Object.assign({}, record), { status: "armed", updatedAt: new Date().toISOString() });
+                        void persist(restored).then(() => {
+                            if (armReminderClocks) {
+                                armReminder(restored);
+                            }
+                        });
+                        continue;
+                    }
+                    if (armReminderClocks && record.status === "armed") {
+                        armReminder(record);
+                    }
+                }
+            },
+            stop() {
+                stopScheduleTicker();
+                for (const id of [...reminderTimers.keys()]) {
+                    clearReminderTimer(id);
+                }
+                inflight.clear();
+                if (scmRelay !== undefined) {
+                    void scmRelay.stop();
+                    scmRelay = undefined;
+                }
+            },
+        };
+    });
+}

package/dist/internal/local-env.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Loads an agent directory's env files (and each immediate child's, for
+ * multi-agent hosts) into process.env. Load order per directory is
+ * `.env.local` then `.env` — `process.loadEnvFile` never overrides, so
+ * real env wins over both, and `.env.local` wins over checked-in `.env`
+ * defaults. Values a previous call loaded are refreshed, so a reload
+ * picks up edits made since.
+ */
+export declare function loadAgentLocalEnv(dir: string): string[];
+//# sourceMappingURL=local-env.d.ts.map

package/dist/internal/local-env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-env.d.ts","sourceRoot":"","sources":["../../src/internal/local-env.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AASH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CA0CvD"}

package/dist/internal/local-env.js

@@ -0,0 +1,55 @@
+/**
+ * Loads an agent directory's env files (and each immediate child's, for
+ * multi-agent hosts) into process.env. Load order per directory is
+ * `.env.local` then `.env` — `process.loadEnvFile` never overrides, so
+ * real env wins over both, and `.env.local` wins over checked-in `.env`
+ * defaults. Values a previous call loaded are refreshed, so a reload
+ * picks up edits made since.
+ */
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+// Not real env, so a reload has to clear them first: loadEnvFile skips
+// anything already in process.env, which would pin the first-boot values.
+let fileLoadedKeys = new Set();
+export function loadAgentLocalEnv(dir) {
+    for (const key of fileLoadedKeys) {
+        delete process.env[key];
+    }
+    const realKeys = new Set(Object.keys(process.env));
+    const loaded = [];
+    const tryLoad = (path) => {
+        if (!existsSync(path)) {
+            return;
+        }
+        process.loadEnvFile(path);
+        loaded.push(path);
+    };
+    const trackLoadedKeys = () => {
+        fileLoadedKeys = new Set(Object.keys(process.env).filter(key => !realKeys.has(key)));
+    };
+    const tryLoadDir = (agentDir) => {
+        // `.env.local` first so its values win over checked-in `.env` defaults
+        // under loadEnvFile's no-override semantics.
+        tryLoad(join(agentDir, ".env.local"));
+        tryLoad(join(agentDir, ".env"));
+    };
+    tryLoadDir(dir);
+    let children;
+    try {
+        children = readdirSync(dir, { withFileTypes: true })
+            .filter(entry => entry.isDirectory() && !entry.name.startsWith("."))
+            .map(entry => entry.name);
+    }
+    catch (_a) {
+        trackLoadedKeys();
+        return loaded;
+    }
+    for (const child of children) {
+        if (child === "node_modules") {
+            continue;
+        }
+        tryLoadDir(join(dir, child));
+    }
+    trackLoadedKeys();
+    return loaded;
+}