@ai-matrx/messaging 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,76 @@
 # Changelog — `@ai-matrx/messaging`
 
+## 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
+types** — the one line the README tells every consumer to write.
+
+### Fixed
+
+- **The public `client` prop type is now shallow.** Checking a fully-typed
+  `SupabaseClient<Database>` against the rich internal shape makes tsc chase PostgREST's schema
+  machinery until it bails with `TS2589: Type instantiation is excessively deep and possibly
+  infinite`, followed by a page of "not assignable" — so the only way to pass the client a host
+  already has was the cast this package's own header forbids. The boundary is method names and
+  arity with `unknown` results; the rich contract (`MessagingSupabaseInternal`, formerly the
+  public type's body) is still what everything inside works against, and the provider narrows to
+  it ONCE, in-package. Same lesson as data 0.2.1: type a public boundary over `unknown`, never
+  over a strict recursive type the host's generator also produces.
+- **`createMessagingRepository` takes the same shallow client**, so the framework-free path a
+  service module uses (the README's "Outside React" section) compiles for the same host that the
+  provider does. Both legs are proven at compile time.
+- **`supabase-shape.test.ts` now proves the consumer's leg**: a `SupabaseClient<Database>` is
+  assignable to `MessagingSupabaseClient`. The old proof deliberately checked only the CALLS,
+  noting that whole-interface assignability "makes tsc bail with TS2589, which is a compiler
+  limit, not a contract failure" — true, and precisely why the consumer could not compile. The
+  limit was the contract failure.
+
+### Consumer action (C28)
+
+None, and one less cast: pass your `SupabaseClient` straight in. A host that had written
+`client={supabase as never}` can delete the cast. `MessagingSupabaseInternal` is exported for
+anyone building the repository directly.
+
 ## 0.8.0 — 2026-09-07
 
 **Every conversation in the first real inbox was titled with a raw UUID.** The second live defect

package/README.md

@@ -166,14 +166,33 @@ 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
 >
 ```
 
-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.
+
+**"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
     )
   };
 }
@@ -1571,12 +1584,13 @@ function requireOrg(organizationId, operation) {
   return organizationId;
 }
 function createMessagingRepository(options) {
-  const { client, identity } = options;
+  const { identity } = options;
   const org = requireOrg(identity.organizationId, "createMessagingRepository");
   const userCache = createReadCache({
     ttlMs: options.userTtlMs ?? 5 * 6e4,
     ...options.now !== void 0 ? { now: options.now } : {}
   });
+  const client = options.client;
   const db = () => client.schema(MESSAGING_SCHEMA);
   const rpcDb = () => client.schema(MESSAGING_RPC_SCHEMA);
   async function withSessionRetry(operation, run) {