totemlayer 0.1.0 → 0.1.1

package/README.md

@@ -10,7 +10,21 @@ Node.js 22.14 or newer is required.
 
 ```bash
 npm install --global totemlayer
-totem --help
+totem
+```
+
+Running `totem` opens the branded command guide, confirms the installed version,
+and shows the complete challenge → presentation → verification flow. Interactive
+commands return a readable result card with the decision, relevant evidence, and
+the safest next step. Add `--json` when the output is being saved or consumed by
+another program; machine-readable output remains undecorated JSON.
+
+```text
+       ╭╮
+   ╭───╯╰────╮   ╺┳╸┏━┓╺┳╸┏━╸┏┳┓
+  ╰────╮╭────╯    ┃ ┃ ┃ ┃ ┣╸ ┃┃┃
+       ╰╯          ╹ ┗━┛ ╹ ┗━╸╹ ╹
+TotemLayer CLI 0.1.1 · cross-company agent authorization
 ```
 
 For a one-off run without a global install:

package/bin/totem.mjs

@@ -6,7 +6,7 @@ import { stripVTControlCharacters } from "node:util";
 
 const RFQ_EXAMPLE =
   "Request a quote for 50,000 Industrial Sensors (SKU-1001) from SupplyCo using Acme Procurement Agent.";
-const CLI_VERSION = "0.1.0";
+const CLI_VERSION = "0.1.1";
 const DEFAULT_BASE_URL = "https://totemlayer.com";
 const API_KEY_PATTERN = /^at_(?:live|test)_[A-Za-z0-9_-]{20,}$/;
 const ACTION_PATTERN = /^[a-z0-9][a-z0-9._:-]*$/;
@@ -16,6 +16,12 @@ const TERMINAL_UNSAFE_PATTERN =
   /[\u0000-\u001f\u007f-\u009f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/g;
 const MAX_JSON_INPUT_BYTES = 128 * 1_024;
 const MAX_REQUEST_FILE_BYTES = 16 * 1_024 * 1_024;
+const BRAND_ART = [
+  "       ╭╮",
+  "   ╭───╯╰────╮   ╺┳╸┏━┓╺┳╸┏━╸┏┳┓",
+  "  ╰────╮╭────╯    ┃ ┃ ┃ ┃ ┣╸ ┃┃┃",
+  "       ╰╯          ╹ ┗━┛ ╹ ┗━╸╹ ╹",
+];
 const PRESENTATION_REJECTION_CODES = new Set([
   "CHALLENGE_NOT_FOUND",
   "CHALLENGE_NOT_PRESENTED",
@@ -29,20 +35,91 @@ const PRESENTATION_REJECTION_CODES = new Set([
   "INVALID_PRESENTATION_SIGNATURE",
   "PRESENTATION_CLAIMS_MISMATCH",
 ]);
+const ACTION_CHECK_POLICY_CODES = new Set([
+  "ACTION_APPROVAL_REQUIRED",
+  "ACTION_APPROVAL_STALE",
+  "ACTION_AUTHORITY_CHANGED",
+  "ACTION_CHECKS_NOT_ALLOWED",
+  "ACTION_CONFIRMATION_MISMATCH",
+  "ACTION_DIGEST_MISMATCH",
+  "ACTION_EXECUTION_ATTEMPT_CONFLICT",
+  "ACTION_EXPIRED",
+  "ACTION_FINAL_CHECKS_FAILED",
+  "ACTION_GRANT_BINDING_MISMATCH",
+  "ACTION_GRANT_EXPIRED",
+  "ACTION_GRANT_INVALID",
+  "ACTION_GRANT_REPLAYED",
+  "ACTION_POLICY_CHANGED",
+  "ACTION_RECEIPT_STATE_CHANGED",
+  "ACTION_SUITE_EXPIRED",
+  "ACTION_SUITE_INCOMPLETE",
+  "ACTION_SUITE_STALE",
+  "ACTION_SUITE_STATE_CHANGED",
+  "DEMO_FIXTURE_INACTIVE",
+  "DEMO_FIXTURE_NOT_OWNED",
+  "DESTRUCTIVE_TARGET_UNCONSTRAINED",
+  "EXECUTOR_ADAPTER_MISMATCH",
+  "EXECUTOR_ADAPTER_NOT_PUBLIC",
+  "FINANCIAL_CONTEXT_MISSING",
+]);
 
-function help() {
-  process.stdout.write(`TotemLayer CLI ${CLI_VERSION}
+function supportsColor(stream = process.stdout) {
+  return Boolean(stream.isTTY && !process.env.NO_COLOR && process.env.TERM !== "dumb");
+}
+
+function styled(value, code, stream = process.stdout) {
+  return supportsColor(stream) ? `\u001b[${code}m${value}\u001b[0m` : value;
+}
 
-Install:
-  npm install --global totemlayer
-  npx --yes totemlayer --help
+function writeBrand() {
+  const art = BRAND_ART.map((line, index) =>
+    styled(line, index < 2 ? "38;2;58;153;200" : "38;2;21;37;131"),
+  ).join("\n");
+  process.stdout.write(`${art}\n`);
+  process.stdout.write(
+    `${styled(`TotemLayer CLI ${CLI_VERSION}`, "1")} · cross-company agent authorization\n\n`,
+  );
+}
+
+function writeHumanResult(header, fields, nextStep, tone = "success") {
+  const toneCode = tone === "danger" ? "38;2;255;114;114" : "38;2;58;153;200";
+  process.stdout.write(`${styled(header, `1;${toneCode}`)}\n`);
+  process.stdout.write(`${styled("────────────────────────────────────────", "2")}\n`);
+  for (const [label, value] of fields) {
+    if (value === undefined || value === null || value === "") continue;
+    process.stdout.write(`${styled(`${label}:`, "2")} ${terminalText(value)}\n`);
+  }
+  if (nextStep) process.stdout.write(`\n${styled("Next →", "1")} ${nextStep}\n`);
+}
 
-Usage:
+function compactDigest(value) {
+  const digest = terminalText(value, "not returned");
+  return digest.length > 28 ? `${digest.slice(0, 16)}…${digest.slice(-8)}` : digest;
+}
+
+function help() {
+  writeBrand();
+  process.stdout.write(`Start here
+  Install once          npm install --global totemlayer
+  Confirm installation totem --version
+  Run one-off           npx --yes totemlayer --help
+
+Authorization handshake
   totem challenge --presenter-agent <agent-id> --action <action> \\
     (--request-digest <sha256> | --request-file <path>) [--amount <number> --currency <ISO-4217>] --json
   totem present --credential-id <credential-id> [--challenge-file <path>] --json
   totem verify --challenge-file <receiver-challenge.json> \\
     (--request-digest <sha256> | --request-file <path>) [--presentation-file <path>] --json
+
+Action Checks · local or self-hosted
+  totem checks run --file <action.json>
+  totem checks view <suite-id>
+  totem checks approve <suite-id> [--file <decision.json>]
+  totem checks reject <suite-id> [--file <decision.json>]
+  totem checks grant <suite-id> --file <action.json>
+  totem checks execute <suite-id> --file <execution.json>
+
+Procurement demonstration
   totem rfq "${RFQ_EXAMPLE}"  # sandbox/self-hosted demo only
 
 Shared options:
@@ -71,18 +148,38 @@ Presentation input:
   compares it with the receiver-owned --challenge-file before consuming the proof.
   Raw keys, nonces, credentials, and presentation tokens are never accepted as arguments.
 
+Action Checks input (local/self-hosted only):
+  --file <path>             run/grant: exact action JSON; execute: {"action":...,"grant":"..."}
+  decision.json             Optional {"confirmation":"...","reason":"..."}; never put the
+                            confirmation, grant, session cookie, or action payload on the command line
+  Action Checks always emit structured JSON. A blocked, rejected, expired, stale, or replayed
+  action exits 2; invalid input, network, authentication, and operational failures exit 1.
+
 Authentication:
   challenge and verify use TOTEM_API_KEY.
   present uses TOTEM_AGENT_API_KEY bound to the presenting agent.
+  checks run/view/grant/execute use TOTEM_API_KEY with an Action Checks scope.
+  checks approve/reject never use an API key. They require an authenticated human browser
+  session supplied only through TOTEM_SESSION_COOKIE as a Cookie header value. Clear it after
+  the command. Without it, use the /checks browser page.
   Keys are sent only in the Authorization header and are never printed.
 
-Production supports challenge, present, and verify. The RFQ command requires a
-sandbox or self-hosted Totem deployment with the procurement demo enabled.
+Production supports challenge, present, and verify. Action Checks and RFQ commands require a
+sandbox or self-hosted Totem deployment with their respective local demonstrations enabled.
+
+Human-readable commands show the decision, relevant evidence, and the safest next step.
+Add --json whenever another program needs the complete machine-readable response.
 `);
 }
 
 function fail(message) {
-  process.stderr.write(`Totem: ${terminalText(message, "The Totem command failed.")}\n`);
+  process.stderr.write(
+    `${styled("Totem: command failed", "1;38;2;255;114;114", process.stderr)}\n`,
+  );
+  process.stderr.write(`Reason: ${terminalText(message, "The Totem command failed.")}\n`);
+  process.stderr.write(
+    "Next: Fix the reason above, or run `totem --help` for a complete example.\n",
+  );
   process.exitCode = 1;
 }
 
@@ -118,6 +215,7 @@ function parseArguments(values) {
     "--challenge-file",
     "--credential-id",
     "--presentation-file",
+    "--file",
   ]);
   for (let index = 0; index < values.length; index += 1) {
     const value = values[index];
@@ -162,6 +260,14 @@ function safeBaseUrl(value) {
   return url;
 }
 
+function requireLocalActionChecks(baseUrl) {
+  if (baseUrl.origin === DEFAULT_BASE_URL) {
+    throw new Error(
+      "Action Checks commands are available only on a local or self-hosted Totem deployment. Set TOTEM_URL to that deployment; use the /checks browser page for human decisions.",
+    );
+  }
+}
+
 function aliasedEnvironment(primaryName, legacyName) {
   const primary = process.env[primaryName]?.trim();
   const legacy = process.env[legacyName]?.trim();
@@ -181,6 +287,45 @@ function apiKey(environmentName, legacyEnvironmentName) {
   return value;
 }
 
+function actionCheckSessionCookie() {
+  const raw = process.env.TOTEM_SESSION_COOKIE;
+  if (!raw?.trim()) {
+    throw new Error(
+      "Action check decisions require an authenticated human browser session. Open the local /checks page, or set TOTEM_SESSION_COOKIE from your own current browser session. API keys cannot approve or reject.",
+    );
+  }
+  const value = raw.trim();
+  if (value.length > 16 * 1_024 || /[\u0000-\u001f\u007f]/.test(value)) {
+    throw new Error("TOTEM_SESSION_COOKIE is not a valid browser Cookie header.");
+  }
+  const pairs = value
+    .split(";")
+    .map((pair) => pair.trim())
+    .filter(Boolean);
+  let hasSessionCookie = false;
+  for (const pair of pairs) {
+    const separator = pair.indexOf("=");
+    const name = separator > 0 ? pair.slice(0, separator) : "";
+    const cookieValue = separator > 0 ? pair.slice(separator + 1) : "";
+    if (
+      !/^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/.test(name) ||
+      !cookieValue ||
+      /[\u0000-\u0020\u007f;]/.test(cookieValue)
+    ) {
+      throw new Error("TOTEM_SESSION_COOKIE is not a valid browser Cookie header.");
+    }
+    if (/^(?:__Secure-)?(?:next-auth|authjs)\.session-token(?:\.\d+)?$/.test(name)) {
+      hasSessionCookie = true;
+    }
+  }
+  if (!hasSessionCookie) {
+    throw new Error(
+      "TOTEM_SESSION_COOKIE does not contain a Totem browser session. Open the local /checks page to approve or reject instead; API keys cannot make human decisions.",
+    );
+  }
+  return value;
+}
+
 function errorFrom(payload, fallback) {
   if (!payload || typeof payload !== "object") return fallback;
   const error = payload.error;
@@ -190,6 +335,45 @@ function errorFrom(payload, fallback) {
   return `${code}: ${message}`;
 }
 
+function redactCliSecrets(value, secrets) {
+  let redacted = terminalText(value, "The Action Checks request failed.");
+  for (const secret of secrets) {
+    if (typeof secret === "string" && secret.length >= 8)
+      redacted = redacted.replaceAll(secret, "[REDACTED]");
+  }
+  return redacted;
+}
+
+function writeActionCheckFailure(payload, fallback, status, secrets = []) {
+  const error = record(record(payload)?.error);
+  const code = redactCliSecrets(
+    typeof error?.code === "string" ? error.code : "ACTION_CHECK_REQUEST_FAILED",
+    secrets,
+  );
+  const message = redactCliSecrets(
+    typeof error?.message === "string" ? error.message : fallback,
+    secrets,
+  );
+  const safePayload = { error: { code, message } };
+  writeJson(safePayload);
+  const policyRejection =
+    status < 500 &&
+    (ACTION_CHECK_POLICY_CODES.has(code) ||
+      (status === 409 && code !== "ACTION_APPROVAL_NOT_REQUIRED"));
+  process.exitCode = policyRejection ? 2 : 1;
+}
+
+function writeActionCheckOperationalError(message, outcome) {
+  writeJson({
+    error: {
+      code: "ACTION_CHECK_OPERATIONAL_ERROR",
+      message: terminalText(message, "The Action Checks command failed."),
+      ...(outcome ? { outcome } : {}),
+    },
+  });
+  process.exitCode = 1;
+}
+
 function number(value) {
   return typeof value === "number" && Number.isFinite(value) ? value.toLocaleString("en-US") : "—";
 }
@@ -237,6 +421,7 @@ function validateCommandOptions(command, options) {
       "request_digest",
       "request_file",
     ]),
+    checks: new Set([...shared, "file"]),
   }[command];
   if (!allowed) throw new Error(`Unknown command ${command || "(missing)"}.`);
   for (const [key, value] of Object.entries(options)) {
@@ -451,18 +636,28 @@ function boundPresentationClaims(token, challenge, credentialId, expiresAt) {
   return claims;
 }
 
-async function requestJson({ baseUrl, path, key, body, idempotencyKey, timeout = 30_000 }) {
-  const headers = {
-    authorization: `Bearer ${key}`,
-    "content-type": "application/json",
-  };
+async function requestJson({
+  baseUrl,
+  path,
+  key,
+  cookie,
+  method = "POST",
+  body,
+  idempotencyKey,
+  timeout = 30_000,
+}) {
+  const headers = { accept: "application/json" };
+  if (key) headers.authorization = `Bearer ${key}`;
+  if (cookie) headers.cookie = cookie;
+  if (body !== undefined) headers["content-type"] = "application/json";
   if (idempotencyKey) headers["idempotency-key"] = idempotencyKey;
   let response;
   try {
     response = await fetch(new URL(path, baseUrl), {
-      method: "POST",
+      method,
       headers,
-      body: JSON.stringify(body),
+      ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+      redirect: "manual",
       signal: AbortSignal.timeout(timeout),
     });
   } catch (error) {
@@ -552,11 +747,24 @@ async function runChallenge(options, baseUrl) {
   }
   if (options.json) writeJson(result.payload);
   else {
-    process.stdout.write(`Totem challenge · ${terminalText(challenge.id)}\n`);
-    process.stdout.write(`Action: ${terminalText(challenge.requestedAction ?? requestedAction)}\n`);
-    process.stdout.write(`Expires: ${terminalText(challenge.expiresAt)}\n`);
-    process.stdout.write(
-      "Use --json to emit the nonce-bearing challenge for the presenting agent.\n",
+    writeHumanResult(
+      `Totem challenge · ${terminalText(challenge.id)}`,
+      [
+        [
+          "Status",
+          result.payload?.replayed ? "READY · existing idempotent result" : "READY · created",
+        ],
+        ["Presenter", challenge.presenterAgentId ?? presenterAgentId],
+        ["Action", challenge.requestedAction ?? requestedAction],
+        ["Request", compactDigest(challenge.requestDigest ?? requestDigest)],
+        [
+          "Transaction",
+          transactionAmount !== undefined ? `${number(transactionAmount)} ${currency}` : undefined,
+        ],
+        ["Expires", challenge.expiresAt],
+        ["Protection", "Recipient-bound · request-bound · single-use"],
+      ],
+      "Run again with --json to save the nonce-bearing challenge for the presenting agent.",
     );
   }
 }
@@ -593,8 +801,16 @@ async function runPresent(options, baseUrl) {
     if (typeof apiError?.code === "string" && PRESENTATION_REJECTION_CODES.has(apiError.code)) {
       if (options.json) writeJson(result.payload);
       else {
-        process.stdout.write("Totem presentation · REJECTED\n");
-        process.stdout.write(`Reason: ${apiError.code}\n`);
+        writeHumanResult(
+          "Totem presentation · REJECTED",
+          [
+            ["Status", "Proof was not created"],
+            ["Challenge", challengeId],
+            ["Reason", apiError.code],
+          ],
+          "Return to the receiver for a fresh challenge before trying again.",
+          "danger",
+        );
       }
       process.exitCode = 2;
       return;
@@ -617,10 +833,19 @@ async function runPresent(options, baseUrl) {
   }
   if (options.json) writeJson(result.payload);
   else {
-    process.stdout.write(`Totem presentation · ${terminalText(presentation.challengeId)}\n`);
-    process.stdout.write(`Credential: ${terminalText(presentation.credentialId)}\n`);
-    process.stdout.write(`Expires: ${terminalText(presentation.expiresAt)}\n`);
-    process.stdout.write("Use --json to emit the token-bearing presentation for the verifier.\n");
+    writeHumanResult(
+      `Totem presentation · ${terminalText(presentation.challengeId)}`,
+      [
+        ["Status", "READY · signed proof created"],
+        ["Challenge", presentation.challengeId],
+        ["Credential", presentation.credentialId],
+        ["Presenter", challenge.presenterAgentId],
+        ["Action", challenge.requestedAction],
+        ["Expires", presentation.expiresAt],
+        ["Protection", "Challenge-bound · recipient-bound · one-minute proof"],
+      ],
+      "Run again with --json to save the token-bearing presentation for the verifier.",
+    );
   }
 }
 
@@ -674,8 +899,17 @@ async function runVerify(options, baseUrl) {
     if (typeof apiError?.code === "string" && PRESENTATION_REJECTION_CODES.has(apiError.code)) {
       if (options.json) writeJson(payload);
       else {
-        process.stdout.write("Totem verification · REJECTED\n");
-        process.stdout.write(`Reason: ${apiError.code}\n`);
+        writeHumanResult(
+          "Totem verification · REJECTED",
+          [
+            ["Decision", "DO NOT ACT"],
+            ["Challenge", challenge.id],
+            ["Action", challenge.requestedAction],
+            ["Reason", apiError.code],
+          ],
+          "Create a fresh challenge and verify the exact request again before taking action.",
+          "danger",
+        );
       }
       process.exitCode = 2;
       return;
@@ -740,23 +974,285 @@ async function runVerify(options, baseUrl) {
 
   if (options.json) writeJson(payload);
   else {
-    process.stdout.write(`Totem verification · ${terminalText(payload.result)}\n`);
-    if (payload.agent?.name || payload.agent?.id) {
-      process.stdout.write(`Agent: ${terminalText(payload.agent.name ?? payload.agent.id)}\n`);
+    const approvedResult = payload.verified && payload.result === "APPROVED" && result.response.ok;
+    writeHumanResult(
+      `Totem verification · ${terminalText(payload.result)}`,
+      [
+        ["Decision", approvedResult ? "AUTHORIZED FOR THIS EXACT REQUEST" : "DO NOT ACT"],
+        ["Agent", payload.agent?.name ?? payload.agent?.id],
+        ["Agent ID", payload.agent?.id],
+        ["Organization", payload.organization?.name ?? payload.organization?.id],
+        [
+          "Organization proof",
+          payload.organization?.verified
+            ? `${terminalText(payload.organization.domain, "verified domain")} · verified`
+            : payload.organization?.domain,
+        ],
+        ["Action", payload.authorization?.requestedAction],
+        [
+          "Authority",
+          payload.authorization?.allowed ? "Active credential permits this action" : undefined,
+        ],
+        [
+          "Human review",
+          typeof payload.authorization?.humanApprovalRequired === "boolean"
+            ? payload.authorization.humanApprovalRequired
+              ? "Required"
+              : "Not required by credential"
+            : undefined,
+        ],
+        ["Credential", payload.evidence?.credentialId],
+        ["Request", compactDigest(payload.evidence?.requestDigest ?? expectedRequestDigest)],
+        ["Verified", payload.evidence?.verifiedAt],
+        ["Reason", payload.reasonCode],
+        ["Receipt", payload.requestId],
+      ],
+      approvedResult
+        ? "Continue only with the unchanged request bytes shown by this approval."
+        : "Do not process the request; resolve the reason and create a fresh proof.",
+      approvedResult ? "success" : "danger",
+    );
+  }
+  if (payload.verified && payload.result === "APPROVED" && result.response.ok) return;
+  process.exitCode = payload.result === "REJECTED" ? 2 : 1;
+}
+
+function checksFile(options, command) {
+  const path = options.file?.trim();
+  if (!path || path.length > 4_096 || path.includes("\0")) {
+    throw new Error(`${command} requires --file with a readable JSON file.`);
+  }
+  return path;
+}
+
+function checksSuiteId(options, subcommand) {
+  if (options.positionals.length !== 3) {
+    throw new Error(`checks ${subcommand} requires exactly one suite ID.`);
+  }
+  const suiteId = options.positionals[2];
+  if (
+    typeof suiteId !== "string" ||
+    suiteId.length > 200 ||
+    !SAFE_IDENTIFIER_PATTERN.test(suiteId)
+  ) {
+    throw new Error("The Action Checks suite ID is invalid.");
+  }
+  return suiteId;
+}
+
+async function decisionFile(options) {
+  if (!options.file) return { confirmation: null, reason: null };
+  const input = await readJson(checksFile(options, "The decision command"), "decision JSON");
+  if (Object.keys(input).some((key) => !["confirmation", "reason"].includes(key))) {
+    throw new Error("Decision JSON may contain only confirmation and reason.");
+  }
+  const confirmation = input.confirmation;
+  const reason = input.reason;
+  if (
+    confirmation !== undefined &&
+    confirmation !== null &&
+    (typeof confirmation !== "string" || confirmation.length > 500)
+  ) {
+    throw new Error("Decision confirmation must be a string of at most 500 characters.");
+  }
+  if (
+    reason !== undefined &&
+    reason !== null &&
+    (typeof reason !== "string" || reason.length > 1_000)
+  ) {
+    throw new Error("Decision reason must be a string of at most 1000 characters.");
+  }
+  return {
+    confirmation:
+      typeof confirmation === "string" && confirmation.trim() ? confirmation.trim() : null,
+    reason: typeof reason === "string" && reason.trim() ? reason.trim() : null,
+  };
+}
+
+async function actionCheckRequest({
+  baseUrl,
+  path,
+  method = "POST",
+  key,
+  cookie,
+  body,
+  secrets = [],
+}) {
+  let result;
+  try {
+    result = await requestJson({ baseUrl, path, method, key, cookie, body });
+  } catch (error) {
+    writeActionCheckOperationalError(
+      error instanceof Error ? error.message : "Could not reach Totem.",
+      method === "GET" ? undefined : "unknown",
+    );
+    return undefined;
+  }
+  if (!result.response.ok) {
+    writeActionCheckFailure(
+      result.payload,
+      `The Action Checks endpoint returned HTTP ${result.response.status}.`,
+      result.response.status,
+      secrets,
+    );
+    return undefined;
+  }
+  const payload = record(result.payload);
+  if (!payload) {
+    writeActionCheckOperationalError("Totem returned an invalid Action Checks response.");
+    return undefined;
+  }
+  return payload;
+}
+
+async function runChecks(options, baseUrl) {
+  requireLocalActionChecks(baseUrl);
+  const subcommand = options.positionals[1];
+  if (!subcommand)
+    throw new Error(
+      "Provide an Action Checks command: run, view, approve, reject, grant, or execute.",
+    );
+
+  if (subcommand === "run") {
+    if (options.positionals.length !== 2)
+      throw new Error("checks run does not accept positional values.");
+    const action = await readJson(checksFile(options, "checks run"), "action JSON");
+    const key = apiKey("TOTEM_API_KEY", "AGENTTRUST_API_KEY");
+    const payload = await actionCheckRequest({
+      baseUrl,
+      path: "/api/action-checks",
+      key,
+      body: { action },
+      secrets: [key],
+    });
+    if (!payload) return;
+    const suite = record(payload.suite);
+    if (!suite || typeof suite.id !== "string" || typeof suite.conclusion !== "string") {
+      writeActionCheckOperationalError("Totem returned an invalid action check suite.");
+      return;
     }
-    if (payload.organization?.name || payload.organization?.id) {
-      process.stdout.write(
-        `Organization: ${terminalText(payload.organization.name ?? payload.organization.id)}\n`,
-      );
+    writeJson({ suite });
+    if (suite.status === "STALE" || ["BLOCK", "REQUIRES_APPROVAL"].includes(suite.conclusion)) {
+      process.exitCode = 2;
+    } else if (suite.conclusion === "ERROR") {
+      process.exitCode = 1;
     }
-    if (payload.authorization?.requestedAction) {
-      process.stdout.write(`Action: ${terminalText(payload.authorization.requestedAction)}\n`);
+    return;
+  }
+
+  if (subcommand === "view") {
+    if (options.file !== undefined) throw new Error("--file is not valid for checks view.");
+    const suiteId = checksSuiteId(options, subcommand);
+    const key = apiKey("TOTEM_API_KEY", "AGENTTRUST_API_KEY");
+    const payload = await actionCheckRequest({
+      baseUrl,
+      path: `/api/action-checks/${encodeURIComponent(suiteId)}`,
+      method: "GET",
+      key,
+      secrets: [key],
+    });
+    if (!payload) return;
+    const suite = record(payload.suite);
+    if (!suite || typeof suite.id !== "string") {
+      writeActionCheckOperationalError("Totem returned an invalid action check suite.");
+      return;
     }
-    if (payload.reasonCode) process.stdout.write(`Reason: ${terminalText(payload.reasonCode)}\n`);
-    if (payload.requestId) process.stdout.write(`Receipt: ${terminalText(payload.requestId)}\n`);
+    writeJson({ suite });
+    return;
   }
-  if (payload.verified && payload.result === "APPROVED" && result.response.ok) return;
-  process.exitCode = payload.result === "REJECTED" ? 2 : 1;
+
+  if (subcommand === "approve" || subcommand === "reject") {
+    const suiteId = checksSuiteId(options, subcommand);
+    const cookie = actionCheckSessionCookie();
+    const decision = subcommand === "approve" ? "APPROVE" : "REJECT";
+    const input = await decisionFile(options);
+    const payload = await actionCheckRequest({
+      baseUrl,
+      path: `/api/action-checks/${encodeURIComponent(suiteId)}/decision`,
+      cookie,
+      body: { decision, confirmation: input.confirmation, reason: input.reason },
+      secrets: [cookie],
+    });
+    if (!payload) return;
+    const suite = record(payload.suite);
+    if (!suite || typeof suite.id !== "string") {
+      writeActionCheckOperationalError("Totem returned an invalid action check decision response.");
+      return;
+    }
+    writeJson({ suite });
+    if (decision === "REJECT") process.exitCode = 2;
+    return;
+  }
+
+  if (subcommand === "grant") {
+    const suiteId = checksSuiteId(options, subcommand);
+    const action = await readJson(checksFile(options, "checks grant"), "action JSON");
+    const key = apiKey("TOTEM_API_KEY", "AGENTTRUST_API_KEY");
+    const payload = await actionCheckRequest({
+      baseUrl,
+      path: `/api/action-checks/${encodeURIComponent(suiteId)}/grant`,
+      key,
+      body: { action },
+      secrets: [key],
+    });
+    if (!payload) return;
+    const grant = record(payload.grant);
+    const suite = record(grant?.suite);
+    if (
+      !grant ||
+      typeof grant.token !== "string" ||
+      grant.token.length < 32 ||
+      grant.token.length > 512 ||
+      typeof grant.expiresAt !== "string" ||
+      !suite
+    ) {
+      writeActionCheckOperationalError("Totem returned an invalid execution grant response.");
+      return;
+    }
+    writeJson({ grant: { token: grant.token, expiresAt: grant.expiresAt, suite } });
+    return;
+  }
+
+  if (subcommand === "execute") {
+    const suiteId = checksSuiteId(options, subcommand);
+    const input = await readJson(checksFile(options, "checks execute"), "execution JSON");
+    const action = record(input.action);
+    const grant = input.grant;
+    if (!action || typeof grant !== "string" || grant.length < 32 || grant.length > 512) {
+      throw new Error("Execution JSON must contain the exact action object and opaque grant.");
+    }
+    const key = apiKey("TOTEM_API_KEY", "AGENTTRUST_API_KEY");
+    const payload = await actionCheckRequest({
+      baseUrl,
+      path: `/api/action-checks/${encodeURIComponent(suiteId)}/execute`,
+      key,
+      body: { action, grant },
+      secrets: [key, grant],
+    });
+    if (!payload) return;
+    const suite = record(payload.suite);
+    const receipt = record(payload.receipt);
+    if (
+      !suite ||
+      !receipt ||
+      typeof receipt.id !== "string" ||
+      typeof receipt.outcome !== "string"
+    ) {
+      writeActionCheckOperationalError("Totem returned an invalid execution receipt response.");
+      return;
+    }
+    writeJson({
+      suite,
+      receipt,
+      ...(typeof payload.receiptId === "string" ? { receiptId: payload.receiptId } : {}),
+    });
+    if (["FAILED", "UNKNOWN", "COMPENSATED"].includes(receipt.outcome)) process.exitCode = 1;
+    return;
+  }
+
+  throw new Error(
+    "Unknown Action Checks command. Use run, view, approve, reject, grant, or execute.",
+  );
 }
 
 async function runRfq(options, baseUrl) {
@@ -813,25 +1309,36 @@ async function runRfq(options, baseUrl) {
 
   const verification = record(run.verification);
   const supplier = record(run.supplierRequest);
-  process.stdout.write(`Totem RFQ · ${terminalText(run.id, "unknown run")}\n`);
-  process.stdout.write(`Run: ${terminalText(run.status, "UNKNOWN")}\n`);
-  if (run.summary) process.stdout.write(`${terminalText(run.summary)}\n`);
-  if (verification)
-    process.stdout.write(`Agent authority: ${terminalText(verification.result, "UNKNOWN")}\n`);
-  if (supplier) {
-    process.stdout.write(`Delivery: ${terminalText(supplier.status, "UNKNOWN")}\n`);
-    process.stdout.write(
-      `Supplier response: ${terminalText(supplier.businessStatus, "UNKNOWN")}\n`,
-    );
-    process.stdout.write(
-      `Available now: ${number(supplier.availableQuantity)} ${terminalText(supplier.unit, "units")}\n`,
-    );
-    process.stdout.write(
-      `Backorder: ${number(supplier.backorderQuantity)} ${terminalText(supplier.unit, "units")}\n`,
-    );
-    if (supplier.supplierReference)
-      process.stdout.write(`Reference: ${terminalText(supplier.supplierReference)}\n`);
-  }
+  const succeeded = run.status === "SUCCEEDED";
+  writeHumanResult(
+    `Totem RFQ · ${terminalText(run.id, "unknown run")}`,
+    [
+      ["Run", run.status ?? "UNKNOWN"],
+      ["Request", prompt],
+      ["Summary", run.summary],
+      ["Agent authority", verification?.result ?? "UNKNOWN"],
+      ["Delivery", supplier?.status ?? "UNKNOWN"],
+      ["Supplier response", supplier?.businessStatus ?? "UNKNOWN"],
+      [
+        "Available now",
+        supplier
+          ? `${number(supplier.availableQuantity)} ${terminalText(supplier.unit, "units")}`
+          : undefined,
+      ],
+      [
+        "Backorder",
+        supplier
+          ? `${number(supplier.backorderQuantity)} ${terminalText(supplier.unit, "units")}`
+          : undefined,
+      ],
+      ["Reference", supplier?.supplierReference],
+      ["Mode", "Non-binding procurement demonstration"],
+    ],
+    succeeded
+      ? "Review the supplier response and retain the run ID as the audit reference."
+      : "Open the Totem operator run for the bounded trace before retrying.",
+    succeeded ? "success" : "danger",
+  );
   if (run.status !== "SUCCEEDED") process.exitCode = 1;
 }
 
@@ -855,11 +1362,13 @@ async function main() {
     if (command === "challenge") await runChallenge(options, baseUrl);
     else if (command === "present") await runPresent(options, baseUrl);
     else if (command === "verify") await runVerify(options, baseUrl);
+    else if (command === "checks") await runChecks(options, baseUrl);
     else await runRfq(options, baseUrl);
   } catch (error) {
     const message = error instanceof Error ? error.message : "The Totem command failed.";
-    const command = options?.positionals?.[0];
-    if (command && command !== "rfq") failCommand(message, options?.json);
+    const command = options?.positionals?.[0] ?? process.argv[2];
+    if (command === "checks") writeActionCheckOperationalError(message);
+    else if (command && command !== "rfq") failCommand(message, options?.json);
     else fail(message);
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "totemlayer",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Cross-platform CLI for TotemLayer agent identity and authorization",
   "type": "module",
   "bin": {