@godspeedai/cognate-profile-copilot 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.
Files changed (2) hide show
  1. package/README.md +100 -30
  2. package/package.json +13 -13
package/README.md CHANGED
@@ -1,32 +1,102 @@
1
1
  # @godspeedai/cognate-profile-copilot
2
2
 
3
- Reference Copilot profile (spec §29.1, §40.J, CG-PRF-002): a pure composition of existing packages. No
4
- kernel or runtime primitive is added; every profile component name resolves to an existing package.
5
-
6
- | Profile component | Backing package | Primitive used |
7
- | ----------------------- | --------------------------------- | ---------------------------------------------------------------------------------- |
8
- | `runtime` | `@godspeedai/cognate-runtime-bun` | `createRuntime` (kernel, store, agent execution loop) |
9
- | `runs` | `@godspeedai/cognate-runtime-api` | `AgentDefinition.run(input, RunContext)` |
10
- | `continuations` | `@godspeedai/cognate-continuations` | `RunContext.waitFor` (approval gate + frontend tool waits) |
11
- | `frontend-capabilities` | `@godspeedai/cognate-runtime-api` | `invokeFrontend` (a `frontend_capability` continuation, no bidi transport) |
12
- | `state-projections` | `@godspeedai/cognate-client` | `state.changed {snapshot|patch}` folded into `RunState.state` (RFC 6902) |
13
- | `artifact-projections` | `@godspeedai/cognate-artifacts` | `RunContext.artifact` → `run.artifact` → `RunState.artifacts` / `getArtifact` |
14
- | `ag-ui` | `@godspeedai/cognate-ag-ui` | `createAgUiHandler({ service, defaultAgent, authenticate })` |
15
- | `react` | `@godspeedai/cognate-react` | `useCognate`, `CognateProvider` (headless client bindings) |
16
- | `astryx` | `@godspeedai/cognate-ui-astryx` | `ArtifactViewer` (used directly by consumers; not reimplemented here) |
17
-
18
- `createCopilotApp` mounts `modelComponent(options.model)` (`@godspeedai/cognate-provider-openai-compatible`) plus one
19
- kernel component per backend tool, each publishing exactly `tool.contract` (its own capability id/version) —
20
- no new contract shapes. `COPILOT_AGENT` is an ordinary `AgentDefinition`: it builds a `ModelRequest`, prefers
21
- `provider.stream()` when available (recorded once via `ctx.step`, replayed as ordered `ctx.emit("message.delta")`
22
- calls — `ctx.emit` is idempotent per call site, so replay never duplicates), and per tool call either
23
- `ctx.waitFor` an approval continuation (`type` containing `"approval"`, `condition.kind: "human_approval"`) or
24
- `invokeFrontend` a client-served tool. Approved backend calls go through `ctx.invoke(capability, args)`; their
25
- `statePatch`/`render`/`artifact` projections emit `state.changed`, `ui.render`, and `ctx.artifact` respectively.
26
-
27
- `GenerativeSurface` renders a run's `ui.render` events with an app-supplied component registry, synchronously
28
- draining `useCognate().subscribe({ runId })`'s replayed buffer (so it also works under `renderToString`) and
29
- keeping live via `useEffect` in a mounted client; an unknown `component` name renders a placeholder, never throws.
30
-
31
- No file in this package touches `@godspeedai/cognate-kernel-cordis`, `@godspeedai/cognate-kernel-api`'s scope/fiber machinery, or any
32
- runtime-bun internal — only its public `createRuntime` and `RunContext` surface.
3
+ The Copilot reference profile: a complete interactive chat application composed from existing Cognate packages — a model-and-tool agent loop, human approvals, frontend tools served by the browser, shared state and artifact projections, an AG-UI endpoint, and React/Astryx surfaces. It adds no new kernel or runtime primitives; every piece is a package you can also use separately.
4
+
5
+ **When to use this package:** you want a working chat-copilot skeleton (streamed replies, approval-gated backend tools, browser-served tools, generative UI) to run as-is or study before composing your own. For an autonomous, session-and-scheduler style agent instead, see [`@godspeedai/cognate-profile-harness`](https://www.npmjs.com/package/@godspeedai/cognate-profile-harness).
6
+
7
+ ## Installation
8
+
9
+ ```sh
10
+ bun add @godspeedai/cognate-profile-copilot
11
+ ```
12
+
13
+ Requires [Bun](https://bun.sh) >= 1.4.0 and **React 19.3.0** with **react-dom 19.3.0** (both declared as peer dependencies). It builds on [`@godspeedai/cognate-runtime-bun`](https://www.npmjs.com/package/@godspeedai/cognate-runtime-bun), [`@godspeedai/cognate-ag-ui`](https://www.npmjs.com/package/@godspeedai/cognate-ag-ui), [`@godspeedai/cognate-react`](https://www.npmjs.com/package/@godspeedai/cognate-react), and [`@godspeedai/cognate-ui-astryx`](https://www.npmjs.com/package/@godspeedai/cognate-ui-astryx); the model connects through [`@godspeedai/cognate-provider-openai-compatible`](https://www.npmjs.com/package/@godspeedai/cognate-provider-openai-compatible).
14
+
15
+ ## Quick start
16
+
17
+ ```tsx
18
+ import { createClient } from "@godspeedai/cognate-client";
19
+ import { openAICompatible } from "@godspeedai/cognate-provider-openai-compatible";
20
+ import { COPILOT_AGENT, createCopilotApp, GenerativeSurface } from "@godspeedai/cognate-profile-copilot";
21
+ const app = await createCopilotApp({
22
+ store: "./copilot.sqlite",
23
+ model: openAICompatible({
24
+ id: "main",
25
+ baseURL: process.env.MODEL_BASE_URL!,
26
+ model: "my-model",
27
+ apiKey: () => process.env.MODEL_API_KEY!, // read per request, never stored
28
+ }),
29
+ instructions: "You are a support copilot.",
30
+ backendTools: [
31
+ {
32
+ contract: { id: "refund.approve", version: "1.0.0" },
33
+ description: "Issue a refund",
34
+ inputSchema: { type: "object" },
35
+ handler: (input) => ({ refunded: (input as { amount: number }).amount }),
36
+ requiresApproval: true, // pauses the run as a human-approval continuation
37
+ statePatch: (input) => [{ op: "add", path: "/refund", value: { amount: (input as { amount: number }).amount, status: "refunded" } }],
38
+ render: (input) => ({ component: "RefundCard", props: { amount: (input as { amount: number }).amount } }),
39
+ artifact: (input, output) => ({ name: "refund-receipt.json", mediaType: "application/json", content: JSON.stringify({ request: input, result: output }) }),
40
+ },
41
+ ],
42
+ frontendTools: [{ name: "map.focus", description: "Focus the map", inputSchema: { type: "object" } }],
43
+ });
44
+
45
+ // Serve the AG-UI endpoint (SSE) for browser clients:
46
+ Bun.serve({ port: 3000, fetch: app.agUi });
47
+ ```
48
+
49
+ A connected client serves `map.focus` itself and resolves the approval:
50
+
51
+ ```tsx
52
+ import { useCapability } from "@godspeedai/cognate-react";
53
+
54
+ const caller = { actor: { id: "alice", kind: "user" }, tenant: "tenant-a" };
55
+ const client = createClient({ service: app.runtime.service, caller });
56
+ client.provideCapability("map.focus", (input) => ({ centered: true }));
57
+
58
+ // Or per component lifetime:
59
+ function MapTool() {
60
+ useCapability("map.focus", (input) => ({ centered: true }));
61
+ return null;
62
+ }
63
+
64
+ // Render a run's generative-UI events with your own component registry:
65
+ function Surface({ runId }: { runId: string }) {
66
+ return <GenerativeSurface runId={runId} components={{ RefundCard: (props) => <b>Refund of {String(props.amount)}</b> }} />;
67
+ }
68
+ ```
69
+
70
+ An unknown component name renders a placeholder instead of throwing, and the surface works under server-side rendering because the client replays its buffered events into the first subscription.
71
+
72
+ ## What the profile composes
73
+
74
+ | Concern | Backing package |
75
+ | --- | --- |
76
+ | runtime, durable runs | [`@godspeedai/cognate-runtime-bun`](https://www.npmjs.com/package/@godspeedai/cognate-runtime-bun) |
77
+ | continuations (approvals) | [`@godspeedai/cognate-continuations`](https://www.npmjs.com/package/@godspeedai/cognate-continuations) |
78
+ | frontend capabilities | [`@godspeedai/cognate-runtime-api`](https://www.npmjs.com/package/@godspeedai/cognate-runtime-api) |
79
+ | state/artifact projections | [`@godspeedai/cognate-client`](https://www.npmjs.com/package/@godspeedai/cognate-client) |
80
+ | AG-UI endpoint | [`@godspeedai/cognate-ag-ui`](https://www.npmjs.com/package/@godspeedai/cognate-ag-ui) |
81
+ | React bindings | [`@godspeedai/cognate-react`](https://www.npmjs.com/package/@godspeedai/cognate-react) |
82
+ | UI surfaces | [`@godspeedai/cognate-ui-astryx`](https://www.npmjs.com/package/@godspeedai/cognate-ui-astryx) |
83
+
84
+ The exported `copilotProfile` and `copilotRegistry` declare this composition by name (`resolveProfile` from [`@godspeedai/cognate-profile`](https://www.npmjs.com/package/@godspeedai/cognate-profile) resolves every entry to an existing package), and `COPILOT_AGENT` is the built-in agent id (`agent.copilot`).
85
+
86
+ Inside a run, the copilot agent streams model output as `message.delta`, invokes approved backend tools through its capability contracts, serves frontend tools to the client as continuations, and publishes `state.changed`, `ui.render`, and artifact events that the client folds into shared state, generative UI, and the artifact list. A run survives a full application restart: waiting continuations resume where they left off.
87
+
88
+ ## Limitations
89
+
90
+ - The built-in AG-UI endpoint authenticates with the development `Bearer <tenant>:<user>` token convention — bring your own `authenticate` (compose `createAgUiHandler` from `@godspeedai/cognate-ag-ui` directly) for anything real.
91
+ - One copilot agent per app instance; multi-agent routing is yours to add.
92
+ - `requiresApproval` gates on a human decision only — there is no auto-approve or delegation policy built in.
93
+
94
+ ## Related packages
95
+
96
+ - [`@godspeedai/cognate-profile-harness`](https://www.npmjs.com/package/@godspeedai/cognate-profile-harness) — the autonomous profile (tools, scheduler, sandbox, subagents).
97
+ - [`@godspeedai/cognate-provider-openai-compatible`](https://www.npmjs.com/package/@godspeedai/cognate-provider-openai-compatible) — the model provider used by `createCopilotApp`.
98
+ - [`@godspeedai/cognate`](https://www.npmjs.com/package/@godspeedai/cognate) — the SDK umbrella.
99
+
100
+ ## License
101
+
102
+ Apache-2.0
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@godspeedai/cognate-profile-copilot",
3
- "version": "0.1.1",
3
+ "version": "0.1.2",
4
4
  "description": "Copilot reference profile: a composition of runtime, runs, continuations, frontend capabilities, state and artifact projections, AG-UI, React, and Astryx (spec §29.1). No kernel additions.",
5
5
  "type": "module",
6
6
  "license": "Apache-2.0",
@@ -22,18 +22,18 @@
22
22
  ".": "./src/index.tsx"
23
23
  },
24
24
  "dependencies": {
25
- "@godspeedai/cognate-ag-ui": "^0.1.1",
26
- "@godspeedai/cognate-capabilities": "^0.1.1",
27
- "@godspeedai/cognate-client": "^0.1.1",
28
- "@godspeedai/cognate-events": "^0.1.1",
29
- "@godspeedai/cognate-kernel-api": "^0.1.1",
30
- "@godspeedai/cognate-profile": "^0.1.1",
31
- "@godspeedai/cognate-protocol-connect-bun": "^0.1.1",
32
- "@godspeedai/cognate-provider-openai-compatible": "^0.1.1",
33
- "@godspeedai/cognate-react": "^0.1.1",
34
- "@godspeedai/cognate-runtime-api": "^0.1.1",
35
- "@godspeedai/cognate-runtime-bun": "^0.1.1",
36
- "@godspeedai/cognate-ui-astryx": "^0.1.1"
25
+ "@godspeedai/cognate-ag-ui": "^0.1.2",
26
+ "@godspeedai/cognate-capabilities": "^0.1.2",
27
+ "@godspeedai/cognate-client": "^0.1.2",
28
+ "@godspeedai/cognate-events": "^0.1.2",
29
+ "@godspeedai/cognate-kernel-api": "^0.1.2",
30
+ "@godspeedai/cognate-profile": "^0.1.2",
31
+ "@godspeedai/cognate-protocol-connect-bun": "^0.1.2",
32
+ "@godspeedai/cognate-provider-openai-compatible": "^0.1.2",
33
+ "@godspeedai/cognate-react": "^0.1.2",
34
+ "@godspeedai/cognate-runtime-api": "^0.1.2",
35
+ "@godspeedai/cognate-runtime-bun": "^0.1.2",
36
+ "@godspeedai/cognate-ui-astryx": "^0.1.2"
37
37
  },
38
38
  "devDependencies": {
39
39
  "@ag-ui/core": "1.0.0",