Skip to content

Explain mapper failures before a guarded dispatch receipt #321

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
aruintelligence merged 2 commits into from
Oct 13, 2026
Merged

Explain mapper failures before a guarded dispatch receipt #321

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7290a67
Explain host mapper preflight errors (1/2)
aruintelligence Oct 13, 2026
1ef2077
Explain host mapper preflight errors (2/2)
aruintelligence Oct 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/AGENT_TOOL_QUICKSTART.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ const execute = createGuardedToolExecute({
// It returns { protocol, plan, receipt, result? }.
```

`requestApproval` must return `{ approved: true, proposal_sha256 }` for the exact frozen proposal, or refuse, and identify a host-issued one-use grant. The `consumeApproval` hook must atomically claim that grant, bound to the digest, and return exactly `true` once. The placeholder above throws, so a copied sketch cannot dispatch until the host implements the claim. The approval callback may be omitted for a policy rule that allows an action without approval. If an approval-required rule has no callback, dispatch blocks. The adapter passes the framework's second `execute` argument as `context` to the host callbacks, and calls the tool with the frozen canonical arguments. A host mapping error throws before any tool invocation.
`requestApproval` must return `{ approved: true, proposal_sha256 }` for the exact frozen proposal, or refuse, and identify a host-issued one-use grant. The `consumeApproval` hook must atomically claim that grant, bound to the digest, and return exactly `true` once. The placeholder above throws, so a copied sketch cannot dispatch until the host implements the claim. The approval callback may be omitted for a policy rule that allows an action without approval. If an approval-required rule has no callback, dispatch blocks. The adapter passes the framework's second `execute` argument as `context` to the host callbacks, and calls the tool with the frozen canonical arguments. A host mapping error throws before an action plan or dispatch receipt exists and before any tool invocation. Handle it in the host error path rather than fabricating a blocked receipt.

The adapter captures the tool arguments once before calling `resourceFor`. Keep that host mapper synchronous and read-only: it receives a snapshot, and a mutation throws before approval or dispatch. The policy resource and provider callback must describe the same destination. If your provider callback adds recipients or rewrites a request, use the prepared request adapters below so the complete provider request is checked before dispatch.

Expand Down
4 changes: 2 additions & 2 deletions docs/agent-start.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@
<style>
:root{color-scheme:dark;--bg:#07111f;--ink:#f2f8fb;--muted:#b9cad4;--cyan:#83edec;--gold:#f5cc7e;--rose:#ff9eb2;--line:#355269;font:16px/1.55 ui-sans-serif,system-ui,-apple-system,"Segoe UI",sans-serif}*{box-sizing:border-box}html{scroll-behavior:smooth}body{margin:0;color:var(--ink);background:radial-gradient(circle at 83% 4%,#18424c,transparent 37rem),radial-gradient(circle at 0 47%,#172b45,transparent 35rem),var(--bg)}a{color:var(--cyan)}button{font:inherit;cursor:pointer}button:focus-visible,a:focus-visible{outline:3px solid var(--gold);outline-offset:3px}.wrap{width:min(1130px,calc(100% - 36px));margin:auto}.top{display:flex;justify-content:space-between;align-items:center;gap:16px;padding:22px 0;border-bottom:1px solid #ffffff24}.brand{font-weight:950;letter-spacing:.13em;color:var(--ink);text-decoration:none}.top nav{display:flex;gap:18px;flex-wrap:wrap}.top nav a{font-weight:800;font-size:.85rem;text-decoration:none;color:var(--muted)}.top nav a:hover{color:var(--cyan)}
h1,h2,h3{letter-spacing:-.04em;line-height:1.08}.hero{padding:clamp(52px,8vw,97px) 0 55px;display:grid;grid-template-columns:minmax(0,1.3fr) minmax(270px,.7fr);gap:30px;align-items:end}.eyebrow{font:800 .73rem ui-monospace,monospace;letter-spacing:.15em;color:var(--cyan)}h1{font-size:clamp(3.1rem,7.4vw,6.7rem);margin:15px 0 20px}h1 em{font-style:normal;color:var(--cyan)}.lead{color:#d2e1e9;font-size:1.16rem;max-width:720px;margin:0}.jump{display:inline-flex;margin-top:28px;padding:12px 19px;border-radius:999px;background:var(--cyan);color:#081723;text-decoration:none;font-weight:900}.case{border:1px solid #527682;border-radius:20px;padding:23px;background:radial-gradient(circle at 70% 0,#1c64726b,transparent 70%),#0b1d2c;box-shadow:0 20px 65px #0005}.case small{font:800 .7rem ui-monospace,monospace;letter-spacing:.13em;color:var(--gold)}.case strong{display:block;font:850 1.27rem/1.3 ui-monospace,monospace;overflow-wrap:anywhere;margin:18px 0;color:var(--ink)}.case p{color:var(--muted);margin:0 0 16px}.case a{font-weight:800;font-size:.85rem}
.flow{border:1px solid #517582;border-radius:25px;overflow:hidden;background:linear-gradient(130deg,#102536,#0a1525);box-shadow:0 26px 90px #0007}.bar{display:flex;justify-content:space-between;gap:12px;align-items:center;padding:17px 23px;border-bottom:1px solid var(--line);font:.74rem ui-monospace,monospace;letter-spacing:.13em;color:#c8dce5}.dots{display:flex;gap:7px}.dots i{width:8px;height:8px;background:#587586;border-radius:50%}.dots i:first-child{background:var(--cyan)}.stage{display:grid;grid-template-columns:94px minmax(0,1fr);border-bottom:1px solid var(--line)}.stage:last-child{border-bottom:0}.number{font:900 1.65rem ui-monospace,monospace;color:var(--cyan);padding:30px;border-right:1px solid var(--line);background:#061320}.content{padding:29px clamp(20px,4vw,46px)}.content h2{font-size:clamp(1.5rem,3vw,2.15rem);margin:0 0 11px}.content>p{color:var(--muted);max-width:780px;margin:0 0 18px}.code-row{display:flex;justify-content:space-between;align-items:center;gap:18px;flex-wrap:wrap}.copy{border:1px solid var(--cyan);background:#123745;color:var(--cyan);font-weight:850;padding:9px 14px;border-radius:9px}.copy:hover{background:#1d5464}.code{display:block;white-space:pre;overflow:auto;padding:19px;border:1px solid var(--line);border-radius:12px;background:#020b16;color:#dcf4f4;font:12px/1.7 ui-monospace,SFMono-Regular,monospace;margin:16px 0 11px}.small{color:var(--muted);font-size:.83rem}.small strong{color:var(--ink)}.outcomes{display:grid;grid-template-columns:1fr 1fr;gap:12px;margin:20px 0 0}.outcome{border:1px solid var(--line);border-radius:12px;padding:16px;background:#ffffff08}.outcome b{display:block;font:.73rem ui-monospace,monospace;letter-spacing:.09em;color:var(--gold)}.outcome strong{display:block;margin:8px 0;color:var(--ink);font-size:1.13rem}.outcome p{margin:0;color:var(--muted);font-size:.82rem}.sketch{max-height:500px}.status{min-height:1.3em;color:var(--gold);font-size:.81rem;margin:8px 0 0}.links{display:flex;flex-wrap:wrap;gap:12px 20px;margin-top:20px}.links a{font-weight:800}.notice{border-left:3px solid var(--gold);padding:14px 18px;background:#f5cc7e10;color:#e1d7bf;border-radius:0 11px 11px 0;max-width:780px}.next{display:grid;grid-template-columns:repeat(3,1fr);gap:15px;margin:50px 0 75px}.next a{padding:22px;border:1px solid var(--line);border-radius:16px;background:#ffffff08;text-decoration:none}.next a:hover{border-color:var(--cyan)}.next span{display:block;color:var(--gold);font:.72rem ui-monospace,monospace;letter-spacing:.1em}.next b{display:block;color:var(--ink);font-size:1.15rem;margin:11px 0 7px}.next small{color:var(--muted);font-size:.84rem}.foot{border-top:1px solid var(--line);color:var(--muted);padding:25px 0 50px;font-size:.84rem}.foot strong{color:var(--ink)}
.flow{border:1px solid #517582;border-radius:25px;overflow:hidden;background:linear-gradient(130deg,#102536,#0a1525);box-shadow:0 26px 90px #0007}.bar{display:flex;justify-content:space-between;gap:12px;align-items:center;padding:17px 23px;border-bottom:1px solid var(--line);font:.74rem ui-monospace,monospace;letter-spacing:.13em;color:#c8dce5}.dots{display:flex;gap:7px}.dots i{width:8px;height:8px;background:#587586;border-radius:50%}.dots i:first-child{background:var(--cyan)}.stage{display:grid;grid-template-columns:94px minmax(0,1fr);border-bottom:1px solid var(--line)}.stage:last-child{border-bottom:0}.number{font:900 1.65rem ui-monospace,monospace;color:var(--cyan);padding:30px;border-right:1px solid var(--line);background:#061320}.content{padding:29px clamp(20px,4vw,46px)}.content h2{font-size:clamp(1.5rem,3vw,2.15rem);margin:0 0 11px}.content>p{color:var(--muted);max-width:780px;margin:0 0 18px}.code-row{display:flex;justify-content:space-between;align-items:center;gap:18px;flex-wrap:wrap}.copy{border:1px solid var(--cyan);background:#123745;color:var(--cyan);font-weight:850;padding:9px 14px;border-radius:9px}.copy:hover{background:#1d5464}.code{display:block;white-space:pre;overflow:auto;padding:19px;border:1px solid var(--line);border-radius:12px;background:#020b16;color:#dcf4f4;font:12px/1.7 ui-monospace,SFMono-Regular,monospace;margin:16px 0 11px}.small{color:var(--muted);font-size:.83rem}.small strong{color:var(--ink)}.outcomes{display:grid;grid-template-columns:1fr 1fr;gap:12px;margin:20px 0 0}.outcome{border:1px solid var(--line);border-radius:12px;padding:16px;background:#ffffff08}.outcome b{display:block;font:.73rem ui-monospace,monospace;letter-spacing:.09em;color:var(--gold)}.outcome strong{display:block;margin:8px 0;color:var(--ink);font-size:1.13rem}.outcome p{margin:0;color:var(--muted);font-size:.82rem}.sketch{max-height:500px}.status{min-height:1.3em;color:var(--gold);font-size:.81rem;margin:8px 0 0}.links{display:flex;flex-wrap:wrap;gap:12px 20px;margin-top:20px}.links a{font-weight:800}.preflight{margin-top:18px;padding:14px 16px;border:1px solid #416779;border-radius:12px;background:#83edec0b;color:#d9e9ef;font-size:.82rem}.preflight strong{color:var(--cyan)}.notice{border-left:3px solid var(--gold);padding:14px 18px;background:#f5cc7e10;color:#e1d7bf;border-radius:0 11px 11px 0;max-width:780px}.next{display:grid;grid-template-columns:repeat(3,1fr);gap:15px;margin:50px 0 75px}.next a{padding:22px;border:1px solid var(--line);border-radius:16px;background:#ffffff08;text-decoration:none}.next a:hover{border-color:var(--cyan)}.next span{display:block;color:var(--gold);font:.72rem ui-monospace,monospace;letter-spacing:.1em}.next b{display:block;color:var(--ink);font-size:1.15rem;margin:11px 0 7px}.next small{color:var(--muted);font-size:.84rem}.foot{border-top:1px solid var(--line);color:var(--muted);padding:25px 0 50px;font-size:.84rem}.foot strong{color:var(--ink)}
.rehearsal{margin-top:27px;border:1px solid #557988;border-radius:19px;overflow:hidden;background:#071522}.rehearsal-head{display:flex;justify-content:space-between;gap:14px;align-items:start;flex-wrap:wrap;padding:22px;border-bottom:1px solid var(--line);background:linear-gradient(100deg,#154050,#101d33)}.rehearsal-head span{font:800 .7rem ui-monospace,monospace;letter-spacing:.13em;color:var(--cyan)}.rehearsal-head h3{font-size:1.55rem;margin:7px 0}.rehearsal-head p{color:var(--muted);margin:0;max-width:630px;font-size:.87rem}.rehearsal-head a{font-size:.78rem;font-weight:800}.case-picker{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:8px;padding:17px;border-bottom:1px solid var(--line)}.case-picker button{text-align:left;border:1px solid var(--line);border-radius:11px;padding:12px;background:#ffffff07;color:var(--ink);font-weight:800;font-size:.8rem;line-height:1.3}.case-picker button span{display:block;font:700 .62rem ui-monospace,monospace;letter-spacing:.1em;color:var(--gold);margin-bottom:5px}.case-picker button[data-tone="go"] span{color:#a9f1c0}.case-picker button[data-tone="stop"] span{color:var(--rose)}.case-picker button[aria-checked="true"]{border-color:var(--cyan);background:#83edec1c;box-shadow:inset 0 0 0 1px #83edec55}.case-picker button:hover{border-color:var(--cyan)}.case-detail{padding:22px}.case-detail h4{font-size:1.35rem;margin:5px 0}.case-detail>p{color:var(--muted);margin:0 0 18px}.case-detail .eyebrow{font-size:.64rem}.attempts{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:11px}.attempt{border:1px solid var(--line);border-radius:12px;background:#ffffff06;padding:16px}.attempt[data-tone="stop"]{border-color:#a66275;background:#ff9eb20b}.attempt[data-tone="go"]{border-color:#70a98f;background:#a9f1c00b}.attempt[data-tone="hold"]{border-color:#b89d67;background:#f5cc7e0b}.attempt small{display:block;color:var(--muted);font:700 .65rem ui-monospace,monospace;letter-spacing:.1em}.attempt strong{display:block;margin:8px 0;font-size:1.27rem}.attempt[data-tone="stop"] strong{color:var(--rose)}.attempt[data-tone="go"] strong{color:#a9f1c0}.attempt[data-tone="hold"] strong{color:var(--gold)}.attempt .receipt-meaning{margin:0 0 9px;color:var(--muted);font-size:.75rem}.attempt code{display:block;color:#d4e4eb;font:.72rem/1.5 ui-monospace,monospace;overflow-wrap:anywhere}.case-metrics{display:flex;gap:9px;flex-wrap:wrap;margin-top:17px}.case-metrics span{border:1px solid var(--line);border-radius:999px;padding:7px 11px;color:#d8e9ef;font:.72rem ui-monospace,monospace}.case-detail .limit{margin:17px 0 0;color:var(--muted);font-size:.73rem}.host-move{margin-top:19px;padding:16px 18px;border-left:3px solid var(--gold);border-radius:0 10px 10px 0;background:#f5cc7e0d}.host-move span{display:block;color:var(--gold);font:800 .65rem ui-monospace,monospace;letter-spacing:.12em}.host-move p{margin:7px 0 0;color:#e4e1d9;font-size:.88rem}
.attempt .trace-label{margin-top:17px}.hook-trace{list-style:none;margin:8px 0 0;padding:12px 0 0;border-top:1px solid var(--line)}.hook-trace li{position:relative;margin:0 0 8px;padding-left:17px;color:var(--muted);font-size:.73rem}.hook-trace li:before{content:"";position:absolute;left:0;top:.44em;width:6px;height:6px;border-radius:50%;background:var(--cyan)}.hook-trace li:last-child{margin:0}.hook-trace .none:before{background:#8297a5}
.case-command-row{display:flex;justify-content:space-between;align-items:center;gap:12px;flex-wrap:wrap;margin-top:21px}.case-command-row span{font:800 .67rem ui-monospace,monospace;letter-spacing:.12em;color:var(--cyan)}.case-actions{display:flex;gap:8px;flex-wrap:wrap}.case-command-row button{border:1px solid #608697;background:#113344;color:var(--cyan);border-radius:9px;padding:7px 11px;font-size:.77rem;font-weight:800}.case-command-row button:hover{background:#1a5264}.case-detail .case-command{margin:9px 0 0;padding:12px 14px}.case-detail .case-copy-status{min-height:1.2em;margin:5px 0 0;font-size:.73rem;color:var(--gold)}
Expand Down Expand Up @@ -59,7 +59,7 @@
hostApproveExact(proposal, proposal_sha256, context),
consumeApproval: (input, context) => hostConsumeGrantOnce(input, context),
execute: (args, context) => sendFromHost(args, context)
});</code><p id="sketch-status" class="status" role="status" aria-live="polite"></p><p class="small">The approval hook must return <code>{ approved: true, proposal_sha256 }</code> for the exact frozen proposal and identify a host-issued grant. The claim hook must atomically consume that grant once and return exactly <code>true</code>. For callbacks with CC/BCC or transformed provider requests, use the dedicated adapters in the full guide. Do not copy the rehearsal’s automatic approval into a real host.</p></div></div>
});</code><p id="sketch-status" class="status" role="status" aria-live="polite"></p><p class="small">The approval hook must return <code>{ approved: true, proposal_sha256 }</code> for the exact frozen proposal and identify a host-issued grant. The claim hook must atomically consume that grant once and return exactly <code>true</code>. For callbacks with CC/BCC or transformed provider requests, use the dedicated adapters in the full guide. Do not copy the rehearsal’s automatic approval into a real host.</p><div class="preflight" role="note"><strong>Before a receipt exists.</strong> The host <code>resourceFor</code> mapper runs on a canonical argument snapshot. If it throws, returns a non-string, or mutates that snapshot, the adapter rejects before planning or entering the tool callback. Handle the host error separately; no dispatch receipt is produced.</div></div></div>
<div class="stage"><div class="number">03</div><div class="content"><h2>Recheck before any real dispatch.</h2><p>The host must supply its own authentication, durable one-use claims, operation idempotency, audit storage, and honest mapping to the provider request. An <code>unknown</code> callback result might already have caused a side effect; this wrapper does not retry it.</p><div class="notice">A digest binds the proposal bytes. It does not prove who approved them, whether the policy is trustworthy, or whether the outside service completed the action.</div><div class="links"><a href="https://github.com/aruintelligence/aml-core/blob/main/docs/AGENT_TOOL_QUICKSTART.md">Full function-tool guide ↗</a><a href="https://github.com/aruintelligence/aml-core/blob/main/pilots/action-boundary/guarded-tool.mjs">Inspect the adapter ↗</a><a href="https://github.com/aruintelligence/aml-core/blob/main/pilots/action-boundary/MAIL_GUARDED_TOOL.md">Multi-recipient mail path ↗</a></div></div></div>
</section>
<div class="next"><a href="action-boundary-studio.html"><span>DESIGN</span><b>Edit proposal and policy ↗</b><small>Export a calculation bundle and recheck it in Node.</small></a><a href="connected-mcp-lab.html"><span>TRACE</span><b>See a connected MCP call ↗</b><small>Compare a misleading tool hint with a host-owned rule.</small></a><a href="action-challenge.html?case=changed-destination#build"><span>CHALLENGE</span><b>Build your own adapter ↗</b><small>Run the public cases outside the reference implementation.</small></a></div>
Expand Down
Loading