approval-md 0.0.1 → 0.2.0

package/dist/src/cli/gloss-options.js

@@ -0,0 +1,79 @@
+/** Shared provider selection for the three optional gloss surfaces (APRV-255). */
+import { boolFlag } from "./args.js";
+import { codexGlossRunnerFor } from "./gloss-codex.js";
+import { GLOSS_MODEL, GLOSS_MODEL_ID_MAX_CHARS, glossRunnerFor, normalizeGlossModelId, } from "./gloss.js";
+/**
+ * Resolve the flags shared by `up`, Telegram listen and the terminal channel.
+ *
+ * The caller supplies its historical default: Telegram and `up` pass `true`,
+ * while the terminal channel passes `false`. `--no-gloss` wins a tie so an
+ * explicit request to remove a model from the path can never accidentally
+ * spawn one. Provider and model values are validated even when disabled;
+ * otherwise a typo could wait unnoticed until a later invocation adds
+ * `--gloss`.
+ */
+export function parseGlossOptions(flags, enabledByDefault) {
+    const providerValue = flags["--gloss-provider"];
+    if (providerValue !== undefined &&
+        (typeof providerValue !== "string" ||
+            (providerValue !== "claude" && providerValue !== "codex"))) {
+        return {
+            ok: false,
+            message: `--gloss-provider expects claude or codex, got ${JSON.stringify(providerValue)}`,
+        };
+    }
+    const provider = providerValue ?? "claude";
+    const modelValue = flags["--gloss-model"];
+    if (modelValue !== undefined && typeof modelValue !== "string") {
+        return {
+            ok: false,
+            message: `--gloss-model expects a model identifier, got ${JSON.stringify(modelValue)}`,
+        };
+    }
+    if (provider === "codex" && modelValue === undefined) {
+        return {
+            ok: false,
+            message: "--gloss-provider codex requires --gloss-model <model>",
+        };
+    }
+    const model = normalizeGlossModelId(modelValue ?? GLOSS_MODEL);
+    if (model === null) {
+        return {
+            ok: false,
+            message: `--gloss-model expects a nonblank model identifier of at most ${GLOSS_MODEL_ID_MAX_CHARS} letters, numbers, or . _ : / + - characters`,
+        };
+    }
+    return {
+        ok: true,
+        options: {
+            enabled: !boolFlag(flags, "--no-gloss") &&
+                (boolFlag(flags, "--gloss") || enabledByDefault),
+            provider,
+            model,
+        },
+    };
+}
+/** Construct exactly the selected runner, or no runner when glossing is disabled. */
+export function glossRunnerFromOptions(selection, factoryOptions = {}) {
+    if (!selection.enabled)
+        return undefined;
+    const passphraseEnv = factoryOptions.passphraseEnv ?? null;
+    if (selection.provider === "claude") {
+        return (factoryOptions.claudeRunnerFor ?? glossRunnerFor)(passphraseEnv, selection.model);
+    }
+    const runnerFor = factoryOptions.codexRunnerFor ?? codexGlossRunnerFor;
+    const diagnostic = factoryOptions.diagnostic;
+    return runnerFor(selection.model, passphraseEnv, diagnostic === undefined
+        ? {}
+        : {
+            diagnostic: (reason) => {
+                try {
+                    diagnostic(reason);
+                }
+                catch {
+                    // Reporting an absent convenience cannot break prompt dispatch.
+                }
+            },
+        });
+}
+//# sourceMappingURL=gloss-options.js.map

package/dist/src/cli/gloss-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gloss-options.js","sourceRoot":"","sources":["../../../src/cli/gloss-options.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAElF,OAAO,EAAE,QAAQ,EAAoB,MAAM,WAAW,CAAC;AACvD,OAAO,EAAE,mBAAmB,EAAoC,MAAM,kBAAkB,CAAC;AACzF,OAAO,EACL,WAAW,EACX,wBAAwB,EACxB,cAAc,EACd,qBAAqB,GAGtB,MAAM,YAAY,CAAC;AAapB;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAAkB,EAClB,gBAAyB;IAEzB,MAAM,aAAa,GAAG,KAAK,CAAC,kBAAkB,CAAC,CAAC;IAChD,IACE,aAAa,KAAK,SAAS;QAC3B,CAAC,OAAO,aAAa,KAAK,QAAQ;YAChC,CAAC,aAAa,KAAK,QAAQ,IAAI,aAAa,KAAK,OAAO,CAAC,CAAC,EAC5D,CAAC;QACD,OAAO;YACL,EAAE,EAAE,KAAK;YACT,OAAO,EAAE,iDAAiD,IAAI,CAAC,SAAS,CAAC,aAAa,CAAC,EAAE;SAC1F,CAAC;IACJ,CAAC;IACD,MAAM,QAAQ,GAAkB,aAAa,IAAI,QAAQ,CAAC;IAE1D,MAAM,UAAU,GAAG,KAAK,CAAC,eAAe,CAAC,CAAC;IAC1C,IAAI,UAAU,KAAK,SAAS,IAAI,OAAO,UAAU,KAAK,QAAQ,EAAE,CAAC;QAC/D,OAAO;YACL,EAAE,EAAE,KAAK;YACT,OAAO,EAAE,iDAAiD,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,EAAE;SACvF,CAAC;IACJ,CAAC;IACD,IAAI,QAAQ,KAAK,OAAO,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QACrD,OAAO;YACL,EAAE,EAAE,KAAK;YACT,OAAO,EAAE,uDAAuD;SACjE,CAAC;IACJ,CAAC;IACD,MAAM,KAAK,GAAG,qBAAqB,CAAC,UAAU,IAAI,WAAW,CAAC,CAAC;IAC/D,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACnB,OAAO;YACL,EAAE,EAAE,KAAK;YACT,OAAO,EACL,gEAAgE,wBAAwB,8CAA8C;SACzI,CAAC;IACJ,CAAC;IAED,OAAO;QACL,EAAE,EAAE,IAAI;QACR,OAAO,EAAE;YACP,OAAO,EACL,CAAC,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;gBAC9B,CAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,IAAI,gBAAgB,CAAC;YAClD,QAAQ;YACR,KAAK;SACN;KACF,CAAC;AACJ,CAAC;AAgBD,qFAAqF;AACrF,MAAM,UAAU,sBAAsB,CACpC,SAAuB,EACvB,cAAc,GAA8B,EAAE;IAE9C,IAAI,CAAC,SAAS,CAAC,OAAO;QAAE,OAAO,SAAS,CAAC;IACzC,MAAM,aAAa,GAAG,cAAc,CAAC,aAAa,IAAI,IAAI,CAAC;IAC3D,IAAI,SAAS,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QACpC,OAAO,CAAC,cAAc,CAAC,eAAe,IAAI,cAAc,CAAC,CAAC,aAAa,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC;IAC5F,CAAC;IAED,MAAM,SAAS,GAAG,cAAc,CAAC,cAAc,IAAI,mBAAmB,CAAC;IACvE,MAAM,UAAU,GAAG,cAAc,CAAC,UAAU,CAAC;IAC7C,OAAO,SAAS,CACd,SAAS,CAAC,KAAK,EACf,aAAa,EACb,UAAU,KAAK,SAAS;QACtB,CAAC,CAAC,EAAE;QACJ,CAAC,CAAC;YACE,UAAU,EAAE,CAAC,MAAM,EAAE,EAAE;gBACrB,IAAI,CAAC;oBACH,UAAU,CAAC,MAAM,CAAC,CAAC;gBACrB,CAAC;gBAAC,MAAM,CAAC;oBACP,gEAAgE;gBAClE,CAAC;YACH,CAAC;SACF,CACN,CAAC;AACJ,CAAC"}

package/dist/src/cli/gloss.d.ts

@@ -0,0 +1,265 @@
+/**
+ * The model gloss: one sentence saying what a payload does, attached to a
+ * prompt at render time and to nothing else (APRV-144, APRV-164).
+ *
+ * The observed complaint (Carter, 2026-08-25): "the claimed isn't very useful —
+ * I mostly see the path, not a readable claim of what is happening". The
+ * deterministic half of the answer is `channels/payload-view.ts`'s command
+ * breakdown, which is derived from the classifier's own parse and is COMPUTED.
+ * This is the other half, and it is the opposite kind of thing: a sentence from
+ * a language model, which no party vouches for and which the runtime must
+ * therefore treat as decoration.
+ *
+ * Four properties hold the design together, and every one of them is about
+ * keeping a model out of the decision.
+ *
+ * **The gate never sees it.** This runs in the LISTENER, at the moment a
+ * message is about to be sent, on a `ChannelRequest` the tagger has already
+ * finished building. The payload hash covers the bytes and not this; the log
+ * records the approval lifecycle and not this; a restart forgets it. Nothing
+ * here writes anything anywhere.
+ *
+ * **It is never load-bearing.** No code path branches on the content of a
+ * gloss. The only thing that turns on it at all is whether one more line
+ * appears in the CLAIMED block, which is why every failure mode below resolves
+ * to ABSENCE rather than to a placeholder, an error line, or a retry: a prompt
+ * with no gloss is the prompt approval.md shipped for its whole life so far,
+ * and a listener that waited on a model would have made a language model part
+ * of the availability of the gate.
+ *
+ * **It fails toward absence, fast.** A hard timeout (default
+ * {@link GLOSS_TIMEOUT_MS}), a non-zero exit, empty output, a binary that is
+ * not installed, a spawn that throws: all `null`. The timeout is bounded on
+ * purpose — this sits in a dispatch cycle that an approver is waiting on — and
+ * since APRV-197 it is bounded by a MEASUREMENT rather than by a guess, because
+ * a ceiling the model cannot meet is not a fast failure, it is a feature that
+ * never runs. See {@link GLOSS_TIMEOUT_MS}. Absences are counted and reported
+ * by the caller (`cli/gloss-attach.ts`), so a ceiling that is wrong again
+ * announces itself instead of looking like silence.
+ *
+ * **Its output is untrusted text.** Whatever comes back is collapsed to a
+ * single line, capped at {@link GLOSS_MAX_CHARS}, and handed to the channel as
+ * a CLAIMED field, which means it goes through the same `escapeHtml` every
+ * other claimed value does. It is treated exactly like a summary an agent
+ * wrote, because that is precisely what it is a cousin of.
+ *
+ * The subprocess is injectable ({@link GlossRunner}) so the tests drive both
+ * branches without a model ever being invoked: the suite never spawns
+ * anything, and the default runner below is exercised only in production.
+ */
+/**
+ * How long the subprocess gets before it is killed and the gloss is dropped.
+ *
+ * **Measured, not guessed (APRV-197).** APRV-144 chose 2s on the reasoning that
+ * "a slow reading aid is worse than no reading aid", which is true and was the
+ * wrong number: five fresh `claude -p --model haiku` spawns of this module's
+ * own command instruction, timed on the author's machine on 2026-09-01, came
+ * back in 10.2s, 11.3s, 13.5s, 14.6s and 14.9s. Every one of them would have
+ * been killed. The gloss was therefore not "occasionally absent"; it was
+ * absent every single time, and because absence is silent by design that was
+ * indistinguishable from the feature never having shipped — which is exactly
+ * how it was reported (Carter, 2026-09-01: "i thought we implemented a change
+ * so that the claim would be an llm summary").
+ *
+ * A pre-warm was the other option on the table and the measurement rules it
+ * out: the runs above were consecutive, so runs two through five were warm in
+ * every sense a second process can be (page cache, module cache), and they took
+ * 10s to 15s all the same. What is being waited on is inference, not start-up,
+ * and nothing a listener does once at boot shortens it.
+ *
+ * So the ceiling is set above the slowest observed run with headroom, and the
+ * price of that honesty is made explicit rather than hidden. A gloss is now
+ * asked for only under `--gloss` (on `channel cli`, `channel telegram listen`
+ * and `up` alike): an operator who wants the sentence spends the seconds
+ * knowingly, one who does not is never made to wait, and the reading aid that
+ * is always present is the deterministic `command_breakdown` the classifier
+ * derives from the same bytes for free.
+ */
+export declare const GLOSS_TIMEOUT_MS = 20000;
+/** The most characters a gloss may occupy on the prompt. */
+export declare const GLOSS_MAX_CHARS = 200;
+/** Maximum length of an exact provider-supplied model identifier. */
+export declare const GLOSS_MODEL_ID_MAX_CHARS = 100;
+/**
+ * The model tier this spends: the cheap one.
+ *
+ * CLAUDE.md's model tiers put "cheap classification" on a `claude -p` haiku
+ * subprocess, and a one-sentence paraphrase of a command line is the cheapest
+ * kind of language task there is. Nothing about the prompt or the gate changes
+ * if the flag is unrecognised by the installed CLI: an unusable invocation
+ * exits non-zero and the gloss is absent.
+ */
+export declare const GLOSS_MODEL = "haiku";
+/**
+ * The historical author label for legacy string-valued test runners.
+ *
+ * Production runners return explicit provenance. Keeping this constant is a
+ * compatibility bridge for callers whose injected seam predates APRV-253; it
+ * must never be used to guess the provenance of a typed production result.
+ */
+export declare const GLOSS_AUTHOR = "model:haiku";
+/**
+ * The instruction the model is given.
+ *
+ * Deliberately narrow: describe, do not judge. A model asked whether a command
+ * is safe would produce a sentence an approver could read as a recommendation,
+ * and a recommendation from an unverified party sitting beside an Approve
+ * button is the failure this whole codebase is arranged to prevent. It is
+ * asked what the command DOES, and the answer is labelled as a model's on the
+ * line where it appears.
+ */
+export declare const GLOSS_INSTRUCTION: string;
+/**
+ * The same instruction for a file change (APRV-164).
+ *
+ * A payload kind gets its own wording because "what this shell command does" is
+ * the wrong question to ask about a diff, and a model handed the wrong question
+ * answers a question nobody asked. The discipline is identical: describe the
+ * change, do not rate it, and above all do not say whether the edit looks
+ * correct — a judgement of a diff sitting beside an Approve button is the same
+ * failure as a judgement of a command.
+ */
+export declare const GLOSS_EDIT_INSTRUCTION: string;
+/** The same instruction for an email (APRV-164): what it says, and to whom. */
+export declare const GLOSS_EMAIL_INSTRUCTION: string;
+/**
+ * The most material a gloss may hand the subprocess.
+ *
+ * A whole-file `Write` payload is megabytes, and a reading aid must not turn a
+ * dispatch cycle into a megabyte of argv and a model reading it. The cap is on
+ * the INPUT only: {@link GLOSS_MAX_CHARS} still bounds what comes back.
+ */
+export declare const GLOSS_MAX_INPUT_CHARS = 8192;
+/**
+ * What the model is told when the cap bit.
+ *
+ * Announced rather than silent, for the reason every other fold in this
+ * codebase is announced: a model describing a prefix as if it were the whole
+ * would produce a confident sentence about a change the approver is not being
+ * shown. The line is for the model; the approver's own evidence is the PAYLOAD
+ * block, which is never folded.
+ */
+export declare const GLOSS_TRUNCATION_NOTE = "(input truncated; describe what is shown)";
+/** A summarizer implementation the listener may explicitly select. */
+export type GlossProvider = "claude" | "codex";
+/**
+ * The model identity a runner can honestly establish.
+ *
+ * `requestedModel` is always present because it is controlled by the
+ * invocation. `confirmedModel` is present only when machine-readable process
+ * output identifies the model that actually served the request. A successful
+ * process exit alone does not confirm that identity.
+ */
+export interface GlossProvenance {
+    provider: GlossProvider;
+    requestedModel: string;
+    confirmedModel?: string;
+}
+/** One raw model answer together with runner-supplied provenance. */
+export interface GlossResult {
+    text: string;
+    provenance: GlossProvenance;
+    /** Compatibility marker for the pre-APRV-253 injected string seam. */
+    legacy?: true;
+}
+/**
+ * How a gloss is obtained.
+ *
+ * New runners return a {@link GlossResult}. A raw string remains accepted only
+ * so existing injected stubs keep working; it is explicitly interpreted as
+ * the historical Claude/Haiku seam. Every flavour of "no answer" is `null`.
+ *
+ * MUST NOT throw: a runner that raised would put a language model on the
+ * failure path of the listener's dispatch cycle.
+ */
+export type GlossRunnerOutput = GlossResult | string | null;
+export type GlossRunner = (prompt: string) => GlossRunnerOutput;
+/**
+ * One line, capped, or `null`.
+ *
+ * Newlines are stripped rather than escaped because the prompt renders this as
+ * a single bullet, and a multi-line value would break the one-fact-per-line
+ * shape the whole COMPUTED/CLAIMED split relies on to stay legible. Truncation
+ * is marked, for the same reason every other fold in this codebase is.
+ */
+export declare function tidyGloss(raw: string | null): string | null;
+/**
+ * Normalize a runner answer without inventing provenance.
+ *
+ * Objects with incomplete metadata fail toward absence. Raw strings take the
+ * one narrowly documented legacy path and retain the historical Haiku label.
+ */
+export declare function tidyGlossResult(raw: unknown): GlossResult | null;
+/** A bounded, single-line identifier, or `null` rather than a misleading fold. */
+export declare function normalizeGlossModelId(raw: unknown): string | null;
+/**
+ * The claimed author rendered beside one gloss.
+ *
+ * Requested and confirmed identities are deliberately distinct. The default
+ * subprocess knows what it asked Claude for, but its plain stdout does not
+ * prove which model served the request, so it renders as requested.
+ */
+export declare function glossAuthor(result: GlossResult): string;
+/**
+ * The production runner: `claude -p --model haiku`, with a hard timeout.
+ *
+ * `spawnSync` with no shell, in the manner of `cli/hook.ts`'s git calls: the
+ * prompt is an argument and never a string a shell re-parses. Every failure is
+ * a value rather than an exception — `spawnSync` reports a missing binary and a
+ * timeout kill on the result object, and both are simply "no gloss".
+ *
+ * **Starved, like a granted child (APRV-207).** The environment is built by
+ * APRV-205's scrub rather than inherited: this is a third-party CLI that talks
+ * to the network on every prompt render, spawned by the listener, which is the
+ * process holding the Telegram bot token and the vault passphrase. It has no
+ * use for either, and a gate that hands its own credentials to a convenience is
+ * a gate whose custody claim is decorative. No credential is DECLARED here,
+ * because a gloss is not a granted action and no adapter asked for one.
+ *
+ * What passes is what the scrub does not take: the model's own auth
+ * (`ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, `CLAUDE_CODE_OAUTH_TOKEN`,
+ * `ANTHROPIC_BASE_URL`, `ANTHROPIC_MODEL` and kin), `PATH`, `HOME`, `TMPDIR`
+ * and the locale. None of them is under the gate's credential-bearing prefixes,
+ * so none of them needs a list of its own: a second list here is a second list
+ * to drift, and the CLI's ability to reach its own model is not this gate's
+ * secret to keep.
+ *
+ * `passphraseEnv` is the name the policy's `vault.passphrase_env` gives, for
+ * the deployment that renamed it out from under the prefixes. Omitted, the
+ * default (`APPROVAL_VAULT_PASSPHRASE`) is removed by the prefix rule anyway.
+ */
+export declare function spawnGloss(prompt: string, passphraseEnv?: string | null, model?: string): GlossResult | null;
+/**
+ * {@link spawnGloss} bound to one policy's passphrase variable (APRV-207).
+ *
+ * The verbs that wire a runner (`channel cli`, `channel telegram listen`, `up`)
+ * have a policy load in hand already, and this is the only thing the scrub
+ * needs from it. A runner is still a `(prompt) => string | null`, so nothing
+ * downstream learns that a policy exists.
+ */
+export declare function glossRunnerFor(passphraseEnv: string | null, model?: string): GlossRunner;
+/**
+ * `material`, capped at {@link GLOSS_MAX_INPUT_CHARS} and marked when it was.
+ *
+ * The marker precedes the material rather than trailing it, so a model reading
+ * a long prefix meets the caveat before the text it is about to describe.
+ */
+export declare function glossPrompt(instruction: string, material: string): string;
+/**
+ * A gloss for one payload's material, or `null`.
+ *
+ * The material is passed to the model as data inside the prompt. It is
+ * agent-authored text, and it is worth being explicit about what that does and
+ * does not mean here: a command (or a diff, or a body) crafted to talk the
+ * model into writing "harmless cleanup" gets that sentence onto the prompt,
+ * labelled `(model, unverified)`, next to a COMPUTED breakdown derived from the
+ * same bytes by code and a PAYLOAD block carrying the canonical rendering verbatim. It
+ * cannot change the class, the autonomy, the budget verdicts or the payload
+ * hash, because nothing downstream reads it. That is the whole reason this is
+ * allowed to exist on the prompt at all.
+ *
+ * The caller chooses the instruction, which is the only thing that varies by
+ * payload kind: the bounds, the failure modes and the author label are one
+ * pipeline for every kind (APRV-164).
+ */
+export declare function glossFor(instruction: string, material: string, run?: GlossRunner): GlossResult | null;