@godspeedai/cognate-execution

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

Framework-owned execution-world contracts: filesystem and process ports, replaceable providers, and the filesystem./process. capability component. No transport or library types.

原始使用文档
文档目录8 节
  1. Installation
  2. Quick start
  3. Contracts and providers
  4. program.run
  5. Writing a provider
  6. Limitations
  7. Related packages
  8. License

@godspeedai/cognate-execution

Execution-world contracts for Cognate: the framework-owned filesystem and process ports that higher-level tools (read, edit, bash, and anything else that touches files or runs commands) consume, plus the provider registry that swaps where those operations happen — local machine, SSH host, WSL distribution, or your own — without changing the tools.

When to use this package: you want file/process access behind replaceable providers, or you are writing a provider (SSH, a container runtime, a test double) that must satisfy the same contracts. Ready-made providers: @godspeedai/cognate-execution-ssh and @godspeedai/cognate-execution-wsl.

The idea in one line: a workspace says what a user works on; an execution world says where its files are read and its commands run; replacing the provider under one filesystem.* / process.exec contract moves execution to another machine with zero change to the tools, the agent, or the approvals.

Installation

bun add @godspeedai/cognate-execution

Requires Bun >= 1.4.0. Depends on @godspeedai/cognate-kernel-api for the Component shape only — no transport or library types cross this package's boundary.

Quick start

import { createExecutionWorldRegistry, localExecutionWorld } from "@godspeedai/cognate-execution";

const registry = createExecutionWorldRegistry([
  localExecutionWorld({ worldId: "local", metadata: { host: "dev-box" } }),
]);

const world = registry.get("local");
const path = world.fileSystem.resolve("/home/me/workspace", "src/app.ts"); // canonical path; escapes throw PathEscapeError
const exists = await world.fileSystem.exists(path);
const result = await world.process.exec({ argv: ["bun", "test"], cwd: "/home/me/workspace", timeoutMs: 60_000 });
console.log(result.exitCode, result.stdout, result.timedOut);

await registry.dispose();

registry.get throws WorldUnavailableError for an unknown or disposed world — it never falls back to another world. A missing file is reported as undefined from stat/version, not as an error. Provider metadata is safe for durable state and logs: host names and auth kinds, never credentials.

To expose the worlds as capabilities (so agents and tools invoke filesystem.readText and process.exec instead of importing providers), mount the capability component on your runtime or kernel:

import { executionWorldsComponent } from "@godspeedai/cognate-execution";
import { createRuntime } from "@godspeedai/cognate-runtime-bun";

const runtime = await createRuntime({
  store: "./app.sqlite",
  agents: [/* ... */],
  policy, // authorize the filesystem.*/process.exec capabilities
  actions,
  components: [executionWorldsComponent(registry)],
});

Contracts and providers

ExportKindMeaning
FileSystemPortportresolve, stat, exists, readText, list, writeText, version
ProcessPortportexec(spec, { signal }) → { stdout, stderr, exitCode, timedOut }
ExecutionWorldProviderproviderone worldId, kind, safe metadata, both ports, idempotent dispose()
createExecutionWorldRegistry()factoryregister/unregister/get providers; list() returns secret-free descriptors
executionWorldsComponent(registry)componentpublishes the capabilities below, routed by the caller's worldId
localExecutionWorld()providerthe local machine (node:fs + Bun.spawn)
memoryExecutionWorld()providerdeterministic in-process world with a virtual filesystem and scripted commands (memory echo/fail/slow) for tests
PathEscapeError, WorldUnavailableErrorerrorspath escaped its root; world unknown, unreachable, or disposed

Published capability ids: filesystem.resolve, filesystem.stat, filesystem.readText, filesystem.writeText, filesystem.list, filesystem.version, process.exec. Removing a provider makes its capabilities resolve unavailable — a clean failure, never a silent local fallback.

program.run

programExecutorComponent(registry) publishes program.run, a separate capability that applies a hash-pinned unified diff inside a declared workspace and then runs one declared command. It is invoked through the kernel like any capability, so your policy and governance decide whether it runs (it is deliberately not in EXECUTION_CAPABILITY_IDS).

  • Input: { worldId, workspace, patch, patchSha256, argv, cwd?, timeoutMs? }. patchSha256 is the sha256 of the patch's UTF-8 bytes; a mismatch is refused (ProgramRefusedError, reason patch_hash_mismatch) before anything runs.
  • The patch is applied in memory first and written only if every hunk applies exactly; otherwise the workspace is untouched. v1 edits existing text files only (no create, delete, rename or binary).
  • argv is an array handed to the world's process port, never a shell; patch targets and cwd must resolve under workspace. On a world whose file system offers the optional realPath (the local world does), the real path of each target and of cwd must equal the real workspace root plus the same relative path: a symlink anywhere along a path is refused with path_escape, whether it points outside or stays inside. The check repeats immediately before each write and before the command. A link swapped in by a concurrent process between that last check and the write is not excluded.
  • If a write fails, every file touched (including the one that failed, which may be partly written) is written back; if a restore also fails the error names the files left unrestored. Worlds without realPath (memory, and the POSIX-script worlds, which guard symlinks in their own resolve/IO) skip the real-path check.
  • Result: { patchSha256, filesPatched, command, exitCode, timedOut, outputDigest, stdout, stderr }. A non-zero exit throws ProgramCommandFailedError, so the failed invocation record keeps the exit code, patch hash, command and digest.

Also exported: commandFileSystem(runScript) — a FileSystemPort built from a single "run this POSIX script" primitive (used by the WSL provider; handy for containers); the POSIX helpers shellQuote, execScript, supervisedExecScript, resolvePosix, createRootGuard; and the ./conformance subpath.

Writing a provider

Export a function that returns an ExecutionWorldProvider, and prove it with the shared suite:

import { executionWorldConformance } from "@godspeedai/cognate-execution/conformance";

executionWorldConformance("my-world", async () => ({
  provider: myExecutionWorld({ /* ... */ }),
  root: "/workspace", // a location this provider owns
  commands: {
    echo: (marker) => ({ argv: ["printf", "%s", marker], cwd: "/workspace" }),
    fail: (marker, code) => ({ argv: ["sh", "-c", `printf %s ${JSON.stringify(marker)} 1>&2; exit ${code}`], cwd: "/workspace" }),
    slow: () => ({ argv: ["sleep", "30"], cwd: "/workspace" }),
  },
}));

The suite asserts, for any provider: containment rejects escapes, a missing file is undefined rather than a throw, reads and writes round-trip, version changes with content, exec reports stdout/stderr/exit code, timeouts and aborts really end the process, and dispose() is idempotent. The shipped local, memory, SSH, and WSL providers all pass it unchanged.

Limitations

  • The contracts define files and processes only — no sockets, no watch, no glob.
  • resolve containment is lexical for the local world (symlinks are resolved as-is); the SSH provider adds a symlink check, and commandFileSystem-based worlds check via realpath. A check-then-use race on a concurrently swapped symlink is not prevented anywhere.
  • cwd in an ExecSpec is provider-owned: an OS path for local, a POSIX path inside the distribution for WSL, and so on — only meaningful to the provider that minted it.

License

Apache-2.0

版本与发布记录

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

@godspeedai/cognate-execution 是什么?

Framework-owned execution-world contracts: filesystem and process ports, replaceable providers, and the filesystem./process. capability component. No transport or library types.

如何安装 @godspeedai/cognate-execution?

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

@godspeedai/cognate-execution 支持 TypeScript 吗?

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

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

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

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

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

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

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

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

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