[stack 7/8] feat(trace): cover Responses WebSocket turns

docs-site/src/content/docs/reference/cli.md

@@ -511,6 +511,54 @@ With no scope, `ocx debug` prints usage and, when the proxy is stopped, the next
 defaults. Provider debug defaults from `OCX_DEBUG=1` (legacy `OCX_DEBUG_FRAMES=1` also works); usage
 debug defaults from `OPENCODEX_USAGE_DEBUG=1`.
 
+## Request traces
+
+`usage.jsonl` stays a compact telemetry log. Full prompts and responses go to a separate local store,
+`trace.sqlite` in the opencodex config directory, linked to usage rows by `traceId` (the request id).
+Tracing is **off by default** and is configured by environment variable at proxy start:
+
+| Variable                   | Default  | Meaning                                                                 |
+| -------------------------- | -------- | ----------------------------------------------------------------------- |
+| `OCX_TRACE`                | `off`    | `off`, `metadata`, `redacted`, or `full`.                               |
+| `OCX_TRACE_TTL_HOURS`      | `24`     | Retention for stored traces (1–720).                                    |
+| `OCX_TRACE_MAX_BODY_BYTES` | `524288` | Cap per stored body. Hashes and byte counts always cover the full body. |
+| `OCX_TRACE_MAX_DB_MB`      | `256`    | Total store cap; oldest traces are evicted first.                       |
+| `OCX_TRACE_SAMPLE`         | `1`      | Fraction of requests whose bodies are stored in `redacted`/`full` mode. |
+
+- `metadata` stores nothing but adds a payload-free `trace` object to each usage row: byte sizes,
+  message/tool-call/attachment counts, request/outbound/response hashes, and `systemHash`, `toolsHash`
+  and `prefixHash` of the final provider wire body. Comparing these between two turns of one conversation
+  shows which section broke a provider prompt-cache prefix.
+- `redacted` also stores the inbound request, the final provider body, and the response, with credentials
+  and token-shaped values removed. Free-text secrets in prompts that do not match a known pattern are not
+  detectable, so treat the store as sensitive.
+- `full` stores bodies verbatim. Use it deliberately and briefly.
+
+Outbound capture covers adapters that send through the shared upstream fetch helper; inbound and response
+capture covers `/v1/responses`, `/v1/messages`, `/v1/chat/completions`, and `/v1/responses/compact`.
+Responses WebSocket `response.create` turns are traced as separate logical requests: the inbound hash covers
+the client WS frame, while the outbound hash covers the final provider wire body.
+Proxy response-cache hits are traced without duplicating the cached response body: the usage trace records
+`cacheHit`, a response hash/byte count, and the request id that originally populated the cache when known.
+Voice/realtime live-sideband WebSockets remain outside this trace lane because they are long-lived
+bidirectional sessions rather than request/response turns.
+
+Stored traces can be inspected directly from the local SQLite store; the proxy does not need to be running:
+
+```bash
+ocx trace list
+ocx trace list --conversation <conversation-id> --limit 20
+ocx trace show <trace-id>
+ocx trace show <trace-id> --json
+ocx trace show <trace-id> --body
+```
+
+`trace list` and `trace show` are payload-free by default. `--json` changes only the output format and
+does **not** reveal request or response bodies. Bodies are included only when `--body` is explicitly
+provided. Human `--body` output JSON-escapes stored strings so terminal control sequences from traced
+content are not executed. Metadata-only trace summaries remain in `usage.jsonl`; `ocx trace list`
+enumerates rows whose bodies were actually persisted in `trace.sqlite`.
+
 ## Updating
 
 ### `ocx update`

gui/src/styles-models-workspace.css

@@ -6,7 +6,7 @@
    ============================================================================ */
 
 .main-inner:has(.models-workspace-shell) {
-  max-width: 1200px;
+  max-width: var(--workspace-measure);
 }
 
 .models-workspace-shell {
@@ -30,7 +30,7 @@
 .models-workspace-main {
   display: flex;
   flex-direction: column;
-  gap: var(--space-3);
+  gap: var(--space-5);
   min-width: 0;
 }
 
@@ -141,16 +141,22 @@
 .models-provider-list {
   display: flex;
   flex-direction: column;
-  gap: var(--space-2);
+  gap: 0;
+  border-top: 1px solid var(--border-subtle);
 }
 
 .models-provider-card {
   margin-bottom: 0;
   overflow: hidden;
+  border: 0;
+  border-bottom: 1px solid var(--border-subtle);
+  border-radius: 0;
+  background: transparent;
+  box-shadow: none;
 }
 
 .models-provider-body {
-  padding: var(--space-3) var(--space-4);
+  padding: 0 0 var(--space-4);
 }
 
 .models-provider-body > .input {

gui/src/styles/model-catalog.css

@@ -1,6 +1,6 @@
 .models-workspace-root {
-  grid-template-columns: minmax(0, 1fr) clamp(320px, 24vw, 400px);
-  gap: 32px;
+  grid-template-columns: minmax(0, 1fr) clamp(340px, 25vw, 420px);
+  gap: var(--space-8);
   align-items: start;
   min-height: max(400px, calc(100dvh - 330px));
 }
@@ -36,8 +36,12 @@
 .models-catalog-toolbar {
   display: flex;
   align-items: center;
-  gap: 12px;
-  margin: 24px 0 20px;
+  gap: var(--space-3);
+  margin: var(--space-6) 0 var(--space-4);
+  padding: var(--space-3);
+  background: var(--surface-paper);
+  border: 1px solid var(--border-subtle);
+  border-radius: var(--radius-lg);
 }
 .models-search-field {
   flex: 1;
@@ -66,11 +70,11 @@
 .models-catalog-columns {
   display: grid;
   grid-template-columns: minmax(0, 1fr) 140px 84px 88px;
-  gap: 12px;
+  gap: var(--space-3);
   color: var(--muted);
   font-size: var(--text-caption);
-  padding: 0 12px 12px;
-  border-bottom: 1px solid var(--border-soft);
+  padding: 0 var(--space-3) var(--space-2);
+  border-bottom: 1px solid var(--border-subtle);
 }
 .models-catalog-columns > :last-child {
   text-align: right;
@@ -79,14 +83,14 @@
   gap: 0;
 }
 .models-provider-list {
-  gap: 12px;
+  gap: 0;
 }
 .models-provider-card {
   overflow: visible;
 }
 .models-provider-card .models-provider-head {
-  min-height: 48px;
-  padding: 0 10px;
+  min-height: var(--control-touch);
+  padding: var(--space-2) var(--space-2);
   border: 0;
   background: transparent;
   align-items: center;
@@ -135,31 +139,26 @@
   display: flex;
   align-items: center;
   position: relative;
-  gap: 16px;
-  padding: 0 12px 0 0;
-  border-radius: 6px;
+  gap: var(--space-4);
+  padding: 0 var(--space-3) 0 0;
+  border-bottom: 1px solid var(--border-subtle);
+  border-radius: 0;
   min-height: 56px;
 }
 .models-catalog-row + .models-catalog-row {
-  margin-top: 2px;
+  margin-top: 0;
 }
 @media (hover: hover) and (pointer: fine) {
   .models-catalog-row:hover {
     background: var(--hover);
   }
 }
 .models-catalog-row.is-selected {
-  background: var(--raised);
+  background: var(--surface-raised);
+  box-shadow: inset 2px 0 0 var(--text-primary);
 }
 .models-catalog-row.is-selected::before {
-  content: "";
-  position: absolute;
-  left: 0;
-  top: 12px;
-  bottom: 12px;
-  width: 2px;
-  background: var(--text);
-  border-radius: 2px;
+  content: none;
 }
 .models-workspace-shell .switch {
   position: relative;
@@ -257,23 +256,24 @@
 }
 .model-inspector {
   position: sticky;
-  top: calc(var(--workspace-header) + 24px);
+  top: calc(var(--workspace-header) + var(--space-6));
   align-self: start;
   min-width: 0;
-  border-radius: 0;
-  border-left: 1px solid var(--border-soft);
-  background: transparent;
-  padding: 0 0 24px 28px;
+  padding: var(--space-6);
+  background: var(--surface-paper);
+  border: 1px solid var(--border-subtle);
+  border-radius: var(--radius-lg);
+  box-shadow: none;
 }
 .model-inspector-empty {
   min-height: 220px;
 }
 .model-inspector h3 {
   margin: 0;
-  font-size: 24px;
-  font-weight: 650;
-  line-height: 1.35;
-  letter-spacing: -0.025em;
+  font-size: clamp(1.45rem, 2vw, 1.9rem);
+  font-weight: var(--weight-semibold);
+  line-height: 1.08;
+  letter-spacing: -0.03em;
   overflow-wrap: anywhere;
 }
 .model-inspector-empty p,
@@ -343,10 +343,10 @@
 .model-inspector-identifier {
   position: relative;
   overflow: hidden;
-  background: var(--rail);
-  border: 1px solid var(--border-soft);
-  border-radius: 8px;
-  padding: 4px 12px 12px;
+  background: var(--surface-raised);
+  border: 1px solid var(--border-subtle);
+  border-radius: var(--radius-lg);
+  padding: var(--space-2) var(--space-3) var(--space-3);
 }
 .model-inspector-identifier::after {
   content: "";
@@ -408,8 +408,8 @@
   color: var(--red);
 }
 .models-advanced {
-  border-top: 1px solid var(--border-soft);
-  margin-top: 24px;
+  border-top: 1px solid var(--border-subtle);
+  margin-top: var(--space-6);
 }
 .models-advanced
   > [data-slot="accordion-item"]

gui/src/styles/ocx-system.css

@@ -6,13 +6,23 @@
 
 :root,
 :root[data-style] {
-  --workspace-measure: 1400px;
-  --page-gutter: clamp(var(--space-4), 3vw, var(--space-12));
-  --section-gap: var(--space-6);
-  --card-radius: var(--radius-group);
-  --card-border: var(--border-soft);
+  /* Auth-inspired semantic aliases. The underlying Signaal palette stays canonical. */
+  --surface-canvas: var(--bg);
+  --surface-paper: var(--surface);
+  --surface-raised: var(--raised);
+  --text-primary: var(--text);
+  --text-secondary: var(--muted);
+  --border-subtle: var(--border-soft);
+  --interactive-accent: var(--accent-blue);
+
+  --workspace-measure: 1480px;
+  --page-gutter: clamp(var(--space-4), 3.5vw, var(--space-12));
+  --section-gap: var(--space-8);
+  --card-radius: var(--radius-lg);
+  --card-border: var(--border-subtle);
   --card-shadow: none;
-  --card-shadow-raised: none;
+  --card-shadow-raised: 0 12px 34px
+    color-mix(in srgb, var(--text) 7%, transparent);
   --focus-ring: 0 0 0 3px var(--accent-soft);
 
   --ease-out: cubic-bezier(0.22, 1, 0.36, 1);
@@ -32,8 +42,8 @@
   position: sticky;
   top: 0;
   z-index: var(--z-sticky);
-  background: color-mix(in srgb, var(--surface) 96%, transparent);
-  border-bottom: 1px solid var(--border-soft);
+  background: var(--surface-paper);
+  border-bottom: 1px solid var(--border-subtle);
 }
 .ocx-workspace .brand .name {
   font-weight: var(--weight-semibold);
@@ -168,8 +178,9 @@
    --------------------------------------------------------------------------- */
 .ocx-workspace .page-head {
   align-items: flex-start;
-  gap: 24px;
-  margin-bottom: 24px;
+  gap: var(--space-8);
+  margin-bottom: var(--space-8);
+  padding-top: var(--space-2);
 }
 .ocx-workspace .page-head > div:first-child {
   min-width: 0;
@@ -178,18 +189,20 @@
   gap: 6px;
 }
 .ocx-workspace .page-head h2 {
-  font-size: var(--text-title);
+  max-width: 18ch;
+  font-size: clamp(1.9rem, 3vw, 2.8rem);
   font-weight: var(--weight-semibold);
-  letter-spacing: var(--tracking-tight);
-  line-height: var(--leading-tight);
+  letter-spacing: -0.035em;
+  line-height: 1.02;
+  text-wrap: balance;
 }
 .ocx-workspace .page-head p,
 .ocx-workspace .page-head .page-sub {
   margin: 0;
-  color: var(--muted);
-  font-size: var(--text-control);
-  line-height: var(--leading-body);
-  max-width: 64ch;
+  color: var(--text-secondary);
+  font-size: 0.95rem;
+  line-height: 1.6;
+  max-width: 62ch;
 }
 .ocx-workspace .page-head-actions {
   flex-shrink: 0;
@@ -254,6 +267,7 @@
    --------------------------------------------------------------------------- */
 .ocx-workspace .panel,
 .ocx-workspace .card {
+  background: var(--surface-paper);
   border-color: var(--card-border);
   border-radius: var(--card-radius);
   box-shadow: var(--card-shadow);