@animalabs/connectome-host 0.5.0 → 0.5.2

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 ## Unreleased
 
+## 0.5.2 — 2026-07-26
+
+### Fixed
+
+- **Settings preview reported unreachable budgets as fitting.** context-manager's
+  `PreviewResult.budgetTokens` is the *rejection* budget —
+  `(requested - reserve) * (1 + overBudgetGraceRatio)` — and its `fits` means
+  "would not throw `OverBudgetError`", not "fits the budget you asked for". On
+  Mythos (`overBudgetGraceRatio: 0.35`) those differ by a third: previewing
+  250k reported `fits: true` at 273,828 tokens, a budget the picker had in fact
+  exhausted trying to reach. The endpoint now returns an `accounting` block
+  separating `fitsRequested` / `withinGrace` / `unreachable`, and the panel
+  renders three distinct verdicts (fits / over-requested-but-graced /
+  would-hard-fail) plus the full budget derivation.
+
+## 0.5.1
+
+### Added
+
+- **llm-calls logging for every provider**: `LoggingProviderAdapter`, a
+  provider-agnostic decorator over any `ProviderAdapter`, wraps the
+  openai-codex, openrouter, and openai-responses transports — which
+  previously had NO wire visibility (found post-deploy on Mica: zero
+  llm-calls files, requests undiagnosable). Full raw request + response
+  summary + usage + timing + error per call, size-guarded against
+  pathological payloads. Anthropic/Bedrock keep their purpose-built
+  logging classes.
+
 ## 0.5.0 — 2026-07-26
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@animalabs/connectome-host",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "General-purpose agent TUI host with recipe-based configuration",
   "type": "module",
   "scripts": {

package/src/index.ts

@@ -25,6 +25,7 @@ import {
   OpenRouterAdapter,
 } from '@animalabs/membrane';
 import { LoggingAnthropicAdapter } from './logging-adapter.js';
+import { LoggingProviderAdapter } from './logging-provider-wrapper.js';
 import { LoggingBedrockAdapter } from './logging-bedrock-adapter.js';
 import { CodexSubscriptionAdapter } from './codex-subscription-adapter.js';
 import { CallLedger } from './call-ledger.js';
@@ -835,11 +836,22 @@ async function main() {
     ? new LoggingBedrockAdapter({}, llmLogPath)
     : undefined;
   const adapter = provider === 'openai-responses'
-    ? new OpenAIResponsesAPIAdapter({
-        apiKey: config.openaiApiKey!,
-        baseURL: process.env.OPENAI_BASE_URL || undefined,
-      })
-    : bedrockAdapter ?? openrouterAdapter ?? codexAdapter ?? new LoggingAnthropicAdapter(
+    ? new LoggingProviderAdapter(
+        new OpenAIResponsesAPIAdapter({
+          apiKey: config.openaiApiKey!,
+          baseURL: process.env.OPENAI_BASE_URL || undefined,
+        }),
+        llmLogPath,
+      )
+    // Codex/openrouter/openai adapters get the provider-agnostic logging
+    // decorator (llm-calls.jsonl); anthropic and bedrock keep their
+    // purpose-built logging classes below. The bare `codexAdapter` /
+    // `openrouterAdapter` instances stay un-wrapped for auth commands and
+    // dispose() — only the membrane sees the wrapper.
+    : bedrockAdapter
+      ?? (openrouterAdapter ? new LoggingProviderAdapter(openrouterAdapter, llmLogPath) : undefined)
+      ?? (codexAdapter ? new LoggingProviderAdapter(codexAdapter, llmLogPath) : undefined)
+      ?? new LoggingAnthropicAdapter(
         {
           // Anthropic OAuth wins over API-key auth when both are present.
           // Subscription tokens additionally require this beta header.

package/src/logging-provider-wrapper.ts

@@ -0,0 +1,165 @@
+// Provider-agnostic ProviderAdapter decorator that appends each LLM call's
+// request, response, usage, timing, and any error to the same
+// `llm-calls.<iso>.jsonl` file the Anthropic and Bedrock paths use.
+//
+// Exists because llm-call logging grew adapter-by-adapter (Anthropic subclass,
+// Bedrock wrapper) and the remaining providers — openai-codex (Mica),
+// openrouter (K3) — had NO wire visibility at all: a post-deploy "did her
+// requests actually work?" check on Mica (2026-07-26) found zero llm-calls
+// files because the codex path never logged. This decorator wraps ANY
+// ProviderAdapter, so a new provider gets logging by construction rather than
+// by remembering to build a logging twin.
+//
+// Contents: full raw request and a summarized-but-complete response record
+// (stop reason, usage, per-block shape, full text) on every call, plus the
+// raw provider response. Retention/rotation/S3 shipping is the host box's
+// llm-logs sync job's problem — this file just writes lines.
+//
+// OOM note (learned on the Anthropic path, which once logged raw+normalized+
+// summary and contributed to production OOMs): we serialize the record ONCE,
+// and a size guard drops the raw bodies for pathological payloads (giant
+// image batches) rather than buffering multi-hundred-MB lines.
+//
+// Decorator safety: adapters whose complete() internally delegates to their
+// own stream() (codex does) self-call the INNER method, not the wrapper —
+// each membrane-level call logs exactly once.
+//
+// Each line: { type: 'call'|'error', provider, kind: 'complete'|'stream',
+//   timestamp, durationMs, requestSummary, response?, rawRequest?,
+//   rawResponse?, error?, truncated? }
+
+import type {
+  ProviderAdapter,
+  ProviderRequest,
+  ProviderResponse,
+  ProviderRequestOptions,
+  StreamCallbacks,
+} from '@animalabs/membrane';
+import { appendFileSync } from 'node:fs';
+
+/** Above this many serialized bytes, drop raw bodies and keep summaries. */
+const MAX_RECORD_BYTES = 16 * 1024 * 1024;
+
+function summarizeRequest(request: ProviderRequest): Record<string, unknown> {
+  const msgs = (request.messages ?? []) as Array<{ role?: string; content?: unknown }>;
+  const last = msgs[msgs.length - 1];
+  const lastPreview = typeof last?.content === 'string'
+    ? last.content.slice(0, 200)
+    : Array.isArray(last?.content)
+      ? (last.content as Array<{ type?: string; text?: string }>)
+          .map((b) => (b.type === 'text' ? (b.text ?? '').slice(0, 120) : `[${b.type}]`))
+          .join(' | ').slice(0, 300)
+      : undefined;
+  return {
+    model: request.model,
+    maxTokens: request.maxTokens,
+    messageCount: msgs.length,
+    systemChars: typeof request.system === 'string'
+      ? request.system.length
+      : Array.isArray(request.system)
+        ? JSON.stringify(request.system).length
+        : 0,
+    toolNames: (request.tools as Array<{ name?: string }> | undefined)?.map((t) => t.name) ?? null,
+    toolCount: (request.tools as unknown[] | undefined)?.length ?? 0,
+    lastMessageRole: last?.role,
+    lastMessagePreview: lastPreview,
+  };
+}
+
+function summarizeResponse(response: ProviderResponse): Record<string, unknown> {
+  const content = (response.content ?? []) as Array<{ type?: string; text?: string; name?: string }>;
+  return {
+    stopReason: response.stopReason
+      ?? (response.raw as { stop_reason?: string } | undefined)?.stop_reason
+      ?? null,
+    usage: response.usage ?? null,
+    blocks: content.map((b) => ({
+      type: b.type,
+      ...(b.type === 'text' ? { chars: (b.text ?? '').length, text: b.text } : {}),
+      ...(b.type === 'tool_use' ? { name: b.name } : {}),
+    })),
+  };
+}
+
+export class LoggingProviderAdapter implements ProviderAdapter {
+  readonly name: string;
+
+  constructor(
+    private readonly inner: ProviderAdapter,
+    private readonly logPath: string,
+  ) {
+    this.name = inner.name;
+  }
+
+  supportsModel(modelId: string): boolean {
+    return this.inner.supportsModel(modelId);
+  }
+
+  private log(record: Record<string, unknown>): void {
+    try {
+      let line = JSON.stringify(record);
+      if (line.length > MAX_RECORD_BYTES) {
+        const { rawRequest: _rq, rawResponse: _rr, ...rest } = record;
+        line = JSON.stringify({ ...rest, truncated: 'raw bodies dropped (record exceeded size guard)' });
+      }
+      appendFileSync(this.logPath, line + '\n');
+    } catch {
+      // Logging must never break inference.
+    }
+  }
+
+  private record(
+    kind: 'complete' | 'stream',
+    request: ProviderRequest,
+    started: number,
+    response?: ProviderResponse,
+    error?: unknown,
+  ): void {
+    this.log({
+      type: error === undefined ? 'call' : 'error',
+      provider: this.name,
+      kind,
+      timestamp: new Date(started).toISOString(),
+      durationMs: Date.now() - started,
+      requestSummary: summarizeRequest(request),
+      rawRequest: request,
+      ...(response !== undefined
+        ? { response: summarizeResponse(response), rawResponse: response.raw ?? null }
+        : {}),
+      ...(error !== undefined
+        ? { error: error instanceof Error ? `${error.name}: ${error.message}` : String(error) }
+        : {}),
+    });
+  }
+
+  async complete(
+    request: ProviderRequest,
+    options?: ProviderRequestOptions,
+  ): Promise<ProviderResponse> {
+    const started = Date.now();
+    try {
+      const response = await this.inner.complete(request, options);
+      this.record('complete', request, started, response);
+      return response;
+    } catch (error) {
+      this.record('complete', request, started, undefined, error);
+      throw error;
+    }
+  }
+
+  async stream(
+    request: ProviderRequest,
+    callbacks: StreamCallbacks,
+    options?: ProviderRequestOptions,
+  ): Promise<ProviderResponse> {
+    const started = Date.now();
+    try {
+      const response = await this.inner.stream(request, callbacks, options);
+      this.record('stream', request, started, response);
+      return response;
+    } catch (error) {
+      this.record('stream', request, started, undefined, error);
+      throw error;
+    }
+  }
+}

package/src/modules/web-ui-module.ts

@@ -1249,7 +1249,43 @@ export class WebUiModule implements Module {
           { status: 501 },
         );
       }
-      return Response.json({ agent: agentName, budget, ...(overrides as object), preview: result });
+      // Honest budget accounting. context-manager's `budgetTokens` is the
+      // REJECTION budget: (requested - reserve) * (1 + overBudgetGraceRatio),
+      // i.e. the threshold above which a compile throws. Its `fits` therefore
+      // means "would not hard-fail", NOT "fits the budget you asked for".
+      //
+      // On a recipe with overBudgetGraceRatio 0.35 those differ by a third, so
+      // reporting cm's `fits` verbatim told operators that a budget they
+      // cannot actually reach was fine. Split the two questions apart and let
+      // the panel say which one it means.
+      const r = result as { finalTokens?: number; budgetTokens?: number; exhausted?: boolean };
+      const reserve = app.recipe.agent.maxTokens ?? 16_384;
+      const effectiveBudget = Math.max(0, budget - reserve);
+      const finalTokens = typeof r.finalTokens === 'number' ? r.finalTokens : NaN;
+      const fitsRequested = Number.isFinite(finalTokens) && finalTokens <= effectiveBudget;
+      const withinGrace = Number.isFinite(finalTokens) && typeof r.budgetTokens === 'number'
+        ? finalTokens <= r.budgetTokens
+        : undefined;
+      return Response.json({
+        agent: agentName,
+        budget,
+        ...(overrides as object),
+        accounting: {
+          requestedBudgetTokens: budget,
+          reserveForResponseTokens: reserve,
+          /** What the picker actually targets. */
+          effectiveBudgetTokens: effectiveBudget,
+          /** Hard-fail ceiling — requested minus reserve, plus grace. */
+          rejectionBudgetTokens: r.budgetTokens,
+          /** Fits the budget the operator asked for. */
+          fitsRequested,
+          /** Merely tolerated by the grace margin — over budget, but no throw. */
+          withinGrace,
+          /** Exhausted AND over the request => this budget is UNREACHABLE. */
+          unreachable: r.exhausted === true && !fitsRequested,
+        },
+        preview: result,
+      });
     } catch (err) {
       return Response.json(
         { error: err instanceof Error ? err.message : String(err) },

package/web/src/Settings.tsx

@@ -36,6 +36,24 @@ export interface SettingsState {
   previewAvailable: boolean;
 }
 
+/**
+ * Honest budget accounting from the server.
+ *
+ * `preview.fits` from context-manager means "would not throw OverBudgetError",
+ * which on a recipe with a grace ratio is NOT the same as "fits the budget you
+ * typed". These three flags keep the questions separate.
+ */
+interface PreviewAccounting {
+  requestedBudgetTokens: number;
+  reserveForResponseTokens: number;
+  effectiveBudgetTokens: number;
+  rejectionBudgetTokens?: number;
+  fitsRequested: boolean;
+  withinGrace?: boolean;
+  /** Picker exhausted AND still over the request — this budget cannot be reached. */
+  unreachable: boolean;
+}
+
 interface PreviewResult {
   finalTokens: number;
   budgetTokens: number;
@@ -91,6 +109,7 @@ export function SettingsPanel(props: {
   const [notify, setNotify] = createSignal(false);
 
   const [preview, setPreview] = createSignal<PreviewResult | null>(null);
+  const [acct, setAcct] = createSignal<PreviewAccounting | null>(null);
   const [previewErr, setPreviewErr] = createSignal<string | null>(null);
   const [previewing, setPreviewing] = createSignal(false);
 
@@ -133,12 +152,15 @@ export function SettingsPanel(props: {
         const body = await res.json();
         if (!res.ok) {
           setPreview(null);
+          setAcct(null);
           setPreviewErr(body?.error ?? `HTTP ${res.status}`);
           return;
         }
         setPreview(body.preview as PreviewResult);
+        setAcct((body.accounting ?? null) as PreviewAccounting | null);
       } catch (e) {
         setPreview(null);
+        setAcct(null);
         setPreviewErr(e instanceof Error ? e.message : String(e));
       } finally {
         setPreviewing(false);
@@ -357,20 +379,45 @@ export function SettingsPanel(props: {
           <Show when={preview()}>
             {(p) => (
               <div>
+                {/* Three distinct verdicts. Collapsing "fits your budget" into
+                    "wouldn't throw" is how a 35%-grace recipe reports an
+                    unreachable budget as fine — so they are kept apart. */}
                 <div
                   class={`px-2 py-1 rounded mb-1.5 text-[11px] border ${
-                    p().fits
+                    acct()?.fitsRequested
                       ? 'bg-emerald-950/40 border-emerald-800 text-emerald-300'
-                      : 'bg-red-950/40 border-red-800 text-red-300'
+                      : acct()?.withinGrace
+                        ? 'bg-amber-950/40 border-amber-800 text-amber-200'
+                        : 'bg-red-950/40 border-red-800 text-red-300'
                   }`}
                 >
-                  {p().fits
-                    ? `fits — ${p().finalTokens.toLocaleString()} of ${p().budgetTokens.toLocaleString()} tok`
-                    : `DOES NOT FIT — ${p().finalTokens.toLocaleString()} tok vs ${p().budgetTokens.toLocaleString()} budget`}
-                  <Show when={!p().fits && p().exhausted}>
+                  <Show when={acct()?.fitsRequested}>
+                    <div>
+                      fits — {p().finalTokens.toLocaleString()} of{' '}
+                      {acct()!.effectiveBudgetTokens.toLocaleString()} usable tok
+                    </div>
+                  </Show>
+                  <Show when={!acct()?.fitsRequested && acct()?.withinGrace}>
+                    <div>
+                      OVER REQUESTED BUDGET — {p().finalTokens.toLocaleString()} tok vs{' '}
+                      {acct()!.effectiveBudgetTokens.toLocaleString()} usable
+                    </div>
+                    <div class="text-[10px] opacity-90 mt-0.5">
+                      it would not hard-fail, but only because the grace margin absorbs the
+                      overshoot (ceiling {acct()!.rejectionBudgetTokens?.toLocaleString()}).
+                      The context would run above your target indefinitely.
+                    </div>
+                  </Show>
+                  <Show when={acct() && !acct()!.fitsRequested && acct()!.withinGrace === false}>
+                    <div>
+                      WOULD HARD-FAIL — {p().finalTokens.toLocaleString()} tok exceeds even the
+                      grace ceiling {acct()!.rejectionBudgetTokens?.toLocaleString()}
+                    </div>
+                  </Show>
+                  <Show when={acct()?.unreachable}>
                     <div class="text-[10px] opacity-90 mt-0.5">
-                      picker exhausted: nothing further can be folded. Applying this would
-                      hard-fail the compile.
+                      <b>unreachable:</b> the picker exhausted — nothing further can be folded,
+                      so this budget cannot be reached no matter how long you wait.
                     </div>
                   </Show>
                 </div>
@@ -378,6 +425,10 @@ export function SettingsPanel(props: {
                 <table class="w-full font-mono text-[10px]">
                   <tbody>
                     <For each={[
+                      ['requested budget', acct()?.requestedBudgetTokens],
+                      ['− reserve for response', acct()?.reserveForResponseTokens],
+                      ['= usable for context', acct()?.effectiveBudgetTokens],
+                      ['grace ceiling (hard fail above)', acct()?.rejectionBudgetTokens],
                       ['head (verbatim)', p().headTokens],
                       ['tail (verbatim)', p().tailTokens],
                       ['middle (foldable)', p().middleTokens],
@@ -389,7 +440,11 @@ export function SettingsPanel(props: {
                         <tr>
                           <td class="text-neutral-500 pr-2">{k}</td>
                           <td class="text-neutral-300 text-right tabular-nums">
-                            {typeof v === 'number' ? v.toLocaleString() : String(v)}
+                            {typeof v === 'number'
+                              ? v.toLocaleString()
+                              : v === undefined || v === null
+                                ? '–'
+                                : String(v)}
                           </td>
                         </tr>
                       )}