@arbidocs/cli 0.4.76 → 0.4.78

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## v0.4.78
+
+[compare changes](https://github.com/arbicity/ARBI-frontend/compare/v0.4.77...HEAD)
+
+### 🚀 Enhancements
+
+- **blocks:** Readable workflow step bar with prev/current/next window ([5b49b05aa](https://github.com/arbicity/ARBI-frontend/commit/5b49b05aa))
+
+## v0.4.77
+
+[compare changes](https://github.com/arbicity/ARBI-frontend/compare/v0.4.76...HEAD)
+
+### 🚀 Enhancements
+
+- **sdk:** Workflow signals, send-back, tag fields, project details and spend ([d69f79fbb](https://github.com/arbicity/ARBI-frontend/commit/d69f79fbb))
+- **react:** Hooks for the tag matrix, project details, spend and send-back ([cbea31105](https://github.com/arbicity/ARBI-frontend/commit/cbea31105))
+- **cli:** Send-back, review fields, signals, tag matrix, project details and spend ([9b4d3a91a](https://github.com/arbicity/ARBI-frontend/commit/9b4d3a91a))
+- **blocks:** Workflow action steps, assignees and send-back in the builder and runner ([e2302faed](https://github.com/arbicity/ARBI-frontend/commit/e2302faed))
+- Workflow step actions in the thread bar and step chips in chat ([03db457a6](https://github.com/arbicity/ARBI-frontend/commit/03db457a6))
+
+### 🩹 Fixes
+
+- **sdk:** Stop reading the stream once response.completed arrives ([470862f40](https://github.com/arbicity/ARBI-frontend/commit/470862f40))
+
+### 🏡 Chore
+
+- Regenerate OpenAPI schema ([89eb57d20](https://github.com/arbicity/ARBI-frontend/commit/89eb57d20))
+
 ## v0.4.76
 
 [compare changes](https://github.com/arbicity/ARBI-frontend/compare/v0.4.75...HEAD)

package/SKILL.md

@@ -61,7 +61,7 @@ Scripting notes:
 
 ## For Automations / AI Agents
 
-- **Structured output (`--json`)**: supported on `status`, `config show`, `health`, `models`, `workspaces`, `workspace users`, `workspace current`, `docs`, `convo` (or `convo list`), `tags` (or `tags list`), `contacts` (or `contacts list`), `find`, `settings get`, `task list` / `task status` / `task result`, `agent list`, `session list`, `dm list`, `notifications list`, `local ls` / `local find` / `local cat` / `local tree`, `update --check`, `register --non-interactive`, `ask -b`, `upload`, `watch`, `workflow list` / `create` / `run` / `update`, `run start` / `run steps` / `run step`. Use it whenever parsing output. `docs` also supports `--csv`, `--ids`, and `--count`. `arbi ask --json` without `-b` errors out — streaming mode is prose, not JSON; pass `-b` to get a background task ID, then `arbi task result --json`.
+- **Structured output (`--json`)**: supported on `status`, `config show`, `health`, `models`, `workspaces`, `workspace users`, `workspace current`, `docs`, `convo` (or `convo list`), `tags` (or `tags list`), `contacts` (or `contacts list`), `find`, `settings get`, `task list` / `task status` / `task result`, `agent list`, `session list`, `dm list`, `notifications list`, `local ls` / `local find` / `local cat` / `local tree`, `update --check`, `register --non-interactive`, `ask -b`, `upload`, `watch`, `workflow list` / `create` / `run` / `update`, `run start` / `run steps` / `run step`, `tags create` / `tags fields` / `tags matrix`, `project set` / `show` / `events`, `usage conversation` / `usage project`. Use it whenever parsing output. `docs` also supports `--csv`, `--ids`, and `--count`. `arbi ask --json` without `-b` errors out — streaming mode is prose, not JSON; pass `-b` to get a background task ID, then `arbi task result --json`.
 - **Human table output is lossy**: table rows may contain status glyphs (`●`, `🟩`, etc.) and emoji, and column widths truncate content. Never parse tables — always pass `--json`.
 - **Exit codes**:
   - `0` success
@@ -95,7 +95,8 @@ All document list/search/meta commands support machine-readable output. Prefer `
 - **Per-doc**: `arbi doc get <id...>` returns full JSON (no flag needed). `arbi doc delete <id...>` and `arbi doc update <id> '<json>'` take IDs directly.
 - **Upload by URL**: `arbi doc upload-url <url> --json`.
 - **Download**: `arbi download <id> -o <path>` writes the file; `-o -` streams raw bytes to stdout; `--json` emits a `{doc_id, path, bytes, filename}` metadata line after writing.
-- **Tags**: `arbi tags list --json`, `arbi tags create <name> -t <type>`, `arbi tags delete <id>`.
+- **Tags**: `arbi tags list --json`, `arbi tags create <name> -t <type> [--parent <tag>]`, `arbi tags delete <id>`.
+- **Tag fields and the matrix**: a tag can carry typed fields (`text`, `number`, `date`, `checkbox`, `select`, `person`); a child tag inherits its parent's, so a parent's fields are the columns of its children. `arbi tags fields <tag>` shows a tag's fields and values; `--define '<json>'` (or a `.json`/`.yaml` file of `[{name, type, options}]`) sets its own fields (a field defined again by name keeps its values; ones left out are dropped unless `--keep-others`); `--set name=value` (repeatable, `name=` clears) sets values, checked against the fields and a select's options. `arbi tags matrix --parent <tag>` (or `--tag <tag>` repeated) prints rows = tags, columns = fields, then DOCS and FACTS counts, gaps marked `—` and listed; `--json` adds each row's newest documents and facts (`--links <n>`). Tags are taken by id or unique name.
 - **Doctags** (tag↔doc link): `arbi doctags create <tag-id> <doc-id...>` / `arbi doctags delete <tag-id> <doc-id...>`.
 - **Retrieve only**: `arbi find <query> --json` returns raw retrieval results without running the LLM.
 - **Exit codes**: 0 on success (including clean skips), 1 on error. Errors print to stderr.
@@ -117,8 +118,10 @@ All list commands that summarize people or state support `--json`:
 - **Inbox housekeeping**: `arbi notifications mark-read --all` and `arbi notifications delete --all` drain the non-DM queue for long-running agents whose `--unread` filter would otherwise grow unbounded.
 - **Leave a workspace**: `arbi workspace leave [id-or-name]` self-removes from a workspace (defaults to the active one); requires `-y/--yes` in non-TTY shells. Symmetric to `arbi workspace add-user`.
 - **Projects**: `arbi project list` (and `create`, `refresh`) — projects are the tenancy unit above workspaces. Until this command existed the only way to discover a `projectExtId` was inside `arbi register`, blocking multi-project bootstrap from a fresh agent install.
+- **Project details**: `arbi project set <prj> --budget 6000GBP --client 'Acme Ltd' --client-ref crm-1042 --stage Discovery --lead <usr-id|email> --field matter_type=dispute` (owner only; `none` clears a detail, `--field key=` removes a field; the budget is stored in minor units, so `6000GBP` is 600000 pence). The lead must be a member of one of the project's workspaces. `arbi project show <prj>` prints them; `arbi project events <prj> [--kind stage_changed|budget_changed] --json` lists stage and budget changes, newest first; `arbi project list --stage <label> --lead <usr-id|email>` filters. Projects are taken by id or unique name.
 - **Files (Responses API attachments)**: `arbi files list/upload/get/delete/content` — ephemeral files for the OpenAI-compatible Responses path. Independent of the workspace document index; meant for short-lived attachments to single `arbi ask -b` requests.
 - **Usage probe**: `arbi usage today --json` is the cheapest pre-flight check before launching a long batch. Returns whatever quota the project surfaces (credits, storage, token caps) so agents can budget.
+- **Spend**: `arbi usage conversation <con-id>` shows what a thread's AI work cost this billing period by step, run (a send-back runs a step again), model and agent (`--json` adds `by_feature`); `arbi usage project <prj> --by-conversation [--months-back N]` shows a project's spend per conversation plus what no conversation accounts for. Spend is in credits.
 - **Execution trace**: `arbi convo trace <message-id>` (alias of `arbi convo message`) returns the full decrypted reasoning + tool-call trail for one agent response. Post-mortem primitive for debugging failed steps.
 - **Switch conversations**: `arbi convo switch <conv-id>` points the chat session at a different conversation so the next `arbi ask` resumes there. CLI equivalent of clicking a conversation in the web UI sidebar.
 
@@ -151,7 +154,7 @@ Footnote-style rendering at the end of the answer is currently not supported —
 
 ## Workflows
 
-A workflow starts by hand (no trigger flags), on a schedule (`--run-at` or `--rrule`), on an event (`--event-kind`, optional `--event-filter` JSON), or after a task (`--after <con-id>`). It runs a prompt, a skill, a document action, or named steps (`--steps <file>`). `arbi automation` is an alias for `arbi workflow`. `run <wfl-id>` starts any saved workflow now. Scheduled document actions require an assistant with standing workspace access (`--agent <agt-id> --auth-mode scheduled_permanent`). Do not silently grant that access.
+A workflow starts by hand (no trigger flags), on a schedule (`--run-at` or `--rrule`), on an event (`--event-kind`, optional `--event-filter` JSON), on a signal another run's step raises (`--on-signal <name>`), or after a task (`--after <con-id>`). It runs a prompt, a skill, a document action, or named steps (`--steps <file>`). `arbi automation` is an alias for `arbi workflow`. `run <wfl-id>` starts any saved workflow now. Scheduled document actions require an assistant with standing workspace access (`--agent <agt-id> --auth-mode scheduled_permanent`). Do not silently grant that access.
 
 ```bash
 # Daily annotation review of documents currently carrying a label.
@@ -167,7 +170,7 @@ Document actions return `execution_id` and do not require a conversation. Execut
 
 ### Stepped workflows (forms, agent steps, reviews)
 
-A stepped workflow's steps are a list in the API's `TaskPlanStep` shape, in a `.json`, `.yaml` or `.yml` file (a list, or an object with `steps`). Fields: `id` (lowercase, `[a-z][a-z0-9_-]*`), `title`, `kind` (`form` | `upload` | `agent` | `review`), `after` (step ids it waits for; default the step before it, `[]` = at the start), `prompt` or `skill` (agent steps only; `{{field}}` fills from the run's inputs), `inputs` (a skill step's input templates), `branch` (agent steps), `ui` (what the app shows: a form's `fields` as `{name, type, label, required}`, a review's `instructions`). The CLI checks the file before sending it and lists every problem (`steps[1].kind: must be one of …`).
+A stepped workflow's steps are a list in the API's `TaskPlanStep` shape, in a `.json`, `.yaml` or `.yml` file (a list, or an object with `steps`). Fields: `id` (lowercase, `[a-z][a-z0-9_-]*`), `title`, `kind` (`form` | `upload` | `agent` | `review`), `after` (step ids it waits for; default the step before it, `[]` = at the start), `prompt` or `skill` (agent steps only; `{{field}}` fills from the run's inputs), `inputs` (a skill step's input templates), `branch` (agent steps), `ui` (what the app shows: a form's `fields` as `{name, type, label, required}`, a review's `instructions`), and `signals`, `assignee`, `remind_after_hours`, `fields` (below). The CLI checks the file before sending it and lists every problem (`steps[1].kind: must be one of …`).
 
 ```yaml
 # steps.yaml
@@ -200,7 +203,45 @@ arbi run step con-example draft skip                                  # skip any
 arbi run start --steps steps.yaml --title 'Acme note' --input client=Acme   # a one-off run, no saved workflow
 ```
 
-`arbi run steps --json` gives `waiting_on` (`person` | `agent` | `finished` | `stuck`) and per step `state`, `after`, `answer_id` (a done agent step's message in the thread) and `error`; with `--answers` each done agent step also has `answer` (its text). `--watch` polls (`--interval`, default 3s) until the run stops waiting on an agent step (`--timeout`, default 600s; `timed_out` in the JSON). A form step's required fields are checked before completing it. Agent steps run themselves: they can only be skipped.
+`arbi run steps --json` gives `waiting_on` (`person` | `agent` | `finished` | `stuck`) and per step `state`, `after`, `answer_id` (a done agent step's message in the thread) and `error`; with `--answers` each done agent step also has `answer` (its text). `--watch` polls (`--interval`, default 3s) until the run stops waiting on an agent step (`--timeout`, default 600s; `timed_out` in the JSON). A form step's required fields are checked before completing it. Agent steps run themselves: they can only be skipped (or sent back to).
+
+#### Signals, assignees, reminders, fields and send-back
+
+A step can also have:
+
+- `signals`: `[{name, when}]` raised when the step is **done** and `when` holds — `{contains: "phrase"}` or `{matches: "regex"}` on an agent step's answer, `{field: name, equals: value}` on a form value, `{approved: true}` on a review; no `when` = always. Names are `[a-z0-9][a-z0-9_.-]*`. A signal starts every workflow made with `--on-signal <name>` (shorthand for `--event-kind workflow_signal --event-filter '{"signal":"<name>"}'`); the new thread is linked to the run that raised it and gets its inputs.
+- `assignee`: exactly one of `{user: usr-…}`, `{run_owner: true}`, `{input: <person field>}` or `{project_lead: true}` — who is told when it is ready, and (with the run's owner and workspace owners) the only one who may complete it or send it back.
+- `remind_after_hours`: a person step not done this long after it became ready is notified once more.
+- `fields` (person steps): what completing it asks for, e.g. a rating at sign-off — `[{name, type, label, required, options: [{value}], min, max}]`, types `text`, `longtext`, `boolean`, `select`, `number`, `date`, `scope`, `documents`, `person`. `arbi run step … complete --input name=value` is checked against them (the option, the range, required, unknown names) before it is sent.
+
+```yaml
+# risk.yaml — the agent rates the risk and signals; the run's owner signs off with a rating
+- id: risk
+  title: Rate the risk
+  kind: agent
+  prompt: Assess the contract's risk. End with the line "Risk rating: High" when it is high.
+  signals:
+    - { name: risk-high, when: { contains: "Risk rating: High" } }
+- id: signoff
+  title: Sign off
+  kind: review
+  assignee: { run_owner: true }
+  remind_after_hours: 24
+  fields:
+    - { name: rating, type: select, required: true, options: [{ value: low }, { value: medium }, { value: high }] }
+```
+
+```bash
+arbi workflow create --name 'Contract risk' --steps risk.yaml
+arbi workflow create --name 'Escalate' --steps escalate.yaml --on-signal risk-high --shared   # starts on each risk-high
+arbi workflow run wfl-risk                                              # → con-run
+arbi run steps con-run --watch --answers   # NOTES: ⚑ risk-high; → con-linked   FOR: run owner
+arbi run step con-run signoff send-back --note 'Name the clauses and suggest a cap'   # reopens risk (+ signoff); the agent runs again with the note
+arbi run step con-run signoff complete --input rating=high
+arbi usage conversation con-run                                          # spend by step, run, model, agent
+```
+
+`send-back` goes from a ready person step to a step it waits for (`--to <step>`, default the one step it waits for; required when it waits for several): that step and every step after it are open again, and an agent step runs again with the `--note`. `arbi run steps` shows who each step is for (`FOR`), what it sent back or raised (`NOTES`), and the run's signals, linked runs (`arbi run steps <con-linked>` shows `Started from <con-run>`) and send-backs, oldest first; the JSON has per step `assignee`, `announced_to`, `sent_back`, `sent_back_note`, `times_sent_back`, `signals`, `linked_runs`, and per run `signals`, `linked_runs`, `send_backs`. The note itself is encrypted in the thread's history. The message that starts an agent step carries `tools.workflow_step` (the step id) in `arbi convo threads` output. `arbi workflow list` shows each workflow's `TRIGGER` (`signal risk-high`, `by hand`, …).
 
 In the terminal UI: `/automations` lists rules; `/automation view|run|runs|pause|resume|delete <wfl-id>` manages them; `/automation create <JSON>` and `/automation update <wfl-id> <JSON>` accept the same request bodies as the SDK.