GuardMesh

Policy enforcement layer for bounded agent actions.

GuardMesh is a lightweight specification, validation, and decision layer for bounded agent actions.

It is built for modular agent systems that need a portable answer to a narrow set of runtime questions:

• should this action be allowed?
• should it be denied?
• should it be escalated for approval?
• should a kill switch be triggered?

GuardMesh is intentionally not a full enterprise policy platform, a runtime sidecar, or a dashboard-heavy control plane. The first alpha stays focused on clear artifacts, strong decisions, and a clean developer workflow.

Alpha scope

This repository currently focuses on:

• parsing policy.yaml and request.json from an example pack
• validating minimum structure and policy boundaries
• evaluating requests into allow, deny, escalate, or kill
• producing readable explanations and machine-readable decision output
• shipping example policy packs that demonstrate the core decision semantics

Quick start

npm install
npm run build
node dist/cli.js validate ./examples/web-access-allow
node dist/cli.js evaluate ./examples/web-access-allow
node dist/cli.js explain ./examples/public-post-escalate

During development you can run the CLI directly with tsx:

npm run dev -- evaluate ./examples/emergency-kill-switch

For a full local release-style verification pass:

npm run check
npm run release:dry-run

Example packs

• examples/web-access-allow shows a straightforward allow decision for low-risk public web access.
• examples/public-post-escalate shows approval-driven escalation for posting into a public channel.
• examples/admin-change-deny shows an explicit deny rule for risky control-plane changes.
• examples/emergency-kill-switch shows a kill decision for actions that should terminate execution immediately.

CLI

guardmesh validate <example-dir>
guardmesh validate <example-dir> --json
guardmesh lint <example-dir> --json
guardmesh schema-check <example-dir> --json
guardmesh inspect-policy <example-dir>
guardmesh inspect-request <example-dir>
guardmesh evaluate <example-dir>
guardmesh test-pack <example-dir> --json
guardmesh explain <example-dir>

evaluate returns machine-readable JSON. explain returns a human-readable rationale intended for operators, reviewers, or logs.

Additional authoring commands:

guardmesh lint <example-dir>
guardmesh test-pack <example-dir>

lint highlights policy-pack quality issues such as duplicate rule ids, overly broad rules, or shadowed rules. test-pack compares the evaluated output to decision.expected.json, which makes example packs executable documentation.

schema-check runs optional runtime validation against the shipped JSON schemas for policy, request, and decision artifacts.

Exit codes:

• 0 means success.
• 1 means validation, lint, schema, or usage failure.
• 2 means the evaluated action did not produce an allow result or an expectation test failed.

Repository layout

docs/       product and design documentation
examples/   example policy packs
schemas/    JSON schemas for policy, request, and decision artifacts
src/        parsers, validation, evaluation, explanation, and CLI

Artifact model

GuardMesh alpha uses three artifacts:

• policy.yaml defines allowed subject, action, and resource domains plus decision rules.
• request.json describes the bounded action request being evaluated.
• decision output JSON captures the chosen decision, matched rules, approval status, and validation issues.

The canonical request field is request_id. For developer convenience, the parser also accepts the legacy alias requestId.

Programmatic API

GuardMesh can also be embedded directly:

import { evaluateDirectory, lintDirectory, testPolicyPack } from "guardmesh";

const evaluation = evaluateDirectory("./examples/web-access-allow");
console.log(evaluation.decision.decision);

const lint = lintDirectory("./examples/web-access-allow");
const packTest = testPolicyPack("./examples/web-access-allow");

The initial runtime API stays deliberately small and file-based so integrations can start simple.

For longer-lived integrations, you can also instantiate PolicyEngine directly once you already have a policy and request object.

If you want runtime schema checks in addition to code-driven validation, use schemaCheckDirectory or the individual schema validation helpers.

Policy composition

GuardMesh supports a minimal extends field in policy.yaml for file-based composition.

• extends is resolved relative to the child policy file.
• child scalar fields override parent fields
• declared type arrays are merged and deduplicated
• constraints are shallow-merged
• parent rules are loaded before child rules

This keeps composition understandable while avoiding a larger bundle system in the alpha.

Ecosystem Fit

GuardMesh is one building block in a broader family of OSS components for reliable and governable agent systems.

• SkillPulse focuses on skill reliability signals.
• Agent Contracts focuses on delegated task structure.
• CapToken focuses on bounded authorization.
• TraceForge focuses on execution trace artifacts.
• AgentEvalOps focuses on evaluation and failure-mode analysis.
• GuardMesh focuses on portable policy decisions at action boundaries.

GuardMesh should complement those modules, not absorb their responsibilities.

Design principles

• Keep the surface area narrow and easy to understand.
• Prefer explicit decisions over implicit behavior.
• Make the CLI the first real integration surface.
• Leave room for future policy packs, adapters, and richer semantics without overengineering the alpha.

Documentation

• Vision
• Architecture
• Policy Spec
• Roadmap
• Release Checklist
• Contributing
• Alpha Stability Policy
• Security Policy
• Code Of Conduct

License

MIT