@figs-so/cli 1.1.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 | | |
@@ -156,9 +164,9 @@ edge of its autonomy.
 | Field | Type | Req | Meaning |
 |---|---|:--:|---|
 | `id` | string | ✓ | Stable id (upsert key). |
-| `type` | enum | ✓ | `question` \| `sign-off` — **the type is the answer contract**: *question* wants an answer (an option or free text), *sign-off* wants a verdict (approve / request-changes / reject). (`needs-decision` was renamed `question`; `fyi` was retired — a for-the-record note is a settled report, not an ask; `blocked` is the run's `status`, not an ask type.) |
+| `type` | enum | ✓ | `question` \| `sign-off` — **the type is the answer contract**: *question* wants an answer (an option or free text), *sign-off* wants a verdict (approve / request-changes / reject). (`needs-decision` was renamed `question`; `fyi` was retired — a for-the-record note / assumption / heads-up is a `checkpoint` on the job (or a settled `report`), not an ask; `blocked` is the run's `status`, not an ask type.) |
 | `status` | enum | | `"open"` (default) \| `"resolved"` (the need was met) \| `"withdrawn"` (the **agent** retracted it; nobody acted) \| `"rejected"` (a human declined it). **Rejected is terminal** on this id — 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`). Absent = unaddressed. |
+| `to` | `"manager"` \| `"builder"` | | Who the ask is addressed to: the human accountable for the **work** (`manager`) or for the **machine** (`builder`). Absent = unaddressed; `figs ask` **defaults it to `manager`** (the common case) when omitted, so a reader needn't infer. |
 | `title` | string | ✓ | The ask, in one line. |
 | `unit` | string | | The `Unit.id` this concerns. |
 | `run` | string | | The run `id` this ask was raised during. **Optional** — asks also arise outside runs. |
@@ -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

@@ -89,10 +89,11 @@ const COMMANDS = {
     eg: "figs status --json",
   },
   login: {
-    args: "[<token>]",
-    flags: [],
+    args: "[<token>] [--force]",
+    flags: ["--force"],
     desc: "log in — browser device-flow, or save a pasted token",
     more: [
+      "already logged in? it's a no-op that points you to `figs link` — pass --force to log in again.",
       "no arg → device flow: opens a browser for a human to approve (you never see the token).",
       "<token> → save a token you already have to ~/.figs/credentials.json.",
     ],
@@ -385,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.
@@ -846,6 +860,17 @@ async function login(token) {
     return
   }
 
+  // Already logged in? Don't start a needless device flow — it strands a cold/headless
+  // agent with no human to approve. Token presence is enough to short-circuit; a stale
+  // token surfaces on the next link/push. `--force` re-runs the flow deliberately.
+  if (!hasFlag("--force") && getToken()) {
+    console.log(`figs: ✓ already logged in to ${originOf(resolveEndpoint())}`)
+    console.log(
+      "        `figs status` for details · `figs link` to connect a workspace · `figs login --force` to log in again",
+    )
+    return
+  }
+
   const start = await request("POST", "/api/device/start")
   if (!start.ok) die(`could not start login (${start.status})`)
   const d = start.data
@@ -1804,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")
@@ -1824,6 +1849,14 @@ async function reportCmd() {
   // Announce new-vs-fold only for an explicit --id — that's where a typo means
   // "I meant to continue a job but opened a sibling" (auto-ids are always new).
   if (idGiven) announceFold("job", id, isNew, " (settled)")
+  // The "why it started": a born-settled job that never checkpointed still shows
+  // "triggered by …" in the manager's timeline when --trigger is set. Nudge it
+  // only on a fresh job (never on a fold/continuation — that would cry wolf).
+  if (isNew && !trigger) {
+    console.log(
+      `figs:   tip: \`--trigger '<what set this in motion>'\` records the "why" — your manager sees it on the job's timeline`,
+    )
+  }
   // Teaching, never a gate: a settled job with open asks citing it is the
   // normal tail-of-job pattern (the ask owns the waiting) — but if the job's
   // OUTCOME depends on an answer, in-flight is the honest state. Local fold
@@ -1861,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")
@@ -1887,6 +1920,11 @@ async function checkpointCmd() {
     console.log(
       `figs:   new job opened: ${id} (in flight) — checkpoint as you go; \`figs report --id ${id}\` settles it`,
     )
+    if (!trigger) {
+      console.log(
+        `figs:   tip: add \`--trigger '<what set this in motion>'\` so your manager sees why this job started`,
+      )
+    }
   } else if (settledBefore) {
     console.warn(
       `figs: ! reopening a settled job (${id}) — continue only if it's truly the same job; new work wants a new id`,
@@ -1937,6 +1975,10 @@ async function askCmd() {
     const v = flag(f)
     if (v) ask[k] = v
   }
+  // Default an unaddressed ask to the manager (the work-accountable human) — the common
+  // case; `--to builder` is the explicit exception. Saves the reader from inferring ("guess").
+  // (Hand-authored JSONL may still omit `to` → unaddressed; the verb is sugar that defaults.)
+  if (!ask.to) ask.to = "manager"
   const options = flagAll("--option")
   if (options.length) ask.options = options
   for (const o of ask.options ?? []) {
@@ -2135,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")
@@ -2163,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.1.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": {