@ai-matrx/chat 0.7.21 → 0.7.23

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @ai-matrx/chat
 
+## 0.7.23
+### Unreleased
+
+### A run parked on the person waits for them (lane F15)
+
+- **`runHeadlessAgentJson` / `adoptHeadlessAgentJson` / `continueAgentJson`: waiting on the person is a
+  waiting state, never a failure.** A turn that ends parked on a question (`ask_person`,
+  `suspended_awaiting_client`) no longer settles from the parked call (the Applet builder said "The
+  builder answered without an app" over a question it never showed). The wait fires the new
+  `onAwaitingPerson`, pauses `timeoutMs`, re-reads the conversation (`rereadAndFollow`) when the ask
+  closes anywhere, and resolves from the resumed turn's answer; `personWaitMs` (default 6h) bounds it.
+  A parked run that stops waiting harvests nothing (`awaitingPerson: true`). Consumer action: a surface
+  that runs an agent which may ask passes `onAwaitingPerson` to say it is waiting.
+- **A dropped connection is not a failed run.** When the stream dies on a connection loss
+  (`transport_lost` / `heartbeat_timeout`) the server finishes the turn and `reconnectServerOperation`
+  re-reads it; the headless wait now waits for that (5 min ceiling) and resolves from the answer it
+  brings, instead of failing "before returning a result" while the build finished on the server. A
+  reconnect that brings nothing ends with the stream's own reason. Consumer action: none.
+- **A settled turn that ended on a tool call shows the call, not "Processing…"** (`isWaitingForFirstContent`):
+  the parked ask's card now draws in place of a shimmer that never ended. Consumer action: none.
+
+## 0.7.22
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/chat/v0.7.21..npm/chat/v0.7.22 -- apps/shared/chat`).
+No source changes intended and no consumer action required.
+
 ## 0.7.21
 ### Unreleased
 

package/dist/agents/redux/execution-system/thunks/continue-agent-json.d.ts

@@ -22,7 +22,7 @@ import type { RequestInitiation } from "../../../types/instance.types.js";
 import type { Resource } from "../../../resources/types.js";
 import { type HostTurnInput } from "./execute-instance.thunk.js";
 import { type AdoptedAgentJsonOptions, type HeadlessAgentJsonResult } from "./run-headless-agent-json.js";
-export interface ContinueAgentJsonOptions extends Pick<AdoptedAgentJsonOptions, "surfaceKey" | "timeoutMs" | "pollIntervalMs" | "settleMs" | "expect" | "onResult" | "signal" | "failureMessages"> {
+export interface ContinueAgentJsonOptions extends Pick<AdoptedAgentJsonOptions, "surfaceKey" | "timeoutMs" | "pollIntervalMs" | "settleMs" | "expect" | "onResult" | "signal" | "failureMessages" | "onAwaitingPerson" | "personWaitMs"> {
     conversationId: string;
     /** What the person typed for this turn. Exclusive with `hostTurn`. */
     userInput?: string;

package/dist/agents/redux/execution-system/thunks/continue-agent-json.js

@@ -54,7 +54,9 @@ async function continueAgentJson(dispatch, getState, opts) {
       ...opts.expect ? { expect: opts.expect } : {},
       ...opts.onResult ? { onResult: opts.onResult } : {},
       ...opts.signal ? { signal: opts.signal } : {},
-      ...opts.failureMessages ? { failureMessages: opts.failureMessages } : {}
+      ...opts.failureMessages ? { failureMessages: opts.failureMessages } : {},
+      ...opts.onAwaitingPerson ? { onAwaitingPerson: opts.onAwaitingPerson } : {},
+      ...opts.personWaitMs !== void 0 ? { personWaitMs: opts.personWaitMs } : {}
     });
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);

package/dist/agents/redux/execution-system/thunks/run-headless-agent-json.d.ts

@@ -168,6 +168,19 @@ export interface HeadlessAgentJsonOptions {
      * discards. Pair it with `onResult` so an unmounting surface still persists.
      */
     signal?: AbortSignal;
+    /**
+     * THE RUN IS WAITING ON THE PERSON, NOT FAILED. The turn ended parked on a question
+     * (`ask_person`, or a server park on a person): its answer is the turn that resumes once
+     * they answer. The wait pauses `timeoutMs`, fires this once so the surface can say so and
+     * show the question, re-reads the conversation when the ask closes (answered here, in
+     * another tab or by text), and resolves from the resumed turn. Bounded by `personWaitMs`.
+     */
+    onAwaitingPerson?: (info: {
+        requestId: string;
+        conversationId: string;
+    }) => void;
+    /** Ceiling on waiting for the person once a run parks on them. Default 6h; `signal` stops it sooner. */
+    personWaitMs?: number;
     /** Fires with the conversation id BEFORE the stream runs (live UI handle). */
     onConversationCreated?: (conversationId: string) => void;
     /**
@@ -271,6 +284,8 @@ export interface HeadlessAgentJsonResult {
      * from a failure that carries its own reason.
      */
     noResult?: boolean;
+    /** `true` when the run ended parked on the person and stopped waiting before they answered. */
+    awaitingPerson?: boolean;
 }
 /**
  * 🚨 A WARNED CHOICE THAT ANSWERS WITHOUT A REQUIRED KEY FAILS PLAINLY.
@@ -333,6 +348,10 @@ export interface AdoptedAgentJsonOptions {
     onResult?: HeadlessAgentJsonOptions["onResult"];
     /** Stop waiting and harvest — same contract as `HeadlessAgentJsonOptions.signal`. */
     signal?: AbortSignal;
+    /** Same contract as `HeadlessAgentJsonOptions.onAwaitingPerson`. */
+    onAwaitingPerson?: HeadlessAgentJsonOptions["onAwaitingPerson"];
+    /** Same contract as `HeadlessAgentJsonOptions.personWaitMs`. */
+    personWaitMs?: number;
     /** Per-feature user-facing failure copy. */
     failureMessages?: HeadlessAgentJsonOptions["failureMessages"];
     /** See `deferNoJsonCapture` on `HeadlessAgentJsonOptions`. */

package/dist/agents/redux/execution-system/thunks/run-headless-agent-json.js

@@ -8,10 +8,17 @@ import {
   selectExtractedJson,
   selectFirstExtractedObject,
   selectJsonExtractionComplete,
+  selectRequestAwaitingPerson,
   selectRequestError,
   selectRequestStatus,
   selectRenderBlocksByType
 } from "../active-requests/active-requests.selectors.js";
+import {
+  selectLatestAnswerText as selectCommittedAnswerText,
+  selectLatestAssistantMessageId
+} from "../messages/messages.selectors.js";
+import { countOpenAsksForConversation } from "../../../runtime-reconnect/parked-on-person.js";
+import { rereadAndFollow } from "../../../runtime-reconnect/reread-and-follow.js";
 import {
   selectLatestAnswerText,
   selectLatestRequestId
@@ -44,6 +51,10 @@ function safeShape(err) {
 const DEFAULT_TIMEOUT_MS = 12e4;
 const DEFAULT_POLL_MS = 250;
 const DEFAULT_SETTLE_MS = 6e3;
+const DEFAULT_PERSON_WAIT_MS = 6 * 60 * 6e4;
+const RECONNECT_WAIT_MS = 5 * 6e4;
+const isConnectionLoss = (errorType) => errorType === "transport_lost" || errorType === "heartbeat_timeout";
+const PERSON_ASK_POLL_MS = 1e4;
 const DEFAULT_MESSAGES = {
   streamError: "The agent failed before returning a result.",
   noJson: "The agent finished but produced no structured JSON.",
@@ -243,6 +254,8 @@ async function adoptHeadlessAgentJson(dispatch, getState, opts) {
       msgs,
       expect: opts.expect ?? "json",
       ...opts.signal ? { signal: opts.signal } : {},
+      ...opts.onAwaitingPerson ? { onAwaitingPerson: opts.onAwaitingPerson } : {},
+      personWaitMs: opts.personWaitMs ?? DEFAULT_PERSON_WAIT_MS,
       deferNoJsonCapture: opts.deferNoJsonCapture === true
     });
   } catch (err) {
@@ -388,6 +401,8 @@ async function launchAndWait(dispatch, getState, opts) {
       msgs,
       expect: opts.expect ?? "json",
       ...opts.signal ? { signal: opts.signal } : {},
+      ...opts.onAwaitingPerson ? { onAwaitingPerson: opts.onAwaitingPerson } : {},
+      personWaitMs: opts.personWaitMs ?? DEFAULT_PERSON_WAIT_MS,
       deferNoJsonCapture: opts.deferNoJsonCapture === true
     });
   } catch (err) {
@@ -549,13 +564,45 @@ async function waitForExtraction(dispatch, getState, args) {
       ...base()
     };
   };
+  const answerSince = (state) => {
+    if (!state.messages) return `live\0${selectLatestAnswerText(conversationId)(state)}`;
+    const committed = selectCommittedAnswerText(conversationId)(state);
+    if (committed.trim()) return `${selectLatestAssistantMessageId(conversationId)(state) ?? ""}\0${committed}`;
+    return `live\0${selectLatestAnswerText(conversationId)(state)}`;
+  };
+  const unanswered = (why) => ({
+    success: false,
+    data: null,
+    error: why === "timeout" ? "Your agent's question was not answered in time." : "Stopped waiting for your answer.",
+    awaitingPerson: true,
+    ...base()
+  });
+  const startMarker = answerSince(getState());
+  let lostAt = null;
+  const reconnectedAnswer = () => {
+    const marker = answerSince(getState());
+    if (marker === startMarker) return null;
+    return fuzzyFallback(marker.slice(marker.indexOf("\0") + 1));
+  };
+  let person = null;
   try {
-    while (Date.now() - start < args.timeoutMs) {
+    while (person ? Date.now() - person.since < args.personWaitMs : Date.now() - start < args.timeoutMs || lostAt !== null && Date.now() - lostAt < RECONNECT_WAIT_MS) {
       if (args.signal?.aborted) {
-        return settle("aborted", noResultMsg);
+        return person ? unanswered("aborted") : settle("aborted", noResultMsg);
       }
       const state = getState();
       const status = selectRequestStatus(requestId)(state);
+      if (lostAt !== null) {
+        const recovered = reconnectedAnswer();
+        if (recovered != null) return { success: true, data: recovered, ...base() };
+      }
+      if (status === "error" && isConnectionLoss(selectRequestError(requestId)(state)?.error_type)) {
+        lostAt ??= Date.now();
+        if (Date.now() - lostAt < RECONNECT_WAIT_MS) {
+          await sleep(args.pollMs);
+          continue;
+        }
+      }
       if (status === "error") {
         const reqError = selectRequestError(requestId)(state);
         const { data } = resolveRunData(getState, requestId, conversationId);
@@ -572,6 +619,44 @@ async function waitForExtraction(dispatch, getState, args) {
           ...base()
         };
       }
+      if (!person && status !== void 0 && TERMINAL_STATUSES.has(status) && selectRequestAwaitingPerson(requestId)(state)) {
+        person = {
+          since: Date.now(),
+          baseline: answerSince(state),
+          askedAt: Date.now(),
+          following: false,
+          changedAt: null
+        };
+        try {
+          args.onAwaitingPerson?.({ requestId, conversationId });
+        } catch (err) {
+          console.error("[runHeadlessAgentJson] onAwaitingPerson threw", err);
+        }
+      }
+      if (person) {
+        const now = Date.now();
+        if (!person.following && now - person.askedAt >= PERSON_ASK_POLL_MS) {
+          person.askedAt = now;
+          try {
+            if (await countOpenAsksForConversation(conversationId) === 0) {
+              person.following = true;
+              await rereadAndFollow(dispatch, conversationId, "runHeadlessAgentJson: the ask closed");
+            }
+          } catch {
+          }
+        }
+        const now2 = getState();
+        const marker = answerSince(now2);
+        const answer = marker.slice(marker.indexOf("\0") + 1);
+        if (answer.trim() && marker !== person.baseline) {
+          const data = fuzzyFallback(answer);
+          if (data != null) return { success: true, data, ...base() };
+          person.changedAt ??= now;
+          if (now - person.changedAt > args.settleMs) return settle("stream-ended", noResultMsg);
+        }
+        await sleep(args.pollMs);
+        continue;
+      }
       if (selectJsonExtractionComplete(requestId)(state)) {
         return settle("extraction-complete", noResultMsg);
       }
@@ -586,6 +671,18 @@ async function waitForExtraction(dispatch, getState, args) {
       }
       await sleep(args.pollMs);
     }
+    if (person) return unanswered("timeout");
+    if (lostAt !== null && selectRequestStatus(requestId)(getState()) === "error") {
+      const reqError = selectRequestError(requestId)(getState());
+      const { data } = resolveRunData(getState, requestId, conversationId);
+      return {
+        success: false,
+        data,
+        error: reqError?.user_message ?? reqError?.message ?? msgs.streamError,
+        ...reqError?.error_type ? { errorDetail: reqError.error_type } : {},
+        ...base()
+      };
+    }
     return settle("timeout", msgs.timeout);
   } finally {
     dispatch(releaseRequestForViewer({ requestId, viewerId }));

package/dist/ui/markdown-stream/EnhancedChatMarkdown.js

@@ -5,6 +5,7 @@ import { useState, useEffect, useLayoutEffect, useMemo, useCallback, useRef } fr
 import { cn } from "@ai-matrx/design-system";
 import { WIDE_FIGURE_HOST_CLASS, WIDE_FIGURE_PROSE_CLIP_CLASS } from "../../agents/components/shared/assistant-message-layout.js";
 import { splitContentIntoBlocksV2 } from "@ai-matrx/rich-content/display/markdown-classification/processors/utils/content-splitter-v2";
+import { isWaitingForFirstContent } from "./waiting-for-content.js";
 import { renderSettledFromRecord, settledOneShotBlocks } from "@ai-matrx/rich-content/display/chat-markdown/settle-stream-blocks";
 import { expandTextBlocksInList } from "@ai-matrx/rich-content/display/markdown-classification/processors/utils/expand-text-blocks";
 import { reuseUnchangedBlocks } from "@ai-matrx/rich-content/display/chat-markdown/stable-blocks";
@@ -316,13 +317,19 @@ const EnhancedChatMarkdownInternal = ({
   const currentContent = editedContent ?? resolvedContent;
   const hasRequestOrTaskId = requestId || taskId;
   const hasReceivedNonTextContent = serverProcessedBlocks && serverProcessedBlocks.length > 0 || hasReduxRenderBlocks;
-  const isWaitingForContent = hasRequestOrTaskId && !resolvedContent.trim() && !hasReceivedNonTextContent;
-  const hasUnifiedSpecial = !settledFromRecord && (streamSlotStart !== void 0 || streamSlotEnd !== void 0 || agentCallId !== void 0 || unifiedSlots.some(
-    (s) => s.kind === "tool" || s.kind === "status" || s.kind === "error" || s.kind === "thinking" || s.kind === "render_block" && blockCarriesDataNotText(renderBlocksMap[s.blockId])
-  ));
   const hasDbInterleavedSpecial = messageInterleavedContent.some(
     (s) => s.type === "db_tool" || s.type === "thinking"
   );
+  const isWaitingForContent = isWaitingForFirstContent({
+    hasRequestOrTaskId: !!hasRequestOrTaskId,
+    resolvedContent,
+    hasReceivedNonTextContent: !!hasReceivedNonTextContent,
+    settledFromRecord,
+    recordHasNonText: hasDbInterleavedSpecial
+  });
+  const hasUnifiedSpecial = !settledFromRecord && (streamSlotStart !== void 0 || streamSlotEnd !== void 0 || agentCallId !== void 0 || unifiedSlots.some(
+    (s) => s.kind === "tool" || s.kind === "status" || s.kind === "error" || s.kind === "thinking" || s.kind === "render_block" && blockCarriesDataNotText(renderBlocksMap[s.blockId])
+  ));
   const toolLifecycleMapSelector = useMemo(
     () => requestId ? selectToolLifecycleMap(requestId) : () => void 0,
     [requestId]

package/dist/ui/markdown-stream/waiting-for-content.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Is this assistant turn still waiting for its first content (the "Processing…" shimmer)?
+ *
+ * A turn that ENDED on a tool call with no text — an `ask_person` parked on the person — is
+ * settled: its record holds the call, and the call is what the person must see. Before this rule
+ * the empty text kept the shimmer up forever over the question it was hiding (the Applet
+ * builder, live 2026-10-09: "Processing…" while the server waited on a choose_one ask).
+ */
+export declare function isWaitingForFirstContent(args: {
+    hasRequestOrTaskId: boolean;
+    resolvedContent: string;
+    hasReceivedNonTextContent: boolean;
+    settledFromRecord: boolean;
+    recordHasNonText: boolean;
+}): boolean;

package/dist/ui/markdown-stream/waiting-for-content.js

@@ -0,0 +1,10 @@
+function isWaitingForFirstContent(args) {
+  if (!args.hasRequestOrTaskId) return false;
+  if (args.resolvedContent.trim()) return false;
+  if (args.hasReceivedNonTextContent) return false;
+  if (args.settledFromRecord && args.recordHasNonText) return false;
+  return true;
+}
+export {
+  isWaitingForFirstContent
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-matrx/chat",
-  "version": "0.7.21",
+  "version": "0.7.23",
   "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",
@@ -4681,12 +4681,13 @@
     "server-only": "^0.0.1",
     "uuid": "^14.0.2",
     "zod": "^4.6.5",
+    "@ai-matrx/associations": "latest",
     "@ai-matrx/browser-audio": "latest",
+    "@ai-matrx/alchemy": "latest",
     "@ai-matrx/canvas": "latest",
-    "@ai-matrx/associations": "latest",
     "@ai-matrx/content-ir": "latest",
-    "@ai-matrx/data": "latest",
     "@ai-matrx/content-ir-react": "latest",
+    "@ai-matrx/data": "latest",
     "@ai-matrx/design-system": "latest",
     "@ai-matrx/diff": "latest",
     "@ai-matrx/icons": "latest",
@@ -4698,8 +4699,7 @@
     "@ai-matrx/records-ui": "latest",
     "@ai-matrx/rich-content": "latest",
     "@ai-matrx/rich-editor": "latest",
-    "@ai-matrx/agents": "latest",
-    "@ai-matrx/alchemy": "latest"
+    "@ai-matrx/agents": "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": "60c95feed80fd7dcac973ff29aec22faa19a1f2c"
+  "gitHead": "39aa4a6200282fa60c92b648157a3627a13b5083"
 }