@sero-ai/app-runtime 0.1.0 → 0.1.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sero-ai/app-runtime",
-  "version": "0.1.0",
-  "description": "Hooks for Sero federated app modules — useAppState, useAppInfo, useAgentPrompt",
+  "version": "0.1.1",
+  "description": "Hooks for Sero federated app modules — useAppState, useAppInfo, useAgentPrompt, useAppTools",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -10,7 +10,8 @@
     "./package.json": "./package.json"
   },
   "files": [
-    "src"
+    "src",
+    "README.md"
   ],
   "scripts": {
     "typecheck": "tsc --noEmit"
@@ -22,6 +23,7 @@
     "react": ">=19.0.0"
   },
   "devDependencies": {
+    "@sero/common": "^0.1.0",
     "@types/react": "^19.2.13",
     "typescript": "^5.9.3"
   }

package/src/context.ts

@@ -6,7 +6,7 @@
  * multiple times (which happens in Vite dev mode with MF).
  */
 
-import { createContext } from 'react';
+import { createContext, type Context } from 'react';
 
 export interface AppContextValue {
   /** App identifier (e.g. "todo"). */
@@ -29,15 +29,15 @@ export interface AppContextValue {
   themePresetId?: string;
 }
 
-const CONTEXT_KEY = '__sero_app_context__';
-
-// Ensure a single context instance across all module copies
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-const g = globalThis as any;
-if (!g[CONTEXT_KEY]) {
-  g[CONTEXT_KEY] = createContext<AppContextValue | null>(null);
+declare global {
+  var __sero_app_context__: Context<AppContextValue | null> | undefined;
 }
 
-export const AppContext: React.Context<AppContextValue | null> = g[CONTEXT_KEY];
+const appContext = globalThis.__sero_app_context__
+  ?? createContext<AppContextValue | null>(null);
+
+globalThis.__sero_app_context__ = appContext;
+
+export const AppContext: Context<AppContextValue | null> = appContext;
 
 export const AppProvider = AppContext.Provider;

package/src/index.ts

@@ -10,7 +10,12 @@ export { useAppState } from './use-app-state';
 export { useAppInfo } from './use-app-info';
 export { useAgentPrompt } from './use-agent-prompt';
 export { useAI, type AppAI } from './use-ai';
+export { useAppTools, type AppTools } from './use-app-tools';
 export { useAvailableModels, type UseAvailableModelsResult } from './use-available-models';
 export { useTheme, type UseThemeResult } from './use-theme';
 export { getSeroApi } from './sero-bridge';
 export type { AppModelInfo, AppModelGroup } from './sero-bridge';
+export type { AppToolContentBlock, AppToolImageContent, AppToolResult, AppToolTextContent } from '@sero/common';
+export { registerWidget, getRuntimeWidgets, onWidgetRegistryChange } from './widget-registry';
+export type { RuntimeWidget } from './widget-registry';
+export { useWidgetRegistration } from './use-widget-registration';

package/src/sero-bridge.ts

@@ -5,17 +5,24 @@
  * module declares only the subset app-runtime hooks need, keeping the
  * package decoupled from the desktop app's types while providing type
  * safety for all IPC calls.
- *
- * The single `(window as ...)` cast lives here — every other module
- * imports the typed getter.
  */
 
-export interface SeroAppStateBridge {
-  read(filePath: string): Promise<unknown>;
-  write(filePath: string, data: unknown): Promise<void>;
-  watch(filePath: string): Promise<unknown>;
+import type {
+  AppToolResult,
+  GitActionResult,
+  GitManagerRequest,
+  SharedAvailableModelGroup,
+  SharedModelInfo,
+  WebAppActionResult,
+  WebAppRequest,
+} from '@sero/common';
+
+export interface SeroWindowAppStateBridge {
+  read<TData = unknown>(filePath: string): Promise<TData>;
+  write<TData = unknown>(filePath: string, data: TData): Promise<void>;
+  watch<TData = unknown>(filePath: string): Promise<TData>;
   unwatch(filePath: string): Promise<void>;
-  onChange(cb: (filePath: string, data: unknown) => void): () => void;
+  onChange<TData = unknown>(cb: (filePath: string, data: TData) => void): () => void;
 }
 
 export interface SeroAppAgentBridge {
@@ -26,26 +33,20 @@ export interface SeroAppAgentBridge {
     text: string,
     onDelta: (delta: string) => void,
   ): Promise<string>;
+  invokeTool?(
+    appId: string,
+    workspaceId: string,
+    toolName: string,
+    params: Record<string, unknown>,
+  ): Promise<AppToolResult>;
 }
 
-export interface SeroGitAppActionParams {
-  action: string;
-  file?: string;
-  message?: string;
-  branch?: string;
-  hash?: string;
-  staged?: boolean;
-  all?: boolean;
-  stashIndex?: number;
-}
-
-export interface SeroGitAppActionResult {
-  ok: boolean;
-  message: string;
+export interface SeroGitAppBridge {
+  run(workspaceId: string, params: GitManagerRequest): Promise<GitActionResult>;
 }
 
-export interface SeroGitAppBridge {
-  run(workspaceId: string, params: SeroGitAppActionParams): Promise<SeroGitAppActionResult>;
+export interface SeroWebAppBridge {
+  run(workspaceId: string, params: WebAppRequest): Promise<WebAppActionResult>;
 }
 
 export interface SeroEditorExecResult {
@@ -61,39 +62,41 @@ export interface SeroEditorBridge {
 // ── Model types (subset of desktop's ipc types) ──────────────
 
 /** Serialisable model info for app modules. */
-export interface AppModelInfo {
-  provider: string;
-  modelId: string;
-  name: string;
-  reasoning: boolean;
-}
+export type AppModelInfo = SharedModelInfo;
 
 /** A group of models under a single provider. */
-export interface AppModelGroup {
-  provider: string;
-  displayName: string;
-  logo: string;
-  models: AppModelInfo[];
-}
+export type AppModelGroup = SharedAvailableModelGroup<AppModelInfo>;
 
 export interface SeroModelsBridge {
   list(): Promise<AppModelGroup[]>;
 }
 
 export interface SeroBridge {
-  appState: SeroAppStateBridge;
+  appState: SeroWindowAppStateBridge;
   appAgent: SeroAppAgentBridge;
   gitApp?: SeroGitAppBridge;
+  webApp?: SeroWebAppBridge;
   editor?: SeroEditorBridge;
   models?: SeroModelsBridge;
 }
 
+function readWindowSero(value: Window): unknown {
+  return Reflect.get(value, 'sero');
+}
+
+function isSeroBridge(value: unknown): value is SeroBridge {
+  return typeof value === 'object'
+    && value !== null
+    && 'appState' in value
+    && 'appAgent' in value;
+}
+
 /**
  * Get the Sero preload bridge. Throws if not running inside the Sero shell.
  */
 export function getSeroApi(): SeroBridge {
-  const sero = (window as unknown as { sero?: SeroBridge }).sero;
-  if (!sero) {
+  const sero = readWindowSero(window);
+  if (!isSeroBridge(sero)) {
     throw new Error('[app-runtime] window.sero not available — must run inside Sero shell');
   }
   return sero;

package/src/use-app-state.ts

@@ -8,7 +8,7 @@
 
 import { useState, useEffect, useCallback, useContext, useRef } from 'react';
 import { AppContext } from './context';
-import { getSeroApi } from './sero-bridge';
+import { getSeroApi, type SeroWindowAppStateBridge } from './sero-bridge';
 
 /**
  * File-backed reactive state hook.
@@ -24,55 +24,78 @@ export function useAppState<T>(defaultState: T): [T, (updater: (prev: T) => T) =
 
   const { stateFilePath } = ctx;
   const [state, setState] = useState<T>(defaultState);
+  const defaultStateRef = useRef<T>(defaultState);
   const stateRef = useRef<T>(defaultState);
+  const latestWriteIdRef = useRef(0);
 
-  // Keep ref in sync for the updater closure
+  defaultStateRef.current = defaultState;
   stateRef.current = state;
 
-  // Initial read + start watching
+  const applyState = useCallback((nextState: T) => {
+    stateRef.current = nextState;
+    setState(nextState);
+  }, []);
+
+  const recoverFromWriteFailure = useCallback(
+    async (api: SeroWindowAppStateBridge, writeId: number, fallbackState: T) => {
+      if (writeId !== latestWriteIdRef.current) return;
+
+      try {
+        const current = await api.read<T | null>(stateFilePath);
+        if (writeId !== latestWriteIdRef.current) return;
+        applyState(current ?? fallbackState);
+      } catch {
+        if (writeId !== latestWriteIdRef.current) return;
+        applyState(fallbackState);
+      }
+    },
+    [applyState, stateFilePath],
+  );
+
   useEffect(() => {
     const api = getSeroApi();
-    let unsubChange: (() => void) | null = null;
+    let isActive = true;
 
-    stateRef.current = defaultState;
-    setState(defaultState);
+    const applyIfActive = (nextState: T) => {
+      if (!isActive) return;
+      applyState(nextState);
+    };
 
-    // Subscribe to file changes from main process
-    unsubChange = api.appState.onChange((fp: string, data: unknown) => {
-      if (fp === stateFilePath && data != null) {
-        const parsed = data as T;
-        stateRef.current = parsed;
-        setState(parsed);
-      }
+    applyState(defaultStateRef.current);
+
+    const unsubscribe = api.appState.onChange<T | null>((filePath, data) => {
+      if (filePath !== stateFilePath || data == null) return;
+      applyIfActive(data);
     });
 
-    // Start watching (also returns current state)
-    api.appState.watch(stateFilePath).then((current) => {
-      if (current != null) {
-        const parsed = current as T;
-        stateRef.current = parsed;
-        setState(parsed);
-      }
+    void api.appState.watch<T | null>(stateFilePath).then((current) => {
+      if (current == null) return;
+      applyIfActive(current);
     });
 
     return () => {
-      unsubChange?.();
-      api.appState.unwatch(stateFilePath);
+      isActive = false;
+      unsubscribe();
+      void api.appState.unwatch(stateFilePath);
     };
-  }, [stateFilePath]);
+  }, [applyState, stateFilePath]);
 
-  // Write updater
   const updateState = useCallback(
     (updater: (prev: T) => T) => {
-      const next = updater(stateRef.current);
-      stateRef.current = next;
-      setState(next);
+      const previous = stateRef.current;
+      const next = updater(previous);
+      const writeId = latestWriteIdRef.current + 1;
+      latestWriteIdRef.current = writeId;
+      applyState(next);
 
-      // Persist to disk (async, fire-and-forget — watcher will confirm)
       const api = getSeroApi();
-      api.appState.write(stateFilePath, next);
+      void api.appState.write(stateFilePath, next).catch((error: unknown) => {
+        if (writeId !== latestWriteIdRef.current) return;
+        console.warn(`[app-runtime] Failed to persist app state for ${stateFilePath}`, error);
+        void recoverFromWriteFailure(api.appState, writeId, previous);
+      });
     },
-    [stateFilePath],
+    [applyState, recoverFromWriteFailure, stateFilePath],
   );
 
   return [state, updateState];

package/src/use-app-tools.ts

@@ -0,0 +1,31 @@
+import type { AppToolResult } from '@sero/common';
+import { useCallback, useContext, useMemo } from 'react';
+
+import { AppContext } from './context';
+import { getSeroApi } from './sero-bridge';
+
+export interface AppTools {
+  run(toolName: string, params?: Record<string, unknown>): Promise<AppToolResult>;
+}
+
+export function useAppTools(): AppTools {
+  const ctx = useContext(AppContext);
+
+  const run = useCallback<AppTools['run']>(
+    async (toolName, params): Promise<AppToolResult> => {
+      if (!ctx?.appId || !ctx?.workspaceId) {
+        throw new Error('[useAppTools] No app context — must be used inside a Sero app');
+      }
+
+      const { appAgent } = getSeroApi();
+      if (!appAgent.invokeTool) {
+        throw new Error('[useAppTools] App tool bridge unavailable');
+      }
+
+      return appAgent.invokeTool(ctx.appId, ctx.workspaceId, toolName, params ?? {});
+    },
+    [ctx],
+  );
+
+  return useMemo(() => ({ run }), [run]);
+}

package/src/use-widget-registration.ts

@@ -0,0 +1,83 @@
+/**
+ * useWidgetRegistration — hook for apps to register widgets at runtime.
+ *
+ * Registers a widget component for the current renderer session.
+ * This complements static manifest declarations in package.json.
+ *
+ * Usage:
+ * ```tsx
+ * import { useWidgetRegistration } from '@sero-ai/app-runtime';
+ * import { MyWidget } from './widgets/MyWidget';
+ *
+ * export function MyApp() {
+ *   useWidgetRegistration({
+ *     widgetId: 'summary',
+ *     name: 'Summary',
+ *     component: MyWidget,
+ *     defaultSize: { w: 2, h: 2 },
+ *   });
+ *   // ...
+ * }
+ * ```
+ */
+
+import { useContext, useEffect } from 'react';
+import type { ComponentType } from 'react';
+import { AppContext } from './context';
+import { registerWidget } from './widget-registry';
+
+interface WidgetRegistrationOptions {
+  /** Unique widget identifier within the app. */
+  widgetId: string;
+  /** Display name. */
+  name: string;
+  /** The React component to render. */
+  component: ComponentType;
+  /** Default grid size. */
+  defaultSize: { w: number; h: number };
+  /** Minimum grid size. */
+  minSize?: { w: number; h: number };
+  /** Maximum grid size. */
+  maxSize?: { w: number; h: number };
+  /** Optional description. */
+  description?: string;
+}
+
+/**
+ * Register a widget component for the current app.
+ *
+ * Registration is intentionally sticky for the renderer session so a
+ * dashboard widget can keep rendering after the full app view unmounts.
+ */
+export function useWidgetRegistration(options: WidgetRegistrationOptions): void {
+  const ctx = useContext(AppContext);
+  const appId = ctx?.appId;
+
+  // Acceptable useEffect — registration into a shared external registry
+  useEffect(() => {
+    if (!appId) return;
+
+    registerWidget({
+      appId,
+      widgetId: options.widgetId,
+      name: options.name,
+      component: options.component,
+      defaultSize: options.defaultSize,
+      minSize: options.minSize,
+      maxSize: options.maxSize,
+      description: options.description,
+    });
+  }, [
+    appId,
+    options.widgetId,
+    options.name,
+    options.component,
+    options.defaultSize.w,
+    options.defaultSize.h,
+    options.minSize?.w,
+    options.minSize?.h,
+    options.maxSize?.w,
+    options.maxSize?.h,
+    options.description,
+  ]);
+}

package/src/widget-registry.ts

@@ -0,0 +1,124 @@
+/**
+ * Widget registry — runtime registration of widgets from app modules.
+ *
+ * Apps can register widget components dynamically (in addition to static
+ * manifest declarations). The host dashboard subscribes to changes and
+ * renders registered widgets.
+ *
+ * Uses a globalThis singleton to ensure a single registry across all
+ * module federation copies, matching the AppContext pattern.
+ */
+
+import type { ComponentType } from 'react';
+
+/** A runtime-registered widget definition. */
+export interface RuntimeWidget {
+  /** App ID that owns this widget. */
+  appId: string;
+  /** Unique widget identifier within the app. */
+  widgetId: string;
+  /** Display name. */
+  name: string;
+  /** The React component to render. */
+  component: ComponentType;
+  /** Default grid size (react-grid-layout units). */
+  defaultSize: { w: number; h: number };
+  /** Minimum grid size. */
+  minSize?: { w: number; h: number };
+  /** Maximum grid size. */
+  maxSize?: { w: number; h: number };
+  /** Optional description. */
+  description?: string;
+}
+
+type WidgetChangeListener = () => void;
+
+interface WidgetRegistryState {
+  widgets: Map<string, RuntimeWidget>;
+  snapshot: RuntimeWidget[];
+  listeners: Set<WidgetChangeListener>;
+}
+
+declare global {
+  var __sero_widget_registry__: WidgetRegistryState | undefined;
+}
+
+function createRegistryState(): WidgetRegistryState {
+  return {
+    widgets: new Map<string, RuntimeWidget>(),
+    snapshot: [],
+    listeners: new Set<WidgetChangeListener>(),
+  };
+}
+
+function getRegistry(): WidgetRegistryState {
+  if (!globalThis.__sero_widget_registry__) {
+    globalThis.__sero_widget_registry__ = createRegistryState();
+  }
+  return globalThis.__sero_widget_registry__;
+}
+
+function makeKey(appId: string, widgetId: string): string {
+  return `${appId}:${widgetId}`;
+}
+
+function publishSnapshot(registry: WidgetRegistryState): void {
+  registry.snapshot = Array.from(registry.widgets.values());
+  registry.listeners.forEach((fn) => fn());
+}
+
+function sameGridSize(
+  left: RuntimeWidget['defaultSize'] | RuntimeWidget['minSize'] | RuntimeWidget['maxSize'],
+  right: RuntimeWidget['defaultSize'] | RuntimeWidget['minSize'] | RuntimeWidget['maxSize'],
+): boolean {
+  if (!left && !right) return true;
+  if (!left || !right) return false;
+  return left.w === right.w && left.h === right.h;
+}
+
+function sameWidget(existing: RuntimeWidget | undefined, next: RuntimeWidget): boolean {
+  if (!existing) return false;
+  return existing.appId === next.appId
+    && existing.widgetId === next.widgetId
+    && existing.name === next.name
+    && existing.component === next.component
+    && sameGridSize(existing.defaultSize, next.defaultSize)
+    && sameGridSize(existing.minSize, next.minSize)
+    && sameGridSize(existing.maxSize, next.maxSize)
+    && existing.description === next.description;
+}
+
+/**
+ * Register a widget component at runtime. Call from your app's root
+ * component or module initialisation.
+ *
+ * @returns An unregister function.
+ */
+export function registerWidget(widget: RuntimeWidget): () => void {
+  const registry = getRegistry();
+  const key = makeKey(widget.appId, widget.widgetId);
+  const existing = registry.widgets.get(key);
+  if (!sameWidget(existing, widget)) {
+    registry.widgets.set(key, widget);
+    publishSnapshot(registry);
+  }
+
+  return () => {
+    registry.widgets.delete(key);
+    publishSnapshot(registry);
+  };
+}
+
+/** Get all runtime-registered widgets. */
+export function getRuntimeWidgets(): RuntimeWidget[] {
+  return getRegistry().snapshot;
+}
+
+/** Subscribe to widget registration changes. Returns an unsubscribe function. */
+export function onWidgetRegistryChange(listener: WidgetChangeListener): () => void {
+  const registry = getRegistry();
+  registry.listeners.add(listener);
+  return () => {
+    registry.listeners.delete(listener);
+  };
+}