fruxon 2.0.2__tar.gz → 2.1.0__tar.gz

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

@@ -1,5 +1,34 @@
 # History
 
+## 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.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fruxon
-Version: 2.0.2
+Version: 2.1.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,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 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. |

{fruxon-2.0.2 → fruxon-2.1.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,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 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. |

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

@@ -80,6 +80,7 @@ from fruxon.models import (
     LedgerFunnelCell,
     LedgerGatheringGroup,
     LedgerItem,
+    LedgerItemAdmission,
     LedgerItemPoint,
     LedgerItemTimeseries,
     LedgerItemTransition,
@@ -123,6 +124,8 @@ from fruxon.models import (
     TriggerParameterMapping,
     TriggerRevision,
     UnhandledEscalation,
+    VoiceCall,
+    VoiceCallTurn,
     WorkShapeDoor,
     WorkShapeDoorConversation,
     WorkShapeDoorField,
@@ -212,6 +215,7 @@ __all__ = [
     "LedgerFunnelCell",
     "LedgerGatheringGroup",
     "LedgerItem",
+    "LedgerItemAdmission",
     "LedgerItemTransition",
     "LedgerPass",
     "LedgerPurgeResult",
@@ -250,6 +254,8 @@ __all__ = [
     "TriggerRevision",
     "UnhandledEscalation",
     "ValidationError",
+    "VoiceCall",
+    "VoiceCallTurn",
     "WorkShapeDoor",
     "WorkShapeDoorConversation",
     "WorkShapeDoorField",

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

{fruxon-2.0.2 → fruxon-2.1.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.1.0/src/fruxon/cli/agents_voice_calls.py

@@ -0,0 +1,379 @@
+"""``fruxon agents voice-calls`` — read an agent's voice (Talk) calls back.
+
+A voice call is a Talk press in the studio Test lab: the caller speaks, the
+voice worker transcribes, the agent answers, and the worker speaks the reply.
+Each turn records two things a text transcript cannot: whether the reply ran
+to the end (``generation``) and how much of it the caller actually heard
+(``delivery``, with ``spokenText`` when they cut in). This is the read surface
+over them — "what did the caller say, what did the agent answer, what was
+heard of it" — without reading the cell's database.
+
+Agent-nested like executions (the backend's
+``agents/{agent}/voiceSessions``, ``executions:read``), and every turn names
+its run, so ``fruxon agents executions trace <agent> <execution-id>`` follows
+on from any reply.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Annotated
+
+import typer
+from rich.markup import escape as markup_escape
+
+from fruxon.cli._shared import build_client, format_ts
+from fruxon.cli.agents import _hint_for_get_error, agents_app
+from fruxon.exceptions import FruxonError, NotFoundError
+from fruxon.fruxon import FruxonClient, VoiceCall, VoiceCallTurn
+from fruxon.ui import (
+    EXIT_VALIDATION,
+    fail,
+    fail_from_api_error,
+    format_duration,
+    print_banner,
+    resolve_output_format,
+    say_info,
+    say_ok,
+    stderr,
+)
+
+voice_calls_app = typer.Typer(
+    help="Read an agent's voice (Talk) calls back: what was said, the reply, what was heard (list / get).",
+    no_args_is_help=True,
+)
+agents_app.add_typer(voice_calls_app, name="voice-calls")
+
+# How much of a transcript or reply a table cell shows; `get -o text` / `-o json` show all of it.
+_CELL_CHARS = 60
+
+
+@voice_calls_app.command("list")
+def voice_calls_list(
+    agent: Annotated[str, typer.Argument(help="Agent whose voice calls to list.")],
+    limit: Annotated[int, typer.Option("--limit", "-n", help="Max calls to return (newest first).")] = 20,
+    workspace: Annotated[str | None, typer.Option("--workspace", help="Workspace identifier override.")] = None,
+    base_url: Annotated[str | None, typer.Option("--base-url", help="API base URL override.")] = None,
+    output: Annotated[
+        str | None,
+        typer.Option("--output", "-o", help="Output format: table (default), json, id. Agent mode defaults to json."),
+    ] = None,
+):
+    """List an agent's voice calls, newest first.
+
+    One row per Talk press: when, language, status, why it ended, how many
+    turns, how long. Read one call's turns with
+    ``fruxon agents voice-calls get <agent> <voice-session-id>``.
+
+    A call with no turns and ``START_TIMEOUT`` never reached a voice worker;
+    ``ENDED`` with zero turns and ``USER_HANGUP`` is a caller who hung up
+    before saying anything the worker heard.
+
+    Examples:
+        fruxon agents voice-calls list my-agent
+        fruxon agents voice-calls list my-agent -n 5 --output json
+        fruxon agents voice-calls list my-agent -o id | head -1
+    """
+    output = resolve_output_format(output, human_default="table", agent_default="json")
+    if output not in {"table", "json", "id"}:
+        fail(
+            f"Unknown output format: [bold]{output}[/bold]",
+            hint="Valid formats: table, json, id.",
+            code=EXIT_VALIDATION,
+        )
+    if limit <= 0:
+        fail("--limit must be greater than zero.", code=EXIT_VALIDATION)
+
+    client = build_client(workspace, base_url)
+    try:
+        calls = client.list_voice_calls(agent, limit=limit)
+    except FruxonError as e:
+        fail_from_api_error(e, hint=_hint_for_get_error(e, agent, client))
+
+    if output == "id":
+        for c in calls:
+            print(c.id)
+        return
+    if output == "json":
+        print(json.dumps([_call_to_dict(c) for c in calls], indent=2, ensure_ascii=False))
+        return
+
+    if not calls:
+        say_info(
+            f"[bold]{agent}[/bold] has no voice calls.",
+            hint="Calls are made with the Talk button in the agent's Test lab.",
+        )
+        return
+    if stderr.is_terminal:
+        print_banner(subtitle=f"voice calls · {agent} · {len(calls)}")
+    stderr.print()
+    stderr.print(_build_calls_table(calls))
+    stderr.print()
+    say_ok(
+        f"[bold]{len(calls)}[/bold] call(s). Read one: "
+        f"[dim]fruxon agents voice-calls get {agent} <voice-session-id>[/dim]"
+    )
+    if len(calls) >= limit:
+        say_info(f"Showing the newest {limit}. Raise [bold]-n[/bold] to see older calls.")
+
+
+@voice_calls_app.command("get")
+def voice_calls_get(
+    agent: Annotated[str, typer.Argument(help="Agent the call was made to.")],
+    voice_session: Annotated[str, typer.Argument(help="The call's id (from `voice-calls list`).")],
+    workspace: Annotated[str | None, typer.Option("--workspace", help="Workspace identifier override.")] = None,
+    base_url: Annotated[str | None, typer.Option("--base-url", help="API base URL override.")] = None,
+    output: Annotated[
+        str | None,
+        typer.Option(
+            "--output",
+            "-o",
+            help="Output format: text (default; the whole transcript), table (one row a turn), json.",
+        ),
+    ] = None,
+):
+    """Show one voice call turn by turn: what the caller said, the reply, what was heard.
+
+    **What was heard is not always the reply.** ``delivery`` is
+    ``INTERRUPTED`` when the caller cut in; ``spokenText`` is then the part
+    they heard, and the rest of ``replyText`` never reached them.
+    ``generation`` is separate: ``CANCELLED`` is a reply stopped by that
+    interruption or by the caller's next turn, ``PENDING`` a turn the caller
+    talked over before it ran.
+
+    Every turn names its run in ``executionRecordId``; follow it with
+    ``fruxon agents executions trace <agent> <execution-id>`` to see the
+    tools, the prompt and the model call behind a reply. Times are epoch ms;
+    ``userStartedAt`` / ``userEndedAt`` are the voice worker's clock.
+
+    Examples:
+        fruxon agents voice-calls get my-agent 0199f3c2-…
+        fruxon agents voice-calls get my-agent 0199f3c2-… --output table
+        fruxon agents voice-calls get my-agent 0199f3c2-… -o json | jq '.turns[] | select(.delivery == "INTERRUPTED")'
+    """
+    output = resolve_output_format(output, human_default="text", agent_default="json")
+    if output not in {"text", "table", "json"}:
+        fail(
+            f"Unknown output format: [bold]{output}[/bold]",
+            hint="Valid formats: text, table, json.",
+            code=EXIT_VALIDATION,
+        )
+
+    client = build_client(workspace, base_url)
+    try:
+        call = client.get_voice_call(agent, voice_session)
+    except FruxonError as e:
+        fail_from_api_error(e, hint=_hint_for_call_error(e, agent, voice_session, client))
+
+    if output == "json":
+        print(json.dumps(_call_to_dict(call, with_turns=True), indent=2, ensure_ascii=False))
+        return
+
+    if stderr.is_terminal:
+        print_banner(subtitle=f"voice call · {agent} · {len(call.turns)} turn(s)")
+    stderr.print()
+    _render_call_header(call)
+    stderr.print()
+    if not call.turns:
+        say_info("No turns: the worker never heard the caller say anything.")
+        return
+    if output == "table":
+        stderr.print(_build_turns_table(call))
+    else:
+        for index, turn in enumerate(call.turns, start=1):
+            _render_turn(call, index, turn)
+    stderr.print()
+    if any(t.execution_record_id for t in call.turns):
+        say_ok(f"Trace a reply: [dim]fruxon agents executions trace {agent} <execution-id>[/dim]")
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# helpers
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def _hint_for_call_error(error: FruxonError, agent: str, voice_session: str, client: FruxonClient) -> str | None:
+    """A 404 on ``get`` is usually the call id, not the agent; say which."""
+    if not isinstance(error, NotFoundError):
+        return _hint_for_get_error(error, agent, client)
+    try:
+        client.get_agent(agent)
+    except FruxonError:
+        return _hint_for_get_error(error, agent, client)
+    return (
+        f"[bold]{agent}[/bold] has no voice call [bold]{voice_session}[/bold]. "
+        f"List its calls with [bold]fruxon agents voice-calls list {agent}[/bold]."
+    )
+
+
+def _call_length_ms(call: VoiceCall) -> int | None:
+    if call.call_duration_ms is not None:
+        return call.call_duration_ms
+    if call.started_at is not None and call.ended_at is not None:
+        return call.ended_at - call.started_at
+    return None
+
+
+def _offset(call: VoiceCall, turn: VoiceCallTurn) -> str:
+    """When the turn began, from the start of the call: the caller's first word if known."""
+    origin = call.started_at or call.created_at
+    at = turn.user_started_at or turn.created_at
+    if not origin or not at:
+        return ""
+    return f"+{format_duration(max(at - origin, 0))}"
+
+
+_DELIVERY_COLOR = {"PLAYED": "green", "INTERRUPTED": "yellow", "UNKNOWN": "red"}
+
+
+def _delivery_word(turn: VoiceCallTurn) -> str:
+    delivery = turn.delivery or "?"
+    color = _DELIVERY_COLOR.get(delivery)
+    return f"[{color}]{delivery}[/{color}]" if color else delivery
+
+
+def _delivery_label(turn: VoiceCallTurn) -> str:
+    delivery = turn.delivery or "?"
+    label = _delivery_word(turn)
+    if turn.delivered_duration_ms is not None and delivery in {"PLAYED", "INTERRUPTED"}:
+        label += f" [dim]({format_duration(turn.delivered_duration_ms)} played)[/dim]"
+    if turn.generation and turn.generation != "DONE":
+        label += f" · generation {turn.generation}"
+    return label
+
+
+def _render_call_header(call: VoiceCall) -> None:
+    status = call.status or "?"
+    reason = f" · {call.end_reason}" if call.end_reason else ""
+    stderr.print(f"  [bold]{call.id}[/bold]  {status} · {call.language or '?'}{reason}")
+    length = _call_length_ms(call)
+    parts = [f"started {format_ts(call.started_at)}" if call.started_at else f"pressed {format_ts(call.created_at)}"]
+    if length is not None:
+        parts.append(format_duration(length))
+    parts.append(f"{call.turn_count or len(call.turns)} turn(s)")
+    stderr.print(f"     [dim]{' · '.join(parts)}[/dim]")
+    stderr.print(f"     [dim]Test lab session {call.fruxon_session_id}[/dim]")
+    speech = []
+    if call.stt_provider:
+        heard = f" ({call.stt_seconds:.1f}s)" if call.stt_seconds is not None else ""
+        speech.append(f"speech-to-text {call.stt_provider}{heard}")
+    if call.tts_provider:
+        chars = f" ({call.tts_characters} chars)" if call.tts_characters is not None else ""
+        speech.append(f"voice {call.tts_provider}{chars}")
+    if speech:
+        stderr.print(f"     [dim]{' · '.join(speech)}[/dim]")
+
+
+def _render_turn(call: VoiceCall, index: int, turn: VoiceCallTurn) -> None:
+    stderr.print(f"  [bold]#{index}[/bold]  [dim]{_offset(call, turn)}[/dim]  {_delivery_label(turn)}")
+    caller = markup_escape(turn.transcript) if turn.transcript else "[dim]— (no transcript)[/dim]"
+    stderr.print(f"     [bold]Caller[/bold]  {caller}")
+    reply = markup_escape(turn.reply_text) if turn.reply_text else "[dim]— (no reply)[/dim]"
+    stderr.print(f"     [bold]Agent[/bold]   {reply}")
+    if turn.delivery == "INTERRUPTED":
+        heard = markup_escape(turn.spoken_text) if turn.spoken_text else "[dim]nothing[/dim]"
+        stderr.print(f"     [bold]Heard[/bold]   {heard}")
+    if turn.execution_record_id:
+        stderr.print(f"     [dim]execution {turn.execution_record_id}[/dim]")
+    stderr.print()
+
+
+def _cell(text: str) -> str:
+    flat = " ".join(text.split())
+    return markup_escape(flat if len(flat) <= _CELL_CHARS else flat[: _CELL_CHARS - 1] + "…")
+
+
+def _build_calls_table(calls: list[VoiceCall]):
+    from rich.table import Table
+
+    table = Table(show_header=True, header_style="bold", show_edge=False, pad_edge=False, box=None, padding=(0, 1))
+    table.add_column("ID", style="bold", no_wrap=True)
+    table.add_column("Pressed", no_wrap=True, style="dim")
+    table.add_column("Lang", no_wrap=True)
+    table.add_column("Status", no_wrap=True)
+    table.add_column("Ended", no_wrap=True)
+    table.add_column("Turns", justify="right")
+    table.add_column("Length", justify="right", no_wrap=True)
+    for c in calls:
+        length = _call_length_ms(c)
+        table.add_row(
+            c.id,
+            format_ts(c.created_at),
+            c.language or "[dim]—[/dim]",
+            c.status or "[dim]—[/dim]",
+            c.end_reason or "[dim]—[/dim]",
+            str(c.turn_count),
+            format_duration(length) if length is not None else "[dim]—[/dim]",
+        )
+    return table
+
+
+def _build_turns_table(call: VoiceCall):
+    from rich.table import Table
+
+    table = Table(show_header=True, header_style="bold", show_edge=False, pad_edge=False, box=None, padding=(0, 1))
+    table.add_column("#", justify="right", style="bold")
+    table.add_column("At", no_wrap=True, style="dim")
+    table.add_column("Caller", overflow="fold", ratio=1, min_width=16)
+    table.add_column("Heard", overflow="fold", ratio=1, min_width=16)
+    table.add_column("Delivery", no_wrap=True)
+    table.add_column("Execution", no_wrap=True, style="dim")
+    for index, t in enumerate(call.turns, start=1):
+        # What the caller heard: all of the reply, or the part before they cut in.
+        heard = (t.spoken_text or "") if t.delivery == "INTERRUPTED" else t.reply_text
+        table.add_row(
+            str(index),
+            _offset(call, t),
+            _cell(t.transcript) if t.transcript else "[dim]—[/dim]",
+            _cell(heard) if heard else "[dim]—[/dim]",
+            _delivery_word(t),
+            t.execution_record_id or "[dim]—[/dim]",
+        )
+    return table
+
+
+def _turn_to_dict(t: VoiceCallTurn) -> dict:
+    return {
+        "id": t.id,
+        "turnId": t.turn_id,
+        "language": t.language,
+        "transcript": t.transcript,
+        "replyText": t.reply_text,
+        "generation": t.generation,
+        "delivery": t.delivery,
+        "spokenText": t.spoken_text,
+        "deliveredDurationMs": t.delivered_duration_ms,
+        "executionRecordId": t.execution_record_id or None,
+        "createdAt": t.created_at,
+        "userStartedAt": t.user_started_at,
+        "userEndedAt": t.user_ended_at,
+        "generationEndedAt": t.generation_ended_at,
+        "cancelRequestedAt": t.cancel_requested_at,
+        "deliveryReportedAt": t.delivery_reported_at,
+    }
+
+
+def _call_to_dict(c: VoiceCall, *, with_turns: bool = False) -> dict:
+    body = {
+        "id": c.id,
+        "agentId": c.agent_id,
+        "fruxonSessionId": c.fruxon_session_id,
+        "status": c.status,
+        "language": c.language,
+        "createdAt": c.created_at,
+        "startedAt": c.started_at,
+        "endedAt": c.ended_at,
+        "endReason": c.end_reason or None,
+        "callDurationMs": c.call_duration_ms,
+        "turnCount": c.turn_count,
+        "createdByUserId": c.created_by_user_id or None,
+    }
+    if with_turns:
+        body |= {
+            "sttProvider": c.stt_provider or None,
+            "ttsProvider": c.tts_provider or None,
+            "sttSeconds": c.stt_seconds,
+            "ttsCharacters": c.tts_characters,
+            "turns": [_turn_to_dict(t) for t in c.turns],
+        }
+    return body

{fruxon-2.0.2 → fruxon-2.1.0}/src/fruxon/cli/examples.py

@@ -99,6 +99,7 @@ _EXAMPLES: dict[str, list[tuple[str, str]]] = {
         ),
         ("fruxon agents tests list my-agent", "List your saved test-chat sessions for an agent"),
         ("fruxon agents executions list my-agent", "List past executions — find a record id to trace"),
+        ("fruxon agents voice-calls list my-agent", "Talk calls made to the agent — find one to read back"),
         ("fruxon agents budget list my-agent", "Every cost cap — PRODUCTION + TEST, daily / weekly / monthly"),
         (
             "fruxon agents budget set my-agent --origin TEST --period DAILY --amount 20",
@@ -373,6 +374,15 @@ _EXAMPLES: dict[str, list[tuple[str, str]]] = {
         ),
         ("fruxon agents inbox my-agent", "What the agent is focused on (per participant)"),
     ],
+    "voice-calls": [
+        ("fruxon agents voice-calls list my-agent", "The agent's Talk calls, newest first — status, turns, length"),
+        ("fruxon agents voice-calls get my-agent 0199f3c2-…", "One call turn by turn: said, replied, heard"),
+        ("fruxon agents voice-calls get my-agent 0199f3c2-… -o table", "…one row a turn, with each turn's run"),
+        (
+            "fruxon agents voice-calls get my-agent 0199f3c2-… -o json | jq '.turns[].executionRecordId'",
+            "The runs behind the replies — feed one to `agents executions trace`",
+        ),
+    ],
     "memory": [
         ("fruxon agents memory list my-agent --subject user_42", "What the agent remembers about one person"),
         ("fruxon agents memory list my-agent --query 'dark mode'", "Full-text over its memories"),
@@ -734,6 +744,11 @@ _EXAMPLES: dict[str, list[tuple[str, str]]] = {
         ("fruxon llm-providers configs get vertex_ai 4950…", "Draft (masked), published revision, health"),
         ("fruxon llm-providers configs test vertex_ai 4950…", "Probe every surface sharing the credential"),
         ("fruxon llm-providers configs test vertex_ai_maas 4950…", "…or just that one surface"),
+        (
+            "fruxon llm-providers configs complete google 4950… --model gemini-3.1-flash-lite "
+            "--system @voice.txt -m 'hi'",
+            "One completion on the config, no agent: does the model follow this system prompt?",
+        ),
         ("fruxon llm-providers configs publish vertex_ai 4950…", "Ship the draft; every agent on it switches"),
         (
             "fruxon llm-providers connect openai",