@ai-matrx/chat 0.7.9 → 0.7.11

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @ai-matrx/chat
 
+## 0.7.11
+### continue-agent-json is exported again
+
+- **`./agents/redux/execution-system/thunks/continue-agent-json`** is back in the public surface; 0.7.9 dropped it
+  from `public-modules.json` while `matrx-frontend`'s Applet builder imports it (`continueAgentJson`).
+- **Consumer action:** none.
+
+## 0.7.10
+### a refused answer is a failed run (lane M3)
+
+- **`useHeadlessAgentJson.run`**: when `coerce` refuses the answer the model gave, the run is recorded as failed
+  (`chat.user_request` status `failed`, `error` = the reason, `metadata.output_refused`) through the guarded
+  `mergeJsonColumn` write (`recordRunOutputRefused`); a write that does not land is a `console.error`. Before, the run
+  stayed `completed` with `error` null forever. The error is re-thrown unchanged for the surface to say plainly.
+- **Consumer action:** none.
+
 ## 0.7.9
 
 Automatic changed-only republish (docs/metadata drift since the last tag — see
@@ -15,6 +31,11 @@ No source changes intended and no consumer action required.
 ## 0.7.7
 ### Unreleased
 
+- **No first-load layout shift from assistant messages** (spend register item 32): `AgentAssistantMessage` no longer swaps a fixed-height
+  skeleton for the markdown after 140 ms (measured CLS 0.48 on the run page). Persisted answers render in place on first paint.
+  `deferColdMarkdown` is removed from `AgentAssistantMessage`, `AssistantTurnGroup` and `AgentConversationDisplay` (the column keeps its
+  own history staging). **Consumer action:** none.
+
 - **`continueAgentJson`** (`agents/redux/execution-system/thunks/continue-agent-json`): the NEXT turn of a
   conversation whose first turn ran headlessly, waited on like the first (`adoptHeadlessAgentJson`). A turn is
   the person's words (`userInput`) or a turn the HOST writes (`hostTurn` — sent as `host_turn`, never

package/dist/agents/components/messages-display/AgentConversationDisplay.d.ts

@@ -8,9 +8,8 @@ interface AgentConversationDisplayProps {
      */
     surfaceKey?: string;
     compact?: boolean;
-    deferColdMarkdown?: boolean;
     fallbackVisibleGroupLimit?: number | null;
     bottomPinned?: boolean;
 }
-export declare function AgentConversationDisplay({ conversationId, surfaceKey, compact, deferColdMarkdown, fallbackVisibleGroupLimit, bottomPinned, }: AgentConversationDisplayProps): import("react").JSX.Element;
+export declare function AgentConversationDisplay({ conversationId, surfaceKey, compact, fallbackVisibleGroupLimit, bottomPinned, }: AgentConversationDisplayProps): import("react").JSX.Element;
 export {};

package/dist/agents/components/messages-display/AgentConversationDisplay.js

@@ -53,7 +53,6 @@ function AgentConversationDisplay({
   conversationId,
   surfaceKey,
   compact = false,
-  deferColdMarkdown = false,
   fallbackVisibleGroupLimit = null,
   bottomPinned = false
 }) {
@@ -262,8 +261,7 @@ function AgentConversationDisplay({
                 isStreamActive: false,
                 surfaceKey,
                 compact: true,
-                hideActionBar: true,
-                deferColdMarkdown
+                hideActionBar: true
               },
               member.messageId
             )
@@ -307,8 +305,7 @@ function AgentConversationDisplay({
               isStreamActive: group.isStreamActive,
               surfaceKey,
               compact,
-              canRetry: group.canRetry,
-              deferColdMarkdown
+              canRetry: group.canRetry
             }
           )
         },
@@ -327,8 +324,7 @@ function AgentConversationDisplay({
             conversationId,
             surfaceKey,
             compact,
-            members: group.members,
-            deferColdMarkdown
+            members: group.members
           }
         )
       },

package/dist/agents/components/messages-display/assistant/AgentAssistantMessage.d.ts

@@ -33,8 +33,6 @@ export interface AgentAssistantMessageProps {
      * button. Retry is non-destructive (the failed turn stays in history).
      */
     canRetry?: boolean;
-    /** Chat cold-load only: show a short text skeleton before DB markdown mounts. */
-    deferColdMarkdown?: boolean;
     /**
      * False for the intermediate iterations of a multi-step agentic turn. Only
      * the LAST member of a turn carries the answer, so only it may say "this run
@@ -43,4 +41,4 @@ export interface AgentAssistantMessageProps {
      */
     isTurnAnswer?: boolean;
 }
-export declare function AgentAssistantMessage({ conversationId, requestId, messageId, isStreamActive, recordMessageIds, streamSlotStart, streamSlotEnd, surfaceKey, hideActionBar, canRetry, deferColdMarkdown, isTurnAnswer, }: AgentAssistantMessageProps): import("react").JSX.Element;
+export declare function AgentAssistantMessage({ conversationId, requestId, messageId, isStreamActive, recordMessageIds, streamSlotStart, streamSlotEnd, surfaceKey, hideActionBar, canRetry, isTurnAnswer, }: AgentAssistantMessageProps): import("react").JSX.Element;

package/dist/agents/components/messages-display/assistant/AgentAssistantMessage.js

@@ -1,7 +1,6 @@
 "use client";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import {
-  startTransition,
   useCallback,
   useMemo,
   useState,
@@ -117,7 +116,6 @@ function AgentAssistantMessage({
   surfaceKey,
   hideActionBar = false,
   canRetry = false,
-  deferColdMarkdown = false,
   isTurnAnswer = true
 }) {
   useDebugContext("AgentAssistantMessage");
@@ -137,17 +135,7 @@ function AgentAssistantMessage({
   }, [surfaceKey, conversationId, messageId, requestId, isStreamActive]);
   const dispatch = useAppDispatch();
   const [retrying, setRetrying] = useState(false);
-  const shouldDeferColdMarkdown = deferColdMarkdown && !requestId && !!messageId && !isStreamActive;
-  const [coldMarkdownSettledMessageId, setColdMarkdownSettledMessageId] = useState(null);
-  const coldMarkdownReady = !shouldDeferColdMarkdown || coldMarkdownSettledMessageId === messageId;
   const [providerRetryBusyAction, setProviderRetryBusyAction] = useState(null);
-  useEffect(() => {
-    if (!shouldDeferColdMarkdown || !messageId) return void 0;
-    const timer = window.setTimeout(() => {
-      startTransition(() => setColdMarkdownSettledMessageId(messageId));
-    }, 140);
-    return () => window.clearTimeout(timer);
-  }, [shouldDeferColdMarkdown, messageId]);
   const { captureRef, isCapturing, captureAsPDF } = useDomCapturePrint();
   const handleFullPrint = useCallback(() => {
     captureAsPDF({
@@ -308,7 +296,6 @@ function AgentAssistantMessage({
       rowParts: extractContentBlocks(record)
     }),
     failed,
-    coldMarkdownReady,
     messageId,
     renderedText,
     attachmentCount: attachmentParts.length,
@@ -394,7 +381,7 @@ function AgentAssistantMessage({
       "data-message-id": messageId ?? void 0,
       className: "group/assistant-msg rounded transition-shadow",
       children: [
-        !coldMarkdownReady ? /* @__PURE__ */ jsx(AssistantMarkdownSkeleton, {}) : bufferStream && isStreamActive && !failed ? /* @__PURE__ */ jsxs(Fragment, { children: [
+        bufferStream && isStreamActive && !failed ? /* @__PURE__ */ jsxs(Fragment, { children: [
           showProviderRetry && providerRetry && /* @__PURE__ */ jsx(
             ProviderRetryCard,
             {
@@ -538,15 +525,6 @@ function readErrorDoor(details) {
   const { label, href } = door;
   return typeof label === "string" && typeof href === "string" && href.startsWith("/") ? { label, href } : null;
 }
-function AssistantMarkdownSkeleton() {
-  return /* @__PURE__ */ jsxs("div", { className: "space-y-2 py-1", "aria-hidden": true, children: [
-    /* @__PURE__ */ jsx("div", { className: "h-3.5 w-[96%] animate-pulse rounded bg-muted/55" }),
-    /* @__PURE__ */ jsx("div", { className: "h-3.5 w-[88%] animate-pulse rounded bg-muted/50" }),
-    /* @__PURE__ */ jsx("div", { className: "h-3.5 w-[72%] animate-pulse rounded bg-muted/45" }),
-    /* @__PURE__ */ jsx("div", { className: "h-3.5 w-[94%] animate-pulse rounded bg-muted/40" }),
-    /* @__PURE__ */ jsx("div", { className: "h-3.5 w-[42%] animate-pulse rounded bg-muted/35" })
-  ] });
-}
 export {
   AgentAssistantMessage
 };

package/dist/agents/components/messages-display/assistant/AssistantTurnGroup.d.ts

@@ -16,7 +16,6 @@ interface AssistantTurnGroupProps {
     compact?: boolean;
     /** Every assistant member of this logical turn, in transcript order. */
     members: AssistantTurnGroupMember[];
-    deferColdMarkdown?: boolean;
 }
-export declare function AssistantTurnGroup({ conversationId, surfaceKey, compact, members: rawMembers, deferColdMarkdown, }: AssistantTurnGroupProps): import("react").JSX.Element;
+export declare function AssistantTurnGroup({ conversationId, surfaceKey, compact, members: rawMembers, }: AssistantTurnGroupProps): import("react").JSX.Element;
 export {};

package/dist/agents/components/messages-display/assistant/AssistantTurnGroup.js

@@ -26,8 +26,7 @@ function AssistantTurnGroup({
   conversationId,
   surfaceKey,
   compact = false,
-  members: rawMembers,
-  deferColdMarkdown = false
+  members: rawMembers
 }) {
   const { captureRef, isCapturing, captureAsPDF } = useDomCapturePrint();
   const persistedView = useAppSelector(
@@ -96,8 +95,7 @@ function AssistantTurnGroup({
                 surfaceKey,
                 compact,
                 hideActionBar: true,
-                isTurnAnswer: idx === members.length - 1 && m.streamSlotEnd === void 0,
-                deferColdMarkdown: deferColdMarkdown && idx < members.length - 1
+                isTurnAnswer: idx === members.length - 1 && m.streamSlotEnd === void 0
               }
             ) }, m.key))
           }

package/dist/agents/components/messages-display/assistant/answerless-turn.d.ts

@@ -113,8 +113,6 @@ export interface AnswerlessTurnInput {
     isStreamActive: boolean;
     /** True when the turn failed — the error path owns that case. */
     failed: boolean;
-    /** False while a cold-load skeleton stands in for the persisted markdown. */
-    coldMarkdownReady: boolean;
     /** `cx_message.id`; null/undefined until the row settles. */
     messageId: string | null | undefined;
     /** The text this turn renders (citation markers included). */

package/dist/agents/components/messages-display/assistant/answerless-turn.js

@@ -31,7 +31,6 @@ function isAnswerlessTurn(input) {
   if (input.isStreamActive) return false;
   if (input.awaitingPerson) return false;
   if (input.failed) return false;
-  if (!input.coldMarkdownReady) return false;
   if (!input.messageId) return false;
   if (input.attachmentCount > 0) return false;
   if (input.mediaBlockCount > 0) return false;

package/dist/agents/components/messages-display/user/AgentUserMessage.js

@@ -204,7 +204,9 @@ function AgentUserMessage({
     bodyBlocks,
     trimmedText
   ]);
-  const compactUserMessage = useTranscriptLayout().userMessage === "compact";
+  const userMessageLook = useTranscriptLayout().userMessage;
+  const bubbleUserMessage = userMessageLook === "bubble";
+  const compactUserMessage = userMessageLook === "compact" || bubbleUserMessage;
   const { isCollapsed, setIsCollapsed, shouldBeCollapsible, measureRef } = useCollapsibleMessageText(collapseSignature, compactUserMessage ? COMPACT_COLLAPSE_THRESHOLD_PX : void 0);
   const authoredByHost = metadata?.authored_by === "host";
   const isSuperAdmin = useAppSelector(selectIsSuperAdmin);
@@ -271,7 +273,8 @@ function AgentUserMessage({
   return /* @__PURE__ */ jsxs(
     "div",
     {
-      className: cn("group relative", containerMargin),
+      className: cn("group relative", containerMargin, bubbleUserMessage && "flex flex-col items-end"),
+      "data-user-message-look": userMessageLook,
       "data-message-id": messageId,
       onMouseEnter: () => setIsHovered(true),
       onMouseLeave: () => setIsHovered(false),
@@ -292,11 +295,14 @@ function AgentUserMessage({
         /* @__PURE__ */ jsx(
           "div",
           {
-            className: compactUserMessage ? (
+            className: bubbleUserMessage ? (
+              // The person's turn on the trailing side, in a rounded bubble as wide as its words (Messages).
+              "w-fit max-w-[80%] min-w-0 bg-muted rounded-2xl px-3.5 py-2 [&_.math-content-wrapper]:my-0 [&_p:last-child]:mb-0"
+            ) : compactUserMessage ? (
               // Tight: no inset from the left, and the markdown paragraph's own margins dropped.
               "bg-muted rounded-md px-3 py-2 [&_.math-content-wrapper]:my-0 [&_p:last-child]:mb-0"
             ) : "bg-muted border border-border rounded-lg px-2 py-2",
-            "data-user-message-style": compactUserMessage ? "compact" : "card",
+            "data-user-message-style": bubbleUserMessage ? "bubble" : compactUserMessage ? "compact" : "card",
             children: /* @__PURE__ */ jsxs("div", { className: "relative min-w-0", children: [
               /* @__PURE__ */ jsxs(
                 "div",

package/dist/agents/components/shared/AgentConversationColumn.js

@@ -299,7 +299,6 @@ function AgentConversationColumn({
                         {
                           conversationId: displayId,
                           surfaceKey,
-                          deferColdMarkdown,
                           bottomPinned: shouldPinColdScroll,
                           fallbackVisibleGroupLimit: deferColdMarkdown ? chatVisibleGroupLimit ?? CHAT_INITIAL_VISIBLE_GROUPS : null
                         }

package/dist/agents/components/shared/transcript-layout.d.ts

@@ -8,7 +8,9 @@
  *  - `width`: "reading" (the canonical `max-w-3xl` reading column) | "fill" (the host's pane).
  *  - `align`: "center" | "start" — where a reading-width column sits in a wider pane.
  *  - `userMessage`: "compact" (DEFAULT: a flat tight block; only a genuinely long message
- *    collapses) | "card" (the bordered card that collapses a long message behind a chevron).
+ *    collapses) | "card" (the bordered card that collapses a long message behind a chevron) |
+ *    "bubble" (Messages / Xcode's coding assistant: the person's turn on the trailing side in a
+ *    rounded bubble as wide as its words, answers full width; collapses like "compact").
  *  - `answerActions`: "hover" (DEFAULT: the action row is revealed on hover / keyboard focus, and
  *    always on touch — its height is reserved, so revealing it moves nothing; a finished answer ends
  *    on its last word) | "latest" (the latest answer's row is always visible, older ones on hover) |
@@ -18,7 +20,7 @@ import { type ReactNode } from "react";
 export interface TranscriptLayout {
     width?: "reading" | "fill";
     align?: "center" | "start";
-    userMessage?: "card" | "compact";
+    userMessage?: "card" | "compact" | "bubble";
     answerActions?: "shown" | "latest" | "hover";
 }
 export declare const DEFAULT_TRANSCRIPT_LAYOUT: Required<TranscriptLayout>;

package/dist/agents/hooks/useHeadlessAgentJson.js

@@ -3,6 +3,7 @@ import { useCallback, useState } from "react";
 import { useAppDispatch, useAppSelector, useAppStore } from "../../store/hooks.js";
 import { selectConversationRequestIds } from "../redux/execution-system/active-requests/active-requests.selectors.js";
 import { useRetainRequestForViewer } from "../redux/execution-system/active-requests/useRetainRequestForViewer.js";
+import { recordRunOutputRefused } from "../redux/execution-system/thunks/record-run-output-refused.js";
 import {
   runHeadlessAgentJson
 } from "../redux/execution-system/thunks/run-headless-agent-json.js";
@@ -49,7 +50,14 @@ function useHeadlessAgentJson() {
           ...result.conversationId ? { conversationId: result.conversationId } : {}
         });
       }
-      return opts.coerce ? opts.coerce(result.data, result) : result.data;
+      if (!opts.coerce) return result.data;
+      try {
+        return opts.coerce(result.data, result);
+      } catch (refused) {
+        const why = refused instanceof Error ? refused.message : String(refused);
+        if (result.requestId) void recordRunOutputRefused(result.requestId, why);
+        throw refused;
+      }
     } catch (e) {
       const message = e instanceof Error ? e.message : "Failed to run the agent";
       setError(message);

package/dist/agents/redux/execution-system/thunks/record-run-output-refused.d.ts

@@ -0,0 +1,14 @@
+/**
+ * recordRunOutputRefused — a run whose answer the BROWSER refused is a failed run.
+ *
+ * The server marks a run `completed` the moment the model stops; whether the answer was usable is only
+ * known where it is read (the feature's `coerce`, its own check). Before this, such a run stayed
+ * `completed` with `error` null forever (Make's describe box, 2026-10-09: "personal" is not one of
+ * organization, individual). The refusal is written onto the run's own `chat.user_request` row —
+ * status `failed`, `error` = the reason, and `metadata.output_refused` — through the guarded
+ * read-modify-write (`mergeJsonColumn`, a version guard, never a blind update).
+ *
+ * Never silent: a write that does not land is a `console.error` naming the run.
+ */
+export declare const OUTPUT_REFUSED_METADATA_KEY = "output_refused";
+export declare function recordRunOutputRefused(requestId: string, reason: string): Promise<boolean>;

package/dist/agents/redux/execution-system/thunks/record-run-output-refused.js

@@ -0,0 +1,24 @@
+import { mergeJsonColumn } from "@ai-matrx/data/db";
+import { supabase } from "../../../../host/db.js";
+import { hasBrowserSession } from "../../../../host/identity.js";
+const OUTPUT_REFUSED_METADATA_KEY = "output_refused";
+async function recordRunOutputRefused(requestId, reason) {
+  if (!requestId || !await hasBrowserSession()) return false;
+  const result = await mergeJsonColumn({
+    fetchCurrent: () => supabase.schema("chat").from("user_request").select("id, version, metadata").eq("id", requestId).maybeSingle(),
+    readColumn: (row) => row.metadata,
+    merge: (current) => ({ ...current, [OUTPUT_REFUSED_METADATA_KEY]: { reason, at: (/* @__PURE__ */ new Date()).toISOString() } }),
+    applyUpdate: ({ value, expectedVersion, nextVersion }) => supabase.schema("chat").from("user_request").update({ metadata: value, version: nextVersion, status: "failed", error: reason.slice(0, 500) }).eq("id", requestId).eq("version", expectedVersion).select("id, version, metadata").maybeSingle()
+  });
+  if (result.status !== "saved") {
+    console.error(
+      `[run-output-refused] Could not record the refusal on run ${requestId}: ` + (result.status === "error" ? String(result.error) : `write ${result.status}`) + `. The run still reads as completed. Reason: ${reason}`
+    );
+    return false;
+  }
+  return true;
+}
+export {
+  OUTPUT_REFUSED_METADATA_KEY,
+  recordRunOutputRefused
+};

package/dist/host/defaults/server-api.d.ts

@@ -10,7 +10,7 @@
  * values here — no admin lane, no admin door, no endpoint overrides, no local
  * engine, no browser extension (each refusal says so once).
  */
-import { applyOrganizationContextHeader, type MatrxCallError, type MatrxCallResult, type MatrxTransport, type ProviderSessionFailure, type ProviderSessionFailureVerdict } from "@ai-matrx/agents/matrx";
+import { applyOrganizationContextHeader, type MatrxCallError, type MatrxCallResult, type MatrxTransport, type ProviderSessionFailure, type ProviderSessionFailureVerdict, type ProviderSessionUsage } from "@ai-matrx/agents/matrx";
 import type { TypedStreamEvent } from "@ai-matrx/agents/generated/stream-events";
 import type { ApiPaths, ApiSchemas as Schemas, DefaultBrokeredCredential, DefaultRequestOptions, GetResult, PatchBody, PatchResult, PathWith, PostBody, PostResult } from "./typed-paths.js";
 import type { ChatIdentityPort, ChatOrgPort, ChatServerPort } from "../contract.js";
@@ -349,6 +349,7 @@ export declare function createDefaultServerApi(host: () => ServerHostView): {
         captureErrors?: boolean;
     }) => Promise<DefaultBrokeredCredential>;
     reportBrowserProviderFailure: (failure: ProviderSessionFailure) => DefaultServerThunk<Promise<ProviderSessionFailureVerdict | null>>;
+    reportBrowserProviderUsage: (usage: ProviderSessionUsage) => void;
     parseNdjsonStream: (response: Response, signal?: AbortSignal) => {
         requestId: string | null;
         conversationId: string | null;

package/dist/host/defaults/server-api.js

@@ -7,7 +7,9 @@ import {
   executeMatrxCall,
   normalizeMatrxError,
   parseMatrxNdjsonResponse,
+  createProviderUsageReporter,
   reportProviderSessionFailure,
+  reportProviderSessionUsage,
   sendMatrxRequest
 } from "@ai-matrx/agents/matrx";
 import { announceOnce } from "../errors.js";
@@ -149,6 +151,9 @@ function createDefaultServerApi(host) {
     });
   }
   const productionUrl = () => baseUrl();
+  const usageReporter = createProviderUsageReporter({
+    send: (usage) => reportProviderSessionUsage(transport({ source: "providerSessionUsage" }), usage)
+  });
   return {
     // call-api
     callApi,
@@ -234,6 +239,8 @@ function createDefaultServerApi(host) {
         return null;
       }
     },
+    // what a browser-held provider session spent: queued, retried, billed once per usage_id
+    reportBrowserProviderUsage: (usage) => usageReporter.report(usage),
     // the NDJSON stream every run reads
     // THE shared parser: a body that breaks mid-run is a TRANSPORT loss (the
     // run may still finish and is reattachable), never a failed run.

package/dist/host/server/provider-session-usage.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Server seam — what a browser-held provider session spent (`POST /broker/usage`), reported through
+ * the configured host's server client. Fire-and-forget: the host queues, retries and de-duplicates.
+ */
+export declare const reportBrowserProviderUsage: (usage: import("@ai-matrx/agents").ProviderSessionUsage) => void;

package/dist/host/server/provider-session-usage.js

@@ -0,0 +1,5 @@
+import { forwardServer } from "../server.js";
+const reportBrowserProviderUsage = forwardServer("reportBrowserProviderUsage");
+export {
+  reportBrowserProviderUsage
+};

package/dist/voice-agent/hooks/useXaiVoiceSession.js

@@ -53,6 +53,8 @@ import {
   createXaiClient
 } from "../transport/xaiClient.js";
 import { reportBrowserProviderFailure } from "../../host/server/provider-session-failure.js";
+import { reportBrowserProviderUsage } from "../../host/server/provider-session-usage.js";
+import { createXaiUsageMeter } from "../usage.js";
 import { transcriptTextFromEvent } from "../transport/serverEvents.js";
 import {
   voiceDebugLog,
@@ -103,6 +105,13 @@ function useXaiVoiceSession(opts) {
   const voiceIdRef = useRef(voiceId);
   const realtimeModelRef = useRef(realtimeModel);
   realtimeModelRef.current = realtimeModel;
+  const usageMeterRef = useRef(null);
+  if (!usageMeterRef.current) {
+    usageMeterRef.current = createXaiUsageMeter({
+      model: () => realtimeModelRef.current,
+      report: (usage) => reportBrowserProviderUsage(usage)
+    });
+  }
   const instructionsRef = useRef(instructions);
   const toolsRef = useRef(tools);
   voiceIdRef.current = voiceId;
@@ -334,6 +343,7 @@ function useXaiVoiceSession(opts) {
       switch (event.type) {
         case "session.created":
           voiceDebugLog(instanceId, "info", "ws.session.created");
+          usageMeterRef.current?.started(event.session.id);
           break;
         case "session.updated": {
           voiceDebugLog(
@@ -523,6 +533,7 @@ function useXaiVoiceSession(opts) {
           break;
         }
         case "response.done": {
+          usageMeterRef.current?.responseDone(event.response);
           runFlush();
           if (!pendingAssistantTurnIdRef.current) break;
           const playedMs = playbackRef.current?.markTurnEnded() ?? 0;
@@ -658,6 +669,7 @@ function useXaiVoiceSession(opts) {
     assistantTurnStartedAtMsRef.current = null;
     assistantAudioStartedAtMsRef.current = null;
     firstAudioReceivedRef.current = false;
+    usageMeterRef.current?.ended();
     xaiClientRef.current?.disconnect();
     clearSessionSubscriptions();
     await captureRef.current?.stop();
@@ -771,6 +783,7 @@ function useXaiVoiceSession(opts) {
     const unsubEvent = client.onEvent(handleServerEvent);
     const unsubError = client.onError(handleClientError);
     const unsubClose = client.onClose((info) => {
+      usageMeterRef.current?.ended();
       voiceDebugIncr(instanceId, "closeCount");
       voiceDebugSetFlags(instanceId, {
         lastCloseIntentional: info.intentional,

package/dist/voice-agent/usage.d.ts

@@ -0,0 +1,20 @@
+import type { ProviderSessionUsage } from "@ai-matrx/agents/matrx";
+import type { XaiResponseUsage } from "./transport/serverEvents.js";
+export interface XaiUsageMeterOptions {
+    /** The realtime model the session opened with; unresolved = nothing priceable to report. */
+    model: () => string | null | undefined;
+    report: (usage: ProviderSessionUsage) => void;
+    now?: () => number;
+}
+export interface XaiUsageMeter {
+    /** Session opened: start the clock and remember xAI's session id. */
+    started(sessionId: string | null | undefined): void;
+    /** One `response.done`: report its tokens plus the session time since the last report. */
+    responseDone(response: {
+        id: string;
+        usage?: XaiResponseUsage;
+    }): void;
+    /** Session closed (clean or dropped): report the trailing slice of session time. Idempotent. */
+    ended(): void;
+}
+export declare function createXaiUsageMeter(options: XaiUsageMeterOptions): XaiUsageMeter;

package/dist/voice-agent/usage.js

@@ -0,0 +1,50 @@
+function createXaiUsageMeter(options) {
+  const now = options.now ?? (() => Date.now());
+  let sessionId = null;
+  let sliceStartedAt = null;
+  let ordinal = 0;
+  function takeSeconds() {
+    if (sliceStartedAt === null) return 0;
+    const at = now();
+    const seconds = Math.max(0, (at - sliceStartedAt) / 1e3);
+    sliceStartedAt = at;
+    return seconds;
+  }
+  return {
+    started(id) {
+      sessionId = id?.trim() || null;
+      sliceStartedAt = now();
+      ordinal = 0;
+    },
+    responseDone(response) {
+      const model = options.model()?.trim();
+      if (!model || !response.id) return;
+      options.report({
+        provider: "xai",
+        model,
+        usage_id: response.id,
+        input_tokens: response.usage?.input_tokens,
+        output_tokens: response.usage?.output_tokens,
+        seconds: takeSeconds()
+      });
+    },
+    ended() {
+      const model = options.model()?.trim();
+      const startedAt = sliceStartedAt;
+      sliceStartedAt = null;
+      if (!model || startedAt === null) return;
+      const seconds = Math.max(0, (now() - startedAt) / 1e3);
+      if (seconds < 1) return;
+      ordinal += 1;
+      options.report({
+        provider: "xai",
+        model,
+        usage_id: `${sessionId ?? `session-${startedAt}`}:end:${ordinal}`,
+        seconds
+      });
+    }
+  };
+}
+export {
+  createXaiUsageMeter
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-matrx/chat",
-  "version": "0.7.9",
+  "version": "0.7.11",
   "description": "THE one AI Matrx person-to-agent chat system: the full chat (running agents, conversations, tool calls, streaming, context, surfaces, voice) as explicit per-module subpaths @ai-matrx/chat/<domain>/<module> (no wildcards: scripts/public-modules.json) over a host contract (/host, /host/react) whose only required value is a db. One chat, one renderer: the old kernel entries (., /external-store, /matrx, /react, /tools, styles.css, tokens.css) are retired.",
   "type": "module",
   "license": "MIT",
@@ -2140,6 +2140,11 @@
       "import": "./dist/agents/redux/execution-system/thunks/call-conversation-api.js",
       "default": "./dist/agents/redux/execution-system/thunks/call-conversation-api.js"
     },
+    "./agents/redux/execution-system/thunks/continue-agent-json": {
+      "types": "./dist/agents/redux/execution-system/thunks/continue-agent-json.d.ts",
+      "import": "./dist/agents/redux/execution-system/thunks/continue-agent-json.js",
+      "default": "./dist/agents/redux/execution-system/thunks/continue-agent-json.js"
+    },
     "./agents/redux/execution-system/thunks/conversation-bundle": {
       "types": "./dist/agents/redux/execution-system/thunks/conversation-bundle.d.ts",
       "import": "./dist/agents/redux/execution-system/thunks/conversation-bundle.js",
@@ -2435,11 +2440,6 @@
       "import": "./dist/agents/route/buildSystemAgentAiPayload.js",
       "default": "./dist/agents/route/buildSystemAgentAiPayload.js"
     },
-    "./agents/run/useRunAgent": {
-      "types": "./dist/agents/run/useRunAgent.d.ts",
-      "import": "./dist/agents/run/useRunAgent.js",
-      "default": "./dist/agents/run/useRunAgent.js"
-    },
     "./agents/runtime-reconnect/ServerOperationBanner": {
       "types": "./dist/agents/runtime-reconnect/ServerOperationBanner.d.ts",
       "import": "./dist/agents/runtime-reconnect/ServerOperationBanner.js",
@@ -4681,25 +4681,25 @@
     "server-only": "^0.0.1",
     "uuid": "^14.0.2",
     "zod": "^4.6.5",
-    "@ai-matrx/agents": "latest",
     "@ai-matrx/alchemy": "latest",
     "@ai-matrx/associations": "latest",
     "@ai-matrx/browser-audio": "latest",
     "@ai-matrx/canvas": "latest",
     "@ai-matrx/content-ir": "latest",
+    "@ai-matrx/agents": "latest",
+    "@ai-matrx/content-ir-react": "latest",
     "@ai-matrx/data": "latest",
     "@ai-matrx/design-system": "latest",
+    "@ai-matrx/icons": "latest",
     "@ai-matrx/kit": "latest",
     "@ai-matrx/media": "latest",
-    "@ai-matrx/icons": "latest",
     "@ai-matrx/print": "latest",
-    "@ai-matrx/diff": "latest",
     "@ai-matrx/realtime": "latest",
     "@ai-matrx/records": "latest",
     "@ai-matrx/records-ui": "latest",
     "@ai-matrx/rich-content": "latest",
     "@ai-matrx/rich-editor": "latest",
-    "@ai-matrx/content-ir-react": "latest"
+    "@ai-matrx/diff": "latest"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.5",
@@ -4818,5 +4818,5 @@
     "check:side-effects": "node ../scripts/check-side-effects-listed.mjs . && node ../scripts/check-side-effects-listed.mjs --self-test",
     "check:public-surface": "node ./scripts/sync-public-surface.mjs --check && node ./scripts/sync-public-surface.mjs --self-test"
   },
-  "gitHead": "6f80fabd57ab4f61aa950c7e2d9b1f3309797abd"
+  "gitHead": "db3bd1fad7851f7648e0aeee094cf4df6152b3ae"
 }

package/dist/agents/run/useRunAgent.d.ts

@@ -1,69 +0,0 @@
-import type { Action } from "redux";
-import type { ThunkAction } from "redux-thunk";
-import type { ChatRootState } from "../../store/root-state.js";
-import { type CallScope, type LLMParamsBody } from "../../host/server/call-api.js";
-import type { components } from "@ai-matrx/agents/generated/api-types";
-export interface RunAgentArgs {
-    /** Live agent id (UUID) or slug. */
-    agentId: string;
-    /** The user message sent to the agent (optional for variable-only agents). */
-    userInput?: string;
-    /** Variable name → value map, filling the agent's declared variables. */
-    variables?: Record<string, string>;
-    /** Per-run model/config overrides (temperature, ai_model_id, …). */
-    configOverrides?: LLMParamsBody;
-    /** Entity-local scope. Explicit values beat the user's global active context. */
-    organizationId?: string;
-    projectId?: string;
-    taskId?: string;
-    /**
-     * Stable durable-entity identity. The server reloads this row and uses its
-     * saved scope; the browser does not get to redefine that scope.
-     */
-    contextAnchor?: components["schemas"]["ContextAnchor"];
-    /** Durable producer attribution for the conversation and usage ledger. */
-    sourceApp: string;
-    sourceFeature: string;
-    /**
-     * Interactivity attestation — the ONLY input a client has into
-     * `origin_class`. "user" (the default) is a person's gesture on the screen
-     * that calls this hook; client code firing a run with no gesture behind it
-     * passes "auto". Omitting it entirely is what makes the server class our own
-     * screens as unattested API callers.
-     */
-    initiation?: "user" | "auto";
-    /** Abort the in-flight run. */
-    signal?: AbortSignal;
-    /** Stream chunk-by-chunk text as it arrives (e.g. to show live progress). */
-    onChunk?: (fullText: string) => void;
-}
-export interface UseRunAgent {
-    /** Run the agent and resolve with the full accumulated text output. */
-    run: (args: RunAgentArgs) => Promise<string>;
-    running: boolean;
-    error: string | null;
-    reset: () => void;
-}
-/** Body type for POST /ai/agents/{agent_id} with transport-injected scope. */
-type RunAgentBody = Omit<components["schemas"]["AgentStartRequest"], "organization_id" | "project_id" | "task_id"> & Partial<Pick<components["schemas"]["AgentStartRequest"], "organization_id" | "project_id" | "task_id">>;
-export declare function buildRunAgentRequest(args: RunAgentArgs): {
-    body: RunAgentBody;
-    scopeOverrides: Partial<CallScope>;
-};
-/**
- * Run a one-shot agent through the published package client and resolve with
- * the full text output. Thunk-shaped so the hook (and thunk-style callers)
- * share ONE implementation with real `getState` access.
- *
- * Result semantics (parity with the pre-package flow, proven by
- * `useRunAgent.test.ts` + `run-agent-via-matrx.test.ts`):
- *   - a fatal `error` event → throw its `user_message` → `message` → fallback;
- *   - a `failed`/`cancelled` `user_request` completion → throw
- *     `result.error` → `result.user_message` → "The agent run <status>"
- *     (when both fire, the error event wins — the package/projector ruling);
- *   - otherwise resolve accumulated chunk text, falling back to the
- *     completion's `result.output`.
- */
-export declare function runAgentViaMatrxClient(args: RunAgentArgs): ThunkAction<Promise<string>, ChatRootState, unknown, Action>;
-export declare function useRunAgent(): UseRunAgent;
-export {};

package/dist/agents/run/useRunAgent.js

@@ -1,135 +0,0 @@
-"use client";
-import { useCallback, useRef, useState } from "react";
-import { useAppDispatch } from "../../store/hooks.js";
-import {
-  startAgentRun
-} from "@ai-matrx/agents/matrx";
-import {
-  createAgentRequestProjection,
-  projectAgentEvent
-} from "@ai-matrx/agents/projection/request";
-import {
-  buildRequestBody,
-  resolveScope,
-  waitForAuthReady
-} from "../../host/server/call-api.js";
-import { createMatrxTransport } from "../../host/server/matrx-transport.js";
-import { applyDesktopTargetToRequestBody } from "@ai-matrx/agents/matrx";
-import { extractErrorMessage } from "@ai-matrx/data/net";
-import { selectDesktopTargetInstanceId } from "../../host/prefs.js";
-function buildRunAgentRequest(args) {
-  const scopeOverrides = {};
-  if (args.organizationId !== void 0) {
-    scopeOverrides.organization_id = args.organizationId;
-  }
-  if (args.projectId !== void 0) scopeOverrides.project_id = args.projectId;
-  if (args.taskId !== void 0) scopeOverrides.task_id = args.taskId;
-  return {
-    body: {
-      // One-shot run: a freshly minted id for correlation, is_new so the
-      // server never looks anything up, store:false so nothing is written.
-      conversation_id: crypto.randomUUID(),
-      is_new: true,
-      store: false,
-      user_input: args.userInput ?? null,
-      variables: args.variables && Object.keys(args.variables).length > 0 ? args.variables : void 0,
-      config_overrides: args.configOverrides,
-      source_app: args.sourceApp,
-      source_feature: args.sourceFeature,
-      initiation: args.initiation ?? "user",
-      context_anchor: args.contextAnchor,
-      stream: true,
-      debug: false
-    },
-    scopeOverrides
-  };
-}
-const stringField = (bag, key) => {
-  if (typeof bag !== "object" || bag === null) return null;
-  const value = bag[key];
-  return typeof value === "string" && value ? value : null;
-};
-function runAgentViaMatrxClient(args) {
-  return async (_dispatch, getState) => {
-    await waitForAuthReady(getState);
-    const state = getState();
-    const { body, scopeOverrides } = buildRunAgentRequest(args);
-    const scope = resolveScope(state, scopeOverrides);
-    const request = buildRequestBody(body, scope);
-    const desktopTargetInstanceId = selectDesktopTargetInstanceId(state);
-    if (desktopTargetInstanceId) {
-      applyDesktopTargetToRequestBody(request, desktopTargetInstanceId);
-    }
-    const transport = createMatrxTransport(getState, {
-      organizationId: scope.organization_id,
-      source: "runAgentViaMatrxClient"
-    });
-    const handle = await startAgentRun(
-      transport,
-      args.agentId,
-      request,
-      args.signal ? { signal: args.signal } : {}
-    );
-    let projection = createAgentRequestProjection({
-      requestId: handle.requestId ?? String(request.conversation_id),
-      conversationId: handle.conversationId
-    });
-    for await (const envelope of handle.events) {
-      const previousAnswer = projection.answer;
-      projection = projectAgentEvent(projection, envelope);
-      if (projection.answer !== previousAnswer) {
-        args.onChunk?.(projection.answer);
-      }
-    }
-    if (projection.error) {
-      throw new Error(
-        stringField(projection.error, "user_message") ?? stringField(projection.error, "message") ?? "The agent run failed"
-      );
-    }
-    const completion = projection.completion;
-    const completionStatus = typeof completion?.status === "string" ? completion.status : null;
-    if (completionStatus === "failed" || completionStatus === "cancelled") {
-      const result = completion?.result;
-      throw new Error(
-        stringField(result, "error") ?? stringField(result, "user_message") ?? `The agent run ${completionStatus}`
-      );
-    }
-    if (projection.answer) return projection.answer;
-    return stringField(completion?.result, "output") ?? "";
-  };
-}
-function useRunAgent() {
-  const dispatch = useAppDispatch();
-  const [running, setRunning] = useState(false);
-  const [error, setError] = useState(null);
-  const runningRef = useRef(false);
-  const reset = useCallback(() => {
-    setRunning(false);
-    setError(null);
-    runningRef.current = false;
-  }, []);
-  const run = useCallback(
-    async (args) => {
-      setRunning(true);
-      setError(null);
-      runningRef.current = true;
-      try {
-        return await dispatch(runAgentViaMatrxClient(args));
-      } catch (err) {
-        const message = extractErrorMessage(err);
-        setError(message);
-        throw err instanceof Error ? err : new Error(message);
-      } finally {
-        runningRef.current = false;
-        setRunning(false);
-      }
-    },
-    [dispatch]
-  );
-  return { run, running, error, reset };
-}
-export {
-  buildRunAgentRequest,
-  runAgentViaMatrxClient,
-  useRunAgent
-};