@godspeedai/cognate-react 0.1.1 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +85 -3
  2. package/package.json +4 -4
package/README.md CHANGED
@@ -1,7 +1,89 @@
1
1
  # @godspeedai/cognate-react
2
2
 
3
- React 19 bindings over `@godspeedai/cognate-client` (§25.2), via `useSyncExternalStore`.
3
+ 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.
4
4
 
5
- `CognateProvider`, `useCognate`, `useRun`, `useAgent`, `useSharedState` (`{ state, update }` — shared state is bidirectional, spec §29.1: a component can write it and a suspended agent reads the write through `RunContext.state`), `useProjection`, `useCapability` (registers a frontend capability for the component's lifetime; unregistered on unmount — a reversible effect), `useContinuations`, `useArtifact`, `useConnectionStatus`.
5
+ **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`](https://www.npmjs.com/package/@godspeedai/cognate-ui-astryx) on top.
6
6
 
7
- No Astryx dependency; renderers such as `@godspeedai/cognate-ui-astryx` sit above this package (§3.8). Proof: `test/hooks.test.tsx` (CG-UI-001). Tests register happy-dom through `test/setup-dom.ts` and use render-bound queries.
7
+ ## Installation
8
+
9
+ ```sh
10
+ bun add @godspeedai/cognate-react
11
+ ```
12
+
13
+ Requires [Bun](https://bun.sh) >= 1.4.0 and **React 19.3.0** (declared as a peer dependency, `"react": "19.3.0"`). Depends on [`@godspeedai/cognate-client`](https://www.npmjs.com/package/@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`.
14
+
15
+ ## Quick start
16
+
17
+ ```tsx
18
+ import { createClient } from "@godspeedai/cognate-client";
19
+ import { CognateProvider, useAgent, useContinuations } from "@godspeedai/cognate-react";
20
+ import { createRuntime } from "@godspeedai/cognate-runtime-bun";
21
+
22
+ const runtime = await createRuntime({
23
+ store: ":memory:",
24
+ agents: [myAgent],
25
+ policy, // your kernel invocation policy
26
+ actions, // your action authorization
27
+ });
28
+ const caller = { actor: { id: "alice", kind: "user" }, tenant: "tenant-a" };
29
+ const client = createClient({ service: runtime.service, caller });
30
+
31
+ function App() {
32
+ const { start, runId, state } = useAgent("agent.support");
33
+ const { open, resolve } = useContinuations(runId);
34
+
35
+ return (
36
+ <main>
37
+ <button onClick={() => void start({ message: "I was double charged" })}>Ask</button>
38
+ <p>{state?.text}</p>
39
+ {open
40
+ .filter((c) => (c.condition as { kind?: string } | null)?.kind === "human_approval")
41
+ .map((c) => (
42
+ <button key={c.id} onClick={() => void resolve(c.id, "resume", { approved: true })}>
43
+ Approve {c.id}
44
+ </button>
45
+ ))}
46
+ </main>
47
+ );
48
+ }
49
+
50
+ // Wrap once, near the root:
51
+ <CognateProvider client={client}><App /></CognateProvider>;
52
+ ```
53
+
54
+ ## Hooks
55
+
56
+ | Hook | Purpose |
57
+ | --- | --- |
58
+ | `useCognate()` | the client from the nearest `CognateProvider` |
59
+ | `useRun(runId)` | live `RunState` of a run — status, streamed `text`, error, open continuations, artifacts, derived state |
60
+ | `useAgent(agent)` | `start(input)`, the latest `runId`, and its live state |
61
+ | `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` |
62
+ | `useThreadSharedState(threadId)` | the same, shared by all runs in a thread |
63
+ | `useProjection(name)` | entries of a public projection |
64
+ | `useCapability(capability, handler)` | serves a frontend capability while the component is mounted; unregistered on unmount, leaving any open continuation waiting |
65
+ | `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 }` |
66
+ | `useRemoteCapabilityHistory(runId)` | per-call render provenance for remote capability calls in a run (same-session only) |
67
+ | `useContinuations(runId)` | open continuations plus `resolve(id, "resume" \| "cancel", input?)` |
68
+ | `useArtifact(artifactId)` | fetches an artifact: `{ status, name, mediaType, text? }` (text decoded for `text/*` media types) |
69
+ | `useConnectionStatus()` | the client's connection status |
70
+
71
+ 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.
72
+
73
+ ## Limitations
74
+
75
+ - The package renders nothing and styles nothing; it is hooks and a provider. Astryx types and components stay out by design.
76
+ - 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.
77
+ - `useCapability` and `useRemoteCapability` follow component lifetime: unmounting withdraws the capability or offer; an agent mid-wait stays waiting rather than falling back.
78
+
79
+ ## Related packages
80
+
81
+ - [`@godspeedai/cognate-client`](https://www.npmjs.com/package/@godspeedai/cognate-client) — the headless client these hooks bind.
82
+ - [`@godspeedai/cognate-ui-astryx`](https://www.npmjs.com/package/@godspeedai/cognate-ui-astryx) — reference Astryx components built on this package.
83
+ - [`@godspeedai/cognate-runtime-bun`](https://www.npmjs.com/package/@godspeedai/cognate-runtime-bun) — the runtime serving the runs.
84
+ - [`@godspeedai/cognate-profile-copilot`](https://www.npmjs.com/package/@godspeedai/cognate-profile-copilot) — a composed interactive chat application using these bindings.
85
+ - [`@godspeedai/cognate`](https://www.npmjs.com/package/@godspeedai/cognate) — the SDK umbrella.
86
+
87
+ ## License
88
+
89
+ Apache-2.0
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@godspeedai/cognate-react",
3
- "version": "0.1.1",
3
+ "version": "0.2.0",
4
4
  "description": "React 19 bindings over the headless client: runs, projections, frontend capabilities, continuations, artifacts (spec §25.2). No Astryx.",
5
5
  "type": "module",
6
6
  "license": "Apache-2.0",
@@ -22,9 +22,9 @@
22
22
  ".": "./src/index.tsx"
23
23
  },
24
24
  "dependencies": {
25
- "@godspeedai/cognate-client": "^0.1.1",
26
- "@godspeedai/cognate-events": "^0.1.1",
27
- "@godspeedai/cognate-runtime-api": "^0.1.1"
25
+ "@godspeedai/cognate-client": "^0.2.0",
26
+ "@godspeedai/cognate-events": "^0.2.0",
27
+ "@godspeedai/cognate-runtime-api": "^0.2.0"
28
28
  },
29
29
  "devDependencies": {
30
30
  "@godspeedai/cognate-runtime-bun": "workspace:*",