approval-md 0.0.1 → 0.2.0

package/cli.js

@@ -1,4 +1,30 @@
 #!/usr/bin/env node
-console.log("approval.md: human approval for agent actions.");
-console.log("Pre-release. Spec: https://approval.md");
-console.log("Repo: https://github.com/approval-md");
+/**
+ * `approval` bin entry: a thin loader for the compiled CLI.
+ *
+ * All behaviour lives in src/cli/main.ts. This file exists only to find the
+ * build output and hand it argv, so the published bin and
+ * `node dist/src/cli/main.js` are the same program.
+ *
+ * The exit code is set via `process.exitCode` rather than `process.exit()`, so
+ * stdout is flushed by the normal exit path — a JSON object truncated by an
+ * early exit would be worse than no output.
+ */
+
+import { existsSync } from "node:fs";
+
+const entry = new URL("./dist/src/cli/main.js", import.meta.url);
+
+if (!existsSync(entry)) {
+  // Exit 4 = I/O error in the frozen exit-code table (src/cli/exit-codes.ts).
+  process.stderr.write(
+    "approval: dist/src/cli/main.js is missing — run `npm run build` first.\n",
+  );
+  process.exitCode = 4;
+} else {
+  const { main } = await import(entry.href);
+  // `main` is asynchronous since APRV-209: every verb is loaded on demand, and
+  // ESM has no synchronous dynamic import. The exit code still travels through
+  // `process.exitCode`, so the flush behaviour described above is unchanged.
+  process.exitCode = await main(process.argv.slice(2));
+}

package/dist/src/adapters/agentmail.d.ts

@@ -0,0 +1,426 @@
+/**
+ * The AgentMail adapter (SPEC.md §6.1, §6.2, §10.4, §11; APRV-222).
+ *
+ * A second executor for `communicate.email.external`, over the AgentMail HTTPS
+ * API. It exists because AgentMail is becoming the way an agent holds a mailbox,
+ * and because its Drafts primitive is documented as mail that only leaves when
+ * something outside the agent says so. approval.md is that something, with a
+ * hash-chained log behind it.
+ *
+ * Like every adapter it implements exactly one method, {@link Adapter.act}, and
+ * `adapters/contract.ts` owns everything around the call: the hash
+ * recomputation, the token spend, `execution.started`, the credential window,
+ * the outcome event, and the redaction sweep. Nothing here touches a token or
+ * the log.
+ *
+ * ## The enforcement model this adapter assumes
+ *
+ * AgentMail API keys carry per-permission booleans (`draft_create`,
+ * `draft_update`, `draft_read`, `draft_send`, `message_send` are separate). The
+ * deployment this adapter is written for gives the agent a key WITHOUT the two
+ * send permissions and puts a key WITH them in the vault under
+ * {@link DEFAULT_AGENTMAIL_CREDENTIAL_NAMES}.apiKey, where it is readable only
+ * inside the verified execution window the contract opens. The agent can therefore
+ * compose all day and cannot send at all; the sending key answers to a grant.
+ *
+ * ## Two payload modes, discriminated by shape, ambiguity refused
+ *
+ * **Direct send.** The email adapter's own payload, validated by the email
+ * adapter's own {@link validateEmailPayload} rather than a second copy of it:
+ *
+ * ```ts
+ * { from, to: string[], cc?, bcc?, subject, body, content_type? }
+ * ```
+ *
+ * posted to `POST /v0/inboxes/{inbox_id}/messages/send`.
+ *
+ * **Draft send.** A snapshot of a draft the agent has already composed, taken at
+ * request time so a human approves the words rather than an id:
+ *
+ * ```ts
+ * { inbox_id, draft_id, to: string[], cc?, bcc?, subject, text }
+ * ```
+ *
+ * The adapter re-fetches the draft, canonicalizes those same fields (RFC 8785,
+ * the same `core/jcs.ts` the hash chain uses) on both sides, and refuses
+ * `agentmail-draft-drifted` on any difference before calling
+ * `POST .../drafts/{draft_id}/send`. That check is the whole point of the mode:
+ * a draft is mutable server-side state, and an approval of a draft id would
+ * otherwise be an approval of whatever the agent last wrote into it. The
+ * refusal names WHICH fields differ and never what they now hold — a drift
+ * message is written to a log and read by a human who did not approve the new
+ * text, and quoting it there would publish unapproved content through the
+ * refusal path.
+ *
+ * ## The comparison runs before the token is spent (APRV-276)
+ *
+ * It happens TWICE, through one function ({@link checkDraftBeforeSend}), and
+ * the first of the two is the one this section exists for.
+ *
+ * The first call is {@link Adapter.precheck}: the contract runs it after the
+ * declared credentials resolve and BEFORE the token is consumed, so a drifted
+ * draft refuses with nothing appended and the grant intact. Until APRV-276 the
+ * comparison ran only inside `act`, which meant a drift refused correctly and
+ * spent the single-use token doing it: the human's tap was consumed by an
+ * attempt that sent nothing, and restoring the approved text then refused
+ * `token-consumed`. That is the failure mode the whole design is against — a
+ * refusal that costs a human another tap teaches operators to stop checking.
+ *
+ * The second call is `act`'s own, inside the consumed-token window and
+ * immediately before the POST. It is not redundant: AgentMail sends a draft by
+ * id, so something must stand between the last read and the send, and this is
+ * what makes that gap as small as the transport allows. A drift caught there is
+ * `execution.started` then `execution.failed`, which is the honest record of a
+ * window that was open when the far side moved.
+ *
+ * **Which key performs the pre-spend read.** The same sending key from the
+ * vault, handed over by the credential provider the contract scopes to the
+ * precheck call. Not the agent's own `AGENTMAIL_API_KEY`, even though the demo
+ * has one in the environment: a comparison whose input the party under
+ * oversight chooses is scrutiny that party controls, and SPEC.md §11.1
+ * invariant 4 puts that the other way round. Nothing new is opened to make this
+ * possible — the contract already reads the vault before the spend, to resolve
+ * {@link Adapter.requiredCredentials} (APRV-169), inside APRV-168's
+ * `presented`-phase grant, which is minted only when the caller's token matches
+ * the digest the human's grant recorded. SPEC.md §10.4 carries the decision.
+ *
+ * A payload carrying markers of both modes, or of neither, is refused rather
+ * than guessed at (`agentmail-payload-ambiguous`, `agentmail-payload-invalid`):
+ * choosing a send mode by inference is choosing a side effect by inference.
+ *
+ * ## `from`, and why it costs one extra read
+ *
+ * AgentMail's send endpoint has no `from` field. The inbox IS the sender, so
+ * the payload cannot bind the From address the way the SMTP adapter's can, and
+ * a human who approved a message "from carter@…" would otherwise be approving a
+ * sender this adapter never checked.
+ *
+ * The resolution: `from` stays in the payload as the human-facing claim about
+ * the sender (reusing {@link validateEmailPayload} keeps it required and
+ * well-formed), it is sent to AgentMail in no field at all, and `act` performs
+ * one extra read — `GET /v0/inboxes/{inbox_id}` — before the send, refusing
+ * `agentmail-from-mismatch` (case-insensitively) when the inbox's own address is
+ * not the approved one. So `from` is informational on the wire and binding here.
+ * The read runs on every direct send because it doubles as the credential
+ * check: a key that cannot open its own inbox is a key that should not discover
+ * this by half-sending. It is a GET, it is idempotent, it puts no message
+ * anywhere, and a transport failure on it is `agentmail-unreachable` precisely
+ * because nothing was attempted.
+ *
+ * ## Failures
+ *
+ * Every HTTP refusal is a RETURNED failure ({@link ActOutcome} `ok: false`), so
+ * the contract records `execution.failed`: the far side answered, and an answer
+ * is knowledge. A throw from the SEND call is deliberately NOT caught — it
+ * propagates, the contract records `execution.indeterminate`, and a human finds
+ * out that nobody knows whether the message went (APRV-120). A throw from the
+ * pre-send GETs is returned as `agentmail-unreachable`, because those run before
+ * anything is attempted.
+ *
+ * Deterministic apart from its transport: no randomness, no clock, no
+ * environment reads. Every string this file returns has been through
+ * {@link redactSecrets} against the API key.
+ */
+import type { CredentialSpec } from "../core/credential-spec.js";
+import { type Adapter, type CredentialProvider, type JsonValue } from "./contract.js";
+/** The one class this adapter serves. The same string the email adapter serves. */
+export declare const AGENTMAIL_CLASS = "communicate.email.external";
+/** The public API. Overridable so the whole adapter can run against loopback. */
+export declare const AGENTMAIL_DEFAULT_API_BASE = "https://api.agentmail.to";
+/** Whole-request budget for one HTTP call. */
+export declare const AGENTMAIL_DEFAULT_TIMEOUT_MS = 15000;
+/**
+ * The two vault names, as an open record rather than a literal type: a
+ * deployment that stores these under other names must be able to SAY so, and a
+ * `typeof` of the defaults would type `credentialNames` as the defaults.
+ */
+export interface AgentmailCredentialNames {
+    apiKey: string;
+    inboxId: string;
+}
+/** The vault names, overridable per deployment. */
+export declare const DEFAULT_AGENTMAIL_CREDENTIAL_NAMES: AgentmailCredentialNames;
+export declare const AGENTMAIL_FAILURE_CODES: readonly ["agentmail-payload-invalid", "agentmail-payload-ambiguous", "agentmail-config-invalid", "agentmail-inbox-mismatch", "agentmail-from-mismatch", "agentmail-draft-missing", "agentmail-draft-drifted", "agentmail-unreachable", "agentmail-unauthorized", "agentmail-not-found", "agentmail-conflict", "agentmail-rate-limited", "agentmail-rejected", "agentmail-server-error", "credential-unavailable", "credential-refused", "credential-window-closed"];
+export type AgentmailFailureCode = (typeof AGENTMAIL_FAILURE_CODES)[number];
+export declare function isAgentmailFailureCode(value: string): boolean;
+/**
+ * What this adapter reads from the vault, declared rather than discovered, so
+ * `approval setup adapter agentmail` can ask for it without knowing what
+ * AgentMail is. DERIVED from {@link DEFAULT_AGENTMAIL_CREDENTIAL_NAMES} rather
+ * than restating the strings.
+ */
+export declare const AGENTMAIL_CREDENTIAL_SPECS: readonly CredentialSpec[];
+/**
+ * The names this adapter cannot act without (APRV-169), for the contract's
+ * pre-token resolution. Derived from the manifest, mapped through `names` so a
+ * deployment that renamed one gets the name it actually stored.
+ */
+export declare function requiredAgentmailCredentials(names?: AgentmailCredentialNames): readonly string[];
+/** What {@link readAgentmailConfig} resolved. */
+export interface AgentmailConfig {
+    apiKey: string;
+    inboxId: string;
+}
+/**
+ * What one configuration read produced.
+ *
+ * `secrets` is the redaction corpus and holds ONLY the secret-kind values (the
+ * API key). The inbox id is not a secret and is deliberately left scrubbable-not:
+ * it appears in refusal sentences that are useless without it. Returned on both
+ * branches, because a caller that goes on to make requests must scrub the far
+ * side's sentences with the same corpus this read built.
+ */
+export type AgentmailConfigOutcome = {
+    ok: true;
+    config: AgentmailConfig;
+    secrets: readonly string[];
+} | {
+    ok: false;
+    code: AgentmailFailureCode;
+    message: string;
+    secrets: readonly string[];
+};
+/**
+ * Read this adapter's whole configuration from a credential provider.
+ *
+ * The single place in the repository that turns a {@link CredentialProvider}
+ * into AgentMail settings — the names it asks for, the order, the shape rules —
+ * mirroring `readEmailSmtpConfig` for the same reason: `act` calls it inside the
+ * verified execution window and `approval setup adapter agentmail` calls it to probe
+ * a configuration it only partly typed, and a second reader would be a second
+ * opinion about what "configured" means.
+ */
+export declare function readAgentmailConfig(credentials: CredentialProvider, names?: AgentmailCredentialNames): AgentmailConfigOutcome;
+/**
+ * The slice of `fetch` this module uses, structurally.
+ *
+ * Declared here rather than imported so the adapter depends on a shape and not
+ * on a lib: a test hands over a stub, and the default is the global `fetch`
+ * Node ≥ 20 ships.
+ */
+export type AgentmailFetch = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+    signal: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    text(): Promise<string>;
+}>;
+/** The one non-sending read, exported so the setup wizard can probe a key. */
+export type AgentmailProbe = {
+    ok: true;
+    address: string;
+    http_status: number;
+    /**
+     * The permissions the inbox read DISCLOSED about the calling key, or
+     * `null` when it disclosed none (APRV-223).
+     *
+     * Read from the one response this adapter already asks for, never from a
+     * second endpoint: a setup verb that probed a URL nobody has confirmed
+     * exists would report a 404 as a permissions problem, which is a worse
+     * answer than "not disclosed". `null` therefore means UNKNOWN and never
+     * "none", and every caller must treat it as the reminder it is.
+     */
+    permissions: readonly string[] | null;
+} | {
+    ok: false;
+    code: AgentmailFailureCode;
+    message: string;
+};
+/** The two permissions a key must hold to send anything for this adapter. */
+export declare const AGENTMAIL_SEND_PERMISSIONS: readonly ["draft_send", "message_send"];
+export interface AgentmailProbeOptions {
+    fetch?: AgentmailFetch;
+    apiBase?: string;
+    timeoutMs?: number;
+}
+/**
+ * `GET /v0/inboxes/{inbox_id}`: does this key open this inbox, and what address
+ * does it send as? Sends nothing, changes nothing, and is the credential check
+ * both `act` and `approval setup adapter agentmail` use.
+ */
+export declare function probeAgentmail(config: AgentmailConfig, options?: AgentmailProbeOptions): Promise<AgentmailProbe>;
+/** The snapshot of a composed draft a grant binds to. */
+export interface AgentmailDraftPayload {
+    inbox_id: string;
+    draft_id: string;
+    to: string[];
+    cc?: string[];
+    bcc?: string[];
+    subject: string;
+    text: string;
+}
+/** The fields the drift check covers: everything a reader of the draft saw. */
+export declare const AGENTMAIL_DRAFT_FIELDS: readonly ["to", "cc", "bcc", "subject", "text"];
+export type AgentmailMode = "direct" | "draft";
+export type AgentmailDraftValidation = {
+    ok: true;
+    payload: AgentmailDraftPayload;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Structural validation of a draft payload. Never throws; returns the reason.
+ *
+ * Exported so a caller can check a payload BEFORE requesting approval for it,
+ * which is the only place a shape error can still be fixed cheaply.
+ */
+export declare function validateAgentmailDraftPayload(value: JsonValue): AgentmailDraftValidation;
+/**
+ * Which mode a payload is in, by the markers it carries.
+ *
+ * A payload with markers of both modes is ambiguous and a payload with markers
+ * of neither is not addressed to this adapter at all. Both are refused: a send
+ * mode chosen by inference is a side effect chosen by inference.
+ */
+export declare function agentmailMode(value: JsonValue): {
+    ok: true;
+    mode: AgentmailMode;
+} | {
+    ok: false;
+    code: AgentmailFailureCode;
+    message: string;
+};
+/**
+ * Which of {@link AGENTMAIL_DRAFT_FIELDS} differ between the approved snapshot
+ * and what the server now holds. Names only — never values.
+ */
+export declare function draftDrift(approved: AgentmailDraftPayload, fetched: Record<string, unknown>): string[];
+export type AgentmailDraftSnapshot = {
+    ok: true;
+    payload: AgentmailDraftPayload;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * The payload a grant should bind to, built from what the API holds RIGHT NOW
+ * (APRV-223).
+ *
+ * `approval payload agentmail-draft` prints this and nothing else, and it lives
+ * here rather than in the CLI for one reason: the bytes it prints are the bytes
+ * {@link draftDrift} will compare against the same draft at send time, so the
+ * two must be one piece of code. A second opinion in the CLI about what "the
+ * draft's cc" is would be a snapshot that drifts from a draft nobody changed.
+ *
+ * The rules follow {@link canonicalField} exactly. `cc`/`bcc` are OMITTED when
+ * the draft holds nothing for them, because absent, `null` and `[]` are one
+ * fact there; `to` is copied through as the array it is, unnormalized, because
+ * a reordered or re-shaped recipient list is a different message. Anything this
+ * function cannot turn into a well-formed snapshot is refused with the reason:
+ * a payload that fails {@link validateAgentmailDraftPayload} at send time is a
+ * refusal a human has already been asked to approve.
+ */
+export declare function draftSnapshot(inboxId: string, draftId: string, fetched: Record<string, unknown>): AgentmailDraftSnapshot;
+export type AgentmailDraftRead = {
+    ok: true;
+    draft: Record<string, unknown>;
+    http_status: number;
+} | {
+    ok: false;
+    code: AgentmailFailureCode;
+    message: string;
+};
+export interface AgentmailDraftReadOptions extends AgentmailProbeOptions {
+    /** The key that reads the draft. The AGENT's key here, not the vault's. */
+    apiKey: string;
+    inboxId: string;
+    draftId: string;
+}
+/**
+ * `GET /v0/inboxes/{inbox}/drafts/{draft}`: one draft, read and nothing else.
+ *
+ * The read half of the draft flow, exported for `approval payload
+ * agentmail-draft` (APRV-223), which runs BEFORE any approval exists and with
+ * the agent's own key rather than the vault's. It sends nothing and spends no
+ * token: what it produces is a proposal a human has yet to see.
+ */
+export declare function readAgentmailDraft(options: AgentmailDraftReadOptions): Promise<AgentmailDraftRead>;
+/**
+ * How many messages one page asks for. The API's own cap is higher; this is the
+ * page size, and {@link OBSERVE_MAX_PAGES} bounds how many pages are walked.
+ */
+export declare const AGENTMAIL_OBSERVE_PAGE_SIZE = 100;
+/**
+ * How many pages one observation walks.
+ *
+ * A bound rather than a full drain, because a reporting verb must terminate
+ * against an inbox of any size. A run that hits the bound says so, so a reader
+ * never mistakes a truncated page walk for a quiet mailbox.
+ */
+export declare const OBSERVE_MAX_PAGES = 10;
+/** One sent message, reduced to what a coverage report may say out loud. */
+export interface AgentmailObservedMessage {
+    messageId: string;
+    /** RFC 3339, as the provider reported it. */
+    at: string;
+    subject: string;
+    recipients: number;
+}
+export type AgentmailObservation = {
+    ok: true;
+    messages: AgentmailObservedMessage[];
+    /** Set when the page bound stopped the walk before the far side ran out. */
+    truncated: boolean;
+} | {
+    ok: false;
+    code: AgentmailFailureCode;
+    message: string;
+};
+export interface AgentmailObserveOptions extends AgentmailProbeOptions {
+    /** Override {@link AGENTMAIL_OBSERVE_PAGE_SIZE}. */
+    pageSize?: number;
+    /** Override {@link OBSERVE_MAX_PAGES}. */
+    maxPages?: number;
+}
+/**
+ * `GET /v0/inboxes/{inbox_id}/messages`: what this inbox actually sent.
+ *
+ * The endpoint and its fields are AgentMail's own, documented at
+ * https://docs.agentmail.to/api-reference/inboxes/messages/list — `message_id`,
+ * `labels`, `timestamp`, `to` and `subject`. The query carries `after`, `before`
+ * and `limit`, and `page_token` on every page after the first.
+ *
+ * **The sent filter is client-side, and that is a limit worth stating.** The
+ * documented list endpoint exposes no sent-only parameter, so this asks for the
+ * window's messages and keeps the ones whose `labels` include `sent`. Two
+ * consequences follow and neither is papered over: the request reads received
+ * mail as well as sent (a read, changing nothing), and a provider that stopped
+ * labelling sent mail would make this source report an empty window rather than
+ * an error. The remedy for the second is the same as for everything else here:
+ * the source reports what the provider said, and a source that says nothing is
+ * a gap a reader can see rather than a pass.
+ *
+ * Sends nothing. Spends no token. Reads no clock: the window is the caller's.
+ */
+export declare function observeAgentmail(config: AgentmailConfig, window: {
+    since: string;
+    until: string;
+}, options?: AgentmailObserveOptions): Promise<AgentmailObservation>;
+export interface AgentmailAdapterOptions {
+    /**
+     * Additional classes this adapter serves, **added** to {@link AGENTMAIL_CLASS}
+     * rather than replacing it: the class list is routing, and a list that
+     * replaced the default would make "add one class" silently stop serving the
+     * canonical one.
+     */
+    classes?: readonly string[];
+    /** Injectable `fetch`, for tests. Defaults to the global. */
+    fetch?: AgentmailFetch;
+    /** API base. Defaults to {@link AGENTMAIL_DEFAULT_API_BASE}. */
+    apiBase?: string;
+    /** Per-request budget. Defaults to {@link AGENTMAIL_DEFAULT_TIMEOUT_MS}. */
+    timeoutMs?: number;
+    /** Override the vault names. Partial: unnamed entries keep their default. */
+    credentialNames?: Partial<AgentmailCredentialNames>;
+}
+/**
+ * A fresh AgentMail adapter.
+ *
+ * Stateless and reusable: it holds no connection and nothing from a previous
+ * send. Two concurrent executions through the same instance share nothing.
+ */
+export declare function agentmailAdapter(options?: AgentmailAdapterOptions): Adapter;