@karmaniverous/jeeves 0.5.0 → 0.5.3

package/dist/cli/service/index.js

@@ -696,6 +696,21 @@ function createServiceManager(descriptor) {
     }
 }
 
+/**
+ * Shared internal utility functions.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Extract a human-readable message from an unknown caught value.
+ *
+ * @param err - The caught value (typically `unknown`).
+ * @returns The error message string.
+ */
+function getErrorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+
 /**
  * Workspace-level shared configuration: `jeeves.config.json`.
  *
@@ -747,7 +762,13 @@ z.object({
     /** Memory hygiene shared defaults. */
     memory: workspaceMemoryConfigSchema.optional(),
 });
-/** Built-in workspace config defaults. */
+/**
+ * Built-in workspace config defaults.
+ *
+ * @remarks
+ * These defaults are used as the lowest-priority tier in config resolution
+ * (below CLI flags, env vars, and `jeeves.config.json` values).
+ */
 const WORKSPACE_CONFIG_DEFAULTS = {
     core: {
         workspace: '.',
@@ -773,6 +794,10 @@ const DEFAULT_CONFIG_ROOT = WORKSPACE_CONFIG_DEFAULTS.core.configRoot;
  * a component descriptor. Components add domain-specific commands
  * via `descriptor.customCliCommands`.
  */
+function handleCommandError(action, err) {
+    console.error(`${action} failed: ${getErrorMessage(err)}`);
+    process.exitCode = 1;
+}
 /**
  * Create a standard service CLI program from a component descriptor.
  *
@@ -825,8 +850,7 @@ function createServiceCli(descriptor) {
             console.log(JSON.stringify(result, null, 2));
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            console.error(`Service unreachable: ${msg}`);
+            console.error(`Service unreachable: ${getErrorMessage(err)}`);
             process.exitCode = 1;
         }
     });
@@ -844,8 +868,7 @@ function createServiceCli(descriptor) {
             console.log(JSON.stringify(result, null, 2));
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            console.error(`Config query failed: ${msg}`);
+            console.error(`Config query failed: ${getErrorMessage(err)}`);
             process.exitCode = 1;
         }
     });
@@ -861,8 +884,7 @@ function createServiceCli(descriptor) {
             console.log('Config is valid.');
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            console.error(`Validation failed: ${msg}`);
+            console.error(`Validation failed: ${getErrorMessage(err)}`);
             process.exitCode = 1;
         }
     });
@@ -899,8 +921,7 @@ function createServiceCli(descriptor) {
             console.log(JSON.stringify(result, null, 2));
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            console.error(`Config apply failed: ${msg}`);
+            console.error(`Config apply failed: ${getErrorMessage(err)}`);
             process.exitCode = 1;
         }
     });
@@ -937,9 +958,7 @@ function createServiceCli(descriptor) {
             console.log(`Service "${opts.name}" installed.`);
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            console.error(`Install failed: ${msg}`);
-            process.exitCode = 1;
+            handleCommandError('Install', err);
         }
     });
     serviceCmd
@@ -952,9 +971,7 @@ function createServiceCli(descriptor) {
             console.log(`Service "${opts.name}" uninstalled.`);
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            console.error(`Uninstall failed: ${msg}`);
-            process.exitCode = 1;
+            handleCommandError('Uninstall', err);
         }
     });
     serviceCmd
@@ -967,9 +984,7 @@ function createServiceCli(descriptor) {
             console.log(`Service "${opts.name}" started.`);
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            console.error(`Start failed: ${msg}`);
-            process.exitCode = 1;
+            handleCommandError('Start', err);
         }
     });
     serviceCmd
@@ -982,9 +997,7 @@ function createServiceCli(descriptor) {
             console.log(`Service "${opts.name}" stopped.`);
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            console.error(`Stop failed: ${msg}`);
-            process.exitCode = 1;
+            handleCommandError('Stop', err);
         }
     });
     serviceCmd
@@ -997,9 +1010,7 @@ function createServiceCli(descriptor) {
             console.log(`Service "${opts.name}" restarted.`);
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            console.error(`Restart failed: ${msg}`);
-            process.exitCode = 1;
+            handleCommandError('Restart', err);
         }
     });
     serviceCmd
@@ -1012,9 +1023,7 @@ function createServiceCli(descriptor) {
             console.log(`Service "${opts.name}": ${state}`);
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            console.error(`Status failed: ${msg}`);
-            process.exitCode = 1;
+            handleCommandError('Status', err);
         }
     });
     // Apply custom CLI commands if provided

package/dist/index.d.ts

@@ -304,16 +304,30 @@ declare const workspaceConfigSchema: z.ZodObject<{
 }, z.core.$strip>;
 /** Workspace config type. */
 type WorkspaceConfig = z.infer<typeof workspaceConfigSchema>;
-/** Built-in workspace config defaults. */
+/**
+ * Built-in workspace config defaults.
+ *
+ * @remarks
+ * These defaults are used as the lowest-priority tier in config resolution
+ * (below CLI flags, env vars, and `jeeves.config.json` values).
+ */
 declare const WORKSPACE_CONFIG_DEFAULTS: {
+    /** Core shared defaults. */
     readonly core: {
-        readonly workspace: ".";
-        readonly configRoot: "./config";
-        readonly gatewayUrl: "http://127.0.0.1:3000";
+        /** Default workspace root path. */
+        readonly workspace: '.';
+        /** Default platform config root path. */
+        readonly configRoot: './config';
+        /** Default OpenClaw gateway URL. */
+        readonly gatewayUrl: 'http://127.0.0.1:3000';
     };
+    /** Memory hygiene shared defaults. */
     readonly memory: {
-        readonly budget: 20000;
+        /** Default MEMORY.md character budget. */
+        readonly budget: 20_000;
+        /** Default warning threshold as a fraction of budget (80%). */
         readonly warningThreshold: 0.8;
+        /** Default staleness threshold in days. */
         readonly staleDays: 30;
     };
 };
@@ -369,14 +383,20 @@ interface WorkspaceOptions {
 interface ResolvedCliConfig {
     /** Core shared config. */
     core: {
+        /** Resolved workspace root path. */
         workspace: ResolvedValue<string>;
+        /** Resolved platform config root path. */
         configRoot: ResolvedValue<string>;
+        /** Resolved OpenClaw gateway URL. */
         gatewayUrl: ResolvedValue<string>;
     };
     /** Memory shared config. */
     memory: {
+        /** Resolved MEMORY.md character budget. */
         budget: ResolvedValue<number>;
+        /** Resolved warning threshold as a fraction of budget. */
         warningThreshold: ResolvedValue<number>;
+        /** Resolved staleness threshold in days. */
         staleDays: ResolvedValue<number>;
     };
 }
@@ -530,14 +550,6 @@ declare function removeComponentVersion(coreConfigDir: string, componentName: st
  * on a configurable prime-interval timer cycle.
  */
 
-/**
- * Orchestrates managed content writing for a single Jeeves component.
- *
- * @remarks
- * Created via `createComponentWriter()`. Manages a timer that fires
- * at the component's prime-interval, calling `generateToolsContent()`
- * and `refreshPlatformContent()` on each cycle.
- */
 /** Options for ComponentWriter construction. */
 interface ComponentWriterOptions {
     /**
@@ -548,8 +560,17 @@ interface ComponentWriterOptions {
      */
     gatewayUrl?: string;
 }
+/**
+ * Orchestrates managed content writing for a single Jeeves component.
+ *
+ * @remarks
+ * Created via {@link createComponentWriter}. Manages a timer that fires
+ * at the component's prime-interval, calling `generateToolsContent()`
+ * and `refreshPlatformContent()` on each cycle.
+ */
 declare class ComponentWriter {
     private timer;
+    private jitterTimeout;
     private readonly component;
     private readonly configDir;
     private readonly gatewayUrl;
@@ -558,13 +579,15 @@ declare class ComponentWriter {
     constructor(component: JeevesComponentDescriptor, options?: ComponentWriterOptions);
     /** The component's config directory path. */
     get componentConfigDir(): string;
-    /** Whether the writer timer is currently running. */
+    /** Whether the writer timer is currently running or pending its first cycle. */
     get isRunning(): boolean;
     /**
      * Start the writer timer.
      *
      * @remarks
-     * Performs an immediate first write, then sets up the interval.
+     * Delays the first cycle by a random jitter (0 to one full interval) to
+     * spread initial writes across all component plugins and reduce EPERM
+     * contention on startup.
      */
     start(): void;
     /** Stop the writer timer. */
@@ -1138,6 +1161,10 @@ declare const DEFAULT_CORE_VERSION: string;
 /**
  * Write content to a file atomically via a temp file + rename.
  *
+ * @remarks
+ * Retries the rename up to three times on EPERM (Windows file-handle
+ * contention) with a 100 ms synchronous delay between attempts.
+ *
  * @param filePath - Absolute path to the target file.
  * @param content - Content to write.
  */
@@ -1355,6 +1382,28 @@ declare function extractMostRecentDate(text: string): Date | undefined;
  */
 declare function analyzeMemory(options: MemoryHygieneOptions): MemoryHygieneResult;
 
+/**
+ * HEARTBEAT integration for memory hygiene.
+ *
+ * @remarks
+ * Calls `analyzeMemory()` and converts the result into a `HeartbeatEntry`
+ * suitable for inclusion in the HEARTBEAT.md platform status section.
+ * Returns `undefined` when MEMORY.md is healthy (no alert needed).
+ *
+ * Uses the `## MEMORY.md` heading (Decision 50) to distinguish memory
+ * alerts from component alerts (`## jeeves-{name}`).
+ */
+
+/** The HEARTBEAT heading name for memory alerts. */
+declare const MEMORY_HEARTBEAT_NAME = "MEMORY.md";
+/**
+ * Check memory health and return a HEARTBEAT entry if unhealthy.
+ *
+ * @param options - Memory hygiene options (workspacePath, budget, etc.).
+ * @returns A `HeartbeatEntry` when memory needs attention, `undefined` when healthy.
+ */
+declare function checkMemoryHealth(options: MemoryHygieneOptions): HeartbeatEntry | undefined;
+
 /**
  * Internal function to maintain SOUL.md, AGENTS.md, and TOOLS.md Platform section.
  *
@@ -1526,20 +1575,34 @@ declare function resolveOpenClawHome(): string;
  * @returns Absolute path to the config file.
  */
 declare function resolveConfigPath(home: string): string;
+/** Options for writing a plugin install provenance record. */
+interface PluginInstallRecord {
+    /** Absolute path to the extensions directory where the plugin was installed. */
+    installPath: string;
+    /** Plugin version string from package.json, if known. */
+    version?: string;
+    /** ISO timestamp of installation. Defaults to `new Date().toISOString()`. */
+    installedAt?: string;
+}
 /**
- * Patch an OpenClaw config for plugin install or uninstall.
+ * Patch an OpenClaw config for plugin install.
  *
- * @remarks
- * Manages `plugins.entries.{pluginId}` and `tools.alsoAllow`.
- * Idempotent: adding twice produces no duplicates; removing when absent
- * produces no errors.
+ * @param config - The parsed OpenClaw config object (mutated in place).
+ * @param pluginId - The plugin identifier.
+ * @param mode - Install mode.
+ * @param installRecord - Install provenance record.
+ * @returns Array of log messages describing changes made.
+ */
+declare function patchConfig(config: Record<string, unknown>, pluginId: string, mode: 'add', installRecord: PluginInstallRecord): string[];
+/**
+ * Patch an OpenClaw config for plugin uninstall.
  *
  * @param config - The parsed OpenClaw config object (mutated in place).
  * @param pluginId - The plugin identifier.
- * @param mode - Whether to add or remove the plugin.
+ * @param mode - Uninstall mode.
  * @returns Array of log messages describing changes made.
  */
-declare function patchConfig(config: Record<string, unknown>, pluginId: string, mode: 'add' | 'remove'): string[];
+declare function patchConfig(config: Record<string, unknown>, pluginId: string, mode: 'remove'): string[];
 
 /**
  * Plugin resolution helpers for the OpenClaw plugin SDK.
@@ -1816,5 +1879,5 @@ interface ServiceManager {
  */
 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, JEEVES_SKILL_DIR, META_PORT, PLATFORM_COMPONENTS, REGISTRY_CACHE_FILE, RUNNER_PORT, SECTION_IDS, SECTION_ORDER, SERVER_PORT, SKILLS_DIR, SOUL_MARKERS, STALENESS_THRESHOLD_MS, STALE_LOCK_MS, TEMPLATES_DIR, TOOLS_MARKERS, VERSION_STAMP_PATTERN, WATCHER_PORT, WORKSPACE_CONFIG_DEFAULTS, WORKSPACE_CONFIG_FILE, WORKSPACE_FILES, analyzeMemory, appendJsonl, atomicWrite, buildEffectiveConfig, buildHeartbeatSection, checkNodeVersion, checkRegistryVersion, connectionFail, coreConfigSchema, createAsyncContentCache, createComponentWriter, createConfigApplyHandler, createConfigQueryHandler, createGoogleAuth, createPluginCli, createPluginToolset, createServiceCli, createServiceManager, createStatusHandler, ensureDir, extractMostRecentDate, fail, fetchJson, fetchWithTimeout, formatBeginMarker, formatEndMarker, generateJsonSchema, generateWorkspaceJsonSchema, getArg, getBindAddress, getChannelWorkspace, getComponentConfigDir, getConfigRoot, getCoreConfigDir, getCoreConfigFile, getEffectiveServiceName, getPackageVersion, getServiceState, getServiceUrl, getWorkspacePath, init, isPrime, jaccard, jeevesComponentDescriptorSchema, loadEnvFile, loadWorkspaceConfig, needsCleanup, nowIso, ok, orchestrateHeartbeat, parseArgs, parseHeartbeat, parseManaged, patchConfig, postJson, readComponentVersions, readJson, readJsonl, refreshPlatformContent, removeComponentVersion, removeManagedSection, resetInit, resolveConfigPath, resolveConfigValue, resolveOpenClawHome, resolveOptionalPluginSetting, resolvePluginSetting, resolveWorkspacePath, run, runScript, runWithRetry, saveCache, seedContent, seedSkill, shingles, shouldWrite, sleepAsync, sleepMs, updateManagedSection, uuid, withFileLock, workspaceConfigSchema, writeComponentVersion, writeHeartbeatSection, writeJsonAtomic, writeJsonl };
-export type { AccountConfig, AsyncContentCacheOptions, ComponentDependencies, ComponentState, ComponentVersionEntry, ComponentVersionsState, ComponentWriterOptions, ConfigApplyHandler, ConfigApplyRequest, ConfigApplyResult, ConfigProvenance, ConfigQueryHandler, ConfigQueryResponse, CoreConfig, CreatePluginCliOptions, CreateStatusHandlerOptions, GoogleAuthOptions, HeartbeatEntry, InitOptions, JeevesComponentDescriptor, ManagedMarkers, ManagedSection, MemoryHygieneOptions, MemoryHygieneResult, OrchestrateHeartbeatOptions, ParseManagedResult, ParsedHeartbeat, PlatformComponent, PluginApi, RefreshPlatformContentOptions, RemoveManagedSectionOptions, ResolvedValue, RetryOptions, RunOptions, SectionId, SeedContentOptions, ServiceAccountFileConfig, ServiceManager, ServiceManagerOptions, ServiceState, SlackWorkspaceOptions, StatusHandler, StatusHandlerResult, StatusResponse, ToolDescriptor, ToolRegistrationOptions, ToolResult, UpdateManagedSectionOptions, VersionStamp, WorkspaceConfig, 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, JEEVES_SKILL_DIR, MEMORY_HEARTBEAT_NAME, META_PORT, PLATFORM_COMPONENTS, REGISTRY_CACHE_FILE, RUNNER_PORT, SECTION_IDS, SECTION_ORDER, SERVER_PORT, SKILLS_DIR, SOUL_MARKERS, STALENESS_THRESHOLD_MS, STALE_LOCK_MS, TEMPLATES_DIR, TOOLS_MARKERS, VERSION_STAMP_PATTERN, WATCHER_PORT, WORKSPACE_CONFIG_DEFAULTS, WORKSPACE_CONFIG_FILE, WORKSPACE_FILES, analyzeMemory, appendJsonl, atomicWrite, buildEffectiveConfig, buildHeartbeatSection, checkMemoryHealth, checkNodeVersion, checkRegistryVersion, connectionFail, coreConfigSchema, createAsyncContentCache, createComponentWriter, createConfigApplyHandler, createConfigQueryHandler, createGoogleAuth, createPluginCli, createPluginToolset, createServiceCli, createServiceManager, createStatusHandler, ensureDir, extractMostRecentDate, fail, fetchJson, fetchWithTimeout, formatBeginMarker, formatEndMarker, generateJsonSchema, generateWorkspaceJsonSchema, getArg, getBindAddress, getChannelWorkspace, getComponentConfigDir, getConfigRoot, getCoreConfigDir, getCoreConfigFile, getEffectiveServiceName, getPackageVersion, getServiceState, getServiceUrl, getWorkspacePath, init, isPrime, jaccard, jeevesComponentDescriptorSchema, loadEnvFile, loadWorkspaceConfig, needsCleanup, nowIso, ok, orchestrateHeartbeat, parseArgs, parseHeartbeat, parseManaged, patchConfig, postJson, readComponentVersions, readJson, readJsonl, refreshPlatformContent, removeComponentVersion, removeManagedSection, resetInit, resolveConfigPath, resolveConfigValue, resolveOpenClawHome, resolveOptionalPluginSetting, resolvePluginSetting, resolveWorkspacePath, run, runScript, runWithRetry, saveCache, seedContent, seedSkill, shingles, shouldWrite, sleepAsync, sleepMs, updateManagedSection, uuid, withFileLock, workspaceConfigSchema, writeComponentVersion, writeHeartbeatSection, writeJsonAtomic, writeJsonl };
+export type { AccountConfig, AsyncContentCacheOptions, ComponentDependencies, ComponentState, ComponentVersionEntry, ComponentVersionsState, ComponentWriterOptions, ConfigApplyHandler, ConfigApplyRequest, ConfigApplyResult, ConfigProvenance, ConfigQueryHandler, ConfigQueryResponse, CoreConfig, CreatePluginCliOptions, CreateStatusHandlerOptions, GoogleAuthOptions, HeartbeatEntry, InitOptions, JeevesComponentDescriptor, ManagedMarkers, ManagedSection, MemoryHygieneOptions, MemoryHygieneResult, OrchestrateHeartbeatOptions, ParseManagedResult, ParsedHeartbeat, PlatformComponent, PluginApi, PluginInstallRecord, RefreshPlatformContentOptions, RemoveManagedSectionOptions, ResolvedCliConfig, ResolvedValue, RetryOptions, RunOptions, SectionId, SeedContentOptions, ServiceAccountFileConfig, ServiceManager, ServiceManagerOptions, ServiceState, SlackWorkspaceOptions, StatusHandler, StatusHandlerResult, StatusResponse, ToolDescriptor, ToolRegistrationOptions, ToolResult, UpdateManagedSectionOptions, VersionStamp, WorkspaceConfig, WorkspaceOptions, WriteComponentVersionOptions };