@ai-matrx/chat 0.1.77 → 0.2.1

package/dist/agents/hooks/useAgentModelLabel.js

@@ -0,0 +1,27 @@
+"use client";
+import { useAppSelector } from "../../store/hooks.js";
+import {
+  selectAgentModelId,
+  selectAgentOfferingPin
+} from "../redux/agent-definition/selectors.js";
+import {
+  selectModelLabelById,
+  selectModelLabelWithClass
+} from "../model-registry/modelRegistrySlice.js";
+import { useModelClassLabels } from "../../host/model-class.js";
+function useAgentModelLabel(agentId) {
+  useModelClassLabels();
+  const modelId = useAppSelector(
+    (state) => agentId ? selectAgentModelId(state, agentId) : null
+  );
+  const offeringId = useAppSelector(
+    (state) => agentId ? selectAgentOfferingPin(state, agentId) : void 0
+  );
+  const label = useAppSelector(
+    (state) => offeringId === void 0 ? selectModelLabelById(state, modelId) : selectModelLabelWithClass(state, modelId, offeringId)
+  );
+  return { modelId, offeringId, label };
+}
+export {
+  useAgentModelLabel
+};

package/dist/agents/hooks/useAgentRunSurfaceScope.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Build the surface scope for `matrx-user/agent-run`.
+ *
+ * Snapshots, at trigger time, everything the run page has loaded: the agent
+ * definition that ran, the request that went in, the transcript that came
+ * back, tool calls, completion stats, and live status.
+ *
+ * Reads through the store (not `useAppSelector`) so the returned builder is
+ * stable and always pulls fresh state — the Agents chrome calls it only when
+ * the user hits Run, which may be many renders after mount.
+ *
+ * Mounted by `AgentRunnerPage` via `<SurfaceRuntimeProvider>`, and only for
+ * the standalone run route: the same component backs the `/code` workspace,
+ * which is a different surface.
+ */
+import type { SurfaceScopePayload } from "../../surfaces/types.js";
+export interface AgentRunSurfaceScopeArgs {
+    agentId: string;
+    /** Active conversation for the run page. Undefined before one exists. */
+    conversationId: string | undefined;
+    /** Product surface that owns the run (`"agent-runner"` for /agents/[id]/run). */
+    sourceFeature: string;
+}
+export declare function useAgentRunSurfaceScope({ agentId, conversationId, sourceFeature, }: AgentRunSurfaceScopeArgs): () => SurfaceScopePayload;

package/dist/agents/hooks/useAgentRunSurfaceScope.js

@@ -0,0 +1,103 @@
+import { useCallback } from "react";
+import { useAppStore } from "../../store/hooks.js";
+import { createAgentRunScope } from "../../surfaces/manifests/agent-run.manifest.js";
+import { extractAgentSystemInstruction } from "../utils/agent-system-instruction.js";
+import {
+  selectAgentDefinition,
+  selectAgentDescription,
+  selectAgentModelId,
+  selectAgentName,
+  selectAgentSystemMessage,
+  selectAgentTools,
+  selectAgentVariableDefinitions,
+  selectAgentVersion
+} from "../redux/agent-definition/selectors.js";
+import {
+  extractFlatText,
+  selectConversationMessages,
+  selectConversationTitle,
+  selectMessageCount
+} from "../redux/execution-system/messages/messages.selectors.js";
+import { selectInstance } from "../redux/execution-system/conversations/conversations.selectors.js";
+import { selectUserInputText } from "../redux/execution-system/instance-user-input/instance-user-input.selectors.js";
+import { selectResolvedVariables } from "../redux/execution-system/instance-variable-values/instance-variable-values.selectors.js";
+import { selectInstanceContextEntries } from "../redux/execution-system/instance-context/instance-context.selectors.js";
+import {
+  selectIsExecuting,
+  selectIsStreaming,
+  selectLatestAccumulatedReasoning,
+  selectLatestAnswerText,
+  selectLatestCompletion,
+  selectLatestError,
+  selectLatestToolLifecycles
+} from "../redux/execution-system/selectors/aggregate.selectors.js";
+function useAgentRunSurfaceScope({
+  agentId,
+  conversationId,
+  sourceFeature
+}) {
+  const store = useAppStore();
+  return useCallback(() => {
+    const state = store.getState();
+    const definition = selectAgentDefinition(state, agentId);
+    const agentScope = {
+      agent_id: agentId,
+      agent_name: selectAgentName(state, agentId) ?? void 0,
+      agent_description: selectAgentDescription(state, agentId) ?? void 0,
+      agent_version: selectAgentVersion(state, agentId) ?? void 0,
+      agent_system_instruction: extractAgentSystemInstruction(
+        selectAgentSystemMessage(state, agentId)
+      ),
+      agent_model_id: selectAgentModelId(state, agentId) ?? void 0,
+      agent_tools: selectAgentTools(state, agentId) ?? void 0,
+      agent_variable_definitions: selectAgentVariableDefinitions(state, agentId) ?? void 0,
+      agent_json: definition ?? void 0,
+      run_source_feature: sourceFeature
+    };
+    if (!conversationId) return createAgentRunScope(agentScope);
+    const instance = selectInstance(conversationId)(state);
+    const messages = selectConversationMessages(conversationId)(state);
+    const latestUserMessage = [...messages].reverse().find((m) => m.role === "user");
+    const completion = selectLatestCompletion(conversationId)(state);
+    const error = selectLatestError(conversationId)(state);
+    const reasoning = selectLatestAccumulatedReasoning(conversationId)(state);
+    const title = selectConversationTitle(conversationId)(state);
+    return createAgentRunScope({
+      ...agentScope,
+      // ── Run identity ───────────────────────────────────────────────────
+      run_conversation_id: conversationId,
+      run_status: instance?.status ?? void 0,
+      run_origin: instance?.origin ?? void 0,
+      conversation_title: title ?? void 0,
+      message_count: selectMessageCount(conversationId)(state),
+      // ── Request ────────────────────────────────────────────────────────
+      user_request: latestUserMessage ? extractFlatText(latestUserMessage) : void 0,
+      user_input_draft: selectUserInputText(conversationId)(state) || void 0,
+      variable_values: selectResolvedVariables(conversationId)(state),
+      context_entries: selectInstanceContextEntries(conversationId)(state),
+      // ── Response ───────────────────────────────────────────────────────
+      agent_response: selectLatestAnswerText(conversationId)(state) || lastAssistantText(messages),
+      agent_reasoning: reasoning || void 0,
+      all_messages: messages.map((m) => ({
+        id: m.id,
+        role: m.role,
+        text: extractFlatText(m)
+      })),
+      tool_calls: selectLatestToolLifecycles(conversationId)(state) ?? [],
+      completion_stats: completion ? completion : void 0,
+      // ── Live state ─────────────────────────────────────────────────────
+      is_streaming: selectIsStreaming(conversationId)(state),
+      is_executing: selectIsExecuting(conversationId)(state),
+      error_message: error?.message ?? void 0
+    });
+  }, [store, agentId, conversationId, sourceFeature]);
+}
+function lastAssistantText(messages) {
+  const last = [...messages].reverse().find((m) => m.role === "assistant");
+  if (!last) return void 0;
+  const text = extractFlatText(last);
+  return text.length > 0 ? text : void 0;
+}
+export {
+  useAgentRunSurfaceScope
+};

package/dist/agents/hooks/useAgentUndoRedo.d.ts

@@ -0,0 +1,31 @@
+export type Platform = "mac" | "windows" | "ios" | "android" | "linux" | "unknown";
+export declare function getPlatform(): Platform;
+export declare function isMacLike(): boolean;
+export declare function isTouchDevice(): boolean;
+/**
+ * Returns a human-readable shortcut hint string for the current platform.
+ * Examples: "⌘Z" on Mac, "Ctrl+Z" on Windows, "Shake" on iOS.
+ */
+export declare function getUndoShortcutHint(): string;
+export declare function getRedoShortcutHint(): string;
+interface UseAgentUndoRedoOptions {
+    agentId: string | null;
+    /**
+     * The editing surface this mount owns — the shortcut answers only keys
+     * pressed inside it. The builder mounts this hook once per message; an
+     * unscoped listener undid the agent once PER MESSAGE on a single ⌘Z.
+     */
+    scope: () => Element | null;
+    enabled?: boolean;
+}
+interface UseAgentUndoRedoReturn {
+    canUndo: boolean;
+    canRedo: boolean;
+    undo: () => void;
+    redo: () => void;
+    undoHint: string;
+    redoHint: string;
+    platform: Platform;
+}
+export declare function useAgentUndoRedo({ agentId, scope, enabled, }: UseAgentUndoRedoOptions): UseAgentUndoRedoReturn;
+export {};

package/dist/agents/hooks/useAgentUndoRedo.js

@@ -0,0 +1,134 @@
+"use client";
+import { useEffect, useCallback } from "react";
+import { keyEventInside } from "@ai-matrx/kit/keyboard-scope";
+import { useAppDispatch, useAppSelector } from "../../store/hooks.js";
+import {
+  undoAgentEdit,
+  redoAgentEdit
+} from "../redux/agent-definition/slice.js";
+import {
+  selectAgentCanUndo,
+  selectAgentCanRedo
+} from "../redux/agent-definition/selectors.js";
+let _cachedPlatform = null;
+function getPlatform() {
+  if (_cachedPlatform) return _cachedPlatform;
+  if (typeof navigator === "undefined") return "unknown";
+  const ua = navigator.userAgent.toLowerCase();
+  if (/iphone|ipad|ipod/.test(ua)) {
+    _cachedPlatform = "ios";
+  } else if (/android/.test(ua)) {
+    _cachedPlatform = "android";
+  } else if (/mac/.test(ua)) {
+    _cachedPlatform = "mac";
+  } else if (/win/.test(ua)) {
+    _cachedPlatform = "windows";
+  } else if (/linux/.test(ua)) {
+    _cachedPlatform = "linux";
+  } else {
+    _cachedPlatform = "unknown";
+  }
+  return _cachedPlatform;
+}
+function isMacLike() {
+  const p = getPlatform();
+  return p === "mac" || p === "ios";
+}
+function isTouchDevice() {
+  const p = getPlatform();
+  return p === "ios" || p === "android";
+}
+function getUndoShortcutHint() {
+  const p = getPlatform();
+  switch (p) {
+    case "mac":
+      return "\u2318Z";
+    case "ios":
+      return "Shake to Undo";
+    case "android":
+      return "Ctrl+Z";
+    case "windows":
+      return "Ctrl+Z";
+    case "linux":
+      return "Ctrl+Z";
+    default:
+      return "Ctrl+Z";
+  }
+}
+function getRedoShortcutHint() {
+  const p = getPlatform();
+  switch (p) {
+    case "mac":
+      return "\u21E7\u2318Z";
+    case "ios":
+      return "Shake to Redo";
+    case "android":
+      return "Ctrl+Shift+Z";
+    case "windows":
+      return "Ctrl+Y";
+    case "linux":
+      return "Ctrl+Shift+Z";
+    default:
+      return "Ctrl+Shift+Z";
+  }
+}
+function useAgentUndoRedo({
+  agentId,
+  scope,
+  enabled = true
+}) {
+  const dispatch = useAppDispatch();
+  const canUndo = useAppSelector(
+    (state) => agentId ? selectAgentCanUndo(state, agentId) : false
+  );
+  const canRedo = useAppSelector(
+    (state) => agentId ? selectAgentCanRedo(state, agentId) : false
+  );
+  const undo = useCallback(() => {
+    if (agentId && canUndo) dispatch(undoAgentEdit({ id: agentId }));
+  }, [dispatch, agentId, canUndo]);
+  const redo = useCallback(() => {
+    if (agentId && canRedo) dispatch(redoAgentEdit({ id: agentId }));
+  }, [dispatch, agentId, canRedo]);
+  useEffect(() => {
+    if (!enabled || !agentId) return void 0;
+    function handleKeyDown(e) {
+      const mod = isMacLike() ? e.metaKey : e.ctrlKey;
+      if (!mod) return;
+      if (!keyEventInside(e, scope())) return;
+      if (e.key === "z" || e.key === "Z") {
+        if (e.shiftKey) {
+          e.preventDefault();
+          if (canRedo) dispatch(redoAgentEdit({ id: agentId }));
+        } else {
+          e.preventDefault();
+          if (canUndo) dispatch(undoAgentEdit({ id: agentId }));
+        }
+        return;
+      }
+      if ((e.key === "y" || e.key === "Y") && !isMacLike()) {
+        e.preventDefault();
+        if (canRedo) dispatch(redoAgentEdit({ id: agentId }));
+      }
+    }
+    document.addEventListener("keydown", handleKeyDown, true);
+    return () => document.removeEventListener("keydown", handleKeyDown, true);
+  }, [enabled, agentId, canUndo, canRedo, dispatch, scope]);
+  return {
+    canUndo,
+    canRedo,
+    undo,
+    redo,
+    undoHint: getUndoShortcutHint(),
+    redoHint: getRedoShortcutHint(),
+    platform: getPlatform()
+  };
+}
+export {
+  getPlatform,
+  getRedoShortcutHint,
+  getUndoShortcutHint,
+  isMacLike,
+  isTouchDevice,
+  useAgentUndoRedo
+};

package/dist/agents/hooks/useAgentUsages.d.ts

@@ -0,0 +1,17 @@
+/**
+ * useAgentUsages — dispatch-on-idle hook for one agent's find-usages scan.
+ * Every consumer (user window, admin window, report detail pane) reads through
+ * this hook so no component fetches ad hoc.
+ */
+import type { UsageScope } from "../../ui/usages/usages.slice.js";
+export declare function useAgentUsages(agentId: string | null, scope: UsageScope): {
+    readonly status: import("../../ui/usages/usages.types.js").UsagesLoadStatus;
+    readonly error: string | null;
+    readonly groups: {
+        usageType: string;
+        items: import("../../ui/usages/usages.types.js").AgentUsageRow[];
+    }[];
+    readonly aggregates: import("../../ui/usages/usages.types.js").AgentUsageAggregate[];
+    readonly summary: import("../../host/ui-slots.js").RedFlagSummary;
+    readonly refresh: () => void;
+};

package/dist/agents/hooks/useAgentUsages.js

@@ -0,0 +1,36 @@
+"use client";
+import { useEffect, useCallback } from "react";
+import { useAppDispatch, useAppSelector } from "../../store/hooks.js";
+import { fetchAgentUsages } from "../../host/ui-slots.js";
+import { makeSelectUsageCache, makeSelectUsageGroups, makeSelectUsageAggregates, makeSelectRedFlagSummary } from "../../host/ui-slots.js";
+import { useMemo } from "react";
+function useAgentUsages(agentId, scope) {
+  const dispatch = useAppDispatch();
+  const id = agentId ?? "";
+  const selectCache = useMemo(() => makeSelectUsageCache(scope, id), [scope, id]);
+  const selectGroups = useMemo(() => makeSelectUsageGroups(scope, id), [scope, id]);
+  const selectAggregates = useMemo(() => makeSelectUsageAggregates(scope, id), [scope, id]);
+  const selectSummary = useMemo(() => makeSelectRedFlagSummary(scope, id), [scope, id]);
+  const cache = useAppSelector(selectCache);
+  const groups = useAppSelector(selectGroups);
+  const aggregates = useAppSelector(selectAggregates);
+  const summary = useAppSelector(selectSummary);
+  useEffect(() => {
+    if (!agentId) return;
+    dispatch(fetchAgentUsages({ agentId, scope }));
+  }, [dispatch, agentId, scope]);
+  const refresh = useCallback(() => {
+    if (agentId) dispatch(fetchAgentUsages({ agentId, scope, force: true }));
+  }, [dispatch, agentId, scope]);
+  return {
+    status: cache?.status ?? "idle",
+    error: cache?.error ?? null,
+    groups,
+    aggregates,
+    summary,
+    refresh
+  };
+}
+export {
+  useAgentUsages
+};

package/dist/agents/hooks/useBoundVariableScope.d.ts

@@ -0,0 +1,30 @@
+import type { ContextItemBinding, VariableCustomComponent } from "../types/agent-definition.types.js";
+import type { ResolvedValue } from "../../context/sources/scopes.js";
+import { type ReferenceItemConfig } from "../../context/sources/scopes.js";
+export interface BoundVarInfo {
+    name: string;
+    binding: ContextItemBinding;
+    scopeTypeLabel: string;
+    /** A scope of the binding's type is currently active. */
+    scopeActive: boolean;
+    /** The resolved value from the active scope, or null when none. */
+    resolved: ResolvedValue | null;
+    /** The scope_id that supplied the value (write-back target), or null. */
+    sourceScopeId: string | null;
+    /** The input component inherited from the bound context item. */
+    customComponent: VariableCustomComponent | undefined;
+    /** The item's storage value_type — drives write-back column routing. */
+    valueType: string | undefined;
+    /** Reference-cell config (`valueType === "reference"` only), for `ContextValueInput`. */
+    referenceConfig: ReferenceItemConfig | null;
+    /** The active scope of the binding's type (write-back target when nothing resolved yet). */
+    activeScopeIdOfType: string | null;
+    /** The binding's scope type (for the "Select {ScopeType}" affordance). */
+    scopeTypeId: string;
+    /** True when the binding's scope type exists in the user's org — i.e. they COULD pick a
+     * scope of it. When false (e.g. a public-agent user without this type), show no prompt. */
+    scopeTypeAccessible: boolean;
+    /** Bound but no value AND no active scope of its type — the "pick a scope" case. */
+    missing: boolean;
+}
+export declare function useBoundVariableScope(conversationId: string): BoundVarInfo[];

package/dist/agents/hooks/useBoundVariableScope.js

@@ -0,0 +1,122 @@
+"use client";
+import { useEffect, useMemo, useRef } from "react";
+import { useAppDispatch, useAppSelector } from "../../store/hooks.js";
+import { selectInstanceVariableDefinitions } from "../redux/execution-system/instance-variable-values/instance-variable-values.selectors.js";
+import {
+  mergeScopeVariableValues,
+  removeScopeVariableValues
+} from "../redux/execution-system/instance-variable-values/instance-variable-values.slice.js";
+import {
+  selectActiveOrganizationId,
+  selectActiveScopeIds,
+  selectActiveScopeIdsByType
+} from "../../context/sources/scopes.js";
+import { ensureContextValues } from "../../context/sources/scopes.js";
+import { makeSelectResolvedContext } from "../../context/sources/scopes.js";
+import { makeSelectScopeTypeLabelMapForOrg } from "../../context/sources/scopes.js";
+import {
+  listScopeTypeItems,
+  selectAllContextItems,
+  selectLoadedCatalogTypeIds
+} from "../../context/sources/scopes.js";
+import { contextItemBindingOf } from "../utils/variable-binding.js";
+import {
+  referenceConfigFromItem
+} from "../../context/sources/scopes.js";
+const EMPTY = [];
+const RESOLVE_ARGS = { userId: "" };
+function useBoundVariableScope(conversationId) {
+  const dispatch = useAppDispatch();
+  const definitions = useAppSelector(
+    selectInstanceVariableDefinitions(conversationId)
+  );
+  const orgId = useAppSelector(selectActiveOrganizationId);
+  const activeScopeIds = useAppSelector(selectActiveScopeIds);
+  const activeIdsByType = useAppSelector(selectActiveScopeIdsByType);
+  const selectScopeTypeLabelMap = useMemo(
+    makeSelectScopeTypeLabelMapForOrg,
+    []
+  );
+  const labelMap = useAppSelector((s) => selectScopeTypeLabelMap(s, orgId));
+  const allItems = useAppSelector(selectAllContextItems);
+  const loadedTypes = useAppSelector(selectLoadedCatalogTypeIds);
+  const resolvedSelector = useMemo(makeSelectResolvedContext, []);
+  const resolved = useAppSelector((s) => resolvedSelector(s, RESOLVE_ARGS));
+  const boundDefs = useMemo(
+    () => (
+      // Scope/system bindings only — a custom-data (`merge_field`) binding is
+      // server-filled and locked; it has no scope to resolve or write back to.
+      definitions.flatMap((d) => {
+        const binding = contextItemBindingOf(d.binding);
+        return binding && (binding.itemKey || binding.contextItemId) ? [{ name: d.name, binding }] : [];
+      })
+    ),
+    [definitions]
+  );
+  useEffect(() => {
+    for (const sid of activeScopeIds) dispatch(ensureContextValues(sid));
+  }, [activeScopeIds, dispatch]);
+  useEffect(() => {
+    const typeIds = new Set(
+      boundDefs.map((d) => d.binding.scopeTypeId).filter(Boolean)
+    );
+    for (const t of typeIds) {
+      if (!loadedTypes.includes(t)) dispatch(listScopeTypeItems(t));
+    }
+  }, [boundDefs, loadedTypes, dispatch]);
+  const infos = useMemo(() => {
+    if (boundDefs.length === 0) return EMPTY;
+    return boundDefs.map((d) => {
+      const binding = d.binding;
+      const item = binding.contextItemId ? allItems.find((i) => i.id === binding.contextItemId) : void 0;
+      const resolvedValue = binding.contextItemId ? resolved.values[binding.contextItemId] ?? null : null;
+      const source = binding.contextItemId ? resolved.sourcePerKey[binding.contextItemId] : void 0;
+      const activeScopeIdOfType = activeIdsByType[binding.scopeTypeId]?.[0] ?? null;
+      const scopeActive = !!activeScopeIdOfType;
+      return {
+        name: d.name,
+        binding,
+        scopeTypeLabel: labelMap[binding.scopeTypeId] ?? "scope",
+        scopeActive,
+        resolved: resolvedValue,
+        sourceScopeId: source?.kind === "scope" ? source.id : null,
+        customComponent: item?.custom_component ?? void 0,
+        valueType: item?.value_type,
+        referenceConfig: item ? referenceConfigFromItem(item) : null,
+        activeScopeIdOfType,
+        scopeTypeId: binding.scopeTypeId,
+        scopeTypeAccessible: !!labelMap[binding.scopeTypeId],
+        missing: !resolvedValue && !scopeActive
+      };
+    });
+  }, [boundDefs, allItems, resolved, activeIdsByType, labelMap]);
+  const lastSyncRef = useRef("");
+  const foldedNamesRef = useRef([]);
+  const syncedConversationRef = useRef(conversationId);
+  useEffect(() => {
+    if (syncedConversationRef.current !== conversationId) {
+      syncedConversationRef.current = conversationId;
+      lastSyncRef.current = "";
+      foldedNamesRef.current = [];
+    }
+    const patch = {};
+    for (const info of infos) {
+      if (info.resolved) patch[info.name] = info.resolved.value;
+    }
+    const key = JSON.stringify(patch);
+    if (key === lastSyncRef.current) return;
+    lastSyncRef.current = key;
+    const stale = foldedNamesRef.current.filter((n) => !(n in patch));
+    if (stale.length > 0) {
+      dispatch(removeScopeVariableValues({ conversationId, names: stale }));
+    }
+    if (Object.keys(patch).length > 0) {
+      dispatch(mergeScopeVariableValues({ conversationId, values: patch }));
+    }
+    foldedNamesRef.current = Object.keys(patch);
+  }, [infos, conversationId, dispatch]);
+  return infos;
+}
+export {
+  useBoundVariableScope
+};

package/dist/agents/hooks/useBuilderContextSeed.d.ts

@@ -0,0 +1,25 @@
+import type { ContextObjectType } from "../types/agent-api-types.js";
+export interface BuilderContextStoredEntry {
+    value: unknown;
+    type: ContextObjectType;
+    label: string;
+    slotMatched: boolean;
+}
+export declare function readBuilderContext(agentId: string | null | undefined): Record<string, BuilderContextStoredEntry>;
+/** Upsert one entry in localStorage. Safe no-op outside the browser. */
+export declare function writeBuilderContextEntry(agentId: string, key: string, entry: BuilderContextStoredEntry): void;
+/** Remove one entry from localStorage. */
+export declare function deleteBuilderContextEntry(agentId: string, key: string): void;
+/** Wipe all stored context for an agent. */
+export declare function clearBuilderContext(agentId: string): void;
+/**
+ * Call once from the builder root (AgentBuilderRightPanel). On every
+ * conversation id change (initial create, reset, auto-clear split), this
+ * pushes stored entries into instanceContext so they're included in the
+ * next submission even if the user never opens the Context tab.
+ *
+ * Safe to call when either argument is null — it no-ops.
+ */
+export declare function useBuilderContextSeed(conversationId: string | null | undefined, agentId: string | null | undefined): void;
+/** Optional helper exposed for a future "Reset all" button. */
+export declare function useClearBuilderContext(): (conversationId: string, agentId: string) => void;

package/dist/agents/hooks/useBuilderContextSeed.js

@@ -0,0 +1,86 @@
+"use client";
+import { useEffect } from "react";
+import { useAppDispatch } from "../../store/hooks.js";
+import {
+  setContextEntries,
+  clearInstanceContext
+} from "../redux/execution-system/instance-context/instance-context.slice.js";
+const VERSION_KEY = "v1";
+function storageKey(agentId) {
+  return `agent-builder-context:${VERSION_KEY}:${agentId}`;
+}
+function readBuilderContext(agentId) {
+  if (!agentId || typeof window === "undefined") return {};
+  try {
+    const raw = window.localStorage.getItem(storageKey(agentId));
+    if (!raw) return {};
+    const parsed = JSON.parse(raw);
+    return parsed?.entries ?? {};
+  } catch {
+    return {};
+  }
+}
+function writeAll(agentId, entries) {
+  if (typeof window === "undefined") return;
+  try {
+    window.localStorage.setItem(
+      storageKey(agentId),
+      JSON.stringify({ entries })
+    );
+  } catch {
+  }
+}
+function writeBuilderContextEntry(agentId, key, entry) {
+  const current = readBuilderContext(agentId);
+  current[key] = entry;
+  writeAll(agentId, current);
+}
+function deleteBuilderContextEntry(agentId, key) {
+  const current = readBuilderContext(agentId);
+  if (!(key in current)) return;
+  delete current[key];
+  writeAll(agentId, current);
+}
+function clearBuilderContext(agentId) {
+  if (typeof window === "undefined") return;
+  try {
+    window.localStorage.removeItem(storageKey(agentId));
+  } catch {
+  }
+}
+function useBuilderContextSeed(conversationId, agentId) {
+  const dispatch = useAppDispatch();
+  useEffect(() => {
+    if (!conversationId || !agentId) return;
+    const stored = readBuilderContext(agentId);
+    const keys = Object.keys(stored);
+    if (keys.length === 0) return;
+    dispatch(
+      setContextEntries({
+        conversationId,
+        entries: keys.map((key) => ({
+          key,
+          value: stored[key].value,
+          type: stored[key].type,
+          label: stored[key].label,
+          slotMatched: stored[key].slotMatched
+        }))
+      })
+    );
+  }, [conversationId, agentId, dispatch]);
+}
+function useClearBuilderContext() {
+  const dispatch = useAppDispatch();
+  return (conversationId, agentId) => {
+    clearBuilderContext(agentId);
+    dispatch(clearInstanceContext(conversationId));
+  };
+}
+export {
+  clearBuilderContext,
+  deleteBuilderContextEntry,
+  readBuilderContext,
+  useBuilderContextSeed,
+  useClearBuilderContext,
+  writeBuilderContextEntry
+};

package/dist/agents/hooks/useConversationMaterialized.d.ts

@@ -0,0 +1,5 @@
+/**
+ * True once `conversationId` is known to have a committed server row. Gate every
+ * durable write of a conversation id on this.
+ */
+export declare function useConversationMaterialized(conversationId: string | null | undefined): boolean;