@absolutejs/agent-runtime 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AbsoluteJS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,36 @@
+# @absolutejs/agent-runtime
+
+Durable, provider-neutral orchestration for AI agents. This package owns runs,
+steps, leases, budgets, checkpoints, timers, cancellation, effects, and handoffs.
+It does not choose a model, database driver, queue, or web framework.
+
+Every run pins the exact signed discovery descriptor id, version, and digest that
+was selected. A remote agent therefore cannot silently replace its advertised
+capabilities during a workflow or handoff.
+
+```ts
+const runtime = createAgentRuntime({
+  store: createPostgresAgentRuntimeStore({ client: sql }),
+  driver: myModelAdapter,
+  effects: executionAdapter,
+});
+
+await runtime.start({
+  actor: { tenantId, userId, agentId, delegationId },
+  agent: selectedDiscoveryIdentity,
+  goal: "Rebook the delayed flight",
+  input,
+  budget: { actions: 8, costMicros: 50_000, spendMinor: 30_000 },
+});
+```
+
+Workers claim due runs with `FOR UPDATE SKIP LOCKED`. Every append checks the
+lease, optimistic version, sequence, idempotency key, and budget inside one
+transaction. Effects are recorded as requested before execution and require a
+stable idempotency key; use `@absolutejs/execution` as the executor for crash-safe
+external effects and reconciliation.
+
+PostgreSQL is the durable default. Apply `agentRuntimePostgresSchemaSql()` through
+your migrations. Redis is not a run store or work queue.
+
+Memory stores are development and test defaults only.

package/dist/budget.d.ts

@@ -0,0 +1,6 @@
+import type { AgentBudget, AgentBudgetUsage } from "./types";
+export declare const zeroUsage: () => AgentBudgetUsage;
+export declare const normalizeUsage: (value?: AgentBudget) => AgentBudgetUsage;
+export declare const addUsage: (left: AgentBudgetUsage, right: AgentBudgetUsage) => AgentBudgetUsage;
+export declare const remainingBudget: (budget: AgentBudget, usage: AgentBudgetUsage) => AgentBudgetUsage;
+export declare const budgetExceeded: (budget: AgentBudget, usage: AgentBudgetUsage, requested: AgentBudgetUsage) => keyof AgentBudget | undefined;

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./types";
+export * from "./budget";
+export * from "./memory";
+export * from "./runtime";
+export * from "./postgres";

package/dist/index.js

@@ -0,0 +1,639 @@
+// @bun
+// src/budget.ts
+var zeroUsage = () => ({
+  actions: 0,
+  costMicros: 0,
+  inputTokens: 0,
+  outputTokens: 0,
+  spendMinor: 0,
+  wallTimeMs: 0
+});
+var normalizeUsage = (value = {}) => {
+  const result = { ...zeroUsage(), ...value };
+  for (const [name, amount] of Object.entries(result)) {
+    if (!Number.isSafeInteger(amount) || amount < 0)
+      throw new Error(`Invalid budget usage: ${name}`);
+  }
+  return result;
+};
+var addUsage = (left, right) => ({
+  actions: left.actions + right.actions,
+  costMicros: left.costMicros + right.costMicros,
+  inputTokens: left.inputTokens + right.inputTokens,
+  outputTokens: left.outputTokens + right.outputTokens,
+  spendMinor: left.spendMinor + right.spendMinor,
+  wallTimeMs: left.wallTimeMs + right.wallTimeMs
+});
+var remainingBudget = (budget, usage) => ({
+  actions: Math.max(0, (budget.actions ?? Number.MAX_SAFE_INTEGER) - usage.actions),
+  costMicros: Math.max(0, (budget.costMicros ?? Number.MAX_SAFE_INTEGER) - usage.costMicros),
+  inputTokens: Math.max(0, (budget.inputTokens ?? Number.MAX_SAFE_INTEGER) - usage.inputTokens),
+  outputTokens: Math.max(0, (budget.outputTokens ?? Number.MAX_SAFE_INTEGER) - usage.outputTokens),
+  spendMinor: Math.max(0, (budget.spendMinor ?? Number.MAX_SAFE_INTEGER) - usage.spendMinor),
+  wallTimeMs: Math.max(0, (budget.wallTimeMs ?? Number.MAX_SAFE_INTEGER) - usage.wallTimeMs)
+});
+var budgetExceeded = (budget, usage, requested) => {
+  const next = addUsage(usage, requested);
+  return Object.keys(next).find((name) => budget[name] !== undefined && next[name] > (budget[name] ?? 0));
+};
+// src/memory.ts
+var clone = (value) => structuredClone(value);
+var createMemoryAgentRuntimeStore = () => {
+  const runs = new Map;
+  const steps = new Map;
+  const idempotency = new Set;
+  return {
+    createRun: async (run) => {
+      if (runs.has(run.id))
+        throw new Error("Run already exists");
+      runs.set(run.id, clone(run));
+      steps.set(run.id, []);
+    },
+    getRun: async (id) => clone(runs.get(id)),
+    listSteps: async (runId) => clone(steps.get(runId) ?? []),
+    claimDue: async ({ workerId, now, leaseExpiresAt }) => {
+      const timestamp = Date.parse(now);
+      const due = [...runs.values()].filter((run) => (run.status === "queued" || run.status === "waiting" && Date.parse(run.wakeAt ?? "") <= timestamp || run.status === "running" && Date.parse(run.leaseExpiresAt ?? "") <= timestamp) && run.cancelRequestedAt === undefined).sort((left, right) => left.createdAt.localeCompare(right.createdAt))[0];
+      if (!due)
+        return;
+      const next = {
+        ...due,
+        status: "running",
+        leaseOwner: workerId,
+        leaseExpiresAt,
+        wakeAt: undefined,
+        version: due.version + 1,
+        updatedAt: now
+      };
+      runs.set(next.id, next);
+      return clone(next);
+    },
+    heartbeat: async ({
+      runId,
+      workerId,
+      expectedVersion,
+      leaseExpiresAt,
+      now
+    }) => {
+      const run = runs.get(runId);
+      if (!run || run.version !== expectedVersion || run.leaseOwner !== workerId || run.status !== "running")
+        return;
+      const next = {
+        ...run,
+        leaseExpiresAt,
+        version: run.version + 1,
+        updatedAt: now
+      };
+      runs.set(runId, next);
+      return clone(next);
+    },
+    appendStep: async ({ runId, workerId, expectedVersion, step, now }) => {
+      const run = runs.get(runId);
+      if (!run || run.version !== expectedVersion || run.leaseOwner !== workerId || run.status !== "running")
+        return;
+      const key = step.idempotencyKey ? `${runId}:${step.idempotencyKey}:${step.kind}` : undefined;
+      if (key && idempotency.has(key))
+        return clone(run);
+      const exceeded = budgetExceeded(run.budget, run.usage, step.usage);
+      if (exceeded)
+        throw new Error(`Agent budget exceeded: ${exceeded}`);
+      const list = steps.get(runId) ?? [];
+      if (step.sequence !== list.length + 1)
+        return;
+      list.push(clone(step));
+      if (key)
+        idempotency.add(key);
+      const next = {
+        ...run,
+        usage: addUsage(run.usage, step.usage),
+        version: run.version + 1,
+        updatedAt: now
+      };
+      runs.set(runId, next);
+      return clone(next);
+    },
+    transition: async ({
+      runId,
+      workerId,
+      expectedVersion,
+      status,
+      now,
+      output,
+      checkpoint,
+      wakeAt,
+      error
+    }) => {
+      const run = runs.get(runId);
+      if (!run || run.version !== expectedVersion || workerId && run.leaseOwner !== workerId)
+        return;
+      const next = {
+        ...run,
+        status,
+        version: run.version + 1,
+        updatedAt: now,
+        ...output === undefined ? {} : { output },
+        ...checkpoint === undefined ? {} : { checkpoint },
+        ...wakeAt === undefined ? {} : { wakeAt },
+        ...error === undefined ? {} : { error },
+        ...status === "running" ? {} : { leaseOwner: undefined, leaseExpiresAt: undefined }
+      };
+      runs.set(runId, next);
+      return clone(next);
+    },
+    requestCancel: async ({ runId, now }) => {
+      const run = runs.get(runId);
+      if (!run)
+        return;
+      const terminal = [
+        "completed",
+        "failed",
+        "cancelled",
+        "handed_off"
+      ].includes(run.status);
+      if (terminal)
+        return clone(run);
+      const canCancelImmediately = run.status !== "running";
+      const next = {
+        ...run,
+        status: canCancelImmediately ? "cancelled" : run.status,
+        cancelRequestedAt: now,
+        version: run.version + 1,
+        updatedAt: now,
+        ...canCancelImmediately ? {
+          leaseOwner: undefined,
+          leaseExpiresAt: undefined,
+          wakeAt: undefined
+        } : {}
+      };
+      runs.set(runId, next);
+      return clone(next);
+    }
+  };
+};
+// src/runtime.ts
+var makeId = () => crypto.randomUUID();
+var createAgentRuntime = ({
+  store,
+  driver,
+  effects,
+  now = Date.now,
+  id = makeId,
+  leaseMs = 30000,
+  maxStepsPerClaim = 25,
+  onEvent
+}) => {
+  const emit = async (event) => {
+    await onEvent?.(event);
+  };
+  const transition = async (run, workerId, change) => {
+    const updated = await store.transition({
+      runId: run.id,
+      workerId,
+      expectedVersion: run.version,
+      now: new Date(now()).toISOString(),
+      ...change
+    });
+    if (!updated)
+      throw new Error("Agent run lease or version was lost");
+    await emit({ type: "run.transitioned", run: updated });
+    return updated;
+  };
+  const append = async (run, workerId, value) => {
+    const steps = await store.listSteps(run.id);
+    const step = {
+      ...value,
+      id: id(),
+      runId: run.id,
+      sequence: steps.length + 1,
+      createdAt: new Date(now()).toISOString(),
+      usage: normalizeUsage(value.usage)
+    };
+    const updated = await store.appendStep({
+      runId: run.id,
+      workerId,
+      expectedVersion: run.version,
+      step,
+      now: step.createdAt
+    });
+    if (!updated)
+      throw new Error("Agent run lease, sequence, or version was lost");
+    await emit({ type: "step.appended", run: updated, step });
+    return { run: updated, step };
+  };
+  const handle = async (run, workerId, result) => {
+    if (result.type === "continue")
+      return (await append(run, workerId, {
+        kind: result.kind ?? "observation",
+        name: result.name,
+        input: result.input,
+        output: result.output,
+        usage: result.usage
+      })).run;
+    if (result.type === "effect") {
+      const requested = await append(run, workerId, {
+        kind: "effect.requested",
+        name: result.name,
+        input: result.input,
+        idempotencyKey: result.idempotencyKey,
+        usage: { ...result.usage, actions: (result.usage?.actions ?? 0) + 1 }
+      });
+      try {
+        const output = await effects.execute({
+          run: requested.run,
+          step: requested.step,
+          name: result.name,
+          payload: result.input,
+          idempotencyKey: result.idempotencyKey
+        });
+        return (await append(requested.run, workerId, {
+          kind: "effect.completed",
+          name: result.name,
+          output,
+          idempotencyKey: result.idempotencyKey
+        })).run;
+      } catch (error) {
+        const failed2 = await append(requested.run, workerId, {
+          kind: "effect.failed",
+          name: result.name,
+          output: {
+            message: error instanceof Error ? error.message : "Effect failed"
+          },
+          idempotencyKey: result.idempotencyKey
+        });
+        return transition(failed2.run, workerId, {
+          status: "failed",
+          error: {
+            code: "effect_failed",
+            message: error instanceof Error ? error.message : "Effect failed",
+            retryable: true
+          }
+        });
+      }
+    }
+    if (result.type === "checkpoint") {
+      const checkpointed = await append(run, workerId, {
+        kind: "checkpoint",
+        output: { reason: result.reason, checkpoint: result.checkpoint }
+      });
+      return transition(checkpointed.run, workerId, {
+        status: "suspended",
+        checkpoint: result.checkpoint
+      });
+    }
+    if (result.type === "wait") {
+      if (!Number.isFinite(Date.parse(result.until)))
+        throw new Error("Invalid wait timestamp");
+      const waiting = await append(run, workerId, {
+        kind: "wait",
+        output: { reason: result.reason, until: result.until }
+      });
+      return transition(waiting.run, workerId, {
+        status: "waiting",
+        wakeAt: result.until,
+        checkpoint: result.checkpoint
+      });
+    }
+    if (result.type === "handoff") {
+      const handed = await append(run, workerId, {
+        kind: "handoff",
+        output: {
+          target: result.target,
+          input: result.input,
+          reason: result.reason
+        }
+      });
+      return transition(handed.run, workerId, {
+        status: "handed_off",
+        output: {
+          target: result.target,
+          input: result.input,
+          reason: result.reason
+        }
+      });
+    }
+    if (result.type === "complete") {
+      const completed = await append(run, workerId, {
+        kind: "completed",
+        output: result.output
+      });
+      return transition(completed.run, workerId, {
+        status: "completed",
+        output: result.output
+      });
+    }
+    const failed = await append(run, workerId, {
+      kind: "failed",
+      output: { code: result.code, message: result.message }
+    });
+    return transition(failed.run, workerId, {
+      status: "failed",
+      error: {
+        code: result.code,
+        message: result.message,
+        retryable: result.retryable ?? false
+      }
+    });
+  };
+  const resumePendingEffect = async (run, workerId, steps) => {
+    const requested = steps.at(-1);
+    if (requested?.kind !== "effect.requested" || !requested.name || !requested.idempotencyKey)
+      return;
+    try {
+      const output = await effects.execute({
+        run,
+        step: requested,
+        name: requested.name,
+        payload: requested.input,
+        idempotencyKey: requested.idempotencyKey
+      });
+      return (await append(run, workerId, {
+        kind: "effect.completed",
+        name: requested.name,
+        output,
+        idempotencyKey: requested.idempotencyKey
+      })).run;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Effect failed";
+      const failed = await append(run, workerId, {
+        kind: "effect.failed",
+        name: requested.name,
+        output: { message },
+        idempotencyKey: requested.idempotencyKey
+      });
+      return transition(failed.run, workerId, {
+        status: "failed",
+        error: { code: "effect_failed", message, retryable: true }
+      });
+    }
+  };
+  return {
+    start: async (input) => {
+      const timestamp = new Date(now()).toISOString();
+      const run = {
+        id: input.idempotencyKey ?? id(),
+        actor: input.actor,
+        agent: input.agent,
+        goal: input.goal,
+        input: input.input,
+        ...input.parentRunId ? { parentRunId: input.parentRunId } : {},
+        status: "queued",
+        budget: input.budget ?? {},
+        usage: zeroUsage(),
+        version: 0,
+        createdAt: timestamp,
+        updatedAt: timestamp
+      };
+      await store.createRun(run);
+      await emit({ type: "run.created", run });
+      return run;
+    },
+    cancel: (runId) => store.requestCancel({ runId, now: new Date(now()).toISOString() }),
+    inspect: async (runId) => {
+      const run = await store.getRun(runId);
+      return run ? { run, steps: await store.listSteps(runId) } : undefined;
+    },
+    workOne: async (workerId) => {
+      const claimedAt = now();
+      let run = await store.claimDue({
+        workerId,
+        now: new Date(claimedAt).toISOString(),
+        leaseExpiresAt: new Date(claimedAt + leaseMs).toISOString()
+      });
+      if (!run)
+        return;
+      await emit({ type: "run.claimed", run });
+      for (let count = 0;count < maxStepsPerClaim && run.status === "running"; count += 1) {
+        const current = await store.getRun(run.id);
+        if (!current)
+          throw new Error("Claimed run disappeared");
+        if (current.cancelRequestedAt) {
+          run = await transition(current, workerId, { status: "cancelled" });
+          break;
+        }
+        run = current;
+        const steps = await store.listSteps(run.id);
+        try {
+          const resumed = await resumePendingEffect(run, workerId, steps);
+          if (resumed) {
+            run = resumed;
+            continue;
+          }
+          run = await handle(run, workerId, await driver.next({
+            run,
+            steps,
+            remaining: remainingBudget(run.budget, run.usage)
+          }));
+        } catch (error) {
+          if (error instanceof Error && error.message.startsWith("Agent budget exceeded:")) {
+            run = await transition(run, workerId, {
+              status: "failed",
+              error: {
+                code: "budget_exceeded",
+                message: error.message,
+                retryable: false
+              }
+            });
+            break;
+          }
+          throw error;
+        }
+      }
+      if (run.status === "running") {
+        run = await transition(run, workerId, { status: "queued" });
+      }
+      return run;
+    }
+  };
+};
+// src/postgres.ts
+var safe = (value) => {
+  if (!/^[a-z_][a-z0-9_]*$/i.test(value))
+    throw new Error("Invalid SQL namespace");
+  return value;
+};
+var agentRuntimePostgresSchemaSql = (schema = "agent_runtime") => {
+  const ns = safe(schema);
+  return `CREATE SCHEMA IF NOT EXISTS ${ns};
+CREATE TABLE IF NOT EXISTS ${ns}.runs (
+  id text PRIMARY KEY,
+  document jsonb NOT NULL,
+  status text NOT NULL,
+  version integer NOT NULL,
+  wake_at timestamptz,
+  lease_owner text,
+  lease_expires_at timestamptz,
+  cancel_requested_at timestamptz,
+  created_at timestamptz NOT NULL,
+  updated_at timestamptz NOT NULL
+);
+CREATE INDEX IF NOT EXISTS agent_runs_due_idx ON ${ns}.runs (status, wake_at, lease_expires_at, created_at);
+CREATE INDEX IF NOT EXISTS agent_runs_actor_idx ON ${ns}.runs ((document->'actor'->>'tenantId'), (document->'actor'->>'userId'), created_at DESC);
+CREATE TABLE IF NOT EXISTS ${ns}.steps (
+  run_id text NOT NULL REFERENCES ${ns}.runs(id) ON DELETE CASCADE,
+  sequence integer NOT NULL,
+  id text NOT NULL UNIQUE,
+  kind text NOT NULL,
+  idempotency_key text,
+  document jsonb NOT NULL,
+  created_at timestamptz NOT NULL,
+  PRIMARY KEY (run_id, sequence)
+);
+CREATE UNIQUE INDEX IF NOT EXISTS agent_steps_idempotency_idx ON ${ns}.steps (run_id, idempotency_key, kind) WHERE idempotency_key IS NOT NULL;`;
+};
+var saved = (run) => [
+  JSON.stringify(run),
+  run.status,
+  run.version,
+  run.wakeAt ?? null,
+  run.leaseOwner ?? null,
+  run.leaseExpiresAt ?? null,
+  run.cancelRequestedAt ?? null,
+  run.updatedAt,
+  run.id
+];
+var createPostgresAgentRuntimeStore = ({
+  client,
+  schema = "agent_runtime"
+}) => {
+  const ns = safe(schema);
+  const update = async (tx, run) => {
+    const result = await tx.query(`UPDATE ${ns}.runs SET document=$1::jsonb,status=$2,version=$3,wake_at=$4::timestamptz,lease_owner=$5,lease_expires_at=$6::timestamptz,cancel_requested_at=$7::timestamptz,updated_at=$8::timestamptz WHERE id=$9 RETURNING document`, saved(run));
+    return result.rows[0]?.document;
+  };
+  return {
+    createRun: async (run) => {
+      await client.query(`INSERT INTO ${ns}.runs (id,document,status,version,wake_at,lease_owner,lease_expires_at,cancel_requested_at,created_at,updated_at) VALUES ($1,$2::jsonb,$3,$4,$5,$6,$7,$8,$9::timestamptz,$10::timestamptz)`, [
+        run.id,
+        JSON.stringify(run),
+        run.status,
+        run.version,
+        null,
+        null,
+        null,
+        null,
+        run.createdAt,
+        run.updatedAt
+      ]);
+    },
+    getRun: async (id) => (await client.query(`SELECT document FROM ${ns}.runs WHERE id=$1`, [id])).rows[0]?.document,
+    listSteps: async (runId) => (await client.query(`SELECT document FROM ${ns}.steps WHERE run_id=$1 ORDER BY sequence`, [runId])).rows.map((row) => row.document),
+    claimDue: async ({ workerId, now, leaseExpiresAt }) => client.transaction(async (tx) => {
+      const result = await tx.query(`SELECT document FROM ${ns}.runs WHERE cancel_requested_at IS NULL AND (status='queued' OR (status='waiting' AND wake_at <= $1::timestamptz) OR (status='running' AND lease_expires_at <= $1::timestamptz)) ORDER BY created_at FOR UPDATE SKIP LOCKED LIMIT 1`, [now]);
+      const run = result.rows[0]?.document;
+      if (!run)
+        return;
+      return update(tx, {
+        ...run,
+        status: "running",
+        wakeAt: undefined,
+        leaseOwner: workerId,
+        leaseExpiresAt,
+        version: run.version + 1,
+        updatedAt: now
+      });
+    }),
+    heartbeat: async ({
+      runId,
+      workerId,
+      expectedVersion,
+      leaseExpiresAt,
+      now
+    }) => client.transaction(async (tx) => {
+      const run = (await tx.query(`SELECT document FROM ${ns}.runs WHERE id=$1 AND version=$2 AND lease_owner=$3 AND status='running' FOR UPDATE`, [runId, expectedVersion, workerId])).rows[0]?.document;
+      return run ? update(tx, {
+        ...run,
+        leaseExpiresAt,
+        version: run.version + 1,
+        updatedAt: now
+      }) : undefined;
+    }),
+    appendStep: async ({ runId, workerId, expectedVersion, step, now }) => client.transaction(async (tx) => {
+      const run = (await tx.query(`SELECT document FROM ${ns}.runs WHERE id=$1 AND version=$2 AND lease_owner=$3 AND status='running' FOR UPDATE`, [runId, expectedVersion, workerId])).rows[0]?.document;
+      if (!run)
+        return;
+      const keys = Object.keys(step.usage);
+      const exceeded = keys.find((key) => run.budget[key] !== undefined && run.usage[key] + step.usage[key] > (run.budget[key] ?? 0));
+      if (exceeded)
+        throw new Error(`Agent budget exceeded: ${exceeded}`);
+      const inserted = await tx.query(`INSERT INTO ${ns}.steps (run_id,sequence,id,kind,idempotency_key,document,created_at) VALUES ($1,$2,$3,$4,$5,$6::jsonb,$7::timestamptz) ON CONFLICT DO NOTHING RETURNING id`, [
+        runId,
+        step.sequence,
+        step.id,
+        step.kind,
+        step.idempotencyKey ?? null,
+        JSON.stringify(step),
+        step.createdAt
+      ]);
+      if (!inserted.rows.length)
+        return;
+      const usage = Object.fromEntries(keys.map((key) => [key, run.usage[key] + step.usage[key]]));
+      return update(tx, {
+        ...run,
+        usage,
+        version: run.version + 1,
+        updatedAt: now
+      });
+    }),
+    transition: async ({
+      runId,
+      workerId,
+      expectedVersion,
+      status,
+      now,
+      output,
+      checkpoint,
+      wakeAt,
+      error
+    }) => client.transaction(async (tx) => {
+      const params = [runId, expectedVersion];
+      const owner = workerId ? ` AND lease_owner=$3` : "";
+      if (workerId)
+        params.push(workerId);
+      const run = (await tx.query(`SELECT document FROM ${ns}.runs WHERE id=$1 AND version=$2${owner} FOR UPDATE`, params)).rows[0]?.document;
+      if (!run)
+        return;
+      return update(tx, {
+        ...run,
+        status,
+        version: run.version + 1,
+        updatedAt: now,
+        ...output === undefined ? {} : { output },
+        ...checkpoint === undefined ? {} : { checkpoint },
+        ...wakeAt === undefined ? {} : { wakeAt },
+        ...error === undefined ? {} : { error },
+        ...status === "running" ? {} : { leaseOwner: undefined, leaseExpiresAt: undefined }
+      });
+    }),
+    requestCancel: async ({ runId, now }) => client.transaction(async (tx) => {
+      const run = (await tx.query(`SELECT document FROM ${ns}.runs WHERE id=$1 FOR UPDATE`, [runId])).rows[0]?.document;
+      if (!run)
+        return;
+      if (["completed", "failed", "cancelled", "handed_off"].includes(run.status))
+        return run;
+      const canCancelImmediately = run.status !== "running";
+      return update(tx, {
+        ...run,
+        status: canCancelImmediately ? "cancelled" : run.status,
+        cancelRequestedAt: now,
+        version: run.version + 1,
+        updatedAt: now,
+        ...canCancelImmediately ? {
+          leaseOwner: undefined,
+          leaseExpiresAt: undefined,
+          wakeAt: undefined
+        } : {}
+      });
+    })
+  };
+};
+export {
+  zeroUsage,
+  remainingBudget,
+  normalizeUsage,
+  createPostgresAgentRuntimeStore,
+  createMemoryAgentRuntimeStore,
+  createAgentRuntime,
+  budgetExceeded,
+  agentRuntimePostgresSchemaSql,
+  addUsage
+};

package/dist/manifest.d.ts

@@ -0,0 +1 @@
+export declare const manifest: import("@absolutejs/manifest").PackageManifest<Record<string, never>, never>;

package/dist/manifest.js

@@ -0,0 +1,20 @@
+// @bun
+// src/manifest.ts
+import { defineManifest } from "@absolutejs/manifest";
+import { Type } from "@sinclair/typebox";
+var manifest = defineManifest()({
+  contract: 2,
+  identity: {
+    accent: "#f97316",
+    category: "ai",
+    description: "Durable provider-neutral AI agent orchestration with leased runs, atomic steps, hard budgets, checkpoints, timers, cancellation, idempotent effects, and discovery-pinned handoffs.",
+    docsUrl: "https://github.com/absolutejs/agent-runtime",
+    name: "@absolutejs/agent-runtime",
+    tagline: "Run agents durably without choosing their model provider."
+  },
+  settings: Type.Object({}),
+  wiring: []
+});
+export {
+  manifest
+};

package/dist/manifest.json

@@ -0,0 +1,16 @@
+{
+	"contract": 2,
+	"identity": {
+		"accent": "#f97316",
+		"category": "ai",
+		"description": "Durable provider-neutral AI agent orchestration with leased runs, atomic steps, hard budgets, checkpoints, timers, cancellation, idempotent effects, and discovery-pinned handoffs.",
+		"docsUrl": "https://github.com/absolutejs/agent-runtime",
+		"name": "@absolutejs/agent-runtime",
+		"tagline": "Run agents durably without choosing their model provider."
+	},
+	"settings": {
+		"type": "object",
+		"properties": {}
+	},
+	"wiring": []
+}

package/dist/memory.d.ts

@@ -0,0 +1,2 @@
+import type { AgentRuntimeStore } from "./types";
+export declare const createMemoryAgentRuntimeStore: () => AgentRuntimeStore;

package/dist/postgres.d.ts

@@ -0,0 +1,15 @@
+import type { AgentRuntimeStore } from "./types";
+export type AgentRuntimeSqlResult<Row> = {
+    rows: Row[];
+};
+export type AgentRuntimeSqlTransaction = {
+    query<Row = Record<string, unknown>>(sql: string, params?: readonly unknown[]): Promise<AgentRuntimeSqlResult<Row>>;
+};
+export type AgentRuntimeSqlClient = AgentRuntimeSqlTransaction & {
+    transaction<Value>(work: (tx: AgentRuntimeSqlTransaction) => Promise<Value>): Promise<Value>;
+};
+export declare const agentRuntimePostgresSchemaSql: (schema?: string) => string;
+export declare const createPostgresAgentRuntimeStore: ({ client, schema, }: {
+    client: AgentRuntimeSqlClient;
+    schema?: string;
+}) => AgentRuntimeStore;

package/dist/runtime.d.ts

@@ -0,0 +1,11 @@
+import type { AgentDriver, AgentEffectExecutor, AgentRunEvent, AgentRuntime, AgentRuntimeStore } from "./types";
+export declare const createAgentRuntime: ({ store, driver, effects, now, id, leaseMs, maxStepsPerClaim, onEvent, }: {
+    store: AgentRuntimeStore;
+    driver: AgentDriver;
+    effects: AgentEffectExecutor;
+    now?: () => number;
+    id?: () => string;
+    leaseMs?: number;
+    maxStepsPerClaim?: number;
+    onEvent?: (event: AgentRunEvent) => void | Promise<void>;
+}) => AgentRuntime;

package/dist/types.d.ts

@@ -0,0 +1,183 @@
+export type AgentRunStatus = "queued" | "running" | "waiting" | "suspended" | "handed_off" | "completed" | "failed" | "cancelled";
+export type AgentIdentityPin = {
+    descriptorId: string;
+    descriptorVersion: string;
+    descriptorDigest: string;
+};
+export type AgentActor = {
+    tenantId: string;
+    userId: string;
+    agentId: string;
+    delegationId?: string;
+    organizationId?: string;
+};
+export type AgentBudget = {
+    actions?: number;
+    costMicros?: number;
+    inputTokens?: number;
+    outputTokens?: number;
+    spendMinor?: number;
+    wallTimeMs?: number;
+};
+export type AgentBudgetUsage = Required<AgentBudget>;
+export type AgentRun = {
+    id: string;
+    parentRunId?: string;
+    actor: AgentActor;
+    agent: AgentIdentityPin;
+    goal: string;
+    input: unknown;
+    output?: unknown;
+    status: AgentRunStatus;
+    budget: AgentBudget;
+    usage: AgentBudgetUsage;
+    version: number;
+    cancelRequestedAt?: string;
+    checkpoint?: unknown;
+    wakeAt?: string;
+    leaseOwner?: string;
+    leaseExpiresAt?: string;
+    error?: {
+        code: string;
+        message: string;
+        retryable: boolean;
+    };
+    createdAt: string;
+    updatedAt: string;
+};
+export type AgentStepKind = "observation" | "thought" | "message" | "effect.requested" | "effect.completed" | "effect.failed" | "checkpoint" | "handoff" | "wait" | "completed" | "failed";
+export type AgentStep = {
+    id: string;
+    runId: string;
+    sequence: number;
+    kind: AgentStepKind;
+    idempotencyKey?: string;
+    name?: string;
+    input?: unknown;
+    output?: unknown;
+    usage: AgentBudgetUsage;
+    createdAt: string;
+};
+export type AgentRunEvent = {
+    type: "run.created";
+    run: AgentRun;
+} | {
+    type: "run.claimed";
+    run: AgentRun;
+} | {
+    type: "run.transitioned";
+    run: AgentRun;
+} | {
+    type: "step.appended";
+    run: AgentRun;
+    step: AgentStep;
+};
+export type AgentRuntimeStore = {
+    createRun(run: AgentRun): Promise<void>;
+    getRun(id: string): Promise<AgentRun | undefined>;
+    listSteps(runId: string): Promise<readonly AgentStep[]>;
+    claimDue(input: {
+        workerId: string;
+        now: string;
+        leaseExpiresAt: string;
+    }): Promise<AgentRun | undefined>;
+    heartbeat(input: {
+        runId: string;
+        workerId: string;
+        expectedVersion: number;
+        leaseExpiresAt: string;
+        now: string;
+    }): Promise<AgentRun | undefined>;
+    appendStep(input: {
+        runId: string;
+        workerId: string;
+        expectedVersion: number;
+        step: AgentStep;
+        now: string;
+    }): Promise<AgentRun | undefined>;
+    transition(input: {
+        runId: string;
+        workerId?: string;
+        expectedVersion: number;
+        status: AgentRunStatus;
+        now: string;
+        output?: unknown;
+        checkpoint?: unknown;
+        wakeAt?: string;
+        error?: AgentRun["error"];
+    }): Promise<AgentRun | undefined>;
+    requestCancel(input: {
+        runId: string;
+        now: string;
+    }): Promise<AgentRun | undefined>;
+};
+export type AgentEffectExecutor = {
+    execute(input: {
+        run: AgentRun;
+        step: AgentStep;
+        name: string;
+        payload: unknown;
+        idempotencyKey: string;
+    }): Promise<unknown>;
+};
+export type AgentTransition = {
+    type: "continue";
+    kind?: "observation" | "thought" | "message";
+    name?: string;
+    input?: unknown;
+    output?: unknown;
+    usage?: AgentBudget;
+} | {
+    type: "effect";
+    name: string;
+    input: unknown;
+    idempotencyKey: string;
+    usage?: AgentBudget;
+} | {
+    type: "checkpoint";
+    checkpoint: unknown;
+    reason?: string;
+} | {
+    type: "wait";
+    until: string;
+    reason: string;
+    checkpoint?: unknown;
+} | {
+    type: "handoff";
+    target: AgentIdentityPin;
+    input: unknown;
+    reason: string;
+} | {
+    type: "complete";
+    output: unknown;
+} | {
+    type: "fail";
+    code: string;
+    message: string;
+    retryable?: boolean;
+};
+export type AgentDriverContext = {
+    run: AgentRun;
+    steps: readonly AgentStep[];
+    remaining: AgentBudgetUsage;
+};
+export type AgentDriver = {
+    next(context: AgentDriverContext): Promise<AgentTransition>;
+};
+export type AgentRuntime = {
+    start(input: {
+        actor: AgentActor;
+        agent: AgentIdentityPin;
+        goal: string;
+        input: unknown;
+        budget?: AgentBudget;
+        idempotencyKey?: string;
+        parentRunId?: string;
+    }): Promise<AgentRun>;
+    cancel(runId: string): Promise<AgentRun | undefined>;
+    inspect(runId: string): Promise<{
+        run: AgentRun;
+        steps: readonly AgentStep[];
+    } | undefined>;
+    workOne(workerId: string): Promise<AgentRun | undefined>;
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@absolutejs/agent-runtime",
+  "version": "0.1.0",
+  "description": "Durable provider-neutral AI agent runs, steps, checkpoints, budgets, leases, timers, effects, and handoffs.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/absolutejs/agent-runtime.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "absolutejs": {
+    "manifestContract": 2
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./manifest": {
+      "types": "./dist/manifest.d.ts",
+      "import": "./dist/manifest.js"
+    },
+    "./manifest.json": "./dist/manifest.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "format": "prettier --write \"./**/*.{ts,json,md,yml}\"",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "build": "rm -rf dist && bun build src/index.ts src/manifest.ts --outdir dist --target=bun --external @absolutejs/manifest --external @sinclair/typebox && tsc -p tsconfig.build.json && absolute-manifest emit",
+    "check:package": "bun run typecheck && bun run test && bun run build"
+  },
+  "dependencies": {
+    "@absolutejs/manifest": "^0.2.0",
+    "@sinclair/typebox": "^0.34.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "prettier": "3.5.3",
+    "typescript": "5.8.3"
+  }
+}