#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

#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

#Concurrent writers

A state file can have three writers: the plugin UI, the plugin runtime, and the plugin extension. The host serialises them:

• Every host-side mutation runs under a cross-process lock (<stateFile>.lock).
• useAppState writes carry an etag. When another writer changed the file first, the hook re-applies your updater on top of the new content and writes again. Keep updaters pure functions of prev — an updater that closes over older state re-applies stale values.
• An extension that writes a state file directly must hold the same lock. Use withStateLock(stateFile, fn) from @sero-ai/extension-runtime around each read-modify-write.

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

• Plugin Author Quick Path
• Plugins Reference
• Plugins and Apps
• Dashboard and Widgets