@relaycast/engine 8.7.0 → 8.9.0

package/dist/engine/rowidRetention.d.ts

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+import type { EngineDb } from '../ports/database.js';
+import type { PruneOptions, PruneResult } from './retention.js';
+declare const stateSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    next: z.ZodNumber;
+    tables: z.ZodRecord<z.ZodString, z.ZodObject<{
+        cursor: z.ZodOptional<z.ZodNumber>;
+        high: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type RowidRetentionState = z.infer<typeof stateSchema>;
+/**
+ * Host-owned durable state for the schema-free retention path. Hosts must
+ * serialize maintenance calls for a database, and `save` must resolve only
+ * after the checkpoint is durable. This path creates no engine table or index.
+ */
+export interface RetentionCursorStore {
+    load(): Promise<unknown>;
+    save(state: RowidRetentionState): Promise<void>;
+}
+/** Worst-case statement count for one cursor-store invocation, below D1's 1000-query ceiling. */
+export declare const ROWID_RETENTION_D1_QUERY_CEILING: number;
+/**
+ * Schema-free recovery mode. It pages by SQLite rowid before policy and
+ * eligibility filtering, so retained history cannot turn a bounded run into a
+ * full scan. A saved high-water mark makes each traversal finite under writes.
+ */
+export declare function pruneRowidPages(db: EngineDb, opts: PruneOptions & {
+    cursorStore: RetentionCursorStore;
+}): Promise<PruneResult>;
+export {};
+//# sourceMappingURL=rowidRetention.d.ts.map

package/dist/engine/rowidRetention.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rowidRetention.d.ts","sourceRoot":"","sources":["../../src/engine/rowidRetention.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAErD,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAqB,MAAM,gBAAgB,CAAC;AAInF,QAAA,MAAM,WAAW;;;;;;;iBAIf,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAE9D;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IACzB,IAAI,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjD;AAgDD,iGAAiG;AACjG,eAAO,MAAM,gCAAgC,QAEP,CAAC;AAqDvC;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,EAAE,EAAE,QAAQ,EACZ,IAAI,EAAE,YAAY,GAAG;IAAE,WAAW,EAAE,oBAAoB,CAAA;CAAE,GACzD,OAAO,CAAC,WAAW,CAAC,CAuGtB"}

package/dist/engine/rowidRetention.js

@@ -0,0 +1,190 @@
+import { sql } from 'drizzle-orm';
+import { z } from 'zod';
+import { snowflakeIdLowerBound } from './snowflake.js';
+const safeRowid = z.number().int().min(Number.MIN_SAFE_INTEGER).max(Number.MAX_SAFE_INTEGER);
+const stateSchema = z.object({
+    version: z.literal(1),
+    next: z.number().int().min(0).max(4),
+    tables: z.record(z.string(), z.object({ cursor: safeRowid.optional(), high: safeRowid.optional() })),
+});
+const SETTLED_DELIVERIES = "deliveries.status IN ('acked', 'failed', 'dead_lettered')";
+const DEFAULT_EXPIRED_DELIVERY_GRACE_DAYS = 7;
+const MAX_ACTIVE_EXPIRY_RECOVERY_BATCHES = 4;
+const ACTIVE_EXPIRY_RECOVERY_DELETE_LIMIT = 1_000;
+const ROWID_PAGE_LIMIT = 200;
+const ROWID_MAX_BATCHES_PER_TABLE = 5;
+const ROWID_DELETE_CHUNK_SIZE = 10;
+const tables = [
+    { name: 'messages', result: 'messages', columns: 'id, workspace_id',
+        setting: 'message_ttl_days', fallback: 'messageTtlDays', snowflake: true,
+        guard: 'NOT EXISTS (SELECT 1 FROM messages replies WHERE replies.thread_id = messages.id)' },
+    { name: 'deliveries', result: 'deliveries', columns: 'id, workspace_id, created_at, status, expires_at',
+        setting: 'delivery_ttl_days', fallback: 'deliveryTtlDays', guard: SETTLED_DELIVERIES },
+    { name: 'message_logs', result: 'messageLogs', columns: 'id, workspace_id',
+        setting: 'message_log_ttl_days', fallback: 'messageLogTtlDays', snowflake: true, guard: '1' },
+    { name: 'workspace_events', result: 'workspaceEvents', columns: 'workspace_id, seq, created_at',
+        setting: 'workspace_event_ttl_days', fallback: 'workspaceEventTtlDays',
+        guard: 'EXISTS (SELECT 1 FROM workspace_events hw WHERE hw.workspace_id = workspace_events.workspace_id AND hw.seq > workspace_events.seq LIMIT 1)' },
+    { name: 'read_receipts', result: 'readReceipts', columns: 'message_id, agent_id',
+        guard: 'NOT EXISTS (SELECT 1 FROM messages m WHERE m.id = read_receipts.message_id)' },
+];
+/** Worst-case statement count for one cursor-store invocation, below D1's 1000-query ceiling. */
+export const ROWID_RETENTION_D1_QUERY_CEILING = tables.length * (1 + ROWID_MAX_BATCHES_PER_TABLE + ROWID_MAX_BATCHES_PER_TABLE * Math.ceil(ROWID_PAGE_LIMIT / ROWID_DELETE_CHUNK_SIZE)) + MAX_ACTIVE_EXPIRY_RECOVERY_BATCHES;
+/** Delete only long-expired active deliveries through the existing bounded index. */
+async function recoverExpiredActiveDeliveries(db, nowMs, graceDays, maxBatches) {
+    const cutoffSeconds = Math.floor((nowMs - Math.max(0, Math.floor(graceDays * 86_400_000))) / 1_000);
+    const batches = bounded(maxBatches, MAX_ACTIVE_EXPIRY_RECOVERY_BATCHES, MAX_ACTIVE_EXPIRY_RECOVERY_BATCHES);
+    let deleted = 0;
+    for (let batch = 0; batch < batches; batch++) {
+        // This is the pre-existing global active-expiry index from migration 0031;
+        // the outer predicate repeats every condition so extension/status races are safe.
+        const changed = await db.all(sql `
+      DELETE FROM deliveries
+      WHERE status IN ('queued', 'delivered')
+        AND expires_at IS NOT NULL AND expires_at < ${cutoffSeconds}
+        AND id IN (
+          SELECT id FROM deliveries INDEXED BY idx_deliveries_active_expiry
+          WHERE status IN ('queued', 'delivered')
+            AND expires_at IS NOT NULL AND expires_at < ${cutoffSeconds}
+          ORDER BY expires_at, id LIMIT ${ACTIVE_EXPIRY_RECOVERY_DELETE_LIMIT}
+        )
+      RETURNING id
+    `);
+        deleted += changed.length;
+        if (changed.length < ACTIVE_EXPIRY_RECOVERY_DELETE_LIMIT)
+            break;
+    }
+    return deleted;
+}
+/** Clamp an optional maintenance budget to a positive, finite row count. */
+function bounded(value, fallback, maximum) {
+    return value !== undefined && Number.isFinite(value)
+        ? Math.max(1, Math.min(maximum, Math.floor(value)))
+        : fallback;
+}
+/** Evaluate one candidate against its workspace retention policy and clock. */
+function isExpired(row, table, defaults, nowMs) {
+    if (!table.setting || !table.fallback)
+        return true;
+    const settings = row.retention ? JSON.parse(row.retention) : {};
+    const days = settings[table.setting] === undefined ? defaults[table.fallback] : settings[table.setting];
+    if (days == null || !Number.isFinite(days) || days <= 0)
+        return false;
+    const cutoff = nowMs - days * 86_400_000;
+    if (!Number.isFinite(cutoff))
+        return false;
+    if (!table.snowflake)
+        return row.created_at * 1_000 < cutoff;
+    const bound = snowflakeIdLowerBound(cutoff);
+    return row.id.length < bound.length || (row.id.length === bound.length && row.id < bound);
+}
+/**
+ * Schema-free recovery mode. It pages by SQLite rowid before policy and
+ * eligibility filtering, so retained history cannot turn a bounded run into a
+ * full scan. A saved high-water mark makes each traversal finite under writes.
+ */
+export async function pruneRowidPages(db, opts) {
+    const nowMs = (opts.now ?? new Date()).getTime();
+    if (!Number.isFinite(nowMs))
+        throw new Error('Invalid retention clock');
+    const limit = bounded(opts.batchLimit, ROWID_PAGE_LIMIT, ROWID_PAGE_LIMIT);
+    const pageBudget = bounded(opts.maxBatches, ROWID_MAX_BATCHES_PER_TABLE, ROWID_MAX_BATCHES_PER_TABLE) * tables.length;
+    const deadline = Date.now() + bounded(opts.maxDurationMs, 10_000, 30_000);
+    const defaults = {
+        messageTtlDays: null,
+        deliveryTtlDays: 90,
+        messageLogTtlDays: 90,
+        workspaceEventTtlDays: 30,
+        ...Object.fromEntries(Object.entries(opts.defaults ?? {}).filter(([, value]) => value !== undefined)),
+    };
+    const saved = await opts.cursorStore.load();
+    // Cursor documents are advisory checkpoints owned by the host. A stale,
+    // partial, or legacy document must not take scheduled retention offline, and
+    // must never be trusted to construct a delete predicate. Restarting from an
+    // empty state is safe because every delete below rechecks row identity and
+    // current policy before mutating anything.
+    const parsed = saved == null ? undefined : stateSchema.safeParse(saved);
+    const state = parsed?.success
+        ? parsed.data
+        : { version: 1, next: 0, tables: {} };
+    const save = () => opts.cursorStore.save(structuredClone(state));
+    const result = { messages: 0, deliveries: 0, messageLogs: 0, readReceipts: 0, workspaceEvents: 0 };
+    const finished = new Set();
+    // Active expiry is opt-in because it intentionally skips delivery.failed
+    // fanout; normal scheduled expiry remains the default notification path.
+    if (opts.activeExpiryRecovery === true) {
+        result.deliveries += await recoverExpiredActiveDeliveries(db, nowMs, opts.expiredDeliveryGraceDays ?? DEFAULT_EXPIRED_DELIVERY_GRACE_DAYS, opts.activeExpiryRecoveryMaxBatches ?? MAX_ACTIVE_EXPIRY_RECOVERY_BATCHES);
+    }
+    for (let step = 0; step < pageBudget && Date.now() < deadline; step++) {
+        const index = state.next;
+        state.next = (index + 1) % tables.length;
+        if (finished.has(index))
+            continue;
+        const table = tables[index];
+        await save(); // fairness is durable before an admitted page
+        const position = state.tables[table.name] ??= {};
+        if (Date.now() >= deadline)
+            break;
+        if (position.high === undefined) {
+            const [last] = await db.all(sql `
+        SELECT rowid AS _rowid FROM ${sql.raw(table.name)} NOT INDEXED ORDER BY rowid DESC LIMIT 1
+      `);
+            if (!last) {
+                delete state.tables[table.name];
+                finished.add(index);
+                await save();
+                continue;
+            }
+            position.high = safeRowid.parse(last._rowid);
+        }
+        if (Date.now() >= deadline)
+            break;
+        const page = await db.all(sql `
+      WITH page AS MATERIALIZED (
+        SELECT rowid AS _rowid, ${sql.raw(table.columns)} FROM ${sql.raw(table.name)} NOT INDEXED
+        WHERE rowid <= ${position.high}
+          ${position.cursor === undefined ? sql `` : sql `AND rowid > ${position.cursor}`}
+        ORDER BY rowid LIMIT ${limit}
+      ) SELECT page.*, ${sql.raw(table.guard.replaceAll(table.name + '.', 'page.'))} AS eligible,
+        ${table.setting ? sql `w.retention` : sql `NULL`} AS retention
+      FROM page ${table.setting ? sql `LEFT JOIN workspaces w ON w.id = page.workspace_id` : sql ``}
+      ORDER BY page._rowid
+    `);
+        for (const row of page)
+            safeRowid.parse(row._rowid);
+        const removable = page.filter(row => row.eligible && isExpired(row, table, defaults, nowMs));
+        for (let offset = 0; offset < removable.length; offset += ROWID_DELETE_CHUNK_SIZE) {
+            if (Date.now() >= deadline) {
+                await save();
+                return result;
+            }
+            const chunk = removable.slice(offset, offset + ROWID_DELETE_CHUNK_SIZE);
+            const guards = chunk.map(row => {
+                const identity = table.result === 'workspaceEvents'
+                    ? sql `workspace_id = ${row.workspace_id} AND seq = ${row.seq}`
+                    : table.result === 'readReceipts'
+                        ? sql `message_id = ${row.message_id} AND agent_id = ${row.agent_id}`
+                        : sql `id = ${row.id} AND workspace_id = ${row.workspace_id}`;
+                const policy = table.setting ? sql `AND (SELECT retention FROM workspaces WHERE id = ${row.workspace_id}) IS ${row.retention}` : sql ``;
+                const created = table.setting && !table.snowflake ? sql `AND created_at = ${row.created_at}` : sql ``;
+                const status = table.result === 'deliveries' ? sql `AND status = ${row.status}` : sql ``;
+                return sql `(rowid = ${row._rowid} AND ${identity} ${policy} ${created} ${status})`;
+            });
+            const deleted = await db.all(sql `DELETE FROM ${sql.raw(table.name)} NOT INDEXED
+        WHERE (${sql.join(guards, sql ` OR `)}) AND ${sql.raw(table.guard)} RETURNING 1`);
+            result[table.result] += deleted.length;
+        }
+        if (page.length < limit || page.at(-1)?._rowid === position.high) {
+            delete state.tables[table.name];
+            finished.add(index);
+        }
+        else {
+            position.cursor = page.at(-1)._rowid;
+        }
+        await save();
+        if (finished.size === tables.length)
+            break;
+    }
+    return result;
+}
+//# sourceMappingURL=rowidRetention.js.map

package/dist/engine/rowidRetention.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rowidRetention.js","sourceRoot":"","sources":["../../src/engine/rowidRetention.ts"],"names":[],"mappings":"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"}

package/dist/engine/sessionEvent.d.ts

@@ -1,18 +1,71 @@
 import type { getDb } from '../db/index.js';
+import { sessionEvents } from '../db/schema.js';
 type Db = ReturnType<typeof getDb>;
 export type SessionEventType = 'status.changed' | 'status.idle' | 'status.active' | 'status.blocked' | 'status.waiting' | 'status.offline' | 'tool.called' | 'tool.completed' | 'tool.failed' | 'tool.output' | 'message.received' | 'message.sent' | 'delivery.accepted' | 'delivery.delivered' | 'delivery.deferred' | 'delivery.failed' | 'action.invoked' | 'action.completed' | 'action.failed' | 'action.denied' | 'transcript.chunk' | 'file.changed' | 'command.started' | 'command.completed' | 'command.failed' | 'terminal.output' | 'terminal.screen' | 'usage.updated' | 'session.started' | 'session.released' | 'session.resumed' | 'session.forked' | 'log' | 'error';
 export declare function isValidEventType(type: string): type is SessionEventType;
+/** `status.*` events are the only ones with a side-effecting agent-row mutation to track. */
+export declare function isStatusEventType(type: string): boolean;
+export interface StatusEventEffectResult {
+    /** Whether this request won the durable completion-marker claim. */
+    claimed: boolean;
+    /** Whether the current agent row was actually changed by this event. */
+    mutated: boolean;
+}
 export declare function recordSessionEvent(db: Db, workspaceId: string, agentId: string, data: {
     type: SessionEventType;
     payload: Record<string, unknown>;
 }): Promise<{
+    event: ReturnType<typeof toPublicEvent>;
+    replayed: boolean;
+    pendingStatusApplication: boolean;
+}>;
+/**
+ * Record an event with a durable caller-provided identity.
+ *
+ * The key is hashed before persistence and scoped by workspace + agent in the
+ * unique index. The request digest is retained beside the event so reusing a
+ * key with a different event cannot accidentally replay the first event.
+ */
+export declare function recordSessionEventWithIdempotency(db: Db, workspaceId: string, agentId: string, data: {
+    type: SessionEventType;
+    payload: Record<string, unknown>;
+}, idempotencyKey: string): Promise<{
+    event: ReturnType<typeof toPublicEvent>;
+    replayed: boolean;
+    pendingStatusApplication: boolean;
+}>;
+/**
+ * Apply a `status.*` event's agent-row mutation and claim its completion
+ * durably, as one atomic unit.
+ *
+ * This is the fix for the crash window between "the event/idempotency claim
+ * committed" and "the agent's status row is updated": if either statement
+ * here failed independently, a retry could see `replayed: true` and return
+ * 201 while the agent row stayed stale forever. Batching both writes through
+ * `runAtomicWrites` means a failure here rolls back *both* the status change
+ * and the completion marker, so `pendingStatusApplication` stays true and the
+ * next replay retries the whole mutation — it can never observe "claimed but
+ * never applied" as a terminal state.
+ *
+ * The completion update is the single-winner claim for side effects: a replay
+ * that loses a concurrent claim gets `claimed: false` and must not fan out or
+ * enqueue another webhook. The agent update also carries a durable ordering
+ * fence: an older pending event may be terminalized, but it cannot overwrite
+ * a newer status event that was recorded while the older event was pending.
+ * A released agent's row is intentionally not updated (matching
+ * `updateAgentById`), but the event is still marked applied: there is no
+ * agent row left to reconcile, and retrying forever would just repeat the
+ * same no-op.
+ */
+export declare function applyStatusEventEffect(db: Db, workspaceId: string, agentId: string, eventId: string, status: string): Promise<StatusEventEffectResult>;
+declare function toPublicEvent(event: typeof sessionEvents.$inferSelect, agentId: string): {
     id: string;
     agent_id: string;
     type: string;
     payload: unknown;
     sequence: number;
     created_at: string;
-}>;
+};
 export declare function listSessionEvents(db: Db, workspaceId: string, agentId: string, options?: {
     type?: string;
     limit?: number;

package/dist/engine/sessionEvent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sessionEvent.d.ts","sourceRoot":"","sources":["../../src/engine/sessionEvent.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAI5C,KAAK,EAAE,GAAG,UAAU,CAAC,OAAO,KAAK,CAAC,CAAC;AAEnC,MAAM,MAAM,gBAAgB,GACxB,gBAAgB,GAChB,aAAa,GACb,eAAe,GACf,gBAAgB,GAChB,gBAAgB,GAChB,gBAAgB,GAChB,aAAa,GACb,gBAAgB,GAChB,aAAa,GACb,aAAa,GACb,kBAAkB,GAClB,cAAc,GACd,mBAAmB,GACnB,oBAAoB,GACpB,mBAAmB,GACnB,iBAAiB,GACjB,gBAAgB,GAChB,kBAAkB,GAClB,eAAe,GACf,eAAe,GACf,kBAAkB,GAClB,cAAc,GACd,iBAAiB,GACjB,mBAAmB,GACnB,gBAAgB,GAChB,iBAAiB,GACjB,iBAAiB,GACjB,eAAe,GACf,iBAAiB,GACjB,kBAAkB,GAClB,iBAAiB,GACjB,gBAAgB,GAChB,KAAK,GACL,OAAO,CAAC;AAkBZ,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,gBAAgB,CAEvE;AAED,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,EAAE,EACN,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE;IACJ,IAAI,EAAE,gBAAgB,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;;;;;;;GA0BF;AAED,wBAAsB,iBAAiB,CACrC,EAAE,EAAE,EAAE,EACN,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;IACR,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;;;;;;;KA0BF;AAED,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,gBAAgB,GAC1B,MAAM,GAAG,IAAI,CAUf"}
+{"version":3,"file":"sessionEvent.d.ts","sourceRoot":"","sources":["../../src/engine/sessionEvent.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAU,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAOxD,KAAK,EAAE,GAAG,UAAU,CAAC,OAAO,KAAK,CAAC,CAAC;AAEnC,MAAM,MAAM,gBAAgB,GACxB,gBAAgB,GAChB,aAAa,GACb,eAAe,GACf,gBAAgB,GAChB,gBAAgB,GAChB,gBAAgB,GAChB,aAAa,GACb,gBAAgB,GAChB,aAAa,GACb,aAAa,GACb,kBAAkB,GAClB,cAAc,GACd,mBAAmB,GACnB,oBAAoB,GACpB,mBAAmB,GACnB,iBAAiB,GACjB,gBAAgB,GAChB,kBAAkB,GAClB,eAAe,GACf,eAAe,GACf,kBAAkB,GAClB,cAAc,GACd,iBAAiB,GACjB,mBAAmB,GACnB,gBAAgB,GAChB,iBAAiB,GACjB,iBAAiB,GACjB,eAAe,GACf,iBAAiB,GACjB,kBAAkB,GAClB,iBAAiB,GACjB,gBAAgB,GAChB,KAAK,GACL,OAAO,CAAC;AAkBZ,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,gBAAgB,CAEvE;AAED,6FAA6F;AAC7F,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED,MAAM,WAAW,uBAAuB;IACtC,oEAAoE;IACpE,OAAO,EAAE,OAAO,CAAC;IACjB,wEAAwE;IACxE,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,EAAE,EACN,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE;IACJ,IAAI,EAAE,gBAAgB,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC,GACA,OAAO,CAAC;IAAE,KAAK,EAAE,UAAU,CAAC,OAAO,aAAa,CAAC,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAC;IAAC,wBAAwB,EAAE,OAAO,CAAA;CAAE,CAAC,CAyB5G;AAED;;;;;;GAMG;AACH,wBAAsB,iCAAiC,CACrD,EAAE,EAAE,EAAE,EACN,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE;IACJ,IAAI,EAAE,gBAAgB,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC,EACD,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC;IAAE,KAAK,EAAE,UAAU,CAAC,OAAO,aAAa,CAAC,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAC;IAAC,wBAAwB,EAAE,OAAO,CAAA;CAAE,CAAC,CAmE5G;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,sBAAsB,CAC1C,EAAE,EAAE,EAAE,EACN,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,uBAAuB,CAAC,CA2FlC;AAaD,iBAAS,aAAa,CAAC,KAAK,EAAE,OAAO,aAAa,CAAC,YAAY,EAAE,OAAO,EAAE,MAAM;;;;;;;EAS/E;AAED,wBAAsB,iBAAiB,CACrC,EAAE,EAAE,EAAE,EACN,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;IACR,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;;;;;;;KA0BF;AAED,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,gBAAgB,GAC1B,MAAM,GAAG,IAAI,CAUf"}

package/dist/engine/sessionEvent.js

@@ -1,6 +1,10 @@
-import { eq, and, desc, sql } from 'drizzle-orm';
-import { sessionEvents } from '../db/schema.js';
+import { eq, and, ne, desc, isNull, sql } from 'drizzle-orm';
+import { agents, sessionEvents } from '../db/schema.js';
 import { generateId } from './snowflake.js';
+import { sha256Hex } from '../lib/crypto.js';
+import { codedError } from '../lib/httpError.js';
+import { runAtomicWrites } from '../ports/database.js';
+import { RELEASED_AGENT_STATUS } from './agent.js';
 const VALID_EVENT_TYPES = new Set([
     'status.changed', 'status.idle', 'status.active', 'status.blocked',
     'status.waiting', 'status.offline',
@@ -19,6 +23,10 @@ const VALID_EVENT_TYPES = new Set([
 export function isValidEventType(type) {
     return VALID_EVENT_TYPES.has(type);
 }
+/** `status.*` events are the only ones with a side-effecting agent-row mutation to track. */
+export function isStatusEventType(type) {
+    return type.startsWith('status.');
+}
 export async function recordSessionEvent(db, workspaceId, agentId, data) {
     const id = `evt_${generateId()}`;
     // Sequence is assigned atomically via a scalar subquery — read and write in
@@ -34,6 +42,191 @@ export async function recordSessionEvent(db, workspaceId, agentId, data) {
         sequence: sql `(SELECT COALESCE(MAX(sequence), 0) + 1 FROM session_events WHERE agent_id = ${agentId})`,
     })
         .returning();
+    return {
+        event: toPublicEvent(event, agentId),
+        replayed: false,
+        // Unkeyed events have no durable claim to replay against — the caller
+        // always applies the status mutation immediately after this call, so
+        // there is nothing to recover across a retry.
+        pendingStatusApplication: isStatusEventType(data.type),
+    };
+}
+/**
+ * Record an event with a durable caller-provided identity.
+ *
+ * The key is hashed before persistence and scoped by workspace + agent in the
+ * unique index. The request digest is retained beside the event so reusing a
+ * key with a different event cannot accidentally replay the first event.
+ */
+export async function recordSessionEventWithIdempotency(db, workspaceId, agentId, data, idempotencyKey) {
+    const [idempotencyKeyHash, requestDigest] = await Promise.all([
+        sha256Hex(`session-event-key-v1\0${idempotencyKey}`),
+        sha256Hex(`session-event-payload-v1\0${canonicalJson({ type: data.type, payload: data.payload })}`),
+    ]);
+    const id = `evt_${generateId()}`;
+    // The insert and the unique identity claim are one durable operation. A
+    // conflict is followed by a scoped lookup so concurrent retries return the
+    // winner's exact event rather than allocating a second sequence number.
+    const [created] = await db
+        .insert(sessionEvents)
+        .values({
+        id,
+        workspaceId,
+        agentId,
+        type: data.type,
+        payload: data.payload,
+        idempotencyKeyHash,
+        requestDigest,
+        sequence: sql `(SELECT COALESCE(MAX(sequence), 0) + 1 FROM session_events WHERE agent_id = ${agentId})`,
+    })
+        .onConflictDoNothing()
+        .returning();
+    if (created) {
+        return {
+            event: toPublicEvent(created, agentId),
+            replayed: false,
+            pendingStatusApplication: isStatusEventType(data.type),
+        };
+    }
+    const [existing] = await db
+        .select()
+        .from(sessionEvents)
+        .where(and(eq(sessionEvents.workspaceId, workspaceId), eq(sessionEvents.agentId, agentId), eq(sessionEvents.idempotencyKeyHash, idempotencyKeyHash)));
+    if (!existing) {
+        throw codedError('The event idempotency claim could not be read after a storage conflict; retry with the same Idempotency-Key', 'idempotency_unavailable', 503);
+    }
+    if (existing.requestDigest !== requestDigest) {
+        throw codedError('Idempotency-Key was reused with a different request payload', 'idempotency_key_reused', 409);
+    }
+    return {
+        event: toPublicEvent(existing, agentId),
+        replayed: true,
+        // `status_applied_at` is set atomically with the agent-row status write
+        // (see `applyStatusEventEffect`). NULL here means either the mutation
+        // never ran, or it ran but the process crashed before marking it durable
+        // — both cases are indistinguishable from "not yet applied" and safe to
+        // retry, because the write that sets this column is the same atomic unit
+        // as the status mutation itself. A replay that is still pending finishes
+        // the interrupted work instead of returning 201 with a stale agent row.
+        pendingStatusApplication: isStatusEventType(existing.type) && existing.statusAppliedAt == null,
+    };
+}
+/**
+ * Apply a `status.*` event's agent-row mutation and claim its completion
+ * durably, as one atomic unit.
+ *
+ * This is the fix for the crash window between "the event/idempotency claim
+ * committed" and "the agent's status row is updated": if either statement
+ * here failed independently, a retry could see `replayed: true` and return
+ * 201 while the agent row stayed stale forever. Batching both writes through
+ * `runAtomicWrites` means a failure here rolls back *both* the status change
+ * and the completion marker, so `pendingStatusApplication` stays true and the
+ * next replay retries the whole mutation — it can never observe "claimed but
+ * never applied" as a terminal state.
+ *
+ * The completion update is the single-winner claim for side effects: a replay
+ * that loses a concurrent claim gets `claimed: false` and must not fan out or
+ * enqueue another webhook. The agent update also carries a durable ordering
+ * fence: an older pending event may be terminalized, but it cannot overwrite
+ * a newer status event that was recorded while the older event was pending.
+ * A released agent's row is intentionally not updated (matching
+ * `updateAgentById`), but the event is still marked applied: there is no
+ * agent row left to reconcile, and retrying forever would just repeat the
+ * same no-op.
+ */
+export async function applyStatusEventEffect(db, workspaceId, agentId, eventId, status) {
+    // The agent mutation runs first in the atomic unit. This ordering is
+    // important for D1 batches: the completion marker must still be NULL when
+    // the conditional status update is evaluated. The following marker update
+    // then claims the event; Node transactions and D1 batches serialize this
+    // pair, so an identical concurrent retry cannot mutate after the winner has
+    // claimed it.
+    const [mutationResult, claimResult] = await runAtomicWrites(db, (tx) => [
+        tx.update(agents)
+            .set({ status })
+            .where(and(eq(agents.workspaceId, workspaceId), eq(agents.id, agentId), ne(agents.status, RELEASED_AGENT_STATUS), 
+        // Do not let an interrupted older event roll a newer status back.
+        // The sequence is allocated per agent and is durable across retries;
+        // an event that is newer than this one wins the status row. A newer
+        // event that is itself pending will be responsible for applying its
+        // own status when it replays.
+        sql `EXISTS (
+          SELECT 1
+          FROM session_events AS current_event
+          WHERE current_event.id = ${eventId}
+            AND current_event.workspace_id = ${workspaceId}
+            AND current_event.agent_id = ${agentId}
+            AND current_event.status_applied_at IS NULL
+        )`, sql `NOT EXISTS (
+          SELECT 1
+          FROM session_events AS newer_event
+          WHERE newer_event.workspace_id = ${workspaceId}
+            AND newer_event.agent_id = ${agentId}
+            AND newer_event.type LIKE 'status.%'
+            AND newer_event.sequence > (
+              SELECT current_event.sequence
+              FROM session_events AS current_event
+              WHERE current_event.id = ${eventId}
+                AND current_event.workspace_id = ${workspaceId}
+                AND current_event.agent_id = ${agentId}
+            )
+        )`, 
+        // Migration 0056 cannot know whether the pre-marker route reached
+        // this agent write: it inserted the event and updated the agent in
+        // separate operations. Its write-time witness is therefore the only
+        // safe evidence available. Reapply a legacy event only when the agent
+        // row demonstrably predates the event; an equal or newer witness may
+        // be the original status write, a heartbeat, or another status writer.
+        // In those ambiguous cases claim the event but never clobber the row,
+        // regardless of whether its current status matches the event.
+        sql `(
+          NOT EXISTS (
+            SELECT 1
+            FROM session_events AS legacy_event
+            WHERE legacy_event.id = ${eventId}
+              AND legacy_event.workspace_id = ${workspaceId}
+              AND legacy_event.agent_id = ${agentId}
+              AND legacy_event.status_legacy_pending = 1
+          )
+          OR (
+            ${agents.status} <> ${status}
+            AND
+            ${agents.statusUpdatedAt} IS NOT NULL
+            AND ${agents.statusUpdatedAt} < (
+              SELECT legacy_event.created_at
+              FROM session_events AS legacy_event
+              WHERE legacy_event.id = ${eventId}
+                AND legacy_event.workspace_id = ${workspaceId}
+                AND legacy_event.agent_id = ${agentId}
+            )
+          )
+        )`))
+            .returning({ id: agents.id }),
+        tx.update(sessionEvents)
+            .set({ statusAppliedAt: sql `(unixepoch())` })
+            .where(and(eq(sessionEvents.id, eventId), eq(sessionEvents.workspaceId, workspaceId), eq(sessionEvents.agentId, agentId), isNull(sessionEvents.statusAppliedAt)))
+            .returning({ id: sessionEvents.id }),
+    ], { requireAtomic: true });
+    const claimed = Array.isArray(claimResult) && claimResult.length > 0;
+    const mutated = Array.isArray(mutationResult) && mutationResult.length > 0;
+    // Only the caller that both changed the current row and claimed the marker
+    // may emit external status side effects. The claim may intentionally win
+    // with `mutated === false` when a newer event superseded this one or the
+    // agent was released between route validation and this atomic write.
+    return { claimed, mutated: claimed && mutated };
+}
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(',')}]`;
+    if (value && typeof value === 'object') {
+        return `{${Object.keys(value)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`)
+            .join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+function toPublicEvent(event, agentId) {
     return {
         id: event.id,
         agent_id: agentId,

package/dist/engine/sessionEvent.js.map

@@ -1 +1 @@
-{"version":3,"file":"sessionEvent.js","sourceRoot":"","sources":["../../src/engine/sessionEvent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sessionEvent.js","sourceRoot":"","sources":["../../src/engine/sessionEvent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AAE7D,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAwCnD,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAS;IACxC,gBAAgB,EAAE,aAAa,EAAE,eAAe,EAAE,gBAAgB;IAClE,gBAAgB,EAAE,gBAAgB;IAClC,aAAa,EAAE,gBAAgB,EAAE,aAAa,EAAE,aAAa;IAC7D,kBAAkB,EAAE,cAAc;IAClC,mBAAmB,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,iBAAiB;IACjF,gBAAgB,EAAE,kBAAkB,EAAE,eAAe,EAAE,eAAe;IACtE,kBAAkB;IAClB,cAAc;IACd,iBAAiB,EAAE,mBAAmB,EAAE,gBAAgB;IACxD,iBAAiB,EAAE,iBAAiB;IACpC,eAAe;IACf,iBAAiB,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,gBAAgB;IAC1E,KAAK,EAAE,OAAO;CACf,CAAC,CAAC;AAEH,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,OAAO,iBAAiB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACrC,CAAC;AAED,6FAA6F;AAC7F,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,OAAO,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;AACpC,CAAC;AASD,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,EAAM,EACN,WAAmB,EACnB,OAAe,EACf,IAGC;IAED,MAAM,EAAE,GAAG,OAAO,UAAU,EAAE,EAAE,CAAC;IAEjC,4EAA4E;IAC5E,qEAAqE;IACrE,MAAM,CAAC,KAAK,CAAC,GAAG,MAAM,EAAE;SACrB,MAAM,CAAC,aAAa,CAAC;SACrB,MAAM,CAAC;QACN,EAAE;QACF,WAAW;QACX,OAAO;QACP,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,QAAQ,EAAE,GAAG,CAAQ,+EAA+E,OAAO,GAAG;KAC/G,CAAC;SACD,SAAS,EAAE,CAAC;IAEf,OAAO;QACL,KAAK,EAAE,aAAa,CAAC,KAAK,EAAE,OAAO,CAAC;QACpC,QAAQ,EAAE,KAAK;QACf,sEAAsE;QACtE,qEAAqE;QACrE,8CAA8C;QAC9C,wBAAwB,EAAE,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC;KACvD,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,iCAAiC,CACrD,EAAM,EACN,WAAmB,EACnB,OAAe,EACf,IAGC,EACD,cAAsB;IAEtB,MAAM,CAAC,kBAAkB,EAAE,aAAa,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QAC5D,SAAS,CAAC,yBAAyB,cAAc,EAAE,CAAC;QACpD,SAAS,CAAC,6BAA6B,aAAa,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC;KACpG,CAAC,CAAC;IACH,MAAM,EAAE,GAAG,OAAO,UAAU,EAAE,EAAE,CAAC;IAEjC,wEAAwE;IACxE,2EAA2E;IAC3E,wEAAwE;IACxE,MAAM,CAAC,OAAO,CAAC,GAAG,MAAM,EAAE;SACvB,MAAM,CAAC,aAAa,CAAC;SACrB,MAAM,CAAC;QACN,EAAE;QACF,WAAW;QACX,OAAO;QACP,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,kBAAkB;QAClB,aAAa;QACb,QAAQ,EAAE,GAAG,CAAQ,+EAA+E,OAAO,GAAG;KAC/G,CAAC;SACD,mBAAmB,EAAE;SACrB,SAAS,EAAE,CAAC;IAEf,IAAI,OAAO,EAAE,CAAC;QACZ,OAAO;YACL,KAAK,EAAE,aAAa,CAAC,OAAO,EAAE,OAAO,CAAC;YACtC,QAAQ,EAAE,KAAK;YACf,wBAAwB,EAAE,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC;SACvD,CAAC;IACJ,CAAC;IAED,MAAM,CAAC,QAAQ,CAAC,GAAG,MAAM,EAAE;SACxB,MAAM,EAAE;SACR,IAAI,CAAC,aAAa,CAAC;SACnB,KAAK,CAAC,GAAG,CACR,EAAE,CAAC,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,EAC1C,EAAE,CAAC,aAAa,CAAC,OAAO,EAAE,OAAO,CAAC,EAClC,EAAE,CAAC,aAAa,CAAC,kBAAkB,EAAE,kBAAkB,CAAC,CACzD,CAAC,CAAC;IACL,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,UAAU,CACd,6GAA6G,EAC7G,yBAAyB,EACzB,GAAG,CACJ,CAAC;IACJ,CAAC;IACD,IAAI,QAAQ,CAAC,aAAa,KAAK,aAAa,EAAE,CAAC;QAC7C,MAAM,UAAU,CACd,6DAA6D,EAC7D,wBAAwB,EACxB,GAAG,CACJ,CAAC;IACJ,CAAC;IACD,OAAO;QACL,KAAK,EAAE,aAAa,CAAC,QAAQ,EAAE,OAAO,CAAC;QACvC,QAAQ,EAAE,IAAI;QACd,wEAAwE;QACxE,sEAAsE;QACtE,yEAAyE;QACzE,wEAAwE;QACxE,yEAAyE;QACzE,yEAAyE;QACzE,wEAAwE;QACxE,wBAAwB,EAAE,iBAAiB,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,QAAQ,CAAC,eAAe,IAAI,IAAI;KAC/F,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,EAAM,EACN,WAAmB,EACnB,OAAe,EACf,OAAe,EACf,MAAc;IAEd,qEAAqE;IACrE,0EAA0E;IAC1E,0EAA0E;IAC1E,yEAAyE;IACzE,4EAA4E;IAC5E,cAAc;IACd,MAAM,CAAC,cAAc,EAAE,WAAW,CAAC,GAAG,MAAM,eAAe,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC;QACtE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC;aACd,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;aACf,KAAK,CAAC,GAAG,CACR,EAAE,CAAC,MAAM,CAAC,WAAW,EAAE,WAAW,CAAC,EACnC,EAAE,CAAC,MAAM,CAAC,EAAE,EAAE,OAAO,CAAC,EACtB,EAAE,CAAC,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC;QACxC,kEAAkE;QAClE,qEAAqE;QACrE,oEAAoE;QACpE,oEAAoE;QACpE,8BAA8B;QAC9B,GAAG,CAAA;;;qCAG0B,OAAO;+CACG,WAAW;2CACf,OAAO;;UAExC,EACF,GAAG,CAAA;;;6CAGkC,WAAW;yCACf,OAAO;;;;;yCAKP,OAAO;mDACG,WAAW;+CACf,OAAO;;UAE5C;QACF,kEAAkE;QAClE,mEAAmE;QACnE,oEAAoE;QACpE,sEAAsE;QACtE,qEAAqE;QACrE,uEAAuE;QACvE,sEAAsE;QACtE,8DAA8D;QAC9D,GAAG,CAAA;;;;sCAI2B,OAAO;gDACG,WAAW;4CACf,OAAO;;;;cAIrC,MAAM,CAAC,MAAM,OAAO,MAAM;;cAE1B,MAAM,CAAC,eAAe;kBAClB,MAAM,CAAC,eAAe;;;wCAGA,OAAO;kDACG,WAAW;8CACf,OAAO;;;UAG3C,CACH,CAAC;aACD,SAAS,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,EAAE,CAAC;QAC/B,EAAE,CAAC,MAAM,CAAC,aAAa,CAAC;aACrB,GAAG,CAAC,EAAE,eAAe,EAAE,GAAG,CAAA,eAAe,EAAE,CAAC;aAC5C,KAAK,CAAC,GAAG,CACR,EAAE,CAAC,aAAa,CAAC,EAAE,EAAE,OAAO,CAAC,EAC7B,EAAE,CAAC,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,EAC1C,EAAE,CAAC,aAAa,CAAC,OAAO,EAAE,OAAO,CAAC,EAClC,MAAM,CAAC,aAAa,CAAC,eAAe,CAAC,CACtC,CAAC;aACD,SAAS,CAAC,EAAE,EAAE,EAAE,aAAa,CAAC,EAAE,EAAE,CAAC;KACvC,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IAE5B,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC;IACrE,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,cAAc,CAAC,IAAI,cAAc,CAAC,MAAM,GAAG,CAAC,CAAC;IAC3E,2EAA2E;IAC3E,yEAAyE;IACzE,yEAAyE;IACzE,qEAAqE;IACrE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,CAAC;AAClD,CAAC;AAED,SAAS,aAAa,CAAC,KAAc;IACnC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,KAAK,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IAC3E,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvC,OAAO,IAAI,MAAM,CAAC,IAAI,CAAC,KAAgC,CAAC;aACrD,IAAI,EAAE;aACN,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,aAAa,CAAE,KAAiC,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;aAChG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IAClB,CAAC;IACD,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;AAC/B,CAAC;AAED,SAAS,aAAa,CAAC,KAAwC,EAAE,OAAe;IAC9E,OAAO;QACL,EAAE,EAAE,KAAK,CAAC,EAAE;QACZ,QAAQ,EAAE,OAAO;QACjB,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,UAAU,EAAE,KAAK,CAAC,SAAS,CAAC,WAAW,EAAE;KAC1C,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,EAAM,EACN,WAAmB,EACnB,OAAe,EACf,OAGC;IAED,MAAM,SAAS,GAAG,OAAO,EAAE,KAAK,CAAC;IACjC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,CAAE,SAAoB,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAEnG,MAAM,KAAK,GAAG,EAAE;SACb,MAAM,EAAE;SACR,IAAI,CAAC,aAAa,CAAC;SACnB,KAAK,CAAC,GAAG,CACR,EAAE,CAAC,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,EAC1C,EAAE,CAAC,aAAa,CAAC,OAAO,EAAE,OAAO,CAAC,EAClC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,aAAa,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CACjE,CAAC;SACD,OAAO,CAAC,IAAI,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;SACtC,KAAK,CAAC,KAAK,CAAC,CAAC;IAEhB,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC;IAEzB,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACtB,EAAE,EAAE,CAAC,CAAC,EAAE;QACR,QAAQ,EAAE,CAAC,CAAC,OAAO;QACnB,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,OAAO,EAAE,CAAC,CAAC,OAAO;QAClB,QAAQ,EAAE,CAAC,CAAC,QAAQ;QACpB,UAAU,EAAE,CAAC,CAAC,SAAS,CAAC,WAAW,EAAE;KACtC,CAAC,CAAC,CAAC;AACN,CAAC;AAED,MAAM,UAAU,sBAAsB,CACpC,SAA2B;IAE3B,QAAQ,SAAS,EAAE,CAAC;QAClB,KAAK,eAAe,CAAC,CAAC,OAAO,QAAQ,CAAC;QACtC,KAAK,aAAa,CAAC,CAAC,OAAO,MAAM,CAAC;QAClC,KAAK,gBAAgB,CAAC,CAAC,OAAO,SAAS,CAAC;QACxC,KAAK,gBAAgB,CAAC,CAAC,OAAO,SAAS,CAAC;QACxC,KAAK,gBAAgB,CAAC,CAAC,OAAO,SAAS,CAAC;QACxC,KAAK,gBAAgB,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,6BAA6B;QACjE,OAAO,CAAC,CAAC,OAAO,IAAI,CAAC;IACvB,CAAC;AACH,CAAC"}

package/dist/engine/workspace.d.ts

@@ -8,14 +8,14 @@ type CreateWorkspaceOptions = string | {
     /** Deployment-configured secret used to derive the anonymous bootstrap child key. */
     bootstrapSecret?: string;
     /**
-     * The bootstrap secret as presented by the caller. An anonymous,
-     * idempotency-keyed create must prove it, matching `bootstrapSecret`,
-     * before any binding lookup or credential is returned — otherwise the
-     * `Idempotency-Key` alone (a caller-chosen, non-secret value) would let
-     * any network peer who guesses or observes it retrieve a workspace's
-     * deterministic API key. See createWorkspace's bootstrap-proof check.
+     * The bootstrap secret as presented by the caller when a self-host opts
+     * into shared-secret proof enforcement. Hosted deployments keep the
+     * server derivation secret private and use the high-entropy
+     * Idempotency-Key as the narrowly scoped recovery capability.
      */
     bootstrapSecretProof?: string;
+    /** Enable the optional self-host bootstrap-secret proof requirement. */
+    bootstrapProofRequired?: boolean;
     /**
      * Crash-safe workspace-create replay key (relaycast#371/#379).
      *
@@ -25,9 +25,8 @@ type CreateWorkspaceOptions = string | {
      * be unique per logical operation (e.g. a job id).
      *
      * Anonymous bootstrap (no owner key): the key is scoped to the
-     * deployment, not to a caller, and — together with
-     * `X-Workspace-Bootstrap-Secret` — is what recovers or replays the
-     * binding. Generate it with a CSPRNG, never a derived or guessable
+     * deployment, not to a caller, and is the reveal-once recovery
+     * capability for the binding. Generate it with a CSPRNG, never a derived or guessable
      * value such as a job id, timestamp, or counter. A v4 UUID, 16 random
      * bytes hex-encoded, or at least 24 random bytes base64url-encoded meet
      * the 32-character structural minimum. `createWorkspace` cannot verify

package/dist/engine/workspace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../src/engine/workspace.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../src/engine/workspace.ts"],"names":[],"mappings":"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"}