@ai-matrx/agents 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,135 @@
 # Changelog
 
+## 0.8.0 — 2026-09-08
+
+**THE ORCHESTRA BADGE IS BACK, in every client at once.**
+
+An **Orchestra** is a conductor agent that delegates to member agents at run
+time: choosing one for a step, a chat or a workflow node runs the whole
+ensemble. The Workflow Studio's old hand-rolled picker showed that — a
+conductor marker, the member count, the run mode, the tagline and the member
+titles — because the Python route `GET /agents` stamped it from
+`platform.associations`.
+
+Every picker on the platform now reads the RPC `agx_get_list_full`, and that
+RPC had no such column. So the day the pickers unified, EVERY client lost the
+badge at once, and an Orchestra became indistinguishable from an ordinary
+agent in the one place where the difference decides what happens next.
+
+The fix is in the read every client shares, not in any client.
+
+### Consumer action (C28)
+
+**None for the badge — it appears by itself.** The column is served by the
+platform RPC, this package parses it, and the picker renders it. Update to
+`0.8.0` (hosts on `"latest"` get it on their next install) and any Orchestra in
+the list wears its marker.
+
+**One import path changed, compatibly:** `SORT_OPTIONS` now lives in the pure
+`@ai-matrx/agents/catalog` entry. `@ai-matrx/agents/catalog/react` re-exports
+it unchanged, so nothing breaks — but a server-reachable module that only wants
+the five sort labels should import it from `./catalog` and stop dragging the
+`"use client"` bundle into a server graph.
+
+**Rendering your own summary of a chosen agent?** Use the exported `Music4Icon`
+and `orchestraLabel` / `orchestraDelegatesLine` / `orchestraDepthLine` rather
+than writing a second vocabulary for the same badge.
+
+### What is new
+
+- **`AgentSummary.orchestra: OrchestraBadge | null`** — strict, on every row.
+  `{ mode, tagline, depthBudget, memberCount, memberTitles }`, camelCased from
+  the new nullable `orchestra jsonb` column.
+- **`AgentRow`** carries the conductor marker: the Orchestra glyph plus the
+  member count, titled with the delegates line. Absent on an ordinary agent —
+  never a dead or empty chip.
+- **`AgentDetailCard`** leads with the Orchestra block — "Orchestra · supervisor
+  · 4 members", the tagline, "Delegates to: …" (collapsing past three into
+  "+N more") and the declared delegation depth. It sits ABOVE the description
+  because it changes what selecting this agent MEANS.
+- **`orchestraLabel` / `orchestraModeLabel` / `orchestraDelegatesLine` /
+  `orchestraDepthLine`** — the Creator words, ported verbatim from the studio
+  picker, exported from both entries.
+- **`Music4Icon`** — inlined SVG (C19), the same glyph the studio used.
+- **`assertAgentCatalogSchema`** reports `orchestraColumn: boolean | null`: a
+  database that predates the column is VISIBLE, not silently badge-less.
+
+### The platform side
+
+Migration `matrx-frontend/migrations/agx_list_orchestra_badge_column.sql` adds
+a trailing nullable `orchestra jsonb` to `agx_get_list`, `agx_get_list_full`
+and `agx_search`, built by ONE new helper `public.agx_orchestra_badges()` —
+the conductor self-edge (`source_type='agent'`, `source_id=target_id`,
+`role='orchestra'`) for mode/tagline/depth_budget, its `role='member'` edges
+for the count and the non-empty labels. Membership, `ORDER BY`, `SECURITY
+DEFINER`, `search_path` and every grant are unchanged; the page is cut BEFORE
+the badge join so `LIMIT`/`OFFSET` still bite on exactly the rows they did.
+
+### Deliberate deltas, said out loud
+
+- **`depthBudget` is what the composition DECLARED, and `null` when it declared
+  nothing.** The old studio badge printed the EFFECTIVE ceiling, defaulting to
+  the platform constant `PROJECTED_AGENT_MAX_RECURSION_DEPTH`. That constant
+  lives in the Python that enforces it; copying it into SQL and again into
+  TypeScript would be three places to drift. So a composition with no declared
+  budget shows no depth line at all, rather than a number nobody wrote.
+- **The literal token "orchestra" is not searchable.** The studio's picker let
+  an author type the word and see only ensembles. The canonical scorer this
+  package ports (from matrx-frontend) never had that, and adding it would
+  change the 295-case parity matrix. Not ported; recorded here rather than lost.
+
+### Proof
+
+`catalog/__tests__/orchestra.test.ts` layers conductor rows onto the SAME
+66-row parity fixture and asserts the badge survives the parser, every sort,
+the user/builtin split and a real filtered-search selector, pinned to literal
+expectations (comparing output to input passes trivially when both are null —
+which is the regression it exists to catch). `catalog/react/picker.test.tsx`
+renders a conductor beside an ordinary agent and asserts the marker, its count,
+its hover text and its ABSENCE on the ordinary row. Both proven RED on a
+deliberate perturbation and GREEN restored.
+
+
+## 0.7.1 — 2026-09-08
+
+**0.7.0's two catalog entries did not typecheck together.** `./catalog` and
+`./catalog/react` are emitted by two separate tsup passes (only the react group
+carries the `"use client"` banner), so each `.d.ts` holds its own copy of the
+shared declarations. `AgentId` was branded with a `unique symbol`, which is
+NOMINAL — the two copies were unrelated types, and the wiring the 0.7.0
+`Consumer action` prescribes:
+
+```tsx
+<AgentCatalogProvider catalog={createAgentCatalog({ client, identity })}>
+```
+
+failed with *"Two different types with this name exist, but they are
+unrelated"* in every consumer. Every runtime canary was green; only a `tsc` in
+a real host caught it (matrx-extend, on its first compile of the adoption).
+
+### Consumer action (C28)
+
+Update to 0.7.1 and the documented wiring compiles. No source change is needed
+in a host — if you worked around this with a cast, DELETE the cast.
+
+### The fix, and the guard
+
+- `AgentId` is now branded with a string literal
+  (`string & { readonly __agentId: "ai-matrx.agent-id" }`). A literal brand is
+  structural, so the two emitted copies unify; a bare `string` still cannot be
+  passed where an `AgentId` is required, so the branding is not weakened. Any
+  future brand in this package follows the same rule — the reason is recorded
+  at the declaration.
+- `scripts/verify-tarball.mjs` grew THE TWO-ENTRY TYPE-IDENTITY CANARY: it
+  installs the packed tarball into a scratch consumer with `strict`,
+  `exactOptionalPropertyTypes`, `noUncheckedIndexedAccess` and
+  `skipLibCheck: false`, then compiles the real provider wiring plus reads that
+  cross the seam in both directions. Proven RED against the 0.7.0 brand
+  (the same "two different types" error, from the packed types) and GREEN
+  after the fix. It runs inside `pnpm check:package`, which the publish
+  workflow gates on.
+
+
 ## 0.7.0 — 2026-09-08
 
 **THE ONE AGENT PICKER moves into the package.** Two new entries — `./catalog`

package/dist/catalog/index.cjs

@@ -30,6 +30,7 @@ __export(catalog_exports, {
   DEFAULT_AGENT_CATALOG_LABELS: () => DEFAULT_AGENT_CATALOG_LABELS,
   DEFAULT_AGENT_CONSUMER_STATE: () => DEFAULT_AGENT_CONSUMER_STATE,
   MandateDefaultRowError: () => MandateDefaultRowError,
+  SORT_OPTIONS: () => SORT_OPTIONS,
   _resetCatalogGlobalState: () => _resetCatalogGlobalState,
   agentConsumerHasActiveFilters: () => agentConsumerHasActiveFilters,
   agentListEmptyLabel: () => agentListEmptyLabel,
@@ -61,6 +62,10 @@ __export(catalog_exports, {
   memoize1: () => memoize1,
   memoize2: () => memoize2,
   memoize3: () => memoize3,
+  orchestraDelegatesLine: () => orchestraDelegatesLine,
+  orchestraDepthLine: () => orchestraDepthLine,
+  orchestraLabel: () => orchestraLabel,
+  orchestraModeLabel: () => orchestraModeLabel,
   parseMandateResolution: () => parseMandateResolution,
   readAgentCatalogRows: () => readAgentCatalogRows,
   readCachedDefaultRow: () => readCachedDefaultRow,
@@ -96,6 +101,13 @@ function mandateAgentId(mandateKey) {
 function isMandateAgentId(id) {
   return id.startsWith("mandate:");
 }
+var SORT_OPTIONS = [
+  { value: "updated-desc", label: "Recent" },
+  { value: "created-desc", label: "Created" },
+  { value: "name-asc", label: "A \u2192 Z" },
+  { value: "name-desc", label: "Z \u2192 A" },
+  { value: "category-asc", label: "Category" }
+];
 var AGENT_NONE_SENTINEL = "__none__";
 var DEFAULT_AGENT_CONSUMER_STATE = {
   tab: "mine",
@@ -165,6 +177,18 @@ function stringArray(value) {
 function agentType(value) {
   return value === "builtin" ? "builtin" : "user";
 }
+function orchestraBadge(value) {
+  if (!isRecord(value)) return null;
+  const depth = value["depth_budget"];
+  const count = value["member_count"];
+  return {
+    mode: str(value["mode"]) ?? "supervisor",
+    tagline: str(value["tagline"]),
+    depthBudget: typeof depth === "number" && Number.isFinite(depth) && depth > 0 ? depth : null,
+    memberCount: typeof count === "number" && Number.isFinite(count) && count >= 0 ? count : 0,
+    memberTitles: stringArray(value["member_titles"])
+  };
+}
 function toAgentSummary(raw) {
   if (!isRecord(raw)) return null;
   const id = str(raw["id"]);
@@ -188,7 +212,8 @@ function toAgentSummary(raw) {
     updatedAt: str(raw["updated_at"]),
     isOwner: boolOrNull(raw["is_owner"]),
     accessLevel: str(raw["access_level"]),
-    sharedByEmail: str(raw["shared_by_email"])
+    sharedByEmail: str(raw["shared_by_email"]),
+    orchestra: orchestraBadge(raw["orchestra"])
   };
 }
 
@@ -426,6 +451,9 @@ function defaultRowFromResolution(resolved) {
     isOwner: null,
     accessLevel: null,
     sharedByEmail: null,
+    // A mandate default row is a live reference to whichever agent the mandate
+    // resolves to; the badge belongs to the RESOLVED agent's own catalog row.
+    orchestra: null,
     mandateKey: resolved.mandateKey
   };
 }
@@ -530,10 +558,14 @@ async function assertAgentCatalogSchema(client, options = {}) {
   const missing = [];
   const unreachable = [];
   const answered = [];
+  let orchestraColumn = null;
   for (const fn of names) {
     const args = DEMANDED_RPCS[fn] ?? {};
     try {
-      const { error } = await client.rpc(fn, args);
+      const { data, error } = await client.rpc(fn, args);
+      if (fn === "agx_get_list_full" && error == null) {
+        orchestraColumn = readsOrchestraColumn(data);
+      }
       if (error == null) answered.push(fn);
       else if (isMissingFunctionError(error)) missing.push(fn);
       else answered.push(fn);
@@ -573,7 +605,8 @@ async function assertAgentCatalogSchema(client, options = {}) {
     missing,
     unreachable,
     answered,
-    favoriteWritable
+    favoriteWritable,
+    orchestraColumn
   };
   if (!ok && throwOnViolation) {
     const parts = [];
@@ -591,6 +624,12 @@ async function assertAgentCatalogSchema(client, options = {}) {
   }
   return report;
 }
+function readsOrchestraColumn(data) {
+  if (!Array.isArray(data) || data.length === 0) return null;
+  return data.some(
+    (row) => typeof row === "object" && row !== null && Object.prototype.hasOwnProperty.call(row, "orchestra")
+  );
+}
 function isPermissionRefusal(error) {
   if (!error) return false;
   const code = error.code;
@@ -964,6 +1003,33 @@ function getRegisteredAgentCatalog(catalogId = "default") {
   return found;
 }
 
+// catalog/orchestra.ts
+var ORCHESTRA_MODE_LABEL = {
+  supervisor: "supervisor",
+  sequential: "in order",
+  parallel: "together",
+  dag: "custom flow"
+};
+function orchestraModeLabel(mode) {
+  return ORCHESTRA_MODE_LABEL[mode] ?? mode;
+}
+function orchestraLabel(badge) {
+  const n = badge.memberCount;
+  return `Orchestra \xB7 ${orchestraModeLabel(badge.mode)} \xB7 ${n} ${n === 1 ? "member" : "members"}`;
+}
+function orchestraDepthLine(badge) {
+  const n = badge.depthBudget;
+  if (typeof n !== "number" || n <= 0) return null;
+  return `Team members can call helpers up to ${n} ${n === 1 ? "level" : "levels"} deep`;
+}
+function orchestraDelegatesLine(badge, limit = 3) {
+  const titles = badge.memberTitles;
+  if (titles.length === 0) return null;
+  const shown = titles.slice(0, limit);
+  const extra = titles.length - shown.length;
+  return `Delegates to: ${shown.join(", ")}${extra > 0 ? ` +${extra} more` : ""}`;
+}
+
 // catalog/labels.ts
 function agentListEmptyLabel(tab, labels) {
   switch (tab) {