fruxon 2.1.0__tar.gz → 2.2.0__tar.gz

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

@@ -1,5 +1,36 @@
 # 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fruxon
-Version: 2.1.0
+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
@@ -172,6 +172,7 @@ 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). |
@@ -182,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. |
@@ -343,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.1.0 → fruxon-2.2.0}/README.md

@@ -137,6 +137,7 @@ 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). |
@@ -147,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. |
@@ -308,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.1.0 → fruxon-2.2.0}/src/fruxon/__init__.py

@@ -81,7 +81,14 @@ from fruxon.models import (
     LedgerGatheringGroup,
     LedgerItem,
     LedgerItemAdmission,
+    LedgerItemAttempt,
+    LedgerItemAttemptAsk,
+    LedgerItemAttemptBatch,
+    LedgerItemAttemptOutcome,
+    LedgerItemAttemptWait,
     LedgerItemPoint,
+    LedgerItemRuns,
+    LedgerItemRunTotals,
     LedgerItemTimeseries,
     LedgerItemTransition,
     LedgerPass,
@@ -98,6 +105,11 @@ from fruxon.models import (
     LedgerStageTestSimulatedCall,
     LedgerStageTestSink,
     LedgerStageTestVerdict,
+    LedgerWaitCapture,
+    LedgerWaitConfig,
+    LedgerWaitEventConfig,
+    LedgerWaitExit,
+    LedgerWaitMatch,
     ManagedBy,
     ManagedResourceLink,
     Memory,
@@ -216,6 +228,13 @@ __all__ = [
     "LedgerGatheringGroup",
     "LedgerItem",
     "LedgerItemAdmission",
+    "LedgerItemAttempt",
+    "LedgerItemAttemptAsk",
+    "LedgerItemAttemptBatch",
+    "LedgerItemAttemptOutcome",
+    "LedgerItemAttemptWait",
+    "LedgerItemRuns",
+    "LedgerItemRunTotals",
     "LedgerItemTransition",
     "LedgerPass",
     "LedgerPurgeResult",
@@ -225,6 +244,11 @@ __all__ = [
     "LedgerStageTestSimulatedCall",
     "LedgerStageTestSink",
     "LedgerStageTestVerdict",
+    "LedgerWaitCapture",
+    "LedgerWaitConfig",
+    "LedgerWaitEventConfig",
+    "LedgerWaitExit",
+    "LedgerWaitMatch",
     "LedgerSkippedItem",
     "ManagedBy",
     "Memory",

{fruxon-2.1.0 → 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.1.0'
-__version_tuple__ = version_tuple = (2, 1, 0)
+__version__ = version = '2.2.0'
+__version_tuple__ = version_tuple = (2, 2, 0)
 
 __commit_id__ = commit_id = None

{fruxon-2.1.0 → 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.1.0 → 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.
 

{fruxon-2.1.0 → fruxon-2.2.0}/src/fruxon/cli/auth.py

@@ -18,6 +18,7 @@ import typer
 
 from fruxon import credentials, device_auth
 from fruxon.cli import app
+from fruxon.cli._shared import KeyAccess, read_key_access
 from fruxon.fruxon import FruxonClient
 from fruxon.ui import (
     EXIT_INTERACTIVE_REQUIRED,
@@ -586,14 +587,15 @@ def _storage_hint(path) -> str:
     return str(path)
 
 
-def _fetch_current_key_safely(token: str | None, workspace: str | None, base_url: str | None) -> dict | None:
-    """Best-effort call to ``/tokens/current`` for whoami enrichment.
+def _fetch_key_access_safely(token: str | None, workspace: str | None, base_url: str | None) -> KeyAccess | None:
+    """Best-effort call to ``/tokens/current`` (and the owner's role) for whoami enrichment.
 
-    Returns the key's metadata dict on success, ``None`` on any
-    failure — missing creds, network error, federation/JWT auth (no
-    token in scope), or anything else. Whoami's job is to answer
-    "am I signed in?" with local state; this just decorates the
-    answer with what the key can do when we can reach the server.
+    Returns what the key carries and what its owner's role lets it use
+    on success, ``None`` on any failure — missing creds, network error,
+    federation/JWT auth (no token in scope), or anything else. Whoami's
+    job is to answer "am I signed in?" with local state; this just
+    decorates the answer with what the key can do when we can reach the
+    server.
     """
     if not token or not workspace:
         return None
@@ -603,9 +605,9 @@ def _fetch_current_key_safely(token: str | None, workspace: str | None, base_url
             workspace=workspace,
             base_url=base_url or FruxonClient.DEFAULT_BASE_URL,
         )
-        return client.get_current_token()
     except Exception:
         return None
+    return read_key_access(client)
 
 
 @app.command()
@@ -668,7 +670,8 @@ def whoami(
     # core whoami data: a network failure here shouldn't break the
     # ability to ask "am I signed in?". The CLI's primary identity
     # check stays local-only; this just enriches it.
-    current_key = _fetch_current_key_safely(token, workspace, base_url)
+    access = _fetch_key_access_safely(token, workspace, base_url)
+    current_key = access.key if access else None
 
     if output == "json":
         # Structured shape an agent can branch on without parsing text.
@@ -690,12 +693,21 @@ def whoami(
                 {
                     "name": current_key.get("name"),
                     "keyPrefix": current_key.get("keyPrefix"),
-                    "scopes": current_key.get("scopes") or [],
+                    # The key's own scopes, as minted. A personal key may use
+                    # only those its owner's role also carries: effectiveScopes,
+                    # null when the role couldn't be read. A service-account
+                    # key carries none of its own and no role caps it; its
+                    # effectiveScopes is the account's grant (null on a server
+                    # older than fruxon-backend #1571).
+                    "scopes": access.scopes,
+                    "ownerType": current_key.get("ownerType"),
+                    "ownerRole": access.role,
+                    "effectiveScopes": access.effective_scopes,
                     "revokedAt": current_key.get("revokedAt"),
                     "expiresAt": current_key.get("expiresAt"),
                     "lastUsedAt": current_key.get("lastUsedAt"),
                 }
-                if current_key
+                if access and current_key
                 else None
             ),
         }
@@ -749,14 +761,70 @@ def whoami(
     # scope count. Full scope list is one extra line so it doesn't
     # bury the credential info above. Omitting on failure keeps
     # whoami useful when the network is unreachable.
-    if current_key:
+    if access and current_key:
         name = current_key.get("name") or "(unnamed)"
-        scopes = current_key.get("scopes") or []
+        if current_key.get("ownerType") == "SERVICE_ACCOUNT":
+            _say_service_account_grant(name, access)
+            return
+        scopes = access.scopes
         scope_count = len(scopes)
         say_ok(
-            f"Key [bold]{name}[/bold] · {scope_count} scope{'s' if scope_count != 1 else ''}",
+            f"Key [bold]{name}[/bold] · {scope_count} scope{'s' if scope_count != 1 else ''} on the key",
             hint=", ".join(scopes) if scopes else "no scopes (key is dead weight)",
         )
+        if access.personal:
+            _say_role_cap(access)
+
+
+def _say_service_account_grant(name: str, access: KeyAccess) -> None:
+    """Name a service-account key and the account's grant it acts with.
+
+    The key carries no scopes of its own, so the personal key's "0 scopes
+    on the key · dead weight" would call a working key dead. What it may
+    do is the account's grant, which a server with fruxon-backend #1571
+    reports as ``effectiveScopes``. No role caps it, so there is no role
+    line.
+    """
+    grant = access.effective_scopes
+    if grant is None:
+        say_ok(
+            f"Key [bold]{name}[/bold] · service account",
+            hint="It acts with the account's grant, which this server doesn't report.",
+        )
+        return
+    count = len(grant)
+    say_ok(
+        f"Key [bold]{name}[/bold] · service account · {count} scope{'s' if count != 1 else ''} from its grant",
+        hint=", ".join(grant) if grant else "no scopes (the account's grant is empty)",
+    )
+
+
+def _say_role_cap(access: KeyAccess) -> None:
+    """Say how much of a personal key its owner's workspace role lets it use.
+
+    The list above is the key's own; the server cuts a personal key down
+    to its owner's current role on every request. Without this line a
+    Viewer reads agents:write there, gets a 403 for it, and is told to
+    sign in again — which mints a key cut down the same way.
+    """
+    if access.role is None or access.effective_scopes is None:
+        say_info(
+            "Those are the key's own scopes. The server lets a personal key use "
+            "only those your workspace role also carries; your role couldn't be read here.",
+        )
+        return
+    role = access.role.replace("_", " ").title()
+    effective = access.effective_scopes
+    if set(effective) == set(access.scopes):
+        say_ok(f"Role [bold]{role}[/bold] · every scope on the key is in effect")
+        return
+    say_warn(
+        f"Role [bold]{role}[/bold] · this key may use {len(effective)} of its {len(set(access.scopes))} scopes here",
+        hint=(
+            f"{', '.join(effective) if effective else 'none'}\n"
+            "     Signing in again won't widen it; a workspace Admin can raise your role."
+        ),
+    )
 
 
 def _source_label(env_name: str, active: str | None, from_file: str | None) -> str:

{fruxon-2.1.0 → fruxon-2.2.0}/src/fruxon/cli/knowledge_notices.py

@@ -33,7 +33,7 @@ from typing import Annotated
 
 import typer
 
-from fruxon.cli._shared import build_client, confirm_or_die
+from fruxon.cli._shared import build_client, confirm_or_die, format_relative
 from fruxon.cli.knowledge_bases import _esc, _say_kv, knowledge_bases_app
 from fruxon.exceptions import FruxonError
 from fruxon.fruxon import KnowledgeNotice
@@ -643,20 +643,7 @@ def _when(ms: int, zone: str | None, now: int) -> str:
     """``2026-10-14 18:00 Asia/Jerusalem (in 4h 10m)``: in the zone agents tell it in, and how far off."""
     tz = _tzinfo(zone)
     at = datetime.fromtimestamp(ms / 1000, tz=tz or timezone.utc).strftime("%Y-%m-%d %H:%M")
-    return f"{at} {zone if tz else 'UTC'} ({_relative(ms, now)})"
-
-
-def _relative(ms: int, now: int) -> str:
-    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"
+    return f"{at} {zone if tz else 'UTC'} ({format_relative(ms, now)})"
 
 
 def _state(n: KnowledgeNotice) -> str:
@@ -677,11 +664,11 @@ def _notices_table(notices: list[KnowledgeNotice], now: int):
     table.add_column("Ends")
     for n in notices:
         if n.active:
-            ends = _relative(n.valid_until, now)
+            ends = format_relative(n.valid_until, now)
             state = "[green]active[/green]"
         else:
             note = f": {_esc(n.withdraw_note)}" if n.withdraw_note else ""
-            ends = f"[dim]{_relative(n.ended_at, now)}{note}[/dim]"
+            ends = f"[dim]{format_relative(n.ended_at, now)}{note}[/dim]"
             state = f"[dim]{_state(n)}[/dim]"
         table.add_row(_esc(n.id), _esc(n.title), state, ends)
     return table