@raybase/core 0.0.2 → 0.3.3

package/dist/agent-follow-ups.js

@@ -0,0 +1,840 @@
+import { recordAudit } from "./audit.js";
+import { sha256Hex, stableJson } from "./internal.js";
+import { durationMs } from "./jobs.js";
+import { nowIso, q, randomId } from "./sql.js";
+import { continueAgentFollowUpStore, getAgentFollowUp, parsedFollowUpJson } from "./agent-follow-up-store.js";
+export { followUpDispatchRecencyMs, followUpMaxDispatchAttempts, followUpStaleRunningMs, raybaseAgentFollowUpSystemTables } from "./agent-follow-up-store.js";
+export const raybaseAgentFollowUpLimits = {
+    maxPending: 32,
+    dailyCreates: 48,
+    apiMinDelayMs: 60_000,
+    toolMinDelayMs: 5 * 60_000,
+    maxHorizonMs: 30 * 24 * 60 * 60_000,
+    minIdleAfterMs: 60_000,
+    minFallbackEveryMs: 5 * 60_000,
+    maxKeyChars: 128,
+    maxBodyChars: 4_000,
+    maxContextBytes: 32_768,
+    maxReasonChars: 500,
+    maxConversationBytes: 8_192,
+    maxWakeEventChars: 128,
+    maxWakeMatchKeys: 16,
+    maxWakeKeyChars: 64,
+    maxWakeMatchBytes: 2_048,
+    maxWakePayloadKeys: 32,
+    maxWakePayloadBytes: 8_192
+};
+export class AgentFollowUpPolicyError extends Error {
+    reason;
+    details;
+    constructor(reason, message, details = {}) {
+        super(message);
+        this.reason = reason;
+        this.details = details;
+        this.name = "AgentFollowUpPolicyError";
+    }
+}
+const keyPattern = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+function positiveInteger(value, fallback, label) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isInteger(value) || value < 1)
+        throw new Error(`${label} must be a positive integer`);
+    return value;
+}
+function positiveDuration(value, fallback, label) {
+    if (value === undefined)
+        return fallback;
+    let parsed;
+    try {
+        parsed = durationMs(value);
+    }
+    catch (error) {
+        throw new Error(`${label} must be a positive duration: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        throw new Error(`${label} must be a positive duration`);
+    return parsed;
+}
+export function normalizeAgentFollowUpsConfig(agent) {
+    if (agent.followUps === undefined)
+        return null;
+    if (!agent.followUps || typeof agent.followUps !== "object" || Array.isArray(agent.followUps) || agent.followUps.enabled !== true) {
+        throw new Error(`Raybase agent ${agent.name} followUps must be configured with { enabled: true }`);
+    }
+    const limits = agent.followUps.limits ?? {};
+    if (!limits || typeof limits !== "object" || Array.isArray(limits)) {
+        throw new Error(`Raybase agent ${agent.name} followUps.limits must be an object`);
+    }
+    const minDelayMs = positiveDuration(limits.minDelay, null, `Raybase agent ${agent.name} followUps.limits.minDelay`);
+    const maxHorizonMs = positiveDuration(limits.maxHorizon, raybaseAgentFollowUpLimits.maxHorizonMs, `Raybase agent ${agent.name} followUps.limits.maxHorizon`);
+    if (minDelayMs !== null && minDelayMs > maxHorizonMs) {
+        throw new Error(`Raybase agent ${agent.name} followUps.limits.minDelay must not exceed maxHorizon`);
+    }
+    return {
+        maxPending: positiveInteger(limits.maxPending, raybaseAgentFollowUpLimits.maxPending, `Raybase agent ${agent.name} followUps.limits.maxPending`),
+        dailyCreates: positiveInteger(limits.dailyCreates, raybaseAgentFollowUpLimits.dailyCreates, `Raybase agent ${agent.name} followUps.limits.dailyCreates`),
+        minDelayMs,
+        maxHorizonMs
+    };
+}
+export function validateAgentFollowUpsForAgent(agent) {
+    normalizeAgentFollowUpsConfig(agent);
+}
+function validKey(value, label) {
+    if (typeof value !== "string" || !keyPattern.test(value.trim())) {
+        throw new AgentFollowUpPolicyError("invalid-request", `${label} must start with an alphanumeric character and contain at most 128 alphanumeric, dot, underscore, colon, or hyphen characters`);
+    }
+    return value.trim();
+}
+function textValue(value, max, label, required = false) {
+    if (value === undefined || value === null) {
+        if (required)
+            throw new AgentFollowUpPolicyError("invalid-request", `${label} is required`);
+        return null;
+    }
+    if (typeof value !== "string")
+        throw new AgentFollowUpPolicyError("invalid-request", `${label} must be a string`);
+    const normalized = value.trim();
+    if (!normalized && required)
+        throw new AgentFollowUpPolicyError("invalid-request", `${label} is required`);
+    if (normalized.length > max)
+        throw new AgentFollowUpPolicyError("invalid-request", `${label} must be at most ${max} characters`);
+    return normalized || null;
+}
+function boundedJson(value, maxBytes, label) {
+    if (value === undefined)
+        return null;
+    let json;
+    try {
+        json = stableJson(value);
+    }
+    catch {
+        throw new AgentFollowUpPolicyError("invalid-request", `${label} must be JSON serializable`);
+    }
+    if (new TextEncoder().encode(json).byteLength > maxBytes) {
+        throw new AgentFollowUpPolicyError("invalid-request", `${label} is too large`);
+    }
+    return json;
+}
+const wakeEventPattern = /^[A-Za-z][A-Za-z0-9_.:-]{0,127}$/;
+/** Validates one app-chosen wake event name. */
+export function normalizeAgentFollowUpWakeEvent(value, label = "Follow-up wakeOn.event") {
+    if (typeof value !== "string" || !wakeEventPattern.test(value.trim())) {
+        throw new AgentFollowUpPolicyError("invalid-request", `${label} must start with a letter and contain at most ${raybaseAgentFollowUpLimits.maxWakeEventChars} letters, digits, dots, underscores, colons, or hyphens`);
+    }
+    return value.trim();
+}
+function flatScalarObject(value, input) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new AgentFollowUpPolicyError("invalid-request", `${input.label} must be a flat object`);
+    }
+    const entries = Object.entries(value);
+    if (entries.length > input.maxKeys) {
+        throw new AgentFollowUpPolicyError("invalid-request", `${input.label} must have at most ${input.maxKeys} keys`);
+    }
+    const normalized = {};
+    for (const [key, entry] of entries) {
+        if (!key.trim() || key.length > raybaseAgentFollowUpLimits.maxWakeKeyChars) {
+            throw new AgentFollowUpPolicyError("invalid-request", `${input.label} keys must be non-empty and at most ${raybaseAgentFollowUpLimits.maxWakeKeyChars} characters`);
+        }
+        if (entry === undefined || (entry === null && !input.allowNull))
+            continue;
+        if (typeof entry !== "string"
+            && typeof entry !== "boolean"
+            && entry !== null
+            && !(typeof entry === "number" && Number.isFinite(entry))) {
+            throw new AgentFollowUpPolicyError("invalid-request", `${input.label} values must be strings, finite numbers, or booleans`);
+        }
+        normalized[key] = entry;
+    }
+    if (new TextEncoder().encode(stableJson(normalized)).byteLength > input.maxBytes) {
+        throw new AgentFollowUpPolicyError("invalid-request", `${input.label} is too large`);
+    }
+    return normalized;
+}
+/**
+ * Normalizes the optional `wakeOn` trigger. Returns null when the follow-up
+ * waits only on time.
+ */
+export function normalizeAgentFollowUpWakeOn(value) {
+    if (value === undefined || value === null)
+        return null;
+    if (typeof value !== "object" || Array.isArray(value)) {
+        throw new AgentFollowUpPolicyError("invalid-request", "Follow-up wakeOn must be an object");
+    }
+    const record = value;
+    const event = normalizeAgentFollowUpWakeEvent(record.event);
+    if (record.match === undefined || record.match === null)
+        return { event, match: null };
+    const match = flatScalarObject(record.match, {
+        label: "Follow-up wakeOn.match",
+        maxKeys: raybaseAgentFollowUpLimits.maxWakeMatchKeys,
+        maxBytes: raybaseAgentFollowUpLimits.maxWakeMatchBytes,
+        allowNull: false
+    });
+    return { event, match: Object.keys(match).length ? match : null };
+}
+/** Normalizes the payload an app fires with a wake. */
+export function normalizeAgentFollowUpWakePayload(value) {
+    if (value === undefined || value === null)
+        return {};
+    return flatScalarObject(value, {
+        label: "Follow-up wake payload",
+        maxKeys: raybaseAgentFollowUpLimits.maxWakePayloadKeys,
+        maxBytes: raybaseAgentFollowUpLimits.maxWakePayloadBytes,
+        allowNull: true
+    });
+}
+/**
+ * Exact equality on a flat object: every `match` entry must equal the payload's
+ * value for that key. No expressions, no coercion, no missing keys.
+ */
+export function agentFollowUpWakeMatches(match, payload) {
+    if (!match)
+        return true;
+    for (const [key, expected] of Object.entries(match)) {
+        if (!Object.prototype.hasOwnProperty.call(payload, key))
+            return false;
+        if (payload[key] !== expected)
+            return false;
+    }
+    return true;
+}
+function parsedWakeOn(row) {
+    if (!row.wakeOnEvent)
+        return null;
+    const match = parsedFollowUpJson(row.wakeOnMatchJson);
+    return {
+        event: row.wakeOnEvent,
+        match: match && typeof match === "object" && !Array.isArray(match) ? match : null
+    };
+}
+function parsedWakePayload(row) {
+    const payload = parsedFollowUpJson(row.wokePayloadJson);
+    return payload && typeof payload === "object" && !Array.isArray(payload)
+        ? payload
+        : null;
+}
+function parseContext(row) {
+    if (!row.contextJson)
+        return null;
+    try {
+        return JSON.parse(row.contextJson);
+    }
+    catch {
+        return null;
+    }
+}
+export function followUpSafeProjection(row) {
+    return {
+        id: row.id,
+        agentName: row.agentName,
+        key: row.key,
+        ownerKey: row.ownerKey,
+        body: row.body,
+        context: parseContext(row),
+        dueAt: row.dueAt,
+        mode: row.onDue === "lapse" ? "lapse" : row.fallbackEveryMs === null ? "once" : "continuing",
+        status: row.status,
+        runCount: row.runCount,
+        maxRuns: row.maxRuns,
+        fallbackEveryMs: row.fallbackEveryMs,
+        drifted: row.driftCount > 0,
+        wakeOn: parsedWakeOn(row),
+        wokeBy: row.wokeBy === "event" ? "event" : null,
+        wokeEvent: row.wokeEvent,
+        wokePayload: parsedWakePayload(row),
+        wokeAt: row.wokeAt,
+        createdBy: row.createdBy,
+        createdAt: row.createdAt
+    };
+}
+export function followUpToolProjection(row) {
+    const safe = followUpSafeProjection(row);
+    return {
+        followUpId: safe.id,
+        key: safe.key,
+        ownerKey: safe.ownerKey,
+        status: safe.status,
+        dueAt: safe.dueAt,
+        mode: safe.mode,
+        runCount: safe.runCount,
+        maxRuns: safe.maxRuns,
+        drifted: safe.drifted,
+        body: safe.body,
+        context: safe.context,
+        wakeOn: safe.wakeOn,
+        wokeBy: safe.wokeBy,
+        wokeEvent: safe.wokeEvent,
+        wokePayload: safe.wokePayload
+    };
+}
+export function followUpAdminProjection(row) {
+    let context = null;
+    let contextInvalid = false;
+    if (row.contextJson) {
+        try {
+            context = JSON.parse(row.contextJson);
+        }
+        catch {
+            contextInvalid = true;
+        }
+    }
+    return {
+        ...row,
+        context,
+        contextInvalid,
+        mode: followUpSafeProjection(row).mode,
+        drifted: row.driftCount > 0,
+        wakeOn: parsedWakeOn(row),
+        wokeBy: row.wokeBy === "event"
+            ? "event"
+            : row.wakeOnEvent && (row.status === "fired" || row.status === "lapsed")
+                ? "deadline"
+                : null,
+        wokePayload: parsedWakePayload(row)
+    };
+}
+async function normalizedConversation(agentName, followUpId, value) {
+    if (!value || value.mode === undefined || value.mode === "new") {
+        const digest = (await sha256Hex(stableJson({ agentName, followUpId }))).slice(0, 32);
+        return { mode: "thread", key: followUpId, conversationId: `agent_follow_up_thread:${digest}` };
+    }
+    if (value.mode === "thread") {
+        if (typeof value.key !== "string" || !value.key.trim()) {
+            throw new AgentFollowUpPolicyError("invalid-request", 'Follow-up conversation mode "thread" requires a non-empty key');
+        }
+        const key = value.key.trim();
+        if (key.length > 512)
+            throw new AgentFollowUpPolicyError("invalid-request", "Follow-up conversation thread key is too long");
+        const digest = (await sha256Hex(stableJson({ agentName, key }))).slice(0, 32);
+        return { mode: "thread", key, conversationId: `agent_follow_up_thread:${digest}`, metadata: value.metadata ?? null };
+    }
+    if (value.mode === "chat") {
+        if (typeof value.conversationId !== "string" || !value.conversationId.trim()) {
+            throw new AgentFollowUpPolicyError("invalid-request", 'Follow-up conversation mode "chat" requires a conversationId');
+        }
+        return { mode: "chat", conversationId: value.conversationId.trim() };
+    }
+    throw new AgentFollowUpPolicyError("invalid-request", "Unsupported follow-up conversation mode");
+}
+function requestedDueAt(options, nowMs) {
+    const hasAt = options.at !== undefined;
+    const hasIn = options.in !== undefined;
+    if (hasAt === hasIn)
+        throw new AgentFollowUpPolicyError("invalid-request", 'Provide exactly one of follow-up options "at" or "in"');
+    if (hasAt) {
+        const parsed = Date.parse(options.at);
+        if (!Number.isFinite(parsed))
+            throw new AgentFollowUpPolicyError("invalid-request", "Follow-up at must be a valid ISO timestamp");
+        return parsed;
+    }
+    try {
+        return nowMs + durationMs(options.in);
+    }
+    catch (error) {
+        throw new AgentFollowUpPolicyError("invalid-request", error instanceof Error ? error.message : String(error));
+    }
+}
+async function constrainedDueAt(agent, requestedMs, input) {
+    const nowMs = Date.parse(input.now);
+    const floor = nowMs + input.minDelayMs;
+    const ceiling = nowMs + input.maxHorizonMs;
+    let requested = new Date(Math.min(Math.max(requestedMs, floor), ceiling));
+    if (agent.followUps?.constrainDueAt) {
+        requested = await agent.followUps.constrainDueAt(requested, {
+            agentName: agent.name,
+            key: input.key,
+            ownerKey: input.ownerKey,
+            createdBy: input.createdBy,
+            source: input.source,
+            now: new Date(nowMs),
+            env: input.env
+        });
+        if (!(requested instanceof Date) || !Number.isFinite(requested.getTime())) {
+            throw new AgentFollowUpPolicyError("constrain-invalid", `Agent ${agent.name} followUps.constrainDueAt returned an invalid Date`);
+        }
+    }
+    let resultMs = Math.min(Math.max(requested.getTime(), floor), ceiling);
+    if (input.notLaterThan) {
+        const cap = Date.parse(input.notLaterThan);
+        if (!Number.isFinite(cap))
+            throw new AgentFollowUpPolicyError("invalid-request", "Follow-up notLaterThan must be a valid ISO timestamp");
+        if (cap < floor)
+            throw new AgentFollowUpPolicyError("invalid-request", "Follow-up notLaterThan is earlier than the minimum allowed due time");
+        resultMs = Math.min(resultMs, cap);
+    }
+    return new Date(resultMs).toISOString();
+}
+async function claimDailyCreateBudget(control, agentName, limit, nowMs) {
+    const duration = 24 * 60 * 60_000;
+    const windowStartMs = Math.floor(nowMs / duration) * duration;
+    const windowStart = new Date(windowStartMs).toISOString();
+    const windowEnd = new Date(windowStartMs + duration).toISOString();
+    const scope = "agent-follow-ups";
+    const row = await control.first(`SELECT "requestCount" FROM ${q("_agent_limit_windows")} WHERE "scope" = ? AND "scopeId" = ? AND "windowStart" = ? LIMIT 1`, [scope, agentName, windowStart]);
+    const next = Number(row?.requestCount ?? 0) + 1;
+    if (next > limit)
+        throw new AgentFollowUpPolicyError("daily-limit", `Daily follow-up creation limit reached for ${agentName}`);
+    if (row) {
+        await control.run(`UPDATE ${q("_agent_limit_windows")} SET "requestCount" = ?, "updatedAt" = ? WHERE "scope" = ? AND "scopeId" = ? AND "windowStart" = ?`, [next, nowIso(), scope, agentName, windowStart]);
+    }
+    else {
+        await control.run(`INSERT INTO ${q("_agent_limit_windows")} ("id", "scope", "scopeId", "windowStart", "windowEnd", "requestCount", "estimatedOutputTokens", "updatedAt")
+       VALUES (?, ?, ?, ?, ?, ?, 0, ?)`, [randomId("agent_limit"), scope, agentName, windowStart, windowEnd, next, nowIso()]);
+    }
+}
+export async function listAgentFollowUps(control, input) {
+    const limit = Math.max(1, Math.min(500, input.limit ?? 100));
+    if (input.status) {
+        return control.all(`SELECT * FROM ${q("_agent_follow_ups")} WHERE "agentName" = ? AND "status" = ? ORDER BY "dueAt" ASC, "createdAt" DESC LIMIT ?`, [input.agentName, input.status, limit]);
+    }
+    return control.all(`SELECT * FROM ${q("_agent_follow_ups")} WHERE "agentName" = ?
+     ORDER BY CASE "status" WHEN 'pending' THEN 0 ELSE 1 END, "dueAt" ASC, "createdAt" DESC LIMIT ?`, [input.agentName, limit]);
+}
+export async function createAgentFollowUp(input) {
+    const config = normalizeAgentFollowUpsConfig(input.agent);
+    if (!config)
+        throw new AgentFollowUpPolicyError("invalid-request", `Agent ${input.agent.name} does not enable follow-ups`);
+    const key = validKey(input.options.key, "Follow-up key");
+    const ownerKey = input.options.ownerKey === undefined ? null : validKey(input.options.ownerKey, "Follow-up ownerKey");
+    const body = textValue(input.options.body, raybaseAgentFollowUpLimits.maxBodyChars, "Follow-up body", true);
+    const contextJson = boundedJson(input.options.context, raybaseAgentFollowUpLimits.maxContextBytes, "Follow-up context");
+    const now = input.now ?? nowIso();
+    const nowMs = Date.parse(now);
+    const minDelayMs = config.minDelayMs ?? (input.toolInitiated ? raybaseAgentFollowUpLimits.toolMinDelayMs : raybaseAgentFollowUpLimits.apiMinDelayMs);
+    const wakeOn = normalizeAgentFollowUpWakeOn(input.options.wakeOn);
+    // A wakeOn row with no clock trigger is due at its deadline, which is then
+    // required: a follow-up that could wait forever is refused, exactly as an
+    // unbounded idleAfter is.
+    const deadlineIsDueAt = Boolean(wakeOn) && input.options.at === undefined && input.options.in === undefined;
+    if (deadlineIsDueAt && !input.options.notLaterThan) {
+        throw new AgentFollowUpPolicyError("invalid-request", 'A follow-up with "wakeOn" and no "at" or "in" must set "notLaterThan" as its deadline');
+    }
+    const rawDueAt = deadlineIsDueAt
+        ? (() => {
+            const parsed = Date.parse(input.options.notLaterThan);
+            if (!Number.isFinite(parsed))
+                throw new AgentFollowUpPolicyError("invalid-request", "Follow-up notLaterThan must be a valid ISO timestamp");
+            return parsed;
+        })()
+        : requestedDueAt(input.options, nowMs);
+    const idleAfterMs = input.options.idleAfter === undefined
+        ? null
+        : positiveDuration(input.options.idleAfter, null, "Follow-up idleAfter");
+    if (idleAfterMs !== null && (idleAfterMs < raybaseAgentFollowUpLimits.minIdleAfterMs || idleAfterMs > config.maxHorizonMs)) {
+        throw new AgentFollowUpPolicyError("invalid-request", "Follow-up idleAfter must be between 1 minute and maxHorizon");
+    }
+    const notLaterThan = input.options.notLaterThan ?? null;
+    if (notLaterThan) {
+        const cap = Date.parse(notLaterThan);
+        if (!Number.isFinite(cap) || cap > nowMs + config.maxHorizonMs || (cap <= rawDueAt && !deadlineIsDueAt)) {
+            throw new AgentFollowUpPolicyError("invalid-request", "Follow-up notLaterThan must be valid, after the initial dueAt, and within maxHorizon");
+        }
+    }
+    let onDue;
+    let fallbackEveryMs = null;
+    let maxRuns = null;
+    if (input.options.onDue === "lapse") {
+        onDue = "lapse";
+    }
+    else if (input.options.onDue && typeof input.options.onDue === "object" && "run" in input.options.onDue) {
+        onDue = "run";
+        const run = input.options.onDue.run;
+        if (run && typeof run === "object" && "fallbackEvery" in run) {
+            fallbackEveryMs = positiveDuration(run.fallbackEvery, null, "Follow-up fallbackEvery");
+            if (fallbackEveryMs === null || fallbackEveryMs < raybaseAgentFollowUpLimits.minFallbackEveryMs || fallbackEveryMs > config.maxHorizonMs) {
+                throw new AgentFollowUpPolicyError("invalid-request", "Follow-up fallbackEvery must be between 5 minutes and maxHorizon");
+            }
+            maxRuns = run.maxRuns === undefined ? null : positiveInteger(run.maxRuns, 1, "Follow-up maxRuns");
+        }
+        else if (run && typeof run === "object" && Object.keys(run).length > 0) {
+            throw new AgentFollowUpPolicyError("invalid-request", "Follow-up run configuration is invalid");
+        }
+    }
+    else {
+        throw new AgentFollowUpPolicyError("invalid-request", "Follow-up onDue must be lapse or run");
+    }
+    const dueAt = await constrainedDueAt(input.agent, rawDueAt, {
+        key,
+        ownerKey: ownerKey ?? undefined,
+        createdBy: input.createdBy,
+        source: "create",
+        now,
+        minDelayMs,
+        maxHorizonMs: config.maxHorizonMs,
+        notLaterThan,
+        env: input.env
+    });
+    const existing = await input.control.first(`SELECT * FROM ${q("_agent_follow_ups")} WHERE "agentName" = ? AND "key" = ? AND "status" = 'pending' LIMIT 1`, [input.agent.name, key]);
+    if (existing)
+        throw new AgentFollowUpPolicyError("duplicate-key", `Agent ${input.agent.name} already has a pending follow-up with key "${key}"`, { existing });
+    const pending = await listAgentFollowUps(input.control, { agentName: input.agent.name, status: "pending", limit: config.maxPending + 1 });
+    if (pending.length >= config.maxPending) {
+        throw new AgentFollowUpPolicyError("max-pending", `Agent ${input.agent.name} already has ${config.maxPending} pending follow-ups`, { pending });
+    }
+    if (input.toolInitiated)
+        await claimDailyCreateBudget(input.control, input.agent.name, config.dailyCreates, nowMs);
+    const id = randomId("agent_follow_up");
+    const conversationJson = boundedJson(await normalizedConversation(input.agent.name, id, input.options.conversation), raybaseAgentFollowUpLimits.maxConversationBytes, "Follow-up conversation");
+    try {
+        await input.control.run(`INSERT INTO ${q("_agent_follow_ups")}
+       ("id","agentName","key","ownerKey","body","contextJson","conversationJson","dueAt","idleAfterMs","notLaterThan",
+        "wakeOnEvent","wakeOnMatchJson","wokeBy","wokeEvent","wokeEventId","wokePayloadJson","wokeAt",
+        "onDue","fallbackEveryMs","maxRuns","status","reason","dispatchGeneration","dispatchAttempts","dispatchStartedAt","dispatchClaimToken","claimAcquiredAt","lastRunGeneration","continuedGeneration",
+        "runCount","lastRunAt","continuedAt","driftCount","lastDriftAt","settledAt","lapseHandledAt","lapseAttempts",
+        "createdBy","requestedByConversationId","requestedByRunId","triggerEventId","createdAt","updatedAt")
+       VALUES (?,?,?,?,?,?,?,?,?,?, ?,?,NULL,NULL,NULL,NULL,NULL, ?,?,?,'pending',NULL,0,0,NULL,NULL,NULL,NULL,NULL, 0,NULL,NULL,0,NULL,NULL,NULL,0, ?,?,?,NULL,?,?)`, [
+            id, input.agent.name, key, ownerKey, body, contextJson, conversationJson, dueAt, idleAfterMs, notLaterThan,
+            wakeOn?.event ?? null, wakeOn?.match ? stableJson(wakeOn.match) : null,
+            onDue, fallbackEveryMs, maxRuns,
+            input.createdBy, input.requestedByConversationId ?? null, input.requestedByRunId ?? null, now, now
+        ]);
+    }
+    catch (error) {
+        const raced = await input.control.first(`SELECT * FROM ${q("_agent_follow_ups")} WHERE "agentName" = ? AND "key" = ? AND "status" = 'pending' LIMIT 1`, [input.agent.name, key]);
+        if (raced)
+            throw new AgentFollowUpPolicyError("duplicate-key", `Agent ${input.agent.name} already has a pending follow-up with key "${key}"`, { existing: raced });
+        throw error;
+    }
+    const row = await getAgentFollowUp(input.control, id);
+    if (!row)
+        throw new Error(`Follow-up could not be loaded after creation: ${input.agent.name}/${key}`);
+    return {
+        followUpId: id,
+        key,
+        dueAt,
+        status: row.status,
+        row,
+        pendingCount: pending.length + 1
+    };
+}
+async function settleByKey(control, input) {
+    const key = validKey(input.key, "Follow-up key");
+    const reason = textValue(input.reason, raybaseAgentFollowUpLimits.maxReasonChars, "Follow-up reason");
+    const row = await control.first(`SELECT * FROM ${q("_agent_follow_ups")} WHERE "agentName" = ? AND "key" = ? AND "status" = 'pending' LIMIT 1`, [input.agentName, key]);
+    if (!row)
+        return { changed: false, row: null };
+    const now = input.now ?? nowIso();
+    await control.run(`UPDATE ${q("_agent_follow_ups")} SET "status" = ?, "reason" = ?, "settledAt" = ?, "updatedAt" = ?
+     WHERE "id" = ? AND "status" = 'pending'`, [input.status, reason, now, now, row.id]);
+    const updated = await getAgentFollowUp(control, row.id);
+    return { changed: updated?.status === input.status, row: updated };
+}
+export function resolveAgentFollowUp(control, input) {
+    return settleByKey(control, { ...input, status: "resolved" });
+}
+export function closeAgentFollowUp(control, input) {
+    return settleByKey(control, { ...input, status: "closed" });
+}
+export async function closeAgentFollowUpById(control, input) {
+    const row = await getAgentFollowUp(control, input.followUpId);
+    if (!row || row.agentName !== input.agentName || row.status !== "pending")
+        return { changed: false, row };
+    return closeAgentFollowUp(control, { agentName: input.agentName, key: row.key, reason: input.reason, now: input.now });
+}
+export async function closeAgentFollowUpsByOwner(control, input) {
+    const ownerKey = validKey(input.ownerKey, "Follow-up ownerKey");
+    const reason = textValue(input.reason, raybaseAgentFollowUpLimits.maxReasonChars, "Follow-up reason");
+    const rows = await control.all(`SELECT * FROM ${q("_agent_follow_ups")} WHERE "agentName" = ? AND "ownerKey" = ? AND "status" = 'pending'`, [input.agentName, ownerKey]);
+    const now = input.now ?? nowIso();
+    await control.run(`UPDATE ${q("_agent_follow_ups")} SET "status" = 'closed', "reason" = ?, "settledAt" = ?, "updatedAt" = ?
+     WHERE "agentName" = ? AND "ownerKey" = ? AND "status" = 'pending'`, [reason, now, now, input.agentName, ownerKey]);
+    return { closed: rows.length };
+}
+export async function touchAgentFollowUp(control, input) {
+    const key = validKey(input.key, "Follow-up key");
+    const row = await control.first(`SELECT * FROM ${q("_agent_follow_ups")} WHERE "agentName" = ? AND "key" = ? AND "status" = 'pending' LIMIT 1`, [input.agentName, key]);
+    if (!row || row.idleAfterMs === null)
+        return { touched: false, row };
+    const now = input.now ?? nowIso();
+    const horizon = Date.parse(row.createdAt) + (input.maxHorizonMs ?? raybaseAgentFollowUpLimits.maxHorizonMs);
+    const ceiling = Math.min(row.notLaterThan ? Date.parse(row.notLaterThan) : Number.POSITIVE_INFINITY, horizon);
+    const dueAt = new Date(Math.min(Date.parse(now) + row.idleAfterMs, ceiling)).toISOString();
+    await control.run(`UPDATE ${q("_agent_follow_ups")} SET "dueAt" = ?, "updatedAt" = ? WHERE "id" = ? AND "status" = 'pending'`, [dueAt, now, row.id]);
+    return { touched: true, row: { ...row, dueAt, updatedAt: now } };
+}
+/**
+ * Wakes every pending `wakeOn` row of one agent whose event name is `event`
+ * and whose `match` filter is satisfied by `payload`. A woken row becomes due
+ * now (never later than its own deadline) and records why it woke. A row wakes
+ * at most once: the CAS below refuses a second wake, a row that already ran or
+ * settled is no longer pending, and a non-matching payload changes nothing.
+ */
+export async function wakeAgentFollowUps(control, input) {
+    const event = normalizeAgentFollowUpWakeEvent(input.event, "Follow-up wake event");
+    const payload = normalizeAgentFollowUpWakePayload(input.payload);
+    const payloadJson = stableJson(payload);
+    const now = input.now ?? nowIso();
+    const nowMs = Date.parse(now);
+    const wokeEventId = randomId("agent_follow_up_wake");
+    const candidates = await control.all(`SELECT * FROM ${q("_agent_follow_ups")}
+     WHERE "agentName" = ? AND "status" = 'pending' AND "wakeOnEvent" = ? AND "wokeBy" IS NULL
+     ORDER BY "createdAt" ASC`, [input.agentName, event]);
+    const woken = [];
+    let matched = 0;
+    for (const candidate of candidates) {
+        if (!agentFollowUpWakeMatches(parsedWakeOn(candidate)?.match ?? null, payload))
+            continue;
+        matched += 1;
+        const cap = candidate.notLaterThan ? Date.parse(candidate.notLaterThan) : Number.NaN;
+        const dueAt = new Date(Number.isFinite(cap) ? Math.min(nowMs, cap) : nowMs).toISOString();
+        await control.run(`UPDATE ${q("_agent_follow_ups")}
+       SET "dueAt" = ?, "wokeBy" = 'event', "wokeEvent" = ?, "wokeEventId" = ?, "wokePayloadJson" = ?, "wokeAt" = ?, "updatedAt" = ?
+       WHERE "id" = ? AND "status" = 'pending' AND "wokeBy" IS NULL AND "updatedAt" = ?`, [dueAt, event, wokeEventId, payloadJson, now, now, candidate.id, candidate.updatedAt]);
+        const row = await getAgentFollowUp(control, candidate.id);
+        if (row?.wokeEventId === wokeEventId)
+            woken.push(row);
+    }
+    return { event, wokeEventId, payload, woken, matched };
+}
+function notifyDueAtChanged(callback, targetIso) {
+    if (!callback)
+        return;
+    try {
+        void Promise.resolve(callback(targetIso)).catch((error) => {
+            console.warn("Failed to arm Agent follow-up alarm.", error);
+        });
+    }
+    catch (error) {
+        console.warn("Failed to arm Agent follow-up alarm.", error);
+    }
+}
+function record(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+/**
+ * The model's `wakeOnMatch` argument. An open record travels the strict tool
+ * subset as a JSON string, so accept either form; validation stays in
+ * `normalizeAgentFollowUpWakeOn`.
+ */
+function toolWakeOnMatch(value) {
+    if (typeof value === "string") {
+        if (!value.trim())
+            return null;
+        try {
+            return toolWakeOnMatch(JSON.parse(value));
+        }
+        catch {
+            throw new AgentFollowUpPolicyError("invalid-request", "Follow-up wakeOn.match must be a flat object");
+        }
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const entries = Object.entries(value);
+    return entries.length ? value : null;
+}
+function auditActor(principal) {
+    return principal.kind === "user" && principal.user.id.startsWith("service:")
+        ? { kind: "service", service: principal.user.id.slice("service:".length) || "raybase-agent" }
+        : principal;
+}
+export function agentFollowUpRuntimeTools(input) {
+    if (!input.agent.followUps || input.principal.kind === "public")
+        return [];
+    return [
+        {
+            name: "follow_up",
+            displayName: "Create follow-up",
+            description: "Create one keyed pending expectation. This tool supports a one-time model run or a structural lapse; continuing chains are created by app code. Wait for the clock with delayMinutes/at, or wait for something the app records with wakeOnEvent (and wakeOnMatch to pin it to one record) — then notLaterThan is the deadline you come back on anyway, and is required when you give no delayMinutes or at.",
+            parameters: {
+                type: "object",
+                properties: {
+                    key: { type: "string", description: "Stable dedupe key. Omit only when dedupe is unnecessary." },
+                    ownerKey: { type: "string" },
+                    body: { type: "string" },
+                    context: {},
+                    delayMinutes: { type: "number" },
+                    at: { type: "string" },
+                    idleAfterMinutes: { type: "number" },
+                    notLaterThan: { type: "string" },
+                    wakeOnEvent: {
+                        type: "string",
+                        description: "Wake as soon as the app records this named event, instead of only waiting for the clock. Ask the app which event names it fires."
+                    },
+                    wakeOnMatch: {
+                        type: "object",
+                        description: "Only wake when the event's payload has exactly these values, e.g. {\"questionId\": \"q_12\"}. Plain strings, numbers, or true/false.",
+                        additionalProperties: { anyOf: [{ type: "string" }, { type: "number" }, { type: "boolean" }] }
+                    },
+                    onDue: { type: "string", enum: ["run", "lapse"] }
+                },
+                required: ["body", "onDue"],
+                additionalProperties: false
+            },
+            dataChange: { actionName: "follow_up", effects: ["agent-follow-up"] },
+            run: async (args) => {
+                const value = record(args);
+                try {
+                    const result = await createAgentFollowUp({
+                        control: input.control,
+                        agent: input.agent,
+                        env: input.env,
+                        createdBy: "agent-tool",
+                        requestedByConversationId: input.conversationId,
+                        requestedByRunId: input.runId,
+                        toolInitiated: true,
+                        options: {
+                            key: typeof value.key === "string" && value.key.trim() ? value.key : `auto:${randomId("fu")}`,
+                            ...(typeof value.ownerKey === "string" ? { ownerKey: value.ownerKey } : {}),
+                            body: typeof value.body === "string" ? value.body : "",
+                            ...(value.context !== undefined ? { context: value.context } : {}),
+                            ...(value.at !== undefined ? { at: value.at } : {}),
+                            ...(value.delayMinutes !== undefined ? { in: `${String(value.delayMinutes)} minutes` } : {}),
+                            ...(value.idleAfterMinutes !== undefined ? { idleAfter: `${String(value.idleAfterMinutes)} minutes` } : {}),
+                            ...(typeof value.notLaterThan === "string" ? { notLaterThan: value.notLaterThan } : {}),
+                            ...(typeof value.wakeOnEvent === "string" && value.wakeOnEvent.trim()
+                                ? {
+                                    wakeOn: {
+                                        event: value.wakeOnEvent,
+                                        ...(toolWakeOnMatch(value.wakeOnMatch) ? { match: toolWakeOnMatch(value.wakeOnMatch) } : {})
+                                    }
+                                }
+                                : {}),
+                            onDue: value.onDue === "lapse" ? "lapse" : { run: {} }
+                        }
+                    });
+                    notifyDueAtChanged(input.onDueAtChanged, result.row.dueAt);
+                    await recordAudit(input.control, {
+                        actor: auditActor(input.principal),
+                        action: "agent.follow_up.created",
+                        target: { type: "_agent_follow_ups", id: result.row.id },
+                        metadata: { agentName: input.agent.name, key: result.row.key, conversationId: input.conversationId, runId: input.runId }
+                    });
+                    return { ok: true, ...followUpToolProjection(result.row), pendingCount: result.pendingCount };
+                }
+                catch (error) {
+                    if (error instanceof AgentFollowUpPolicyError) {
+                        return {
+                            ok: false,
+                            reason: error.reason,
+                            message: error.message,
+                            ...(error.details.existing ? { existing: followUpToolProjection(error.details.existing) } : {}),
+                            ...(error.details.pending ? { pending: error.details.pending.map(followUpToolProjection) } : {})
+                        };
+                    }
+                    throw error;
+                }
+            }
+        },
+        {
+            name: "list_follow_ups",
+            displayName: "List follow-ups",
+            description: "List this agent's pending follow-ups, including their body and cross-run context.",
+            parameters: { type: "object", properties: {}, additionalProperties: false },
+            run: async () => ({
+                ok: true,
+                followUps: (await listAgentFollowUps(input.control, { agentName: input.agent.name, status: "pending" })).map(followUpToolProjection)
+            })
+        },
+        {
+            name: "close_follow_up",
+            displayName: "Close follow-up",
+            description: "End a pending follow-up because it is no longer wanted or has been superseded. Resolution attested by app code uses the separate code API.",
+            parameters: {
+                type: "object",
+                properties: { key: { type: "string" }, reason: { type: "string" } },
+                required: ["key", "reason"],
+                additionalProperties: false
+            },
+            dataChange: { actionName: "close_follow_up", effects: ["agent-follow-up"] },
+            run: async (args) => {
+                const value = record(args);
+                try {
+                    const result = await closeAgentFollowUp(input.control, {
+                        agentName: input.agent.name,
+                        key: typeof value.key === "string" ? value.key : "",
+                        reason: typeof value.reason === "string" ? value.reason : ""
+                    });
+                    if (result.changed && result.row) {
+                        await recordAudit(input.control, {
+                            actor: auditActor(input.principal),
+                            action: "agent.follow_up.closed",
+                            target: { type: "_agent_follow_ups", id: result.row.id },
+                            metadata: { agentName: input.agent.name, key: result.row.key, reason: result.row.reason, conversationId: input.conversationId, runId: input.runId }
+                        });
+                    }
+                    return { ok: result.changed, reason: result.changed ? undefined : "conflict", followUp: result.row ? followUpToolProjection(result.row) : null };
+                }
+                catch (error) {
+                    if (error instanceof AgentFollowUpPolicyError)
+                        return { ok: false, reason: error.reason, message: error.message };
+                    throw error;
+                }
+            }
+        }
+    ];
+}
+export function agentFollowUpContinueTools(input) {
+    const baseClose = agentFollowUpRuntimeTools(input).find((tool) => tool.name === "close_follow_up");
+    if (!baseClose)
+        return [];
+    const continueTool = {
+        name: "continue_follow_up",
+        displayName: "Continue follow-up",
+        description: "Schedule the next check for the continuing follow-up that started this run, optionally replacing its body or context.",
+        parameters: {
+            type: "object",
+            properties: {
+                delayMinutes: { type: "number" },
+                at: { type: "string" },
+                body: { type: "string" },
+                context: {}
+            },
+            additionalProperties: false
+        },
+        dataChange: { actionName: "continue_follow_up", effects: ["agent-follow-up"] },
+        run: async (args) => {
+            const value = record(args);
+            const config = normalizeAgentFollowUpsConfig(input.agent);
+            if (!config)
+                return { ok: false, reason: "conflict" };
+            try {
+                const now = nowIso();
+                const requested = requestedDueAt({
+                    ...(value.at !== undefined ? { at: value.at } : {}),
+                    ...(value.delayMinutes !== undefined ? { in: `${String(value.delayMinutes)} minutes` } : {})
+                }, Date.parse(now));
+                const dueAt = await constrainedDueAt(input.agent, requested, {
+                    key: input.followUp.key,
+                    ownerKey: input.followUp.ownerKey ?? undefined,
+                    createdBy: input.followUp.createdBy,
+                    source: "continue",
+                    now,
+                    minDelayMs: config.minDelayMs ?? raybaseAgentFollowUpLimits.toolMinDelayMs,
+                    maxHorizonMs: config.maxHorizonMs,
+                    notLaterThan: input.followUp.notLaterThan,
+                    env: input.env
+                });
+                const body = value.body === undefined ? undefined : textValue(value.body, raybaseAgentFollowUpLimits.maxBodyChars, "Follow-up body", true);
+                const contextJson = value.context === undefined ? undefined : boundedJson(value.context, raybaseAgentFollowUpLimits.maxContextBytes, "Follow-up context");
+                const row = await continueAgentFollowUpStore(input.control, {
+                    id: input.followUp.id,
+                    generation: input.generation,
+                    dueAt,
+                    body,
+                    contextJson,
+                    now
+                });
+                if (!row)
+                    return { ok: false, reason: "conflict", message: "The follow-up is no longer pending for this run generation." };
+                notifyDueAtChanged(input.onDueAtChanged, row.dueAt);
+                await recordAudit(input.control, {
+                    actor: auditActor(input.principal),
+                    action: "agent.follow_up.continued",
+                    target: { type: "_agent_follow_ups", id: row.id },
+                    metadata: { agentName: row.agentName, key: row.key, generation: input.generation, dueAt }
+                });
+                return { ok: true, followUp: followUpToolProjection(row) };
+            }
+            catch (error) {
+                if (error instanceof AgentFollowUpPolicyError)
+                    return { ok: false, reason: error.reason, message: error.message };
+                throw error;
+            }
+        }
+    };
+    return [continueTool, baseClose];
+}
+//# sourceMappingURL=agent-follow-ups.js.map