@cursor/bdk 0.2.1

package/dist/internal/reminder-runner.js

@@ -0,0 +1,1231 @@
+/**
+ * Per-session reminder runner: durable wake subscriptions with
+ * prompt XOR named handler XOR run, every/cron/delay/at schedules, and
+ * until as function XOR prompt.
+ */
+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 { randomBytes } from "node:crypto";
+import { channelContinuationIdentity, httpContinuationIdentity } from "./continuation-channel.js";
+import { continuationSource } from "./continuation-identity.js";
+import { NAME_PATTERN } from "./discovery/names.js";
+import { parseDuration } from "./duration.js";
+import { REMINDER_CP_PROTOCOL_VERSION, scheduleSpecFromCreateInput, toWireReschedule, } from "./reminder-control-plane-protocol.js";
+import { defaultBusyPolicy, MAX_TIMER_MS, nextCronFireMs, ReminderValidationError, resolveSchedule, } from "./reminder-schedule.js";
+import { APP_AUTH } from "./schedule-runner.js";
+import { HTTP_CHANNEL_ID, SessionAuthError, SessionBusyError, } from "./session-engine.js";
+export { ReminderValidationError } from "./reminder-schedule.js";
+/** Max UTF-8 byte length of `JSON.stringify(args)` on named-handler create. */
+export const REMINDER_ARGS_MAX_BYTES = 32 * 1024;
+export class UnknownReminderError extends Error {
+    constructor(reminderId, availableReminderIds) {
+        super(`Unknown reminder "${reminderId}"`);
+        this.availableReminderIds = availableReminderIds;
+        this.name = "UnknownReminderError";
+    }
+}
+/**
+ * Reschedule applied when a hosted fire cannot open a session (no
+ * principal). A one-shot `skipped` outcome without a reschedule completes
+ * the reminder, which would lose the check-in for good.
+ */
+export const REMINDER_SESSION_OPEN_RETRY_DELAY = "5m";
+export const REMINDER_FIRE_OUTCOME_METRIC = "agent_sdk.reminder.fire_outcome";
+/**
+ * Server wiring for {@link ReminderRunnerOptions.rejectAnonymousHandlers}:
+ * architecture v2 always rejects anonymous run/until (local or hosted).
+ */
+export function rejectAnonymousReminderHandlers(options) {
+    return options.architecture === "v2";
+}
+function newReminderId() {
+    return `rem_${randomBytes(8).toString("hex")}`;
+}
+function isJsonObject(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        Object.values(value).every(isJsonValue));
+}
+function isJsonValue(value) {
+    if (value === null || typeof value === "string" || typeof value === "boolean") {
+        return true;
+    }
+    if (typeof value === "number") {
+        return Number.isFinite(value);
+    }
+    if (Array.isArray(value)) {
+        return value.every(isJsonValue);
+    }
+    return isJsonObject(value);
+}
+/** Same stem rules as `agent/reminders/<name>.ts` discovery. */
+function isValidReminderHandlerName(name) {
+    return NAME_PATTERN.test(name) && !name.includes("__");
+}
+function assertReminderArgsSize(args) {
+    const bytes = Buffer.byteLength(JSON.stringify(args), "utf8");
+    if (bytes > REMINDER_ARGS_MAX_BYTES) {
+        throw new ReminderValidationError(`reminders.create args exceed ${REMINDER_ARGS_MAX_BYTES} bytes (got ${bytes})`);
+    }
+}
+function toInfo(record) {
+    return {
+        id: record.id,
+        purpose: record.purpose,
+        channelId: record.channelId,
+        continuationToken: record.continuationToken,
+        target: record.target,
+        scheduleKind: record.scheduleKind,
+        scheduleValue: record.scheduleValue,
+        prompt: record.prompt,
+        handler: record.handler,
+        args: record.args,
+        untilPrompt: record.untilPrompt,
+        busyPolicy: record.busyPolicy,
+        status: record.status === "firing" ? "armed" : record.status,
+        disarmReason: record.disarmReason,
+        fireCount: record.fireCount,
+        nextFireAt: new Date(record.nextFireAtMs).toISOString(),
+        createdAt: record.createdAt,
+        updatedAt: record.updatedAt,
+        hasRunHandler: record.hasRunHandler === true,
+        hasUntilFn: record.hasUntilFn === true,
+    };
+}
+function stopFire(reason) {
+    return { outcome: { kind: "stop", reason }, reason };
+}
+function runReason(result) {
+    switch (result.action) {
+        case "stop":
+            return "run_stop";
+        case "skip":
+            return "run_skip";
+        case "delivered":
+            return "run_delivered";
+    }
+}
+function buildFirePrompt(record) {
+    var _a;
+    const recurring = record.scheduleKind === "every" || record.scheduleKind === "cron";
+    const lines = [
+        `[reminder] id=${record.id} purpose=${record.purpose}`,
+        (_a = record.prompt) !== null && _a !== void 0 ? _a : "Reminder fired. Check current state and only act if needed.",
+    ];
+    if (record.untilPrompt !== undefined && record.untilPrompt.trim() !== "") {
+        lines.push("", `Stop condition: ${record.untilPrompt}`);
+        if (recurring) {
+            lines.push(`When the stop condition is met, call reminders_cancel with id=${record.id}.`);
+        }
+        else {
+            lines.push("This is a one-shot reminder (auto-completes after this fire); no cancel needed unless you armed a separate recurring reminder.");
+        }
+    }
+    return lines.join("\n");
+}
+export class ReminderRunner {
+    constructor(engine, logger = () => { }, platformTimers, options = {}) {
+        var _a;
+        this.engine = engine;
+        this.logger = logger;
+        this.platformTimers = platformTimers;
+        this.records = new Map();
+        this.handlers = new Map();
+        this.namedHandlers = new Map();
+        this.namedHandlerNames = new Map();
+        this.timers = new Map();
+        this.firing = new Set();
+        /** Single-flight idle gates keyed by `channelId:continuationToken`. */
+        this.idleGates = new Map();
+        this.started = false;
+        /**
+         * A control-plane read failure is logged once per outage, not per call.
+         * The next successful read re-arms the log.
+         */
+        this.controlPlaneReadFailureLogged = false;
+        this.rejectAnonymousHandlers = options.rejectAnonymousHandlers === true;
+        this.controlPlane = options.controlPlane;
+        this.architecture = options.architecture;
+        this.hostedGuest = options.hostedGuest;
+        for (const reminder of (_a = options.namedHandlers) !== null && _a !== void 0 ? _a : []) {
+            this.namedHandlers.set(reminder.name, reminder.definition);
+            this.namedHandlerNames.set(reminder.definition, reminder.name);
+        }
+    }
+    /** True when create/cancel/rekey/fire go through the CP protocol. */
+    get usesControlPlaneProtocol() {
+        return this.controlPlane !== undefined && this.architecture === "v2";
+    }
+    /**
+     * Where reminder documents are read from. Under the CP protocol that is
+     * the v2 control-plane client; the v1 timed-work route answers 405 for a
+     * v2 deployment, which used to leave `list()` with only this process's
+     * in-memory map (breaking arm idempotence and `cancelForContinuation`).
+     */
+    get reminderReader() {
+        if (this.usesControlPlaneProtocol) {
+            return this.controlPlane;
+        }
+        return this.platformTimers;
+    }
+    logControlPlaneReadFailure(what, error) {
+        if (this.usesControlPlaneProtocol && this.controlPlaneReadFailureLogged) {
+            return;
+        }
+        this.controlPlaneReadFailureLogged = true;
+        this.logger(`[agent-sdk] reminders: control-plane ${what} failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    /**
+     * Load reminder documents from the control plane into memory. Does not
+     * arm in-process timers — the CP owns clocks.
+     */
+    hydrate() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const reader = this.reminderReader;
+            if (reader === undefined) {
+                return;
+            }
+            let remote = [];
+            try {
+                remote = yield reader.listReminders();
+            }
+            catch (error) {
+                this.logControlPlaneReadFailure("list", error);
+                return;
+            }
+            this.controlPlaneReadFailureLogged = false;
+            this.records.clear();
+            for (const record of remote) {
+                this.records.set(record.id, record);
+            }
+            if (this.usesControlPlaneProtocol) {
+                // The CP owns status; a fire whose handler is missing reports `stop`
+                // from executeFire instead of the guest writing a disarm.
+                if (remote.length > 0) {
+                    this.logger(`[agent-sdk] reminders: hydrated ${remote.length} reminder(s) from control plane`);
+                }
+                return;
+            }
+            let disarmedOrphan = 0;
+            for (const record of [...this.records.values()]) {
+                if (record.status !== "armed") {
+                    continue;
+                }
+                if (record.handler !== undefined) {
+                    if (this.namedHandlers.get(record.handler) === undefined) {
+                        yield this.disarm(record, "handler_missing");
+                        disarmedOrphan += 1;
+                    }
+                    continue;
+                }
+                if ((record.hasRunHandler === true || record.hasUntilFn === true) &&
+                    this.handlers.get(record.id) === undefined) {
+                    yield this.disarm(record, "handler_lost_on_restart");
+                    disarmedOrphan += 1;
+                }
+            }
+            if (remote.length > 0 || disarmedOrphan > 0) {
+                this.logger(`[agent-sdk] reminders: hydrated ${remote.length} reminder(s) from control plane` +
+                    (disarmedOrphan > 0 ? `; disarmed ${disarmedOrphan} without live handlers` : ""));
+            }
+        });
+    }
+    /** Start deadline timers for armed reminders (tests / no control plane). */
+    start() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.started)
+                return;
+            this.started = true;
+            yield this.hydrate();
+            if (this.platformTimers !== undefined) {
+                return;
+            }
+            const armed = [...this.records.values()].filter(r => r.status === "armed");
+            let restored = 0;
+            let disarmedOrphan = 0;
+            for (const record of armed) {
+                if (record.handler !== undefined) {
+                    if (this.namedHandlers.get(record.handler) === undefined) {
+                        yield this.disarm(record, "handler_missing");
+                        disarmedOrphan += 1;
+                        continue;
+                    }
+                    this.armTimer(record);
+                    restored += 1;
+                    continue;
+                }
+                if ((record.hasRunHandler === true || record.hasUntilFn === true) &&
+                    this.handlers.get(record.id) === undefined) {
+                    yield this.disarm(record, "handler_lost_on_restart");
+                    disarmedOrphan += 1;
+                    continue;
+                }
+                this.armTimer(record);
+                restored += 1;
+            }
+            if (restored > 0 || disarmedOrphan > 0) {
+                this.logger(`[agent-sdk] reminders: restored ${restored} armed reminder(s)` +
+                    (disarmedOrphan > 0 ? `; disarmed ${disarmedOrphan} without live handlers` : ""));
+            }
+        });
+    }
+    persist(record) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.platformTimers !== undefined) {
+                yield this.platformTimers.putReminder(record);
+            }
+            this.records.set(record.id, record);
+        });
+    }
+    getRecord(id) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const reader = this.reminderReader;
+            if (reader !== undefined) {
+                try {
+                    const remote = yield reader.getReminder(id);
+                    this.controlPlaneReadFailureLogged = false;
+                    if (remote === undefined) {
+                        this.records.delete(id);
+                        return undefined;
+                    }
+                    this.records.set(id, remote);
+                    return remote;
+                }
+                catch (error) {
+                    this.logControlPlaneReadFailure(`get for ${id}`, error);
+                    return this.records.get(id);
+                }
+            }
+            return this.records.get(id);
+        });
+    }
+    /**
+     * Under the CP protocol a list failure propagates: the in-memory map is
+     * only what this process created, and returning it would let a caller
+     * arm duplicates or miss rows to cancel. v1 keeps the best-effort form.
+     */
+    allRecords() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const reader = this.reminderReader;
+            if (reader !== undefined) {
+                try {
+                    const remote = yield reader.listReminders();
+                    this.controlPlaneReadFailureLogged = false;
+                    this.records.clear();
+                    for (const record of remote) {
+                        this.records.set(record.id, record);
+                    }
+                }
+                catch (error) {
+                    this.logControlPlaneReadFailure("list", error);
+                    if (this.usesControlPlaneProtocol) {
+                        throw error;
+                    }
+                }
+            }
+            return [...this.records.values()];
+        });
+    }
+    stop() {
+        this.started = false;
+        for (const timer of this.timers.values()) {
+            clearTimeout(timer);
+        }
+        this.timers.clear();
+        this.idleGates.clear();
+    }
+    create(input) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            const hasPrompt = input.prompt !== undefined;
+            const hasRun = input.run !== undefined;
+            const hasHandler = input.handler !== undefined;
+            const formCount = [hasPrompt, hasRun, hasHandler].filter(Boolean).length;
+            if (formCount !== 1) {
+                throw new ReminderValidationError("reminders.create requires exactly one of prompt, handler, or run");
+            }
+            if (input.continuationToken.trim() === "") {
+                throw new ReminderValidationError("continuationToken is required");
+            }
+            if (input.channelId.trim() === "") {
+                throw new ReminderValidationError("channelId is required");
+            }
+            if (input.purpose.trim() === "") {
+                throw new ReminderValidationError("purpose is required");
+            }
+            const untilPrompt = typeof input.until === "string" ? input.until : undefined;
+            const untilFn = typeof input.until === "function" ? input.until : undefined;
+            if (hasHandler && input.until !== undefined) {
+                throw new ReminderValidationError("reminders.create: until is not valid with handler; encode the stop condition in args and the handler body");
+            }
+            if (this.rejectAnonymousHandlers) {
+                if (hasRun) {
+                    throw new ReminderValidationError("reminders.create: anonymous run handlers are not durable on architecture v2; author reminders/<name>.ts under the project root and pass handler + args");
+                }
+                if (untilFn !== undefined) {
+                    throw new ReminderValidationError("reminders.create: function until is not durable on architecture v2; use a string until prompt");
+                }
+            }
+            let handlerName;
+            let handlerArgs;
+            if (hasHandler) {
+                const handler = input.handler;
+                const name = typeof handler === "string" ? handler.trim() : this.namedHandlerNames.get(handler);
+                if (name === undefined) {
+                    throw new ReminderValidationError("Unknown reminder handler definition (expected a default export discovered under reminders/)");
+                }
+                if (name === "") {
+                    throw new ReminderValidationError("handler name is required");
+                }
+                if (!isValidReminderHandlerName(name)) {
+                    throw new ReminderValidationError(name.includes("__")
+                        ? `Invalid reminder handler name "${name}": may not contain "__"`
+                        : `Invalid reminder handler name "${name}": must match ${NAME_PATTERN}`);
+                }
+                if (this.namedHandlers.get(name) === undefined) {
+                    throw new ReminderValidationError(`Unknown reminder handler "${name}" (expected reminders/${name}.ts under the project root)`);
+                }
+                if (input.args !== undefined && !isJsonObject(input.args)) {
+                    throw new ReminderValidationError("reminders.create args must be a JSON object");
+                }
+                handlerName = name;
+                handlerArgs = (_a = input.args) !== null && _a !== void 0 ? _a : {};
+                assertReminderArgsSize(handlerArgs);
+            }
+            else if (input.args !== undefined) {
+                throw new ReminderValidationError("reminders.create args is only valid with handler");
+            }
+            const schedule = resolveSchedule(input);
+            const busyPolicy = (_b = input.busyPolicy) !== null && _b !== void 0 ? _b : defaultBusyPolicy(schedule.kind);
+            const hasRunHandler = input.run !== undefined;
+            const hasUntilFn = untilFn !== undefined;
+            let record;
+            if (this.usesControlPlaneProtocol) {
+                const intent = {
+                    protocolVersion: REMINDER_CP_PROTOCOL_VERSION,
+                    purpose: input.purpose,
+                    channelId: input.channelId,
+                    continuationToken: input.continuationToken,
+                    target: input.target,
+                    // CP recalculates nextFireAtMs / intervalMs from the raw schedule.
+                    schedule: scheduleSpecFromCreateInput(input),
+                    prompt: input.prompt,
+                    handler: handlerName,
+                    args: handlerArgs,
+                    hasRunHandler,
+                    hasUntilFn,
+                    untilPrompt,
+                    busyPolicy,
+                };
+                record = yield this.controlPlane.createReminder(intent);
+                this.records.set(record.id, record);
+            }
+            else {
+                const now = new Date().toISOString();
+                const id = newReminderId();
+                record = {
+                    version: 1,
+                    id,
+                    purpose: input.purpose,
+                    channelId: input.channelId,
+                    continuationToken: input.continuationToken,
+                    target: input.target,
+                    scheduleKind: schedule.kind,
+                    scheduleValue: schedule.value,
+                    intervalMs: schedule.intervalMs,
+                    prompt: input.prompt,
+                    handler: handlerName,
+                    args: handlerArgs,
+                    hasRunHandler,
+                    hasUntilFn,
+                    untilPrompt,
+                    busyPolicy,
+                    status: "armed",
+                    fireCount: 0,
+                    nextFireAtMs: schedule.nextFireAtMs,
+                    generation: 0,
+                    createdAt: now,
+                    updatedAt: now,
+                };
+                yield this.persist(record);
+            }
+            this.handlers.set(record.id, {
+                run: input.run,
+                untilFn,
+            });
+            if (this.started && this.platformTimers === undefined && !this.usesControlPlaneProtocol) {
+                this.armTimer(record);
+            }
+            return toInfo(record);
+        });
+    }
+    list(filter) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const all = yield this.allRecords();
+            return all
+                .filter(r => {
+                if ((filter === null || filter === void 0 ? void 0 : filter.status) !== undefined) {
+                    const publicStatus = r.status === "firing" ? "armed" : r.status;
+                    if (publicStatus !== filter.status) {
+                        return false;
+                    }
+                }
+                if ((filter === null || filter === void 0 ? void 0 : filter.purpose) !== undefined && r.purpose !== filter.purpose) {
+                    return false;
+                }
+                if ((filter === null || filter === void 0 ? void 0 : filter.continuationToken) !== undefined &&
+                    r.continuationToken !== filter.continuationToken) {
+                    return false;
+                }
+                return true;
+            })
+                .map(r => {
+                const live = this.handlers.get(r.id);
+                const info = toInfo(r);
+                if (live === undefined)
+                    return info;
+                return Object.assign(Object.assign({}, info), { hasRunHandler: live.run !== undefined || info.hasRunHandler, hasUntilFn: live.untilFn !== undefined || info.hasUntilFn });
+            });
+        });
+    }
+    cancel(id_1) {
+        return __awaiter(this, arguments, void 0, function* (id, reason = "explicit_cancel") {
+            var _a;
+            if (this.usesControlPlaneProtocol) {
+                const updated = yield this.controlPlane.cancelReminder(id, reason);
+                if (updated === undefined) {
+                    this.records.delete(id);
+                    this.handlers.delete(id);
+                    return undefined;
+                }
+                this.records.set(id, updated);
+                this.handlers.delete(id);
+                return toInfo(updated);
+            }
+            const record = yield this.getRecord(id);
+            if (record === undefined) {
+                return undefined;
+            }
+            if (record.status !== "armed" && record.status !== "firing") {
+                return toInfo(record);
+            }
+            this.clearTimer(id);
+            const updated = Object.assign(Object.assign({}, record), { status: "cancelled", disarmReason: reason, generation: ((_a = record.generation) !== null && _a !== void 0 ? _a : 0) + 1, updatedAt: new Date().toISOString() });
+            yield this.persist(updated);
+            this.handlers.delete(id);
+            return toInfo(updated);
+        });
+    }
+    /** Cancel all armed reminders matching a continuation token (e.g. PR closed). */
+    cancelForContinuation(continuationToken, reason) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const armed = (yield this.allRecords()).filter(r => r.status === "armed");
+            let n = 0;
+            for (const record of armed) {
+                if (record.continuationToken === continuationToken) {
+                    yield this.cancel(record.id, reason);
+                    n += 1;
+                }
+            }
+            return n;
+        });
+    }
+    /**
+     * Re-key armed reminders when a channel rotates a session's continuation
+     * token (the built-in HTTP channel rotates after every follow-up). Without
+     * this, a reminder armed before the rotation misses its session at fire
+     * time and disarms as `session_gone`.
+     */
+    rekeyContinuation(channelId, oldToken, newToken) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            if (this.usesControlPlaneProtocol) {
+                return this.controlPlane.rekeyReminders(channelId, oldToken, newToken);
+            }
+            const armed = (yield this.allRecords()).filter(r => r.status === "armed" || r.status === "firing");
+            let n = 0;
+            for (const record of armed) {
+                if (record.channelId !== channelId || record.continuationToken !== oldToken) {
+                    continue;
+                }
+                yield this.persist(Object.assign(Object.assign({}, record), { continuationToken: newToken, generation: ((_a = record.generation) !== null && _a !== void 0 ? _a : 0) + 1, updatedAt: new Date().toISOString() }));
+                n += 1;
+            }
+            return n;
+        });
+    }
+    /** Fire one reminder immediately (dev / hillclimb / control plane). */
+    dispatch(reminderId_1) {
+        return __awaiter(this, arguments, void 0, function* (reminderId, opts = {}) {
+            const record = yield this.getRecord(reminderId);
+            if (record === undefined) {
+                const ids = (yield this.allRecords()).map(r => r.id);
+                throw new UnknownReminderError(reminderId, ids);
+            }
+            if (opts.expectedFireCount !== undefined && record.fireCount !== opts.expectedFireCount) {
+                return {
+                    reminderId,
+                    outcome: "noop",
+                    reason: "stale_fire_count",
+                };
+            }
+            const result = yield this.fire(record.id, { force: true });
+            return Object.assign({ reminderId }, result);
+        });
+    }
+    /**
+     * Architecture v2 / CP protocol guest entrypoint: execute an immutable fire
+     * descriptor and return an outcome. Does not mint ids or mutate
+     * authoritative status/fireCount — the control plane applies the outcome.
+     */
+    executeFire(descriptor) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const record = this.recordFromDescriptor(descriptor);
+            this.records.set(record.id, record);
+            let fire;
+            try {
+                fire = yield this.runFire(record);
+            }
+            catch (error) {
+                // The hosted admission maps the throw to a retryable failure; count
+                // it so the retry loop is visible beside the settled outcomes.
+                this.recordFireOutcome(record, {
+                    kind: "error",
+                    reason: "fire_threw",
+                    detail: error instanceof Error ? error.message : String(error),
+                });
+                throw error;
+            }
+            this.recordFireOutcome(record, {
+                kind: fire.outcome.kind,
+                reason: fire.reason,
+                turnStatus: fire.turnStatus,
+            });
+            return fire.outcome;
+        });
+    }
+    runFire(record) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const live = (_a = this.handlers.get(record.id)) !== null && _a !== void 0 ? _a : {};
+            if (record.handler !== undefined) {
+                if (this.resolveNamedHandler(record.handler) === undefined) {
+                    return stopFire("handler_missing");
+                }
+            }
+            else if ((record.hasRunHandler === true || record.hasUntilFn === true) &&
+                live.run === undefined &&
+                live.untilFn === undefined) {
+                return stopFire("handler_lost_on_restart");
+            }
+            if (live.untilFn !== undefined) {
+                try {
+                    const done = yield live.untilFn(this.buildUntilContext(record));
+                    if (done) {
+                        return stopFire("until_fn");
+                    }
+                }
+                catch (error) {
+                    this.logger(`[agent-sdk] reminder "${record.id}" until() failed: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+            if (yield this.isSessionBusy(record.channelId, record.continuationToken)) {
+                if (record.busyPolicy === "skipIfBusy") {
+                    return { outcome: { kind: "skipped" }, reason: "busy" };
+                }
+                yield this.whenSessionIdle(record.channelId, record.continuationToken);
+            }
+            let result;
+            let reason;
+            let turnStatus;
+            if (record.handler !== undefined) {
+                const named = this.resolveNamedHandler(record.handler);
+                if (named === undefined) {
+                    return stopFire("handler_missing");
+                }
+                result = yield named.run(this.buildFireContext(record));
+                reason = runReason(result);
+            }
+            else if (live.run !== undefined) {
+                result = yield live.run(this.buildFireContext(record));
+                reason = runReason(result);
+            }
+            else if (record.prompt !== undefined) {
+                const delivery = yield this.deliverPromptFire(record);
+                result = delivery.result;
+                reason = delivery.reason;
+                turnStatus = delivery.turnStatus;
+            }
+            else {
+                return stopFire("missing_handler");
+            }
+            if (result.action === "stop") {
+                return { outcome: { kind: "stop", reason }, reason };
+            }
+            const reschedule = result.reschedule !== undefined ? toWireReschedule(result.reschedule) : undefined;
+            return {
+                outcome: {
+                    kind: result.action === "skip" ? "skipped" : "delivered",
+                    reschedule,
+                },
+                reason,
+                turnStatus,
+            };
+        });
+    }
+    /**
+     * One structured line and one `agent_sdk.reminder.fire_outcome` count per
+     * fire. Emitted through the host OTel meter, the same path hosted v2
+     * exports turn/tool metrics on, so a fire that ends in `stop` is visible
+     * beside the control plane's `timed_work.fire` count.
+     */
+    recordFireOutcome(record, fire) {
+        this.logger(`[agent-sdk] reminder fire_outcome kind=${fire.kind} reason=${fire.reason}` +
+            ` reminderId=${record.id} purpose=${record.purpose}` +
+            ` channelId=${record.channelId} fireCount=${record.fireCount}` +
+            (fire.turnStatus === undefined ? "" : ` turn=${fire.turnStatus}`) +
+            (fire.detail === undefined ? "" : ` detail=${JSON.stringify(fire.detail)}`));
+        // Test doubles may omit `host.otel`; the metric is best-effort.
+        const otel = this.engine.host.otel;
+        if (otel === undefined) {
+            return;
+        }
+        try {
+            otel.increment(REMINDER_FIRE_OUTCOME_METRIC, {
+                kind: fire.kind,
+                reason: fire.reason,
+                purpose: record.purpose,
+            });
+        }
+        catch (error) {
+            this.logger(`[agent-sdk] reminder fire_outcome metric failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    recordFromDescriptor(descriptor) {
+        const now = new Date().toISOString();
+        return {
+            version: 1,
+            id: descriptor.id,
+            purpose: descriptor.purpose,
+            channelId: descriptor.channelId,
+            continuationToken: descriptor.continuationToken,
+            target: descriptor.target,
+            scheduleKind: descriptor.scheduleKind,
+            scheduleValue: descriptor.scheduleValue,
+            intervalMs: descriptor.intervalMs,
+            prompt: descriptor.prompt,
+            handler: descriptor.handler,
+            args: descriptor.args,
+            hasRunHandler: descriptor.hasRunHandler,
+            hasUntilFn: descriptor.hasUntilFn,
+            untilPrompt: descriptor.untilPrompt,
+            busyPolicy: descriptor.busyPolicy,
+            status: "firing",
+            fireCount: descriptor.fireCount,
+            nextFireAtMs: descriptor.nextFireAtMs,
+            generation: descriptor.generation,
+            createdAt: now,
+            updatedAt: now,
+        };
+    }
+    armTimer(record) {
+        var _a;
+        this.clearTimer(record.id);
+        if (!this.started || record.status !== "armed")
+            return;
+        const nextFireAtMs = Number.isFinite(record.nextFireAtMs) ? record.nextFireAtMs : Date.now();
+        const delay = Math.min(MAX_TIMER_MS, Math.max(0, nextFireAtMs - Date.now()));
+        const timer = setTimeout(() => {
+            void this.fire(record.id).catch((error) => __awaiter(this, void 0, void 0, function* () {
+                this.logger(`[agent-sdk] reminder "${record.id}" fire failed: ${error instanceof Error ? error.message : String(error)}`);
+                // Keep recurring reminders alive after unexpected throws.
+                // One-shots stay armed so a failed wake can be retried / dispatched.
+                try {
+                    const current = yield this.getRecord(record.id);
+                    if (current === undefined || current.status !== "armed")
+                        return;
+                    const oneShot = current.scheduleKind === "delay" || current.scheduleKind === "at";
+                    if (oneShot) {
+                        this.armTimer(current);
+                        return;
+                    }
+                    yield this.afterFire(current, "skip");
+                }
+                catch (rescheduleError) {
+                    this.logger(`[agent-sdk] reminder "${record.id}" reschedule after failure failed: ${rescheduleError instanceof Error ? rescheduleError.message : String(rescheduleError)}`);
+                }
+            }));
+        }, delay);
+        (_a = timer.unref) === null || _a === void 0 ? void 0 : _a.call(timer);
+        this.timers.set(record.id, timer);
+    }
+    clearTimer(id) {
+        const timer = this.timers.get(id);
+        if (timer !== undefined) {
+            clearTimeout(timer);
+            this.timers.delete(id);
+        }
+    }
+    resolveNamedHandler(name) {
+        return this.namedHandlers.get(name);
+    }
+    fire(id_1) {
+        return __awaiter(this, arguments, void 0, function* (id, opts = {}) {
+            var _a, _b;
+            if (this.firing.has(id)) {
+                return { outcome: "noop", reason: "already_firing" };
+            }
+            this.firing.add(id);
+            try {
+                const record = yield this.getRecord(id);
+                if (record === undefined || record.status !== "armed") {
+                    this.clearTimer(id);
+                    return { outcome: "noop", reason: "not_armed" };
+                }
+                if (!opts.force && record.nextFireAtMs > Date.now() + 50) {
+                    // Spurious early wake — re-arm.
+                    this.armTimer(record);
+                    return { outcome: "noop", reason: "not_due" };
+                }
+                const live = (_a = this.handlers.get(id)) !== null && _a !== void 0 ? _a : {};
+                if (record.handler !== undefined) {
+                    if (this.resolveNamedHandler(record.handler) === undefined) {
+                        yield this.disarm(record, "handler_missing");
+                        return { outcome: "noop", reason: "handler_missing" };
+                    }
+                }
+                else if ((record.hasRunHandler === true || record.hasUntilFn === true) &&
+                    live.run === undefined &&
+                    live.untilFn === undefined) {
+                    yield this.disarm(record, "handler_lost_on_restart");
+                    return { outcome: "noop", reason: "handler_lost_on_restart" };
+                }
+                const untilCtx = this.buildUntilContext(record);
+                if (live.untilFn !== undefined) {
+                    try {
+                        const done = yield live.untilFn(untilCtx);
+                        if (done) {
+                            yield this.disarm(record, "until_fn");
+                            return { outcome: "fired", reason: "until_fn" };
+                        }
+                    }
+                    catch (error) {
+                        this.logger(`[agent-sdk] reminder "${id}" until() failed: ${error instanceof Error ? error.message : String(error)}`);
+                    }
+                }
+                if (yield this.isSessionBusy(record.channelId, record.continuationToken)) {
+                    if (record.busyPolicy === "skipIfBusy") {
+                        yield this.afterFire(record, "skip");
+                        this.logger(`[agent-sdk] reminder "${id}" (${record.purpose}) skipped: session busy`);
+                        return { outcome: "fired", reason: "skipped_busy" };
+                    }
+                    yield this.whenSessionIdle(record.channelId, record.continuationToken);
+                    const still = yield this.getRecord(id);
+                    if (still === undefined || still.status !== "armed") {
+                        return { outcome: "noop", reason: "disarmed_while_waiting" };
+                    }
+                }
+                let result;
+                if (record.handler !== undefined) {
+                    const named = this.resolveNamedHandler(record.handler);
+                    if (named === undefined) {
+                        yield this.disarm(record, "handler_missing");
+                        return { outcome: "noop", reason: "handler_missing" };
+                    }
+                    result = yield named.run(this.buildFireContext(record));
+                }
+                else if (live.run !== undefined) {
+                    result = yield live.run(this.buildFireContext(record));
+                }
+                else if (record.prompt !== undefined) {
+                    result = yield this.deliverPrompt(record);
+                }
+                else {
+                    yield this.disarm(record, "missing_handler");
+                    return { outcome: "noop", reason: "missing_handler" };
+                }
+                // Cancel / disarm during the handler must win over reschedule.
+                const latest = yield this.getRecord(id);
+                if (result.action === "stop") {
+                    if (latest !== undefined && latest.status === "armed") {
+                        yield this.disarm(latest, "run_stop");
+                        this.logger(`[agent-sdk] reminder "${id}" (${record.purpose}) disarmed: run_stop`);
+                        return { outcome: "fired", reason: "run_stop" };
+                    }
+                    return {
+                        outcome: "fired",
+                        reason: (_b = latest === null || latest === void 0 ? void 0 : latest.disarmReason) !== null && _b !== void 0 ? _b : "run_stop",
+                    };
+                }
+                if (latest === undefined || latest.status !== "armed") {
+                    return { outcome: "noop", reason: "disarmed_during_fire" };
+                }
+                if (result.action === "skip") {
+                    yield this.afterFire(latest, "skip", result.reschedule);
+                    this.logger(`[agent-sdk] reminder "${id}" (${record.purpose}) skipped`);
+                    return { outcome: "fired", reason: "skipped" };
+                }
+                yield this.afterFire(latest, "delivered", result.reschedule);
+                this.logger(`[agent-sdk] reminder "${id}" (${record.purpose}) fired`);
+                return { outcome: "fired", reason: "delivered" };
+            }
+            finally {
+                this.firing.delete(id);
+            }
+        });
+    }
+    isSessionBusy(channelId, continuationToken) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const existing = yield this.engine.sessions.findByContinuation(channelId, continuationToken);
+            if (existing === undefined)
+                return false;
+            return this.engine.isTurnRunning(existing.sessionId);
+        });
+    }
+    whenSessionIdle(channelId, continuationToken) {
+        const sessionKey = `${channelId}:${continuationToken}`;
+        const existing = this.idleGates.get(sessionKey);
+        if (existing !== undefined)
+            return existing;
+        const gate = (() => __awaiter(this, void 0, void 0, function* () {
+            const session = yield this.engine.sessions.findByContinuation(channelId, continuationToken);
+            if (session === undefined)
+                return;
+            yield this.engine.waitForCompletion(session.sessionId);
+        }))().finally(() => {
+            this.idleGates.delete(sessionKey);
+        });
+        this.idleGates.set(sessionKey, gate);
+        return gate;
+    }
+    /**
+     * Follow-ups must use the bound session's principal. If the session is gone,
+     * disarm rather than creating a fresh APP_AUTH conversation.
+     */
+    resolveFollowupAuth(channelId, continuationToken) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const existing = yield this.engine.sessions.findByContinuation(channelId, continuationToken);
+            if (existing !== undefined) {
+                return existing.auth;
+            }
+            return undefined;
+        });
+    }
+    deliverPrompt(record) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return (yield this.deliverPromptFire(record)).result;
+        });
+    }
+    /**
+     * Where a prompt fire joins. The pod's own store first; on a hosted guest
+     * the durable mirror next, because the pod that armed the reminder is
+     * usually gone and the session lives only in storage. A restored session
+     * keeps its own principal (channel admissions may carry a sender), so the
+     * fire joins under that, never under {@link ReminderHostedGuestOptions.fireAuth}.
+     */
+    resolveFollowupTarget(record) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const local = yield this.resolveFollowupAuth(record.channelId, record.continuationToken);
+            if (local !== undefined) {
+                return { auth: local, reached: "session_joined" };
+            }
+            if (this.hostedGuest === undefined) {
+                return { auth: undefined, reached: "session_gone" };
+            }
+            // Materializes the durable record locally; a storage error propagates
+            // and the hosted admission retries the fire.
+            const restored = yield this.engine.hasContinuationSession(record.channelId, record.continuationToken);
+            if (!restored) {
+                return { auth: undefined, reached: "session_gone" };
+            }
+            const auth = yield this.resolveFollowupAuth(record.channelId, record.continuationToken);
+            return auth === undefined
+                ? { auth: undefined, reached: "session_unreadable" }
+                : { auth, reached: "session_restored" };
+        });
+    }
+    deliverPromptFire(record) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const target = yield this.resolveFollowupTarget(record);
+            if (target.auth !== undefined) {
+                return this.promptDelivery(record, target.auth, target.reached);
+            }
+            if (target.reached === "session_unreadable") {
+                this.logger(`[agent-sdk] reminder "${record.id}" (${record.purpose}) durable session did not materialize locally; not opening a new one`);
+                return { result: { action: "stop" }, reason: "session_gone" };
+            }
+            if (this.hostedGuest !== undefined &&
+                this.channelUsesControlPlaneContinuation(record.channelId)) {
+                // No session on this pod and none in durable storage. Open one on the
+                // stored key the way an inbound event on a fresh key does, instead of
+                // consuming the fire with no turn.
+                const fireAuth = this.hostedGuest.fireAuth();
+                if (fireAuth === undefined) {
+                    return {
+                        result: {
+                            action: "skip",
+                            reschedule: { delay: REMINDER_SESSION_OPEN_RETRY_DELAY },
+                        },
+                        reason: "session_gone",
+                    };
+                }
+                try {
+                    return yield this.promptDelivery(record, fireAuth, "session_opened");
+                }
+                catch (error) {
+                    if (!(error instanceof SessionAuthError)) {
+                        throw error;
+                    }
+                    // A session landed on this key under another principal between the
+                    // lookup and the send. That does not change on retry, so stop
+                    // rather than let the control plane re-admit until its attempt cap.
+                    this.logger(`[agent-sdk] reminder "${record.id}" (${record.purpose}) cannot join session on its continuation: ${error.message}`);
+                    return { result: { action: "stop" }, reason: "session_gone" };
+                }
+            }
+            // Under CP protocol, return stop and let the CP apply/CAS; do not
+            // mutate authoritative status from the guest mid-fire.
+            if (!this.usesControlPlaneProtocol) {
+                yield this.disarm(record, "session_gone");
+            }
+            return { result: { action: "stop" }, reason: "session_gone" };
+        });
+    }
+    promptDelivery(record, auth, delivered) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const settle = {};
+            const result = yield this.sendFollowup(record, buildFirePrompt(record), auth, settle);
+            return {
+                result,
+                reason: result.action === "skip" ? ((_a = settle.skipReason) !== null && _a !== void 0 ? _a : "busy") : delivered,
+                turnStatus: settle.turnStatus,
+            };
+        });
+    }
+    /**
+     * Join the reminder's existing session. Control-plane (`/v2`) channels
+     * refuse authored `continuationToken`; pass the stored key as
+     * {@link EngineSendOptions.mailboxContinuation} so the engine reuses the
+     * CP-selected identity without channel admission.
+     */
+    followupSendOptions(record, auth) {
+        if (this.channelUsesControlPlaneContinuation(record.channelId)) {
+            return {
+                auth,
+                mailboxContinuation: { key: record.continuationToken },
+            };
+        }
+        return {
+            auth,
+            continuationToken: record.continuationToken,
+        };
+    }
+    channelUsesControlPlaneContinuation(channelId) {
+        var _a;
+        const project = this.engine.project;
+        // Test doubles may omit `project`; keep the legacy continuationToken path.
+        if (project === undefined) {
+            return false;
+        }
+        const identity = channelId === HTTP_CHANNEL_ID
+            ? httpContinuationIdentity(project.httpChannel)
+            : channelContinuationIdentity((_a = project.channels.find(channel => channel.id === channelId)) === null || _a === void 0 ? void 0 : _a.definition);
+        return continuationSource(identity) === "control-plane";
+    }
+    /**
+     * Local and v1 track the turn in the background: the process outlives the
+     * fire. A hosted v2 guest waits for the turn and its durable writes first,
+     * because the control plane may stop the pod as soon as the fire's
+     * outcome is applied, and `delivered` must mean the turn ran.
+     */
+    settleFollowup(session, settle) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const completion = this.engine.waitForCompletion(session.id);
+            if (this.hostedGuest === undefined) {
+                this.engine.trackBackground(completion);
+                return;
+            }
+            const outcome = yield completion;
+            yield this.engine.drainSessionDurability(session.id);
+            if (settle !== undefined) {
+                settle.turnStatus = outcome.status;
+            }
+        });
+    }
+    sendFollowup(record, message, auth, settle, extra) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const sendOptions = Object.assign(Object.assign({}, this.followupSendOptions(record, auth)), { state: extra === null || extra === void 0 ? void 0 : extra.state, refreshState: extra === null || extra === void 0 ? void 0 : extra.refreshState, title: extra === null || extra === void 0 ? void 0 : extra.title, clearCloudOverride: extra === null || extra === void 0 ? void 0 : extra.clearCloudOverride });
+            try {
+                const session = yield this.engine.send(record.channelId, message, sendOptions);
+                yield this.settleFollowup(session, settle);
+                return { action: "delivered" };
+            }
+            catch (error) {
+                if (error instanceof SessionBusyError) {
+                    if (record.busyPolicy === "skipIfBusy") {
+                        if (settle !== undefined) {
+                            settle.skipReason = "busy";
+                        }
+                        return { action: "skip" };
+                    }
+                    yield this.whenSessionIdle(record.channelId, record.continuationToken);
+                    try {
+                        const session = yield this.engine.send(record.channelId, message, sendOptions);
+                        yield this.settleFollowup(session, settle);
+                        return { action: "delivered" };
+                    }
+                    catch (retryError) {
+                        this.logger(`[agent-sdk] reminder "${record.id}" followup failed after wait: ${retryError instanceof Error ? retryError.message : String(retryError)}`);
+                        if (settle !== undefined) {
+                            settle.skipReason = "followup_failed";
+                        }
+                        return { action: "skip" };
+                    }
+                }
+                throw error;
+            }
+        });
+    }
+    buildFireContext(record) {
+        var _a, _b;
+        const self = this;
+        return {
+            id: record.id,
+            purpose: record.purpose,
+            fireCount: record.fireCount,
+            target: Object.assign({ channelId: record.channelId, continuationToken: record.continuationToken }, ((_a = record.target) !== null && _a !== void 0 ? _a : {})),
+            args: (_b = record.args) !== null && _b !== void 0 ? _b : {},
+            host: this.engine.host,
+            mcp: this.engine.host.mcp,
+            appAuth: APP_AUTH,
+            artifacts: this.engine.artifacts,
+            followup(args) {
+                return __awaiter(this, void 0, void 0, function* () {
+                    const target = yield self.resolveFollowupTarget(record);
+                    let auth = target.auth;
+                    // `openAuth` opens only when nothing exists anywhere: an unreadable
+                    // durable session must not be shadowed by a second one on the same
+                    // key (prompt-fire parity).
+                    if (auth === undefined &&
+                        target.reached === "session_gone" &&
+                        args.openAuth !== undefined) {
+                        auth = args.openAuth;
+                    }
+                    if (auth === undefined) {
+                        // Under the CP protocol the guest never writes reminder status;
+                        // the fire's `stop` outcome carries the reason instead.
+                        if (!self.usesControlPlaneProtocol) {
+                            yield self.disarm(record, "session_gone");
+                        }
+                        throw new Error(`Reminder "${record.id}" followup: session gone for continuation`);
+                    }
+                    const result = yield self.sendFollowup(record, args.message, auth, undefined, args);
+                    if (result.action === "skip") {
+                        throw new Error(`Reminder "${record.id}" followup skipped: session busy`);
+                    }
+                    const existing = yield self.engine.sessions.findByContinuation(record.channelId, record.continuationToken);
+                    if (existing === undefined) {
+                        throw new Error(`Reminder "${record.id}" followup: session not found for continuation`);
+                    }
+                    const session = yield self.engine.getChannelSession(record.channelId, existing.sessionId);
+                    if (session === null) {
+                        throw new Error(`Reminder "${record.id}" followup: channel session missing`);
+                    }
+                    return session;
+                });
+            },
+            cancel() {
+                return __awaiter(this, arguments, void 0, function* (reason = "handler_cancel") {
+                    yield self.cancel(record.id, reason);
+                });
+            },
+        };
+    }
+    buildUntilContext(record) {
+        var _a;
+        return {
+            id: record.id,
+            purpose: record.purpose,
+            fireCount: record.fireCount,
+            target: Object.assign({ channelId: record.channelId, continuationToken: record.continuationToken }, ((_a = record.target) !== null && _a !== void 0 ? _a : {})),
+            host: this.engine.host,
+            mcp: this.engine.host.mcp,
+        };
+    }
+    disarm(record, reason) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.clearTimer(record.id);
+            const updated = Object.assign(Object.assign({}, record), { status: "disarmed", disarmReason: reason, updatedAt: new Date().toISOString() });
+            yield this.persist(updated);
+            this.handlers.delete(record.id);
+        });
+    }
+    afterFire(record, _outcome, reschedule) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const current = yield this.getRecord(record.id);
+            if (current === undefined || current.status !== "armed") {
+                return;
+            }
+            const now = Date.now();
+            const oneShot = current.scheduleKind === "delay" || current.scheduleKind === "at";
+            if (reschedule !== undefined) {
+                let nextFireAtMs;
+                if (reschedule.delay !== undefined) {
+                    nextFireAtMs = now + parseDuration(reschedule.delay);
+                }
+                else if (reschedule.at !== undefined) {
+                    nextFireAtMs =
+                        reschedule.at instanceof Date
+                            ? reschedule.at.getTime()
+                            : Date.parse(String(reschedule.at));
+                    if (!Number.isFinite(nextFireAtMs)) {
+                        throw new ReminderValidationError(`Invalid reschedule.at for reminder "${current.id}"`);
+                    }
+                }
+                else {
+                    throw new ReminderValidationError(`reschedule requires delay or at for reminder "${current.id}"`);
+                }
+                const updated = Object.assign(Object.assign({}, current), { fireCount: current.fireCount + 1, nextFireAtMs, 
+                    // Promote to one-shot-from-now semantics if they rescheduled
+                    scheduleKind: reschedule.delay !== undefined ? "delay" : "at", scheduleValue: reschedule.delay !== undefined ? String(reschedule.delay) : String(reschedule.at), updatedAt: new Date().toISOString() });
+                yield this.persist(updated);
+                if (this.platformTimers === undefined) {
+                    this.armTimer(updated);
+                }
+                return;
+            }
+            if (oneShot) {
+                this.clearTimer(current.id);
+                const updated = Object.assign(Object.assign({}, current), { fireCount: current.fireCount + 1, status: "completed", disarmReason: "one_shot_complete", updatedAt: new Date().toISOString() });
+                yield this.persist(updated);
+                this.handlers.delete(current.id);
+                return;
+            }
+            // Recurring
+            let nextFireAtMs;
+            if (current.scheduleKind === "every" && current.intervalMs !== undefined) {
+                nextFireAtMs = now + current.intervalMs;
+            }
+            else if (current.scheduleKind === "cron") {
+                nextFireAtMs = nextCronFireMs(current.scheduleValue, now);
+            }
+            else {
+                throw new Error(`Reminder "${current.id}" has recurring status with scheduleKind=${current.scheduleKind}`);
+            }
+            const updated = Object.assign(Object.assign({}, current), { fireCount: current.fireCount + 1, nextFireAtMs, updatedAt: new Date().toISOString() });
+            yield this.persist(updated);
+            if (this.platformTimers === undefined) {
+                this.armTimer(updated);
+            }
+        });
+    }
+}