@ai-matrx/messaging 0.9.0 → 0.10.1

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # Changelog — `@ai-matrx/messaging`
 
+## 0.10.1 — 2026-09-07
+
+**Every AI call would have been refused by the real server.** `<MessagingProvider>` never forwarded
+`sourceApp` / `sourceFeature` to the core, so every run went out stamped with this package's
+placeholder `ai-matrx` / `messaging.<capability>` — and the AI Matrx server keeps a REGISTER of
+legal producers and answers an unregistered one with a 422. Found by putting a real request on the
+wire, not by reading the code; the same shape as the 0.7.0 wrong-schema defect.
+
+### Added
+
+- **`<MessagingProvider sourceApp sourceFeature>`**, forwarded to `createMessagingAi`. Only the
+  host knows its registered slugs, so the host passes them; the package's defaults are documented
+  as placeholders that will not survive a real server.
+
+## 0.10.0 — 2026-09-07
+
+**The four AI-native intelligences rendered nothing in the first host that shipped them, and
+would have shown a skeleton instead of an answer if they had.** Three defects, all found by
+wiring the package to a real switching layer rather than by reading it.
+
+### Changed (breaking, one line at the call site)
+
+- **`agents` now takes an IDENTITY per capability, not a bare id.**
+  `{ summarize: "id" }` becomes `{ summarize: { agentId: "id", configOverrides } }`. A host that
+  resolves a capability's agent from a switching layer resolves a PAIR — which agent, and the
+  settings that layer decided for it. Taking only the id silently dropped the settings half on
+  every call. `configOverrides` rides to the server as the turn's `config_overrides`, verbatim;
+  omitted, the field is not sent at all and the agent's own settings stand.
+
+### Added
+
+- **AI runs STREAM.** Every capability takes `onText`, and `useMessagingAi` exposes
+  `partialText` + `activeCapability`. `ConversationView` renders the answer as it arrives; the
+  skeleton survives only for the gap before the first chunk, where it now names the job that is
+  running. A placeholder that sat until a run finished was a spinner standing in for an answer.
+- **`<MessagingProvider maxTranscriptMessages>`** — the provider never forwarded the core's
+  transcript cap, so the 200 in this package was unreachable taste. A host with an
+  organization-configurable knob passes the resolved number.
+- **`unreadCutoff(messages, unreadCount)`**, exported from the framework-free core.
+
+### Fixed
+
+- **"Catch me up" was a second "Summarize".** It always passed `since: null`, so it sent the
+  whole loaded window and answered the question nobody asked. It now derives the exclusive
+  cutoff from the store's own unread count — the message just before the first unread one — and
+  passes `null` only when there is genuinely no honest cutoff (nothing unread, or a loaded
+  window that does not reach back that far). Never a guessed timestamp.
+
+### Consumer action (C28)
+
+Change `agents={{ summarize: id }}` to `agents={{ summarize: { agentId: id } }}` and pass
+`configOverrides` when your resolution layer produces them. If you render the AI output
+yourself, render `partialText` while `isRunning`.
+
 ## 0.9.0 — 2026-09-07
 
 **`<MessagingProvider client={supabase}>` did not typecheck for a host with generated Supabase

package/README.md

@@ -166,14 +166,39 @@ messages, keyset pagination, and the whole polished UI. There is nothing else to
   organizationId={org.id}
   transport={matrxTransport}          // from @ai-matrx/agents/matrx
   agents={{
-    catchUp: "…", summarize: "…", actionItems: "…", draftReply: "…",
+    catchUp:     { agentId: "…", configOverrides: { … } },
+    summarize:   { agentId: "…" },
+    actionItems: { agentId: "…" },
+    draftReply:  { agentId: "…" },
   }}
+  maxTranscriptMessages={200}         // your knob, not our taste
+  sourceApp="matrx-frontend"          // YOUR registered producer slugs
+  sourceFeature="messages"
 >
 ```
 
-Agent definitions live in the **database**, never in this package — the id is the only part a
-host injects. A capability with no agent id **does not render at all**; it is never a dead button
-that fails when pressed.
+Agent definitions live in the **database**, never in this package — the injected **identity** is
+the only part a host supplies. A capability with no identity **does not render at all**; it is
+never a dead button that fails when pressed.
+
+**An identity is both halves.** If your app resolves a capability's agent from a switching layer
+that also decides settings for the job, pass `configOverrides` with the id — it is sent verbatim
+as the turn's `config_overrides`. Passing the id alone silently drops the settings half. Omit it
+and nothing is sent, so the agent's own settings stand.
+
+**A run the user watches streams.** `useMessagingAi` reports `partialText` after every chunk and
+`ConversationView` renders it; the skeleton appears only in the gap before the first chunk, and
+names the job it is waiting on. If you render the output yourself, render `partialText` while
+`isRunning` — a placeholder that sits until the run finishes is a spinner standing in for an
+answer.
+
+🚨 **`sourceApp` / `sourceFeature` are not analytics garnish.** The AI Matrx server keeps a register
+of legal producers and answers an unregistered one with a **422** — so every AI call fails until you
+pass slugs your server knows. This package's defaults are placeholders; only you know yours.
+
+**"Catch me up" means the unread tail**, derived from the store's own unread count. Nothing
+unread, or a loaded window that does not reach back to the read mark, means there is no honest
+cutoff and the whole window applies — never a guessed timestamp.
 
 ### Making references open
 

package/dist/index.cjs

@@ -63,7 +63,8 @@ __export(src_exports, {
   projectUserSummary: () => projectUserSummary,
   resolveActor: () => resolveActor,
   splitText: () => splitText,
-  summarizeText: () => summarizeText
+  summarizeText: () => summarizeText,
+  unreadCutoff: () => unreadCutoff
 });
 module.exports = __toCommonJS(src_exports);
 
@@ -357,6 +358,12 @@ ${JSON.stringify(references, null, 2)}
 }
 
 // src/core/ai.ts
+function unreadCutoff(messages, unreadCount) {
+  if (unreadCount <= 0) return null;
+  const index = messages.length - unreadCount - 1;
+  if (index < 0) return null;
+  return messages[index]?.createdAt ?? null;
+}
 function nameOf(participants, senderId) {
   return participants.find((p) => p.userId === senderId)?.displayName ?? senderId;
 }
@@ -377,22 +384,23 @@ function buildTranscript(messages, participants, limit, since) {
 }
 function createMessagingAi(options) {
   const limit = options.maxTranscriptMessages ?? 200;
-  function agentFor(capability) {
-    const agentId = options.agents[capability];
-    if (typeof agentId !== "string" || agentId.length === 0) {
+  function identityFor(capability) {
+    const identity = options.agents[capability];
+    if (identity === void 0 || identity.agentId.length === 0) {
       throw new MessagingError(
         "misconfigured",
         `Messaging AI capability "${capability}" has no agent configured`,
-        `Pass agents={{ ${capability}: "<agent-id>" }} to <MessagingProvider>. Agent definitions live in the database, never in this package \u2014 the id is the only part a host injects. Until then the UI hides this action rather than offering a button that cannot work.`
+        `Pass agents={{ ${capability}: { agentId: "<agent-id>" } }} to <MessagingProvider>. Agent definitions live in the database, never in this package \u2014 the identity is the only part a host injects. Until then the UI hides this action rather than offering a button that cannot work.`
       );
     }
-    return agentId;
+    return identity;
   }
-  async function run(capability, variables, userInput, signal) {
-    const agentId = agentFor(capability);
+  async function run(capability, variables, userInput, signal, onText) {
+    const identity = identityFor(capability);
+    const overrides = identity.configOverrides;
     const completed = await (0, import_matrx.runAgentToCompletion)(
       options.transport,
-      agentId,
+      identity.agentId,
       {
         ...(0, import_matrx.newEphemeralConversationStart)(),
         organization_id: options.organizationId,
@@ -401,9 +409,15 @@ function createMessagingAi(options) {
         initiation: "user",
         // THE USER-INPUT LAW: structured content is NEVER here.
         ...userInput !== null ? { user_input: userInput } : {},
+        // The settings half of the injected identity, verbatim. An absent one
+        // is OMITTED rather than sent as null: the agent's own settings stand.
+        ...overrides != null ? { config_overrides: overrides } : {},
         variables
       },
-      signal !== void 0 ? { signal } : {}
+      {
+        ...signal !== void 0 ? { signal } : {},
+        ...onText !== void 0 ? { onChunk: onText } : {}
+      }
     );
     return {
       capability,
@@ -436,27 +450,26 @@ function createMessagingAi(options) {
       ...args.since != null ? { unread_since: args.since } : {}
     };
   }
+  function configured(capability) {
+    const identity = options.agents[capability];
+    return identity !== void 0 && identity.agentId.length > 0;
+  }
   return {
     available: () => ["catchUp", "summarize", "actionItems", "draftReply"].filter(
-      (capability) => {
-        const id = options.agents[capability];
-        return typeof id === "string" && id.length > 0;
-      }
+      configured
     ),
-    isAvailable(capability) {
-      const id = options.agents[capability];
-      return typeof id === "string" && id.length > 0;
-    },
-    catchMeUp: (args) => run("catchUp", variablesFor(args), null, args.signal),
-    summarize: (args) => run("summarize", variablesFor(args), null, args.signal),
-    extractActionItems: (args) => run("actionItems", variablesFor(args), null, args.signal),
+    isAvailable: configured,
+    catchMeUp: (args) => run("catchUp", variablesFor(args), null, args.signal, args.onText),
+    summarize: (args) => run("summarize", variablesFor(args), null, args.signal, args.onText),
+    extractActionItems: (args) => run("actionItems", variablesFor(args), null, args.signal, args.onText),
     draftReply: (args) => run(
       "draftReply",
       variablesFor(args),
       // The ONE genuine human utterance in this module: what the user asked
       // the drafter for. Everything else rode `variables`.
       args.instruction !== void 0 && args.instruction.trim().length > 0 ? args.instruction.trim() : null,
-      args.signal
+      args.signal,
+      args.onText
     )
   };
 }