@inneranimalmedia/agentsam-sdk 2.6.9 → 2.6.11

package/packages/agentsam-queue-control/src/adapters/sqlite.js

@@ -0,0 +1,259 @@
+import { assertJobEnvelope } from '../contracts.js';
+
+function rows(result) {
+  if (Array.isArray(result)) return result;
+  if (Array.isArray(result?.results)) return result.results;
+  return [];
+}
+
+function changes(result) {
+  if (Number.isFinite(Number(result?.changes))) return Number(result.changes);
+  if (Number.isFinite(Number(result?.meta?.changes))) return Number(result.meta.changes);
+  return 0;
+}
+
+function clean(value) {
+  return value == null ? '' : String(value).trim();
+}
+
+function parseJob(row) {
+  if (!row) return null;
+  const body = JSON.parse(row.job_json);
+  return {
+    ...body,
+    status: row.status,
+    available_at: Number(row.available_at),
+    attempt: Number(row.attempt),
+    lease_owner: row.lease_owner || null,
+    lease_expires_at: row.lease_expires_at == null ? null : Number(row.lease_expires_at),
+    lease_generation: Number(row.lease_generation || 0),
+  };
+}
+
+const PRIORITY_SQL = "CASE priority WHEN 'urgent' THEN 4 WHEN 'high' THEN 3 WHEN 'normal' THEN 2 ELSE 1 END";
+
+/**
+ * Durable provider-neutral queue adapter over AgentSam's D1-shaped DB contract.
+ * Local SQLite is the reference host; other hosts may supply the same prepare/bind API.
+ */
+export class SqliteQueueAdapter {
+  constructor({
+    database,
+    leaseOwner = 'sqlite-' + process.pid,
+    leaseTtlSeconds = 60,
+  } = {}) {
+    if (!database || typeof database.prepare !== 'function') {
+      throw new TypeError('database with prepare() is required');
+    }
+    this.database = database;
+    this.leaseOwner = clean(leaseOwner) || ('sqlite-' + process.pid);
+    this.leaseTtlSeconds = Math.max(1, Number(leaseTtlSeconds) || 60);
+  }
+
+  async publish(queue, job) {
+    assertJobEnvelope(job);
+    const physicalQueue = clean(queue);
+    if (!physicalQueue) throw new TypeError('queue is required');
+
+    const existing = await this.database.prepare(
+      'SELECT id, status FROM agentsam_queue_job WHERE account_id = ? AND idempotency_key = ? LIMIT 1'
+    ).bind(job.account_id, job.idempotency_key).first();
+
+    if (existing && existing.id !== job.id) {
+      return {
+        provider: 'sqlite',
+        queue: physicalQueue,
+        accepted: 0,
+        deduplicated: true,
+        existing_job_id: existing.id,
+        existing_status: existing.status,
+      };
+    }
+
+    const maxAttempts = Math.max(1, Number(job.retry?.max_attempts) || 3);
+    const now = Math.floor(Date.now() / 1000);
+    const sql = [
+      'INSERT INTO agentsam_queue_job (',
+      'id, account_id, physical_queue, logical_queue, kind, status, priority,',
+      'available_at, attempt, max_attempts, idempotency_key, source_run_id,',
+      'step_id, lease_owner, lease_expires_at, lease_generation, job_json,',
+      'created_at_unix, updated_at_unix',
+      ') VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)',
+      'ON CONFLICT(id) DO UPDATE SET',
+      'physical_queue = excluded.physical_queue,',
+      'logical_queue = excluded.logical_queue,',
+      'kind = excluded.kind,',
+      'status = excluded.status,',
+      'priority = excluded.priority,',
+      'available_at = excluded.available_at,',
+      'attempt = excluded.attempt,',
+      'max_attempts = excluded.max_attempts,',
+      'source_run_id = excluded.source_run_id,',
+      'step_id = excluded.step_id,',
+      'lease_owner = excluded.lease_owner,',
+      'lease_expires_at = excluded.lease_expires_at,',
+      'lease_generation = excluded.lease_generation,',
+      'job_json = excluded.job_json,',
+      'result_json = NULL, error_json = NULL, completed_at_unix = NULL,',
+      'updated_at_unix = excluded.updated_at_unix'
+    ].join(' ');
+
+    await this.database.prepare(sql).bind(
+      job.id,
+      job.account_id,
+      physicalQueue,
+      job.logical_queue,
+      job.kind,
+      job.status,
+      job.priority,
+      job.available_at,
+      job.attempt,
+      maxAttempts,
+      job.idempotency_key,
+      job.source_run_id,
+      job.step_id,
+      job.lease_owner,
+      job.lease_expires_at,
+      job.lease_generation || 0,
+      JSON.stringify(job),
+      job.created_at || now,
+      now,
+    ).run();
+
+    return { provider: 'sqlite', queue: physicalQueue, accepted: 1, deduplicated: false };
+  }
+
+  async publishBatch(queue, jobs) {
+    let accepted = 0;
+    let deduplicated = 0;
+    for (const job of jobs) {
+      const result = await this.publish(queue, job);
+      accepted += Number(result.accepted || 0);
+      if (result.deduplicated) deduplicated += 1;
+    }
+    return { provider: 'sqlite', queue, accepted, deduplicated };
+  }
+
+  async pull(queue, max = 1, {
+    now = Math.floor(Date.now() / 1000),
+    owner = this.leaseOwner,
+    ttl_seconds = this.leaseTtlSeconds,
+  } = {}) {
+    const physicalQueue = clean(queue);
+    const leaseOwner = clean(owner);
+    if (!physicalQueue) throw new TypeError('queue is required');
+    if (!leaseOwner) throw new TypeError('lease owner is required');
+
+    const limit = Math.max(1, Math.floor(Number(max) || 1));
+    const ttl = Math.max(1, Math.floor(Number(ttl_seconds) || this.leaseTtlSeconds));
+    const selectSql = [
+      'SELECT * FROM agentsam_queue_job',
+      'WHERE physical_queue = ?',
+      "AND status IN ('queued','retry_scheduled','waiting','claimed')",
+      'AND available_at <= ?',
+      'AND (lease_expires_at IS NULL OR lease_expires_at <= ?)',
+      'ORDER BY ' + PRIORITY_SQL + ' DESC, available_at ASC, created_at_unix ASC',
+      'LIMIT ?'
+    ].join(' ');
+
+    const result = await this.database.prepare(selectSql).bind(
+      physicalQueue, now, now, limit
+    ).all();
+
+    const claimed = [];
+    for (const row of rows(result)) {
+      const leaseExpiresAt = now + ttl;
+      const updateSql = [
+        "UPDATE agentsam_queue_job SET status = 'claimed',",
+        'lease_owner = ?, lease_expires_at = ?,',
+        'lease_generation = lease_generation + 1, updated_at_unix = ?',
+        'WHERE id = ?',
+        "AND status IN ('queued','retry_scheduled','waiting','claimed')",
+        'AND available_at <= ?',
+        'AND (lease_expires_at IS NULL OR lease_expires_at <= ?)'
+      ].join(' ');
+      const update = await this.database.prepare(updateSql).bind(
+        leaseOwner, leaseExpiresAt, now, row.id, now, now
+      ).run();
+
+      if (changes(update) !== 1) continue;
+      const current = await this.database.prepare(
+        'SELECT * FROM agentsam_queue_job WHERE id = ? LIMIT 1'
+      ).bind(row.id).first();
+      if (current) claimed.push(parseJob(current));
+    }
+    return claimed;
+  }
+
+  async ack(jobOrId, {
+    status = 'completed',
+    result = null,
+    error = null,
+    now = Math.floor(Date.now() / 1000),
+  } = {}) {
+    const id = typeof jobOrId === 'string' ? jobOrId : jobOrId?.id;
+    if (!clean(id)) throw new TypeError('job id is required');
+    const sql = [
+      'UPDATE agentsam_queue_job SET status = ?,',
+      'lease_owner = NULL, lease_expires_at = NULL,',
+      'result_json = ?, error_json = ?, completed_at_unix = ?, updated_at_unix = ?',
+      'WHERE id = ?'
+    ].join(' ');
+    const update = await this.database.prepare(sql).bind(
+      status,
+      result == null ? null : JSON.stringify(result),
+      error == null ? null : JSON.stringify(error),
+      now,
+      now,
+      id,
+    ).run();
+    return { provider: 'sqlite', job_id: id, status, updated: changes(update) };
+  }
+
+  async release(jobOrId, {
+    status = 'queued',
+    available_at = Math.floor(Date.now() / 1000),
+    now = Math.floor(Date.now() / 1000),
+  } = {}) {
+    const id = typeof jobOrId === 'string' ? jobOrId : jobOrId?.id;
+    if (!clean(id)) throw new TypeError('job id is required');
+    const sql = [
+      'UPDATE agentsam_queue_job SET status = ?, available_at = ?,',
+      'lease_owner = NULL, lease_expires_at = NULL, updated_at_unix = ?',
+      'WHERE id = ?'
+    ].join(' ');
+    const update = await this.database.prepare(sql).bind(
+      status, available_at, now, id
+    ).run();
+    return { provider: 'sqlite', job_id: id, status, updated: changes(update), available_at };
+  }
+
+  async get(id) {
+    const row = await this.database.prepare(
+      'SELECT * FROM agentsam_queue_job WHERE id = ? LIMIT 1'
+    ).bind(id).first();
+    return parseJob(row);
+  }
+
+  async depth(queue, { now = null, includeTerminal = false } = {}) {
+    const clauses = ['physical_queue = ?'];
+    const values = [queue];
+    if (!includeTerminal) clauses.push("status NOT IN ('completed','failed','cancelled')");
+    if (now != null) {
+      clauses.push('available_at <= ?');
+      values.push(now);
+    }
+    const sql = 'SELECT COUNT(*) AS count FROM agentsam_queue_job WHERE ' + clauses.join(' AND ');
+    const row = await this.database.prepare(sql).bind(...values).first();
+    return Number(row?.count || 0);
+  }
+
+  async ensureTopology(topology) {
+    await this.database.prepare('SELECT id FROM agentsam_queue_job LIMIT 1').all();
+    return {
+      provider: 'sqlite',
+      created: [],
+      existing: [...new Set(Object.values(topology?.routes || {}))],
+    };
+  }
+}

package/packages/agentsam-queue-control/src/contracts.js

@@ -7,6 +7,7 @@ export const JOB_STATUSES = Object.freeze([
   'waiting',
   'batch_waiting',
   'awaiting_input',
+  'retry_scheduled',
   'completed',
   'failed',
   'cancelled',
@@ -36,6 +37,7 @@ export const DEFAULT_RETRY_POLICY = Object.freeze({
   backoff: 'exponential',
   initial_delay_ms: 1_000,
   max_delay_ms: 60_000,
+  jitter: true,
 });
 
 function clean(value) {
@@ -48,6 +50,198 @@ function assertEnum(value, allowed, field) {
   }
 }
 
+function epochSeconds(value, fallback, field = 'timestamp') {
+  if (value == null || value === '') return fallback;
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric) || numeric < 0) throw new TypeError(`${field} must be a non-negative epoch second`);
+  return Math.floor(numeric);
+}
+
+export function computeRetryDelayMs(retry = DEFAULT_RETRY_POLICY, attempt = 1, random = Math.random) {
+  const policy = { ...DEFAULT_RETRY_POLICY, ...(retry || {}) };
+  const n = Math.max(1, Number.isInteger(attempt) ? attempt : 1);
+  const initial = Math.max(0, Number(policy.initial_delay_ms) || 0);
+  const maximum = Math.max(initial, Number(policy.max_delay_ms) || initial);
+  let delay = policy.backoff === 'exponential'
+    ? initial * (2 ** (n - 1))
+    : initial;
+  delay = Math.min(maximum, delay);
+  if (policy.jitter && delay > 0) {
+    const sample = Math.max(0, Math.min(1, Number(random()) || 0));
+    delay = Math.floor((delay / 2) + ((delay / 2) * sample));
+  }
+  return Math.max(0, Math.floor(delay));
+}
+
+export function createRetrySchedule(job, { now_ms = Date.now(), random = Math.random, error = null } = {}) {
+  assertJobEnvelope(job);
+  const nextAttempt = (Number.isInteger(job.attempt) ? job.attempt : 0) + 1;
+  const maxAttempts = Math.max(1, Number(job.retry?.max_attempts) || DEFAULT_RETRY_POLICY.max_attempts);
+  if (nextAttempt >= maxAttempts) {
+    return {
+      retryable: false,
+      exhausted: true,
+      attempt: nextAttempt,
+      delay_ms: 0,
+      available_at: null,
+      job: null,
+    };
+  }
+  const delayMs = computeRetryDelayMs(job.retry, nextAttempt, random);
+  const availableAt = Math.ceil((Number(now_ms) + delayMs) / 1000);
+  return {
+    retryable: true,
+    exhausted: false,
+    attempt: nextAttempt,
+    delay_ms: delayMs,
+    available_at: availableAt,
+    job: {
+      ...job,
+      status: 'retry_scheduled',
+      attempt: nextAttempt,
+      available_at: availableAt,
+      lease_owner: null,
+      lease_expires_at: null,
+      metadata: {
+        ...(job.metadata || {}),
+        ...(error ? { last_error: String(error?.message || error) } : {}),
+      },
+    },
+  };
+}
+
+export function createDeadLetterJob(job, {
+  error = null,
+  attempt = (Number.isInteger(job?.attempt) ? job.attempt : 0) + 1,
+  now = Math.floor(Date.now() / 1000),
+} = {}) {
+  assertJobEnvelope(job);
+  const originalKey = clean(job.idempotency_key) || job.id;
+  return createJobEnvelope({
+    id: job.id + ':dlq:' + attempt,
+    account_id: job.account_id,
+    kind: 'dead_letter',
+    logical_queue: 'dead_letter',
+    executor: 'queue',
+    priority: job.priority === 'urgent' ? 'urgent' : 'high',
+    parent_job_id: job.id,
+    conversation_id: job.conversation_id,
+    agent_id: job.agent_id,
+    source_run_id: job.source_run_id,
+    step_id: job.step_id,
+    idempotency_key: originalKey + ':dlq:' + attempt,
+    payload: {
+      original_job: job,
+      failure: error == null ? null : {
+        message: String(error?.message || error),
+        code: clean(error?.code) || null,
+      },
+    },
+    metadata: {
+      ...(job.metadata || {}),
+      dead_letter: true,
+      original_job_id: job.id,
+      original_kind: job.kind,
+      exhausted_attempt: attempt,
+    },
+    retry: {
+      max_attempts: 1,
+      backoff: 'fixed',
+      initial_delay_ms: 0,
+      max_delay_ms: 0,
+      jitter: false,
+    },
+    attempt: 0,
+    available_at: now,
+    created_at: now,
+  });
+}
+
+export function isJobAvailable(job, now = Math.floor(Date.now() / 1000)) {
+  return (job?.available_at ?? 0) <= now;
+}
+
+export function jobExecutionIdentity(job) {
+  assertJobEnvelope(job);
+  return Object.freeze({
+    job_id: job.id,
+    run_id: job.source_run_id ?? null,
+    step_id: job.step_id ?? null,
+    attempt: job.attempt ?? 0,
+    idempotency_key: clean(job.idempotency_key) || job.id,
+    lease_owner: job.lease_owner ?? null,
+    lease_expires_at: job.lease_expires_at ?? null,
+    lease_generation: job.lease_generation ?? 0,
+  });
+}
+
+export function canClaimJobLease(job, { now = Math.floor(Date.now() / 1000), owner = null } = {}) {
+  assertJobEnvelope(job);
+  if (isTerminalJobStatus(job.status)) return false;
+  if (!isJobAvailable(job, now)) return false;
+  const leaseOwner = clean(job.lease_owner);
+  const leaseExpiresAt = job.lease_expires_at == null
+    ? null
+    : epochSeconds(job.lease_expires_at, null, 'lease_expires_at');
+  if (!leaseOwner || leaseExpiresAt == null || leaseExpiresAt <= now) return true;
+  return Boolean(owner && leaseOwner === clean(owner));
+}
+
+export function claimJobLease(job, { owner, now = Math.floor(Date.now() / 1000), ttl_seconds = 60 } = {}) {
+  assertJobEnvelope(job);
+  const leaseOwner = clean(owner);
+  if (!leaseOwner) throw new TypeError('lease owner is required');
+  const ttl = Math.max(1, Math.floor(Number(ttl_seconds) || 0));
+  if (!canClaimJobLease(job, { now, owner: leaseOwner })) {
+    const error = new Error(isJobAvailable(job, now) ? 'job_lease_held' : 'job_not_available');
+    error.code = isJobAvailable(job, now) ? 'lease_held' : 'job_not_available';
+    throw error;
+  }
+  return {
+    ...job,
+    status: 'claimed',
+    lease_owner: leaseOwner,
+    lease_expires_at: now + ttl,
+    lease_generation: Math.max(0, Number(job.lease_generation) || 0) + 1,
+  };
+}
+
+export function refreshJobLease(job, { owner, now = Math.floor(Date.now() / 1000), ttl_seconds = 60 } = {}) {
+  assertJobEnvelope(job);
+  const leaseOwner = clean(owner);
+  if (!leaseOwner || leaseOwner !== clean(job.lease_owner)) {
+    const error = new Error('job_lease_owner_mismatch');
+    error.code = 'lease_owner_mismatch';
+    throw error;
+  }
+  const currentExpiry = epochSeconds(job.lease_expires_at, 0, 'lease_expires_at');
+  if (currentExpiry <= now) {
+    const error = new Error('job_lease_expired');
+    error.code = 'lease_expired';
+    throw error;
+  }
+  const ttl = Math.max(1, Math.floor(Number(ttl_seconds) || 0));
+  return { ...job, lease_expires_at: now + ttl };
+}
+
+export function releaseJobLease(job, { owner, status = 'queued', available_at = job.available_at } = {}) {
+  assertJobEnvelope(job);
+  const leaseOwner = clean(owner);
+  if (leaseOwner && clean(job.lease_owner) && leaseOwner !== clean(job.lease_owner)) {
+    const error = new Error('job_lease_owner_mismatch');
+    error.code = 'lease_owner_mismatch';
+    throw error;
+  }
+  assertEnum(status, JOB_STATUSES, 'status');
+  return {
+    ...job,
+    status,
+    available_at: epochSeconds(available_at, job.available_at, 'available_at'),
+    lease_owner: null,
+    lease_expires_at: null,
+  };
+}
+
 export function createJobEnvelope(input = {}) {
   const kind = clean(input.kind);
   if (!kind) throw new TypeError('kind is required');
@@ -56,6 +250,8 @@ export function createJobEnvelope(input = {}) {
   if (!accountId) throw new TypeError('account_id is required');
 
   const now = input.created_at ?? Math.floor(Date.now() / 1000);
+  const availableAt = epochSeconds(input.available_at ?? input.availableAt, now, 'available_at');
+  const id = clean(input.id) || `job_${randomUUID().replaceAll('-', '')}`;
   const priority = input.priority ?? 'normal';
   assertEnum(priority, JOB_PRIORITIES, 'priority');
 
@@ -64,7 +260,7 @@ export function createJobEnvelope(input = {}) {
 
   return {
     schema_version: '1',
-    id: clean(input.id) || `job_${randomUUID().replaceAll('-', '')}`,
+    id,
     account_id: accountId,
     kind,
     logical_queue: clean(input.logical_queue) || null,
@@ -74,8 +270,12 @@ export function createJobEnvelope(input = {}) {
     parent_job_id: clean(input.parent_job_id) || null,
     conversation_id: clean(input.conversation_id) || null,
     agent_id: clean(input.agent_id) || null,
-    source_run_id: clean(input.source_run_id) || null,
-    idempotency_key: clean(input.idempotency_key) || null,
+    source_run_id: clean(input.source_run_id ?? input.run_id) || null,
+    step_id: clean(input.step_id) || null,
+    idempotency_key: clean(input.idempotency_key ?? input.idempotencyKey) || id,
+    lease_owner: clean(input.lease_owner) || null,
+    lease_expires_at: input.lease_expires_at == null ? null : epochSeconds(input.lease_expires_at, null, 'lease_expires_at'),
+    lease_generation: Number.isInteger(input.lease_generation) ? Math.max(0, input.lease_generation) : 0,
     payload: input.payload ?? null,
     payload_ref: clean(input.payload_ref) || null,
     metadata: input.metadata && typeof input.metadata === 'object' ? input.metadata : {},
@@ -84,6 +284,7 @@ export function createJobEnvelope(input = {}) {
       ...(input.retry && typeof input.retry === 'object' ? input.retry : {}),
     },
     attempt: Number.isInteger(input.attempt) ? input.attempt : 0,
+    available_at: availableAt,
     created_at: now,
   };
 }
@@ -97,6 +298,9 @@ export function assertJobEnvelope(job) {
   assertEnum(job.priority ?? 'normal', JOB_PRIORITIES, 'job.priority');
   assertEnum(job.executor ?? 'queue', EXECUTOR_KINDS, 'job.executor');
   assertEnum(job.status ?? 'queued', JOB_STATUSES, 'job.status');
+  epochSeconds(job.available_at, job.created_at ?? 0, 'job.available_at');
+  if (job.lease_expires_at != null) epochSeconds(job.lease_expires_at, null, 'job.lease_expires_at');
+  if (job.lease_owner && job.lease_expires_at == null) throw new TypeError('job.lease_expires_at is required when job.lease_owner is set');
   return job;
 }
 

package/packages/agentsam-queue-control/src/control-plane.js

@@ -1,4 +1,4 @@
-import { createJobEnvelope, assertJobEnvelope } from './contracts.js';
+import { createJobEnvelope, assertJobEnvelope, computeRetryDelayMs, createRetrySchedule, createDeadLetterJob } from './contracts.js';
 import { buildQueueTopology, resolvePhysicalQueue } from './topology.js';
 import { routeWork, shouldRequireProvisionApproval } from './policy.js';
 import { JobDispatcher } from './dispatch.js';
@@ -117,6 +117,16 @@ export class QueueControl {
     return this.adapter.ensureTopology(this.topology, options);
   }
 
+  async deadLetter(job, error, { attempt = (job.attempt || 0) + 1 } = {}) {
+    const deadLetter = createDeadLetterJob(job, { error, attempt });
+    const queue = resolvePhysicalQueue(this.topology, 'dead_letter');
+    const receipt = await this.adapter.publish(queue, deadLetter, {
+      logical_queue: 'dead_letter',
+      dead_letter: true,
+    });
+    return { job: deadLetter, queue, receipt: receipt ?? null };
+  }
+
   async consume(messages, context = {}) {
     const results = [];
     for (const message of messages) {
@@ -127,12 +137,62 @@ export class QueueControl {
         if (typeof message?.ack === 'function') message.ack();
         results.push({ job_id: job.id, ok: true, result });
       } catch (error) {
-        if (typeof message?.retry === 'function') message.retry();
+        let retry = null;
+        if (typeof message?.retry === 'function') {
+          const attempt = Number.isInteger(message.attempts) ? message.attempts : (job.attempt + 1);
+          const maxAttempts = Math.max(1, Number(job.retry?.max_attempts) || 3);
+          if (attempt >= maxAttempts) {
+            // Do not ACK an exhausted provider-managed message here. A configured
+            // provider DLQ is the crash-safe fallback; retry/failure delivery lets
+            // the provider move it after max_retries instead of silently deleting it.
+            const delayMs = computeRetryDelayMs(job.retry, attempt);
+            const delaySeconds = Math.max(0, Math.ceil(delayMs / 1000));
+            message.retry(delaySeconds > 0 ? { delaySeconds } : undefined);
+            retry = {
+              scheduled: false,
+              exhausted: true,
+              provider_managed: true,
+              delegated_to_provider_dlq: true,
+              attempt,
+              delay_ms: delayMs,
+              delay_seconds: delaySeconds,
+            };
+          } else {
+            const delayMs = computeRetryDelayMs(job.retry, attempt);
+            const delaySeconds = Math.max(0, Math.ceil(delayMs / 1000));
+            message.retry(delaySeconds > 0 ? { delaySeconds } : undefined);
+            retry = { scheduled: true, provider_managed: true, attempt, delay_ms: delayMs, delay_seconds: delaySeconds };
+          }
+        } else if (job.logical_queue) {
+          const schedule = createRetrySchedule(job, { error });
+          if (schedule.retryable && schedule.job) {
+            const queue = resolvePhysicalQueue(this.topology, job.logical_queue);
+            await this.adapter.publish(queue, schedule.job, { logical_queue: job.logical_queue });
+            retry = {
+              scheduled: true,
+              provider_managed: false,
+              delay_ms: schedule.delay_ms,
+              available_at: schedule.available_at,
+              attempt: schedule.attempt,
+            };
+          } else {
+            const deadLetter = await this.deadLetter(job, error, { attempt: schedule.attempt });
+            retry = {
+              scheduled: false,
+              exhausted: true,
+              attempt: schedule.attempt,
+              dead_lettered: true,
+              dead_letter_job_id: deadLetter.job.id,
+              dead_letter_queue: deadLetter.queue,
+            };
+          }
+        }
         results.push({
           job_id: job.id,
           ok: false,
           error: String(error?.message || error),
           code: error?.code ?? null,
+          retry,
         });
       }
     }

package/packages/agentsam-queue-control/src/index.js

@@ -5,3 +5,4 @@ export * from './dispatch.js';
 export * from './control-plane.js';
 export * from './adapters/memory.js';
 export * from './adapters/cloudflare.js';
+export * from './adapters/sqlite.js';