@ai-matrx/chat 0.3.5 → 0.3.6

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @ai-matrx/chat
 
+## 0.3.6 — 2026-10-07
+### Re-sync before matrx-frontend consumes the published package (P27)
+
+- `src/surfaces/lib/ui-surfaces-agent-writes` + `ui-surfaces-scope` ship at last: the repo-root `lib/`
+  ignore (Python) kept them out of every commit since 0.3.1; `apps/shared/chat/.gitignore` re-includes
+  `src/**/lib/`.
+- Carries every matrx-frontend `packages/chat` edit after `62656d3a69` (begin-fresh chat, agent-definition
+  `markFieldSaved`, tool-state effects/registry, ALC-19 copy results).
+- Consumer action: none.
+
 ## 0.3.5 — 2026-10-07
 ### Chat mode opens the agent itself; Duplicate opens the copy in a new tab
 

package/dist/agents/components/chat/ChatNewClient.d.ts

@@ -18,8 +18,13 @@ import type { ComposerMode } from "../inputs/smart-input/composer/composer-types
  *
  * The quick actions are the `agents.chat_composer.quick_actions` knob.
  */
-export declare function ChatNewClient({ agentId, composer, }: {
+export declare function ChatNewClient({ agentId, pinned, composer, }: {
     agentId: string | null;
+    /**
+     * `/chat/new?agent=<id>`: the person named the agent, so it answers directly
+     * and the default-chat mandate neither seeds nor overrides it.
+     */
+    pinned?: boolean;
     /** The three-mode composer (server-read "last mode used" cookie). */
     composer: {
         initialMode: ComposerMode | null;

package/dist/agents/components/chat/ChatNewClient.js

@@ -18,9 +18,15 @@ import { asClause } from "@ai-matrx/kit/text";
 import { WorkspaceGate } from "../../../host/ui-slots.js";
 function ChatNewClient({
   agentId,
+  pinned = false,
   composer
 }) {
-  return agentId ? /* @__PURE__ */ jsx(ChatNewBody, { agentId, composer }) : /* @__PURE__ */ jsx(ChatNewClientResolved, { composer });
+  const { mandate } = useMandate(DEFAULT_NEW_CHAT_MANDATE_KEY, { optional: true });
+  if (pinned && agentId) {
+    return /* @__PURE__ */ jsx(ChatNewBody, { agentId, composer, pinned: true });
+  }
+  const effectiveAgentId = mandate?.agentId ?? agentId;
+  return effectiveAgentId ? /* @__PURE__ */ jsx(ChatNewBody, { agentId: effectiveAgentId, composer }) : /* @__PURE__ */ jsx(ChatNewClientResolved, { composer });
 }
 function ChatNewClientResolved({
   composer
@@ -62,14 +68,15 @@ function ChatMandateUnavailable({ error }) {
 }
 function ChatNewBody({
   agentId,
-  composer
+  composer,
+  pinned = false
 }) {
   const surfaceKey = chatRouteSurfaceKey(agentId);
   return /* @__PURE__ */ jsx(
     ChatRoomClient,
     {
       agentId,
-      mandateKey: DEFAULT_NEW_CHAT_MANDATE_KEY,
+      mandateKey: pinned ? void 0 : DEFAULT_NEW_CHAT_MANDATE_KEY,
       composer,
       landingContent: (conversationId, composerPresentation) => composerPresentation ? /* @__PURE__ */ jsx(
         NewChatGreeting,

package/dist/agents/components/chat/begin-fresh-chat.d.ts

@@ -50,6 +50,8 @@ export declare function stageChatAgentSwitch({ dispatch, router, getState, targe
 }): void;
 /** Catch package-owned chat links before they bypass the same-tab handoff. */
 export declare function interceptChatAgentLink(event: ReactMouseEvent<HTMLElement>, args: Omit<Parameters<typeof stageChatAgentSwitch>[0], "targetAgentId" | "href">): void;
+/** How long "New chat" waits for the default-agent lookup before navigating anyway. */
+export declare const DEFAULT_AGENT_LOOKUP_WAIT_MS = 1500;
 /** Start a brand-new chat: drop stale surface focus, bump the fresh-session
  *  nonce (so `/chat/new` remints even when the path is unchanged), navigate.
  *

package/dist/agents/components/chat/begin-fresh-chat.js

@@ -92,6 +92,22 @@ function interceptChatAgentLink(event, args) {
     href
   });
 }
+const DEFAULT_AGENT_LOOKUP_WAIT_MS = 1500;
+async function resolveDefaultAgentBounded() {
+  let timer;
+  const lookup = resolveMandateAsking(DEFAULT_NEW_CHAT_MANDATE_KEY).then(
+    (resolved) => resolved.agentId
+  );
+  lookup.catch(() => void 0);
+  const wait = new Promise((resolve) => {
+    timer = setTimeout(() => resolve(null), DEFAULT_AGENT_LOOKUP_WAIT_MS);
+  });
+  try {
+    return await Promise.race([lookup, wait]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
 async function beginFreshChat({
   dispatch,
   router,
@@ -103,7 +119,7 @@ async function beginFreshChat({
   const auth = state.userAuth;
   if (auth && auth.id !== null && !auth.isAnonymous) {
     try {
-      defaultAgentId = (await resolveMandateAsking(DEFAULT_NEW_CHAT_MANDATE_KEY)).agentId;
+      defaultAgentId = await resolveDefaultAgentBounded();
     } catch (error) {
       if (isOrganizationSelectionCancelled(error)) return;
       console.error(
@@ -125,6 +141,7 @@ async function beginFreshChat({
   router.push(getFreshChatHref(activeAgentId, defaultAgentId));
 }
 export {
+  DEFAULT_AGENT_LOOKUP_WAIT_MS,
   beginFreshChat,
   chatRouteSurfaceKey,
   getFreshChatHref,

package/dist/agents/components/inputs/smart-input/composer/ComposerAgentPeek.js

@@ -41,7 +41,7 @@ function ComposerAgentPeek({ agentId, onDone }) {
     AgentDetailCard,
     {
       agent,
-      actions: /* @__PURE__ */ jsx(AgentPeekDuplicateButton, { agentId, onDuplicated: onDone })
+      actions: /* @__PURE__ */ jsx(AgentPeekDuplicateButton, { agentId, onStart: onDone })
     }
   );
 }

package/dist/agents/components/shared/AgentPeekDuplicateButton.d.ts

@@ -1,5 +1,8 @@
-export declare function AgentPeekDuplicateButton({ agentId, onDuplicated, }: {
+export declare function AgentPeekDuplicateButton({ agentId, onStart, }: {
     agentId: string;
-    /** Close the peek once the copy opens. */
-    onDuplicated?: () => void;
+    /**
+     * Close the peek as the copy starts: the organization question (when none is
+     * chosen) and the new tab must never open behind a menu.
+     */
+    onStart?: () => void;
 }): import("react").JSX.Element | null;

package/dist/agents/components/shared/AgentPeekDuplicateButton.js

@@ -13,7 +13,7 @@ import { selectAgentById, selectAgentReadyForBuilder } from "../../redux/agent-d
 import { agentGoHref } from "../../addressing/agentAddress.js";
 function AgentPeekDuplicateButton({
   agentId,
-  onDuplicated
+  onStart
 }) {
   const dispatch = useAppDispatch();
   const userId = useAppSelector(selectUserId);
@@ -27,20 +27,21 @@ function AgentPeekDuplicateButton({
   const duplicate = async () => {
     if (busy) return;
     setBusy(true);
-    const tab = window.open("about:blank", "_blank");
+    onStart?.();
     try {
       const newId = await dispatch(door.duplicateAgent(agentId)).unwrap();
       const href = agentGoHref(newId, "/build");
+      const tab = window.open(href, "_blank");
       if (tab) {
         tab.opener = null;
-        tab.location.href = href;
+        toast.success(`Duplicated "${record.name}" \u2014 opened in a new tab`);
       } else {
-        window.open(href, "_blank", "noopener");
+        toast.success(`Duplicated "${record.name}"`, {
+          description: "Your browser kept the new tab closed",
+          action: { label: "Open", onClick: () => window.open(href, "_blank", "noopener") }
+        });
       }
-      toast.success(`Duplicated "${record.name}" \u2014 opened in a new tab`);
-      onDuplicated?.();
     } catch (err) {
-      tab?.close();
       if (!isOrganizationSelectionCancelled(err)) {
         toast.error("Could not duplicate agent", { description: getUserMessage(err) });
       }

package/dist/agents/redux/agent-definition/slice.d.ts

@@ -121,6 +121,18 @@ export declare const agentDefinitionSlice: import("@reduxjs/toolkit").Slice<Agen
     markAgentSaved(state: AgentDefinitionSliceState, action: PayloadAction<{
         id: string;
     }>): void;
+    /**
+     * A SINGLE field was written to the database (inline edits such as the
+     * Agent Info Editor's name). Only that field becomes the clean baseline —
+     * every other staged edit (e.g. an Output Schema kind binding applied in
+     * Model Settings) must stay dirty so the main Save still persists it.
+     * `markAgentSaved` here used to wipe every dirty flag, silently dropping
+     * unrelated staged edits (feedback 222a2925).
+     */
+    markAgentFieldSaved(state: AgentDefinitionSliceState, action: PayloadAction<{
+        id: string;
+        field: keyof AgentDefinition;
+    }>): void;
     /** Save failed — restore from the snapshot taken before the optimistic write. */
     rollbackAgentOptimisticUpdate(state: AgentDefinitionSliceState, action: PayloadAction<{
         id: string;
@@ -227,7 +239,10 @@ export declare const upsertAgent: import("@reduxjs/toolkit").ActionCreatorWithPa
     id: string;
 }, "agentDefinition/resetAllAgentFields">, markAgentSaved: import("@reduxjs/toolkit").ActionCreatorWithPayload<{
     id: string;
-}, "agentDefinition/markAgentSaved">, rollbackAgentOptimisticUpdate: import("@reduxjs/toolkit").ActionCreatorWithPayload<{
+}, "agentDefinition/markAgentSaved">, markAgentFieldSaved: import("@reduxjs/toolkit").ActionCreatorWithPayload<{
+    id: string;
+    field: keyof AgentDefinition;
+}, "agentDefinition/markAgentFieldSaved">, rollbackAgentOptimisticUpdate: import("@reduxjs/toolkit").ActionCreatorWithPayload<{
     id: string;
     snapshot: FieldSnapshot;
 }, "agentDefinition/rollbackAgentOptimisticUpdate">, undoAgentEdit: import("@reduxjs/toolkit").ActionCreatorWithPayload<{

package/dist/agents/redux/agent-definition/slice.js

@@ -493,6 +493,24 @@ const agentDefinitionSlice = createSlice({
       if (!record) return;
       markRecordClean(record);
     },
+    /**
+     * A SINGLE field was written to the database (inline edits such as the
+     * Agent Info Editor's name). Only that field becomes the clean baseline —
+     * every other staged edit (e.g. an Output Schema kind binding applied in
+     * Model Settings) must stay dirty so the main Save still persists it.
+     * `markAgentSaved` here used to wipe every dirty flag, silently dropping
+     * unrelated staged edits (feedback 222a2925).
+     */
+    markAgentFieldSaved(state, action) {
+      const { id, field } = action.payload;
+      const record = state.agents[id];
+      if (!record) return;
+      removeField(record._dirtyFields, field);
+      delete record._fieldHistory[field];
+      record._undoPast = record._undoPast.filter((e) => e.field !== field);
+      record._undoFuture = record._undoFuture.filter((e) => e.field !== field);
+      record._dirty = fieldFlagsSize(record._dirtyFields) > 0;
+    },
     /** Save failed — restore from the snapshot taken before the optimistic write. */
     rollbackAgentOptimisticUpdate(state, action) {
       const { id, snapshot } = action.payload;
@@ -636,6 +654,7 @@ const {
   resetAgentField,
   resetAllAgentFields,
   markAgentSaved,
+  markAgentFieldSaved,
   rollbackAgentOptimisticUpdate,
   undoAgentEdit,
   redoAgentEdit,
@@ -655,6 +674,7 @@ export {
   agentDefinitionSlice,
   clearAgentUndoHistory,
   slice_default as default,
+  markAgentFieldSaved,
   markAgentFieldsLoaded,
   markAgentSaved,
   mergePartialAgent,

package/dist/agents/types/agent-definition.types.d.ts

@@ -564,6 +564,32 @@ export interface LinkedAgentRef {
      * silently reported as "not linked".
      */
     deletedAt: string | null;
+    /** Archived agents are not offered as a sync partner. */
+    isArchived: boolean;
+    /**
+     * Who owns it, from the viewer's seat: "me", a person, an organization (an
+     * org-visible agent of someone else in an org the viewer can read) or the
+     * system. Drives every owner word in Linked Agent Sync.
+     */
+    ownerKind: "me" | "person" | "organization" | "system";
+    /** Person display name or organization name; null when not readable ("Someone else"). */
+    ownerName: string | null;
+    /** The viewer's level from `agx_get_access_level` (owner/admin/editor/viewer/public/none). */
+    accessLevel: string;
+    /**
+     * The builder's own save rule for a user agent: owner or editor. Always false
+     * for a system agent — that write is the registered admin feature, decided by
+     * the panel from `agent.system-sync`.
+     */
+    canEdit: boolean;
+}
+/**
+ * The agent this one was made from, when it still exists by id but the viewer
+ * can no longer open it (unshared, made private, archived, or deleted).
+ */
+export interface LostLinkedSource {
+    id: string;
+    reason: "unreadable" | "archived" | "deleted";
 }
 /**
  * Resolved linkage around a single agent. `source` is what it was copied from;
@@ -574,8 +600,10 @@ export interface LinkedCounterpartResult {
     self: LinkedAgentRef;
     source: LinkedAgentRef | null;
     derived: LinkedAgentRef[];
+    /** Set when `self.sourceAgentId` names an agent the viewer can no longer open. */
+    lostSource: LostLinkedSource | null;
 }
-/** Result of `createPersonalCopy` — idempotent personal copy of a system agent. */
+/** Result of `createPersonalCopy` — idempotent personal copy of any agent the viewer can read. */
 export interface PersonalCopyResult {
     agentId: string;
     /** True when a personal copy already existed and was returned instead of created. */

package/dist/host/ui-slots.js

@@ -410,7 +410,7 @@ const loadCodeEditHistoryThunk = slotFn("loadCodeEditHistoryThunk");
 const applySkillStreamEvent = slotFn("applySkillStreamEvent");
 const isSkillStreamEvent = slotFn("isSkillStreamEvent", () => false);
 const materializeMessageArtifacts = slotFn("materializeMessageArtifacts");
-const reconcileMessagesArtifacts = slotFn("reconcileMessagesArtifacts", () => void 0);
+const reconcileMessagesArtifacts = slotFn("reconcileMessagesArtifacts", async () => void 0);
 const noteBrowserActivity = slotFn("noteBrowserActivity");
 const selectCloudBrowserRunLive = slotFn("selectCloudBrowserRunLive");
 const adoptCloudBrowserRunFromStream = slotFn("adoptCloudBrowserRunFromStream");

package/dist/surfaces/lib/ui-surfaces-agent-writes.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Pure parsers for the UI Surfaces registry's agent write targets
+ * (`create_surfaces` / `update_surfaces` / `delete_surfaces` on
+ * `matrx-admin/ui-surfaces`). Each reads the agent's WHOLE list, reports every
+ * problem at once, and returns plans the page saves through its own service
+ * functions. No I/O here — unit-tested in `__tests__/ui-surfaces-agent-writes.test.ts`.
+ */
+export declare const DEFAULT_PARENT = "matrx-default/default";
+export declare const DEFAULT_SORT_ORDER = 150;
+/** What a parser needs to know about one existing surface. */
+export interface ExistingSurface {
+    name: string;
+    has_manifest: boolean;
+}
+export interface SurfaceWriteContext {
+    existing: readonly ExistingSurface[];
+    clientNames: readonly string[];
+}
+export interface CreateSurfacePlan {
+    name: string;
+    client_name: string;
+    label: string | null;
+    description: string;
+    parent_surface_name: string | null;
+    sort_order: number;
+    is_active: boolean;
+    executor_name: string | null;
+    url_pattern: string | null;
+}
+export interface UpdateSurfacePatch {
+    description?: string | null;
+    parent_surface_name?: string | null;
+    sort_order?: number;
+    is_active?: boolean;
+    executor_name?: string | null;
+    url_pattern?: string | null;
+}
+export interface UpdateSurfacePlan {
+    name: string;
+    patch: UpdateSurfacePatch;
+    changed: string[];
+}
+export declare function parseCreateSurfacesValue(value: unknown, ctx: SurfaceWriteContext): CreateSurfacePlan[];
+export declare function parseUpdateSurfacesValue(value: unknown, ctx: SurfaceWriteContext): UpdateSurfacePlan[];
+export declare function parseDeleteSurfacesValue(value: unknown, ctx: SurfaceWriteContext): ExistingSurface[];
+/** Fields the New surface dialog holds — the `new_surface_draft` target. */
+export interface NewSurfaceDraftFields {
+    client?: string;
+    local?: string;
+    /** A surface name, or null for a root surface. */
+    parent_surface_name?: string | null;
+    /** A tier label: Pages | Specialized | Overlays | Editor variants | Debug. */
+    tier?: string;
+    description?: string;
+}
+export declare const NEW_SURFACE_TIERS: readonly ["Pages", "Specialized", "Overlays", "Editor variants", "Debug"];
+/**
+ * Read the `new_surface_draft` value: an OBJECT with any of { name, parent_surface_name,
+ * tier, description }. Every problem is reported at once; nothing is saved.
+ */
+export declare function parseNewSurfaceDraftValue(value: unknown, ctx: SurfaceWriteContext): NewSurfaceDraftFields;

package/dist/surfaces/lib/ui-surfaces-agent-writes.js

@@ -0,0 +1,305 @@
+import {
+  collectProblems,
+  ListLevelProblem,
+  ProblemList,
+  readCollectionList,
+  repeatsProblem
+} from "../runtime/collection-write-targets.js";
+const DEFAULT_PARENT = "matrx-default/default";
+const DEFAULT_SORT_ORDER = 150;
+const LOCAL_RE = /^[a-z0-9][a-z0-9-/]*$/;
+const UPDATE_FIELDS = [
+  "description",
+  "parent_surface_name",
+  "sort_order",
+  "is_active",
+  "executor_name",
+  "url_pattern"
+];
+const MANIFEST_OWNED = /* @__PURE__ */ new Set([
+  "description",
+  "parent_surface_name",
+  "is_active",
+  "url_pattern"
+]);
+function asObject(raw) {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+    throw new Error("must be an object.");
+  return raw;
+}
+function optionalText(obj, key, problems, nullable) {
+  if (!(key in obj)) return void 0;
+  const v = obj[key];
+  if (v === null && nullable) return null;
+  if (typeof v !== "string") {
+    problems.add(`${key} must be a string${nullable ? " or null" : ""}.`);
+    return void 0;
+  }
+  return v.trim();
+}
+function readSortOrder(obj, problems) {
+  if (!("sort_order" in obj)) return void 0;
+  const v = obj.sort_order;
+  if (typeof v !== "number" || !Number.isInteger(v) || v < 100) {
+    problems.add(
+      "sort_order must be a whole number of at least 100 (0-99 is reserved)."
+    );
+    return void 0;
+  }
+  return v;
+}
+function readParent(obj, names, problems, self) {
+  const parent = optionalText(obj, "parent_surface_name", problems, true);
+  if (typeof parent === "string") {
+    if (!parent) return null;
+    if (parent === self) {
+      problems.add("a surface cannot be its own parent.");
+      return void 0;
+    }
+    if (!names.has(parent)) {
+      problems.add(`parent_surface_name "${parent}" is not a surface in the registry.`);
+      return void 0;
+    }
+  }
+  return parent;
+}
+function nameOfRaw(raw) {
+  if (typeof raw === "string") return raw;
+  if (raw && typeof raw === "object" && typeof raw.name === "string")
+    return raw.name;
+  return void 0;
+}
+function parseCreateSurfacesValue(value, ctx) {
+  const target = "create_surfaces";
+  const list = readCollectionList(target, "surfaces", value);
+  const names = new Set(ctx.existing.map((s) => s.name));
+  const clients = new Set(ctx.clientNames);
+  return collectProblems(
+    target,
+    list,
+    (raw) => {
+      const obj = asObject(raw);
+      const problems = new ProblemList(target);
+      const name = typeof obj.name === "string" ? obj.name.trim() : "";
+      let client = "";
+      if (!name) problems.add('name is required ("<client>/<local>").');
+      else {
+        const slash = name.indexOf("/");
+        client = slash > 0 ? name.slice(0, slash) : "";
+        const local = slash > 0 ? name.slice(slash + 1) : "";
+        if (!client || !local)
+          problems.add(`name "${name}" must be "<client>/<local>".`);
+        else {
+          if (!clients.has(client))
+            problems.add(
+              `client "${client}" is not a UI client (one of: ${[...clients].join(", ")}).`
+            );
+          if (!LOCAL_RE.test(local))
+            problems.add(
+              `the local part "${local}" may use only lowercase letters, digits, hyphens and slashes.`
+            );
+        }
+      }
+      const label = optionalText(obj, "label", problems, true);
+      const description = optionalText(obj, "description", problems, true);
+      const parent = readParent(obj, names, problems);
+      const sort = readSortOrder(obj, problems);
+      const executor = optionalText(obj, "executor_name", problems, true);
+      const url = optionalText(obj, "url_pattern", problems, true);
+      let isActive = true;
+      if ("is_active" in obj) {
+        if (typeof obj.is_active !== "boolean")
+          problems.add("is_active must be true or false.");
+        else isActive = obj.is_active;
+      }
+      problems.throwIfAny();
+      return {
+        name,
+        client_name: client,
+        label: label || null,
+        description: description ?? "",
+        parent_surface_name: parent === void 0 ? DEFAULT_PARENT : parent,
+        sort_order: sort ?? DEFAULT_SORT_ORDER,
+        is_active: isActive,
+        executor_name: executor || null,
+        url_pattern: url || null
+      };
+    },
+    {
+      nameOf: nameOfRaw,
+      listChecks: (items) => [
+        repeatsProblem(target, items.map((i) => i.name), "name"),
+        ...items.filter((i) => i.name && names.has(i.name)).map(
+          (i) => `${target}[${i.index}] "${i.name}" already exists in the registry \u2014 use update_surfaces to change it.`
+        )
+      ]
+    }
+  );
+}
+function parseUpdateSurfacesValue(value, ctx) {
+  const target = "update_surfaces";
+  const list = readCollectionList(target, "surfaces", value);
+  const byName = new Map(ctx.existing.map((s) => [s.name, s]));
+  const names = new Set(byName.keys());
+  return collectProblems(
+    target,
+    list,
+    (raw) => {
+      const obj = asObject(raw);
+      const name = typeof obj.name === "string" ? obj.name.trim() : "";
+      if (!name) throw new Error("name is required (from surfaces).");
+      const current = byName.get(name);
+      if (!current)
+        throw new ListLevelProblem(
+          `${target}: "${name}" is not a surface in the registry.`
+        );
+      const problems = new ProblemList(target);
+      const unknown = Object.keys(obj).filter(
+        (k) => k !== "name" && !UPDATE_FIELDS.includes(k)
+      );
+      if (unknown.length)
+        problems.add(
+          `cannot change ${unknown.join(", ")} here (changeable: ${UPDATE_FIELDS.join(", ")}).`
+        );
+      if (current.has_manifest) {
+        const owned = Object.keys(obj).filter((k) => MANIFEST_OWNED.has(k));
+        if (owned.length)
+          problems.add(
+            `"${name}" has a code manifest, which owns ${owned.join(", ")} \u2014 Sync manifests would overwrite the change. Change the manifest in code; here only sort_order and executor_name may change.`
+          );
+      }
+      const patch = {};
+      const description = optionalText(obj, "description", problems, true);
+      if (description !== void 0) patch.description = description || null;
+      const parent = readParent(obj, names, problems, name);
+      if (parent !== void 0) patch.parent_surface_name = parent;
+      const sort = readSortOrder(obj, problems);
+      if (sort !== void 0) patch.sort_order = sort;
+      if ("is_active" in obj) {
+        if (typeof obj.is_active !== "boolean")
+          problems.add("is_active must be true or false.");
+        else patch.is_active = obj.is_active;
+      }
+      const executor = optionalText(obj, "executor_name", problems, true);
+      if (executor !== void 0) patch.executor_name = executor || null;
+      const url = optionalText(obj, "url_pattern", problems, true);
+      if (url !== void 0) patch.url_pattern = url || null;
+      problems.throwIfAny();
+      const changed = Object.keys(patch);
+      if (changed.length === 0) throw new Error("sends no field to change.");
+      return { name, patch, changed };
+    },
+    {
+      nameOf: nameOfRaw,
+      listChecks: (items) => [
+        repeatsProblem(target, items.map((i) => i.name), "surface")
+      ]
+    }
+  );
+}
+function parseDeleteSurfacesValue(value, ctx) {
+  const target = "delete_surfaces";
+  const list = readCollectionList(target, "surfaces", value);
+  const byName = new Map(ctx.existing.map((s) => [s.name, s]));
+  return collectProblems(
+    target,
+    list,
+    (raw) => {
+      const name = nameOfRaw(raw)?.trim();
+      if (!name) throw new Error('must be a surface name or { "name": "\u2026" }.');
+      const current = byName.get(name);
+      if (!current)
+        throw new ListLevelProblem(
+          `${target}: "${name}" is not a surface in the registry.`
+        );
+      if (current.has_manifest)
+        throw new Error(
+          `"${name}" has a code manifest, so code owns it: remove the manifest in code, or deactivate it instead.`
+        );
+      return current;
+    },
+    {
+      nameOf: nameOfRaw,
+      listChecks: (items) => [
+        repeatsProblem(target, items.map((i) => i.name), "surface")
+      ]
+    }
+  );
+}
+const NEW_SURFACE_TIERS = [
+  "Pages",
+  "Specialized",
+  "Overlays",
+  "Editor variants",
+  "Debug"
+];
+function parseNewSurfaceDraftValue(value, ctx) {
+  const target = "new_surface_draft";
+  const problems = new ProblemList(target);
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    problems.add(
+      "new_surface_draft expects a JSON OBJECT like { name, parent_surface_name, tier, description }."
+    );
+    problems.throwIfAny();
+  }
+  const obj = value;
+  const allowed = ["name", "parent_surface_name", "tier", "description"];
+  const unknown = Object.keys(obj).filter((k) => !allowed.includes(k));
+  if (unknown.length)
+    problems.add(
+      `the dialog has no ${unknown.join(", ")} field (fields: ${allowed.join(", ")}).`
+    );
+  const out = {};
+  if ("name" in obj) {
+    const name = typeof obj.name === "string" ? obj.name.trim() : "";
+    const slash = name.indexOf("/");
+    const client = slash > 0 ? name.slice(0, slash) : "";
+    const local = slash > 0 ? name.slice(slash + 1) : "";
+    if (!client || !local) problems.add(`name must be "<client>/<local>".`);
+    else {
+      if (!ctx.clientNames.includes(client))
+        problems.add(
+          `client "${client}" is not a UI client (one of: ${ctx.clientNames.join(", ")}).`
+        );
+      if (!LOCAL_RE.test(local))
+        problems.add(
+          `the local part "${local}" may use only lowercase letters, digits, hyphens and slashes.`
+        );
+      if (ctx.existing.some((s) => s.name === name))
+        problems.add(`"${name}" already exists in the registry.`);
+      out.client = client;
+      out.local = local;
+    }
+  }
+  if ("parent_surface_name" in obj) {
+    const parent = readParent(
+      obj,
+      new Set(ctx.existing.map((s) => s.name)),
+      problems
+    );
+    if (parent !== void 0) out.parent_surface_name = parent;
+  }
+  if ("tier" in obj) {
+    if (typeof obj.tier !== "string" || !NEW_SURFACE_TIERS.includes(obj.tier))
+      problems.add(`tier must be one of: ${NEW_SURFACE_TIERS.join(", ")}.`);
+    else out.tier = obj.tier;
+  }
+  if ("description" in obj) {
+    if (typeof obj.description !== "string")
+      problems.add("description must be a string.");
+    else out.description = obj.description;
+  }
+  problems.throwIfAny();
+  if (Object.keys(out).length === 0)
+    throw new Error("new_surface_draft sends no field to fill. Nothing was changed.");
+  return out;
+}
+export {
+  DEFAULT_PARENT,
+  DEFAULT_SORT_ORDER,
+  NEW_SURFACE_TIERS,
+  parseCreateSurfacesValue,
+  parseDeleteSurfacesValue,
+  parseNewSurfaceDraftValue,
+  parseUpdateSurfacesValue
+};

package/dist/surfaces/lib/ui-surfaces-scope.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Pure scope builder for the UI Surfaces registry page
+ * (`matrx-admin/ui-surfaces`, `/administration/ui/surfaces`).
+ *
+ * Called by `SurfacesContainer` with state the page already rendered — it
+ * never fetches (the runtime polls it every 400 ms). Not loaded yet → the
+ * registry keys are omitted; a failed load reports only `load_state`.
+ */
+import type { SurfaceScopePayload } from "../types.js";
+import { type UiSurfaceScopeEntry, type UiSurfacesFilterScope, type UiSurfacesRegistryCounts } from "../manifests/admin-ui-surfaces.manifest.js";
+import { type SurfaceWithStats } from "../services/surfaces.service.js";
+import type { SurfacesFilterState } from "../host-surface-types.js";
+import type { NewSurfaceDraftScope } from "../host-surface-types.js";
+/** How many rows `surface_list` carries up front (~4,000 chars). */
+export declare const SURFACE_LIST_MAX_ROWS = 40;
+export type UiSurfacesDialog = "new_surface" | "new_client" | "candidates" | "sync_manifests" | "drift_report";
+export interface UiSurfacesScopeInput {
+    loading: boolean;
+    error: string | null;
+    /** Every row loaded (empty until the first successful load). */
+    surfaces: readonly SurfaceWithStats[];
+    /** The rows after the page's own filters, in the page's order. */
+    visible: readonly SurfaceWithStats[];
+    clientNames: readonly string[];
+    manifestedNames: ReadonlySet<string>;
+    filters: SurfacesFilterState;
+    readinessCounts: UiSurfacesRegistryCounts["readiness"];
+    candidatesAvailable: number;
+    /** The drift report's total (countDriftIssues); null until it loads. */
+    driftIssues: number | null;
+    peekedName: string | null;
+    openDialog: UiSurfacesDialog | null;
+    /** The New surface dialog's live values; null while it is closed. */
+    newSurfaceDraft: NewSurfaceDraftScope | null;
+}
+export declare function filtersToScope(f: SurfacesFilterState): UiSurfacesFilterScope;
+export declare function toSurfaceScopeEntry(row: SurfaceWithStats, manifestedNames: ReadonlySet<string>): UiSurfaceScopeEntry;
+/** The condensed on-screen list as one XML bundle. */
+export declare function buildSurfaceListBundle(visible: readonly SurfaceWithStats[], manifestedNames: ReadonlySet<string>, filters: UiSurfacesFilterScope): string;
+export declare function buildUiSurfacesScope(input: UiSurfacesScopeInput): SurfaceScopePayload;

package/dist/surfaces/lib/ui-surfaces-scope.js

@@ -0,0 +1,116 @@
+import { getManifest } from "../runtime/registry.js";
+import {
+  createAdminUiSurfacesScope
+} from "../manifests/admin-ui-surfaces.manifest.js";
+import {
+  readinessBucketOf,
+  tierFor
+} from "../services/surfaces.service.js";
+import { surfaceCheckState } from "../utils/surface-check-ledger.js";
+import { xmlElement, xmlList } from "../runtime/context-bundle.js";
+const SURFACE_LIST_MAX_ROWS = 40;
+function filtersToScope(f) {
+  return {
+    client: f.client === "__all__" ? "all" : f.client,
+    status: f.status,
+    check_age: f.checked,
+    manifest: f.manifest,
+    parent: f.parent === "__all__" ? "all" : f.parent === "__none__" ? "none" : f.parent,
+    readiness: f.readiness
+  };
+}
+function toSurfaceScopeEntry(row, manifestedNames) {
+  return {
+    name: row.name,
+    label: row.label ?? null,
+    client_name: row.client_name,
+    executor_name: row.executor_name ?? null,
+    parent_surface_name: row.parent_surface_name ?? null,
+    sort_order: row.sort_order,
+    tier: tierFor(row.sort_order).label,
+    is_active: row.is_active !== false,
+    readiness: readinessBucketOf(row),
+    readiness_note: row.readiness_note ?? null,
+    has_manifest: manifestedNames.has(row.name),
+    value_count: row.surfaceValueCount,
+    declared_value_count: getManifest(row.name)?.values.length ?? null,
+    agent_count: row.agentCount,
+    tool_count: row.toolCount,
+    check_state: surfaceCheckState(row),
+    last_checked_at: row.last_checked_at ?? null,
+    last_checked_by: row.last_checked_by ?? null,
+    url_pattern: row.url_pattern ?? null,
+    description: row.description ?? null
+  };
+}
+function buildSurfaceListBundle(visible, manifestedNames, filters) {
+  const active = Object.fromEntries(
+    Object.entries(filters).filter(([, v]) => v !== "all")
+  );
+  return xmlList(
+    "surfaces",
+    visible,
+    (row) => xmlElement("s", {
+      name: row.name,
+      label: row.label,
+      client: row.client_name,
+      parent: row.parent_surface_name,
+      tier: `${tierFor(row.sort_order).label} ${row.sort_order}`,
+      readiness: readinessBucketOf(row),
+      values: row.surfaceValueCount,
+      declared: getManifest(row.name)?.values.length,
+      agents: row.agentCount,
+      tools: row.toolCount,
+      checked: surfaceCheckState(row),
+      active: row.is_active !== false,
+      manifest: manifestedNames.has(row.name)
+    }),
+    { maxRows: SURFACE_LIST_MAX_ROWS, attrs: active }
+  ) || '<surfaces total="0"/>';
+}
+function buildUiSurfacesScope(input) {
+  const filters = filtersToScope(input.filters);
+  const extras = {
+    ...input.peekedName ? { peeked_surface: input.peekedName } : {},
+    ...input.openDialog ? { open_dialog: input.openDialog } : {},
+    ...input.newSurfaceDraft ? { new_surface_draft: input.newSurfaceDraft } : {}
+  };
+  if (input.error) {
+    return createAdminUiSurfacesScope({
+      load_state: `error: ${input.error}`,
+      filters,
+      ...extras
+    });
+  }
+  if (input.loading && input.surfaces.length === 0) {
+    return createAdminUiSurfacesScope({ load_state: "loading", filters, ...extras });
+  }
+  const surfaces = input.surfaces.map(
+    (s) => toSurfaceScopeEntry(s, input.manifestedNames)
+  );
+  return createAdminUiSurfacesScope({
+    load_state: "ready",
+    filters,
+    surface_list: buildSurfaceListBundle(input.visible, input.manifestedNames, filters),
+    surfaces,
+    registry_counts: {
+      total: surfaces.length,
+      active: surfaces.filter((s) => s.is_active).length,
+      manifests: input.manifestedNames.size,
+      unused: surfaces.filter((s) => s.agent_count === 0 && s.tool_count === 0).length,
+      visible: input.visible.length,
+      readiness: input.readinessCounts,
+      candidates_available: input.candidatesAvailable,
+      ...input.driftIssues !== null ? { drift_issues: input.driftIssues } : {}
+    },
+    client_names: [...input.clientNames],
+    ...extras
+  });
+}
+export {
+  SURFACE_LIST_MAX_ROWS,
+  buildSurfaceListBundle,
+  buildUiSurfacesScope,
+  filtersToScope,
+  toSurfaceScopeEntry
+};

package/dist/tool-call-visualization/effects/toolStateEffects.d.ts

@@ -27,7 +27,7 @@
  * that dispatches the feature's refetch thunk(s). Known not-yet-covered
  * writers (no canonical Redux refetch today, or their state is hook-local):
  * picklist (session-cached `usePickListDetail`), dictionary, workbook,
- * dataset/usertable, document. The working document is already reconciled by
+ * dataset, document. The working document is already reconciled by
  * its own `context_changed` re-read; the scratchpad is agent-readonly.
  */
 import type { ChatRootState } from "../../store/root-state.js";

package/dist/tool-call-visualization/registry/registry.js

@@ -1066,7 +1066,6 @@ const APP_FEATURE_TOOL_NAMES = /* @__PURE__ */ new Set([
   "user_todos",
   "document",
   "dataset",
-  "usertable_create",
   "knowledge_search",
   "document_search",
   "knowledge_browse",
@@ -1202,7 +1201,6 @@ const TOOL_GLYPHS = {
   update_plan: { icon: ListTodo, accent: "primary" },
   document: { icon: FileText, accent: "slate" },
   dataset: { icon: Table2, accent: "cyan" },
-  usertable_create: { icon: Table2, accent: "cyan" },
   workbook: { icon: Sheet, accent: "green" },
   dictionary: { icon: BookText, accent: "amber" },
   note: { icon: NotebookPen, accent: "amber" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-matrx/chat",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "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",
@@ -202,23 +202,23 @@
     "uuid": "^14.0.2",
     "zod": "^4.6.5",
     "@ai-matrx/agents": "latest",
-    "@ai-matrx/alchemy": "latest",
     "@ai-matrx/associations": "latest",
+    "@ai-matrx/alchemy": "latest",
     "@ai-matrx/browser-audio": "latest",
     "@ai-matrx/canvas": "latest",
-    "@ai-matrx/content-ir": "latest",
     "@ai-matrx/content-ir-react": "latest",
-    "@ai-matrx/data": "latest",
-    "@ai-matrx/design-system": "latest",
     "@ai-matrx/diff": "latest",
+    "@ai-matrx/data": "latest",
     "@ai-matrx/icons": "latest",
-    "@ai-matrx/kit": "latest",
+    "@ai-matrx/design-system": "latest",
     "@ai-matrx/media": "latest",
+    "@ai-matrx/kit": "latest",
     "@ai-matrx/print": "latest",
     "@ai-matrx/realtime": "latest",
     "@ai-matrx/records": "latest",
     "@ai-matrx/records-ui": "latest",
-    "@ai-matrx/tap-target": "latest"
+    "@ai-matrx/tap-target": "latest",
+    "@ai-matrx/content-ir": "latest"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.5",