@raybase/core 0.0.2 → 0.3.3

package/dist/agent-wakes.d.ts

@@ -0,0 +1,213 @@
+import type { RaybaseAgent, RaybaseAgentDirectConversationBinding } from "./agent.js";
+import type { AgentRuntimeTool } from "./agent-runtime.js";
+import type { RaybaseAgentPrincipal } from "./ai.js";
+import type { SqlExecutor } from "./db.js";
+import { type RaybaseSchema, type RaybaseSystemTable } from "./schema.js";
+export type RaybaseAgentWakeActivityRule = {
+    purpose: string;
+    /** Debounce window: each completed member chat turn re-arms the pending wake to now + quietFor. */
+    quietFor: string | number;
+};
+export type RaybaseAgentWakesConfig = {
+    enabled: true;
+    purposes?: string[];
+    /**
+     * Declarative activity-debounced wakes: "act when things go quiet". After
+     * each completed member chat turn of this agent, Core moves the pending
+     * (agent, purpose) wake to now + quietFor — replacement semantics, unlike
+     * the earlier-only collapse of schedule_wakeup. App-declared re-arms never
+     * consume the dailySchedules tool budget and bypass maxPending (they are
+     * bounded by the number of rules, one pending wake per purpose).
+     */
+    activity?: RaybaseAgentWakeActivityRule[];
+    limits?: {
+        maxPending?: number;
+        minDelay?: string | number;
+        maxHorizon?: string | number;
+        dailySchedules?: number;
+    };
+};
+export type RaybaseAgentWakeOptions = {
+    purpose: string;
+    at?: string;
+    in?: string | number;
+    note?: string;
+    input?: unknown;
+    userMessage?: string;
+    conversation?: RaybaseAgentDirectConversationBinding;
+};
+export type RaybaseAgentWakeResult = {
+    wakeId: string;
+    runAt: string;
+    collapsed: boolean;
+};
+export type RaybaseAgentWakeRow = {
+    id: string;
+    agentName: string;
+    purpose: string;
+    status: "pending" | "dispatched" | "cancelled";
+    runAt: string;
+    note: string | null;
+    inputJson: string | null;
+    userMessage: string | null;
+    conversationJson: string | null;
+    requestedByKind: "agent-tool" | "app" | "operator";
+    requestedByConversationId: string | null;
+    requestedByRunId: string | null;
+    collapsedCount: number;
+    dispatchedAt: string | null;
+    triggerEventId: string | null;
+    dispatchGeneration: number | null;
+    dispatchAttempts: number | null;
+    dispatchLeaseExpiresAt: string | null;
+    lastDispatchAt: string | null;
+    lastDispatchError: string | null;
+    createdAt: string;
+    updatedAt: string;
+};
+export declare const raybaseAgentWakeToolNames: readonly ["schedule_wakeup", "cancel_wakeup", "list_wakeups"];
+export declare const raybaseAgentWakeSystemTables: RaybaseSystemTable[];
+export declare const raybaseAgentWakeLimits: {
+    readonly maxPending: 8;
+    readonly apiMinDelayMs: 60000;
+    readonly toolMinDelayMs: number;
+    readonly maxHorizonMs: number;
+    readonly dailySchedules: 48;
+    readonly maxPurposeChars: 64;
+    readonly maxNoteChars: 2000;
+    readonly maxUserMessageChars: 8000;
+    readonly maxInputBytes: 32768;
+    readonly maxConversationBytes: 8192;
+};
+export declare const agentWakeMaxDispatchAttempts = 5;
+export type RaybaseAgentWakeDispatch = {
+    id: string;
+    agentName: string;
+    generation: number;
+    runAt: string;
+};
+export type NormalizedAgentWakesConfig = {
+    purposes: string[] | null;
+    activity: Array<{
+        purpose: string;
+        quietForMs: number;
+    }>;
+    maxPending: number;
+    minDelayMs: number | null;
+    maxHorizonMs: number;
+    dailySchedules: number;
+};
+export declare class AgentWakePolicyError extends Error {
+    readonly reason: "invalid-request" | "purpose-not-allowed" | "max-pending" | "daily-limit";
+    readonly pending: RaybaseAgentWakeRow[];
+    constructor(reason: "invalid-request" | "purpose-not-allowed" | "max-pending" | "daily-limit", message: string, pending?: RaybaseAgentWakeRow[]);
+}
+export declare function normalizeAgentWakesConfig<Env, Schema extends RaybaseSchema = RaybaseSchema>(agent: Pick<RaybaseAgent<Env, Schema>, "name" | "wakes">): NormalizedAgentWakesConfig | null;
+export declare function validateAgentWakesForAgent<Env, Schema extends RaybaseSchema = RaybaseSchema>(agent: Pick<RaybaseAgent<Env, Schema>, "name" | "wakes">): void;
+export declare function validateAgentWakePurpose(value: unknown): string;
+export declare function listAgentWakes(control: SqlExecutor, input: {
+    organizationId?: string | null;
+    agentName: string;
+    status?: RaybaseAgentWakeRow["status"];
+    limit?: number;
+}): Promise<RaybaseAgentWakeRow[]>;
+export declare function listDueAgentWakes(control: SqlExecutor, input?: {
+    organizationId?: string | null;
+    now?: string;
+    limit?: number;
+}): Promise<RaybaseAgentWakeRow[]>;
+export declare function claimDueAgentWakes(control: SqlExecutor, input: {
+    organizationId?: string | null;
+    now: string;
+    wallNow: string;
+    leaseExpiresAt: string;
+    limit?: number;
+    maxAttempts?: number;
+}): Promise<RaybaseAgentWakeDispatch[]>;
+export declare function loadClaimedAgentWake(control: SqlExecutor, input: {
+    id: string;
+    generation: number;
+}): Promise<RaybaseAgentWakeRow | null>;
+export declare function releaseAgentWakeDispatch(control: SqlExecutor, input: {
+    id: string;
+    generation: number;
+    error: string;
+    now?: string;
+}): Promise<void>;
+export declare function scheduleAgentWake<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>;
+    options: RaybaseAgentWakeOptions;
+    requestedByKind: RaybaseAgentWakeRow["requestedByKind"];
+    requestedByConversationId?: string | null;
+    requestedByRunId?: string | null;
+    toolInitiated?: boolean;
+    now?: string;
+}): Promise<RaybaseAgentWakeResult & {
+    row: RaybaseAgentWakeRow;
+    pendingCount: number;
+}>;
+/**
+ * Re-arms this agent's declared activity-debounced wakes after a completed
+ * member chat turn: each `wakes.activity` purpose's pending wake moves to
+ * now + quietFor (created if absent). Replacement semantics — unlike the
+ * earlier-only collapse of scheduleAgentWake — because a debounce must push
+ * the run LATER on fresh activity. System-initiated: never consumes the
+ * dailySchedules tool budget, bypasses maxPending (bounded by the rule list,
+ * one pending row per purpose), and preserves an existing pending row's
+ * note/input/userMessage/conversation so a model-scheduled wake for the same
+ * purpose keeps its content while its timing debounces.
+ */
+export declare function rearmAgentActivityWakes<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>;
+    requestedByConversationId?: string | null;
+    requestedByRunId?: string | null;
+    now?: string;
+}): Promise<Array<{
+    purpose: string;
+    runAt: string;
+    created: boolean;
+}>>;
+export declare function cancelAgentWake(control: SqlExecutor, input: {
+    organizationId?: string | null;
+    agentName: string;
+    purpose: string;
+    now?: string;
+}): Promise<{
+    cancelled: boolean;
+    row: RaybaseAgentWakeRow | null;
+}>;
+export declare function cancelAgentWakeById(control: SqlExecutor, input: {
+    organizationId?: string | null;
+    agentName: string;
+    wakeId: string;
+    now?: string;
+}): Promise<{
+    cancelled: boolean;
+    row: RaybaseAgentWakeRow | null;
+}>;
+export declare function finishAgentWake(control: SqlExecutor, input: {
+    /** Opaque first-party runtime scope metadata; Core leaves this unset. */
+    organizationId?: string | null;
+    wakeId: string;
+    status: "dispatched" | "cancelled";
+    triggerEventId: string;
+    generation?: number;
+    now?: string;
+}): Promise<void>;
+type WakeToolInput<Env, Schema extends RaybaseSchema> = {
+    agent: RaybaseAgent<Env, Schema>;
+    principal: RaybaseAgentPrincipal;
+    control: SqlExecutor;
+    conversationId: string;
+    runId: string;
+    onDueAtChanged?: (targetIso: string) => void | Promise<void>;
+};
+export declare function agentWakeRuntimeTools<Env, Schema extends RaybaseSchema = RaybaseSchema>(input: WakeToolInput<Env, Schema>): AgentRuntimeTool[];
+export {};
+//# sourceMappingURL=agent-wakes.d.ts.map

package/dist/agent-wakes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-wakes.d.ts","sourceRoot":"","sources":["../src/agent-wakes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,qCAAqC,EAAE,MAAM,YAAY,CAAC;AACtF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAErD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAG3C,OAAO,EAAmD,KAAK,aAAa,EAAE,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAG3H,MAAM,MAAM,4BAA4B,GAAG;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,mGAAmG;IACnG,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,OAAO,EAAE,IAAI,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,4BAA4B,EAAE,CAAC;IAC1C,MAAM,CAAC,EAAE;QACP,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;QAC3B,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;QAC7B,cAAc,CAAC,EAAE,MAAM,CAAC;KACzB,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,qCAAqC,CAAC;CACtD,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,SAAS,GAAG,YAAY,GAAG,WAAW,CAAC;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,eAAe,EAAE,YAAY,GAAG,KAAK,GAAG,UAAU,CAAC;IACnD,yBAAyB,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,sBAAsB,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,eAAO,MAAM,yBAAyB,+DAAgE,CAAC;AAEvG,eAAO,MAAM,4BAA4B,EAAE,kBAAkB,EAoC5D,CAAC;AAEF,eAAO,MAAM,sBAAsB;;;;;;;;;;;CAWzB,CAAC;AAEX,eAAO,MAAM,4BAA4B,IAAI,CAAC;AAE9C,MAAM,MAAM,wBAAwB,GAAG;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG;IACvC,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAC1B,QAAQ,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACzD,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,qBAAa,oBAAqB,SAAQ,KAAK;aAE3B,MAAM,EAAE,iBAAiB,GAAG,qBAAqB,GAAG,aAAa,GAAG,aAAa;aAEjF,OAAO,EAAE,mBAAmB,EAAE;gBAF9B,MAAM,EAAE,iBAAiB,GAAG,qBAAqB,GAAG,aAAa,GAAG,aAAa,EACjG,OAAO,EAAE,MAAM,EACC,OAAO,GAAE,mBAAmB,EAAO;CAKtD;AAiBD,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,SAAS,aAAa,GAAG,aAAa,EACzF,KAAK,EAAE,IAAI,CAAC,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,GACvD,0BAA0B,GAAG,IAAI,CA6DnC;AAED,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,SAAS,aAAa,GAAG,aAAa,EAC1F,KAAK,EAAE,IAAI,CAAC,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,GACvD,IAAI,CAEN;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAQ/D;AA6FD,wBAAsB,cAAc,CAClC,OAAO,EAAE,WAAW,EACpB,KAAK,EAAE;IAAE,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,mBAAmB,CAAC,QAAQ,CAAC,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GACnH,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAYhC;AAED,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,WAAW,EAAE,KAAK,GAAE;IAAE,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAK1K;AAED,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE;IACpE,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GAAG,OAAO,CAAC,wBAAwB,EAAE,CAAC,CAwCtC;AAED,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE;IACtE,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAMtC;AAED,wBAAsB,wBAAwB,CAAC,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE;IAC1E,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,GAAG,OAAO,CAAC,IAAI,CAAC,CAOhB;AAED,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,SAAS,aAAa,GAAG,aAAa,EAAE,KAAK,EAAE;IAChG,yEAAyE;IACzE,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,OAAO,EAAE,WAAW,CAAC;IACrB,KAAK,EAAE,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IACjC,OAAO,EAAE,uBAAuB,CAAC;IACjC,eAAe,EAAE,mBAAmB,CAAC,iBAAiB,CAAC,CAAC;IACxD,yBAAyB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,GAAG,OAAO,CAAC,sBAAsB,GAAG;IAAE,GAAG,EAAE,mBAAmB,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAAC,CA8EvF;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,uBAAuB,CAAC,GAAG,EAAE,MAAM,SAAS,aAAa,GAAG,aAAa,EAAE,KAAK,EAAE;IACtG,yEAAyE;IACzE,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,OAAO,EAAE,WAAW,CAAC;IACrB,KAAK,EAAE,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IACjC,yBAAyB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,GAAG,OAAO,CAAC,KAAK,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC,CA4CvE;AAED,wBAAsB,eAAe,CAAC,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE;IAAE,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC;IAAE,SAAS,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,mBAAmB,GAAG,IAAI,CAAA;CAAE,CAAC,CAUzN;AAED,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE;IAAE,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC;IAAE,SAAS,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,mBAAmB,GAAG,IAAI,CAAA;CAAE,CAAC,CAS5N;AAED,wBAAsB,eAAe,CAAC,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE;IACjE,yEAAyE;IACzE,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,YAAY,GAAG,WAAW,CAAC;IACnC,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,GAAG,OAAO,CAAC,IAAI,CAAC,CAShB;AAED,KAAK,aAAa,CAAC,GAAG,EAAE,MAAM,SAAS,aAAa,IAAI;IACtD,KAAK,EAAE,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IACjC,SAAS,EAAE,qBAAqB,CAAC;IACjC,OAAO,EAAE,WAAW,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9D,CAAC;AAUF,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,SAAS,aAAa,GAAG,aAAa,EAAE,KAAK,EAAE,aAAa,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,gBAAgB,EAAE,CAmG9I"}