@karmaniverous/jeeves 0.3.1 → 0.4.1

package/dist/index.d.ts

@@ -1,5 +1,255 @@
+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>>>;
+    /**
+     * 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;
+    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;
+    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 +287,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.
  *
@@ -87,62 +449,18 @@ interface WriteComponentVersionOptions {
  * @param options - Component version data to write.
  */
 declare function writeComponentVersion(coreConfigDir: string, options: WriteComponentVersionOptions): void;
-
 /**
- * Component interface types for the Jeeves platform.
+ * Remove a component's version entry from the shared state file.
  *
  * @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 descriptor — the contract that Jeeves component plugins
- * must implement to participate in the platform.
+ * Called during plugin uninstall to prevent the HEARTBEAT writer from
+ * probing a service that's intentionally gone. If the component isn't
+ * in the file, this is a no-op.
+ *
+ * @param coreConfigDir - Path to the core config directory.
+ * @param componentName - The component name to remove.
  */
-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;
-}
+declare function removeComponentVersion(coreConfigDir: string, componentName: string): void;
 
 /**
  * Timer-based orchestrator for managed content writing.
@@ -166,7 +484,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. */
@@ -195,7 +513,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
@@ -249,24 +567,136 @@ 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(descriptor: JeevesComponentDescriptor): ComponentWriter;
+
+/**
+ * Heading-based HEARTBEAT section writer.
+ *
+ * @remarks
+ * Manages the `# Jeeves Platform Status` section in HEARTBEAT.md.
+ * Unlike TOOLS/SOUL/AGENTS (which use HTML comment markers), HEARTBEAT
+ * uses markdown headings as markers — this ensures the file passes
+ * OpenClaw's heartbeat emptiness check when only headings remain.
+ *
+ * The section is always at the bottom of the file (H1 to EOF).
+ * User heartbeat items above the section are preserved.
+ */
+/** The H1 heading that anchors the platform status section. */
+declare const HEARTBEAT_HEADING = "# Jeeves Platform Status";
+/** A single component entry in the HEARTBEAT section. */
+interface HeartbeatEntry {
+    /** Component name (e.g., 'runner', 'watcher'). */
+    name: string;
+    /** Whether the component is declined. */
+    declined: boolean;
+    /** Alert content (list items). Empty string if healthy or declined. */
+    content: string;
+}
+/** Result of parsing the HEARTBEAT section. */
+interface ParsedHeartbeat {
+    /** Content above the `# Jeeves Platform Status` heading (user zone). */
+    userContent: string;
+    /** Whether the heading was found. */
+    found: boolean;
+    /** Parsed component entries. */
+    entries: HeartbeatEntry[];
+}
+/**
+ * Parse the HEARTBEAT.md file content.
+ *
+ * @param fileContent - Full file content.
+ * @returns Parsed result with user zone and component entries.
+ */
+declare function parseHeartbeat(fileContent: string): ParsedHeartbeat;
+/**
+ * Build the HEARTBEAT section content from entries.
+ *
+ * @param entries - Component entries to write.
+ * @returns The full section string (H1 + H2s).
+ */
+declare function buildHeartbeatSection(entries: HeartbeatEntry[]): string;
+/**
+ * Write the HEARTBEAT section to a file.
+ *
+ * @remarks
+ * Replaces everything from `# Jeeves Platform Status` to EOF.
+ * Preserves user content above the heading. Uses file-level locking.
+ *
+ * @param filePath - Absolute path to HEARTBEAT.md.
+ * @param entries - Component entries to write.
+ */
+declare function writeHeartbeatSection(filePath: string, entries: HeartbeatEntry[]): Promise<void>;
+
+/**
+ * HEARTBEAT health orchestration.
+ *
+ * @remarks
+ * Determines the state of each platform component and generates
+ * HEARTBEAT entries with actionable alert text. Applies the dependency
+ * graph for alert suppression and auto-decline.
+ */
+
+/** Component state as determined by the orchestrator. */
+type ComponentState = 'not_installed' | 'deps_missing' | 'config_missing' | 'service_not_installed' | 'service_stopped' | 'healthy' | 'update_available';
+/** Options for the orchestrator. */
+interface OrchestrateHeartbeatOptions {
+    /** Path to the core config directory. */
+    coreConfigDir: string;
+    /** Path to the config root. */
+    configRoot: string;
+    /** Existing declined component names (from parsing current HEARTBEAT). */
+    declinedNames: Set<string>;
+}
+/**
+ * Orchestrate HEARTBEAT entries for all platform components.
+ *
+ * @param options - Orchestration configuration.
+ * @returns Array of HeartbeatEntry for writeHeartbeatSection.
  */
-declare function createComponentWriter(component: JeevesComponent): ComponentWriter;
+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.
@@ -285,6 +715,14 @@ interface ManagedMarkers {
     end: string;
     /** Optional H1 title prepended inside the managed block. */
     title?: string;
+    /**
+     * Position of the managed block within the file.
+     * - `'top'`: managed block first, user content below (current default).
+     * - `'bottom'`: user content first, managed block at end.
+     *
+     * @defaultValue `'top'`
+     */
+    position?: 'top' | 'bottom';
 }
 /** Default markers for TOOLS.md managed block. */
 declare const TOOLS_MARKERS: ManagedMarkers;
@@ -320,6 +758,8 @@ declare const WORKSPACE_FILES: {
     readonly soul: "SOUL.md";
     /** AGENTS.md — operational protocols and memory architecture. */
     readonly agents: "AGENTS.md";
+    /** HEARTBEAT.md — platform status and health alerts. */
+    readonly heartbeat: "HEARTBEAT.md";
 };
 /** Templates directory name within core config. */
 declare const TEMPLATES_DIR = "templates";
@@ -352,7 +792,7 @@ declare const META_PORT = 1938;
 declare const DEFAULT_PORTS: Record<string, number>;
 
 /**
- * Managed section IDs and their stable ordering for TOOLS.md.
+ * Managed section IDs, stable ordering, and platform component registry.
  *
  * @remarks
  * Section ordering is fixed to prevent diff churn regardless of which
@@ -378,6 +818,19 @@ type SectionId = (typeof SECTION_IDS)[keyof typeof SECTION_IDS];
  * Sections always appear in this order regardless of write order.
  */
 declare const SECTION_ORDER: readonly string[];
+/**
+ * The four essential platform components.
+ *
+ * @remarks
+ * These components constitute the Jeeves platform. `jeeves install` writes
+ * initial HEARTBEAT "Not installed" alerts for all of them. The HEARTBEAT
+ * writer generates "Not installed" alerts only for platform components not
+ * in `component-versions.json`. Optional future components (not in this list)
+ * appear in HEARTBEAT only after explicit install.
+ */
+declare const PLATFORM_COMPONENTS: readonly ["runner", "watcher", "server", "meta"];
+/** A platform component name. */
+type PlatformComponent = (typeof PLATFORM_COMPONENTS)[number];
 
 /**
  * Core library version, inlined at build time.
@@ -403,12 +856,19 @@ declare const CORE_VERSION: string;
  * 3. Hardcoded library defaults
  */
 
+/** Default bind address for all Jeeves services. */
+declare const DEFAULT_BIND_ADDRESS = "0.0.0.0";
 /** Zod schema for the core config file. */
 declare const coreConfigSchema: z.ZodObject<{
     /** JSON Schema pointer for IDE autocomplete. */
     $schema: z.ZodOptional<z.ZodString>;
     /** Owner identity keys (canonical identityLinks references). */
     owners: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /**
+     * Bind address for all Jeeves services. Default: `0.0.0.0` (all interfaces).
+     * Individual components can override in their own config.
+     */
+    bindAddress: z.ZodDefault<z.ZodString>;
     /** Service URL overrides keyed by service name. */
     services: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
         /** Service URL (must be a valid URL). */
@@ -429,6 +889,7 @@ declare const coreConfigSchema: z.ZodObject<{
     }>>;
 }, "strip", z.ZodTypeAny, {
     owners: string[];
+    bindAddress: string;
     services: Record<string, {
         url: string;
     }>;
@@ -439,6 +900,7 @@ declare const coreConfigSchema: z.ZodObject<{
 }, {
     $schema?: string | undefined;
     owners?: string[] | undefined;
+    bindAddress?: string | undefined;
     services?: Record<string, {
         url: string;
     }> | undefined;
@@ -455,6 +917,41 @@ type CoreConfig = z.infer<typeof coreConfigSchema>;
  */
 declare function generateJsonSchema(): Record<string, unknown>;
 
+/**
+ * Resolve the bind address for a Jeeves service.
+ *
+ * @remarks
+ * Resolution order (four-tier):
+ * 1. Component config `bindAddress` field (if componentName provided)
+ * 2. Core config `bindAddress` field
+ * 3. `JEEVES_BIND_ADDRESS` environment variable
+ * 4. Default: `0.0.0.0`
+ */
+/**
+ * Resolve the bind address for a Jeeves service.
+ *
+ * @param componentName - Optional component name for component-specific override.
+ * @returns The resolved bind address.
+ */
+declare function getBindAddress(componentName?: string): string;
+
+/**
+ * Platform-aware service state detection.
+ *
+ * @remarks
+ * Detects whether a system service is installed and running.
+ * Delegates to NSSM (Windows), systemd (Linux), or launchd (macOS).
+ */
+/** Service states returned by getServiceState. */
+type ServiceState = 'not_installed' | 'stopped' | 'running';
+/**
+ * Detect the state of a system service by name.
+ *
+ * @param serviceName - The service name (e.g., 'jeeves-runner').
+ * @returns The detected service state.
+ */
+declare function getServiceState(serviceName: string): ServiceState;
+
 /**
  * Service URL resolution.
  *
@@ -813,12 +1310,34 @@ interface SeedContentOptions {
  * @remarks
  * Uses the same `updateManagedSection()` code path as writer cycles.
  * Creates core config with defaults if missing. Copies templates.
+ * Writes initial HEARTBEAT with "Not installed" alerts for all platform components.
  * Jaccard cleanup detection runs automatically via `updateManagedSection`.
  *
  * @param options - Seeding configuration.
  */
 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.
  *
@@ -898,86 +1417,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.
  *
@@ -1063,5 +1502,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_CORE_VERSION, DEFAULT_PORTS, META_PORT, 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, checkRegistryVersion, connectionFail, coreConfigSchema, createAsyncContentCache, createComponentWriter, createConfigQueryHandler, fail, fetchJson, fetchWithTimeout, formatBeginMarker, formatEndMarker, generateJsonSchema, getComponentConfigDir, getConfigRoot, getCoreConfigDir, getCoreConfigFile, getServiceUrl, getWorkspacePath, init, jaccard, needsCleanup, ok, parseManaged, patchConfig, postJson, readComponentVersions, refreshPlatformContent, removeManagedSection, resetInit, resolveConfigPath, resolveOpenClawHome, resolveOptionalPluginSetting, resolvePluginSetting, resolveWorkspacePath, seedContent, shingles, shouldWrite, updateManagedSection, withFileLock, writeComponentVersion };
-export type { AsyncContentCacheOptions, ComponentVersionEntry, ComponentVersionsState, ConfigQueryHandler, ConfigQueryResponse, CoreConfig, InitOptions, JeevesComponent, ManagedMarkers, ManagedSection, ParseManagedResult, PluginApi, PluginCommands, RefreshPlatformContentOptions, RemoveManagedSectionOptions, SectionId, SeedContentOptions, ServiceCommands, 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 };