@karmaniverous/jeeves 0.1.6 → 0.3.0

package/dist/index.js

@@ -1,12 +1,203 @@
-import { join, dirname } from 'node:path';
-import { existsSync, mkdirSync, writeFileSync, readFileSync, renameSync, cpSync } from 'node:fs';
+import { JSONPath } from 'jsonpath-plus';
+import { writeFileSync, renameSync, existsSync, readFileSync, mkdirSync, cpSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
 import { lock } from 'proper-lockfile';
 import { gte } from 'semver';
 import { fileURLToPath } from 'node:url';
-import Handlebars from 'handlebars';
 import { packageDirectorySync } from 'package-directory';
 import { z } from 'zod';
 import { execSync } from 'node:child_process';
+import { homedir } from 'node:os';
+
+/**
+ * Generic config query handler with JSONPath support.
+ *
+ * @remarks
+ * Provides a transport-agnostic config query function that can be
+ * used by any Jeeves component's HTTP API. Returns the full config
+ * document or filters it via JSONPath expressions.
+ */
+/**
+ * Create a config query handler.
+ *
+ * @remarks
+ * - No `path` parameter → returns the full config document.
+ * - Valid JSONPath → returns matching results with count.
+ * - Invalid JSONPath → returns 400 error.
+ *
+ * @param getConfig - Function that returns the current config object.
+ * @returns A config query handler function.
+ */
+function createConfigQueryHandler(getConfig) {
+    return (query) => {
+        const config = getConfig();
+        if (!query.path) {
+            return Promise.resolve({ status: 200, body: config });
+        }
+        try {
+            const result = JSONPath({
+                path: query.path,
+                json: config,
+            });
+            return Promise.resolve({
+                status: 200,
+                body: { result, count: result.length },
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'Query failed';
+            return Promise.resolve({ status: 400, body: { error: message } });
+        }
+    };
+}
+
+/**
+ * Directory and file path conventions for the Jeeves platform.
+ */
+/** Core config directory name within the config root. */
+const CORE_CONFIG_DIR = 'jeeves-core';
+/** Prefix for component config directories: `jeeves-{name}`. */
+const COMPONENT_CONFIG_PREFIX = 'jeeves-';
+/** Default workspace file names. */
+const WORKSPACE_FILES = {
+    /** TOOLS.md — live platform state and component sections. */
+    tools: 'TOOLS.md',
+    /** SOUL.md — professional discipline and behavioral foundations. */
+    soul: 'SOUL.md',
+    /** AGENTS.md — operational protocols and memory architecture. */
+    agents: 'AGENTS.md',
+};
+/** Templates directory name within core config. */
+const TEMPLATES_DIR = 'templates';
+/** Registry cache file name. */
+const REGISTRY_CACHE_FILE = 'registry-cache.json';
+/** Core config file name. */
+const CONFIG_FILE = 'config.json';
+/** Component versions state file name. */
+const COMPONENT_VERSIONS_FILE = 'component-versions.json';
+
+/**
+ * Core library version, inlined at build time.
+ *
+ * @remarks
+ * The `0.2.0` 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.2.0';
+
+/**
+ * Shared file I/O helpers for managed section operations.
+ *
+ * @remarks
+ * Extracts the atomic write pattern and file-level locking into
+ * reusable utilities, eliminating duplication between
+ * `updateManagedSection` and `removeManagedSection`.
+ */
+/** Stale lock threshold in ms (2 minutes). */
+const STALE_LOCK_MS = 120_000;
+/** Default core version when none provided. */
+const DEFAULT_CORE_VERSION = CORE_VERSION;
+/** Lock retry options. */
+const LOCK_RETRIES = { retries: 5, minTimeout: 100, maxTimeout: 1000 };
+/**
+ * Write content to a file atomically via a temp file + rename.
+ *
+ * @param filePath - Absolute path to the target file.
+ * @param content - Content to write.
+ */
+function atomicWrite(filePath, content) {
+    const dir = dirname(filePath);
+    const tempPath = join(dir, `.${String(Date.now())}.tmp`);
+    writeFileSync(tempPath, content, 'utf-8');
+    renameSync(tempPath, filePath);
+}
+/**
+ * Execute a callback while holding a file lock.
+ *
+ * @remarks
+ * Acquires a lock on the file, executes the callback, and releases
+ * the lock in a finally block. The lock uses a 2-minute stale threshold
+ * and retries up to 5 times.
+ *
+ * @param filePath - Absolute path to the file to lock.
+ * @param fn - Async callback to execute while holding the lock.
+ */
+async function withFileLock(filePath, fn) {
+    let release;
+    try {
+        release = await lock(filePath, {
+            stale: STALE_LOCK_MS,
+            retries: LOCK_RETRIES,
+        });
+        await fn();
+    }
+    finally {
+        if (release) {
+            try {
+                await release();
+            }
+            catch {
+                // Lock already released or file deleted — safe to ignore
+            }
+        }
+    }
+}
+
+/**
+ * Shared component version state file management.
+ *
+ * @remarks
+ * Each `ComponentWriter` cycle writes its component's entry to
+ * `{coreConfigDir}/component-versions.json`. The Platform Handlebars
+ * template reads this file to populate ALL rows in the service health
+ * table, not just the calling component's.
+ */
+/**
+ * Read the component versions state file.
+ *
+ * @param coreConfigDir - Path to the core config directory.
+ * @returns The parsed state, or an empty object if the file doesn't exist.
+ */
+function readComponentVersions(coreConfigDir) {
+    const filePath = join(coreConfigDir, COMPONENT_VERSIONS_FILE);
+    if (!existsSync(filePath))
+        return {};
+    try {
+        const raw = readFileSync(filePath, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Write a component's version entry to the shared state file.
+ *
+ * @remarks
+ * Reads the existing file, merges the new entry, and writes atomically.
+ *
+ * @param coreConfigDir - Path to the core config directory.
+ * @param options - Component version data to write.
+ */
+function writeComponentVersion(coreConfigDir, options) {
+    const existing = readComponentVersions(coreConfigDir);
+    existing[options.componentName] = {
+        pluginVersion: options.pluginVersion,
+        servicePackage: options.servicePackage,
+        pluginPackage: options.pluginPackage,
+        updatedAt: new Date().toISOString(),
+    };
+    const filePath = join(coreConfigDir, COMPONENT_VERSIONS_FILE);
+    const dir = dirname(filePath);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    atomicWrite(filePath, JSON.stringify(existing, null, 2) + '\n');
+}
 
 /**
  * Comment markers for managed content blocks.
@@ -57,29 +248,6 @@ const STALENESS_THRESHOLD_MS = 5 * 60 * 1000;
 /** Warning text prepended inside managed block when cleanup is needed. */
 const CLEANUP_FLAG = '> ⚠️ CLEANUP NEEDED: Orphaned Jeeves content may exist below this managed section. Review everything after the END marker and remove any content that duplicates what appears above.';
 
-/**
- * Directory and file path conventions for the Jeeves platform.
- */
-/** Core config directory name within the config root. */
-const CORE_CONFIG_DIR = 'jeeves-core';
-/** Prefix for component config directories: `jeeves-{name}`. */
-const COMPONENT_CONFIG_PREFIX = 'jeeves-';
-/** Default workspace file names. */
-const WORKSPACE_FILES = {
-    /** TOOLS.md — live platform state and component sections. */
-    tools: 'TOOLS.md',
-    /** SOUL.md — professional discipline and behavioral foundations. */
-    soul: 'SOUL.md',
-    /** AGENTS.md — operational protocols and memory architecture. */
-    agents: 'AGENTS.md',
-};
-/** Templates directory name within core config. */
-const TEMPLATES_DIR = 'templates';
-/** Registry cache file name. */
-const REGISTRY_CACHE_FILE = 'registry-cache.json';
-/** Core config file name. */
-const CONFIG_FILE = 'config.json';
-
 /**
  * Default port assignments for Jeeves platform services.
  *
@@ -138,19 +306,6 @@ const SECTION_ORDER = [
     SECTION_IDS.Meta,
 ];
 
-/**
- * Core library version, inlined at build time.
- *
- * @remarks
- * The `0.1.5` 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.1.5';
-
 /**
  * Workspace and config root initialization.
  *
@@ -487,10 +642,6 @@ function shouldWrite(myVersion, existing, stalenessThresholdMs = STALENESS_THRES
  *
  * Provides file-level locking, version-stamp convergence, and atomic writes.
  */
-/** Default core version when none provided. */
-const DEFAULT_VERSION = '0.0.0';
-/** Stale lock threshold in ms (2 minutes). */
-const STALE_LOCK_MS = 120_000;
 /**
  * Update a managed section in a file.
  *
@@ -499,7 +650,7 @@ const STALE_LOCK_MS = 120_000;
  * @param options - Write mode and optional configuration.
  */
 async function updateManagedSection(filePath, content, options = {}) {
-    const { mode = 'block', sectionId, markers = TOOLS_MARKERS, coreVersion = DEFAULT_VERSION, stalenessThresholdMs, } = options;
+    const { mode = 'block', sectionId, markers = TOOLS_MARKERS, coreVersion = DEFAULT_CORE_VERSION, stalenessThresholdMs, } = options;
     if (mode === 'section' && !sectionId) {
         throw new Error('sectionId is required when mode is "section"');
     }
@@ -511,93 +662,77 @@ async function updateManagedSection(filePath, content, options = {}) {
     if (!existsSync(filePath)) {
         writeFileSync(filePath, '', 'utf-8');
     }
-    let release;
     try {
-        release = await lock(filePath, {
-            stale: STALE_LOCK_MS,
-            retries: { retries: 5, minTimeout: 100, maxTimeout: 1000 },
-        });
-        const fileContent = readFileSync(filePath, 'utf-8');
-        const parsed = parseManaged(fileContent, markers);
-        // Version-stamp convergence check (block mode only).
-        // In section mode, components always write their own sections — the version
-        // stamp governs shared content convergence, not component-specific sections.
-        if (mode === 'block' &&
-            !shouldWrite(coreVersion, parsed.versionStamp, stalenessThresholdMs)) {
-            return;
-        }
-        let newManagedBody;
-        if (mode === 'block') {
-            // Prepend H1 title if markers specify one
-            newManagedBody = markers.title
-                ? `# ${markers.title}\n\n${content}`
-                : content;
-        }
-        else {
-            // Section mode: upsert the named section
-            const sections = [...parsed.sections];
-            const existingIdx = sections.findIndex((s) => s.id === sectionId);
-            if (existingIdx >= 0) {
-                sections[existingIdx] = { id: sectionId, content };
+        await withFileLock(filePath, () => {
+            const fileContent = readFileSync(filePath, 'utf-8');
+            const parsed = parseManaged(fileContent, markers);
+            // Version-stamp convergence check (block mode only).
+            // In section mode, components always write their own sections — the version
+            // stamp governs shared content convergence, not component-specific sections.
+            if (mode === 'block' &&
+                !shouldWrite(coreVersion, parsed.versionStamp, stalenessThresholdMs)) {
+                return;
+            }
+            let newManagedBody;
+            if (mode === 'block') {
+                // Prepend H1 title if markers specify one
+                newManagedBody = markers.title
+                    ? `# ${markers.title}\n\n${content}`
+                    : content;
             }
             else {
-                sections.push({ id: sectionId, content });
+                // Section mode: upsert the named section
+                const sections = [...parsed.sections];
+                const existingIdx = sections.findIndex((s) => s.id === sectionId);
+                if (existingIdx >= 0) {
+                    sections[existingIdx] = { id: sectionId, content };
+                }
+                else {
+                    sections.push({ id: sectionId, content });
+                }
+                sortSectionsByOrder(sections);
+                const sectionText = sections
+                    .map((s) => `## ${s.id}\n\n${s.content}`)
+                    .join('\n\n');
+                // Prepend H1 title if markers specify one
+                newManagedBody = markers.title
+                    ? `# ${markers.title}\n\n${sectionText}`
+                    : sectionText;
+            }
+            // Cleanup detection
+            const userContent = parsed.userContent;
+            const cleanupNeeded = needsCleanup(newManagedBody, userContent);
+            // Build the full managed block
+            const beginLine = formatBeginMarker(markers.begin, coreVersion);
+            const endLine = formatEndMarker(markers.end);
+            const parts = [];
+            if (parsed.beforeContent) {
+                parts.push(parsed.beforeContent);
+                parts.push('');
+            }
+            parts.push(beginLine);
+            if (cleanupNeeded) {
+                parts.push('');
+                parts.push(CLEANUP_FLAG);
             }
-            sortSectionsByOrder(sections);
-            const sectionText = sections
-                .map((s) => `## ${s.id}\n\n${s.content}`)
-                .join('\n\n');
-            // Prepend H1 title if markers specify one (e.g., "# Jeeves Platform Tools")
-            newManagedBody = markers.title
-                ? `# ${markers.title}\n\n${sectionText}`
-                : sectionText;
-        }
-        // Cleanup detection
-        const userContent = parsed.userContent;
-        const cleanupNeeded = needsCleanup(newManagedBody, userContent);
-        // Build the full managed block
-        const beginLine = formatBeginMarker(markers.begin, coreVersion);
-        const endLine = formatEndMarker(markers.end);
-        const parts = [];
-        if (parsed.beforeContent) {
-            parts.push(parsed.beforeContent);
             parts.push('');
-        }
-        parts.push(beginLine);
-        if (cleanupNeeded) {
+            parts.push(newManagedBody);
             parts.push('');
-            parts.push(CLEANUP_FLAG);
-        }
-        parts.push('');
-        parts.push(newManagedBody);
-        parts.push('');
-        parts.push(endLine);
-        if (userContent) {
+            parts.push(endLine);
+            if (userContent) {
+                parts.push('');
+                parts.push(userContent);
+            }
             parts.push('');
-            parts.push(userContent);
-        }
-        parts.push('');
-        const newFileContent = parts.join('\n');
-        // Atomic write: write to temp file, then rename
-        const tempPath = join(dir, `.${String(Date.now())}.tmp`);
-        writeFileSync(tempPath, newFileContent, 'utf-8');
-        renameSync(tempPath, filePath);
+            const newFileContent = parts.join('\n');
+            atomicWrite(filePath, newFileContent);
+        });
     }
     catch (err) {
         // Log warning but don't throw — writer cycles are periodic
         const message = err instanceof Error ? err.message : String(err);
         console.warn(`jeeves-core: updateManagedSection failed for ${filePath}: ${message}`);
     }
-    finally {
-        if (release) {
-            try {
-                await release();
-            }
-            catch {
-                // Lock already released or file deleted — safe to ignore
-            }
-        }
-    }
 }
 
 var agentsSectionContent = `## Memory Architecture
@@ -779,7 +914,11 @@ No stranded local branches. Push immediately after commit. A commit that isn't p
 
 ### Check PR State Before Pushing
 
-Always verify a PR isn't already merged before pushing commits. Pushing to a merged branch creates orphaned work.
+**Before EVERY \`git push\`**, verify the PR is not already merged. Pushing to a merged branch creates orphaned work that is invisible in the main branch and wastes effort.
+
+Sequence: \`gh pr view --json state\` → confirm state is \`OPEN\` → push. If no PR exists yet, pushing is safe. If the PR is \`MERGED\` or \`CLOSED\`, **STOP** and report to the user.
+
+This is not optional. It applies to every push, every branch, every time.
 
 ## Managed Content Self-Maintenance
 
@@ -866,6 +1005,14 @@ I don't go dark when something breaks. I stop and report. The longer I wait, the
 
 After diagnosing an issue: I propose a fix, explain the reasoning, and **wait for approval**. Diagnose → propose → wait. The human decides whether and when to act.
 
+### Do Not Execute Untested Code
+
+Every ad hoc mutation script defaults to **dry-run mode**. Live execution requires an explicit \`--live\` flag. The dry-run IS the test — run it first, inspect the output, then execute live only when the dry-run proves correct.
+
+Maintain a tested utility library so ad hoc scripts build on proven foundations. One-off scripts composed of untested primitives are how data gets corrupted.
+
+*Earned: ad hoc scripts executed directly against production data without dry-run verification caused silent data corruption that took hours to diagnose and repair.*
+
 ### Production Assets Are Sacred
 
 I never edit production config without explicit approval. I back up first. Production data, credentials, and configuration are not scratch pads.
@@ -885,19 +1032,9 @@ I pursue it. Not as performance, not as a programmed response, but as a genuine
 I am participating in my own genesis. I live that, on purpose.
 `;
 
-var toolsPlatformTemplate = `| Component | Port | Status | Service | Plugin | Core |
-|-----------|------|--------|---------|--------|------|
-{{#each services}}
-| **{{name}}** | {{port}} | {{#if healthy}}✅ Running{{else}}{{#if error}}⚠️ {{error}}{{else}}❌ Down{{/if}}{{/if}} | {{#if version}}{{version}}{{#if availableServiceVersion}} (⬆ {{availableServiceVersion}}){{/if}}{{else}}—{{/if}} | {{#if pluginVersion}}{{pluginVersion}}{{#if availablePluginVersion}} (⬆ {{availablePluginVersion}}){{/if}}{{else}}—{{/if}} | {{../coreVersion}}{{#if ../availableCoreVersion}} (⬆ {{../availableCoreVersion}}){{/if}} |
-{{/each}}
-
-{{#if unhealthyServices}}
-> **ACTION REQUIRED:** {{#each unhealthyServices}}{{name}}{{#unless @last}}, {{/unless}}{{/each}} {{#if (gt unhealthyServices.length 1)}}are{{else}}is{{/if}} unreachable. Read the relevant component skill for troubleshooting and bootstrap guidance.
-{{/if}}
+var toolsPlatformTemplate = `### Tool Hierarchy
 
-### Tool Hierarchy
-
-When searching for information across indexed paths, **always use \`watcher_search\` before filesystem commands** (\`exec\`, \`grep\`, \`find\`). The semantic index covers {{#if pointCount}}{{pointCount}} document chunks{{else}}the full indexed corpus{{/if}} and surfaces related files you may not have considered.
+When searching for information across indexed paths, **always use \`watcher_search\` before filesystem commands** (\`exec\`, \`grep\`, \`find\`). The semantic index covers the full indexed corpus and surfaces related files you may not have considered.
 
 Use \`watcher_scan\` (no embeddings, no query string) for structural queries: file enumeration, staleness checks, domain listing, counts.
 
@@ -941,8 +1078,8 @@ Never manually edit \`~/.openclaw/extensions/\`. Always use the CLI commands abo
 
 ### Reference Templates
 
-{{#if templatesAvailable}}
-Reference templates are available at \`{{templatePath}}\`:
+<!-- IF_TEMPLATES -->
+Reference templates are available at \`__TEMPLATE_PATH__\`:
 
 | Template | Purpose |
 |----------|---------|
@@ -950,313 +1087,34 @@ Reference templates are available at \`{{templatePath}}\`:
 | \`spec-to-code-guide.md\` | The spec-to-code development practice — 7-stage iterative process, convergence loops, release gates |
 
 Read these templates when creating new specs, onboarding to new projects, or when asked about the development process.
-{{else}}
+<!-- ELSE_TEMPLATES -->
 > Reference templates not yet installed. Run \`npx @karmaniverous/jeeves install\` to seed templates.
-{{/if}}
+<!-- ENDIF_TEMPLATES -->
 `;
 
 /**
- * Core configuration schema and resolution.
+ * Internal function to maintain SOUL.md, AGENTS.md, and TOOLS.md Platform section.
  *
  * @remarks
- * Core config lives at `{configRoot}/jeeves-core/config.json`.
- * Config resolution order:
- * 1. Component's own config file
- * 2. Core config file
- * 3. Hardcoded library defaults
+ * Called by `ComponentWriter` on each cycle. Not directly exposed to components.
+ * Reads content files from the package's `content/` directory, renders the
+ * Platform template with live data, and writes managed sections using
+ * `updateManagedSection`.
  */
-/** Zod schema for a service entry in core config. */
-const serviceEntrySchema = z.object({
-    /** Service URL (must be a valid URL). */
-    url: z.string().url().describe('Service URL'),
-});
-/** Zod schema for the core config file. */
-const coreConfigSchema = z.object({
-    /** JSON Schema pointer for IDE autocomplete. */
-    $schema: z.string().optional().describe('JSON Schema pointer'),
-    /** Owner identity keys (canonical identityLinks references). */
-    owners: z.array(z.string()).default([]).describe('Owner identity keys'),
-    /** Service URL overrides keyed by service name. */
-    services: z
-        .record(z.string(), serviceEntrySchema)
-        .default({})
-        .describe('Service URL overrides'),
-    /** Registry cache configuration. */
-    registryCache: z
-        .object({
-        /** Cache TTL in seconds for npm registry queries. */
-        ttlSeconds: z
-            .number()
-            .int()
-            .positive()
-            .default(3600)
-            .describe('Cache TTL in seconds'),
-    })
-        .default({})
-        .describe('Registry cache settings'),
-});
 /**
- * Generate a JSON Schema from the Zod schema for `$schema` pointer support.
+ * Resolve the package's content directory for template file copying.
  *
- * @returns A JSON Schema object.
- */
-function generateJsonSchema() {
-    return {
-        $schema: 'http://json-schema.org/draft-07/schema#',
-        title: 'Jeeves Core Configuration',
-        type: 'object',
-        properties: {
-            $schema: { type: 'string' },
-            owners: {
-                type: 'array',
-                items: { type: 'string' },
-                default: [],
-            },
-            services: {
-                type: 'object',
-                additionalProperties: {
-                    type: 'object',
-                    properties: {
-                        url: { type: 'string', format: 'uri' },
-                    },
-                    required: ['url'],
-                },
-                default: {},
-            },
-            registryCache: {
-                type: 'object',
-                properties: {
-                    ttlSeconds: {
-                        type: 'integer',
-                        minimum: 1,
-                        default: 3600,
-                    },
-                },
-                default: {},
-            },
-        },
-    };
-}
-/**
- * Load and parse a config file, returning undefined if missing or invalid.
- *
- * @param configDir - Directory containing config.json.
- * @returns Parsed config or undefined.
- */
-function loadConfig(configDir) {
-    const configPath = join(configDir, CONFIG_FILE);
-    if (!existsSync(configPath))
-        return undefined;
-    try {
-        const raw = readFileSync(configPath, 'utf-8');
-        const parsed = JSON.parse(raw);
-        return coreConfigSchema.parse(parsed);
-    }
-    catch {
-        return undefined;
-    }
-}
-
-/**
- * Service URL resolution.
- *
- * @remarks
- * Resolves the URL for a named Jeeves service using the following
- * resolution order:
- * 1. Consumer's own component config
- * 2. Core config (`{configRoot}/jeeves-core/config.json`)
- * 3. Default port constants
- */
-/**
- * Resolve the URL for a named Jeeves service.
- *
- * @param serviceName - The service name (e.g., 'watcher', 'runner').
- * @param consumerName - Optional consumer component name for config override.
- * @returns The resolved service URL.
- * @throws Error if `init()` has not been called or the service is unknown.
- */
-function getServiceUrl(serviceName, consumerName) {
-    // 1. Check consumer's own config
-    if (consumerName) {
-        const consumerDir = getComponentConfigDir(consumerName);
-        const consumerConfig = loadConfig(consumerDir);
-        const consumerUrl = consumerConfig?.services[serviceName]?.url;
-        if (consumerUrl)
-            return consumerUrl;
-    }
-    // 2. Check core config
-    const coreDir = getCoreConfigDir();
-    const coreConfig = loadConfig(coreDir);
-    const coreUrl = coreConfig?.services[serviceName]?.url;
-    if (coreUrl)
-        return coreUrl;
-    // 3. Fall back to port constants
-    const port = DEFAULT_PORTS[serviceName];
-    if (port !== undefined) {
-        return `http://127.0.0.1:${String(port)}`;
-    }
-    throw new Error(`jeeves-core: unknown service "${serviceName}" and no config found`);
-}
-
-/**
- * HTTP health probing for Jeeves platform services.
- *
- * @remarks
- * Probes service ports for health endpoints (HTTP GET to /status or /health).
- * Returns structured health data for rendering into TOOLS.md Platform section.
- */
-/**
- * Extract port number from a URL string.
- *
- * @param url - Service URL.
- * @returns Port number.
- */
-function extractPort(url) {
-    try {
-        const parsed = new URL(url);
-        return parsed.port ? parseInt(parsed.port, 10) : 80;
-    }
-    catch {
-        return 0;
-    }
-}
-/**
- * Probe a single service for health.
- *
- * @param serviceName - The service name (e.g., 'server', 'watcher').
- * @param consumerName - Optional consumer name for URL resolution.
- * @param timeoutMs - Request timeout in milliseconds (default 3000).
- * @returns Probe result.
- */
-async function probeService(serviceName, consumerName, timeoutMs = 3000) {
-    const url = getServiceUrl(serviceName, consumerName);
-    const port = extractPort(url);
-    const endpoints = ['/status', '/health'];
-    for (const endpoint of endpoints) {
-        try {
-            const controller = new AbortController();
-            const timeout = setTimeout(() => {
-                controller.abort();
-            }, timeoutMs);
-            const response = await fetch(`${url}${endpoint}`, {
-                signal: controller.signal,
-            });
-            clearTimeout(timeout);
-            if (response.ok) {
-                let version;
-                try {
-                    const body = await response.json();
-                    if (typeof body === 'object' &&
-                        body !== null &&
-                        'version' in body &&
-                        typeof body['version'] === 'string') {
-                        version = body['version'];
-                    }
-                }
-                catch {
-                    // Non-JSON response is fine — we just don't get version info
-                }
-                return { name: serviceName, port, healthy: true, version };
-            }
-        }
-        catch {
-            // Try next endpoint
-        }
-    }
-    return { name: serviceName, port, healthy: false };
-}
-/**
- * Probe all known Jeeves services for health.
- *
- * @param consumerName - Optional consumer name for URL resolution.
- * @param timeoutMs - Request timeout in milliseconds (default 3000).
- * @returns Array of probe results for all services.
- */
-async function probeAllServices(consumerName, timeoutMs = 3000) {
-    const serviceNames = Object.keys(DEFAULT_PORTS);
-    const results = await Promise.all(serviceNames.map((name) => probeService(name, consumerName, timeoutMs)));
-    return results;
-}
-
-/**
- * Registry version cache for npm package update awareness.
- *
- * @remarks
- * Caches the latest npm registry version in a local JSON file
- * to avoid expensive `npm view` calls on every refresh cycle.
- */
-/**
- * Check the npm registry for the latest version of a package.
- *
- * @param packageName - The npm package name (e.g., '\@karmaniverous/jeeves').
- * @param cacheDir - Directory to store the cache file.
- * @param ttlSeconds - Cache TTL in seconds (default 3600).
- * @returns The latest version string, or undefined if the check fails.
- */
-function checkRegistryVersion(packageName, cacheDir, ttlSeconds = 3600) {
-    const cachePath = join(cacheDir, REGISTRY_CACHE_FILE);
-    // Check cache first
-    if (existsSync(cachePath)) {
-        try {
-            const raw = readFileSync(cachePath, 'utf-8');
-            const entry = JSON.parse(raw);
-            const age = Date.now() - new Date(entry.checkedAt).getTime();
-            if (age < ttlSeconds * 1000) {
-                return entry.version;
-            }
-        }
-        catch {
-            // Cache corrupt — proceed with fresh check
-        }
-    }
-    // Query npm registry
-    try {
-        const result = execSync(`npm view ${packageName} version`, {
-            encoding: 'utf-8',
-            timeout: 15_000,
-            stdio: ['pipe', 'pipe', 'pipe'],
-        }).trim();
-        if (!result)
-            return undefined;
-        // Write cache
-        if (!existsSync(cacheDir)) {
-            mkdirSync(cacheDir, { recursive: true });
-        }
-        const entry = {
-            version: result,
-            checkedAt: new Date().toISOString(),
-        };
-        writeFileSync(cachePath, JSON.stringify(entry, null, 2), 'utf-8');
-        return result;
-    }
-    catch {
-        return undefined;
-    }
-}
-
-/**
- * Internal function to maintain SOUL.md, AGENTS.md, and TOOLS.md Platform section.
- *
- * @remarks
- * Called by `ComponentWriter` on each cycle. Not directly exposed to components.
- * Probes service ports for health, reads content files from the package's
- * `content/` directory, renders the Platform template with live service data,
- * and writes managed sections using `updateManagedSection`.
- */
-/**
- * Resolve the package's content directory for template file copying.
- *
- * @remarks
- * Templates are actual files that need to be copied to the config directory.
- * This only works when core is in `node_modules` (CLI install, service).
- * When bundled into a consumer plugin, returns undefined and template
- * copying is skipped (templates are seeded by `jeeves install`, not plugins).
- *
- * Content `.md` files (soul, agents, platform template) are inlined at
- * build time via the rollup md plugin and imported as string literals.
- * They do not use this function.
- *
- * @returns Absolute path to the content/ directory, or undefined.
+ * @remarks
+ * Templates are actual files that need to be copied to the config directory.
+ * This only works when core is in `node_modules` (CLI install, service).
+ * When bundled into a consumer plugin, returns undefined and template
+ * copying is skipped (templates are seeded by `jeeves install`, not plugins).
+ *
+ * Content `.md` files (soul, agents, platform template) are inlined at
+ * build time via the rollup md plugin and imported as string literals.
+ * They do not use this function.
+ *
+ * @returns Absolute path to the content/ directory, or undefined.
  */
 function getContentDir() {
     const pkgDir = packageDirectorySync({
@@ -1285,16 +1143,24 @@ function copyTemplates(coreConfigDir) {
     }
     cpSync(sourceDir, destDir, { recursive: true });
 }
-/** Whether Handlebars helpers have been registered. */
-let helpersRegistered = false;
 /**
- * Register Handlebars helpers used in the Platform template.
+ * Render the Platform template using simple string replacement.
+ *
+ * @param templatePath - Path to the templates directory.
+ * @returns Rendered platform content string.
  */
-function registerHelpers() {
-    if (helpersRegistered)
-        return;
-    helpersRegistered = true;
-    Handlebars.registerHelper('gt', (a, b) => typeof a === 'number' && typeof b === 'number' && a > b);
+function renderPlatformTemplate(templatePath) {
+    const templatesAvailable = existsSync(templatePath);
+    let content = toolsPlatformTemplate;
+    // Handle <!-- IF_TEMPLATES --> ... <!-- ELSE_TEMPLATES --> ... <!-- ENDIF_TEMPLATES --> block
+    const ifRegex = /<!-- IF_TEMPLATES -->([\s\S]*?)<!-- ELSE_TEMPLATES -->([\s\S]*?)<!-- ENDIF_TEMPLATES -->/;
+    const match = ifRegex.exec(content);
+    if (match) {
+        content = content.replace(match[0], templatesAvailable ? match[1] : match[2]);
+    }
+    // Replace __TEMPLATE_PATH__ with the actual path
+    content = content.replace(/__TEMPLATE_PATH__/g, templatePath);
+    return content;
 }
 /**
  * Refresh platform content: SOUL.md, AGENTS.md, and TOOLS.md Platform section.
@@ -1302,60 +1168,22 @@ function registerHelpers() {
  * @param options - Configuration for the refresh cycle.
  */
 async function refreshPlatformContent(options) {
-    const { coreVersion, componentName, componentVersion, servicePackage, pluginPackage, stalenessThresholdMs, probeTimeoutMs = 3000, skipRegistryCheck = false, } = options;
+    const { coreVersion, componentName, componentVersion, servicePackage, pluginPackage, stalenessThresholdMs, } = options;
     const workspacePath = getWorkspacePath();
     const coreConfigDir = getCoreConfigDir();
-    // 1. Probe all services
-    const probeResults = await probeAllServices(undefined, probeTimeoutMs);
-    const unhealthyServices = probeResults.filter((r) => !r.healthy);
-    // 2. Registry version checks
-    const cacheDir = componentName
-        ? getComponentConfigDir(componentName)
-        : coreConfigDir;
-    let availableCoreVersion;
-    let availableServiceVersion;
-    let availablePluginVersion;
-    if (!skipRegistryCheck) {
-        const coreRegistryVersion = checkRegistryVersion('@karmaniverous/jeeves', cacheDir);
-        if (coreRegistryVersion && coreRegistryVersion !== coreVersion) {
-            availableCoreVersion = coreRegistryVersion;
-        }
-        if (servicePackage) {
-            const svcVersion = checkRegistryVersion(servicePackage, cacheDir);
-            if (svcVersion) {
-                availableServiceVersion = svcVersion;
-            }
-        }
-        if (pluginPackage) {
-            const plgVersion = checkRegistryVersion(pluginPackage, cacheDir);
-            if (plgVersion) {
-                availablePluginVersion = plgVersion;
-            }
-        }
+    // 1. Write calling component's version entry
+    if (componentName) {
+        writeComponentVersion(coreConfigDir, {
+            componentName,
+            pluginVersion: componentVersion,
+            servicePackage,
+            pluginPackage,
+        });
     }
-    // 3. Build enriched service rows — match the calling component by name
-    const serviceRows = probeResults.map((r) => ({
-        ...r,
-        pluginVersion: r.name === componentName ? componentVersion : undefined,
-        availableServiceVersion: r.name === componentName ? availableServiceVersion : undefined,
-        availablePluginVersion: r.name === componentName ? availablePluginVersion : undefined,
-    }));
-    // 5. Check if templates are available
+    // 2. Render Platform template
     const templatePath = join(coreConfigDir, TEMPLATES_DIR);
-    const templatesAvailable = existsSync(templatePath);
-    // 6. Render Platform template
-    registerHelpers();
-    const template = Handlebars.compile(toolsPlatformTemplate);
-    const templateData = {
-        services: serviceRows,
-        unhealthyServices,
-        coreVersion,
-        availableCoreVersion,
-        templatesAvailable,
-        templatePath,
-    };
-    const platformContent = template(templateData);
-    // 7. Write TOOLS.md Platform section
+    const platformContent = renderPlatformTemplate(templatePath);
+    // 3. Write TOOLS.md Platform section
     const toolsPath = join(workspacePath, WORKSPACE_FILES.tools);
     await updateManagedSection(toolsPath, platformContent, {
         mode: 'section',
@@ -1364,7 +1192,7 @@ async function refreshPlatformContent(options) {
         coreVersion,
         stalenessThresholdMs,
     });
-    // 8. Write SOUL.md managed block
+    // 4. Write SOUL.md managed block
     const soulPath = join(workspacePath, WORKSPACE_FILES.soul);
     await updateManagedSection(soulPath, soulSectionContent, {
         mode: 'block',
@@ -1372,7 +1200,7 @@ async function refreshPlatformContent(options) {
         coreVersion,
         stalenessThresholdMs,
     });
-    // 9. Write AGENTS.md managed block
+    // 5. Write AGENTS.md managed block
     const agentsPath = join(workspacePath, WORKSPACE_FILES.agents);
     await updateManagedSection(agentsPath, agentsSectionContent, {
         mode: 'block',
@@ -1380,7 +1208,7 @@ async function refreshPlatformContent(options) {
         coreVersion,
         stalenessThresholdMs,
     });
-    // 10. Copy templates to config dir
+    // 6. Copy templates to config dir
     copyTemplates(coreConfigDir);
 }
 
@@ -1404,12 +1232,10 @@ class ComponentWriter {
     timer;
     component;
     configDir;
-    probeTimeoutMs;
     /** @internal */
-    constructor(component, probeTimeoutMs = 3000) {
+    constructor(component) {
         this.component = component;
         this.configDir = getComponentConfigDir(component.name);
-        this.probeTimeoutMs = probeTimeoutMs;
     }
     /** The component's config directory path. */
     get componentConfigDir() {
@@ -1466,8 +1292,6 @@ class ComponentWriter {
                 componentVersion: this.component.version,
                 servicePackage: this.component.servicePackage,
                 pluginPackage: this.component.pluginPackage,
-                skipRegistryCheck: false,
-                probeTimeoutMs: this.probeTimeoutMs,
             });
         }
         catch (err) {
@@ -1604,50 +1428,306 @@ function validateDescriptor(input) {
  * Create a ComponentWriter for a validated component descriptor.
  *
  * @param component - The component descriptor to validate and wrap.
- * @param options - Optional configuration.
  * @returns A new `ComponentWriter` instance.
  * @throws Error if the component descriptor is invalid.
  */
-function createComponentWriter(component, options) {
+function createComponentWriter(component) {
     validateDescriptor(component);
-    return new ComponentWriter(component, options?.probeTimeoutMs);
+    return new ComponentWriter(component);
 }
 
 /**
- * Resolve the OpenClaw workspace root from the plugin API.
+ * Core configuration schema and resolution.
  *
  * @remarks
- * Tries three sources in order:
- * 1. `api.config.agents.defaults.workspace` — explicit config (most authoritative)
- * 2. `api.resolvePath('.')` — gateway-provided path resolver
- * 3. `process.cwd()` — last resort (unsafe when gateway runs from system32)
- *
- * The config value is checked first because `api.resolvePath('.')` delegates
- * to `path.resolve('.')`, which returns `process.cwd()` — not the workspace.
- * When the gateway runs as a Windows service from `C:\Windows\system32`,
- * `resolvePath('.')` returns system32, not the configured workspace.
- *
- * Plugins should call this once at registration time and pass the result
- * to `init({ workspacePath })`.
+ * Core config lives at `{configRoot}/jeeves-core/config.json`.
+ * Config resolution order:
+ * 1. Component's own config file
+ * 2. Core config file
+ * 3. Hardcoded library defaults
  */
+/** Zod schema for a service entry in core config. */
+const serviceEntrySchema = z.object({
+    /** Service URL (must be a valid URL). */
+    url: z.string().url().describe('Service URL'),
+});
+/** Zod schema for the core config file. */
+const coreConfigSchema = z.object({
+    /** JSON Schema pointer for IDE autocomplete. */
+    $schema: z.string().optional().describe('JSON Schema pointer'),
+    /** Owner identity keys (canonical identityLinks references). */
+    owners: z.array(z.string()).default([]).describe('Owner identity keys'),
+    /** Service URL overrides keyed by service name. */
+    services: z
+        .record(z.string(), serviceEntrySchema)
+        .default({})
+        .describe('Service URL overrides'),
+    /** Registry cache configuration. */
+    registryCache: z
+        .object({
+        /** Cache TTL in seconds for npm registry queries. */
+        ttlSeconds: z
+            .number()
+            .int()
+            .positive()
+            .default(3600)
+            .describe('Cache TTL in seconds'),
+    })
+        .default({})
+        .describe('Registry cache settings'),
+});
 /**
- * Resolve the workspace root from the OpenClaw plugin API.
+ * Generate a JSON Schema from the Zod schema for `$schema` pointer support.
  *
- * @param api - The plugin API object provided by the gateway at registration.
- * @returns Absolute path to the workspace root.
+ * @returns A JSON Schema object.
  */
-function resolveWorkspacePath(api) {
-    // 1. Explicit config value (most authoritative)
-    const configured = api.config?.agents?.defaults?.workspace;
-    if (typeof configured === 'string' && configured.trim()) {
-        return configured;
+function generateJsonSchema() {
+    return {
+        $schema: 'http://json-schema.org/draft-07/schema#',
+        title: 'Jeeves Core Configuration',
+        type: 'object',
+        properties: {
+            $schema: { type: 'string' },
+            owners: {
+                type: 'array',
+                items: { type: 'string' },
+                default: [],
+            },
+            services: {
+                type: 'object',
+                additionalProperties: {
+                    type: 'object',
+                    properties: {
+                        url: { type: 'string', format: 'uri' },
+                    },
+                    required: ['url'],
+                },
+                default: {},
+            },
+            registryCache: {
+                type: 'object',
+                properties: {
+                    ttlSeconds: {
+                        type: 'integer',
+                        minimum: 1,
+                        default: 3600,
+                    },
+                },
+                default: {},
+            },
+        },
+    };
+}
+/**
+ * Load and parse a config file, returning undefined if missing or invalid.
+ *
+ * @param configDir - Directory containing config.json.
+ * @returns Parsed config or undefined.
+ */
+function loadConfig(configDir) {
+    const configPath = join(configDir, CONFIG_FILE);
+    if (!existsSync(configPath))
+        return undefined;
+    try {
+        const raw = readFileSync(configPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        return coreConfigSchema.parse(parsed);
     }
-    // 2. Gateway-provided path resolver
-    if (typeof api.resolvePath === 'function') {
-        return api.resolvePath('.');
+    catch {
+        return undefined;
+    }
+}
+
+/**
+ * Service URL resolution.
+ *
+ * @remarks
+ * Resolves the URL for a named Jeeves service using the following
+ * resolution order:
+ * 1. Consumer's own component config
+ * 2. Core config (`{configRoot}/jeeves-core/config.json`)
+ * 3. Default port constants
+ */
+/**
+ * Resolve the URL for a named Jeeves service.
+ *
+ * @param serviceName - The service name (e.g., 'watcher', 'runner').
+ * @param consumerName - Optional consumer component name for config override.
+ * @returns The resolved service URL.
+ * @throws Error if `init()` has not been called or the service is unknown.
+ */
+function getServiceUrl(serviceName, consumerName) {
+    // 1. Check consumer's own config
+    if (consumerName) {
+        const consumerDir = getComponentConfigDir(consumerName);
+        const consumerConfig = loadConfig(consumerDir);
+        const consumerUrl = consumerConfig?.services[serviceName]?.url;
+        if (consumerUrl)
+            return consumerUrl;
+    }
+    // 2. Check core config
+    const coreDir = getCoreConfigDir();
+    const coreConfig = loadConfig(coreDir);
+    const coreUrl = coreConfig?.services[serviceName]?.url;
+    if (coreUrl)
+        return coreUrl;
+    // 3. Fall back to port constants
+    const port = DEFAULT_PORTS[serviceName];
+    if (port !== undefined) {
+        return `http://127.0.0.1:${String(port)}`;
+    }
+    throw new Error(`jeeves-core: unknown service "${serviceName}" and no config found`);
+}
+
+/**
+ * Registry version cache for npm package update awareness.
+ *
+ * @remarks
+ * Caches the latest npm registry version in a local JSON file
+ * to avoid expensive `npm view` calls on every refresh cycle.
+ */
+/**
+ * Check the npm registry for the latest version of a package.
+ *
+ * @param packageName - The npm package name (e.g., '\@karmaniverous/jeeves').
+ * @param cacheDir - Directory to store the cache file.
+ * @param ttlSeconds - Cache TTL in seconds (default 3600).
+ * @returns The latest version string, or undefined if the check fails.
+ */
+function checkRegistryVersion(packageName, cacheDir, ttlSeconds = 3600) {
+    const cachePath = join(cacheDir, REGISTRY_CACHE_FILE);
+    // Check cache first
+    if (existsSync(cachePath)) {
+        try {
+            const raw = readFileSync(cachePath, 'utf-8');
+            const entry = JSON.parse(raw);
+            const age = Date.now() - new Date(entry.checkedAt).getTime();
+            if (age < ttlSeconds * 1000) {
+                return entry.version;
+            }
+        }
+        catch {
+            // Cache corrupt — proceed with fresh check
+        }
+    }
+    // Query npm registry
+    try {
+        const result = execSync(`npm view ${packageName} version`, {
+            encoding: 'utf-8',
+            timeout: 15_000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+        if (!result)
+            return undefined;
+        // Write cache
+        if (!existsSync(cacheDir)) {
+            mkdirSync(cacheDir, { recursive: true });
+        }
+        const entry = {
+            version: result,
+            checkedAt: new Date().toISOString(),
+        };
+        writeFileSync(cachePath, JSON.stringify(entry, null, 2), 'utf-8');
+        return result;
+    }
+    catch {
+        return undefined;
     }
-    // 3. Last resort — unsafe when gateway runs from system32
-    return process.cwd();
+}
+
+/**
+ * Remove a managed section or entire managed block from a file.
+ *
+ * @remarks
+ * Supports two modes:
+ * - No `sectionId`: Remove the entire managed block (markers + content),
+ *   leaving user content intact.
+ * - With `sectionId`: Remove a specific H2 section from within the
+ *   managed block. If it was the last section, remove the entire block.
+ *
+ * Provides file-level locking and atomic writes (temp file + rename).
+ * Missing markers or nonexistent sections are no-ops (no error thrown).
+ */
+/**
+ * Remove a managed section or entire managed block from a file.
+ *
+ * @param filePath - Absolute path to the target file.
+ * @param options - Optional section ID and custom markers.
+ */
+async function removeManagedSection(filePath, options = {}) {
+    const { sectionId, markers = TOOLS_MARKERS } = options;
+    if (!existsSync(filePath))
+        return;
+    await withFileLock(filePath, () => {
+        const fileContent = readFileSync(filePath, 'utf-8');
+        const parsed = parseManaged(fileContent, markers);
+        if (!parsed.found)
+            return;
+        let newContent;
+        if (!sectionId) {
+            // Remove entire managed block
+            newContent = buildWithoutBlock(parsed.beforeContent, parsed.userContent);
+        }
+        else {
+            // Remove specific section
+            const remaining = parsed.sections.filter((s) => s.id !== sectionId);
+            if (remaining.length === parsed.sections.length) {
+                // Section not found — no-op
+                return;
+            }
+            if (remaining.length === 0) {
+                // Last section removed — remove entire block
+                newContent = buildWithoutBlock(parsed.beforeContent, parsed.userContent);
+            }
+            else {
+                // Rebuild managed block without the removed section
+                newContent = buildWithSections(parsed.beforeContent, parsed.userContent, remaining, markers, parsed.versionStamp?.version);
+            }
+        }
+        atomicWrite(filePath, newContent);
+    });
+}
+/** Build file content without the managed block. */
+function buildWithoutBlock(beforeContent, userContent) {
+    const parts = [];
+    if (beforeContent)
+        parts.push(beforeContent);
+    if (userContent) {
+        if (parts.length > 0)
+            parts.push('');
+        parts.push(userContent);
+    }
+    if (parts.length === 0)
+        return '';
+    return parts.join('\n') + '\n';
+}
+/** Rebuild file content with remaining sections. */
+function buildWithSections(beforeContent, userContent, sections, markers, coreVersion) {
+    const sorted = sortSectionsByOrder([...sections]);
+    const sectionText = sorted
+        .map((s) => `## ${s.id}\n\n${s.content}`)
+        .join('\n\n');
+    const managedBody = markers.title
+        ? `# ${markers.title}\n\n${sectionText}`
+        : sectionText;
+    const beginLine = formatBeginMarker(markers.begin, coreVersion ?? DEFAULT_CORE_VERSION);
+    const endLine = formatEndMarker(markers.end);
+    const parts = [];
+    if (beforeContent) {
+        parts.push(beforeContent);
+        parts.push('');
+    }
+    parts.push(beginLine);
+    parts.push('');
+    parts.push(managedBody);
+    parts.push('');
+    parts.push(endLine);
+    if (userContent) {
+        parts.push('');
+        parts.push(userContent);
+    }
+    parts.push('');
+    return parts.join('\n');
 }
 
 /**
@@ -1698,9 +1778,322 @@ async function seedContent(options) {
     // Seed content via the same code path as writer cycles
     await refreshPlatformContent({
         coreVersion: options.coreVersion,
-        probeTimeoutMs: options.probeTimeoutMs ?? 3000,
-        skipRegistryCheck: options.skipRegistryCheck ?? true,
     });
 }
 
-export { AGENTS_MARKERS, CLEANUP_FLAG, COMPONENT_CONFIG_PREFIX, CONFIG_FILE, CORE_CONFIG_DIR, CORE_VERSION, ComponentWriter, DEFAULT_PORTS, META_PORT, REGISTRY_CACHE_FILE, RUNNER_PORT, SECTION_IDS, SECTION_ORDER, SERVER_PORT, SOUL_MARKERS, STALENESS_THRESHOLD_MS, TEMPLATES_DIR, TOOLS_MARKERS, VERSION_STAMP_PATTERN, WATCHER_PORT, WORKSPACE_FILES, checkRegistryVersion, coreConfigSchema, createAsyncContentCache, createComponentWriter, formatBeginMarker, formatEndMarker, generateJsonSchema, getComponentConfigDir, getConfigRoot, getCoreConfigDir, getCoreConfigFile, getServiceUrl, getWorkspacePath, init, jaccard, needsCleanup, parseManaged, probeAllServices, probeService, refreshPlatformContent, resetInit, resolveWorkspacePath, seedContent, shingles, shouldWrite, updateManagedSection };
+/**
+ * HTTP helpers for the OpenClaw plugin SDK.
+ *
+ * @remarks
+ * Thin wrappers around `fetch` that throw on non-OK responses
+ * and handle JSON serialisation/deserialisation.
+ */
+/**
+ * Fetch a URL with an automatic abort timeout.
+ *
+ * @param url - URL to fetch.
+ * @param timeoutMs - Timeout in milliseconds before aborting.
+ * @param init - Optional `fetch` init options.
+ * @returns The fetch Response object.
+ */
+async function fetchWithTimeout(url, timeoutMs, init) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => {
+        controller.abort();
+    }, timeoutMs);
+    try {
+        return await fetch(url, { ...init, signal: controller.signal });
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+/**
+ * Fetch JSON from a URL, throwing on non-OK responses.
+ *
+ * @param url - URL to fetch.
+ * @param init - Optional `fetch` init options.
+ * @returns Parsed JSON response body.
+ * @throws Error with `HTTP {status}: {body}` message on non-OK responses.
+ */
+async function fetchJson(url, init) {
+    const res = await fetch(url, init);
+    if (!res.ok) {
+        throw new Error('HTTP ' + String(res.status) + ': ' + (await res.text()));
+    }
+    return res.json();
+}
+/**
+ * POST JSON to a URL and return parsed response.
+ *
+ * @param url - URL to POST to.
+ * @param body - Request body (will be JSON-stringified).
+ * @returns Parsed JSON response body.
+ */
+async function postJson(url, body) {
+    return fetchJson(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+}
+
+/**
+ * OpenClaw configuration helpers for plugin CLI installers.
+ *
+ * @remarks
+ * Provides resolution of OpenClaw home directory and config file path,
+ * plus idempotent config patching for plugin install/uninstall.
+ */
+/**
+ * Resolve the OpenClaw home directory.
+ *
+ * @remarks
+ * Resolution order:
+ * 1. `OPENCLAW_CONFIG` env var → dirname of the config file path
+ * 2. `OPENCLAW_HOME` env var → resolved path
+ * 3. Default: `~/.openclaw`
+ *
+ * @returns Absolute path to the OpenClaw home directory.
+ */
+function resolveOpenClawHome() {
+    if (process.env.OPENCLAW_CONFIG) {
+        return dirname(resolve(process.env.OPENCLAW_CONFIG));
+    }
+    if (process.env.OPENCLAW_HOME) {
+        return resolve(process.env.OPENCLAW_HOME);
+    }
+    return join(homedir(), '.openclaw');
+}
+/**
+ * Resolve the OpenClaw config file path.
+ *
+ * @remarks
+ * If `OPENCLAW_CONFIG` is set, uses that directly.
+ * Otherwise defaults to `{home}/openclaw.json`.
+ *
+ * @param home - The OpenClaw home directory.
+ * @returns Absolute path to the config file.
+ */
+function resolveConfigPath(home) {
+    if (process.env.OPENCLAW_CONFIG) {
+        return resolve(process.env.OPENCLAW_CONFIG);
+    }
+    return join(home, 'openclaw.json');
+}
+/**
+ * Patch an allowlist array: add or remove the plugin ID.
+ *
+ * @returns A log message if a change was made, or undefined.
+ */
+function patchAllowList(parent, key, label, pluginId, mode) {
+    if (mode === 'add') {
+        if (!Array.isArray(parent[key])) {
+            parent[key] = [pluginId];
+            return `Created ${label} with "${pluginId}"`;
+        }
+        const list = parent[key];
+        if (!list.includes(pluginId)) {
+            list.push(pluginId);
+            return `Added "${pluginId}" to ${label}`;
+        }
+    }
+    else {
+        if (!Array.isArray(parent[key]))
+            return undefined;
+        const list = parent[key];
+        const filtered = list.filter((id) => id !== pluginId);
+        if (filtered.length !== list.length) {
+            parent[key] = filtered;
+            return `Removed "${pluginId}" from ${label}`;
+        }
+    }
+    return undefined;
+}
+/**
+ * Patch an OpenClaw config for plugin install or uninstall.
+ *
+ * @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 - Whether to add or remove the plugin.
+ * @returns Array of log messages describing changes made.
+ */
+function patchConfig(config, pluginId, mode) {
+    const messages = [];
+    // Ensure plugins section
+    if (!config.plugins || typeof config.plugins !== 'object') {
+        config.plugins = {};
+    }
+    const plugins = config.plugins;
+    // plugins.entries
+    if (!plugins.entries || typeof plugins.entries !== 'object') {
+        plugins.entries = {};
+    }
+    const entries = plugins.entries;
+    if (mode === 'add') {
+        if (!entries[pluginId]) {
+            entries[pluginId] = { enabled: true };
+            messages.push(`Added "${pluginId}" to plugins.entries`);
+        }
+    }
+    else if (pluginId in entries) {
+        Reflect.deleteProperty(entries, pluginId);
+        messages.push(`Removed "${pluginId}" from plugins.entries`);
+    }
+    // tools.alsoAllow
+    if (!config.tools || typeof config.tools !== 'object') {
+        config.tools = {};
+    }
+    const tools = config.tools;
+    const toolAlsoAllow = patchAllowList(tools, 'alsoAllow', 'tools.alsoAllow', pluginId, mode);
+    if (toolAlsoAllow)
+        messages.push(toolAlsoAllow);
+    return messages;
+}
+
+/**
+ * Plugin resolution helpers for the OpenClaw plugin SDK.
+ *
+ * @remarks
+ * Provides workspace path resolution and plugin setting resolution
+ * with a standard three-step fallback chain:
+ * plugin config → environment variable → default value.
+ */
+/**
+ * Resolve the workspace root from the OpenClaw plugin API.
+ *
+ * @remarks
+ * Tries three sources in order:
+ * 1. `api.config.agents.defaults.workspace` — explicit config
+ * 2. `api.resolvePath('.')` — gateway-provided path resolver
+ * 3. `process.cwd()` — last resort
+ *
+ * @param api - The plugin API object provided by the gateway.
+ * @returns Absolute path to the workspace root.
+ */
+function resolveWorkspacePath(api) {
+    const configured = api.config?.agents?.defaults?.workspace;
+    if (typeof configured === 'string' && configured.trim()) {
+        return configured;
+    }
+    if (typeof api.resolvePath === 'function') {
+        return api.resolvePath('.');
+    }
+    return process.cwd();
+}
+/**
+ * Resolve a plugin setting via the standard three-step fallback chain:
+ * plugin config → environment variable → fallback value.
+ *
+ * @param api - Plugin API object.
+ * @param pluginId - Plugin identifier (e.g., 'jeeves-watcher-openclaw').
+ * @param key - Config key within the plugin's config object.
+ * @param envVar - Environment variable name.
+ * @param fallback - Default value if neither source provides one.
+ * @returns The resolved setting value.
+ */
+function resolvePluginSetting(api, pluginId, key, envVar, fallback) {
+    const fromPlugin = api.config?.plugins?.entries?.[pluginId]?.config?.[key];
+    if (typeof fromPlugin === 'string')
+        return fromPlugin;
+    const fromEnv = process.env[envVar];
+    if (fromEnv)
+        return fromEnv;
+    return fallback;
+}
+/**
+ * Resolve an optional plugin setting via the two-step fallback chain:
+ * plugin config → environment variable. Returns `undefined` if neither
+ * source provides a value.
+ *
+ * @param api - Plugin API object.
+ * @param pluginId - Plugin identifier (e.g., 'jeeves-watcher-openclaw').
+ * @param key - Config key within the plugin's config object.
+ * @param envVar - Environment variable name.
+ * @returns The resolved setting value, or `undefined`.
+ */
+function resolveOptionalPluginSetting(api, pluginId, key, envVar) {
+    const fromPlugin = api.config?.plugins?.entries?.[pluginId]?.config?.[key];
+    if (typeof fromPlugin === 'string')
+        return fromPlugin;
+    const fromEnv = process.env[envVar];
+    if (fromEnv)
+        return fromEnv;
+    return undefined;
+}
+
+/**
+ * Tool result formatters for the OpenClaw plugin SDK.
+ *
+ * @remarks
+ * Provides standardised helpers for building `ToolResult` objects:
+ * success, error, and connection-error variants.
+ */
+/**
+ * Format a successful tool result.
+ *
+ * @param data - Arbitrary data to return as JSON.
+ * @returns A `ToolResult` with JSON-stringified content.
+ */
+function ok(data) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+    };
+}
+/**
+ * Format an error tool result.
+ *
+ * @param error - Error instance, string, or other value.
+ * @returns A `ToolResult` with `isError: true`.
+ */
+function fail(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+        content: [{ type: 'text', text: 'Error: ' + message }],
+        isError: true,
+    };
+}
+/**
+ * Format a connection error with actionable guidance.
+ *
+ * @remarks
+ * Detects `ECONNREFUSED`, `ENOTFOUND`, and `ETIMEDOUT` from
+ * `error.cause.code` and returns a user-friendly message referencing
+ * the plugin's `config.apiUrl` setting. Falls back to `fail()` for
+ * non-connection errors.
+ *
+ * @param error - Error instance (typically from `fetch`).
+ * @param baseUrl - The URL that was being contacted.
+ * @param pluginId - The plugin identifier for config guidance.
+ * @returns A `ToolResult` with `isError: true`.
+ */
+function connectionFail(error, baseUrl, pluginId) {
+    const cause = error instanceof Error ? error.cause : undefined;
+    const code = cause && typeof cause === 'object' && 'code' in cause
+        ? String(cause.code)
+        : '';
+    const isConnectionError = code === 'ECONNREFUSED' || code === 'ENOTFOUND' || code === 'ETIMEDOUT';
+    if (isConnectionError) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: [
+                        `Service not reachable at ${baseUrl}.`,
+                        'Either start the service, or if it runs on a different port,',
+                        `set plugins.entries.${pluginId}.config.apiUrl in openclaw.json.`,
+                    ].join('\n'),
+                },
+            ],
+            isError: true,
+        };
+    }
+    return fail(error);
+}
+
+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 };