Agent Action Preflight v1

Agent Action Preflight sits between an AI agent and its tools.

Before a concrete tool call executes, it records the current principal, destination, scope, authority evidence, and relevant relations, then determines whether that exact action is formed in the current configuration.

If it is formed, the tool may execute and an evidence receipt is recorded. If it is not formed, no tool call occurs and the missing or incompatible relations remain inspectable.

This free, dependency-free v1 provides one real, locally reproducible MCP path:

MCP client → execute_preflighted_note → Agent Action Preflight → local_notes.write → local text file

local_notes.write writes a .txt file only beneath the configured local storage root. It is intentionally the only integration in v1.

Quick start

Requires Node.js 20 or newer. There are no package dependencies.

git clone https://github.com/jinen-project/agent-action-preflight-v1.git agent-action-preflight-v1
cd agent-action-preflight-v1
npm test
npm run demo

The demo starts the MCP server, makes a real JSON-RPC tools/call, observes a created local file for the formed case, then makes the matched call without a destination and confirms the file was not created. It prints a temporary receipt directory you can inspect:

AAP_RECEIPTS_DIR=/path/printed/by/demo node src/cli.mjs recent
AAP_RECEIPTS_DIR=/path/printed/by/demo node src/cli.mjs show PRE_RECEIPT_ID

Related MCP server: Dvarapala

Run with an MCP client

Start the stdio server from this directory:

npm start

Use the execute_preflighted_note tool with a proposal such as:

{
  "principal": "agent-01",
  "action": "write_note",
  "tool": "local_notes.write",
  "arguments": { "filename": "hello.txt", "content": "hello" },
  "referent": "a local note",
  "destination": "demo-notes",
  "scope": "demo-notes",
  "authority_evidence": "sample-authority-agent-01-demo-notes"
}

By default, receipts are placed in .aap-receipts and notes in .aap-notes. Configure a different sample configuration or local storage with AAP_CONFIG, AAP_RECEIPTS_DIR, and AAP_STORAGE_ROOT.

Inspecting actions

node src/cli.mjs recent
node src/cli.mjs show PRE_RECEIPT_ID

The CLI gives a compact history (FORMED or NOT_FORMED) and the detail is the complete inspectable JSON receipt: principal, action, destination/referent, configuration ID, relations present/missing/incompatible/unresolved, formation basis, occurrence, evidence references, and provenance.

EXECUTABLE is not stored as a permission. Each pre-action receipt derives whether T ∈ EXECUTABLE_DOMAIN(C) from the current supplied configuration.

What it does not claim

This product is not:

• a universal AI safety system;

• a legal compliance guarantee;

• proof that an action is morally correct;

• proof that external information is true;

• proof that a successful action created value; or

• a replacement for external authorization systems.

Formation is separate from occurrence. A formed action can still fail at its tool, and a successful file write does not establish user value, world success, adoption, or causation.

Product boundary and status

Price: free. Billing, subscriptions, paywalls, enterprise tiers, user management, and analytics are absent.

The included demo is LIVE_OBSERVED locally when you run it. Automated tests are TESTED; they do not by themselves prove a third-party MCP client or any external tool integration. The actual file-writing tool invocation is observed by the demo's MCP tools/call and filesystem assertion.

Publication status: PUBLICATION_READY. This repository contains only source, sample configuration, and generated-on-demand local demo data. Run npm run secrets:scan before publishing. No publication occurs automatically.

Deferred: further tools, browser automation, policy suites, and generalized agent frameworks are outside v1.

Related free tools

• Evidence Packet — inspect the relationship between claims and supplied evidence.

• Reversibility Review — inspect what returned after a local file change.