@godspeedai/cognate-react 0.1.1 → 0.1.2
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.
- package/README.md +85 -3
- 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
|
|
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
|
-
|
|
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
|
-
|
|
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.
|
|
3
|
+
"version": "0.1.2",
|
|
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.
|
|
26
|
-
"@godspeedai/cognate-events": "^0.1.
|
|
27
|
-
"@godspeedai/cognate-runtime-api": "^0.1.
|
|
25
|
+
"@godspeedai/cognate-client": "^0.1.2",
|
|
26
|
+
"@godspeedai/cognate-events": "^0.1.2",
|
|
27
|
+
"@godspeedai/cognate-runtime-api": "^0.1.2"
|
|
28
28
|
},
|
|
29
29
|
"devDependencies": {
|
|
30
30
|
"@godspeedai/cognate-runtime-bun": "workspace:*",
|