@inneranimalmedia/agentsam-sdk 2.6.10 → 2.6.12

package/packages/agentsam-queue-control/README.md

@@ -11,7 +11,7 @@ The package deliberately separates four concerns:
 
 ## Goals
 
-- Cloudflare-first without Cloudflare lock-in.
+- Runs well on Cloudflare without Cloudflare lock-in.
 - One stable job envelope across CAD, code indexing, CMS, commerce, deployment, webhook, batch-AI, and future worker types.
 - Logical queues stay stable while physical topology can start compact and split later.
 - Deterministic routing keeps LLMs out of timers, polling loops, retries, and ordinary scheduling.
@@ -105,3 +105,6 @@ Queue Control does not replace `@inneranimalmedia/agentsam-work-graph`. A WorkGr
 ## Relationship to AgentSam tools and MCP
 
 The canonical capability/tool contract should sit above transports. A tool may be called inline, queued, from a WorkGraph, from a hook, from CLI, or exposed through MCP. Queue Control only owns execution routing and job lifecycle semantics.
+
+<!-- agentsam:trademark-notice -->
+> Independent project. Not affiliated with, endorsed by, or sponsored by Cloudflare, Inc. or by any other company whose products are named here. Cloudflare is a registered trademark of Cloudflare, Inc. Other names are trademarks of their respective owners. See [TRADEMARKS](https://github.com/SamPrimeaux/agentsam-sdk/blob/main/TRADEMARKS.md).

package/packages/agentsam-queue-control/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@inneranimalmedia/agentsam-queue-control",
-  "version": "2.6.10",
-  "description": "Portable AgentSam queue, job-routing, batching, and execution-control primitives with Cloudflare-first adapters.",
+  "version": "2.6.12",
+  "description": "Portable AgentSam queue, job-routing, retry, scheduling, and execution-control primitives with provider adapters.",
   "type": "module",
   "main": "./src/index.js",
   "exports": {
@@ -11,7 +11,8 @@
     "./topology": "./src/topology.js",
     "./dispatch": "./src/dispatch.js",
     "./adapters/memory": "./src/adapters/memory.js",
-    "./adapters/cloudflare": "./src/adapters/cloudflare.js"
+    "./adapters/cloudflare": "./src/adapters/cloudflare.js",
+    "./adapters/sqlite": "./src/adapters/sqlite.js"
   },
   "files": [
     "src",

package/packages/agentsam-queue-control/schemas/job-envelope.schema.json

@@ -14,11 +14,27 @@
     "created_at"
   ],
   "properties": {
-    "schema_version": { "const": "1" },
-    "id": { "type": "string", "minLength": 1 },
-    "account_id": { "type": "string", "minLength": 1 },
-    "kind": { "type": "string", "minLength": 1 },
-    "logical_queue": { "type": ["string", "null"] },
+    "schema_version": {
+      "const": "1"
+    },
+    "id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "account_id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "kind": {
+      "type": "string",
+      "minLength": 1
+    },
+    "logical_queue": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
     "executor": {
       "enum": [
         "inline",
@@ -31,7 +47,14 @@
         "external"
       ]
     },
-    "priority": { "enum": ["low", "normal", "high", "urgent"] },
+    "priority": {
+      "enum": [
+        "low",
+        "normal",
+        "high",
+        "urgent"
+      ]
+    },
     "status": {
       "enum": [
         "queued",
@@ -40,17 +63,94 @@
         "waiting",
         "batch_waiting",
         "awaiting_input",
+        "retry_scheduled",
         "completed",
         "failed",
         "cancelled"
       ]
     },
     "payload": {},
-    "payload_ref": { "type": ["string", "null"] },
-    "metadata": { "type": "object" },
-    "retry": { "type": "object" },
-    "attempt": { "type": "integer", "minimum": 0 },
-    "created_at": { "type": "integer", "minimum": 0 }
+    "payload_ref": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "metadata": {
+      "type": "object"
+    },
+    "retry": {
+      "type": "object",
+      "properties": {
+        "max_attempts": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "backoff": {
+          "enum": [
+            "fixed",
+            "exponential"
+          ]
+        },
+        "initial_delay_ms": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "max_delay_ms": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "jitter": {
+          "type": "boolean"
+        }
+      },
+      "additionalProperties": true
+    },
+    "attempt": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "created_at": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "available_at": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "source_run_id": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "step_id": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "idempotency_key": {
+      "type": "string",
+      "minLength": 1
+    },
+    "lease_owner": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "lease_expires_at": {
+      "type": [
+        "integer",
+        "null"
+      ],
+      "minimum": 0
+    },
+    "lease_generation": {
+      "type": "integer",
+      "minimum": 0
+    }
   },
   "additionalProperties": true
 }

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

@@ -6,6 +6,19 @@ function uniquePhysicalQueueNames(topology) {
   return [...new Set(Object.values(topology?.routes || {}).filter(Boolean))];
 }
 
+const MAX_CLOUDFLARE_DELAY_SECONDS = 86_400;
+
+export function delaySecondsForAvailableAt(availableAt, now = Math.floor(Date.now() / 1000)) {
+  if (availableAt == null) return 0;
+  const delay = Math.max(0, Math.ceil(Number(availableAt) - Number(now)));
+  if (delay > MAX_CLOUDFLARE_DELAY_SECONDS) {
+    const error = new RangeError('cloudflare_queue_delay_exceeds_24h');
+    error.code = 'delay_exceeds_provider_limit';
+    throw error;
+  }
+  return delay;
+}
+
 export class CloudflareQueueBindingAdapter {
   constructor({ bindings = {} } = {}) {
     this.bindings = bindings;
@@ -20,16 +33,25 @@ export class CloudflareQueueBindingAdapter {
   }
 
   async publish(queue, job, options = {}) {
-    await this.resolve(queue).send(job, options.send_options);
-    return { provider: 'cloudflare-binding', queue, accepted: 1 };
+    const sendOptions = { ...(options.send_options || {}) };
+    const delaySeconds = delaySecondsForAvailableAt(job.available_at, options.now);
+    if (delaySeconds > 0) sendOptions.delaySeconds = delaySeconds;
+    await this.resolve(queue).send(job, Object.keys(sendOptions).length ? sendOptions : undefined);
+    return { provider: 'cloudflare-binding', queue, accepted: 1, delay_seconds: delaySeconds };
   }
 
-  async publishBatch(queue, jobs) {
+  async publishBatch(queue, jobs, options = {}) {
     const binding = this.resolve(queue);
     if (typeof binding.sendBatch === 'function') {
-      await binding.sendBatch(jobs.map((body) => ({ body })));
+      await binding.sendBatch(jobs.map((body) => {
+        const delaySeconds = delaySecondsForAvailableAt(body.available_at, options.now);
+        return delaySeconds > 0 ? { body, delaySeconds } : { body };
+      }));
     } else {
-      await Promise.all(jobs.map((job) => binding.send(job)));
+      await Promise.all(jobs.map((job) => {
+        const delaySeconds = delaySecondsForAvailableAt(job.available_at, options.now);
+        return binding.send(job, delaySeconds > 0 ? { delaySeconds } : undefined);
+      }));
     }
     return { provider: 'cloudflare-binding', queue, accepted: jobs.length };
   }
@@ -91,6 +113,7 @@ export class CloudflareQueueApiAdapter {
     max_retries = 3,
     retry_delay = 5,
     max_concurrency,
+    dead_letter_queue = null,
   } = {}) {
     if (!script_name) throw new TypeError('script_name is required');
     const settings = {
@@ -109,6 +132,7 @@ export class CloudflareQueueApiAdapter {
       body: JSON.stringify({
         type: 'worker',
         script_name,
+        ...(dead_letter_queue ? { dead_letter_queue } : {}),
         settings,
       }),
     });
@@ -134,7 +158,11 @@ export class CloudflareQueueApiAdapter {
       if (consumer?.script_name) {
         const queueId = queue.queue_id ?? queue.id;
         if (!queueId) throw new Error(`cloudflare_queue_id_missing:${queueName}`);
-        await this.attachWorkerConsumer(queueId, consumer);
+        const physical = Object.values(topology.physical || {}).find((entry) => entry?.name === queueName);
+        await this.attachWorkerConsumer(queueId, {
+          ...consumer,
+          dead_letter_queue: consumer.dead_letter_queue || physical?.dead_letter || null,
+        });
       }
     }
 

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

@@ -18,8 +18,17 @@ export class MemoryQueueAdapter {
     return { provider: 'memory', queue, accepted: jobs.length };
   }
 
-  async pull(queue, max = 1) {
-    return this.#queue(queue).splice(0, Math.max(0, Number(max) || 1));
+  async pull(queue, max = 1, { now = Math.floor(Date.now() / 1000) } = {}) {
+    const items = this.#queue(queue);
+    const limit = Math.max(0, Number(max) || 1);
+    const ready = [];
+    const pending = [];
+    for (const item of items) {
+      if (ready.length < limit && (item.available_at ?? 0) <= now) ready.push(item);
+      else pending.push(item);
+    }
+    this.queues.set(queue, pending);
+    return ready;
   }
 
   async ensureTopology(topology) {

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 || {}))],
+    };
+  }
+}