jishushell 0.4.17 → 0.4.24-beta.2

package/dist/services/runtime/types.d.ts

@@ -0,0 +1,545 @@
+/**
+ * Runtime adapter types — §32.2 full decoupling contract.
+ *
+ * Goal: adding a new agent = 1 new file in `runtime/adapters/` + 1 import in
+ * `runtime/index.ts`. Core files (instance-manager / nomad-manager /
+ * setup-manager / routes / llm-proxy) never mention specific agent kinds.
+ *
+ * - Field names use camelCase; on-wire JSON matches the type exactly.
+ * - Legacy OpenClaw path remains wired through `instance-manager` helpers,
+ *   but the control flow now enters through `OpenClawAdapter` methods so
+ *   framework code dispatches via `getAdapter(agentType)` uniformly.
+ */
+/**
+ * Discriminator for pluggable agent runtimes. Canonical identifier in code,
+ * on-disk `instance.json`, and HTTP APIs is `agentType`.
+ */
+export type AgentType = "openclaw" | "hermes" | (string & {});
+export interface RuntimePortSpec {
+    name: string;
+    containerPort: number;
+    hostPort?: number;
+    visibility?: "external" | "internal";
+}
+export interface RuntimeVolumeSpec {
+    hostPath: string;
+    containerPath: string;
+    mode: "rw" | "ro";
+}
+export interface RuntimeHealthSpec {
+    type: "http" | "tcp" | "process";
+    path?: string;
+    port?: number;
+    interval?: string;
+    timeout?: string;
+    retries?: number;
+}
+export interface RuntimeResources {
+    CPU: number;
+    MemoryMB: number;
+    MemoryMaxMB?: number;
+}
+/**
+ * Engine-neutral description of a runnable unit.
+ * Scheduler (Nomad / process manager) consumes this without knowing the runtime kind.
+ */
+export interface RuntimeSpec {
+    image?: string | null;
+    command: string;
+    args: string[];
+    cwd: string;
+    user?: string;
+    env: Record<string, string>;
+    envFiles?: string[];
+    resources: RuntimeResources;
+    ports?: RuntimePortSpec[];
+    volumes?: RuntimeVolumeSpec[];
+    health?: RuntimeHealthSpec | null;
+}
+export interface CapabilityProfile {
+    gateway: {
+        http: boolean;
+        websocket: boolean;
+        /**
+         * Which Chat UI style the frontend should use for this runtime. Values
+         * describe **behavior**, not agent identity, so a new adapter can pick
+         * the right mode without touching framework code.
+         * - "iframe":  iframe the runtime's own gateway web UI (OpenClaw today)
+         * - "inline":  JishuShell-side chat panel via frontend registry's
+         *              `chatComponent` (Hermes today); runtime exposes an
+         *              OpenAI-compat endpoint reached through
+         *              /api/instances/:id/agent/chat
+         * - "none":    no Chat UI; users interact via CLI / messaging platforms
+         */
+        chatPanel: "iframe" | "inline" | "none";
+    };
+    pairing: {
+        list: boolean;
+        approve: boolean;
+        revoke: boolean;
+        clearPending: boolean;
+    };
+    configEditor: "json" | "yaml+env" | "custom";
+    configSchema: boolean;
+    customProvider: boolean;
+    pluginInstall: boolean;
+    skills: boolean;
+    mcp: boolean;
+    memory: boolean;
+    backupRestore: boolean;
+    usageStats: boolean;
+    restartlessReload: boolean;
+    messagingPlatforms: string[];
+}
+/**
+ * Runtime version info exposed to the UI / CLI per §32.7.
+ *
+ * - `agentType` — mirror of the adapter's own agentType for symmetry with the registry
+ * - `ref`       — hermes: commit sha when in overlay mode; openclaw: package.json version
+ * - `digest`    — image digest captured in panel.json when installHermes ran
+ * - `mode`      — hermes-only distinction, OpenClaw always "baseline"
+ */
+export interface RuntimeVersionInfo {
+    agentType: string;
+    ref?: string;
+    digest?: string;
+    mode: "baseline" | "overlay";
+}
+export interface InstancePaths {
+    instanceDir: string;
+    agentHome: string;
+    primaryConfig?: string;
+    secretEnv?: string;
+}
+/**
+ * Entry in panel.json:runtime_catalog.<agentType>. Catalog-level defaults captured at
+ * install time. `defaultImageDigest` is the digest captured by
+ * setup-manager.installHermes() per §32.1 so the HermesAdapter.buildRuntime()
+ * can pin the image by digest (preferred) instead of the mutable tag.
+ */
+export interface RuntimeCatalogEntry {
+    defaultImage: string;
+    defaultImageDigest?: string;
+    shimPath?: string;
+    configFormat: "json" | "yaml+env" | "custom";
+    homeDirName: string;
+    resources: RuntimeResources;
+    allowDockerSock?: boolean;
+}
+export interface CreateInstanceContext {
+    instanceId: string;
+    name: string;
+    description?: string;
+}
+export type JsonConfigDocument = {
+    format: "json";
+    content: Record<string, any>;
+};
+export type YamlEnvConfigDocument = {
+    format: "yaml+env";
+    yaml: string;
+    env: string;
+    /**
+     * Optional JishuShell meta block persisted alongside yaml/env. Mirrors
+     * the `x-jishushell` key OpenClaw stores inside its JSON config — for
+     * Hermes and other yaml+env runtimes, this block lives on instance.json
+     * but rides through the same ConfigDocument shape so the frontend can
+     * edit per-instance upstream provider config (provider id, baseUrl,
+     * API key, models) without learning runtime-specific storage paths.
+     *
+     * When the adapter's `writeConfig` sees this field, it delegates to the
+     * shared llm-proxy `saveInstanceConfig` flow so API key encryption,
+     * provider.env persistence, and cache invalidation stay in one place.
+     */
+    "x-jishushell"?: Record<string, any>;
+};
+export type ConfigDocument = JsonConfigDocument | YamlEnvConfigDocument;
+export interface InstanceConfigMeta {
+    agentType: AgentType;
+    format: ConfigDocument["format"];
+    schemaId: string;
+    capabilities: CapabilityProfile;
+    secretFields: string[];
+    runtimeVersion: RuntimeVersionInfo;
+}
+export interface PairingApproveInput {
+    channel: string;
+    code: string;
+    notify?: boolean;
+}
+/**
+ * Input shape handed to `RuntimeAdapter.createInstance()` from route / CLI layer.
+ * Framework-level fields only — agent-specific extras live inside `extras` so
+ * the core layer never special-cases by kind.
+ */
+export interface CreateInstanceArgs {
+    instanceId: string;
+    name: string;
+    description: string;
+    cloneFrom?: string;
+    agentHome?: string;
+    cloneOptions?: {
+        include_sessions?: boolean;
+        include_memory?: boolean;
+    };
+    appSpec?: any;
+    extras?: Record<string, any>;
+}
+/**
+ * Declarative metadata that describes a runtime without requiring any runtime
+ * code from the framework. Exposed via `GET /api/runtime/catalog` to drive
+ * frontend cards / create-forms / install wizards (§32.2.2).
+ *
+ * All fields are OPTIONAL in MVP so existing adapters can land incrementally.
+ */
+export interface AdapterManifest {
+    agentType: AgentType;
+    displayName: string;
+    description: string;
+    defaultCapabilities: CapabilityProfile;
+    defaultCatalogEntry?: Partial<RuntimeCatalogEntry>;
+    /** Declarative hint: does this runtime require Nomad + Docker driver? */
+    requiresNomadDocker?: boolean;
+    /** Approximate disk space (MB) required for install — surfaced in setup UI. */
+    diskSpaceMB?: number;
+    /** Provider presets the adapter wants to contribute to the UI picker. */
+    providerPresets?: Array<Record<string, any>>;
+}
+/**
+ * Cross-cutting lifecycle hooks. Framework calls these at well-defined
+ * points so adapters can extend behavior without forcing if/else branches
+ * into `instance-manager.ts` / `backup-manager.ts` / `routes/*`.
+ *
+ * All hooks are optional — adapters implement only what they need.
+ */
+export interface AdapterHooks {
+    /** Run immediately after instance.json is persisted on a fresh create. */
+    onCreate?(args: {
+        instanceId: string;
+        meta: Record<string, any>;
+    }): Promise<void>;
+    /** Run just before the instance directory is removed from disk.
+     *  Return `{ warnings }` to surface non-fatal advisories (e.g. legacy
+     *  `openclaw_home` pointing outside the instance dir). Returning void
+     *  means "no warnings". */
+    onDelete?(args: {
+        instanceId: string;
+        meta: Record<string, any>;
+    }): Promise<void | {
+        warnings?: string[];
+    }>;
+    /** Run after a successful `writeConfig` — lets adapters auto-install
+     *  channel plugins, enforce terminal.backend, etc. */
+    onConfigSaved?(args: {
+        instanceId: string;
+        oldConfig: unknown;
+        newConfig: unknown;
+    }): Promise<void>;
+    /** Run just before Nomad receives a job submission. Adapters can patch
+     *  on-disk files, seed symlinks, or precompute secrets here. */
+    onBeforeStart?(args: {
+        instanceId: string;
+    }): Promise<void>;
+    /** Run after service control reports the instance as started. */
+    onAfterStart?(args: {
+        instanceId: string;
+    }): Promise<void>;
+    /** Run just before service control issues a stop. */
+    onBeforeStop?(args: {
+        instanceId: string;
+    }): Promise<void>;
+    /** Run when panel default_provider changes — adapters rewrite whatever
+     *  file their runtime reads upstream credentials from. */
+    onUpstreamProviderChange?(args: {
+        instanceId: string;
+        upstream: Record<string, any>;
+    }): Promise<void>;
+}
+/**
+ * Full RuntimeAdapter contract — §32.2 / §32.8.
+ *
+ * All new methods below the "MVP core" block are OPTIONAL so HermesAdapter
+ * (which predates §32.8) continues to work. OpenClawAdapter implements the
+ * full surface, enabling framework code to dispatch uniformly instead of
+ * branching on `agentType === "hermes"`.
+ */
+export interface RuntimeAdapter {
+    readonly agentType: AgentType;
+    readonly displayName: string;
+    readonly defaultCapabilities: CapabilityProfile;
+    readonly manifest?: AdapterManifest;
+    readonly hooks?: AdapterHooks;
+    /**
+     * Default port the framework uses as a fallback when an instance's
+     * persisted runtime spec has no host port recorded. Adapters declare
+     * their canonical base port here (OpenClaw 18789, Hermes 8642).
+     */
+    readonly defaultGatewayPort?: number;
+    createInitialLayout(ctx: CreateInstanceContext): Promise<InstancePaths>;
+    buildRuntime(instanceId: string): Promise<RuntimeSpec>;
+    getRuntimeVersion(instanceId: string): Promise<RuntimeVersionInfo>;
+    getConfigMeta(instanceId: string): Promise<InstanceConfigMeta>;
+    readConfig(instanceId: string): Promise<ConfigDocument>;
+    writeConfig(instanceId: string, doc: ConfigDocument): Promise<ConfigDocument>;
+    buildPairingListCommand(instanceId: string): Promise<string[]>;
+    buildPairingApproveCommand(instanceId: string, input: PairingApproveInput): Promise<string[]>;
+    /**
+     * Create a new instance end-to-end: filesystem layout + port allocation +
+     * persist instance.json + seed proxy token. Returns the fully-populated
+     * meta that framework code passes back to the HTTP route layer.
+     *
+     * Optional for backward compat: adapters that do not implement this will
+     * fall back to the legacy `instance-manager.createInstance()` path.
+     */
+    createInstance?(args: CreateInstanceArgs): Promise<Record<string, any>>;
+    /**
+     * Read the runtime's raw native configuration object. For OpenClaw this
+     * is the parsed `openclaw.json` body; for Hermes it is a synthetic stub
+     * containing only the `x-jishushell` upstream metadata block.
+     *
+     * Used by LLM proxy, backup manager, and other framework code that needs
+     * to inspect the merged config without going through the typed
+     * `readConfig()` wrapper. Returns null if no config is available.
+     */
+    getNativeConfig?(instanceId: string): Record<string, any> | null;
+    /**
+     * Read the stored native configuration including backend-managed fields
+     * (plugin installs, channel credentials, weixin accounts) that would be
+     * filtered out of the typed `readConfig()` editor view. Used by flows
+     * that round-trip the full config to disk.
+     */
+    getStoredNativeConfig?(instanceId: string): Record<string, any> | null;
+    /**
+     * Persist a raw native configuration object. For OpenClaw this drives
+     * the full `saveConfig` pipeline (channel plugin auto-install, env file
+     * key rewrites, x-jishushell propagation). Returns true on success.
+     *
+     * Framework callers (`instance-manager.saveConfig`) always `await` the
+     * result, so async implementations get proper success/failure signalling.
+     * Synchronous implementations are transparently supported.
+     */
+    saveNativeConfig?(instanceId: string, config: Record<string, any>): boolean | Promise<boolean>;
+    /**
+     * Install a channel-specific plugin into the running instance. Returns
+     * once install is complete. Throws on fatal error. OpenClaw-specific;
+     * other adapters can leave unimplemented or throw "not supported".
+     */
+    installChannelPlugin?(instanceId: string, channelId: string): Promise<void>;
+    /** Report whether a channel plugin is already installed. */
+    isChannelPluginInstalled?(instanceId: string, channelId: string): boolean;
+    /** Channel-id → npm package map for auto-install decisions. */
+    readonly channelPluginMap?: Record<string, string>;
+    /**
+     * Save Feishu/Lark OAuth credentials into the instance's native config.
+     * OpenClaw-specific; other adapters can leave unimplemented.
+     */
+    saveFeishuCredentials?(instanceId: string, creds: {
+        appId: string;
+        appSecret: string;
+        domain: string;
+        channelKey?: string;
+    }): void;
+    /** Save WeChat bot login credentials + register the account. */
+    saveWeixinCredentials?(instanceId: string, creds: {
+        accountId: string;
+        token: string;
+        baseUrl: string;
+        userId: string;
+    }): void;
+    /** Read the list of connected WeChat accounts for an instance. */
+    getWeixinAccounts?(instanceId: string): Array<{
+        accountId: string;
+        userId?: string;
+        savedAt?: string;
+    }>;
+    /** Return the list of other instance IDs that share this one's agent-home. */
+    findInstancesSharingHome?(instanceId: string): string[];
+    /** Resolve the canonical agent binary path (OpenClaw only). */
+    resolveBin?(): string;
+    /** Resolve the instance's on-disk config file path. */
+    resolveConfigPath?(instanceId: string): string;
+    /** Resolve the legacy (pre-state-dir) config file path if applicable. */
+    resolveLegacyConfigPath?(instanceId: string): string;
+    /** Resolve the agent-home directory for an instance (not the instance dir). */
+    resolveAgentHome?(instanceId: string): string;
+    /**
+     * Build the env var set the adapter's native CLI expects when run as
+     * a subprocess (e.g. for backup/restore via `openclaw backup create`).
+     * Used by backup-manager so it doesn't hardcode `OPENCLAW_HOME`.
+     */
+    buildCliEnv?(instanceId: string): Record<string, string>;
+    /**
+     * Read the gateway port out of a raw runtime record — used as a
+     * back-compat fallback when `RuntimeSpec.ports[]` is empty (legacy
+     * OpenClaw instances still persist their port in `runtime.env`).
+     */
+    readLegacyGatewayPort?(runtime: Record<string, any>): number | null;
+    /**
+     * Rewrite a runtime spec in place to target a new host port. Called
+     * by `reallocateGatewayPort` when the previously-assigned port is
+     * busy at start time — each adapter knows how to express the change
+     * in its own runtime shape (args, env, ports[], etc.).
+     */
+    reallocateRuntimePort?(runtime: Record<string, any>, newPort: number): void;
+    /**
+     * Job name prefix for Nomad submissions. Framework reads this via
+     * `getAdapter(agentType).nomadJobPrefix` so nomad-manager doesn't hardcode
+     * per-runtime prefixes.
+     */
+    readonly nomadJobPrefix?: string;
+    /**
+     * Nomad task name inside the TaskGroup. Framework code (nomad-manager.ts)
+     * reads allocation state, stats, and log streams keyed by this name.
+     * Default "gateway" — an adapter can override if its buildNomadTask()
+     * returns a different `Name`.
+     */
+    readonly nomadTaskName?: string;
+    /**
+     * Whether this adapter's runtime install is **required** for overall
+     * panel readiness. When true, a failed install in `runFullSetup` aborts
+     * the whole setup (panel.json not written as complete). When false (the
+     * default), install failures are downgraded to warning-level step
+     * results — the panel still completes setup and the user can install
+     * this agent later from the wizard.
+     *
+     * Only `openclaw` is required today (it is the default/core runtime).
+     * Third-party agents should leave this unset so upgrade paths don't
+     * break when their image registry is unreachable.
+     */
+    readonly required?: boolean;
+    /**
+     * Suffix appended to `nomad/jobs/<jid>/` for the adapter's per-instance
+     * secret storage (e.g. "openclaw/gateway"). When undefined, nomad-manager
+     * skips all Variable writes for this adapter — adapters that do not use
+     * Nomad Variables (no Template interpolation) should leave it unset.
+     *
+     * The value must match the path referenced by the adapter's own
+     * `buildNomadTask()` Templates so the template interpolation resolves.
+     */
+    readonly nomadVariablePath?: string;
+    /**
+     * Build the Nomad task definition for this instance. Called by
+     * `nomad-manager.buildJob()` at start time. Lets adapters fully own how
+     * their RuntimeSpec maps onto a Nomad docker/raw_exec task (volumes,
+     * templates, cap_drop profile, etc.) without nomad-manager knowing the
+     * runtime kind. Name of the task becomes the Nomad task group's Name.
+     */
+    buildNomadTask?(instanceId: string): Promise<Record<string, any>>;
+    /**
+     * Framework → adapter delete hook. Lets the adapter decide whether to
+     * preserve a custom agent-home directory when the instance is removed.
+     * Returns a list of warnings surfaced to the caller.
+     */
+    onDelete?(args: {
+        instanceId: string;
+        meta: Record<string, any>;
+    }): Promise<string[]>;
+    /**
+     * Install the runtime binaries / docker images / shim templates required
+     * to launch this agent. Called by `setup-manager.install<Kind>()` via
+     * adapter dispatch. Returns an InstallResult-shaped object; the framework
+     * layer is agnostic to the exact shape so we stay typed as `any` to
+     * avoid a cross-module dependency back into setup-manager types.
+     */
+    installRuntime?(opts?: Record<string, any>): Promise<any>;
+    /**
+     * Non-blocking variant: returns immediately with a task id the caller
+     * can poll via `/api/setup/tasks/:id` SSE. Adapters implement this when
+     * their install takes long enough that the HTTP layer wants to avoid
+     * holding the connection open (Hermes image pull, OpenClaw docker build).
+     */
+    startInstallRuntime?(opts?: Record<string, any>): any;
+    /**
+     * Build the runtime's docker image (OpenClaw only — baked base image
+     * shared across all OpenClaw instances). Non-OpenClaw adapters may leave
+     * this unimplemented.
+     */
+    buildRuntimeImage?(opts?: Record<string, any>): Promise<any>;
+    /**
+     * Non-blocking variant of `buildRuntimeImage`.
+     */
+    startBuildRuntimeImage?(opts?: Record<string, any>): any;
+    /**
+     * One-shot, panel-level migration invoked at server startup. Adapters
+     * use this to rewrite stale panel.json catalog entries (mutable image
+     * tags → digest-pinned tags) or perform similar self-repair that has
+     * to happen before instances start. Must be idempotent and silent on
+     * no-op. The framework runs all registered adapters' migrations via
+     * `runStartupMigrations()` so `server.ts` never imports an adapter.
+     */
+    migrateStartup?(): void | Promise<void>;
+    /**
+     * Report whether this adapter's runtime is ready to spawn instances. The
+     * framework uses this to (a) gate the NewInstance UI, (b) render the
+     * per-agent row in the Setup wizard, and (c) decide whether `runFullSetup`
+     * should invoke `buildRuntimeImage`/`installRuntime` for this agent.
+     *
+     * Shape is intentionally minimal and adapter-agnostic:
+     *   - installed:   everything required to start an instance is present
+     *   - imageReady:  the docker image (if any) is local or pinned
+     *   - version:     free-form version string for the Setup UI label
+     *   - digest:      pinned image digest (when available)
+     *
+     * Implementations should be synchronous or fast-async (no network). They
+     * are called from the status endpoint that the Setup wizard polls.
+     */
+    getInstallStatus?(): {
+        installed: boolean;
+        imageReady: boolean;
+        version?: string;
+        digest?: string;
+    } | Promise<{
+        installed: boolean;
+        imageReady: boolean;
+        version?: string;
+        digest?: string;
+    }>;
+    /**
+     * Register adapter-owned HTTP endpoints. Called by `routes/instances.ts`
+     * at server startup with the shared Fastify instance. Implementations
+     * should use the framework helpers re-exported from `routes/instances.ts`
+     * (validateId, getSvc, HOP_BY_HOP, etc.) so cross-cutting plumbing stays
+     * in one place. New agents that need zero custom routes leave this
+     * unimplemented.
+     */
+    registerRoutes?(app: any): void | Promise<void>;
+    /**
+     * Declarative descriptor for the shared inline-chat forwarder route
+     * `POST /api/instances/:id/agent/chat`. Adapters that declare
+     * `capabilities.gateway.chatPanel === "inline"` set this so the
+     * framework-owned route can dispatch without hardcoding Hermes-specific
+     * env var names or endpoint paths.
+     *
+     * Omit this field (or leave chatPanel !== "inline") and the route
+     * returns HTTP 400 for this runtime.
+     */
+    readonly inlineChatDescriptor?: InlineChatDescriptor;
+}
+/**
+ * Per-adapter configuration for the shared inline-chat HTTP forwarder.
+ * Declarative so a new agent with an OpenAI-compat HTTP endpoint can
+ * plug in without touching `routes/instances.ts`.
+ */
+export interface InlineChatDescriptor {
+    /**
+     * Name of the env var (inside the instance's secretEnv file) that holds
+     * the bearer/auth token for the agent's own chat endpoint. Hermes uses
+     * `API_SERVER_KEY`; third-party agents declare their own name.
+     */
+    apiKeyEnvVar: string;
+    /**
+     * URL path appended to `http://127.0.0.1:<gatewayHostPort>` for the chat
+     * endpoint. Default: `/v1/chat/completions`.
+     */
+    endpointPath?: string;
+    /** Auth header name. Default `Authorization`. */
+    authHeader?: string;
+    /** Prefix applied before the key in the header. Default `Bearer `. */
+    authScheme?: string;
+    /**
+     * Upstream response timeout in milliseconds. Default 120_000. Agents that
+     * run expensive tool loops can raise this; simple chat endpoints can
+     * tighten it.
+     */
+    timeoutMs?: number;
+}

package/dist/services/runtime/types.js

@@ -0,0 +1,14 @@
+/**
+ * Runtime adapter types — §32.2 full decoupling contract.
+ *
+ * Goal: adding a new agent = 1 new file in `runtime/adapters/` + 1 import in
+ * `runtime/index.ts`. Core files (instance-manager / nomad-manager /
+ * setup-manager / routes / llm-proxy) never mention specific agent kinds.
+ *
+ * - Field names use camelCase; on-wire JSON matches the type exactly.
+ * - Legacy OpenClaw path remains wired through `instance-manager` helpers,
+ *   but the control flow now enters through `OpenClawAdapter` methods so
+ *   framework code dispatches via `getAdapter(agentType)` uniformly.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/services/runtime/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/services/runtime/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/services/setup-manager.d.ts

@@ -1,30 +1,20 @@
+import { type Task } from "./task-registry.js";
 export declare function setServerPort(port: number): void;
-export interface TaskEvent {
-    type: "log" | "progress" | "done" | "error";
-    message: string;
-    progress?: number;
-}
-interface Task {
-    id: string;
-    name: string;
-    status: "running" | "done" | "error";
-    events: TaskEvent[];
-    listeners: Set<(event: TaskEvent) => void>;
-}
-export declare function getTask(id: string): Task | undefined;
-export interface TaskSnapshot {
-    id: string;
-    name: string;
-    status: "running" | "done" | "error";
-    events: TaskEvent[];
-}
-export declare function getTaskSnapshot(id: string): TaskSnapshot | undefined;
-/** Find running tasks, optionally filtered by name prefix */
-export declare function getRunningTasks(namePrefix?: string): Array<{
-    id: string;
-    name: string;
+export { createTask, emitTask, getTask, getTaskSnapshot, getRunningTasks, subscribeTask, } from "./task-registry.js";
+export type { Task, TaskEvent, TaskSnapshot } from "./task-registry.js";
+/** Run a shell command as a spawned process, streaming output to a task */
+export declare function spawnWithTask(task: Task, cmd: string, args: string[], options?: {
+    timeout?: number;
+    env?: Record<string, string>;
+    cwd?: string;
+    progressParser?: (line: string) => number | null;
+}): Promise<{
+    ok: boolean;
+    output: string;
 }>;
-export declare function subscribeTask(id: string, listener: (event: TaskEvent) => void): (() => void) | null;
+export declare function npmProgressParser(line: string): number | null;
+export declare function dockerBuildProgressParser(line: string): number | null;
+export declare function getDirSizeMB(dir: string): number;
 export interface DependencyStatus {
     name: string;
     installed: boolean;
@@ -50,10 +40,30 @@ export interface SetupStatus {
         id: string;
         name: string;
     }>;
+    /**
+     * Per-runtime install status, keyed by agentType. Populated by iterating
+     * over `listRegisteredAdapters()` and calling each adapter's
+     * `getInstallStatus()`. OpenClaw is **also** reported at the top level
+     * (`openclaw` field + `dockerImageReady`) for backward compat with older
+     * frontends — new frontend code should read `runtimes[agentType]`.
+     */
+    runtimes?: Record<string, {
+        installed: boolean;
+        imageReady: boolean;
+        version?: string;
+        digest?: string;
+        /**
+         * Mirror of `adapter.required`. The Setup wizard must gate overall
+         * completion on `required === true` runtimes only; optional runtimes
+         * (the default for third-party agents) stay advertised in the UI
+         * but do not block progress when absent.
+         */
+        required: boolean;
+    }>;
 }
 /** Enable cgroup memory in boot cmdline if not already enabled. Returns true if a reboot is needed. */
 export declare function ensureCgroupMemory(): boolean;
-export declare function getSetupStatus(): SetupStatus;
+export declare function getSetupStatus(): Promise<SetupStatus>;
 export interface InstallResult {
     ok: boolean;
     message: string;
@@ -71,10 +81,42 @@ export declare function startNomad(): Promise<InstallResult>;
 export declare function stopNomad(): Promise<InstallResult>;
 export declare function installNomadSystemd(): InstallResult;
 export declare function installJishushellSystemd(port?: number): InstallResult;
+/**
+ * Install OpenClaw runtime — thin dispatch wrapper.
+ *
+ * The heavy lifting lives in `OpenClawAdapter.installRuntime()` (§32.2.4).
+ * This wrapper is kept only for back-compat with the existing
+ * `routes/setup.ts` endpoint and the CLI installer.
+ */
 export declare function installOpenclaw(version?: string): Promise<InstallResult>;
-export declare function buildOpenclawDockerImage(tag?: string): Promise<InstallResult>;
-export declare function startBuildOpenclawDockerImage(tag?: string): InstallResult;
+/**
+ * Capture the immutable digest of a locally-present image so HermesAdapter
+ * can pin via digest rather than the mutable tag. Returns undefined if the
+ * image has no RepoDigests (e.g. locally-built image) — caller may still
+ * proceed using the tag alone.
+ */
+export declare function captureImageDigest(imageRef: string): string | undefined;
+/**
+ * Install Hermes runtime — thin dispatch wrapper.
+ *
+ * Heavy lifting lives in `HermesAdapter.installRuntime()` (§32.2.4).
+ */
+export declare function installHermes(): Promise<InstallResult>;
+/**
+ * Non-blocking variant — returns a task id immediately. Implementation
+ * dispatches via `HermesAdapter.startInstallRuntime()`.
+ */
+export declare function startInstallHermes(): InstallResult;
+/** Helper for setup status — true when runtime catalog has hermes entry. */
+export declare function isHermesInstalled(): boolean;
+export type DockerInvocation = {
+    cmd: string;
+    argsPrefix: string[];
+};
+export declare function resolveDockerInvocation(): DockerInvocation;
+/** Blocking: pull or build the OpenClaw docker image. */
 export declare function buildSlimOpenclawImage(tag?: string): Promise<InstallResult>;
+/** Non-blocking: returns immediately with a task id for SSE polling. */
 export declare function startBuildSlimOpenclawImage(tag?: string): InstallResult;
 /** @deprecated Use buildSlimOpenclawImage instead */
 export declare function buildCustomOpenclawImage(tag?: string): Promise<InstallResult>;
@@ -92,4 +134,3 @@ export declare function runFullSetup(options?: {
     ok: boolean;
     steps: SetupProgress[];
 }>;
-export {};