@godspeedai/cognate-profile-harness

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

Harness reference profile: model providers, tool registry, agent loop, sessions, storage, skills, scheduler, sandbox, replaceable services, subagents (spec §29.2). No kernel additions.

原始使用文档
文档目录6 节
  1. Installation
  2. Quick start
  3. What a harness does
  4. Limitations
  5. Related packages
  6. License

@godspeedai/cognate-profile-harness

The Harness reference profile: a ready-to-run autonomous agent — model provider, tool registry, agent loop, sessions, durable key-value storage, skills, a scheduler, a code sandbox, and subagents — composed entirely from existing runtime primitives. No new kernel machinery.

Security warning. This profile's reference configuration authorizes every capability invocation and every action: its policy is allow-all by default and cannot be tightened through options. It is a reference and demo harness for a local, single-user setting. Do not expose it to untrusted callers or networks. For real deployments, build on @godspeedai/cognate-runtime-bun directly and pass your own policy and actions to createRuntime.

When to use this package: you want a working autonomous loop (model picks tools, tools run, loop continues until answered), durable sessions and scheduled runs, sandboxed code execution, and parent/child subagent composition — to run as-is or study before composing your own. For an interactive chat copilot instead, see @godspeedai/cognate-profile-copilot.

Installation

bun add @godspeedai/cognate-profile-harness

Requires Bun >= 1.4.0 (the sandbox spawns bun -e subprocesses). Builds on @godspeedai/cognate-runtime-bun, @godspeedai/cognate-capabilities, and @godspeedai/cognate-kernel-api.

Quick start

import {
  createHarness,
  providerComponent,
  toolComponent,
} from "@godspeedai/cognate-profile-harness";
import { openAICompatible } from "@godspeedai/cognate-provider-openai-compatible";

const harness = await createHarness({
  store: "./harness.sqlite", // durable runs, sessions, schedules, and kv records
  instructions: "You are a build assistant.",
  maxSteps: 8, // model/tool iterations per run
});

// Mount a model provider (replaceable live: dispose one, mount another).
await harness.mount(providerComponent(
  openAICompatible({ id: "main", baseURL: process.env.MODEL_BASE_URL!, model: "my-model", apiKey: () => process.env.MODEL_API_KEY! }),
));

// Mount a tool; the loop discovers it from the registry on the next run.
await harness.mount(toolComponent({
  name: "reverse",
  description: "Reverse a string",
  inputSchema: { type: "object" },
  handler: (input) => ({ reversed: [...String((input as { text: string }).text)].reverse().join("") }),
}));

const runId = await harness.send("session-1", "please reverse this");
// ... the run executes; poll or subscribe for completion
const runs = await harness.session("session-1"); // [{ runId, status, output }]
await harness.close();

What a harness does

ConcernBehaviour
Agent loopagent.loop calls model.generate, executes the requested tools from the live registry, feeds results back, and stops when the model answers (bounded by maxSteps)
Tool registrytoolComponent mounts one tool; skillComponent mounts a named bundle; tools appear/disappear live as components mount and dispose, and a tool can declare capability requires so it waits for its dependencies
Sessionssend(sessionId, message) starts runs correlated by session:<id>; session(sessionId) lists them oldest-first
Storagethe built-in storage.kv capability — get/set/delete backed by durable records, partitioned by the caller's tenant
Schedulerschedule(agent, input, at) records a durable schedule; a loop starts due runs (idempotently, safe across restarts)
Sandboxthe sandbox.exec capability runs code in a bun -e subprocess with a scrubbed environment (no inherited secrets), a timeout, and an output cap
SubagentsspawnSubagent(ctx, id, agent, input) starts a child run durably from inside a run and waits for its output — the wait survives a restart

spawnSubagent is the one piece that runs inside an agent:

import { spawnSubagent } from "@godspeedai/cognate-profile-harness";

const myAgent = {
  id: "agent.researcher",
  version: "1.0.0",
  async run(input, ctx) {
    const summary = await spawnSubagent(ctx, "search", "agent.search", { query: input.topic });
    return { summary };
  },
};
// pass it via createHarness({ agents: [myAgent], ... })

spawnSubagent needs two things: a subagent.start provider, which lets the parent start its child, and something that settles its run_completion continuations. createHarness provides both. An app that composes createRuntime directly mounts the exported subagentStartComponent(runtime) on runtime.kernel, calls watchSubagentCompletions(runtime, caller) once, and keeps the returned dispose function for teardown. Without both, the parent waits forever.

The exported harnessProfile and harnessRegistry declare the composition by name (resolvable with resolveProfile from @godspeedai/cognate-profile), and every behaviour above is an ordinary component, agent definition, or durable-store/service call you can reassemble yourself.

Limitations

  • Allow-all authorization is baked into the reference configuration (see the warning above); multi-tenant or least-privilege deployments need createRuntime with a real policy instead.
  • The scheduler is an in-process interval loop: schedules are durable, but starting them requires a running harness process.
  • The sandbox isolates only by scrubbed environment, timeout, and output cap — it is not a security boundary against hostile code.
  • There is exactly one slot for the model provider contract: swap providers by disposing the mounted one and mounting the next (a verified live swap); routing between concurrent providers is not provided.

License

Apache-2.0

版本与发布记录

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

@godspeedai/cognate-profile-harness 是什么?

Harness reference profile: model providers, tool registry, agent loop, sessions, storage, skills, scheduler, sandbox, replaceable services, subagents (spec §29.2). No kernel additions.

如何安装 @godspeedai/cognate-profile-harness?

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

@godspeedai/cognate-profile-harness 支持 TypeScript 吗?

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

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

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

@godspeedai/cognate-profile-harness 可以商用吗?

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

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

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

@godspeedai/cognate-profile-harness 还在维护吗?

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