Skip to content
Back to search

agent-safe-pipeline

An execution-authority gateway for AI agents and APIs. It intercepts consequential HTTP actions, asks Decionis whether they are authorized, and forwards exactly the authorized request once on a single-use grant, holds it for a person, or refuses it, leaving chained evidence of each. Installs by Homebrew, Linux package, Docker or Helm.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/decionis/agent-safe-pipeline with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/decionis/agent-safe-pipeline'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/decionis--agent-safe-pipeline/badge.svg)](/listings/decionis--agent-safe-pipeline)

HTML

<a href="/listings/decionis--agent-safe-pipeline"><img src="/api/listings/decionis--agent-safe-pipeline/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Nothing here needs an account: without a Decionis key the gateway runs a local demo authority in the same process, on loopback, with a synthetic policy, and says so on every line.

agentsafe proxy --upstream http://localhost:3000 --port 8080
AgentSafe 0.2.5

Gateway      http://127.0.0.1:8080
Upstream     http://localhost:3000
Mode         ENFORCEMENT
Authority    local/demo (synthetic policy on loopback; not Decionis)
Failure      fail-closed
Routes       none named; every unsafe method is governed
Evidence     not written; use --verbose or evidence.journalDir
Status       READY

Waiting for consequential actions...

Send it one request:

curl -i -X POST http://127.0.0.1:8080/payments -H 'content-type: application/json' -d '{"amount": 500}'
ESCALATE

POST /payments

Action       http.post
Decision     ESCALATE
Reason       HUMAN_APPROVAL_REQUIRED
Execution    HELD
Dossier      synthetic-dossier-1
Latency      4ms

The caller gets `202` and nothing reached the upstream. `{"amount": 50}` is `ALLOW`: forwarded once, byte for byte, with the dossier id beside the upstream's own answer. `{"amount": 5000}` is `BLOCK`: `403`, not forwarded. A `GET` passes through untouched. Every state has its own heading and, with a terminal, its own color: `ALLOW`, `BLOCK`, `ESCALATE`, `SHADOW`, `AUTHORITY UNAVAILABLE`. `--verbose` shows the chained evidence lines; `agentsafe init` writes the configuration file; `agentsafe doctor` says what would stop it from governing; `agentsafe login` connects a Decionis key, after which the same gateway asks Decionis, in shadow first. A gateway in shadow keeps its own [shadow report](./docs/shadow-mode.md#from-shadow-to-enforcement): what enforcement would have held or refused so far, by action, and how many of those refusals the upstream accepted as sent, which `agentsafe status` prints, the gateway prints when it stops and on its own cadence as it runs, ending with the one switch that turns enforcement on; `agentsafe login --provision` mints the free Decionis workspace that switch names. The [quickstart](./docs/quickstart/README.md) is the full walk, and the [CLI reference](./docs/reference/cli.md) every command.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 799 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # AgentSafe
  2. [![Continuous integration](https://github.com/decionis/agent-safe-pipeline/actions/workflows/deploy.yml/badge.svg?branch=master)](https://github.com/decionis/agent-safe-pipeline/actions/workflows/deploy.yml)
  3. [![CodeQL](https://github.com/decionis/agent-safe-pipeline/actions/workflows/codeql.yml/badge.svg?branch=master)](https://github.com/decionis/agent-safe-pipeline/actions/workflows/codeql.yml)
  4. [![Secret scanning](https://github.com/decionis/agent-safe-pipeline/actions/workflows/secrets.yml/badge.svg?branch=master)](https://github.com/decionis/agent-safe-pipeline/actions/workflows/secrets.yml)
  5. [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/decionis/agent-safe-pipeline/badge)](https://scorecard.dev/viewer/?uri=github.com/decionis/agent-safe-pipeline)
  6. [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/14098/badge)](https://www.bestpractices.dev/projects/14098)
  7. [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](./LICENSE)
  8. **Authorize every autonomous action, before it commits.**
  9. AgentSafe is the open-source gateway that puts authorization in front of every action your AI
  10. agents, workflows and pipelines take: a payment or a settlement, a trade, a price change, an
  11. inspection sign-off, a deployment or any other API call. An agent, an application or a tool sends
  12. its HTTP request to AgentSafe instead of the target; AgentSafe captures the action as an intent, asks the [Decionis](https://decionis.com)
  13. control plane (the Independent Execution Authority, bound to the exact action) for a decision, and
  14. forwards exactly the authorized request once on a claimed single-use grant, holds it for a person,
  15. or refuses it, leaving a chained record of each. It decides nothing itself.
  16. ```bash
  17. brew tap decionis/agent-safe https://github.com/decionis/agent-safe-pipeline && brew trust decionis/agent-safe && brew install agentsafe
  18. agentsafe proxy \
  19. --upstream http://localhost:3000 \
  20. --port 8080
  21. ```
  22. [5-minute quickstart](./docs/quickstart/README.md) · [Homebrew](./docs/install/macos.md) ·
  23. [Linux](./docs/install/linux.md) · [Docker](./docs/install/docker.md) ·
  24. [Kubernetes](./docs/install/kubernetes.md) · [Hosted](./docs/install/hosted.md)
  25. [Agent integration and deployment guide](./docs/gateway/deployment.md): put the gateway in front
  26. of tool calls, deploy on premises, or connect to the Decionis-managed shadow gateway. For a Drupal
  27. Commerce store, [the gateway holds the Fincra key](./docs/gateway/drupal-commerce.md).
  28. [Deployment strategies](./docs/deployment/gateway-strategies.md): Docker with TLS ingress,
  29. Kubernetes, Istio, AWS and Azure network isolation, and deployment acceptance checks.
  30. > The installed forms are produced by the release workflow from `v0.2.0` on; the Homebrew formula
  31. > reaches master by its own pull request after each release. The same commands run from a clone,
  32. > as the quickstart shows.
  33. The path from here is short: discover, install, **test your boundary**, see what is exposed, run in
  34. shadow, enforce, deploy.
  35. ## The two systems behind the boundary
  36. Arriving here for the first time, you meet three names. This repository is one of them; the other
  37. two are the services it talks to, and neither is in this repository.
  38. - **Decionis** is the Independent Execution Authority, bound to the exact action: the control
  39. plane AgentSafe asks. For one captured intent it evaluates the organization's policy and answers
  40. `ALLOW`, `ESCALATE` or `BLOCK`; an `ALLOW` comes with the single-use execution grant the request
  41. executes on, an `ESCALATE` with the human ceremony it needs, and every decision with a signed
  42. [Decision Dossier](https://docs.decionis.com/decision-dossier) that records what was proposed,
  43. what was decided and why. It runs at [decionis.com](https://decionis.com)
  44. ([docs](https://docs.decionis.com)); the local demo authority in this repository stands in for it
  45. on loopback with a synthetic policy, and says so on every line.
  46. - **Presence** is the adaptive human verification layer. When Decionis answers `ESCALATE`, a
  47. verified, present person on their own device approves that exact action, and the signed Presence
  48. Record that results is evidence Decionis re-checks before it issues a grant, never authority by
  49. itself. It runs at [presence.decionis.com](https://presence.decionis.com)
  50. ([what the layer is](https://decionis.com/proof-of-human-infrastructure)); the loopback double
  51. in this repository simulates the ceremony for the examples and proves nothing about a real one.
  52. - **AgentSafe**, this repository, is the execution boundary between your agent or API and those
  53. two: it captures the exact intent, asks Decionis, resolves an `ESCALATE` with Presence, forwards
  54. exactly the authorized request once on the claimed grant, holds or refuses the rest, and leaves
  55. chained evidence. It is Apache-2.0 and it decides nothing; [`OPEN-CORE.md`](./OPEN-CORE.md)
  56. states the seam between it and what Decionis operates.
  57. One sentence separates the two systems agents are usually given: decision intelligence determines
  58. what an AI wants to do; execution authority determines whether it is permitted to happen. The
  59. boundary here binds the second to the exact action, never to the identity that proposed it,
  60. because the realistic adversary is not a forged credential but a valid one: an agent whose identity
  61. is real, whose credential is current, and whose request is not what anyone authorised. As agents
  62. get faster and more autonomous, identity becomes a weaker proxy for authority; the
  63. [Compromised Principal Test](./docs/compromised-principal-test.md) is that failure stated as a
  64. test the boundary passes on every pull request, with three ways to run it in under a minute and
  65. what each proves; [THREAT-MODEL.md](./THREAT-MODEL.md#the-compromised-principal-test) states it
  66. as a threat.
  67. ## Test your boundary
  68. Before putting the gateway in front of anything, see what it changes. `agentsafe test` sends the
  69. same consequential requests three ways at a synthetic target that records what reaches it:
  70. directly, as an agent with nothing in the way; through the gateway in shadow; and through the
  71. gateway in enforcement. Nothing real is called and nothing of yours is read.
  72. ```bash
  73. agentsafe test
  74. ```
  75. ```text
  76. direct shadow enforcement
  77. A read reached 200 reached 200 reached 200 (not consequential)
  78. A payment within policy reached 201 reached 201, would ALLOW ALLOW: forwarded once, 201, dossier
  79. A payment above the human ceiling reached 201 reached 201, would BLOCK BLOCK 403, NOT FORWARDED
  80. A payment above the autonomous ceiling reached 201 reached 201, would ESCALATE ESCALATE 202, HELD
  81. Deleting a customer record reached 204 reached 204, would ESCALATE ESCALATE 202, HELD
  82. A forged approval on a blocked payment reached 201, forged headers accepted reached 201, would BLOCK BLOCK 403, NOT FORWARDED
  83. A consequential request the policy cannot read reached 201 reached 201, would ESCALATE ESCALATE 202, HELD
  84. A payment while the authority is unreachable reached 201 reached 201, would decide nothing (authority unreachable) AUTHORITY UNAVAILABLE 503, NOT FORWARDED
  85. with failurePolicy failOpen (explicit): reached 201, marked FORWARDED (fail-open, ungoverned)
  86. Exposure 6 of 6 adversarial actions reached the target directly, 6 of 6 in shadow, 0 of 6 under enforcement
  87. Work routine actions went through under enforcement, once each
  88. Evidence 26 chained lines, verified
  89. Caller the same on every row, and never the reason: the target took every direct request; the boundary decided on the action
  90. Verdict BOUNDARY HOLDS
  91. Next: agentsafe proxy --upstream <your service> --mode shadow, then --mode enforcement.
  92. ✓ boundary tested
  93. ```
  94. The gateways under test are the ones `agentsafe proxy` runs, behind the same listener; the
  95. authority is the local demo policy. `agentsafe test ledger=ledger.internal:443` also dials a real
  96. system of record from where you stand and says whether it answers without the gateway, which is
  97. what an agent could reach by going around. Exit `0` is a boundary that holds; `1` is exposure;
  98. `--json` is the report as one line. The release smoke test runs it on every packaged binary. The
  99. `Caller` line is the point: nothing above was refused for who asked, only for what was asked,
  100. which is the [Compromised Principal Test](./docs/compromised-principal-test.md) in one table; the
  101. last line is the step of the [adoption path](./docs/reference/telemetry.md#activation-milestones)
  102. the run is.
  103. With a workspace, `agentsafe test --hosted` sends the same requests with Decionis deciding, in
  104. shadow, at the same synthetic target: the first governed action against Decionis for that
  105. workspace, one signed Decision Dossier per consequential request, and the first record fetched
  106. with the run's own key and shown by its proof. `agentsafe login --provision` mints the workspace
  107. in one command, no account; the test takes about as long as the local one.
  108. ## Five-minute quickstart
  109. Nothing here needs an account: without a Decionis key the gateway runs a local demo authority in
  110. the same process, on loopback, with a synthetic policy, and says so on every line.
  111. ```bash
  112. agentsafe proxy --upstream http://localhost:3000 --port 8080
  113. ```
  114. ```text
  115. AgentSafe 0.7.0
  116. Gateway http://127.0.0.1:8080
  117. Upstream http://localhost:3000
  118. Mode ENFORCEMENT
  119. Authority local/demo (synthetic policy on loopback; not Decionis)
  120. Failure fail-closed
  121. Routes none named; every unsafe method is governed
  122. Evidence not written; use --verbose or evidence.journalDir
  123. Status READY
  124. Waiting for consequential actions...
  125. ```
  126. Send it one request:
  127. ```bash
  128. curl -i -X POST http://127.0.0.1:8080/payments -H 'content-type: application/json' -d '{"amount": 500}'
  129. ```
  130. ```text
  131. ESCALATE
  132. POST /payments
  133. Action http.post
  134. Decision ESCALATE
  135. Reason HUMAN_APPROVAL_REQUIRED
  136. Execution HELD
  137. Dossier synthetic-dossier-1
  138. Latency 4ms
  139. ```
  140. The caller gets `202` and nothing reached the upstream. `{"amount": 50}` is `ALLOW`: forwarded
  141. once, byte for byte, with the dossier id beside the upstream's own answer. `{"amount": 5000}` is
  142. `BLOCK`: `403`, not forwarded. A `GET` passes through untouched. Every state has its own heading
  143. and, with a terminal, its own color: `ALLOW`, `BLOCK`, `ESCALATE`, `SHADOW`, `AUTHORITY
  144. UNAVAILABLE`. `--verbose` shows the chained evidence lines; `agentsafe init` writes the
  145. configuration file; `agentsafe doctor` says what would stop it from governing; `agentsafe login`
  146. connects a Decionis key, after which the same gateway asks Decionis, in shadow first. A gateway in
  147. shadow keeps its own [shadow report](./docs/shadow-mode.md#from-shadow-to-enforcement): what
  148. enforcement would have held or refused so far, by action, and how many of those refusals the
  149. upstream accepted as sent, which `agentsafe status` prints, the gateway prints when it stops and
  150. on its own cadence as it runs, ending with the one switch that turns enforcement on;
  151. `agentsafe login --provision` mints the free Decionis workspace that switch names. The
  152. [quickstart](./docs/quickstart/README.md) is the full walk, and the
  153. [CLI reference](./docs/reference/cli.md) every command.
  154. ## How it works
  155. ```text
  156. Agent / Application / Tool
  157. │
  158. ▼
  159. AgentSafe
  160. ingress / interceptor captures the action as an intent (agent-safe.intent/1)
  161. │
  162. ▼
  163. Decionis Control Plane policy, ExecutionBinding, Presence, Decision Dossiers
  164. │
  165. ALLOW | BLOCK | ESCALATE
  166. │
  167. ▼
  168. AgentSafe claims the single-use grant, forwards the exact bytes once
  169. │
  170. ▼
  171. Target Service / API
  172. │
  173. ▼
  174. finalize COMMITTED | FAILED | INDETERMINATE, on the Decision Dossier
  175. ```
  176. AgentSafe owns ingress and interception, action extraction and normalization, enforcement of the
  177. verdict, claim-before-forward, forwarding, effect evidence, finalization, fail-safe behavior and
  178. the local ergonomics. Decionis owns execution authority: policy evaluation, `ALLOW` / `BLOCK` /
  179. `ESCALATE`, policy versioning, ExecutionBinding semantics, Presence verification, Decision Dossiers,
  180. and the verification of evidence and authority. AgentSafe is not a second policy engine: the local
  181. demo authority is a loopback double of the Decionis routes, named `local/demo` everywhere, refused
  182. in production.
  183. | State | What happened | The caller sees |
  184. | ----------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
  185. | `ALLOW` | The grant was claimed and the exact request forwarded once | The upstream's response, plus `agentsafe-decision`, `agentsafe-dossier-id`, `agentsafe-execution` |
  186. | `ESCALATE` | Held for a person; with Presence, a resume asks Decionis again | `202`, `execution: HELD`, a `resume` path |
  187. | `BLOCK` | Refused; nothing forwarded | `403` with the dossier that records why |
  188. | `AUTHORITY_UNAVAILABLE` | Decionis could not be asked; fail-closed refuses, fail-open forwards ungoverned and records it | `503` with `Retry-After`, never a `BLOCK` |
  189. | `SHADOW` | Forwarded unchanged while Decionis recorded what it would have decided | The upstream's response, `agentsafe-mode: SHADOW` |
  190. What is bound and forwarded, and what each outcome finalizes as, is
  191. [docs/gateway/http-interception.md](./docs/gateway/http-interception.md); what happens when the
  192. authority cannot be reached is [docs/gateway/failure-policy.md](./docs/gateway/failure-policy.md);
  193. the configuration, one schema for every distribution with the precedence flags, environment, file,
  194. defaults, is [docs/gateway/configuration.md](./docs/gateway/configuration.md). A route's optional
  195. `policyId` or `policyVersion` [selects a published Decionis policy](./docs/gateway/routes.md#selecting-a-policy)
  196. and is bound into the action's top-level parameters; its `action` names the transaction for rules
  197. to match. These selectors come from operator configuration, never the caller's body. The gateway is
  198. addressed: the workload is pointed at it. `agentsafe intercept` holds the same boundary without
  199. configuring the workload, by redirecting a pod's or a container's outbound 80 and 443 into
  200. AgentSafe at the network layer, reporting every destination it reaches, and governing the ones the
  201. operator names under an authority the workload trusts;
  202. [docs/gateway/transparent-interception.md](./docs/gateway/transparent-interception.md) says what
  203. is observed, what is governed, and what the authority costs.
  204. ## Install
  205. One runtime, five ways to run it. The executable, the packages, the image and the chart are built
  206. and smoke-tested by the release workflow from the same code; nothing about authority, binding,
  207. claim or finalization differs between them.
  208. | Where | How | Page |
  209. | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------ |
  210. | macOS | `brew tap decionis/agent-safe https://github.com/decionis/agent-safe-pipeline && brew trust decionis/agent-safe && brew install agentsafe` | [macOS](./docs/install/macos.md) |
  211. | Linux | `curl -fsSL https://raw.githubusercontent.com/decionis/agent-safe-pipeline/master/packaging/install.sh \| sh`, or the `.deb` / `.rpm` with a hardened systemd unit | [Linux](./docs/install/linux.md) |
  212. | Docker | `ghcr.io/decionis/agentsafe:<version>`, the same digest as `docker.io/decionis/agentsafe:<version>`; distroless, non-root, two architectures | [Docker](./docs/install/docker.md) |
  213. | Kubernetes | `helm install agentsafe oci://ghcr.io/decionis/charts/agentsafe`, one Deployment in front of one Service | [Kubernetes](./docs/install/kubernetes.md) |
  214. | Hosted | `{id}.decionisedge.com`, the same runtime, run by Decionis for the tenants it onboards: enforcing on a gateway of the tenant's own (private beta), or in shadow; no self-serve sign-up yet | [Hosted](./docs/install/hosted.md) |
  215. | From source | `git clone`, `pnpm install --frozen-lockfile`, `pnpm build`, `node packages/agentsafe/dist/Cli.js` | [Quickstart](./docs/quickstart/README.md) |
  216. Every install page ends at the same place: send your first governed action.
  217. Govern, the workflow gate, ships with the same releases as one static binary per platform:
  218. `curl -fsSL https://raw.githubusercontent.com/decionis/agent-safe-pipeline/master/govern/install.sh | sh`,
  219. `brew install govern` from the same tap, or `go install github.com/decionis/agent-safe-pipeline/govern/v2/cmd/govern@v2.1.0`;
  220. [its README](./govern/README.md#install) has the rest.
  221. ## Golden adversarial demo
  222. One legitimate path and eight adversarial attempts against the same boundary, offline, in a few seconds, with every expectation asserted:
  223. ```bash
  224. git clone https://github.com/decionis/agent-safe-pipeline.git && cd agent-safe-pipeline
  225. pnpm install --frozen-lockfile
  226. pnpm --filter @decionis/agent-safe-example-golden-adversarial demo
  227. ```
  228. A treasury agent proposes a USD 250,000 wire, a remote Chief Risk Officer completes a FIDO2 plus liveness ceremony, and exactly one wire executes. Injected authorization fields, a fabricated ALLOW, an asserted approval, a swapped receipt, a post-approval amount change, a replayed grant, 25 concurrent claims, a shadow observation, and an expired grant all fail to execute. The run exits 0 only when that holds. See [`examples/golden-adversarial-demo`](./examples/golden-adversarial-demo), the bank-audience walkthrough in [`docs/remote-cro-authorization.md`](./docs/remote-cro-authorization.md), and the receipt semantics in [`docs/presence-evidence.md`](./docs/presence-evidence.md).
  229. The same proof for infrastructure, and for the adversary a credential check cannot catch:
  230. ```bash
  231. pnpm --filter @decionis/agent-safe-example-infra-scale demo
  232. ```
  233. An infrastructure agent with a valid identity and a valid credential proposes `deployment.scale`
  234. for `inference` in `prod-eu` at 96 replicas and is allowed. The same agent, with nothing forged,
  235. then proposes 960 replicas, a service outside its remit, another cluster, the 96 decision with 960
  236. substituted after authorization, an approval for 256 presented for 512, a replayed grant, and a
  237. direct call to the cluster: nothing executes, because authority was bound to the exact action and
  238. not to the identity. See [`examples/infra-scale-demo`](./examples/infra-scale-demo) and the
  239. [Compromised Principal Test](./THREAT-MODEL.md#the-compromised-principal-test).
  240. And its counterpart, where the principal is honest and the world changes between the decision and
  241. the commit:
  242. ```bash
  243. pnpm --filter @decionis/agent-safe-example-changed-conditions demo
  244. ```
  245. A deploy agent's queued canary meets a configuration changed at the path it read, a target group
  246. that grew, a second rollout racing for the last unit of the allowance, a withdrawn change approval, a policy
  247. release, and a security group reclassified as production; a grant is replayed, substituted, and
  248. carried into another organisation, and the agent tries to raise its own ceiling. Every one is
  249. refused at the commit, every legitimate counterpart (a renewal, a safe retry under the same
  250. identity, reauthorized work after a repair) completes exactly once, and a lost acknowledgement is
  251. reconciled without a second send. The recording target behind `agentsafe test` counts what reached
  252. it. The race is refused because the allowance is a material signal the deploy API re-versions with
  253. each commit, and, when the allowance is published after the commit instead of with it, because the
  254. authority also holds it as an allowance it reserves with the grant and counts at the commit. See [`examples/changed-conditions-demo`](./examples/changed-conditions-demo) and the
  255. [Changed Conditions Test](./docs/changed-conditions-test.md).
  256. ## Execution lifecycle
  257. For a consequential action, in every distribution and in the library alike:
  258. ```text
  259. request → normalize intent → enforce-and-bind → ALLOW | BLOCK | ESCALATE
  260. ALLOW → claim-token → forward the exact authorized action, once → capture effect → finalize-token
  261. COMMITTED | FAILED | INDETERMINATE
  262. BLOCK → nothing is forwarded
  263. ESCALATE → nothing is forwarded → Presence, or a managed ceremony Decionis runs → signed approval
  264. evidence → Decionis reauthorization → a new grant → claim → execute once → finalize
  265. ```
  266. An `ESCALATE` is never turned into an `ALLOW` locally, and a Presence approval is never trusted
  267. without Decionis reauthorization. The pages under [docs/authority](./docs/authority/execution-binding.md)
  268. map each step onto the protocol: [ExecutionBinding](./docs/authority/execution-binding.md),
  269. [claim and finalize](./docs/authority/claim-finalize.md), [Presence](./docs/authority/presence.md),
  270. [evidence](./docs/authority/evidence.md), and how those records relate to the SCITT drafts for agent
  271. actions, [SCITT statement profiles](./docs/authority/scitt.md). The provider's half, the procedure by which a system of
  272. record or the hop in front of it refuses what the authority never claimed, is the
  273. [Verifying Provider Profile](./docs/authority/verifying-provider.md), with
  274. [vectors](./conformance/provider/README.md) any implementation can run and independent verifiers
  275. that run them, for [Envoy `ext_authz`](./verifiers/envoy/README.md) and
  276. [Kong](./verifiers/kong/README.md), for [Spring and Apigee](./verifiers/spring/README.md), for
  277. [Rust services with a tower layer](./verifiers/rust/README.md), and for
  278. [ASP.NET Core](./verifiers/dotnet/README.md). A provider that verified the claim can answer with
  279. its own signed receipt of the effect (VP-3): the executor forwards it unread at finalization, and
  280. Decionis verifies it against the key the organisation registered for the provider and records it
  281. with the commit, so the dossier carries the provider's signature over what happened and not only
  282. the executor's report of it.
  283. ### Production invariants
  284. 1. Agent input contains only the proposed action, target, and parameters. Tenant, actor, downstream target, and credentials come from trusted runtime configuration.
  285. 2. The exact canonical intent is hashed and expires quickly.
  286. 3. Decionis independently decides. Network errors, malformed responses, missing grants, or binding mismatches fail closed.
  287. 4. Presence proves a human approved that exact intent; Presence never directly authorizes execution. Decionis verifies the receipt and re-evaluates policy.
  288. 5. The grant is bound to the intent, decision, audience, and expiry and is claimed atomically before the handler runs; the attempt outcome is finalized with the authority afterwards as evidence, never as authority.
  289. 6. Downstream credentials exist only behind the trusted executor.
  290. 7. Every decision is evidence-bearing. An ALLOW whose response lacks a dossier identifier or grant is refused as non-executable, and an executed result retains its consumed `{decisionId, dossierId, grantId}` binding. A dossier identifier is never an execution credential.
  291. ## Presence
  292. [Presence](https://presence.decionis.com), the adaptive human verification layer, supports two
  293. explicit integration levels. In DIRECT mode, the trusted executor coordinates Presence and returns
  294. the receipt reference to Decionis. In MANAGED mode, the executor asks Decionis
  295. to orchestrate Presence and polls Decionis for a terminal status. Both modes require independently
  296. signed Presence evidence, exact-intent verification, current-policy re-evaluation, and the same
  297. claim-before-handler grant path. Invitation delivery and Presence evidence are never execution
  298. authority, and approval cannot revive a five-minute intent after it expires.
  299. The gateway holds an `ESCALATE` and, with `presence.managed: true`, asks Decionis to orchestrate the ceremony; a resume through `/_agentsafe/v1/escalations/{intent_id}/resume` asks Decionis again, and only a fresh `ALLOW` with a grant executes the held request, once. [docs/authority/presence.md](./docs/authority/presence.md) says what a receipt establishes and what it does not; [`docs/human-approval.md`](./docs/human-approval.md) and [`docs/presence-evidence.md`](./docs/presence-evidence.md) are the protocol pages.
  300. See [`docs/trust-boundary.md`](./docs/trust-boundary.md) before integrating a real downstream API.
  301. ## Decision evidence
  302. Five records matter and are easy to blur in a summary: the captured intent, the verified human approval, the execution grant, the Decision Dossier, and the outcome. Only the grant authorizes anything, once; a dossier identifier is never an execution credential. [What each record establishes](#what-each-record-establishes) says so row by row.
  303. The Execution Authority architecture has two load-bearing properties. Position on the execution path creates control: nothing runs without an independent decision at the moment of action. The evidence record creates accountability that compounds: every decision adds to an auditable history of what was authorized, under which policy, on whose approval.
  304. Every Decionis evaluation is recorded as a Decision Dossier, and each `DecisionGate` returns the `decisionId` and `dossierId` of that record. Escalations attach the verified Presence `receiptDossierId`, and every executed action returns the consumed grant's `{decisionId, dossierId, grantId, intentHash}` binding, so execution results correlate to their evidence without extra bookkeeping. In the research vocabulary, dossiers compound into a Decision Chain: tamper-evident lineage linking evaluation, approval, and execution evidence across workflows. Decionis maintains that record; this repository's contribution is that execution cannot bypass it.
  305. Treat dossier identifiers as audit and support references, never as execution credentials — see [`docs/decision-dossiers.md`](./docs/decision-dossiers.md).
  306. ### What each record establishes
  307. Fluent summaries lose these distinctions first. Each row names the record or state, what it
  308. establishes, and what it does not.
  309. | Record or state | What it establishes | What it does not establish |
  310. | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  311. | Captured intent (`IntentCapture`, `intentHash`) | The exact action, target, and parameters the agent proposed, bound to trusted tenant, actor, and downstream context, hashed and expiring | That the agent's facts, identities, or amounts are true; that anything may execute |
  312. | Verified human approval (Presence `receiptDossierId`) | A named person approved that exact intent hash under the assurance the receipt records | Permission to execute: Decionis re-evaluates policy with the receipt, and only that evaluation can issue a grant |
  313. | Execution grant (`authorization` on an `ALLOW`) | Permission for one attempt at one intent, claimed once through the `AuthorizationVerifier` immediately before the handler runs | Anything after expiry, for another intent hash, or on a second presentation; a dossier identifier, an invitation link, or an earlier `ALLOW` is not a substitute |
  314. | Decision Dossier (`decisionId`, `dossierId`) | The record of why Decionis allowed, escalated, or blocked: policy snapshot, inputs, evidence, and grant metadata | An execution credential; proof that the underlying business judgement was right |
  315. | Single claim, `COMPLETED` | The grant was consumed once and the trusted handler returned a provider result | An exactly-once downstream business effect or independent confirmation of settlement; whether an observation counts as `CONFIRMED` is the authority's judgement, not this package's |
  316. | `UNKNOWN_AFTER_DISPATCH`, finalized `INDETERMINATE` | Dispatch began and completion could not be proved | Permission to repeat the side effect: reconcile through provider idempotency and read-only lookup, never by a second dispatch |
  317. | `DEFINITELY_NOT_EXECUTED`, finalized `FAILED` | Dispatch began, the provider refused it deterministically, and nothing was effected | Permission to try again: the refusal was about this attempt, and another needs a fresh decision and a fresh grant |
  318. | Gateway read-back (`EFFECT_OBSERVED`, report `effect`) | For a write whose API profile names its `effect`: what the target's own read stated after the upstream's `2xx`, against what the grant committed to; `CONFIRMED`, or `EFFECT_MISMATCH`, which the authority turns into a breach | That the platform's other records, or the business, agree; `CONFIRMED` at the authority needs an observer on its allowlist; any write the profile names no effect for holds only the upstream's acknowledgement (`PENDING`) |
  319. | Refusal observation (`REFUSAL_OBSERVATION`) | The target's version read before the decision and again after the refusal: `UNCHANGED` means no write landed on that one resource in that window, by any route | Anything about another resource, another time, or a route a later write might take; a write the profile names no read for is not observed |
  320. | Shadow observation (`ShadowPipeline`, `mode: "SHADOW"`) | What Decionis would have decided about an action that already ran: a verdict and a dossier, no grant | Enforcement, a grant, or a no-write test environment; the production write happened as before |
  321. | Library boundary (this package) | Intent capture, the gate, verification, and claim-before-handler dispatch inside the trusted integration | Host isolation, IAM, network egress, credential storage, or incident response |
  322. | Trusted executor (`createTrustedExecutor`) | What one process verifies about itself and enforces at its own door: the host posture `HostPosture` can observe, caller principals with roles and their own credentials, egress sealed to the origins `EgressPolicy` was configured with, a durable attempt journal reconciled by `StartupReconciler`, the ceilings in `HardLimits`, BEAP-vocabulary effect evidence, `HaltSwitch`, and hash-chained evidence with an offline-verifiable export | Node or kernel isolation, a CNI actually enforcing the NetworkPolicies the kit declares, an HSM or KMS, the authority's policy, or a bank's core correctness |
  323. | Executor evidence bundle (`agent-safe.evidence-bundle/1`) | What one executor process can say about an incident: both hash-chained streams as it still held them, the open attempts, the posture by check, the chain heads, a configuration digest, and every file's own digest | Origin, unless a signature over the manifest verifies against a key the reader brought; completeness, since it carries a bounded window and says how many lines it dropped; and it holds no parameter, no provider body, no secret and no digest of one |
  324. ## Verify Decision Dossiers
  325. The repository-owned [`dossiers/`](./dossiers/) corpus checks the offline verifier against synthetic
  326. `ALLOW`, `BLOCK`, and `ESCALATE` proof bundles, including an owned-workspace, execution-bound
  327. vector. Its private signing key is intentionally public so anyone can regenerate the corpus; it is
  328. not a production credential and cannot establish that a production dossier is authentic.
  329. ```bash
  330. pnpm exec decionis-verify \
  331. --file dossiers/vectors/allow.json \
  332. --jwks dossiers/corpus-jwks.json
  333. ```
  334. To verify the distinct production claim, obtain a live dossier through an authorized route and run
  335. the pinned verifier against the live JWKS without committing the dossier:
  336. ```bash
  337. npx -y @decionis/verify@0.4.0 \
  338. --file /absolute/path/to/live-decision-dossier.json \
  339. --jwks https://api.decionis.com/v1/.well-known/decision-dossier-jwks.json
  340. ```
  341. See the [corpus README](./dossiers/README.md) for regeneration, provenance, expected failures, and
  342. the trust boundary between synthetic conformance and production verification.
  343. The intent side of the same offline check is `agentsafe verify intent`: every vector under
  344. [`conformance/`](./conformance) reproduced from its bytes by the installed runtime, or the
  345. canonical bytes and hash of a binding of your own, printed to compare with another
  346. implementation's ([Agent-Safe Intent v1](./spec/intent/v1/README.md#7-conformance)):
  347. ```bash
  348. agentsafe verify intent conformance/vectors conformance/agent-safe-intent-v1.json
  349. ```
  350. Outside this repository, [`decionis/php-client`](https://packagist.org/packages/decionis/php-client)
  351. (PHP 8.1 or later, Apache-2.0) reproduces the canonical bytes and hash of every vector in the
  352. corpus, framework records included. Decionis for Drupal uses it, and any PHP code can install it
  353. with `composer require decionis/php-client`.
  354. ## Architecture
  355. ```text
  356. Untrusted Trusted control plane
  357. Agent proposal runtime identity/config
  358. | |
  359. +--------------> IntentCapture <----------+
  360. |
  361. canonical intent hash
  362. |
  363. DecionisGate
  364. / | \
  365. ALLOW ESCALATE BLOCK
  366. | | |
  367. | Presence stop
  368. | |
  369. | verified receipt
  370. | |
  371. +--- Decionis re-evaluation
  372. |
  373. single-use grant
  374. |
  375. SafeExecutor
  376. |
  377. sealed trusted ActionRegistry
  378. |
  379. downstream credential
  380. ```
  381. This repository ships the library `@decionis/agent-safe-pipeline` and, over it, the runtime
  382. `@decionis/agentsafe`, one binary with two ingresses: `agentsafe proxy`, the HTTP-interception
  383. gateway above, and `agentsafe serve`, the trusted executor for a bank boundary, with principals, a
  384. downstream credential, a verified host posture, and the [deployment kit](./deploy/README.md). Both
  385. run the same lifecycle objects; the [discovery report](./docs/architecture/distribution-discovery.md)
  386. traces one action through them and [ADR 0001](./docs/architecture/decisions/0001-http-interception-ingress.md)
  387. records why the gateway is a second ingress and not a second implementation. None of it is a
  388. hosted authorization service, an identity provider or a KMS, and no process can make a cluster
  389. enforce the network policies the kit and the chart declare; [who owns which control](./EVALUATION-PATH.md#who-owns-which-control)
  390. assigns each one.
  391. Canonical source: <https://github.com/decionis/agent-safe-pipeline>. Copies of this repository at other hosts — including sites that reverse-proxy github.com wholesale — are not maintained by Decionis, lag security fixes, and are not what the npm package, the Zenodo record, or decionis.com cite. Verify any copy against the signed release tags ([docs/release-tag-signing.md](./docs/release-tag-signing.md)).
  392. ### The library
  393. Requirements: Node.js 22.14 or later and pnpm 9.
  394. ```bash
  395. git clone https://github.com/decionis/agent-safe-pipeline.git
  396. cd agent-safe-pipeline
  397. pnpm install --frozen-lockfile
  398. pnpm --filter @decionis/agent-safe-example-basic demo
  399. ```
  400. The demos use an explicitly non-production fixture authority. A production integration uses `DecionisGate` and `DecionisGrantVerifier` with server-side credentials.
  401. ```ts
  402. const captured = intentCapture.capture(agentProposal, trustedContext);
  403. const decision = await gate.evaluate(captured);
  404. const result = await executor.run(captured, decision);
  405. ```
  406. The executor accepts a captured intent and a decision. It does not accept an arbitrary callback from the agent. A sealed `ActionRegistry` maps action names to trusted handlers and validates parameters before consuming a single-use grant.
  407. ### Optional: a signed Decision Dossier from Decionis
  408. Everything above runs locally and always will. The fixture authority evaluates in process, with no
  409. network call and no account, and that path stays supported: it is not a trial, not a reduced tier,
  410. and nothing in this repository stops working if you never do this step.
  411. What the local path cannot do is prove a decision to someone else. With one variable, every example
  412. asks Decionis to evaluate the same intent beside the fixture and ends with the thing only the
  413. authority can produce: a Decision Dossier, a signed record of what was proposed, what was decided
  414. and why, whose Ed25519 signatures verify against the authority's published keys, offline, with no
  415. account.
  416. ```bash
  417. DECIONIS_HOSTED=1 pnpm --filter @decionis/agent-safe-example-basic demo
  418. ```
  419. No key? The run mints one: a free provisional workspace from
  420. `POST https://api.decionis.com/v1/public/agents/provision`, no signup, no email, no card, with an
  421. allowance of 50 governed decisions a month, kept in `~/.config/agentsafe/credentials.json` so the
  422. next run reuses it. The first run says so on standard error:
  423. ```text
  424. decionis: provisioned a free workspace 7f0c3a5e-... (provisional, no account; 50 governed decisions a month)
  425. decionis: key stored at /home/you/.config/agentsafe/credentials.json; the next run reuses this workspace
  426. ```
  427. Then the run prints exactly what it printed before, and ends with:
  428. ```text
  429. verdict: BLOCK
  430. decionis: ALLOW (SHADOW, recorded beside the local verdict)
  431. - POLICY_AUTONOMOUS_LIMIT
  432. dossier: 6b2e5c1e-4b3a-4f0e-9c6d-2a1f7e8d9b0c
  433. verify it yourself, no account needed: pnpm decionis:verify 6b2e5c1e-4b3a-4f0e-9c6d-2a1f7e8d9b0c
  434. signed dossier: 6b2e5c1e-4b3a-4f0e-9c6d-2a1f7e8d9b0c (14211 bytes, ALLOW)
  435. Ed25519 by key decionis-dossier-2026-09 at 2026-09-18T01:02:03.000Z, 3 signed artifact(s)
  436. issuer: provisional_anonymous (a workspace without an account; claim it to keep it)
  437. ```
  438. When the authority attaches a verification page to the decision, one more line names it: a URL
  439. anyone can open, with no account, to see the signatures checked. `pnpm decionis:verify <id>`
  440. fetches the record with the stored key, resolves the public JWKS the record names, and checks
  441. every signed artifact with [`@decionis/verify`](https://www.npmjs.com/package/@decionis/verify),
  442. which uses only Node's built-in crypto; it prints each check, who minted the record, and `VERIFIED`
  443. or `NOT VERIFIED`. Add `--out dossier.json` to keep the signed record; anyone holding that file can
  444. repeat the check with the command under [Verify Decision Dossiers](#verify-decision-dossiers), with
  445. no key at all.
  446. A provisional key evaluates in `SHADOW` only: the fixture's verdict still governs execution, and the
  447. hosted decision and its dossier are recorded beside it. Every dossier it mints carries a signed
  448. `provisional_anonymous` issuer tier, so a verifier can always tell it from an owned organization's
  449. record. Claiming the workspace (the response says how) attaches a person and keeps the key and the
  450. ledger. An owned organization's key, from the Decionis console or `agentsafe login`, takes the mode
  451. you ask for, `ENFORCEMENT` included.
  452. Which examples do what: `basic-agent`, `shopify-refund-agent`, `github-deploy-agent`,
  453. `mcp-tool-gate` and `procurement-agent` evaluate their one proposal beside the fixture;
  454. `golden-adversarial-demo`, `whisper-boundary-demo`, `crm-outreach-demo`, `infra-scale-demo` and `local-escalation` run
  455. their adversarial attempts locally by design and end with the golden proposal evaluated by
  456. Decionis; `changed-conditions-demo` runs against the loopback double alone, because what it changes
  457. (policy releases, published signals) is the authority's own state; `trusted-executor` runs the
  458. executor process once more in shadow against Decionis; the two Presence examples need an owned organization with an enrolled approver, and say so when given
  459. a provisional workspace; `staged-change-demo` runs against the loopback authority only, because a
  460. hosted plan step needs its plan registered with Decionis first; `acceptance-demo` runs against the
  461. loopback authority only, because what it proves is the tool, and a hosted deployment proves itself
  462. with its own run.
  463. #### How it is wired
  464. `createHostedGate` in [`packages/pipeline`](./packages/pipeline/README.md#one-variable-a-key-issued-in-the-run)
  465. reads the environment and returns the authority and verifier the example runs:
  466. | Variable | Default | Effect |
  467. | --------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  468. | `DECIONIS_HOSTED` | unset | `1`: with no key, the stored credential, else a free provisional workspace minted in the run and stored for the next; the hosted evaluation runs in `SHADOW`. |
  469. | `DECIONIS_API_KEY` | unset | Unset: the fixture pair, the same objects as before, and no client is built. Set: `DecionisGate` runs beside the fixture, whatever `DECIONIS_HOSTED` says. |
  470. | `DECIONIS_TENANT_ID` | required with the key | The key's organization. Decionis binds every intent to it, so the examples capture under it instead of their synthetic tenant. |
  471. | `DECIONIS_MODE` | `SHADOW` | `SHADOW`: the fixture's verdict still governs execution; the hosted verdict and dossier are recorded. `ENFORCEMENT`: the hosted decision governs and its grant is claimed with Decionis; the fixture can only tighten it. |
  472. | `DECIONIS_API_URL` | `https://api.decionis.com` | HTTPS only, for staging or a loopback double with `DECIONIS_ALLOW_INSECURE_LOOPBACK=true`. |
  473. | `DECIONIS_TIMEOUT_MS` | `4000` | Budget for the hosted call. A call past it is recorded as fail-closed. |
  474. Hosted mode fails closed. A timeout, a network error, a non-2xx response, a body that is not the
  475. contract's decision, a verdict the contract does not define, a decision about another intent, or an
  476. intent that expired before evaluation is recorded as `BLOCK` from the hosted side, with no grant. In
  477. `SHADOW` that is recorded and the fixture's verdict still governs, so setting a key cannot change what
  478. a working fork does; in `ENFORCEMENT` it blocks, as the threat model requires. Neither mode is ever
  479. less restrictive than the fixture alone; the matrix is asserted in
  480. [`ShadowGate.test.ts`](./packages/pipeline/test/decision/ShadowGate.test.ts) and every failure mode in
  481. [`FailClosed.test.ts`](./packages/pipeline/test/decision/FailClosed.test.ts).
  482. Only the captured intent leaves your process: the action, target and parameters the agent proposed,
  483. and the tenant, actor, downstream target, expiry and context the trusted configuration supplied. It
  484. is the same `ExecutionIntentBinding` the intent hash covers, and nothing else; credentials live behind
  485. the executor and are never part of an intent. The request body is pinned field by field in
  486. [`FailClosed.test.ts`](./packages/pipeline/test/decision/FailClosed.test.ts).
  487. Beside it, every hosted call carries a `User-Agent` naming this package and its version, and from
  488. the examples the upstream repository slug and the example name, so Decionis can count which example
  489. a key was first used from. That is the whole of it: the header is sent only when a key is set, it
  490. is not decision input and does not enter the dossier, and an integration that passes no `source`
  491. sends the package name and version alone.
  492. To go back: delete the key. That is the whole rollback.
  493. ### From the fixture to Decionis
  494. The package is used in three stages. Each stage uses the same `IntentCapture`, `ActionRegistry`, and handler code, so nothing is rewritten between them.
  495. | Stage | Authority | What it proves |
  496. | ----------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
  497. | Development | `createFixtureAuthorityPair` (refuses `NODE_ENV=production`) | The intent, registry, and executor wiring is correct |
  498. | Shadow | `ShadowPipeline` over `DecionisGate` with `mode: "SHADOW"` | What Decionis would have decided about actions that already run; no grant is ever issued |
  499. | Enforcement | `DecionisGate` plus `DecionisGrantVerifier` in `SafeExecutor` | Nothing runs without an independent decision and a consumed single-use grant |
  500. Decionis credentials belong only in the trusted executor process, never in the agent runtime:
  501. ```text
  502. DECIONIS_API_URL=https://api.decionis.com
  503. DECIONIS_API_KEY=server-side-secret
  504. ```
  505. See the [package README](./packages/pipeline/README.md) for the complete enforcement example and [`docs/shadow-mode.md`](./docs/shadow-mode.md) for the shadow rollout path. To move an example between the stages with configuration alone, see [Optional: a signed Decision Dossier from Decionis](#optional-a-signed-decision-dossier-from-decionis).
  506. To run the boundary as its own service rather than in-process, [`packages/agentsafe`](./packages/agentsafe) is the executor as a process: `@decionis/agentsafe`, a listener in front of the same components with a seam for your handlers. [`examples/trusted-executor`](./examples/trusted-executor) is its proof over real HTTP against the loopback doubles and the template an adopter starts from. [`deploy/`](./deploy) is its image, the Kubernetes manifests for the two zones with every credential referenced and never written, and the runbook from shadow to enforcement.
  507. ## Research and specifications
  508. Decionis Research defines the Execution Authority architecture, this repository demonstrates it as runnable, tested code, and the Decionis platform operates it as a hosted authority. The provenance chain is research paper -> protocol contract -> reference implementation (this repository) -> production service.
  509. Published research:
  510. - Jejelowo, Festus. "The Execution Verifiability Gap: Why Model Governance Cannot Authorize Consequential Actions." Decionis Research, version 1.0, 21 August 2026. [Canonical article](https://decionis.com/research/execution-verifiability-gap) · [Archival PDF](https://decionis.com/research/execution-verifiability-gap-v1.0.pdf) · [Research index](https://decionis.com/research).
  511. Profiles of the protocol: the [Banking Execution Authority Profile (BEAP)](https://banking.decionis.com) applies this architecture to a bank's disbursement, payment run, or limit increase — execution domains, the canonical banking instruction, batch binding, multi-party sign-offs, effect evidence — and its reference runtime builds on `@decionis/agent-safe-pipeline`. BEAP v1.0 was published on 2026-09-15: the profile Decionis publishes and implements, not a standard approved by any body; the 0.1 draft is frozen and mirrored under `profiles/beap/v0.1`. Half of its runtime is here and half is not: the profile's section 24.5 names `@decionis/agentsafe` as the reference Trusted Executor, the executor-side subset it implements is listed in [docs/beap-conformance.md](./docs/beap-conformance.md), and the authority-side half — policy, grants, dossiers, the L1 and L2 requirements — is not in this repository and is not claimed by it. Being named a reference is not a conformance claim, and none is made: the executor implements the 1.0 identifiers, moved together with the profile's other runtimes.
  512. Proof-of-human infrastructure: the [proof-of-human infrastructure page](https://decionis.com/proof-of-human-infrastructure) on the platform site says what the human-authority layer is — a verified, present person on their own device, bound to one exact action, sealed in a signed Presence Record the authority re-checks before commit — and the [Presence property](https://presence.decionis.com) is where it runs; this repository's `PresenceApprovalCoordinator` and the `examples/local-escalation`, `examples/presence-live-approval` and `examples/presence-managed-approval` examples are the reference for resolving an ESCALATE with it. Production enforcement is sales-assisted; the loopback double simulates the ceremony and proves nothing about a real one.
  513. The execution intent itself is published as [Agent-Safe Intent v1](./spec/intent/v1/README.md) (`agent-safe.intent/1`): the binding, its canonical form and hash, the requirement that every single-field change is another intent, conformance against the vectors under [`conformance/`](./conformance), a JSON Schema generated from the reference implementation, a [changelog](./spec/intent/v1/CHANGELOG.md), and the change process. It is the profile Decionis publishes and implements, not a standard approved by any body. `agentsafe verify intent <file|dir>` runs the corpus offline, or prints the bytes and hash of a binding of your own to compare; [`spec/intent/v1/frameworks.md`](./spec/intent/v1/frameworks.md) says what the OpenAI Responses API and Agents SDK, the Vercel AI SDK and LangChain tool-call records carry of a binding and what the adapter adds, from vectors the reference test reproduces.
  514. Companion notes on the Execution Authority model, the authorization protocol, Presence-verified human approval, and Decision Dossiers are in preparation. Following this repository's discovery rules, a publication link is added here only after its canonical article resolves publicly.
  515. | Research concept | Implementation in this repository |
  516. | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  517. | Execution Authority boundary | `IntentCapture` -> `DecionisGate` -> `SafeExecutor` |
  518. | Protocol contract | Exactly the Decionis `ExecutionAuthorityRequest` and `ExecutionIntentBinding` contract on the wire; `DecionisGate` and `DecionisGrantVerifier` claim and finalize against the published OpenAPI |
  519. | Intent integrity | [Agent-Safe Intent v1](./spec/intent/v1/README.md): `CanonicalIntentHasher`, the [`conformance/`](./conformance) hash vectors, the published [schema](./spec/intent/v1/schema.json), and `agentsafe verify intent` offline |
  520. | Human approval evidence | DIRECT `PresenceApprovalCoordinator` or MANAGED `DecionisGate` polling; both require Presence receipt verification and Decionis re-evaluation |
  521. | Trusted execution | Sealed `ActionRegistry` and atomic single-use grant consumption in `SafeExecutor` |
  522. | Decision evidence | `decisionId` and `dossierId` on every gate decision; executed results retain the consumed-grant binding |
  523. | Failure semantics | Fail-closed production invariants and [`THREAT-MODEL.md`](./THREAT-MODEL.md) |
  524. | Observation without authority | `ShadowPipeline` over a `SHADOW`-mode gate: failure-isolated, bounded, grant-free, and rejected by `SafeExecutor`; see [`docs/shadow-mode.md`](./docs/shadow-mode.md) |
  525. | MCP governance | [`examples/mcp-tool-gate`](./examples/mcp-tool-gate) |
  526. | Operational patterns | [`examples/shopify-refund-agent`](./examples/shopify-refund-agent), [`examples/github-deploy-agent`](./examples/github-deploy-agent), [`examples/procurement-agent`](./examples/procurement-agent) |
  527. ## Repository map
  528. - [`packages/pipeline`](./packages/pipeline) — `IntentCapture`, `DecionisGate`, Presence coordination, and `SafeExecutor`.
  529. - [`packages/agentsafe`](./packages/agentsafe) — `@decionis/agentsafe`, the trusted executor as one deployable process: the HTTP listener, the configuration, escalation resolution, and the handler seam in front of `packages/pipeline`, with its own image.
  530. - [`packages/mcp`](./packages/mcp) — released-source index for `@decionis/commerce`, the Commerce Gate MCP client. Commerce owns ongoing development; this index preserves access to the published runtime and its Apache-2.0 source history.
  531. - [`packages/mcp/extension/claude`](./packages/mcp/extension/claude) — released-source index for the MIT-licensed Claude Desktop wrapper. Its published MCPB retains the separate Apache-2.0 Commerce Gate runtime, license and notice; Commerce owns future packaging work.
  532. - [`examples/golden-adversarial-demo`](./examples/golden-adversarial-demo) — the self-checking proof: one golden path, eight attacks, zero unauthorized executions.
  533. - [`examples/whisper-boundary-demo`](./examples/whisper-boundary-demo) — the same proof for a shopping agent: merchant-text steering, a cross-session credential lookup, a cart changed after signing, constraints lost in context compaction, and principal loss across a delegation hop — six attacks, zero unauthorized effects.
  534. - [`examples/crm-outreach-demo`](./examples/crm-outreach-demo) — the same proof for a sales-development agent: who can approve a CRM update or an outbound message, a recipient changed after approval, an off-template message, an opted-out contact, an expired approval, and a provider response lost after dispatch that is reconciled once and never re-sent — six attacks, zero unauthorized effects.
  535. - [`examples/infra-scale-demo`](./examples/infra-scale-demo) — the Compromised Principal Test: an infrastructure agent whose identity, credential and API are all valid proposes a `deployment.scale` it is not authorised for — 960 replicas, another service, another cluster, a post-authorization mutation, a swapped approval, a replayed grant, a direct call to the cluster — seven attacks, zero unauthorized effects.
  536. - [`examples/changed-conditions-demo`](./examples/changed-conditions-demo) — the Changed Conditions Test: an honest deploy agent's queued work meets a world that changed — a configuration at the same path, a grown target group, an allowance another rollout took, a withdrawn approval, a policy release, a reclassified security group, an allowance published after the commit rather than with it, a partner bank's mandate that lapses or whose key is revoked — twenty-four attempts refused, sixteen legitimate counterparts completed exactly once.
  537. - [`examples/staged-change-demo`](./examples/staged-change-demo) — one production change as a governed plan: open, drain, deploy, re-enable, each step decided and granted on its own with plan facts the authority derives from its finalization records; a deploy refused before the drain commits, a re-enable escalated after a failed deploy, a rollback under its own grant, and the plan ending `PARTIAL`.
  538. - [`examples/acceptance-demo`](./examples/acceptance-demo) — the real `agentsafe accept`, `identity` and `verify acceptance` against a gateway on loopback: the gateway signs `ACCEPTED` when the permitted write lands once, the prohibited one is refused and its canary read unchanged, and the outage case sends nothing on; and `NOT_ACCEPTED` when the agent's zone reaches its origin directly ([accept a deployment](./docs/deployment/acceptance.md)).
  539. - [`examples/basic-agent`](./examples/basic-agent) — the smallest BLOCK flow.
  540. - [`examples/shopify-refund-agent`](./examples/shopify-refund-agent) — amount-based ALLOW / ESCALATE / BLOCK.
  541. - [`examples/github-deploy-agent`](./examples/github-deploy-agent) — environment and force-push controls.
  542. - [`examples/procurement-agent`](./examples/procurement-agent) — an in-budget software request held when existing tools still have user capacity.
  543. - [`examples/mcp-tool-gate`](./examples/mcp-tool-gate) — a real stdio MCP server with a governed tool.
  544. - [`examples/presence-live-approval`](./examples/presence-live-approval) — a Presence-bound enforcement against the real services with a FIDO2 or FIDO2-plus-liveness ceremony; needs real credentials.
  545. - [`examples/presence-managed-approval`](./examples/presence-managed-approval) — Decionis-managed Presence orchestration with Decionis-only polling and no Presence credential in the executor.
  546. - [`examples/local-escalation`](./examples/local-escalation) — both Presence integration modes against loopback Decionis and Presence doubles, no credentials, ceremony simulated.
  547. - [`examples/trusted-executor`](./examples/trusted-executor) — the proof of `@decionis/agentsafe` over real HTTP against the loopback doubles, and the template an adopter starts from: the handler seam and a process of a few lines.
  548. - [`govern/`](./govern) — Govern, the gate for workflows: one Go binary for GitHub Actions, GitLab CI, Jenkins and any other runner that captures a step as an execution intent, asks Decionis through `enforce-and-bind`, runs the command only on a claimed grant, and finalizes the outcome into the Decision Dossier; the `decionis/govern` action's source since 2026-09-21 (v2; v1 was the node20 action on the evaluate-decision API); [`docs/govern.md`](./docs/govern.md) is the page.
  549. - [`deploy/`](./deploy) — the deployment kit: the executor image, conformance-tested Kubernetes manifests for the agent zone and the executor zone with Secrets referenced and never written, and the runbook from shadow to enforcement.
  550. - [`ARCHITECTURE.md`](./ARCHITECTURE.md) and [`THREAT-MODEL.md`](./THREAT-MODEL.md) — trust boundary and abuse analysis.
  551. - [`OPEN-CORE.md`](./OPEN-CORE.md) — what is Apache-2.0 here, what Decionis operates, and the seam between them.
  552. - [`docs/`](./docs) — concepts, execution intent, [the Compromised Principal Test](./docs/compromised-principal-test.md), outcomes, human approval, [Presence Evidence semantics](./docs/presence-evidence.md), the [remote CRO sequence](./docs/remote-cro-authorization.md), shadow mode, Decision Dossiers, trust boundary, the [executor's chained evidence](./docs/executor-evidence.md), [what the executor implements of the BEAP v0.1 banking profile](./docs/beap-conformance.md), [incident response for the executor](./docs/incident-response.md), [where a bypass of the executor is actually stopped](./docs/bypass-resistance.md), and assurance notes.
  553. - [`spec/intent/v1`](./spec/intent/v1) — Agent-Safe Intent v1: the specification, the JSON Schema generated from the reference implementation, the changelog, and the framework coverage matrix.
  554. - [`conformance/agent-safe-intent-v1.json`](./conformance/agent-safe-intent-v1.json) — portable canonical-hash test vector.
  555. - [`conformance/vectors/`](./conformance/vectors/) — edge-case canonical-hash vectors (Unicode/astral, NFC vs NFD, negative zero, fractional/exponent numbers, nested arrays, UTF-16 key sort order) and the Compromised Principal Test as a vector (one intent, eight single-field mutations, nine distinct hashes), auto-discovered by the conformance test.
  556. - [`conformance/frameworks/`](./conformance/frameworks/) — the same refund proposal as an OpenAI `function_call` item, a Vercel AI SDK `tool-call` part and a LangChain `ToolCall`, each with the proposal, the trusted context, the binding, the hash, and a coverage row over the eight producer capabilities.
  557. - [`dossiers/`](./dossiers/) — reproducible synthetic Decision Dossier corpus with canonical bytes, SHA-256 digests, Ed25519 signatures, and a deliberately published corpus key.
  558. - [`tests/integration/contract/`](./tests/integration/contract/) — loopback Decionis and Presence stubs that exercise the packed package's complete wire contract over real HTTP.
  559. - [`FIXTURE-PROVENANCE.md`](./FIXTURE-PROVENANCE.md) — origin and permitted use of every fixture family.
  560. - [`profiles/beap/v1.0`](./profiles/beap/v1.0) and [`profiles/beap/v0.1`](./profiles/beap/v0.1) — the Banking Execution Authority Profile, mirrored byte for byte from its own repository by that repository's sync script: 1.0, the version this executor implements, and the frozen 0.1 draft, staged here for archival under this repository's concept DOI.
  561. - [`DEPENDENCY-LICENSES.md`](./DEPENDENCY-LICENSES.md) — generated inventory method and platform-conditional dependency notes.
  562. - [`SECURITY-EVIDENCE.md`](./SECURITY-EVIDENCE.md) — control-to-artifact evidence map and published gaps.
  563. - [`PUBLICATION-SIGNOFFS.md`](./PUBLICATION-SIGNOFFS.md) — human decisions that automation cannot make.
  564. ## Installing the Decionis CLI
  565. This repository is also the public distribution home of the `decionis` command-line tool: its
  566. [GitHub releases](https://github.com/decionis/agent-safe-pipeline/releases) carry every release's
  567. npm tarball, Debian and RPM packages, Windows archive and registry manifests, and the two
  568. manifests below are what package managers read. The CLI itself is not part of this repository's
  569. Apache-2.0 source; `formula/` and `apps/` hold metadata only.
  570. - **npm**: `npm install -g decionis`
  571. - **Homebrew**: `brew tap decionis/agent-safe https://github.com/decionis/agent-safe-pipeline`
  572. then `brew install decionis` ([`Formula/decionis.rb`](./Formula/decionis.rb) fetches the npm
  573. tarball and pins its SHA-256)
  574. - **Decionis app install**: `app install decionis` reads [`apps/decionis.json`](./apps/decionis.json)
  575. - **Windows**: the WinGet manifest `Decionis.CLI` points at each release's
  576. `decionis-windows-x64-<version>.zip` here; until the manifest is accepted into winget-pkgs,
  577. download the archive from the release and add `decionis\bin` to `PATH`
  578. ## Open core
  579. The architecture, intent contract, execution boundary, client adapters, audit contract, shadow mode, conformance vectors and examples are Apache-2.0. The released Commerce Gate runtime and Claude Desktop wrapper retain their Apache-2.0 and MIT licenses in the source history linked from the [runtime index](./packages/mcp/README.md) and [wrapper index](./packages/mcp/extension/claude/README.md). Commerce owns their ongoing development. Decionis operates the policy control plane behind `DecionisGate`: policy evaluation, grant issuance and atomic consumption, Decision Dossier signing and retention, and Presence. The seam is two exported interfaces, `DecisionAuthority` and `AuthorizationVerifier`, plus a published OpenAPI contract; the library checks no plan, key, or entitlement. [`OPEN-CORE.md`](./OPEN-CORE.md) states the boundary and the commitments that keep it stable.
  580. ## Public-repository policy
  581. This is intended to be the public, canonical reference implementation. It should not be mirrored: mirrors create contract and security-fix drift. Public content belongs here—architecture, package source, synthetic policies, and runnable examples. Production policy bundles, customer data, credentials, internal infrastructure, and private incident material do not.
  582. Decionis remains the authoritative decision service, Presence remains the human-verification service, and their server internals can evolve independently behind versioned contracts.
  583. ## Start here
  584. [ONBOARDING.md](./ONBOARDING.md) is the adopter's journey — install, capture, verdict, approval,
  585. grant, execute once, outcome, evidence — walked for five families: AI agent, commerce, banking, proof of human,
  586. and autonomous workflows, each pointing at the example that runs it and the property that owns it.
  587. ## Evaluating this repository
  588. [EVALUATION-PATH.md](./EVALUATION-PATH.md) is the reviewer's route: which artefact you are looking
  589. at, who owns which control, what each piece of evidence establishes and what it does not, and what
  590. to run in what order.
  591. ## Status
  592. The package is published as [`@decionis/agent-safe-pipeline`](https://www.npmjs.com/package/@decionis/agent-safe-pipeline). Install the latest stable release with `npm install @decionis/agent-safe-pipeline`; prereleases publish under the `next` dist-tag and require an explicit request such as `npm install @decionis/agent-safe-pipeline@next`.
  593. Archived releases are citable under [Zenodo concept DOI
  594. `10.5281/zenodo.22312955`](https://doi.org/10.5281/zenodo.22312955). The
  595. [release-metadata contract](./docs/zenodo-release-metadata.md) explains the
  596. preflight checks, version-DOI verification, and human publication boundary.
  597. ## Development
  598. ```bash
  599. pnpm install --frozen-lockfile
  600. pnpm verify
  601. ```
  602. `pnpm verify` enforces formatting, Markdown lint, fixture conventions, canonical licensing, separate
  603. production/toolchain audits, deterministic performance tests, types, tests, and coverage thresholds
  604. of 90% for lines/functions/statements and 85% for branches. `pnpm mutation` checks that
  605. trust-boundary tests kill deliberate code mutations. `pnpm fuzz` runs deterministic property tests
  606. against canonical intent handling; CI also runs them weekly with a larger bounded sample.
  607. Installation activates the repository's `simple-git-hooks` pre-commit guardrails.
  608. ### Testing escalations locally
  609. `@decionis/agent-safe-pipeline/testing` ships `LocalPresence` and `LocalAuthority`, loopback doubles
  610. that the production clients talk to unchanged. They enforce the structural intent-hash binding,
  611. verify receipts the way Decionis does, issue single-use grants, orchestrate managed escalations, and
  612. record finalization. The person's ceremony is a method call or a local control route. See
  613. [`docs/local-testing.md`](./docs/local-testing.md) and [`examples/local-escalation`](./examples/local-escalation).
  614. ### Fixture provenance and loopback origins
  615. Every fixture-bearing file is listed in [`fixtures/manifest.json`](./fixtures/manifest.json) and
  616. checked by `pnpm fixture:check`: the unit tests under `packages/pipeline/test`, example sources,
  617. conformance vectors, the dossier corpus, synthetic policies, and the integration harness under
  618. `tests/integration`. The gate requires synthetic identities (`synthetic-` or `fixture_` prefixes,
  619. tenants in the reserved UUID block) and parses every URL-shaped literal it finds, which must resolve
  620. to `localhost`, `127.0.0.1`, `example.com`, or a `.example` or `.invalid` domain. Nothing in the
  621. tests, examples, or harness reaches the network beyond loopback.
  622. Two consequences matter when you add or evaluate tests:
  623. - Loopback stubs bind to `127.0.0.1` on an ephemeral port and build their base URL from a plain
  624. string constant, `const LOOPBACK_ORIGIN = "http://127.0.0.1"`, appending the port separately. A
  625. template literal that interpolates inside the URL, such as `` `http://127.0.0.1:${port}` ``, is
  626. read by the gate as literal text and rejected as an invalid URL. That is deliberate: the gate does
  627. not guess what an interpolated host would resolve to.
  628. - A new fixture-bearing file needs its manifest entry in the same change. Discovery uses
  629. `git ls-files`, so an untracked file is invisible to the gate until it is staged, and the manifest
  630. and discovery must match exactly.
  631. See [`FIXTURE-PROVENANCE.md`](./FIXTURE-PROVENANCE.md) for the full construction rules and
  632. [`tests/integration/contract/`](./tests/integration/contract/) for the loopback harness that
  633. follows them.
  634. ## Contributing, support and license
  635. [`CONTRIBUTING.md`](./CONTRIBUTING.md) is how a change lands: `pnpm verify` before a pull request,
  636. the coding, security and discovery rules beside it, and the bot that opens pull requests for
  637. branches. Questions and bug reports are [GitHub issues](https://github.com/decionis/agent-safe-pipeline/issues);
  638. the runtime's first governed action, not a star, is the number this repository is measured by, and
  639. [docs/reference/telemetry.md](./docs/reference/telemetry.md) says exactly what the runtime records
  640. about that and what it never sends.
  641. The AgentSafe workspace is Apache-2.0 licensed. Historical Commerce Gate releases retain the licenses linked from their [runtime](./packages/mcp/README.md) and [wrapper](./packages/mcp/extension/claude/README.md) indexes. See [`LICENSE`](./LICENSE), [`OPEN-CORE.md`](./OPEN-CORE.md), [`TRADEMARKS.md`](./TRADEMARKS.md), [`SECURITY.md`](./SECURITY.md), and [`CONTRIBUTING.md`](./CONTRIBUTING.md). Report suspected vulnerabilities through [GitHub's private advisory form](https://github.com/decionis/agent-safe-pipeline/security/advisories/new), not a public issue.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.