@atoms-agent/extensions

Headless Extension Runtime for atoms_agent (v0.9): explicit Manifest/Loader, Capability registration, lifecycle hooks, transport-neutral commands, and bounded ephemeral state.

This package depends only on @atoms-agent/core and @atoms-agent/llm public root exports. Core does not know about extensions. Hosts must explicitly load extensions, apply registrations, bridge Core events, and call dispose().

Install

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

Local tarball (publish-ready verification):

npm install ./atoms-agent-llm-1.0.0.tgz ./atoms-agent-core-1.0.0.tgz ./atoms-agent-extensions-1.0.0.tgz

Usage

import { createRegistry, defineTool } from "@atoms-agent/core";
import {
  createAuditExtension,
  createCodingPolicyExtension,
  createExtensionRuntime,
  createReviewCommandExtension,
} from "@atoms-agent/extensions";

const runtime = createExtensionRuntime();
await runtime.load([
  { kind: "factory", extension: createAuditExtension() },
  { kind: "factory", extension: createCodingPolicyExtension() },
  { kind: "factory", extension: createReviewCommandExtension() },
]);
await runtime.start();

const registry = createRegistry();
runtime.applyToRegistry(registry);

const hostTool = defineTool<{ text: string }>({
  name: "echo",
  description: "Echo text",
  inputSchema: {
    type: "object",
    properties: { text: { type: "string" } },
    required: ["text"],
    additionalProperties: false,
  },
  sideEffect: "none",
  execute: async ({ text }) => ({ text }),
});
void hostTool;

const review = await runtime.executeCommand("review", { args: "security" });
void review;

const decision = await runtime.decideAuthorization({
  runId: "run-1",
  requestId: "req-1",
  toolCallId: "tc-1",
  toolName: "run_shell",
  sideEffect: "non_idempotent",
  claims: [{ action: "shell.exec" }],
});
void decision;

await runtime.dispose("host");

Semantics

| API | Notes | | --------------------- | ---------------------------------------------------------------------- | | load | Explicit factory / path / package sources only; no auto-scan/install | | start | Validates manifests, runs setup, checks conflicts, emits runtime_ready | | applyToRegistry | Writes registered model/tool/context into a Core RuntimeRegistry | | dispatch | Observer + transform hooks; never mutates Core Agent state | | decideAuthorization | Decision hooks; timeout/throw fail-closed to deny | | executeCommand | Transport-neutral commands; no TTY |

Only import from the package root. Subpath / deep imports are not supported.

Safety notes

• Extensions are process-local collaborators, not an OS sandbox.
• path/package sources require an explicit trust policy.
• Extension tools still pass through Core Validate → Claim → authorize → Execute → Output.
• Event payloads are redacted; secrets, raw tool output, and absolute paths stay out.
• Capability labels such as network / process are metadata only.

See docs/V09-EXTENSION-SYSTEM.md in the monorepo for the frozen contract.

Requirements

• Node.js >= 22.13
• ESM