In-Loop Processors

A Processor is a loop-internal observer/guardrail for the agent run. It watches the model's streamed output and the tool calls it requests as the run progresses, keeps its own scratch state, and can abort the run before a "done" is claimed. This is the structural prerequisite for real-time guardrails (block disallowed output mid-stream) and a proof-of-done / coverage gate (inspect what the model is about to do and halt it).

The hooks

A processor implements any subset of three optional lifecycle hooks (the shape is borrowed from Mastra's output processors):

Each processor gets its own mutable, run-scoped state object that persists across every one of its hook invocations within a single run and is isolated from other processors' state.

import type { Processor } from "@agent-native/core";

const noSecretsInOutput: Processor = {
  name: "no-secrets",
  processOutputStream({ part, abort }) {
    if (part.type === "text" && /sk-live_/.test(part.text)) {
      abort("Model attempted to emit a live secret token.", {
        kind: "secret-leak",
      });
    }
  },
};

const coverageGate: Processor = {
  name: "proof-of-done",
  processOutputStep({ toolCalls, state }) {
    // Track what the model has actually done this run...
    for (const call of toolCalls) {
      (state.ran ??= new Set<string>()).add(call.name);
    }
  },
  processOutputResult({ text, state }) {
    // ...and record a verdict over the final answer.
    const ran = state.ran as Set<string> | undefined;
    state.verdict = ran?.has("run-tests") ? "verified" : "unverified";
  },
};

Aborting with TripWire

A hook halts the run by calling abort(reason, meta?), which throws a TripWire. The loop catches it, emits a single tripwire event, stops cleanly, and surfaces the reason as the final assistant message.

import { TripWire } from "@agent-native/core";

The tripwire event carries:

TripWire also carries optional structured meta and the originating processor name for programmatic consumers that instanceof-check it. Because a halt is graceful, processOutputResult still fires on the (halted) final text so a proof-of-done processor can record its verdict even when the run was aborted.

Wiring processors

Processors are configured in code via the processors array on runAgentLoop:

await runAgentLoop({
  engine,
  model,
  systemPrompt,
  tools,
  messages,
  actions,
  send,
  signal,
  processors: [noSecretsInOutput, coverageGate],
});

Zero-overhead when unused. The loop builds the processor chain only when at least one processor is supplied; when processors is omitted or empty, none of the seam code runs and the loop is byte-for-byte unchanged. Hooks run in registration order and may be sync or async.

What's next

• Durable Resume — how the loop survives interruptions without re-running completed side effects.
• Custom Agents & Teams — sub-agents run the same loop and can carry their own processors.
• Observability — record processor verdicts alongside run traces.