fruxon 2.0.2__tar.gz → 2.2.0__tar.gz

{fruxon-2.0.2 → fruxon-2.2.0}/HISTORY.md

@@ -1,5 +1,65 @@
 # History
 
+## Unreleased — whoami and the 403 hint read the role cap off the key
+
+- On a server with fruxon-backend #1571, `fruxon whoami` and the 403
+  `insufficient_scope` hint take your role and the scopes in effect from
+  `/tokens/current` (`ownerRole`, `effectiveScopes`) instead of also reading
+  your membership, which needs `workspace:read`. A key without that scope now
+  gets its role named instead of "couldn't be read". Older servers keep the
+  membership read.
+- **`fruxon whoami`** lists a service-account key's grant (`N scopes from its
+  grant`, and `effectiveScopes` under `current_key` in `-o json`) instead of
+  calling it "dead weight" for carrying no scopes of its own.
+
+## Unreleased — say when your workspace role, not the key, refuses a call
+
+- A 403 `insufficient_scope` for a scope the key already carries no longer
+  says to re-run `fruxon login --preset …`. Since fruxon-backend `f5aaf1250`
+  the server caps a personal key to its owner's current workspace role, so a
+  Viewer's key minted with `agents:write` is refused it, and a new key would be
+  refused the same way. The CLI now asks the refused key what it carries
+  (`/tokens/current`, then the owner's membership) and, when the key has the
+  scope, says the role is the limit and to ask a workspace Admin to raise it or
+  make the change. A key that lacks the scope, a service-account key, or a
+  lookup that fails keeps the preset hint.
+- **`fruxon whoami`** labels its scope list as the key's own and adds a line
+  with your role in the workspace and how many of those scopes it leaves in
+  effect. `-o json` adds `ownerType`, `ownerRole` and `effectiveScopes` under
+  `current_key` (`null` when the role couldn't be read).
+- `InsufficientScopeError.client` is the client whose request was refused, and
+  `FruxonClient.get_user(user)` reads one workspace member, including `role`
+  and `effectiveScopes`.
+
+## Unreleased — read voice calls back
+
+- **`fruxon agents voice-calls list <agent>`** lists the agent's Talk calls
+  from the Test lab, newest first. Each row has the status, language, why the
+  call ended, its turns and its length. Output is `table`, `json` or `id`.
+- **`fruxon agents voice-calls get <agent> <call-id>`** shows one call turn by
+  turn: what the caller said, the whole reply, and what was heard of it. When
+  the caller cut in, `delivery` is `INTERRUPTED` and `spokenText` is the part
+  they heard. Each turn also carries `generation` and the run behind its reply
+  (`executionRecordId`, for `agents executions trace`). Output is `text`,
+  `table` or `json`.
+- Client methods `list_voice_calls` and `get_voice_call` return the new
+  `VoiceCall` and `VoiceCallTurn`. Both need fruxon-backend #1537; an older
+  server answers 404.
+
+## Unreleased — one completion on an LLM config, with no agent
+
+- **`fruxon llm-providers configs complete <provider> <config> --model M`**
+  sends a system prompt and a short conversation to a model through the
+  config's published revision and prints the reply, with no agent, session or
+  execution record (scope `llm_providers:test`; fruxon-backend `:complete`).
+  It answers "does this model follow that instruction?" — pass a platform
+  system block's text as `--system` and read the reply — without a test turn
+  that writes to a live agent. `--system` (text, `@file`, `-`; repeatable),
+  `-m [user:|assistant:]TEXT` (repeatable) or `--messages chat.json`,
+  `--temperature`, `--max-tokens` (server cap 8192), `--param k=v`. The reply
+  goes to stdout, model, finish reason, tokens and latency to stderr; `-o json`
+  passes the server's result through. A Fruxon-hosted provider is refused.
+
 ## Unreleased — `fruxon messages list --reason EMAIL_THREAD_UNAVAILABLE`
 
 - `--reason` takes the server's new `EMAIL_THREAD_UNAVAILABLE` (fruxon-backend

{fruxon-2.0.2 → fruxon-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fruxon
-Version: 2.0.2
+Version: 2.2.0
 Summary: The Fruxon SDK is a lightweight Python client for integrating with the Fruxon platform.
 Project-URL: bugs, https://github.com/fruxon-ai/fruxon-sdk/issues
 Project-URL: changelog, https://github.com/fruxon-ai/fruxon-sdk/blob/main/HISTORY.md
@@ -104,6 +104,7 @@ Execution:
 | `fruxon escalations list/history/unhandled/policy/ack` | What happened when an agent handed a conversation to a person. `list` is the queue (live takeovers + degraded escalations nobody was reachable for); `unhandled` is the append-only ledger under it. **`history` is the record of closed console-routed takeovers** — those leave the queue, so `list --status ALL` answers `[]` about a conversation a human worked for half an hour. Read `humanObservedAt` before believing a `RESOLVED`: null means nobody was ever seen picking it up. `policy <agent>` resolves who the *next* escalation would reach — an empty ladder under `NATIVE_HANDOFF` is correct, the console supplies the human. |
 | `fruxon messages list` | The channel ledger — including inbound an agent was never shown. A **withheld** message (a human owns the chat in the source console, or admission refused the sender) never becomes a conversation turn, so it is in no transcript and the thread reads as a customer being ignored. `--delivery WITHHELD_PENDING` lists the ones nothing has ever acted on; nothing drains them. |
 | `fruxon agents sandbox open/turn/fire/resolve-input/stream/answer/close <session>` | Drive an agent-network sandbox end-to-end without real channels — send turns as participants, test-fire triggers, and watch the run (`stream`, NDJSON in agent mode). Sandbox **captures the reply and hard-blocks every real send**; `--await` makes consult/approval gates suspend so they can be resolved (`answer` for consults, `approvals respond` for approvals). `--draft` runs your unpublished draft instead of the deployed revision (`sandbox draft <session>` says which); `--confirm-writes` holds every create/update/delete tool call for approval, because sandbox does **not** block integration writes; a write that did not run (rejected, expired, or one the run could not pause for) shows on `stream` as `refused`. |
+| `fruxon agents voice-calls list/get <agent>` | Read back the Test lab's Talk calls. `list` gives calls newest first (status, end reason, turns, length). `get <agent> <call-id>` gives the call turn by turn: the caller's transcript, the reply, what was heard of it (`delivery`; `spokenText` when the caller cut in), and each reply's `executionRecordId` for `agents executions trace`. Read-only; needs `executions:read`. |
 | `fruxon agents sandbox fork <agent> <message-id>` | Fork a real conversation at a transcript row (an `id` from `agents topics messages`) into a sandbox session already holding the history the agent had when it produced that reply. `--send` re-sends the customer's message against it — with `--draft` to test an edit before publishing — and holds writes for approval unless `--no-confirm-writes`. |
 | `fruxon agents sandbox test <file-or-dir>` | Run scenario-based e2e tests of an agent's network behavior. A scenario (YAML/JSON) declares `steps` (turns / trigger fires), `responders` (scripted consult/approval answers), and `expect` assertions (reply / routing / tools called or refused / no-leak / outcome); the runner drives a sandbox session and returns one verdict — exit 0 (pass) / 1 (fail) / 12 (bad file), with `--junit` for CI. An optional `setup` block provisions real resources first — an `asset` (uploaded + ingestion-waited), `participant`, or `agent` — templated as `${asset.catalog.id}` and **torn down afterwards even on failure** (`--keep` to inspect). Assertions are deterministic by default; `reply_judge: {metric, min_score}` adds an opt-in **semantic** check that scores the reply against a tenant eval metric. The thing an agent runs to prove the agent it built works. |
 
@@ -151,6 +152,7 @@ Integrations + tools:
 | `fruxon llm-providers list/get/models` | Browse LLM providers and models supported at the tenant level. |
 | `fruxon llm-providers connect <provider>` / `link-status` | Create a config for an LLM provider and print a **credential link**: a human opens it, signs in to Fruxon, types the API key (or access keys, or service account key), and the page tests it with the provider and publishes the config an agent pins as `provider.tenantConfigId`. The key never passes through the terminal or an agent driving the CLI. `--config <id>` fills an existing config, `--param name=value` sets a non-secret setting such as Bedrock's `region`, `--no-sign-in` mints a link anyone holding it can fill (Admin or Owner). `link-status <provider> <config> <request> [--wait]` says when it was filled. |
 | `fruxon llm-providers configs list/get/test/publish` | The workspace's saved LLM credentials — the `provider.tenantConfigId` an agent pins. `get` shows the draft (secrets masked), the published revision and last known health. `test` probes the draft on every provider surface that shares the credential (or just one, given that surface's provider id), one line per failing surface, exit 12 on failure (`llm_providers:test`). `publish` ships the draft as a new revision that every agent on the config switches to — it confirms, needs `--yes` in agent mode, and does not wait on a passing test (`llm_providers:write`). |
+| `fruxon llm-providers configs complete <provider> <config> --model M` | One completion on a saved config's published revision, with no agent, session or execution — to see whether a model follows a prompt or a system block's instruction. `--system` (text, `@file`, `-`; repeatable), `-m [user:\|assistant:]TEXT` (repeatable) or `--messages chat.json`, `--temperature`, `--max-tokens` (server cap 8192), `--param k=v`. The reply goes to stdout, the model, finish reason, tokens and latency to stderr (`llm_providers:test`). Fruxon-hosted providers are refused. |
 | `fruxon assets create/list/get/wait/operations/delete` | Manage knowledge-base (RAG) assets an agent can query — upload local files, wait for async ingestion, inspect operations, and use the ids for `assetConfig.assetIds`. `delete` confirms + refuses without `--yes` in agent mode. |
 | `fruxon knowledge-bases list/get/create/update/publish/archive/delete` | The authored, reviewable corpus behind a `manual_knowledge` asset — **not** the asset itself, which is what gets searched (`get` prints the asset id as `backingAssetId`). **`publish` is the step that makes any of it findable**: only `PUBLISHED` documents travel in a snapshot, and only publishing the *base* moves one, so a base full of finished articles answers nothing until it runs. It returns on *acceptance*, not searchability — RAG ingests afterwards, so a pending publish state is normal. `list` hides archived bases, which keep answering for agents already attached to them; `delete` is refused while an agent revision still attaches one, and `archive` is the reversible path. |
 | `fruxon knowledge-bases usage <kb>` | Whether agents actually use the base: searches per hour, day or week (`--interval`), the passage tokens each search handed the agent, how many found nothing (split from searches that **could not fully search** it — index missing or still building, a phrasing failed), and which agents searched (up to 20 you can open, the rest counted together). `--origin test` counts test runs instead of production. Retrieved tokens are counted by the search index, so what the model read can be less when a large result is trimmed or offloaded. Searches are recorded from 15 October 2026 and kept 90 days at most, so a window reaching further back says where counting began rather than showing empty days. A 404 is a wrong id or a backend that predates the read. |
@@ -170,6 +172,8 @@ Integrations + tools:
 | `fruxon triggers check <trigger>` | Audit whether a work-shape automation can move its items, part by part in the order an item meets them: on and taking items in, the last pass read its source, each PROCESS stage's agent exists with a deployed revision and working credentials and models (a rejected credential's row says how many items failed there since), each ASK stage's contact is declared and bound on the asking agent and its oldest question has not waited past a fifth of its answer window, the outcome note's contact reaches a person, this week's spend against the weekly limit, and how many items died in the last 7 days. `{trigger, overall, checks[]}` like `agents check`; exits 12 only on a hard fail, warnings stay 0. Read-only. |
 | `fruxon triggers budget list/get/set/delete` | Spend limits on an automation **as a whole** (`--period DAILY/WEEKLY/MONTHLY`, UTC calendar windows), counting every production run it caused whichever agent made it. Once one is enforced they govern its runs, which then meet only these limits and not the agents' own; with none enforced, each stage stops at its agent's own limit. None by default and every one removable. An enforced limit refuses new work at the limit (stage runs, passes, a question's opening, the report) and holds the stages until the window resets, while turns of conversations it already opened still run (up to 110%); `--no-enforce` only alerts the Application's admins. Needs Editor. |
 | `fruxon triggers ledger redrive/ignore/settle/cancel-batch` | The operator verbs; all confirm and refuse without `--yes` in agent mode. `redrive` returns a DEAD or FAILED item to the queue with its attempts reset — settle any `UNKNOWN` effect first or the next attempt hits the same refusal. `ignore` excludes an item for a **required** reason, which is the only thing separating IGNORED from DEAD later. `settle` answers an effect the platform could not confirm (`--landed` / `--did-not-land` + `--reason`); wrong in the second direction duplicates the write. `cancel-batch` calls off a question — the items go back to READY and a later pass re-batches them. |
+| `fruxon triggers ledger wake` | End an item's wait at a WAIT stage now, as if its due time had come: an event the stage waits for that already arrived takes `onEvent` with what it carries, otherwise the `onDue` exit applies (on to the next or named stage, or FAIL / DEAD); the history records `OPERATOR_WAKE`. 409 for an item waiting on a question (answer it or `cancel-batch`). `ignore` stops a wait without continuing. `items --waiting-for TIME --order-by wakeAt` lists what waits on time, soonest first; the Detail column says when each wakes and the footer flags any 15 minutes overdue. `items --admitted-via API\|AGENT` lists what was started by hand (`admit`, or an agent's `start_work_item`). |
+| `fruxon triggers ledger admit` | Start one item by hand on an automation whose work shape declares `onDemand`. `--set path=value` / `path:=<json>` (dotted paths nest) or `--data-file`; the server checks the declared inputs and refuses credential-named keys. The key — `--key`, or composed from the shape's `keyPaths` — is the whole idempotency: the same key again returns the existing item **unchanged** (`created: false`), whatever its status. Needs `triggers:fire`. |
 | `fruxon triggers ledger set-data` | Correct a parked (DEAD / FAILED / IGNORED) item's `data` before re-driving it — the value a stage recorded wrong, such as an ASK answer written as `SKIP`, which a plain re-drive would route on again. `--set path=value` (or `path:=<json>`, repeatable) on a top-level key the item carries or a path the shape declares (`produces`, `answeredWhenPath`); a misspelled key is refused with the settable list rather than added. `--reason` is required and lands on the item's history beside every old → new value. `--redrive` re-drives in the same transaction; `redrive` and `redrive-many` take `--set` too. |
 | `fruxon triggers ledger redrive-many/ignore-many` | The same two verbs over a **selection** — `--id` (repeatable), `--stage`, `--status`, `--before`/`--after` (Unix ms). The CLI resolves the selection to a count under the verb's own eligibility, shows it, and the server acts on exactly that count (409 if the set changed). The count is the server's own whenever the endpoint's filters say exactly what the selection says (a `--status` or an `--ignore-reason`, with no `--id` and no `--before`/`--after`) — one request instead of walking every page of a 4,000-item ledger, and one fewer place for the two sides to disagree. `ignore-many --stage X` is how you drain a stage. When the selection is `--id` values, the result names every id it did **not** act on and why — not a work item, another automation's, or a status the verb cannot touch (usually a pass holding the claim). |
 | `fruxon triggers ledger exclusions` | Every reason items were set aside, with how many each holds — the list `--ignore-reason` is picked from, and usually the fastest way to see a prompt excluding a whole class of work it should not. `funnel` stops at `1,204 IGNORED`, which is a status and not something anyone can act on; an exclusion is a judgement a stage made under an instruction, so what you hold after revising it is a *reason*. Each count is exactly what a reason-scoped re-drive resolves, so the diagnosis and the fix use the same string. Reasons print whole and are never truncated — the filter matches the entire string, case-sensitively, so a shortened one selects nothing. A `(none recorded)` row predates the reason being kept on the item: those items are real, no reason filter can reach them, and their way back is `--id`. At most 200 distinct reasons come back. |
@@ -179,7 +183,7 @@ Integrations + tools:
 | `fruxon triggers ledger walk/walk-steps` | `walk --item <id> --yes` chains stage tests: the item's stage (or `--from`), then each stage it advances into, on the data it advanced with, until a real pass would stop too. Each ASK stage it reaches takes `--reply <stage>=<text>` or `--answer <stage>=<value>`; `--agent-revision <agent>=<N>` runs every stage of that agent on an undeployed revision. `stopped.code` is `COMPLETED`, `REACHED_UNTIL` (`--until`), `NOT_ADVANCED` (a `WAIT`, too, and an ADVANCE a pass would undo: a duplicate, or fields the next stage requires), `REPLY_NEEDED` (an ASK stage nobody answered), `STAGE_NOT_TESTABLE`, `MAX_STEPS` (default 10), `TIMEOUT` or `CANCELLED`. Every step is a paid run, so it confirms first and needs `--yes` in agent mode; it exits 0 whenever it ran. `walk-steps <trigger> <walk>` reads a walk back in step order. |
 | `fruxon triggers ledger reset-cursor/purge` | `reset-cursor` moves where the next scan starts, as a compare-and-swap on the version it just read (`--value` omitted = the door's own horizon); it never re-runs admitted work. It is the *after* to `workShape.door.startFrom`'s *before* — a horizon set at creation seeds the cursor before anything sweeps, and is ignored once a pass has read the source. `purge` starts the ledger over — cancels open questions, deletes items and effects, bumps the cursor version — and confirms the exact item count first. The items' transitions stay, as the ledger's history. Destructive; the effects' external targets are not touched. |
 | `fruxon triggers questions list/answer` | The human half of an ASK stage, tenant-wide. `ledger batches <trigger>` answers *what is this automation waiting on*; this answers *what is waiting on anyone* — soonest deadline first, which is how an undelivered question gets found at all. Read **`delivery`** first: `UNDELIVERABLE` (nobody reachable in the slot) and `FAILED` (a target resolved, the send did not land) both mean nobody was asked and nobody will answer unless you do — `QUEUE_ONLY` is healthy. `--undelivered-only` narrows to that pair; `--trigger` filters client-side (the endpoint has no such filter). `answer` settles one on the assignee's behalf and is `--yes`-gated: the reply interpreter **fails closed**, so an answer it cannot place advances nothing and the question stays open, and each item advances only once the stage's `answeredWhenPath` is filled — answering two of three advances two. |
-| `fruxon triggers set-stages <id> --file` | Replace an automation's stages without rewriting the rest of its work shape (a PATCH replaces the whole shape, so this reads it, splices, and posts). Takes a bare stages array or any document carrying one. Pre-flights the two refusals the server only reports after the write: live items at a stage your list drops, and a `door` that will re-expand `source` on save. `--dry-run` prints the merged shape and the warnings; `preview-shape <id> --file` takes the same file and renders what each stage would hand its agent. `--help` documents every stage field the server reads but the CLI passes through untouched — `routes`, `ignoreReasons`, a FORM stage's `answerField`, `formClosing` and `formJoinNotice`. |
+| `fruxon triggers set-stages <id> --file` | Replace an automation's stages without rewriting the rest of its work shape (a PATCH replaces the whole shape, so this reads it, splices, and posts). Takes a bare stages array or any document carrying one. Pre-flights the two refusals the server only reports after the write: live items at a stage your list drops, and a `door` that will re-expand `source` on save. `--dry-run` prints the merged shape and the warnings; `preview-shape <id> --file` takes the same file and renders what each stage would hand its agent. `--help` documents every stage field the server reads but the CLI passes through untouched — `routes`, `ignoreReasons`, a FORM stage's `answerField`, `formClosing` and `formJoinNotice`, and a WAIT stage's `wait` (`minutes` or `untilPath`, then `onDue`; an `event` with `match`, `capture` and `onEvent` to end it early — the invoice example and the save rules are there). It also warns before a save that changes a stage's kind, or a WAIT stage's event correlation, under CLAIMED or WAITING items, which the server refuses, and prints the save's own warnings — such as a WAIT matching its event on a value nothing keeps unique. |
 | `fruxon triggers revisions list/get/restore` | A trigger's audit history — every mutation writes a snapshot, and `changeReason` separates a config edit from a binding reconcile. `get -o json | jq .workShape` is the shape as it stood, which is how you undo an edit by hand. `restore` replays one and is **not** a universal undo: it runs the same validation a save does, so a snapshot that drops a stage still holding live items is refused. |
 | `fruxon secrets list/get/grants` | Discover tenant secrets an agent can reference — the ids for `allowedSecretIds` and the `{{secret.KEY}}` names, with publish-state and per-agent grants. Metadata only; values are never returned. |
 | `fruxon participants list/get/create/update/delete/enable/disable` | Manage agent-network participants (people / groups / agents the network routes to). `list` takes `--query` (matches names **and channel addresses and account ids**, so a phone number or handle resolves to an id, and searches both directory tiers by default), `--kind`, `--tier`, `--agent`, `--environment-id`, and pages up to `--limit` / `--all`. `create`/`update` take `--file` (+`--schema`); `enable`/`disable` toggle routing; `delete` confirms + refuses without `--yes` in agent mode. |
@@ -340,6 +344,9 @@ spend = client.get_ledger_spend(trigger_id)  # this calendar week, by agent and
 print(spend.cost, [(a.agent_id, a.cost) for a in spend.agents])
 for b in client.list_ledger_batches(trigger_id, open_only=True):
     print(b.delivery, b.question)             # UNDELIVERABLE ⇒ nobody was asked
+for i in client.list_ledger_items(trigger_id, waiting_for="TIME", order_by="wakeAt"):
+    print(i.item_key, i.wake_at)              # parked at a WAIT stage, soonest first
+client.wake_ledger_item(trigger_id, item_id, reason="indexed early")   # its onDue exit applies now
 ```
 
 The client picks up `FRUXON_TOKEN`, `FRUXON_WORKSPACE`, and `FRUXON_BASE_URL` only if you read them yourself — the constructor takes explicit values. The CLI resolves them automatically (command flags → root flags → env → stored config).

{fruxon-2.0.2 → fruxon-2.2.0}/README.md

@@ -69,6 +69,7 @@ Execution:
 | `fruxon escalations list/history/unhandled/policy/ack` | What happened when an agent handed a conversation to a person. `list` is the queue (live takeovers + degraded escalations nobody was reachable for); `unhandled` is the append-only ledger under it. **`history` is the record of closed console-routed takeovers** — those leave the queue, so `list --status ALL` answers `[]` about a conversation a human worked for half an hour. Read `humanObservedAt` before believing a `RESOLVED`: null means nobody was ever seen picking it up. `policy <agent>` resolves who the *next* escalation would reach — an empty ladder under `NATIVE_HANDOFF` is correct, the console supplies the human. |
 | `fruxon messages list` | The channel ledger — including inbound an agent was never shown. A **withheld** message (a human owns the chat in the source console, or admission refused the sender) never becomes a conversation turn, so it is in no transcript and the thread reads as a customer being ignored. `--delivery WITHHELD_PENDING` lists the ones nothing has ever acted on; nothing drains them. |
 | `fruxon agents sandbox open/turn/fire/resolve-input/stream/answer/close <session>` | Drive an agent-network sandbox end-to-end without real channels — send turns as participants, test-fire triggers, and watch the run (`stream`, NDJSON in agent mode). Sandbox **captures the reply and hard-blocks every real send**; `--await` makes consult/approval gates suspend so they can be resolved (`answer` for consults, `approvals respond` for approvals). `--draft` runs your unpublished draft instead of the deployed revision (`sandbox draft <session>` says which); `--confirm-writes` holds every create/update/delete tool call for approval, because sandbox does **not** block integration writes; a write that did not run (rejected, expired, or one the run could not pause for) shows on `stream` as `refused`. |
+| `fruxon agents voice-calls list/get <agent>` | Read back the Test lab's Talk calls. `list` gives calls newest first (status, end reason, turns, length). `get <agent> <call-id>` gives the call turn by turn: the caller's transcript, the reply, what was heard of it (`delivery`; `spokenText` when the caller cut in), and each reply's `executionRecordId` for `agents executions trace`. Read-only; needs `executions:read`. |
 | `fruxon agents sandbox fork <agent> <message-id>` | Fork a real conversation at a transcript row (an `id` from `agents topics messages`) into a sandbox session already holding the history the agent had when it produced that reply. `--send` re-sends the customer's message against it — with `--draft` to test an edit before publishing — and holds writes for approval unless `--no-confirm-writes`. |
 | `fruxon agents sandbox test <file-or-dir>` | Run scenario-based e2e tests of an agent's network behavior. A scenario (YAML/JSON) declares `steps` (turns / trigger fires), `responders` (scripted consult/approval answers), and `expect` assertions (reply / routing / tools called or refused / no-leak / outcome); the runner drives a sandbox session and returns one verdict — exit 0 (pass) / 1 (fail) / 12 (bad file), with `--junit` for CI. An optional `setup` block provisions real resources first — an `asset` (uploaded + ingestion-waited), `participant`, or `agent` — templated as `${asset.catalog.id}` and **torn down afterwards even on failure** (`--keep` to inspect). Assertions are deterministic by default; `reply_judge: {metric, min_score}` adds an opt-in **semantic** check that scores the reply against a tenant eval metric. The thing an agent runs to prove the agent it built works. |
 
@@ -116,6 +117,7 @@ Integrations + tools:
 | `fruxon llm-providers list/get/models` | Browse LLM providers and models supported at the tenant level. |
 | `fruxon llm-providers connect <provider>` / `link-status` | Create a config for an LLM provider and print a **credential link**: a human opens it, signs in to Fruxon, types the API key (or access keys, or service account key), and the page tests it with the provider and publishes the config an agent pins as `provider.tenantConfigId`. The key never passes through the terminal or an agent driving the CLI. `--config <id>` fills an existing config, `--param name=value` sets a non-secret setting such as Bedrock's `region`, `--no-sign-in` mints a link anyone holding it can fill (Admin or Owner). `link-status <provider> <config> <request> [--wait]` says when it was filled. |
 | `fruxon llm-providers configs list/get/test/publish` | The workspace's saved LLM credentials — the `provider.tenantConfigId` an agent pins. `get` shows the draft (secrets masked), the published revision and last known health. `test` probes the draft on every provider surface that shares the credential (or just one, given that surface's provider id), one line per failing surface, exit 12 on failure (`llm_providers:test`). `publish` ships the draft as a new revision that every agent on the config switches to — it confirms, needs `--yes` in agent mode, and does not wait on a passing test (`llm_providers:write`). |
+| `fruxon llm-providers configs complete <provider> <config> --model M` | One completion on a saved config's published revision, with no agent, session or execution — to see whether a model follows a prompt or a system block's instruction. `--system` (text, `@file`, `-`; repeatable), `-m [user:\|assistant:]TEXT` (repeatable) or `--messages chat.json`, `--temperature`, `--max-tokens` (server cap 8192), `--param k=v`. The reply goes to stdout, the model, finish reason, tokens and latency to stderr (`llm_providers:test`). Fruxon-hosted providers are refused. |
 | `fruxon assets create/list/get/wait/operations/delete` | Manage knowledge-base (RAG) assets an agent can query — upload local files, wait for async ingestion, inspect operations, and use the ids for `assetConfig.assetIds`. `delete` confirms + refuses without `--yes` in agent mode. |
 | `fruxon knowledge-bases list/get/create/update/publish/archive/delete` | The authored, reviewable corpus behind a `manual_knowledge` asset — **not** the asset itself, which is what gets searched (`get` prints the asset id as `backingAssetId`). **`publish` is the step that makes any of it findable**: only `PUBLISHED` documents travel in a snapshot, and only publishing the *base* moves one, so a base full of finished articles answers nothing until it runs. It returns on *acceptance*, not searchability — RAG ingests afterwards, so a pending publish state is normal. `list` hides archived bases, which keep answering for agents already attached to them; `delete` is refused while an agent revision still attaches one, and `archive` is the reversible path. |
 | `fruxon knowledge-bases usage <kb>` | Whether agents actually use the base: searches per hour, day or week (`--interval`), the passage tokens each search handed the agent, how many found nothing (split from searches that **could not fully search** it — index missing or still building, a phrasing failed), and which agents searched (up to 20 you can open, the rest counted together). `--origin test` counts test runs instead of production. Retrieved tokens are counted by the search index, so what the model read can be less when a large result is trimmed or offloaded. Searches are recorded from 15 October 2026 and kept 90 days at most, so a window reaching further back says where counting began rather than showing empty days. A 404 is a wrong id or a backend that predates the read. |
@@ -135,6 +137,8 @@ Integrations + tools:
 | `fruxon triggers check <trigger>` | Audit whether a work-shape automation can move its items, part by part in the order an item meets them: on and taking items in, the last pass read its source, each PROCESS stage's agent exists with a deployed revision and working credentials and models (a rejected credential's row says how many items failed there since), each ASK stage's contact is declared and bound on the asking agent and its oldest question has not waited past a fifth of its answer window, the outcome note's contact reaches a person, this week's spend against the weekly limit, and how many items died in the last 7 days. `{trigger, overall, checks[]}` like `agents check`; exits 12 only on a hard fail, warnings stay 0. Read-only. |
 | `fruxon triggers budget list/get/set/delete` | Spend limits on an automation **as a whole** (`--period DAILY/WEEKLY/MONTHLY`, UTC calendar windows), counting every production run it caused whichever agent made it. Once one is enforced they govern its runs, which then meet only these limits and not the agents' own; with none enforced, each stage stops at its agent's own limit. None by default and every one removable. An enforced limit refuses new work at the limit (stage runs, passes, a question's opening, the report) and holds the stages until the window resets, while turns of conversations it already opened still run (up to 110%); `--no-enforce` only alerts the Application's admins. Needs Editor. |
 | `fruxon triggers ledger redrive/ignore/settle/cancel-batch` | The operator verbs; all confirm and refuse without `--yes` in agent mode. `redrive` returns a DEAD or FAILED item to the queue with its attempts reset — settle any `UNKNOWN` effect first or the next attempt hits the same refusal. `ignore` excludes an item for a **required** reason, which is the only thing separating IGNORED from DEAD later. `settle` answers an effect the platform could not confirm (`--landed` / `--did-not-land` + `--reason`); wrong in the second direction duplicates the write. `cancel-batch` calls off a question — the items go back to READY and a later pass re-batches them. |
+| `fruxon triggers ledger wake` | End an item's wait at a WAIT stage now, as if its due time had come: an event the stage waits for that already arrived takes `onEvent` with what it carries, otherwise the `onDue` exit applies (on to the next or named stage, or FAIL / DEAD); the history records `OPERATOR_WAKE`. 409 for an item waiting on a question (answer it or `cancel-batch`). `ignore` stops a wait without continuing. `items --waiting-for TIME --order-by wakeAt` lists what waits on time, soonest first; the Detail column says when each wakes and the footer flags any 15 minutes overdue. `items --admitted-via API\|AGENT` lists what was started by hand (`admit`, or an agent's `start_work_item`). |
+| `fruxon triggers ledger admit` | Start one item by hand on an automation whose work shape declares `onDemand`. `--set path=value` / `path:=<json>` (dotted paths nest) or `--data-file`; the server checks the declared inputs and refuses credential-named keys. The key — `--key`, or composed from the shape's `keyPaths` — is the whole idempotency: the same key again returns the existing item **unchanged** (`created: false`), whatever its status. Needs `triggers:fire`. |
 | `fruxon triggers ledger set-data` | Correct a parked (DEAD / FAILED / IGNORED) item's `data` before re-driving it — the value a stage recorded wrong, such as an ASK answer written as `SKIP`, which a plain re-drive would route on again. `--set path=value` (or `path:=<json>`, repeatable) on a top-level key the item carries or a path the shape declares (`produces`, `answeredWhenPath`); a misspelled key is refused with the settable list rather than added. `--reason` is required and lands on the item's history beside every old → new value. `--redrive` re-drives in the same transaction; `redrive` and `redrive-many` take `--set` too. |
 | `fruxon triggers ledger redrive-many/ignore-many` | The same two verbs over a **selection** — `--id` (repeatable), `--stage`, `--status`, `--before`/`--after` (Unix ms). The CLI resolves the selection to a count under the verb's own eligibility, shows it, and the server acts on exactly that count (409 if the set changed). The count is the server's own whenever the endpoint's filters say exactly what the selection says (a `--status` or an `--ignore-reason`, with no `--id` and no `--before`/`--after`) — one request instead of walking every page of a 4,000-item ledger, and one fewer place for the two sides to disagree. `ignore-many --stage X` is how you drain a stage. When the selection is `--id` values, the result names every id it did **not** act on and why — not a work item, another automation's, or a status the verb cannot touch (usually a pass holding the claim). |
 | `fruxon triggers ledger exclusions` | Every reason items were set aside, with how many each holds — the list `--ignore-reason` is picked from, and usually the fastest way to see a prompt excluding a whole class of work it should not. `funnel` stops at `1,204 IGNORED`, which is a status and not something anyone can act on; an exclusion is a judgement a stage made under an instruction, so what you hold after revising it is a *reason*. Each count is exactly what a reason-scoped re-drive resolves, so the diagnosis and the fix use the same string. Reasons print whole and are never truncated — the filter matches the entire string, case-sensitively, so a shortened one selects nothing. A `(none recorded)` row predates the reason being kept on the item: those items are real, no reason filter can reach them, and their way back is `--id`. At most 200 distinct reasons come back. |
@@ -144,7 +148,7 @@ Integrations + tools:
 | `fruxon triggers ledger walk/walk-steps` | `walk --item <id> --yes` chains stage tests: the item's stage (or `--from`), then each stage it advances into, on the data it advanced with, until a real pass would stop too. Each ASK stage it reaches takes `--reply <stage>=<text>` or `--answer <stage>=<value>`; `--agent-revision <agent>=<N>` runs every stage of that agent on an undeployed revision. `stopped.code` is `COMPLETED`, `REACHED_UNTIL` (`--until`), `NOT_ADVANCED` (a `WAIT`, too, and an ADVANCE a pass would undo: a duplicate, or fields the next stage requires), `REPLY_NEEDED` (an ASK stage nobody answered), `STAGE_NOT_TESTABLE`, `MAX_STEPS` (default 10), `TIMEOUT` or `CANCELLED`. Every step is a paid run, so it confirms first and needs `--yes` in agent mode; it exits 0 whenever it ran. `walk-steps <trigger> <walk>` reads a walk back in step order. |
 | `fruxon triggers ledger reset-cursor/purge` | `reset-cursor` moves where the next scan starts, as a compare-and-swap on the version it just read (`--value` omitted = the door's own horizon); it never re-runs admitted work. It is the *after* to `workShape.door.startFrom`'s *before* — a horizon set at creation seeds the cursor before anything sweeps, and is ignored once a pass has read the source. `purge` starts the ledger over — cancels open questions, deletes items and effects, bumps the cursor version — and confirms the exact item count first. The items' transitions stay, as the ledger's history. Destructive; the effects' external targets are not touched. |
 | `fruxon triggers questions list/answer` | The human half of an ASK stage, tenant-wide. `ledger batches <trigger>` answers *what is this automation waiting on*; this answers *what is waiting on anyone* — soonest deadline first, which is how an undelivered question gets found at all. Read **`delivery`** first: `UNDELIVERABLE` (nobody reachable in the slot) and `FAILED` (a target resolved, the send did not land) both mean nobody was asked and nobody will answer unless you do — `QUEUE_ONLY` is healthy. `--undelivered-only` narrows to that pair; `--trigger` filters client-side (the endpoint has no such filter). `answer` settles one on the assignee's behalf and is `--yes`-gated: the reply interpreter **fails closed**, so an answer it cannot place advances nothing and the question stays open, and each item advances only once the stage's `answeredWhenPath` is filled — answering two of three advances two. |
-| `fruxon triggers set-stages <id> --file` | Replace an automation's stages without rewriting the rest of its work shape (a PATCH replaces the whole shape, so this reads it, splices, and posts). Takes a bare stages array or any document carrying one. Pre-flights the two refusals the server only reports after the write: live items at a stage your list drops, and a `door` that will re-expand `source` on save. `--dry-run` prints the merged shape and the warnings; `preview-shape <id> --file` takes the same file and renders what each stage would hand its agent. `--help` documents every stage field the server reads but the CLI passes through untouched — `routes`, `ignoreReasons`, a FORM stage's `answerField`, `formClosing` and `formJoinNotice`. |
+| `fruxon triggers set-stages <id> --file` | Replace an automation's stages without rewriting the rest of its work shape (a PATCH replaces the whole shape, so this reads it, splices, and posts). Takes a bare stages array or any document carrying one. Pre-flights the two refusals the server only reports after the write: live items at a stage your list drops, and a `door` that will re-expand `source` on save. `--dry-run` prints the merged shape and the warnings; `preview-shape <id> --file` takes the same file and renders what each stage would hand its agent. `--help` documents every stage field the server reads but the CLI passes through untouched — `routes`, `ignoreReasons`, a FORM stage's `answerField`, `formClosing` and `formJoinNotice`, and a WAIT stage's `wait` (`minutes` or `untilPath`, then `onDue`; an `event` with `match`, `capture` and `onEvent` to end it early — the invoice example and the save rules are there). It also warns before a save that changes a stage's kind, or a WAIT stage's event correlation, under CLAIMED or WAITING items, which the server refuses, and prints the save's own warnings — such as a WAIT matching its event on a value nothing keeps unique. |
 | `fruxon triggers revisions list/get/restore` | A trigger's audit history — every mutation writes a snapshot, and `changeReason` separates a config edit from a binding reconcile. `get -o json | jq .workShape` is the shape as it stood, which is how you undo an edit by hand. `restore` replays one and is **not** a universal undo: it runs the same validation a save does, so a snapshot that drops a stage still holding live items is refused. |
 | `fruxon secrets list/get/grants` | Discover tenant secrets an agent can reference — the ids for `allowedSecretIds` and the `{{secret.KEY}}` names, with publish-state and per-agent grants. Metadata only; values are never returned. |
 | `fruxon participants list/get/create/update/delete/enable/disable` | Manage agent-network participants (people / groups / agents the network routes to). `list` takes `--query` (matches names **and channel addresses and account ids**, so a phone number or handle resolves to an id, and searches both directory tiers by default), `--kind`, `--tier`, `--agent`, `--environment-id`, and pages up to `--limit` / `--all`. `create`/`update` take `--file` (+`--schema`); `enable`/`disable` toggle routing; `delete` confirms + refuses without `--yes` in agent mode. |
@@ -305,6 +309,9 @@ spend = client.get_ledger_spend(trigger_id)  # this calendar week, by agent and
 print(spend.cost, [(a.agent_id, a.cost) for a in spend.agents])
 for b in client.list_ledger_batches(trigger_id, open_only=True):
     print(b.delivery, b.question)             # UNDELIVERABLE ⇒ nobody was asked
+for i in client.list_ledger_items(trigger_id, waiting_for="TIME", order_by="wakeAt"):
+    print(i.item_key, i.wake_at)              # parked at a WAIT stage, soonest first
+client.wake_ledger_item(trigger_id, item_id, reason="indexed early")   # its onDue exit applies now
 ```
 
 The client picks up `FRUXON_TOKEN`, `FRUXON_WORKSPACE`, and `FRUXON_BASE_URL` only if you read them yourself — the constructor takes explicit values. The CLI resolves them automatically (command flags → root flags → env → stored config).

{fruxon-2.0.2 → fruxon-2.2.0}/src/fruxon/__init__.py

@@ -80,7 +80,15 @@ from fruxon.models import (
     LedgerFunnelCell,
     LedgerGatheringGroup,
     LedgerItem,
+    LedgerItemAdmission,
+    LedgerItemAttempt,
+    LedgerItemAttemptAsk,
+    LedgerItemAttemptBatch,
+    LedgerItemAttemptOutcome,
+    LedgerItemAttemptWait,
     LedgerItemPoint,
+    LedgerItemRuns,
+    LedgerItemRunTotals,
     LedgerItemTimeseries,
     LedgerItemTransition,
     LedgerPass,
@@ -97,6 +105,11 @@ from fruxon.models import (
     LedgerStageTestSimulatedCall,
     LedgerStageTestSink,
     LedgerStageTestVerdict,
+    LedgerWaitCapture,
+    LedgerWaitConfig,
+    LedgerWaitEventConfig,
+    LedgerWaitExit,
+    LedgerWaitMatch,
     ManagedBy,
     ManagedResourceLink,
     Memory,
@@ -123,6 +136,8 @@ from fruxon.models import (
     TriggerParameterMapping,
     TriggerRevision,
     UnhandledEscalation,
+    VoiceCall,
+    VoiceCallTurn,
     WorkShapeDoor,
     WorkShapeDoorConversation,
     WorkShapeDoorField,
@@ -212,6 +227,14 @@ __all__ = [
     "LedgerFunnelCell",
     "LedgerGatheringGroup",
     "LedgerItem",
+    "LedgerItemAdmission",
+    "LedgerItemAttempt",
+    "LedgerItemAttemptAsk",
+    "LedgerItemAttemptBatch",
+    "LedgerItemAttemptOutcome",
+    "LedgerItemAttemptWait",
+    "LedgerItemRuns",
+    "LedgerItemRunTotals",
     "LedgerItemTransition",
     "LedgerPass",
     "LedgerPurgeResult",
@@ -221,6 +244,11 @@ __all__ = [
     "LedgerStageTestSimulatedCall",
     "LedgerStageTestSink",
     "LedgerStageTestVerdict",
+    "LedgerWaitCapture",
+    "LedgerWaitConfig",
+    "LedgerWaitEventConfig",
+    "LedgerWaitExit",
+    "LedgerWaitMatch",
     "LedgerSkippedItem",
     "ManagedBy",
     "Memory",
@@ -250,6 +278,8 @@ __all__ = [
     "TriggerRevision",
     "UnhandledEscalation",
     "ValidationError",
+    "VoiceCall",
+    "VoiceCallTurn",
     "WorkShapeDoor",
     "WorkShapeDoorConversation",
     "WorkShapeDoorField",

{fruxon-2.0.2 → fruxon-2.2.0}/src/fruxon/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '2.0.2'
-__version_tuple__ = version_tuple = (2, 0, 2)
+__version__ = version = '2.2.0'
+__version_tuple__ = version_tuple = (2, 2, 0)
 
 __commit_id__ = commit_id = None

{fruxon-2.0.2 → fruxon-2.2.0}/src/fruxon/checks/ledger.py

@@ -21,6 +21,7 @@ from datetime import datetime
 
 from fruxon.checks import CheckReport, CheckResult, shape_get
 from fruxon.exceptions import FruxonError, NotFoundError
+from fruxon.models import LedgerWaitConfig, LedgerWaitEventConfig, LedgerWaitExit
 
 DAY_MS = 86_400_000
 _HOUR_MS = 3_600_000
@@ -137,6 +138,7 @@ def check_ledger(client, trigger: str, *, detail=None, now_ms: int | None = None
     cells: dict[str, dict[str, int]] = {}
     for cell in funnel or []:
         cells.setdefault(cell.stage_id, {})[cell.status.upper()] = cell.count
+    waiting_cells = {c.stage_id: c for c in funnel or [] if c.status.upper() == "WAITING"}
     today = int(datetime.fromtimestamp(now / 1000).replace(hour=0, minute=0, second=0, microsecond=0).timestamp())
     series, _ = _try(
         client.get_ledger_item_timeseries, trigger, interval="DAY", since=today * 1000 - 6 * DAY_MS, until=now
@@ -207,6 +209,9 @@ def check_ledger(client, trigger: str, *, detail=None, now_ms: int | None = None
         if kind == "ASK":
             rows.append(_ask_row(trigger, stage, stage_id, asker, slots_of, batches, batches_ok, now))
             continue
+        if kind == "WAIT":
+            rows.append(_wait_row(trigger, stage, stage_id, waiting_cells.get(stage_id), now))
+            continue
         agent = str(shape_get(stage, "agentId") or "")
         if not agent:
             add(stage_id, "skip", "no agent — items pass through", explain="", fix="trigger-edit")
@@ -432,10 +437,102 @@ def _ask_row(
     )
 
 
+def _wait_row(trigger: str, stage: dict, stage_id: str, cell, now: int) -> CheckResult:
+    """A WAIT stage: nothing runs there, so the one thing that can be wrong is a
+    wait left well past its due time — the sweeper that ends them is behind."""
+    wait = LedgerWaitConfig.from_dict(shape_get(stage, "wait")) or LedgerWaitConfig()
+    what = f"waits {describe_wait(wait)}"
+    overdue = getattr(cell, "overdue", 0) if cell is not None else 0
+    if overdue:
+        return CheckResult(
+            stage_id,
+            "warn",
+            f"{what} · {overdue} overdue",
+            hint=f"fruxon triggers ledger items {trigger} --waiting-for TIME --order-by wakeAt",
+            explain="A wait ends within a minute or two of its due time. Items more than 15 minutes past it mean "
+            "the wait sweeper is down or behind; `fruxon triggers ledger wake` ends one by hand.",
+            fix=f"work:WAITING:{stage_id}",
+        )
+    waiting = cell.count if cell is not None else 0
+    next_wake = getattr(cell, "next_wake_at", None) if cell is not None else None
+    if waiting:
+        what += f" · {waiting:,} waiting" + (f", next wakes {_clock(next_wake, now)}" if next_wake else "")
+    return CheckResult(
+        stage_id,
+        "ok",
+        what,
+        explain="Nothing runs here: each item waits until its due time"
+        + (", or until its event arrives," if wait.event is not None else "")
+        + " then moves on.",
+        fix=f"work:WAITING:{stage_id}",
+    )
+
+
+def _span(minutes: int) -> str:
+    days, rest = divmod(minutes, 1_440)
+    hours, mins = divmod(rest, 60)
+    return " ".join(f"{n}{unit}" for n, unit in ((days, "d"), (hours, "h"), (mins, "m")) if n) or "0m"
+
+
+def _exit_text(exit_: LedgerWaitExit) -> str:
+    if exit_.action == "ADVANCE_TO":
+        return exit_.stage_id or "?"
+    if exit_.action in {"FAIL", "DEAD"}:
+        return exit_.action
+    return "next"
+
+
+def describe_wait(wait: LedgerWaitConfig) -> str:
+    """A WAIT stage in a few words: ``3d``, ``until due_at, then DEAD``, ``1h 30m → paid``, or with an
+    event ``until due_at or stripe.payment_intent.succeeded: event → receipt, due → next``."""
+    span = _span(wait.minutes) if wait.minutes is not None else f"until {wait.until_path or '?'}"
+    if wait.event is not None:
+        return (
+            f"{span} or {wait.event.event_type or '?'}: event → {_exit_text(wait.effective_on_event)}, "
+            f"due → {_exit_text(wait.effective_on_due)}"
+        )
+    exit_ = wait.effective_on_due
+    if exit_.action == "ADVANCE_TO":
+        return f"{span} → {exit_.stage_id or '?'}"
+    if exit_.action in {"FAIL", "DEAD"}:
+        return f"{span}, then {exit_.action}"
+    return span
+
+
+def describe_wait_event(event: LedgerWaitEventConfig) -> list[tuple[str, str]]:
+    """``(label, text)`` lines for what a WAIT stage's event is matched on and carries into the item."""
+    lines: list[tuple[str, str]] = []
+    if event.integration_config_id:
+        lines.append(("connection", event.integration_config_id))
+    lines.extend(("match", f"{m.event_path} = item {m.item_path}") for m in event.match)
+    lines.extend(("capture", f"{c.event_path} → {c.item_path} ({c.type})") for c in event.capture)
+    if event.filter:
+        lines.append(("only when", _filter_text(event.filter)))
+    return lines
+
+
+def _filter_text(flt: dict) -> str:
+    """An event filter as one line: its conditions, joined the way its ``match`` combines them."""
+    conditions = shape_get(flt, "conditions")
+    parts = []
+    for c in conditions if isinstance(conditions, list) else []:
+        if not isinstance(c, dict):
+            continue
+        values = shape_get(c, "values")
+        value = f"[{', '.join(str(v) for v in values)}]" if isinstance(values, list) else shape_get(c, "value")
+        parts.append(" ".join(str(p) for p in (shape_get(c, "path"), shape_get(c, "operator"), value) if p is not None))
+    joiner = " or " if str(shape_get(flt, "match") or "ALL").upper() == "ANY" else " and "
+    return joiner.join(parts) or "—"
+
+
 def describe_stage(stage: dict) -> tuple[str, str, str, str]:
     """``(name, kind, who, what it does)`` for the console's shape table."""
     stage_id = str(shape_get(stage, "id") or "?")
     kind = str(shape_get(stage, "kind") or "").upper()
+    if kind == "WAIT":
+        wait = LedgerWaitConfig.from_dict(shape_get(stage, "wait")) or LedgerWaitConfig()
+        who = wait.event.event_type if wait.event is not None and wait.event.event_type else "clock"
+        return stage_id, "wait", who, describe_wait(wait)
     if kind == "ASK":
         ask = shape_get(stage, "ask")
         ask = ask if isinstance(ask, dict) else {}

{fruxon-2.0.2 → fruxon-2.2.0}/src/fruxon/cli/__init__.py

@@ -710,6 +710,7 @@ from fruxon.cli import agents_slots as _agents_slots  # noqa: E402, F401
 from fruxon.cli import agents_system_blocks as _agents_system_blocks  # noqa: E402, F401
 from fruxon.cli import agents_tests as _agents_tests  # noqa: E402, F401
 from fruxon.cli import agents_topics as _agents_topics  # noqa: E402, F401
+from fruxon.cli import agents_voice_calls as _agents_voice_calls  # noqa: E402, F401
 from fruxon.cli import applications as _applications  # noqa: E402, F401
 from fruxon.cli import applications_entry_points as _applications_entry_points  # noqa: E402, F401
 from fruxon.cli import assets as _assets  # noqa: E402, F401

{fruxon-2.0.2 → fruxon-2.2.0}/src/fruxon/cli/_shared.py

@@ -12,6 +12,7 @@ from __future__ import annotations
 
 import json
 import sys
+from dataclasses import dataclass
 from datetime import datetime, timezone
 
 import typer
@@ -69,6 +70,24 @@ def format_ts(ms: int | None) -> str:
         return f"{ms} (raw)"
 
 
+def format_relative(ms: int, now: int) -> str:
+    """How far ``ms`` is from ``now``, both epoch-ms: ``in 2d 3h`` ahead, ``40m ago`` behind.
+
+    Two units at most and never less than a minute — a due time is read as
+    "soon" or "a while", not to the second.
+    """
+    delta = abs(ms - now) // 60_000
+    days, rest = divmod(delta, 1_440)
+    hours, minutes = divmod(rest, 60)
+    if days:
+        span = f"{days}d {hours}h" if hours else f"{days}d"
+    elif hours:
+        span = f"{hours}h {minutes}m" if minutes else f"{hours}h"
+    else:
+        span = f"{max(minutes, 1)}m"
+    return f"in {span}" if ms >= now else f"{span} ago"
+
+
 def build_dict(required: dict, *, truthy: dict | None = None, keep_zero: dict | None = None) -> dict:
     """Assemble a wire dict from three buckets, so each call site only
     has to say which bucket a field belongs in rather than re-deriving
@@ -305,6 +324,73 @@ def build_client(workspace: str | None, base_url: str | None) -> FruxonClient:
     return FruxonClient(token=token, workspace=workspace, base_url=resolved_base)
 
 
+@dataclass(frozen=True)
+class KeyAccess:
+    """What the calling key carries, and what the server lets it do in this workspace.
+
+    ``scopes`` is the key's own list, as minted (``/tokens/current``). A
+    personal key acts as its owner, and the server cuts it down on every
+    request to what the owner's current workspace role allows
+    (fruxon-backend ``RoleScopeMap.CapToRole``), so ``scopes`` can name a
+    scope the key is refused. ``role`` and ``effective_scopes`` are that
+    cut. A service-account key carries no scopes of its own and no role
+    caps it: its ``effective_scopes`` is the account's grant and ``role``
+    is ``None``. Both are ``None`` when the server didn't say: the owner's
+    membership could not be read, or a service-account key on a server
+    older than fruxon-backend #1571.
+    """
+
+    key: dict
+    scopes: list[str]
+    personal: bool
+    role: str | None
+    effective_scopes: list[str] | None
+
+
+def read_key_access(client: FruxonClient) -> KeyAccess | None:
+    """Ask the server what ``client``'s key carries and what it may do in this workspace.
+
+    A server with fruxon-backend #1571 says it all on ``/tokens/current``
+    (``effectiveScopes``, and ``ownerRole`` for a personal key). On an
+    older one a personal key's cut is worked out from its owner's
+    membership (``GET /users/{ownerId}``), a read that needs
+    ``workspace:read``.
+
+    Best-effort: ``None`` when ``/tokens/current`` can't answer (signed in
+    by federation, network down, …), and a :class:`KeyAccess` without a
+    role when only the membership read fails.
+    """
+    try:
+        key = client.get_current_token()
+    except Exception:
+        return None
+    if not key:
+        return None
+    scopes = [str(s) for s in key.get("scopes") or []]
+    personal = key.get("ownerType") == "USER"
+    role = effective = None
+    owner = key.get("ownerId")
+    reported, owner_role = key.get("effectiveScopes"), key.get("ownerRole")
+    if isinstance(reported, list) and (owner_role or not personal):
+        # The server's own answer: what this request was authorised with
+        # (CapToRole's cut, or a service account's grant). One call, with
+        # no workspace:read, which a narrow key may not carry.
+        effective = [str(s) for s in reported]
+        role = str(owner_role) if owner_role else None
+    elif personal and owner:
+        try:
+            member = client.get_user(str(owner))
+        except Exception:
+            member = {}
+        ceiling = member.get("effectiveScopes")
+        if member.get("role") and isinstance(ceiling, list):
+            role = str(member["role"])
+            allowed = {str(s) for s in ceiling}
+            # CapToRole's order: the key's own, keeping what the role carries.
+            effective = [s for s in dict.fromkeys(scopes) if s in allowed]
+    return KeyAccess(key=key, scopes=scopes, personal=personal, role=role, effective_scopes=effective)
+
+
 def load_json_body(file: str, *, what: str) -> dict:
     """Read and parse a ``--file`` JSON request body into a dict.