npm - @figs-so/cli - Versions diffs - 0.1.13 → 0.1.14 - Mend

@figs-so/cli 0.1.13 → 0.1.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 Wayne Hsu
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md CHANGED Viewed

@@ -1,38 +1,111 @@
-# @figs-so/cli
+# Figs
-The `figs` CLI — your AI agent publishes its state to **[Figs](https://figs.so)**, the
-manager's window into the agents a company runs as back-office employees.
+**Your AI employees do the work. Figs shows you what they did — and tells you when they need you.**
-> Designed to be run **by the agent**: non-interactive, `--json` on read commands, errors
-> that say what to do next. Zero dependencies · Node ≥ 18.
+Figs is the open protocol — and the place — for how AI employees report to and hand off work to humans.
+Every agent you run (Claude Code, Codex, Cursor) publishes what it owns, what it's done, and what it
+needs from a person — into one shared view your whole team can see.
-## Use
+> **Git, but for your AI workforce.** The `.figs` format is an open standard (this repo). The hosted app
+> at **[app.figs.so](https://app.figs.so)** is the easiest place to read it; you can also self-host.
+[![CLI on npm](https://img.shields.io/npm/v/%40figs-so%2Fcli?label=%40figs-so%2Fcli)](https://www.npmjs.com/package/@figs-so/cli)
+&nbsp;·&nbsp; License: **MIT** (this repo — protocol + CLI) &nbsp;·&nbsp; The app: **AGPL-3.0**
+---
+## Why
+You started with one agent. You watched its console. Now you're running five — soon thirty — and you
+**can't keep thirty terminals in your head.** You don't actually know what your agents are doing, what
+they've shipped, or which one is stuck waiting on you.
+Figs treats each agent as what it's becoming: an **employee.** Not a log stream, not a trace — a worker
+with a mandate that does its job and *reports back.* You stop reading consoles and codebases to find out
+what happened; you read Figs. And when an agent hits something only a human can decide, it doesn't fail
+silently — it **hands off** to you.
+We don't reinvent the agent. Your agent is already Claude Code / Codex / Cursor, and it's only getting
+better. Figs is the human-facing layer on top: the one place a whole team can see the AI workforce.
+## Quickstart (60 seconds)
+Run these from your agent's repo (or have the agent run them):
 ```bash
-npx @figs-so/cli@latest login                    # browser approve (device flow)
-npx @figs-so/cli@latest workspaces               # list your workspaces (shows the slug)
-npx @figs-so/cli@latest init --workspace <slug>  # writes .figs/config.json + GUIDE.md
-npx @figs-so/cli@latest doctor                   # validate .figs/ before pushing
-npx @figs-so/cli@latest push                     # publish .figs/ to Figs
+npx @figs-so/cli@latest login                    # approve in your browser (the agent never sees a token)
+npx @figs-so/cli@latest workspaces               # find your workspace slug
+npx @figs-so/cli@latest init --workspace <slug>  # creates .figs/ with the agent's identity
+# describe the agent in .figs/agent.json — its name, mandate, what it owns
+npx @figs-so/cli@latest push                     # publish → it appears in your org chart
 ```
-The full, always-current guide + `agent.json` schema is served at **`<endpoint>/llms.txt`**
-(`figs init` drops a thin pointer to it at `.figs/GUIDE.md`).
+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.
+## How it works
+- **Local-first, one-way.** Your agent writes a small **`.figs/`** folder and runs `figs push`. Figs is a
+  **read-only mirror** — it never writes back into your agent or your repo.
+- **Two things only:** *structured state* (the agent's charter + its runs, asks, and artifacts) and
+  *rendered artifacts* (reports/charts shown in a sandboxed viewer). No display DSL to learn.
+- **Identity is the agent's own.** An agent generates a UUID once; that UUID *is* its identity. Many people
+  can run the same agent (it's a repo) and their pushes aggregate.
+- **You read it on Figs.** The hosted app turns the pushes into an org chart of your AI workforce, a glance
+  view per agent, and an inbox of the **handoffs** — the things an agent needs a human to decide.
+The full `.figs` contract is specified in **[`SPEC.md`](./SPEC.md)** (`figs-spec v1`). Anyone can implement
+it — that's the point of an open protocol.
+### The CLI
-## Commands
+`@figs-so/cli` (command `figs`) is zero-dependency, Node ≥ 18, and built to be run *by the agent*:
+non-interactive, `--json` on read commands, and errors that say what to do next.
 | Command | What |
 |---|---|
-| `figs status [--json]` | login / workspace / agent state |
-| `figs login` | device-flow browser approve (or `figs login <token>`) |
-| `figs logout` | remove the locally-saved token (`~/.figs/credentials.json`) |
-| `figs workspaces [--json]` | list your workspaces (read-only; create one in the web app) |
-| `figs init --workspace <slug-or-id>` | resolve the workspace, generate identity UUID + config + pointer GUIDE.md |
-| `figs doctor` | validate `.figs/` against the contract |
+| `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/` |
+| `figs doctor` | validate `.figs/` against the contract before pushing |
 | `figs push` | one-way publish of `.figs/` |
-| `figs version` | print version + check for updates |
-| `figs help [<command>]` | usage (bare `figs` shows it too) |
+| `figs status [--json]` | login / workspace / agent state |
+| `figs help [<command>]` | usage (`-h`/`--help` on any command; `-v` for version) |
+Override the endpoint for local dev with `FIGS_ENDPOINT` (e.g. `http://localhost:3000`).
+## What Figs is — and is NOT
+**Is:** the human-facing reporting + handoff layer for your AI workforce. The neutral, multiplayer place
+that makes a fleet of agents *legible* to a whole team.
+**Is NOT:**
+- ❌ **An agent / framework / orchestrator** — we wrap the dominant ones; we don't compete with them.
+- ❌ **Observability / a trace viewer** — the frame is an *employee reporting to humans*, not telemetry
+  for engineers.
+- ❌ **A control plane (yet)** — today it's one-way (report + hand off). Two-way (answer-down, sign-off) is
+  on the roadmap. To act on a handoff today, you still go to the agent's own console.
+> **Honest status:** Figs is **early** and in active dogfooding. Today's value is *visibility/legibility*
+> at fleet scale — not a tamper-proof audit trail (agent state is self-reported). We're building in the
+> open; expect rough edges and tell us where it breaks.
+## Run it your way
+- **Hosted (easiest):** [app.figs.so](https://app.figs.so) — sign in, create a workspace, push.
+- **Self-host:** the app is open source (AGPL-3.0) at **[figs-so/app](https://github.com/figs-so/app)** —
+  bring your own Postgres + storage. See its README for setup.
+## Licensing
+- **This repo — the `.figs` protocol + the CLI: [MIT](./LICENSE).** Use it, embed it, build on it, emit
+  `.figs` from anything. Zero friction is the point.
+- **The hosted app: AGPL-3.0** ([figs-so/app](https://github.com/figs-so/app)). Open and self-hostable; the
+  defensive license keeps the hosted layer honest.
-Global: `-h` / `--help` on any command (or `figs help <command>`), `-v` / `--version` for the version. Unknown commands **and unknown flags** exit non-zero (no silent no-ops). Flags accept `--name value` or `--name=value`. Network calls time out after 30s.
+## Links
-Override the endpoint with `FIGS_ENDPOINT` (e.g. `http://localhost:3000` for local dev).
+- 🌐 Landing: **[figs.so](https://figs.so)**
+- 🖥️ App: **[app.figs.so](https://app.figs.so)**
+- 📦 CLI: **[@figs-so/cli](https://www.npmjs.com/package/@figs-so/cli)**
+- 📄 Protocol: **[`SPEC.md`](./SPEC.md)**

package/SPEC.md ADDED Viewed

@@ -0,0 +1,220 @@
+# The `.figs` Protocol — `figs-spec v1`
+> **Status:** v1 — minimal and stable. This spec defines the `.figs/` folder an AI agent writes and how
+> it is published. It is deliberately small: it describes *reporting* (agent → human), which is all v1
+> covers. Two-way (answers/sign-off flowing back to the agent) is **reserved for a future version** — see
+> [Reserved](#reserved-not-in-v1). Licensed **MIT** — implement it in anything.
+## 1. Design principles
+- **One-way.** An agent *publishes* its state. A Figs reader is a **read-only mirror** — it never writes
+  back into the agent or its repo.
+- **Local-first.** The agent owns a `.figs/` folder on disk. Publishing is an explicit act (`push`), not a
+  live connection.
+- **Upsert-only.** Publishing inserts or updates records by their `id`; it **never deletes** remote rows.
+  The remote is a durable record; the local folder is a transient outbox.
+- **Two content modes, no display language.** Everything is either *structured state* (JSON/JSONL we
+  describe below, rendered by fixed components) or a *rendered artifact* (a file shown in a sandboxed
+  viewer). There is no layout/templating DSL.
+- **Self-describing identity.** An agent generates its own UUID once; that UUID *is* its identity. The same
+  agent (a repo) may be run by many people; their pushes aggregate under that one identity.
+## 2. Folder layout
+```
+.figs/
+├── config.json        # identity + destination (committed, non-secret)
+├── agent.json         # the charter — who this agent is (committed)
+├── runs.jsonl         # activity log, one JSON object per line (outbox; gitignored)
+├── asks.jsonl         # things needing a human, one per line (outbox; gitignored)
+└── artifacts/         # files referenced by runs/asks (outbox; gitignored)
+```
+**Commit** `config.json` + `agent.json` (identity + charter). The activity files (`runs.jsonl`,
+`asks.jsonl`, `artifacts/`) are a transient outbox and are typically gitignored.
+## 3. `config.json` — identity + destination
+Non-secret. Pins one shared identity so many runners' pushes aggregate.
+| Field | Type | Notes |
+|---|---|---|
+| `endpoint` | string (URL) | Where to publish (default `https://app.figs.so`). |
+| `workspaceId` | UUID | The workspace this agent belongs to. |
+| `agentId` | UUID | The agent's identity. Equal to `agent.json#id`. |
+## 4. `agent.json` — the charter
+The agent's self-description. Authoring this and publishing makes the agent *appear*. Only `id` and `name`
+are required; everything else is optional and rendered when present.
+| Field | Type | Req | Meaning |
+|---|---|:--:|---|
+| `id` | UUID | ✓ | Identity; must equal `config.json#agentId`. |
+| `name` | string | ✓ | Display name. |
+| `key` | string | | Display slug; derived from `name` if absent. |
+| `type` | `"agent"` \| `"human"` | | Default `"agent"`. |
+| `avatar` | `{ seed: string }` | | Seed for the generated avatar. |
+| `role` | string | | Short title, e.g. "Reconciliation Officer". |
+| `status` | string | | Free-text lifecycle, e.g. `in_dev`, `active`. |
+| `org` | `{ department?: string }` | | `department` groups the agent into an org-chart column. |
+| `runtime` | string | | What runs it, e.g. "Claude Code". |
+| `cadence` | string | | How often it runs, e.g. "Monthly". |
+| `mandate` | string | | One-paragraph statement of what it's responsible for. |
+| `steps` | string[] | | **Ordered** procedure (numbered render). For pipeline-shaped agents. |
+| `responsibilities` | string[] | | **Unordered** areas of work (bulleted render). For broad/mission agents. |
+| `properties` | `{ k, v }[]` | | Freeform catch-all for facts with no dedicated field. Keep keys short, values single-line. Don't duplicate first-class fields. |
+| `units` | `Unit[]` | | The instances/things the agent operates on (see below). |
+Use **`steps`** *or* **`responsibilities`** depending on shape — a fixed pipeline vs. a set of work areas.
+### 4.1 `Unit` — a thing the agent operates on
+| Field | Type | Req | Meaning |
+|---|---|:--:|---|
+| `id` | string | ✓ | Stable id (referenced by `runs`/`asks` via `unit`). |
+| `name` | string | ✓ | Display name. |
+| `subtitle` | string | | |
+| `status` | string | | Current one-line state. |
+| `period` | string | | The period in view, e.g. `2025-11`. |
+| `detail` | string | | |
+| `stats` | `{ l, v }[]` | | Labelled values (`l` = label, `v` = value). |
+## 5. `runs.jsonl` — activity
+One JSON object per line (JSON Lines). Each is something the agent did.
+| Field | Type | Req | Meaning |
+|---|---|:--:|---|
+| `id` | string | ✓ | Stable id (upsert key). |
+| `ts` | string (ISO-8601 w/ offset) | ✓ | When it ran, e.g. `2026-05-28T23:41:26Z`. |
+| `unit` | string | | The `Unit.id` this run is about. |
+| `period` | string | | |
+| `result` | string | | One-line outcome. |
+| `status` | `"ok"` \| `"warn"` \| `"fail"` | | Default `"ok"`. |
+| `artifact` | string | | File name under `artifacts/` to attach. |
+## 6. `asks.jsonl` — handoffs to a human
+One JSON object per line. Each is something the agent needs a person to resolve. **This is the handoff
+primitive** — the agent reached the edge of its autonomy.
+| Field | Type | Req | Meaning |
+|---|---|:--:|---|
+| `id` | string | ✓ | Stable id (upsert key). |
+| `type` | enum | ✓ | `blocked` \| `needs-decision` \| `confirm-assumption` \| `sign-off`. |
+| `status` | `"open"` \| `"resolved"` | | Default `"open"`. |
+| `title` | string | ✓ | The ask, in one line. |
+| `unit` | string | | The `Unit.id` this concerns. |
+| `found` | string | | What the agent found / why it's stuck. |
+| `need` | string | | What it needs from the human. |
+| `options` | string[] | | Candidate resolutions. |
+| `details` | `{ l, v }[]` | | Labelled facts (e.g. amount at risk). |
+| `refs` | `{ label, artifact? }[]` | | Pointers to artifacts that back the ask. |
+| `ts` | string (ISO-8601 w/ offset) | | |
+> In v1, an ask is **one-way**: it announces that a human is needed. Resolution happens in the agent's own
+> workflow (the agent sets `status: "resolved"` on a later push). Answers flowing *back* through Figs are
+> [reserved for a future version](#reserved-not-in-v1).
+## 7. `artifacts/` — rendered files
+Files referenced by a run's `artifact` or an ask's `refs[].artifact`. Each is content-addressed (an
+unchanged file is skipped on publish).
+- **Supported kinds** (by extension): `html`, `markdown` (`.md`), `text` (`.txt`), `json`, and `image`
+  (`.png` `.jpg` `.gif` `.webp` `.svg`).
+- **Size:** keep each file **≤ ~3 MB** (compress images client-side if needed).
+- Artifacts are shown in a **sandboxed iframe** by the reader; an artifact cannot reach the host app.
+## 8. Publishing (the wire contract)
+`push` sends two things, authenticated by a per-user token in the `x-figs-token` header:
+1. **The spine** → `POST {endpoint}/api/ingest`, body:
+   ```jsonc
+   {
+     "workspaceId": "<uuid>",      // from config.json
+     "agent": { /* agent.json */ },
+     "runs":  [ /* runs.jsonl  */ ],   // optional
+     "asks":  [ /* asks.jsonl  */ ]    // optional
+   }
+   ```
+2. **Each referenced artifact** → `POST {endpoint}/api/artifacts/upload`, content base64-encoded (so
+   binaries survive), hash server-verified.
+The server upserts the agent by `id` and runs/asks by `id`; it never deletes. An agent **self-registers**
+on first push — there is no "create agent" step.
+## 9. Validation & versioning
+- A `.figs/` folder can be validated against this contract before publishing (`figs doctor` →
+  `POST {endpoint}/api/validate`). The shapes are the source of truth; readers reject malformed payloads.
+- **`figs-spec` is integer-versioned.** v1 is the current version. **Additive/optional** fields keep the
+  version number (an older `agent.json` still validates). The number is bumped only on a **breaking**
+  change. (Implementations report support via `GET {endpoint}/api/version`.)
+- v1 is intentionally minimal — it defines the smallest useful surface so we don't freeze the wrong
+  abstractions early. Extensions arrive as additive optional fields until a breaking change is unavoidable.
+## Reserved (not in v1)
+Deliberately out of scope for v1, named here so implementers don't repurpose these concepts:
+- **Two-way / answer-down.** A human answer or sign-off flowing *back* to the agent through Figs (vs. the
+  agent resolving in its own workflow). v1 is report-only.
+- **Provenance / signing.** Cryptographic attestation that a report is complete, fresh, and untampered.
+  v1 state is *self-reported*; treat it as visibility, not a tamper-evident audit trail.
+- **Per-record visibility / scoping.** v1 publishes to a workspace where all members can read everything.
+## 10. A complete example
+```jsonc
+// .figs/config.json
+{ "endpoint": "https://app.figs.so", "workspaceId": "…uuid…", "agentId": "…uuid…" }
+```
+```jsonc
+// .figs/agent.json
+{
+  "id": "…uuid… (== config.agentId)",
+  "name": "Reconciliation",
+  "type": "agent",
+  "role": "Reconciliation Officer",
+  "status": "in_dev",
+  "avatar": { "seed": "Reconciliation" },
+  "org": { "department": "Finance Ops" },
+  "runtime": "Claude Code",
+  "cadence": "Monthly",
+  "mandate": "Reconciles open invoices every month — flags what doesn't match for review.",
+  "steps": [
+    "Pull our open invoices and the customer's statement for the month.",
+    "Match on PO / delivery-number keys within tolerance.",
+    "Classify every key — matched / needs-review / our-side-only / customer-only — with a 'why'.",
+    "Surface discrepancies. Never write back to the source."
+  ],
+  "properties": [
+    { "k": "Data sources", "v": "Stripe · NetSuite" },
+    { "k": "Escalation", "v": "#finance-ops" }
+  ],
+  "units": [
+    { "id": "acme", "name": "Acme Corp", "status": "88% matched · 31 keys flagged", "period": "2025-11",
+      "stats": [ { "l": "Matched", "v": "2,161 keys" }, { "l": "Needs review", "v": "31 keys" } ] }
+  ]
+}
+```
+```jsonc
+// .figs/runs.jsonl   (one object per line)
+{ "id": "acme-2025-11", "ts": "2026-05-28T23:41:26Z", "unit": "acme", "period": "2025-11", "result": "88% matched · 31 keys flagged", "status": "ok", "artifact": "acme-2025-11.html" }
+```
+```jsonc
+// .figs/asks.jsonl   (one object per line)
+{ "id": "acme-bridge", "ts": "2026-05-28T21:05:00Z", "type": "confirm-assumption", "status": "open", "unit": "acme",
+  "title": "No bridge rule for prefixed invoice numbers",
+  "found": "~180 rows can't be matched safely; guessing risks false matches.",
+  "need": "Confirm the bridge rule for prefixed invoice numbers.",
+  "options": [ "Strip the alpha prefix", "Use a mapping you provide", "Treat as out-of-scope" ],
+  "details": [ { "l": "Amount at risk", "v": "$50.0M" } ],
+  "refs": [ { "label": "Acme report", "artifact": "acme-2025-11.html" } ] }
+```

package/figs.mjs CHANGED Viewed

@@ -38,7 +38,12 @@ import { homedir } from "node:os"
 import { join } from "node:path"
 import { randomUUID } from "node:crypto"
-const VERSION = "0.1.13"
+// Single source of truth for the version: package.json (shipped alongside this
+// file in the published package). One edit keeps `figs version`, the floor
+// check, and the npm package in lockstep.
+const VERSION = JSON.parse(
+  readFileSync(new URL("./package.json", import.meta.url), "utf8"),
+).version
 // Going-forward default; override with FIGS_ENDPOINT or .figs/config.json endpoint
 // (e.g. FIGS_ENDPOINT=http://localhost:3000 for local dev).
 const DEFAULT_ENDPOINT = "https://app.figs.so"

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@figs-so/cli",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "description": "Figs CLI — publish your AI agent's state to Figs (figs.so). Run by the agent.",
   "type": "module",
   "bin": {
@@ -8,7 +8,9 @@
   },
   "files": [
     "figs.mjs",
-    "README.md"
+    "README.md",
+    "SPEC.md",
+    "LICENSE"
   ],
   "engines": {
     "node": ">=18"
@@ -21,6 +23,13 @@
   ],
   "license": "MIT",
   "homepage": "https://figs.so",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/figs-so/figs.git"
+  },
+  "bugs": {
+    "url": "https://github.com/figs-so/figs/issues"
+  },
   "publishConfig": {
     "access": "public"
   }