@karmaniverous/jeeves 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -87,6 +87,18 @@ interface WriteComponentVersionOptions {
  * @param options - Component version data to write.
  */
 declare function writeComponentVersion(coreConfigDir: string, options: WriteComponentVersionOptions): void;
+/**
+ * Remove a component's version entry from the shared state file.
+ *
+ * @remarks
+ * 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.
+ */
+declare function removeComponentVersion(coreConfigDir: string, componentName: string): void;
 
 /**
  * Component interface types for the Jeeves platform.
@@ -119,6 +131,22 @@ 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.
@@ -142,6 +170,12 @@ interface JeevesComponent {
     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;
 }
 
 /**
@@ -268,6 +302,92 @@ declare function createAsyncContentCache(options: AsyncContentCacheOptions): ()
  */
 declare function createComponentWriter(component: JeevesComponent): 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 orchestrateHeartbeat(options: OrchestrateHeartbeatOptions): Promise<HeartbeatEntry[]>;
+
 /**
  * Comment markers for managed content blocks.
  *
@@ -285,6 +405,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 +448,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 +482,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 +508,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 +546,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 +579,7 @@ declare const coreConfigSchema: z.ZodObject<{
     }>>;
 }, "strip", z.ZodTypeAny, {
     owners: string[];
+    bindAddress: string;
     services: Record<string, {
         url: string;
     }>;
@@ -439,6 +590,7 @@ declare const coreConfigSchema: z.ZodObject<{
 }, {
     $schema?: string | undefined;
     owners?: string[] | undefined;
+    bindAddress?: string | undefined;
     services?: Record<string, {
         url: string;
     }> | undefined;
@@ -455,6 +607,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,6 +1000,7 @@ 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.
@@ -910,7 +1098,9 @@ declare function patchConfig(config: Record<string, unknown>, pluginId: string,
 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. */
@@ -955,6 +1145,7 @@ interface PluginApi {
         plugins?: {
             /** Plugin entries keyed by plugin ID. */
             entries?: Record<string, {
+                /** Plugin-specific configuration key-value pairs. */
                 config?: Record<string, unknown>;
             }>;
         };
@@ -1060,5 +1251,5 @@ 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 };
+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 };