diff --git a/docs-site/src/content/docs/reference/cli/agents.md b/docs-site/src/content/docs/reference/cli/agents.md index 882c7ef59db..f0d1f4b55d1 100644 --- a/docs-site/src/content/docs/reference/cli/agents.md +++ b/docs-site/src/content/docs/reference/cli/agents.md @@ -450,6 +450,24 @@ Any displayed totals reflect readable records only. If a filter has no readable the warning and guidance instead of total lines; skipped records may contain matches. `--json` preserves the response-level `usageIncomplete` diagnostic and reason. +### Page indexed request history + +```bash +ocx logs history --provider xai --status 200 --limit 50 --json +ocx logs history --cursor '' --json +ocx logs get --json +``` + +`ocx observe logs history` and `ocx observe logs get` are the equivalent family +forms. These read the derived request-history index, not the recent `ocx logs` +ring. `--limit` is 1–100 (default 50). `--from` and `--to` accept epoch +milliseconds or full ISO datetimes with a timezone and are inclusive. `--json` +returns `{entries,hasMore,nextCursor,index}`. `--jsonl` emits rows only; when +more pages exist, `nextCursor=…` is printed on stderr so a caller can resume +without mixing the token into the row stream. Empty matches succeed. `get` +returns one canonical row by request ID; `ocx logs explain` remains the +route-decision view for that same ID. + ### Filter a bounded log snapshot ```bash diff --git a/docs-site/src/content/docs/reference/configuration/routing.md b/docs-site/src/content/docs/reference/configuration/routing.md index ff299a2b440..47c688e9509 100644 --- a/docs-site/src/content/docs/reference/configuration/routing.md +++ b/docs-site/src/content/docs/reference/configuration/routing.md @@ -367,7 +367,8 @@ Returned history and route-decision payloads expose only masked request metadata (for example opaque `apiKeyId` labels). They do not include credentials, raw prompt bodies, or provider secrets. -CLI: `ocx logs explain `, `ocx logs rebuild-index`, +CLI: `ocx logs history`, `ocx logs get `, +`ocx logs explain `, `ocx logs rebuild-index`, `ocx logs index-status`, `ocx route policy list | show | dry-run | evaluate`. ## Migration diff --git a/scripts/test-layout/layout.json b/scripts/test-layout/layout.json index 16227fe5cf1..68630b8f8e1 100644 --- a/scripts/test-layout/layout.json +++ b/scripts/test-layout/layout.json @@ -22,7 +22,7 @@ "management-sidecar-anthropic-instance.test.ts": "server", "anthropic2-usage-attribution.test.ts": "usage", "vision-anthropic-instance-sidecar.test.ts": "vision", "web-search-anthropic-instance.test.ts": "web-search", "provider-anthropic-instance.test.ts": "providers", "config-anthropic-instance-pool.test.ts": "config", "oauth-anthropic-instance-registration.test.ts": "oauth", "oauth-anthropic-instance-refresh.test.ts": "oauth", "claude-picker-upload.test.ts": "claude-integration", "claude-picker-linger.test.ts": "claude-integration", "messages-native-scope.test.ts": "claude-integration", "catalog-auto-review-row.test.ts": "codex-integration", - "cli-log-view-filter.test.ts": "cli", "cli-usage-model-search.test.ts": "cli", "cli-companion-usage.test.ts": "cli", "cli-account-key-quota.test.ts": "cli", + "cli-log-view-filter.test.ts": "cli", "cli-log-history.test.ts": "cli", "cli-usage-model-search.test.ts": "cli", "cli-companion-usage.test.ts": "cli", "cli-account-key-quota.test.ts": "cli", "cli-observe-snapshot.test.ts": "cli", "cli-access-data-plane.test.ts": "cli", "cli-access-key-guard.test.ts": "cli", "cli-access-rename.test.ts": "cli", "cli-access-audio.test.ts": "cli", "cli-access-audio-live.test.ts": "cli", "cli-log-follow.test.ts": "cli", "cli-injection-follow.test.ts": "cli", "cli-usage-scope.test.ts": "cli", "cli-system-health.test.ts": "cli", "cli-companion-timeline.test.ts": "cli", "server-cli-key-probe-admission.test.ts": "server", diff --git a/skills/ocx/references/01_management_surface.md b/skills/ocx/references/01_management_surface.md index 901cb97f388..f00b52a573e 100644 --- a/skills/ocx/references/01_management_surface.md +++ b/skills/ocx/references/01_management_surface.md @@ -30,7 +30,7 @@ These answer in the CLI head and never reach the proxy, so they work with nothin | [accounts](01_surface_accounts.md) | 40 | | [agents-routing](01_surface_agents-routing.md) | 51 | | [integrations](01_surface_integrations.md) | 41 | -| [observe-system](01_surface_observe-system.md) | 92 | +| [observe-system](01_surface_observe-system.md) | 94 | | [access-remote](01_surface_access-remote.md) | 32 | | [lab](01_surface_lab.md) | 21 | @@ -923,6 +923,14 @@ Original invocation order. These headings preserve links to the previous single- [Read-oriented task](01_surface_observe-system.md#ocx-observe-logs) +### `ocx logs history` + +[Read-oriented task](01_surface_observe-system.md#ocx-logs-history) + +### `ocx logs get` + +[Read-oriented task](01_surface_observe-system.md#ocx-logs-get) + ### `ocx logs explain` [Read-oriented task](01_surface_observe-system.md#ocx-logs-explain) @@ -1393,6 +1401,6 @@ Original invocation order. These headings preserve links to the previous single- ## Counts -- declared capabilities: 336 +- declared capabilities: 338 - of those, state-changing: 205 - head-resolved invocations: 2 diff --git a/skills/ocx/references/01_surface_observe-system.md b/skills/ocx/references/01_surface_observe-system.md index 2c6f86aded2..ad8e60897fc 100644 --- a/skills/ocx/references/01_surface_observe-system.md +++ b/skills/ocx/references/01_surface_observe-system.md @@ -8,7 +8,7 @@ Use these declarations to choose a task, then check its flags and authority before execution. Non-mutating probes may still contact providers, consume quota or refresh caches. -Declared capabilities: 92. +Declared capabilities: 94. ### `ocx companion` @@ -95,7 +95,7 @@ JSON mode: `payload`. - Follow uses the server cursor and a bounded ordered window, preserving same-ID amendments and repeated row occurrences. It never enables logging. - --events emits version1 snapshots/appends with cursor and limit for observed-window reconstruction. Legacy row JSONL cannot express removals or resets exactly; neither mode promises lossless history between polls. - Follow limit is1–2000, default200. Polling is serial and cancellable; SIGINT exits130 and SIGTERM143. Malformed/oversized/unavailable responses stop without a fabricated empty snapshot or retry. -- Nested explain reads recorded decisions; rebuild-index and index-status touch the local derived index and retain separate declarations. +- Nested history pages the derived index and get reads one canonical row; explain reads recorded decisions; rebuild-index and index-status touch the local derived index and retain separate declarations. ### `ocx storage report` @@ -565,6 +565,63 @@ JSON mode: `payload`. - --events emits version1 snapshots/appends with cursor and limit for observed-window reconstruction. Legacy row JSONL cannot express removals or resets exactly; neither mode promises lossless history between polls. - Follow limit is1–2000, default200. Polling is serial and cancellable; SIGINT exits130 and SIGTERM143. Malformed/oversized/unavailable responses stop without a fabricated empty snapshot or retry. +### `ocx logs history` + +Usage: `ocx logs history [--provider ] [--model ] [--requested-model ] [--status ] [--conversation ] [--surface ] [--protocol ] [--api-key-id ] [--profile ] [--fallback ] [--from ] [--to ] [--cursor ] [--limit <1-100>] [--json|--jsonl]` + +Page the indexed request-history ledger with filters and a resumable cursor. + +State-changing: no. + +| Method | Route | +|---|---| +| GET | `/api/request-history` | + +| Flag | Value | Meaning | +|---|---|---| +| `--provider` | string | Filter provider, including failover attempts. | +| `--model` | string | Filter served model, including failover attempts. | +| `--requested-model` | string | Filter the model the client asked for. | +| `--status` | number | HTTP status 100-599. | +| `--conversation` | string | Conversation ID or stored hash. | +| `--conversationId` | string | Alias of --conversation. | +| `--surface` | string | Calling client surface recorded on the row. | +| `--protocol` | string | Inbound wire: responses, chat or messages. | +| `--api-key-id` | string | Exact management key id recorded on the row. | +| `--profile` | string | Routing profile id. | +| `--fallback` | string | true selects rows that failed over; false selects rows that did not. | +| `--from` | string | Inclusive start as epoch milliseconds or ISO datetime with timezone. | +| `--to` | string | Inclusive end as epoch milliseconds or ISO datetime with timezone. | +| `--cursor` | string | Opaque nextCursor from a previous page. | +| `--limit` | number | 1-100 rows; default 50. | +| `--json` | boolean | Emit the management payload, including hasMore, nextCursor and index. | +| `--jsonl` | boolean | Matching rows only; hasMore and nextCursor go to stderr. | + +JSON mode: `payload`. + +- Pages the derived request-history index, not the recent /api/logs ring. Empty matches succeed. Also accepted after observe logs. +- JSON is the management payload. JSONL emits entries only; resume with --cursor from stderr when hasMore is true. + +### `ocx logs get` + +Usage: `ocx logs get [--json]` + +Read one canonical request-history row by request ID. + +State-changing: no. + +| Method | Route | +|---|---| +| GET | `/api/request-history/{id}` | + +| Flag | Value | Meaning | +|---|---|---| +| `--json` | boolean | Emit the canonical row as JSON. | + +JSON mode: `payload`. + +- The request ID is URI-encoded. This is the stored row, not the route-decision view from logs explain. A missing id is a 404. Also accepted after observe logs. + ### `ocx logs explain` Usage: `ocx logs explain [--json]` diff --git a/skills/ocx/references/02_json_shapes.md b/skills/ocx/references/02_json_shapes.md index 0a36442ff36..f8fcbb35037 100644 --- a/skills/ocx/references/02_json_shapes.md +++ b/skills/ocx/references/02_json_shapes.md @@ -40,7 +40,7 @@ One row per line. The fields worth branching on: | Field | Meaning | |---|---| -| `requestId` | pass to `ocx logs explain` | +| `requestId` | pass to `ocx logs get` or `ocx logs explain` | | `conversationId` | groups a conversation; also printed as `conv=` in human output | | `accountLogLabel` | which account served it (`main`, `p`, `o`); also printed as `acct=