@atoms-agent/testing

Offline test helpers for atoms_agent: ScriptedModel, fake clock, deterministic IDs, TestGate, and Context/authorize/Tool fixtures for Run Control / HITL tests.

Dev/test dependency only. Production application runtimes should depend on @atoms-agent/core and @atoms-agent/llm only. Do not ship this package in application runtime installs unless you intentionally run offline demos.

Install

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

Local tarball (publish-ready verification):

npm install ./atoms-agent-llm-0.7.1.tgz ./atoms-agent-core-0.7.1.tgz ./atoms-agent-testing-0.7.1.tgz

Usage

import { createScriptedModel, createTestGate } from "@atoms-agent/testing";
import { createAgent } from "@atoms-agent/core";

const beforeEnd = createTestGate({ name: "before-message-end" });
const model = createScriptedModel({
  script: [{ kind: "text", deltas: ["hello from scripted model"] }],
  gates: { beforeMessageEnd: beforeEnd },
});

const agent = createAgent({
  model,
  systemPrompt: "Reply briefly.",
});

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

T501 helpers

| Helper | Purpose | | --------------------------------- | ---------------------------------------------------- | | createTestGate | Deterministic block/release without wall-clock sleep | | createGatedContextStrategy | Context prepare enter/count/abort observations | | createGatedAuthorize | authorize enter/decision/abort observations | | createGatedTool | Tool execute count + gate before body | | createFakeDeadline | FakeClock-driven AbortSignal for timeout races | | createDeferred / neverResolve | Host never-replies / interleaved control | | takeEventsThenClose | Consume N events then abandon iterator |

T601 Toolkit security harness

| Helper | Purpose | | --------------------------------- | -------------------------------------------------------------------- | | detectToolkitCapabilities | Platform symlink/junction/hardlink/git capability probe with reasons | | createTempWorkspace | Isolated temp workspace + optional files/links | | createSecurityWorkspaceFixture | UTF-8/BOM/CRLF/long-line/nested/outside-root security materials | | pathEscapeSamples | Lexical absolute/../NUL/UNC/ADS samples for Toolkit path tests | | createFakeFilesystemOperations | In-memory FS Operations with call log, block, fail | | createFakeProcessOperations | Scripted process execute + killAttempts | | createFakeGitBackend / Contract | Fake git argv backend layered separately from real git | | createTempGitRepository | Real temp git worktree (capability-gated) | | createNodeProcessFixture | Offline node scripts: success/nonzero/interleaved/long/hang | | createObservedToolContext | Execute count, claims snapshot, progress sequence assertions |

Requirements

• Node.js >= 22.13
• ESM

License

MIT