fruxon 2.1.0__tar.gz → 2.2.1__tar.gz

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

@@ -1,5 +1,55 @@
 # History
 
+## Unreleased — `chat_user` is deprecated: the server ignores it
+
+- `execute`, `stream` and `stream_text` no longer send `chat_user` (as
+  `chatUser`). The execution endpoints have no field for it, so the server
+  dropped it unread: it did not identify the end user to the agent, gave no
+  per-user memory and filled no `{{sender.*}}` values. The argument is still
+  accepted, so existing calls keep working, but passing it emits a
+  `DeprecationWarning`. To give the agent details about the user, pass them in
+  `parameters`.
+
+## Unreleased — `agents memory` names a person by participant id or address
+
+- `fruxon agents memory forget-subject` and `list --subject` document the
+  subject the server takes: the person's participant id, or one of their
+  addresses as `provider:identifier` (e.g. `telegram:123456789`). The old
+  example, `user_42`, matched nothing. With fruxon-backend's fix either form
+  reaches every memory about the person — those filed under the participant
+  id since memory follows the person, and older ones filed under an address.
+
+## 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.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fruxon
-Version: 2.1.0
+Version: 2.2.1
 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.1}/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.1}/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.1}/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.1'
+__version_tuple__ = version_tuple = (2, 2, 1)
 
 __commit_id__ = commit_id = None

{fruxon-2.1.0 → fruxon-2.2.1}/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.1}/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.1}/src/fruxon/cli/agents_memory.py

@@ -51,7 +51,13 @@ def memory_list(
     agent: Annotated[str, typer.Argument(help="Agent whose memories to list.")],
     subject: Annotated[
         str | None,
-        typer.Option("--subject", help="Only memories about this subject (person / end-user key)."),
+        typer.Option(
+            "--subject",
+            help=(
+                "Only memories about this person: their participant id, or a channel address as "
+                "provider:identifier (e.g. telegram:123456789)."
+            ),
+        ),
     ] = None,
     query: Annotated[str | None, typer.Option("--query", "-q", help="Full-text filter over title + content.")] = None,
     scope: Annotated[
@@ -75,10 +81,13 @@ def memory_list(
     """List what an agent remembers — narrow with --subject / --query / --scope.
 
     The filters run server-side, so "what does my agent remember about
-    user_42" is `--subject user_42`, not a client-side scan.
+    the Telegram user 123456789" is `--subject telegram:123456789`, not a
+    client-side scan. A subject is the person's participant id or one of
+    their addresses as provider:identifier; either matches every memory
+    about them.
 
     Examples:
-        fruxon agents memory list my-agent --subject user_42
+        fruxon agents memory list my-agent --subject telegram:123456789
         fruxon agents memory list my-agent --query "dark mode"
         fruxon agents memory list my-agent --scope AGENT --output id
     """
@@ -228,7 +237,15 @@ def memory_get(
 @memory_app.command("forget-subject")
 def memory_forget_subject(
     agent: Annotated[str, typer.Argument(help="Agent whose memories to prune.")],
-    subject: Annotated[str, typer.Argument(help="The subject (person / end-user key) to forget entirely.")],
+    subject: Annotated[
+        str,
+        typer.Argument(
+            help=(
+                "The person to forget entirely: their participant id, or a channel address as "
+                "provider:identifier (e.g. telegram:123456789)."
+            )
+        ),
+    ],
     yes: Annotated[
         bool,
         typer.Option("--yes", "-y", help="Skip the confirmation prompt. REQUIRED under agent mode (CLAUDECODE / CI)."),
@@ -242,11 +259,17 @@ def memory_forget_subject(
 ):
     """Forget every memory an agent holds about one subject (GDPR-style).
 
-    Irreversible — it deletes all of the subject's memories. Confirms
-    first, and under agent mode refuses without [bold]--yes[/bold].
+    Irreversible — it deletes all of the person's memories, whether they
+    are filed under the participant id or under any of the person's
+    addresses, and records each deletion in the agent's deletion trail.
+    Confirms first, and under agent mode refuses without [bold]--yes[/bold].
+
+    Name the person by participant id (the `subject` column of
+    `agents memory subjects`) or by an address as provider:identifier.
 
     Examples:
-        fruxon agents memory forget-subject my-agent user_42 --yes
+        fruxon agents memory forget-subject my-agent telegram:123456789 --yes
+        fruxon agents memory forget-subject my-agent 0199f3c2-5b1e-7c4a-9d2e-3f6a8b1c0d4e --yes
     """
     output = resolve_output_format(output, human_default="text", agent_default="json")
     if output not in {"text", "json"}: