@ai-matrx/chat 0.4.9 → 0.4.10

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @ai-matrx/chat
 
+## 0.4.10 — a confidential conversation never reaches a cloud target
+
+- THE CONFIDENTIAL-ROUTING RULE moves from the frozen kernel (`src/compat`) into the real chat:
+  `agents/routing/confidential-routing.ts` (pure: `decideRouting`, `localityOfChannel`,
+  `ConfidentialRoutingRefusedError`), also exported from `@ai-matrx/chat/host`.
+- New host port `routing: { policy(conversationId) => "any" | "local-only" }` (default `"any"`).
+- `resolveBackendForConversation` — the one place every send path resolves its target — refuses a
+  `local-only` conversation on every channel but `local-runtime` (the Matrx Local engine on this
+  computer), including the cloud fallback when a local-pc conversation finds no engine. It throws
+  `ConfidentialRoutingRefusedError` (message = the sentence the person reads, `remedy`, `code`
+  `confidential_thread_cloud_target_refused`) before any request is made.
+- Forcing test `agents/routing/__tests__/confidential-conversation-never-reaches-the-cloud.test.ts`
+  (red on the unfixed resolver; three plant.py mutations red).
+
+Consumer action: none for hosts without confidential conversations (the default policy is `"any"`).
+A host with confidential conversations (matrx-local) passes `routing` to its chat host.
+
 ## 0.4.9 — the shell chat remembers each page's own chat, and its title menu lists your conversations
 
 - `shellChatHome`: outside boards and Education, the conversation is remembered PER PAGE

package/dist/agents/redux/execution-system/thunks/resolve-base-url.js

@@ -14,6 +14,12 @@ import {
   supportsLocalAgentExecution
 } from "../../../../host/server/local-engine.js";
 import { selectOrganizationId } from "../../../../host/org.js";
+import { getChatHost, isChatHostConfigured } from "../../../../host/configure.js";
+import {
+  ConfidentialRoutingRefusedError,
+  decideRouting,
+  localityOfChannel
+} from "../../../routing/confidential-routing.js";
 const EC2_SANDBOX_SERVER_URL = typeof process !== "undefined" && process.env.NEXT_PUBLIC_EC2_SANDBOX_SERVER_URL || "";
 function dedicatedEc2ServerForConversation(state, conversationId) {
   if (selectActiveServer(state) !== "production") return null;
@@ -65,6 +71,17 @@ function resolveBaseUrlForConversation(state, conversationId) {
   return resolved.endsWith("/") ? resolved.slice(0, -1) : resolved;
 }
 function resolveBackendForConversation(state, conversationId) {
+  const resolved = resolveBackendUnchecked(state, conversationId);
+  if (resolved && isChatHostConfigured()) {
+    const decision = decideRouting(
+      getChatHost().routing.policy(conversationId),
+      localityOfChannel(resolved.channel)
+    );
+    if (!decision.allowed) throw new ConfidentialRoutingRefusedError(conversationId, decision);
+  }
+  return resolved;
+}
+function resolveBackendUnchecked(state, conversationId) {
   const entry = state.instanceUIState?.byConversationId?.[conversationId] ?? null;
   const overrideUrl = entry?.serverOverrideUrl ?? null;
   const headers = {

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

@@ -151,7 +151,8 @@ async function failWarnedOutputMissingKeys(getState, opts, result) {
   }
   const who = holderName ?? (warning.holderType === "workflow" ? "The chosen workflow" : "The chosen agent");
   const keys = missing.join(", ");
-  const sentence = `${who} ran, but its answer is missing ${keys} this job needs, so nothing was saved. It was chosen although it does not declare those keys \u2014 pick one that does.`;
+  const brokenJson = !(result.success && isRecord) && looksLikeBrokenJson(result.fullResponse);
+  const sentence = brokenJson ? `${who} ran, but its answer came back as broken JSON, so it couldn't be read and nothing was saved. Run it again.` : `${who} ran, but its answer is missing ${keys} this job needs, so nothing was saved. It was chosen although it does not declare those keys \u2014 pick one that does.`;
   captureError({
     source: "agent-json-result",
     code: "mandate_output_unusable",
@@ -162,7 +163,7 @@ async function failWarnedOutputMissingKeys(getState, opts, result) {
     ...result.requestId ? { requestId: result.requestId } : {},
     ...result.conversationId ? { conversationId: result.conversationId } : {},
     raw: {
-      defect: "warned-holder-answer-missing-required-keys",
+      defect: brokenJson ? "answer-is-broken-json" : "warned-holder-answer-missing-required-keys",
       mandateKey: opts.mandateKey,
       surfaceKey: opts.surfaceKey,
       holderId,
@@ -179,6 +180,17 @@ async function failWarnedOutputMissingKeys(getState, opts, result) {
     errorDetail: `mandate_output_unusable: missing ${keys}`
   };
 }
+function looksLikeBrokenJson(text) {
+  if (!text) return false;
+  const t = text.trim().replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/, "");
+  if (!t.startsWith("{") && !t.startsWith("[")) return false;
+  try {
+    JSON.parse(t);
+    return false;
+  } catch {
+    return true;
+  }
+}
 function missingRequiredKeys(record, required) {
   const answers = typeof record.answers === "object" && record.answers !== null && !Array.isArray(record.answers) ? record.answers : null;
   return required.filter((key) => !(key in record) && !(answers && key in answers));

package/dist/agents/routing/confidential-routing.d.ts

@@ -0,0 +1,52 @@
+/**
+ * THE CONFIDENTIAL-ROUTING RULE (CHAT-UI-PACKAGE-DESIGN §12 risk 4 — the highest-severity item).
+ *
+ * A conversation pinned `local-only` (matrx-local's "Confidential") REFUSES every target that is
+ * not the person's own machine. It does not downgrade, it does not warn-and-send, and it never
+ * quietly picks a different target: the send fails with a named reason and a remedy, before a byte
+ * leaves the machine. Re-deriving this per host is how private text reaches a cloud provider.
+ *
+ * Ported from the frozen kernel (`src/compat/config.ts` `decideRouting`) into the real chat
+ * (lanes/agents-chat-proposal.md W0(a)). Enforced at the one place every send path resolves its
+ * target: `resolveBackendForConversation` (`agents/redux/execution-system/thunks/resolve-base-url.ts`).
+ * The policy comes from the host's `routing` port (`host/contract.ts`; default: `"any"`).
+ *
+ * PURE on purpose: no imports, no React, no Redux, no `window`. The decision is headless so it can
+ * move (e.g. into `@ai-matrx/agents`) without a rewrite.
+ */
+/**
+ * Where a conversation's text is allowed to go.
+ * - `"any"` — the platform default: any target the host offers.
+ * - `"local-only"` — CONFIDENTIAL: only the person's own machine (the Matrx Local engine).
+ */
+export type ChatRoutingPolicy = "any" | "local-only";
+/** Where a resolved target sends text. */
+export type ChatTargetLocality = "local" | "cloud";
+/** The refusal a confidential conversation produces instead of a silent fallback. */
+export interface ChatRoutingRefusal {
+    readonly allowed: false;
+    readonly code: "confidential_thread_cloud_target_refused";
+    readonly userMessage: string;
+    readonly remedy: string;
+}
+export type ChatRoutingDecision = {
+    readonly allowed: true;
+} | ChatRoutingRefusal;
+export declare const CONFIDENTIAL_REFUSAL_MESSAGE = "This conversation is marked confidential, so it cannot be sent to a cloud AI provider.";
+export declare const CONFIDENTIAL_REFUSAL_REMEDY = "Run it on Matrx Local on this computer, or start a new conversation that is not marked confidential.";
+/** The one decision. Anything that is not `"local"` is treated as cloud by its callers. */
+export declare function decideRouting(policy: ChatRoutingPolicy, target: ChatTargetLocality): ChatRoutingDecision;
+/**
+ * The locality of a resolved backend channel. Only `"local-runtime"` — the Matrx Local engine on
+ * this computer — is local. Every other channel (the global server, a sandbox override, a dedicated
+ * EC2 server, and any channel added later) is cloud: an unknown channel can never pass the rule.
+ */
+export declare function localityOfChannel(channel: string): ChatTargetLocality;
+/** Thrown by the target resolver when a confidential conversation would reach the cloud. */
+export declare class ConfidentialRoutingRefusedError extends Error {
+    readonly code: "confidential_thread_cloud_target_refused";
+    readonly remedy: string;
+    readonly conversationId: string;
+    constructor(conversationId: string, refusal: ChatRoutingRefusal);
+}
+export declare function isConfidentialRoutingRefusedError(error: unknown): error is ConfidentialRoutingRefusedError;

package/dist/agents/routing/confidential-routing.js

@@ -0,0 +1,38 @@
+const CONFIDENTIAL_REFUSAL_MESSAGE = "This conversation is marked confidential, so it cannot be sent to a cloud AI provider.";
+const CONFIDENTIAL_REFUSAL_REMEDY = "Run it on Matrx Local on this computer, or start a new conversation that is not marked confidential.";
+function decideRouting(policy, target) {
+  if (policy === "local-only" && target !== "local") {
+    return {
+      allowed: false,
+      code: "confidential_thread_cloud_target_refused",
+      userMessage: CONFIDENTIAL_REFUSAL_MESSAGE,
+      remedy: CONFIDENTIAL_REFUSAL_REMEDY
+    };
+  }
+  return { allowed: true };
+}
+function localityOfChannel(channel) {
+  return channel === "local-runtime" ? "local" : "cloud";
+}
+class ConfidentialRoutingRefusedError extends Error {
+  code = "confidential_thread_cloud_target_refused";
+  remedy;
+  conversationId;
+  constructor(conversationId, refusal) {
+    super(refusal.userMessage);
+    this.name = "ConfidentialRoutingRefusedError";
+    this.remedy = refusal.remedy;
+    this.conversationId = conversationId;
+  }
+}
+function isConfidentialRoutingRefusedError(error) {
+  return error instanceof ConfidentialRoutingRefusedError;
+}
+export {
+  CONFIDENTIAL_REFUSAL_MESSAGE,
+  CONFIDENTIAL_REFUSAL_REMEDY,
+  ConfidentialRoutingRefusedError,
+  decideRouting,
+  isConfidentialRoutingRefusedError,
+  localityOfChannel
+};

package/dist/host/configure.js

@@ -44,8 +44,10 @@ const PORTS = [
   "chrome",
   "feedback",
   "routes",
-  "canvas"
+  "canvas",
+  "routing"
 ];
+const ANY_ROUTING = Object.freeze({ policy: () => "any" });
 const EMPTY_REGISTRATIONS = Object.freeze({});
 function assertDb(host) {
   const db = host?.db;
@@ -127,6 +129,7 @@ function resolveChatHost(host) {
     feedback: host.feedback ?? createDbFeedback(db, () => ref.identity),
     routes: { ...DEFAULT_CHAT_ROUTES, ...host.routes },
     canvas: host.canvas ?? createUnhostedCanvas(() => ref.diagnostics),
+    routing: host.routing ?? ANY_ROUTING,
     overridden
   });
   return ref;

package/dist/host/contract.d.ts

@@ -25,6 +25,7 @@ import type { ChatCanvasTabKind } from "./canvas-tabs.js";
 import type { ChatWindowOpeners } from "./window-openers.js";
 import type { DefaultChatServerApi, DefaultChatServerTypes } from "./defaults/server-api.js";
 import type { ChatMessageSource } from "./source.js";
+import type { ChatRoutingPolicy } from "../agents/routing/confidential-routing.js";
 /**
  * The connection contract (R10). Authenticated, RLS applies. Typed with the
  * package's own `ChatDatabase` (`./db-types`, generated: the schemas the
@@ -731,6 +732,15 @@ export interface ChatAppIdentity {
     /** `source_feature` for every conversation this app starts; absent keeps each screen's own. */
     sourceFeature?: string;
 }
+/**
+ * Where each conversation's text may go (lanes/agents-chat-proposal.md W0(a)). The package enforces
+ * the answer at the one place every send resolves its target (`resolveBackendForConversation`): a
+ * `"local-only"` (confidential) conversation refuses every target but the Matrx Local engine on this
+ * computer, loudly, before a byte leaves the machine. Default: `"any"` for every conversation.
+ */
+export interface ChatRoutingPort {
+    policy(conversationId: string): ChatRoutingPolicy;
+}
 export interface ChatHost {
     /**
      * R10 connection contract. Authenticated, RLS applies. Required unless `source` is given: a
@@ -791,8 +801,10 @@ export interface ChatHost {
     routes?: Partial<ChatRoutes>;
     /** Default: no canvas here — every open refuses and says so. */
     canvas?: ChatCanvasPort;
+    /** Default: every conversation may go to any target (`"any"`). */
+    routing?: ChatRoutingPort;
 }
-export type ChatPortName = "identity" | "org" | "server" | "notify" | "diagnostics" | "prefs" | "navigation" | "windows" | "catalog" | "registry" | "chrome" | "feedback" | "routes" | "canvas";
+export type ChatPortName = "identity" | "org" | "server" | "notify" | "diagnostics" | "prefs" | "navigation" | "windows" | "catalog" | "registry" | "chrome" | "feedback" | "routes" | "canvas" | "routing";
 /** Every port present. `overridden` names the ports the host supplied itself. */
 export interface ResolvedChatHost {
     /** The host's client, or the no-database stand-in when it gave only a `source`. */
@@ -818,5 +830,6 @@ export interface ResolvedChatHost {
     feedback: ChatFeedbackPort;
     routes: ChatRoutes;
     canvas: ChatCanvasPort;
+    routing: ChatRoutingPort;
     overridden: ReadonlySet<ChatPortName>;
 }

package/dist/host/index.d.ts

@@ -24,3 +24,4 @@ export { createClient, getClaimsUser, schedulerDb, supabase, type ChatClaimsUser
 export type { ChatDatabase } from "./db-types.js";
 export { ChatNoDatabaseError, NO_DATABASE_CODE_PREFIX, createNoDatabaseStandIn, isChatNoDatabaseError, isNoDatabase, } from "./no-database.js";
 export * from "./source.js";
+export * from "../agents/routing/confidential-routing.js";

package/dist/host/index.js

@@ -55,6 +55,7 @@ import {
   isNoDatabase
 } from "./no-database.js";
 export * from "./source.js";
+export * from "../agents/routing/confidential-routing.js";
 export {
   CHAT_ACTIVE_ORG_STORAGE_KEY,
   CHAT_PREFS_PREFIX,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-matrx/chat",
-  "version": "0.4.9",
+  "version": "0.4.10",
   "description": "THE one AI Matrx person-to-agent chat system: the full chat (running agents, conversations, tool calls, streaming, context, surfaces, voice) as per-module subpaths @ai-matrx/chat/<domain>/<module> over a host contract (/host, /host/react) whose only required value is a db; plus the kernel compatibility entries (., /external-store, /matrx, /react, /tools, styles.css, tokens.css) until P28.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -227,25 +227,25 @@
     "uuid": "^14.0.2",
     "zod": "^4.6.5",
     "@ai-matrx/agents": "latest",
-    "@ai-matrx/associations": "latest",
-    "@ai-matrx/browser-audio": "latest",
     "@ai-matrx/alchemy": "latest",
+    "@ai-matrx/associations": "latest",
     "@ai-matrx/canvas": "latest",
+    "@ai-matrx/browser-audio": "latest",
     "@ai-matrx/content-ir": "latest",
-    "@ai-matrx/diff": "latest",
     "@ai-matrx/content-ir-react": "latest",
-    "@ai-matrx/design-system": "latest",
     "@ai-matrx/data": "latest",
+    "@ai-matrx/design-system": "latest",
+    "@ai-matrx/diff": "latest",
     "@ai-matrx/icons": "latest",
+    "@ai-matrx/kit": "latest",
     "@ai-matrx/media": "latest",
     "@ai-matrx/print": "latest",
-    "@ai-matrx/kit": "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/tap-target": "latest",
-    "@ai-matrx/records-ui": "latest"
+    "@ai-matrx/rich-editor": "latest"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.5",