@sero-ai/app-runtime 0.1.0

package/README.md

@@ -0,0 +1,33 @@
+# @sero-ai/app-runtime
+
+Shared runtime hooks for Sero federated app modules.
+
+This package provides the React hooks and context used by Sero apps:
+
+- `useAppState`
+- `useAppInfo`
+- `useAgentPrompt`
+- `useAI`
+- `useAvailableModels`
+- `useTheme`
+- `AppProvider`
+
+## Development
+
+Inside the Sero monorepo, workspace packages consume the source entrypoint.
+
+## Publishing
+
+This package intentionally publishes its TypeScript source directly under the
+`@sero-ai` npm scope.
+
+```bash
+cd packages/app-runtime
+npm publish --access public
+```
+
+## Consumption
+
+Inside the Sero monorepo and exported plugin source repos, consumers keep
+importing `@sero-ai/app-runtime`. Package manifests map that import name to the
+published package via npm aliasing (`npm:@sero-ai/app-runtime@<version>`).

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@sero-ai/app-runtime",
+  "version": "0.1.0",
+  "description": "Hooks for Sero federated app modules — useAppState, useAppInfo, useAgentPrompt",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "react": ">=19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.13",
+    "typescript": "^5.9.3"
+  }
+}

package/src/context.ts

@@ -0,0 +1,43 @@
+/**
+ * App context — provided by Sero's shell when mounting a federated app.
+ *
+ * Uses a globalThis singleton so the SAME context object is shared
+ * between host and remote even if @sero-ai/app-runtime is instantiated
+ * multiple times (which happens in Vite dev mode with MF).
+ */
+
+import { createContext } from 'react';
+
+export interface AppContextValue {
+  /** App identifier (e.g. "todo"). */
+  appId: string;
+  /** Workspace identifier (e.g. "global"). */
+  workspaceId: string;
+  /** Absolute path to the workspace root. */
+  workspacePath: string;
+  /** Absolute path to the state file on disk. */
+  stateFilePath: string;
+  /**
+   * Send a prompt to the active agent session.
+   * Injected by the shell — apps don't need to know about session IDs.
+   * Returns undefined if no session is active.
+   */
+  promptAgent?: (text: string) => void;
+  /** Current effective theme mode ('light' or 'dark'). */
+  themeMode?: 'light' | 'dark';
+  /** Active theme preset ID. */
+  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);
+}
+
+export const AppContext: React.Context<AppContextValue | null> = g[CONTEXT_KEY];
+
+export const AppProvider = AppContext.Provider;

package/src/index.ts

@@ -0,0 +1,16 @@
+/**
+ * @sero-ai/app-runtime — hooks for Sero federated app modules.
+ *
+ * Shared via module federation so every app gets the host's singleton.
+ * Hooks communicate with the Electron main process via window.sero IPC.
+ */
+
+export { AppContext, AppProvider, type AppContextValue } from './context';
+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 { 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';

package/src/sero-bridge.ts

@@ -0,0 +1,100 @@
+/**
+ * Typed access to the `window.sero` preload API.
+ *
+ * The full SeroAPI lives in apps/desktop/src/types/electron.d.ts. This
+ * 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>;
+  unwatch(filePath: string): Promise<void>;
+  onChange(cb: (filePath: string, data: unknown) => void): () => void;
+}
+
+export interface SeroAppAgentBridge {
+  prompt(appId: string, workspaceId: string, text: string): Promise<string>;
+  promptStream?(
+    appId: string,
+    workspaceId: string,
+    text: string,
+    onDelta: (delta: string) => void,
+  ): Promise<string>;
+}
+
+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: SeroGitAppActionParams): Promise<SeroGitAppActionResult>;
+}
+
+export interface SeroEditorExecResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+export interface SeroEditorBridge {
+  exec(workspaceId: string, command: string): Promise<SeroEditorExecResult>;
+}
+
+// ── 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;
+}
+
+/** A group of models under a single provider. */
+export interface AppModelGroup {
+  provider: string;
+  displayName: string;
+  logo: string;
+  models: AppModelInfo[];
+}
+
+export interface SeroModelsBridge {
+  list(): Promise<AppModelGroup[]>;
+}
+
+export interface SeroBridge {
+  appState: SeroAppStateBridge;
+  appAgent: SeroAppAgentBridge;
+  gitApp?: SeroGitAppBridge;
+  editor?: SeroEditorBridge;
+  models?: SeroModelsBridge;
+}
+
+/**
+ * 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) {
+    throw new Error('[app-runtime] window.sero not available — must run inside Sero shell');
+  }
+  return sero;
+}

package/src/use-agent-prompt.ts

@@ -0,0 +1,33 @@
+/**
+ * useAgentPrompt — send a message to the agent from an app UI.
+ *
+ * Returns a function that, when called, sends a text prompt to the
+ * currently active agent session. The shell injects the actual
+ * prompt function via AppContext — apps never need to know about
+ * session IDs or storage details.
+ */
+
+import { useContext, useCallback } from 'react';
+import { AppContext } from './context';
+
+/**
+ * Returns a function that sends a prompt to the active agent session.
+ *
+ * Usage:
+ *   const prompt = useAgentPrompt();
+ *   prompt("Add a todo: buy milk");
+ */
+export function useAgentPrompt(): (text: string) => void {
+  const ctx = useContext(AppContext);
+
+  return useCallback(
+    (text: string) => {
+      if (!ctx?.promptAgent) {
+        console.warn('[useAgentPrompt] No promptAgent in context — prompt dropped');
+        return;
+      }
+      ctx.promptAgent(text);
+    },
+    [ctx],
+  );
+}

package/src/use-ai.ts

@@ -0,0 +1,59 @@
+/**
+ * useAI — make ad-hoc LLM calls from an app UI.
+ *
+ * Each app gets a dedicated agent session managed by the main process.
+ * Calls go through `window.sero.appAgent.prompt()` — no active chat
+ * session required. The session persists for the app × workspace pair,
+ * so the LLM accumulates context across calls.
+ *
+ * Usage:
+ *   const ai = useAI();
+ *   const response = await ai.prompt("Generate an inspirational quote.");
+ */
+
+import { useContext, useCallback, useMemo } from 'react';
+import { AppContext } from './context';
+import { getSeroApi } from './sero-bridge';
+
+export interface AppAI {
+  /** Send a prompt to the app's dedicated agent session. Returns the LLM's text response. */
+  prompt: (text: string) => Promise<string>;
+  /** Send a prompt and receive text deltas as they stream in. Returns the final full text. */
+  promptStream: (text: string, onDelta: (delta: string) => void) => Promise<string>;
+}
+
+export function useAI(): AppAI {
+  const ctx = useContext(AppContext);
+
+  const prompt = useCallback(
+    async (text: string): Promise<string> => {
+      if (!ctx?.appId || !ctx?.workspaceId) {
+        throw new Error('[useAI] No app context — must be used inside a Sero app');
+      }
+
+      const { appAgent } = getSeroApi();
+      return appAgent.prompt(ctx.appId, ctx.workspaceId, text);
+    },
+    [ctx],
+  );
+
+  const promptStream = useCallback(
+    async (text: string, onDelta: (delta: string) => void): Promise<string> => {
+      if (!ctx?.appId || !ctx?.workspaceId) {
+        throw new Error('[useAI] No app context — must be used inside a Sero app');
+      }
+
+      const { appAgent } = getSeroApi();
+
+      // Fall back to non-streaming if bridge doesn't support it
+      if (!appAgent.promptStream) {
+        return appAgent.prompt(ctx.appId, ctx.workspaceId, text);
+      }
+
+      return appAgent.promptStream(ctx.appId, ctx.workspaceId, text, onDelta);
+    },
+    [ctx],
+  );
+
+  return useMemo(() => ({ prompt, promptStream }), [prompt, promptStream]);
+}

package/src/use-app-info.ts

@@ -0,0 +1,25 @@
+/**
+ * useAppInfo — read-only context about the current app and workspace.
+ */
+
+import { useContext } from 'react';
+import { AppContext } from './context';
+
+export interface AppInfo {
+  appId: string;
+  workspaceId: string;
+  workspacePath: string;
+}
+
+export function useAppInfo(): AppInfo {
+  const ctx = useContext(AppContext);
+  if (!ctx) {
+    throw new Error('useAppInfo must be used inside an <AppProvider>');
+  }
+
+  return {
+    appId: ctx.appId,
+    workspaceId: ctx.workspaceId,
+    workspacePath: ctx.workspacePath,
+  };
+}

package/src/use-app-state.ts

@@ -0,0 +1,79 @@
+/**
+ * useAppState — file-backed reactive state for Sero apps.
+ *
+ * 1. Initial read via IPC
+ * 2. File watching via main process (fs.watch → IPC push)
+ * 3. Writes via IPC (atomic file write → watcher fires → all consumers update)
+ */
+
+import { useState, useEffect, useCallback, useContext, useRef } from 'react';
+import { AppContext } from './context';
+import { getSeroApi } from './sero-bridge';
+
+/**
+ * File-backed reactive state hook.
+ *
+ * @param defaultState — returned while the file is being read (or if missing)
+ * @returns [state, updateState] — updateState accepts an updater function
+ */
+export function useAppState<T>(defaultState: T): [T, (updater: (prev: T) => T) => void] {
+  const ctx = useContext(AppContext);
+  if (!ctx) {
+    throw new Error('useAppState must be used inside an <AppProvider>');
+  }
+
+  const { stateFilePath } = ctx;
+  const [state, setState] = useState<T>(defaultState);
+  const stateRef = useRef<T>(defaultState);
+
+  // Keep ref in sync for the updater closure
+  stateRef.current = state;
+
+  // Initial read + start watching
+  useEffect(() => {
+    const api = getSeroApi();
+    let unsubChange: (() => void) | null = null;
+
+    stateRef.current = defaultState;
+    setState(defaultState);
+
+    // 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);
+      }
+    });
+
+    // 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);
+      }
+    });
+
+    return () => {
+      unsubChange?.();
+      api.appState.unwatch(stateFilePath);
+    };
+  }, [stateFilePath]);
+
+  // Write updater
+  const updateState = useCallback(
+    (updater: (prev: T) => T) => {
+      const next = updater(stateRef.current);
+      stateRef.current = next;
+      setState(next);
+
+      // Persist to disk (async, fire-and-forget — watcher will confirm)
+      const api = getSeroApi();
+      api.appState.write(stateFilePath, next);
+    },
+    [stateFilePath],
+  );
+
+  return [state, updateState];
+}

package/src/use-available-models.ts

@@ -0,0 +1,58 @@
+/**
+ * useAvailableModels — fetches the list of available models from the
+ * Sero host's ModelRegistry. Session-independent: apps don't need an
+ * active agent session to enumerate models.
+ *
+ * Returns { groups, loading, error, refresh }.
+ */
+
+import { useState, useEffect, useCallback } from 'react';
+import { getSeroApi, type AppModelGroup } from './sero-bridge';
+
+export interface UseAvailableModelsResult {
+  /** Model groups, grouped by provider. */
+  groups: AppModelGroup[];
+  /** True while the initial fetch is in flight. */
+  loading: boolean;
+  /** Error message if the fetch failed. */
+  error: string | null;
+  /** Manually re-fetch the list (e.g. after adding auth). */
+  refresh: () => void;
+}
+
+export function useAvailableModels(): UseAvailableModelsResult {
+  const [groups, setGroups] = useState<AppModelGroup[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  const fetch = useCallback(() => {
+    setLoading(true);
+    setError(null);
+
+    const api = getSeroApi();
+    if (!api.models) {
+      setError('Model listing not available in this Sero version');
+      setLoading(false);
+      return;
+    }
+
+    api.models
+      .list()
+      .then((result) => {
+        setGroups(result);
+        setError(null);
+      })
+      .catch((err: unknown) => {
+        setError(err instanceof Error ? err.message : 'Failed to fetch models');
+      })
+      .finally(() => {
+        setLoading(false);
+      });
+  }, []);
+
+  useEffect(() => {
+    fetch();
+  }, [fetch]);
+
+  return { groups, loading, error, refresh: fetch };
+}

package/src/use-theme.ts

@@ -0,0 +1,25 @@
+/**
+ * useTheme — read the current theme mode and preset ID from app context.
+ *
+ * Most federated apps don't need this — CSS variables update automatically.
+ * Use this hook when you need programmatic access to the theme (e.g. for
+ * canvas rendering, charts, or conditional logic).
+ */
+
+import { useContext } from 'react';
+import { AppContext } from './context';
+
+export interface UseThemeResult {
+  /** Current effective mode ('light' or 'dark'). */
+  mode: 'light' | 'dark';
+  /** Active theme preset ID. */
+  presetId: string;
+}
+
+export function useTheme(): UseThemeResult {
+  const ctx = useContext(AppContext);
+  return {
+    mode: ctx?.themeMode ?? 'dark',
+    presetId: ctx?.themePresetId ?? 'default',
+  };
+}