@ai-matrx/chat 0.3.4 → 0.3.6

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @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
+
+- The Chat-mode agent pill's menu starts with "This chat's agent": its row opens the agent menu's own
+  peek card (`AgentDetailCard`) — view, open, Sneak Peek, and Duplicate when the agent is not yours.
+- `agents/components/shared/AgentPeekDuplicateButton` moved here from matrx-frontend (one Duplicate for
+  every peek). It now opens the copy's page in a NEW TAB instead of navigating away from the chat.
+- Needs `@ai-matrx/agents` 0.49.0.
+- The composer's + (Chat Options) is tinted only when something was added — no longer blue on every fresh
+  chat. The Chat Options window lists its sections as start-aligned rows (`Tile`), not centred buttons.
+- Consumer action: import `AgentPeekDuplicateButton` from
+  `@ai-matrx/chat/agents/components/shared/AgentPeekDuplicateButton` and delete the app's copy.
+
 ## 0.3.4 — 2026-10-07
 ### Re-sync before matrx-frontend consumes the published package (P27)
 

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/RunControlsMenu.js

@@ -89,7 +89,7 @@ function RunControlsMenu({
     Button,
     {
       variant: "quiet",
-      tone: rc.addedCount > 0 || rc.isCustomized ? "primary" : void 0,
+      tone: rc.addedCount > 0 ? "primary" : void 0,
       icon: /* @__PURE__ */ jsx(TriggerIcon, {}),
       tabIndex: variant === "plus" ? -1 : void 0,
       title: "Chat Options",

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

@@ -0,0 +1,4 @@
+export declare function ComposerAgentPeek({ agentId, onDone }: {
+    agentId: string;
+    onDone?: () => void;
+}): import("react").JSX.Element | null;

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

@@ -0,0 +1,50 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import { useEffect } from "react";
+import { AgentDetailCard, useAgentCatalogState } from "@ai-matrx/agents/catalog/react";
+import { useAppDispatch, useAppSelector } from "../../../../../store/hooks.js";
+import { selectAgentById, selectAgentReadyForBuilder } from "../../../../redux/agent-definition/selectors.js";
+import { fetchFullAgent } from "../../../../redux/agent-definition/thunks.js";
+import { AgentPeekDuplicateButton } from "../../../shared/AgentPeekDuplicateButton.js";
+function ComposerAgentPeek({ agentId, onDone }) {
+  const dispatch = useAppDispatch();
+  const row = useAgentCatalogState((state) => state.byId[agentId]);
+  const record = useAppSelector((state) => selectAgentById(state, agentId));
+  const isReady = useAppSelector((state) => selectAgentReadyForBuilder(state, agentId));
+  useEffect(() => {
+    if (!isReady) void dispatch(fetchFullAgent(agentId)).unwrap().catch(() => void 0);
+  }, [dispatch, agentId, isReady]);
+  const agent = row ?? (record ? {
+    id: record.id,
+    name: record.name,
+    description: record.description,
+    category: record.category,
+    tags: record.tags,
+    agentType: record.agentType,
+    modelId: record.modelId,
+    isActive: record.isActive,
+    isArchived: record.isArchived,
+    isFavorite: record.isFavorite,
+    createdBy: record.createdBy,
+    organizationId: record.organizationId,
+    taskId: record.taskId,
+    sourceAgentId: record.sourceAgentId,
+    createdAt: record.createdAt,
+    updatedAt: record.updatedAt,
+    isOwner: record.isOwner,
+    accessLevel: record.accessLevel,
+    sharedByEmail: record.sharedByEmail,
+    orchestra: null
+  } : null);
+  if (!agent) return null;
+  return /* @__PURE__ */ jsx(
+    AgentDetailCard,
+    {
+      agent,
+      actions: /* @__PURE__ */ jsx(AgentPeekDuplicateButton, { agentId, onStart: onDone })
+    }
+  );
+}
+export {
+  ComposerAgentPeek
+};

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

@@ -36,6 +36,7 @@ import { composerShows } from "./composer-mode-visibility.js";
 import { composerPillClass } from "./composer-chip.js";
 import { useComposerAgent, useEffectiveModelId } from "./useComposerAgent.js";
 import { useComposerAgentFilter } from "./useComposerAgentFilter.js";
+import { ComposerAgentPeek } from "./ComposerAgentPeek.js";
 import { presentOrganizationRefusal } from "../../../../../host/org.js";
 import { ensureOrgId, isOrganizationSelectionCancelled } from "../../../../../host/org.js";
 function pillLabel(info, mode) {
@@ -150,6 +151,17 @@ function ComposerAgentPill({ conversationId, mode, size, agentControl, menuSide,
     )
   ] });
 }
+function ThisAgentRow({ info, close }) {
+  if (!info.agentId) return null;
+  return /* @__PURE__ */ jsx(
+    ComposerSubmenu,
+    {
+      row: { icon: Webhook, label: info.agentName ?? "Agent", description: "View, open or duplicate" },
+      panelClassName: "w-[340px] h-[420px] p-0",
+      children: /* @__PURE__ */ jsx(ComposerAgentPeek, { agentId: info.agentId, onDone: close })
+    }
+  );
+}
 function ChatPresetsPanel({
   conversationId,
   info,
@@ -169,7 +181,7 @@ function ChatPresetsPanel({
   if (!onSelectAgent) {
     return /* @__PURE__ */ jsxs(Fragment, { children: [
       /* @__PURE__ */ jsx(ComposerMenuLabel, { children: "Agent" }),
-      /* @__PURE__ */ jsx(ComposerMenuRow, { label: info.agentName ?? "Agent", checked: true }),
+      /* @__PURE__ */ jsx(ThisAgentRow, { info, close }),
       /* @__PURE__ */ jsx(ComposerMenuHelp, { children: "This page always answers with this agent." }),
       /* @__PURE__ */ jsx(ComposerMenuDivider, {}),
       /* @__PURE__ */ jsx(ComposerMenuLabel, { children: "Model for this chat" }),
@@ -229,6 +241,9 @@ function ChatPresetsPanel({
     void savePersonalDefault("chat_default_offering", offeringId ?? "");
   };
   return /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsx(ComposerMenuLabel, { children: "This chat's agent" }),
+    /* @__PURE__ */ jsx(ThisAgentRow, { info, close }),
+    /* @__PURE__ */ jsx(ComposerMenuDivider, {}),
     /* @__PURE__ */ jsx(ComposerMenuLabel, { children: "Chat agents" }),
     info.presets.map((preset) => /* @__PURE__ */ jsx(
       ComposerMenuRow,

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

@@ -0,0 +1,8 @@
+export declare function AgentPeekDuplicateButton({ agentId, onStart, }: {
+    agentId: string;
+    /**
+     * 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

@@ -0,0 +1,66 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import { useState } from "react";
+import { CopyPlus, Loader2 } from "lucide-react";
+import { Button } from "@ai-matrx/design-system/controls";
+import { getUserMessage } from "@ai-matrx/agents/matrx";
+import { useAppDispatch, useAppSelector } from "../../../store/hooks.js";
+import { selectUserId } from "../../../host/identity.js";
+import { getBuilderDoor } from "../../../host/builder-door.js";
+import { toast } from "../../../host/notify.js";
+import { isOrganizationSelectionCancelled } from "../../../host/org.js";
+import { selectAgentById, selectAgentReadyForBuilder } from "../../redux/agent-definition/selectors.js";
+import { agentGoHref } from "../../addressing/agentAddress.js";
+function AgentPeekDuplicateButton({
+  agentId,
+  onStart
+}) {
+  const dispatch = useAppDispatch();
+  const userId = useAppSelector(selectUserId);
+  const record = useAppSelector((state) => selectAgentById(state, agentId));
+  const isReady = useAppSelector((state) => selectAgentReadyForBuilder(state, agentId));
+  const [busy, setBusy] = useState(false);
+  const door = getBuilderDoor();
+  if (!door || !isReady || !record) return null;
+  const ownsIt = record.isOwner === true || record.createdBy != null && record.createdBy === userId;
+  if (ownsIt) return null;
+  const duplicate = async () => {
+    if (busy) return;
+    setBusy(true);
+    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;
+        toast.success(`Duplicated "${record.name}" \u2014 opened in a new tab`);
+      } else {
+        toast.success(`Duplicated "${record.name}"`, {
+          description: "Your browser kept the new tab closed",
+          action: { label: "Open", onClick: () => window.open(href, "_blank", "noopener") }
+        });
+      }
+    } catch (err) {
+      if (!isOrganizationSelectionCancelled(err)) {
+        toast.error("Could not duplicate agent", { description: getUserMessage(err) });
+      }
+    } finally {
+      setBusy(false);
+    }
+  };
+  return /* @__PURE__ */ jsx(
+    Button,
+    {
+      icon: busy ? /* @__PURE__ */ jsx(Loader2, { className: "animate-spin" }) : /* @__PURE__ */ jsx(CopyPlus, {}),
+      variant: "outline",
+      onClick: duplicate,
+      disabled: busy,
+      title: "Make your own copy of this agent, in a new tab",
+      children: "Duplicate"
+    }
+  );
+}
+export {
+  AgentPeekDuplicateButton
+};

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/dist/window-panels/windows/agents/RunControlsWindow.js

@@ -1,5 +1,5 @@
 "use client";
-import { jsx, jsxs } from "react/jsx-runtime";
+import { jsx } from "react/jsx-runtime";
 import { useState } from "react";
 import { useAppDispatch } from "../../../store/hooks.js";
 import { closeOverlay, CHAT_WINDOWS } from "../../../host/windows.js";
@@ -20,7 +20,7 @@ import { selectInstanceAgentId } from "../../../agents/redux/execution-system/in
 import { selectAgentName } from "../../../agents/redux/agent-definition/selectors.js";
 import { NonEditableContextMenu } from "../../../host/ui-slots.js";
 import { buildAgentMenuSection, agentEntityRef } from "../../../agents/menu/agent-actions.js";
-import { Button } from "@ai-matrx/design-system/controls";
+import { Tile } from "@ai-matrx/design-system/controls";
 const OVERLAY_ID = CHAT_WINDOWS.runControlsWindow;
 function RunControlsWindowInner({
   conversationId,
@@ -104,10 +104,23 @@ function RunControlsWindowInner({
           children: rc.tabs.map((t) => {
             const Icon = t.icon;
             const on = activeTab === t.id;
-            return /* @__PURE__ */ jsxs(Button, { variant: "quiet", pressed: on, icon: /* @__PURE__ */ jsx(Icon, {}), role: "tab", "aria-selected": on, onClick: () => setTab(t.id), children: [
-              /* @__PURE__ */ jsx("span", { className: "min-w-0 flex-1 truncate", children: t.label }),
-              rc.tabTrailing(t.id)
-            ] }, t.id);
+            return (
+              // A list of sections is rows, start-aligned — never centred buttons.
+              /* @__PURE__ */ jsx(
+                Tile,
+                {
+                  variant: "quiet",
+                  selected: on,
+                  icon: /* @__PURE__ */ jsx(Icon, {}),
+                  title: t.label,
+                  end: rc.tabTrailing(t.id),
+                  role: "tab",
+                  "aria-selected": on,
+                  onClick: () => setTab(t.id)
+                },
+                t.id
+              )
+            );
           })
         }
       ),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-matrx/chat",
-  "version": "0.3.4",
+  "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",
@@ -201,24 +201,24 @@
     "server-only": "^0.0.1",
     "uuid": "^14.0.2",
     "zod": "^4.6.5",
-    "@ai-matrx/alchemy": "latest",
     "@ai-matrx/agents": "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/diff": "latest",
     "@ai-matrx/data": "latest",
+    "@ai-matrx/icons": "latest",
     "@ai-matrx/design-system": "latest",
-    "@ai-matrx/associations": "latest",
-    "@ai-matrx/diff": "latest",
-    "@ai-matrx/kit": "latest",
     "@ai-matrx/media": "latest",
-    "@ai-matrx/icons": "latest",
+    "@ai-matrx/kit": "latest",
+    "@ai-matrx/print": "latest",
     "@ai-matrx/realtime": "latest",
     "@ai-matrx/records": "latest",
-    "@ai-matrx/print": "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",