@figs-so/cli 1.2.0 → 1.3.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,7 +265,8 @@ 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
@@ -265,8 +274,10 @@ minimum CLI version requires Bearer.)
    ```
 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
+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

@@ -386,6 +386,19 @@ 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()}`
+}
+
 // ---------- 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.
@@ -1816,7 +1829,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 +1894,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 +2177,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 +2214,7 @@ async function doPush() {
         workspaceId: config.workspaceId,
         agent,
         runs,
+        runEvents,
         asks,
         messages,
         ...(confirmRename ? { confirmRename: true } : {}),

package/package.json

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