@inneranimalmedia/agentsam-sdk 2.6.2 → 2.6.3

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

@@ -0,0 +1,152 @@
+function trimSlash(value) {
+  return String(value || '').replace(/\/+$/, '');
+}
+
+function uniquePhysicalQueueNames(topology) {
+  return [...new Set(Object.values(topology?.routes || {}).filter(Boolean))];
+}
+
+export class CloudflareQueueBindingAdapter {
+  constructor({ bindings = {} } = {}) {
+    this.bindings = bindings;
+  }
+
+  resolve(queue) {
+    const binding = this.bindings[queue] ?? this.bindings.default ?? null;
+    if (!binding || typeof binding.send !== 'function') {
+      throw new Error(`cloudflare_queue_binding_missing:${queue}`);
+    }
+    return binding;
+  }
+
+  async publish(queue, job, options = {}) {
+    await this.resolve(queue).send(job, options.send_options);
+    return { provider: 'cloudflare-binding', queue, accepted: 1 };
+  }
+
+  async publishBatch(queue, jobs) {
+    const binding = this.resolve(queue);
+    if (typeof binding.sendBatch === 'function') {
+      await binding.sendBatch(jobs.map((body) => ({ body })));
+    } else {
+      await Promise.all(jobs.map((job) => binding.send(job)));
+    }
+    return { provider: 'cloudflare-binding', queue, accepted: jobs.length };
+  }
+}
+
+export class CloudflareQueueApiAdapter {
+  constructor({
+    cloudflareAccountId,
+    apiToken,
+    fetchImpl = fetch,
+    apiBase = 'https://api.cloudflare.com/client/v4',
+  } = {}) {
+    if (!cloudflareAccountId) throw new TypeError('cloudflareAccountId is required');
+    if (!apiToken) throw new TypeError('apiToken is required');
+    this.cloudflareAccountId = cloudflareAccountId;
+    this.apiToken = apiToken;
+    this.fetchImpl = fetchImpl;
+    this.apiBase = trimSlash(apiBase);
+  }
+
+  async request(path, init = {}) {
+    const response = await this.fetchImpl(`${this.apiBase}${path}`, {
+      ...init,
+      headers: {
+        authorization: `Bearer ${this.apiToken}`,
+        'content-type': 'application/json',
+        ...(init.headers || {}),
+      },
+    });
+    const body = await response.json().catch(() => null);
+    if (!response.ok || body?.success === false) {
+      const error = new Error(body?.errors?.[0]?.message || `cloudflare_http_${response.status}`);
+      error.code = body?.errors?.[0]?.code ? String(body.errors[0].code) : `cloudflare_http_${response.status}`;
+      error.status = response.status;
+      error.response = body;
+      throw error;
+    }
+    return body?.result ?? body;
+  }
+
+  async listQueues() {
+    const path = `/accounts/${encodeURIComponent(this.cloudflareAccountId)}/queues`;
+    const result = await this.request(path, { method: 'GET' });
+    return Array.isArray(result) ? result : [];
+  }
+
+  async createQueue(queueName) {
+    const path = `/accounts/${encodeURIComponent(this.cloudflareAccountId)}/queues`;
+    return this.request(path, {
+      method: 'POST',
+      body: JSON.stringify({ queue_name: queueName }),
+    });
+  }
+
+  async attachWorkerConsumer(queueId, {
+    script_name,
+    batch_size = 10,
+    max_wait_time_ms = 5_000,
+    max_retries = 3,
+    retry_delay = 5,
+    max_concurrency,
+  } = {}) {
+    if (!script_name) throw new TypeError('script_name is required');
+    const settings = {
+      batch_size,
+      max_wait_time_ms,
+      max_retries,
+      retry_delay,
+    };
+    if (Number.isInteger(max_concurrency) && max_concurrency > 0) {
+      settings.max_concurrency = max_concurrency;
+    }
+
+    const path = `/accounts/${encodeURIComponent(this.cloudflareAccountId)}/queues/${encodeURIComponent(queueId)}/consumers`;
+    return this.request(path, {
+      method: 'POST',
+      body: JSON.stringify({
+        type: 'worker',
+        script_name,
+        settings,
+      }),
+    });
+  }
+
+  async ensureTopology(topology, options = {}) {
+    const existing = await this.listQueues();
+    const byName = new Map(existing.map((queue) => [queue.queue_name ?? queue.name, queue]));
+    const created = [];
+    const present = [];
+
+    for (const queueName of uniquePhysicalQueueNames(topology)) {
+      let queue = byName.get(queueName);
+      if (!queue) {
+        queue = await this.createQueue(queueName);
+        created.push(queueName);
+        byName.set(queueName, queue);
+      } else {
+        present.push(queueName);
+      }
+
+      const consumer = options.consumers?.[queueName];
+      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);
+      }
+    }
+
+    return {
+      provider: 'cloudflare-api',
+      created,
+      existing: present,
+      queues: [...byName.values()],
+    };
+  }
+
+  async publish() {
+    throw new Error('cloudflare_api_adapter_publish_not_supported_use_queue_binding_or_http_producer');
+  }
+}

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

@@ -0,0 +1,38 @@
+export class MemoryQueueAdapter {
+  constructor() {
+    this.queues = new Map();
+  }
+
+  #queue(name) {
+    if (!this.queues.has(name)) this.queues.set(name, []);
+    return this.queues.get(name);
+  }
+
+  async publish(queue, job) {
+    this.#queue(queue).push(structuredClone(job));
+    return { provider: 'memory', queue, accepted: 1 };
+  }
+
+  async publishBatch(queue, jobs) {
+    this.#queue(queue).push(...jobs.map((job) => structuredClone(job)));
+    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 ensureTopology(topology) {
+    const names = new Set(Object.values(topology.routes || {}));
+    for (const name of names) this.#queue(name);
+    return {
+      provider: 'memory',
+      created: [...names],
+      existing: [],
+    };
+  }
+
+  depth(queue) {
+    return this.#queue(queue).length;
+  }
+}

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

@@ -0,0 +1,130 @@
+import { randomUUID } from 'node:crypto';
+
+export const JOB_STATUSES = Object.freeze([
+  'queued',
+  'claimed',
+  'running',
+  'waiting',
+  'batch_waiting',
+  'awaiting_input',
+  'completed',
+  'failed',
+  'cancelled',
+]);
+
+export const TERMINAL_JOB_STATUSES = Object.freeze([
+  'completed',
+  'failed',
+  'cancelled',
+]);
+
+export const JOB_PRIORITIES = Object.freeze(['low', 'normal', 'high', 'urgent']);
+
+export const EXECUTOR_KINDS = Object.freeze([
+  'inline',
+  'queue',
+  'workflow',
+  'execos',
+  'worker_rpc',
+  'openai_batch',
+  'gemini_batch',
+  'external',
+]);
+
+export const DEFAULT_RETRY_POLICY = Object.freeze({
+  max_attempts: 3,
+  backoff: 'exponential',
+  initial_delay_ms: 1_000,
+  max_delay_ms: 60_000,
+});
+
+function clean(value) {
+  return value == null ? '' : String(value).trim();
+}
+
+function assertEnum(value, allowed, field) {
+  if (!allowed.includes(value)) {
+    throw new TypeError(`${field} must be one of: ${allowed.join(', ')}`);
+  }
+}
+
+export function createJobEnvelope(input = {}) {
+  const kind = clean(input.kind);
+  if (!kind) throw new TypeError('kind is required');
+
+  const accountId = clean(input.account_id);
+  if (!accountId) throw new TypeError('account_id is required');
+
+  const now = input.created_at ?? Math.floor(Date.now() / 1000);
+  const priority = input.priority ?? 'normal';
+  assertEnum(priority, JOB_PRIORITIES, 'priority');
+
+  const executor = input.executor ?? 'queue';
+  assertEnum(executor, EXECUTOR_KINDS, 'executor');
+
+  return {
+    schema_version: '1',
+    id: clean(input.id) || `job_${randomUUID().replaceAll('-', '')}`,
+    account_id: accountId,
+    kind,
+    logical_queue: clean(input.logical_queue) || null,
+    executor,
+    priority,
+    status: input.status ?? 'queued',
+    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,
+    payload: input.payload ?? null,
+    payload_ref: clean(input.payload_ref) || null,
+    metadata: input.metadata && typeof input.metadata === 'object' ? input.metadata : {},
+    retry: {
+      ...DEFAULT_RETRY_POLICY,
+      ...(input.retry && typeof input.retry === 'object' ? input.retry : {}),
+    },
+    attempt: Number.isInteger(input.attempt) ? input.attempt : 0,
+    created_at: now,
+  };
+}
+
+export function assertJobEnvelope(job) {
+  if (!job || typeof job !== 'object') throw new TypeError('job envelope must be an object');
+  if (job.schema_version !== '1') throw new TypeError('unsupported job schema_version');
+  if (!clean(job.id)) throw new TypeError('job.id is required');
+  if (!clean(job.account_id)) throw new TypeError('job.account_id is required');
+  if (!clean(job.kind)) throw new TypeError('job.kind is required');
+  assertEnum(job.priority ?? 'normal', JOB_PRIORITIES, 'job.priority');
+  assertEnum(job.executor ?? 'queue', EXECUTOR_KINDS, 'job.executor');
+  assertEnum(job.status ?? 'queued', JOB_STATUSES, 'job.status');
+  return job;
+}
+
+export function createReceipt(job, input = {}) {
+  assertJobEnvelope(job);
+  const status = input.status ?? 'completed';
+  assertEnum(status, JOB_STATUSES, 'receipt.status');
+
+  return {
+    schema_version: '1',
+    receipt_id: clean(input.receipt_id) || `receipt_${randomUUID().replaceAll('-', '')}`,
+    job_id: job.id,
+    account_id: job.account_id,
+    kind: job.kind,
+    status,
+    executor: input.executor ?? job.executor,
+    provider: clean(input.provider) || null,
+    provider_job_id: clean(input.provider_job_id) || null,
+    result: input.result ?? null,
+    result_ref: clean(input.result_ref) || null,
+    error: input.error ?? null,
+    attempt: Number.isInteger(input.attempt) ? input.attempt : job.attempt,
+    started_at: input.started_at ?? null,
+    completed_at: input.completed_at ?? Math.floor(Date.now() / 1000),
+    metadata: input.metadata && typeof input.metadata === 'object' ? input.metadata : {},
+  };
+}
+
+export function isTerminalJobStatus(status) {
+  return TERMINAL_JOB_STATUSES.includes(status);
+}

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

@@ -0,0 +1,141 @@
+import { createJobEnvelope, assertJobEnvelope } from './contracts.js';
+import { buildQueueTopology, resolvePhysicalQueue } from './topology.js';
+import { routeWork, shouldRequireProvisionApproval } from './policy.js';
+import { JobDispatcher } from './dispatch.js';
+
+export class QueueControl {
+  constructor({
+    adapter,
+    topology = buildQueueTopology(),
+    routingPolicy = {},
+    approval = null,
+    dispatcher = new JobDispatcher(),
+  } = {}) {
+    if (!adapter) throw new TypeError('adapter is required');
+    this.adapter = adapter;
+    this.topology = topology;
+    this.routingPolicy = routingPolicy;
+    this.approval = approval;
+    this.dispatcher = dispatcher;
+  }
+
+  register(kind, handler) {
+    this.dispatcher.register(kind, handler);
+    return this;
+  }
+
+  plan(task) {
+    const route = routeWork(task, this.routingPolicy);
+    return {
+      ...route,
+      physical_queue: route.logical_queue === 'interactive'
+        ? null
+        : resolvePhysicalQueue(this.topology, route.logical_queue),
+    };
+  }
+
+  async enqueue(task, input = {}) {
+    const plan = this.plan(task);
+    const job = createJobEnvelope({
+      ...input,
+      kind: task.kind,
+      payload: input.payload ?? task.payload ?? null,
+      account_id: input.account_id ?? task.account_id,
+      logical_queue: plan.logical_queue,
+      executor: plan.executor,
+      priority: input.priority ?? task.priority ?? 'normal',
+    });
+
+    if (plan.mode === 'interactive') {
+      return { job, plan, published: false };
+    }
+
+    assertJobEnvelope(job);
+    const physicalQueue = resolvePhysicalQueue(this.topology, plan.logical_queue);
+    const receipt = await this.adapter.publish(physicalQueue, job, {
+      logical_queue: plan.logical_queue,
+    });
+    return { job, plan, published: true, publish_receipt: receipt ?? null };
+  }
+
+  async enqueueMany(tasks, common = {}) {
+    const grouped = new Map();
+
+    for (const task of tasks) {
+      const plan = this.plan(task);
+      if (plan.mode === 'interactive') {
+        throw new Error('enqueueMany does not accept interactive tasks');
+      }
+      const job = createJobEnvelope({
+        ...common,
+        account_id: common.account_id ?? task.account_id,
+        kind: task.kind,
+        payload: task.payload ?? null,
+        logical_queue: plan.logical_queue,
+        executor: plan.executor,
+        priority: task.priority ?? common.priority ?? 'normal',
+      });
+      const queue = resolvePhysicalQueue(this.topology, plan.logical_queue);
+      const bucket = grouped.get(queue) ?? [];
+      bucket.push(job);
+      grouped.set(queue, bucket);
+    }
+
+    const receipts = [];
+    for (const [queue, jobs] of grouped) {
+      const receipt = this.adapter.publishBatch
+        ? await this.adapter.publishBatch(queue, jobs)
+        : await Promise.all(jobs.map((job) => this.adapter.publish(queue, job)));
+      receipts.push({ queue, count: jobs.length, receipt });
+    }
+    return receipts;
+  }
+
+  async provision(options = {}) {
+    if (typeof this.adapter.ensureTopology !== 'function') {
+      throw new Error('adapter_does_not_support_provisioning');
+    }
+
+    if (shouldRequireProvisionApproval('provision', this.routingPolicy)) {
+      if (typeof this.approval !== 'function') {
+        const error = new Error('queue_provision_approval_required');
+        error.code = 'approval_required';
+        throw error;
+      }
+      const allowed = await this.approval({
+        action: 'provision',
+        topology: this.topology,
+        options,
+      });
+      if (!allowed) {
+        const error = new Error('queue_provision_denied');
+        error.code = 'approval_denied';
+        throw error;
+      }
+    }
+
+    return this.adapter.ensureTopology(this.topology, options);
+  }
+
+  async consume(messages, context = {}) {
+    const results = [];
+    for (const message of messages) {
+      const job = message?.body ?? message;
+      assertJobEnvelope(job);
+      try {
+        const result = await this.dispatcher.dispatch(job, context);
+        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();
+        results.push({
+          job_id: job.id,
+          ok: false,
+          error: String(error?.message || error),
+          code: error?.code ?? null,
+        });
+      }
+    }
+    return results;
+  }
+}

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

@@ -0,0 +1,43 @@
+export class JobDispatcher {
+  #handlers = new Map();
+
+  register(kind, handler) {
+    if (!kind || typeof handler !== 'function') {
+      throw new TypeError('register(kind, handler) requires a kind and function');
+    }
+    this.#handlers.set(kind, handler);
+    return this;
+  }
+
+  unregister(kind) {
+    return this.#handlers.delete(kind);
+  }
+
+  resolve(kind) {
+    if (this.#handlers.has(kind)) return this.#handlers.get(kind);
+
+    let best = null;
+    for (const [registered, handler] of this.#handlers.entries()) {
+      if (!registered.endsWith('*')) continue;
+      const prefix = registered.slice(0, -1);
+      if (kind.startsWith(prefix) && (!best || prefix.length > best.prefix.length)) {
+        best = { prefix, handler };
+      }
+    }
+    return best?.handler ?? null;
+  }
+
+  async dispatch(job, context = {}) {
+    const handler = this.resolve(job.kind);
+    if (!handler) {
+      const error = new Error(`job_handler_not_found:${job.kind}`);
+      error.code = 'job_handler_not_found';
+      throw error;
+    }
+    return handler(job, context);
+  }
+
+  kinds() {
+    return [...this.#handlers.keys()];
+  }
+}

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

@@ -0,0 +1,7 @@
+export * from './contracts.js';
+export * from './policy.js';
+export * from './topology.js';
+export * from './dispatch.js';
+export * from './control-plane.js';
+export * from './adapters/memory.js';
+export * from './adapters/cloudflare.js';

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

@@ -0,0 +1,88 @@
+const DEFAULT_KIND_ROUTES = Object.freeze({
+  'deploy.': { logical_queue: 'deployments', executor: 'workflow' },
+  'infra.': { logical_queue: 'deployments', executor: 'workflow' },
+  'cad.': { logical_queue: 'cad', executor: 'queue' },
+  'code.index': { logical_queue: 'indexing', executor: 'queue' },
+  'repository.index': { logical_queue: 'indexing', executor: 'queue' },
+  'cms.': { logical_queue: 'cms', executor: 'queue' },
+  'commerce.': { logical_queue: 'cms', executor: 'queue' },
+  'webhook.': { logical_queue: 'webhooks', executor: 'queue' },
+});
+
+function firstKindMatch(kind, routes) {
+  for (const [prefix, route] of Object.entries(routes)) {
+    if (kind === prefix || kind.startsWith(prefix)) return route;
+  }
+  return null;
+}
+
+export function routeWork(task = {}, policy = {}) {
+  const kind = String(task.kind || '').trim();
+  if (!kind) throw new TypeError('task.kind is required');
+
+  if (task.interactive === true || task.requires_immediate_response === true) {
+    return {
+      mode: 'interactive',
+      logical_queue: 'interactive',
+      executor: 'inline',
+      reason: 'interactive_requirement',
+    };
+  }
+
+  const aiCalls = Number(task.estimated_ai_calls || 0);
+  const independent = task.independent_items === true || Number(task.item_count || 0) > 1;
+  const latency = task.latency ?? 'normal';
+  const batchThreshold = Number(policy.batch_ai_min_calls ?? 50);
+
+  if (
+    task.ai_provider &&
+    aiCalls >= batchThreshold &&
+    independent &&
+    ['deferred', 'background', 'hours'].includes(latency)
+  ) {
+    const provider = String(task.ai_provider).toLowerCase();
+    if (provider === 'openai' || provider === 'google' || provider === 'gemini') {
+      return {
+        mode: 'batch_ai',
+        logical_queue: 'batch_ai',
+        executor: provider === 'openai' ? 'openai_batch' : 'gemini_batch',
+        reason: 'bulk_independent_ai_work',
+      };
+    }
+  }
+
+  const configuredRoutes = {
+    ...DEFAULT_KIND_ROUTES,
+    ...(policy.kind_routes || {}),
+  };
+  const matched = firstKindMatch(kind, configuredRoutes);
+  if (matched) {
+    return {
+      mode: 'background',
+      ...matched,
+      reason: 'kind_policy',
+    };
+  }
+
+  if (task.machine_required === true) {
+    return {
+      mode: 'background',
+      logical_queue: 'jobs',
+      executor: 'execos',
+      reason: 'machine_requirement',
+    };
+  }
+
+  return {
+    mode: 'background',
+    logical_queue: 'jobs',
+    executor: 'queue',
+    reason: 'default_durable_work',
+  };
+}
+
+export function shouldRequireProvisionApproval(action, policy = {}) {
+  const normalized = String(action || '');
+  if (policy.allow_infrastructure_mutation === true) return false;
+  return ['provision', 'configure', 'delete'].includes(normalized);
+}

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

@@ -0,0 +1,66 @@
+export const DEFAULT_LOGICAL_QUEUES = Object.freeze({
+  interactive: { lane: 'interactive', durability: 'best_effort' },
+  jobs: { lane: 'general', durability: 'durable' },
+  deployments: { lane: 'infra', durability: 'durable' },
+  cad: { lane: 'compute', durability: 'durable' },
+  indexing: { lane: 'compute', durability: 'durable' },
+  cms: { lane: 'business', durability: 'durable' },
+  webhooks: { lane: 'events', durability: 'durable' },
+  batch_ai: { lane: 'ai', durability: 'durable' },
+  dead_letter: { lane: 'failure', durability: 'durable' },
+});
+
+export function buildQueueTopology({
+  namespace = 'agentsam',
+  environment = 'dev',
+  mode = 'compact',
+  logicalQueues = DEFAULT_LOGICAL_QUEUES,
+} = {}) {
+  if (!['compact', 'segmented'].includes(mode)) {
+    throw new TypeError('mode must be compact or segmented');
+  }
+
+  const prefix = [namespace, environment].filter(Boolean).join('-');
+  const physical = {};
+  const routes = {};
+
+  if (mode === 'compact') {
+    physical.jobs = {
+      name: `${prefix}-jobs`,
+      dead_letter: `${prefix}-dlq`,
+    };
+    for (const key of Object.keys(logicalQueues)) {
+      if (key === 'interactive') continue;
+      routes[key] = key === 'dead_letter' ? physical.jobs.dead_letter : physical.jobs.name;
+    }
+  } else {
+    for (const [key, config] of Object.entries(logicalQueues)) {
+      if (key === 'interactive') continue;
+      const name = key === 'dead_letter'
+        ? `${prefix}-dlq`
+        : `${prefix}-${config.lane || key}`;
+      physical[key] = {
+        name,
+        dead_letter: key === 'dead_letter' ? null : `${prefix}-dlq`,
+      };
+      routes[key] = name;
+    }
+  }
+
+  return {
+    schema_version: '1',
+    mode,
+    namespace,
+    environment,
+    logical_queues: logicalQueues,
+    physical,
+    routes,
+  };
+}
+
+export function resolvePhysicalQueue(topology, logicalQueue) {
+  if (!topology?.routes) throw new TypeError('topology.routes is required');
+  const value = topology.routes[logicalQueue];
+  if (!value) throw new Error(`logical_queue_not_routed:${logicalQueue}`);
+  return value;
+}