@godspeedai/cognate-protocol-connect 0.1.1 → 0.1.2

package/README.md

@@ -1,11 +1,72 @@
 # @godspeedai/cognate-protocol-connect
 
-Maps `RuntimeService` (runtime-api) to the generated Connect service `cognate.v1.RuntimeService` (`@godspeedai/cognate-proto`), independent of the HTTP server.
+Maps the Cognate `RuntimeService` onto the generated Connect service (`cognate.v1.RuntimeService`), independent of any HTTP server. It provides the server-side route registration and a remote client that behaves like an in-process service.
 
-- `registerRuntimeService(router, service, { authenticate, maxJsonDepth })` — server routes. The caller comes from request headers via `authenticate`, never from message bodies (§32). `google.protobuf.Value` inputs are depth-checked.
-- `createRemoteRuntimeService(transport, tokenFor)` — a `RuntimeService` over any Connect transport; ServiceError codes round-trip exactly.
-- `errorCodes` — ServiceError ↔ Connect code table.
+**When to use this package:** install it when you host the Connect router yourself (any fetch-based server can drive it) or when you need a typed `RuntimeService` backed by a remote endpoint. If you serve from Bun, [`@godspeedai/cognate-protocol-connect-bun`](https://www.npmjs.com/package/@godspeedai/cognate-protocol-connect-bun) wraps this package with a ready-made `Bun.serve` transport, payload limits, and deadlines — install that instead and you get this one automatically.
 
-Proof: `test/service.test.ts` runs the same service conformance kit as the in-process runtime, over JSON and binary encodings (CG-WIR-003, §40.G).
+## Installation
 
-Mode matrix (DEBT-004): unary and server streaming only; client/bidi streaming are not offered.
+```sh
+bun add @godspeedai/cognate-protocol-connect
+```
+
+Requires [Bun](https://bun.sh) >= 1.4.0. Depends on `@connectrpc/connect`, `@bufbuild/protobuf`, [`@godspeedai/cognate-proto`](https://www.npmjs.com/package/@godspeedai/cognate-proto), and the `RuntimeService`/`ServiceError` types from [`@godspeedai/cognate-runtime-api`](https://www.npmjs.com/package/@godspeedai/cognate-runtime-api).
+
+## Quick start
+
+Turn a Connect transport into a full remote `RuntimeService` — the returned object satisfies the same interface as an in-process runtime's service:
+
+```ts
+import { createConnectTransport } from "@connectrpc/connect-web";
+import { createRemoteRuntimeService } from "@godspeedai/cognate-protocol-connect";
+
+const service = createRemoteRuntimeService(
+  createConnectTransport({ baseUrl: "http://127.0.0.1:3000" }),
+  (caller) => issueToken(caller), // Bearer credential for this caller
+);
+
+const caller = { actor: { id: "alice", kind: "user" }, tenant: "tenant-a" };
+const run = await service.startRun(caller, { agent: "agent.echo", input: { text: "hi" } });
+for await (const event of service.events(caller, { runId: run.runId, follow: true })) {
+  console.log(event.eventType);
+}
+```
+
+Plain JSON works for `input` and other value-typed fields — the adapter converts to and from protobuf `Value` for you — and a `ServiceError` raised by the server arrives with the same code, so `service` is a drop-in for an in-process service.
+
+On the server side, register the routes on a Connect router:
+
+```ts
+import { registerRuntimeService } from "@godspeedai/cognate-protocol-connect";
+
+registerRuntimeService(router, runtime.service, {
+  // Caller identity comes from request headers, never from message bodies.
+  authenticate: (headers) => myBearerAuth(headers.get("authorization")),
+  maxJsonDepth: 32, // reject over-deep JSON values from clients
+});
+```
+
+A missing or invalid credential fails every route with `unauthenticated`. If you are serving from Bun, [`serveRuntime`](https://www.npmjs.com/package/@godspeedai/cognate-protocol-connect-bun) does this registration for you and adds body-size and deadline enforcement.
+
+## API surface
+
+- `registerRuntimeService(router, service, { authenticate, maxJsonDepth })` — server routes for every `RuntimeService` method.
+- `createRemoteRuntimeService(transport, tokenFor)` — a client-side `RuntimeService` over any Connect transport; `tokenFor` supplies the Bearer credential for each caller.
+- `errorCodes` — the `ServiceError` code to Connect code table (for example `not_found` → `NotFound`), exported so other transports can reuse the exact mapping.
+
+## Limitations
+
+- The service defines unary and server-streaming methods only; there are no client-streaming or bidirectional methods on the wire.
+- Observation ingestion is an in-process mechanism: the remote client's `observe` always fails with `failed_precondition` rather than exposing it over the wire.
+- Requests are bounded by your `authenticate` implementation and `maxJsonDepth` only; body-size limits and call deadlines are transport concerns (the Bun package adds both).
+
+## Related packages
+
+- [`@godspeedai/cognate-protocol-connect-bun`](https://www.npmjs.com/package/@godspeedai/cognate-protocol-connect-bun) — `Bun.serve` transport, limits, deadlines, and the fetch transport factory.
+- [`@godspeedai/cognate-proto`](https://www.npmjs.com/package/@godspeedai/cognate-proto) — the generated messages and service descriptor this package maps to.
+- [`@godspeedai/cognate-runtime-api`](https://www.npmjs.com/package/@godspeedai/cognate-runtime-api) — the `RuntimeService` contract and `ServiceError` type.
+- [`@godspeedai/cognate`](https://www.npmjs.com/package/@godspeedai/cognate) — the SDK umbrella.
+
+## License
+
+Apache-2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@godspeedai/cognate-protocol-connect",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Maps RuntimeService to the generated Connect service (server routes and a remote client). Transport-agnostic.",
   "type": "module",
   "license": "Apache-2.0",
@@ -23,10 +23,10 @@
   },
   "dependencies": {
     "@bufbuild/protobuf": "2.15.0",
-    "@godspeedai/cognate-events": "^0.1.1",
-    "@godspeedai/cognate-kernel-api": "^0.1.1",
-    "@godspeedai/cognate-proto": "^0.1.1",
-    "@godspeedai/cognate-runtime-api": "^0.1.1",
+    "@godspeedai/cognate-events": "^0.1.2",
+    "@godspeedai/cognate-kernel-api": "^0.1.2",
+    "@godspeedai/cognate-proto": "^0.1.2",
+    "@godspeedai/cognate-runtime-api": "^0.1.2",
     "@connectrpc/connect": "2.2.0"
   },
   "devDependencies": {