@atoms-agent/agent-runtime

atoms_agent v1.0 产品编排层。它把现有 Core Agent Loop、Session DAG、Extensions、Coding Toolkit、 Skills 和 MCP 组合为可恢复的 Coding/General Agent；不实现第二套 Loop。

Install

npm install @atoms-agent/[email protected] @atoms-agent/[email protected] @atoms-agent/[email protected]

Node.js >=22.13，ESM only。只从包根导入。

General Runtime

import { slidingWindow } from "@atoms-agent/core";
import type { ModelAdapter } from "@atoms-agent/llm";
import {
  createAgentRuntime,
  createGeneralProfile,
  createLocalSessionBackend,
  createSessionManager,
} from "@atoms-agent/agent-runtime";

export async function openGeneralRuntime(model: ModelAdapter, sessionRoot: string) {
  const backend = createLocalSessionBackend({ root: sessionRoot });
  const manager = createSessionManager({
    backend,
    profile: { id: "atoms.general", revision: "1" },
  });
  await manager.create({ sessionId: "demo" });

  const generalProfile = createGeneralProfile({
    systemPrompt: "Be concise.",
    context: {
      ref: "window",
      fingerprint: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      strategy: slidingWindow({ maxTokens: 16_000 }),
    },
  });
  const runtime = createAgentRuntime({
    profile: generalProfile,
    model: { ref: "main", adapter: model },
    session: { manager },
  });
  await runtime.start();

  const run = runtime.run("Continue the task");
  for await (const event of run) {
    void event;
  }
  await run.result;
  return runtime;
}

Coding Profile

createCodingProfile() is asynchronous because the Toolkit verifies the explicit Workspace Root. The default Toolkit preset is read-only; Shell, Process, Git writes and filesystem writes require explicit selection and an explicit authorize policy.

import { slidingWindow as codingWindow, type AuthorizeFn } from "@atoms-agent/core";
import { createCodingProfile } from "@atoms-agent/agent-runtime";

export async function buildCodingProfile(workspaceRoot: string, authorize: AuthorizeFn) {
  return createCodingProfile({
    systemPrompt: "Inspect and edit only after authorization.",
    context: {
      ref: "coding-window",
      fingerprint: "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
      strategy: codingWindow({ maxTokens: 16_000 }),
    },
    authorize,
    toolkit: {
      root: workspaceRoot,
      preset: "read-only",
    },
  });
}

Session Contract

• createLocalSessionBackend() stores immutable Header + strict append-only JSONL Records.
• All writes require expected Revision; stale writers fail with SESSION_CONFLICT.
• SessionManager exposes create/resume/branch/switch/fork/clone and versioned Custom Entry append.
• fork copies one root-to-entry path; clone copies the complete DAG. Sources remain unchanged.
• v0.8 FileSessionStore can only be imported through importFileStoreSnapshot() into a create-only v1 Session. It is not a SessionBackend.
• Truncated JSONL, bad UTF-8/JSON, duplicate keys, unknown fields/versions, broken Revision chains and invalid DAG/Tool pairing fail closed.

Runtime Behavior

• Default auto save is { mode: "after_run", saveOn: "all_terminal" }; one Run is one append batch.
• Manual mode holds one bounded dirty journal. A second Run/command is rejected until save() succeeds.
• Durable Compaction Entries are validated projection hints. Complete Canonical history is always restored into Core; summaries remain fixed-marker untrusted User content.
• Extension state remains ephemeral unless a Host binds an extension-scoped Custom Entry handler.
• JSON, JSON-RPC and CLI adapters only call the Runtime command bus; they never write Session files.

Reliability Boundary

The Local Backend provides instance-local FIFO and atomic visibility at complete Record write + file sync. It does not promise power-loss durability, cross-process CAS, network filesystem semantics, side-effect reconciliation, encryption, a Secret scanner, OS sandboxing or background jobs. Session files are plaintext; the Host owns filesystem permissions, retention and backups.

The frozen wire/runtime contract is in docs/V10-AGENT-RUNTIME.md in the repository.

License

MIT