agent-kernel

@caisson/agent-kernel is the engine-neutral base for governed AI agent work: a Zod schema for agent/skill/rule artifacts, a seven-act lifecycle state machine (spec through ship), allow/deny/mutate governance guards, a hooks dispatcher, and an opt-in tamper-evident audit-chain recorder. It imports no vendor SDK and runs no LLM, composition mechanism only, consumed down-only by both the base cli/mcp-server and the Agentic-Dev bundle.

Install

bun add @caisson/agent-kernel

Quickstart

import {
  parseArtifact,
  runLifecycle,
  transition,
  HookDispatcher,
} from "@caisson/agent-kernel";

const agent = parseArtifact({ kind: "agent", name: "reviewer" /* … */ });
const next = transition("plan", "execute"); // "execute"; transition("spec","execute") throws
const trace = runLifecycle([
  "spec",
  "plan",
  "execute",
  "verify",
  "sweep",
  "eval",
  "ship",
]);

const hooks = new HookDispatcher();
hooks.on("before:execute", (ctx) => {
  /* … */
});
await hooks.dispatch("before:execute", { act: "execute", phase: "before" });

Typed agent/skill/rule schema

AgentArtifact, SkillArtifact, and RuleArtifact are a Zod discriminatedUnion on kind, built on @caisson/kernel's strictObject: an unknown field is rejected outright, not silently dropped. A bad artifact fails through parseArtifact as a redaction-safe ValidationError: never the rejected values.

The lifecycle FSM

ACTS runs spec through ship in canonical order. transition() is the only way to move between acts and throws on any edge outside the fixed adjacency. The two branches that matter:

const TRANSITIONS: Record<Act, readonly Act[]> = {
  spec: ["plan"],
  plan: ["execute"],
  execute: ["verify"],
  verify: ["sweep", "plan"], // a failed goal-backward verify reopens plan
  sweep: ["eval", "ship"],
  eval: ["ship"], // an eval regression has no edge but ship — fail-stop
  ship: [], // terminal
};

verify is the only act with two outgoing edges, a failed VERIFY reopens plan, it has no edge to ship. ship: [] makes SHIP a hard terminal state in the type itself, not just a documented convention.

Governance: allow / deny / mutate

evaluateGuards folds a TransitionGuard[] list fail-closed: the first deny short-circuits (remaining guards do not run), a mutate(ctx) threads its context into the guards after it, and a guard that throws is itself treated as a deny: a buggy guard can never accidentally admit a transition.

import { predicateGuard, evaluateGuards } from "@caisson/agent-kernel";

const requireReview = predicateGuard(
  (t) => t.context.reviewed === true,
  "ship requires a recorded review",
);
evaluateGuards([requireReview], { from: "sweep", to: "ship", context });

Hooks: fail-open on crashes, fail-closed on vetoes

HookDispatcher.dispatch runs registered before:/after: act handlers in registration order and awaits each. A handler that throws is isolated, reported to an optional sink (hook name + error type only, never a message or stack), and treated as allow; a handler that returns deny() still short-circuits the loop. An unregistered point is a no-op.

commandHandler runs a fixed argv array through node:child_process execFile: no shell is spawned, and no HookContext value can reach the command's arguments, shell injection through a hook is structurally impossible.

Opt-in tamper-evident audit chain

AuditedLifecycle wraps every governed transition with the kernel's chainEntry/anchorChain/verifyChain hash-chain primitives, the same mechanism the Compliance bundle's audit-worm package uses. Off by default; set audited: true with a store (InMemoryAuditLifecycleStore ships for offline/CLI use, or bring your own) and each admitted step becomes an append-only, tamper-evident chain entry.

Composition

agent-kernel imports no vendor SDK and runs no LLM: it contributes the schema/FSM/ governance/hooks/audit-chain mechanism, never the engine wiring. It sits below the edition line, both base cli/mcp-server and the Agentic-Dev bundle's curated agent/skill/rule content compose it down-only.