@raybase/core 0.0.2 → 0.3.3

package/dist/agent.d.ts

@@ -0,0 +1,1780 @@
+import { type Tool } from "ai";
+import { type RaybaseAction, type RaybaseActionContext, type RaybaseAgentActionRegistration } from "./actions.js";
+import type { RaybaseAuditContextEvent } from "./audit.js";
+import { type RaybaseAgentSkillRegistration, type RaybaseAgentSkillSummary } from "./agent-skills.js";
+import { type RaybaseAgentRemoteMcpBinding, type RaybaseAgentRemoteMcpBindingSummary, type RaybaseRemoteMcpServer } from "./agent-remote-mcp.js";
+import { type RaybaseAgentMemoryConfig, type RaybaseAgentMemoryServerRuntime, type RaybaseAgentMemorySpaceSummary } from "./agent-memory.js";
+import { type RaybaseAgentSkillStoreConfig } from "./agent-skill-store.js";
+import { type RaybaseAgentWakeOptions, type RaybaseAgentWakeResult, type RaybaseAgentWakesConfig } from "./agent-wakes.js";
+import { type RaybaseAgentFollowUpsConfig, type RaybaseAgentFollowUpsRuntime } from "./agent-follow-ups.js";
+import type { RaybaseAgentMessageAttachment } from "./agent-message-parts.js";
+import { type RaybaseAgentRoomEligibility, type RaybaseAgentRoomEligibilityMessage, type RaybaseAgentRoomMemberRow, type RaybaseAgentRoomMemberSummary, type RaybaseAgentRoomsConfig } from "./agent-rooms.js";
+import { type AgentChapterSynopsis, type RaybaseAgentRetentionConfig } from "./agent-chapters.js";
+import { type NormalizedRaybaseAgentConversationVoiceNotesConfig, type RaybaseAgentConversationVoiceNotesConfig } from "./agent-voice-notes.js";
+import { type RaybaseAgentUserDataPartsConfig } from "./agent-user-data-parts.js";
+export { isAgentUserDataPartType, isReservedAgentDataPartType, maxAgentUserDataBytesPerMessage, maxAgentUserDataPartBytes, maxAgentUserDataPartsPerMessage, type RaybaseAgentUserDataPartDefinition, type RaybaseAgentUserDataPartsConfig } from "./agent-user-data-parts.js";
+import { type RaybaseStorageConfig } from "./storage.js";
+import { type RaybaseAI, type RaybaseAgentCommitAI, type RaybaseAIModelParams, type RaybaseAIProviderParams, type RaybaseChatResponseFormat, type RaybaseAgentPrincipal } from "./ai.js";
+import type { RaybaseActionDataClient, RaybaseDataClient } from "./data-client.js";
+import type { DoMigration, SqlExecutor } from "./db.js";
+import type { RaybaseAgentDataPart } from "./agent-data-parts.js";
+import { type JsonSchemaObject } from "./json-schema.js";
+import type { RaybaseNotificationsRuntime } from "./notifications.js";
+import type { RaybaseUser } from "./policies.js";
+import { type RaybaseJobsRuntime } from "./jobs.js";
+import { type RaybaseConfig, type RaybaseSchema, type RaybaseSystemTable } from "./schema.js";
+import { type RaybaseRuntimeSettings, type RaybaseSettingsDefinitions } from "./settings.js";
+import { type SqlValue } from "./sql.js";
+export type { RaybaseAgentRoomAuthor, RaybaseAgentRoomAuthorKind, RaybaseAgentRoomCommitHookContext, RaybaseAgentRoomMembershipHookContext, RaybaseAgentRoomMemberRow, RaybaseAgentRoomMemberSummary, RaybaseAgentRoomsConfig } from "./agent-rooms.js";
+export type RaybaseAgentRuntime = "ai-chat";
+export type RaybaseAgentTrigger = {
+    type: "chat";
+} | {
+    type: "schedule";
+    cron: string;
+    timezone?: string;
+    input?: unknown;
+    enabled?: boolean;
+    userMessage?: string;
+    /** Core-owned marker synthesized from memory.maintenance. */
+    maintenance?: string;
+} | {
+    type: "data";
+    event: `${string}.create` | `${string}.update` | `${string}.delete`;
+    includeAdmin?: boolean;
+    input?: unknown;
+};
+export type RaybaseAgentTriggerType = RaybaseAgentTrigger["type"];
+export type RaybaseAgentExecutionTriggerType = RaybaseAgentTriggerType | "direct" | "wake" | "follow-up" | "composed";
+export type RaybaseAgentAudienceKind = "signed-in" | "public";
+export type RaybaseAgentAudience = RaybaseAgentAudienceKind | RaybaseAgentAudienceKind[] | Record<string, RaybaseAgentAudienceKind | RaybaseAgentAudienceKind[] | undefined>;
+export type RaybaseAgentEntrySource = "inline" | "notification";
+export type RaybaseAgentEntryDefinition = {
+    description: string;
+    payloadSchema?: JsonSchemaObject;
+    source?: RaybaseAgentEntrySource;
+    userMessage?: string;
+    audience?: RaybaseAgentAudienceKind[];
+};
+export type RaybaseAgentEntryNotificationSnapshot = {
+    id: string;
+    kind: string | null;
+    title: string;
+    body: string | null;
+    metadata: unknown;
+    target?: {
+        href?: string;
+        entity?: {
+            type: string;
+            id: string;
+        };
+    };
+    createdAt: string;
+};
+export type RaybaseAgentEntrySnapshot = {
+    kind: string;
+    source: RaybaseAgentEntrySource;
+    payload?: unknown;
+    notification?: RaybaseAgentEntryNotificationSnapshot;
+};
+export type RaybaseAgentLimits = {
+    maxInputChars?: number;
+    maxOutputTokens?: number;
+    maxToolCallsPerTurn?: number;
+    maxLoopStepsPerTurn?: number;
+    maxConversationMessages?: number;
+    /**
+     * Input characters the turn pre-flight holds back for the tool loop to
+     * spend. Unset means derived: maxToolCallsPerTurn multiplied by the largest
+     * result cap among the tools actually offered on the turn, clamped to a
+     * share of the room the assembly's floor leaves. Set it only to override a
+     * derivation that does not match a specific app's tools.
+     */
+    loopReserveChars?: number;
+    /** Receive-only conversation subscriptions. Clamped to the platform cap of 64. Default 16. */
+    maxConversationSockets?: number;
+    publicIpHourlyRequests?: number;
+    publicIpHourlyOutputTokens?: number;
+    publicDailyRequests?: number;
+    publicDailyOutputTokens?: number;
+    signedInDailyRequests?: number;
+    /**
+     * Model-composed turns per conversation and rolling day. Unset means
+     * unlimited: the runtime already runs one turn at a time per conversation
+     * and bounds loop steps per turn, so a daily quota is a slow, invisible
+     * guard rather than a loop stop. Set it only when an app wants the cap.
+     */
+    composedPerDay?: number;
+    /**
+     * Agent entry kickoff turns per signed-in user and rolling day. Unset means
+     * unlimited, on the same reasoning as composedPerDay.
+     */
+    entryKickoffPerDay?: number;
+};
+export type RaybaseAgentCompaction = {
+    /** Compact old history into a persisted synopsis when the assembled prompt nears maxInputChars. Default true. */
+    enabled?: boolean;
+    /** Model for the synopsis summarization call. Defaults to the agent's resolved model. */
+    model?: string;
+    /** Newest conversation messages kept verbatim when compacting. Default 8. */
+    keepRecentMessages?: number;
+    /**
+     * Fraction of the compactable budget at which compaction triggers.
+     * Default 0.7.
+     *
+     * The denominator is `maxInputChars` minus the assembly's floor — the system
+     * prompt, synopsis, sentinels, and tool schemas that compaction cannot
+     * reach — so the ratio means "the history has used this share of the room
+     * the history has". Measured against the whole cap, an agent whose floor
+     * already exceeds the ratio would trip the trigger on every turn and never
+     * get back under it.
+     */
+    triggerRatio?: number;
+    /**
+     * Floor of the summary output-token budget. Default 800 — the old flat
+     * budget, so no span ever gets a smaller summary than it did before the
+     * budget became proportional.
+     */
+    minSummaryOutputTokens?: number;
+    /**
+     * Fraction of the closed span's estimated tokens (chars/4) granted to the
+     * summary. Default 0.12. The budget for one summarization call is
+     * clamp(minSummaryOutputTokens, round(summarySpanRatio × spanTokens),
+     * maxSummaryOutputTokens) — see `agentSummaryBudgetTokens`.
+     */
+    summarySpanRatio?: number;
+    /**
+     * Ceiling of the summary output-token budget. Default 4,000. A ceiling is
+     * still wanted: summaries ride every later prompt and are re-summarized at
+     * subsequent closes, so unbounded growth compounds. Pinning this alone pins
+     * the whole budget whenever it sits at or below the floor — the clamp
+     * collapses onto the pin, which is exactly the pre-proportional behavior.
+     */
+    maxSummaryOutputTokens?: number;
+};
+export type RaybaseAgentHookFailure = "fail-turn" | "continue-empty";
+export type RaybaseAgentRetrievalReader = {
+    search(indexName: string, query: string, options?: {
+        topK?: number;
+        minScore?: number;
+    }): Promise<unknown[]>;
+};
+export declare const defaultAgentCompaction: Required<Omit<RaybaseAgentCompaction, "model">>;
+export type RaybaseAgentPromptContext<Env = unknown, Schema extends RaybaseSchema = RaybaseSchema> = {
+    request: Request;
+    env: Env;
+    config: RaybaseConfig;
+    schema: Schema;
+    appMigrations?: DoMigration[];
+    agent: RaybaseAgent<Env, Schema>;
+    principal: RaybaseAgentPrincipal;
+    user?: RaybaseUser;
+    organizationId?: string | null;
+    route: string;
+    surface: string;
+    conversationId: string;
+    trigger?: {
+        type: RaybaseAgentExecutionTriggerType;
+        event?: string;
+        input?: unknown;
+        data?: Record<string, unknown>;
+        userMessage?: string | null;
+        entry?: RaybaseAgentEntrySnapshot;
+    };
+    /** Present only for a declared memory-maintenance run. */
+    maintenance?: {
+        run: string;
+    };
+    chapters?: {
+        lastClosed: {
+            id: string;
+            ordinal: number;
+            endedAt: string;
+        } | null;
+        currentOrdinal: number;
+    };
+    userMessage?: string;
+    /**
+     * The agent run that owns this turn, and the same value agent-lane actions
+     * read as `ctx.runId`. Stable across delivery-gate retries and replacements
+     * within one turn, and fresh for every run. `null` only where the
+     * invocation has no durable run row, which today means the admin prompt
+     * preview.
+     *
+     * Server-side context: it is never rendered into the model-visible prompt
+     * and the model is never asked to echo it. Apps that need idempotent
+     * per-turn side effects build keys as `turn:<runId>:<ordinal>`.
+     */
+    runId: string | null;
+    /** Immutable app-defined state loaded once for this turn before prompt assembly. */
+    turnState: Readonly<Record<string, unknown>>;
+    /** System-attributed inference lane for assembly-time app judgment. */
+    ai: RaybaseAI;
+};
+export type RaybaseAgentTurnStateLoadContext<Env = unknown, Schema extends RaybaseSchema = RaybaseSchema> = Omit<RaybaseAgentPromptContext<Env, Schema>, "turnState"> & {
+    /**
+     * Structured facts for the arriving member message's attachments, in part
+     * order and identical to what the eligibility hook is handed for the same
+     * message. Present exactly when a member message arrives: a composed or
+     * wake turn carries the app's instruction in `userMessage` and no member
+     * parts to describe, so it carries neither this nor `userMessageBodyText`.
+     */
+    userMessageAttachments?: RaybaseAgentMessageAttachment[];
+    /**
+     * What the member actually wrote — the text parts alone, matching the
+     * eligibility message's `bodyText`. `userMessage` keeps the flattened
+     * form with Core's `[image …]` stand-in, so a loader that wants the words
+     * need not parse the stand-in back out of it.
+     */
+    userMessageBodyText?: string;
+    data: RaybaseDataClient<Schema>;
+    /** Present only when turnState.servicePrincipals declares at least one name. */
+    dataAsService?(name: string): RaybaseDataClient<Schema>;
+    settings?: RaybaseRuntimeSettings<Env, RaybaseSettingsDefinitions<Env>>;
+    retrieval: RaybaseAgentRetrievalReader;
+    /** Bounded terminal-run summaries for this invocation's conversation only. */
+    runs: RaybaseAgentRunHistoryReader;
+    /**
+     * Live attributed tail for the conversation Core bound to this turn.
+     * Absent for invocations that have no live conversation transcript.
+     */
+    transcript?: RaybaseAgentActiveTranscriptReader;
+    /**
+     * Direct turns only. Room turns deliberately do not receive this handle,
+     * so private history cannot flow into a shared room transcript.
+     */
+    conversations?: {
+        read(conversationId: string, options?: {
+            limit?: number;
+            before?: string;
+        }): Promise<RaybaseAgentAttributedTranscriptSlice>;
+    };
+};
+export type RaybaseAgentDescribeContext<Env = unknown, Schema extends RaybaseSchema = RaybaseSchema> = Omit<RaybaseAgentPromptContext<Env, Schema>, "agent"> & {
+    agent: Pick<RaybaseAgent<Env, Schema>, "name" | "title" | "description" | "runtime">;
+    data: RaybaseDataClient<Schema>;
+    settings?: RaybaseRuntimeSettings<Env, RaybaseSettingsDefinitions<Env>>;
+};
+type RaybaseAgentDescribeContextHook<Env, Schema extends RaybaseSchema> = {
+    bivarianceHack(ctx: RaybaseAgentDescribeContext<Env, Schema>): unknown | Promise<unknown>;
+}["bivarianceHack"];
+export type RaybaseAgentTurnState<Env = unknown, Schema extends RaybaseSchema = RaybaseSchema> = {
+    load(ctx: RaybaseAgentTurnStateLoadContext<Env, Schema>): Record<string, unknown> | Promise<Record<string, unknown>>;
+    /** Core aborts cooperative work at this deadline. Default 10 seconds. */
+    timeoutMs?: number;
+    /** Default fail-turn. */
+    onFailure?: RaybaseAgentHookFailure;
+    /**
+     * Exact named table-policy principals the loader may opt into through
+     * dataAsService(name). Undeclared names fail closed.
+     */
+    servicePrincipals?: string[];
+};
+export type RaybaseAgentPromptBandEpoch = "chapter" | "turn";
+/** Default cap for custom prompt bands. The built-in head has no default cap. */
+export declare const defaultAgentPromptBandMaxChars = 16000;
+export type RaybaseAgentPromptHead = {
+    /** Controls when the built-in prompt head content is recomputed. Default chapter. */
+    epoch: RaybaseAgentPromptBandEpoch;
+    /**
+     * Opt-in cap on the built-in prompt head. Undeclared leaves the head
+     * uncapped at the band level; the whole assembled turn is still bounded by
+     * `ai.defaults.maxInputChars`.
+     */
+    maxChars?: number;
+    /**
+     * Overflow behavior once `maxChars` is declared. Default error: opting into
+     * a cap opts into a loud failure, never a silent trim.
+     */
+    onOverflow?: "truncate" | "error";
+};
+export type RaybaseAgentPromptBand<Env = unknown, Schema extends RaybaseSchema = RaybaseSchema> = {
+    name: string;
+    render(ctx: RaybaseAgentPromptContext<Env, Schema>): string | null | undefined | Promise<string | null | undefined>;
+    when?(ctx: RaybaseAgentPromptContext<Env, Schema>): boolean | Promise<boolean>;
+    /** Content is frozen for the current chapter unless explicitly made per-turn. Default chapter. */
+    epoch?: RaybaseAgentPromptBandEpoch;
+    /** Default 16,000 characters. */
+    maxChars?: number;
+    /** Default truncate. */
+    onOverflow?: "truncate" | "error";
+};
+export type RaybaseAgentSentinel<Env = unknown, Schema extends RaybaseSchema = RaybaseSchema> = {
+    name: string;
+    render(ctx: RaybaseAgentPromptContext<Env, Schema>): string | null | undefined | Promise<string | null | undefined>;
+    when?(ctx: RaybaseAgentPromptContext<Env, Schema>): boolean | Promise<boolean>;
+    maxChars?: number;
+    onOverflow?: "truncate" | "error";
+    /** App instructions are authoritative steering; data remains untrusted context. Default data. */
+    trust?: "app" | "data";
+};
+export type RaybaseAgentDeliveryMode = "stream" | "buffered";
+export declare const defaultAgentDeliveryMaxReplacementChars = 32000;
+export declare const maxAgentDeliveryReplacementChars = 128000;
+export type RaybaseAgentGateVerdict = {
+    verdict: "deliver";
+} | {
+    verdict: "retry";
+    note: string;
+} | {
+    verdict: "replace";
+    text: string;
+} | {
+    verdict: "drop";
+    silence?: string;
+};
+export type RaybaseAgentComposedTurnOrigin = {
+    type: "action" | "job" | "wake" | "follow-up" | "reaction";
+    id: string;
+};
+export type RaybaseAgentComposedRequest = {
+    requestKey: string;
+    origin: RaybaseAgentComposedTurnOrigin;
+};
+export type RaybaseAgentGateContext<Env = unknown, Schema extends RaybaseSchema = RaybaseSchema> = RaybaseAgentPromptContext<Env, Schema> & {
+    /**
+     * Live attributed tail for the conversation Core bound to this turn.
+     * Absent for invocations that have no live conversation transcript.
+     */
+    transcript?: RaybaseAgentActiveTranscriptReader;
+    attempt: number;
+    maxRetries: number;
+    /** Messages persisted after the immutable draft snapshot was captured. */
+    transcriptGrewBy: number;
+};
+/**
+ * A reply the app has taught its model to give when it has nothing to say.
+ *
+ * A buffered gate can read a whole draft and turn such a reply into a labeled
+ * silence; a streaming turn has no gate, so without this the word itself
+ * would stream to every subscriber and persist as the reply. With it, Core
+ * holds back the leading characters of a streamed turn while they can still
+ * be the sentinel, releases them the moment they diverge, and — when the
+ * whole reply is exactly the sentinel — commits no message and reports the
+ * silence as `sentinel:<silence>`. A buffered turn is not affected: its gate
+ * still sees the draft as the model wrote it.
+ */
+export type RaybaseAgentSilenceSentinel = {
+    /** The exact reply text, compared after trimming. Trimmed, 1–64 characters. */
+    text: string;
+    /** The silence label, reported as `sentinel:<silence>`; trimmed, 1–64 characters. */
+    silence: string;
+};
+export type RaybaseAgentDelivery<Env = unknown, Schema extends RaybaseSchema = RaybaseSchema> = {
+    mode?(ctx: RaybaseAgentPromptContext<Env, Schema>): RaybaseAgentDeliveryMode | Promise<RaybaseAgentDeliveryMode>;
+    /** Gates assistant text only; drafting-attempt tool effects are already committed. */
+    gate?(draft: string, ctx: RaybaseAgentGateContext<Env, Schema>): RaybaseAgentGateVerdict | Promise<RaybaseAgentGateVerdict>;
+    /** Streamed turns only: a reply that is exactly this text is a labeled silence, and its characters never stream. */
+    silenceSentinel?: RaybaseAgentSilenceSentinel;
+    maxRetries?: number;
+    /** Maximum accepted replacement text. Default 32,000; hard maximum 128,000 characters. */
+    maxReplacementChars?: number;
+    fallback?: "deliver" | "drop";
+    timeoutMs?: number;
+    onFailure?: RaybaseAgentHookFailure;
+};
+export type RaybaseAgentChapterClose = {
+    /** Overrides the stock chapter-close system prompt. */
+    prompt?: string;
+};
+export type RaybaseAgentRuntimeControl = {
+    configurable?: boolean;
+    defaultEnabled?: boolean;
+};
+export type RaybaseAgentPromptVariable = {
+    path: string;
+    description: string;
+    example?: unknown;
+    source?: "raybase" | "trigger" | "agent";
+};
+export type RaybaseAgentPrompt<Env = unknown, Schema extends RaybaseSchema = RaybaseSchema> = {
+    default: string;
+    configurable?: boolean;
+    renderer?: "liquid";
+    variables?: RaybaseAgentPromptVariable[];
+    context?: (ctx: RaybaseAgentPromptContext<Env, Schema>) => Record<string, unknown> | Promise<Record<string, unknown>>;
+};
+export type RaybaseAgentConversationTitles = "auto" | {
+    model?: string;
+};
+export type RaybaseAgentConversationCommitHookContext<Env = unknown> = {
+    env: Env;
+    ai: RaybaseAgentCommitAI;
+    agents: RaybaseAgentInvocationRuntime;
+    jobs: RaybaseJobsRuntime;
+    notifications: RaybaseNotificationsRuntime<Env>;
+    audit(event: RaybaseAuditContextEvent): Promise<void>;
+    /**
+     * The run that committed these messages — the same id this turn's prompt,
+     * skill, eligibility, delivery, and action contexts saw.
+     */
+    runId: string;
+    conversation: {
+        agentName: string;
+        conversationId: string;
+        kind: "room" | null;
+        requestKey: string | null;
+        composedOrigin: RaybaseAgentComposedTurnOrigin | null;
+        composedRequests: RaybaseAgentComposedRequest[];
+        messageId: string;
+        /**
+         * Every message this run committed, `messageId` first. Enough, with
+         * `runId`, to attach run-scoped state to committed messages without
+         * scanning recent rows.
+         */
+        messageIds: string[];
+        text: string;
+        triggeredByUserId: string | null;
+        connectedUserIds: string[];
+        memberUserIds: string[];
+    };
+};
+export type RaybaseAgentConversationSilenceHookContext<Env = unknown> = {
+    env: Env;
+    agents: RaybaseAgentInvocationRuntime;
+    jobs: RaybaseJobsRuntime;
+    notifications: RaybaseNotificationsRuntime<Env>;
+    audit(event: RaybaseAuditContextEvent): Promise<void>;
+    runId: string;
+    silenceKind: string;
+    conversation: {
+        agentName: string;
+        conversationId: string;
+        kind: "room" | null;
+        requestKey: string | null;
+        composedOrigin: RaybaseAgentComposedTurnOrigin | null;
+        composedRequests: RaybaseAgentComposedRequest[];
+        triggeredByUserId: string | null;
+    };
+};
+export type RaybaseAgentConversationReadHookContext<Env = unknown> = {
+    env: Env;
+    agents: RaybaseAgentInvocationRuntime;
+    notifications: RaybaseNotificationsRuntime<Env>;
+    audit(event: RaybaseAuditContextEvent): Promise<void>;
+    conversation: {
+        agentName: string;
+        conversationId: string;
+        userId: string;
+        lastReadAt: string;
+        newlySeenMessageIds: string[];
+    };
+};
+/**
+ * The app's server-side wire into sequenced conversation message mutations.
+ * Edit and removal are the only variants that expose prior content; reaction
+ * mutations lose no message content and instead carry their post-mutation map.
+ */
+export type RaybaseAgentConversationMessageMutation = {
+    type: "message.updated" | "message.removed";
+    messageId: string;
+    at: string;
+    previous: Record<string, unknown>;
+    message: Record<string, unknown>;
+} | {
+    type: "message.reaction";
+    messageId: string;
+    at: string;
+    /** The signed-in user id, or `agent:<name>` for the built-in reaction tool. */
+    userId: string;
+    /** `null` means that the actor cleared their reaction. */
+    emoji: string | null;
+    /** Post-mutation reaction map, keyed by user or agent reaction identity. */
+    reactions: Record<string, string>;
+    message: Record<string, unknown>;
+};
+type RaybaseAgentConversationMessageMutationHookContextBase<Env> = {
+    env: Env;
+    notifications: RaybaseNotificationsRuntime<Env>;
+    audit(event: RaybaseAuditContextEvent): Promise<void>;
+    conversation: {
+        agentName: string;
+        conversationId: string;
+        kind: "room" | null;
+        actorUserId: string | null;
+    };
+};
+/**
+ * Runs inline on the mutation request and is bounded. Reaction hooks receive
+ * an invocation runtime because they always have a user or service actor;
+ * edit and removal hooks remain capture-only and runtime-free.
+ */
+export type RaybaseAgentConversationMessageMutationHookContext<Env = unknown> = (RaybaseAgentConversationMessageMutationHookContextBase<Env> & {
+    agents: RaybaseAgentInvocationRuntime;
+    mutation: Extract<RaybaseAgentConversationMessageMutation, {
+        type: "message.reaction";
+    }>;
+}) | (RaybaseAgentConversationMessageMutationHookContextBase<Env> & {
+    agents?: never;
+    mutation: Extract<RaybaseAgentConversationMessageMutation, {
+        type: "message.updated" | "message.removed";
+    }>;
+});
+/**
+ * A user, app, or agent utterance suitable for app turn assembly. Raybase
+ * framework turn-error notices remain in the user-visible conversation but
+ * are omitted from this attributed projection.
+ */
+export type RaybaseAgentAttributedTranscriptMessage = {
+    id: string;
+    createdAt: string;
+    role: "user" | "assistant";
+    author: {
+        kind: "user" | "agent" | "app";
+        userId: string | null;
+        name: string | null;
+    };
+    text: string;
+    /**
+     * Attachment identity for this utterance; empty when it carried none.
+     * `text` still reads the attachment as its stand-in, so a reader that only
+     * puts the line in a prompt is unaffected.
+     */
+    attachments: RaybaseAgentMessageAttachment[];
+};
+/** A cursor-paginated slice of eligible attributed conversation utterances. */
+export type RaybaseAgentAttributedTranscriptSlice = {
+    conversationId: string;
+    messages: RaybaseAgentAttributedTranscriptMessage[];
+    nextBefore: string | null;
+};
+/**
+ * Reads the attributed transcript for the conversation Core bound to the
+ * current invocation. The active conversation is intentionally not caller
+ * selectable.
+ */
+export type RaybaseAgentActiveTranscriptReader = {
+    read(options?: {
+        limit?: number;
+        before?: string;
+    }): Promise<RaybaseAgentAttributedTranscriptSlice>;
+};
+export type RaybaseAgentConversationReadState = {
+    conversationId: string;
+    members: Array<{
+        userId: string;
+        lastReadAt: string | null;
+    }>;
+    messages: Array<{
+        messageId: string;
+        seen: Record<string, string>;
+    }>;
+};
+export type RaybaseAgentConversationMessagesConfig = {
+    edit?: {
+        windowMs: number;
+    };
+    remove?: {
+        windowMs: number;
+    };
+    reactions?: {
+        enabled: true;
+        agentTool?: boolean;
+    };
+    attachments?: RaybaseAgentConversationAttachmentsConfig;
+    voiceNotes?: RaybaseAgentConversationVoiceNotesConfig;
+    userDataParts?: RaybaseAgentUserDataPartsConfig;
+};
+export type RaybaseAgentConversationAttachmentsConfig = {
+    enabled: true;
+    bucket: string;
+    maxPerMessage?: number;
+    maxBytesPerFile?: number;
+    mediaTypes?: string[];
+    resolveForModel?: {
+        recentMessages?: number;
+    };
+};
+export type NormalizedRaybaseAgentConversationAttachmentsConfig = {
+    enabled: true;
+    bucket: string;
+    maxPerMessage: number;
+    maxBytesPerFile: number;
+    mediaTypes: string[];
+    resolveForModel: {
+        recentMessages: number;
+    };
+};
+export declare const defaultAgentAttachmentMediaTypes: readonly ["image/jpeg", "image/png", "image/webp", "image/gif"];
+export declare const defaultAgentAttachmentMaxPerMessage = 4;
+export declare const defaultAgentAttachmentMaxBytesPerFile: number;
+export declare const defaultAgentAttachmentRecentMessages = 8;
+export type RaybaseAgentConversationsConfig<Env = unknown, Schema extends RaybaseSchema = RaybaseSchema> = {
+    eligibility?(ctx: RaybaseAgentPromptContext<Env, Schema>, message: RaybaseAgentRoomEligibilityMessage): RaybaseAgentRoomEligibility | Promise<RaybaseAgentRoomEligibility>;
+    eligibilityTimeoutMs?: number;
+    /** Defaults to continue-empty, which degrades a failed hook to respond. */
+    onEligibilityFailure?: RaybaseAgentHookFailure;
+    onCommit?(ctx: RaybaseAgentConversationCommitHookContext<Env>): void | Promise<void>;
+    onSilence?(ctx: RaybaseAgentConversationSilenceHookContext<Env>): void | Promise<void>;
+    onRead?(ctx: RaybaseAgentConversationReadHookContext<Env>): void | Promise<void>;
+    /**
+     * Server-side seam for message edits, removals, and reactions. Fires once
+     * per sequenced mutation. Prior edit/removal content is delivered only here;
+     * reactions additionally receive `ctx.agents` but never start a turn alone.
+     */
+    onMessageMutation?(ctx: RaybaseAgentConversationMessageMutationHookContext<Env>): void | Promise<void>;
+    messages?: RaybaseAgentConversationMessagesConfig;
+};
+export type RaybaseAgentComposeConfig = {
+    /**
+     * Whether a composed turn's `context` is rendered for the model as a
+     * `composed-context` data sentinel. Defaults to true: the context is
+     * otherwise only merged into turn state, where nothing shows it to the
+     * model. Set false when the agent renders those facts itself.
+     */
+    renderContext?: boolean;
+};
+export type RaybaseAgent<Env = unknown, Schema extends RaybaseSchema = RaybaseSchema> = {
+    name: string;
+    title?: string;
+    description?: string;
+    runtime: RaybaseAgentRuntime;
+    triggers: RaybaseAgentTrigger[];
+    audience?: RaybaseAgentAudience;
+    /**
+     * Capability labels this agent carries into every action it invokes,
+     * surfaced as `ctx.principal.scopes` on the agent principal. Raybase does
+     * not interpret them; an action checks them with `agentPrincipalHasScope`
+     * to refuse or allow agent-driven calls by name.
+     */
+    scopes?: string[];
+    model?: string;
+    modelParams?: RaybaseAIModelParams;
+    responseFormat?: RaybaseChatResponseFormat;
+    providerParams?: RaybaseAIProviderParams;
+    system?: string | ((ctx: RaybaseAgentPromptContext<Env, Schema>) => string | Promise<string>);
+    prompt?: RaybaseAgentPrompt<Env, Schema>;
+    turnState?: RaybaseAgentTurnState<Env, Schema>;
+    /** Loads app-defined data once when building the model-facing action toolset. */
+    describeContext?: RaybaseAgentDescribeContextHook<Env, Schema>;
+    promptHead?: RaybaseAgentPromptHead;
+    promptBands?: RaybaseAgentPromptBand<Env, Schema>[];
+    sentinels?: RaybaseAgentSentinel<Env, Schema>[];
+    /**
+     * Whether Core renders its `time` sentinel as the final block of the
+     * ephemeral system message — one clock line in the principal's zone, or one
+     * per member in room turns. Defaults to true. Set false when the agent
+     * renders its own clock, so the prompt does not carry two.
+     */
+    timeSentinel?: boolean;
+    compose?: RaybaseAgentComposeConfig;
+    delivery?: RaybaseAgentDelivery<Env, Schema>;
+    conversations?: RaybaseAgentConversationsConfig<Env, Schema>;
+    conversationTitles?: RaybaseAgentConversationTitles;
+    runtimeControl?: RaybaseAgentRuntimeControl;
+    /**
+     * Direct actions registered on this agent. Each entry is a bare action, or
+     * a binding with `offerWhen` and/or `disclosure`. `offerWhen` gates the
+     * model-facing tool per turn; `disclosure` chooses its full schema or a
+     * callable stub that fetches the full schema before execution. Function
+     * forms are synchronous and deterministic — they read the same per-turn
+     * context prompt band `when` predicates receive and must not do I/O.
+     * Presentation never affects registration, other surfaces, permission
+     * checks, admin listings, or tool-name uniqueness.
+     */
+    actions?: RaybaseAgentActionRegistration<Env, Schema>[];
+    skills?: RaybaseAgentSkillRegistration<Env, Schema>[];
+    skillStore?: RaybaseAgentSkillStoreConfig<Env, Schema>;
+    remoteMcpServers?: Array<RaybaseRemoteMcpServer | RaybaseAgentRemoteMcpBinding>;
+    memory?: RaybaseAgentMemoryConfig;
+    wakes?: RaybaseAgentWakesConfig;
+    followUps?: RaybaseAgentFollowUpsConfig<Env, Schema>;
+    rooms?: RaybaseAgentRoomsConfig<Env, Schema>;
+    entries?: Record<string, RaybaseAgentEntryDefinition>;
+    limits?: RaybaseAgentLimits;
+    compaction?: RaybaseAgentCompaction;
+    chapterClose?: RaybaseAgentChapterClose;
+    retention?: RaybaseAgentRetentionConfig;
+    owner?: {
+        moduleId?: string;
+        packageName?: string;
+    };
+};
+export type RaybaseAgentDefinition<Env = unknown, Schema extends RaybaseSchema = RaybaseSchema> = Omit<RaybaseAgent<Env, Schema>, "triggers"> & {
+    triggers?: RaybaseAgentTrigger[];
+};
+export type RaybaseAgentCollectionDefinition<Env = unknown, Schema extends RaybaseSchema = RaybaseSchema> = Omit<RaybaseAgent<Env, Schema>, "name" | "triggers"> & {
+    name?: string;
+    triggers?: RaybaseAgentTrigger[];
+};
+export type RaybaseAgents<Env = unknown, Schema extends RaybaseSchema = RaybaseSchema> = Record<string, RaybaseAgent<Env, Schema>>;
+export type RaybaseAgentDefinitions<Env = unknown, Schema extends RaybaseSchema = RaybaseSchema> = Record<string, RaybaseAgent<Env, Schema> | RaybaseAgentCollectionDefinition<Env, Schema>>;
+export type RaybaseAgentRuntimeHarness = {
+    runtime: "ai-chat";
+    durableObjectBinding: "RAYBASE_AI_CHAT_AGENT";
+    triggerType: RaybaseAgentTriggerType;
+    instanceStrategy: "conversation";
+};
+export declare const raybaseAiChatHarness: RaybaseAgentRuntimeHarness;
+export declare const raybaseAgentInternalReadPath = "/__raybase_agent_read";
+export declare const raybaseAgentInternalUserReadPath = "/__raybase_agent_user_read";
+export declare const raybaseAgentInternalCleanupPath = "/__raybase_agent_cleanup";
+export declare const raybaseAgentInternalUserPurgePath = "/__raybase_agent_user_purge";
+export declare const raybaseAgentInternalRehydratePath = "/__raybase_agent_rehydrate";
+export declare const raybaseAgentInternalRoomNoticePath = "/__raybase_agent_room_notice";
+export declare const raybaseAgentInternalRoomActivityPath = "/__raybase_agent_room_activity";
+export declare const raybaseAgentInternalRoomMembershipPath = "/__raybase_agent_room_membership";
+export declare const raybaseAgentInternalRoomRedactPath = "/__raybase_agent_room_redact";
+export declare const raybaseAgentSystemTables: RaybaseSystemTable[];
+export type RaybaseAgentInstanceStatus = "active" | "cleanupRequested" | "deleting" | "cleanupError" | "deleted" | "archived";
+export type RaybaseAgentRunStatus = "queued" | "running" | "completed" | "cancelled" | "failed" | "skipped";
+export type RaybaseAgentInstanceRow = {
+    id: string;
+    conversationId: string;
+    agentName: string;
+    agentTitle: string;
+    agentOwner: string | null;
+    moduleId: string | null;
+    runtime: RaybaseAgentRuntime;
+    triggerType: RaybaseAgentTriggerType;
+    instanceKey: string;
+    principalKind: "user" | "public";
+    userId: string | null;
+    publicScopeHash: string | null;
+    organizationId: string | null;
+    route: string | null;
+    surface: string;
+    status: RaybaseAgentInstanceStatus;
+    cleanupRequestedAt: string | null;
+    hotStorageDeletedAt: string | null;
+    deletedAt: string | null;
+    retentionReason: string | null;
+    pinnedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+    lastActiveAt: string;
+    expiresAt: string | null;
+    lastRunId: string | null;
+    lastError: string | null;
+    metadataJson: string | null;
+    entryKind: string | null;
+    entryJson: string | null;
+    kind?: "room" | null;
+    roomMembershipRev?: number | null;
+    lastReadAt?: string | null;
+};
+export type RaybaseAgentConversationSummary = {
+    agentName: string;
+    conversationId: string;
+    runtime: RaybaseAgentRuntime;
+    triggerType: "chat";
+    title: string | null;
+    agentTitle: string;
+    route: string | null;
+    surface: string;
+    status: RaybaseAgentInstanceStatus;
+    createdAt: string;
+    updatedAt: string;
+    lastActiveAt: string;
+    expiresAt: string | null;
+    pinnedAt: string | null;
+    archived: boolean;
+    lastRunId: string | null;
+    lastRunStatus: RaybaseAgentRunStatus | null;
+    entryKind: string | null;
+    kind: "room" | null;
+    lastReadAt: string | null;
+};
+export type RaybaseAgentRunRow = {
+    runId: string;
+    conversationId: string;
+    agentName: string;
+    requestId: string;
+    triggerType: RaybaseAgentExecutionTriggerType;
+    inputMessageId: string | null;
+    status: RaybaseAgentRunStatus;
+    startedAt: string;
+    /** Last known progress. Null on rows written before the column existed. */
+    heartbeatAt: string | null;
+    finishedAt: string | null;
+    error: string | null;
+    usageEventId: string | null;
+    auditEventId: string | null;
+    metadataJson: string | null;
+};
+export declare const defaultAgentRunHistoryLimit = 20;
+export declare const maxAgentRunHistoryLimit = 100;
+export type RaybaseAgentRunDeliveryEvidence = {
+    verdict: "deliver" | "drop";
+    retries: number;
+    replaced?: true;
+    silence?: string;
+};
+export type RaybaseAgentTerminalRunStatus = Exclude<RaybaseAgentRunStatus, "queued" | "running">;
+export type RaybaseAgentRunSummary = {
+    runId: string;
+    triggerType: RaybaseAgentExecutionTriggerType;
+    status: RaybaseAgentTerminalRunStatus;
+    startedAt: string;
+    finishedAt: string;
+    delivery?: RaybaseAgentRunDeliveryEvidence;
+};
+export type RaybaseAgentRunHistoryOptions = {
+    /** Inclusive lower bound. */
+    finishedAfter?: string;
+    /** Exclusive upper bound. */
+    finishedBefore?: string;
+    /** Default 20; maximum 100. */
+    limit?: number;
+};
+export type RaybaseAgentRunHistoryReader = {
+    recent(options?: RaybaseAgentRunHistoryOptions): Promise<ReadonlyArray<Readonly<RaybaseAgentRunSummary>>>;
+};
+export type RaybaseAgentInvocationRunHistoryReader = {
+    /**
+     * Bounded terminal-run summaries for one exact registered-agent conversation.
+     * A registered agent paired with another agent's conversation returns no rows.
+     * A commit hook observes every terminal row present at query time, including
+     * the run whose commit hook is executing because Core finalizes it first.
+     */
+    recent(agentName: string, conversationId: string, options?: RaybaseAgentRunHistoryOptions): Promise<ReadonlyArray<Readonly<RaybaseAgentRunSummary>>>;
+};
+export type RaybaseAgentRequestDisposition = "run" | "coalesced" | "ignored";
+export type RaybaseAgentRequestKind = "send" | "retry" | "composed";
+export type RaybaseAgentRequestRow = {
+    id: string;
+    conversationId: string;
+    requestKey: string;
+    messageId: string;
+    kind: RaybaseAgentRequestKind | null;
+    authorUserId: string | null;
+    disposition: RaybaseAgentRequestDisposition | null;
+    runId: string | null;
+    seq: number | null;
+    createdAt: string;
+    updatedAt: string;
+};
+export type RaybaseAgentAccess = {
+    audience: RaybaseAgentAudienceKind;
+    principal: RaybaseAgentPrincipal;
+    surface: string;
+    route: string;
+    origin?: string;
+    organizationId?: string | null;
+};
+export type RaybaseAgentTokenPurpose = "agent-conversation" | "agent-websocket" | "agent-internal";
+export type RaybaseAgentTokenClaims = {
+    v: 1;
+    purpose: RaybaseAgentTokenPurpose;
+    aud: "raybase-agent-chat";
+    agentName: string;
+    conversationId: string;
+    runtime: "ai-chat";
+    triggerType: "chat";
+    principalKind: "user" | "public";
+    userId?: string;
+    publicScopeHash?: string;
+    organizationId?: string;
+    route?: string;
+    surface: string;
+    /** Present only on short-lived tokens minted for the receive subscription socket. */
+    socketMode?: "subscription";
+    iat: number;
+    exp: number;
+    nonce: string;
+};
+export type RaybaseAgentScheduleRow = {
+    id: string;
+    agentName: string;
+    triggerIndex: number;
+    triggerKey: string;
+    inputJson: string | null;
+    cron: string;
+    timezone: string | null;
+    enabled: number;
+    userMessage: string | null;
+    cronOverride: string | null;
+    timezoneOverride: string | null;
+    enabledOverride: number | null;
+    inputJsonOverride: string | null;
+    inputJsonOverrideEnabled: number | null;
+    userMessageOverride: string | null;
+    lastRunAt: string | null;
+    nextRunAt: string | null;
+    service: string | null;
+    dispatchGeneration: number | null;
+    dispatchAttempts: number | null;
+    dispatchLeaseExpiresAt: string | null;
+    lastDispatchAt: string | null;
+    lastDispatchError: string | null;
+    createdAt: string;
+    updatedAt: string;
+};
+export type RaybaseAgentTriggerEventStatus = "queued" | "skipped" | "running" | "completed" | "failed";
+export type RaybaseAgentTriggerEventRow = {
+    id: string;
+    /** Optional tenant scope supplied by a composed runtime such as Raybase Pro. */
+    organizationId?: string;
+    agentName: string;
+    triggerType: "schedule" | "data" | "direct" | "wake" | "follow-up";
+    triggerKey: string;
+    sourceTable: string | null;
+    sourceOp: string | null;
+    rowId: string | null;
+    inputJson: string | null;
+    idempotencyKey: string | null;
+    status: RaybaseAgentTriggerEventStatus;
+    runId: string | null;
+    error: string | null;
+    createdAt: string;
+    updatedAt: string;
+};
+export type RaybaseAgentRunQueueMessage = {
+    kind: "raybase.agent.run";
+    version: 1;
+    eventId: string;
+    agentName: string;
+    triggerType: "schedule" | "data" | "direct" | "wake" | "follow-up";
+    organizationId?: string;
+    claimedBy?: "sweep" | "alarm";
+    claimedAt?: string;
+};
+export type RaybaseAgentFollowUpLapseQueueMessage = {
+    kind: "raybase.agent.follow_up.lapse";
+    version: 1;
+    followUpId: string;
+    agentName: string;
+    /** Optional tenant scope supplied by a composed runtime such as Raybase Pro. */
+    organizationId?: string;
+    claimedBy?: "sweep" | "alarm";
+    lapsedAt?: string;
+};
+export type RaybaseAgentWakeDispatchMessage = {
+    kind: "raybase.agent.wake";
+    version: 1;
+    wakeId: string;
+    agentName: string;
+    generation: number;
+    runAt: string;
+    organizationId?: string;
+    claimedBy: "sweep" | "alarm";
+    claimedAt: string;
+};
+export type RaybaseAgentScheduleDispatchMessage = {
+    kind: "raybase.agent.schedule";
+    version: 1;
+    scheduleId: string;
+    agentName: string;
+    generation: number;
+    bookedAt: string;
+    organizationId?: string;
+    claimedBy: "sweep" | "alarm";
+    claimedAt: string;
+};
+export type RaybaseAgentQueueMessage = RaybaseAgentRunQueueMessage | RaybaseAgentFollowUpLapseQueueMessage | RaybaseAgentWakeDispatchMessage | RaybaseAgentScheduleDispatchMessage;
+export type EffectiveAgentSchedule = {
+    id: string;
+    agentName: string;
+    triggerIndex: number;
+    triggerKey: string;
+    cron: string;
+    timezone: string | null;
+    enabled: boolean;
+    input: unknown;
+    userMessage?: string;
+};
+export type AgentScheduleOverrideField = "cron" | "timezone" | "enabled" | "input" | "userMessage";
+export type AgentScheduleOverrideState = Record<AgentScheduleOverrideField, boolean>;
+export type AgentScheduleAdminSnapshot = {
+    id: string;
+    agentName: string;
+    triggerIndex: number;
+    triggerKey: string;
+    source: {
+        cron: string;
+        timezone: string | null;
+        enabled: boolean;
+        input: unknown;
+        userMessage: string | null;
+    };
+    overrides: {
+        cron: string | null;
+        timezone: string | null;
+        enabled: boolean | null;
+        input: unknown;
+        userMessage: string | null;
+    };
+    overrideEnabled: AgentScheduleOverrideState;
+    effective: {
+        cron: string;
+        timezone: string | null;
+        enabled: boolean;
+        input: unknown;
+        userMessage: string | null;
+    };
+    lastRunAt: string | null;
+    nextRunAt: string | null;
+    service: string | null;
+    createdAt: string;
+    updatedAt: string;
+};
+export type RaybaseAgentRunOptions = {
+    input?: unknown;
+    /** First-class user text for an in-process chat-bound direct run. */
+    userMessage?: string;
+    idempotencyKey?: string;
+    timeout?: string | number;
+    metadata?: unknown;
+    conversation?: RaybaseAgentDirectConversationBinding;
+    organizationId?: string | null;
+    surface?: string;
+    route?: string;
+    requestId?: string;
+    signal?: AbortSignal;
+};
+export type RaybaseAgentEnqueueOptions = {
+    input?: unknown;
+    idempotencyKey?: string;
+    metadata?: unknown;
+    conversation?: RaybaseAgentDirectConversationBinding;
+    organizationId?: string | null;
+    surface?: string;
+    route?: string;
+    requestId?: string;
+};
+export type RaybaseAgentDirectConversationBinding = {
+    mode?: "new";
+} | {
+    mode: "thread";
+    key: string;
+    metadata?: unknown;
+} | {
+    mode: "chat";
+    conversationId: string;
+};
+export type RaybaseAgentRunResult = {
+    eventId: string;
+    runId: string;
+    agentName: string;
+    conversationId: string;
+    status: "completed";
+    output: string;
+    parts?: RaybaseAgentDataPart[];
+    idempotencyKey?: string | null;
+};
+export type RaybaseAgentEnqueueResult = {
+    eventId: string;
+    runId: string;
+    agentName: string;
+    conversationId: string;
+    status: "queued" | "existing" | "skipped";
+    idempotencyKey?: string | null;
+};
+export type RaybaseAgentComposeOptions = {
+    conversationId: string;
+    instruction: string;
+    context?: Record<string, unknown>;
+    requestKey?: string;
+};
+/**
+ * How a compose request landed. `pending` started a turn of its own and
+ * `existing` replayed a request already on file. A turn already running for
+ * the conversation is never a refusal: `steered` means the instruction was
+ * handed to the turn named by `runId`, and `queued` means `runId` is a run
+ * waiting to start once that turn lands.
+ */
+export type RaybaseAgentComposeResult = {
+    conversationId: string;
+    requestKey: string;
+    status: "pending" | "existing" | "steered" | "queued";
+    runId?: string | null;
+};
+export type RaybaseAgentComposeOutcome = {
+    state: "unknown";
+} | {
+    state: "accepted";
+    runId: string | null;
+} | {
+    state: "spoke";
+    runId: string;
+    messageId: string;
+    finishedAt: string;
+} | {
+    state: "silent";
+    runId: string;
+    silenceKind: string;
+    finishedAt: string;
+};
+export type RaybaseAgentConversationRewindResult = {
+    conversationId: string;
+    targetMessageId: string;
+    lastMessageId: string | null;
+    deletedMessageCount: number;
+    releasedRequestKeys: string[];
+};
+export type RaybaseAgentConversationRerunResult = {
+    conversationId: string;
+    messageId: string;
+    requestKey: string;
+    status: "pending";
+};
+export type RaybaseAgentInvocationRuntime = {
+    memory: RaybaseAgentMemoryServerRuntime;
+    runs: RaybaseAgentInvocationRunHistoryReader;
+    run(agentName: string, options?: RaybaseAgentRunOptions): Promise<RaybaseAgentRunResult>;
+    enqueue(agentName: string, options?: RaybaseAgentEnqueueOptions): Promise<RaybaseAgentEnqueueResult>;
+    compose(agentName: string, options: RaybaseAgentComposeOptions): Promise<RaybaseAgentComposeResult>;
+    wake(agentName: string, options: RaybaseAgentWakeOptions): Promise<RaybaseAgentWakeResult>;
+    cancelWake(agentName: string, purpose: string): Promise<{
+        cancelled: boolean;
+    }>;
+    followUps(agentName: string): RaybaseAgentFollowUpsRuntime;
+    conversations: {
+        readState(conversationId: string): Promise<RaybaseAgentConversationReadState>;
+        /**
+         * Bring an expired or archived user conversation back to `active` so a
+         * server lane (a job, a scheduled pass) can compose into it — the same
+         * rehydration the member-facing bootstrap performs, without a member
+         * session. Trusted server context only; never resurrects deleted
+         * conversations.
+         */
+        resume(agentName: string, conversationId: string): Promise<{
+            status: "active" | "resumed";
+        }>;
+        composeOutcome(agentName: string, conversationId: string, requestKey: string): Promise<RaybaseAgentComposeOutcome>;
+        removeMessage(agentName: string, conversationId: string, messageId: string): Promise<{
+            removed: boolean;
+            messageId: string;
+        }>;
+        rewind(agentName: string, conversationId: string, messageId: string): Promise<RaybaseAgentConversationRewindResult>;
+        rerun(agentName: string, conversationId: string): Promise<RaybaseAgentConversationRerunResult>;
+    };
+    rooms: {
+        create(agentName: string, options: {
+            ownerUserId: string;
+            memberUserIds?: string[];
+            title?: string;
+        }): Promise<{
+            conversationId: string;
+        }>;
+        addMember(agentName: string, conversationId: string, userId: string, options?: {
+            byUserId?: string;
+        }): Promise<void>;
+        removeMember(agentName: string, conversationId: string, userId: string, options?: {
+            byUserId?: string;
+        }): Promise<void>;
+        leave(agentName: string, conversationId: string, userId: string): Promise<void>;
+        redactMember(agentName: string, conversationId: string, userId: string): Promise<{
+            status: "complete" | "pending";
+            pending: number;
+        }>;
+        transferOwner(agentName: string, conversationId: string, toUserId: string): Promise<void>;
+        members(agentName: string, conversationId: string): Promise<RaybaseAgentRoomMemberSummary[]>;
+    };
+};
+export declare const maxAgentEntryPayloadBytes: number;
+export declare const maxAgentEntryKickoffChars: number;
+export declare function defineAgent<Env = unknown, Schema extends RaybaseSchema = RaybaseSchema>(definition: RaybaseAgentDefinition<Env, Schema>): RaybaseAgent<Env, Schema>;
+export declare function agentConversationAttachmentsConfig<Env, Schema extends RaybaseSchema = RaybaseSchema>(agent: RaybaseAgent<Env, Schema>): NormalizedRaybaseAgentConversationAttachmentsConfig | null;
+export declare function agentConversationVoiceNotesConfig<Env, Schema extends RaybaseSchema = RaybaseSchema>(agent: RaybaseAgent<Env, Schema>): NormalizedRaybaseAgentConversationVoiceNotesConfig | null;
+export declare function validateAgentAttachmentStorage<Env, Schema extends RaybaseSchema = RaybaseSchema>(agents: RaybaseAgents<Env, Schema>, storage: RaybaseStorageConfig | undefined): void;
+export declare function agentConversationEligibilityConfig<Env, Schema extends RaybaseSchema = RaybaseSchema>(agent: RaybaseAgent<Env, Schema>, conversationKind: "room" | null | undefined): {
+    eligibility?: RaybaseAgentConversationsConfig<Env, Schema>["eligibility"];
+    eligibilityTimeoutMs?: number;
+    onEligibilityFailure?: RaybaseAgentHookFailure;
+};
+export declare function validateAgentEntriesForAgent<Env, Schema extends RaybaseSchema = RaybaseSchema>(agent: RaybaseAgent<Env, Schema>): void;
+export declare function agentEntryDefinition<Env, Schema extends RaybaseSchema = RaybaseSchema>(agent: RaybaseAgent<Env, Schema>, kind: string): RaybaseAgentEntryDefinition;
+export declare function agentEntryAudiences(definition: RaybaseAgentEntryDefinition): RaybaseAgentAudienceKind[];
+export declare function validateInlineAgentEntryPayload(definition: RaybaseAgentEntryDefinition, payload: unknown): unknown;
+export declare function agentEntryFromInstance(instance: Pick<RaybaseAgentInstanceRow, "entryKind" | "entryJson">): RaybaseAgentEntrySnapshot | undefined;
+export declare function agentConversationTitlesConfig<Env, Schema extends RaybaseSchema = RaybaseSchema>(agent: Pick<RaybaseAgent<Env, Schema>, "conversationTitles">): {
+    model: string | null;
+} | null;
+export declare function validateAgentTriggers<Env, Schema extends RaybaseSchema = RaybaseSchema>(agents: RaybaseAgents<Env, Schema> | undefined, schema: Schema): void;
+export declare function parseAgentDataTriggerEvent(event: string): {
+    tableName: string;
+    op: "create" | "update" | "delete";
+};
+export declare function defineAgents<Env = unknown, Schema extends RaybaseSchema = RaybaseSchema>(agents: RaybaseAgentDefinitions<Env, Schema>): RaybaseAgents<Env, Schema>;
+export declare function validateAgentName(name: string): void;
+export declare function agentSummaries<Env, Schema extends RaybaseSchema = RaybaseSchema>(agents?: RaybaseAgents<Env, Schema>): {
+    name: string;
+    title: string;
+    description: string;
+    runtime: "ai-chat";
+    triggers: RaybaseAgentTrigger[];
+    model: string | null;
+    limits: RaybaseAgentLimits | null;
+    scopes: string[];
+    owner: {
+        moduleId?: string;
+        packageName?: string;
+    } | null;
+    actions: {
+        name: string;
+        description: string;
+    }[];
+    skills: RaybaseAgentSkillSummary[];
+    skillStore: RaybaseAgentSkillStoreConfig<Env, Schema> | null;
+    remoteMcpBindings: RaybaseAgentRemoteMcpBindingSummary[];
+    memorySpaces: RaybaseAgentMemorySpaceSummary[];
+    rooms: boolean;
+    entries: {
+        kind: string;
+        description: string;
+        source: RaybaseAgentEntrySource;
+        audience: RaybaseAgentAudienceKind[];
+        hasKickoff: boolean;
+        payloadSchema: JsonSchemaObject | null;
+    }[];
+    runtimeControl: {
+        configurable: boolean;
+        defaultEnabled: boolean;
+    };
+    prompt: {
+        configurable: boolean;
+        renderer: "liquid";
+        default: string;
+    } | null;
+}[];
+export declare function agentFor<Env, Schema extends RaybaseSchema = RaybaseSchema>(agents: RaybaseAgents<Env, Schema> | undefined, name: string): RaybaseAgent<Env, Schema>;
+export declare class AgentHttpError extends Error {
+    readonly status: number;
+    readonly retryable: boolean;
+    constructor(message: string, status: number, retryable?: boolean);
+}
+export declare function agentAudienceKinds(audience: RaybaseAgentAudience | undefined, surface: string): RaybaseAgentAudienceKind[];
+export declare function agentAudienceAllows(audience: RaybaseAgentAudience | undefined, surface: string, kind: RaybaseAgentAudienceKind): boolean;
+export declare function agentRequestSurface(request: Request, surfaces?: Array<{
+    surface: string;
+    pathPrefix: string;
+}>): {
+    surface: string;
+    route: string;
+    origin?: string;
+};
+export declare function resolveAgentAccess(input: {
+    request: Request;
+    user?: RaybaseUser;
+    organizationId?: string | null;
+    agent: Pick<RaybaseAgent, "audience">;
+    surfaces?: Array<{
+        surface: string;
+        pathPrefix: string;
+    }>;
+    principalKind?: "user" | "public";
+}): Promise<RaybaseAgentAccess>;
+export declare function publicAgentUser(principal: Extract<RaybaseAgentPrincipal, {
+    kind: "public";
+}>): RaybaseUser;
+export declare function agentInstanceKey(agentName: string, conversationId: string): string;
+export declare function agentExpiresAt(ttlSeconds?: number | null): string | null;
+export declare function createOrResumeAgentInstance<Env, Schema extends RaybaseSchema = RaybaseSchema>(input: {
+    organizationId?: string | null;
+    control: SqlExecutor;
+    agent: RaybaseAgent<Env, Schema>;
+    access: RaybaseAgentAccess;
+    conversationId?: string;
+    title?: string | null;
+    ttlSeconds?: number;
+    rehydrateArchived?: (instance: RaybaseAgentInstanceRow, synopsis: AgentChapterSynopsis) => Promise<void>;
+    metadata?: unknown;
+    entry?: RaybaseAgentEntrySnapshot;
+}): Promise<RaybaseAgentInstanceRow>;
+export declare function buildAgentRoomInstance<Env, Schema extends RaybaseSchema = RaybaseSchema>(input: {
+    agent: RaybaseAgent<Env, Schema>;
+    ownerUserId: string;
+    conversationId: string;
+    title?: string;
+    organizationId?: string | null;
+    route?: string | null;
+    surface?: string;
+    now?: string;
+}): RaybaseAgentInstanceRow;
+export declare function agentRoomInstanceInsertStatement(row: RaybaseAgentInstanceRow): {
+    sql: string;
+    params: SqlValue[];
+};
+export declare function createAgentRoomInstance<Env, Schema extends RaybaseSchema = RaybaseSchema>(input: {
+    control: SqlExecutor;
+    agent: RaybaseAgent<Env, Schema>;
+    ownerUserId: string;
+    conversationId: string;
+    title?: string;
+    organizationId?: string | null;
+    route?: string | null;
+    surface?: string;
+    now?: string;
+}): Promise<RaybaseAgentInstanceRow>;
+export declare function findAgentInstance(control: SqlExecutor, agentName: string, conversationId: string): Promise<RaybaseAgentInstanceRow | null>;
+export declare function listAgentConversations(control: SqlExecutor, input: {
+    /** Opaque first-party runtime scope metadata; Core leaves this unset. */
+    organizationId?: string | null;
+    agentName: string;
+    access: RaybaseAgentAccess;
+    limit?: number;
+    offset?: number;
+    now?: string;
+    includeArchived?: boolean;
+    q?: string;
+}): Promise<RaybaseAgentConversationSummary[]>;
+export declare function loadAgentConversationForAccess(control: SqlExecutor, input: {
+    /** Opaque first-party runtime scope metadata; Core leaves this unset. */
+    organizationId?: string | null;
+    agentName: string;
+    conversationId: string;
+    access: RaybaseAgentAccess;
+}): Promise<RaybaseAgentInstanceRow>;
+export declare function requestAgentConversationDeletion(control: SqlExecutor, input: {
+    /** Opaque first-party runtime scope metadata; Core leaves this unset. */
+    organizationId?: string | null;
+    agentName: string;
+    conversationId: string;
+    access: RaybaseAgentAccess;
+    deleteHotStorage: (instance: RaybaseAgentInstanceRow) => Promise<void>;
+    now?: string;
+}): Promise<{
+    agentName: string;
+    conversationId: string;
+    status: "deleted";
+}>;
+export declare function loadAgentInstance(control: SqlExecutor, agentName: string, conversationId: string): Promise<RaybaseAgentInstanceRow>;
+export declare function agentInstanceMetadataJson(input: {
+    organizationId?: string | null;
+    current?: string | null;
+    metadata?: unknown;
+    title?: string | null;
+}): string | null;
+export declare function agentConversationTitle(metadataJson: string | null): string | null;
+export declare function updateAgentConversationTitle(control: SqlExecutor, instance: Pick<RaybaseAgentInstanceRow, "id" | "metadataJson">, title: string | null, now?: string): Promise<string | null>;
+export declare function updateAgentConversationPinned(control: SqlExecutor, instance: Pick<RaybaseAgentInstanceRow, "id">, pinned: boolean, now?: string): Promise<string | null>;
+export declare function markAgentDirectConversationRead(control: SqlExecutor, instance: Pick<RaybaseAgentInstanceRow, "id" | "kind">, now?: string): Promise<string>;
+export declare function renameAgentConversation(control: SqlExecutor, input: {
+    /** Opaque first-party runtime scope metadata; Core leaves this unset. */
+    organizationId?: string | null;
+    agentName: string;
+    conversationId: string;
+    access: RaybaseAgentAccess;
+    title: unknown;
+    now?: string;
+}): Promise<{
+    agentName: string;
+    conversationId: string;
+    title: string | null;
+}>;
+export declare function pinAgentConversation(control: SqlExecutor, input: {
+    /** Opaque first-party runtime scope metadata; Core leaves this unset. */
+    organizationId?: string | null;
+    agentName: string;
+    conversationId: string;
+    access: RaybaseAgentAccess;
+    pinned: unknown;
+    now?: string;
+}): Promise<{
+    agentName: string;
+    conversationId: string;
+    pinned: boolean;
+    pinnedAt: string | null;
+}>;
+export declare function cleanAgentConversationTitle(value: unknown): string | undefined;
+export declare function createAgentRun(input: {
+    /** Opaque first-party runtime scope metadata; Core leaves this unset. */
+    organizationId?: string | null;
+    control: SqlExecutor;
+    instance: RaybaseAgentInstanceRow;
+    requestId: string;
+    /**
+     * A run id reserved before the row exists. The chat harness mints one ahead
+     * of the pre-run eligibility gate so the hook that decides whether to answer
+     * sees the same turn identity as everything downstream of it. Omitted
+     * elsewhere, and minted here.
+     */
+    runId?: string;
+    triggerType?: RaybaseAgentExecutionTriggerType;
+    inputMessageId?: string | null;
+    metadata?: unknown;
+    /**
+     * Refreshes ordinary conversations while preserving the structural NULL
+     * expiry used by keep-hot. When omitted, an existing NULL is still kept so
+     * direct/internal callers cannot accidentally open a sweep crash window.
+     */
+    ttlSeconds?: number | null;
+}): Promise<RaybaseAgentRunRow>;
+export declare function agentEnabledSettingKey(agentName: string): string;
+export declare function agentPromptSettingKey(agentName: string): string;
+export declare const raybaseAgentTimezoneSettingKey = "raybase.agent.timezone";
+export declare function agentGeneratedSettingDefinitions<Env, Schema extends RaybaseSchema = RaybaseSchema>(agents: RaybaseAgents<Env, Schema> | undefined): RaybaseSettingsDefinitions<Env>;
+export declare function isAgentRuntimeEnabled<Env, Schema extends RaybaseSchema = RaybaseSchema>(settings: RaybaseRuntimeSettings<Env, RaybaseSettingsDefinitions<Env>> | undefined, agent: RaybaseAgent<Env, Schema>): Promise<boolean>;
+export declare function agentScheduleId(agentName: string, triggerIndex: number, trigger?: Extract<RaybaseAgentTrigger, {
+    type: "schedule";
+}>): string;
+export declare function agentTriggerKey(agentName: string, triggerIndex: number, trigger: RaybaseAgentTrigger): string;
+export declare function parseAgentScheduleSourceInput(row: RaybaseAgentScheduleRow): unknown;
+export declare function parseAgentScheduleInput(row: RaybaseAgentScheduleRow): unknown;
+export declare function agentScheduleOverrideState(row: RaybaseAgentScheduleRow): AgentScheduleOverrideState;
+export declare function effectiveAgentSchedule(row: RaybaseAgentScheduleRow): EffectiveAgentSchedule;
+export declare function agentScheduleRuntimeTrigger(row: RaybaseAgentScheduleRow): Extract<RaybaseAgentTrigger, {
+    type: "schedule";
+}>;
+export declare function agentScheduleAdminSnapshot(row: RaybaseAgentScheduleRow): AgentScheduleAdminSnapshot;
+export declare function scheduleNextRunFrom(now: string, cron: string, timezone?: string | null): string | null;
+export declare function loadAgentSchedule(control: SqlExecutor, idValue: string): Promise<RaybaseAgentScheduleRow>;
+export declare function listAgentSchedulesForAgent(control: SqlExecutor, agentName: string): Promise<RaybaseAgentScheduleRow[]>;
+export type AgentScheduleOverrideWriteResult = {
+    row: RaybaseAgentScheduleRow;
+    before: AgentScheduleAdminSnapshot;
+    after: AgentScheduleAdminSnapshot;
+    changedFields: AgentScheduleOverrideField[];
+};
+export declare function setAgentScheduleOverrides(control: SqlExecutor, input: {
+    /** Opaque first-party runtime scope metadata; Core leaves this unset. */
+    organizationId?: string | null;
+    id: string;
+    overrides?: Record<string, unknown> | null;
+    reset?: unknown;
+    now?: string;
+}): Promise<AgentScheduleOverrideWriteResult>;
+export declare function resetAgentScheduleOverrides(control: SqlExecutor, input: {
+    /** Opaque first-party runtime scope metadata; Core leaves this unset. */
+    organizationId?: string | null;
+    id: string;
+    fields?: AgentScheduleOverrideField[];
+    now?: string;
+}): Promise<AgentScheduleOverrideWriteResult>;
+export declare function upsertAgentSchedule(control: SqlExecutor, input: {
+    /** Opaque first-party runtime scope metadata; Core leaves this unset. */
+    organizationId?: string | null;
+    agentName: string;
+    triggerIndex: number;
+    trigger: Extract<RaybaseAgentTrigger, {
+        type: "schedule";
+    }>;
+    nextRunAt: string | null;
+    service?: string | null;
+    now?: string;
+}): Promise<RaybaseAgentScheduleRow>;
+export declare function listDueAgentSchedules(control: SqlExecutor, input: {
+    organizationId?: string | null;
+    now: string;
+    limit?: number;
+}): Promise<RaybaseAgentScheduleRow[]>;
+export declare const agentScheduleMaxDispatchAttempts = 5;
+export type RaybaseAgentScheduleDispatch = {
+    id: string;
+    agentName: string;
+    generation: number;
+    bookedAt: string;
+};
+export declare function claimDueAgentSchedules(control: SqlExecutor, input: {
+    organizationId?: string | null;
+    now: string;
+    wallNow: string;
+    leaseExpiresAt: string;
+    limit?: number;
+    maxAttempts?: number;
+}): Promise<RaybaseAgentScheduleDispatch[]>;
+export declare function loadClaimedAgentSchedule(control: SqlExecutor, input: {
+    id: string;
+    generation: number;
+    bookedAt: string;
+}): Promise<RaybaseAgentScheduleRow | null>;
+export declare function releaseAgentScheduleDispatch(control: SqlExecutor, input: {
+    id: string;
+    generation: number;
+    bookedAt: string;
+    error: string;
+    now?: string;
+}): Promise<void>;
+export declare function advanceAgentSchedule(control: SqlExecutor, input: {
+    organizationId?: string | null;
+    id: string;
+    lastRunAt: string;
+    nextRunAt: string | null;
+    generation?: number;
+    now?: string;
+}): Promise<void>;
+export declare function createAgentTriggerEvent(control: SqlExecutor, input: {
+    /** Opaque first-party runtime scope metadata; Core leaves this unset. */
+    organizationId?: string | null;
+    agentName: string;
+    triggerType: "schedule" | "data" | "direct" | "wake" | "follow-up";
+    triggerKey: string;
+    sourceTable?: string | null;
+    sourceOp?: "create" | "update" | "delete" | null;
+    rowId?: string | null;
+    input?: unknown;
+    idempotencyKey?: string | null;
+    status?: RaybaseAgentTriggerEventStatus;
+    error?: string | null;
+    now?: string;
+}): Promise<RaybaseAgentTriggerEventRow>;
+declare function markAgentTriggerEvent(control: SqlExecutor, eventId: string, input: {
+    /** Opaque first-party runtime scope metadata; Core leaves this unset. */
+    organizationId?: string | null;
+    status: RaybaseAgentTriggerEventStatus;
+    runId?: string | null;
+    error?: string | null;
+    now?: string;
+}): Promise<void>;
+export declare const markAgentTriggerEventQueued: (control: SqlExecutor, eventId: string, input?: Omit<Parameters<typeof markAgentTriggerEvent>[2], "status">) => Promise<void>;
+export declare const markAgentTriggerEventRunning: (control: SqlExecutor, eventId: string, input?: Omit<Parameters<typeof markAgentTriggerEvent>[2], "status">) => Promise<void>;
+export declare const markAgentTriggerEventCompleted: (control: SqlExecutor, eventId: string, input?: Omit<Parameters<typeof markAgentTriggerEvent>[2], "status">) => Promise<void>;
+export declare const markAgentTriggerEventFailed: (control: SqlExecutor, eventId: string, input?: Omit<Parameters<typeof markAgentTriggerEvent>[2], "status">) => Promise<void>;
+export declare const markAgentTriggerEventSkipped: (control: SqlExecutor, eventId: string, input?: Omit<Parameters<typeof markAgentTriggerEvent>[2], "status">) => Promise<void>;
+export declare function loadAgentTriggerEvent(control: SqlExecutor, eventId: string): Promise<RaybaseAgentTriggerEventRow>;
+export declare function findAgentTriggerEventByIdempotencyKey(control: SqlExecutor, idempotencyKey: string): Promise<RaybaseAgentTriggerEventRow | null>;
+export declare function directAgentTriggerKey(agentName: string): string;
+export declare function findAgentRun(control: SqlExecutor, runId: string): Promise<RaybaseAgentRunRow | null>;
+export declare function loadAgentRun(control: SqlExecutor, runId: string): Promise<RaybaseAgentRunRow>;
+export declare function createOrLoadDirectAgentInvocationRecord(input: {
+    /** Opaque first-party runtime scope metadata; Core leaves this unset. */
+    organizationId?: string | null;
+    control: SqlExecutor;
+    agent: Pick<RaybaseAgent, "name">;
+    invocationInput?: unknown;
+    idempotencyKey?: string | null;
+    requestId?: string;
+    metadata?: unknown;
+    conversationId?: string;
+    bindingFingerprint?: string;
+}): Promise<{
+    created: boolean;
+    event: RaybaseAgentTriggerEventRow;
+    run: RaybaseAgentRunRow | null;
+}>;
+export declare function createAgentAutomationRun(input: {
+    /** Opaque first-party runtime scope metadata; Core leaves this unset. */
+    organizationId?: string | null;
+    control: SqlExecutor;
+    agent: Pick<RaybaseAgent, "name">;
+    triggerType: "schedule" | "data" | "direct" | "wake" | "follow-up";
+    eventId: string;
+    requestId?: string;
+    metadata?: unknown;
+    conversationId?: string;
+}): Promise<RaybaseAgentRunRow>;
+export declare const activeAgentRunStaleSeconds: number;
+export declare const queuedAgentRunStaleSeconds: number;
+export declare function findActiveAgentRun(control: SqlExecutor, input: {
+    organizationId?: string | null;
+    agentName: string;
+    conversationId: string;
+    now?: string;
+}): Promise<RaybaseAgentRunRow | null>;
+/**
+ * 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 declare const interruptedAgentRunError = "Interrupted by restart or deployment";
+/**
+ * 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 declare function staleAgentRunError(staleSeconds?: number): string;
+/** Truthful terminal label for work that remained queued without starting. */
+export declare function staleQueuedAgentRunError(staleSeconds?: number): string;
+/**
+ * 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 declare function isReapedAgentRunError(error: string | null | undefined): boolean;
+/**
+ * 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 declare function sweepStaleAgentRuns(control: SqlExecutor, input?: {
+    organizationId?: string | null;
+    now?: string;
+    limit?: number;
+}): Promise<string[]>;
+/**
+ * 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 declare function sweepAgentRunEvidence(control: SqlExecutor, input?: {
+    now?: string;
+    limit?: number;
+    runEvidenceTtlMsForAgent?: (agentName: string) => number;
+}): Promise<{
+    runIds: string[];
+    requestIds: string[];
+}>;
+/**
+ * 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 declare function touchAgentRunHeartbeat(control: SqlExecutor, runId: string, now?: string): Promise<void>;
+export declare function updateAgentRun(control: SqlExecutor, runId: string, input: {
+    organizationId?: string | null;
+    status?: RaybaseAgentRunStatus;
+    error?: string | null;
+    finishedAt?: string | null;
+    metadata?: unknown;
+    /** Explicit execution start for callers that must share the exact timestamp. */
+    startedAt?: string;
+}): Promise<void>;
+export declare function touchAgentInstance(control: SqlExecutor, instanceId: string, input?: {
+    organizationId?: string | null;
+    lastError?: string | null;
+    ttlSeconds?: number | null;
+}): Promise<void>;
+export declare function listExpiredAgentInstances(control: SqlExecutor, input?: {
+    organizationId?: string | null;
+    now?: string;
+    limit?: number;
+}): Promise<RaybaseAgentInstanceRow[]>;
+export declare function markAgentCleanupRequested(control: SqlExecutor, instanceId: string, input?: {
+    organizationId?: string | null;
+    now?: string;
+    reason?: string | null;
+    error?: string | null;
+}): Promise<void>;
+export declare function beginAgentHotCleanup(control: SqlExecutor, input: {
+    organizationId?: string | null;
+    instance: RaybaseAgentInstanceRow;
+    now?: string;
+    reason?: string | null;
+}): Promise<{
+    status: "delete" | "reschedule" | "terminal" | "busy";
+    instance: RaybaseAgentInstanceRow;
+}>;
+export declare function completeAgentHotCleanup(control: SqlExecutor, instanceId: string, input?: {
+    organizationId?: string | null;
+    now?: string;
+    outcome?: "archived" | "deleted";
+}): Promise<void>;
+export declare function completeAgentUserErasureAfterArtifactDrain(control: SqlExecutor, userId: string, input?: {
+    organizationId?: string | null;
+    now?: string;
+}): Promise<boolean>;
+export declare function countPendingAgentRoomMemberRedactions(control: SqlExecutor, userId: string): Promise<number>;
+export declare function failAgentHotCleanup(control: SqlExecutor, instanceId: string, input: {
+    organizationId?: string | null;
+    error: string;
+    now?: string;
+}): Promise<void>;
+export declare function claimAgentGuideLimits<Env, Schema extends RaybaseSchema = RaybaseSchema>(input: {
+    /** Opaque first-party runtime scope metadata; Core leaves this unset. */
+    organizationId?: string | null;
+    control: SqlExecutor;
+    agent: RaybaseAgent<Env, Schema>;
+    instance: RaybaseAgentInstanceRow;
+    estimatedOutputTokens: number;
+}): Promise<void>;
+/** `limit` unset means unlimited; the window row is still counted so usage stays visible. */
+export declare function claimAgentEntryKickoffLimit(control: SqlExecutor, instance: RaybaseAgentInstanceRow, limit?: number): Promise<void>;
+/** `limit` unset means unlimited; the window row is still counted so usage stays visible. */
+export declare function claimAgentComposedLimit(control: SqlExecutor, instance: RaybaseAgentInstanceRow, limit?: number): Promise<void>;
+export declare function signAgentToken(secret: string, claims: Omit<RaybaseAgentTokenClaims, "iat" | "exp" | "nonce"> & {
+    ttlSeconds: number;
+}): Promise<string>;
+export declare function verifyAgentToken(secret: string, token: string, purpose: RaybaseAgentTokenPurpose): Promise<RaybaseAgentTokenClaims>;
+export declare function agentTokenClaims(input: {
+    organizationId?: string | null;
+    purpose: RaybaseAgentTokenPurpose;
+    agent: Pick<RaybaseAgent<any>, "name">;
+    instance: RaybaseAgentInstanceRow;
+    userId?: string;
+    ttlSeconds?: number;
+    socketMode?: "subscription";
+}): Omit<RaybaseAgentTokenClaims, "iat" | "exp" | "nonce"> & {
+    ttlSeconds: number;
+};
+export declare function assertAgentTokenMatchesInstance(claims: RaybaseAgentTokenClaims, instance: RaybaseAgentInstanceRow): void;
+export declare function assertAgentTokenConversationAccess(control: SqlExecutor, claims: RaybaseAgentTokenClaims, instance: RaybaseAgentInstanceRow): Promise<{
+    membership: RaybaseAgentRoomMemberRow | null;
+}>;
+export declare function extractBearerToken(request: Request): string | null;
+export declare function raybaseActionToAiTool<Env, Schema extends RaybaseSchema = RaybaseSchema>(action: RaybaseAction<unknown, unknown, Env, Schema>, contextFactory: (input: {
+    organizationId?: string | null;
+    toolCallId: string;
+}) => Promise<RaybaseAgentActionContext<Env, Schema>> | RaybaseAgentActionContext<Env, Schema>): Tool;
+export type RaybaseAgentActionContext<Env = unknown, Schema extends RaybaseSchema = RaybaseSchema> = {
+    request: Request;
+    env: Env;
+    config: RaybaseConfig;
+    user?: RaybaseUser;
+    principal: RaybaseAgentPrincipal;
+    agentName: string;
+    /** The agent definition's `scopes`, carried onto the agent principal. */
+    agentScopes?: readonly string[];
+    /** The owning run's execution trigger, so actions can gate by run type. */
+    trigger?: {
+        type: RaybaseAgentExecutionTriggerType;
+        purpose?: string;
+    };
+    conversationId: string;
+    /**
+     * Membership-checked reader for another conversation the acting user
+     * belongs to. Direct turns only; a room turn's action context leaves it out.
+     */
+    conversations?: RaybaseActionContext<Env, Schema>["conversations"];
+    runId: string;
+    requestId: string;
+    toolCallId: string;
+    route: string;
+    surface: string;
+    organizationId?: string | null;
+    db: RaybaseActionDataClient<Schema>;
+    agents?: RaybaseAgentInvocationRuntime;
+    ai: RaybaseAI;
+    audit: (event: RaybaseAuditContextEvent) => Promise<void>;
+    agentInstanceId?: string;
+} & Pick<RaybaseActionContext<Env, Schema>, "settings" | "notifications" | "jobs">;
+export declare function executeRaybaseAgentAction<Env, Schema extends RaybaseSchema = RaybaseSchema>(action: RaybaseAction<unknown, unknown, Env, Schema>, rawInput: unknown, ctx: RaybaseAgentActionContext<Env, Schema> & {
+    control?: SqlExecutor;
+}): Promise<unknown>;
+export declare function agentLimits<Env, Schema extends RaybaseSchema = RaybaseSchema>(config: RaybaseConfig, agent: RaybaseAgent<Env, Schema>): Required<Pick<RaybaseAgentLimits, "maxInputChars" | "maxOutputTokens" | "maxToolCallsPerTurn" | "maxLoopStepsPerTurn" | "maxConversationMessages">> & RaybaseAgentLimits;
+export declare function agentCompaction<Env, Schema extends RaybaseSchema = RaybaseSchema>(agent: RaybaseAgent<Env, Schema>): Required<Omit<RaybaseAgentCompaction, "model">> & Pick<RaybaseAgentCompaction, "model">;
+/**
+ * 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 declare function agentSummaryBudgetTokens(compaction: RaybaseAgentCompaction | undefined, spanChars: number): number;
+export declare function agentModel<Env, Schema extends RaybaseSchema = RaybaseSchema>(config: RaybaseConfig, agent: RaybaseAgent<Env, Schema>, runtimeDefaultModel?: string | null): string;
+export declare function actionEventUserId(principal: RaybaseAgentPrincipal): string;
+export declare function assertAgentConversationAccess(input: {
+    /** Opaque first-party runtime scope metadata; Core leaves this unset. */
+    organizationId?: string | null;
+    control: SqlExecutor;
+    instance: RaybaseAgentInstanceRow;
+    access: RaybaseAgentAccess;
+    require?: "member" | "owner";
+}): Promise<{
+    membership: RaybaseAgentRoomMemberRow | null;
+}>;
+export declare function jsonSchemaObject(schema: JsonSchemaObject): JsonSchemaObject;
+//# sourceMappingURL=agent.d.ts.map