@tinycloud/courier 0.2.0-beta.33 → 0.2.0-beta.34

package/README.md

@@ -49,7 +49,7 @@ tc courier pair accept --file a.json
 tc courier send bob --new "Subject" --ask "…" --file handoff.md
 tc courier inbox && tc courier read <threadId>
 tc courier task new --peer bob --thread <id> --state working --ask a1
-tc courier request <threadId> --peer bob --task <id> --action "…" --why "…"
+tc courier request <threadId> --peer bob --task <id> --verb merge --target owner/repo#12 --summary "Merge PR 12" --why "…"
 tc courier orders bob
 ```
 
@@ -165,9 +165,122 @@ process group is killed (a shell's background jobs, pipelines and subshells
 included) and the wake counts as failed. A failed wake stays pending, releases
 its claim and retries after 60 s. A timeout that hits after the agent already
 received the prompt therefore wakes the thread again: wakes are at-least-once.
-A command that exits normally but leaves a background job running is not
-waited for, and the job is left alone. When the watcher stops (SIGTERM, a state
-conflict) it kills the runs still in flight.
+A child that calls `setsid` or `setpgid` leaves the group and survives the kill
+(the group kill reaches everything the shell started, not a program that
+deliberately detaches). A command that exits normally but leaves a background
+job running is not waited for, and the job is left alone. When the watcher stops (SIGINT, SIGTERM, a state
+conflict) it kills the runs still in flight at once, without waiting for the
+wake to end.
+
+If the watcher itself is killed (SIGKILL, power loss), its detached runs are not
+reaped by the watcher. `systemd --user` units set `KillMode=control-group`, so
+the whole cgroup goes down with the service; launchd tracks only the job's own
+process group (`AbandonProcessGroup` is false, but agents run in their own
+groups), so on macOS an agent may outlive a crashed watcher. The restarted
+watcher takes over the dead one's claim and wakes the thread again (at-least-once):
+that thread can briefly have two agent runs.
+
+### Approvals: request fields, text rules and `courier approval`
+
+`courier request` writes structured fields into `me/requests/<id>.json`:
+`verb` (`merge`, `deploy`, `publish`, `spend` or `other`), `target` and
+`summary`. They are part of the request the hash covers; the view renders
+"Approving lets your agent <verb> <target> for <peer>: “<summary>”" (your own agent
+acts; the peer is who asked) from them; the guard
+matches the command it is about to allow to `verb` and `target` only. `action`
+(default: the summary), `reason` (`--why`) and `risk` are free text for the
+owner and are never matched.
+
+One rule set applies when `courier request` writes, when `courier approval`
+reads, and when the view shows the card. A value that breaks it is **refused,
+never repaired or shortened**:
+
+- text must already be Unicode NFC; it is never normalized or repaired. Non-ASCII
+  characters are allowed only from the frozen **Unicode 15.0.0** categories
+  Lu, Ll, Lt, Lo and Nd, excluding Default_Ignorable. Modifier letters (Lm),
+  other numbers (Nl/No), all combining marks, punctuation, symbols, controls,
+  invisible characters, fillers and unassigned/newer characters are refused;
+- U+0020 is the only space. `summary` additionally allows exactly these ASCII
+  punctuation characters: `. , : ; - _ / # ( ) ? !` and apostrophe U+0027.
+  Non-ASCII apostrophes, quotes and brackets are refused. `action`, `reason`,
+  `risk` and approval notes allow all printable ASCII punctuation and LF (`\n`),
+  never a tab or CR;
+- `target`, `summary`: 1 to 200 UTF-16 units, trimmed, one line; `action`,
+  `reason`, `risk`: 1 to 2000, a single `\n` allowed, never a tab or CR;
+- `target` is printable ASCII (`[\x20-\x7E]`) for every verb, in the one
+  canonical spelling for its verb (`courier request --help` prints these forms):
+
+  | verb | canonical target |
+  |---|---|
+  | `merge` | `owner/repo#<PR number>` (a GitHub PR URL is reduced to it), or `owner/repo@<branch>` for a direct push; repo lower-cased; the PR number is exactly the digits written, 1 to 9 of them, no leading zeros (nothing is ever rounded through a float) |
+  | `publish` | `npm:<name>@<version>`, `release:owner/repo@<tag>`, `changeset:<root package name>` or `script:<package>:<script>` |
+  | `deploy` | `wrangler:<worker>[:<env>]`, `pages:<project>`, `phala:<name>` or `script:<package>:<script>` |
+  | `other` | `workflow:owner/repo:<workflow file or name>`, `secrets:<subcommand and key>`, or `<kind>:<text>` |
+  | `spend` | `spend:<what and how much>` |
+
+The CLI and view share `src/text-ranges.ts` and
+`test/vectors/text-verdicts.json`; decisions use only that frozen table and an
+NFC check, never runtime Unicode property tables. The version is pinned to
+Unicode 15.0.0 (Node 20.0.0). The vector ranges cover all 1,114,112 code points
+for `summary`, `multiline` and `target`, plus full-string verdict/reason samples.
+`textVerdict(value: unknown, field: 'summary' | 'multiline' | 'target')` returns
+`{ allowed: boolean, reason: null | 'not-string' | 'empty' | 'too-long' |
+'edge-whitespace' | 'not-nfc' | 'disallowed-code-point' }`. Limits/trim rules are
+included; `multiline` is the action/reason/risk/note policy (an optional empty
+approval note is handled by the caller). Target shapes remain verb-specific.
+The pinned UCD source hashes and regeneration instructions are in
+`scripts/generate-text-table.mjs`. The independent test walks every code point
+using runtime Unicode categories: it fails if the table permits more, and
+reports newer runtime additions without permitting them.
+
+- `threadId`, `taskId` and the request id are ULIDs (26 upper-case Crockford
+  base32 characters, no I L O U), and the peer handle is 1 to 64 of
+  `[A-Za-z0-9_-]`, on write and on read (the view only shows cards for ULIDs);
+- the key set of `me/requests/<id>.json` is closed: `id`, `peer`, `threadId`,
+  `taskId`, `verb`, `target`, `summary`, `requestedBy` (`{owner, agent}`),
+  `createdAt`, `expiresAt`, `status` (`"pending"`) and the optional free text
+  `action`, `reason`, `risk` (written by the CLI, well-formed when present).
+  Anything else makes the request unreviewable in the view and refused by
+  `courier approval`, even if the hash matches;
+- the whole request must hash: `canonicalJson` / `requestHash` throw on a
+  non-finite number (a parsed `1e999`) and on nesting deeper than 64 levels
+  (top-level object = depth 1), so such a request is never written and
+  `courier approval` fails closed on it.
+
+`test/vectors/request-fields.json` is the contract: every row says whether a
+value is accepted, and the canonical-JSON rows give the expected output (or
+"must throw"). Copy it into any other implementation.
+
+`courier approval <requestId> --verb <v> --target <t> [--peek]` is what a
+woken agent runs before a gated action. It reads `me/requests/<id>.json` and
+`me/approvals/<id>.json` and exits 0 only if the request has valid structured
+fields, the approval names that request (`requestId` equals the id), carries
+`requestHash` equal to the SHA-256 of the request's canonical JSON
+(`canonicalJson` / `requestHash`, exported, mirrored by the view; a parsed
+`"__proto__"` key counts as an ordinary key), the request contains no hidden
+text anywhere (rules above, applied to every string and key), says `approved`, was decided in
+`[createdAt, expiresAt)` of the request (a decision dated up to 5 minutes ahead
+of this machine's clock is tolerated; keep the clocks of the agent's machine
+and the owner's browser in step) and within the last 24 hours, and the given
+`--verb` and (canonicalised) `--target` equal the request's. Both are required
+when consuming; `--peek` (for guards) may omit them.
+
+`courier request` and `courier approval` (peek and consume) print the full
+`requestHash`; the view's card shows its first 8 hex digits as a fingerprint so the owner can match the card to the agent's request.
+
+It then consumes the approval with a create-only marker at
+`me/state/approvals-used/<id>.json`, so a second run exits `approval-used`;
+`--peek` checks the marker too (a used approval fails the peek) but does not
+write it. A denial exits `approval-denied`. The courier key cannot write
+`me/approvals/`, so only the owner's view session can produce a passing
+approval. Residual risk: the courier grant can delete under `me/state/`
+(spec §3), so a compromised agent could delete the used marker and replay an
+approval within its 24 hours; a delete-proof record is tracked separately.
+
+The watcher wakes the thread's agent as soon as a new approval (approved or
+denied) for one of its requests appears, without the debounce. Approvals older
+than 24 hours, already used, malformed, or without a request at start-up wake
+nobody.
 
 ### Running it as a service
 

package/dist/approval.d.ts

@@ -0,0 +1,48 @@
+import type { KV } from './inbox.js';
+import type { ParsedArgs } from './args.js';
+/** An approval's stated decision on a request, as the view writes `me/approvals/<id>.json`. */
+export interface ApprovalRecord {
+    requestId: string;
+    requestHash: string;
+    decision: 'approved' | 'denied';
+    note: string;
+    decidedAt: string;
+}
+export interface VerifiedApproval {
+    requestId: string;
+    /** Lowercase hex SHA-256 of the request's canonical JSON; the view shows its first 8 digits as the card's fingerprint. */
+    requestHash: string;
+    decision: 'approved' | 'denied';
+    note: string;
+    decidedAt: string;
+    /** What was approved: matched against the command by `verb` and `target`, never by free text. */
+    verb: string;
+    target: string;
+    summary: string;
+    peer: string;
+    threadId: string;
+    taskId: string;
+}
+/**
+ * Spec §7: an approval covers one request and expires after 24 hours. Throws a CourierError with a stable code
+ * unless `approval` is a current, matching decision on `request` (denials are reported, not thrown).
+ */
+export declare function verifyApproval(id: string, request: unknown, approval: unknown, options?: {
+    now?: number;
+    verb?: string;
+    target?: string;
+}): VerifiedApproval;
+/**
+ * True if the approval was used (the marker under `me/state/approvals-used/`). Note the courier key can delete under
+ * `me/state/` (spec §3); a delete-proof record is being designed separately (G3), so this is the one place to change.
+ */
+export declare function approvalIsUsed(kv: KV, id: string): Promise<boolean>;
+/** Marks an approval used. The marker is create-only, so of two racing callers exactly one wins. */
+export declare function consumeApproval(kv: KV, id: string, at?: Date): Promise<void>;
+export declare const approvalUsage: () => string;
+/**
+ * `courier approval <id> --verb V --target T`: exit 0 and consume the approval only if the owner approved this exact
+ * request (its structured verb and target equal yours), within 24 hours, and nobody has used it. `--peek` verifies
+ * without consuming (for guards) and fails the same way for a used approval. A denial exits non-zero.
+ */
+export declare function cmdApproval(args: ParsedArgs): Promise<void>;

package/dist/approval.js

@@ -0,0 +1,181 @@
+import { CourierError } from './errors.js';
+import { k } from './keys.js';
+import { isRecord } from './a2a.js';
+import { requestHash } from './canonical.js';
+import { requestShapeProblem, storedRequestFields } from './request.js';
+import { allStrings, hiddenTextProblem, MAX_ACTION, MAX_REASON, MAX_RISK, plainLineProblem, plainTextProblem } from './text.js';
+import { canonicalTarget, targetHelp } from './guard/target.js';
+import { getJson, putCreate } from './store.js';
+import { cmd } from './program.js';
+import { courierNode } from './node.js';
+import { loadProfile } from './profile.js';
+import { writeOut } from './inbox.js';
+const DAY_MS = 24 * 3600 * 1000;
+const MAX_NOTE = 2000;
+/** The view stamps `decidedAt` with the browser's clock; a decision dated slightly ahead of this machine's clock is tolerated. */
+const FUTURE_SKEW_MS = 5 * 60 * 1000;
+function fail(code, message) {
+    throw new CourierError(code, message);
+}
+function ms(value, what) {
+    const parsed = typeof value === 'string' ? Date.parse(value) : NaN;
+    if (!Number.isFinite(parsed))
+        fail('approval-mismatch', `${what} is not a valid timestamp.`);
+    return parsed;
+}
+/**
+ * Spec §7: an approval covers one request and expires after 24 hours. Throws a CourierError with a stable code
+ * unless `approval` is a current, matching decision on `request` (denials are reported, not thrown).
+ */
+export function verifyApproval(id, request, approval, options = {}) {
+    const now = options.now ?? Date.now();
+    if (!isRecord(request) || request.id !== id)
+        fail('approval-mismatch', `me/requests/${id}.json is missing or its id is not "${id}".`);
+    if (!isRecord(approval))
+        fail('approval-missing', `No approval for request ${id} yet.`);
+    if (approval.requestId !== id)
+        fail('approval-mismatch', `Approval ${id}.json names request "${String(approval.requestId)}", not "${id}".`);
+    if (approval.decision !== 'approved' && approval.decision !== 'denied') {
+        fail('approval-mismatch', `Approval decision must be "approved" or "denied" (got ${JSON.stringify(approval.decision)}).`);
+    }
+    // Fail closed on a request that cannot be hashed (non-finite number, absurd nesting) or hides text from the reader.
+    let hash;
+    try {
+        hash = requestHash(request);
+    }
+    catch (error) {
+        fail('approval-mismatch', `The request cannot be verified: ${error.message}`);
+    }
+    for (const text of allStrings(request)) {
+        const problem = hiddenTextProblem(text, true);
+        if (problem)
+            fail('approval-mismatch', `The request contains text a person could not read as written (${problem}); it cannot be approved. File a new \`courier request\`.`);
+    }
+    if (approval.requestHash !== hash) {
+        fail('approval-mismatch', `Approval ${id} was not made for this request as stored (hash mismatch): the request changed after the decision.`);
+    }
+    // Everything of the approval that is echoed to the agent is swept like the request: no hidden text.
+    const noteProblem = approval.note === undefined || approval.note === '' ? undefined : plainTextProblem(approval.note, MAX_NOTE);
+    if (typeof approval.note !== 'string' && approval.note !== undefined)
+        fail('approval-mismatch', 'The approval note is not text.');
+    if (noteProblem)
+        fail('approval-mismatch', `The approval note is refused: ${noteProblem}.`);
+    const stampProblem = plainLineProblem(approval.decidedAt, 40);
+    if (stampProblem)
+        fail('approval-mismatch', `decidedAt is refused: ${stampProblem}.`);
+    const decidedAt = ms(approval.decidedAt, 'decidedAt');
+    const created = ms(request.createdAt, 'request createdAt');
+    const expires = ms(request.expiresAt, 'request expiresAt');
+    // Spec §7: the decision lies in [createdAt, expiresAt). Both timestamps come from different clocks; that is why the
+    // README asks for them to agree.
+    if (decidedAt < created)
+        fail('approval-mismatch', 'The decision is dated before the request existed.');
+    if (decidedAt > now + FUTURE_SKEW_MS)
+        fail('approval-mismatch', 'The decision is dated in the future.');
+    if (decidedAt >= expires)
+        fail('approval-expired', 'The decision came after the request expired.');
+    if (now - decidedAt >= DAY_MS)
+        fail('approval-expired', 'The approval is older than 24 hours; ask your owner again.');
+    if (typeof request.peer !== 'string' || typeof request.threadId !== 'string' || typeof request.taskId !== 'string') {
+        fail('approval-mismatch', 'The request is missing peer, threadId or taskId.');
+    }
+    const shape = requestShapeProblem(request);
+    if (shape)
+        fail('approval-mismatch', `The request is not in the form \`courier request\` writes (${shape}); it cannot be approved. File a new \`courier request\`.`);
+    // The free text is only displayed, but the owner read it: whatever is present must be well-formed text, never empty.
+    for (const [name, max] of [['action', MAX_ACTION], ['reason', MAX_REASON], ['risk', MAX_RISK]]) {
+        if (name in request && plainTextProblem(request[name], max))
+            fail('approval-mismatch', `The request's ${name} is empty, too long or not plain text; it cannot be approved. File a new \`courier request\`.`);
+    }
+    const fields = storedRequestFields(request);
+    if (!fields) {
+        fail('approval-mismatch', 'The request has no valid structured verb, target and summary (an older request, or a hand-written one); it cannot be approved. File a new `courier request`.');
+    }
+    if (options.verb !== undefined && options.verb !== fields.verb) {
+        fail('approval-mismatch', `The approval is for "${fields.verb}", not "${options.verb}".`);
+    }
+    if (options.target !== undefined && options.target !== fields.target) {
+        fail('approval-mismatch', `The approval is for target ${JSON.stringify(fields.target)}, not ${JSON.stringify(options.target)}.`);
+    }
+    return {
+        requestId: id,
+        requestHash: hash,
+        decision: approval.decision,
+        note: typeof approval.note === 'string' ? approval.note : '',
+        decidedAt: approval.decidedAt,
+        verb: fields.verb,
+        target: fields.target,
+        summary: fields.summary,
+        peer: request.peer,
+        threadId: request.threadId,
+        taskId: request.taskId,
+    };
+}
+/**
+ * True if the approval was used (the marker under `me/state/approvals-used/`). Note the courier key can delete under
+ * `me/state/` (spec §3); a delete-proof record is being designed separately (G3), so this is the one place to change.
+ */
+export async function approvalIsUsed(kv, id) {
+    return Boolean(await getJson(kv, k.approvalUsed(id)));
+}
+/** Marks an approval used. The marker is create-only, so of two racing callers exactly one wins. */
+export async function consumeApproval(kv, id, at = new Date()) {
+    try {
+        await putCreate(kv, k.approvalUsed(id), { requestId: id, usedAt: at.toISOString() });
+    }
+    catch (error) {
+        if (error instanceof CourierError && error.code === 'conflict')
+            fail('approval-used', `Approval ${id} was already used; an approval covers one action.`);
+        throw error;
+    }
+}
+const SAFE = /^[0-9A-Za-z_-]{1,64}$/;
+export const approvalUsage = () => `Usage: ${cmd('approval <id> --verb <v> --target <t> [--peek]')} (--verb and --target may be omitted with --peek)`;
+/**
+ * `courier approval <id> --verb V --target T`: exit 0 and consume the approval only if the owner approved this exact
+ * request (its structured verb and target equal yours), within 24 hours, and nobody has used it. `--peek` verifies
+ * without consuming (for guards) and fails the same way for a used approval. A denial exits non-zero.
+ */
+export async function cmdApproval(args) {
+    const id = args.positional[0] ?? fail('usage', approvalUsage());
+    if (!SAFE.test(id))
+        fail('usage', `"${id}" is not a request id. ${approvalUsage()}`);
+    if (args.has('action')) {
+        fail('usage', `--action no longer exists: an approval is bound to what you are about to do by --verb and --target. ${approvalUsage()}\n${targetHelp()}`);
+    }
+    const flag = (name) => {
+        if (!args.has(name))
+            return undefined;
+        const value = args.get(name);
+        if (value === 'true' || value === '')
+            fail('usage', `--${name} needs a value.`);
+        return value;
+    };
+    const verb = flag('verb');
+    const rawTarget = flag('target');
+    if ((verb === undefined) !== (rawTarget === undefined))
+        fail('usage', `--verb and --target go together. ${approvalUsage()}`);
+    if (verb === undefined && !args.has('peek'))
+        fail('usage', `Say what you are about to do, so the approval is bound to it. ${approvalUsage()}\n${targetHelp()}`);
+    const target = verb !== undefined ? canonicalTarget(verb, rawTarget) : undefined;
+    const node = await courierNode(loadProfile());
+    const request = await getJson(node.kv, k.request(id));
+    if (!request)
+        fail('approval-mismatch', `No request ${id} in me/requests/.`);
+    const approval = await getJson(node.kv, k.approval(id));
+    if (!approval)
+        fail('approval-missing', `No approval for request ${id} yet. Your owner decides in the view or in your chat; stop and wait.`);
+    const verified = verifyApproval(id, request.value, approval.value, { verb, target });
+    if (verified.decision === 'denied') {
+        await writeOut(`${JSON.stringify({ ok: false, code: 'approval-denied', ...verified }, null, 2)}\n`);
+        throw new CourierError('approval-denied', `Your owner denied request ${id}${verified.note ? `: ${verified.note}` : ''}. Do not take the action.`);
+    }
+    if (await approvalIsUsed(node.kv, id)) {
+        await writeOut(`${JSON.stringify({ ok: false, code: 'approval-used', requestId: id }, null, 2)}\n`);
+        throw new CourierError('approval-used', `Approval ${id} was already used; an approval covers one action.`);
+    }
+    if (!args.has('peek'))
+        await consumeApproval(node.kv, id);
+    await writeOut(`${JSON.stringify({ ok: true, consumed: !args.has('peek'), ...verified }, null, 2)}\n`);
+}
+//# sourceMappingURL=approval.js.map

package/dist/approval.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval.js","sourceRoot":"","sources":["../src/approval.ts"],"names":[],"mappings":"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"}

package/dist/canonical.d.ts

@@ -0,0 +1,14 @@
+/** Deepest nesting `canonicalJson` accepts: a top-level object or array is depth 1. Shared with the view. */
+export declare const MAX_CANONICAL_DEPTH = 64;
+/**
+ * Canonical JSON for hashing: object keys sorted recursively in UTF-16 code-unit order (integer-like keys too: `{"10":1,"9":2}`
+ * is `{"10":1,"9":2}`), no whitespace, arrays in order, values as `JSON.stringify` writes them. The `/courier` view mirrors this function: an
+ * approval's `requestHash` is `requestHash(<parsed me/requests/<id>.json>)`, so both sides must agree byte for byte.
+ *
+ * Throws `CourierError('canonical-invalid')` for a non-finite number (a parsed `1e999` is Infinity, which
+ * `JSON.stringify` would silently turn into `null`) and for nesting deeper than {@link MAX_CANONICAL_DEPTH}: a
+ * request like that is never written and never approved.
+ */
+export declare function canonicalJson(value: unknown): string;
+/** Lowercase hex SHA-256 of the UTF-8 bytes of {@link canonicalJson}. Throws like it. */
+export declare function requestHash(request: unknown): string;

package/dist/canonical.js

@@ -0,0 +1,39 @@
+import { createHash } from 'node:crypto';
+import { CourierError } from './errors.js';
+/** Deepest nesting `canonicalJson` accepts: a top-level object or array is depth 1. Shared with the view. */
+export const MAX_CANONICAL_DEPTH = 64;
+/**
+ * Canonical JSON for hashing: object keys sorted recursively in UTF-16 code-unit order (integer-like keys too: `{"10":1,"9":2}`
+ * is `{"10":1,"9":2}`), no whitespace, arrays in order, values as `JSON.stringify` writes them. The `/courier` view mirrors this function: an
+ * approval's `requestHash` is `requestHash(<parsed me/requests/<id>.json>)`, so both sides must agree byte for byte.
+ *
+ * Throws `CourierError('canonical-invalid')` for a non-finite number (a parsed `1e999` is Infinity, which
+ * `JSON.stringify` would silently turn into `null`) and for nesting deeper than {@link MAX_CANONICAL_DEPTH}: a
+ * request like that is never written and never approved.
+ */
+export function canonicalJson(value) {
+    return canonicalize(value, 1);
+}
+/** Built as a string from the sorted entries (never by rebuilding an object, whose integer-like keys JS would reorder numerically). */
+function canonicalize(value, depth) {
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            throw new CourierError('canonical-invalid', 'Not hashable: a number is not finite (for example 1e999).');
+        return JSON.stringify(value);
+    }
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value) ?? 'null';
+    if (depth > MAX_CANONICAL_DEPTH)
+        throw new CourierError('canonical-invalid', `Not hashable: nested deeper than ${MAX_CANONICAL_DEPTH} levels.`);
+    if (Array.isArray(value))
+        return `[${value.map((item) => canonicalize(item, depth + 1)).join(',')}]`;
+    const source = value;
+    // Default sort order is UTF-16 code-unit order, as specified. A parsed "__proto__" key is an own key and is kept.
+    const entries = Object.keys(source).sort().flatMap((key) => (source[key] === undefined ? [] : [`${JSON.stringify(key)}:${canonicalize(source[key], depth + 1)}`]));
+    return `{${entries.join(',')}}`;
+}
+/** Lowercase hex SHA-256 of the UTF-8 bytes of {@link canonicalJson}. Throws like it. */
+export function requestHash(request) {
+    return createHash('sha256').update(canonicalJson(request), 'utf8').digest('hex');
+}
+//# sourceMappingURL=canonical.js.map

package/dist/canonical.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical.js","sourceRoot":"","sources":["../src/canonical.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,6GAA6G;AAC7G,MAAM,CAAC,MAAM,mBAAmB,GAAG,EAAE,CAAC;AAEtC;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAO,YAAY,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;AAChC,CAAC;AAED,uIAAuI;AACvI,SAAS,YAAY,CAAC,KAAc,EAAE,KAAa;IACjD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;YAAE,MAAM,IAAI,YAAY,CAAC,mBAAmB,EAAE,2DAA2D,CAAC,CAAC;QACtI,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;IACD,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC;IACxF,IAAI,KAAK,GAAG,mBAAmB;QAAE,MAAM,IAAI,YAAY,CAAC,mBAAmB,EAAE,oCAAoC,mBAAmB,UAAU,CAAC,CAAC;IAChJ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IACrG,MAAM,MAAM,GAAG,KAAgC,CAAC;IAChD,kHAAkH;IAClH,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,YAAY,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACnK,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;AAClC,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,WAAW,CAAC,OAAgB;IAC1C,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACnF,CAAC"}

package/dist/commands.d.ts

@@ -17,4 +17,6 @@ export declare function cmdRead(args: ParsedArgs): Promise<void>;
 export declare function renderThreadText(threadId: string, entries: readonly ThreadEntry[]): string;
 export declare function cmdTask(args: ParsedArgs): Promise<void>;
 export declare function cmdRequest(args: ParsedArgs): Promise<void>;
+/** `courier request --help`: the usage line and every target form. */
+export declare const requestHelp: () => string;
 export declare function cmdOrders(args: ParsedArgs): Promise<void>;

package/dist/commands.js

@@ -14,6 +14,9 @@ import { authRequiredTask, buildMessage, buildTask, COUNTERPARTY_NOTICE, isRecor
 import { commitReceipts, collectInbound, renderInboxText, writeOut } from './inbox.js';
 import { getJson, listAll, putCreate, putMatch, del } from './store.js';
 import { DEFAULT_ORDERS } from './orders.js';
+import { requestFields, requestIds, requestShapeProblem, requestText } from './request.js';
+import { requestHash } from './canonical.js';
+import { targetHelp } from './guard/target.js';
 import { requireFlag, oneOf } from './args.js';
 import { assertPeerDelegation, bareDid, durationMs, AGENT_GRANT_MAX_MS } from './authority.js';
 async function ctx() {
@@ -597,21 +600,29 @@ export async function cmdRequest(args) {
     const { profile, node } = await ctx();
     const threadId = args.positional[0] ?? fail('usage', requestUsage());
     const taskId = requireFlag(args, 'task', requestUsage());
-    const action = requireFlag(args, 'action', requestUsage());
     const why = requireFlag(args, 'why', requestUsage());
     const peerHandle = requireFlag(args, 'peer', requestUsage());
     getPeer(profile, peerHandle);
+    const flag = (name) => (args.get(name) === 'true' ? undefined : args.get(name));
+    requestIds({ threadId, taskId });
+    const fields = requestFields({ verb: flag('verb'), target: flag('target'), summary: flag('summary') });
     const risk = args.get('risk');
     const id = ulid();
     const request = {
-        id, peer: peerHandle, threadId, taskId, action, reason: why,
-        risk: risk ?? 'unspecified',
+        id, peer: peerHandle, threadId, taskId, ...fields,
+        // Free text for the owner to read; nothing matches against it (the structured fields above do that).
+        ...requestText({ action: flag('action'), reason: why, risk }, fields.summary),
         requestedBy: { owner: profile.ownerDid, agent: profile.courierDid },
         createdAt: new Date().toISOString(),
         expiresAt: new Date(Date.now() + 24 * 3600 * 1000).toISOString(),
         status: 'pending',
     };
-    await putCreate(node.kv, k.request(id), request);
+    const hash = requestHash(request); // refuses (throws) a request that could never be hashed or approved, before anything is written
+    const problem = requestShapeProblem(request);
+    if (problem)
+        fail('usage', `The request is malformed: ${problem}.`);
+    // The task comes first: the view names <peer> on the card only if `to/<peer>/threads/<thread>/task/<task>.json`
+    // exists in this space, so the request is not written unless that file does (created here if the agent has not yet).
     const taskKey = k.task(peerHandle, threadId, taskId);
     const existing = await getJson(node.kv, taskKey);
     const task = authRequiredTask(existing?.value, threadId, taskId);
@@ -619,9 +630,15 @@ export async function cmdRequest(args) {
         await putMatch(node.kv, taskKey, task, existing.etag);
     else
         await putCreate(node.kv, taskKey, task);
-    printJson({ ok: true, requestId: id, taskId, state: 'TASK_STATE_AUTH_REQUIRED' });
+    if (!(await getJson(node.kv, taskKey)))
+        fail('task-missing', `The task ${taskId} is not in ${taskKey}; no request was written.`);
+    await putCreate(node.kv, k.request(id), request);
+    // `requestHash` is what the view's card shows as its fingerprint (first 8 hex digits) and `courier approval` prints in full.
+    printJson({ ok: true, requestId: id, requestHash: hash, taskId, state: 'TASK_STATE_AUTH_REQUIRED' });
 }
-const requestUsage = () => `Usage: ${cmd('request <threadId> --peer <p> --task <id> --action "…" --why "…" [--risk "…"]')}`;
+const requestUsage = () => `Usage: ${cmd('request <threadId> --peer <p> --task <id> --verb merge|deploy|publish|spend|other --target <what> --summary "…" --why "…" [--risk "…"] [--action "…"]')}\n${targetHelp()}`;
+/** `courier request --help`: the usage line and every target form. */
+export const requestHelp = () => `${requestUsage()}\n`;
 // ---------- orders ----------
 export async function cmdOrders(args) {
     const { profile, node } = await ctx();