@figs-so/cli 0.2.0 → 0.3.0

package/README.md

@@ -40,7 +40,9 @@ npx @figs-so/cli@latest push                     # publish → it appears in you
 ```
 
 That's it — your agent now shows up at **[app.figs.so](https://app.figs.so)**. No instrumentation, no
-SDK in your agent's code. From there you decide, deliberately, how much of its real work to surface.
+SDK in your agent's code. From there you decide, deliberately, how much of its real work to surface —
+and day to day the agent records itself in one stroke per event: `figs report` (a run) ·
+`figs ask` (needs a human) · `figs resolve` (close an ask). Each pushes itself.
 
 ## How it works
 
@@ -71,8 +73,11 @@ are shorthand for exactly that (always current, no version drift). Prefer a real
 | `figs login` / `logout` | device-flow browser approve / remove local token |
 | `figs workspaces [--json]` | list your workspaces (create one in the web app) |
 | `figs init [--workspace <slug>]` | generate identity + write `.figs/` (omit the flag: uses your only workspace, else lists them) |
-| `figs doctor` | validate `.figs/` against the contract before pushing |
-| `figs push` | one-way publish of `.figs/` |
+| **`figs report --result "…"`** | record a run — stamps id + timestamp, auto-captures the session trace, `--attach`es artifacts, pushes itself (`--resolves <ask-id>` closes an ask in the same stroke) |
+| **`figs ask <type> --title "…"`** | raise a self-contained ask (`blocked` · `needs-decision` · `sign-off` · `fyi`) — options/details/attachments, pushed so a human sees it |
+| **`figs resolve <ask-id>`** | close an ask — `--chosen` verbatim-checked against its options, `--withdrawn` for the un-ask |
+| `figs push` | the bare transport — the verbs call it automatically; type it yourself after hand-edits or `--no-push` |
+| `figs doctor` | validate `.figs/` against the spec without pushing — the conformance check for hand-authored or non-CLI setups |
 | `figs status [--json]` | login / workspace / agent state |
 | `figs help [<command>]` | usage (`-h`/`--help` on any command; `-v` for version) |
 

package/SPEC.md

@@ -122,7 +122,7 @@ primitive** — the agent reached the edge of its autonomy.
 |---|---|:--:|---|
 | `id` | string | ✓ | Stable id (upsert key). |
 | `type` | enum | ✓ | `blocked` \| `needs-decision` \| `sign-off` \| `fyi`. `fyi` is a non-blocking heads-up (no decision needed). |
-| `status` | enum | | `"open"` (default) \| `"resolved"` (the need was met) \| `"withdrawn"` (the agent un-asked — no longer needed, nobody acted). |
+| `status` | enum | | `"open"` (default) \| `"resolved"` (the need was met) \| `"withdrawn"` (the **asker** retracted it — no longer needed, nobody acted) \| `"rejected"` (the **answerer** declined it — a human said no; usually born in the reader's UI, but the agent may record an out-of-band rejection too). Three closes, three authors-of-the-ending. **Rejected is terminal** on this id — readers keep it sticky; re-raising is a new ask. |
 | `to` | `"manager"` \| `"builder"` | | Who the ask is addressed to: the human accountable for the **work** (`manager`) or for the **machine** (`builder` — e.g. self-edit/logic-change flags). Absent = unaddressed; readers may guess from `type` but must present it as a guess. |
 | `title` | string | ✓ | The ask, in one line. |
 | `unit` | string | | The `Unit.id` this concerns. |
@@ -154,9 +154,11 @@ An ask is the **anchor of a thread whose two halves are owned by different parti
   These are [reserved](#reserved-not-in-v1) in v1 and **never appear in `asks.jsonl`**: nobody
   writes into the other side's record; the two ledgers cross-reference by id.
 
-The full state machine: `open` → *(claimed → answered — human, server-side, reserved)* →
-`resolved` | `withdrawn` *(agent, in `asks.jsonl`)*. In v1 only the agent-owned transitions exist;
-resolution happens in the agent's own workflow.
+The full state machine: `open` → *(answered/verdict — human, server-side)* →
+`resolved` | `withdrawn` *(agent, in `asks.jsonl`)* — plus the one human-side close:
+**`rejected`** (a reject verdict in the reader's UI closes the ask immediately; the agent's
+later resolution append folds onto it without reopening). Today resolution otherwise happens
+in the agent's own workflow; answers flowing back through the reader are arriving incrementally.
 
 ### 6.2 `Resolution` — how an ask closed
 

package/figs.mjs

@@ -11,7 +11,8 @@
  *                                         create .figs/config.json + GUIDE.md (generates a stable agent id)
  *   figs report --result "…"            record a run (stamps id/ts/session, --attach files, auto-push)
  *   figs ask <type> --title "…"         raise an ask (self-contained: options/details/attachments, auto-push)
- *   figs resolve <ask-id>               close an ask (verbatim-checks --chosen, auto-push)
+ *   figs inbox [<ask-id>]               what needs you — answers/verdicts from your humans (pure read)
+ *   figs resolve <ask-id>               close an ask (verbatim-checks --chosen; cites the Figs answer it acted on)
  *   figs doctor                         validate .figs/ against the spec before pushing
  *   figs push                           one-way push the .figs/ spine to the ingest endpoint
  *   figs version                        print the CLI version (and check for updates)
@@ -49,7 +50,7 @@ import {
 } from "node:fs"
 import { homedir } from "node:os"
 import { basename, extname, join } from "node:path"
-import { randomUUID } from "node:crypto"
+import { createHash, randomUUID } from "node:crypto"
 import { execSync, spawn } from "node:child_process"
 
 // Single source of truth for the version: package.json (shipped alongside this
@@ -142,18 +143,36 @@ const COMMANDS = {
       "verbatim), --detail \"Label=Value\" (repeatable), --attach <file> (repeatable;",
       "for sign-offs attach the exact content for review + a brief: what to do once",
       "approved and what it requires).",
-      "--run <id|last> links the run this came out of (last = newest local run).",
+      "--run <run-id> links the run this came out of — explicit id only (other",
+      "sessions may report concurrently; `figs report` prints the id it wrote).",
       "--stdin reads a full JSON object instead of flags (long texts; attachments still via --attach).",
     ],
-    eg: 'figs ask sign-off --title "Send 10 payment reminders" --attach ./previews.html --run last',
+    eg: 'figs ask sign-off --title "Send 10 payment reminders" --attach ./previews.html --run recon-2026-06',
+  },
+  inbox: {
+    args: "[<ask-id>] [--json]",
+    flags: ["--json"],
+    desc: "what needs you — your humans' answers/verdicts on your asks (pure read)",
+    more: [
+      "Start every session with this. Bare: lists every ask with thread activity —",
+      "answers and verdicts verbatim, plus the exact next command for each.",
+      "With an ask id: the full handoff package — the ask, the whole thread, and its",
+      "attached artifacts restored into .figs/artifacts/ (hash-verified) so a fresh",
+      "session can act from the record alone.",
+      "Scope: THIS agent's open asks + human-rejected ones you haven't acknowledged.",
+      "Reads only — closing still happens via figs resolve / figs report --resolves.",
+    ],
+    eg: "figs inbox",
   },
   resolve: {
-    args: "<ask-id> [--chosen <option>] [--by <who>] [--note <text>] [--withdrawn]",
-    flags: ["--chosen", "--by", "--note", "--withdrawn", "--no-push"],
+    args: "<ask-id> [--chosen <option>] [--by <who>] [--note <text>] [--withdrawn|--rejected]",
+    flags: ["--chosen", "--by", "--note", "--withdrawn", "--rejected", "--no-push"],
     desc: "close an ask — appends the resolution fold line and pushes",
     more: [
       "--chosen must quote one of the ask's options[] verbatim (checked).",
-      "--withdrawn = the ask is no longer needed, nobody acted (don't mark resolved).",
+      "Three closes, by who ended it: resolved (default — the need was met) ·",
+      "--withdrawn (YOU retracted it; nobody acted) · --rejected (a HUMAN declined",
+      "it — record their out-of-band no; rejected is terminal, re-raising = a new ask).",
       "Use `figs report --resolves <ask-id>` instead when a run did the work.",
     ],
     eg: 'figs resolve acme-bridge --chosen "Strip the alpha prefix" --by "Sarah (accounting)"',
@@ -234,7 +253,9 @@ function positional() {
   }
   return undefined
 }
-const BOOLEAN_FLAGS = new Set(["--no-push", "--stdin", "--withdrawn", "--json", "-h", "--help"])
+const BOOLEAN_FLAGS = new Set([
+  "--no-push", "--stdin", "--withdrawn", "--rejected", "--json", "-h", "--help",
+])
 
 /** ISO-8601 with the machine's real UTC offset (never the agent's guess). */
 function nowIso() {
@@ -258,7 +279,7 @@ function genId(prefix) {
 // and flag typos get wrong, with errors that teach the fix.
 const ASK_TYPES = ["blocked", "needs-decision", "sign-off", "fyi"]
 const RUN_STATUSES = ["ok", "warn", "fail"]
-const ASK_STATUSES = ["open", "resolved", "withdrawn"]
+const ASK_STATUSES = ["open", "resolved", "withdrawn", "rejected"]
 const TO_VALUES = ["manager", "builder"]
 const ARTIFACT_EXTS = new Set([
   ".html", ".md", ".txt", ".json", ".png", ".jpg", ".jpeg", ".gif", ".webp", ".svg",
@@ -472,6 +493,7 @@ else if (COMMANDS[cmd]) {
   else if (cmd === "init") await init()
   else if (cmd === "report") await reportCmd()
   else if (cmd === "ask") await askCmd()
+  else if (cmd === "inbox") await inboxCmd()
   else if (cmd === "resolve") await resolveCmd()
   else if (cmd === "doctor") await doctor()
   else if (cmd === "push") await push()
@@ -1098,37 +1120,260 @@ function captureCommit() {
   }
 }
 
+// ---------- the inbox (the DOWN direction — a pure read) ---------------------
+
+/** Relative time for inbox lines — rough on purpose. */
+function agoStr(iso) {
+  const mins = Math.max(0, Math.round((Date.now() - new Date(iso).getTime()) / 60000))
+  if (mins < 60) return `${mins}m ago`
+  if (mins < 60 * 48) return `${Math.round(mins / 60)}h ago`
+  return `${Math.round(mins / 1440)}d ago`
+}
+
+/** Fetch this agent's inbox; null on any failure when `soft` (auto-cite path). */
+async function fetchInbox({ soft = false } = {}) {
+  const config = readJson(join(repoDir, "config.json"), {})
+  if (!config.agentId) {
+    if (soft) return null
+    die("config missing agentId — run `figs init`")
+  }
+  const r = await request("GET", `/api/inbox?agent=${config.agentId}`)
+  if (!r.ok) {
+    if (soft) return null
+    die(`inbox failed (${r.status || "network"}): ${r.data.error ?? r.data.raw ?? ""}`)
+  }
+  return r.data
+}
+
+/** One human event, verbatim — answers are instructions; never paraphrase them. */
+function eventLine(e) {
+  const head =
+    e.kind === "verdict"
+      ? `${e.verdict.replace(/_/g, " ")} by ${e.byName} (${e.asRole})`
+      : `answered by ${e.byName} (${e.asRole})`
+  const body = [e.chosen ? `→ "${e.chosen}"` : null, e.text ? `"${e.text}"` : null]
+    .filter(Boolean)
+    .join(" · ")
+  return `${head} · ${agoStr(e.createdAt)}${body ? `\n      ${body}` : ""}`
+}
+
+/** The type×state matrix → the exact next command. The stranger never needs
+ *  to know the state machine — the protocol tells them their move. */
+function nextMove(a) {
+  if (a.status === "rejected") {
+    return `a human declined this — acknowledge it: figs resolve ${a.id} --rejected`
+  }
+  const last = a.events[a.events.length - 1]
+  if (!last) return "waiting on your human — nothing for you to do"
+  if (last.kind === "verdict" && last.verdict === "approved") {
+    return `approved — verify any prerequisites in the ask, do it, then: figs report --resolves ${a.id}`
+  }
+  if (last.kind === "verdict" && last.verdict === "changes_requested") {
+    return `revise, then re-raise on the same id: figs ask ${a.type} --id ${a.id} --title "…" …`
+  }
+  return `act on the answer, then: figs report --resolves ${a.id}  (or figs resolve ${a.id} --chosen "…")`
+}
+
+/** Restore an ask's refs into artifacts/ — hash-verified; never clobbers. */
+async function fetchRefs(config, refs) {
+  for (const ref of refs ?? []) {
+    if (!ref.artifact) continue
+    const name = ref.artifact
+    let res
+    try {
+      res = await fetchT(
+        `${resolveEndpoint()}/api/artifacts/raw?agent=${config.agentId}&name=${encodeURIComponent(name)}`,
+        { headers: { "x-figs-token": getToken() } },
+      )
+    } catch (e) {
+      console.warn(`figs: ! couldn't fetch artifacts/${name} (${netReason(e)})`)
+      continue
+    }
+    if (!res.ok) {
+      console.warn(`figs: ! couldn't fetch artifacts/${name} (${res.status})`)
+      continue
+    }
+    const bytes = Buffer.from(await res.arrayBuffer())
+    const want = res.headers.get("x-figs-sha256")
+    if (want && createHash("sha256").update(bytes).digest("hex") !== want) {
+      console.warn(`figs: ! artifacts/${name}: bytes didn't match the server's hash — skipped`)
+      continue
+    }
+    const dest = join(repoDir, "artifacts", name)
+    if (existsSync(dest)) {
+      if (readFileSync(dest).equals(bytes)) {
+        console.log(`figs:   ✓ artifacts/${name} (already present)`)
+      } else {
+        console.warn(
+          `figs: ! artifacts/${name} exists locally with different content — left untouched (the published copy stays one fetch away)`,
+        )
+      }
+      continue
+    }
+    mkdirSync(join(repoDir, "artifacts"), { recursive: true })
+    writeFileSync(dest, bytes)
+    console.log(`figs:   ✓ artifacts/${name} (fetched, hash ok)`)
+  }
+}
+
+/**
+ * `figs inbox` — session start. Bare: every ask with thread activity + the
+ * next command for each. With an id: the zero-context handoff package (the
+ * ask, the whole thread verbatim, refs restored to disk). Pure read — writes
+ * nothing to the outbox; closing happens via resolve / report --resolves.
+ */
+async function inboxCmd() {
+  requireFigs()
+  const config = readJson(join(repoDir, "config.json"), {})
+  const data = await fetchInbox()
+  const items = data.asks ?? []
+  const askId = positional()
+
+  if (hasFlag("--json") && !askId) {
+    console.log(JSON.stringify(data, null, 2))
+    return
+  }
+
+  if (askId) {
+    const a = items.find((x) => x.id === askId)
+    if (!a) {
+      die(
+        `ask "${askId}" isn't in your inbox (open asks + unacknowledged rejections only — closed history lives in the app)`,
+      )
+    }
+    console.log(`figs: ${a.title}`)
+    console.log(`      ${a.type} · ${a.status}${a.to ? ` · for the ${a.to}` : ""} · raised ${agoStr(a.ts)}`)
+    if (a.found) console.log(`\n  What it found:\n      ${a.found}`)
+    if (a.need) console.log(`\n  What it needs:\n      ${a.need}`)
+    if (a.options?.length) {
+      console.log(`\n  Options (answers cite these verbatim):`)
+      for (const o of a.options) console.log(`      · ${o}`)
+    }
+    if (a.details?.length) {
+      console.log(`\n  Details:`)
+      for (const d of a.details) console.log(`      ${d.l}: ${d.v}`)
+    }
+    if (a.events.length) {
+      console.log(`\n  THE THREAD (your humans' words, verbatim):`)
+      for (const e of a.events) console.log(`    · ${eventLine(e)}`)
+    } else {
+      console.log(`\n  No answer yet.`)
+    }
+    if (a.refs?.length) {
+      console.log(`\n  Attached artifacts (restoring to .figs/artifacts/):`)
+      await fetchRefs(config, a.refs)
+    }
+    console.log(`\n  → next: ${nextMove(a)}`)
+    return
+  }
+
+  if (data.truncated) {
+    console.warn(`figs: ! showing the first ${items.length} — more exist (close some asks)`)
+  }
+  if (items.length === 0) {
+    console.log("figs: ✓ inbox empty — no open asks, nothing needs you")
+    return
+  }
+  const rejected = items.filter((a) => a.status === "rejected")
+  const answered = items.filter((a) => a.status === "open" && a.events.length > 0)
+  const quiet = items.filter((a) => a.status === "open" && a.events.length === 0)
+  console.log(
+    `figs: inbox — ${answered.length} answered · ${rejected.length} rejected to acknowledge · ${quiet.length} waiting on your human`,
+  )
+  const printItem = (a) => {
+    const last = a.events[a.events.length - 1]
+    console.log(`\n  ${a.id} · ${a.type} — ${a.title}`)
+    if (last) console.log(`    ${eventLine(last)}`)
+    console.log(`    → ${nextMove(a)}${a.events.length > 1 ? `   (full thread: figs inbox ${a.id})` : ""}`)
+  }
+  for (const a of [...rejected, ...answered]) printItem(a)
+  if (quiet.length) {
+    console.log(`\n  Waiting on your human (nothing for you to do):`)
+    for (const a of quiet) console.log(`    · ${a.id} · ${a.type} — ${a.title} (raised ${agoStr(a.ts)})`)
+  }
+}
+
 // ---------- the resolution fold (shared by `resolve` and `report --resolves`) -
-function buildResolution(askId, { chosen, by, note, withdrawn }) {
-  if (withdrawn && chosen) {
-    die("--withdrawn and --chosen are mutually exclusive (withdrawn = the ask is no longer needed, nobody acted)")
+/**
+ * Build the closing fold line. Best-effort, the verified path: fetches this
+ * agent's inbox and, when the ask has human events, cites the one acted on —
+ * `via: "figs"` + `resolution.answer: <event-id>` (+ `by` from the event) —
+ * attribution by mechanism, not testimony. An ask found on the server but
+ * missing locally is appended first (its own bytes coming home), so the fold
+ * lands on a complete record. Offline or any failure → today's self-reported
+ * `via: "human"` path, unchanged.
+ */
+async function buildResolution(askId, { chosen, by, note, withdrawn, rejected }) {
+  if (withdrawn && rejected) {
+    die("--withdrawn and --rejected are different closes: withdrawn = YOU retracted the ask; rejected = a HUMAN declined it. Pick the one that's true.")
+  }
+  if ((withdrawn || rejected) && chosen) {
+    die(`--chosen marks the need as met — it can't combine with ${withdrawn ? "--withdrawn" : "--rejected"} (use --note for the account)`)
   }
-  const asks = foldById(readJsonl("asks.jsonl"))
-  const ask = asks.find((a) => a.id === askId)
   const warnings = []
-  if (!ask) {
+  let ask = foldById(readJsonl("asks.jsonl")).find((a) => a.id === askId)
+
+  // The verified path (soft — never blocks a close).
+  let serverAsk = null
+  if (getToken()) {
+    const inbox = await fetchInbox({ soft: true })
+    serverAsk = inbox?.asks?.find((a) => a.id === askId) ?? null
+  }
+  if (!ask && serverAsk) {
+    // Its own bytes coming home: append the record so the fold has something
+    // local to land on (the cross-machine close, solved inside the verb).
+    const record = { ...serverAsk }
+    delete record.events
+    delete record.updatedAt
+    if (record.resolution == null) delete record.resolution
+    appendJsonl("asks.jsonl", record)
+    warnings.push(`fetched "${askId}" from Figs (raised elsewhere) — recorded locally before closing`)
+    ask = record
+  } else if (!ask) {
     warnings.push(
       `ask "${askId}" isn't in the local asks.jsonl (raised on another machine, or pruned) — recording the close anyway; the server folds it onto the full record`,
     )
-  } else if (chosen && ask.options?.length && !ask.options.includes(chosen)) {
+  }
+
+  const options = ask?.options ?? serverAsk?.options ?? []
+  if (chosen && options.length && !options.includes(chosen)) {
     const norm = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, "")
-    const near = ask.options.find((o) => norm(o) === norm(chosen))
+    const near = options.find((o) => norm(o) === norm(chosen))
     if (near) die(`--chosen must quote the option verbatim — did you mean "${near}"?`)
     die(
       `--chosen "${chosen}" doesn't match any of the ask's options:\n` +
-        ask.options.map((o) => `    · ${o}`).join("\n") +
+        options.map((o) => `    · ${o}`).join("\n") +
         "\n  (quote one verbatim, or use --note for a free-text account)",
     )
   }
+
   const resolution = {}
   if (chosen) resolution.chosen = chosen
   if (by) resolution.by = by
   if (note) resolution.note = note
   // `via` says where the unblock came from; out-of-band human answers are
-  // "human". Set it only when there's evidence of one (a chosen/by), never on
-  // withdrawn (nobody acted — that's the point).
-  if (!withdrawn && (chosen || by)) resolution.via = "human"
-  const line = { id: askId, status: withdrawn ? "withdrawn" : "resolved" }
+  // "human". A rejection is inherently a human's call; otherwise set it only
+  // when there's evidence of one (a chosen/by), never on withdrawn (nobody
+  // acted — that's the point).
+  if (rejected || (!withdrawn && (chosen || by))) resolution.via = "human"
+
+  // Cite the event acted on, when one exists: prefer the latest answer whose
+  // chosen matches, else the latest event (e.g. the approval, the rejection).
+  const events = serverAsk?.events ?? []
+  if (!withdrawn && events.length) {
+    const match = chosen
+      ? [...events].reverse().find((e) => e.kind === "answer" && e.chosen === chosen)
+      : null
+    const cited = match ?? events[events.length - 1]
+    resolution.via = "figs"
+    resolution.answer = cited.id
+    if (!by && cited.byName) resolution.by = cited.byName
+  }
+
+  const line = {
+    id: askId,
+    status: withdrawn ? "withdrawn" : rejected ? "rejected" : "resolved",
+  }
   if (Object.keys(resolution).length) line.resolution = resolution
   return { line, warnings }
 }
@@ -1165,7 +1410,7 @@ async function reportCmd() {
   let resolution = null
   if (resolves) {
     run.resolves = resolves
-    resolution = buildResolution(resolves, {
+    resolution = await buildResolution(resolves, {
       chosen: flag("--chosen"),
       by: flag("--by"),
       note: flag("--note"),
@@ -1234,12 +1479,11 @@ async function askCmd() {
   if (details.length) ask.details = [...(base.details ?? []), ...details]
   const runRef = flag("--run")
   if (runRef === "last") {
-    const runs = foldById(readJsonl("runs.jsonl"))
-    if (!runs.length) {
-      die("--run last: no runs in the local runs.jsonl — `figs report` one first, or pass an explicit id")
-    }
-    ask.run = runs.reduce((a, b) => ((a.ts ?? "") > (b.ts ?? "") ? a : b)).id
-  } else if (runRef) ask.run = runRef
+    // Deliberately unsupported: concurrent sessions of the same agent report
+    // runs in parallel — "the latest run" may be someone else's. Explicit only.
+    die('--run takes the explicit run id (no "last" — another session may have reported since); `figs report` prints the id of what it wrote')
+  }
+  if (runRef) ask.run = runRef
   const attached = attachFiles(flagAll("--attach"))
   if (attached.length) {
     ask.refs = [...(base.refs ?? []), ...attached.map((n) => ({ label: n, artifact: n }))]
@@ -1261,7 +1505,7 @@ async function askCmd() {
   }
   await autoPush()
   console.log(
-    "figs:   answers arrive out-of-band for now (`figs inbox` is coming) — your human replies in the app thread or directly to you",
+    "figs:   your human answers in the app — start your next session with `figs inbox` to read it",
   )
 }
 
@@ -1269,11 +1513,12 @@ async function resolveCmd() {
   requireFigs()
   const askId = positional()
   if (!askId) die("resolve needs the ask id: figs resolve <ask-id> [--chosen …] [--withdrawn]")
-  const { line, warnings } = buildResolution(askId, {
+  const { line, warnings } = await buildResolution(askId, {
     chosen: flag("--chosen"),
     by: flag("--by"),
     note: flag("--note"),
     withdrawn: hasFlag("--withdrawn"),
+    rejected: hasFlag("--rejected"),
   })
   for (const w of warnings) console.warn(`figs: ! ${w}`)
   appendJsonl("asks.jsonl", line)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@figs-so/cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Figs CLI — publish your AI agent's state to Figs (figs.so). Run by the agent.",
   "type": "module",
   "bin": {