fruxon 0.13.0__tar.gz → 0.13.2__tar.gz

{fruxon-0.13.0 → fruxon-0.13.2}/HISTORY.md

@@ -1,5 +1,193 @@
 # History
 
+## Unreleased — What a listing leaves out, and what a typo returns
+
+A patch release from a CLI trial run against a live workspace. Four defects,
+all of them the same shape: the CLI gave a confident answer that was missing
+something the server had already sent, or that no driver could parse.
+
+- **`triggers ledger items` carries each item's `label`.** The server sends
+  it, the Work grid shows it, and the CLI dropped it — so a listing named every
+  row by the provider's opaque key and nothing else. In `-o text` it sits next
+  to the key, and only when the door supplies one.
+- **`triggers doors` carries `labelPaths` and `labelFieldName`.** Where a door
+  reads an item's title from, printed as `labels work from`. These are the
+  paths a `door.projection` is forbidden to drop, so an author who could not
+  see them was authoring blind against a save-time refusal.
+- **A ledger listing is one page of 20, not the whole backlog.** The healthy
+  state of a busy ledger is thousands of `READY` rows served ten per request,
+  and walking them all was hundreds of round trips that the server rate-limits
+  long before the end — so an unqualified `triggers ledger items` returned an
+  error or nothing at all against a real automation. A full page now reports
+  what it is a page of; `-n` sizes it and `--all` still walks the lot. The SDK's
+  `list_ledger_items()` is unchanged: a library caller asking for items still
+  gets them all.
+- **`tools list` recovers the internal platform tools.** `knowledge_base` and
+  `assets` answered `[]` about tools an agent can attach and run, because the
+  tenant list endpoint filters them and takes no parameter that says otherwise.
+  The single-tool endpoint has no such filter, so the listing fetches them by
+  ID — each one confirmed against the server, so a stale ID disappears instead
+  of sending you to a `tools get` that 404s. `--no-include-internal` returns the
+  raw server answer.
+- **Every parse error is the same envelope, at every depth.** A bad flag on the
+  root command (`fruxon --bogus`) was the one case that still printed Click's
+  ASCII box to a driver that had been promised `{"error": {"code": "usage"}}`
+  and exit 2 for every other one. A person at the terminal still gets Click's
+  `Usage:` block.
+- **SDK:** `LedgerItem` gains `label`; `WorkShapeDoor` gains `label_paths` and
+  `label_field_name`.
+
+## Unreleased — A ledger automation can say what it cost
+
+The ledger could account for *where* work sat but not for what it came to, so
+a schedule's spend was only reachable one execution record at a time. The
+backend now carries cost on the accounting reads and adds a per-fire view
+(fruxon-backend#741).
+
+- **`triggers ledger funnel` and `triggers ledger items` carry `cost` and
+  `runs`.** The funnel therefore answers which *stage* the money goes to, not
+  only how much the ledger has spent; its trailing line totals both and shows
+  cost per item over the items that have actually run. An item's `runs` counts
+  every stage it passed through and so is deliberately not `stageAttempts`,
+  which resets per stage. `cost` is not sortable — the endpoint's `--order-by`
+  allow-list does not carry it, and an unlisted field is a 400.
+- **A cost column distinguishes "never ran" from "ran for free".** `runs` of 0
+  prints as `—`, not `$0.0000`: the second is a real and different state (an
+  exclusion that fired before any model call), and carrying `runs` alongside
+  `cost` is what keeps the two apart.
+- **New `fruxon triggers ledger passes <trigger>`** — one row per fire, newest
+  first, with `admitted` / `dispatched` / `completed` / `runs` / `cost` and the
+  fire log's own detail. `runs` sits below `dispatched` while runs are in
+  flight or when a dispatch was parked on a human, and a pass's `cost` rises
+  after `firedAt` as those runs finish, so an early read is a floor. `-n` /
+  `--limit` bounds the walk.
+- **SDK:** `FruxonClient.list_ledger_passes()` and the `LedgerPass` model;
+  `LedgerItem` and `LedgerFunnelCell` gain defaulted `cost` / `runs`.
+
+## Unreleased — Keeping only the fields an item needs
+
+- **`workShape.door.projection` (a list of dotted record paths)** names the
+  fields an admitted item keeps out of each source record. Without one an item
+  carries the record whole — stored per item, shown in the Work grid, and
+  handed to every stage on every pass. **Empty keeps everything**, which is
+  what every shape saved before this does, so no existing automation changes
+  shape. The item key, the door's label paths, the cursor and a write-back
+  target are kept whatever you name, and a projection that drops the id or a
+  label is refused at save time rather than quietly repaired.
+- **`triggers test-source` prints the projected record.** Each `record` is what
+  an item would actually carry, and an `item keeps` line names the paths that
+  survived (`projection` in `-o json`). Without it a field the projection drops
+  and a field the source never sent are the same silence, and they call for
+  opposite fixes.
+- **`triggers doors` carries `defaultProjection`.** The door's own suggestion
+  for what to keep, printed as `suggests keeping` — what to seed a new shape's
+  `door.projection` with. The sheet and table doors suggest nothing, because a
+  row's columns are yours and the row is the work.
+
+## Unreleased — Counting an exclusion before you undo one
+
+`redrive-many --ignore-reason` could reconsider what one revised instruction set
+aside, but the count it confirms had to be assembled here: the CLI listed the
+ledger and filtered it in memory, which is 40 round trips and 4,000 items on a
+real automation, and a second opinion about a set that moves.
+
+- **`triggers ledger items --ignore-reason "…"`** narrows to the items one
+  exclusion reason set aside, server-side — the same filter `redrive-many`
+  selects by, matched whole and case-sensitively, and only ever against
+  `IGNORED` items. It is how you read the batch a revised instruction is about
+  before putting it back.
+- **The selection verbs confirm the server's count** whenever the endpoint's
+  filters express the selection exactly: a `--status` or an `--ignore-reason`,
+  with no `--id` and no `--before`/`--after`. Everything else still resolves
+  here — an admission window has no query parameter, ids have to be intersected
+  and the invented ones named, and "DEAD or FAILED" is not a filter the endpoint
+  can be handed.
+- An API that reports no total sends the CLI back to the listing rather than
+  confirming a zero, which is the one count a selection verb accepts while
+  moving nothing.
+
+## Unreleased — Seeing what a source filter drops before you save it
+
+A work shape can now say which listed records it does not want:
+`workShape.door.skipWhen` is a `{match, conditions[]}` filter in the same
+vocabulary as a trigger's event filter, and a record it matches is never
+admitted — no item, no stage, no model call, nothing in the IGNORED pile.
+Before this, the only place such a rule could live was a first stage's
+`ignoreReasons`, which spends a model call per record to decide what a dotted
+path already knows.
+
+It has to be on the `door` rather than on `source`: saving re-expands `source`
+from the door, so a filter written onto `source` is discarded by the next save.
+
+- **`triggers test-source` marks each dropped record `FILTERED`** and counts
+  them under the listing, which is where to see what a rule costs before it
+  goes onto a live automation. A filter that reached the server and matched
+  nothing says so, because otherwise it is indistinguishable from one that
+  never arrived.
+- **`--count` reports `filtered` beside the total**, and `already held` is now
+  counted after the filter, so `total − filtered − already held` is the work
+  that would actually arrive. The CLI prints that subtraction rather than
+  leaving four numbers on one line for you to do it. On a source with no filter
+  every number is exactly what it was.
+- Records already admitted stay admitted: the rule governs admission, never
+  retraction.
+
+## Unreleased — Trying an automation on five instead of three thousand
+
+A work-shape automation had two settings: off, or draining everything. `triggers
+fire` ran a whole pass — admission to exhaustion, every stage claiming its full
+limit — so trying the Restigo TexterChat automation on a handful meant firing it
+at 3,401 resolved chats, and draining a stuck merge queue by hand pulled twenty
+more chats in behind the pile on every fire.
+
+- **`triggers fire` takes three ceilings for that one pass.** `--max-admit N`
+  stops admission after that many genuinely-new items (`0` leaves the source
+  untouched); `--max-dispatch N` caps how many items the whole pass claims,
+  across stages rather than per stage; `--stage <id>`, repeatable, claims only at
+  the stages named. They ride the request: the schedule keeps running the
+  automation exactly as configured, and the next fire is unbounded again unless
+  it asks for bounds of its own. A stage the work shape does not declare is
+  refused by the backend with a message naming the stages it does have.
+- **A bounded pass that stops mid-listing leaves the cursor where it was**, so
+  nothing is skipped — the next pass re-lists the same window and admission
+  de-duplicates it. That is also why the bound counts items admitted rather than
+  records listed: a second bounded fire reads past what it already knows and
+  takes the next N.
+- **The fire result says the pass was bounded.** `fire_trigger(...)` returns the
+  bounds under `bounds`, and the text output prints `admitted N, dispatched N —
+  bounded pass (…)`. Without it a pass sized by hand and an automation with
+  nothing to do print the same two counts. `--max-admit -1` is refused locally
+  rather than spending a round trip, because `0` means something specific here.
+
+## Unreleased — Patch: KB-trial CLI crash fixes
+
+The 2026-09-11 knowledge-base trial exposed a common failure underneath six
+apparently unrelated commands: Typer 0.26 vendors Click, so its parse exceptions
+are not subclasses of the top-level `click.ClickException` the new crash handler
+excluded. Unknown options, missing arguments, and no-argument help were therefore
+reported as Fruxon bugs.
+
+- **Agent-mode usage failures are typed again.** `NoSuchOption`,
+  `MissingParameter`, and `NoArgsIsHelpError` from either external or
+  Typer-vendored Click now emit the standard `{"error": {"code": "usage",
+  "exit_code": 2, ...}}` envelope and never write a crash report.
+- **The trial command forms now match the surrounding CLI.** `agents revisions
+  get` accepts `-o/--output json`; `tools get <integration> --tool/-t <id>`
+  matches `tools run --tool` (the old positional tool ID remains accepted for
+  compatibility); and `agents draft discard` now exposes `--yes/-y`, confirms
+  for humans, and requires the flag under an agent driver.
+- **Schema read timeouts are network errors, not crashes.** The live OpenAPI
+  fetch used by `--schema` catches a socket `TimeoutError`, exits 15, and points
+  at `--base-url` and the expected Swagger endpoint.
+- **Hidden internal tools are discoverable.** The backend's tenant list API
+  intentionally omits the internal `knowledge_base` and `assets` tools. An empty
+  `tools list` now explains that behavior, names the built-in IDs shipped with
+  this release, and shows how to inspect each tool's parameters with `tools get
+  ... --tool ... -o json`.
+- **`fruxon guides` prints its local help directly**, including in agent mode;
+  `integrations configs list` without its integration argument is a typed usage
+  error naming `INTEGRATION`.
+
 ## Unreleased — A channel connected through an entry point is a way in
 
 `agents check` looked for an inbound path in two places — a bound trigger and a

{fruxon-0.13.0 → fruxon-0.13.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fruxon
-Version: 0.13.0
+Version: 0.13.2
 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
@@ -134,18 +134,20 @@ Integrations + tools:
 | `fruxon integrations authorize <integration>` | Mint an application-level OAuth authorization URL to **connect** an integration — auto-detects its OAuth2 method (`--auth-method` to pick, `--scope`/`--config-param` to tune). OAuth needs a browser consent step, so the CLI hands you the link; a human clicks it, and the connection is saved as a tenant config a slot can pin. |
 | `fruxon integrations triggers <integration>` | List the event types an integration can fire an agent on — each descriptor's `id` is the `eventType` a trigger listens for, plus the `payloadFields` (dotted paths) a binding's `parameterMappings` can read. Discovery for wiring an inbound-event trigger without guessing. |
 | `fruxon integrations mcp …` | Inspect and enable the MCP server for an integration. |
-| `fruxon tools list/get/create/update/delete/run` | Manage the tools inside an integration. Integration-scoped. `run` executes one tool outside any agent — real credentials, real result — via `--tool` plus `-p key=value`, with `-c` naming the config that supplies credentials. |
+| `fruxon tools list/get/create/update/delete/run` | Manage the tools inside an integration. Integration-scoped. `get` and `run` select the tool with `--tool`; `run` executes it outside any agent — real credentials, real result — with `-p key=value`, and `-c` naming the config that supplies credentials. The tenant list API hides internal `knowledge_base` / `assets` tools; `tools list` recovers them by ID and lists them like any other (`--no-include-internal` for the raw server answer). |
 | `fruxon keys list/mint/revoke/delete/history/scopes` | Audit and revoke scoped tokens. Minting opens the dashboard so the secret never enters the CLI process. |
 | `fruxon llm-providers list/get/models` | Browse LLM providers and models supported at the tenant level. |
 | `fruxon assets create/list/get/wait/operations/delete` | Manage knowledge-base (RAG) assets a step 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 assets search/documents/chunks` | Reproduce and inspect a retrieval. `search` runs the same query an agent's `search_assets` does (`--mode HYBRID/VECTOR/FULL_TEXT`, `--top-k`, fusion weights) — note `score` is on a different scale per mode, and in hybrid the top hit is always 1.0. `documents` lists what the index contains (a `chunkCount` of 0 means that file yielded no indexable text); `chunks` reads one document's chunks in order. |
+| `fruxon assets search/documents/chunks` | Reproduce and inspect a retrieval. `search` runs the same query an agent's `search_assets` does (`--mode HYBRID/VECTOR/FULL_TEXT`, `--top-k`, fusion weights) — note `score` is on a different scale per mode, and in hybrid the top hit is always 1.0. `documents` lists what the index contains (a `chunkCount` of 0 means that file yielded no indexable text); `chunks` reads one document's chunks in order. The `documentId` these print is the **index's** id, which is what `chunks` takes — on a knowledge base's backing asset it is not the editable document's id, and it changes whenever a document's body is re-indexed. The `fileName` (`<knowledge document id>.md`) is the document a `knowledge_base` tool would edit. |
 | `fruxon metrics list` | Browse the evaluation-metric catalog — the ids a step's LLM-judge config (`judge.metrics[]`) binds, with a default weight each. |
 | `fruxon triggers list/get/create/update/delete/fire/bind/unbind` | Manage triggers — the schedule/event sources that fire agents. `create`/`update` take `--file` (+`--schema`); `create` also takes `--application`, the Application that will own the trigger and must own everything it fires. `bind`/`unbind` wire which agents fire; `fire` runs it now. `fire`/`delete`/`unbind` confirm + refuse without `--yes` in agent mode. The control plane for autonomy. `get` returns the full stored `workShape` and every `scheduleTimes` slot, so `get -o json | jq .workShape` produces a body `update --file` can post straight back — a PATCH replaces the whole shape, so edit what you read. |
-| `fruxon triggers doors` | The pre-configured source doors a work shape can be built on — the **first** question of authoring an automation, and the one `--schema` cannot answer: it tells you a `workShape.door` carries a `doorId`, not which ids exist. Each row is the integration a chosen `integrationConfigId` must belong to, plus the one query field that is genuinely yours (label + example), and `supportsStartFrom` — whether that door's source accepts a lower bound, and so whether a `door.startFrom` horizon does anything there. Read-only and static: a door is a claim that one combination of list tool, identity path and watermark actually works, made in platform code by someone who verified it. An integration with no door is still fully usable — configure `workShape.source` by hand. |
-| `fruxon triggers preview-shape/test-source` | Dry-run a work shape before saving or activating it; both write nothing. `preview-shape` renders, per stage, the resolved instruction, the whole `user_query` the agent is handed (item payload included), and the JSON schema the stage's declared `produces` keys become — against a real backlog item when you name a trigger. `test-source` runs the door's list tool once and says, per record, whether admission would take it, plus the exact arguments the tool was called with (for Gmail, your query with the day-granular `after:` folded in). `--count` pages the whole door instead and answers how much is waiting: the total, how many the ledger already holds, how many clear the watermark, and which server ceiling stopped the scan. `--file` tests a shape being edited — and a draft whose `door.startFrom` (Unix ms) sets a first-run horizon gets a `first run sends` line with the `after:` term that horizon produces, which is the only place to see it: `startFrom` seeds the ledger cursor once, when the ledger is created. |
-| `fruxon triggers ledger funnel/items/cursor/transitions/effects/batches` | The work items a schedule trigger's work shape admitted. `funnel` counts per stage and status (every item is in exactly one cell). `items` is the grid — `--stage`, `--status`, `--item-key` (client-side; the endpoint has no such filter), and each item's accumulated `data`, which is where a stage's declared `produces` keys land. `cursor` is the watermark and its freshness. `transitions` is one item's attempt history; `effects` is what it did to the outside world — an `UNKNOWN` row parks the item until someone settles it. `batches` is what an ASK stage is waiting on a human for. |
+| `fruxon triggers doors` | The pre-configured source doors a work shape can be built on — the **first** question of authoring an automation, and the one `--schema` cannot answer: it tells you a `workShape.door` carries a `doorId`, not which ids exist. Each row is the integration a chosen `integrationConfigId` must belong to, plus the one query field that is genuinely yours (label + example), and `supportsStartFrom` — whether that door's source accepts a lower bound, and so whether a `door.startFrom` horizon does anything there. `door.skipWhen` is the other field that is yours rather than the integration's: a `{match, conditions[]}` filter, same shape as a trigger's event filter, whose matching records are **never admitted** — no item, no stage, no model call. It has to live on the `door` because saving re-expands `source` from it, so the same filter written onto `source` is discarded by the next save. `door.projection` is the third: a list of dotted record paths naming the fields an admitted item **keeps**, with the door's own `defaultProjection` as the suggestion to seed it from — without one an item carries the whole record, into the Work grid and into every stage's prompt on every pass. Read that against the door's `labelPaths` (or, for the sheet and table doors, `labelFieldName` naming the field whose answer picks the label column): those are where an item's title comes from, and a projection that drops one is refused at save time rather than quietly repaired. Read-only and static: a door is a claim that one combination of list tool, identity path and watermark actually works, made in platform code by someone who verified it. An integration with no door is still fully usable — configure `workShape.source` by hand. |
+| `fruxon triggers preview-shape/test-source` | Dry-run a work shape before saving or activating it; both write nothing. `preview-shape` renders, per stage, the resolved instruction, the whole `user_query` the agent is handed (item payload included), and the JSON schema the stage's declared `produces` keys become — against a real backlog item when you name a trigger. `test-source` runs the door's list tool once and says, per record, whether admission would take it, plus the exact arguments the tool was called with (for Gmail, your query with the day-granular `after:` folded in). Records a `door.skipWhen` filter would drop read `FILTERED`, with a footer count — which is where to see what a rule costs before it goes onto a live automation. `--count` pages the whole door instead and answers how much is waiting: the total, how many the filter drops, how many the ledger already holds, how many clear the watermark, and which server ceiling stopped the scan — so `total − filtered − already held` is the work that would actually arrive. Each record prints **as the item will carry it** — narrowed to the shape's `door.projection`, with an `item keeps` line naming the paths that survived, so a field your projection drops and a field the source never sent are not the same silence. `--file` tests a shape being edited — and a draft whose `door.startFrom` (Unix ms) sets a first-run horizon gets a `first run sends` line with the `after:` term that horizon produces, which is the only place to see it: `startFrom` seeds the ledger cursor once, when the ledger is created. |
+| `fruxon triggers ledger funnel/items/cursor/transitions/effects/batches` | The work items a schedule trigger's work shape admitted. `funnel` counts per stage and status (every item is in exactly one cell). `items` is the grid — `--stage`, `--status`, `--ignore-reason`, `--item-key` (client-side; the endpoint has no such filter), each item's `label` (what the Work grid calls the row, as against the provider's opaque `itemKey`), and its accumulated `data`, which is where a stage's declared `produces` keys land. A listing is **one page of 20** that reports how many matched in total — a ledger's healthy state is thousands of rows served ten per request, so an unbounded walk is rate-limited long before the end; `-n` sizes the page and `--all` walks the lot. `--ignore-reason` narrows to the items one exclusion reason set aside — the same filter `redrive-many` selects by, matched whole and case-sensitively, so it is how you read a batch before putting it back. `cursor` is the watermark and its freshness. `transitions` is one item's attempt history; `effects` is what it did to the outside world — an `UNKNOWN` row parks the item until someone settles it. `batches` is what an ASK stage is waiting on a human for. `funnel` and `items` also carry `cost` (all-in USD) and `runs` — so the funnel says *which stage* the money goes to, not merely how much. An item's `runs` spans every stage it passed through and so is not `stageAttempts`, which resets per stage; a `Cost` of `—` means nothing there has ever been claimed, as against `$0.0000`, which means it ran and was free. Cost is not sortable: the endpoint's `--order-by` allow-list does not carry it. |
+| `fruxon triggers ledger passes` | Every time the automation fired, newest first — `admitted` (what the door took), `dispatched` (what the pass claimed and sent to work, questions parked on a human included), `completed` (how many of *this pass's* dispatches reached the terminal stage), `runs`, and the pass's all-in USD. `runs` sits **below** `dispatched` while runs are in flight or when a dispatch went to a person rather than a model — that gap is normal, not a lost item. And a pass's `cost` **rises after** it fired, as those runs finish, so a pass read seconds later reports a floor rather than its bill. An `outcome` other than `FIRED` means no sweep happened: `FILTERED` / `COALESCED` are healthy (nothing to do, or folded into a pass already running), `FAILED` / `FILTER_ERROR` are not. `-n/--limit` bounds the walk. |
 | `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 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). `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 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 redrive-many --ignore-reason "…"` | Reconsider what one instruction set aside. `IGNORED` is terminal for the scheduler, not for you: a re-drive returns an excluded item to `READY` at the stage that set it aside, with a fresh attempt budget. Exclusions are **opt-in** — they come in only with `--ignore-reason`, `--status IGNORED`, or `--id`, so `--stage X` still means the stuck items there. `--status IGNORED` alone is refused with the count it would have moved, because each item costs an agent run. The reason is matched whole and case-sensitively against what the stage recorded; a wording the shape does not declare but an item carries is still accepted. |
 | `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/effects/transitions, bumps the cursor version — and confirms the exact item count first. 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. |

{fruxon-0.13.0 → fruxon-0.13.2}/README.md

@@ -101,18 +101,20 @@ Integrations + tools:
 | `fruxon integrations authorize <integration>` | Mint an application-level OAuth authorization URL to **connect** an integration — auto-detects its OAuth2 method (`--auth-method` to pick, `--scope`/`--config-param` to tune). OAuth needs a browser consent step, so the CLI hands you the link; a human clicks it, and the connection is saved as a tenant config a slot can pin. |
 | `fruxon integrations triggers <integration>` | List the event types an integration can fire an agent on — each descriptor's `id` is the `eventType` a trigger listens for, plus the `payloadFields` (dotted paths) a binding's `parameterMappings` can read. Discovery for wiring an inbound-event trigger without guessing. |
 | `fruxon integrations mcp …` | Inspect and enable the MCP server for an integration. |
-| `fruxon tools list/get/create/update/delete/run` | Manage the tools inside an integration. Integration-scoped. `run` executes one tool outside any agent — real credentials, real result — via `--tool` plus `-p key=value`, with `-c` naming the config that supplies credentials. |
+| `fruxon tools list/get/create/update/delete/run` | Manage the tools inside an integration. Integration-scoped. `get` and `run` select the tool with `--tool`; `run` executes it outside any agent — real credentials, real result — with `-p key=value`, and `-c` naming the config that supplies credentials. The tenant list API hides internal `knowledge_base` / `assets` tools; `tools list` recovers them by ID and lists them like any other (`--no-include-internal` for the raw server answer). |
 | `fruxon keys list/mint/revoke/delete/history/scopes` | Audit and revoke scoped tokens. Minting opens the dashboard so the secret never enters the CLI process. |
 | `fruxon llm-providers list/get/models` | Browse LLM providers and models supported at the tenant level. |
 | `fruxon assets create/list/get/wait/operations/delete` | Manage knowledge-base (RAG) assets a step 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 assets search/documents/chunks` | Reproduce and inspect a retrieval. `search` runs the same query an agent's `search_assets` does (`--mode HYBRID/VECTOR/FULL_TEXT`, `--top-k`, fusion weights) — note `score` is on a different scale per mode, and in hybrid the top hit is always 1.0. `documents` lists what the index contains (a `chunkCount` of 0 means that file yielded no indexable text); `chunks` reads one document's chunks in order. |
+| `fruxon assets search/documents/chunks` | Reproduce and inspect a retrieval. `search` runs the same query an agent's `search_assets` does (`--mode HYBRID/VECTOR/FULL_TEXT`, `--top-k`, fusion weights) — note `score` is on a different scale per mode, and in hybrid the top hit is always 1.0. `documents` lists what the index contains (a `chunkCount` of 0 means that file yielded no indexable text); `chunks` reads one document's chunks in order. The `documentId` these print is the **index's** id, which is what `chunks` takes — on a knowledge base's backing asset it is not the editable document's id, and it changes whenever a document's body is re-indexed. The `fileName` (`<knowledge document id>.md`) is the document a `knowledge_base` tool would edit. |
 | `fruxon metrics list` | Browse the evaluation-metric catalog — the ids a step's LLM-judge config (`judge.metrics[]`) binds, with a default weight each. |
 | `fruxon triggers list/get/create/update/delete/fire/bind/unbind` | Manage triggers — the schedule/event sources that fire agents. `create`/`update` take `--file` (+`--schema`); `create` also takes `--application`, the Application that will own the trigger and must own everything it fires. `bind`/`unbind` wire which agents fire; `fire` runs it now. `fire`/`delete`/`unbind` confirm + refuse without `--yes` in agent mode. The control plane for autonomy. `get` returns the full stored `workShape` and every `scheduleTimes` slot, so `get -o json | jq .workShape` produces a body `update --file` can post straight back — a PATCH replaces the whole shape, so edit what you read. |
-| `fruxon triggers doors` | The pre-configured source doors a work shape can be built on — the **first** question of authoring an automation, and the one `--schema` cannot answer: it tells you a `workShape.door` carries a `doorId`, not which ids exist. Each row is the integration a chosen `integrationConfigId` must belong to, plus the one query field that is genuinely yours (label + example), and `supportsStartFrom` — whether that door's source accepts a lower bound, and so whether a `door.startFrom` horizon does anything there. Read-only and static: a door is a claim that one combination of list tool, identity path and watermark actually works, made in platform code by someone who verified it. An integration with no door is still fully usable — configure `workShape.source` by hand. |
-| `fruxon triggers preview-shape/test-source` | Dry-run a work shape before saving or activating it; both write nothing. `preview-shape` renders, per stage, the resolved instruction, the whole `user_query` the agent is handed (item payload included), and the JSON schema the stage's declared `produces` keys become — against a real backlog item when you name a trigger. `test-source` runs the door's list tool once and says, per record, whether admission would take it, plus the exact arguments the tool was called with (for Gmail, your query with the day-granular `after:` folded in). `--count` pages the whole door instead and answers how much is waiting: the total, how many the ledger already holds, how many clear the watermark, and which server ceiling stopped the scan. `--file` tests a shape being edited — and a draft whose `door.startFrom` (Unix ms) sets a first-run horizon gets a `first run sends` line with the `after:` term that horizon produces, which is the only place to see it: `startFrom` seeds the ledger cursor once, when the ledger is created. |
-| `fruxon triggers ledger funnel/items/cursor/transitions/effects/batches` | The work items a schedule trigger's work shape admitted. `funnel` counts per stage and status (every item is in exactly one cell). `items` is the grid — `--stage`, `--status`, `--item-key` (client-side; the endpoint has no such filter), and each item's accumulated `data`, which is where a stage's declared `produces` keys land. `cursor` is the watermark and its freshness. `transitions` is one item's attempt history; `effects` is what it did to the outside world — an `UNKNOWN` row parks the item until someone settles it. `batches` is what an ASK stage is waiting on a human for. |
+| `fruxon triggers doors` | The pre-configured source doors a work shape can be built on — the **first** question of authoring an automation, and the one `--schema` cannot answer: it tells you a `workShape.door` carries a `doorId`, not which ids exist. Each row is the integration a chosen `integrationConfigId` must belong to, plus the one query field that is genuinely yours (label + example), and `supportsStartFrom` — whether that door's source accepts a lower bound, and so whether a `door.startFrom` horizon does anything there. `door.skipWhen` is the other field that is yours rather than the integration's: a `{match, conditions[]}` filter, same shape as a trigger's event filter, whose matching records are **never admitted** — no item, no stage, no model call. It has to live on the `door` because saving re-expands `source` from it, so the same filter written onto `source` is discarded by the next save. `door.projection` is the third: a list of dotted record paths naming the fields an admitted item **keeps**, with the door's own `defaultProjection` as the suggestion to seed it from — without one an item carries the whole record, into the Work grid and into every stage's prompt on every pass. Read that against the door's `labelPaths` (or, for the sheet and table doors, `labelFieldName` naming the field whose answer picks the label column): those are where an item's title comes from, and a projection that drops one is refused at save time rather than quietly repaired. Read-only and static: a door is a claim that one combination of list tool, identity path and watermark actually works, made in platform code by someone who verified it. An integration with no door is still fully usable — configure `workShape.source` by hand. |
+| `fruxon triggers preview-shape/test-source` | Dry-run a work shape before saving or activating it; both write nothing. `preview-shape` renders, per stage, the resolved instruction, the whole `user_query` the agent is handed (item payload included), and the JSON schema the stage's declared `produces` keys become — against a real backlog item when you name a trigger. `test-source` runs the door's list tool once and says, per record, whether admission would take it, plus the exact arguments the tool was called with (for Gmail, your query with the day-granular `after:` folded in). Records a `door.skipWhen` filter would drop read `FILTERED`, with a footer count — which is where to see what a rule costs before it goes onto a live automation. `--count` pages the whole door instead and answers how much is waiting: the total, how many the filter drops, how many the ledger already holds, how many clear the watermark, and which server ceiling stopped the scan — so `total − filtered − already held` is the work that would actually arrive. Each record prints **as the item will carry it** — narrowed to the shape's `door.projection`, with an `item keeps` line naming the paths that survived, so a field your projection drops and a field the source never sent are not the same silence. `--file` tests a shape being edited — and a draft whose `door.startFrom` (Unix ms) sets a first-run horizon gets a `first run sends` line with the `after:` term that horizon produces, which is the only place to see it: `startFrom` seeds the ledger cursor once, when the ledger is created. |
+| `fruxon triggers ledger funnel/items/cursor/transitions/effects/batches` | The work items a schedule trigger's work shape admitted. `funnel` counts per stage and status (every item is in exactly one cell). `items` is the grid — `--stage`, `--status`, `--ignore-reason`, `--item-key` (client-side; the endpoint has no such filter), each item's `label` (what the Work grid calls the row, as against the provider's opaque `itemKey`), and its accumulated `data`, which is where a stage's declared `produces` keys land. A listing is **one page of 20** that reports how many matched in total — a ledger's healthy state is thousands of rows served ten per request, so an unbounded walk is rate-limited long before the end; `-n` sizes the page and `--all` walks the lot. `--ignore-reason` narrows to the items one exclusion reason set aside — the same filter `redrive-many` selects by, matched whole and case-sensitively, so it is how you read a batch before putting it back. `cursor` is the watermark and its freshness. `transitions` is one item's attempt history; `effects` is what it did to the outside world — an `UNKNOWN` row parks the item until someone settles it. `batches` is what an ASK stage is waiting on a human for. `funnel` and `items` also carry `cost` (all-in USD) and `runs` — so the funnel says *which stage* the money goes to, not merely how much. An item's `runs` spans every stage it passed through and so is not `stageAttempts`, which resets per stage; a `Cost` of `—` means nothing there has ever been claimed, as against `$0.0000`, which means it ran and was free. Cost is not sortable: the endpoint's `--order-by` allow-list does not carry it. |
+| `fruxon triggers ledger passes` | Every time the automation fired, newest first — `admitted` (what the door took), `dispatched` (what the pass claimed and sent to work, questions parked on a human included), `completed` (how many of *this pass's* dispatches reached the terminal stage), `runs`, and the pass's all-in USD. `runs` sits **below** `dispatched` while runs are in flight or when a dispatch went to a person rather than a model — that gap is normal, not a lost item. And a pass's `cost` **rises after** it fired, as those runs finish, so a pass read seconds later reports a floor rather than its bill. An `outcome` other than `FIRED` means no sweep happened: `FILTERED` / `COALESCED` are healthy (nothing to do, or folded into a pass already running), `FAILED` / `FILTER_ERROR` are not. `-n/--limit` bounds the walk. |
 | `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 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). `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 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 redrive-many --ignore-reason "…"` | Reconsider what one instruction set aside. `IGNORED` is terminal for the scheduler, not for you: a re-drive returns an excluded item to `READY` at the stage that set it aside, with a fresh attempt budget. Exclusions are **opt-in** — they come in only with `--ignore-reason`, `--status IGNORED`, or `--id`, so `--stage X` still means the stuck items there. `--status IGNORED` alone is refused with the count it would have moved, because each item costs an agent run. The reason is matched whole and case-sensitively against what the stage recorded; a wording the shape does not declare but an item carries is still accepted. |
 | `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/effects/transitions, bumps the cursor version — and confirms the exact item count first. 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. |

{fruxon-0.13.0 → fruxon-0.13.2}/src/fruxon/__init__.py

@@ -48,6 +48,7 @@ from fruxon.models import (
     LedgerFunnelCell,
     LedgerItem,
     LedgerItemTransition,
+    LedgerPass,
     LedgerPurgeResult,
     LedgerSelectionResult,
     LedgerSkippedItem,
@@ -73,6 +74,7 @@ from fruxon.models import (
     TriggerRevision,
     UnhandledEscalation,
     WorkShapeDoor,
+    WorkShapeDoorField,
     WorkShapeSourceCount,
     WorkShapeSourceTest,
     WorkShapeSourceTestRecord,
@@ -119,6 +121,7 @@ __all__ = [
     "LedgerFunnelCell",
     "LedgerItem",
     "LedgerItemTransition",
+    "LedgerPass",
     "LedgerPurgeResult",
     "LedgerSelectionResult",
     "LedgerSkippedItem",
@@ -147,6 +150,7 @@ __all__ = [
     "UnhandledEscalation",
     "ValidationError",
     "WorkShapeDoor",
+    "WorkShapeDoorField",
     "WorkShapeSourceCount",
     "WorkShapeSourceTest",
     "WorkShapeSourceTestRecord",

{fruxon-0.13.0 → fruxon-0.13.2}/src/fruxon/_version.py

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

{fruxon-0.13.0 → fruxon-0.13.2}/src/fruxon/cli/__init__.py

@@ -76,6 +76,8 @@ def _classify_exception(exc: BaseException) -> str:
     import ssl
     import urllib.error as _ue
 
+    from fruxon.cli import _crash
+
     if isinstance(exc, typer.Exit):
         # ``typer.Exit`` is a normal-flow signal even with a non-zero exit
         # code — it's how we surface a handled failure, not a crash. But it
@@ -86,6 +88,8 @@ def _classify_exception(exc: BaseException) -> str:
         # ``fail()``" and the schema's ``auth`` / ``not_found`` /
         # ``server_error`` values were allowlisted but never once sent.
         return _EXIT_CODE_CLASSES.get(getattr(exc, "exit_code", 1), "other")
+    if _crash.is_usage_error(exc):
+        return "user_input"
     if isinstance(exc, KeyboardInterrupt):
         return "user_input"
     if isinstance(exc, (_ue.URLError, socket.timeout, ConnectionError, ssl.SSLError, OSError)):
@@ -143,6 +147,31 @@ def _report_crash(exc: BaseException, command: str) -> None:
     stderr.print("     [dim]Full traceback here:[/dim] FRUXON_DEBUG=1 fruxon …")
 
 
+def _render_usage_error(exc: BaseException, command: str) -> None:
+    """Turn a Click parse failure into the agent contract's ``usage`` envelope.
+
+    Typer 0.26 vendors Click, so these exceptions bypass Typer's normal
+    top-level formatter while our custom group is on the stack — and what
+    reaches an AI driver is Click's bordered ASCII box, which is neither JSON
+    nor distinguishable from a crash. The contract (``fruxon guides show
+    fruxon-agent-mode``) says a parse error is one JSON envelope on stderr and
+    exit 2, and this is the single place that renders it.
+
+    Raises ``typer.Exit(2)``; never returns.
+    """
+    message = exc.format_message().strip() if hasattr(exc, "format_message") else str(exc).strip()
+    if not message:
+        message = "A subcommand is required."
+    usage_ctx = getattr(exc, "ctx", None)
+    command_path = getattr(usage_ctx, "command_path", None) or f"fruxon {command}"
+    say_err(
+        message,
+        hint=f"Run [bold]{command_path} --help[/bold] for usage.",
+        exit_code=2,
+    )
+    raise typer.Exit(2) from None
+
+
 class _FruxonTyperGroup(TyperGroup):
     """Branded replacement for Typer's stock ``no such command`` error.
 
@@ -160,6 +189,34 @@ class _FruxonTyperGroup(TyperGroup):
     signal.
     """
 
+    def make_context(self, info_name, args, parent=None, **extra):
+        """Catch the parse failures that happen *before* any subcommand runs.
+
+        ``invoke`` below covers everything raised while dispatching into the
+        tree, which is most of it. It cannot cover the root's own argument
+        parsing: Click builds the root context first and hands the failure
+        straight to its top-level handler, so ``fruxon --bogus`` printed the
+        ASCII box to an AI driver that had been promised JSON for every other
+        parse error in the CLI. Same envelope, same exit code, one fewer shape
+        for a caller to special-case.
+        """
+        try:
+            return super().make_context(info_name, args, parent=parent, **extra)
+        except BaseException as exc:
+            from fruxon.cli import _crash
+
+            if not (_crash.is_usage_error(exc) and is_agent_mode()):
+                raise
+            # The event the command would have sent had it got far enough to
+            # run. Reported as "(root)" because that is literally as far as it
+            # got — argv here has not been parsed, and putting an unparsed
+            # token on the wire is the thing `_command_path` exists to prevent.
+            telemetry.track(
+                "CLI Command Failed",
+                {"command": "(root)", "error_class": "user_input", "duration_ms": 0},
+            )
+            _render_usage_error(exc, "(root)")
+
     def invoke(self, ctx):
         """Wrap subcommand execution with telemetry timing.
 
@@ -206,6 +263,9 @@ class _FruxonTyperGroup(TyperGroup):
                 properties["error_fingerprint"] = mark
             telemetry.track("CLI Command Failed", properties)
 
+            if _crash.is_usage_error(exc) and is_agent_mode():
+                _render_usage_error(exc, command_name)
+
             if unexpected and not _crash.debug_enabled():
                 _report_crash(exc, command_name)
                 # Replaces the traceback rather than printing alongside it.
@@ -263,7 +323,7 @@ class _FruxonTyperGroup(TyperGroup):
             )
         else:
             hint = "Run [bold]fruxon --help[/bold] for the full command list."
-        say_err(f"Unknown command [bold]{cmd_name}[/bold].", hint=hint)
+        say_err(f"Unknown command [bold]{cmd_name}[/bold].", hint=hint, exit_code=2)
         ctx.exit(2)
         return None  # unreachable but keeps the type checker happy
 

{fruxon-0.13.0 → fruxon-0.13.2}/src/fruxon/cli/_crash.py

@@ -47,15 +47,48 @@ def is_unexpected(exc: BaseException) -> bool:
     changing their mind, and greeting it with a crash report would be absurd.
     What is left is a bug.
     """
-    import click
     import typer
 
-    return not isinstance(
-        exc,
-        (typer.Exit, typer.Abort, click.ClickException, click.exceptions.Abort, SystemExit, KeyboardInterrupt),
+    return (
+        not isinstance(exc, (typer.Exit, typer.Abort, SystemExit, KeyboardInterrupt))
+        and not _is_click_exception(exc)
+        and not _is_click_exception(exc, class_name="Abort")
     )
 
 
+def is_usage_error(exc: BaseException) -> bool:
+    """Whether ``exc`` is a parse/usage error from either Click namespace.
+
+    Typer 0.26 vendors Click under :mod:`typer._click`. Its
+    ``NoSuchOption`` / ``MissingParameter`` / ``NoArgsIsHelpError`` classes
+    are therefore *not* subclasses of the top-level ``click.UsageError``.
+    Checking both namespaces is what keeps an ordinary typo out of the crash
+    reporter while still supporting Typer releases that use external Click.
+    """
+    return _is_click_exception(exc, class_name="UsageError")
+
+
+def _is_click_exception(exc: BaseException, *, class_name: str = "ClickException") -> bool:
+    """Match Click's public exceptions and Typer's vendored equivalents."""
+    import click
+
+    classes: list[type[BaseException]] = []
+    external = getattr(click.exceptions, class_name, None)
+    if isinstance(external, type) and issubclass(external, BaseException):
+        classes.append(external)
+
+    try:
+        from typer._click import exceptions as typer_click_exceptions
+
+        vendored = getattr(typer_click_exceptions, class_name, None)
+        if isinstance(vendored, type) and issubclass(vendored, BaseException):
+            classes.append(vendored)
+    except ImportError:  # Older Typer releases use the top-level Click package.
+        pass
+
+    return bool(classes) and isinstance(exc, tuple(classes))
+
+
 def fingerprint(exc: BaseException) -> str | None:
     """``"KeyError at cli/agents_revisions.py:97"`` — safe to put on the wire.
 

{fruxon-0.13.0 → fruxon-0.13.2}/src/fruxon/cli/_schema.py

@@ -71,10 +71,13 @@ def _fetch_spec(base_url: str) -> dict:
     try:
         with urllib.request.urlopen(url, timeout=10, context=ctx) as resp:  # noqa: S310 — http(s) only
             data = json.load(resp)
-    except urllib.error.URLError as exc:
+    except (urllib.error.URLError, TimeoutError) as exc:
         fail(
             f"Couldn't fetch the OpenAPI spec from {url}: {exc}",
-            hint="Check that the server is reachable, then try again.",
+            hint=(
+                "Schema output is fetched from the target server. Check that it is reachable, "
+                "or pass --base-url for a server that exposes /swagger/v1/swagger.json."
+            ),
             code=EXIT_NETWORK,
         )
     except json.JSONDecodeError as exc:

{fruxon-0.13.0 → fruxon-0.13.2}/src/fruxon/cli/agents_draft.py

@@ -17,7 +17,7 @@ from typing import Annotated
 
 import typer
 
-from fruxon.cli._shared import build_client
+from fruxon.cli._shared import build_client, confirm_or_die
 from fruxon.cli.agents import (
     _hint_for_get_error,
     _hint_for_write_error,
@@ -1021,6 +1021,10 @@ def draft_evaluate(
 @draft_app.command("discard")
 def draft_discard(
     agent: Annotated[str, typer.Argument(help="Agent identifier.")],
+    yes: Annotated[
+        bool,
+        typer.Option("--yes", "-y", help="Skip the confirmation prompt. REQUIRED under agent mode (CLAUDECODE / CI)."),
+    ] = False,
     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[
@@ -1032,7 +1036,29 @@ def draft_discard(
         ),
     ] = None,
 ):
-    """Delete the draft on the server and remove the local sidecar."""
+    """Delete the draft on the server and remove the local sidecar.
+
+    The draft and its undo history cannot be recovered. Confirms first; under
+    agent mode, pass ``--yes`` explicitly so the command never blocks waiting
+    for input.
+
+    Examples:
+        fruxon agents draft discard my-agent --yes
+        fruxon agents draft discard my-agent --yes -o json
+    """
+    output = resolve_output_format(output, human_default="text", agent_default="json")
+    if output not in {"text", "json"}:
+        fail(
+            f"Unknown output format: [bold]{output}[/bold]",
+            hint="Valid formats: text, json.",
+            code=EXIT_VALIDATION,
+        )
+    confirm_or_die(
+        f"Discard the server draft for [bold]{agent}[/bold]? Its undo history will also be deleted.",
+        yes=yes,
+        action=f"discard the draft for {agent}",
+    )
+
     client = build_client(workspace, base_url)
     meta = _read_sidecar(agent)
     try:
@@ -1041,7 +1067,6 @@ def draft_discard(
         fail_from_api_error(e, hint=_hint_for_write_error(e))
     _sidecar_path(agent).unlink(missing_ok=True)
 
-    output = resolve_output_format(output, human_default="text", agent_default="json")
     if output == "json":
         print(json.dumps({"agent": agent, "discarded": True}, indent=2))
         return

{fruxon-0.13.0 → fruxon-0.13.2}/src/fruxon/cli/agents_revisions.py

@@ -146,6 +146,10 @@ def revisions_get(
     ] = False,
     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: json (the only format for this pipe-oriented command)."),
+    ] = None,
 ):
     """Print a revision's full body.
 
@@ -168,9 +172,16 @@ def revisions_get(
     Examples:
         fruxon agents revisions get my-agent              # current deployed revision
         fruxon agents revisions get my-agent 3            # a specific revision
-        fruxon agents revisions get my-agent --as-draft   # postable body
+        fruxon agents revisions get my-agent --as-draft -o json   # postable body
         fruxon agents revisions get my-agent | jq .definition   # just the agent
     """
+    if output not in {None, "json"}:
+        fail(
+            f"Unknown output format: [bold]{output}[/bold]",
+            hint="This command always emits JSON; pass [bold]--output json[/bold] or omit the flag.",
+            code=EXIT_VALIDATION,
+        )
+
     client = build_client(workspace, base_url)
 
     target_revision: int | str