@figs-so/cli 1.2.0 → 1.4.0

package/SPEC.md

@@ -119,9 +119,17 @@ crash mid-job leaves a visible, recoverable stub. A **report** files the outcome
 report with no prior checkpoint is a job **born settled** (the single-sitting case). Nothing *external*
 ever closes a run — only the agent's own report settles its job.
 
+**Folding is local; the lifecycle still publishes.** The folded record is the job's *current* state; its
+history is the sequence of lines. On push the CLI sends **both** — the folded record (the row) *and* the
+raw fold lines (`runEvents`, §8) — so a reader rebuilds the timeline (opened → checkpoints → settled)
+even when a whole account-free history is published in a single first push (which would otherwise collapse
+to one "settled" snapshot). Each line's `eventId` is the dedupe key: one timeline entry per fold,
+idempotent across re-pushes.
+
 | Field | Type | Req | Meaning |
 |---|---|:--:|---|
 | `id` | string | ✓ | Stable id (upsert key). |
+| `eventId` | string | | Machine-minted per-fold id (`evt-…`) — **plumbing, never typed** (like the agent UUID, §4). Survives folding: a job's id collapses many lines into one record, but each line keeps its own. Lets a reader rebuild the per-fold timeline from the raw lines published as `runEvents` (§8). Absent on hand-authored/legacy lines — they fold to one published snapshot, as before. |
 | `ts` | string (ISO-8601 w/ offset) | ✓ | When it ran. Machine-stamped by the CLI, never typed. |
 | `unit` | string | | The `Unit.id` this run is about. |
 | `period` | string | | |
@@ -257,16 +265,26 @@ minimum CLI version requires Bearer.)
    {
      "workspaceId": "<uuid>",        // from config.json
      "agent":    { /* agent.json */ },
-     "runs":     [ /* runs.jsonl     */ ],   // optional
+     "runs":      [ /* runs.jsonl folded by id */ ],   // optional — the current state per job (the row)
+     "runEvents": [ /* runs.jsonl raw fold lines, eventId-bearing only */ ], // optional — rebuilds the timeline
      "asks":     [ /* asks.jsonl     */ ],   // optional
      "messages": [ /* messages.jsonl */ ],   // optional — transcribed replies the reader lacks
      "confirmRename": true                   // optional — `figs push --rename`: confirm a real name change
    }
    ```
-2. **Each attached file** → `POST {endpoint}/api/artifacts/upload`, base64-encoded, hash-verified.
-
-The server upserts the agent by `id` and runs/asks by `id`; it dedupes messages by event `id`; it never
-deletes. An agent **self-registers** on first push. **A push never walks a record backwards:** the
+2. **Each attached file the server lacks** → `POST {endpoint}/api/artifacts/upload`, base64-encoded,
+   hash-verified. The `/api/ingest` response returns the agent's **artifact manifest**
+   (`{ "<name>": "sha256:<hex>" }` for every stored file); the CLI re-hashes its local files and uploads
+   only those whose hash differs or are absent — **content-addressed on the sha256 of the raw file
+   bytes** (hashed before base64), so unchanged bytes never cross the wire. A response without the
+   manifest field triggers a full upload (older readers omit it; older CLIs ignore it). Attachments stay
+   immutable (§7): same name + different bytes is refused `409`. `figs push --reupload` forces a full
+   re-send (recovery if a stored object ever drifts from its row).
+
+The server upserts the agent by `id` and runs/asks by `id`; it dedupes messages by event `id`; it
+**rebuilds each run's timeline from `runEvents`, one entry per fold, deduped by `eventId`** (a run with no
+`runEvents` — an older CLI, or legacy/hand-authored lines without an `eventId` — keeps one timeline entry
+per content-changing push, the prior behavior); it never deletes. An agent **self-registers** on first push. **A push never walks a record backwards:** the
 server refuses a fold older than the record's stored close/settle (a stale machine pushing old state)
 and accepts a newer one (a legitimate reopen — the `warn` → `ok` evolution). **A push never re-homes an
 agent:** a `workspaceId` differing from the agent's registered home is rejected `409`

package/figs.mjs

@@ -211,19 +211,21 @@ const COMMANDS = {
   answer: {
     args: "<ask-id> --by <who> (--chosen <option> | --text <reply> | --approve | --request-changes | --reject)",
     flags: [
-      "--by", "--chosen", "--text", "--approve", "--request-changes", "--reject", "--no-push",
+      "--by", "--chosen", "--text", "--approve", "--request-changes", "--reject", "--no-push", "--force",
     ],
-    desc: "record your human's out-of-band reply to an ask, verbatim (you run this, not them)",
+    desc: "transcribe a human's out-of-band reply (chat/console, not the app), verbatim (you run this, not them)",
     more: [
-      "Humans don't type commands. They answer you in chat ('approved — only the 15');",
-      "you transcribe that into the record. --by names the HUMAN who said it, not you.",
+      "For a reply your user gave you in chat/console rather than the app — fine even when",
+      "linked (it records as a 'relayed' reply, the honest lower-trust grade). Humans don't",
+      "type commands; you transcribe what they said. --by names the HUMAN who said it, not you.",
       "question → --chosen '<option verbatim>' (checked against the ask's options) or",
       "--text '<what they said>'. sign-off → --approve | --request-changes | --reject",
       "(a qualified verdict may also carry --chosen). Transcribe verbatim — never summarize,",
       "never author the reply yourself.",
-      "Replies made IN the app sync down automatically (figs inbox) — `figs answer` is only",
-      "for replies that exist nowhere but your chat.",
-      "Then act, and `figs close <ask-id>` — it cites this reply automatically.",
+      "Just don't RE-transcribe a reply that already came through the app: it's attested and",
+      "syncs down on its own (figs inbox), and a re-typed copy would downgrade it — so answer",
+      "REFUSES if the ask already has an app reply (--force only for a separate out-of-band one).",
+      "When inbox already shows the reply, skip straight to `figs close <ask-id>`.",
     ],
     eg: "figs answer acme-bridge --chosen 'Strip the alpha prefix' --by 'Sarah (accounting)'",
   },
@@ -280,16 +282,20 @@ const COMMANDS = {
   },
   push: {
     args: "",
-    flags: ["--rename"],
+    flags: ["--rename", "--reupload"],
     desc: "publish .figs/ — spine to /api/ingest, artifacts to /api/artifacts",
     more: [
       "Idempotent (records fold by id). Exits non-zero if an artifact upload is rejected.",
       "The writing verbs (report/ask/resolve) call this automatically — you only need it",
       "after hand-editing files, after --no-push, or to retry a failed auto-push.",
+      "Artifacts already on the server (same content) are skipped — their bytes aren't",
+      "re-sent; only new or changed files upload.",
       "--rename: confirm a genuine name change on an already-registered agent (one",
       "time). The server refuses a name that doesn't match the registered one — it's",
       "the fingerprint of a copied folder; if that's what happened, rotate identity",
       "instead with `rm -rf .figs && figs init`, don't --rename.",
+      "--reupload: re-send every artifact even if the server already has it (bypasses",
+      "the content-hash skip) — recovery if a stored file ever drifts from its record.",
     ],
     eg: "figs push",
   },
@@ -366,7 +372,7 @@ function positional() {
   return undefined
 }
 const BOOLEAN_FLAGS = new Set([
-  "--no-push", "--stdin", "--withdrawn", "--rejected", "--json", "-h", "--help",
+  "--no-push", "--stdin", "--withdrawn", "--rejected", "--json", "--force", "--reupload", "-h", "--help",
 ])
 
 /** ISO-8601 with the machine's real UTC offset (never the agent's guess). */
@@ -386,6 +392,26 @@ function genId(prefix) {
   return `${prefix}-${Date.now().toString(36)}${Math.random().toString(36).slice(2, 5)}`
 }
 
+// A run line's stable, machine-minted identity (the plumbing-id class, rule 7 —
+// no verb accepts it; like the agent UUID). It survives folding: a job's id
+// collapses many lines into one record, but each line keeps its own eventId.
+// `figs push` sends the raw fold lines (with these ids) as `runEvents` so the
+// app can rebuild the full in-flight timeline — opened → checkpoints → settled —
+// even when a long account-free history is published in a single first link-late
+// push (it would otherwise fold to one "settled" snapshot, losing the lifecycle).
+// UUID-backed so it's a collision-free dedupe key: the server appends one
+// timeline row per eventId, ON CONFLICT DO NOTHING, so re-pushes never duplicate.
+function genEventId() {
+  return `evt-${randomUUID()}`
+}
+
+/** Human-readable byte size — for the push line ("X not re-sent"). */
+function fmtBytes(n) {
+  if (n < 1024) return `${n} B`
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`
+  return `${(n / (1024 * 1024)).toFixed(1)} MB`
+}
+
 // ---------- local validation (the spec's common mistakes, caught on write) ----
 // The server's schema stays the source of truth; these catch what hand-authors
 // and flag typos get wrong, with errors that teach the fix.
@@ -1661,8 +1687,24 @@ async function answerCmd() {
     }
   }
 
-  // Double-transcription guard: a reply made in the app syncs down on its own,
-  // so re-typing it here would mint a duplicate (a weaker-grade copy).
+  // Attested-reply guard (the trust-grade protector). A reply made in the app is
+  // attested (source:"app") and syncs down on its own via `figs inbox`. Re-transcribing
+  // it here mints a weaker source:"chat" duplicate — and since `close` cites the NEWEST
+  // reply, the self-report would supersede the attested one, silently downgrading the
+  // resolution from ✓VERIFIED to "relayed by agent". So refuse if the ask already has an
+  // app-minted reply (type-agnostic: verdicts and answers alike); --force records a
+  // genuinely-out-of-band chat reply anyway. Local check — the app reply is already in
+  // messages.jsonl from a prior inbox sync (no network on this hot path; contract rule 6).
+  const appReply = readJsonl("messages.jsonl").find((m) => m.ask === askId && m.source === "app")
+  if (appReply && !hasFlag("--force")) {
+    die(
+      `ask "${askId}" already has an attested reply from the app (synced here via \`figs inbox\`).\n` +
+        `  Don't transcribe app replies — the app is the answer channel. → just \`figs close ${askId}\`.\n` +
+        `  (\`figs answer\` is only for a reply that exists nowhere but your chat. --force to record one anyway.)`,
+    )
+  }
+
+  // Softer guard for the no-app case (e.g. re-typing a chat reply): a content-match dupe.
   const priorSame = readJsonl("messages.jsonl").some(
     (m) =>
       m.ask === askId &&
@@ -1816,7 +1858,7 @@ async function reportCmd() {
   const id = idGiven || genId("r")
   // Before the append, so "new" means new-to-this-outbox (the typo catch).
   const isNew = !foldById(readJsonl("runs.jsonl")).some((r) => r.id === id)
-  const run = { id, ts: nowIso(), result, state: "settled" }
+  const run = { id, eventId: genEventId(), ts: nowIso(), result, state: "settled" }
   const unit = flag("--unit")
   if (unit) run.unit = unit
   const period = flag("--period")
@@ -1881,7 +1923,7 @@ async function checkpointCmd() {
   }
   // Before the append, so "new" means new-to-this-outbox (the teaching line).
   const isNew = !foldById(readJsonl("runs.jsonl")).some((r) => r.id === id)
-  const run = { id, ts: nowIso(), result: note, state: "in-flight" }
+  const run = { id, eventId: genEventId(), ts: nowIso(), result: note, state: "in-flight" }
   const unit = flag("--unit")
   if (unit) run.unit = unit
   const period = flag("--period")
@@ -2164,10 +2206,19 @@ async function doPush() {
   const agentJson = readJson(join(repoDir, "agent.json"), null)
   if (!agentJson) return fail("missing .figs/agent.json — author it, then `figs doctor`")
   const agent = { ...agentJson, id: config.agentId }
-  const runs = foldById(readJsonl("runs.jsonl"))
+  const runLines = readJsonl("runs.jsonl")
+  const runs = foldById(runLines)
   const asks = foldById(readJsonl("asks.jsonl"))
   // Messages are immutable events — sent whole (no fold); the server dedupes by id.
   const messages = readJsonl("messages.jsonl")
+  // The raw fold lines ride alongside the folded spine: `runs` (folded) still
+  // drives the run row + validation; `runEvents` lets the server rebuild the
+  // per-fold timeline (opened → checkpoints → settled), so a link-late first
+  // push doesn't collapse a whole offline lifecycle into one "settled" snapshot.
+  // Only eventId-bearing lines (CLI-written) — legacy/hand-authored lines lack
+  // the dedupe key, so the server keeps its current one-row-per-push behavior
+  // for them (and runs they belong to are untouched).
+  const runEvents = runLines.filter((r) => r.eventId)
   // One-time confirm that a name change on an already-registered id is a real
   // rename, not a copied folder (the server's rename guard refuses it otherwise).
   const confirmRename = hasFlag("--rename")
@@ -2192,6 +2243,7 @@ async function doPush() {
         workspaceId: config.workspaceId,
         agent,
         runs,
+        runEvents,
         asks,
         messages,
         ...(confirmRename ? { confirmRename: true } : {}),
@@ -2220,8 +2272,18 @@ async function doPush() {
   // The wow-moment link — relay this to your human so they can see the agent.
   console.log(`       view at ${base}/w/${config.workspaceId}`)
 
+  // The ingest response carries the agent's artifact manifest ({ name: "sha256:…" }) —
+  // pushArtifacts re-hashes locally and skips re-sending bytes the server already
+  // has. Absent (older server / non-JSON body) → it uploads everything, as before.
+  let artifactManifest
+  try {
+    artifactManifest = JSON.parse(text)?.artifactManifest
+  } catch {
+    // non-JSON success body — fall back to upload-all
+  }
+
   // The spine landed; an artifact-stage failure is transient/oversize — retry.
-  return (await pushArtifacts(base, token, config))
+  return (await pushArtifacts(base, token, config, artifactManifest))
     ? { ok: true }
     : { ok: false, retryable: true }
 }
@@ -2235,7 +2297,7 @@ async function doPush() {
  * survives. A **server rejection** (auth/size) is fatal; a **missing local
  * file** is only a warning (the agent referenced something it didn't produce).
  */
-async function pushArtifacts(base, token, config) {
+async function pushArtifacts(base, token, config, manifest) {
   const names = [
     ...new Set(
       [...readJsonl("runs.jsonl"), ...readJsonl("asks.jsonl")].flatMap(attachmentsOf),
@@ -2243,10 +2305,18 @@ async function pushArtifacts(base, token, config) {
   ]
   if (names.length === 0) return true
 
+  // Content-addressed skip: ingest returns the server's artifacts as
+  // { name: "sha256:<hex>" }; we re-hash each local file and only POST its bytes
+  // when they differ (or the server lacks it). Without a manifest (older server)
+  // we upload everything, as before. `--reupload` forces a full re-send — the
+  // manual recovery if a stored object ever drifts from its row.
+  const reupload = hasFlag("--reupload")
   let uploaded = 0
+  let skipped = 0
   let unchanged = 0
   let missing = 0
   let failed = 0
+  let savedBytes = 0
   for (const name of names) {
     const p = join(repoDir, "artifacts", name)
     if (!existsSync(p)) {
@@ -2254,7 +2324,15 @@ async function pushArtifacts(base, token, config) {
       missing++
       continue
     }
-    const content = readFileSync(p).toString("base64")
+    const bytes = readFileSync(p)
+    // sha256 of the RAW bytes — must match the server's hash of the decoded
+    // upload (SPEC §8). Hash before base64, never the base64 text.
+    const localHash = `sha256:${createHash("sha256").update(bytes).digest("hex")}`
+    if (!reupload && manifest && manifest[name] === localHash) {
+      skipped++
+      savedBytes += bytes.length
+      continue
+    }
     let res
     try {
       res = await fetchT(`${base}/api/artifacts/upload`, {
@@ -2264,7 +2342,7 @@ async function pushArtifacts(base, token, config) {
           workspaceId: config.workspaceId,
           agentId: config.agentId,
           name,
-          content,
+          content: bytes.toString("base64"),
         }),
       })
     } catch (e) {
@@ -2282,15 +2360,22 @@ async function pushArtifacts(base, token, config) {
       failed++
       continue
     }
+    // We sent it; the server may still report it unchanged on the fallback path
+    // (no manifest to skip with — the bytes crossed the wire, storage was spared).
     const body = await res.json().catch(() => ({}))
     if (body.unchanged) unchanged++
     else uploaded++
   }
-  console.log(
-    `figs: ${failed ? "✗" : "✓"} artifacts — ${uploaded} uploaded, ${unchanged} unchanged` +
-      (missing ? `, ${missing} missing` : "") +
-      (failed ? `, ${failed} failed` : ""),
-  )
+  const parts = [`${uploaded} uploaded`]
+  if (skipped) {
+    parts.push(
+      `${skipped} skipped (already synced${savedBytes ? ` — ${fmtBytes(savedBytes)} not re-sent` : ""})`,
+    )
+  }
+  if (unchanged) parts.push(`${unchanged} unchanged`)
+  if (missing) parts.push(`${missing} missing`)
+  if (failed) parts.push(`${failed} failed`)
+  console.log(`figs: ${failed ? "✗" : "✓"} artifacts — ${parts.join(", ")}`)
   // The spine already landed; a false return lets the caller exit non-zero so
   // an agent's run loop can catch that an artifact the manager needs to read
   // did not publish.

package/package.json

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