Skip to content

The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.

docs: document physical dispatch observer and refresh storage schema

Steven Enamakel1620c074c0e1
diff --git a/docs/gitbooks/en/developing/embed/api-index.json b/docs/gitbooks/en/developing/embed/api-index.json
index ff226db3f7..cfc0ccbdf3 100644
--- a/docs/gitbooks/en/developing/embed/api-index.json
+++ b/docs/gitbooks/en/developing/embed/api-index.json
@@ -86,6 +86,12 @@
"PendingApproval",
"PermissionFuture",
"PermissionLevel",
+ "PhysicalDispatchMetadata",
+ "PhysicalDispatchObserver",
+ "PhysicalDispatchOutcome",
+ "PhysicalDispatchStatus",
+ "PhysicalDispatchTerminal",
+ "PhysicalDispatchUsage",
"PickListenPortError",
"ProfileError",
"ProfileEvents",
diff --git a/docs/gitbooks/en/developing/embed/api-index.md b/docs/gitbooks/en/developing/embed/api-index.md
index e9afe29292..e2cd45122a 100644
--- a/docs/gitbooks/en/developing/embed/api-index.md
+++ b/docs/gitbooks/en/developing/embed/api-index.md
@@ -89,6 +89,12 @@ Generate the complete local Rust API reference with `cargo doc -p openhuman-embe
- [`PendingApproval`](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/src/lib.rs)
- [`PermissionFuture`](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/src/lib.rs)
- [`PermissionLevel`](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/src/lib.rs)
+- [`PhysicalDispatchMetadata`](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/src/lib.rs)
+- [`PhysicalDispatchObserver`](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/src/lib.rs)
+- [`PhysicalDispatchOutcome`](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/src/lib.rs)
+- [`PhysicalDispatchStatus`](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/src/lib.rs)
+- [`PhysicalDispatchTerminal`](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/src/lib.rs)
+- [`PhysicalDispatchUsage`](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/src/lib.rs)
- [`PickListenPortError`](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/src/lib.rs)
- [`ProfileError`](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/src/lib.rs)
- [`ProfileEvents`](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/src/lib.rs)
diff --git a/docs/storage-schema.md b/docs/storage-schema.md
index c08396cf39..1ad4868416 100644
--- a/docs/storage-schema.md
+++ b/docs/storage-schema.md
@@ -340,6 +340,7 @@ Migration steps:
| Kind | Name | Version | Scope | Indexed fields |
| --- | --- | --- | --- | --- |
+| collection | `subagents.session_epochs` | 1 | agent | |
| collection | `subagents.sessions` | 2 | agent | |
Migration steps:
@@ -398,15 +399,3 @@ Migration steps:
Migration steps:
- `transcript_keys_v2`: `threads.transcript_keys` v1 to v2 from `threads_transcript_keys`
-
-## wallet
-
-| Kind | Name | Version | Scope | Indexed fields |
-| --- | --- | --- | --- | --- |
-| collection | `wallet.budgets` | 2 | module | |
-| stream | `wallet.payments` | | module | |
-
-Migration steps:
-
-- `budgets_v2`: `wallet.budgets` v1 to v2 from `x402_budget`
-- `payments_v2`: `wallet.payments` v1 to v2 from `x402.payments`
diff --git a/llms-full.txt b/llms-full.txt
index 3e68d396ca..558e9fb812 100644
--- a/llms-full.txt
+++ b/llms-full.txt
@@ -536,6 +536,10 @@ A physical timeout is an RPC transport failure, so an explicit `CompletionLadder
A timed-out physical attempt has unknown reported cost. Ladder aggregate cost stays unknown, and a budgeted call keeps its conservative reservation if no authoritative usage arrived. The remaining budget may therefore refuse a fallback before it sends another request. See the [routing guide](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/ROUTING.md) for the explicit ladder API.
+## Provider dispatch observation
+
+Attach `Completer::physical_observer` to receive one content-free start and terminal outcome for each provider invocation. The observer runs inside budget admission, so a request refused by the budget produces no dispatch event. A dropped in-flight request reports cancellation; terminal outcomes carry duration and provider-reported usage when available. The existing `CompletionObserver` remains a logical completion hook and still fires once for the whole call, including structured repair attempts.
+
<!-- Source: docs/gitbooks/en/developing/embed/concepts/cron.md -->
---
description: "Cron provides durable named jobs, explicit run-now execution and job history addressed to registered agents."
@@ -2501,6 +2505,18 @@ tools that spawn independent tasks or processes must provide their own cleanup;
MCP server lifecycles remain owned by the agent. Keep polling `send()` while
awaiting cancellation, for example in a spawned task.
+## Observing provider dispatches
+
+Attach `Completer::physical_observer` to receive one content-free terminal event
+for each admitted provider `ChatModel` invocation. Structured JSON repairs
+produce separate events, while request and response content remains private.
+Transport-level compatibility retries performed inside one provider invocation
+remain within that event, and its latency includes those retries. With a model
+budget, the explicit and turn-scoped observers run inside admission and after
+gateway charge normalization, so they see the same authoritative amount the
+ledger settles. A budget refusal before provider invocation creates no event.
+The existing `CompletionObserver` remains a once-per-logical-call callback.
+
## Steering one turn
Acquire `Turn::steering_handle()` before sending a turn to add messages to it
@@ -2962,6 +2978,12 @@ Generate the complete local Rust API reference with `cargo doc -p openhuman-embe
- [`PendingApproval`](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/src/lib.rs)
- [`PermissionFuture`](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/src/lib.rs)
- [`PermissionLevel`](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/src/lib.rs)
+- [`PhysicalDispatchMetadata`](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/src/lib.rs)
+- [`PhysicalDispatchObserver`](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/src/lib.rs)
+- [`PhysicalDispatchOutcome`](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/src/lib.rs)
+- [`PhysicalDispatchStatus`](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/src/lib.rs)
+- [`PhysicalDispatchTerminal`](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/src/lib.rs)
+- [`PhysicalDispatchUsage`](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/src/lib.rs)
- [`PickListenPortError`](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/src/lib.rs)
- [`ProfileError`](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/src/lib.rs)
- [`ProfileEvents`](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/src/lib.rs)