@raybase/core 0.0.1 → 0.3.3

package/dist/agent.js

@@ -0,0 +1,3123 @@
+import { jsonSchema, tool } from "ai";
+import { agentPrincipal } from "./principal.js";
+import { actionInputJsonSchema, agentActionRegistrations, executeAction, restoreStrictActionInput, unsupportedRaybaseAgentInvocationRuntime } from "./actions.js";
+import { authSecret, createRaybaseAuthContextRuntime, unsupportedRaybaseAuthContextRuntime } from "./auth.js";
+import { agentActionToolName, agentSkillActionBindings, agentSkillRegistrations, agentSkillSummaries, validateAgentSkillsForAgent } from "./agent-skills.js";
+import { agentRemoteMcpBindingSummaries, agentRemoteMcpToolBindings, validateAgentRemoteMcpBindings } from "./agent-remote-mcp.js";
+import { agentMemoryMaintenanceRuns, agentMemorySpaces, raybaseAgentMemorySystemTables, raybaseAgentMemoryToolNames, validateAgentMemoryForAgent } from "./agent-memory.js";
+import { raybaseAgentSkillSystemTables, raybaseAgentSkillToolNames, validateAgentSkillStoreForAgent } from "./agent-skill-store.js";
+import { raybaseAgentWakeSystemTables, raybaseAgentWakeToolNames, validateAgentWakesForAgent } from "./agent-wakes.js";
+import { raybaseAgentFollowUpSystemTables, validateAgentFollowUpsForAgent } from "./agent-follow-ups.js";
+import { findAgentRoomMember, raybaseAgentRoomSystemTables, setAgentRoomMemberPinned, validateAgentRoomsForAgent } from "./agent-rooms.js";
+import { buildAgentChapterRehydrateSeed, defaultAgentRunEvidenceTtlMs, loadLastAgentChapter, minAgentRunEvidenceTtlMs, normalizeAgentRetentionConfig, purgeAgentChaptersForConversation, raybaseAgentChapterSystemTables, validateAgentRetentionForAgent } from "./agent-chapters.js";
+import { ensureAgentChapterSearch } from "./agent-chapter-search.js";
+import { raybaseAgentChapterArchiveSystemTables } from "./agent-chapter-archive.js";
+import { normalizeAgentVoiceNotesConfig } from "./agent-voice-notes.js";
+import { validateAgentUserDataPartsConfig } from "./agent-user-data-parts.js";
+export { isAgentUserDataPartType, isReservedAgentDataPartType, maxAgentUserDataBytesPerMessage, maxAgentUserDataPartBytes, maxAgentUserDataPartsPerMessage } from "./agent-user-data-parts.js";
+import { parseSearchQuery } from "./search.js";
+import { storageHardMaxSizeBytes } from "./storage.js";
+import { estimateTokensFromChars, normalizeAiDefaults, normalizeAiLimits, recordAiActionEvent } from "./ai.js";
+import { sha256Hex, stableJson, validateRaybaseName } from "./internal.js";
+import { validateJsonSchema } from "./json-schema.js";
+import { nextCronRun, validateCron } from "./jobs.js";
+import { id, integer, longText, raybaseSystemTable, text } from "./schema.js";
+import { setting } from "./settings.js";
+import { nowIso, q, randomId } from "./sql.js";
+import { appNowMs, wallNowIso, wallNowMs } from "./clock.js";
+export const defaultAgentCompaction = {
+    enabled: true,
+    keepRecentMessages: 16,
+    triggerRatio: 0.7,
+    minSummaryOutputTokens: 800,
+    summarySpanRatio: 0.12,
+    maxSummaryOutputTokens: 4_000
+};
+/** Default cap for custom prompt bands. The built-in head has no default cap. */
+export const defaultAgentPromptBandMaxChars = 16_000;
+export const defaultAgentDeliveryMaxReplacementChars = 32_000;
+export const maxAgentDeliveryReplacementChars = 128_000;
+export const defaultAgentAttachmentMediaTypes = [
+    "image/jpeg",
+    "image/png",
+    "image/webp",
+    "image/gif"
+];
+export const defaultAgentAttachmentMaxPerMessage = 4;
+export const defaultAgentAttachmentMaxBytesPerFile = 8 * 1024 * 1024;
+export const defaultAgentAttachmentRecentMessages = 8;
+export const raybaseAiChatHarness = {
+    runtime: "ai-chat",
+    durableObjectBinding: "RAYBASE_AI_CHAT_AGENT",
+    triggerType: "chat",
+    instanceStrategy: "conversation"
+};
+export const raybaseAgentInternalReadPath = "/__raybase_agent_read";
+export const raybaseAgentInternalUserReadPath = "/__raybase_agent_user_read";
+export const raybaseAgentInternalCleanupPath = "/__raybase_agent_cleanup";
+export const raybaseAgentInternalUserPurgePath = "/__raybase_agent_user_purge";
+export const raybaseAgentInternalRehydratePath = "/__raybase_agent_rehydrate";
+export const raybaseAgentInternalRoomNoticePath = "/__raybase_agent_room_notice";
+export const raybaseAgentInternalRoomActivityPath = "/__raybase_agent_room_activity";
+export const raybaseAgentInternalRoomMembershipPath = "/__raybase_agent_room_membership";
+export const raybaseAgentInternalRoomRedactPath = "/__raybase_agent_room_redact";
+export const raybaseAgentSystemTables = [
+    ...raybaseAgentChapterSystemTables,
+    ...raybaseAgentChapterArchiveSystemTables,
+    ...raybaseAgentRoomSystemTables,
+    raybaseSystemTable("_agent_prompt_bands", {
+        id: id(),
+        agentName: text({ required: true }),
+        conversationId: text({ required: true }),
+        userId: text(),
+        bandName: text({ required: true }),
+        epochKey: text({ required: true }),
+        included: integer({ required: true }),
+        content: longText(),
+        totalChars: integer(),
+        truncatedAt: integer(),
+        updatedAt: text({ required: true })
+    }, {
+        indexes: [
+            ["agentName", "conversationId"],
+            ["userId"],
+            ["conversationId", "bandName"]
+        ]
+    }),
+    raybaseSystemTable("_agent_instances", {
+        id: id(),
+        conversationId: text({ required: true, unique: true }),
+        agentName: text({ required: true }),
+        agentTitle: text({ required: true }),
+        agentOwner: text(),
+        moduleId: text(),
+        runtime: text({ required: true }),
+        triggerType: text({ required: true }),
+        instanceKey: text({ required: true, unique: true }),
+        principalKind: text({ required: true }),
+        userId: text(),
+        publicScopeHash: text(),
+        organizationId: text(),
+        route: text(),
+        surface: text({ required: true }),
+        status: text({ required: true }),
+        cleanupRequestedAt: text(),
+        hotStorageDeletedAt: text(),
+        deletedAt: text(),
+        retentionReason: text(),
+        pinnedAt: text(),
+        createdAt: text({ required: true }),
+        updatedAt: text({ required: true }),
+        lastActiveAt: text({ required: true }),
+        expiresAt: text(),
+        lastRunId: text(),
+        lastError: longText(),
+        metadataJson: longText(),
+        entryKind: text(),
+        entryJson: longText(),
+        kind: text(),
+        roomMembershipRev: integer(),
+        lastReadAt: text()
+    }, {
+        indexes: [
+            ["agentName", "conversationId"],
+            ["principalKind", "userId", "updatedAt"],
+            ["principalKind", "publicScopeHash", "updatedAt"],
+            ["status", "expiresAt"],
+            ["instanceKey"]
+        ]
+    }),
+    raybaseSystemTable("_agent_runs", {
+        runId: id(),
+        conversationId: text({ required: true }),
+        agentName: text({ required: true }),
+        requestId: text({ required: true }),
+        triggerType: text({ required: true }),
+        inputMessageId: text(),
+        status: text({ required: true }),
+        startedAt: text({ required: true }),
+        /**
+         * The last moment this run was known to be making progress.
+         *
+         * `startedAt` cannot answer "is it still alive": it never moves, so a
+         * turn working steadily for six minutes and a turn whose writer died in
+         * its first second look identical to any reader outside the isolate. The
+         * staleness sweep read `startedAt`, could not tell those apart, and said
+         * so in its own comments — then failed live runs anyway (found 2026-08-25:
+         * a member watched "Birch ran into a problem while answering" arrive 24
+         * seconds before the same run delivered its answer).
+         *
+         * It is touched per model step rather than on a timer, and that is the
+         * point: a wedged turn stops beating and is still reaped, which is what
+         * the horizon is for. Null on rows written before the column existed, and
+         * every predicate coalesces to `startedAt` so those behave exactly as
+         * they used to.
+         */
+        heartbeatAt: text(),
+        finishedAt: text(),
+        error: longText(),
+        usageEventId: text(),
+        auditEventId: text(),
+        metadataJson: longText()
+    }, { indexes: [["conversationId", "startedAt"], ["agentName", "startedAt"], ["status", "startedAt"], ["requestId"]] }),
+    raybaseSystemTable("_agent_requests", {
+        id: id(),
+        conversationId: text({ required: true }),
+        requestKey: text({ required: true }),
+        messageId: text({ required: true }),
+        kind: text(),
+        authorUserId: text(),
+        disposition: text(),
+        runId: text(),
+        seq: integer(),
+        createdAt: text({ required: true }),
+        updatedAt: text({ required: true })
+    }, {
+        indexes: [
+            { columns: ["conversationId", "requestKey"], unique: true },
+            ["conversationId", "createdAt"],
+            ["runId"]
+        ]
+    }),
+    raybaseSystemTable("_agent_limit_windows", {
+        id: id(),
+        scope: text({ required: true }),
+        scopeId: text({ required: true }),
+        windowStart: text({ required: true }),
+        windowEnd: text({ required: true }),
+        requestCount: integer({ required: true }),
+        estimatedOutputTokens: integer({ required: true }),
+        updatedAt: text({ required: true })
+    }, { indexes: [{ columns: ["scope", "scopeId", "windowStart"], unique: true }, ["windowEnd"]] }),
+    raybaseSystemTable("_agent_schedules", {
+        id: id(),
+        agentName: text({ required: true }),
+        triggerIndex: integer({ required: true }),
+        triggerKey: text({ required: true }),
+        inputJson: longText(),
+        cron: text({ required: true }),
+        timezone: text(),
+        enabled: integer({ required: true }),
+        userMessage: longText(),
+        cronOverride: text(),
+        timezoneOverride: text(),
+        enabledOverride: integer(),
+        inputJsonOverride: longText(),
+        inputJsonOverrideEnabled: integer(),
+        userMessageOverride: longText(),
+        lastRunAt: text(),
+        nextRunAt: text(),
+        service: text(),
+        dispatchGeneration: integer(),
+        dispatchAttempts: integer(),
+        dispatchLeaseExpiresAt: text(),
+        lastDispatchAt: text(),
+        lastDispatchError: longText(),
+        createdAt: text({ required: true }),
+        updatedAt: text({ required: true })
+    }, {
+        indexes: [
+            ["agentName", "triggerIndex"],
+            ["enabled", "nextRunAt"],
+            ["enabledOverride", "nextRunAt"],
+            ["triggerKey"]
+        ]
+    }),
+    raybaseSystemTable("_agent_trigger_events", {
+        id: id(),
+        agentName: text({ required: true }),
+        triggerType: text({ required: true }),
+        triggerKey: text({ required: true }),
+        sourceTable: text(),
+        sourceOp: text(),
+        rowId: text(),
+        inputJson: longText(),
+        idempotencyKey: text({ unique: true }),
+        status: text({ required: true }),
+        runId: text(),
+        error: longText(),
+        createdAt: text({ required: true }),
+        updatedAt: text({ required: true })
+    }, {
+        indexes: [
+            ["agentName", "createdAt"],
+            ["triggerType", "status"],
+            ["sourceTable", "sourceOp", "createdAt"],
+            ["runId"]
+        ]
+    }),
+    ...raybaseAgentWakeSystemTables,
+    ...raybaseAgentFollowUpSystemTables,
+    ...raybaseAgentMemorySystemTables,
+    ...raybaseAgentSkillSystemTables
+];
+export const defaultAgentRunHistoryLimit = 20;
+export const maxAgentRunHistoryLimit = 100;
+const agentNamePattern = /^[A-Za-z][A-Za-z0-9_.:-]{0,127}$/;
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+const defaultConversationTtlSeconds = 60 * 60 * 4;
+const websocketBootstrapTtlSeconds = 30;
+const staleDeletingRetrySeconds = 10 * 60;
+const retryableCleanupStatuses = new Set(["active", "cleanupRequested", "cleanupError"]);
+const dataTriggerEventPattern = /^([A-Za-z][A-Za-z0-9_:-]*)\.(create|update|delete)$/;
+const agentEntryKindPattern = /^[a-z][a-z0-9-]{0,63}$/;
+export const maxAgentEntryPayloadBytes = 4 * 1024;
+export const maxAgentEntryKickoffChars = 4 * 1024;
+// Composed-turn and entry-kickoff daily caps ship with no default: unset means
+// unlimited. Both are runaway-loop guards in quota clothing, and the runtime
+// already serializes one turn per conversation and bounds loop steps per turn.
+// Apps that want a cap declare limits.composedPerDay / limits.entryKickoffPerDay
+// and get exactly the enforcement below.
+export function defineAgent(definition) {
+    validateAgentName(definition.name);
+    const runtime = definition.runtime;
+    if (runtime !== "ai-chat")
+        throw new Error(`Unsupported Raybase agent runtime: ${String(runtime)}`);
+    const unexpected = definition;
+    if (unexpected.scope !== undefined || unexpected.instance !== undefined) {
+        throw new Error("Raybase agent scope and instance fields are internal and cannot be declared by apps");
+    }
+    if (definition.prompt && definition.system !== undefined) {
+        throw new Error("Raybase agents cannot declare both system and prompt; use prompt.default for configurable prompt defaults");
+    }
+    if (definition.prompt?.configurable === true && !definition.prompt.default.trim()) {
+        throw new Error("Configurable Raybase agent prompts must provide a non-empty default prompt");
+    }
+    validateAgentConversationTitles(definition);
+    validateAgentSkillsForAgent(definition);
+    validateAgentSkillStoreForAgent(definition);
+    validateAgentRemoteMcpBindings(definition);
+    validateAgentMemoryForAgent(definition);
+    validateAgentWakesForAgent(definition);
+    validateAgentFollowUpsForAgent(definition);
+    validateAgentRetentionForAgent(definition);
+    validateAgentAllRuntimeToolNames(definition);
+    validateAgentCompaction(definition.compaction);
+    if (definition.limits?.composedPerDay !== undefined
+        && (!Number.isInteger(definition.limits.composedPerDay) || definition.limits.composedPerDay < 1)) {
+        throw new Error(`Raybase agent ${definition.name} limits.composedPerDay must be a positive integer`);
+    }
+    if (definition.limits?.entryKickoffPerDay !== undefined
+        && (!Number.isInteger(definition.limits.entryKickoffPerDay) || definition.limits.entryKickoffPerDay < 1)) {
+        throw new Error(`Raybase agent ${definition.name} limits.entryKickoffPerDay must be a positive integer`);
+    }
+    if (definition.limits?.loopReserveChars !== undefined
+        && (!Number.isInteger(definition.limits.loopReserveChars) || definition.limits.loopReserveChars < 0)) {
+        throw new Error(`Raybase agent ${definition.name} limits.loopReserveChars must be a non-negative integer`);
+    }
+    if (definition.compose?.renderContext !== undefined && typeof definition.compose.renderContext !== "boolean") {
+        throw new Error(`Raybase agent ${definition.name} compose.renderContext must be a boolean`);
+    }
+    if (definition.timeSentinel !== undefined && typeof definition.timeSentinel !== "boolean") {
+        throw new Error(`Raybase agent ${definition.name} timeSentinel must be a boolean`);
+    }
+    validateAgentExtensionPoints(definition);
+    const scopes = normalizeAgentScopes(definition.scopes, definition.name);
+    const triggers = normalizeAgentTriggers(definition.triggers, agentMemoryMaintenanceRuns(definition));
+    const normalized = { ...definition, runtime, triggers, ...(scopes ? { scopes } : {}) };
+    validateAgentEntriesForAgent(normalized);
+    validateAgentRoomsForAgent(normalized);
+    return normalized;
+}
+function normalizeAgentScopes(scopes, agentName) {
+    if (scopes === undefined)
+        return undefined;
+    if (!Array.isArray(scopes) || scopes.some((scope) => typeof scope !== "string" || !scope.trim())) {
+        throw new Error(`Raybase agent ${agentName} scopes must be an array of non-empty strings`);
+    }
+    return [...new Set(scopes.map((scope) => scope.trim()))];
+}
+function validateAgentExtensionPoints(agent) {
+    if (agent.turnState) {
+        if (typeof agent.turnState.load !== "function")
+            throw new Error(`Raybase agent ${agent.name} turnState.load must be a function`);
+        validateAgentHookTimeout(agent.name, "turnState", agent.turnState.timeoutMs);
+        validateAgentHookFailure(agent.name, "turnState", agent.turnState.onFailure);
+        const seenServicePrincipals = new Set();
+        for (const service of agent.turnState.servicePrincipals ?? []) {
+            if (!/^[A-Za-z][A-Za-z0-9_.:-]{0,127}$/.test(service)) {
+                throw new Error(`Raybase agent ${agent.name} turnState.servicePrincipals contains invalid service name ${String(service)}`);
+            }
+            if (seenServicePrincipals.has(service)) {
+                throw new Error(`Raybase agent ${agent.name} turnState.servicePrincipals declares ${service} more than once`);
+            }
+            seenServicePrincipals.add(service);
+        }
+    }
+    if (agent.promptHead !== undefined
+        && (!agent.promptHead
+            || typeof agent.promptHead !== "object"
+            || Array.isArray(agent.promptHead)
+            || (agent.promptHead.epoch !== "chapter" && agent.promptHead.epoch !== "turn"))) {
+        throw new Error(`Raybase agent ${agent.name} promptHead.epoch must be chapter or turn`);
+    }
+    if (agent.promptHead?.maxChars !== undefined
+        && (!Number.isInteger(agent.promptHead.maxChars) || agent.promptHead.maxChars < 1)) {
+        throw new Error(`Raybase agent ${agent.name} promptHead.maxChars must be a positive integer`);
+    }
+    if (agent.promptHead?.onOverflow !== undefined
+        && agent.promptHead.onOverflow !== "truncate"
+        && agent.promptHead.onOverflow !== "error") {
+        throw new Error(`Raybase agent ${agent.name} promptHead.onOverflow must be truncate or error`);
+    }
+    validateNamedAgentHooks(agent.name, "prompt band", agent.promptBands, ["chapter", "turn"]);
+    validateNamedAgentHooks(agent.name, "sentinel", agent.sentinels);
+    if (agent.delivery) {
+        if (agent.delivery.mode !== undefined && typeof agent.delivery.mode !== "function") {
+            throw new Error(`Raybase agent ${agent.name} delivery.mode must be a function`);
+        }
+        if (agent.delivery.gate !== undefined && typeof agent.delivery.gate !== "function") {
+            throw new Error(`Raybase agent ${agent.name} delivery.gate must be a function`);
+        }
+        if (agent.delivery.maxRetries !== undefined
+            && (!Number.isInteger(agent.delivery.maxRetries) || agent.delivery.maxRetries < 0 || agent.delivery.maxRetries > 2)) {
+            throw new Error(`Raybase agent ${agent.name} delivery.maxRetries must be an integer between 0 and 2`);
+        }
+        if (agent.delivery.maxReplacementChars !== undefined
+            && (!Number.isInteger(agent.delivery.maxReplacementChars)
+                || agent.delivery.maxReplacementChars < 1
+                || agent.delivery.maxReplacementChars > maxAgentDeliveryReplacementChars)) {
+            throw new Error(`Raybase agent ${agent.name} delivery.maxReplacementChars must be a positive integer no greater than ${maxAgentDeliveryReplacementChars}`);
+        }
+        if (agent.delivery.fallback !== undefined && agent.delivery.fallback !== "deliver" && agent.delivery.fallback !== "drop") {
+            throw new Error(`Raybase agent ${agent.name} delivery.fallback must be deliver or drop`);
+        }
+        if (agent.delivery.silenceSentinel !== undefined) {
+            const sentinel = agent.delivery.silenceSentinel;
+            for (const field of ["text", "silence"]) {
+                const value = sentinel?.[field];
+                if (typeof value !== "string" || value.length === 0 || value.length > 64 || value.trim() !== value) {
+                    throw new Error(`Raybase agent ${agent.name} delivery.silenceSentinel.${field} must be a trimmed string of 1 to 64 characters`);
+                }
+            }
+        }
+        validateAgentHookTimeout(agent.name, "delivery", agent.delivery.timeoutMs);
+        validateAgentHookFailure(agent.name, "delivery", agent.delivery.onFailure);
+    }
+    validateAgentConversationsConfig(agent);
+    if (agent.chapterClose) {
+        for (const key of ["prompt"]) {
+            const value = agent.chapterClose[key];
+            if (value !== undefined && (typeof value !== "string" || !value.trim())) {
+                throw new Error(`Raybase agent ${agent.name} chapterClose.${key} must be a non-empty string`);
+            }
+        }
+    }
+}
+function validateAgentConversationsConfig(agent) {
+    const conversations = agent.conversations;
+    if (conversations === undefined)
+        return;
+    if (!conversations || typeof conversations !== "object" || Array.isArray(conversations)) {
+        throw new Error(`Raybase agent ${agent.name} conversations must be an object`);
+    }
+    if (conversations.eligibility !== undefined && typeof conversations.eligibility !== "function") {
+        throw new Error(`Raybase agent ${agent.name} conversations.eligibility must be a function`);
+    }
+    if (conversations.onCommit !== undefined && typeof conversations.onCommit !== "function") {
+        throw new Error(`Raybase agent ${agent.name} conversations.onCommit must be a function`);
+    }
+    if (conversations.onSilence !== undefined && typeof conversations.onSilence !== "function") {
+        throw new Error(`Raybase agent ${agent.name} conversations.onSilence must be a function`);
+    }
+    if (conversations.onRead !== undefined && typeof conversations.onRead !== "function") {
+        throw new Error(`Raybase agent ${agent.name} conversations.onRead must be a function`);
+    }
+    if (conversations.onMessageMutation !== undefined && typeof conversations.onMessageMutation !== "function") {
+        throw new Error(`Raybase agent ${agent.name} conversations.onMessageMutation must be a function`);
+    }
+    validateAgentHookTimeout(agent.name, "conversations.eligibility", conversations.eligibilityTimeoutMs);
+    validateAgentHookFailure(agent.name, "conversations.eligibility", conversations.onEligibilityFailure);
+    const messages = conversations.messages;
+    if (messages === undefined)
+        return;
+    if (!messages || typeof messages !== "object" || Array.isArray(messages)) {
+        throw new Error(`Raybase agent ${agent.name} conversations.messages must be an object`);
+    }
+    for (const key of ["edit", "remove"]) {
+        const config = messages[key];
+        if (config === undefined)
+            continue;
+        if (!config
+            || typeof config !== "object"
+            || Array.isArray(config)
+            || !Number.isInteger(config.windowMs)
+            || config.windowMs < 1) {
+            throw new Error(`Raybase agent ${agent.name} conversations.messages.${key}.windowMs must be a positive integer`);
+        }
+    }
+    if (messages.reactions !== undefined
+        && (!messages.reactions
+            || typeof messages.reactions !== "object"
+            || Array.isArray(messages.reactions)
+            || messages.reactions.enabled !== true
+            || (messages.reactions.agentTool !== undefined && typeof messages.reactions.agentTool !== "boolean"))) {
+        throw new Error(`Raybase agent ${agent.name} conversations.messages.reactions must enable reactions and may set agentTool`);
+    }
+    const attachments = messages.attachments;
+    if (attachments !== undefined) {
+        if (!attachments
+            || typeof attachments !== "object"
+            || Array.isArray(attachments)
+            || attachments.enabled !== true
+            || typeof attachments.bucket !== "string"
+            || !attachments.bucket.trim()) {
+            throw new Error(`Raybase agent ${agent.name} conversations.messages.attachments must enable attachments and name a bucket`);
+        }
+        validateOptionalPositiveInteger(agent.name, "maxPerMessage", attachments.maxPerMessage);
+        validateOptionalPositiveInteger(agent.name, "maxBytesPerFile", attachments.maxBytesPerFile);
+        if ((attachments.maxBytesPerFile ?? 0) > storageHardMaxSizeBytes) {
+            throw new Error(`Raybase agent ${agent.name} conversations.messages.attachments.maxBytesPerFile exceeds the storage hard cap`);
+        }
+        if (attachments.mediaTypes !== undefined) {
+            if (!Array.isArray(attachments.mediaTypes)
+                || !attachments.mediaTypes.length
+                || attachments.mediaTypes.some((value) => typeof value !== "string" || !/^image\/[A-Za-z0-9.+-]+$/.test(value))) {
+                throw new Error(`Raybase agent ${agent.name} conversations.messages.attachments.mediaTypes must contain image media types`);
+            }
+        }
+        const recentMessages = attachments.resolveForModel?.recentMessages;
+        if (attachments.resolveForModel !== undefined
+            && (!attachments.resolveForModel
+                || typeof attachments.resolveForModel !== "object"
+                || Array.isArray(attachments.resolveForModel)
+                || (recentMessages !== undefined && (!Number.isInteger(recentMessages) || recentMessages < 0)))) {
+            throw new Error(`Raybase agent ${agent.name} conversations.messages.attachments.resolveForModel.recentMessages must be a non-negative integer`);
+        }
+    }
+    const voiceNotes = messages.voiceNotes;
+    if (voiceNotes !== undefined) {
+        if (!voiceNotes
+            || typeof voiceNotes !== "object"
+            || Array.isArray(voiceNotes)
+            || voiceNotes.enabled !== true) {
+            throw new Error(`Raybase agent ${agent.name} conversations.messages.voiceNotes must enable voice notes`);
+        }
+        if (!attachments?.enabled) {
+            throw new Error(`Raybase agent ${agent.name} conversations.messages.voiceNotes requires attachments to be enabled`);
+        }
+        validateOptionalPositiveInteger(agent.name, "voiceNotes.maxSeconds", voiceNotes.maxSeconds);
+    }
+    validateAgentUserDataPartsConfig(agent.name, messages.userDataParts);
+}
+function validateOptionalPositiveInteger(agentName, key, value) {
+    if (value !== undefined && (!Number.isInteger(value) || value < 1)) {
+        const path = key.startsWith("voiceNotes.") ? key : `attachments.${key}`;
+        throw new Error(`Raybase agent ${agentName} conversations.messages.${path} must be a positive integer`);
+    }
+}
+export function agentConversationAttachmentsConfig(agent) {
+    const config = agent.conversations?.messages?.attachments;
+    if (!config)
+        return null;
+    return {
+        enabled: true,
+        bucket: config.bucket.trim(),
+        maxPerMessage: config.maxPerMessage ?? defaultAgentAttachmentMaxPerMessage,
+        maxBytesPerFile: config.maxBytesPerFile ?? defaultAgentAttachmentMaxBytesPerFile,
+        mediaTypes: [...(config.mediaTypes ?? defaultAgentAttachmentMediaTypes)],
+        resolveForModel: {
+            recentMessages: config.resolveForModel?.recentMessages ?? defaultAgentAttachmentRecentMessages
+        }
+    };
+}
+export function agentConversationVoiceNotesConfig(agent) {
+    const attachments = agentConversationAttachmentsConfig(agent);
+    if (!attachments)
+        return null;
+    return normalizeAgentVoiceNotesConfig(agent.conversations?.messages?.voiceNotes, attachments.maxBytesPerFile);
+}
+export function validateAgentAttachmentStorage(agents, storage) {
+    for (const agent of Object.values(agents)) {
+        const attachments = agentConversationAttachmentsConfig(agent);
+        if (!attachments)
+            continue;
+        if (!storage?.buckets[attachments.bucket]) {
+            throw new Error(`Raybase agent ${agent.name} attachment bucket ${attachments.bucket} is not configured in storage`);
+        }
+        const voiceNotes = agentConversationVoiceNotesConfig(agent);
+        const acceptedMediaTypes = storage.buckets[attachments.bucket]?.accept;
+        if (voiceNotes && acceptedMediaTypes && !acceptedMediaTypes.includes("audio/wav")) {
+            throw new Error(`Raybase agent ${agent.name} voice note bucket ${attachments.bucket} must accept audio/wav`);
+        }
+    }
+}
+export function agentConversationEligibilityConfig(agent, conversationKind) {
+    const conversations = agent.conversations;
+    if (conversationKind !== "room")
+        return conversations ?? {};
+    return {
+        eligibility: agent.rooms?.eligibility ?? conversations?.eligibility,
+        eligibilityTimeoutMs: agent.rooms?.eligibilityTimeoutMs ?? conversations?.eligibilityTimeoutMs,
+        onEligibilityFailure: agent.rooms?.onEligibilityFailure ?? conversations?.onEligibilityFailure
+    };
+}
+function validateNamedAgentHooks(agentName, label, hooks, epochs) {
+    if (hooks === undefined)
+        return;
+    if (!Array.isArray(hooks))
+        throw new Error(`Raybase agent ${agentName} ${label}s must be an array`);
+    const seen = new Set();
+    for (const [index, hook] of hooks.entries()) {
+        if (!hook || typeof hook !== "object")
+            throw new Error(`Raybase agent ${agentName} ${label} at index ${index} must be an object`);
+        validateRaybaseName("agent", hook.name);
+        if (seen.has(hook.name))
+            throw new Error(`Raybase agent ${agentName} declares duplicate ${label} ${hook.name}`);
+        seen.add(hook.name);
+        if (typeof hook.render !== "function")
+            throw new Error(`Raybase agent ${agentName} ${label} ${hook.name} render must be a function`);
+        if (hook.when !== undefined && typeof hook.when !== "function") {
+            throw new Error(`Raybase agent ${agentName} ${label} ${hook.name} when must be a function`);
+        }
+        if (epochs && hook.epoch !== undefined && !epochs.includes(String(hook.epoch))) {
+            throw new Error(`Raybase agent ${agentName} ${label} ${hook.name} has invalid epoch ${String(hook.epoch)}`);
+        }
+        if (hook.maxChars !== undefined && (!Number.isInteger(hook.maxChars) || hook.maxChars < 1)) {
+            throw new Error(`Raybase agent ${agentName} ${label} ${hook.name} maxChars must be a positive integer`);
+        }
+        if (hook.onOverflow !== undefined && hook.onOverflow !== "truncate" && hook.onOverflow !== "error") {
+            throw new Error(`Raybase agent ${agentName} ${label} ${hook.name} onOverflow must be truncate or error`);
+        }
+        if (hook.trust !== undefined && (label !== "sentinel" || hook.trust !== "app" && hook.trust !== "data")) {
+            throw new Error(`Raybase agent ${agentName} ${label} ${hook.name} trust must be app or data`);
+        }
+    }
+}
+function validateAgentHookTimeout(agentName, label, timeoutMs) {
+    if (timeoutMs !== undefined && (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 60_000)) {
+        throw new Error(`Raybase agent ${agentName} ${label}.timeoutMs must be between 1 and 60000`);
+    }
+}
+function validateAgentHookFailure(agentName, label, failure) {
+    if (failure !== undefined && failure !== "fail-turn" && failure !== "continue-empty") {
+        throw new Error(`Raybase agent ${agentName} ${label}.onFailure must be fail-turn or continue-empty`);
+    }
+}
+export function validateAgentEntriesForAgent(agent) {
+    const entries = agent.entries;
+    if (entries === undefined)
+        return;
+    if (!entries || typeof entries !== "object" || Array.isArray(entries)) {
+        throw new Error(`Raybase agent ${agent.name} entries must be an object`);
+    }
+    if (!agent.triggers?.some((trigger) => trigger.type === "chat")) {
+        throw new Error(`Raybase agent ${agent.name} declares entries but has no chat trigger`);
+    }
+    for (const [kind, definition] of Object.entries(entries)) {
+        if (!agentEntryKindPattern.test(kind)) {
+            throw new Error(`Raybase agent ${agent.name} entry kind "${kind}" must be a lowercase slug`);
+        }
+        if (!definition || typeof definition !== "object" || Array.isArray(definition)) {
+            throw new Error(`Raybase agent ${agent.name} entry ${kind} must be an object`);
+        }
+        if (typeof definition.description !== "string" || !definition.description.trim()) {
+            throw new Error(`Raybase agent ${agent.name} entry ${kind} requires a description`);
+        }
+        const source = definition.source ?? "inline";
+        if (source !== "inline" && source !== "notification") {
+            throw new Error(`Raybase agent ${agent.name} entry ${kind} has an invalid source`);
+        }
+        if (definition.payloadSchema !== undefined)
+            validateAgentEntrySchema(agent.name, kind, definition.payloadSchema);
+        if (definition.userMessage !== undefined) {
+            if (typeof definition.userMessage !== "string" || !definition.userMessage.trim()) {
+                throw new Error(`Raybase agent ${agent.name} entry ${kind} has an invalid userMessage`);
+            }
+            if (definition.userMessage.length > maxAgentEntryKickoffChars) {
+                throw new Error(`Raybase agent ${agent.name} entry ${kind} userMessage exceeds ${maxAgentEntryKickoffChars} characters`);
+            }
+        }
+        const audiences = definition.audience ?? ["signed-in"];
+        if (!Array.isArray(audiences) || audiences.length === 0 || audiences.some((audience) => audience !== "signed-in" && audience !== "public")) {
+            throw new Error(`Raybase agent ${agent.name} entry ${kind} has an invalid audience`);
+        }
+        if (definition.userMessage && audiences.includes("public")) {
+            throw new Error(`Raybase agent ${agent.name} entry ${kind} cannot declare a kickoff userMessage for a public audience`);
+        }
+    }
+}
+function validateAgentEntrySchema(agentName, kind, schema) {
+    if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
+        throw new Error(`Raybase agent ${agentName} entry ${kind} payloadSchema must be a JSON Schema object`);
+    }
+    const allowedTypes = new Set(["object", "array", "string", "number", "integer", "boolean", "null"]);
+    const visit = (node, path) => {
+        if (!node || typeof node !== "object" || Array.isArray(node))
+            throw new Error(`${path} must be a JSON Schema object`);
+        if (node.type !== undefined && (typeof node.type !== "string" || !allowedTypes.has(node.type)))
+            throw new Error(`${path}.type is unsupported`);
+        if (node.properties !== undefined) {
+            if (!node.properties || typeof node.properties !== "object" || Array.isArray(node.properties))
+                throw new Error(`${path}.properties must be an object`);
+            for (const [key, child] of Object.entries(node.properties))
+                visit(child, `${path}.properties.${key}`);
+        }
+        if (node.items !== undefined)
+            visit(node.items, `${path}.items`);
+    };
+    visit(schema, `Raybase agent ${agentName} entry ${kind} payloadSchema`);
+}
+export function agentEntryDefinition(agent, kind) {
+    const definition = agent.entries?.[kind];
+    if (!definition)
+        throw new AgentHttpError(`Unknown agent entry kind: ${kind}`, 400);
+    return definition;
+}
+export function agentEntryAudiences(definition) {
+    return uniqueAudiences(definition.audience ?? ["signed-in"]);
+}
+export function validateInlineAgentEntryPayload(definition, payload) {
+    let serialized;
+    try {
+        serialized = stableJson(payload ?? null);
+    }
+    catch {
+        throw new AgentHttpError("Agent entry payload must be JSON serializable", 400);
+    }
+    if (encoder.encode(serialized).byteLength > maxAgentEntryPayloadBytes) {
+        throw new AgentHttpError(`Agent entry payload exceeds ${maxAgentEntryPayloadBytes} bytes`, 400);
+    }
+    if (!definition.payloadSchema)
+        return payload;
+    try {
+        return validateJsonSchema(definition.payloadSchema, payload, "entry.payload");
+    }
+    catch (error) {
+        throw new AgentHttpError(error instanceof Error ? error.message : "Agent entry payload is invalid", 400);
+    }
+}
+export function agentEntryFromInstance(instance) {
+    if (!instance.entryKind || !instance.entryJson)
+        return undefined;
+    try {
+        const parsed = JSON.parse(instance.entryJson);
+        if (parsed?.kind !== instance.entryKind || (parsed.source !== "inline" && parsed.source !== "notification"))
+            return undefined;
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+function validateAgentConversationTitles(agent) {
+    const config = agent.conversationTitles;
+    if (config === undefined || config === "auto")
+        return;
+    if (config && typeof config === "object" && !Array.isArray(config)) {
+        if (config.model === undefined || (typeof config.model === "string" && config.model.trim()))
+            return;
+        throw new Error(`Raybase agent ${agent.name} conversationTitles.model must be a non-empty string`);
+    }
+    throw new Error(`Raybase agent ${agent.name} conversationTitles must be "auto" or an object like { model }`);
+}
+export function agentConversationTitlesConfig(agent) {
+    const config = agent.conversationTitles;
+    if (config === undefined)
+        return null;
+    if (config === "auto")
+        return { model: null };
+    return { model: config.model?.trim() || null };
+}
+function validateAgentCompaction(compaction) {
+    if (compaction === undefined)
+        return;
+    if (!compaction || typeof compaction !== "object" || Array.isArray(compaction)) {
+        throw new Error("Raybase agent compaction must be an object");
+    }
+    if (compaction.enabled !== undefined && typeof compaction.enabled !== "boolean") {
+        throw new Error("Raybase agent compaction enabled must be a boolean");
+    }
+    if (compaction.model !== undefined && (typeof compaction.model !== "string" || !compaction.model.trim())) {
+        throw new Error("Raybase agent compaction model must be a non-empty string");
+    }
+    if (compaction.keepRecentMessages !== undefined && (!Number.isInteger(compaction.keepRecentMessages) || compaction.keepRecentMessages < 1)) {
+        throw new Error("Raybase agent compaction keepRecentMessages must be an integer of at least 1");
+    }
+    if (compaction.triggerRatio !== undefined && (typeof compaction.triggerRatio !== "number" || !(compaction.triggerRatio > 0) || compaction.triggerRatio > 1)) {
+        throw new Error("Raybase agent compaction triggerRatio must be a number greater than 0 and at most 1");
+    }
+    if (compaction.minSummaryOutputTokens !== undefined && (!Number.isInteger(compaction.minSummaryOutputTokens) || compaction.minSummaryOutputTokens < 1)) {
+        throw new Error("Raybase agent compaction minSummaryOutputTokens must be an integer of at least 1");
+    }
+    if (compaction.summarySpanRatio !== undefined && (typeof compaction.summarySpanRatio !== "number" || !(compaction.summarySpanRatio > 0) || compaction.summarySpanRatio > 1)) {
+        throw new Error("Raybase agent compaction summarySpanRatio must be a number greater than 0 and at most 1");
+    }
+    if (compaction.maxSummaryOutputTokens !== undefined && (!Number.isInteger(compaction.maxSummaryOutputTokens) || compaction.maxSummaryOutputTokens < 1)) {
+        throw new Error("Raybase agent compaction maxSummaryOutputTokens must be an integer of at least 1");
+    }
+    // Only checked when both are pinned: a lone maxSummaryOutputTokens pin below
+    // the default floor is the pre-proportional flat budget and must stay valid.
+    if (compaction.minSummaryOutputTokens !== undefined
+        && compaction.maxSummaryOutputTokens !== undefined
+        && compaction.minSummaryOutputTokens > compaction.maxSummaryOutputTokens) {
+        throw new Error("Raybase agent compaction minSummaryOutputTokens must not exceed maxSummaryOutputTokens");
+    }
+}
+function validateAgentAllRuntimeToolNames(agent) {
+    const seen = new Map();
+    const add = (toolName, source) => {
+        const existing = seen.get(toolName);
+        if (existing)
+            throw new Error(`Raybase agent ${agent.name} has duplicate runtime tool name "${toolName}" from ${existing} and ${source}`);
+        seen.set(toolName, source);
+    };
+    // Uniqueness always covers the full registered set; per-turn offer gates
+    // never relax it.
+    for (const { action } of agentActionRegistrations(agent.actions))
+        add(agentActionToolName(action.name), `direct action ${action.name}`);
+    for (const binding of agentSkillActionBindings(agent))
+        add(binding.modelToolName, `skill ${binding.skill.name} action ${binding.action.name}`);
+    const skillRegistrations = agentSkillRegistrations(agent.skills, agent.name);
+    if (skillRegistrations.some(({ policy, mode, skill }) => Boolean(skill.guidance) && (Boolean(policy) || mode !== "include" && mode !== "excluded")) || agent.skillStore?.enabled === true) {
+        add("load_agent_skill", "built-in skill loader");
+    }
+    if (skillRegistrations.some(({ policy, mode, skill }) => (Boolean(policy) || mode !== "excluded") && (Boolean(skill.files?.length) || Boolean(skill.guidance && skill.guidance.length > (skill.maxChars ?? (skill.ephemeral ? 4_000 : 8_000))))) || agent.skillStore?.enabled === true) {
+        add("read_skill", "built-in skill reader");
+    }
+    for (const binding of agentRemoteMcpToolBindings(agent))
+        add(binding.modelToolName, `remote MCP ${binding.server.name}/${binding.toolName}`);
+    if (agentMemorySpaces(agent).length) {
+        for (const toolName of raybaseAgentMemoryToolNames)
+            add(toolName, "built-in memory tool");
+    }
+    if (agent.skillStore?.enabled === true) {
+        const access = agent.skillStore.agentAccess ?? {};
+        for (const name of raybaseAgentSkillToolNames) {
+            const mutating = name === "skill_write" ? access.create : name === "skill_edit" ? access.edit : name === "skill_delete" ? access.delete : name === "skill_set_enabled" ? access.setEnabled : name.startsWith("skill_import_") ? Boolean(access.importSources?.length) : true;
+            if (mutating)
+                add(name, "built-in database skill tool");
+        }
+    }
+    if (agent.wakes?.enabled === true) {
+        for (const toolName of raybaseAgentWakeToolNames)
+            add(toolName, "built-in wake tool");
+    }
+    if (agent.followUps?.enabled === true) {
+        for (const toolName of ["follow_up", "list_follow_ups", "close_follow_up"])
+            add(toolName, "built-in follow-up tool");
+    }
+    if (agent.conversations?.messages?.reactions?.agentTool === true) {
+        add("react", "built-in conversation reaction tool");
+    }
+}
+function normalizeAgentTriggers(triggers, maintenanceRuns = []) {
+    const declared = triggers?.length ? triggers : [{ type: "chat" }];
+    const existingMaintenance = new Set();
+    for (const [index, trigger] of declared.entries()) {
+        if (trigger?.type === "schedule" && trigger.maintenance !== undefined) {
+            const run = maintenanceRuns.find((candidate) => candidate.name === trigger.maintenance);
+            if (!run
+                || trigger.cron !== run.schedule.cron
+                || (trigger.timezone ?? undefined) !== run.schedule.timezone
+                || trigger.userMessage !== run.instruction) {
+                throw new Error(`Raybase agent schedule trigger at index ${index} cannot declare maintenance directly; use memory.maintenance`);
+            }
+            existingMaintenance.add(trigger.maintenance);
+        }
+    }
+    const normalized = [
+        ...declared,
+        ...maintenanceRuns.filter((run) => !existingMaintenance.has(run.name)).map((run) => ({
+            type: "schedule",
+            cron: run.schedule.cron,
+            ...(run.schedule.timezone ? { timezone: run.schedule.timezone } : {}),
+            userMessage: run.instruction,
+            maintenance: run.name
+        }))
+    ];
+    const seen = new Set();
+    return normalized.map((trigger, index) => {
+        if (!trigger || typeof trigger !== "object")
+            throw new Error(`Raybase agent trigger at index ${index} must be an object`);
+        let key;
+        if (trigger.type === "chat") {
+            key = "chat";
+        }
+        else if (trigger.type === "schedule") {
+            if (typeof trigger.cron !== "string" || !trigger.cron.trim())
+                throw new Error(`Raybase agent schedule trigger at index ${index} requires cron`);
+            validateCron(trigger.cron);
+            if (trigger.timezone !== undefined && typeof trigger.timezone !== "string")
+                throw new Error(`Raybase agent schedule trigger at index ${index} has invalid timezone`);
+            if (trigger.userMessage !== undefined) {
+                if (typeof trigger.userMessage !== "string" || !trigger.userMessage.trim()) {
+                    throw new Error(`Raybase agent schedule trigger at index ${index} has invalid userMessage`);
+                }
+                trigger = { ...trigger, userMessage: trigger.userMessage.trim() };
+            }
+            key = trigger.maintenance
+                ? `maintenance:${trigger.maintenance}`
+                : `schedule:${trigger.cron}:${trigger.timezone ?? "UTC"}:${stableJson(trigger.input ?? null)}`;
+        }
+        else if (trigger.type === "data") {
+            if (typeof trigger.event !== "string" || !dataTriggerEventPattern.test(trigger.event)) {
+                throw new Error(`Raybase agent data trigger at index ${index} must use table.create, table.update, or table.delete`);
+            }
+            key = `data:${trigger.event}:${trigger.includeAdmin === true}:${stableJson(trigger.input ?? null)}`;
+        }
+        else {
+            throw new Error(`Unsupported Raybase agent trigger type: ${String(trigger.type)}`);
+        }
+        if (seen.has(key))
+            throw new Error(`Duplicate Raybase agent trigger: ${key}`);
+        seen.add(key);
+        return trigger;
+    });
+}
+export function validateAgentTriggers(agents, schema) {
+    const tableNames = new Set(Object.values(schema.tables).map((table) => table.name));
+    for (const agent of Object.values(defineAgents(agents ?? {}))) {
+        agent.triggers.forEach((trigger, index) => {
+            if (trigger.type !== "data")
+                return;
+            const parsed = parseAgentDataTriggerEvent(trigger.event);
+            if (!tableNames.has(parsed.tableName)) {
+                throw new Error(`Raybase agent ${agent.name} data trigger ${index} references unknown table ${parsed.tableName}`);
+            }
+        });
+    }
+}
+export function parseAgentDataTriggerEvent(event) {
+    const match = event.match(dataTriggerEventPattern);
+    if (!match)
+        throw new Error(`Invalid Raybase agent data trigger event: ${event}`);
+    return { tableName: match[1], op: match[2] };
+}
+export function defineAgents(agents) {
+    const seen = new Set();
+    const normalized = {};
+    for (const [key, agent] of Object.entries(agents)) {
+        const name = agent.name || key;
+        validateAgentName(name);
+        if (seen.has(name))
+            throw new Error(`Duplicate Raybase agent name: ${name}`);
+        seen.add(name);
+        normalized[key] = defineAgent({ ...agent, name });
+    }
+    return normalized;
+}
+export function validateAgentName(name) {
+    if (!agentNamePattern.test(name)) {
+        throw new Error(`Invalid Raybase agent name "${name}". Use letters, numbers, "_", "-", ".", or ":".`);
+    }
+}
+export function agentSummaries(agents) {
+    return Object.values(defineAgents(agents ?? {})).map((agent) => ({
+        name: agent.name,
+        title: agent.title ?? agent.name,
+        description: agent.description ?? "",
+        runtime: agent.runtime,
+        triggers: agent.triggers,
+        model: agent.model ?? null,
+        limits: agent.limits ?? null,
+        scopes: agent.scopes ?? [],
+        owner: agent.owner ?? null,
+        actions: agentActionRegistrations(agent.actions).map(({ action }) => ({ name: action.name, description: action.description ?? "" })),
+        skills: agentSkillSummaries(agent.skills),
+        skillStore: agent.skillStore ?? null,
+        remoteMcpBindings: agentRemoteMcpBindingSummaries([agent]),
+        memorySpaces: agentMemorySpaces(agent),
+        rooms: agent.rooms?.enabled === true,
+        entries: Object.entries(agent.entries ?? {}).map(([kind, definition]) => ({
+            kind,
+            description: definition.description,
+            source: definition.source ?? "inline",
+            audience: agentEntryAudiences(definition),
+            hasKickoff: Boolean(definition.userMessage),
+            payloadSchema: definition.payloadSchema ?? null
+        })),
+        runtimeControl: {
+            configurable: agent.runtimeControl?.configurable === true,
+            defaultEnabled: agent.runtimeControl?.defaultEnabled !== false
+        },
+        prompt: agent.prompt
+            ? {
+                configurable: agent.prompt.configurable === true,
+                renderer: agent.prompt.renderer ?? "liquid",
+                default: agent.prompt.default
+            }
+            : null
+    }));
+}
+export function agentFor(agents, name) {
+    const registry = defineAgents(agents ?? {});
+    const agent = Object.values(registry).find((candidate) => candidate.name === name || candidate.name.toLowerCase() === name.toLowerCase());
+    if (!agent)
+        throw new AgentHttpError(`Unknown agent: ${name}`, 404);
+    return agent;
+}
+export class AgentHttpError extends Error {
+    status;
+    retryable;
+    constructor(message, status, retryable = false) {
+        super(message);
+        this.status = status;
+        this.retryable = retryable;
+    }
+}
+export function agentAudienceKinds(audience, surface) {
+    const configured = audience ?? "signed-in";
+    if (Array.isArray(configured))
+        return uniqueAudiences(configured);
+    if (typeof configured === "string")
+        return [configured];
+    const value = configured[surface] ?? configured.default ?? configured.app ?? "signed-in";
+    return Array.isArray(value) ? uniqueAudiences(value) : [value];
+}
+export function agentAudienceAllows(audience, surface, kind) {
+    return agentAudienceKinds(audience, surface).includes(kind);
+}
+export function agentRequestSurface(request, surfaces = []) {
+    const url = new URL(request.url);
+    const referer = request.headers.get("referer");
+    const requestedRoute = request.headers.get("x-raybase-agent-route");
+    const requestedSurface = request.headers.get("x-raybase-agent-surface");
+    let route = url.pathname || "/";
+    let origin = request.headers.get("origin") ?? undefined;
+    if (requestedRoute?.trim()) {
+        route = requestedRoute.trim();
+    }
+    else if (referer) {
+        try {
+            const ref = new URL(referer);
+            if (ref.origin === url.origin) {
+                route = ref.pathname || "/";
+                origin = ref.origin;
+            }
+        }
+        catch {
+            // Keep the API route when Referer is malformed.
+        }
+    }
+    const normalizedRoute = normalizeRoute(route);
+    const inferredSurface = surfaces.find((entry) => {
+        const prefix = normalizeRoute(entry.pathPrefix);
+        return normalizedRoute === prefix || normalizedRoute.startsWith(`${prefix.replace(/\/$/, "")}/`);
+    })?.surface ?? "app";
+    const surface = requestedSurface?.trim() || inferredSurface;
+    return { surface, route: normalizedRoute, origin };
+}
+export async function resolveAgentAccess(input) {
+    const requestContext = agentRequestSurface(input.request, input.surfaces);
+    const allowed = agentAudienceKinds(input.agent.audience, requestContext.surface);
+    const requestedKind = input.principalKind;
+    const organizationId = input.organizationId ?? principalOrganizationId(input.user);
+    if (requestedKind === "user" || (!requestedKind && allowed.includes("signed-in") && input.user)) {
+        if (!allowed.includes("signed-in"))
+            throw new AgentHttpError("Agent surface does not allow signed-in access", 403);
+        if (!input.user)
+            throw new AgentHttpError("Authentication required", 401);
+        return {
+            audience: "signed-in",
+            principal: {
+                kind: "user",
+                user: input.user,
+                userId: input.user.id,
+                membershipId: optionalUserField(input.user, "membershipId"),
+                organizationId: organizationId ?? undefined,
+                roles: input.user.appRoles
+            },
+            surface: requestContext.surface,
+            route: requestContext.route,
+            origin: requestContext.origin,
+            organizationId
+        };
+    }
+    if (requestedKind === "public" || (!requestedKind && allowed.includes("public"))) {
+        if (!allowed.includes("public"))
+            throw new AgentHttpError("Agent surface does not allow public access", 403);
+        return {
+            audience: "public",
+            principal: await publicAgentPrincipal(input.request, organizationId, requestContext),
+            surface: requestContext.surface,
+            route: requestContext.route,
+            origin: requestContext.origin,
+            organizationId
+        };
+    }
+    throw new AgentHttpError("Authentication required", 401);
+}
+export function publicAgentUser(principal) {
+    return {
+        id: `public:${principal.id}`,
+        email: "public@raybase.local",
+        name: "Public visitor",
+        operatorRole: null,
+        appRoles: []
+    };
+}
+export function agentInstanceKey(agentName, conversationId) {
+    return `raybase-agent:${agentName}:${conversationId}`;
+}
+export function agentExpiresAt(ttlSeconds = defaultConversationTtlSeconds) {
+    if (ttlSeconds === null)
+        return null;
+    return new Date(wallNowMs() + ttlSeconds * 1000).toISOString();
+}
+export async function createOrResumeAgentInstance(input) {
+    const now = nowIso();
+    const retention = normalizeAgentRetentionConfig(input.agent.retention);
+    const isUserPrincipal = input.access.principal.kind === "user";
+    const keepHot = isUserPrincipal && retention.transcripts === "keep-hot";
+    const defaultTtlSeconds = isUserPrincipal ? retention.hotTtlMs / 1000 : retention.publicHotTtlMs / 1000;
+    const expiresAt = agentExpiresAt(keepHot ? null : input.ttlSeconds ?? defaultTtlSeconds);
+    if (input.conversationId) {
+        const existing = await findAgentInstance(input.control, input.agent.name, input.conversationId);
+        if (!existing)
+            throw new AgentHttpError("Agent conversation not found", 404);
+        if (existing.retentionReason === "user-deleted")
+            throw new AgentHttpError("Agent conversation has been deleted", 410);
+        await assertAgentConversationAccess({ control: input.control, instance: existing, access: input.access });
+        if (existing.status === "deleted")
+            throw new AgentHttpError("Agent conversation has been deleted", 410);
+        if (existing.status === "deleting" || existing.status === "cleanupRequested") {
+            throw new AgentHttpError("Agent conversation cleanup is in progress", 409);
+        }
+        if (existing.status === "cleanupError") {
+            throw new AgentHttpError("Agent conversation cleanup must complete before it can resume", 503);
+        }
+        if (input.entry && stableJson(input.entry) !== (existing.entryJson ?? "")) {
+            throw new AgentHttpError("Agent conversation entry context conflicts with the existing snapshot", 409);
+        }
+        const metadataJson = agentInstanceMetadataJson({
+            current: existing.metadataJson,
+            metadata: input.metadata,
+            title: input.title
+        });
+        if (existing.status === "archived") {
+            const lastChapter = await loadLastAgentChapter(input.control, existing.conversationId);
+            if (!lastChapter) {
+                throw new AgentHttpError("Archived conversation context is unavailable; retry later", 503);
+            }
+            if (!input.rehydrateArchived) {
+                throw new AgentHttpError("Agent conversation rehydration is unavailable", 503);
+            }
+            const synopsis = buildAgentChapterRehydrateSeed(lastChapter);
+            try {
+                await input.rehydrateArchived(existing, synopsis);
+            }
+            catch (error) {
+                throw new AgentHttpError(`Agent conversation rehydration failed: ${error instanceof Error ? error.message : String(error)}`, 503);
+            }
+            await input.control.run(`UPDATE ${q("_agent_instances")}
+         SET "status" = 'active', "cleanupRequestedAt" = NULL, "deletedAt" = NULL, "retentionReason" = NULL,
+             "updatedAt" = ?, "lastActiveAt" = ?, "expiresAt" = ?, "route" = ?, "surface" = ?,
+             "metadataJson" = ?, "lastError" = NULL
+         WHERE "id" = ? AND "status" = 'archived'`, [
+                now,
+                now,
+                expiresAt,
+                input.access.route,
+                input.access.surface,
+                metadataJson,
+                existing.id
+            ]);
+            const activated = await findAgentInstance(input.control, input.agent.name, input.conversationId);
+            if (activated?.status === "active")
+                return activated;
+            if (activated?.status === "archived") {
+                throw new AgentHttpError("Agent conversation rehydration activation did not complete", 503);
+            }
+            throw new AgentHttpError("Agent conversation changed while rehydrating", 409);
+        }
+        await input.control.run(`UPDATE ${q("_agent_instances")}
+       SET "status" = 'active', "cleanupRequestedAt" = NULL, "deletedAt" = NULL, "updatedAt" = ?, "lastActiveAt" = ?,
+           "expiresAt" = ?, "route" = ?, "surface" = ?, "metadataJson" = ?, "lastError" = NULL
+       WHERE "id" = ? AND "status" = 'active'
+         AND COALESCE("retentionReason", '') <> 'user-deleted'`, [
+            now,
+            now,
+            expiresAt,
+            input.access.route,
+            input.access.surface,
+            metadataJson,
+            existing.id
+        ]);
+        const refreshed = await findAgentInstance(input.control, input.agent.name, input.conversationId);
+        if (!refreshed)
+            throw new AgentHttpError("Agent conversation not found", 404);
+        if (refreshed.retentionReason === "user-deleted" || refreshed.status === "deleted") {
+            throw new AgentHttpError("Agent conversation has been deleted", 410);
+        }
+        if (refreshed.status === "cleanupRequested" || refreshed.status === "deleting" || refreshed.status === "archived") {
+            throw new AgentHttpError("Agent conversation changed while resuming; retry", 409);
+        }
+        if (refreshed.status === "cleanupError") {
+            throw new AgentHttpError("Agent conversation cleanup must complete before it can resume", 503);
+        }
+        return refreshed;
+    }
+    const conversationId = randomId("agent_conv");
+    const idValue = randomId("agent_inst");
+    const row = {
+        id: idValue,
+        conversationId,
+        agentName: input.agent.name,
+        agentTitle: input.agent.title ?? input.agent.name,
+        agentOwner: input.agent.owner?.packageName ?? input.agent.owner?.moduleId ?? null,
+        moduleId: input.agent.owner?.moduleId ?? null,
+        runtime: input.agent.runtime,
+        triggerType: "chat",
+        instanceKey: agentInstanceKey(input.agent.name, conversationId),
+        principalKind: input.access.principal.kind,
+        userId: input.access.principal.kind === "user" ? input.access.principal.user.id : null,
+        publicScopeHash: input.access.principal.kind === "public" ? input.access.principal.id : null,
+        organizationId: input.access.organizationId ?? null,
+        route: input.access.route,
+        surface: input.access.surface,
+        status: "active",
+        cleanupRequestedAt: null,
+        hotStorageDeletedAt: null,
+        deletedAt: null,
+        retentionReason: null,
+        pinnedAt: null,
+        createdAt: now,
+        updatedAt: now,
+        lastActiveAt: now,
+        expiresAt,
+        lastRunId: null,
+        lastError: null,
+        metadataJson: agentInstanceMetadataJson({
+            metadata: input.metadata,
+            title: input.title
+        }),
+        entryKind: input.entry?.kind ?? null,
+        entryJson: input.entry ? stableJson(input.entry) : null,
+        kind: null,
+        roomMembershipRev: null
+    };
+    await input.control.run(`INSERT INTO ${q("_agent_instances")}
+     ("id", "conversationId", "agentName", "agentTitle", "agentOwner", "moduleId", "runtime", "triggerType", "instanceKey",
+      "principalKind", "userId", "publicScopeHash", "organizationId", "route", "surface", "status", "cleanupRequestedAt",
+      "hotStorageDeletedAt", "deletedAt", "retentionReason", "pinnedAt", "createdAt", "updatedAt", "lastActiveAt", "expiresAt", "lastRunId", "lastError", "metadataJson", "entryKind", "entryJson", "kind", "roomMembershipRev")
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+        row.id,
+        row.conversationId,
+        row.agentName,
+        row.agentTitle,
+        row.agentOwner,
+        row.moduleId,
+        row.runtime,
+        row.triggerType,
+        row.instanceKey,
+        row.principalKind,
+        row.userId,
+        row.publicScopeHash,
+        row.organizationId,
+        row.route,
+        row.surface,
+        row.status,
+        row.cleanupRequestedAt,
+        row.hotStorageDeletedAt,
+        row.deletedAt,
+        row.retentionReason,
+        row.pinnedAt,
+        row.createdAt,
+        row.updatedAt,
+        row.lastActiveAt,
+        row.expiresAt,
+        row.lastRunId,
+        row.lastError,
+        row.metadataJson,
+        row.entryKind,
+        row.entryJson,
+        row.kind ?? null,
+        row.roomMembershipRev ?? null
+    ]);
+    return row;
+}
+export function buildAgentRoomInstance(input) {
+    if (!input.agent.rooms?.enabled)
+        throw new AgentHttpError(`Agent ${input.agent.name} does not enable rooms`, 400);
+    if (!input.agent.triggers.some((trigger) => trigger.type === "chat")) {
+        throw new AgentHttpError(`Agent ${input.agent.name} does not declare a chat trigger`, 400);
+    }
+    const now = input.now ?? nowIso();
+    const retention = normalizeAgentRetentionConfig(input.agent.retention);
+    const expiresAt = agentExpiresAt(retention.transcripts === "keep-hot" ? null : retention.hotTtlMs / 1000);
+    const row = {
+        id: randomId("agent_inst"),
+        conversationId: input.conversationId,
+        agentName: input.agent.name,
+        agentTitle: input.agent.title ?? input.agent.name,
+        agentOwner: input.agent.owner?.packageName ?? input.agent.owner?.moduleId ?? null,
+        moduleId: input.agent.owner?.moduleId ?? null,
+        runtime: input.agent.runtime,
+        triggerType: "chat",
+        instanceKey: agentInstanceKey(input.agent.name, input.conversationId),
+        principalKind: "user",
+        userId: input.ownerUserId,
+        publicScopeHash: null,
+        organizationId: input.organizationId ?? null,
+        route: input.route ?? null,
+        surface: input.surface ?? "app",
+        status: "active",
+        cleanupRequestedAt: null,
+        hotStorageDeletedAt: null,
+        deletedAt: null,
+        retentionReason: null,
+        pinnedAt: null,
+        createdAt: now,
+        updatedAt: now,
+        lastActiveAt: now,
+        expiresAt,
+        lastRunId: null,
+        lastError: null,
+        metadataJson: agentInstanceMetadataJson({ title: input.title }),
+        entryKind: null,
+        entryJson: null,
+        kind: "room",
+        roomMembershipRev: 1
+    };
+    return row;
+}
+export function agentRoomInstanceInsertStatement(row) {
+    return {
+        sql: `INSERT INTO ${q("_agent_instances")}
+     ("id", "conversationId", "agentName", "agentTitle", "agentOwner", "moduleId", "runtime", "triggerType", "instanceKey",
+      "principalKind", "userId", "publicScopeHash", "organizationId", "route", "surface", "status", "cleanupRequestedAt",
+      "hotStorageDeletedAt", "deletedAt", "retentionReason", "pinnedAt", "createdAt", "updatedAt", "lastActiveAt", "expiresAt", "lastRunId", "lastError", "metadataJson", "entryKind", "entryJson", "kind", "roomMembershipRev")
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+        params: [
+            row.id, row.conversationId, row.agentName, row.agentTitle, row.agentOwner, row.moduleId,
+            row.runtime, row.triggerType, row.instanceKey, row.principalKind, row.userId, row.publicScopeHash,
+            row.organizationId, row.route, row.surface, row.status, row.cleanupRequestedAt, row.hotStorageDeletedAt,
+            row.deletedAt, row.retentionReason, row.pinnedAt, row.createdAt, row.updatedAt, row.lastActiveAt,
+            row.expiresAt, row.lastRunId, row.lastError, row.metadataJson, row.entryKind, row.entryJson, row.kind ?? null,
+            row.roomMembershipRev ?? null
+        ]
+    };
+}
+export async function createAgentRoomInstance(input) {
+    const row = buildAgentRoomInstance(input);
+    const statement = agentRoomInstanceInsertStatement(row);
+    await input.control.run(statement.sql, statement.params);
+    return row;
+}
+export async function findAgentInstance(control, agentName, conversationId) {
+    return control.first(`SELECT * FROM ${q("_agent_instances")} WHERE "agentName" = ? AND "conversationId" = ? LIMIT 1`, [agentName, conversationId]);
+}
+export async function listAgentConversations(control, input) {
+    const limit = boundedAgentConversationPage(input.limit, 20, 1, 100);
+    const offset = boundedAgentConversationPage(input.offset, 0, 0, 10_000);
+    const now = input.now ?? nowIso();
+    const membershipUserId = input.access.principal.kind === "user" ? input.access.principal.user.id : "";
+    const commonParams = [membershipUserId, input.agentName, now];
+    const principalColumn = input.access.principal.kind === "user" ? "userId" : "publicScopeHash";
+    const principalId = input.access.principal.kind === "user" ? input.access.principal.user.id : input.access.principal.id;
+    const query = input.q?.trim();
+    const searchQuery = query ? parseSearchQuery(query) : null;
+    const titleQuery = searchQuery?.terms.join(" ") || query;
+    const hasNormalizedTitleQuery = Boolean(query && titleQuery && titleQuery !== query);
+    if (searchQuery)
+        await ensureAgentChapterSearch(control);
+    const statusPredicate = input.includeArchived && input.access.principal.kind === "user"
+        ? `i."status" IN ('active', 'archived')`
+        : `i."status" = 'active'`;
+    const searchPredicate = query
+        ? `AND (
+         LOWER(COALESCE(json_extract(i."metadataJson", '$.title'), '')) LIKE LOWER(?)
+         ${hasNormalizedTitleQuery
+            ? `OR LOWER(COALESCE(json_extract(i."metadataJson", '$.title'), '')) LIKE LOWER(?)`
+            : ""}
+         ${searchQuery ? `OR EXISTS (
+           SELECT 1 FROM ${q("_agent_chapter_fts")} f
+           JOIN ${q("_agent_chapters")} c ON c."id" = f."chapterId"
+           WHERE f."conversationId" = i."conversationId"
+             AND c."agentName" = i."agentName"
+             AND c."userId" = i."userId"
+             AND ${q("_agent_chapter_fts")} MATCH ?
+         )` : ""}
+       )`
+        : "";
+    const rows = await control.all(`SELECT i.*, r."status" AS "lastRunStatus", m."pinnedAt" AS "roomMemberPinnedAt", m."lastReadAt" AS "roomMemberLastReadAt"
+     FROM ${q("_agent_instances")} i
+     LEFT JOIN ${q("_agent_runs")} r ON r."runId" = i."lastRunId"
+     LEFT JOIN ${q("_agent_room_members")} m
+       ON i."kind" = 'room' AND m."conversationId" = i."conversationId" AND m."userId" = ?
+     WHERE i."agentName" = ?
+       AND i."runtime" = 'ai-chat'
+       AND i."triggerType" = 'chat'
+       AND ${statusPredicate}
+       AND (i."status" = 'archived' OR i."expiresAt" IS NULL OR i."expiresAt" > ?)
+       AND i."surface" = ?
+       AND COALESCE(i."organizationId", '') = COALESCE(?, '')
+       AND (
+         (COALESCE(i."kind", '') <> 'room' AND i."principalKind" = ? AND i.${q(principalColumn)} = ?)
+         OR (i."kind" = 'room' AND ? = 'user' AND m."status" = 'active')
+       )
+       ${searchPredicate}
+     ORDER BY CASE WHEN COALESCE(m."pinnedAt", i."pinnedAt") IS NULL THEN 1 ELSE 0 END,
+              COALESCE(m."pinnedAt", i."pinnedAt") DESC, i."lastActiveAt" DESC, i."createdAt" DESC
+     LIMIT ? OFFSET ?`, [
+        ...commonParams,
+        input.access.surface,
+        input.access.organizationId ?? null,
+        input.access.principal.kind,
+        principalId,
+        input.access.principal.kind,
+        ...(query
+            ? [
+                `%${query}%`,
+                ...(hasNormalizedTitleQuery ? [`%${titleQuery}%`] : []),
+                ...(searchQuery ? [searchQuery.match] : [])
+            ]
+            : []),
+        limit,
+        offset
+    ]);
+    return rows.map((row) => agentConversationSummaryFromRow({
+        ...row,
+        pinnedAt: row.kind === "room" ? row.roomMemberPinnedAt : row.pinnedAt,
+        lastReadAt: row.kind === "room" ? row.roomMemberLastReadAt : row.lastReadAt ?? null
+    }));
+}
+export async function loadAgentConversationForAccess(control, input) {
+    const instance = await loadAgentInstance(control, input.agentName, input.conversationId);
+    await assertAgentConversationAccess({ control, instance, access: input.access });
+    return instance;
+}
+export async function requestAgentConversationDeletion(control, input) {
+    const instance = await findAgentInstance(control, input.agentName, input.conversationId);
+    if (!instance)
+        throw new AgentHttpError("Agent conversation not found", 404);
+    await assertAgentConversationAccess({ control, instance, access: input.access, require: "owner" });
+    const now = input.now ?? nowIso();
+    await control.run(`UPDATE ${q("_agent_instances")}
+     SET "status" = CASE
+           WHEN "status" = 'deleted' THEN 'deleted'
+           WHEN "status" = 'deleting' THEN 'deleting'
+           ELSE 'cleanupRequested'
+         END,
+         "cleanupRequestedAt" = CASE
+           WHEN "status" = 'deleted' THEN "cleanupRequestedAt"
+           ELSE COALESCE("cleanupRequestedAt", ?)
+         END,
+         "deletedAt" = CASE
+           WHEN "status" = 'deleted' THEN COALESCE("deletedAt", ?)
+           ELSE "deletedAt"
+         END,
+         "retentionReason" = 'user-deleted',
+         "expiresAt" = ?,
+         "updatedAt" = ?,
+         "lastError" = NULL
+     WHERE "id" = ?`, [now, now, now, now, instance.id]);
+    const claimed = await findAgentInstance(control, input.agentName, input.conversationId);
+    if (!claimed)
+        throw new AgentHttpError("Agent conversation not found", 404);
+    if (claimed.retentionReason !== "user-deleted") {
+        throw new AgentHttpError("Agent conversation deletion could not be secured", 409);
+    }
+    if (claimed.status !== "deleted") {
+        try {
+            await input.deleteHotStorage(claimed);
+        }
+        catch (error) {
+            throw new AgentHttpError(`Agent conversation hot-storage deletion failed: ${error instanceof Error ? error.message : String(error)}`, 503);
+        }
+    }
+    const completed = await findAgentInstance(control, input.agentName, input.conversationId);
+    if (!completed)
+        throw new AgentHttpError("Agent conversation not found", 404);
+    if (completed.status !== "deleted" || completed.retentionReason !== "user-deleted") {
+        throw new AgentHttpError("Agent conversation deletion has not completed", 503);
+    }
+    await purgeAgentChaptersForConversation(control, {
+        agentName: completed.agentName,
+        conversationId: completed.conversationId
+    });
+    return { agentName: instance.agentName, conversationId: instance.conversationId, status: "deleted" };
+}
+export async function loadAgentInstance(control, agentName, conversationId) {
+    const row = await findAgentInstance(control, agentName, conversationId);
+    if (!row)
+        throw new AgentHttpError("Agent conversation not found", 404);
+    if (row.status !== "active")
+        throw new AgentHttpError("Agent conversation is not active", 410);
+    if (row.expiresAt && new Date(row.expiresAt).getTime() <= wallNowMs())
+        throw new AgentHttpError("Agent conversation expired", 410);
+    return row;
+}
+function agentConversationSummaryFromRow(row) {
+    return {
+        agentName: row.agentName,
+        conversationId: row.conversationId,
+        runtime: row.runtime,
+        triggerType: "chat",
+        title: agentConversationTitle(row.metadataJson),
+        agentTitle: row.agentTitle,
+        route: row.route,
+        surface: row.surface,
+        status: row.status,
+        createdAt: row.createdAt,
+        updatedAt: row.updatedAt,
+        lastActiveAt: row.lastActiveAt,
+        expiresAt: row.expiresAt,
+        pinnedAt: row.pinnedAt,
+        archived: row.status === "archived",
+        lastRunId: row.lastRunId,
+        lastRunStatus: row.lastRunStatus ?? null,
+        entryKind: row.entryKind,
+        kind: row.kind ?? null,
+        lastReadAt: row.lastReadAt ?? null
+    };
+}
+// Title semantics: undefined keeps the stored title, null clears it, and a
+// string replaces it (a string that cleans to nothing keeps the stored title
+// rather than silently clearing). Resuming a conversation without a title
+// must never wipe one that a client or the runtime already stored.
+export function agentInstanceMetadataJson(input) {
+    if (input.metadata === undefined && input.title === undefined)
+        return input.current ?? null;
+    const currentTitle = cleanAgentConversationTitle(parseAgentMetadata(input.current).title);
+    const metadata = input.metadata === undefined
+        ? parseAgentMetadata(input.current)
+        : normalizeAgentMetadata(input.metadata);
+    const title = input.title === null
+        ? undefined
+        : input.title !== undefined
+            ? cleanAgentConversationTitle(input.title) ?? currentTitle
+            : currentTitle ?? cleanAgentConversationTitle(metadata.title);
+    delete metadata.title;
+    if (title)
+        metadata.title = title;
+    return Object.keys(metadata).length ? stableJson(metadata) : null;
+}
+export function agentConversationTitle(metadataJson) {
+    const title = cleanAgentConversationTitle(parseAgentMetadata(metadataJson).title);
+    return title ?? null;
+}
+export async function updateAgentConversationTitle(control, instance, title, now) {
+    const metadataJson = agentInstanceMetadataJson({ current: instance.metadataJson, title });
+    await control.run(`UPDATE ${q("_agent_instances")} SET "metadataJson" = ?, "updatedAt" = ? WHERE "id" = ?`, [metadataJson, now ?? nowIso(), instance.id]);
+    return agentConversationTitle(metadataJson);
+}
+export async function updateAgentConversationPinned(control, instance, pinned, now) {
+    const timestamp = now ?? nowIso();
+    const pinnedAt = pinned ? timestamp : null;
+    await control.run(`UPDATE ${q("_agent_instances")} SET "pinnedAt" = ?, "updatedAt" = ? WHERE "id" = ?`, [pinnedAt, timestamp, instance.id]);
+    return pinnedAt;
+}
+export async function markAgentDirectConversationRead(control, instance, now) {
+    if (instance.kind === "room")
+        throw new AgentHttpError("Agent conversation is a room", 400);
+    const lastReadAt = now ?? nowIso();
+    await control.run(`UPDATE ${q("_agent_instances")}
+     SET "lastReadAt" = CASE
+           WHEN "lastReadAt" IS NULL OR "lastReadAt" < ? THEN ?
+           ELSE "lastReadAt"
+         END,
+         "updatedAt" = CASE
+           WHEN "lastReadAt" IS NULL OR "lastReadAt" < ? THEN ?
+           ELSE "updatedAt"
+         END
+     WHERE "id" = ?`, [lastReadAt, lastReadAt, lastReadAt, lastReadAt, instance.id]);
+    const row = await control.first(`SELECT "lastReadAt" FROM ${q("_agent_instances")} WHERE "id" = ? LIMIT 1`, [instance.id]);
+    if (!row?.lastReadAt)
+        throw new AgentHttpError("Agent conversation read cursor could not be advanced", 500);
+    return row.lastReadAt;
+}
+// Dedicated rename path: unlike the conversations POST resume, this never
+// flips status back to active, bumps lastActiveAt, or extends expiresAt.
+export async function renameAgentConversation(control, input) {
+    if (input.title !== null && typeof input.title !== "string") {
+        throw new AgentHttpError("Conversation title must be a string, or null to clear it", 400);
+    }
+    if (typeof input.title === "string" && !cleanAgentConversationTitle(input.title)) {
+        throw new AgentHttpError("Conversation title must not be blank", 400);
+    }
+    const instance = await findAgentInstance(control, input.agentName, input.conversationId);
+    if (!instance)
+        throw new AgentHttpError("Agent conversation not found", 404);
+    await assertAgentConversationAccess({ control, instance, access: input.access, require: "owner" });
+    if (instance.status !== "active" && instance.status !== "archived") {
+        throw new AgentHttpError("Agent conversation cannot be renamed in its current state", 409);
+    }
+    const title = await updateAgentConversationTitle(control, instance, input.title, input.now);
+    return { agentName: instance.agentName, conversationId: instance.conversationId, title };
+}
+export async function pinAgentConversation(control, input) {
+    if (typeof input.pinned !== "boolean")
+        throw new AgentHttpError("Conversation pinned must be a boolean", 400);
+    if (input.access.principal.kind !== "user")
+        throw new AgentHttpError("Public conversations cannot be pinned", 403);
+    const instance = await findAgentInstance(control, input.agentName, input.conversationId);
+    if (!instance)
+        throw new AgentHttpError("Agent conversation not found", 404);
+    const accessResult = await assertAgentConversationAccess({ control, instance, access: input.access });
+    if (instance.status !== "active" && instance.status !== "archived") {
+        throw new AgentHttpError("Agent conversation cannot be pinned in its current state", 409);
+    }
+    const pinnedAt = instance.kind === "room"
+        ? await setAgentRoomMemberPinned({
+            control,
+            conversationId: instance.conversationId,
+            userId: accessResult.membership.userId,
+            pinned: input.pinned,
+            now: input.now
+        })
+        : await updateAgentConversationPinned(control, instance, input.pinned, input.now);
+    return {
+        agentName: instance.agentName,
+        conversationId: instance.conversationId,
+        pinned: Boolean(pinnedAt),
+        pinnedAt
+    };
+}
+function parseAgentMetadata(value) {
+    if (!value)
+        return {};
+    try {
+        return normalizeAgentMetadata(JSON.parse(value));
+    }
+    catch {
+        return {};
+    }
+}
+function normalizeAgentMetadata(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? { ...value } : {};
+}
+export function cleanAgentConversationTitle(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const title = value.trim().replace(/\s+/g, " ");
+    return title ? title.slice(0, 120) : undefined;
+}
+function boundedAgentConversationPage(value, fallback, min, max) {
+    const numeric = Number(value ?? fallback);
+    if (!Number.isFinite(numeric))
+        return fallback;
+    return Math.max(min, Math.min(max, Math.floor(numeric)));
+}
+export async function createAgentRun(input) {
+    const now = nowIso();
+    const expiresAt = input.ttlSeconds === undefined
+        ? input.instance.expiresAt === null ? null : agentExpiresAt()
+        : agentExpiresAt(input.ttlSeconds);
+    const run = {
+        runId: input.runId || randomId("agent_run"),
+        conversationId: input.instance.conversationId,
+        agentName: input.instance.agentName,
+        requestId: input.requestId,
+        triggerType: input.triggerType ?? input.instance.triggerType,
+        inputMessageId: input.inputMessageId ?? null,
+        status: "queued",
+        startedAt: now,
+        heartbeatAt: now,
+        finishedAt: null,
+        error: null,
+        usageEventId: null,
+        auditEventId: null,
+        metadataJson: input.metadata === undefined ? null : stableJson(input.metadata)
+    };
+    await input.control.run(`INSERT INTO ${q("_agent_runs")}
+     ("runId", "conversationId", "agentName", "requestId", "triggerType", "inputMessageId", "status", "startedAt", "heartbeatAt", "finishedAt",
+      "error", "usageEventId", "auditEventId", "metadataJson")
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+        run.runId,
+        run.conversationId,
+        run.agentName,
+        run.requestId,
+        run.triggerType,
+        run.inputMessageId,
+        run.status,
+        run.startedAt,
+        run.heartbeatAt,
+        run.finishedAt,
+        run.error,
+        run.usageEventId,
+        run.auditEventId,
+        run.metadataJson
+    ]);
+    await input.control.run(`UPDATE ${q("_agent_instances")}
+     SET "lastRunId" = ?, "lastActiveAt" = ?, "expiresAt" = ?, "updatedAt" = ?, "lastError" = NULL
+     WHERE "id" = ?`, [run.runId, now, expiresAt, now, input.instance.id]);
+    return run;
+}
+export function agentEnabledSettingKey(agentName) {
+    return `raybase.agent.${agentName}.enabled`;
+}
+export function agentPromptSettingKey(agentName) {
+    return `raybase.agent.${agentName}.prompt`;
+}
+export const raybaseAgentTimezoneSettingKey = "raybase.agent.timezone";
+export function agentGeneratedSettingDefinitions(agents) {
+    const definitions = {};
+    const resolvedAgents = Object.values(defineAgents(agents ?? {}));
+    if (resolvedAgents.length > 0) {
+        definitions[raybaseAgentTimezoneSettingKey] = setting.string({
+            scope: "user",
+            group: "Agents",
+            label: "Timezone",
+            description: "IANA timezone used for per-turn Agent time context.",
+            default: "UTC",
+            validate: (value) => {
+                try {
+                    new Intl.DateTimeFormat("en", { timeZone: value }).format();
+                    return true;
+                }
+                catch {
+                    return "Timezone must be a valid IANA timezone such as Europe/Paris.";
+                }
+            }
+        });
+    }
+    for (const agent of resolvedAgents) {
+        const group = `Agents / ${agent.title ?? agent.name}`;
+        if (agent.runtimeControl?.configurable === true) {
+            definitions[agentEnabledSettingKey(agent.name)] = setting.boolean({
+                scope: "app",
+                group,
+                label: "Enabled",
+                description: "Controls admission for new chat, scheduled, data-triggered, direct, and wake runs. In-flight work is not cancelled.",
+                default: agent.runtimeControl.defaultEnabled !== false,
+                admin: { hidden: true }
+            });
+        }
+        if (agent.prompt?.configurable === true) {
+            definitions[agentPromptSettingKey(agent.name)] = setting.string({
+                scope: "app",
+                group,
+                label: "Prompt",
+                description: "Operator override for this agent prompt. Resetting removes the stored override and returns to the code-defined default.",
+                default: agent.prompt.default,
+                admin: { hidden: true, multiline: true },
+                validate: (value) => value.trim() ? true : "Prompt override must not be blank"
+            });
+        }
+    }
+    return definitions;
+}
+export async function isAgentRuntimeEnabled(settings, agent) {
+    if (agent.runtimeControl?.configurable !== true)
+        return agent.runtimeControl?.defaultEnabled !== false;
+    try {
+        return Boolean(await settings?.get(agentEnabledSettingKey(agent.name)) ?? (agent.runtimeControl.defaultEnabled !== false));
+    }
+    catch {
+        return agent.runtimeControl.defaultEnabled !== false;
+    }
+}
+export function agentScheduleId(agentName, triggerIndex, trigger) {
+    if (trigger?.maintenance)
+        return `static:${agentName}:maintenance:${trigger.maintenance}`;
+    return `static:${agentName}:${triggerIndex}`;
+}
+export function agentTriggerKey(agentName, triggerIndex, trigger) {
+    if (trigger.type === "chat")
+        return `chat:${agentName}`;
+    if (trigger.type === "schedule") {
+        return trigger.maintenance
+            ? `schedule:${agentName}:maintenance:${trigger.maintenance}`
+            : `schedule:${agentName}:${triggerIndex}:${trigger.cron}:${trigger.timezone ?? "UTC"}`;
+    }
+    return `data:${agentName}:${triggerIndex}:${trigger.event}`;
+}
+function hasOwn(object, key) {
+    return Object.prototype.hasOwnProperty.call(object, key);
+}
+function normalizeScheduleUserMessage(value, label = "Schedule user message") {
+    if (value === undefined || value === null)
+        return null;
+    if (typeof value !== "string")
+        throw new Error(`${label} must be a string`);
+    const trimmed = value.trim();
+    if (!trimmed)
+        throw new Error(`${label} must not be blank`);
+    return trimmed;
+}
+function normalizeScheduleTimezoneOverride(value) {
+    if (value === undefined || value === null)
+        return null;
+    if (typeof value !== "string")
+        throw new Error("Schedule timezone override must be a string");
+    const trimmed = value.trim();
+    return trimmed ? trimmed : null;
+}
+function normalizeScheduleCronOverride(value) {
+    if (typeof value !== "string" || !value.trim())
+        throw new Error("Schedule cron override must be a non-empty string");
+    const cron = value.trim();
+    validateCron(cron);
+    return cron;
+}
+function serializeScheduleJson(value) {
+    const serialized = JSON.stringify(value);
+    if (serialized === undefined)
+        throw new Error("Schedule input override must be JSON-serializable");
+    return stableJson(JSON.parse(serialized));
+}
+function parseScheduleJson(value, fallback) {
+    if (value === null || value === undefined)
+        return fallback;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return fallback;
+    }
+}
+function normalizeOverrideEnabled(value) {
+    return value === 0 || value === 1 ? value : null;
+}
+export function parseAgentScheduleSourceInput(row) {
+    return parseScheduleJson(row.inputJson, {});
+}
+export function parseAgentScheduleInput(row) {
+    if (row.inputJsonOverrideEnabled === 1)
+        return parseScheduleJson(row.inputJsonOverride, null);
+    return parseAgentScheduleSourceInput(row);
+}
+export function agentScheduleOverrideState(row) {
+    return {
+        cron: row.cronOverride !== null && row.cronOverride !== undefined,
+        timezone: row.timezoneOverride !== null && row.timezoneOverride !== undefined,
+        enabled: normalizeOverrideEnabled(row.enabledOverride) !== null,
+        input: row.inputJsonOverrideEnabled === 1,
+        userMessage: row.userMessageOverride !== null && row.userMessageOverride !== undefined
+    };
+}
+export function effectiveAgentSchedule(row) {
+    const enabledOverride = normalizeOverrideEnabled(row.enabledOverride);
+    const userMessage = row.userMessageOverride ?? row.userMessage ?? null;
+    return {
+        id: row.id,
+        agentName: row.agentName,
+        triggerIndex: row.triggerIndex,
+        triggerKey: row.triggerKey,
+        cron: row.cronOverride ?? row.cron,
+        timezone: row.timezoneOverride ?? row.timezone ?? null,
+        enabled: (enabledOverride ?? row.enabled) === 1,
+        input: parseAgentScheduleInput(row),
+        userMessage: userMessage?.trim() || undefined
+    };
+}
+export function agentScheduleRuntimeTrigger(row) {
+    const effective = effectiveAgentSchedule(row);
+    return {
+        type: "schedule",
+        cron: effective.cron,
+        timezone: effective.timezone ?? undefined,
+        input: effective.input,
+        enabled: effective.enabled,
+        userMessage: effective.userMessage
+    };
+}
+export function agentScheduleAdminSnapshot(row) {
+    const overrideEnabled = agentScheduleOverrideState(row);
+    const effective = effectiveAgentSchedule(row);
+    const sourceInput = parseAgentScheduleSourceInput(row);
+    return {
+        id: row.id,
+        agentName: row.agentName,
+        triggerIndex: row.triggerIndex,
+        triggerKey: row.triggerKey,
+        source: {
+            cron: row.cron,
+            timezone: row.timezone ?? null,
+            enabled: row.enabled === 1,
+            input: sourceInput,
+            userMessage: row.userMessage ?? null
+        },
+        overrides: {
+            cron: overrideEnabled.cron ? row.cronOverride : null,
+            timezone: overrideEnabled.timezone ? row.timezoneOverride : null,
+            enabled: overrideEnabled.enabled ? normalizeOverrideEnabled(row.enabledOverride) === 1 : null,
+            input: overrideEnabled.input ? parseScheduleJson(row.inputJsonOverride, null) : null,
+            userMessage: overrideEnabled.userMessage ? row.userMessageOverride : null
+        },
+        overrideEnabled,
+        effective: {
+            cron: effective.cron,
+            timezone: effective.timezone,
+            enabled: effective.enabled,
+            input: effective.input,
+            userMessage: effective.userMessage ?? null
+        },
+        lastRunAt: row.lastRunAt,
+        nextRunAt: row.nextRunAt,
+        service: row.service,
+        createdAt: row.createdAt,
+        updatedAt: row.updatedAt
+    };
+}
+export function scheduleNextRunFrom(now, cron, timezone) {
+    validateCron(cron);
+    return nextCronRun(cron, now, timezone ?? undefined);
+}
+function nextRunAfterScheduleChange(input) {
+    if (!input.before)
+        return input.fallbackNextRunAt ?? scheduleNextRunFrom(input.now, input.after.cron, input.after.timezone);
+    const timingChanged = input.before.cron !== input.after.cron || (input.before.timezone ?? null) !== (input.after.timezone ?? null);
+    const reenabled = !input.before.enabled && input.after.enabled;
+    if (timingChanged || reenabled)
+        return scheduleNextRunFrom(input.now, input.after.cron, input.after.timezone);
+    return input.currentNextRunAt;
+}
+async function findAgentSchedule(control, idValue) {
+    return control.first(`SELECT * FROM ${q("_agent_schedules")} WHERE "id" = ? LIMIT 1`, [idValue]);
+}
+export async function loadAgentSchedule(control, idValue) {
+    const row = await findAgentSchedule(control, idValue);
+    if (!row)
+        throw new Error(`Agent schedule not found: ${idValue}`);
+    return row;
+}
+export async function listAgentSchedulesForAgent(control, agentName) {
+    return control.all(`SELECT * FROM ${q("_agent_schedules")} WHERE "agentName" = ? ORDER BY "triggerIndex" ASC`, [agentName]);
+}
+function applyReset(row, field) {
+    if (field === "cron")
+        row.cronOverride = null;
+    if (field === "timezone")
+        row.timezoneOverride = null;
+    if (field === "enabled")
+        row.enabledOverride = null;
+    if (field === "input") {
+        row.inputJsonOverride = null;
+        row.inputJsonOverrideEnabled = null;
+    }
+    if (field === "userMessage")
+        row.userMessageOverride = null;
+}
+function normalizeResetFields(fields) {
+    if (fields === undefined || fields === null)
+        return [];
+    if (!Array.isArray(fields))
+        throw new Error("Schedule reset must be an array");
+    const allowed = new Set(["cron", "timezone", "enabled", "input", "userMessage"]);
+    return fields.map((field) => {
+        if (typeof field !== "string" || !allowed.has(field))
+            throw new Error(`Unknown schedule override field: ${String(field)}`);
+        return field;
+    });
+}
+async function persistScheduleOverrideRow(control, row) {
+    await control.run(`UPDATE ${q("_agent_schedules")}
+     SET "cronOverride" = ?, "timezoneOverride" = ?, "enabledOverride" = ?,
+         "inputJsonOverride" = ?, "inputJsonOverrideEnabled" = ?, "userMessageOverride" = ?,
+         "nextRunAt" = ?, "dispatchGeneration" = ?, "dispatchAttempts" = ?,
+         "dispatchLeaseExpiresAt" = ?, "lastDispatchAt" = ?, "lastDispatchError" = ?, "updatedAt" = ?
+     WHERE "id" = ?`, [
+        row.cronOverride,
+        row.timezoneOverride,
+        row.enabledOverride,
+        row.inputJsonOverride,
+        row.inputJsonOverrideEnabled,
+        row.userMessageOverride,
+        row.nextRunAt,
+        row.dispatchGeneration,
+        row.dispatchAttempts,
+        row.dispatchLeaseExpiresAt,
+        row.lastDispatchAt,
+        row.lastDispatchError,
+        row.updatedAt,
+        row.id
+    ]);
+    return loadAgentSchedule(control, row.id);
+}
+export async function setAgentScheduleOverrides(control, input) {
+    const current = await loadAgentSchedule(control, input.id);
+    const beforeEffective = effectiveAgentSchedule(current);
+    const before = agentScheduleAdminSnapshot(current);
+    const next = { ...current };
+    const changedFields = new Set();
+    for (const field of normalizeResetFields(input.reset)) {
+        applyReset(next, field);
+        changedFields.add(field);
+    }
+    const overrides = input.overrides && typeof input.overrides === "object" && !Array.isArray(input.overrides)
+        ? input.overrides
+        : {};
+    const allowed = new Set(["cron", "timezone", "enabled", "input", "userMessage"]);
+    for (const key of Object.keys(overrides)) {
+        if (!allowed.has(key))
+            throw new Error(`Unknown schedule override field: ${key}`);
+    }
+    if (hasOwn(overrides, "cron")) {
+        next.cronOverride = normalizeScheduleCronOverride(overrides.cron);
+        changedFields.add("cron");
+    }
+    if (hasOwn(overrides, "timezone")) {
+        next.timezoneOverride = normalizeScheduleTimezoneOverride(overrides.timezone);
+        changedFields.add("timezone");
+    }
+    if (hasOwn(overrides, "enabled")) {
+        if (typeof overrides.enabled !== "boolean")
+            throw new Error("Schedule enabled override must be boolean");
+        next.enabledOverride = overrides.enabled ? 1 : 0;
+        changedFields.add("enabled");
+    }
+    if (hasOwn(overrides, "input")) {
+        next.inputJsonOverride = serializeScheduleJson(overrides.input);
+        next.inputJsonOverrideEnabled = 1;
+        changedFields.add("input");
+    }
+    if (hasOwn(overrides, "userMessage")) {
+        next.userMessageOverride = normalizeScheduleUserMessage(overrides.userMessage, "Schedule user message override");
+        changedFields.add("userMessage");
+    }
+    const now = input.now ?? nowIso();
+    const afterEffective = effectiveAgentSchedule(next);
+    next.nextRunAt = nextRunAfterScheduleChange({
+        before: beforeEffective,
+        after: afterEffective,
+        currentNextRunAt: current.nextRunAt,
+        now
+    });
+    if (stableJson(beforeEffective) !== stableJson(afterEffective) || next.nextRunAt !== current.nextRunAt) {
+        next.dispatchGeneration = Number(current.dispatchGeneration ?? 1) + 1;
+        next.dispatchAttempts = 0;
+        next.dispatchLeaseExpiresAt = null;
+        next.lastDispatchAt = null;
+        next.lastDispatchError = null;
+    }
+    next.updatedAt = now;
+    const row = await persistScheduleOverrideRow(control, next);
+    return {
+        row,
+        before,
+        after: agentScheduleAdminSnapshot(row),
+        changedFields: [...changedFields]
+    };
+}
+export async function resetAgentScheduleOverrides(control, input) {
+    const current = await loadAgentSchedule(control, input.id);
+    const beforeEffective = effectiveAgentSchedule(current);
+    const before = agentScheduleAdminSnapshot(current);
+    const next = { ...current };
+    const fields = input.fields?.length ? input.fields : ["cron", "timezone", "enabled", "input", "userMessage"];
+    for (const field of fields)
+        applyReset(next, field);
+    const now = input.now ?? nowIso();
+    const afterEffective = effectiveAgentSchedule(next);
+    next.nextRunAt = nextRunAfterScheduleChange({
+        before: beforeEffective,
+        after: afterEffective,
+        currentNextRunAt: current.nextRunAt,
+        now
+    });
+    if (stableJson(beforeEffective) !== stableJson(afterEffective) || next.nextRunAt !== current.nextRunAt) {
+        next.dispatchGeneration = Number(current.dispatchGeneration ?? 1) + 1;
+        next.dispatchAttempts = 0;
+        next.dispatchLeaseExpiresAt = null;
+        next.lastDispatchAt = null;
+        next.lastDispatchError = null;
+    }
+    next.updatedAt = now;
+    const row = await persistScheduleOverrideRow(control, next);
+    return {
+        row,
+        before,
+        after: agentScheduleAdminSnapshot(row),
+        changedFields: fields
+    };
+}
+export async function upsertAgentSchedule(control, input) {
+    const now = input.now ?? nowIso();
+    const idValue = agentScheduleId(input.agentName, input.triggerIndex, input.trigger);
+    const existing = await findAgentSchedule(control, idValue);
+    const row = {
+        id: idValue,
+        agentName: input.agentName,
+        triggerIndex: input.triggerIndex,
+        triggerKey: agentTriggerKey(input.agentName, input.triggerIndex, input.trigger),
+        inputJson: stableJson(input.trigger.input ?? {}),
+        cron: input.trigger.cron,
+        timezone: input.trigger.timezone ?? null,
+        enabled: input.trigger.enabled === false ? 0 : 1,
+        userMessage: normalizeScheduleUserMessage(input.trigger.userMessage, "Schedule userMessage"),
+        cronOverride: existing?.cronOverride ?? null,
+        timezoneOverride: existing?.timezoneOverride ?? null,
+        enabledOverride: normalizeOverrideEnabled(existing?.enabledOverride),
+        inputJsonOverride: existing?.inputJsonOverride ?? null,
+        inputJsonOverrideEnabled: existing?.inputJsonOverrideEnabled === 1 ? 1 : null,
+        userMessageOverride: existing?.userMessageOverride ?? null,
+        lastRunAt: existing?.lastRunAt ?? null,
+        nextRunAt: null,
+        service: input.service ?? "scheduler",
+        dispatchGeneration: existing?.dispatchGeneration ?? 1,
+        dispatchAttempts: existing?.dispatchAttempts ?? 0,
+        dispatchLeaseExpiresAt: existing?.dispatchLeaseExpiresAt ?? null,
+        lastDispatchAt: existing?.lastDispatchAt ?? null,
+        lastDispatchError: existing?.lastDispatchError ?? null,
+        createdAt: existing?.createdAt ?? now,
+        updatedAt: now
+    };
+    row.nextRunAt = nextRunAfterScheduleChange({
+        before: existing ? effectiveAgentSchedule(existing) : null,
+        after: effectiveAgentSchedule(row),
+        currentNextRunAt: existing?.nextRunAt ?? null,
+        fallbackNextRunAt: input.nextRunAt,
+        now
+    });
+    const definitionChanged = Boolean(existing) && (existing.agentName !== row.agentName
+        || existing.triggerIndex !== row.triggerIndex
+        || existing.triggerKey !== row.triggerKey
+        || existing.inputJson !== row.inputJson
+        || existing.cron !== row.cron
+        || existing.timezone !== row.timezone
+        || existing.enabled !== row.enabled
+        || existing.userMessage !== row.userMessage
+        || existing.nextRunAt !== row.nextRunAt);
+    if (definitionChanged) {
+        row.dispatchGeneration = Number(existing?.dispatchGeneration ?? 1) + 1;
+        row.dispatchAttempts = 0;
+        row.dispatchLeaseExpiresAt = null;
+        row.lastDispatchAt = null;
+        row.lastDispatchError = null;
+    }
+    await control.run(`INSERT INTO ${q("_agent_schedules")}
+      ("id", "agentName", "triggerIndex", "triggerKey", "inputJson", "cron", "timezone", "enabled", "userMessage",
+       "cronOverride", "timezoneOverride", "enabledOverride", "inputJsonOverride", "inputJsonOverrideEnabled", "userMessageOverride",
+       "lastRunAt", "nextRunAt", "service", "dispatchGeneration", "dispatchAttempts", "dispatchLeaseExpiresAt",
+       "lastDispatchAt", "lastDispatchError", "createdAt", "updatedAt")
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+     ON CONFLICT("id") DO UPDATE SET
+       "agentName" = excluded."agentName",
+       "triggerIndex" = excluded."triggerIndex",
+       "triggerKey" = excluded."triggerKey",
+       "inputJson" = excluded."inputJson",
+       "cron" = excluded."cron",
+       "timezone" = excluded."timezone",
+       "enabled" = excluded."enabled",
+       "userMessage" = excluded."userMessage",
+       "lastRunAt" = excluded."lastRunAt",
+       "nextRunAt" = excluded."nextRunAt",
+       "service" = excluded."service",
+       "dispatchGeneration" = excluded."dispatchGeneration",
+       "dispatchAttempts" = excluded."dispatchAttempts",
+       "dispatchLeaseExpiresAt" = excluded."dispatchLeaseExpiresAt",
+       "lastDispatchAt" = excluded."lastDispatchAt",
+       "lastDispatchError" = excluded."lastDispatchError",
+       "updatedAt" = excluded."updatedAt"`, [
+        row.id,
+        row.agentName,
+        row.triggerIndex,
+        row.triggerKey,
+        row.inputJson,
+        row.cron,
+        row.timezone,
+        row.enabled,
+        row.userMessage,
+        row.cronOverride,
+        row.timezoneOverride,
+        row.enabledOverride,
+        row.inputJsonOverride,
+        row.inputJsonOverrideEnabled,
+        row.userMessageOverride,
+        row.lastRunAt,
+        row.nextRunAt,
+        row.service,
+        row.dispatchGeneration,
+        row.dispatchAttempts,
+        row.dispatchLeaseExpiresAt,
+        row.lastDispatchAt,
+        row.lastDispatchError,
+        row.createdAt,
+        row.updatedAt
+    ]);
+    return (await control.first(`SELECT * FROM ${q("_agent_schedules")} WHERE "id" = ?`, [row.id])) ?? row;
+}
+export async function listDueAgentSchedules(control, input) {
+    const limit = Math.max(1, Math.min(500, input.limit ?? 100));
+    return control.all(`SELECT * FROM ${q("_agent_schedules")}
+     WHERE (("enabledOverride" IS NULL AND "enabled" = 1) OR "enabledOverride" = 1)
+       AND "nextRunAt" IS NOT NULL AND "nextRunAt" <= ?
+     ORDER BY "nextRunAt" ASC
+     LIMIT ?`, [input.now, limit]);
+}
+export const agentScheduleMaxDispatchAttempts = 5;
+export async function claimDueAgentSchedules(control, input) {
+    const limit = Math.max(1, Math.min(500, input.limit ?? 100));
+    const maxAttempts = Math.max(1, input.maxAttempts ?? agentScheduleMaxDispatchAttempts);
+    await control.run(`UPDATE ${q("_agent_schedules")} SET "enabled" = 0, "enabledOverride" = 0,
+     "lastDispatchError" = 'dispatch-attempts-exhausted', "dispatchLeaseExpiresAt" = NULL, "updatedAt" = ?
+     WHERE (("enabledOverride" IS NULL AND "enabled" = 1) OR "enabledOverride" = 1)
+       AND "nextRunAt" IS NOT NULL AND "nextRunAt" <= ? AND COALESCE("dispatchAttempts", 0) >= ?
+       AND ("dispatchLeaseExpiresAt" IS NULL OR "dispatchLeaseExpiresAt" <= ?)`, [input.now, input.now, maxAttempts, input.wallNow]);
+    const due = await control.all(`SELECT * FROM ${q("_agent_schedules")}
+     WHERE (("enabledOverride" IS NULL AND "enabled" = 1) OR "enabledOverride" = 1)
+       AND "nextRunAt" IS NOT NULL AND "nextRunAt" <= ? AND COALESCE("dispatchAttempts", 0) < ?
+       AND ("dispatchLeaseExpiresAt" IS NULL OR "dispatchLeaseExpiresAt" <= ?)
+     ORDER BY "nextRunAt" ASC LIMIT ?`, [input.now, maxAttempts, input.wallNow, limit]);
+    const claimed = [];
+    for (const row of due) {
+        if (!row.nextRunAt)
+            continue;
+        const generation = Number(row.dispatchGeneration ?? 1);
+        const attempts = Number(row.dispatchAttempts ?? 0);
+        await control.run(`UPDATE ${q("_agent_schedules")} SET "dispatchGeneration" = ?, "dispatchAttempts" = ?,
+       "dispatchLeaseExpiresAt" = ?, "lastDispatchAt" = ?, "lastDispatchError" = NULL, "updatedAt" = ?
+       WHERE "id" = ? AND COALESCE("dispatchGeneration", 1) = ? AND COALESCE("dispatchAttempts", 0) = ?
+         AND "nextRunAt" = ? AND ("dispatchLeaseExpiresAt" IS NULL OR "dispatchLeaseExpiresAt" <= ?)`, [generation, attempts + 1, input.leaseExpiresAt, input.wallNow, input.now, row.id, generation, attempts, row.nextRunAt, input.wallNow]);
+        const current = await control.first(`SELECT * FROM ${q("_agent_schedules")} WHERE "id" = ? LIMIT 1`, [row.id]);
+        if (current?.nextRunAt === row.nextRunAt
+            && Number(current.dispatchGeneration ?? 1) === generation
+            && Number(current.dispatchAttempts ?? 0) === attempts + 1
+            && current.dispatchLeaseExpiresAt === input.leaseExpiresAt) {
+            claimed.push({ id: current.id, agentName: current.agentName, generation, bookedAt: current.nextRunAt });
+        }
+    }
+    return claimed;
+}
+export async function loadClaimedAgentSchedule(control, input) {
+    return control.first(`SELECT * FROM ${q("_agent_schedules")} WHERE "id" = ? AND "nextRunAt" = ?
+       AND COALESCE("dispatchGeneration", 1) = ? LIMIT 1`, [input.id, input.bookedAt, input.generation]);
+}
+export async function releaseAgentScheduleDispatch(control, input) {
+    await control.run(`UPDATE ${q("_agent_schedules")} SET "dispatchLeaseExpiresAt" = NULL, "lastDispatchError" = ?, "updatedAt" = ?
+     WHERE "id" = ? AND "nextRunAt" = ? AND COALESCE("dispatchGeneration", 1) = ?`, [input.error, input.now ?? nowIso(), input.id, input.bookedAt, input.generation]);
+}
+export async function advanceAgentSchedule(control, input) {
+    await control.run(`UPDATE ${q("_agent_schedules")} SET "lastRunAt" = ?, "nextRunAt" = ?,
+     "dispatchGeneration" = COALESCE("dispatchGeneration", 1) + 1, "dispatchAttempts" = 0,
+     "dispatchLeaseExpiresAt" = NULL, "lastDispatchAt" = NULL, "lastDispatchError" = NULL, "updatedAt" = ?
+     WHERE "id" = ? ${input.generation === undefined ? "" : `AND COALESCE("dispatchGeneration", 1) = ? AND "nextRunAt" = ?`}`, [input.lastRunAt, input.nextRunAt, input.now ?? nowIso(), input.id,
+        ...(input.generation === undefined ? [] : [input.generation, input.lastRunAt])]);
+}
+export async function createAgentTriggerEvent(control, input) {
+    const now = input.now ?? wallNowIso();
+    const row = {
+        id: randomId("agent_evt"),
+        agentName: input.agentName,
+        triggerType: input.triggerType,
+        triggerKey: input.triggerKey,
+        sourceTable: input.sourceTable ?? null,
+        sourceOp: input.sourceOp ?? null,
+        rowId: input.rowId ?? null,
+        inputJson: input.input === undefined ? null : stableJson(input.input),
+        idempotencyKey: input.idempotencyKey ?? null,
+        status: input.status ?? "queued",
+        runId: null,
+        error: input.error ?? null,
+        createdAt: now,
+        updatedAt: now
+    };
+    await control.run(`INSERT INTO ${q("_agent_trigger_events")}
+      ("id", "agentName", "triggerType", "triggerKey", "sourceTable", "sourceOp", "rowId", "inputJson", "idempotencyKey", "status", "runId", "error", "createdAt", "updatedAt")
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+        row.id,
+        row.agentName,
+        row.triggerType,
+        row.triggerKey,
+        row.sourceTable,
+        row.sourceOp,
+        row.rowId,
+        row.inputJson,
+        row.idempotencyKey,
+        row.status,
+        row.runId,
+        row.error,
+        row.createdAt,
+        row.updatedAt
+    ]);
+    return row;
+}
+async function markAgentTriggerEvent(control, eventId, input) {
+    await control.run(`UPDATE ${q("_agent_trigger_events")} SET "status" = ?, "runId" = COALESCE(?, "runId"), "error" = ?, "updatedAt" = ? WHERE "id" = ?`, [input.status, input.runId ?? null, input.error ?? null, input.now ?? wallNowIso(), eventId]);
+}
+export const markAgentTriggerEventQueued = (control, eventId, input = {}) => markAgentTriggerEvent(control, eventId, { ...input, status: "queued" });
+export const markAgentTriggerEventRunning = (control, eventId, input = {}) => markAgentTriggerEvent(control, eventId, { ...input, status: "running" });
+export const markAgentTriggerEventCompleted = (control, eventId, input = {}) => markAgentTriggerEvent(control, eventId, { ...input, status: "completed" });
+export const markAgentTriggerEventFailed = (control, eventId, input = {}) => markAgentTriggerEvent(control, eventId, { ...input, status: "failed" });
+export const markAgentTriggerEventSkipped = (control, eventId, input = {}) => markAgentTriggerEvent(control, eventId, { ...input, status: "skipped" });
+export async function loadAgentTriggerEvent(control, eventId) {
+    const row = await control.first(`SELECT * FROM ${q("_agent_trigger_events")} WHERE "id" = ? LIMIT 1`, [eventId]);
+    if (!row)
+        throw new AgentHttpError("Agent trigger event not found", 404);
+    return row;
+}
+export async function findAgentTriggerEventByIdempotencyKey(control, idempotencyKey) {
+    return control.first(`SELECT * FROM ${q("_agent_trigger_events")} WHERE "idempotencyKey" = ? LIMIT 1`, [idempotencyKey]);
+}
+export function directAgentTriggerKey(agentName) {
+    return `direct:${agentName}`;
+}
+function directBindingFingerprintFromInput(inputJson) {
+    if (!inputJson)
+        return "new";
+    try {
+        const input = JSON.parse(inputJson);
+        const conversation = input.conversation;
+        if (!conversation || typeof conversation !== "object")
+            return "new";
+        const record = conversation;
+        // Compare the derived id, not the raw external thread key, so replay checks
+        // do not depend on provider ids being used as storage identifiers.
+        if (record.mode === "thread" && typeof record.conversationId === "string") {
+            return `thread:${record.conversationId}`;
+        }
+        if (record.mode === "chat" && typeof record.conversationId === "string") {
+            return `chat:${record.conversationId}`;
+        }
+        return "new";
+    }
+    catch {
+        return "new";
+    }
+}
+export async function findAgentRun(control, runId) {
+    return control.first(`SELECT * FROM ${q("_agent_runs")} WHERE "runId" = ? LIMIT 1`, [runId]);
+}
+export async function loadAgentRun(control, runId) {
+    const row = await findAgentRun(control, runId);
+    if (!row)
+        throw new AgentHttpError("Agent run not found", 404);
+    return row;
+}
+export async function createOrLoadDirectAgentInvocationRecord(input) {
+    const triggerKey = directAgentTriggerKey(input.agent.name);
+    if (input.idempotencyKey !== undefined && input.idempotencyKey !== null) {
+        const existing = await findAgentTriggerEventByIdempotencyKey(input.control, input.idempotencyKey);
+        if (existing) {
+            if (existing.agentName !== input.agent.name || existing.triggerType !== "direct" || existing.triggerKey !== triggerKey) {
+                throw new Error(`Agent idempotency key conflict for ${input.agent.name}`);
+            }
+            const existingFingerprint = directBindingFingerprintFromInput(existing.inputJson);
+            if ((input.bindingFingerprint ?? "new") !== existingFingerprint) {
+                throw new Error(`Agent idempotency key conflict for ${input.agent.name}: conversation binding changed`);
+            }
+            return {
+                created: false,
+                event: existing,
+                run: existing.runId ? await findAgentRun(input.control, existing.runId) : null
+            };
+        }
+    }
+    const event = await createAgentTriggerEvent(input.control, {
+        agentName: input.agent.name,
+        triggerType: "direct",
+        triggerKey,
+        input: input.invocationInput,
+        idempotencyKey: input.idempotencyKey ?? null
+    });
+    const run = await createAgentAutomationRun({
+        control: input.control,
+        agent: input.agent,
+        triggerType: "direct",
+        eventId: event.id,
+        requestId: input.requestId,
+        metadata: input.metadata,
+        conversationId: input.conversationId
+    });
+    await markAgentTriggerEventQueued(input.control, event.id, { runId: run.runId });
+    return {
+        created: true,
+        event: { ...event, runId: run.runId },
+        run
+    };
+}
+export async function createAgentAutomationRun(input) {
+    const now = nowIso();
+    const run = {
+        runId: randomId("agent_run"),
+        conversationId: input.conversationId ?? (input.triggerType === "direct" ? `agent_direct:${input.eventId}` : `agent_auto:${input.eventId}`),
+        agentName: input.agent.name,
+        requestId: input.requestId ?? randomId("agent_req"),
+        triggerType: input.triggerType,
+        inputMessageId: null,
+        status: "queued",
+        startedAt: now,
+        heartbeatAt: now,
+        finishedAt: null,
+        error: null,
+        usageEventId: null,
+        auditEventId: null,
+        metadataJson: input.metadata === undefined ? null : stableJson(input.metadata)
+    };
+    await input.control.run(`INSERT INTO ${q("_agent_runs")}
+     ("runId", "conversationId", "agentName", "requestId", "triggerType", "inputMessageId", "status", "startedAt", "heartbeatAt", "finishedAt",
+      "error", "usageEventId", "auditEventId", "metadataJson")
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+        run.runId,
+        run.conversationId,
+        run.agentName,
+        run.requestId,
+        run.triggerType,
+        run.inputMessageId,
+        run.status,
+        run.startedAt,
+        run.heartbeatAt,
+        run.finishedAt,
+        run.error,
+        run.usageEventId,
+        run.auditEventId,
+        run.metadataJson
+    ]);
+    return run;
+}
+// A crashed isolate can leave a running run with no writer left to finish it;
+// past this age it no longer blocks a retry. Queue wait is deliberately
+// governed by a separate, much longer horizon below: work that has not
+// started must not spend its execution budget while waiting for capacity.
+export const activeAgentRunStaleSeconds = 5 * 60;
+export const queuedAgentRunStaleSeconds = 24 * 60 * 60;
+export async function findActiveAgentRun(control, input) {
+    const now = input.now ?? nowIso();
+    const nowMs = new Date(now).getTime();
+    const runningStaleBefore = new Date(nowMs - activeAgentRunStaleSeconds * 1000).toISOString();
+    const queuedStaleBefore = new Date(nowMs - queuedAgentRunStaleSeconds * 1000).toISOString();
+    return control.first(`SELECT * FROM ${q("_agent_runs")}
+     WHERE "agentName" = ? AND "conversationId" = ?
+       AND (("status" = 'running' AND COALESCE("heartbeatAt", "startedAt") > ?) OR ("status" = 'queued' AND "startedAt" > ?))
+     ORDER BY "startedAt" DESC LIMIT 1`, [input.agentName, input.conversationId, runningStaleBefore, queuedStaleBefore]);
+}
+/**
+ * A run whose writer is known to be gone rather than merely late.
+ *
+ * The staleness sweep does not write this and must not: from a horizon it
+ * cannot tell a restart from a turn that simply ran long, and claiming a
+ * restart sends debugging after reloads that never happened. The conversation
+ * object can tell, because it knows which runs the isolate it is running in
+ * actually holds, so it settles its own orphans under this label the moment it
+ * next reconciles (`isOrphanedRun` in agent-ai-chat.ts). Rows written by
+ * earlier builds carry it too, which is why isReapedAgentRunError still
+ * matches it.
+ */
+export const interruptedAgentRunError = "Interrupted by restart or deployment";
+const staleAgentRunErrorPrefix = "Timed out: no completion within";
+const staleQueuedAgentRunErrorPrefix = "Timed out: did not start within";
+/**
+ * What the execution sweep actually knows: the run was still running when it
+ * passed the horizon. Names the configured horizon so a reader can tell
+ * "this turn was too slow" from "something killed the isolate".
+ */
+export function staleAgentRunError(staleSeconds = activeAgentRunStaleSeconds) {
+    return `${staleAgentRunErrorPrefix} the ${staleSeconds}s agent run staleness horizon`;
+}
+/** Truthful terminal label for work that remained queued without starting. */
+export function staleQueuedAgentRunError(staleSeconds = queuedAgentRunStaleSeconds) {
+    return `${staleQueuedAgentRunErrorPrefix} the ${staleSeconds}s agent queue-wait horizon`;
+}
+/**
+ * True for any run the staleness sweep marked failed, under either current
+ * label or the legacy one. Retry, redispatch and coverage checks
+ * treat such a run as "no live writer" rather than as a real turn outcome, so
+ * they must match both.
+ */
+export function isReapedAgentRunError(error) {
+    if (!error)
+        return false;
+    return error === interruptedAgentRunError
+        || error.startsWith(staleAgentRunErrorPrefix)
+        || error.startsWith(staleQueuedAgentRunErrorPrefix);
+}
+/**
+ * Terminal bookkeeping for runs no writer is left to finish. A deploy or
+ * crash kills the writer between run creation and the completed/failed
+ * update, so the row sits at running with finishedAt null forever and runs
+ * evidence reports a turn that is not executing.
+ *
+ * A running row is judged on `heartbeatAt`, not on when it started (2026-08-25).
+ * On `startedAt` this swept up **live** turns: a turn is not late because it is
+ * long, and a nine-round tool loop passes five minutes without anything being
+ * wrong with it. What that cost was not a stray row — it was a member reading
+ * "Birch ran into a problem while answering" twenty-four seconds before the
+ * same run delivered its answer, because the sweep's terminal write is what the
+ * conversation reports. The heartbeat is touched per model step, so a wedged
+ * turn stops beating and is still reaped on time, which is the whole point of
+ * having a horizon. Rows written before the column coalesce to `startedAt` and
+ * are swept exactly as they were.
+ *
+ * A queued row keeps its own queue-wait horizon against `startedAt` and its own
+ * label, because its execution has not begun and there is nothing to beat.
+ * Status and timestamp predicates are re-checked in each UPDATE so adoption
+ * cannot be reaped using its former queue clock.
+ */
+export async function sweepStaleAgentRuns(control, input = {}) {
+    const now = input.now ?? nowIso();
+    const nowMs = new Date(now).getTime();
+    const runningStaleBefore = new Date(nowMs - activeAgentRunStaleSeconds * 1000).toISOString();
+    const queuedStaleBefore = new Date(nowMs - queuedAgentRunStaleSeconds * 1000).toISOString();
+    const limit = Math.max(1, Math.min(500, input.limit ?? 100));
+    const stale = await control.all(`SELECT "runId", "status" FROM ${q("_agent_runs")}
+     WHERE ("status" = 'running' AND COALESCE("heartbeatAt", "startedAt") <= ?)
+        OR ("status" = 'queued' AND "startedAt" <= ?)
+     ORDER BY "startedAt" ASC LIMIT ?`, [runningStaleBefore, queuedStaleBefore, limit]);
+    if (stale.length === 0)
+        return [];
+    const runningIds = stale.filter((row) => row.status === "running").map((row) => row.runId);
+    const queuedIds = stale.filter((row) => row.status === "queued").map((row) => row.runId);
+    if (runningIds.length) {
+        await control.run(`UPDATE ${q("_agent_runs")}
+       SET "status" = 'failed', "error" = ?, "finishedAt" = ?
+       WHERE "runId" IN (${runningIds.map(() => "?").join(", ")})
+         AND "status" = 'running' AND COALESCE("heartbeatAt", "startedAt") <= ?`, [staleAgentRunError(), now, ...runningIds, runningStaleBefore]);
+    }
+    if (queuedIds.length) {
+        await control.run(`UPDATE ${q("_agent_runs")}
+       SET "status" = 'failed', "error" = ?, "finishedAt" = ?
+       WHERE "runId" IN (${queuedIds.map(() => "?").join(", ")})
+         AND "status" = 'queued' AND "startedAt" <= ?`, [staleQueuedAgentRunError(), now, ...queuedIds, queuedStaleBefore]);
+    }
+    return stale.map((row) => row.runId);
+}
+/**
+ * Deletes poll/idempotency evidence after each owning Agent's configured
+ * evidence window. Request replay and outcome polling are guaranteed only
+ * while their receipt and run evidence remain inside that window.
+ */
+export async function sweepAgentRunEvidence(control, input = {}) {
+    const nowMs = new Date(input.now ?? nowIso()).getTime();
+    const limit = Math.max(1, Math.min(2_000, input.limit ?? 500));
+    const ttlForAgent = input.runEvidenceTtlMsForAgent
+        ?? (() => defaultAgentRunEvidenceTtlMs);
+    const pageSize = Math.min(500, Math.max(100, limit));
+    const earliestPossibleExpiry = new Date(nowMs - minAgentRunEvidenceTtlMs).toISOString();
+    const runIds = [];
+    let runCursor = null;
+    while (runIds.length < limit) {
+        const terminalRuns = await control.all(`SELECT "runId", "agentName", "finishedAt"
+         FROM ${q("_agent_runs")}
+         WHERE "status" IN ('completed', 'cancelled', 'failed', 'skipped')
+           AND "finishedAt" IS NOT NULL
+           AND "finishedAt" < ?
+           ${runCursor ? `AND ("finishedAt" > ? OR ("finishedAt" = ? AND "runId" > ?))` : ""}
+         ORDER BY "finishedAt" ASC, "runId" ASC
+         LIMIT ?`, runCursor
+            ? [earliestPossibleExpiry, runCursor.finishedAt, runCursor.finishedAt, runCursor.runId, pageSize]
+            : [earliestPossibleExpiry, pageSize]);
+        for (const row of terminalRuns) {
+            const finishedAtMs = row.finishedAt ? new Date(row.finishedAt).getTime() : Number.NaN;
+            const ttlMs = ttlForAgent(row.agentName);
+            if (Number.isFinite(finishedAtMs) && Number.isFinite(ttlMs) && nowMs - finishedAtMs > ttlMs) {
+                runIds.push(row.runId);
+                if (runIds.length === limit)
+                    break;
+            }
+        }
+        const last = terminalRuns.at(-1);
+        if (!last?.finishedAt || terminalRuns.length < pageSize || runIds.length === limit)
+            break;
+        runCursor = { finishedAt: last.finishedAt, runId: last.runId };
+    }
+    for (let offset = 0; offset < runIds.length; offset += 50) {
+        const batch = runIds.slice(offset, offset + 50);
+        await control.run(`DELETE FROM ${q("_agent_runs")} WHERE "runId" IN (${batch.map(() => "?").join(", ")})`, batch);
+    }
+    const requestIds = [];
+    let receiptCursor = null;
+    while (requestIds.length < limit) {
+        const receipts = await control.all(`SELECT r."id", r."createdAt", i."agentName"
+       FROM ${q("_agent_requests")} r
+       LEFT JOIN ${q("_agent_instances")} i ON i."conversationId" = r."conversationId"
+       WHERE r."createdAt" < ?
+         ${receiptCursor ? `AND (r."createdAt" > ? OR (r."createdAt" = ? AND r."id" > ?))` : ""}
+       ORDER BY r."createdAt" ASC, r."id" ASC
+       LIMIT ?`, receiptCursor
+            ? [earliestPossibleExpiry, receiptCursor.createdAt, receiptCursor.createdAt, receiptCursor.id, pageSize]
+            : [earliestPossibleExpiry, pageSize]);
+        for (const row of receipts) {
+            const createdAtMs = new Date(row.createdAt).getTime();
+            const ttlMs = row.agentName
+                ? ttlForAgent(row.agentName)
+                : defaultAgentRunEvidenceTtlMs;
+            if (Number.isFinite(createdAtMs) && Number.isFinite(ttlMs) && nowMs - createdAtMs > ttlMs) {
+                requestIds.push(row.id);
+                if (requestIds.length === limit)
+                    break;
+            }
+        }
+        const last = receipts.at(-1);
+        if (!last || receipts.length < pageSize || requestIds.length === limit)
+            break;
+        receiptCursor = { createdAt: last.createdAt, id: last.id };
+    }
+    for (let offset = 0; offset < requestIds.length; offset += 50) {
+        const batch = requestIds.slice(offset, offset + 50);
+        await control.run(`DELETE FROM ${q("_agent_requests")} WHERE "id" IN (${batch.map(() => "?").join(", ")})`, batch);
+    }
+    return { runIds, requestIds };
+}
+/**
+ * Mark a run as still working, without touching anything else about it.
+ *
+ * One column, one row, no read first — it runs once per model step inside a
+ * turn that is already doing far more expensive things, and it must never be
+ * the reason a turn fails. A run that has already reached a terminal status is
+ * left alone by the status predicate rather than by a check here, so a beat
+ * that lands in the teardown race cannot resurrect a finished row.
+ */
+export async function touchAgentRunHeartbeat(control, runId, now = nowIso()) {
+    await control.run(`UPDATE ${q("_agent_runs")} SET "heartbeatAt" = ? WHERE "runId" = ? AND "status" = 'running'`, [now, runId]);
+}
+export async function updateAgentRun(control, runId, input) {
+    const current = await control.first(`SELECT * FROM ${q("_agent_runs")} WHERE "runId" = ? LIMIT 1`, [runId]);
+    if (!current)
+        throw new AgentHttpError("Agent run not found", 404);
+    const status = input.status ?? current.status;
+    const startedAt = input.startedAt
+        ?? (current.status === "queued" && status === "running" ? nowIso() : current.startedAt);
+    const finishedAt = input.finishedAt !== undefined
+        ? input.finishedAt
+        : status === "completed" || status === "cancelled" || status === "failed" || status === "skipped"
+            ? nowIso()
+            : current.finishedAt;
+    // Execution starting is itself a sign of life, and the queue wait before it
+    // is not: a row that sat queued for an hour must not begin its running life
+    // already an hour stale. Every other update leaves the mark where the turn's
+    // own steps put it.
+    const heartbeatAt = startedAt !== current.startedAt ? startedAt : current.heartbeatAt;
+    await control.run(`UPDATE ${q("_agent_runs")}
+     SET "status" = ?, "startedAt" = ?, "heartbeatAt" = ?, "error" = ?, "finishedAt" = ?, "metadataJson" = ?
+     WHERE "runId" = ?`, [
+        status,
+        startedAt,
+        heartbeatAt,
+        input.error !== undefined ? input.error : current.error,
+        finishedAt,
+        input.metadata !== undefined ? stableJson(input.metadata) : current.metadataJson,
+        runId
+    ]);
+}
+export async function touchAgentInstance(control, instanceId, input = {}) {
+    const now = nowIso();
+    await control.run(`UPDATE ${q("_agent_instances")}
+     SET "lastActiveAt" = ?, "expiresAt" = ?, "updatedAt" = ?, "lastError" = ?
+     WHERE "id" = ?`, [now, agentExpiresAt(input.ttlSeconds), now, input.lastError ?? null, instanceId]);
+}
+export async function listExpiredAgentInstances(control, input = {}) {
+    const now = input.now ?? nowIso();
+    const staleDeletingBefore = new Date(new Date(now).getTime() - staleDeletingRetrySeconds * 1000).toISOString();
+    const limit = Math.max(1, Math.min(500, input.limit ?? 50));
+    return control.all(`SELECT * FROM ${q("_agent_instances")}
+     WHERE "runtime" = 'ai-chat'
+       AND "triggerType" = 'chat'
+       AND (
+         ("expiresAt" IS NOT NULL AND "expiresAt" <= ? AND "status" IN ('active', 'cleanupRequested', 'cleanupError'))
+         OR ("status" = 'deleting' AND "updatedAt" <= ?)
+       )
+     ORDER BY "expiresAt" ASC
+     LIMIT ?`, [now, staleDeletingBefore, limit]);
+}
+export async function markAgentCleanupRequested(control, instanceId, input = {}) {
+    const now = input.now ?? nowIso();
+    await control.run(`UPDATE ${q("_agent_instances")}
+     SET "status" = CASE WHEN "status" = 'active' THEN 'cleanupRequested' ELSE "status" END,
+         "cleanupRequestedAt" = COALESCE("cleanupRequestedAt", ?),
+         "retentionReason" = COALESCE("retentionReason", ?),
+         "lastError" = ?,
+         "updatedAt" = ?
+     WHERE "id" = ? AND "status" IN ('active', 'cleanupRequested', 'cleanupError')`, [now, input.reason ?? null, input.error ?? null, now, instanceId]);
+}
+export async function beginAgentHotCleanup(control, input) {
+    const now = input.now ?? nowIso();
+    const staleDeletingBefore = new Date(new Date(now).getTime() - staleDeletingRetrySeconds * 1000).toISOString();
+    const current = await control.first(`SELECT * FROM ${q("_agent_instances")} WHERE "id" = ? LIMIT 1`, [input.instance.id]);
+    if (!current)
+        throw new AgentHttpError("Agent conversation not found", 404);
+    if (current.status === "deleted" || current.status === "archived")
+        return { status: "terminal", instance: current };
+    if (current.status === "deleting" && current.updatedAt > staleDeletingBefore)
+        return { status: "busy", instance: current };
+    if (current.status !== "deleting" && !retryableCleanupStatuses.has(current.status))
+        return { status: "busy", instance: current };
+    if (current.status !== "deleting" && (current.expiresAt === null || new Date(current.expiresAt).getTime() > new Date(now).getTime())) {
+        await control.run(`UPDATE ${q("_agent_instances")}
+       SET "status" = 'active', "lastError" = NULL, "updatedAt" = ?
+       WHERE "id" = ? AND "status" IN ('cleanupRequested', 'cleanupError')`, [now, current.id]);
+        const rescheduled = await control.first(`SELECT * FROM ${q("_agent_instances")} WHERE "id" = ? LIMIT 1`, [current.id]);
+        return { status: "reschedule", instance: rescheduled ?? current };
+    }
+    await control.run(`UPDATE ${q("_agent_instances")}
+     SET "status" = 'deleting',
+         "cleanupRequestedAt" = COALESCE("cleanupRequestedAt", ?),
+         "retentionReason" = COALESCE("retentionReason", ?),
+         "lastError" = NULL,
+         "updatedAt" = ?
+     WHERE "id" = ?
+       AND (
+         ("status" IN ('active', 'cleanupRequested', 'cleanupError') AND "expiresAt" IS NOT NULL AND "expiresAt" <= ?)
+         OR ("status" = 'deleting' AND "updatedAt" <= ?)
+       )`, [now, input.reason ?? null, now, current.id, now, staleDeletingBefore]);
+    const next = await control.first(`SELECT * FROM ${q("_agent_instances")} WHERE "id" = ? LIMIT 1`, [current.id]);
+    if (!next)
+        throw new AgentHttpError("Agent conversation not found", 404);
+    if (next.status !== "deleting") {
+        if (next.status === "deleted" || next.status === "archived")
+            return { status: "terminal", instance: next };
+        if (next.expiresAt === null || new Date(next.expiresAt).getTime() > new Date(now).getTime() || next.status === "active")
+            return { status: "reschedule", instance: next };
+        return { status: "busy", instance: next };
+    }
+    return { status: "delete", instance: next };
+}
+export async function completeAgentHotCleanup(control, instanceId, input = {}) {
+    const now = input.now ?? nowIso();
+    const outcome = input.outcome ?? "deleted";
+    if (outcome === "archived") {
+        await control.run(`UPDATE ${q("_agent_instances")}
+       SET "status" = 'archived', "deletedAt" = NULL,
+           "updatedAt" = ?, "lastError" = NULL
+       WHERE "id" = ? AND "status" = 'deleting'
+         AND COALESCE("retentionReason", '') <> 'user-deleted'`, [now, instanceId]);
+        return;
+    }
+    await control.run(`UPDATE ${q("_agent_instances")}
+     SET "status" = 'deleted', "deletedAt" = COALESCE("deletedAt", ?),
+         "updatedAt" = ?, "lastError" = NULL
+     WHERE "id" = ? AND "status" = 'deleting'
+       AND NOT EXISTS (
+         SELECT 1 FROM ${q("_agent_chapter_purges")} p
+         WHERE p."scopeKind" = 'conversation'
+           AND p."scopeId" = ${q("_agent_instances")}."conversationId"
+       )`, [now, now, instanceId]);
+}
+export async function completeAgentUserErasureAfterArtifactDrain(control, userId, input = {}) {
+    const pendingArtifacts = await control.first(`SELECT COUNT(*) AS "count" FROM ${q("_agent_chapter_purges")}
+     WHERE "scopeKind" = 'user' AND "scopeId" = ?`, [userId]);
+    if (Number(pendingArtifacts?.count ?? 0) > 0)
+        return false;
+    const pendingRoomRedactions = await countPendingAgentRoomMemberRedactions(control, userId);
+    if (pendingRoomRedactions > 0)
+        return false;
+    const unverifiedHotStorage = await control.first(`SELECT COUNT(*) AS "count" FROM ${q("_agent_instances")}
+     WHERE "runtime" = 'ai-chat' AND "triggerType" = 'chat'
+       AND "userId" = ? AND "status" <> 'deleted'
+       AND "hotStorageDeletedAt" IS NULL`, [userId]);
+    if (Number(unverifiedHotStorage?.count ?? 0) > 0)
+        return false;
+    const now = input.now ?? nowIso();
+    await control.run(`UPDATE ${q("_agent_instances")}
+     SET "status" = 'deleted',
+         "deletedAt" = COALESCE("deletedAt", ?),
+         "lastError" = NULL,
+         "updatedAt" = ?
+     WHERE "runtime" = 'ai-chat' AND "triggerType" = 'chat'
+       AND "userId" = ? AND "status" <> 'deleted'
+       AND "retentionReason" = 'user-deleted'
+       AND "hotStorageDeletedAt" IS NOT NULL
+       AND NOT EXISTS (
+         SELECT 1 FROM ${q("_agent_chapter_purges")} p
+         WHERE p."scopeKind" = 'user'
+           AND p."scopeId" = ${q("_agent_instances")}."userId"
+       )`, [now, now, userId]);
+    const remaining = await control.first(`SELECT COUNT(*) AS "count" FROM ${q("_agent_instances")}
+     WHERE "runtime" = 'ai-chat' AND "triggerType" = 'chat'
+       AND "userId" = ? AND "status" <> 'deleted'`, [userId]);
+    return Number(remaining?.count ?? 0) === 0;
+}
+export async function countPendingAgentRoomMemberRedactions(control, userId) {
+    const pending = await control.first(`SELECT COUNT(*) AS "count" FROM ${q("_agent_chapter_purges")}
+     WHERE "scopeKind" = 'room-member'
+       AND substr("scopeId", -(length(?) + 1)) = ':' || ?`, [userId, userId]);
+    return Number(pending?.count ?? 0);
+}
+export async function failAgentHotCleanup(control, instanceId, input) {
+    const now = input.now ?? nowIso();
+    await control.run(`UPDATE ${q("_agent_instances")}
+     SET "status" = 'cleanupError', "lastError" = ?, "updatedAt" = ?
+     WHERE "id" = ? AND "status" IN ('cleanupRequested', 'deleting', 'cleanupError')`, [input.error, now, instanceId]);
+}
+export async function claimAgentGuideLimits(input) {
+    const limits = input.agent.limits;
+    if (!limits)
+        return;
+    if (input.instance.principalKind === "public") {
+        const publicScope = input.instance.publicScopeHash ?? "public";
+        if (limits.publicIpHourlyRequests || limits.publicIpHourlyOutputTokens) {
+            await claimAgentLimitWindow({
+                control: input.control,
+                scope: "public-ip-hourly",
+                scopeId: publicScope,
+                durationMs: 60 * 60 * 1000,
+                requestLimit: limits.publicIpHourlyRequests,
+                outputLimit: limits.publicIpHourlyOutputTokens,
+                estimatedOutputTokens: input.estimatedOutputTokens
+            });
+        }
+        if (limits.publicDailyRequests || limits.publicDailyOutputTokens) {
+            await claimAgentLimitWindow({
+                control: input.control,
+                scope: "public-daily",
+                scopeId: publicScope,
+                durationMs: 24 * 60 * 60 * 1000,
+                requestLimit: limits.publicDailyRequests,
+                outputLimit: limits.publicDailyOutputTokens,
+                estimatedOutputTokens: input.estimatedOutputTokens
+            });
+        }
+    }
+    else if (limits.signedInDailyRequests) {
+        await claimAgentLimitWindow({
+            control: input.control,
+            scope: "signed-in-daily",
+            scopeId: input.instance.userId ?? "user",
+            durationMs: 24 * 60 * 60 * 1000,
+            requestLimit: limits.signedInDailyRequests,
+            estimatedOutputTokens: 0
+        });
+    }
+}
+/** `limit` unset means unlimited; the window row is still counted so usage stays visible. */
+export async function claimAgentEntryKickoffLimit(control, instance, limit) {
+    if (instance.principalKind !== "user" || !instance.userId) {
+        throw new AgentHttpError("Agent entry kickoff requires a signed-in user", 403);
+    }
+    await claimAgentLimitWindow({
+        control,
+        scope: "entry-kickoff",
+        scopeId: instance.userId,
+        durationMs: 24 * 60 * 60 * 1000,
+        requestLimit: limit,
+        estimatedOutputTokens: 0
+    });
+}
+/** `limit` unset means unlimited; the window row is still counted so usage stays visible. */
+export async function claimAgentComposedLimit(control, instance, limit) {
+    if (instance.principalKind !== "user" || !instance.userId) {
+        throw new AgentHttpError("Composed Agent turns require a user conversation", 403);
+    }
+    await claimAgentLimitWindow({
+        control,
+        scope: "composed-daily",
+        scopeId: instance.conversationId,
+        durationMs: 24 * 60 * 60 * 1000,
+        requestLimit: limit,
+        estimatedOutputTokens: 0
+    });
+}
+export async function signAgentToken(secret, claims) {
+    const now = Math.floor(wallNowMs() / 1000);
+    const payload = {
+        ...claims,
+        iat: now,
+        exp: now + Math.max(1, Math.floor(claims.ttlSeconds)),
+        nonce: randomId("agent_nonce")
+    };
+    const body = base64url(encoder.encode(JSON.stringify(payload)));
+    const signature = await hmac(secret, body);
+    return `${body}.${signature}`;
+}
+export async function verifyAgentToken(secret, token, purpose) {
+    const [body, signature] = token.split(".");
+    // Names the shape, not the verdict: this branch is reached by strings that
+    // are not tokens at all (an absent mint interpolated as "undefined", a
+    // truncated copy/paste), and "Invalid agent token" reads as a refusal of a
+    // token that was actually issued.
+    if (!body || !signature)
+        throw new AgentHttpError("Invalid agent token format", 401);
+    const expected = await hmac(secret, body);
+    if (!timingSafeEqual(signature, expected))
+        throw new AgentHttpError("Invalid agent token signature", 401);
+    let claims;
+    try {
+        claims = JSON.parse(decoder.decode(fromBase64url(body)));
+    }
+    catch {
+        throw new AgentHttpError("Invalid agent token payload", 401);
+    }
+    if (claims.v !== 1 || claims.aud !== "raybase-agent-chat" || claims.purpose !== purpose)
+        throw new AgentHttpError("Invalid agent token claims", 401);
+    if (claims.exp <= Math.floor(wallNowMs() / 1000))
+        throw new AgentHttpError("Agent token expired", 401);
+    return claims;
+}
+export function agentTokenClaims(input) {
+    return {
+        v: 1,
+        purpose: input.purpose,
+        aud: "raybase-agent-chat",
+        agentName: input.instance.agentName,
+        conversationId: input.instance.conversationId,
+        runtime: "ai-chat",
+        triggerType: "chat",
+        principalKind: input.instance.principalKind,
+        userId: input.userId ?? input.instance.userId ?? undefined,
+        publicScopeHash: input.instance.publicScopeHash ?? undefined,
+        organizationId: input.instance.organizationId ?? undefined,
+        route: input.instance.route ?? undefined,
+        surface: input.instance.surface,
+        socketMode: input.socketMode,
+        ttlSeconds: input.ttlSeconds ?? (input.purpose === "agent-websocket" ? websocketBootstrapTtlSeconds : defaultConversationTtlSeconds)
+    };
+}
+export function assertAgentTokenMatchesInstance(claims, instance) {
+    if (claims.agentName !== instance.agentName || claims.conversationId !== instance.conversationId || claims.runtime !== instance.runtime) {
+        throw new AgentHttpError("Agent token does not match conversation", 401);
+    }
+    if (claims.principalKind !== instance.principalKind)
+        throw new AgentHttpError("Agent token principal mismatch", 401);
+    if (instance.kind !== "room") {
+        if ((claims.userId ?? null) !== (instance.userId ?? null))
+            throw new AgentHttpError("Agent token user mismatch", 401);
+        if ((claims.publicScopeHash ?? null) !== (instance.publicScopeHash ?? null))
+            throw new AgentHttpError("Agent token public scope mismatch", 401);
+    }
+    else if (!claims.userId) {
+        throw new AgentHttpError("Agent token user mismatch", 401);
+    }
+    if ((claims.organizationId ?? null) !== (instance.organizationId ?? null))
+        throw new AgentHttpError("Agent token organization mismatch", 401);
+}
+export async function assertAgentTokenConversationAccess(control, claims, instance) {
+    assertAgentTokenMatchesInstance(claims, instance);
+    if (instance.kind !== "room")
+        return { membership: null };
+    const membership = await findAgentRoomMember(control, instance.conversationId, claims.userId);
+    if (!membership || membership.status !== "active") {
+        throw new AgentHttpError("Agent room member mismatch", 403);
+    }
+    return { membership };
+}
+export function extractBearerToken(request) {
+    const authorization = request.headers.get("authorization") ?? "";
+    const match = /^Bearer\s+(.+)$/i.exec(authorization.trim());
+    return match?.[1] ?? null;
+}
+export function raybaseActionToAiTool(action, contextFactory) {
+    return tool({
+        description: action.description,
+        inputSchema: jsonSchema(actionInputJsonSchema(action)),
+        execute: async (input, options = {}) => {
+            const toolCallId = typeof options?.toolCallId === "string" ? options.toolCallId : randomId("tool_call");
+            const ctx = await contextFactory({ toolCallId });
+            return executeRaybaseAgentAction(action, input, ctx);
+        }
+    });
+}
+export async function executeRaybaseAgentAction(action, rawInput, 
+// Keep raw control on this wrapper only; action handlers receive it as
+// ctx.control through executeAction().
+ctx) {
+    // The action sees the agent as its principal. Authority (policies, audience,
+    // data access) still comes from the run's own user or visitor, which the
+    // agent principal carries as onBehalfOf; what changes is attribution.
+    const principal = agentPrincipal({
+        agent: ctx.agentName,
+        onBehalfOf: ctx.principal,
+        scopes: ctx.agentScopes,
+        organizationId: ctx.organizationId ?? null,
+        runId: ctx.runId,
+        conversationId: ctx.conversationId
+    });
+    // Tool arguments arrive in the strict wire form a provider will carry. The
+    // action's own schema is the one that decides, so the padding comes off
+    // first; see restoreStrictActionInput.
+    return executeAction(action, restoreStrictActionInput(action, rawInput), {
+        request: ctx.request,
+        env: ctx.env,
+        user: ctx.user,
+        principal,
+        db: ctx.db,
+        auth: ctx.control
+            ? createRaybaseAuthContextRuntime({
+                db: ctx.control,
+                secret: authSecret(ctx.env),
+                config: ctx.config,
+                sessionAuthenticated: false,
+                principal,
+                request: ctx.request,
+                audit: ctx.audit
+            })
+            : unsupportedRaybaseAuthContextRuntime,
+        ai: ctx.ai,
+        settings: ctx.settings,
+        notifications: ctx.notifications,
+        jobs: ctx.jobs,
+        agentName: ctx.agentName,
+        agentInstanceId: ctx.agentInstanceId,
+        trigger: ctx.trigger,
+        conversationId: ctx.conversationId,
+        ...(ctx.conversations ? { conversations: ctx.conversations } : {}),
+        runId: ctx.runId,
+        requestId: ctx.requestId,
+        toolCallId: ctx.toolCallId,
+        route: ctx.route,
+        surface: ctx.surface,
+        organizationId: ctx.organizationId,
+        audit: ctx.audit,
+        agents: ctx.agents ?? unsupportedRaybaseAgentInvocationRuntime,
+        control: ctx.control
+    }, {
+        surface: "agent",
+        requirePolicy: ctx.principal.kind === "user",
+        onAccounting: async (event) => {
+            if (!ctx.control)
+                return;
+            await recordAiActionEvent(ctx.control, {
+                userId: event.status === "denied" && ctx.principal.kind === "user" ? ctx.principal.user.id : actionEventUserId(ctx.principal),
+                agent: ctx.agentName,
+                conversationId: ctx.conversationId,
+                actionName: event.actionName,
+                actionInput: event.actionInput,
+                status: event.status,
+                error: event.error
+            });
+        }
+    });
+}
+export function agentLimits(config, agent) {
+    const defaults = normalizeAiDefaults(config);
+    const aiLimits = normalizeAiLimits(config);
+    return {
+        maxInputChars: agent.limits?.maxInputChars ?? defaults.maxInputChars,
+        maxOutputTokens: agent.limits?.maxOutputTokens ?? defaults.maxOutputTokens,
+        maxToolCallsPerTurn: agent.limits?.maxToolCallsPerTurn ?? aiLimits.maxToolCallsPerTurn,
+        maxLoopStepsPerTurn: agent.limits?.maxLoopStepsPerTurn ?? aiLimits.maxLoopStepsPerTurn,
+        maxConversationMessages: agent.limits?.maxConversationMessages ?? aiLimits.maxConversationMessages,
+        loopReserveChars: agent.limits?.loopReserveChars,
+        publicIpHourlyRequests: agent.limits?.publicIpHourlyRequests,
+        publicIpHourlyOutputTokens: agent.limits?.publicIpHourlyOutputTokens,
+        publicDailyRequests: agent.limits?.publicDailyRequests ?? aiLimits.perPublicDailyRequests,
+        publicDailyOutputTokens: agent.limits?.publicDailyOutputTokens ?? aiLimits.perPublicDailyOutputTokens,
+        signedInDailyRequests: agent.limits?.signedInDailyRequests ?? aiLimits.perUserDailyRequests,
+        composedPerDay: agent.limits?.composedPerDay,
+        entryKickoffPerDay: agent.limits?.entryKickoffPerDay
+    };
+}
+export function agentCompaction(agent) {
+    return {
+        enabled: agent.compaction?.enabled ?? defaultAgentCompaction.enabled,
+        model: agent.compaction?.model,
+        keepRecentMessages: agent.compaction?.keepRecentMessages ?? defaultAgentCompaction.keepRecentMessages,
+        triggerRatio: agent.compaction?.triggerRatio ?? defaultAgentCompaction.triggerRatio,
+        minSummaryOutputTokens: agent.compaction?.minSummaryOutputTokens ?? defaultAgentCompaction.minSummaryOutputTokens,
+        summarySpanRatio: agent.compaction?.summarySpanRatio ?? defaultAgentCompaction.summarySpanRatio,
+        maxSummaryOutputTokens: agent.compaction?.maxSummaryOutputTokens ?? defaultAgentCompaction.maxSummaryOutputTokens
+    };
+}
+/**
+ * Output-token budget for one chapter-close summarization call, proportional
+ * to the span being summarized:
+ * clamp(minSummaryOutputTokens, round(summarySpanRatio × spanChars/4),
+ * maxSummaryOutputTokens). `spanChars` is the total content length of the
+ * messages actually being closed, so a three-message exchange keeps the floor
+ * while a twenty-turn working session gets room for its settled facts.
+ * The ceiling wins over the floor when a pinned `maxSummaryOutputTokens`
+ * sits below the (defaulted) floor: an app that pinned the old flat budget
+ * keeps exactly its pre-proportional summaries.
+ */
+export function agentSummaryBudgetTokens(compaction, spanChars) {
+    const min = compaction?.minSummaryOutputTokens ?? defaultAgentCompaction.minSummaryOutputTokens;
+    const ratio = compaction?.summarySpanRatio ?? defaultAgentCompaction.summarySpanRatio;
+    const max = compaction?.maxSummaryOutputTokens ?? defaultAgentCompaction.maxSummaryOutputTokens;
+    const proportional = Math.round(ratio * estimateTokensFromChars(spanChars));
+    return Math.min(max, Math.max(min, proportional));
+}
+export function agentModel(config, agent, runtimeDefaultModel) {
+    return agent.model ?? runtimeDefaultModel ?? normalizeAiDefaults(config).model;
+}
+export function actionEventUserId(principal) {
+    return principal.kind === "user" ? principal.user.id : principal.id;
+}
+async function claimAgentLimitWindow(input) {
+    const now = appNowMs();
+    const windowStartMs = Math.floor(now / input.durationMs) * input.durationMs;
+    const windowStart = new Date(windowStartMs).toISOString();
+    const windowEnd = new Date(windowStartMs + input.durationMs).toISOString();
+    const row = await input.control.first(`SELECT "requestCount", "estimatedOutputTokens" FROM ${q("_agent_limit_windows")}
+     WHERE "scope" = ? AND "scopeId" = ? AND "windowStart" = ? LIMIT 1`, [input.scope, input.scopeId, windowStart]);
+    const nextRequests = Number(row?.requestCount ?? 0) + 1;
+    const nextOutput = Number(row?.estimatedOutputTokens ?? 0) + Math.max(0, input.estimatedOutputTokens);
+    if (input.requestLimit !== undefined && nextRequests > input.requestLimit) {
+        throw new AgentHttpError(`Agent request limit exceeded for ${input.scope}`, 429);
+    }
+    if (input.outputLimit !== undefined && nextOutput > input.outputLimit) {
+        throw new AgentHttpError(`Agent output token limit exceeded for ${input.scope}`, 429);
+    }
+    if (row) {
+        await input.control.run(`UPDATE ${q("_agent_limit_windows")}
+       SET "requestCount" = ?, "estimatedOutputTokens" = ?, "updatedAt" = ?
+       WHERE "scope" = ? AND "scopeId" = ? AND "windowStart" = ?`, [nextRequests, nextOutput, nowIso(), input.scope, input.scopeId, windowStart]);
+    }
+    else {
+        await input.control.run(`INSERT INTO ${q("_agent_limit_windows")}
+       ("id", "scope", "scopeId", "windowStart", "windowEnd", "requestCount", "estimatedOutputTokens", "updatedAt")
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`, [randomId("agent_limit"), input.scope, input.scopeId, windowStart, windowEnd, nextRequests, nextOutput, nowIso()]);
+    }
+}
+export async function assertAgentConversationAccess(input) {
+    if (input.instance.kind !== "room") {
+        assertAgentInstanceAccess(input.instance, input.access);
+        return { membership: null };
+    }
+    if (input.access.principal.kind !== "user") {
+        throw new AgentHttpError("Agent room member mismatch", 403);
+    }
+    const membership = await findAgentRoomMember(input.control, input.instance.conversationId, input.access.principal.user.id);
+    if (!membership || membership.status !== "active") {
+        throw new AgentHttpError("Agent room member mismatch", 403);
+    }
+    if (input.require === "owner" && membership.role !== "owner") {
+        throw new AgentHttpError("Agent conversation owner mismatch", 403);
+    }
+    return { membership };
+}
+function assertAgentInstanceAccess(instance, access) {
+    if (instance.principalKind !== access.principal.kind)
+        throw new AgentHttpError("Agent conversation principal mismatch", 403);
+    if (access.principal.kind === "user" && instance.userId !== access.principal.user.id)
+        throw new AgentHttpError("Agent conversation user mismatch", 403);
+    if (access.principal.kind === "public" && instance.publicScopeHash !== access.principal.id)
+        throw new AgentHttpError("Agent conversation public scope mismatch", 403);
+}
+function uniqueAudiences(values) {
+    return Array.from(new Set(values));
+}
+function normalizeRoute(path) {
+    const value = path.startsWith("/") ? path : `/${path}`;
+    return value.replace(/\/{2,}/g, "/") || "/";
+}
+function optionalUserField(user, field) {
+    if (!user || typeof user !== "object")
+        return undefined;
+    const value = user[field];
+    return typeof value === "string" && value ? value : undefined;
+}
+function principalOrganizationId(user) {
+    return optionalUserField(user, "organizationId") ?? null;
+}
+async function publicAgentPrincipal(request, organizationId, requestContext) {
+    const ip = request.headers.get("cf-connecting-ip") ?? request.headers.get("x-forwarded-for")?.split(",")[0]?.trim() ?? "local";
+    const userAgent = request.headers.get("user-agent") ?? "unknown";
+    const sessionHash = await sha256Hex(`${ip}:${userAgent}:${requestContext.surface}`);
+    return {
+        kind: "public",
+        id: sessionHash.slice(0, 64),
+        sessionHash: sessionHash.slice(0, 64),
+        organizationId: organizationId ?? undefined,
+        surface: requestContext.surface,
+        route: requestContext.route,
+        origin: requestContext.origin,
+        ipHash: (await sha256Hex(ip)).slice(0, 64),
+        userAgentHash: (await sha256Hex(userAgent)).slice(0, 64)
+    };
+}
+function base64url(bytes) {
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+function fromBase64url(value) {
+    const padded = value.replace(/-/g, "+").replace(/_/g, "/").padEnd(Math.ceil(value.length / 4) * 4, "=");
+    const binary = atob(padded);
+    const bytes = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index += 1)
+        bytes[index] = binary.charCodeAt(index);
+    return bytes;
+}
+async function hmac(secret, data) {
+    const key = await crypto.subtle.importKey("raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    const signature = await crypto.subtle.sign("HMAC", key, encoder.encode(data));
+    return base64url(new Uint8Array(signature));
+}
+function timingSafeEqual(left, right) {
+    const a = encoder.encode(left);
+    const b = encoder.encode(right);
+    if (a.length !== b.length)
+        return false;
+    let result = 0;
+    for (let index = 0; index < a.length; index += 1) {
+        result |= (a[index] ?? 0) ^ (b[index] ?? 0);
+    }
+    return result === 0;
+}
+export function jsonSchemaObject(schema) {
+    return schema;
+}
+//# sourceMappingURL=agent.js.map