@ai-matrx/chat 0.7.29 → 0.7.31

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @ai-matrx/chat
 
+## 0.7.31
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/chat/v0.7.30..npm/chat/v0.7.31 -- apps/shared/chat`).
+No source changes intended and no consumer action required.
+
+## 0.7.30
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/chat/v0.7.29..npm/chat/v0.7.30 -- apps/shared/chat`).
+No source changes intended and no consumer action required.
+
 ## 0.7.29
 ### the agents messenger
 

package/dist/agents/components/inputs/smart-input/useConversationDisplayRows.d.ts

@@ -1,12 +1,11 @@
+import { type ResolvedContextRow } from "@ai-matrx/agents/context";
+import type { ChatRootState } from "../../../../store/root-state.js";
 /**
- * The context rows a conversation's chip and full view DISPLAY: the door's
- * display rows (`selectDisplayContextRows`), with the server-added documents
- * reconciled against what is attached to the conversation NOW — the same
- * platform.associations edges `AttachedDocumentChips` lists, and the connector
- * resources (repos, Google files, synced records) the attachments handle has
- * read (`selectConversationAttachmentsEntry`, no second fetch). An attachment
- * detached since the last receipt drops out at once; one attached since then
- * shows at once, its size unknown until the next receipt.
+ * What the host's context sources (the page the person is on, for a browser host) would add to
+ * the next turn, read now and again whenever a source says it changed, the window regains focus,
+ * or the conversation changes. A host without sources reads `{}` once and never again.
  */
-import type { ResolvedContextRow } from "@ai-matrx/agents/context";
+export declare function useHostContextPreview(conversationId: string): Record<string, unknown>;
+/** The host's would-be context as rows, each under the person's saved rule; keys already shown stay as they are. */
+export declare function hostContextRows(state: ChatRootState, conversationId: string, shown: readonly ResolvedContextRow[], hostContext: Readonly<Record<string, unknown>>): ResolvedContextRow[];
 export declare function useConversationDisplayRows(conversationId: string, mandateKillSwitch: boolean): ResolvedContextRow[];

package/dist/agents/components/inputs/smart-input/useConversationDisplayRows.js

@@ -1,9 +1,22 @@
 "use client";
+import { useEffect, useMemo, useRef, useState } from "react";
+import {
+  DEFAULT_SURFACE_KEY,
+  resolveContextRow
+} from "@ai-matrx/agents/context";
+import { humanizeIdentifier } from "@ai-matrx/kit/text-case";
 import { useAppSelector, useAppStore } from "../../../../store/hooks.js";
 import { useConversationMaterialized } from "../../../hooks/useConversationMaterialized.js";
 import { useContainerLinks } from "@ai-matrx/associations/react";
 import { attachmentContextKey } from "@ai-matrx/agents/context";
 import {
+  previewHostTurnContext,
+  subscribeHostContextChanges
+} from "../../../redux/execution-system/utils/host-turn.js";
+import { resolveClientSurface } from "../../../redux/execution-system/utils/build-tool-injection.js";
+import { selectSavedContextRuleRows } from "../../../redux/execution-system/context-rules/context-rules.thunks.js";
+import {
+  selectContextInlineCap,
   DOCUMENT_ATTACHMENT_PREFIXES,
   RESOURCE_ATTACHMENT_PREFIXES,
   durableAttachmentKey,
@@ -18,6 +31,51 @@ import {
   useAttachedDocumentFileNames
 } from "../resources/attached-documents.js";
 import { selectOrganizationId } from "../../../../host/org.js";
+function useHostContextPreview(conversationId) {
+  const store = useAppStore();
+  const [preview, setPreview] = useState({});
+  const latest = useRef(0);
+  useEffect(() => {
+    let live = true;
+    const read = () => {
+      const ticket = ++latest.current;
+      void previewHostTurnContext(store.getState(), conversationId).then(
+        (context) => {
+          if (live && ticket === latest.current) setPreview(context);
+        },
+        () => void 0
+      );
+    };
+    read();
+    const off = subscribeHostContextChanges(read);
+    const onFocus = () => read();
+    window.addEventListener("focus", onFocus);
+    return () => {
+      live = false;
+      off();
+      window.removeEventListener("focus", onFocus);
+    };
+  }, [store, conversationId]);
+  return preview;
+}
+function hostContextRows(state, conversationId, shown, hostContext) {
+  const keys = Object.keys(hostContext);
+  if (keys.length === 0) return [];
+  const have = new Set(shown.map((row) => row.key));
+  const saved = selectSavedContextRuleRows(state);
+  const cap = selectContextInlineCap(state, conversationId);
+  const primarySurface = resolveClientSurface(state, conversationId) ?? null;
+  return keys.filter((key) => !have.has(key) && hostContext[key] !== void 0).map((key) => {
+    const source = {
+      key,
+      label: humanizeIdentifier(key) || key,
+      surfaceKey: DEFAULT_SURFACE_KEY,
+      origin: "page",
+      value: hostContext[key]
+    };
+    return resolveContextRow(source, saved, cap, primarySurface);
+  });
+}
 function useConversationDisplayRows(conversationId, mandateKillSwitch) {
   const store = useAppStore();
   const rows = useAppSelector(selectDisplayContextRows(conversationId, mandateKillSwitch));
@@ -55,11 +113,28 @@ function useConversationDisplayRows(conversationId, mandateKillSwitch) {
     key: attachmentContextKey(row.provider, row.resource_ref),
     label: row.display_name
   })) : null;
-  return reconcileDurableAttachments(store.getState(), conversationId, rows, [
-    { prefixes: DOCUMENT_ATTACHMENT_PREFIXES, items: documents },
-    { prefixes: RESOURCE_ATTACHMENT_PREFIXES, items: resources }
-  ]);
+  const reconciled = reconcileDurableAttachments(
+    store.getState(),
+    conversationId,
+    rows,
+    [
+      { prefixes: DOCUMENT_ATTACHMENT_PREFIXES, items: documents },
+      { prefixes: RESOURCE_ATTACHMENT_PREFIXES, items: resources }
+    ]
+  );
+  const hostContext = useHostContextPreview(conversationId);
+  return useMemo(() => {
+    const extra = hostContextRows(
+      store.getState(),
+      conversationId,
+      reconciled,
+      hostContext
+    );
+    return extra.length === 0 ? reconciled : [...reconciled, ...extra];
+  }, [store, conversationId, reconciled, hostContext]);
 }
 export {
-  useConversationDisplayRows
+  hostContextRows,
+  useConversationDisplayRows,
+  useHostContextPreview
 };

package/dist/agents/hooks/useComposerStructuredRun.d.ts

@@ -0,0 +1,20 @@
+import { type HeadlessAgentJsonResult } from "../redux/execution-system/thunks/run-headless-agent-json.js";
+export interface ComposerStructuredRunOptions<T> {
+    /** The conversation the page launched and the composer sends. */
+    conversationId: string | null | undefined;
+    /** Stable surface key (telemetry, the same key the launcher used). */
+    surfaceKey: string;
+    /** Variables the page supplies whole — hidden from the form, still sent. */
+    pageOwnedVariables?: readonly string[];
+    /** Narrow the extracted value; throw for an unusable answer. */
+    coerce: (value: unknown, result: HeadlessAgentJsonResult) => T;
+    /** The answer, once a sent run finishes and extracts. */
+    onResult: (answer: T, requestId: string) => void;
+    /** The run failed or its answer could not be used. */
+    onError: (message: string, requestId: string) => void;
+    /** A run the composer just sent (the page shows its own progress). */
+    onStart?: (requestId: string) => void;
+}
+export declare function useComposerStructuredRun<T>({ conversationId, surfaceKey, pageOwnedVariables, coerce, onResult, onError, onStart, }: ComposerStructuredRunOptions<T>): {
+    running: boolean;
+};

package/dist/agents/hooks/useComposerStructuredRun.js

@@ -0,0 +1,75 @@
+"use client";
+import { useEffect, useRef, useState } from "react";
+import { useAppDispatch, useAppSelector, useAppStore } from "../../store/hooks.js";
+import { selectLatestRequestId } from "../redux/execution-system/selectors/aggregate.selectors.js";
+import { setPageOwnedVariableNames } from "../redux/execution-system/instance-variable-values/instance-variable-values.slice.js";
+import {
+  adoptHeadlessAgentJson
+} from "../redux/execution-system/thunks/run-headless-agent-json.js";
+function useComposerStructuredRun({
+  conversationId,
+  surfaceKey,
+  pageOwnedVariables,
+  coerce,
+  onResult,
+  onError,
+  onStart
+}) {
+  const dispatch = useAppDispatch();
+  const store = useAppStore();
+  const [running, setRunning] = useState(false);
+  const latest = useAppSelector(
+    (state) => conversationId ? selectLatestRequestId(conversationId)(state) : void 0
+  );
+  const seen = useRef({
+    conversationId: null,
+    ids: /* @__PURE__ */ new Set()
+  });
+  const callbacks = useRef({ coerce, onResult, onError, onStart });
+  useEffect(() => {
+    callbacks.current = { coerce, onResult, onError, onStart };
+  });
+  const ownedKey = (pageOwnedVariables ?? []).join("\0");
+  useEffect(() => {
+    if (!conversationId || !ownedKey) return;
+    dispatch(setPageOwnedVariableNames({ conversationId, names: ownedKey.split("\0") }));
+  }, [dispatch, conversationId, ownedKey]);
+  useEffect(() => {
+    if (!conversationId) return;
+    if (seen.current.conversationId !== conversationId) {
+      seen.current = { conversationId, ids: new Set(latest ? [latest] : []) };
+      return;
+    }
+    if (!latest || seen.current.ids.has(latest)) return;
+    seen.current.ids.add(latest);
+    const requestId = latest;
+    setRunning(true);
+    callbacks.current.onStart?.(requestId);
+    void adoptHeadlessAgentJson(dispatch, store.getState, {
+      requestId,
+      conversationId,
+      surfaceKey,
+      expect: "json",
+      keepInstance: true
+    }).then((result) => {
+      if (!result.success) {
+        callbacks.current.onError(
+          [result.error, result.errorDetail].filter(Boolean).join(" \u2014 ") || "The run returned no answer.",
+          requestId
+        );
+        return;
+      }
+      try {
+        callbacks.current.onResult(callbacks.current.coerce(result.data, result), requestId);
+      } catch (err) {
+        callbacks.current.onError(err instanceof Error ? err.message : String(err), requestId);
+      }
+    }).catch((err) => {
+      callbacks.current.onError(err instanceof Error ? err.message : String(err), requestId);
+    }).finally(() => setRunning(false));
+  }, [dispatch, store, conversationId, latest, surfaceKey]);
+  return { running };
+}
+export {
+  useComposerStructuredRun
+};

package/dist/agents/redux/execution-system/instance-variable-values/bound-variable.selectors.js

@@ -53,7 +53,9 @@ const selectVisibleInputDefinitions = (conversationId) => {
       (entry, items) => {
         if (!entry || entry.definitions.length === 0) return EMPTY_DEFS;
         const effective = applyInheritedComponents(entry.definitions, items);
+        const pageOwned = entry.pageOwnedNames ?? [];
         const visible = effective.filter((d) => {
+          if (pageOwned.includes(d.name)) return false;
           if (isCustomDataBinding(d.binding)) return false;
           if (!isBound(d)) return true;
           return isEmptyVal(entry.scopeValues[d.name]);

package/dist/agents/redux/execution-system/instance-variable-values/instance-variable-values.slice.d.ts

@@ -62,6 +62,14 @@ export interface InstanceVariableValuesEntry {
      * the name leaves this list: it is now genuinely hers.
      */
     hostValueNames: string[];
+    /**
+     * Variables the PAGE supplies whole and the person never edits (an
+     * organization's facts, the tables a builder may reuse, today's date): they
+     * ship with the run like any value, but the variable form never draws them
+     * as fields — only the variables the person fills appear (Arman, 2026-10-09:
+     * "variables are the stars of the show"). Absent = none.
+     */
+    pageOwnedNames?: string[];
     /** Immutable payload rendered only with the first submitted user turn. */
     submittedFirstTurnValues: Record<string, unknown> | null;
     submittedFirstTurnHostValueNames: string[];
@@ -86,7 +94,10 @@ export declare const initInstanceVariables: import("@reduxjs/toolkit").ActionCre
 }, "instanceVariableValues/setUserVariableValues">, setHostVariableValues: import("@reduxjs/toolkit").ActionCreatorWithPayload<{
     conversationId: string;
     values: Record<string, unknown>;
-}, "instanceVariableValues/setHostVariableValues">, restoreVariableValues: import("@reduxjs/toolkit").ActionCreatorWithPayload<{
+}, "instanceVariableValues/setHostVariableValues">, setPageOwnedVariableNames: import("@reduxjs/toolkit").ActionCreatorWithPayload<{
+    conversationId: string;
+    names: string[];
+}, "instanceVariableValues/setPageOwnedVariableNames">, restoreVariableValues: import("@reduxjs/toolkit").ActionCreatorWithPayload<{
     conversationId: string;
     values: Record<string, unknown>;
     /** The subset of `values` the host wired. Omitted = all of it is hers. */

package/dist/agents/redux/execution-system/instance-variable-values/instance-variable-values.slice.js

@@ -78,6 +78,15 @@ const instanceVariableValuesSlice = createSlice({
       }
       entry.hostValueNames = names;
     },
+    /**
+     * Name the variables this page supplies whole (see `pageOwnedNames`): the
+     * form hides them; their values still ship.
+     */
+    setPageOwnedVariableNames(state, action) {
+      const entry = state.byConversationId[action.payload.conversationId];
+      if (!entry) return;
+      entry.pageOwnedNames = [...new Set(action.payload.names)];
+    },
     /**
      * Put back a set of ALREADY-RESOLVED values TOGETHER WITH THEIR AUTHORSHIP.
      *
@@ -259,6 +268,7 @@ const {
   setUserVariableValue,
   setUserVariableValues,
   setHostVariableValues,
+  setPageOwnedVariableNames,
   restoreVariableValues,
   stampSubmittedFirstTurnValues,
   clearSubmittedFirstTurnValues,
@@ -287,6 +297,7 @@ export {
   resetUserVariableValues,
   restoreVariableValues,
   setHostVariableValues,
+  setPageOwnedVariableNames,
   setRuntimeVariableResourcePolicy,
   setScopeVariableValues,
   setUserVariableValue,

package/dist/agents/redux/execution-system/utils/host-turn.d.ts

@@ -37,6 +37,15 @@ export declare function resetLatchedTurns(): void;
  * keeps what the start latched (a resume whose start predates this page load latches then).
  */
 export declare function collectHostTurnContribution(state: ChatRootState, conversationId: string, phase: ChatHostTurnPhase): Promise<ChatHostTurnContribution | null>;
+/**
+ * What the host's context sources would add to the NEXT turn's `context`, read for display (the
+ * composer's context chip). Same sources, same bounded wait, same merge as a real send, but
+ * nothing is latched. A source that is slow or throws contributes no rows here (the skip is
+ * announced through diagnostics like any other).
+ */
+export declare function previewHostTurnContext(state: ChatRootState, conversationId: string): Promise<Record<string, unknown>>;
+/** Subscribe to every context source's "my answer may have changed" signal; returns one unsubscribe. */
+export declare function subscribeHostContextChanges(onChange: () => void): () => void;
 /**
  * Merge the host's context entries under what the request already carries: a key the person
  * or the agent set always wins. Returns the original object when the host adds nothing.

package/dist/agents/redux/execution-system/utils/host-turn.js

@@ -93,6 +93,29 @@ async function collectHostTurnContribution(state, conversationId, phase) {
   }
   return contribution;
 }
+async function previewHostTurnContext(state, conversationId) {
+  if (!isChatHostConfigured()) return {};
+  const sources = getChatHost().registry.contextSources ?? [];
+  if (sources.length === 0) return {};
+  const input = {
+    conversationId,
+    agentId: agentIdOf(state, conversationId),
+    phase: "start"
+  };
+  const merged = mergeContributions(
+    await Promise.all(sources.map((source) => askSource(source, input)))
+  );
+  return merged?.context ?? {};
+}
+function subscribeHostContextChanges(onChange) {
+  if (!isChatHostConfigured()) return () => void 0;
+  const offs = (getChatHost().registry.contextSources ?? []).flatMap(
+    (source) => source.subscribe ? [source.subscribe(onChange)] : []
+  );
+  return () => {
+    for (const off of offs) off();
+  };
+}
 function mergeHostTurnContext(existing, hostContext) {
   if (!hostContext) return existing;
   const keys = Object.keys(hostContext);
@@ -113,7 +136,9 @@ export {
   devicePermissionModeKey,
   getLatchedTurn,
   mergeHostTurnContext,
+  previewHostTurnContext,
   readDevicePermissionMode,
   resetLatchedTurns,
+  subscribeHostContextChanges,
   writeDevicePermissionMode
 };

package/dist/context/sources/scopes.d.ts

@@ -3,7 +3,7 @@
  *
  * Scopes (user-authored dimensions: organization, project, task, scope types and their
  * values, the active scope selection) are a platform primitive the chat package READS to
- * build what an agent receives. Until `@ai-matrx/scopes` exists (P17s1–s2), the host hands
+ * build what an agent receives. Until the data/records packages own scope reading (scopes package deleted 2026-10-09), the host hands
  * them over through ONE registration, `registerChatScopes({...})`, keyed by the export names
  * that package will publish — so P17s3 swaps this module's import specifier for
  * `@ai-matrx/scopes` and deletes this file, with no call-site change.

package/dist/host/contract.d.ts

@@ -873,6 +873,12 @@ export interface ChatContextSource {
     /** Stable id, for diagnostics. */
     id: string;
     contribute(input: ChatHostTurnInput): Promise<ChatHostTurnContribution | null>;
+    /**
+     * Tell the package this source's answer may have changed (the page navigated, the person
+     * switched tabs), so the composer's context chip re-reads it. Returns the unsubscribe. Absent:
+     * the chip reads the source when the conversation opens and when the window regains focus.
+     */
+    subscribe?(onChange: () => void): () => void;
 }
 export interface ChatRoutingPort {
     policy(conversationId: string): ChatRoutingPolicy;

package/dist/messenger/MessengerRail.js

@@ -139,7 +139,7 @@ function MessengerRail({
       "data-collapsed": collapsed ? "true" : "false",
       className: cn(
         "flex h-full shrink-0 flex-col border-r border-border bg-muted/40 py-2 transition-[width] duration-150",
-        collapsed ? "w-16 px-2" : "w-36 px-2",
+        collapsed ? "w-16 px-2" : "w-40 px-2",
         className
       ),
       children: [

package/dist/messenger/agents/AgentsMessenger.js

@@ -307,7 +307,7 @@ function useAgentsMessengerSource(options = {}) {
         id: agentRowId(row.agentId),
         name: nameOf(row.agentId),
         avatar: { kind: "monogram" },
-        preview: row.latest ? threadTitle(row.latest) : seatOf(row.agentId) ? STARTER_LABEL : void 0,
+        preview: row.latest ? threadTitle(row.latest) : void 0,
         time: relativeDate(row.latest?.updatedAt),
         pinned: row.pinned,
         searchText: info.get(row.agentId)?.description ?? void 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-matrx/chat",
-  "version": "0.7.29",
+  "version": "0.7.31",
   "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",
@@ -4718,12 +4718,12 @@
     "zod": "^4.6.5",
     "@ai-matrx/associations": "latest",
     "@ai-matrx/browser-audio": "latest",
-    "@ai-matrx/alchemy": "latest",
     "@ai-matrx/canvas": "latest",
     "@ai-matrx/content-ir": "latest",
     "@ai-matrx/content-ir-react": "latest",
+    "@ai-matrx/alchemy": "latest",
     "@ai-matrx/data": "latest",
-    "@ai-matrx/diff": "latest",
+    "@ai-matrx/agents": "latest",
     "@ai-matrx/design-system": "latest",
     "@ai-matrx/icons": "latest",
     "@ai-matrx/kit": "latest",
@@ -4735,7 +4735,7 @@
     "@ai-matrx/records-ui": "latest",
     "@ai-matrx/rich-content": "latest",
     "@ai-matrx/rich-editor": "latest",
-    "@ai-matrx/agents": "latest"
+    "@ai-matrx/diff": "latest"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.5",
@@ -4854,5 +4854,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": "4d71c2b833fcf4ddf381519c7ceda59cfa0174db"
+  "gitHead": "49f70431f3ef0317f82a1e22f628cf521e448058"
 }