@ai-matrx/chat 0.1.77 → 0.2.1

package/dist/agents/redux/execution-system/thunks/smart-execute.thunk.js

@@ -0,0 +1,530 @@
+import { createAsyncThunk } from "@reduxjs/toolkit";
+import { serializeExecutionRejection } from "./execution-rejection-meta.js";
+import { selectAutoClearConversation } from "../instance-ui-state/instance-ui-state.selectors.js";
+import {
+  executeInstance,
+  SUBMISSION_REFUSED_AT_ADMISSION
+} from "./execute-instance.thunk.js";
+import { executeManualInstance } from "./execute-manual-instance.thunk.js";
+import { splitInputIntoNewConversation } from "./create-instance.thunk.js";
+import { abortConversation, hasAbortController } from "./abort-registry.js";
+import { setInstanceStatus } from "../conversations/conversations.slice.js";
+import { setRequestStatus } from "../active-requests/active-requests.slice.js";
+import {
+  markInputSubmitted,
+  clearUserInput,
+  resetSubmissionPhase,
+  setUserInputText,
+  setPreSend
+} from "../instance-user-input/instance-user-input.slice.js";
+import { resolvePendingAsksWithInput } from "../../../ui-first-tools/redux/resolve-asks-with-input.thunk.js";
+import { ensureSandboxOrDecide } from "./sandbox-gate.thunk.js";
+import { ensureConversationScopesOrAsk } from "../../../../context/sources/scopes.js";
+import {
+  selectAllResourcesResolved,
+  selectInstanceResources
+} from "../instance-resources/instance-resources.selectors.js";
+import {
+  selectIsAwaitingTools,
+  selectIsExecuting
+} from "../selectors/aggregate.selectors.js";
+import {
+  enqueueInboxMessage,
+  returnQueuedToComposer
+} from "../inbox/inbox.thunks.js";
+import {
+  selectInFlightRequestIds,
+  settleAfterStop
+} from "./settle-after-stop.thunk.js";
+import { cancelAgentRunRequest } from "../../../../host/server/matrx-transport.js";
+import { toast } from "../../../../host/notify.js";
+import { refreshSurfaceScope } from "./refresh-surface-scope.thunk.js";
+import {
+  ensureExecutionOrganization,
+  executionOrganizationForRequest
+} from "../utils/required-organization.js";
+import { getManifest } from "../../../../surfaces/runtime/registry.js";
+import {
+  claimSubmit,
+  isDuplicateSubmittedInput,
+  isSendInFlight,
+  releaseSubmitClaim
+} from "./submit-claims.js";
+import {
+  captureSubmission,
+  isEmptySubmission
+} from "./frozen-submission.js";
+import {
+  addInboxItem,
+  removeInboxItem
+} from "../inbox/inbox.slice.js";
+import { markResourcesSubmitted } from "../instance-resources/instance-resources.slice.js";
+import { flushRemarkWrites, hasPendingRemarkWrites } from "../instance-resources/remarks.js";
+import { withFreshRemarkRefs } from "../instance-resources/remarks-wire.js";
+import { isOrganizationSelectionCancelled } from "../../../../host/org.js";
+function hasConversationAtExecutionBoundary(state, conversationId) {
+  return state.conversations.byConversationId[conversationId] !== void 0;
+}
+function announceMissingConversation(conversationId) {
+  console.warn(
+    `[smart-execute] send dropped: conversation "${conversationId}" no longer exists in this tab.`
+  );
+  toast.info("Message not sent", {
+    description: "This conversation closed before your message could go. Your text was not sent \u2014 reopen the assistant and send it again."
+  });
+}
+function detachFromComposer(dispatch, getState, conversationId, submission) {
+  dispatch(
+    markInputSubmitted({ conversationId, userValues: submission.userValues })
+  );
+  settleComposer(dispatch, getState, conversationId, submission);
+}
+function settleComposer(dispatch, getState, conversationId, submission) {
+  const entry = getState().instanceUserInput?.byConversationId[conversationId];
+  if (entry && entry.text === submission.text) {
+    dispatch(clearUserInput(conversationId));
+  }
+}
+function returnToComposer(dispatch, getState, conversationId, submission) {
+  const state = getState();
+  if (!hasConversationAtExecutionBoundary(state, conversationId)) return;
+  const entry = state.instanceUserInput?.byConversationId[conversationId];
+  const current = entry?.text ?? "";
+  if (current === submission.text) {
+    dispatch(resetSubmissionPhase(conversationId));
+    return;
+  }
+  dispatch(
+    setUserInputText({
+      conversationId,
+      text: current ? `${submission.text}
+
+${current}` : submission.text,
+      userValues: submission.userValues
+    })
+  );
+}
+const heldSends = /* @__PURE__ */ new Map();
+const HOLD_POLL_MS = 25;
+function holdBehindInFlightSend(dispatch, getState, args) {
+  const { conversationId, submission } = args;
+  const cardId = `inbox_local_held_${crypto.randomUUID()}`;
+  dispatch(
+    addInboxItem({
+      injectionId: cardId,
+      conversationId,
+      mode: args.whileRunning,
+      kind: "user_message",
+      text: submission.text,
+      status: "sending",
+      isVisibleToUser: true,
+      queuedAt: (/* @__PURE__ */ new Date()).toISOString()
+    })
+  );
+  const previous = heldSends.get(conversationId) ?? Promise.resolve();
+  const next = previous.then(async () => {
+    while (isSendInFlight(conversationId)) {
+      await new Promise((resolve) => setTimeout(resolve, HOLD_POLL_MS));
+    }
+    dispatch(removeInboxItem({ conversationId, injectionId: cardId }));
+    void dispatch(
+      smartExecute({
+        conversationId,
+        surfaceKey: args.surfaceKey,
+        whileRunning: args.whileRunning,
+        submission
+      })
+    );
+  });
+  const settled = next.catch((error) => {
+    console.error("[smart-execute] a held send failed to re-enter", error);
+  });
+  heldSends.set(conversationId, settled);
+  void settled.then(() => {
+    if (heldSends.get(conversationId) === settled) {
+      heldSends.delete(conversationId);
+    }
+  });
+}
+const smartExecute = createAsyncThunk(
+  "instances/smartExecute",
+  async ({ conversationId, surfaceKey, whileRunning = "queue", submission: handed }, { getState, dispatch }) => {
+    const entryState = getState();
+    if (!handed) {
+      const inputEntry = entryState.instanceUserInput?.byConversationId[conversationId];
+      if (isDuplicateSubmittedInput(inputEntry)) {
+        console.debug(
+          `[smart-execute] duplicate submit dropped for conversation "${conversationId}" \u2014 this exact draft is already being sent. A newly typed draft is held or queued.`
+        );
+        return;
+      }
+      if (!hasConversationAtExecutionBoundary(entryState, conversationId)) {
+        announceMissingConversation(conversationId);
+        return;
+      }
+      if (!selectAllResourcesResolved(conversationId)(entryState)) {
+        console.error(
+          `[smart-execute] blocked conversation "${conversationId}" while attachments are still resolving; sending now would silently omit them.`
+        );
+        toast.info("Attachment is still uploading", {
+          description: "Your message will be ready to send when the upload finishes."
+        });
+        return;
+      }
+    }
+    let submission = handed ?? captureSubmission(entryState, conversationId);
+    if (isSendInFlight(conversationId)) {
+      if (!handed) {
+        if (isEmptySubmission(submission)) return;
+        if (submission.resources.length > 0) {
+          toast.info("Attachments can't be sent while the agent is running", {
+            description: "Stop the agent first, or remove the attachment to queue this message."
+          });
+          return;
+        }
+        detachFromComposer(dispatch, getState, conversationId, submission);
+      }
+      holdBehindInFlightSend(dispatch, getState, {
+        conversationId,
+        surfaceKey,
+        whileRunning,
+        submission
+      });
+      return;
+    }
+    claimSubmit(conversationId);
+    const fromComposer = !handed && !isEmptySubmission(submission);
+    if (fromComposer) {
+      dispatch(
+        markInputSubmitted({
+          conversationId,
+          userValues: submission.userValues,
+          // The chips read at the keypress — the same moment `submission` was
+          // frozen — so a first submit's snapshot holds its attachments too.
+          resources: selectInstanceResources(conversationId)(entryState)
+        })
+      );
+      dispatch(markResourcesSubmitted(conversationId));
+    }
+    if (!handed && hasPendingRemarkWrites(conversationId)) {
+      try {
+        await flushRemarkWrites(conversationId);
+      } catch (error) {
+        console.error("[smart-execute] pending chip writes failed before send:", error);
+      }
+      submission = withFreshRemarkRefs(
+        submission,
+        getState().instanceResources.byConversationId[conversationId]
+      );
+    }
+    let delivered = false;
+    let preSendShown = false;
+    let claimReleased = false;
+    const releaseClaim = () => {
+      if (claimReleased) return;
+      claimReleased = true;
+      releaseSubmitClaim(conversationId);
+    };
+    try {
+      let state = getState();
+      if (!hasConversationAtExecutionBoundary(state, conversationId)) {
+        announceMissingConversation(conversationId);
+        return;
+      }
+      try {
+        await ensureExecutionOrganization(state, conversationId);
+        state = getState();
+        executionOrganizationForRequest(state, conversationId);
+      } catch (error) {
+        if (isOrganizationSelectionCancelled(error)) return;
+        const message = error instanceof Error ? error.message : "Select an organization before sending this message.";
+        toast.info("Organization required", { description: message });
+        return;
+      }
+      const consumedByPendingAsks = dispatch(
+        resolvePendingAsksWithInput(conversationId, submission.text)
+      );
+      if (consumedByPendingAsks) {
+        delivered = true;
+        settleComposer(dispatch, getState, conversationId, submission);
+        return;
+      }
+      if (selectIsExecuting(conversationId)(state) || selectIsAwaitingTools(conversationId)(state)) {
+        const surfaceName = state.conversations.byConversationId[conversationId]?.surfaceName;
+        if (surfaceName && getManifest(surfaceName)?.requiresBeforeExecute === true) {
+          toast.info("Wait for this tutor turn to finish", {
+            description: "Each tutor question searches your material before it sends, so it can't be queued into an already-running answer."
+          });
+          return;
+        }
+        if (submission.resources.length > 0) {
+          toast.info("Attachments can't be sent while the agent is running", {
+            description: "Stop the agent first, or remove the attachment to queue this message."
+          });
+          return;
+        }
+        const sendText = submission.text.trim();
+        if (!sendText) return;
+        delivered = true;
+        settleComposer(dispatch, getState, conversationId, submission);
+        await dispatch(
+          enqueueInboxMessage({
+            conversationId,
+            text: sendText,
+            mode: whileRunning
+          })
+        );
+        return;
+      }
+      const prepSurface = state.conversations.byConversationId[conversationId]?.surfaceName ?? void 0;
+      dispatch(
+        setPreSend({
+          conversationId,
+          preSend: {
+            status: "preparing",
+            text: submission.text,
+            label: prepSurface && getManifest(prepSurface)?.beforeExecuteLabel || "Preparing your message",
+            startedAt: Date.now()
+          }
+        })
+      );
+      preSendShown = true;
+      try {
+        await dispatch(
+          refreshSurfaceScope({ conversationId, composerText: submission.text })
+        ).unwrap();
+      } catch (error) {
+        const message = error instanceof Error ? error.message : typeof error?.message === "string" ? error.message : "This message could not be prepared. Nothing was sent.";
+        dispatch(
+          setPreSend({
+            conversationId,
+            preSend: {
+              status: "failed",
+              text: submission.text,
+              label: "Not sent",
+              error: message,
+              startedAt: Date.now()
+            }
+          })
+        );
+        preSendShown = false;
+        throw error;
+      }
+      state = getState();
+      const gate = await dispatch(
+        ensureSandboxOrDecide({ conversationId })
+      ).unwrap();
+      if (gate === "blocked") return;
+      const apiEndpointMode = state.messages.byConversationId[conversationId]?.apiEndpointMode ?? "agent";
+      const isEphemeral = state.conversations.byConversationId[conversationId]?.isEphemeral === true;
+      let scopeIdsOverride;
+      if (!isEphemeral && apiEndpointMode !== "manual") {
+        const scopeGate = await dispatch(
+          ensureConversationScopesOrAsk(conversationId)
+        );
+        if (scopeGate.blocked) return;
+        scopeIdsOverride = scopeGate.scopeIdsOverride;
+      }
+      state = getState();
+      if (!hasConversationAtExecutionBoundary(state, conversationId)) {
+        announceMissingConversation(conversationId);
+        return;
+      }
+      const autoClear = selectAutoClearConversation(conversationId)(state);
+      dispatch(setPreSend({ conversationId, preSend: null }));
+      preSendShown = false;
+      delivered = true;
+      const executePromise = apiEndpointMode === "manual" ? dispatch(
+        executeManualInstance({
+          conversationId,
+          initiation: "user",
+          surfaceRefreshed: true,
+          submission
+        })
+      ) : dispatch(
+        executeInstance({
+          conversationId,
+          scopeIdsOverride,
+          initiation: "user",
+          // The live page was read above, with the submitted text.
+          surfaceRefreshed: true,
+          submission
+        })
+      );
+      releaseClaim();
+      if (autoClear && surfaceKey) {
+        const lifecycle = state.conversations.byConversationId[conversationId]?.conversationLifecycle;
+        if (lifecycle === "iterate") {
+          await dispatch(
+            splitInputIntoNewConversation({
+              currentConversationId: conversationId,
+              surfaceKey
+            })
+          );
+        } else {
+          console.error(
+            `[smart-input] refused to split a non-iterate conversation "${conversationId}" (lifecycle=${lifecycle ?? "continuous"}) \u2014 would orphan it; treating as continuous. Auto-clear/split is an iterate-surface affordance only \u2014 see ConversationLifecycle.`
+          );
+        }
+      }
+      const executeResult = await executePromise;
+      if (executeInstance.rejected.match(executeResult) && executeResult.payload === SUBMISSION_REFUSED_AT_ADMISSION) {
+        holdBehindInFlightSend(dispatch, getState, {
+          conversationId,
+          surfaceKey,
+          whileRunning,
+          submission
+        });
+        return;
+      }
+      if (executeInstance.rejected.match(executeResult) || executeManualInstance.rejected.match(executeResult)) {
+        const reason = typeof executeResult.payload === "string" ? executeResult.payload : executeResult.error?.message ?? "Send failed";
+        throw Object.assign(new Error(reason), {
+          conversationId,
+          executionRequestId: executeResult.meta.executionRequestId,
+          originalErrorName: executeResult.meta.originalErrorName
+        });
+      }
+    } finally {
+      if (preSendShown) dispatch(setPreSend({ conversationId, preSend: null }));
+      releaseClaim();
+      if (!delivered && !isEmptySubmission(submission)) {
+        returnToComposer(dispatch, getState, conversationId, submission);
+      }
+    }
+  },
+  { serializeError: serializeExecutionRejection }
+);
+function latestServerRequestId(state, conversationId) {
+  const requestIds = state.activeRequests?.byConversationId[conversationId];
+  if (!requestIds?.length) return null;
+  for (let i = requestIds.length - 1; i >= 0; i--) {
+    const req = state.activeRequests.byRequestId[requestIds[i]];
+    if (req?.serverRequestId) return req.serverRequestId;
+  }
+  return null;
+}
+function appliedTransportSeq(state, conversationId, serverRequestId) {
+  const requestIds = state.activeRequests?.byConversationId[conversationId] ?? [];
+  for (let i = requestIds.length - 1; i >= 0; i--) {
+    const req = state.activeRequests.byRequestId[requestIds[i]];
+    if (req?.serverRequestId === serverRequestId) {
+      return typeof req.lastTransportSeq === "number" ? req.lastTransportSeq : void 0;
+    }
+  }
+  return void 0;
+}
+const cancelExecution = createAsyncThunk(
+  "instances/cancelExecution",
+  async (conversationId, { getState, dispatch }) => {
+    const state = getState();
+    const serverRequestId = latestServerRequestId(state, conversationId);
+    abortConversation(conversationId);
+    if (serverRequestId) {
+      const seenSeq = appliedTransportSeq(
+        getState(),
+        conversationId,
+        serverRequestId
+      );
+      void dispatch(
+        cancelAgentRunRequest(serverRequestId, "cancel", seenSeq)
+      ).then((result) => {
+        if (result.error) {
+          console.warn(
+            "[cancel-execution] server cancel failed (best-effort)",
+            {
+              conversationId,
+              serverRequestId,
+              error: result.error
+            }
+          );
+        }
+      });
+    }
+    const stoppedRequestIds = selectInFlightRequestIds(state, conversationId);
+    const requestIds = state.activeRequests?.byConversationId[conversationId];
+    if (requestIds && requestIds.length > 0) {
+      const latestRequestId = requestIds[requestIds.length - 1];
+      dispatch(
+        setRequestStatus({ requestId: latestRequestId, status: "cancelled" })
+      );
+    }
+    dispatch(setInstanceStatus({ conversationId, status: "cancelled" }));
+    dispatch(resetSubmissionPhase(conversationId));
+    void dispatch(returnQueuedToComposer({ conversationId }));
+    void dispatch(
+      settleAfterStop({
+        conversationId,
+        serverRequestId,
+        localRequestIds: stoppedRequestIds
+      })
+    );
+  }
+);
+const interruptAndSend = createAsyncThunk(
+  "instances/interruptAndSend",
+  async ({ conversationId, surfaceKey }, { getState, dispatch }) => {
+    const initial = getState();
+    if (!selectIsExecuting(conversationId)(initial)) {
+      await dispatch(smartExecute({ conversationId, surfaceKey }));
+      return;
+    }
+    const serverRequestId = latestServerRequestId(initial, conversationId);
+    abortConversation(conversationId);
+    if (serverRequestId) {
+      const seenSeq = appliedTransportSeq(
+        getState(),
+        conversationId,
+        serverRequestId
+      );
+      void dispatch(
+        cancelAgentRunRequest(serverRequestId, "interrupt", seenSeq)
+      ).then(
+        (result) => {
+          if (result.error) {
+            console.warn(
+              "[interrupt-and-send] server interrupt signal failed (best-effort)",
+              { conversationId, serverRequestId, error: result.error }
+            );
+          }
+        }
+      );
+    }
+    dispatch(setInstanceStatus({ conversationId, status: "cancelled" }));
+    dispatch(resetSubmissionPhase(conversationId));
+    const ABORT_SETTLE_DEADLINE = Date.now() + 5e3;
+    while (hasAbortController(conversationId) && Date.now() < ABORT_SETTLE_DEADLINE) {
+      await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+    const RETRY_WINDOW_MS = 12e4;
+    const RETRY_DELAY_MS = 750;
+    const deadline = Date.now() + RETRY_DELAY_MS + RETRY_WINDOW_MS;
+    for (; ; ) {
+      const result = await dispatch(
+        smartExecute({ conversationId, surfaceKey })
+      );
+      if (!smartExecute.rejected.match(result)) return;
+      const reason = typeof result.payload === "string" ? result.payload : result.error?.message ?? "";
+      const runInFlight = /run_in_flight/i.test(reason);
+      if (!runInFlight || Date.now() > deadline) {
+        if (runInFlight) {
+          console.error(
+            "[interrupt-and-send] old run never settled inside the retry window",
+            { conversationId }
+          );
+          toast.error("Couldn't send the message", {
+            description: "The previous run is still winding down \u2014 try sending again."
+          });
+        }
+        return;
+      }
+      await new Promise((resolve) => setTimeout(resolve, RETRY_DELAY_MS));
+    }
+  }
+);
+export {
+  cancelExecution,
+  hasConversationAtExecutionBoundary,
+  interruptAndSend,
+  smartExecute
+};

package/dist/agents/redux/execution-system/thunks/stream-flush-scheduler.d.ts

@@ -0,0 +1,18 @@
+/**
+ * ~30 fps. Not rAF's 16 ms on purpose: feeding long markdown to the renderer
+ * 60× a second freezes the main thread (the reason the per-stream timer was
+ * 30 ms before it was shared).
+ */
+export declare const STREAM_FLUSH_INTERVAL_MS = 30;
+/** Ask for `flush` to run on the next shared tick. Idempotent per tick. */
+export declare function scheduleStreamFlush(flush: () => void): void;
+/** The stream flushed synchronously (or is done): drop its pending tick. */
+export declare function unscheduleStreamFlush(flush: () => void): void;
+/** How many streams are waiting on the shared tick (tests/diagnostics). */
+export declare function pendingStreamFlushCount(): number;
+/**
+ * Tag a plain action so the store's `autoBatchEnhancer` coalesces its
+ * subscriber notification into the current frame. Thunks and other
+ * non-object values pass through untouched.
+ */
+export declare function autoBatched<T>(action: T): T;

package/dist/agents/redux/execution-system/thunks/stream-flush-scheduler.js

@@ -0,0 +1,54 @@
+import { SHOULD_AUTOBATCH } from "@reduxjs/toolkit";
+const STREAM_FLUSH_INTERVAL_MS = 30;
+const scheduled = /* @__PURE__ */ new Set();
+let timer = null;
+function drainScheduledFlushes() {
+  timer = null;
+  const due = Array.from(scheduled);
+  scheduled.clear();
+  for (const flush of due) {
+    try {
+      flush();
+    } catch (error) {
+      queueMicrotask(() => {
+        throw error;
+      });
+    }
+  }
+}
+function scheduleStreamFlush(flush) {
+  scheduled.add(flush);
+  if (timer === null) {
+    timer = setTimeout(drainScheduledFlushes, STREAM_FLUSH_INTERVAL_MS);
+  }
+}
+function unscheduleStreamFlush(flush) {
+  if (!scheduled.delete(flush)) return;
+  if (scheduled.size === 0 && timer !== null) {
+    clearTimeout(timer);
+    timer = null;
+  }
+}
+function pendingStreamFlushCount() {
+  return scheduled.size;
+}
+function autoBatched(action) {
+  if (typeof action !== "object" || action === null || !("type" in action) || typeof action.type !== "string") {
+    return action;
+  }
+  const meta = action.meta;
+  return {
+    ...action,
+    meta: {
+      ...typeof meta === "object" && meta !== null ? meta : {},
+      [SHOULD_AUTOBATCH]: true
+    }
+  };
+}
+export {
+  STREAM_FLUSH_INTERVAL_MS,
+  autoBatched,
+  pendingStreamFlushCount,
+  scheduleStreamFlush,
+  unscheduleStreamFlush
+};

package/dist/agents/redux/execution-system/thunks/structured-output-flattening.d.ts

@@ -0,0 +1,83 @@
+import type { AnyMandateKey } from "@ai-matrx/agents/mandates";
+/**
+ * THE FLATTENING DISEASE — detection, in one place.
+ *
+ * Arman, 2026-09-08, on the mandate page's "Refine with AI": coding agents
+ * keep taking a job whose product is a registered `__kind` (a structured
+ * shape with its own component, its own parts, its own actions) and running
+ * it with `expect: "text"`, then pasting whatever string came back into a
+ * textarea. The shape's component never renders, the parts the person needed
+ * (a charge, the questions, the criteria) are lost, the back-and-forth the
+ * job was designed for is impossible, and the system said NOTHING. "The
+ * system cannot function if you take structured responses and spit them out
+ * as text — and it should be screaming."
+ *
+ * This module is the scream's judgment. Two independent signals, both routed
+ * through `runHeadlessAgentJson`:
+ *
+ *  1. DECLARED — the run is a mandate and the mandate declares a structured
+ *     `output_kind`. Known BEFORE the model answers; the call site was wrong
+ *     the moment it was written.
+ *  2. HARVESTED — the run settled with a value carrying `__kind`, whatever
+ *     the caller expected. Evidence-based; covers the `agentId` path too.
+ *
+ * The scream is loud and NON-BLOCKING (`captureError` + `console.error` with
+ * the remedy): the run still resolves so the person is not punished for the
+ * call site's defect, but the Error Inspector and the console name the file
+ * that did it and what to do instead. "Scream, never block."
+ */
+/**
+ * Output kinds that ARE prose. `null` (undeclared) counts as prose because a
+ * job that declares nothing has not promised a shape; `"json"` does NOT — it
+ * is a promise of structure, and flattening it is the same defect.
+ * `"markdown"` is a value the catalogue actually carries and is prose by
+ * definition (a text run renders it through the ONE markdown pipeline).
+ */
+export declare const PROSE_OUTPUT_KINDS: ReadonlySet<string>;
+/** True when a declared output kind promises a SHAPE, not prose. */
+export declare function isStructuredOutputKind(outputKind: string | null | undefined): outputKind is string;
+/** The `__kind` a harvested value carries, when it is a shape. */
+export declare function harvestedKindOf(value: unknown): string | null;
+export interface FlatteningVerdict {
+    /** Which signal fired. */
+    signal: "declared" | "harvested";
+    kind: string;
+    message: string;
+}
+/**
+ * THE remedy sentence — shared verbatim with the static guard
+ * (`scripts/check-flattened-shapes.ts`, `pnpm check:flattened-shapes`) so the
+ * console, the Error Inspector and the CI report all say the same thing.
+ */
+export declare const FLATTENING_REMEDY = "Remedy: do NOT run a shaped job headless-for-text. Give the run a requestId and let the ONE pipeline render it \u2014 open the conversation in the agent run window (`useOpenAgentRunWindow` with `mandateKey`, so the person can keep talking) or float it with `useOpenLiveRunWindow`; read the fields you need from the extracted object (`expect: \"json\"` / `selectFirstExtractedObject`), never from the answer string; and if the page must receive one field, declare a surface write target and let the kind component apply it. See features/content-ir/FEATURE.md \u00A7 No bespoke stream renderers.";
+/**
+ * Judge a run BEFORE it launches, from what the mandate declares.
+ * Returns null when there is nothing to scream about.
+ */
+export declare function judgeDeclaredFlattening(args: {
+    expect: "json" | "text";
+    mandateKey: AnyMandateKey | null | undefined;
+    outputKind: string | null | undefined;
+    surfaceKey: string;
+}): FlatteningVerdict | null;
+/**
+ * The prose an answer carries OUTSIDE its embedded structured regions (fenced
+ * code blocks and tag-wrapped bodies such as `<artifact>`). An answer that is
+ * real prose with a shape embedded in it — the Fact Checker's three markdown
+ * sections plus one fenced `fact_check_report` — is a MARKDOWN answer, and
+ * asking for it as text is correct: the embedded kind still renders through
+ * the one pipeline. Only an answer that IS the shape is flattening.
+ */
+export declare function proseOutsideEmbeddedShapes(answerText: string): string;
+/**
+ * Judge a run AFTER it settled, from what actually came back.
+ * Returns null when there is nothing to scream about.
+ */
+export declare function judgeHarvestedFlattening(args: {
+    expect: "json" | "text";
+    harvested: unknown;
+    agentRef: string;
+    surfaceKey: string;
+    /** The answer text, when known: prose around an embedded shape is not flattening. */
+    answerText?: string;
+}): FlatteningVerdict | null;