← sero-ai.dev
How Sero Works
Guides
Workspace
Agents
Plugins
Reference
← sero-ai.dev
How Sero Works
Guides
Workspace
Agents
Plugins
Reference

App Runtime Reference

@sero-ai/app-runtime connects a plugin's React UI to the Sero host. Use it only in modules that Sero loads. It is not an API for standalone browser apps.

Hook and API table

Hook/APIUse it forRequires app context?Host/bridge caveatSource
AppProvider / AppContextProvide app and workspace identity to hooksyesSero mounts the provider for federated modulespackages/app-runtime/src/context.ts
useAppInfo()Read appId, workspaceId, and workspacePathyesThrows if the provider is not presentpackages/app-runtime/src/use-app-info.ts
useAppState(defaultState)Read and write reactive plugin stateyesReturns [state, updateState, ready]; do not use browser storagepackages/app-runtime/src/use-app-state.ts
useAgentPrompt()Send text to the active agent sessionyesDrops the prompt and writes a warning if no session prompt function is availablepackages/app-runtime/src/use-agent-prompt.ts
useAI()Use app-scoped prompt() / promptStream()yesRequires app/workspace context and app-agent bridgepackages/app-runtime/src/use-ai.ts
useAppTools()Invoke plugin/app tools from UIyesrun(toolName, params?) throws if bridge is unavailablepackages/app-runtime/src/use-app-tools.ts
useAvailableModels()Read available model groups exposed by hostno app-specific stateAvailability depends on configured providerspackages/app-runtime/src/use-available-models.ts
useTheme()Read effective Sero theme mode/presetno app-specific stateTreat as host-provided presentation datapackages/app-runtime/src/use-theme.ts
registerWidget()Register a runtime dashboard widget imperativelynoRuntime registration lasts for the renderer sessionpackages/app-runtime/src/widget-registry.ts
getRuntimeWidgets()Inspect current runtime widget registrationsnoMainly useful for host/dashboard integrationpackages/app-runtime/src/widget-registry.ts
onWidgetRegistryChange()Subscribe to runtime widget registry changesnoUnsubscribe on cleanuppackages/app-runtime/src/widget-registry.ts
useWidgetRegistration()Register runtime dashboard widgets from Reactyes for app identityRegistration stays active for the current renderer sessionpackages/app-runtime/src/use-widget-registration.ts
getSeroApi()Raw window.sero bridge accessornoPrefer hooks unless writing low-level adapter codepackages/app-runtime/src/sero-bridge.ts

State rule

Use useAppState() for plugin UI state that should persist with Sero's profile/workspace model. Do not use localStorage or sessionStorage for durable plugin state.

The hook returns the default state while Sero reads the state file. Its third value becomes true when that first read finishes, including when the read fails. Use this ready value when the UI must distinguish default values from loaded values.

Current public storage model:

  • global app state: <SERO_HOME>/apps/<app-id>/state.json
  • workspace app state: <workspace>/.sero/apps/<app-id>/state.json

See State and Folders for the broader storage map.

Minimal example

import { useAppInfo, useAppState, useAppTools } from '@sero-ai/app-runtime';

type CounterState = { count: number };

export function CounterApp() {
  const { appId } = useAppInfo();
  const [state, setState, ready] = useAppState<CounterState>({ count: 0 });
  const { run } = useAppTools();

  if (!ready) return <p>Loading…</p>;

  return (
    <button
      onClick={() => {
        setState((prev) => ({ count: prev.count + 1 }));
        void run('counter_updated', { count: state.count + 1 });
      }}
    >
      {appId}: {state.count}
    </button>
  );
}

Declare host capabilities such as appAgent.invokeTool, tool.cli, or appRuntime.background only when the plugin actually needs them.

Related docs

ON THIS PAGE