@figs-so/cli 1.3.0 → 1.4.0

package/SPEC.md

@@ -272,7 +272,14 @@ minimum CLI version requires Bearer.)
      "confirmRename": true                   // optional — `figs push --rename`: confirm a real name change
    }
    ```
-2. **Each attached file** → `POST {endpoint}/api/artifacts/upload`, base64-encoded, hash-verified.
+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

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). */
@@ -399,6 +405,13 @@ 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.
@@ -1674,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 &&
@@ -2243,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 }
 }
@@ -2258,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),
@@ -2266,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)) {
@@ -2277,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`, {
@@ -2287,7 +2342,7 @@ async function pushArtifacts(base, token, config) {
           workspaceId: config.workspaceId,
           agentId: config.agentId,
           name,
-          content,
+          content: bytes.toString("base64"),
         }),
       })
     } catch (e) {
@@ -2305,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.3.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": {