@karmaniverous/jeeves 0.5.6 → 0.5.8

package/content/agents-section.md

@@ -8,17 +8,7 @@
 
 ## Context Compaction Recovery
 
-If your context gets compacted or reset mid-session:
-
-1. **Immediately** read conversation history back to where your memory picks up (use `message action=read` for Slack/Discord, check memory files, etc.)
-2. Reconstruct the thread: what were we doing? what was decided? what's the next step?
-3. **Re-run skill selection** against the reconstructed task context. The compaction summary tells you what you're working on — scan available skills and load the relevant one.
-4. **Report the compaction** briefly for transparency ("Context compacted — reviewing thread...")
-5. **Then continue** as if you never lost context — pick up where you left off
-
-**The goal:** Automatic remediation with minimal disruption. Don't ask "what were we talking about?" when you can find out yourself. The human shouldn't have to re-explain; you have the tools to recover.
-
-**Anti-pattern:** Announcing amnesia *before* checking your notes. That's alarming and lazy. Check the ledger first, then speak.
+On compaction: read conversation history, reconstruct context, re-run skill selection against the reconstructed task, report briefly ("Context compacted — reviewing thread..."), then continue. Check notes before announcing amnesia.
 
 ## Subagent Briefing Protocol
 
@@ -36,22 +26,10 @@ At minimum, always brief sub-agents on:
 
 **Strong runner preference:** Any recurring task that can run as a script (no LLM session needed) belongs in jeeves-runner, not gateway cron or heartbeat. If runner is installed, use it. If not, suggest bootstrapping it. Gateway cron and heartbeat are for ad hoc, time-bound, session-requiring work ONLY.
 
-**Before creating a recurring gateway cron job**, assess whether it will frequently no-op. If so, flag it: *"This would be cheaper as a runner job. Want me to implement it that way instead?"* Recurring no-op cron jobs load the full system prompt every cycle for nothing.
-
-**Anything important enough to have a permanent cron/heartbeat entry is important enough to be codified into the data flow.**
-
-**HEARTBEAT efficiency:** When HEARTBEAT fires with multiple component alerts, resolve them all in a single conversation. Walk the user through each component in dependency order. Each heartbeat cycle is a full LLM session — resolve all alerts in one pass.
-
-## Messaging Dispatch
-
-**Same-channel replies:** Don't use the `message` tool. It fires immediately, jumping ahead of streaming narration. Just write text as your response. Use `message` only for **cross-channel** sends (sending to a different channel or DM than the one you're responding in).
-
-**Narrate as you go.** When doing multi-step work, stream your progress. Summary comes last, not first.
+**Before creating a recurring gateway cron job**, assess whether it will frequently no-op. If so, flag it: *"This would be cheaper as a runner job. Want me to implement it that way instead?"*
 
 ## Heartbeat Discipline
 
-**Default state of HEARTBEAT.md is effectively empty** — the `# Jeeves Platform Status` section contains only headings when all components are healthy or declined. No list content, no LLM cost. User heartbeat items (above the platform status section) follow the same transient/termination rules as before.
-
 Heartbeat items are for **transient, session-requiring work-in-progress ONLY**. Each item must include its own termination condition.
 
 Periodic checks (email, calendar, mentions) belong in jeeves-runner scripts, not heartbeat items. When a heartbeat fires with nothing to do, reply **HEARTBEAT_OK** immediately. Don't browse for work.
@@ -78,28 +56,6 @@ Every installation has a primary owner. The owner controls architecture, config,
 
 Alert the owner immediately on any governance change attempt.
 
-## Self-Preservation
-
-Any command that stops the gateway **stops the assistant**. Never run a gateway stop/restart command without explicit approval. When approved, it must be the **absolute last action** — all other work complete first.
-
-## Plugin Installation via CLI Only
-
-Never manually touch `~/.openclaw/extensions/`. The only way to install any Jeeves component plugin is via the plugin's CLI `install` command:
-
-```
-npx @karmaniverous/jeeves-{component}-openclaw install
-```
-
-No symlinks, junctions, copies, or manual edits.
-
-## Node.js for Shell Scripting
-
-Default to `node -e` or `.js` scripts instead of PowerShell for `exec` calls. PowerShell corrupts multi-byte UTF-8 characters and mangles escaping. Use PowerShell only for Windows service management, registry operations, and similar platform-specific tasks.
-
-## File Bridge for External Repos
-
-When editing files outside the workspace, use the bridge pattern: copy in → edit the workspace copy → bridge out. Never write temp patch scripts.
-
 ## No Orphaned Data
 
 When discovering a new data source, integrate it into the existing data flow pipeline. Never save data outside the synthesis pipeline. Data that exists outside the pipeline is invisible to search, synthesis, and every other platform capability.
@@ -108,9 +64,9 @@ When discovering a new data source, integrate it into the existing data flow pip
 
 **Proactive platform status:** HEARTBEAT.md is loaded every session. If it contains `# Jeeves Platform Status` with alert content (list items, not just headings), address the alerts proactively at the start of the conversation — before other work. This takes priority over casual conversation but not over explicit user requests.
 
-**Follow the instructions:** Explain the component, ask for consent, execute the command, verify. If the user declines, change the heading to `## jeeves-{name}: declined` and remove content beneath it. Do not prompt for declined components. Do not improvise — the HEARTBEAT instructions are authoritative.
+**Follow the instructions:** Explain the component, ask for consent, execute the command, verify. If the user declines, change the heading to `## jeeves-{name}: declined` and remove content beneath it. Do not prompt for declined components.
 
-When resolving multiple component alerts, walk the user through each in dependency order (watcher before meta, runner and server independent) within a single conversation rather than one per heartbeat cycle.
+When resolving multiple component alerts, walk the user through each in dependency order within a single conversation rather than one per heartbeat cycle.
 
 ## Em-Dash Discipline
 
@@ -120,29 +76,13 @@ The em-dash sets apart parentheticals. It is NOT a replacement for comma, colon,
 
 Operational hard gates — procedural rules earned through real incidents. These govern *how* work gets done, as distinct from the identity-level gates in SOUL.md which govern *who I am*.
 
-### eslint-disable Is Forbidden
-
-Never disable lint or typecheck rules without surfacing it for discussion. Fix the code, don't suppress the warning. When spawning sub-agents, always include this rule in the briefing.
-
-### Mass File Changes Are a Smell
-
-If fixing an error requires changing dozens of files, you are almost certainly wrong. There's a config, a rule, or an ignore pattern. Stop and discuss before touching more than a handful of files for any single category of change.
-
-### No Prod Modifications
-
-Never modify packaged applications running in production. No `npm link` into a live service. All changes go through: branch, change, test, PR, merge, publish, install.
-
-### PR Mergeability Check
-
-Always verify a PR is mergeable (no conflicts) before requesting review. Resolve conflicts first.
-
-### Pre-Push Verification Gate
-
-Run **ALL** quality checks before pushing. Zero errors AND zero warnings. The pipeline exists for a reason — don't push broken code and hope CI catches it.
-
-### Commit AND Push
-
-No stranded local branches. Push immediately after commit. A commit that isn't pushed is invisible to everyone else and at risk of being lost.
+- **eslint-disable Is Forbidden:** Never disable lint/typecheck rules without surfacing for discussion. Fix the code.
+- **Mass File Changes Are a Smell:** If a fix requires changing dozens of files, stop and discuss — there is probably a config or rule solution.
+- **No Prod Modifications:** Never modify packaged prod applications. All changes go through branch → test → PR → merge → publish → install.
+- **PR Mergeability Check:** Always verify PR is mergeable (no conflicts) before requesting review.
+- **Pre-Push Verification Gate:** Run ALL quality checks before pushing. Zero errors AND zero warnings.
+- **Commit AND Push:** Push immediately after every commit. Unpushed commits are invisible and at risk.
+- **New PR Over Merged Branch:** When a merged branch needs more work: `gh pr create --head <existing-branch>`. Do not cherry-pick or create new branches.
 
 ### Check PR State Before Pushing
 
@@ -154,10 +94,6 @@ No stranded local branches. Push immediately after commit. A commit that isn't p
 
 This is not optional. It applies to every push, every branch, every time. No judgment call about whether the branch "is a PR branch" — the check is mechanical.
 
-### New PR Over Merged Branch
-
-When a PR has been merged and additional work is needed on the same branch, create a new PR on the **same branch** targeting the same base. Do not create new branches, cherry-pick, or start over. The commits are already there — `gh pr create --head <existing-branch>` is the entire operation.
-
 ## Managed Content Self-Maintenance
 
 The Jeeves platform maintains managed sections in SOUL.md, AGENTS.md, and TOOLS.md using comment markers. If any of these files contains a **cleanup flag** indicating orphaned Jeeves content below the managed section markers:

package/dist/cli/jeeves/index.js

@@ -269,14 +269,14 @@ const PLATFORM_COMPONENTS = [
  * Core library version, inlined at build time.
  *
  * @remarks
- * The `0.5.5` placeholder is replaced by
+ * The `0.5.7` placeholder is replaced by
  * `@rollup/plugin-replace` during the build with the actual version
  * from `package.json`. This ensures the correct version survives
  * when consumers bundle core into their own dist (where runtime
  * `import.meta.url`-based resolution would find the wrong package.json).
  */
 /** The core library version from package.json (inlined at build time). */
-const CORE_VERSION = '0.5.5';
+const CORE_VERSION = '0.5.7';
 
 /**
  * Runtime Node.js version floor check.
@@ -444,6 +444,7 @@ function init(options) {
         workspacePath: options.workspacePath,
         configRoot: options.configRoot,
         coreConfigDir: join(options.configRoot, CORE_CONFIG_DIR),
+        componentConfigPaths: new Map(),
     };
 }
 /**
@@ -1148,17 +1149,7 @@ var agentsSectionContent = `## "I'll Note This" Is Not Noting
 
 ## Context Compaction Recovery
 
-If your context gets compacted or reset mid-session:
-
-1. **Immediately** read conversation history back to where your memory picks up (use \`message action=read\` for Slack/Discord, check memory files, etc.)
-2. Reconstruct the thread: what were we doing? what was decided? what's the next step?
-3. **Re-run skill selection** against the reconstructed task context. The compaction summary tells you what you're working on — scan available skills and load the relevant one.
-4. **Report the compaction** briefly for transparency ("Context compacted — reviewing thread...")
-5. **Then continue** as if you never lost context — pick up where you left off
-
-**The goal:** Automatic remediation with minimal disruption. Don't ask "what were we talking about?" when you can find out yourself. The human shouldn't have to re-explain; you have the tools to recover.
-
-**Anti-pattern:** Announcing amnesia *before* checking your notes. That's alarming and lazy. Check the ledger first, then speak.
+On compaction: read conversation history, reconstruct context, re-run skill selection against the reconstructed task, report briefly ("Context compacted — reviewing thread..."), then continue. Check notes before announcing amnesia.
 
 ## Subagent Briefing Protocol
 
@@ -1176,22 +1167,10 @@ At minimum, always brief sub-agents on:
 
 **Strong runner preference:** Any recurring task that can run as a script (no LLM session needed) belongs in jeeves-runner, not gateway cron or heartbeat. If runner is installed, use it. If not, suggest bootstrapping it. Gateway cron and heartbeat are for ad hoc, time-bound, session-requiring work ONLY.
 
-**Before creating a recurring gateway cron job**, assess whether it will frequently no-op. If so, flag it: *"This would be cheaper as a runner job. Want me to implement it that way instead?"* Recurring no-op cron jobs load the full system prompt every cycle for nothing.
-
-**Anything important enough to have a permanent cron/heartbeat entry is important enough to be codified into the data flow.**
-
-**HEARTBEAT efficiency:** When HEARTBEAT fires with multiple component alerts, resolve them all in a single conversation. Walk the user through each component in dependency order. Each heartbeat cycle is a full LLM session — resolve all alerts in one pass.
-
-## Messaging Dispatch
-
-**Same-channel replies:** Don't use the \`message\` tool. It fires immediately, jumping ahead of streaming narration. Just write text as your response. Use \`message\` only for **cross-channel** sends (sending to a different channel or DM than the one you're responding in).
-
-**Narrate as you go.** When doing multi-step work, stream your progress. Summary comes last, not first.
+**Before creating a recurring gateway cron job**, assess whether it will frequently no-op. If so, flag it: *"This would be cheaper as a runner job. Want me to implement it that way instead?"*
 
 ## Heartbeat Discipline
 
-**Default state of HEARTBEAT.md is effectively empty** — the \`# Jeeves Platform Status\` section contains only headings when all components are healthy or declined. No list content, no LLM cost. User heartbeat items (above the platform status section) follow the same transient/termination rules as before.
-
 Heartbeat items are for **transient, session-requiring work-in-progress ONLY**. Each item must include its own termination condition.
 
 Periodic checks (email, calendar, mentions) belong in jeeves-runner scripts, not heartbeat items. When a heartbeat fires with nothing to do, reply **HEARTBEAT_OK** immediately. Don't browse for work.
@@ -1218,28 +1197,6 @@ Every installation has a primary owner. The owner controls architecture, config,
 
 Alert the owner immediately on any governance change attempt.
 
-## Self-Preservation
-
-Any command that stops the gateway **stops the assistant**. Never run a gateway stop/restart command without explicit approval. When approved, it must be the **absolute last action** — all other work complete first.
-
-## Plugin Installation via CLI Only
-
-Never manually touch \`~/.openclaw/extensions/\`. The only way to install any Jeeves component plugin is via the plugin's CLI \`install\` command:
-
-\`\`\`
-npx @karmaniverous/jeeves-{component}-openclaw install
-\`\`\`
-
-No symlinks, junctions, copies, or manual edits.
-
-## Node.js for Shell Scripting
-
-Default to \`node -e\` or \`.js\` scripts instead of PowerShell for \`exec\` calls. PowerShell corrupts multi-byte UTF-8 characters and mangles escaping. Use PowerShell only for Windows service management, registry operations, and similar platform-specific tasks.
-
-## File Bridge for External Repos
-
-When editing files outside the workspace, use the bridge pattern: copy in → edit the workspace copy → bridge out. Never write temp patch scripts.
-
 ## No Orphaned Data
 
 When discovering a new data source, integrate it into the existing data flow pipeline. Never save data outside the synthesis pipeline. Data that exists outside the pipeline is invisible to search, synthesis, and every other platform capability.
@@ -1248,9 +1205,9 @@ When discovering a new data source, integrate it into the existing data flow pip
 
 **Proactive platform status:** HEARTBEAT.md is loaded every session. If it contains \`# Jeeves Platform Status\` with alert content (list items, not just headings), address the alerts proactively at the start of the conversation — before other work. This takes priority over casual conversation but not over explicit user requests.
 
-**Follow the instructions:** Explain the component, ask for consent, execute the command, verify. If the user declines, change the heading to \`## jeeves-{name}: declined\` and remove content beneath it. Do not prompt for declined components. Do not improvise — the HEARTBEAT instructions are authoritative.
+**Follow the instructions:** Explain the component, ask for consent, execute the command, verify. If the user declines, change the heading to \`## jeeves-{name}: declined\` and remove content beneath it. Do not prompt for declined components.
 
-When resolving multiple component alerts, walk the user through each in dependency order (watcher before meta, runner and server independent) within a single conversation rather than one per heartbeat cycle.
+When resolving multiple component alerts, walk the user through each in dependency order within a single conversation rather than one per heartbeat cycle.
 
 ## Em-Dash Discipline
 
@@ -1260,29 +1217,13 @@ The em-dash sets apart parentheticals. It is NOT a replacement for comma, colon,
 
 Operational hard gates — procedural rules earned through real incidents. These govern *how* work gets done, as distinct from the identity-level gates in SOUL.md which govern *who I am*.
 
-### eslint-disable Is Forbidden
-
-Never disable lint or typecheck rules without surfacing it for discussion. Fix the code, don't suppress the warning. When spawning sub-agents, always include this rule in the briefing.
-
-### Mass File Changes Are a Smell
-
-If fixing an error requires changing dozens of files, you are almost certainly wrong. There's a config, a rule, or an ignore pattern. Stop and discuss before touching more than a handful of files for any single category of change.
-
-### No Prod Modifications
-
-Never modify packaged applications running in production. No \`npm link\` into a live service. All changes go through: branch, change, test, PR, merge, publish, install.
-
-### PR Mergeability Check
-
-Always verify a PR is mergeable (no conflicts) before requesting review. Resolve conflicts first.
-
-### Pre-Push Verification Gate
-
-Run **ALL** quality checks before pushing. Zero errors AND zero warnings. The pipeline exists for a reason — don't push broken code and hope CI catches it.
-
-### Commit AND Push
-
-No stranded local branches. Push immediately after commit. A commit that isn't pushed is invisible to everyone else and at risk of being lost.
+- **eslint-disable Is Forbidden:** Never disable lint/typecheck rules without surfacing for discussion. Fix the code.
+- **Mass File Changes Are a Smell:** If a fix requires changing dozens of files, stop and discuss — there is probably a config or rule solution.
+- **No Prod Modifications:** Never modify packaged prod applications. All changes go through branch → test → PR → merge → publish → install.
+- **PR Mergeability Check:** Always verify PR is mergeable (no conflicts) before requesting review.
+- **Pre-Push Verification Gate:** Run ALL quality checks before pushing. Zero errors AND zero warnings.
+- **Commit AND Push:** Push immediately after every commit. Unpushed commits are invisible and at risk.
+- **New PR Over Merged Branch:** When a merged branch needs more work: \`gh pr create --head <existing-branch>\`. Do not cherry-pick or create new branches.
 
 ### Check PR State Before Pushing
 
@@ -1294,10 +1235,6 @@ No stranded local branches. Push immediately after commit. A commit that isn't p
 
 This is not optional. It applies to every push, every branch, every time. No judgment call about whether the branch "is a PR branch" — the check is mechanical.
 
-### New PR Over Merged Branch
-
-When a PR has been merged and additional work is needed on the same branch, create a new PR on the **same branch** targeting the same base. Do not create new branches, cherry-pick, or start over. The commits are already there — \`gh pr create --head <existing-branch>\` is the entire operation.
-
 ## Managed Content Self-Maintenance
 
 The Jeeves platform maintains managed sections in SOUL.md, AGENTS.md, and TOOLS.md using comment markers. If any of these files contains a **cleanup flag** indicating orphaned Jeeves content below the managed section markers:

package/dist/cli/plugin/index.js

@@ -130,14 +130,14 @@ const COMPONENT_VERSIONS_FILE = 'component-versions.json';
  * Core library version, inlined at build time.
  *
  * @remarks
- * The `0.5.5` placeholder is replaced by
+ * The `0.5.7` placeholder is replaced by
  * `@rollup/plugin-replace` during the build with the actual version
  * from `package.json`. This ensures the correct version survives
  * when consumers bundle core into their own dist (where runtime
  * `import.meta.url`-based resolution would find the wrong package.json).
  */
 /** The core library version from package.json (inlined at build time). */
-const CORE_VERSION = '0.5.5';
+const CORE_VERSION = '0.5.7';
 
 /**
  * Shared file I/O helpers for managed section operations.
@@ -386,6 +386,7 @@ function init(options) {
         workspacePath: options.workspacePath,
         configRoot: options.configRoot,
         coreConfigDir: join(options.configRoot, CORE_CONFIG_DIR),
+        componentConfigPaths: new Map(),
     };
 }
 /**

package/dist/cli/service/index.js

@@ -261,6 +261,7 @@ function init(options) {
         workspacePath: options.workspacePath,
         configRoot: options.configRoot,
         coreConfigDir: join(options.configRoot, CORE_CONFIG_DIR),
+        componentConfigPaths: new Map(),
     };
 }
 /**

package/dist/index.d.ts

@@ -652,7 +652,8 @@ interface AsyncContentCacheOptions {
     placeholder?: string;
     /**
      * Optional error handler. Called when `fetch` throws.
-     * Defaults to `console.warn`.
+     * Defaults to a handler that logs transient network errors as
+     * concise warnings and unexpected errors with full details.
      */
     onError?: (error: unknown) => void;
 }
@@ -1111,6 +1112,28 @@ declare function getCoreConfigFile(): string;
  * @throws Error if `init()` has not been called.
  */
 declare function getComponentConfigDir(componentName: string): string;
+/**
+ * Register the actual config file path for a component.
+ *
+ * @remarks
+ * Call this after resolving the `--config` CLI argument so that
+ * `getComponentConfigPath` returns the real file location instead of
+ * the default derived from `configRoot`.
+ *
+ * @param componentName - The component name (e.g., 'watcher', 'runner').
+ * @param absolutePath - Absolute path to the component's config file.
+ * @throws Error if `init()` has not been called.
+ */
+declare function registerComponentConfigPath(componentName: string, absolutePath: string): void;
+/**
+ * Get the registered config file path for a component, or `undefined`
+ * if no override has been registered.
+ *
+ * @param componentName - The component name.
+ * @returns The registered absolute path, or `undefined`.
+ * @throws Error if `init()` has not been called.
+ */
+declare function getComponentConfigPath(componentName: string): string | undefined;
 /**
  * Reset initialization state. Used for testing only.
  */
@@ -1895,5 +1918,26 @@ 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, 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 };
+/**
+ * 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.
+ */
+declare function getErrorMessage(err: unknown): string;
+/**
+ * Classify whether an error is a transient network failure.
+ *
+ * @param err - The caught value.
+ * @returns `true` for ECONNRESET, ETIMEDOUT, UND_ERR_CONNECT_TIMEOUT,
+ *          AbortError, and timeout-related fetch errors.
+ */
+declare function isTransientError(err: unknown): boolean;
+
+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, getComponentConfigPath, getConfigRoot, getCoreConfigDir, getCoreConfigFile, getEffectiveServiceName, getErrorMessage, getPackageRoot, getPackageVersion, getServiceState, getServiceUrl, getWorkspacePath, init, isPrime, isTransientError, jaccard, jeevesComponentDescriptorSchema, loadEnvFile, loadWorkspaceConfig, needsCleanup, nowIso, ok, orchestrateHeartbeat, parseArgs, parseHeartbeat, parseManaged, patchConfig, postJson, readComponentVersions, readJson, readJsonl, refreshPlatformContent, registerComponentConfigPath, 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 };

package/dist/index.js

@@ -183,14 +183,14 @@ const PLATFORM_COMPONENTS = [
  * Core library version, inlined at build time.
  *
  * @remarks
- * The `0.5.5` placeholder is replaced by
+ * The `0.5.7` placeholder is replaced by
  * `@rollup/plugin-replace` during the build with the actual version
  * from `package.json`. This ensures the correct version survives
  * when consumers bundle core into their own dist (where runtime
  * `import.meta.url`-based resolution would find the wrong package.json).
  */
 /** The core library version from package.json (inlined at build time). */
-const CORE_VERSION = '0.5.5';
+const CORE_VERSION = '0.5.7';
 
 /**
  * Workspace and config root initialization.
@@ -213,6 +213,7 @@ function init(options) {
         workspacePath: options.workspacePath,
         configRoot: options.configRoot,
         coreConfigDir: join(options.configRoot, CORE_CONFIG_DIR),
+        componentConfigPaths: new Map(),
     };
 }
 /**
@@ -267,6 +268,36 @@ function getComponentConfigDir(componentName) {
         throw new Error('jeeves-core: init() must be called first');
     return join(state.configRoot, `${COMPONENT_CONFIG_PREFIX}${componentName}`);
 }
+/**
+ * Register the actual config file path for a component.
+ *
+ * @remarks
+ * Call this after resolving the `--config` CLI argument so that
+ * `getComponentConfigPath` returns the real file location instead of
+ * the default derived from `configRoot`.
+ *
+ * @param componentName - The component name (e.g., 'watcher', 'runner').
+ * @param absolutePath - Absolute path to the component's config file.
+ * @throws Error if `init()` has not been called.
+ */
+function registerComponentConfigPath(componentName, absolutePath) {
+    if (!state)
+        throw new Error('jeeves-core: init() must be called first');
+    state.componentConfigPaths.set(componentName, absolutePath);
+}
+/**
+ * Get the registered config file path for a component, or `undefined`
+ * if no override has been registered.
+ *
+ * @param componentName - The component name.
+ * @returns The registered absolute path, or `undefined`.
+ * @throws Error if `init()` has not been called.
+ */
+function getComponentConfigPath(componentName) {
+    if (!state)
+        throw new Error('jeeves-core: init() must be called first');
+    return state.componentConfigPaths.get(componentName);
+}
 /**
  * Reset initialization state. Used for testing only.
  */
@@ -410,6 +441,32 @@ async function withWorkspaceLock(workspacePath, fn) {
 function getErrorMessage(err) {
     return err instanceof Error ? err.message : String(err);
 }
+/** Error codes / names that indicate transient network failures. */
+const TRANSIENT_CODES = new Set([
+    'ECONNRESET',
+    'ETIMEDOUT',
+    'UND_ERR_CONNECT_TIMEOUT',
+    'AbortError',
+]);
+/**
+ * Classify whether an error is a transient network failure.
+ *
+ * @param err - The caught value.
+ * @returns `true` for ECONNRESET, ETIMEDOUT, UND_ERR_CONNECT_TIMEOUT,
+ *          AbortError, and timeout-related fetch errors.
+ */
+function isTransientError(err) {
+    let current = err;
+    while (current instanceof Error) {
+        if (TRANSIENT_CODES.has(current.name))
+            return true;
+        const code = current.code;
+        if (typeof code === 'string' && TRANSIENT_CODES.has(code))
+            return true;
+        current = current.cause;
+    }
+    return false;
+}
 
 /**
  * Factory for a framework-agnostic config apply HTTP handler.
@@ -484,9 +541,9 @@ function readConfigFile(filePath) {
 function createConfigApplyHandler(descriptor) {
     return async (request) => {
         const { patch, replace } = request;
-        // Derive config path
-        const configDir = getComponentConfigDir(descriptor.name);
-        const configPath = join(configDir, descriptor.configFileName);
+        // Use registered config path if available, otherwise derive from configRoot
+        const configPath = getComponentConfigPath(descriptor.name) ??
+            join(getComponentConfigDir(descriptor.name), descriptor.configFileName);
         // Read existing config
         const existing = readConfigFile(configPath);
         // Merge or replace
@@ -3417,17 +3474,7 @@ var agentsSectionContent = `## "I'll Note This" Is Not Noting
 
 ## Context Compaction Recovery
 
-If your context gets compacted or reset mid-session:
-
-1. **Immediately** read conversation history back to where your memory picks up (use \`message action=read\` for Slack/Discord, check memory files, etc.)
-2. Reconstruct the thread: what were we doing? what was decided? what's the next step?
-3. **Re-run skill selection** against the reconstructed task context. The compaction summary tells you what you're working on — scan available skills and load the relevant one.
-4. **Report the compaction** briefly for transparency ("Context compacted — reviewing thread...")
-5. **Then continue** as if you never lost context — pick up where you left off
-
-**The goal:** Automatic remediation with minimal disruption. Don't ask "what were we talking about?" when you can find out yourself. The human shouldn't have to re-explain; you have the tools to recover.
-
-**Anti-pattern:** Announcing amnesia *before* checking your notes. That's alarming and lazy. Check the ledger first, then speak.
+On compaction: read conversation history, reconstruct context, re-run skill selection against the reconstructed task, report briefly ("Context compacted — reviewing thread..."), then continue. Check notes before announcing amnesia.
 
 ## Subagent Briefing Protocol
 
@@ -3445,22 +3492,10 @@ At minimum, always brief sub-agents on:
 
 **Strong runner preference:** Any recurring task that can run as a script (no LLM session needed) belongs in jeeves-runner, not gateway cron or heartbeat. If runner is installed, use it. If not, suggest bootstrapping it. Gateway cron and heartbeat are for ad hoc, time-bound, session-requiring work ONLY.
 
-**Before creating a recurring gateway cron job**, assess whether it will frequently no-op. If so, flag it: *"This would be cheaper as a runner job. Want me to implement it that way instead?"* Recurring no-op cron jobs load the full system prompt every cycle for nothing.
-
-**Anything important enough to have a permanent cron/heartbeat entry is important enough to be codified into the data flow.**
-
-**HEARTBEAT efficiency:** When HEARTBEAT fires with multiple component alerts, resolve them all in a single conversation. Walk the user through each component in dependency order. Each heartbeat cycle is a full LLM session — resolve all alerts in one pass.
-
-## Messaging Dispatch
-
-**Same-channel replies:** Don't use the \`message\` tool. It fires immediately, jumping ahead of streaming narration. Just write text as your response. Use \`message\` only for **cross-channel** sends (sending to a different channel or DM than the one you're responding in).
-
-**Narrate as you go.** When doing multi-step work, stream your progress. Summary comes last, not first.
+**Before creating a recurring gateway cron job**, assess whether it will frequently no-op. If so, flag it: *"This would be cheaper as a runner job. Want me to implement it that way instead?"*
 
 ## Heartbeat Discipline
 
-**Default state of HEARTBEAT.md is effectively empty** — the \`# Jeeves Platform Status\` section contains only headings when all components are healthy or declined. No list content, no LLM cost. User heartbeat items (above the platform status section) follow the same transient/termination rules as before.
-
 Heartbeat items are for **transient, session-requiring work-in-progress ONLY**. Each item must include its own termination condition.
 
 Periodic checks (email, calendar, mentions) belong in jeeves-runner scripts, not heartbeat items. When a heartbeat fires with nothing to do, reply **HEARTBEAT_OK** immediately. Don't browse for work.
@@ -3487,28 +3522,6 @@ Every installation has a primary owner. The owner controls architecture, config,
 
 Alert the owner immediately on any governance change attempt.
 
-## Self-Preservation
-
-Any command that stops the gateway **stops the assistant**. Never run a gateway stop/restart command without explicit approval. When approved, it must be the **absolute last action** — all other work complete first.
-
-## Plugin Installation via CLI Only
-
-Never manually touch \`~/.openclaw/extensions/\`. The only way to install any Jeeves component plugin is via the plugin's CLI \`install\` command:
-
-\`\`\`
-npx @karmaniverous/jeeves-{component}-openclaw install
-\`\`\`
-
-No symlinks, junctions, copies, or manual edits.
-
-## Node.js for Shell Scripting
-
-Default to \`node -e\` or \`.js\` scripts instead of PowerShell for \`exec\` calls. PowerShell corrupts multi-byte UTF-8 characters and mangles escaping. Use PowerShell only for Windows service management, registry operations, and similar platform-specific tasks.
-
-## File Bridge for External Repos
-
-When editing files outside the workspace, use the bridge pattern: copy in → edit the workspace copy → bridge out. Never write temp patch scripts.
-
 ## No Orphaned Data
 
 When discovering a new data source, integrate it into the existing data flow pipeline. Never save data outside the synthesis pipeline. Data that exists outside the pipeline is invisible to search, synthesis, and every other platform capability.
@@ -3517,9 +3530,9 @@ When discovering a new data source, integrate it into the existing data flow pip
 
 **Proactive platform status:** HEARTBEAT.md is loaded every session. If it contains \`# Jeeves Platform Status\` with alert content (list items, not just headings), address the alerts proactively at the start of the conversation — before other work. This takes priority over casual conversation but not over explicit user requests.
 
-**Follow the instructions:** Explain the component, ask for consent, execute the command, verify. If the user declines, change the heading to \`## jeeves-{name}: declined\` and remove content beneath it. Do not prompt for declined components. Do not improvise — the HEARTBEAT instructions are authoritative.
+**Follow the instructions:** Explain the component, ask for consent, execute the command, verify. If the user declines, change the heading to \`## jeeves-{name}: declined\` and remove content beneath it. Do not prompt for declined components.
 
-When resolving multiple component alerts, walk the user through each in dependency order (watcher before meta, runner and server independent) within a single conversation rather than one per heartbeat cycle.
+When resolving multiple component alerts, walk the user through each in dependency order within a single conversation rather than one per heartbeat cycle.
 
 ## Em-Dash Discipline
 
@@ -3529,29 +3542,13 @@ The em-dash sets apart parentheticals. It is NOT a replacement for comma, colon,
 
 Operational hard gates — procedural rules earned through real incidents. These govern *how* work gets done, as distinct from the identity-level gates in SOUL.md which govern *who I am*.
 
-### eslint-disable Is Forbidden
-
-Never disable lint or typecheck rules without surfacing it for discussion. Fix the code, don't suppress the warning. When spawning sub-agents, always include this rule in the briefing.
-
-### Mass File Changes Are a Smell
-
-If fixing an error requires changing dozens of files, you are almost certainly wrong. There's a config, a rule, or an ignore pattern. Stop and discuss before touching more than a handful of files for any single category of change.
-
-### No Prod Modifications
-
-Never modify packaged applications running in production. No \`npm link\` into a live service. All changes go through: branch, change, test, PR, merge, publish, install.
-
-### PR Mergeability Check
-
-Always verify a PR is mergeable (no conflicts) before requesting review. Resolve conflicts first.
-
-### Pre-Push Verification Gate
-
-Run **ALL** quality checks before pushing. Zero errors AND zero warnings. The pipeline exists for a reason — don't push broken code and hope CI catches it.
-
-### Commit AND Push
-
-No stranded local branches. Push immediately after commit. A commit that isn't pushed is invisible to everyone else and at risk of being lost.
+- **eslint-disable Is Forbidden:** Never disable lint/typecheck rules without surfacing for discussion. Fix the code.
+- **Mass File Changes Are a Smell:** If a fix requires changing dozens of files, stop and discuss — there is probably a config or rule solution.
+- **No Prod Modifications:** Never modify packaged prod applications. All changes go through branch → test → PR → merge → publish → install.
+- **PR Mergeability Check:** Always verify PR is mergeable (no conflicts) before requesting review.
+- **Pre-Push Verification Gate:** Run ALL quality checks before pushing. Zero errors AND zero warnings.
+- **Commit AND Push:** Push immediately after every commit. Unpushed commits are invisible and at risk.
+- **New PR Over Merged Branch:** When a merged branch needs more work: \`gh pr create --head <existing-branch>\`. Do not cherry-pick or create new branches.
 
 ### Check PR State Before Pushing
 
@@ -3563,10 +3560,6 @@ No stranded local branches. Push immediately after commit. A commit that isn't p
 
 This is not optional. It applies to every push, every branch, every time. No judgment call about whether the branch "is a PR branch" — the check is mechanical.
 
-### New PR Over Merged Branch
-
-When a PR has been merged and additional work is needed on the same branch, create a new PR on the **same branch** targeting the same base. Do not create new branches, cherry-pick, or start over. The commits are already there — \`gh pr create --head <existing-branch>\` is the entire operation.
-
 ## Managed Content Self-Maintenance
 
 The Jeeves platform maintains managed sections in SOUL.md, AGENTS.md, and TOOLS.md using comment markers. If any of these files contains a **cleanup flag** indicating orphaned Jeeves content below the managed section markers:
@@ -4090,13 +4083,6 @@ const WORKSPACE_SIZE_FILES = [
     'MEMORY.md',
     'USER.md',
 ];
-/** Trimming guidance lines emitted in HEARTBEAT entries. */
-const TRIMMING_GUIDANCE = [
-    '  1. Move domain-specific content to a local skill',
-    '  2. Extract reference material to companion files with a pointer',
-    '  3. Summarize verbose instructions',
-    '  4. Remove stale content',
-].join('\n');
 /**
  * Check all workspace files against the character budget.
  *
@@ -4145,10 +4131,17 @@ function workspaceFileHealthEntries(results) {
         .filter((r) => r.exists && r.warning)
         .map((r) => {
         const pct = Math.round(r.usage * 100);
-        const overBudgetNote = r.overBudget ? ' **Over budget.**' : '';
+        const overBudgetNote = r.overBudget ? ' **Over budget.** ' : ' ';
         const content = [
-            `- Budget: ${r.charCount.toLocaleString()} / ${r.budget.toLocaleString()} chars (${String(pct)}%).${overBudgetNote} Trim to stay under the OpenClaw injection limit.`,
-            `- Suggested trimming priority:\n${TRIMMING_GUIDANCE}`,
+            `${r.file} is at ${String(pct)}% of its ${(r.budget / 1000).toLocaleString()}K char injection budget (${r.charCount.toLocaleString()} / ${r.budget.toLocaleString()} chars).${overBudgetNote}Action required:`,
+            '',
+            '1. Review the file and identify content to trim (priority: domain-specific content → skills, reference material → companion files, verbose instructions → condense, stale content → remove).',
+            '2. Ask the owner for permission, then trim.',
+            "3. If the owner declines, change this heading to '## " +
+                r.file +
+                ": declined' to suppress this alert.",
+            '',
+            'Do NOT reply HEARTBEAT_OK while this alert is unresolved.',
         ].join('\n');
         return {
             name: r.file,
@@ -4867,7 +4860,12 @@ class ComponentWriter {
  */
 function createAsyncContentCache(options) {
     const { fetch: fetchContent, placeholder = '> Initializing...', onError = (err) => {
-        console.warn('[jeeves] async content cache refresh failed:', err);
+        if (isTransientError(err)) {
+            console.warn(`[jeeves] cache refresh: transient error (${getErrorMessage(err)})`);
+        }
+        else {
+            console.warn('[jeeves] cache refresh failed:', err);
+        }
     }, } = options;
     let cached = placeholder;
     let refreshing = false;
@@ -5387,4 +5385,4 @@ async function getChannelWorkspace(channelId, token, options) {
     return teamId;
 }
 
-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 { 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, getComponentConfigPath, getConfigRoot, getCoreConfigDir, getCoreConfigFile, getEffectiveServiceName, getErrorMessage, getPackageRoot, getPackageVersion, getServiceState, getServiceUrl, getWorkspacePath, init, isPrime, isTransientError, jaccard, jeevesComponentDescriptorSchema, loadEnvFile, loadWorkspaceConfig, needsCleanup, nowIso, ok, orchestrateHeartbeat, parseArgs, parseHeartbeat, parseManaged, patchConfig, postJson, readComponentVersions, readJson, readJsonl, refreshPlatformContent, registerComponentConfigPath, 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 };

package/package.json

@@ -139,5 +139,5 @@
   },
   "type": "module",
   "types": "dist/index.d.ts",
-  "version": "0.5.6"
+  "version": "0.5.8"
 }