guardplane 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mohamed Kadri
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,167 @@
+# guardplane
+
+[![CI](https://github.com/mkadri85/guardplane/actions/workflows/ci.yml/badge.svg)](https://github.com/mkadri85/guardplane/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6.svg)
+![runtime dependencies](https://img.shields.io/badge/runtime%20deps-0-brightgreen.svg)
+
+A minimal, framework-agnostic **control plane for AI agent fleets**: a signal plane, a confidence gate, and a kill switch. Zero runtime dependencies.
+
+AI agents have started causing the production incidents they were built to resolve. In April 2026 a coding agent deleted a company's production database and its backups in about nine seconds. The pattern is not rare, and it has the same shape every time: an agent takes a real action on an incomplete view of the world, and nothing stands between its intent and the damage.
+
+This is a small reference implementation of the thing that stands in between. It is the companion to the write-up [**Who Operates the Operators?**](https://mkadri85.github.io/blog/agentic-sre-agent-fleets/).
+
+It is not a framework. It is the skeleton you wrap around whatever agent you already run.
+
+## The idea
+
+Take the incident loop that keeps infrastructure alive and point it at the agents themselves:
+
+- **Signal plane** - record one replayable event per agent decision. You cannot operate what you cannot see.
+- **Reasoning layer** - detectors decide whether an agent is actually broken (a loop, a cost runaway, an error spike, quiet quality drift).
+- **Confidence gate** - the whole safety design. High confidence in a known, reversible fix closes the loop itself; anything novel or ambiguous escalates to a human.
+- **Action layer** - a short menu of reversible remediations: reroute, roll back, pause.
+- **Kill switch** - a global and per-agent off switch you build before you need it.
+
+```
+   CONTROL PLANE    identity . policy . tool contracts . replay . kill switch
+        ^  decide (escalate on low confidence)
+   ACTION LAYER     reroute . roll back . pause
+        ^
+   REASONING LAYER  detect -> triage -> correlate   (is this agent broken?)
+        ^
+   SIGNAL PLANE     one replayable record per decision
+        ^
+   AGENT FLEET      [ a1 ] [ a2 ] [ a3 ] [ a9 failing ] ...
+```
+
+## Try it
+
+```bash
+git clone https://github.com/mkadri85/guardplane
+cd guardplane
+npm install
+npm run demo
+```
+
+The demo runs a small fleet through the plane: a healthy agent proceeds, a looping agent is auto-rerouted, a cost runaway is auto-paused, a quietly drifting agent is escalated to a human with its full replay, and then the kill switch stops the whole fleet.
+
+```text
+  guardplane  live demo
+
+  agent-01 healthy: three clean tool calls
+    allowed  call 1
+    allowed  call 2
+    allowed  call 3
+
+  agent-04 starts looping on a failing tool
+    allowed  retry 1
+    allowed  retry 2
+    allowed  retry 3
+    -> reroute agent-04: known loop, switch model
+    allowed  retry 4  [auto_remediate: confidence 0.90 >= 0.8 and reroute is auto-allowed]
+
+  agent-09 output quality quietly drifting
+    allowed  response 1
+    allowed  response 2
+    allowed  response 3
+    -> pause agent-09: containing before human review
+    ESCALATE agent-09 -> human
+    why: output quality drifting (2/4 weak responses) (confidence 0.50)
+    handing over the last 4 of 4 recorded decisions:
+      model_response   ok   300 tok
+      model_response   ERR  300 tok
+      model_response   ok   300 tok
+      model_response   ERR  300 tok
+    stopped  response 4  [escalate: confidence 0.50 < 0.8]
+
+  agent-07 burning tokens far past its budget
+    -> pause agent-07: token spend 12000 over budget 5000
+    stopped  one very expensive step  [auto_remediate: confidence 0.95 >= 0.8 and pause is auto-allowed]
+
+  kill switch tripped for the whole fleet
+    stopped  agent-01 tries another call  [blocked: kill switch tripped]
+```
+
+## Use it
+
+```ts
+import {
+  controlPlane,
+  loopDetector,
+  costRunawayDetector,
+  errorRateDetector,
+  driftDetector,
+  type Actions,
+} from "guardplane";
+
+// You implement these against your own runtime.
+const actions: Actions = {
+  reroute: (id, why) => switchModel(id),
+  rollback: (id, why) => revertAgent(id),
+  pause: (id, why) => drainToHumanQueue(id),
+};
+
+const plane = controlPlane({
+  detectors: [
+    loopDetector({ repeats: 4 }),
+    costRunawayDetector({ maxTokens: 50_000 }),
+    errorRateDetector({ threshold: 0.6 }),
+    driftDetector(),
+  ],
+  actions,
+  gate: { autoActThreshold: 0.8, autoAllow: ["reroute", "pause"] },
+  onEscalate: ({ agentId, health, replay }) => {
+    pageOnCall(agentId, health, replay); // hand a human the full trace
+  },
+});
+
+const agent = plane.wrap("agent-09");
+
+// Report each decision your agent makes. The plane records it, diagnoses the
+// agent, and tells you whether it may proceed.
+const { allowed, decision } = agent.observe({
+  type: "tool_call",
+  tool: "search",
+  ok: false,
+  tokens: 300,
+});
+
+if (!allowed) {
+  // the plane paused or escalated this agent; decision.reason says why
+}
+
+// The off switch, no deploy required:
+plane.killSwitch.trip("agent-09"); // or "global" for the whole fleet
+```
+
+## The confidence gate
+
+The gate is the only interesting decision in the system, so it is worth stating plainly. An agent earns autonomy per failure type; it is not a switch you flip once.
+
+| Diagnosis | Proposed fix | Ruling |
+| --- | --- | --- |
+| Confidence >= threshold, fix is known-safe and reversible | reroute / pause | **auto-remediate** |
+| Confidence below threshold | anything | **escalate** to a human |
+| Any confidence, but the fix is not on the auto-allow list | rollback, etc. | **escalate** to a human |
+| Healthy | none | **allow** |
+
+The default threshold is `0.8` and the default auto-allowed actions are `reroute` and `pause`. Both are configurable per plane.
+
+## What this is, and is not
+
+- It **is** a dependency-free skeleton you can read in one sitting and wire into an existing agent runtime in an afternoon.
+- It **is not** a hosted platform, an observability product, or a replacement for a real agent framework. It has no opinion about how your agents are built.
+- The detectors and actions are deliberately simple. They are meant to be replaced with your own.
+
+Detection is the hard part in practice: subtle, non-deterministic quality drift is exactly what standard checks miss. The `driftDetector` here is a placeholder for the more sensitive, continuous evaluation that real fleets need.
+
+## Design principles
+
+- **Reversible actions only.** Every built-in remediation can be undone. The gate is allowed to act on its own precisely because it cannot do anything it cannot take back.
+- **Contain before you page.** On escalation the plane pauses the agent first, then hands a human the full replay.
+- **The boring parts come first.** Per-agent identity, one recorded decision per step, and a kill switch matter more than the clever autonomous loop. Build them first.
+
+## License
+
+MIT. Built by [Mohamed Kadri](https://mkadri85.github.io/).

package/dist/actions.d.ts

@@ -0,0 +1,14 @@
+import type { AgentId } from "./types.js";
+/**
+ * The action layer. A deliberately short menu of real, reversible remediations
+ * the control plane can apply to an agent. You implement these against your own
+ * runtime (swap the model, revert a version, drain the agent's work to a queue).
+ */
+export interface Actions {
+    /** Send the agent's traffic to a different model or provider. */
+    reroute(agentId: AgentId, detail?: string): void | Promise<void>;
+    /** Roll the agent back to its last known-good version. */
+    rollback(agentId: AgentId, detail?: string): void | Promise<void>;
+    /** Pause the agent and drain its work to a human queue. */
+    pause(agentId: AgentId, detail?: string): void | Promise<void>;
+}

package/dist/actions.js

@@ -0,0 +1 @@
+export {};

package/dist/confidence-gate.d.ts

@@ -0,0 +1,18 @@
+import type { Decision, Health, Remediation, RemediationKind } from "./types.js";
+export interface GatePolicy {
+    /** Minimum confidence to act without a human. Default 0.8. */
+    autoActThreshold?: number;
+    /**
+     * Remediations the plane may apply on its own, for known, low-risk, reversible
+     * cases. Anything not listed here always escalates. Default: reroute + pause.
+     */
+    autoAllow?: RemediationKind[];
+}
+/**
+ * The confidence gate: the whole safety design in one function.
+ *
+ * High confidence in the diagnosis AND a known-safe, reversible remediation ->
+ * the loop closes itself. Anything novel, ambiguous, or risky -> escalate to a
+ * human. Autonomy is earned per failure type, not switched on globally.
+ */
+export declare function confidenceGate(policy?: GatePolicy): (health: Health, remediation: Remediation) => Decision;

package/dist/confidence-gate.js

@@ -0,0 +1,27 @@
+/**
+ * The confidence gate: the whole safety design in one function.
+ *
+ * High confidence in the diagnosis AND a known-safe, reversible remediation ->
+ * the loop closes itself. Anything novel, ambiguous, or risky -> escalate to a
+ * human. Autonomy is earned per failure type, not switched on globally.
+ */
+export function confidenceGate(policy = {}) {
+    const threshold = policy.autoActThreshold ?? 0.8;
+    const autoAllow = new Set(policy.autoAllow ?? ["reroute", "pause"]);
+    return (health, remediation) => {
+        if (health.status === "healthy") {
+            return { action: "allow", reason: "healthy" };
+        }
+        if (health.confidence >= threshold && autoAllow.has(remediation.kind)) {
+            return {
+                action: "auto_remediate",
+                remediation,
+                reason: `confidence ${health.confidence.toFixed(2)} >= ${threshold} and ${remediation.kind} is auto-allowed`,
+            };
+        }
+        const why = health.confidence < threshold
+            ? `confidence ${health.confidence.toFixed(2)} < ${threshold}`
+            : `${remediation.kind} is not in the auto-allow list`;
+        return { action: "escalate", remediation, reason: why };
+    };
+}

package/dist/control-plane.d.ts

@@ -0,0 +1,62 @@
+import type { AgentEvent, AgentId, Decision, Detector, Health, Remediation } from "./types.js";
+import { SignalPlane, type SignalSink } from "./signal-plane.js";
+import { KillSwitch } from "./kill-switch.js";
+import { type GatePolicy } from "./confidence-gate.js";
+import type { Actions } from "./actions.js";
+/** Everything the control plane hands a human when it decides to escalate. */
+export interface EscalationContext {
+    agentId: AgentId;
+    health: Health;
+    decision: Decision;
+    replay: AgentEvent[];
+}
+export interface ControlPlaneConfig {
+    /** The reasoning layer: run in order, worst finding wins. */
+    detectors: Detector[];
+    /** The action layer implementation. */
+    actions: Actions;
+    /** Called when the gate decides a human is needed. */
+    onEscalate: (ctx: EscalationContext) => void;
+    /** Confidence-gate policy (threshold, auto-allowed remediations). */
+    gate?: GatePolicy;
+    /** How far back detectors look, in ms. Default 60_000. */
+    windowMs?: number;
+    /** Optional durable sink for the signal plane. */
+    signalSink?: SignalSink;
+    /** Injectable clock, for tests and demos. Default Date.now. */
+    now?: () => number;
+    /** Map a diagnosis to a proposed remediation. Default: pause. */
+    planRemediation?: (health: Health, agentId: AgentId) => Remediation;
+}
+/** What `observe` tells the caller: may the agent proceed, and why. */
+export interface Observation {
+    allowed: boolean;
+    decision: Decision;
+}
+/** A per-agent handle onto the control plane. */
+export interface WrappedAgent {
+    agentId: AgentId;
+    observe(event: ObservableEvent): Observation;
+}
+/** An event as reported by the agent (the plane stamps agentId and ts). */
+export type ObservableEvent = Omit<AgentEvent, "agentId" | "ts"> & {
+    ts?: number;
+};
+/**
+ * The control plane. Wraps a fleet of agents so that every decision is recorded
+ * (signal plane), diagnosed (reasoning), gated (confidence gate), and either
+ * auto-remediated or escalated (action layer), with a kill switch over all of it.
+ */
+export declare class ControlPlane {
+    private readonly cfg;
+    readonly signals: SignalPlane;
+    readonly killSwitch: KillSwitch;
+    private readonly gate;
+    private readonly now;
+    constructor(cfg: ControlPlaneConfig);
+    /** Get a handle for one agent in the fleet. */
+    wrap(agentId: AgentId): WrappedAgent;
+    private observe;
+    private diagnose;
+    private apply;
+}

package/dist/control-plane.js

@@ -0,0 +1,91 @@
+import { SignalPlane } from "./signal-plane.js";
+import { KillSwitch } from "./kill-switch.js";
+import { confidenceGate } from "./confidence-gate.js";
+/**
+ * The control plane. Wraps a fleet of agents so that every decision is recorded
+ * (signal plane), diagnosed (reasoning), gated (confidence gate), and either
+ * auto-remediated or escalated (action layer), with a kill switch over all of it.
+ */
+export class ControlPlane {
+    cfg;
+    signals;
+    killSwitch;
+    gate;
+    now;
+    constructor(cfg) {
+        this.cfg = cfg;
+        this.signals = new SignalPlane({ sink: cfg.signalSink });
+        this.killSwitch = new KillSwitch();
+        this.gate = confidenceGate(cfg.gate);
+        this.now = cfg.now ?? (() => Date.now());
+    }
+    /** Get a handle for one agent in the fleet. */
+    wrap(agentId) {
+        return { agentId, observe: (event) => this.observe(agentId, event) };
+    }
+    observe(agentId, raw) {
+        // 1. Kill switch: a hard stop that beats everything else.
+        if (this.killSwitch.isTripped(agentId)) {
+            return { allowed: false, decision: { action: "blocked", reason: "kill switch tripped" } };
+        }
+        // 2. Signal plane: record the decision as one replayable event.
+        const event = {
+            agentId,
+            ts: raw.ts ?? this.now(),
+            type: raw.type,
+            ok: raw.ok,
+            tool: raw.tool,
+            tokens: raw.tokens,
+            detail: raw.detail,
+        };
+        this.signals.record(event);
+        // 3. Reasoning layer: is this agent actually broken?
+        const windowMs = this.cfg.windowMs ?? 60_000;
+        const window = this.signals.recent(agentId, windowMs, this.now());
+        const health = this.diagnose(window);
+        if (health.status === "healthy") {
+            return { allowed: true, decision: { action: "allow", reason: "healthy" } };
+        }
+        // 4. Confidence gate: act or escalate.
+        const remediation = (this.cfg.planRemediation ?? defaultPlan)(health, agentId);
+        const decision = this.gate(health, remediation);
+        // 5. Action layer.
+        if (decision.action === "auto_remediate" && decision.remediation) {
+            void this.apply(agentId, decision.remediation);
+            // a reroute lets the agent keep working; a pause/rollback stops this step
+            return { allowed: decision.remediation.kind === "reroute", decision };
+        }
+        if (decision.action === "escalate") {
+            // contain first, then hand the full replay to a human
+            void this.cfg.actions.pause(agentId, "containing before human review");
+            this.cfg.onEscalate({ agentId, health, decision, replay: this.signals.replay(agentId) });
+            return { allowed: false, decision };
+        }
+        return { allowed: true, decision };
+    }
+    diagnose(events) {
+        const findings = this.cfg.detectors
+            .map((d) => d(events))
+            .filter((f) => f !== null);
+        if (findings.length === 0)
+            return { status: "healthy", confidence: 1, reasons: [] };
+        const failing = findings.filter((f) => f.status === "failing");
+        const chosen = failing.length ? failing : findings;
+        return {
+            status: failing.length ? "failing" : "degraded",
+            confidence: Math.max(...chosen.map((f) => f.confidence)),
+            reasons: chosen.map((f) => f.reason),
+        };
+    }
+    async apply(agentId, r) {
+        if (r.kind === "reroute")
+            await this.cfg.actions.reroute(agentId, r.detail);
+        else if (r.kind === "rollback")
+            await this.cfg.actions.rollback(agentId, r.detail);
+        else
+            await this.cfg.actions.pause(agentId, r.detail);
+    }
+}
+function defaultPlan() {
+    return { kind: "pause" };
+}

package/dist/detector.d.ts

@@ -0,0 +1,30 @@
+import type { Detector } from "./types.js";
+/**
+ * Fires when an agent repeats the same tool call several times in a row. The
+ * classic stuck-in-a-loop failure. High confidence, because a loop is unambiguous.
+ */
+export declare function loopDetector(opts?: {
+    repeats?: number;
+}): Detector;
+/**
+ * Fires when token spend in the window exceeds a budget. Confidence scales with
+ * how far over budget the agent is.
+ */
+export declare function costRunawayDetector(opts: {
+    maxTokens: number;
+}): Detector;
+/** Fires when the recent failure rate crosses a threshold. */
+export declare function errorRateDetector(opts?: {
+    threshold?: number;
+    min?: number;
+}): Detector;
+/**
+ * Fires on subtle quality drift: a run of low-confidence or low-quality model
+ * responses that no single hard threshold catches. Deliberately reports MODEST
+ * confidence, so the gate escalates to a human instead of acting on a guess.
+ * This is the "silent degradation" case that standard checks miss.
+ */
+export declare function driftDetector(opts?: {
+    min?: number;
+    qualityFloor?: number;
+}): Detector;

package/dist/detector.js

@@ -0,0 +1,82 @@
+/**
+ * Fires when an agent repeats the same tool call several times in a row. The
+ * classic stuck-in-a-loop failure. High confidence, because a loop is unambiguous.
+ */
+export function loopDetector(opts = {}) {
+    const limit = opts.repeats ?? 4;
+    return (events) => {
+        const calls = events.filter((e) => e.type === "tool_call");
+        if (calls.length < limit)
+            return null;
+        const tail = calls.slice(-limit);
+        const tool = tail[0]?.tool;
+        if (tool && tail.every((e) => e.tool === tool)) {
+            return {
+                status: "failing",
+                confidence: 0.9,
+                reason: `looping on "${tool}" (${limit}x in a row)`,
+            };
+        }
+        return null;
+    };
+}
+/**
+ * Fires when token spend in the window exceeds a budget. Confidence scales with
+ * how far over budget the agent is.
+ */
+export function costRunawayDetector(opts) {
+    return (events) => {
+        const spent = events.reduce((sum, e) => sum + (e.tokens ?? 0), 0);
+        if (spent <= opts.maxTokens)
+            return null;
+        const over = spent / opts.maxTokens;
+        return {
+            status: over > 2 ? "failing" : "degraded",
+            confidence: Math.min(0.95, 0.5 + over / 4),
+            reason: `token spend ${spent} over budget ${opts.maxTokens}`,
+        };
+    };
+}
+/** Fires when the recent failure rate crosses a threshold. */
+export function errorRateDetector(opts = {}) {
+    const threshold = opts.threshold ?? 0.5;
+    const min = opts.min ?? 4;
+    return (events) => {
+        if (events.length < min)
+            return null;
+        const errors = events.filter((e) => !e.ok).length;
+        const rate = errors / events.length;
+        if (rate < threshold)
+            return null;
+        return {
+            status: rate >= 0.8 ? "failing" : "degraded",
+            confidence: Math.min(0.9, rate),
+            reason: `error rate ${(rate * 100).toFixed(0)}% over ${events.length} steps`,
+        };
+    };
+}
+/**
+ * Fires on subtle quality drift: a run of low-confidence or low-quality model
+ * responses that no single hard threshold catches. Deliberately reports MODEST
+ * confidence, so the gate escalates to a human instead of acting on a guess.
+ * This is the "silent degradation" case that standard checks miss.
+ */
+export function driftDetector(opts = {}) {
+    const min = opts.min ?? 3;
+    const floor = opts.qualityFloor ?? 0.5;
+    return (events) => {
+        const responses = events.filter((e) => e.type === "model_response");
+        if (responses.length < min)
+            return null;
+        // treat a failed model_response as a quality miss
+        const misses = responses.filter((e) => !e.ok).length;
+        const missRate = misses / responses.length;
+        if (missRate < floor)
+            return null;
+        return {
+            status: "degraded",
+            confidence: 0.5, // ambiguous on purpose
+            reason: `output quality drifting (${misses}/${responses.length} weak responses)`,
+        };
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+export type { AgentId, AgentEvent, EventType, Detector, Finding, Health, HealthStatus, Decision, GateAction, Remediation, RemediationKind, } from "./types.js";
+export { SignalPlane } from "./signal-plane.js";
+export type { SignalSink } from "./signal-plane.js";
+export { KillSwitch } from "./kill-switch.js";
+export type { KillScope } from "./kill-switch.js";
+export { confidenceGate } from "./confidence-gate.js";
+export type { GatePolicy } from "./confidence-gate.js";
+export { loopDetector, costRunawayDetector, errorRateDetector, driftDetector } from "./detector.js";
+export type { Actions } from "./actions.js";
+export { ControlPlane } from "./control-plane.js";
+export type { ControlPlaneConfig, WrappedAgent, Observation, ObservableEvent, EscalationContext, } from "./control-plane.js";
+import { ControlPlane, type ControlPlaneConfig } from "./control-plane.js";
+/** Convenience factory. `const plane = controlPlane({ ... })`. */
+export declare function controlPlane(cfg: ControlPlaneConfig): ControlPlane;

package/dist/index.js

@@ -0,0 +1,10 @@
+export { SignalPlane } from "./signal-plane.js";
+export { KillSwitch } from "./kill-switch.js";
+export { confidenceGate } from "./confidence-gate.js";
+export { loopDetector, costRunawayDetector, errorRateDetector, driftDetector } from "./detector.js";
+export { ControlPlane } from "./control-plane.js";
+import { ControlPlane } from "./control-plane.js";
+/** Convenience factory. `const plane = controlPlane({ ... })`. */
+export function controlPlane(cfg) {
+    return new ControlPlane(cfg);
+}

package/dist/kill-switch.d.ts

@@ -0,0 +1,20 @@
+import type { AgentId } from "./types.js";
+export type KillScope = AgentId | "global";
+/**
+ * A global and per-agent kill switch. Build the off switch before you need it,
+ * not during the outage. When tripped, the control plane blocks the agent's
+ * next action outright, no deploy required.
+ */
+export declare class KillSwitch {
+    private globalTripped;
+    private readonly tripped;
+    private readonly listeners;
+    /** Trip the switch. Default scope is the whole fleet. */
+    trip(scope?: KillScope): void;
+    /** Reset the switch. Default scope is the whole fleet. */
+    reset(scope?: KillScope): void;
+    /** Is this agent (or the whole fleet) currently stopped. */
+    isTripped(agentId?: AgentId): boolean;
+    /** Notified whenever the switch is tripped. */
+    onTrip(fn: (scope: KillScope) => void): void;
+}

package/dist/kill-switch.js

@@ -0,0 +1,36 @@
+/**
+ * A global and per-agent kill switch. Build the off switch before you need it,
+ * not during the outage. When tripped, the control plane blocks the agent's
+ * next action outright, no deploy required.
+ */
+export class KillSwitch {
+    globalTripped = false;
+    tripped = new Set();
+    listeners = [];
+    /** Trip the switch. Default scope is the whole fleet. */
+    trip(scope = "global") {
+        if (scope === "global")
+            this.globalTripped = true;
+        else
+            this.tripped.add(scope);
+        for (const l of this.listeners)
+            l(scope);
+    }
+    /** Reset the switch. Default scope is the whole fleet. */
+    reset(scope = "global") {
+        if (scope === "global")
+            this.globalTripped = false;
+        else
+            this.tripped.delete(scope);
+    }
+    /** Is this agent (or the whole fleet) currently stopped. */
+    isTripped(agentId) {
+        if (this.globalTripped)
+            return true;
+        return agentId ? this.tripped.has(agentId) : false;
+    }
+    /** Notified whenever the switch is tripped. */
+    onTrip(fn) {
+        this.listeners.push(fn);
+    }
+}

package/dist/signal-plane.d.ts

@@ -0,0 +1,27 @@
+import type { AgentEvent, AgentId } from "./types.js";
+/** Somewhere to durably ship events (a DB, a log pipeline, a queue). */
+export interface SignalSink {
+    write(event: AgentEvent): void;
+}
+/**
+ * The signal plane. Records one replayable event per agent decision and lets you
+ * replay an agent's full history or query a recent window. In-memory ring buffer
+ * by default; hand it a sink to also ship events somewhere durable.
+ */
+export declare class SignalPlane {
+    private events;
+    private readonly capacity;
+    private readonly sink?;
+    constructor(opts?: {
+        capacity?: number;
+        sink?: SignalSink;
+    });
+    /** Record a decision. Trims the oldest event once capacity is reached. */
+    record(event: AgentEvent): void;
+    /** Every recorded decision for one agent, oldest first. */
+    replay(agentId: AgentId): AgentEvent[];
+    /** Events for one agent within the last `windowMs` relative to `now`. */
+    recent(agentId: AgentId, windowMs: number, now: number): AgentEvent[];
+    /** All events across every agent (read-only). */
+    all(): readonly AgentEvent[];
+}

package/dist/signal-plane.js

@@ -0,0 +1,33 @@
+/**
+ * The signal plane. Records one replayable event per agent decision and lets you
+ * replay an agent's full history or query a recent window. In-memory ring buffer
+ * by default; hand it a sink to also ship events somewhere durable.
+ */
+export class SignalPlane {
+    events = [];
+    capacity;
+    sink;
+    constructor(opts = {}) {
+        this.capacity = opts.capacity ?? 10_000;
+        this.sink = opts.sink;
+    }
+    /** Record a decision. Trims the oldest event once capacity is reached. */
+    record(event) {
+        this.events.push(event);
+        if (this.events.length > this.capacity)
+            this.events.shift();
+        this.sink?.write(event);
+    }
+    /** Every recorded decision for one agent, oldest first. */
+    replay(agentId) {
+        return this.events.filter((e) => e.agentId === agentId);
+    }
+    /** Events for one agent within the last `windowMs` relative to `now`. */
+    recent(agentId, windowMs, now) {
+        return this.events.filter((e) => e.agentId === agentId && now - e.ts <= windowMs);
+    }
+    /** All events across every agent (read-only). */
+    all() {
+        return this.events;
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,45 @@
+export type AgentId = string;
+export type EventType = "tool_call" | "model_response" | "error";
+/**
+ * One replayable record per decision an agent makes. This is the atom of the
+ * signal plane: without it, every layer above is guessing.
+ */
+export interface AgentEvent {
+    agentId: AgentId;
+    ts: number;
+    type: EventType;
+    ok: boolean;
+    tool?: string;
+    tokens?: number;
+    detail?: string;
+}
+export type HealthStatus = "healthy" | "degraded" | "failing";
+/** A single detector's opinion about an agent's recent behavior. */
+export interface Finding {
+    status: HealthStatus;
+    confidence: number;
+    reason: string;
+}
+/** The reasoning layer's combined diagnosis for one agent. */
+export interface Health {
+    status: HealthStatus;
+    confidence: number;
+    reasons: string[];
+}
+/**
+ * A detector inspects an agent's recent events and returns a Finding, or null
+ * if nothing looks wrong to it.
+ */
+export type Detector = (events: AgentEvent[]) => Finding | null;
+export type RemediationKind = "reroute" | "rollback" | "pause";
+export interface Remediation {
+    kind: RemediationKind;
+    detail?: string;
+}
+export type GateAction = "allow" | "auto_remediate" | "escalate" | "blocked";
+/** The confidence gate's ruling on what to do about a diagnosis. */
+export interface Decision {
+    action: GateAction;
+    reason: string;
+    remediation?: Remediation;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "guardplane",
+  "version": "0.1.0",
+  "description": "A minimal, framework-agnostic control plane for AI agent fleets: signal plane, confidence gate, and kill switch.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Mohamed Kadri",
+  "keywords": [
+    "ai-agents",
+    "agentops",
+    "observability",
+    "sre",
+    "llm",
+    "kill-switch",
+    "control-plane",
+    "autonomous-agents"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mkadri85/guardplane.git"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "demo": "tsx examples/demo.ts",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}