@godspeedai/cognate-runtime-bun

中文文档
0.10.0发布于 2026/11/16Apache-2.0ES Module构建来源已验证近 30 天下载 3532

Bun reference runtime: composes kernel, durable store, runs, continuations, commitments, artifacts, and cognition behind RuntimeService.

原始使用文档
文档目录7 节
  1. Installation
  2. Quick start
  3. Suspending on a durable continuation
  4. What you get from createRuntime
  5. Limitations
  6. Related packages
  7. License

@godspeedai/cognate-runtime-bun

The Cognate reference runtime for Bun: durable agent runs, human-in-the-loop continuations, artifacts, projections, and optional cognition, composed in-process behind a single RuntimeService. Point it at a SQLite file and your application's history survives restarts; point it at PostgreSQL (or a pg0-managed local instance) and multiple processes share the same history safely.

When to use this package: to run agents for real — in a server, a worker, or a script. Pair it with @godspeedai/cognate-client to consume it from the same process, or with a transport adapter to serve it over the network.

Installation

bun add @godspeedai/cognate-runtime-bun

Requires Bun >= 1.4.0 (the default store uses Bun's built-in bun:sqlite).

Quick start

import { createRuntime } from "@godspeedai/cognate-runtime-bun";
import type { AgentDefinition } from "@godspeedai/cognate-runtime-api";

const agent: AgentDefinition = {
  id: "agent.order",
  version: "1.0.0",
  async run(_input, ctx) {
    // Shared state: a snapshot, then JSON Patch deltas — clients derive the same state.
    await ctx.emit("state.changed", { snapshot: { order: { id: "o-1", status: "open", total: 0 } } });
    await ctx.emit("state.changed", { patch: [{ op: "replace", path: "/order/status", value: "paid" }] });
    await ctx.emit("state.changed", { patch: [{ op: "replace", path: "/order/total", value: 42 }] });
    return { done: true };
  },
};

const caller = { actor: { id: "alice", kind: "user" }, tenant: "tenant-a" } as const;

const runtime = await createRuntime({
  store: "./app.sqlite", // a durable file; use ":memory:" for an ephemeral runtime
  // policy authorizes capability invocations; actions authorizes run/continuation actions.
  policy: { authorize: () => ({ allow: true, policyId: "p", reason: "allowed" }) },
  actions: { authorize: () => ({ allow: true, reason: "allowed" }) },
  agents: [agent],
});

const started = await runtime.service.startRun(caller, {
  agent: "agent.order",
  input: {},
  idempotencyKey: "order-1", // repeating the key returns the same run, never a duplicate
});

await runtime.idle(); // background work queued so far has been processed

const run = await runtime.service.getRun(caller, { runId: started.runId });
console.log(run.status, run.output); // completed { done: true }

await runtime.close();

Suspending on a durable continuation

ctx.waitFor suspends the run until someone resolves the continuation it opens. The run's progress is durable: it can sit waiting through restarts.

const refundAgent: AgentDefinition = {
  id: "agent.refund",
  version: "1.0.0",
  async run(input, ctx) {
    const { amount } = input as { amount: number };
    const decision = (await ctx.waitFor("approve", {
      type: "refund-approval",
      condition: { kind: "human_approval" },
      payload: { amount },
    })) as { approved: boolean };
    return { amount, approved: decision.approved };
  },
};

const waiting = await runtime.service.startRun(caller, {
  agent: "agent.refund",
  input: { amount: 75 },
  idempotencyKey: "refund-1",
});

// Meanwhile — from a webhook, an admin UI, a shell — list and resolve open continuations.
const [continuation] = await runtime.service.listContinuations(caller, {
  runId: waiting.runId,
  status: "OPEN",
});
await runtime.service.resolveContinuation(caller, {
  continuationId: continuation!.id,
  action: "resume",
  input: { approved: true },
  idempotencyKey: "approve-1",
});

The run re-enters the agent from the top, receives the recorded decision, and completes. Replays never repeat recorded work: every ctx.step, emit, invoke, artifact, and waitFor result is an event on the run's stream, and re-entry returns those results instead of re-executing.

What you get from createRuntime

The returned Runtime exposes:

  • service — the full RuntimeService: start/get/cancel/list runs, a reconnectable event stream (service.events(caller, { follow: true })), continuations, direct capability invoke, getArtifact, public projection reads, and shared run/thread state reads and updates.
  • store — the underlying DurableStore, if you need direct access to the event log.
  • kernel — the embedded capability kernel.
  • inspect(correlationId) — the causal chain for a correlation id: runs, events, invocations, artifacts, observations.
  • erase(eventId, reason, actor) — erase an event's payload; derived views and the cognitive index drop it too.
  • rebuildCognition(), pollApprovals(), idle(timeoutMs?), and close().

Notable options beyond the quick start: components (capability-providing kernel components your agents can ctx.invoke), projections (@godspeedai/cognate-projections kept current automatically), cognition (index completed runs and recall them via ctx.recall), outboxFor (extra outbox intents committed atomically with each run event), governance, and tickMs (background loop interval, default 10 ms).

Limitations

  • One runtime execution owner per store. PostgreSQL supports multiple durable-store writers; that does not establish distributed run ownership. Run execution defaults to serial. Opt-in execution.maxConcurrentRuns admits bounded independent runs in one process and requires a trusted execution.resourceKeys eligibility policy above one. Shared resource keys serialize; callers must canonicalize aliases. Do not start competing runtimes against the same runnable work.
  • Steps are at-least-once. A step that was in flight during a crash re-executes after restart. Keep steps idempotent, and use native commitment receipts and explicit reconciliation for external actions. A continuation or permission gate alone does not establish exactly-once physical effects.
  • Polling, not pushing, inside the process. Background work (run execution, resume delivery, continuation expiry) runs on a loop every tickMs.
  • Erasure has copies. runtime.erase removes an event's payload from the log, derived views, and the cognitive index — but content copied into continuation payloads, idempotency snapshots, or recall results stays.
  • Public projections are tenant-partitioned. Register projections that key their state <tenant>/<key>; service.readProjection returns only the caller's tenant partition.
  • Denied means invisible. Reading an artifact you are not allowed to see returns the same "not found" as a missing one.
  • Recall degrades gracefully. Without a cognition configuration, ctx.recall returns { status: "degraded" } instead of failing the run.

License

Apache-2.0

版本与发布记录

@godspeedai/cognate-runtime-bun 共发布 20 个版本,首次发布于 2026/10/09;过去 12 个月发布了 20 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.10.0latest2026/11/16今天
0.9.22026/11/152 天前
0.9.12026/11/143 天前
0.9.02026/11/0610 天前
0.8.02026/10/2720 天前
0.7.12026/10/2523 天前

关于 @godspeedai/cognate-runtime-bun 的常见问题

@godspeedai/cognate-runtime-bun 是什么?

Bun reference runtime: composes kernel, durable store, runs, continuations, commitments, artifacts, and cognition behind RuntimeService.

如何安装 @godspeedai/cognate-runtime-bun?

在项目目录运行 npm install @godspeedai/cognate-runtime-bun,或使用 pnpm add / yarn add / bun add。

@godspeedai/cognate-runtime-bun 支持 TypeScript 吗?

该包的 package.json 没有声明类型入口。需要类型提示时,可以在 npm 上查找社区维护的 @types/godspeedai__cognate-runtime-bun 是否存在。

@godspeedai/cognate-runtime-bun 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@godspeedai/cognate-runtime-bun 可以商用吗?

@godspeedai/cognate-runtime-bun 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@godspeedai/cognate-runtime-bun 的下载量有多少?

根据 npm 官方下载统计,@godspeedai/cognate-runtime-bun 在 2026/10/17 – 2026/11/15 这 30 天内被下载 3,532 次,日均约 118 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@godspeedai/cognate-runtime-bun 还在维护吗?

最新版本 0.10.0 发布于 2026/11/16(今天);至今共发布 20 个版本,其中过去 12 个月发布了 20 个;首次发布于 2026/10/09。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。