# 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.

```sh
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:

```sh
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
```

## Run with an MCP client

Start the stdio server from this directory:

```sh
npm start
```

Use the `execute_preflighted_note` tool with a proposal such as:

```json
{
  "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

```sh
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](https://github.com/jinen-project/evidence-packet-v1) — inspect the relationship between claims and supplied evidence.
- [Reversibility Review](https://github.com/jinen-project/reversibility-review-v1) — inspect what returned after a local file change.