@karmaniverous/jeeves 0.5.1 → 0.5.4

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>;
     };
 }
@@ -407,8 +427,8 @@ declare function buildEffectiveConfig(opts: WorkspaceOptions): ResolvedCliConfig
 interface CreatePluginCliOptions {
     /** Plugin identifier (e.g., 'jeeves-watcher-openclaw'). */
     pluginId: string;
-    /** Absolute path to the dist directory to copy. */
-    distDir: string;
+    /** `import.meta.url` for the calling plugin CLI module. */
+    importMetaUrl: string;
     /** npm package name for the plugin. */
     pluginPackage: string;
     /** Component name (e.g., 'watcher'). Derived from pluginId if omitted. */
@@ -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.
  */
@@ -1470,6 +1497,19 @@ declare function seedSkill(workspacePath: string): void;
  */
 declare function createPluginToolset(descriptor: JeevesComponentDescriptor): ToolDescriptor[];
 
+/**
+ * Resolve the package root directory from a module's `import.meta.url`.
+ *
+ * @module
+ */
+/**
+ * Get the nearest package root directory relative to the calling module URL.
+ *
+ * @param importMetaUrl - The `import.meta.url` of the calling module.
+ * @returns The absolute package root path, or `undefined` on any error.
+ */
+declare function getPackageRoot(importMetaUrl: string): string | undefined;
+
 /**
  * Resolve the version of a package from its `import.meta.url`.
  *
@@ -1548,20 +1588,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.
@@ -1838,5 +1892,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, 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, 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, getPackageRoot, 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 };