@karmaniverous/jeeves 0.2.0 → 0.3.1

package/dist/index.d.ts

@@ -48,8 +48,6 @@ declare function createConfigQueryHandler(getConfig: () => unknown): ConfigQuery
  */
 /** Version entry for a single component. */
 interface ComponentVersionEntry {
-    /** Service version from health probe. */
-    serviceVersion?: string;
     /** Plugin version (the OpenClaw plugin package version). */
     pluginVersion?: string;
     /** npm package name for the service. */
@@ -72,8 +70,6 @@ declare function readComponentVersions(coreConfigDir: string): ComponentVersions
 interface WriteComponentVersionOptions {
     /** Component name. */
     componentName: string;
-    /** Service version from probe, if available. */
-    serviceVersion?: string;
     /** Plugin version. */
     pluginVersion?: string;
     /** Service npm package name. */
@@ -92,89 +88,6 @@ interface WriteComponentVersionOptions {
  */
 declare function writeComponentVersion(coreConfigDir: string, options: WriteComponentVersionOptions): void;
 
-/**
- * Core types for the OpenClaw plugin SDK.
- *
- * @remarks
- * These types define the contract between plugins and the OpenClaw gateway.
- * They unify the various `PluginApi` definitions previously duplicated
- * across component plugins into a single canonical source.
- */
-/** Result shape returned by tool executions. */
-interface ToolResult {
-    /** Content blocks — typically a single text block. */
-    content: Array<{
-        type: string;
-        text: string;
-    }>;
-    /** Whether this result represents an error. */
-    isError?: boolean;
-}
-/** Tool descriptor for registration with the OpenClaw gateway. */
-interface ToolDescriptor {
-    /** Unique tool name. */
-    name: string;
-    /** Human-readable description. */
-    description: string;
-    /** JSON Schema for the tool's parameters. */
-    parameters: Record<string, unknown>;
-    /** Execute the tool with the given parameters. */
-    execute: (id: string, params: Record<string, unknown>) => Promise<ToolResult>;
-}
-/** Options for tool registration. */
-interface ToolRegistrationOptions {
-    /** Whether the tool is optional (non-fatal if registration fails). */
-    optional?: boolean;
-}
-/**
- * Canonical OpenClaw plugin API interface.
- *
- * @remarks
- * This is the shape of the `api` object passed to plugins by the
- * OpenClaw gateway at registration time. Fields are optional where
- * the gateway may not provide them in all versions.
- */
-interface PluginApi {
-    /** OpenClaw configuration object. */
-    config?: {
-        /** Agent configuration block. */
-        agents?: {
-            /** Default agent settings. */
-            defaults?: {
-                /** Absolute path to the workspace root directory. */
-                workspace?: string;
-            };
-        };
-        /** Installed plugin configuration. */
-        plugins?: {
-            /** Plugin entries keyed by plugin ID. */
-            entries?: Record<string, {
-                config?: Record<string, unknown>;
-            }>;
-        };
-    };
-    /**
-     * Resolve a path relative to the OpenClaw workspace.
-     *
-     * @remarks
-     * Present on newer OpenClaw builds; optional for backwards compatibility.
-     */
-    resolvePath?: (input: string) => string;
-    /**
-     * Register a tool with the OpenClaw gateway.
-     *
-     * @param tool - Tool descriptor.
-     * @param options - Registration options.
-     */
-    registerTool(tool: ToolDescriptor, options?: ToolRegistrationOptions): void;
-}
-/**
- * Alias for `PluginApi`, retained for backward compatibility.
- *
- * Prefer `PluginApi` for new code. This alias will be removed in v0.3.0.
- */
-type PluginApiLike = PluginApi;
-
 /**
  * Component interface types for the Jeeves platform.
  *
@@ -183,7 +96,6 @@ type PluginApiLike = PluginApi;
  * to participate in the platform. The `JeevesComponent` interface is
  * the primary integration point.
  */
-
 /** Service health status. */
 interface ServiceStatus {
     /** Whether the service is running. */
@@ -253,9 +165,8 @@ declare class ComponentWriter {
     private timer;
     private readonly component;
     private readonly configDir;
-    private readonly probeTimeoutMs;
     /** @internal */
-    constructor(component: JeevesComponent, probeTimeoutMs?: number);
+    constructor(component: JeevesComponent);
     /** The component's config directory path. */
     get componentConfigDir(): string;
     /** Whether the writer timer is currently running. */
@@ -348,55 +259,14 @@ declare function createAsyncContentCache(options: AsyncContentCacheOptions): ()
  * - `generateToolsContent` must be a function
  */
 
-/** Options for creating a ComponentWriter. */
-interface CreateComponentWriterOptions {
-    /** Timeout for health probes in ms (default 3000). */
-    probeTimeoutMs?: number;
-}
 /**
  * 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.
  */
-declare function createComponentWriter(component: JeevesComponent, options?: CreateComponentWriterOptions): ComponentWriter;
-
-/**
- * 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.
- */
-declare function resolveWorkspacePath(api: PluginApi): string;
-/**
- * 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.
- */
-declare function resolvePluginSetting(api: PluginApi, pluginId: string, key: string, envVar: string, fallback: string): string;
+declare function createComponentWriter(component: JeevesComponent): ComponentWriter;
 
 /**
  * Comment markers for managed content blocks.
@@ -605,44 +475,6 @@ declare function generateJsonSchema(): Record<string, unknown>;
  */
 declare function getServiceUrl(serviceName: string, consumerName?: string): string;
 
-/**
- * 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.
- */
-/** Health probe result for a single service. */
-interface ProbeResult {
-    /** Service name (e.g., 'server', 'watcher'). */
-    name: string;
-    /** Port number. */
-    port: number;
-    /** Whether the service responded successfully. */
-    healthy: boolean;
-    /** Service version from the health response, if available. */
-    version?: string;
-    /** Error message if the probe failed. */
-    error?: string;
-}
-/**
- * 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.
- */
-declare function probeService(serviceName: string, consumerName?: string, timeoutMs?: number): Promise<ProbeResult>;
-/**
- * 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.
- */
-declare function probeAllServices(consumerName?: string, timeoutMs?: number): Promise<ProbeResult[]>;
-
 /**
  * Registry version cache for npm package update awareness.
  *
@@ -764,7 +596,7 @@ declare function needsCleanup(managedContent: string, userContent: string, thres
 /** Stale lock threshold in ms (2 minutes). */
 declare const STALE_LOCK_MS = 120000;
 /** Default core version when none provided. */
-declare const DEFAULT_CORE_VERSION = "0.0.0";
+declare const DEFAULT_CORE_VERSION: string;
 /**
  * Write content to a file atomically via a temp file + rename.
  *
@@ -936,9 +768,9 @@ declare function shouldWrite(myVersion: string, existing: VersionStamp | undefin
  *
  * @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`.
+ * Reads content files from the package's `content/` directory, renders the
+ * Platform template with live data, and writes managed sections using
+ * `updateManagedSection`.
  */
 /** Options for refreshPlatformContent. */
 interface RefreshPlatformContentOptions {
@@ -954,10 +786,6 @@ interface RefreshPlatformContentOptions {
     pluginPackage?: string;
     /** Staleness threshold override in ms. */
     stalenessThresholdMs?: number;
-    /** Timeout for health probes in ms. */
-    probeTimeoutMs?: number;
-    /** Skip registry version check (useful for testing). */
-    skipRegistryCheck?: boolean;
 }
 /**
  * Refresh platform content: SOUL.md, AGENTS.md, and TOOLS.md Platform section.
@@ -978,10 +806,6 @@ declare function refreshPlatformContent(options: RefreshPlatformContentOptions):
 interface SeedContentOptions {
     /** Core library version for version-stamp convergence. */
     coreVersion: string;
-    /** Timeout for health probes in ms. */
-    probeTimeoutMs?: number;
-    /** Skip registry version check. */
-    skipRegistryCheck?: boolean;
 }
 /**
  * Seed all platform content into the workspace.
@@ -1002,6 +826,15 @@ declare function seedContent(options: SeedContentOptions): Promise<void>;
  * 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.
+ */
+declare function fetchWithTimeout(url: string, timeoutMs: number, init?: RequestInit): Promise<Response>;
 /**
  * Fetch JSON from a URL, throwing on non-OK responses.
  *
@@ -1065,6 +898,133 @@ declare function resolveConfigPath(home: string): string;
  */
 declare function patchConfig(config: Record<string, unknown>, pluginId: string, mode: 'add' | 'remove'): string[];
 
+/**
+ * Core types for the OpenClaw plugin SDK.
+ *
+ * @remarks
+ * These types define the contract between plugins and the OpenClaw gateway.
+ * They unify the various `PluginApi` definitions previously duplicated
+ * across component plugins into a single canonical source.
+ */
+/** Result shape returned by tool executions. */
+interface ToolResult {
+    /** Content blocks — typically a single text block. */
+    content: Array<{
+        /** MIME type identifier (e.g. `"text"`). */
+        type: string;
+        /** Text content of the block. */
+        text: string;
+    }>;
+    /** Whether this result represents an error. */
+    isError?: boolean;
+}
+/** Tool descriptor for registration with the OpenClaw gateway. */
+interface ToolDescriptor {
+    /** Unique tool name. */
+    name: string;
+    /** Human-readable description. */
+    description: string;
+    /** JSON Schema for the tool's parameters. */
+    parameters: Record<string, unknown>;
+    /** Execute the tool with the given parameters. */
+    execute: (id: string, params: Record<string, unknown>) => Promise<ToolResult>;
+}
+/** Options for tool registration. */
+interface ToolRegistrationOptions {
+    /** Whether the tool is optional (non-fatal if registration fails). */
+    optional?: boolean;
+}
+/**
+ * Canonical OpenClaw plugin API interface.
+ *
+ * @remarks
+ * This is the shape of the `api` object passed to plugins by the
+ * OpenClaw gateway at registration time. Fields are optional where
+ * the gateway may not provide them in all versions.
+ */
+interface PluginApi {
+    /** OpenClaw configuration object. */
+    config?: {
+        /** Agent configuration block. */
+        agents?: {
+            /** Default agent settings. */
+            defaults?: {
+                /** Absolute path to the workspace root directory. */
+                workspace?: string;
+            };
+        };
+        /** Installed plugin configuration. */
+        plugins?: {
+            /** Plugin entries keyed by plugin ID. */
+            entries?: Record<string, {
+                /** Plugin-specific configuration key-value pairs. */
+                config?: Record<string, unknown>;
+            }>;
+        };
+    };
+    /**
+     * Resolve a path relative to the OpenClaw workspace.
+     *
+     * @remarks
+     * Present on newer OpenClaw builds; optional for backwards compatibility.
+     */
+    resolvePath?: (input: string) => string;
+    /**
+     * Register a tool with the OpenClaw gateway.
+     *
+     * @param tool - Tool descriptor.
+     * @param options - Registration options.
+     */
+    registerTool(tool: ToolDescriptor, options?: ToolRegistrationOptions): void;
+}
+
+/**
+ * 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.
+ */
+declare function resolveWorkspacePath(api: PluginApi): string;
+/**
+ * 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.
+ */
+declare function resolvePluginSetting(api: PluginApi, pluginId: string, key: string, envVar: string, fallback: string): string;
+/**
+ * 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`.
+ */
+declare function resolveOptionalPluginSetting(api: PluginApi, pluginId: string, key: string, envVar: string): string | undefined;
+
 /**
  * Tool result formatters for the OpenClaw plugin SDK.
  *
@@ -1103,5 +1063,5 @@ declare function fail(error: unknown): ToolResult;
  */
 declare function connectionFail(error: unknown, baseUrl: string, pluginId: string): ToolResult;
 
-export { AGENTS_MARKERS, CLEANUP_FLAG, COMPONENT_CONFIG_PREFIX, COMPONENT_VERSIONS_FILE, CONFIG_FILE, CORE_CONFIG_DIR, CORE_VERSION, ComponentWriter, DEFAULT_CORE_VERSION, DEFAULT_PORTS, META_PORT, REGISTRY_CACHE_FILE, RUNNER_PORT, SECTION_IDS, SECTION_ORDER, SERVER_PORT, SOUL_MARKERS, STALENESS_THRESHOLD_MS, STALE_LOCK_MS, TEMPLATES_DIR, TOOLS_MARKERS, VERSION_STAMP_PATTERN, WATCHER_PORT, WORKSPACE_FILES, atomicWrite, checkRegistryVersion, connectionFail, coreConfigSchema, createAsyncContentCache, createComponentWriter, createConfigQueryHandler, fail, fetchJson, formatBeginMarker, formatEndMarker, generateJsonSchema, getComponentConfigDir, getConfigRoot, getCoreConfigDir, getCoreConfigFile, getServiceUrl, getWorkspacePath, init, jaccard, needsCleanup, ok, parseManaged, patchConfig, postJson, probeAllServices, probeService, readComponentVersions, refreshPlatformContent, removeManagedSection, resetInit, resolveConfigPath, resolveOpenClawHome, resolvePluginSetting, resolveWorkspacePath, seedContent, shingles, shouldWrite, updateManagedSection, withFileLock, writeComponentVersion };
-export type { AsyncContentCacheOptions, ComponentVersionEntry, ComponentVersionsState, ConfigQueryHandler, ConfigQueryResponse, CoreConfig, CreateComponentWriterOptions, InitOptions, JeevesComponent, ManagedMarkers, ManagedSection, ParseManagedResult, PluginApi, PluginApiLike, PluginCommands, ProbeResult, RefreshPlatformContentOptions, RemoveManagedSectionOptions, SectionId, SeedContentOptions, ServiceCommands, ServiceStatus, ToolDescriptor, ToolRegistrationOptions, ToolResult, UpdateManagedSectionOptions, VersionStamp, WriteComponentVersionOptions };
+export { AGENTS_MARKERS, CLEANUP_FLAG, COMPONENT_CONFIG_PREFIX, COMPONENT_VERSIONS_FILE, CONFIG_FILE, CORE_CONFIG_DIR, CORE_VERSION, ComponentWriter, DEFAULT_CORE_VERSION, DEFAULT_PORTS, META_PORT, REGISTRY_CACHE_FILE, RUNNER_PORT, SECTION_IDS, SECTION_ORDER, SERVER_PORT, SOUL_MARKERS, STALENESS_THRESHOLD_MS, STALE_LOCK_MS, TEMPLATES_DIR, TOOLS_MARKERS, VERSION_STAMP_PATTERN, WATCHER_PORT, WORKSPACE_FILES, atomicWrite, checkRegistryVersion, connectionFail, coreConfigSchema, createAsyncContentCache, createComponentWriter, createConfigQueryHandler, fail, fetchJson, fetchWithTimeout, formatBeginMarker, formatEndMarker, generateJsonSchema, getComponentConfigDir, getConfigRoot, getCoreConfigDir, getCoreConfigFile, getServiceUrl, getWorkspacePath, init, jaccard, needsCleanup, ok, parseManaged, patchConfig, postJson, readComponentVersions, refreshPlatformContent, removeManagedSection, resetInit, resolveConfigPath, resolveOpenClawHome, resolveOptionalPluginSetting, resolvePluginSetting, resolveWorkspacePath, seedContent, shingles, shouldWrite, updateManagedSection, withFileLock, writeComponentVersion };
+export type { AsyncContentCacheOptions, ComponentVersionEntry, ComponentVersionsState, ConfigQueryHandler, ConfigQueryResponse, CoreConfig, InitOptions, JeevesComponent, ManagedMarkers, ManagedSection, ParseManagedResult, PluginApi, PluginCommands, RefreshPlatformContentOptions, RemoveManagedSectionOptions, SectionId, SeedContentOptions, ServiceCommands, ServiceStatus, ToolDescriptor, ToolRegistrationOptions, ToolResult, UpdateManagedSectionOptions, VersionStamp, WriteComponentVersionOptions };