@nexus-ai-fs/tui 0.9.18

package/src/stores/delegation-store.ts

@@ -0,0 +1,300 @@
+/**
+ * Shared delegation store (Decision 5A).
+ *
+ * Extracted from access-store.ts and agents-store.ts to eliminate duplication.
+ * Both the Access panel and Agents panel consume from this single store.
+ */
+
+import { create } from "zustand";
+import type { FetchClient } from "@nexus-ai-fs/api-client";
+import { createApiAction, categorizeError } from "./create-api-action.js";
+import { useErrorStore } from "./error-store.js";
+
+// Canonical DelegationItem type — other stores re-export this.
+export interface DelegationItem {
+  readonly delegation_id: string;
+  readonly agent_id: string;
+  readonly parent_agent_id: string;
+  readonly delegation_mode: "copy" | "clean" | "shared";
+  readonly status: "active" | "revoked" | "expired" | "completed";
+  readonly scope_prefix: string | null;
+  readonly lease_expires_at: string | null;
+  readonly zone_id: string | null;
+  readonly intent: string;
+  readonly depth: number;
+  readonly can_sub_delegate: boolean;
+  readonly created_at: string;
+}
+
+export interface DelegationCreateResponse {
+  readonly delegation_id: string;
+  readonly worker_agent_id: string;
+  readonly api_key: string;
+  readonly mount_table: readonly string[];
+  readonly expires_at: string | null;
+  readonly delegation_mode: string;
+}
+
+export interface DelegationChainEntry {
+  readonly delegation_id: string;
+  readonly agent_id: string;
+  readonly parent_agent_id: string;
+  readonly delegation_mode: string;
+  readonly status: string;
+  readonly depth: number;
+  readonly intent: string;
+  readonly created_at: string;
+}
+
+export interface DelegationChain {
+  readonly chain: readonly DelegationChainEntry[];
+  readonly total_depth: number;
+}
+
+export interface NamespaceDetail {
+  readonly delegation_id: string;
+  readonly agent_id: string;
+  readonly delegation_mode: string;
+  readonly scope_prefix: string | null;
+  readonly removed_grants: readonly string[];
+  readonly added_grants: readonly string[];
+  readonly readonly_paths: readonly string[];
+  readonly zone_id: string | null;
+}
+
+export interface DelegationState {
+  // Data
+  readonly delegations: readonly DelegationItem[];
+  readonly delegationsLoading: boolean;
+  readonly selectedDelegationIndex: number;
+  readonly lastDelegationCreate: DelegationCreateResponse | null;
+  readonly delegationChain: DelegationChain | null;
+  readonly delegationChainLoading: boolean;
+  readonly namespaceDetail: NamespaceDetail | null;
+  readonly namespaceDetailLoading: boolean;
+  readonly error: string | null;
+
+  // Pagination
+  readonly delegationsTotal: number;
+  readonly delegationsLimit: number;
+  readonly delegationsOffset: number;
+  readonly delegationsStatusFilter: string | null;
+
+  // Actions
+  readonly fetchDelegations: (client: FetchClient, options?: {
+    limit?: number;
+    offset?: number;
+    status?: string | null;
+  }) => Promise<void>;
+  readonly createDelegation: (
+    request: {
+      readonly worker_id: string;
+      readonly worker_name: string;
+      readonly namespace_mode: string;
+      readonly scope_prefix?: string;
+      readonly intent: string;
+      readonly can_sub_delegate: boolean;
+      readonly ttl_seconds?: number;
+      readonly remove_grants?: readonly string[];
+      readonly add_grants?: readonly string[];
+      readonly readonly_paths?: readonly string[];
+      readonly scope?: {
+        readonly allowed_operations?: readonly string[];
+        readonly resource_patterns?: readonly string[];
+        readonly budget_limit?: string;
+        readonly max_depth?: number;
+      };
+      readonly min_trust_score?: number;
+    },
+    client: FetchClient,
+  ) => Promise<void>;
+  readonly revokeDelegation: (delegationId: string, client: FetchClient) => Promise<void>;
+  readonly completeDelegation: (
+    delegationId: string,
+    outcome: string,
+    qualityScore: number | null,
+    client: FetchClient,
+  ) => Promise<void>;
+  readonly fetchDelegationChain: (delegationId: string, client: FetchClient) => Promise<void>;
+  readonly fetchNamespaceDetail: (delegationId: string, client: FetchClient) => Promise<void>;
+  readonly updateNamespaceConfig: (
+    delegationId: string,
+    update: {
+      readonly scope_prefix?: string;
+      readonly remove_grants?: readonly string[];
+      readonly add_grants?: readonly string[];
+      readonly readonly_paths?: readonly string[];
+    },
+    client: FetchClient,
+  ) => Promise<void>;
+  readonly setSelectedDelegationIndex: (index: number) => void;
+  readonly setStatusFilter: (status: string | null) => void;
+}
+
+const SOURCE = "delegation";
+
+export const useDelegationStore = create<DelegationState>((set, get) => ({
+  delegations: [],
+  delegationsLoading: false,
+  selectedDelegationIndex: 0,
+  lastDelegationCreate: null,
+  delegationChain: null,
+  delegationChainLoading: false,
+  namespaceDetail: null,
+  namespaceDetailLoading: false,
+  error: null,
+  delegationsTotal: 0,
+  delegationsLimit: 50,
+  delegationsOffset: 0,
+  delegationsStatusFilter: null,
+
+  // =========================================================================
+  // Actions — inline with error store integration (complex logic/get())
+  // =========================================================================
+
+  fetchDelegations: async (client, options) => {
+    const limit = options?.limit ?? get().delegationsLimit;
+    const offset = options?.offset ?? get().delegationsOffset;
+    const status = options?.status !== undefined ? options.status : get().delegationsStatusFilter;
+
+    set({ delegationsLoading: true, error: null });
+    try {
+      let url = `/api/v2/agents/delegate?limit=${limit}&offset=${offset}`;
+      if (status) url += `&status=${encodeURIComponent(status)}`;
+
+      const response = await client.get<{
+        readonly delegations: readonly DelegationItem[];
+        readonly total: number;
+        readonly limit: number;
+        readonly offset: number;
+      }>(url);
+      set({
+        delegations: response.delegations,
+        delegationsTotal: response.total,
+        delegationsLimit: response.limit,
+        delegationsOffset: response.offset,
+        delegationsLoading: false,
+        selectedDelegationIndex: 0,
+        delegationsStatusFilter: status,
+      });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Failed to fetch delegations";
+      set({ delegationsLoading: false, error: message });
+      useErrorStore.getState().pushError({ message, category: categorizeError(message), source: SOURCE });
+    }
+  },
+
+  createDelegation: async (request, client) => {
+    set({ delegationsLoading: true, error: null });
+    try {
+      const response = await client.post<DelegationCreateResponse>(
+        "/api/v2/agents/delegate",
+        request,
+      );
+      set({ lastDelegationCreate: response, delegationsLoading: false });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Failed to create delegation";
+      set({ delegationsLoading: false, error: message });
+      useErrorStore.getState().pushError({ message, category: categorizeError(message), source: SOURCE });
+      return;
+    }
+    // Re-fetch list
+    try {
+      const { delegationsLimit, delegationsOffset, delegationsStatusFilter } = get();
+      let url = `/api/v2/agents/delegate?limit=${delegationsLimit}&offset=${delegationsOffset}`;
+      if (delegationsStatusFilter) url += `&status=${encodeURIComponent(delegationsStatusFilter)}`;
+      const listResponse = await client.get<{
+        readonly delegations: readonly DelegationItem[];
+        readonly total: number;
+      }>(url);
+      set({ delegations: listResponse.delegations, selectedDelegationIndex: 0 });
+    } catch {
+      // Non-critical
+    }
+  },
+
+  revokeDelegation: async (delegationId, client) => {
+    set({ delegationsLoading: true, error: null });
+    try {
+      await client.delete(`/api/v2/agents/delegate/${encodeURIComponent(delegationId)}`);
+      set((state) => ({
+        delegations: state.delegations.map((d) =>
+          d.delegation_id === delegationId ? { ...d, status: "revoked" } : d,
+        ),
+        delegationsLoading: false,
+      }));
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Failed to revoke delegation";
+      set({ delegationsLoading: false, error: message });
+      useErrorStore.getState().pushError({ message, category: categorizeError(message), source: SOURCE });
+    }
+  },
+
+  completeDelegation: async (delegationId, outcome, qualityScore, client) => {
+    set({ delegationsLoading: true, error: null });
+    try {
+      const body: { outcome: string; quality_score?: number } = { outcome };
+      if (qualityScore !== null) body.quality_score = qualityScore;
+      await client.post(
+        `/api/v2/agents/delegate/${encodeURIComponent(delegationId)}/complete`,
+        body,
+      );
+      set((state) => ({
+        delegations: state.delegations.map((d) =>
+          d.delegation_id === delegationId ? { ...d, status: "completed" } : d,
+        ),
+        delegationsLoading: false,
+      }));
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Failed to complete delegation";
+      set({ delegationsLoading: false, error: message });
+      useErrorStore.getState().pushError({ message, category: categorizeError(message), source: SOURCE });
+    }
+  },
+
+  // =========================================================================
+  // Actions migrated to createApiAction (Decision 6A)
+  // =========================================================================
+
+  fetchDelegationChain: createApiAction<DelegationState, [string, FetchClient]>(set, {
+    loadingKey: "delegationChainLoading",
+    source: SOURCE,
+    action: async (delegationId, client) => {
+      const response = await client.get<DelegationChain>(
+        `/api/v2/agents/delegate/${encodeURIComponent(delegationId)}/chain`,
+      );
+      return { delegationChain: response };
+    },
+  }),
+
+  fetchNamespaceDetail: createApiAction<DelegationState, [string, FetchClient]>(set, {
+    loadingKey: "namespaceDetailLoading",
+    source: SOURCE,
+    action: async (delegationId, client) => {
+      const response = await client.get<NamespaceDetail>(
+        `/api/v2/agents/delegate/${encodeURIComponent(delegationId)}/namespace`,
+      );
+      return { namespaceDetail: response };
+    },
+  }),
+
+  updateNamespaceConfig: createApiAction<DelegationState, [string, { readonly scope_prefix?: string; readonly remove_grants?: readonly string[]; readonly add_grants?: readonly string[]; readonly readonly_paths?: readonly string[] }, FetchClient]>(set, {
+    loadingKey: "namespaceDetailLoading",
+    source: SOURCE,
+    action: async (delegationId, update, client) => {
+      const response = await client.patch<NamespaceDetail>(
+        `/api/v2/agents/delegate/${encodeURIComponent(delegationId)}/namespace`,
+        update,
+      );
+      return { namespaceDetail: response };
+    },
+  }),
+
+  setSelectedDelegationIndex: (index) => {
+    set({ selectedDelegationIndex: index });
+  },
+
+  setStatusFilter: (status) => {
+    set({ delegationsStatusFilter: status });
+  },
+}));

package/src/stores/error-store.ts

@@ -0,0 +1,102 @@
+/**
+ * Centralized structured error store.
+ *
+ * Replaces fragmented per-store `error: string | null` fields with
+ * categorized, dismissable errors that support retry and source filtering.
+ *
+ * @see Issue #3066 Architecture Decision 8A
+ */
+
+import { create } from "zustand";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export type ErrorCategory = "network" | "validation" | "server";
+
+export interface AppError {
+  readonly id: string;
+  readonly message: string;
+  readonly category: ErrorCategory;
+  readonly source?: string;
+  readonly dismissable: boolean;
+  readonly retryAction?: () => void;
+  readonly timestamp: number;
+}
+
+export interface PushErrorOptions {
+  readonly message: string;
+  readonly category: ErrorCategory;
+  readonly source?: string;
+  readonly dismissable?: boolean;
+  readonly retryAction?: () => void;
+}
+
+export interface ErrorState {
+  readonly errors: readonly AppError[];
+
+  // Actions
+  readonly pushError: (options: PushErrorOptions) => void;
+  readonly dismissError: (id: string) => void;
+  readonly dismissAll: () => void;
+  readonly getErrorsForSource: (source: string) => readonly AppError[];
+  readonly hasErrors: () => boolean;
+}
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+const MAX_ERRORS = 50;
+
+let errorCounter = 0;
+
+// =============================================================================
+// Store
+// =============================================================================
+
+export const useErrorStore = create<ErrorState>((set, get) => ({
+  errors: [],
+
+  pushError: (options) => {
+    const error: AppError = {
+      id: `err-${++errorCounter}-${Date.now()}`,
+      message: options.message,
+      category: options.category,
+      source: options.source,
+      dismissable: options.dismissable ?? true,
+      retryAction: options.retryAction,
+      timestamp: Date.now(),
+    };
+
+    set((state) => {
+      const next = [...state.errors, error];
+      // Evict oldest if over limit
+      if (next.length > MAX_ERRORS) {
+        return { errors: next.slice(next.length - MAX_ERRORS) };
+      }
+      return { errors: next };
+    });
+  },
+
+  dismissError: (id) => {
+    set((state) => ({
+      errors: state.errors.filter((e) => e.id !== id),
+    }));
+  },
+
+  dismissAll: () => {
+    set((state) => ({
+      errors: state.errors.filter((e) => !e.dismissable),
+    }));
+  },
+
+  getErrorsForSource: (source) => {
+    return get().errors.filter((e) => e.source === source);
+  },
+
+  hasErrors: () => {
+    return get().errors.length > 0;
+  },
+}));

package/src/stores/events-store.ts

@@ -0,0 +1,163 @@
+/**
+ * Zustand store for real-time SSE events.
+ */
+
+import { create } from "zustand";
+import type { SseEvent } from "@nexus-ai-fs/api-client";
+import { SseClient } from "@nexus-ai-fs/api-client";
+import { CircularBuffer } from "../shared/lib/circular-buffer.js";
+
+const EVENTS_BUFFER_CAPACITY = 10_000;
+const MAX_RECONNECT_ATTEMPTS = 10;
+
+export interface EventFilters {
+  readonly eventType: string | null;
+  readonly search: string | null;
+}
+
+export interface SseIdentity {
+  readonly agentId?: string;
+  readonly subject?: string;
+  readonly zoneId?: string;
+}
+
+export interface EventsState {
+  readonly events: readonly SseEvent[];
+  readonly connected: boolean;
+  readonly reconnectCount: number;
+  readonly reconnectExhausted: boolean;
+  readonly filters: EventFilters;
+  readonly filteredEvents: readonly SseEvent[];
+  readonly eventsOverflowed: boolean;
+  readonly evictedCount: number;
+
+  // Internal circular buffer (not serializable, but that's fine for Zustand)
+  readonly eventsBuffer: CircularBuffer<SseEvent>;
+
+  // SSE client instance (not serializable, but that's fine for Zustand)
+  readonly sseClient: SseClient | null;
+
+  // Last connection params for manual reconnect after exhaustion
+  readonly lastConnectParams: { baseUrl: string; apiKey: string; identity?: SseIdentity } | null;
+
+  // Actions
+  readonly connect: (baseUrl: string, apiKey: string, identity?: SseIdentity) => void;
+  readonly disconnect: () => void;
+  readonly setFilter: (filters: Partial<EventFilters>) => void;
+  readonly clearEvents: () => void;
+}
+
+export const useEventsStore = create<EventsState>((set, get) => ({
+  events: [],
+  connected: false,
+  reconnectCount: 0,
+  reconnectExhausted: false,
+  filters: { eventType: null, search: null },
+  filteredEvents: [],
+  eventsOverflowed: false,
+  evictedCount: 0,
+  eventsBuffer: new CircularBuffer<SseEvent>(EVENTS_BUFFER_CAPACITY),
+  sseClient: null,
+  lastConnectParams: null,
+
+  connect: (baseUrl, apiKey, identity) => {
+    // Disconnect existing
+    get().sseClient?.disconnect();
+
+    const client = new SseClient({
+      baseUrl,
+      apiKey,
+      agentId: identity?.agentId,
+      subject: identity?.subject,
+      zoneId: identity?.zoneId,
+    });
+
+    client.onEvent((newEvents) => {
+      set((state) => {
+        // Note: eventsBuffer is mutated in-place (push), but consumers read
+        // the derived `events` array (new ref each time), so shallow-comparison
+        // subscribers re-render correctly. Do NOT subscribe to eventsBuffer directly.
+        const buf = state.eventsBuffer;
+        for (const event of newEvents) {
+          buf.push(event);
+        }
+        const allEvents = buf.toArray();
+        return {
+          events: allEvents,
+          filteredEvents: applyFilters(allEvents, state.filters),
+          eventsOverflowed: buf.hasOverflowed,
+          evictedCount: buf.evictedCount,
+          connected: true, // confirmed connected on first event
+          reconnectCount: 0,
+          reconnectExhausted: false,
+        };
+      });
+    });
+
+    client.onReconnect((attempt) => {
+      if (attempt >= MAX_RECONNECT_ATTEMPTS) {
+        client.disconnect();
+        set({ connected: false, reconnectExhausted: true, sseClient: null, reconnectCount: attempt });
+      } else {
+        set({ reconnectCount: attempt });
+      }
+    });
+
+    client.onError(() => {
+      set({ connected: false });
+    });
+
+    set({
+      sseClient: client,
+      connected: false,
+      reconnectCount: 0,
+      reconnectExhausted: false,
+      lastConnectParams: { baseUrl, apiKey, identity },
+    });
+
+    // Connect async — don't await (fire and forget)
+    client.connect("/api/v2/events/stream").catch(() => {
+      set({ connected: false });
+    });
+  },
+
+  disconnect: () => {
+    get().sseClient?.disconnect();
+    set({ sseClient: null, connected: false, reconnectCount: 0, reconnectExhausted: false });
+  },
+
+  setFilter: (partial) => {
+    set((state) => {
+      const filters = { ...state.filters, ...partial };
+      return {
+        filters,
+        filteredEvents: applyFilters(state.events, filters),
+      };
+    });
+  },
+
+  clearEvents: () => {
+    get().sseClient?.clearBuffer();
+    get().eventsBuffer.clear();
+    set({ events: [], filteredEvents: [], eventsOverflowed: false, evictedCount: 0 });
+  },
+}));
+
+function applyFilters(
+  events: readonly SseEvent[],
+  filters: EventFilters,
+): readonly SseEvent[] {
+  let result = events;
+
+  if (filters.eventType) {
+    const type = filters.eventType;
+    result = result.filter((e) => e.event === type);
+  }
+
+  if (filters.search) {
+    const lower = filters.search.toLowerCase();
+    result = result.filter((e) => e.data.toLowerCase().includes(lower));
+  }
+
+  return result;
+}