@godspeedai/cognate-react

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

React 19 bindings over the headless client: runs, projections, frontend capabilities, continuations, artifacts (spec §25.2). No Astryx.

原始使用文档
文档目录6 节
  1. Installation
  2. Quick start
  3. Hooks
  4. Limitations
  5. Related packages
  6. License

@godspeedai/cognate-react

React 19 bindings for Cognate: thin hooks over the headless client that put runs, live projections, frontend capabilities, continuations, and artifacts into your components. Design-system free — bring your own renderer.

When to use this package: you build a React front end for a Cognate runtime and want the state plumbing handled (subscriptions, replay, registration lifecycles) without adopting a component library. For ready-made chat/approval/artifact surfaces, layer @godspeedai/cognate-ui-astryx on top.

Installation

bun add @godspeedai/cognate-react

Requires Bun >= 1.4.0 and React 19.3.0 (declared as a peer dependency, "react": "19.3.0"). Depends on @godspeedai/cognate-client — every hook reads through a CognateClient, which stays the single source of truth. The packages ship Bun-native TypeScript source; if you type-check outside Bun, add @types/bun and @types/node.

Quick start

import { createClient } from "@godspeedai/cognate-client";
import { CognateProvider, useAgent, useContinuations } from "@godspeedai/cognate-react";
import { createRuntime } from "@godspeedai/cognate-runtime-bun";

const runtime = await createRuntime({
  store: ":memory:",
  agents: [myAgent],
  policy, // your kernel invocation policy
  actions, // your action authorization
});
const caller = { actor: { id: "alice", kind: "user" }, tenant: "tenant-a" };
const client = createClient({ service: runtime.service, caller });

function App() {
  const { start, runId, state } = useAgent("agent.support");
  const { open, resolve } = useContinuations(runId);

  return (
    <main>
      <button onClick={() => void start({ message: "I was double charged" })}>Ask</button>
      <p>{state?.text}</p>
      {open
        .filter((c) => (c.condition as { kind?: string } | null)?.kind === "human_approval")
        .map((c) => (
          <button key={c.id} onClick={() => void resolve(c.id, "resume", { approved: true })}>
            Approve {c.id}
          </button>
        ))}
    </main>
  );
}

// Wrap once, near the root:
<CognateProvider client={client}><App /></CognateProvider>;

Hooks

HookPurpose
useCognate()the client from the nearest CognateProvider
useRun(runId)live RunState of a run — status, streamed text, error, open continuations, artifacts, derived state
useAgent(agent)start(input), the latest runId, and its live state
useSharedState(runId)the run's live shared state plus update(patchOrSnapshot); writes resolve once durable and are observed by the suspended agent through RunContext.state
useThreadSharedState(threadId)the same, shared by all runs in a thread
useProjection(name)entries of a public projection
useCapability(capability, handler)serves a frontend capability while the component is mounted; unregistered on unmount, leaving any open continuation waiting
useRemoteCapability(offer, handler, options?)publishes a descriptor-backed remote capability for the mounted lifetime; options.render records the UI that served each durable call; returns { status, error }
useRemoteCapabilityHistory(runId)per-call render provenance for remote capability calls in a run (same-session only)
useContinuations(runId)open continuations plus resolve(id, "resume" | "cancel", input?)
useArtifact(artifactId)fetches an artifact: { status, name, mediaType, text? } (text decoded for text/* media types)
useConnectionStatus()the client's connection status

All subscription hooks are useSyncExternalStore adapters over the client's reactive stores, so they work under server rendering too: the client replays buffered history into the first subscription.

Limitations

  • The package renders nothing and styles nothing; it is hooks and a provider. Astryx types and components stay out by design.
  • Remote-capability render provenance lives in the mounted provider's memory — after a full page reload the durable calls remain inspectable, but the original renderer component is gone.
  • useCapability and useRemoteCapability follow component lifetime: unmounting withdraws the capability or offer; an agent mid-wait stays waiting rather than falling back.

License

Apache-2.0

版本与发布记录

@godspeedai/cognate-react 共发布 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-react 的常见问题

@godspeedai/cognate-react 是什么?

React 19 bindings over the headless client: runs, projections, frontend capabilities, continuations, artifacts (spec §25.2). No Astryx.

如何安装 @godspeedai/cognate-react?

在项目目录运行 npm install @godspeedai/cognate-react,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:react(19.3.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@godspeedai/cognate-react 支持 TypeScript 吗?

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

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

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

@godspeedai/cognate-react 可以商用吗?

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

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

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

@godspeedai/cognate-react 还在维护吗?

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