@elizaos/agent 2.0.3-beta.2 → 2.0.3-beta.3

package/services/approval/sql.js

@@ -0,0 +1,104 @@
+/**
+ * Self-contained raw-SQL helpers for the runtime approval queue.
+ *
+ * The approval store issues raw SQL against the agent's database adapter over
+ * the `approval_requests` table owned by `@elizaos/plugin-sql` (public schema).
+ * This is the minimal subset of encoders/parsers/runners the store needs; it is
+ * intentionally local to `@elizaos/agent` so the runtime approval queue carries
+ * no dependency on plugin-side SQL glue. Mirrors `knowledge-graph/sql.ts`.
+ */
+let cachedSqlRaw = null;
+function asObject(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    return value;
+}
+export function toText(value, fallback = "") {
+    if (typeof value === "string")
+        return value;
+    if (value === null || value === undefined)
+        return fallback;
+    return String(value);
+}
+function isMissingJsonValue(value) {
+    return value === null || value === undefined || value === "";
+}
+function parseJsonValue(value, fallback) {
+    if (isMissingJsonValue(value))
+        return fallback;
+    if (typeof value !== "string") {
+        if (typeof value === "object")
+            return value;
+        throw new Error(`[ApprovalSql] Expected JSON string or object, received ${typeof value}`);
+    }
+    try {
+        return JSON.parse(value);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`[ApprovalSql] Invalid JSON value: ${message}`);
+    }
+}
+export function parseJsonRecord(value) {
+    if (isMissingJsonValue(value))
+        return {};
+    const parsed = parseJsonValue(value, null);
+    const object = asObject(parsed);
+    if (object)
+        return object;
+    throw new Error("[ApprovalSql] Expected JSON object");
+}
+function extractRows(result) {
+    if (Array.isArray(result)) {
+        return result
+            .map((row) => asObject(row))
+            .filter((row) => row !== null);
+    }
+    const object = asObject(result);
+    if (!object)
+        return [];
+    const rows = object.rows;
+    if (!Array.isArray(rows))
+        return [];
+    return rows
+        .map((row) => asObject(row))
+        .filter((row) => row !== null);
+}
+async function getSqlRaw() {
+    if (cachedSqlRaw)
+        return cachedSqlRaw;
+    const drizzle = (await import("drizzle-orm"));
+    cachedSqlRaw = drizzle.sql.raw;
+    return cachedSqlRaw;
+}
+function getRuntimeDb(runtime) {
+    const db = runtime.adapter.db;
+    if (!db || typeof db.execute !== "function") {
+        throw new Error("runtime database adapter unavailable");
+    }
+    return db;
+}
+export async function executeRawSql(runtime, sqlText) {
+    const raw = await getSqlRaw();
+    const db = getRuntimeDb(runtime);
+    const result = await db.execute(raw(sqlText));
+    return extractRows(result);
+}
+export function sqlQuote(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}
+export function sqlText(value) {
+    if (value === null || value === undefined)
+        return "NULL";
+    return sqlQuote(value);
+}
+export function sqlInteger(value) {
+    if (value === null || value === undefined)
+        return "NULL";
+    if (!Number.isFinite(value))
+        throw new Error("invalid numeric SQL literal");
+    return String(Math.trunc(value));
+}
+export function sqlJson(value) {
+    return sqlQuote(JSON.stringify(value ?? null));
+}

package/services/approval/store.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `PgApprovalQueue` — concrete approval queue backed by the `approval_requests`
+ * table from `@elizaos/plugin-sql` (public schema, no schema prefix).
+ *
+ * Promoted from `@elizaos/plugin-personal-assistant`'s `lifeops/approval-queue.ts`
+ * into a first-class `@elizaos/agent` runtime store (LifeOps Slice 4). The raw
+ * SQL is unchanged — it has no schema prefix, so it targets plugin-sql's public
+ * `approval_requests` table exactly as before. There is no data migration.
+ *
+ * Design notes:
+ *  - The state-transition table below is the single source of truth for
+ *    legal moves. Anything not enumerated throws
+ *    `ApprovalStateTransitionError` — there is no fallback, no auto-retry,
+ *    no silent normalization (Commandment 8).
+ *  - All logging goes through the structured logger only (Commandment 9).
+ *  - Each row is scoped to an agent via `agentId`. Cross-agent access is
+ *    not supported.
+ */
+import { type IAgentRuntime } from "@elizaos/core";
+import { type ApprovalEnqueueInput, type ApprovalListFilter, type ApprovalQueue, type ApprovalQueueOptions, type ApprovalRequest, type ApprovalResolution } from "./types.js";
+export declare class PgApprovalQueue implements ApprovalQueue {
+    private readonly runtime;
+    private readonly agentId;
+    constructor(runtime: IAgentRuntime, options: ApprovalQueueOptions);
+    enqueue(input: ApprovalEnqueueInput): Promise<ApprovalRequest>;
+    list(filter: ApprovalListFilter): Promise<ReadonlyArray<ApprovalRequest>>;
+    byId(id: string): Promise<ApprovalRequest | null>;
+    approve(id: string, resolution: ApprovalResolution): Promise<ApprovalRequest>;
+    reject(id: string, resolution: ApprovalResolution): Promise<ApprovalRequest>;
+    markExecuting(id: string): Promise<ApprovalRequest>;
+    markDone(id: string): Promise<ApprovalRequest>;
+    markExpired(id: string): Promise<ApprovalRequest>;
+    purgeExpired(now: Date): Promise<ReadonlyArray<string>>;
+    private fetchById;
+    private transitionWithResolution;
+    private transitionWithoutResolution;
+}
+export declare function createApprovalQueue(runtime: IAgentRuntime, options: ApprovalQueueOptions): ApprovalQueue;
+//# sourceMappingURL=store.d.ts.map

package/services/approval/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/services/approval/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,EAAE,KAAK,aAAa,EAAuB,MAAM,eAAe,CAAC;AASxE,OAAO,EAGL,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EAGvB,KAAK,aAAa,EAClB,KAAK,oBAAoB,EACzB,KAAK,eAAe,EAEpB,KAAK,kBAAkB,EAExB,MAAM,YAAY,CAAC;AA8gBpB,qBAAa,eAAgB,YAAW,aAAa;IACnD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;IACxC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,oBAAoB;IAK3D,OAAO,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,eAAe,CAAC;IAqD9D,IAAI,CACR,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAAC,aAAa,CAAC,eAAe,CAAC,CAAC;IAmBpC,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAKjD,OAAO,CACX,EAAE,EAAE,MAAM,EACV,UAAU,EAAE,kBAAkB,GAC7B,OAAO,CAAC,eAAe,CAAC;IAIrB,MAAM,CACV,EAAE,EAAE,MAAM,EACV,UAAU,EAAE,kBAAkB,GAC7B,OAAO,CAAC,eAAe,CAAC;IAIrB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAInD,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAI9C,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAIjD,YAAY,CAAC,GAAG,EAAE,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;YAe/C,SAAS;YAST,wBAAwB;YA2BxB,2BAA2B;CAoB1C;AAED,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,oBAAoB,GAC5B,aAAa,CAEf"}

package/services/approval/store.js

@@ -0,0 +1,534 @@
+/**
+ * `PgApprovalQueue` — concrete approval queue backed by the `approval_requests`
+ * table from `@elizaos/plugin-sql` (public schema, no schema prefix).
+ *
+ * Promoted from `@elizaos/plugin-personal-assistant`'s `lifeops/approval-queue.ts`
+ * into a first-class `@elizaos/agent` runtime store (LifeOps Slice 4). The raw
+ * SQL is unchanged — it has no schema prefix, so it targets plugin-sql's public
+ * `approval_requests` table exactly as before. There is no data migration.
+ *
+ * Design notes:
+ *  - The state-transition table below is the single source of truth for
+ *    legal moves. Anything not enumerated throws
+ *    `ApprovalStateTransitionError` — there is no fallback, no auto-retry,
+ *    no silent normalization (Commandment 8).
+ *  - All logging goes through the structured logger only (Commandment 9).
+ *  - Each row is scoped to an agent via `agentId`. Cross-agent access is
+ *    not supported.
+ */
+import { randomUUID } from "node:crypto";
+import { logger, ServiceType } from "@elizaos/core";
+import { executeRawSql, parseJsonRecord, sqlInteger, sqlJson, sqlText, toText, } from "./sql.js";
+import { ApprovalNotFoundError, ApprovalStateTransitionError, } from "./types.js";
+const ALLOWED_TRANSITIONS = {
+    pending: ["approved", "rejected", "expired"],
+    approved: ["executing", "rejected"],
+    executing: ["done"],
+    done: [],
+    rejected: [],
+    expired: [],
+};
+function assertTransition(id, from, to) {
+    if (!ALLOWED_TRANSITIONS[from].includes(to)) {
+        throw new ApprovalStateTransitionError(id, from, to);
+    }
+}
+const VALID_STATES = new Set([
+    "pending",
+    "approved",
+    "executing",
+    "done",
+    "rejected",
+    "expired",
+]);
+const VALID_ACTIONS = new Set([
+    "send_message",
+    "send_email",
+    "schedule_event",
+    "modify_event",
+    "cancel_event",
+    "book_travel",
+    "make_call",
+    "sign_document",
+    "execute_workflow",
+    "spend_money",
+]);
+const VALID_CHANNELS = new Set([
+    "telegram",
+    "discord",
+    "slack",
+    "imessage",
+    "sms",
+    "x_dm",
+    "email",
+    "google_calendar",
+    "browser",
+    "phone",
+    "internal",
+]);
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function parseState(value) {
+    const text = toText(value);
+    if (!VALID_STATES.has(text)) {
+        throw new Error(`[ApprovalQueue] unknown state from db: ${text}`);
+    }
+    return text;
+}
+function parseAction(value) {
+    const text = toText(value);
+    if (!VALID_ACTIONS.has(text)) {
+        throw new Error(`[ApprovalQueue] unknown action from db: ${text}`);
+    }
+    return text;
+}
+function parseChannel(value) {
+    const text = toText(value);
+    if (!VALID_CHANNELS.has(text)) {
+        throw new Error(`[ApprovalQueue] unknown channel from db: ${text}`);
+    }
+    return text;
+}
+function parseTimestamp(value) {
+    if (value instanceof Date)
+        return value;
+    const text = toText(value);
+    if (!text) {
+        throw new Error("[ApprovalQueue] missing timestamp from db");
+    }
+    const date = new Date(text);
+    if (Number.isNaN(date.getTime())) {
+        throw new Error(`[ApprovalQueue] invalid timestamp from db: ${text}`);
+    }
+    return date;
+}
+function parseOptionalTimestamp(value) {
+    if (value === null || value === undefined || value === "")
+        return null;
+    return parseTimestamp(value);
+}
+function parseOptionalText(value) {
+    if (value === null || value === undefined)
+        return null;
+    const text = toText(value);
+    return text === "" ? null : text;
+}
+function requireRecord(value, label) {
+    if (!isRecord(value)) {
+        throw new Error(`[ApprovalQueue] invalid ${label}: expected object`);
+    }
+    return value;
+}
+function requireStringField(record, field, label) {
+    if (typeof record[field] !== "string") {
+        throw new Error(`[ApprovalQueue] invalid ${label}.${field}: expected string`);
+    }
+}
+function requireNullableStringField(record, field, label) {
+    const value = record[field];
+    if (value !== null && typeof value !== "string") {
+        throw new Error(`[ApprovalQueue] invalid ${label}.${field}: expected string or null`);
+    }
+}
+function requireOptionalNullableStringField(record, field, label) {
+    if (record[field] === undefined) {
+        return;
+    }
+    requireNullableStringField(record, field, label);
+}
+function requireStringArrayField(record, field, label) {
+    const value = record[field];
+    if (!Array.isArray(value) ||
+        value.some((entry) => typeof entry !== "string")) {
+        throw new Error(`[ApprovalQueue] invalid ${label}.${field}: expected string[]`);
+    }
+}
+function requireFiniteNumberField(record, field, label) {
+    const value = record[field];
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new Error(`[ApprovalQueue] invalid ${label}.${field}: expected number`);
+    }
+}
+function requireNullableFiniteNumberField(record, field, label) {
+    const value = record[field];
+    if (value !== null &&
+        (typeof value !== "number" || !Number.isFinite(value))) {
+        throw new Error(`[ApprovalQueue] invalid ${label}.${field}: expected number or null`);
+    }
+}
+function requireBooleanField(record, field, label) {
+    if (typeof record[field] !== "boolean") {
+        throw new Error(`[ApprovalQueue] invalid ${label}.${field}: expected boolean`);
+    }
+}
+function requireOptionalRecordField(record, field, label) {
+    const value = record[field];
+    if (value !== undefined && value !== null && !isRecord(value)) {
+        throw new Error(`[ApprovalQueue] invalid ${label}.${field}: expected object or null`);
+    }
+}
+function requirePrimitiveRecordField(record, field, label) {
+    const value = requireRecord(record[field], `${label}.${field}`);
+    for (const [key, entry] of Object.entries(value)) {
+        if (typeof entry !== "string" &&
+            typeof entry !== "number" &&
+            typeof entry !== "boolean") {
+            throw new Error(`[ApprovalQueue] invalid ${label}.${field}.${key}: expected string, number, or boolean`);
+        }
+    }
+}
+function requireTravelPassengers(record, label) {
+    const passengers = record.passengers;
+    if (passengers === undefined) {
+        return;
+    }
+    if (!Array.isArray(passengers)) {
+        throw new Error(`[ApprovalQueue] invalid ${label}.passengers: expected array`);
+    }
+    passengers.forEach((passenger, index) => {
+        const passengerRecord = requireRecord(passenger, `${label}.passengers[${index}]`);
+        requireStringField(passengerRecord, "givenName", `${label}.passengers[${index}]`);
+        requireStringField(passengerRecord, "familyName", `${label}.passengers[${index}]`);
+        requireStringField(passengerRecord, "bornOn", `${label}.passengers[${index}]`);
+        for (const field of [
+            "offerPassengerId",
+            "email",
+            "phoneNumber",
+            "title",
+            "gender",
+        ]) {
+            requireOptionalNullableStringField(passengerRecord, field, `${label}.passengers[${index}]`);
+        }
+    });
+}
+function requireTravelCalendarSync(record, label) {
+    const value = record.calendarSync;
+    if (value === undefined || value === null) {
+        return;
+    }
+    const calendarSync = requireRecord(value, `${label}.calendarSync`);
+    requireBooleanField(calendarSync, "enabled", `${label}.calendarSync`);
+    for (const field of [
+        "calendarId",
+        "title",
+        "description",
+        "location",
+        "timeZone",
+    ]) {
+        requireOptionalNullableStringField(calendarSync, field, `${label}.calendarSync`);
+    }
+}
+function requireTravelCost(record, label) {
+    const value = record.cost;
+    if (value === undefined || value === null) {
+        return;
+    }
+    const cost = requireRecord(value, `${label}.cost`);
+    requireFiniteNumberField(cost, "totalUsd", `${label}.cost`);
+    requireFiniteNumberField(cost, "creatorMarkupUsd", `${label}.cost`);
+    requireFiniteNumberField(cost, "platformFeeUsd", `${label}.cost`);
+    requireNullableFiniteNumberField(cost, "markupPercent", `${label}.cost`);
+}
+function requirePaymentRequired(record, label) {
+    const value = record.paymentRequired;
+    if (value === undefined || value === null) {
+        return;
+    }
+    const payment = requireRecord(value, `${label}.paymentRequired`);
+    for (const field of ["amount", "asset", "network", "payTo", "scheme"]) {
+        requireStringField(payment, field, `${label}.paymentRequired`);
+    }
+    requireNullableStringField(payment, "expiresAt", `${label}.paymentRequired`);
+    requireNullableStringField(payment, "description", `${label}.paymentRequired`);
+}
+function assertApprovalPayload(record, action, label) {
+    switch (action) {
+        case "send_message":
+            requireStringField(record, "recipient", label);
+            requireStringField(record, "body", label);
+            requireNullableStringField(record, "replyToMessageId", label);
+            break;
+        case "send_email":
+            requireStringArrayField(record, "to", label);
+            requireStringArrayField(record, "cc", label);
+            requireStringArrayField(record, "bcc", label);
+            requireStringField(record, "subject", label);
+            requireStringField(record, "body", label);
+            requireNullableStringField(record, "threadId", label);
+            requireOptionalNullableStringField(record, "replyToMessageId", label);
+            break;
+        case "schedule_event":
+            requireStringField(record, "calendarId", label);
+            requireStringField(record, "title", label);
+            requireFiniteNumberField(record, "startsAtMs", label);
+            requireFiniteNumberField(record, "endsAtMs", label);
+            requireStringArrayField(record, "attendees", label);
+            requireNullableStringField(record, "location", label);
+            requireNullableStringField(record, "description", label);
+            break;
+        case "modify_event": {
+            requireStringField(record, "calendarId", label);
+            requireStringField(record, "eventId", label);
+            const patch = requireRecord(record.patch, `${label}.patch`);
+            requireNullableStringField(patch, "title", `${label}.patch`);
+            requireNullableFiniteNumberField(patch, "startsAtMs", `${label}.patch`);
+            requireNullableFiniteNumberField(patch, "endsAtMs", `${label}.patch`);
+            const attendees = patch.attendees;
+            if (attendees !== null &&
+                (!Array.isArray(attendees) ||
+                    attendees.some((entry) => typeof entry !== "string"))) {
+                throw new Error(`[ApprovalQueue] invalid ${label}.patch.attendees: expected string[] or null`);
+            }
+            requireNullableStringField(patch, "location", `${label}.patch`);
+            requireNullableStringField(patch, "description", `${label}.patch`);
+            break;
+        }
+        case "cancel_event":
+            requireStringField(record, "calendarId", label);
+            requireStringField(record, "eventId", label);
+            requireBooleanField(record, "notifyAttendees", label);
+            break;
+        case "book_travel":
+            if (record.kind !== "flight" &&
+                record.kind !== "hotel" &&
+                record.kind !== "ground") {
+                throw new Error(`[ApprovalQueue] invalid ${label}.kind`);
+            }
+            requireStringField(record, "provider", label);
+            requireStringField(record, "itineraryRef", label);
+            requireFiniteNumberField(record, "totalCents", label);
+            requireStringField(record, "currency", label);
+            requireOptionalNullableStringField(record, "offerId", label);
+            requireOptionalNullableStringField(record, "offerRequestId", label);
+            if (record.orderType !== undefined &&
+                record.orderType !== null &&
+                record.orderType !== "hold" &&
+                record.orderType !== "instant") {
+                throw new Error(`[ApprovalQueue] invalid ${label}.orderType`);
+            }
+            requireOptionalRecordField(record, "search", label);
+            requireTravelPassengers(record, label);
+            requireTravelCalendarSync(record, label);
+            requireOptionalNullableStringField(record, "summary", label);
+            requireTravelCost(record, label);
+            requirePaymentRequired(record, label);
+            break;
+        case "make_call":
+            requireStringField(record, "to", label);
+            requireStringField(record, "script", label);
+            requireFiniteNumberField(record, "maxDurationSeconds", label);
+            break;
+        case "sign_document":
+            requireStringField(record, "documentId", label);
+            requireStringField(record, "documentName", label);
+            requireStringField(record, "signatureUrl", label);
+            requireStringField(record, "deadline", label);
+            break;
+        case "execute_workflow":
+            requireStringField(record, "workflowId", label);
+            requirePrimitiveRecordField(record, "input", label);
+            break;
+        case "spend_money":
+            requireStringField(record, "vendor", label);
+            requireFiniteNumberField(record, "amountCents", label);
+            requireStringField(record, "currency", label);
+            requireStringField(record, "memo", label);
+            break;
+    }
+}
+function validateApprovalPayload(value, label) {
+    const record = requireRecord(value, label);
+    const action = parseAction(record.action);
+    assertApprovalPayload(record, action, label);
+    return record;
+}
+function rowToRequest(row) {
+    const action = parseAction(row.action);
+    const payload = validateApprovalPayload(parseJsonRecord(row.payload), `row ${toText(row.id)} payload`);
+    if (payload.action !== action) {
+        throw new Error(`[ApprovalQueue] row ${toText(row.id)} payload action ${payload.action} does not match request action ${action}`);
+    }
+    return {
+        id: toText(row.id),
+        createdAt: parseTimestamp(row.created_at),
+        updatedAt: parseTimestamp(row.updated_at),
+        state: parseState(row.state),
+        requestedBy: toText(row.requested_by),
+        subjectUserId: toText(row.subject_user_id),
+        action,
+        payload,
+        channel: parseChannel(row.channel),
+        reason: toText(row.reason),
+        expiresAt: parseTimestamp(row.expires_at),
+        resolvedAt: parseOptionalTimestamp(row.resolved_at),
+        resolvedBy: parseOptionalText(row.resolved_by),
+        resolutionReason: parseOptionalText(row.resolution_reason),
+    };
+}
+const SELECT_COLUMNS = "id, state, requested_by, subject_user_id, action, payload, channel, reason, expires_at, resolved_at, resolved_by, resolution_reason, created_at, updated_at";
+function timestampLiteral(date) {
+    return sqlText(date.toISOString());
+}
+function getNotifier(runtime) {
+    const svc = runtime.getService(ServiceType.NOTIFICATION);
+    return svc && typeof svc.notify === "function" ? svc : null;
+}
+export class PgApprovalQueue {
+    runtime;
+    agentId;
+    constructor(runtime, options) {
+        this.runtime = runtime;
+        this.agentId = options.agentId;
+    }
+    async enqueue(input) {
+        const payload = validateApprovalPayload(input.payload, "enqueue payload");
+        if (input.action !== payload.action) {
+            throw new Error(`[ApprovalQueue] payload action ${payload.action} does not match request action ${input.action}`);
+        }
+        const id = randomUUID();
+        const now = new Date();
+        const sql = `INSERT INTO approval_requests (
+        id, state, requested_by, subject_user_id, action, payload, channel, reason,
+        expires_at, resolved_at, resolved_by, resolution_reason,
+        agent_id, created_at, updated_at
+      ) VALUES (
+        ${sqlText(id)},
+        ${sqlText("pending")},
+        ${sqlText(input.requestedBy)},
+        ${sqlText(input.subjectUserId)},
+        ${sqlText(input.action)},
+        ${sqlJson(payload)},
+        ${sqlText(input.channel)},
+        ${sqlText(input.reason)},
+        ${timestampLiteral(input.expiresAt)},
+        NULL, NULL, NULL,
+        ${sqlText(this.agentId)},
+        ${timestampLiteral(now)},
+        ${timestampLiteral(now)}
+      ) RETURNING ${SELECT_COLUMNS}`;
+        const rows = await executeRawSql(this.runtime, sql);
+        if (rows.length === 0) {
+            throw new Error("[ApprovalQueue] enqueue returned no rows");
+        }
+        logger.info(`[ApprovalQueue] enqueued ${input.action} for ${input.subjectUserId} as ${id}`);
+        // An outbound action now needs the owner's go-ahead. Surface it on the
+        // notification rail so the owner can act without watching the queue
+        // (fire-and-forget; a notify failure must not block the enqueue).
+        void getNotifier(this.runtime)
+            ?.notify({
+            title: "Approval needed",
+            body: input.reason.slice(0, 200),
+            category: "approval",
+            priority: "high",
+            source: "lifeops",
+            deepLink: "/chat",
+            groupKey: `approval:${id}`,
+            data: { requestId: id, kind: input.action },
+        })
+            .catch(() => { });
+        return rowToRequest(rows[0]);
+    }
+    async list(filter) {
+        const where = [`agent_id = ${sqlText(this.agentId)}`];
+        if (filter.subjectUserId !== null) {
+            where.push(`subject_user_id = ${sqlText(filter.subjectUserId)}`);
+        }
+        if (filter.state !== null) {
+            where.push(`state = ${sqlText(filter.state)}`);
+        }
+        if (filter.action !== null) {
+            where.push(`action = ${sqlText(filter.action)}`);
+        }
+        const sql = `SELECT ${SELECT_COLUMNS} FROM approval_requests
+      WHERE ${where.join(" AND ")}
+      ORDER BY created_at DESC
+      LIMIT ${sqlInteger(filter.limit)}`;
+        const rows = await executeRawSql(this.runtime, sql);
+        return rows.map(rowToRequest);
+    }
+    async byId(id) {
+        const rows = await this.fetchById(id);
+        return rows ?? null;
+    }
+    async approve(id, resolution) {
+        return this.transitionWithResolution(id, "approved", resolution);
+    }
+    async reject(id, resolution) {
+        return this.transitionWithResolution(id, "rejected", resolution);
+    }
+    async markExecuting(id) {
+        return this.transitionWithoutResolution(id, "executing");
+    }
+    async markDone(id) {
+        return this.transitionWithoutResolution(id, "done");
+    }
+    async markExpired(id) {
+        return this.transitionWithoutResolution(id, "expired");
+    }
+    async purgeExpired(now) {
+        const sql = `UPDATE approval_requests
+      SET state = ${sqlText("expired")}, updated_at = ${timestampLiteral(now)}
+      WHERE agent_id = ${sqlText(this.agentId)}
+        AND state = ${sqlText("pending")}
+        AND expires_at <= ${timestampLiteral(now)}
+      RETURNING id`;
+        const rows = await executeRawSql(this.runtime, sql);
+        const ids = rows.map((row) => toText(row.id));
+        if (ids.length > 0) {
+            logger.info(`[ApprovalQueue] purged ${ids.length} expired requests`);
+        }
+        return ids;
+    }
+    async fetchById(id) {
+        const sql = `SELECT ${SELECT_COLUMNS} FROM approval_requests
+      WHERE id = ${sqlText(id)} AND agent_id = ${sqlText(this.agentId)}
+      LIMIT 1`;
+        const rows = await executeRawSql(this.runtime, sql);
+        if (rows.length === 0)
+            return null;
+        return rowToRequest(rows[0]);
+    }
+    async transitionWithResolution(id, target, resolution) {
+        const current = await this.fetchById(id);
+        if (!current)
+            throw new ApprovalNotFoundError(id);
+        assertTransition(id, current.state, target);
+        const now = new Date();
+        const sql = `UPDATE approval_requests
+      SET state = ${sqlText(target)},
+          resolved_at = ${timestampLiteral(now)},
+          resolved_by = ${sqlText(resolution.resolvedBy)},
+          resolution_reason = ${sqlText(resolution.resolutionReason)},
+          updated_at = ${timestampLiteral(now)}
+      WHERE id = ${sqlText(id)} AND agent_id = ${sqlText(this.agentId)}
+      RETURNING ${SELECT_COLUMNS}`;
+        const rows = await executeRawSql(this.runtime, sql);
+        if (rows.length === 0) {
+            throw new ApprovalNotFoundError(id);
+        }
+        logger.info(`[ApprovalQueue] ${current.state} -> ${target} (${id}) by ${resolution.resolvedBy}`);
+        return rowToRequest(rows[0]);
+    }
+    async transitionWithoutResolution(id, target) {
+        const current = await this.fetchById(id);
+        if (!current)
+            throw new ApprovalNotFoundError(id);
+        assertTransition(id, current.state, target);
+        const now = new Date();
+        const sql = `UPDATE approval_requests
+      SET state = ${sqlText(target)},
+          updated_at = ${timestampLiteral(now)}
+      WHERE id = ${sqlText(id)} AND agent_id = ${sqlText(this.agentId)}
+      RETURNING ${SELECT_COLUMNS}`;
+        const rows = await executeRawSql(this.runtime, sql);
+        if (rows.length === 0) {
+            throw new ApprovalNotFoundError(id);
+        }
+        logger.info(`[ApprovalQueue] ${current.state} -> ${target} (${id})`);
+        return rowToRequest(rows[0]);
+    }
+}
+export function createApprovalQueue(runtime, options) {
+    return new PgApprovalQueue(runtime, options);
+}