@godspeedai/cognate-proto

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

Generated TypeScript bindings for the canonical proto/ sources. Generated files are never edited by hand (spec §21).

原始使用文档
文档目录7 节
  1. Installation
  2. What it exports
  3. Quick start
  4. Regeneration
  5. Limitations
  6. Related packages
  7. License

@godspeedai/cognate-proto

Generated TypeScript bindings for Cognate's canonical protobuf schemas (the cognate.v1 package), produced with buf and protobuf-es.

When to use this package: you need the typed RuntimeService service descriptor and the generated message and enum classes for Cognate's wire format — for a custom transport, a gateway in another stack, or message-level tooling. Applications that simply call a Cognate runtime should use @godspeedai/cognate-client or the protocol adapters instead; they build on these bindings and handle the wire details for you.

Installation

bun add @godspeedai/cognate-proto

Requires Bun >= 1.4.0. The package depends on @bufbuild/protobuf; calling a runtime over HTTP additionally needs a Connect transport (@connectrpc/connect, plus @connectrpc/connect-web or the convenience exports of @godspeedai/cognate-protocol-connect-bun).

What it exports

The entry point re-exports everything generated from the canonical cognate/v1 schemas:

  • the RuntimeService service descriptor (run start/get/cancel/list, event streaming, continuations, capability invocation, artifacts, projections, shared state, remote capability offers);
  • message types and their schemas — Event/EventSchema, Run, Continuation, StateUpdate, RemoteCapabilityOffer, SemanticRef, and the rest of the family;
  • the enums RunStatus, ContinuationStatus, ContinuationAction, and ResolveOutcome.

Quick start

Messages are ordinary protobuf-es values — create them from JSON, then serialize to canonical JSON or binary protobuf:

import { fromJson, toJson } from "@bufbuild/protobuf";
import { EventSchema } from "@godspeedai/cognate-proto";

const event = fromJson(EventSchema, {
  eventId: "e-1",
  streamId: "s-1",
  streamSequence: "1", // uint64 fields are strings in canonical JSON
  position: "1",
  eventType: "run.started",
  schemaVersion: 1,
  occurredAt: new Date().toISOString(),
  recordedAt: new Date().toISOString(),
  tenant: "tenant-a",
  correlationId: "c-1",
  scopeId: "workspace-1",
});

const json = toJson(EventSchema, event); // canonical JSON
const bytes = event.toBinary(); // binary protobuf

To call a served runtime with a typed client, hand the service descriptor to a Connect transport:

import { createClient } from "@connectrpc/connect";
import { connectTransport } from "@godspeedai/cognate-protocol-connect-bun";
import { RuntimeService } from "@godspeedai/cognate-proto";

const client = createClient(RuntimeService, connectTransport("http://127.0.0.1:3000"));
const run = await client.getRun({ runId: "<run id>" });

Prefer @godspeedai/cognate-protocol-connect's createRemoteRuntimeService when you call the runtime yourself: the generated client does not coerce plain JSON for google.protobuf.Value fields (such as the run input), and that adapter performs the conversion and maps error codes in both directions.

Regeneration

The generated files (src/gen/**) are committed and never edited by hand. Regeneration happens in the Cognate repository, not downstream: running bun run generate in this package executes buf generate with a pinned protoc-gen-es plugin against the canonical proto/ sources. Consumers of the published package never run codegen — they import the committed output like any other module.

Generation is deterministic: two runs into separate directories are byte-identical to each other and to the committed output, and the package's own test suite keeps that true.

Limitations

  • The generated RuntimeService declares unary and server-streaming methods only; the schema has no client-streaming or bidirectional methods.
  • protobuf-es can serialize every message as JSON or binary; choosing a wire format is a transport decision, not something this package configures.
  • Message and field shapes change only through a new release of this package, since there is no downstream codegen path.

License

Apache-2.0

版本与发布记录

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

@godspeedai/cognate-proto 是什么?

Generated TypeScript bindings for the canonical proto/ sources. Generated files are never edited by hand (spec §21).

如何安装 @godspeedai/cognate-proto?

在项目目录运行 npm install @godspeedai/cognate-proto,或使用 pnpm add / yarn add / bun add。

@godspeedai/cognate-proto 支持 TypeScript 吗?

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

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

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

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

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

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

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

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

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