@karmaniverous/jeeves 0.4.0 → 0.4.2

package/dist/index.d.ts

@@ -1,5 +1,266 @@
+import { Command } from '@commander-js/extra-typings';
 import { z } from 'zod';
 
+/**
+ * Core types for the OpenClaw plugin SDK.
+ *
+ * @remarks
+ * These types define the contract between plugins and the OpenClaw gateway.
+ * They unify the various `PluginApi` definitions previously duplicated
+ * across component plugins into a single canonical source.
+ */
+/** Result shape returned by tool executions. */
+interface ToolResult {
+    /** Content blocks — typically a single text block. */
+    content: Array<{
+        /** MIME type identifier (e.g. `"text"`). */
+        type: string;
+        /** Text content of the block. */
+        text: string;
+    }>;
+    /** Whether this result represents an error. */
+    isError?: boolean;
+}
+/** Tool descriptor for registration with the OpenClaw gateway. */
+interface ToolDescriptor {
+    /** Unique tool name. */
+    name: string;
+    /** Human-readable description. */
+    description: string;
+    /** JSON Schema for the tool's parameters. */
+    parameters: Record<string, unknown>;
+    /** Execute the tool with the given parameters. */
+    execute: (id: string, params: Record<string, unknown>) => Promise<ToolResult>;
+}
+/** Options for tool registration. */
+interface ToolRegistrationOptions {
+    /** Whether the tool is optional (non-fatal if registration fails). */
+    optional?: boolean;
+}
+/**
+ * Canonical OpenClaw plugin API interface.
+ *
+ * @remarks
+ * This is the shape of the `api` object passed to plugins by the
+ * OpenClaw gateway at registration time. Fields are optional where
+ * the gateway may not provide them in all versions.
+ */
+interface PluginApi {
+    /** OpenClaw configuration object. */
+    config?: {
+        /** Agent configuration block. */
+        agents?: {
+            /** Default agent settings. */
+            defaults?: {
+                /** Absolute path to the workspace root directory. */
+                workspace?: string;
+            };
+        };
+        /** Installed plugin configuration. */
+        plugins?: {
+            /** Plugin entries keyed by plugin ID. */
+            entries?: Record<string, {
+                /** Plugin-specific configuration key-value pairs. */
+                config?: Record<string, unknown>;
+            }>;
+        };
+    };
+    /**
+     * Resolve a path relative to the OpenClaw workspace.
+     *
+     * @remarks
+     * Present on newer OpenClaw builds; optional for backwards compatibility.
+     */
+    resolvePath?: (input: string) => string;
+    /**
+     * Register a tool with the OpenClaw gateway.
+     *
+     * @param tool - Tool descriptor.
+     * @param options - Registration options.
+     */
+    registerTool(tool: ToolDescriptor, options?: ToolRegistrationOptions): void;
+}
+
+/**
+ * Zod schema for the Jeeves component descriptor.
+ *
+ * @remarks
+ * The descriptor replaces the v0.4.0 `JeevesComponent` interface with a
+ * Zod-first approach. The TypeScript type is inferred via `z.infer<>`.
+ * Validates at parse time: prime interval, callable functions.
+ */
+
+/**
+ * Check whether a number is prime.
+ *
+ * @param n - Number to check.
+ * @returns `true` if n is prime.
+ */
+declare function isPrime(n: number): boolean;
+/**
+ * Zod schema for the Jeeves component descriptor.
+ *
+ * @remarks
+ * Single source of truth for what a component must provide.
+ * Factories consume this descriptor to produce CLI commands,
+ * plugin tools, and HTTP handlers.
+ */
+declare const jeevesComponentDescriptorSchema: z.ZodObject<{
+    /** Component name (e.g., 'watcher', 'runner', 'server', 'meta'). */
+    name: z.ZodString;
+    /** Component version (from package.json). */
+    version: z.ZodString;
+    /** npm package name for the service. */
+    servicePackage: z.ZodString;
+    /** npm package name for the plugin. */
+    pluginPackage: z.ZodString;
+    /** System service name. Defaults to `jeeves-${name}` when not provided. */
+    serviceName: z.ZodOptional<z.ZodString>;
+    /** Default port for the service's HTTP API. */
+    defaultPort: z.ZodNumber;
+    /** Zod schema for validating config files. */
+    configSchema: z.ZodType<z.ZodTypeAny, z.ZodTypeDef, z.ZodTypeAny>;
+    /** Config file name (e.g., 'jeeves-watcher.config.json'). */
+    configFileName: z.ZodString;
+    /** Returns a default config object for `init`. */
+    initTemplate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    /**
+     * Service-side callback after config apply. Receives the merged,
+     * validated config (not the raw patch). Optional — if omitted,
+     * write-only (service picks up changes on restart).
+     */
+    onConfigApply: z.ZodOptional<z.ZodFunction<z.ZodTuple<[z.ZodRecord<z.ZodString, z.ZodUnknown>], z.ZodUnknown>, z.ZodPromise<z.ZodVoid>>>;
+    /**
+     * Custom merge function for config apply. Receives the existing config
+     * and the patch, returns the merged result. Optional — if omitted,
+     * the default deep-merge (object-recursive, array-replacing) is used.
+     *
+     * Use this to implement domain-specific merge strategies such as
+     * name-based array merging for inference rules.
+     */
+    customMerge: z.ZodOptional<z.ZodFunction<z.ZodTuple<[z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodRecord<z.ZodString, z.ZodUnknown>], z.ZodUnknown>, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    /**
+     * Returns command + args for launching the service process.
+     * Consumed by `start` CLI command and `service install`.
+     */
+    startCommand: z.ZodFunction<z.ZodTuple<[z.ZodString], z.ZodUnknown>, z.ZodArray<z.ZodString, "many">>;
+    /** TOOLS.md section name (e.g., 'Watcher'). */
+    sectionId: z.ZodString;
+    /** Refresh interval in seconds (must be a prime number). */
+    refreshIntervalSeconds: z.ZodEffects<z.ZodNumber, number, number>;
+    /** Produce the component's TOOLS.md section content. */
+    generateToolsContent: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodString>;
+    /** Component dependencies for HEARTBEAT alert suppression. */
+    dependencies: z.ZodOptional<z.ZodObject<{
+        hard: z.ZodArray<z.ZodString, "many">;
+        soft: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        hard: string[];
+        soft: string[];
+    }, {
+        hard: string[];
+        soft: string[];
+    }>>;
+    /** Extension point: add custom CLI commands to the service CLI. */
+    customCliCommands: z.ZodOptional<z.ZodFunction<z.ZodTuple<[z.ZodType<Command<[], {}, {}>, z.ZodTypeDef, Command<[], {}, {}>>], z.ZodUnknown>, z.ZodVoid>>;
+    /** Extension point: return additional plugin tool descriptors. */
+    customPluginTools: z.ZodOptional<z.ZodFunction<z.ZodTuple<[z.ZodType<PluginApi, z.ZodTypeDef, PluginApi>], z.ZodUnknown>, z.ZodArray<z.ZodUnknown, "many">>>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    version: string;
+    servicePackage: string;
+    pluginPackage: string;
+    defaultPort: number;
+    configSchema: z.ZodTypeAny;
+    configFileName: string;
+    initTemplate: (...args: unknown[]) => Record<string, unknown>;
+    startCommand: (args_0: string, ...args: unknown[]) => string[];
+    sectionId: string;
+    refreshIntervalSeconds: number;
+    generateToolsContent: (...args: unknown[]) => string;
+    serviceName?: string | undefined;
+    onConfigApply?: ((args_0: Record<string, unknown>, ...args: unknown[]) => Promise<void>) | undefined;
+    customMerge?: ((args_0: Record<string, unknown>, args_1: Record<string, unknown>, ...args: unknown[]) => Record<string, unknown>) | undefined;
+    dependencies?: {
+        hard: string[];
+        soft: string[];
+    } | undefined;
+    customCliCommands?: ((args_0: Command<[], {}, {}>, ...args: unknown[]) => void) | undefined;
+    customPluginTools?: ((args_0: PluginApi, ...args: unknown[]) => unknown[]) | undefined;
+}, {
+    name: string;
+    version: string;
+    servicePackage: string;
+    pluginPackage: string;
+    defaultPort: number;
+    configSchema: z.ZodTypeAny;
+    configFileName: string;
+    initTemplate: (...args: unknown[]) => Record<string, unknown>;
+    startCommand: (args_0: string, ...args: unknown[]) => string[];
+    sectionId: string;
+    refreshIntervalSeconds: number;
+    generateToolsContent: (...args: unknown[]) => string;
+    serviceName?: string | undefined;
+    onConfigApply?: ((args_0: Record<string, unknown>, ...args: unknown[]) => Promise<void>) | undefined;
+    customMerge?: ((args_0: Record<string, unknown>, args_1: Record<string, unknown>, ...args: unknown[]) => Record<string, unknown>) | undefined;
+    dependencies?: {
+        hard: string[];
+        soft: string[];
+    } | undefined;
+    customCliCommands?: ((args_0: Command<[], {}, {}>, ...args: unknown[]) => void) | undefined;
+    customPluginTools?: ((args_0: PluginApi, ...args: unknown[]) => unknown[]) | undefined;
+}>;
+/** Inferred TypeScript type for the component descriptor. */
+type JeevesComponentDescriptor = z.infer<typeof jeevesComponentDescriptorSchema>;
+/**
+ * Derive the effective service name from a descriptor.
+ *
+ * @param descriptor - The component descriptor.
+ * @returns The service name (explicit or derived from `jeeves-{name}`).
+ */
+declare function getEffectiveServiceName(descriptor: JeevesComponentDescriptor): string;
+
+/**
+ * Factory for a framework-agnostic config apply HTTP handler.
+ *
+ * @remarks
+ * Derives the config file path from the descriptor, validates patches
+ * against the descriptor's Zod schema, deep-merges (or replaces),
+ * writes atomically, and calls the optional `onConfigApply` callback.
+ */
+
+/** Request shape for the config apply handler. */
+interface ConfigApplyRequest {
+    /** Config patch to apply (deep-merged with existing config). */
+    patch: Record<string, unknown>;
+    /** When true, replace the entire config instead of merging. */
+    replace?: boolean;
+}
+/** Result shape returned by the config apply handler. */
+interface ConfigApplyResult {
+    /** HTTP status code. */
+    status: number;
+    /** Response body. */
+    body: unknown;
+}
+/** Config apply handler function signature. */
+type ConfigApplyHandler = (request: ConfigApplyRequest) => Promise<ConfigApplyResult>;
+/**
+ * Create a framework-agnostic config apply handler.
+ *
+ * @remarks
+ * The handler:
+ * 1. Reads existing config from `{configRoot}/jeeves-{name}/{configFileName}`
+ * 2. Deep-merges the patch (or replaces if `replace: true`)
+ * 3. Validates the merged result against `descriptor.configSchema`
+ * 4. Writes atomically
+ * 5. Calls `descriptor.onConfigApply` with the merged config (if defined)
+ *
+ * @param descriptor - The component descriptor.
+ * @returns An async handler returning `{ status, body }`.
+ */
+declare function createConfigApplyHandler(descriptor: JeevesComponentDescriptor): ConfigApplyHandler;
+
 /**
  * Generic config query handler with JSONPath support.
  *
@@ -37,6 +298,118 @@ type ConfigQueryHandler = (query: {
  */
 declare function createConfigQueryHandler(getConfig: () => unknown): ConfigQueryHandler;
 
+/**
+ * Factory for a framework-agnostic `/status` HTTP handler.
+ *
+ * @remarks
+ * Returns a standard status response shape consumed by HEARTBEAT
+ * orchestration and the `{name}_status` plugin tool.
+ * Tracks process start time internally for uptime calculation.
+ */
+/** Options for creating a status handler. */
+interface CreateStatusHandlerOptions {
+    /** Component name (e.g., 'watcher'). */
+    name: string;
+    /** Component version. */
+    version: string;
+    /** Optional callback returning component-specific health details. */
+    getHealth?: () => Promise<Record<string, unknown>>;
+}
+/** Standard status response body. */
+interface StatusResponse {
+    /** Component name. */
+    name: string;
+    /** Component version. */
+    version: string;
+    /** Seconds since process start. */
+    uptime: number;
+    /** Overall status. */
+    status: 'healthy' | 'degraded' | 'unhealthy';
+    /** Component-specific health details. */
+    health: Record<string, unknown>;
+}
+/** Return type from a status handler invocation. */
+interface StatusHandlerResult {
+    /** HTTP status code. */
+    status: number;
+    /** Response body. */
+    body: StatusResponse;
+}
+/** Status handler function signature. */
+type StatusHandler = () => Promise<StatusHandlerResult>;
+/**
+ * Create a framework-agnostic status handler.
+ *
+ * @param options - Handler configuration.
+ * @returns An async function returning `{ status, body }`.
+ */
+declare function createStatusHandler(options: CreateStatusHandlerOptions): StatusHandler;
+
+/**
+ * Factory for the standard `-openclaw` plugin installer CLI.
+ *
+ * @remarks
+ * Produces a Commander program with `install` and `uninstall` commands
+ * that handle the full plugin lifecycle: copy dist to extensions,
+ * patch OpenClaw config, manage HEARTBEAT entries, and clean up
+ * managed sections on uninstall.
+ */
+
+/** Options for creating a plugin installer CLI. */
+interface CreatePluginCliOptions {
+    /** Plugin identifier (e.g., 'jeeves-watcher-openclaw'). */
+    pluginId: string;
+    /** Absolute path to the dist directory to copy. */
+    distDir: string;
+    /** npm package name for the plugin. */
+    pluginPackage: string;
+    /** Component name (e.g., 'watcher'). Derived from pluginId if omitted. */
+    componentName?: string;
+    /** Workspace root (defaults to OpenClaw workspace). */
+    workspace?: string;
+    /** Config root (defaults to 'j:/config'). */
+    configRoot?: string;
+}
+/**
+ * Create a standard plugin installer CLI program.
+ *
+ * @param options - Plugin CLI configuration.
+ * @returns A Commander program ready for `.parse()`.
+ */
+declare function createPluginCli(options: CreatePluginCliOptions): Command;
+
+/**
+ * Factory for the standard Jeeves service CLI.
+ *
+ * @remarks
+ * Produces a Commander program with all standard commands from
+ * a component descriptor. Components add domain-specific commands
+ * via `descriptor.customCliCommands`.
+ */
+
+/**
+ * Create a standard service CLI program from a component descriptor.
+ *
+ * @remarks
+ * Standard commands:
+ * - `start -c <path>` - Launch the service process (foreground)
+ * - `status [-p port]` - Probe service health
+ * - `config [jsonpath] [-p port]` - Query running config
+ * - `config validate -c <path>` - Validate a config file
+ * - `config apply [-p port] [--file path] [--replace]` - Apply config patch
+ * - `init [-o path]` - Generate default config
+ * - `service install` - Install system service
+ * - `service uninstall` - Uninstall system service
+ * - `service start` - Start system service
+ * - `service stop` - Stop system service
+ * - `service restart` - Restart system service
+ * - `service status` - Query system service state
+ *
+ * @param descriptor - The component descriptor.
+ * @returns A Commander program ready for custom commands and `.parse()`.
+ */
+declare function createServiceCli(descriptor: JeevesComponentDescriptor): Command;
+
 /**
  * Shared component version state file management.
  *
@@ -100,84 +473,6 @@ declare function writeComponentVersion(coreConfigDir: string, options: WriteComp
  */
 declare function removeComponentVersion(coreConfigDir: string, componentName: string): void;
 
-/**
- * Component interface types for the Jeeves platform.
- *
- * @remarks
- * These types define the contract that component plugins must implement
- * to participate in the platform. The `JeevesComponent` interface is
- * the primary integration point.
- */
-/** Service health status. */
-interface ServiceStatus {
-    /** Whether the service is running. */
-    running: boolean;
-    /** Optional version string. */
-    version?: string;
-    /** Optional uptime in seconds. */
-    uptimeSeconds?: number;
-}
-/** Service lifecycle commands. */
-interface ServiceCommands {
-    /** Stop the service. */
-    stop(): Promise<void>;
-    /** Uninstall the service. */
-    uninstall(): Promise<void>;
-    /** Query service status. */
-    status(): Promise<ServiceStatus>;
-}
-/** Plugin lifecycle commands. */
-interface PluginCommands {
-    /** Uninstall the plugin. */
-    uninstall(): Promise<void>;
-}
-/** Component dependency declarations. */
-interface ComponentDependencies {
-    /**
-     * Hard dependencies — the component cannot function without these.
-     * If a hard dep is not healthy, suppress all alerts for this component
-     * except a "waiting for dependency" message. If a hard dep is declined,
-     * auto-decline this component.
-     */
-    hard: string[];
-    /**
-     * Soft dependencies — the component works without these but with reduced
-     * functionality. When the component is healthy and a soft dep is missing,
-     * generate an informational alert. No alert when a soft dep is declined.
-     */
-    soft: string[];
-}
-/**
- * Component descriptor — the contract that Jeeves component plugins
- * must implement to participate in the platform.
- */
-interface JeevesComponent {
-    /** Component name (e.g., 'watcher', 'runner', 'server', 'meta'). */
-    name: string;
-    /** Component's own version (plugin package version). */
-    version: string;
-    /** npm package name for the service (e.g., `\@karmaniverous/jeeves-watcher`). */
-    servicePackage?: string;
-    /** npm package name for the plugin (e.g., `\@karmaniverous/jeeves-watcher-openclaw`). */
-    pluginPackage?: string;
-    /** TOOLS.md section name (e.g., 'Watcher'). */
-    sectionId: string;
-    /** Refresh interval in seconds (must be a prime number). */
-    refreshIntervalSeconds: number;
-    /** Produce the component's TOOLS.md section content. */
-    generateToolsContent(): string;
-    /** Service lifecycle commands. */
-    serviceCommands: ServiceCommands;
-    /** Plugin lifecycle commands. */
-    pluginCommands: PluginCommands;
-    /**
-     * Component dependencies. Optional — components with no dependencies
-     * omit this field (runner, watcher). Components with dependencies
-     * declare them here (meta: hard=['watcher'], server: soft=['watcher','runner','meta']).
-     */
-    dependencies?: ComponentDependencies;
-}
-
 /**
  * Timer-based orchestrator for managed content writing.
  *
@@ -200,7 +495,7 @@ declare class ComponentWriter {
     private readonly component;
     private readonly configDir;
     /** @internal */
-    constructor(component: JeevesComponent);
+    constructor(component: JeevesComponentDescriptor);
     /** The component's config directory path. */
     get componentConfigDir(): string;
     /** Whether the writer timer is currently running. */
@@ -229,7 +524,7 @@ declare class ComponentWriter {
  * Creates a synchronous content accessor backed by an async data source.
  *
  * @remarks
- * Solves the sync/async gap in `JeevesComponent.generateToolsContent()`:
+ * Solves the sync/async gap in `JeevesComponentDescriptor.generateToolsContent()`:
  * the interface is synchronous, but most components fetch live data from
  * their HTTP service. This utility returns a sync `() => string` that
  * serves the last successfully fetched value while kicking off a background
@@ -283,24 +578,26 @@ interface AsyncContentCacheOptions {
 declare function createAsyncContentCache(options: AsyncContentCacheOptions): () => string;
 
 /**
- * Factory function for creating a ComponentWriter.
+ * Factory function for creating a ComponentWriter from a descriptor.
  *
  * @remarks
- * Validates the component descriptor at runtime:
- * - `refreshIntervalSeconds` must be a prime number
- * - `serviceCommands` and `pluginCommands` must be provided
- * - `name`, `version`, `sectionId` must be non-empty strings
- * - `generateToolsContent` must be a function
+ * Validates the descriptor via Zod schema and creates a ComponentWriter.
+ * Accepts `JeevesComponentDescriptor` (v0.5.0) only. The v0.4.0
+ * `JeevesComponent` interface is no longer accepted.
  */
 
 /**
  * Create a ComponentWriter for a validated component descriptor.
  *
- * @param component - The component descriptor to validate and wrap.
+ * @remarks
+ * The descriptor is validated via the Zod schema at runtime.
+ * This replaces the v0.4.0 `createComponentWriter(JeevesComponent)`.
+ *
+ * @param descriptor - The component descriptor to validate and wrap.
  * @returns A new `ComponentWriter` instance.
- * @throws Error if the component descriptor is invalid.
+ * @throws ZodError if the descriptor is invalid.
  */
-declare function createComponentWriter(component: JeevesComponent): ComponentWriter;
+declare function createComponentWriter(descriptor: JeevesComponentDescriptor): ComponentWriter;
 
 /**
  * Heading-based HEARTBEAT section writer.
@@ -388,6 +685,30 @@ interface OrchestrateHeartbeatOptions {
  */
 declare function orchestrateHeartbeat(options: OrchestrateHeartbeatOptions): Promise<HeartbeatEntry[]>;
 
+/**
+ * Component interface types for the Jeeves platform.
+ *
+ * @remarks
+ * These types support the platform's HEARTBEAT orchestration and
+ * dependency graph resolution.
+ */
+/** Component dependency declarations. */
+interface ComponentDependencies {
+    /**
+     * Hard dependencies — the component cannot function without these.
+     * If a hard dep is not healthy, suppress all alerts for this component
+     * except a "waiting for dependency" message. If a hard dep is declined,
+     * auto-decline this component.
+     */
+    hard: string[];
+    /**
+     * Soft dependencies — the component works without these but with reduced
+     * functionality. When the component is healthy and a soft dep is missing,
+     * generate an informational alert. No alert when a soft dep is declined.
+     */
+    soft: string[];
+}
+
 /**
  * Comment markers for managed content blocks.
  *
@@ -1007,6 +1328,27 @@ interface SeedContentOptions {
  */
 declare function seedContent(options: SeedContentOptions): Promise<void>;
 
+/**
+ * Factory for the standard plugin tool set.
+ *
+ * @remarks
+ * Produces four standard tools from a component descriptor:
+ * - `{name}_status` - Probe service health + version + uptime
+ * - `{name}_config` - Query running config with optional JSONPath
+ * - `{name}_config_apply` - Push config patch to running service
+ * - `{name}_service` - Service lifecycle management
+ *
+ * Components add domain-specific tools separately.
+ */
+
+/**
+ * Create the standard plugin tool set from a component descriptor.
+ *
+ * @param descriptor - The component descriptor.
+ * @returns Array of tool descriptors to register.
+ */
+declare function createPluginToolset(descriptor: JeevesComponentDescriptor): ToolDescriptor[];
+
 /**
  * HTTP helpers for the OpenClaw plugin SDK.
  *
@@ -1086,86 +1428,6 @@ declare function resolveConfigPath(home: string): string;
  */
 declare function patchConfig(config: Record<string, unknown>, pluginId: string, mode: 'add' | 'remove'): string[];
 
-/**
- * Core types for the OpenClaw plugin SDK.
- *
- * @remarks
- * These types define the contract between plugins and the OpenClaw gateway.
- * They unify the various `PluginApi` definitions previously duplicated
- * across component plugins into a single canonical source.
- */
-/** Result shape returned by tool executions. */
-interface ToolResult {
-    /** Content blocks — typically a single text block. */
-    content: Array<{
-        /** MIME type identifier (e.g. `"text"`). */
-        type: string;
-        /** Text content of the block. */
-        text: string;
-    }>;
-    /** Whether this result represents an error. */
-    isError?: boolean;
-}
-/** Tool descriptor for registration with the OpenClaw gateway. */
-interface ToolDescriptor {
-    /** Unique tool name. */
-    name: string;
-    /** Human-readable description. */
-    description: string;
-    /** JSON Schema for the tool's parameters. */
-    parameters: Record<string, unknown>;
-    /** Execute the tool with the given parameters. */
-    execute: (id: string, params: Record<string, unknown>) => Promise<ToolResult>;
-}
-/** Options for tool registration. */
-interface ToolRegistrationOptions {
-    /** Whether the tool is optional (non-fatal if registration fails). */
-    optional?: boolean;
-}
-/**
- * Canonical OpenClaw plugin API interface.
- *
- * @remarks
- * This is the shape of the `api` object passed to plugins by the
- * OpenClaw gateway at registration time. Fields are optional where
- * the gateway may not provide them in all versions.
- */
-interface PluginApi {
-    /** OpenClaw configuration object. */
-    config?: {
-        /** Agent configuration block. */
-        agents?: {
-            /** Default agent settings. */
-            defaults?: {
-                /** Absolute path to the workspace root directory. */
-                workspace?: string;
-            };
-        };
-        /** Installed plugin configuration. */
-        plugins?: {
-            /** Plugin entries keyed by plugin ID. */
-            entries?: Record<string, {
-                /** Plugin-specific configuration key-value pairs. */
-                config?: Record<string, unknown>;
-            }>;
-        };
-    };
-    /**
-     * Resolve a path relative to the OpenClaw workspace.
-     *
-     * @remarks
-     * Present on newer OpenClaw builds; optional for backwards compatibility.
-     */
-    resolvePath?: (input: string) => string;
-    /**
-     * Register a tool with the OpenClaw gateway.
-     *
-     * @param tool - Tool descriptor.
-     * @param options - Registration options.
-     */
-    registerTool(tool: ToolDescriptor, options?: ToolRegistrationOptions): void;
-}
-
 /**
  * Plugin resolution helpers for the OpenClaw plugin SDK.
  *
@@ -1251,5 +1513,48 @@ declare function fail(error: unknown): ToolResult;
  */
 declare function connectionFail(error: unknown, baseUrl: string, pluginId: string): ToolResult;
 
-export { AGENTS_MARKERS, CLEANUP_FLAG, COMPONENT_CONFIG_PREFIX, COMPONENT_VERSIONS_FILE, CONFIG_FILE, CORE_CONFIG_DIR, CORE_VERSION, ComponentWriter, DEFAULT_BIND_ADDRESS, DEFAULT_CORE_VERSION, DEFAULT_PORTS, HEARTBEAT_HEADING, META_PORT, PLATFORM_COMPONENTS, REGISTRY_CACHE_FILE, RUNNER_PORT, SECTION_IDS, SECTION_ORDER, SERVER_PORT, SOUL_MARKERS, STALENESS_THRESHOLD_MS, STALE_LOCK_MS, TEMPLATES_DIR, TOOLS_MARKERS, VERSION_STAMP_PATTERN, WATCHER_PORT, WORKSPACE_FILES, atomicWrite, buildHeartbeatSection, checkRegistryVersion, connectionFail, coreConfigSchema, createAsyncContentCache, createComponentWriter, createConfigQueryHandler, fail, fetchJson, fetchWithTimeout, formatBeginMarker, formatEndMarker, generateJsonSchema, getBindAddress, getComponentConfigDir, getConfigRoot, getCoreConfigDir, getCoreConfigFile, getServiceState, getServiceUrl, getWorkspacePath, init, jaccard, needsCleanup, ok, orchestrateHeartbeat, parseHeartbeat, parseManaged, patchConfig, postJson, readComponentVersions, refreshPlatformContent, removeComponentVersion, removeManagedSection, resetInit, resolveConfigPath, resolveOpenClawHome, resolveOptionalPluginSetting, resolvePluginSetting, resolveWorkspacePath, seedContent, shingles, shouldWrite, updateManagedSection, withFileLock, writeComponentVersion, writeHeartbeatSection };
-export type { AsyncContentCacheOptions, ComponentDependencies, ComponentState, ComponentVersionEntry, ComponentVersionsState, ConfigQueryHandler, ConfigQueryResponse, CoreConfig, HeartbeatEntry, InitOptions, JeevesComponent, ManagedMarkers, ManagedSection, OrchestrateHeartbeatOptions, ParseManagedResult, ParsedHeartbeat, PlatformComponent, PluginApi, PluginCommands, RefreshPlatformContentOptions, RemoveManagedSectionOptions, SectionId, SeedContentOptions, ServiceCommands, ServiceState, ServiceStatus, ToolDescriptor, ToolRegistrationOptions, ToolResult, UpdateManagedSectionOptions, VersionStamp, WriteComponentVersionOptions };
+/**
+ * Factory for platform-aware service lifecycle management.
+ *
+ * @remarks
+ * Produces a `ServiceManager` that handles install, uninstall, start,
+ * stop, restart, and status for system services. Delegates to NSSM
+ * (Windows), systemd (Linux), or launchd (macOS) based on platform.
+ */
+
+/** Options for service manager commands that accept a service name override. */
+interface ServiceManagerOptions {
+    /** Override the default service name. */
+    name?: string;
+    /** Override config path for install. */
+    configPath?: string;
+}
+/** Service lifecycle manager produced by the factory. */
+interface ServiceManager {
+    /** Install the service with the system service manager. */
+    install(options?: ServiceManagerOptions): void;
+    /** Uninstall the service from the system service manager. */
+    uninstall(options?: ServiceManagerOptions): void;
+    /** Start the service. */
+    start(options?: ServiceManagerOptions): void;
+    /** Stop the service. */
+    stop(options?: ServiceManagerOptions): void;
+    /** Restart the service (stop + start). */
+    restart(options?: ServiceManagerOptions): void;
+    /** Query the service state. */
+    status(options?: ServiceManagerOptions): ServiceState;
+}
+/**
+ * Create a platform-aware service manager from a component descriptor.
+ *
+ * @remarks
+ * Detects the current platform and returns a `ServiceManager` that
+ * delegates to NSSM (Windows), systemd (Linux), or launchd (macOS).
+ *
+ * @param descriptor - The component descriptor.
+ * @returns A `ServiceManager` for the current platform.
+ */
+declare function createServiceManager(descriptor: JeevesComponentDescriptor): ServiceManager;
+
+export { AGENTS_MARKERS, CLEANUP_FLAG, COMPONENT_CONFIG_PREFIX, COMPONENT_VERSIONS_FILE, CONFIG_FILE, CORE_CONFIG_DIR, CORE_VERSION, ComponentWriter, DEFAULT_BIND_ADDRESS, DEFAULT_CORE_VERSION, DEFAULT_PORTS, HEARTBEAT_HEADING, META_PORT, PLATFORM_COMPONENTS, REGISTRY_CACHE_FILE, RUNNER_PORT, SECTION_IDS, SECTION_ORDER, SERVER_PORT, SOUL_MARKERS, STALENESS_THRESHOLD_MS, STALE_LOCK_MS, TEMPLATES_DIR, TOOLS_MARKERS, VERSION_STAMP_PATTERN, WATCHER_PORT, WORKSPACE_FILES, atomicWrite, buildHeartbeatSection, checkRegistryVersion, connectionFail, coreConfigSchema, createAsyncContentCache, createComponentWriter, createConfigApplyHandler, createConfigQueryHandler, createPluginCli, createPluginToolset, createServiceCli, createServiceManager, createStatusHandler, fail, fetchJson, fetchWithTimeout, formatBeginMarker, formatEndMarker, generateJsonSchema, getBindAddress, getComponentConfigDir, getConfigRoot, getCoreConfigDir, getCoreConfigFile, getEffectiveServiceName, getServiceState, getServiceUrl, getWorkspacePath, init, isPrime, jaccard, jeevesComponentDescriptorSchema, needsCleanup, ok, orchestrateHeartbeat, parseHeartbeat, parseManaged, patchConfig, postJson, readComponentVersions, refreshPlatformContent, removeComponentVersion, removeManagedSection, resetInit, resolveConfigPath, resolveOpenClawHome, resolveOptionalPluginSetting, resolvePluginSetting, resolveWorkspacePath, seedContent, shingles, shouldWrite, updateManagedSection, withFileLock, writeComponentVersion, writeHeartbeatSection };
+export type { AsyncContentCacheOptions, ComponentDependencies, ComponentState, ComponentVersionEntry, ComponentVersionsState, ConfigApplyHandler, ConfigApplyRequest, ConfigApplyResult, ConfigQueryHandler, ConfigQueryResponse, CoreConfig, CreatePluginCliOptions, CreateStatusHandlerOptions, HeartbeatEntry, InitOptions, JeevesComponentDescriptor, ManagedMarkers, ManagedSection, OrchestrateHeartbeatOptions, ParseManagedResult, ParsedHeartbeat, PlatformComponent, PluginApi, RefreshPlatformContentOptions, RemoveManagedSectionOptions, SectionId, SeedContentOptions, ServiceManager, ServiceManagerOptions, ServiceState, StatusHandler, StatusHandlerResult, StatusResponse, ToolDescriptor, ToolRegistrationOptions, ToolResult, UpdateManagedSectionOptions, VersionStamp, WriteComponentVersionOptions };