@karmaniverous/jeeves 0.6.0-2 → 0.6.0-4

package/README.md

@@ -226,10 +226,13 @@ OpenClaw must already be installed; `jeeves` checks for it and never installs it
 
 1. Renders the SOUL.md/AGENTS.md managed blocks (your content outside the markers is kept) and the core config if it's missing. It never writes TOOLS.md, HEARTBEAT.md, anything under `skills/` or the spec templates (those ship with the jeeves-design skill in jeeves-tools).
 2. For each plugin (default: `runner`, `watcher`, `server`, `meta` at `latest`), resolves an exact version with `npm view`, then runs `openclaw plugins install npm:<pkg>@<version> --pin --accept-capabilities --force`. `--force` is required for any non-ClawHub source, and it also overwrites an existing install, which is how updates land. The install is skipped when that exact version is already installed. The CLI reads OpenClaw's install records once with `openclaw plugins inspect --all --json` (no plugin code is loaded) and skips a plugin only if its record has `source: "npm"`, names the same package, and records the same version, and the loaded plugin reports that version too. A v0.x path install, a leftover legacy copy, or any record it cannot read means a reinstall. `--force-reinstall` always reinstalls. Steps 3 and 4 run either way.
+
+   Each plugin's config (`plugins.entries.<id>.config.<key>`: `configRoot`, `apiUrl`, the server `pluginKey`, and any other value the CLI resolves, see [Plugin config](#plugin-config)) is written **before** that plugin's install, with its own `openclaw config set --batch-file` call, and each install is followed by a migration sweep (see below). With a running gateway, `openclaw plugins install` activates the plugin at once, and the plugins read their config (e.g. `configRoot`) at registration: config written afterwards is too late, and a manifest default (the watcher's `configRoot`) would win. `plugins.entries` is also the only source CLI contexts such as `openclaw doctor --lint` see (they don't have `JEEVES_CONFIG_ROOT`). The order per plugin is config batch, install, sweep. Config for a plugin that is already installed at its version, and every value that is already set, is handled in step 4.
+
 3. Removes any legacy `<openclaw dir>/extensions/<id>` copy left by the v0.x installer, but only if its `package.json` names the expected package.
-4. Runs `openclaw plugins inspect --all --json` once (a migration sweep, see below; its output is not shown and a failure is only logged), then sets `plugins.entries.<id>.hooks.allowConversationAccess: true` for plugins that [declare conversation hooks](#declaring-conversation-hooks), and the plugin config (`plugins.entries.<id>.config.<key>`, see [Plugin config](#plugin-config)), with one `openclaw config set --batch-file <file>` call. The file is created owner-only in a fresh temp directory (mode `0600` in a `0700` directory on Linux/macOS; on Windows the directory ACL is reduced to the current user with `icacls`) and deleted afterwards, so no value, secret or not, appears on a command line. Every write targets a leaf path, so unrelated keys are kept. `plugins.installs` is never written.
+4. Sets `plugins.entries.<id>.hooks.allowConversationAccess: true` for plugins that [declare conversation hooks](#declaring-conversation-hooks) (after the install: OpenClaw checks the installed package), plus the config of plugins that were not installed in this run, with one final `openclaw config set --batch-file <file>` call. When nothing was installed, a migration sweep (`openclaw plugins inspect --all --json`; its output is not shown and a failure is only logged) runs first. Every batch file is created owner-only in a fresh temp directory (mode `0600` in a `0700` directory on Linux/macOS; on Windows the directory ACL is reduced to the current user with `icacls`) and deleted afterwards, so no value, secret or not, appears on a command line. Every write targets a leaf path, so unrelated keys are kept. `plugins.installs` is never written.
 
-   Right after an install, OpenClaw can refuse to edit a plugin's config until it finishes that plugin's data/settings upgrade (`Plugin "<id>" data/settings upgrade is unfinished: ... has not converged`). This happens when the gateway started with `plugins.entries.<id>` configured before the package was installed: OpenClaw records a pending migration for that plugin, installing it does not clear the record, and a refused `openclaw config set` doesn't either. OpenClaw resolves such records in the startup preflight of ordinary CLI commands (not `config`, and not `plugins list`), which is why the sweep runs `plugins inspect` before the batch. Only that refusal is retried: the sweep runs again, then the same batch file is resubmitted after 2s, 4s, 8s, 16s, then every 30s, for up to 120s of waiting in total, with one log line per retry. If the plugin still hasn't converged, the command fails and names the plugin; wait and rerun it (the writes are idempotent). Any other error fails at once. The `openclaw config unset` repairs after an uninstall follow the same rule. A dry run never retries.
+   Right after an install, OpenClaw can refuse to edit a plugin's config until it finishes that plugin's data/settings upgrade (`Plugin "<id>" data/settings upgrade is unfinished: ... has not converged`). This happens when the gateway started with `plugins.entries.<id>` configured before the package was installed: OpenClaw records a pending migration for that plugin, installing it does not clear the record, and a refused `openclaw config set` doesn't either. OpenClaw resolves such records in the startup preflight of ordinary CLI commands (not `config`, and not `plugins list`), which is why a sweep runs `plugins inspect` right after each install. Every config batch (before an install and the final one) goes through the same retry: only that refusal is retried: the sweep runs again, then the same batch file is resubmitted after 2s, 4s, 8s, 16s, then every 30s, for up to 120s of waiting in total, with one log line per retry. If the plugin still hasn't converged, the command fails and names the plugin; wait and rerun it (the writes are idempotent). Any other error fails at once. The `openclaw config unset` repairs after an uninstall follow the same rule. A dry run never retries.
 
 Plugin specs can be short (`watcher`, `watcher@1.2.3`, `runner@^1`) or full (`@karmaniverous/jeeves-watcher-openclaw@1.2.3`). Only `@karmaniverous/jeeves-*-openclaw` packages are accepted. `--content-only` skips the plugins.
 
@@ -304,8 +307,8 @@ $ jeeves install watcher --dry-run
   @karmaniverous/jeeves-watcher-openclaw@0.16.0 (legacy copy found; conversation hooks: before_prompt_build)
 …
 [dry-run] openclaw plugins install npm:@karmaniverous/jeeves-watcher-openclaw@0.16.0 --pin --accept-capabilities --force
-[dry-run] remove legacy plugin copy: /home/jeeves/.openclaw/extensions/jeeves-watcher-openclaw
 [dry-run] openclaw plugins inspect --all --json (lets OpenClaw clear pending plugin migrations)
+[dry-run] remove legacy plugin copy: /home/jeeves/.openclaw/extensions/jeeves-watcher-openclaw
 [dry-run] openclaw config set --batch-file <private temp file>
 [dry-run]   batch file content: [{"path":"plugins.entries.jeeves-watcher-openclaw.hooks.allowConversationAccess","value":true}]
 ```
@@ -323,9 +326,12 @@ Plugin config:
 …
 [dry-run] set keys._plugin = <redacted> in /srv/jeeves/config/jeeves-server/config.json (currently unset; backup /srv/jeeves/config/jeeves-server/config.json.bak-<timestamp> first, then atomic write; restart jeeves-server afterwards)
 …
-[dry-run] openclaw plugins inspect --all --json (lets OpenClaw clear pending plugin migrations)
 [dry-run] openclaw config set --batch-file <private temp file>
 [dry-run]   batch file content: [{"path":"plugins.entries.jeeves-server-openclaw.config.configRoot","value":"/srv/jeeves/config"},{"path":"plugins.entries.jeeves-server-openclaw.config.apiUrl","value":"http://127.0.0.1:1934"},{"path":"plugins.entries.jeeves-server-openclaw.config.pluginKey","value":"<redacted>"}]
+[dry-run] openclaw plugins install npm:@karmaniverous/jeeves-server-openclaw@0.14.0 --pin --accept-capabilities --force
+[dry-run] openclaw plugins inspect --all --json (lets OpenClaw clear pending plugin migrations)
+[dry-run] openclaw config set --batch-file <private temp file>
+[dry-run]   batch file content: [{"path":"plugins.entries.jeeves-server-openclaw.hooks.allowConversationAccess","value":true}]
 ```
 
 A live run stops at the first failing step. A non-zero exit from any `openclaw` or `npm` command makes `jeeves` exit 1 and print the command and its error output. Commands are spawned with an argument vector and no shell, so the same invocation works on Linux, macOS and Windows.

package/dist/cli/jeeves/index.js

@@ -140,14 +140,14 @@ const DEFAULT_PORTS = {
  * Core library version, inlined at build time.
  *
  * @remarks
- * The `0.6.0-1` placeholder is replaced by
+ * The `0.6.0-3` 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.6.0-1';
+const CORE_VERSION = '0.6.0-3';
 
 /**
  * Shared internal utility functions.
@@ -3185,7 +3185,9 @@ function installOptionsFromCli(opts, configRoot) {
  * install records, declared hooks, legacy directories) and then either
  * printed (`--dry-run`) or executed by {@link executePlan}. Step order encodes
  * the safety rules: legacy copies are removed only after the npm install
- * succeeded; config repair runs only after uninstall succeeded. Config writes
+ * succeeded; a plugin's config is written before its install (a running
+ * gateway activates it at once); config repair runs only after uninstall
+ * succeeded. Config writes
  * are `configSetBatch` steps, run as `openclaw config set --batch-file` with an
  * owner-only temp file, so no value (secret or not) is on a command line.
  *
@@ -3196,6 +3198,32 @@ const openclaw = (args) => ({
     command: OPENCLAW_BIN,
     args,
 });
+/** A config batch step (secrets attached for redaction when present). */
+const configBatch = (ops, secrets) => ({
+    kind: 'configSetBatch',
+    ops,
+    ...(secrets.length > 0 ? { redact: [...secrets] } : {}),
+});
+/**
+ * Split resolved config ops into per-plugin groups for the given plugin ids
+ * and the rest.
+ *
+ * @param ops - Resolved `plugins.entries.<id>.config.<key>` operations.
+ * @param pluginIds - Plugins whose config is written before their install.
+ * @returns Ops by plugin id, and the ops not claimed by any of them.
+ */
+function splitConfigOps(ops, pluginIds) {
+    const byPlugin = new Map();
+    const rest = [];
+    for (const op of ops) {
+        const owner = pluginIds.find((id) => op.path.startsWith(configValuePath(id, '')));
+        if (owner === undefined)
+            rest.push(op);
+        else
+            byPlugin.set(owner, [...(byPlugin.get(owner) ?? []), op]);
+    }
+    return { byPlugin, rest };
+}
 /**
  * Build the install/update plan.
  *
@@ -3203,22 +3231,33 @@ const openclaw = (args) => ({
  * @param plugins - Current `plugins` config slice.
  * @param config - Resolved plugin config to write (optional).
  * @returns The server `keys._plugin` write (if planned; first, so a failure
- *   there, e.g. a held lock, leaves OpenClaw untouched), then install steps
- *   (targets not yet installed at their version), then legacy removals, then
- *   (when there is config to write) a migration sweep so OpenClaw clears the
- *   pending migration records it keeps for freshly installed plugins, then
- *   one config batch with hook access (only for targets that declare
- *   conversation hooks) and plugin config. Re-running after a later failure
- *   converges: the server then has the key and the plugin side copies it.
+ *   there, e.g. a held lock, leaves OpenClaw untouched); then, per target not
+ *   yet installed at its version: a config batch with that plugin's resolved
+ *   `plugins.entries.<id>.config` values (when any need writing), the
+ *   `openclaw plugins install`, and a migration sweep. A running gateway
+ *   activates each plugin as soon as it is installed and plugins read their
+ *   config (e.g. `configRoot`) at registration, so the config must already
+ *   be there; it also overrides manifest defaults (e.g. the watcher's
+ *   `configRoot`). Then legacy removals, then one final batch (preceded by
+ *   a sweep when nothing was installed) with hook access (only for targets
+ *   that declare conversation hooks; OpenClaw checks the installed package)
+ *   and the config of already installed targets. Re-running after a later
+ *   failure converges: the server then has the key and the plugin side
+ *   copies it.
  */
 function buildInstallPlan(targets, plugins, config) {
     const steps = config?.serverKeyWrite
         ? [{ kind: 'serverKeyWrite', write: config.serverKeyWrite }]
         : [];
-    for (const t of targets) {
-        if (t.installed !== true) {
-            steps.push(openclaw(pluginInstallArgs(t.packageName, t.version)));
-        }
+    const secrets = config?.secrets ?? [];
+    const toInstall = targets.filter((t) => t.installed !== true);
+    const { byPlugin, rest } = splitConfigOps(config?.ops ?? [], toInstall.map((t) => t.pluginId));
+    for (const t of toInstall) {
+        const ops = byPlugin.get(t.pluginId);
+        if (ops)
+            steps.push(configBatch(ops, secrets));
+        steps.push(openclaw(pluginInstallArgs(t.packageName, t.version)));
+        steps.push({ kind: 'migrationSweep' });
     }
     for (const t of targets) {
         if (t.legacyDir)
@@ -3228,16 +3267,12 @@ function buildInstallPlan(targets, plugins, config) {
         ...computeHookAccessOps(plugins, targets
             .filter((t) => t.conversationHooks.length > 0)
             .map((t) => t.pluginId)),
-        ...(config?.ops ?? []),
+        ...rest,
     ];
     if (ops.length > 0) {
-        const secrets = config?.secrets ?? [];
-        steps.push({ kind: 'migrationSweep' });
-        steps.push({
-            kind: 'configSetBatch',
-            ops,
-            ...(secrets.length > 0 ? { redact: [...secrets] } : {}),
-        });
+        if (toInstall.length === 0)
+            steps.push({ kind: 'migrationSweep' });
+        steps.push(configBatch(ops, secrets));
     }
     return steps;
 }

package/dist/index.d.ts

@@ -1132,6 +1132,27 @@ declare function recordRegisteredHooks(register: (api: PluginApi) => unknown, ap
  */
 declare function validateConversationHooks(packageJson: unknown, registeredHooks: readonly string[]): string[];
 
+/**
+ * Service base URL resolution for plugin tools.
+ *
+ * @remarks
+ * Plugin tools must call the service at the plugin's configured `apiUrl`
+ * (`plugins.entries.<id>.config.apiUrl`). The descriptor's `defaultPort`
+ * is only the fallback when no `apiUrl` is set.
+ */
+
+/**
+ * Lazy `apiUrl` resolver, evaluated on every tool call (so a plugin can
+ * read its config at call time, like `configRoot`).
+ */
+type PluginApiUrlResolver = () => string | undefined;
+/** Options for {@link createPluginToolset}. */
+declare const pluginToolsetOptionsSchema: z.ZodObject<{
+    apiUrl: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodCustom<PluginApiUrlResolver, PluginApiUrlResolver>]>>;
+}, z.core.$strip>;
+/** Options for {@link createPluginToolset}. */
+type PluginToolsetOptions = z.infer<typeof pluginToolsetOptionsSchema>;
+
 /**
  * Factory for the standard plugin tool set.
  *
@@ -1142,6 +1163,10 @@ declare function validateConversationHooks(packageJson: unknown, registeredHooks
  * - `{name}_config_apply` - Push config patch to running service
  * - `{name}_service` - Service lifecycle management
  *
+ * The HTTP tools call the plugin's configured `apiUrl` (see
+ * {@link PluginToolsetOptions}); the descriptor's `defaultPort` is only the
+ * fallback when `apiUrl` is unset.
+ *
  * Components add domain-specific tools separately.
  */
 
@@ -1149,9 +1174,11 @@ declare function validateConversationHooks(packageJson: unknown, registeredHooks
  * Create the standard plugin tool set from a component descriptor.
  *
  * @param descriptor - The component descriptor.
+ * @param options - Tool options; pass the plugin's `apiUrl` (string or lazy
+ *   resolver). Omitted, the tools call `http://127.0.0.1:<defaultPort>`.
  * @returns Array of tool descriptors to register.
  */
-declare function createPluginToolset(descriptor: JeevesComponentDescriptor): ToolDescriptor[];
+declare function createPluginToolset(descriptor: JeevesComponentDescriptor, options?: PluginToolsetOptions): ToolDescriptor[];
 
 /**
  * Resolve the package root directory from a module's `import.meta.url`.
@@ -1616,5 +1643,5 @@ declare function getErrorMessage(err: unknown): string;
  */
 declare function isTransientError(err: unknown): boolean;
 
-export { AGENTS_MARKERS, COMPONENT_CONFIG_PREFIX, CONFIG_FILE, CONVERSATION_HOOK_NAMES, CORE_CONFIG_DIR, CORE_VERSION, DEFAULT_BIND_ADDRESS, DEFAULT_PORTS, LEGACY_TOOLS_MARKERS, META_PORT, PLATFORM_COMPONENTS, RUNNER_PORT, SERVER_PORT, SOUL_MARKERS, STALE_LOCK_MS, VERSION_STAMP_PATTERN, WATCHER_PORT, WORKSPACE_CONFIG_DEFAULTS, WORKSPACE_CONFIG_FILE, WORKSPACE_FILES, analyzeMemory, appendJsonl, atomicWrite, buildEffectiveConfig, checkNodeVersion, connectionFail, coreConfigSchema, createConfigApplyHandler, createConfigQueryHandler, createGoogleAuth, createPluginToolset, createServiceCli, createServiceManager, createStatusHandler, ensureDir, fail, fetchJson, fetchWithTimeout, formatBeginMarker, formatEndMarker, generateJsonSchema, generateWorkspaceJsonSchema, getArg, getBindAddress, getChannelWorkspace, getComponentConfigDir, getComponentConfigPath, getConfigRoot, getCoreConfigDir, getCoreConfigFile, getEffectiveServiceName, getErrorMessage, getPackageRoot, getPackageVersion, getServiceState, getServiceUrl, getWorkspacePath, init, isTransientError, jeevesComponentDescriptorSchema, loadEnvFile, loadWorkspaceConfig, nowIso, ok, onPluginDispose, parseArgs, parseManaged, postJson, promptContextOptionsSchema, readJson, readJsonl, recordRegisteredHooks, registerComponentConfigPath, registerPromptContext, rejectWindowsDrivePath, removeManagedBlock, renderManagedBlock, resetInit, resolveConfigValue, resolveOptionalPluginSetting, resolvePluginSetting, resolveWorkspacePath, run, runScript, runWithRetry, saveCache, sleepAsync, sleepMs, substituteEnvVars, upsertManagedBlock, uuid, validateConversationHooks, validateSkillFrontmatter, withFileLock, workspaceConfigSchema, writeJsonAtomic, writeJsonl };
-export type { AccountConfig, ConfigApplyHandler, ConfigApplyRequest, ConfigApplyResult, ConfigProvenance, ConfigQueryHandler, ConfigQueryResponse, CoreConfig, CreateStatusHandlerOptions, GoogleAuthOptions, HookRegistrationOptions, InitOptions, JeevesComponentDescriptor, ManagedBlockStampOptions, ManagedMarkers, MemoryHygieneOptions, MemoryHygieneResult, ParseManagedResult, PlatformComponent, PluginApi, PluginLifecycleApi, PromptBuildContext, PromptBuildEvent, PromptBuildHandler, PromptBuildResult, PromptContextOptions, PromptContextProvider, ResolvedCliConfig, ResolvedValue, RetryOptions, RunOptions, ServiceAccountFileConfig, ServiceManager, ServiceManagerOptions, ServiceState, SkillFrontmatter, SlackWorkspaceOptions, StatusHandler, StatusHandlerResult, StatusResponse, ToolDescriptor, ToolRegistrationOptions, ToolResult, VersionStamp, WorkspaceConfig, WorkspaceOptions };
+export { AGENTS_MARKERS, COMPONENT_CONFIG_PREFIX, CONFIG_FILE, CONVERSATION_HOOK_NAMES, CORE_CONFIG_DIR, CORE_VERSION, DEFAULT_BIND_ADDRESS, DEFAULT_PORTS, LEGACY_TOOLS_MARKERS, META_PORT, PLATFORM_COMPONENTS, RUNNER_PORT, SERVER_PORT, SOUL_MARKERS, STALE_LOCK_MS, VERSION_STAMP_PATTERN, WATCHER_PORT, WORKSPACE_CONFIG_DEFAULTS, WORKSPACE_CONFIG_FILE, WORKSPACE_FILES, analyzeMemory, appendJsonl, atomicWrite, buildEffectiveConfig, checkNodeVersion, connectionFail, coreConfigSchema, createConfigApplyHandler, createConfigQueryHandler, createGoogleAuth, createPluginToolset, createServiceCli, createServiceManager, createStatusHandler, ensureDir, fail, fetchJson, fetchWithTimeout, formatBeginMarker, formatEndMarker, generateJsonSchema, generateWorkspaceJsonSchema, getArg, getBindAddress, getChannelWorkspace, getComponentConfigDir, getComponentConfigPath, getConfigRoot, getCoreConfigDir, getCoreConfigFile, getEffectiveServiceName, getErrorMessage, getPackageRoot, getPackageVersion, getServiceState, getServiceUrl, getWorkspacePath, init, isTransientError, jeevesComponentDescriptorSchema, loadEnvFile, loadWorkspaceConfig, nowIso, ok, onPluginDispose, parseArgs, parseManaged, pluginToolsetOptionsSchema, postJson, promptContextOptionsSchema, readJson, readJsonl, recordRegisteredHooks, registerComponentConfigPath, registerPromptContext, rejectWindowsDrivePath, removeManagedBlock, renderManagedBlock, resetInit, resolveConfigValue, resolveOptionalPluginSetting, resolvePluginSetting, resolveWorkspacePath, run, runScript, runWithRetry, saveCache, sleepAsync, sleepMs, substituteEnvVars, upsertManagedBlock, uuid, validateConversationHooks, validateSkillFrontmatter, withFileLock, workspaceConfigSchema, writeJsonAtomic, writeJsonl };
+export type { AccountConfig, ConfigApplyHandler, ConfigApplyRequest, ConfigApplyResult, ConfigProvenance, ConfigQueryHandler, ConfigQueryResponse, CoreConfig, CreateStatusHandlerOptions, GoogleAuthOptions, HookRegistrationOptions, InitOptions, JeevesComponentDescriptor, ManagedBlockStampOptions, ManagedMarkers, MemoryHygieneOptions, MemoryHygieneResult, ParseManagedResult, PlatformComponent, PluginApi, PluginApiUrlResolver, PluginLifecycleApi, PluginToolsetOptions, PromptBuildContext, PromptBuildEvent, PromptBuildHandler, PromptBuildResult, PromptContextOptions, PromptContextProvider, ResolvedCliConfig, ResolvedValue, RetryOptions, RunOptions, ServiceAccountFileConfig, ServiceManager, ServiceManagerOptions, ServiceState, SkillFrontmatter, SlackWorkspaceOptions, StatusHandler, StatusHandlerResult, StatusResponse, ToolDescriptor, ToolRegistrationOptions, ToolResult, VersionStamp, WorkspaceConfig, WorkspaceOptions };

package/dist/index.js

@@ -142,14 +142,14 @@ const DEFAULT_PORTS = {
  * Core library version, inlined at build time.
  *
  * @remarks
- * The `0.6.0-1` placeholder is replaced by
+ * The `0.6.0-3` 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.6.0-1';
+const CORE_VERSION = '0.6.0-3';
 
 /**
  * Workspace and config root initialization.
@@ -2347,6 +2347,43 @@ function validateConversationHooks(packageJson, registeredHooks) {
     return declared;
 }
 
+/**
+ * Service base URL resolution for plugin tools.
+ *
+ * @remarks
+ * Plugin tools must call the service at the plugin's configured `apiUrl`
+ * (`plugins.entries.<id>.config.apiUrl`). The descriptor's `defaultPort`
+ * is only the fallback when no `apiUrl` is set.
+ */
+/** Options for {@link createPluginToolset}. */
+const pluginToolsetOptionsSchema = z.object({
+    /**
+     * Service base URL (e.g. `http://127.0.0.1:1936`), or a resolver
+     * evaluated per tool call. Unset, empty, or a resolver returning
+     * `undefined` falls back to `http://127.0.0.1:<defaultPort>`.
+     */
+    apiUrl: z
+        .union([
+        z.string(),
+        z.custom((v) => typeof v === 'function', {
+            message: 'apiUrl must be a string or a function',
+        }),
+    ])
+        .optional(),
+});
+/**
+ * Resolve the service base URL for a plugin tool call.
+ *
+ * @param apiUrl - Configured URL or lazy resolver (optional).
+ * @param defaultPort - Descriptor default port, used when `apiUrl` is unset.
+ * @returns Base URL without a trailing slash.
+ */
+function resolvePluginApiUrl(apiUrl, defaultPort) {
+    const value = (typeof apiUrl === 'function' ? apiUrl() : apiUrl)?.trim();
+    const url = value ? value : `http://127.0.0.1:${String(defaultPort)}`;
+    return url.replace(/\/+$/, '');
+}
+
 /**
  * Tool result formatters for the OpenClaw plugin SDK.
  *
@@ -2426,6 +2463,10 @@ function connectionFail(error, baseUrl, pluginId) {
  * - `{name}_config_apply` - Push config patch to running service
  * - `{name}_service` - Service lifecycle management
  *
+ * The HTTP tools call the plugin's configured `apiUrl` (see
+ * {@link PluginToolsetOptions}); the descriptor's `defaultPort` is only the
+ * fallback when `apiUrl` is unset.
+ *
  * Components add domain-specific tools separately.
  */
 /** Timeout for HTTP probes in milliseconds. */
@@ -2434,11 +2475,14 @@ const PROBE_TIMEOUT_MS = 5000;
  * Create the standard plugin tool set from a component descriptor.
  *
  * @param descriptor - The component descriptor.
+ * @param options - Tool options; pass the plugin's `apiUrl` (string or lazy
+ *   resolver). Omitted, the tools call `http://127.0.0.1:<defaultPort>`.
  * @returns Array of tool descriptors to register.
  */
-function createPluginToolset(descriptor) {
+function createPluginToolset(descriptor, options = {}) {
     const { name, defaultPort } = descriptor;
-    const baseUrl = `http://127.0.0.1:${String(defaultPort)}`;
+    const { apiUrl } = pluginToolsetOptionsSchema.parse(options);
+    const resolveBaseUrl = () => resolvePluginApiUrl(apiUrl, defaultPort);
     const svcManager = createServiceManager(descriptor);
     const statusTool = {
         name: `${name}_status`,
@@ -2448,6 +2492,7 @@ function createPluginToolset(descriptor) {
             properties: {},
         },
         execute: async () => {
+            const baseUrl = resolveBaseUrl();
             try {
                 const res = await fetchWithTimeout(`${baseUrl}/status`, PROBE_TIMEOUT_MS);
                 if (!res.ok) {
@@ -2476,6 +2521,7 @@ function createPluginToolset(descriptor) {
         execute: async (_id, params) => {
             const path = params.path;
             const qs = path ? `?path=${encodeURIComponent(path)}` : '';
+            const baseUrl = resolveBaseUrl();
             try {
                 const result = await fetchJson(`${baseUrl}/config${qs}`);
                 return ok(result);
@@ -2503,6 +2549,7 @@ function createPluginToolset(descriptor) {
             if (!config) {
                 return fail('Missing required parameter: config');
             }
+            const baseUrl = resolveBaseUrl();
             try {
                 const result = await postJson(`${baseUrl}/config/apply`, {
                     patch: config,
@@ -3242,4 +3289,4 @@ async function getChannelWorkspace(channelId, token, options) {
     return teamId;
 }
 
-export { AGENTS_MARKERS, COMPONENT_CONFIG_PREFIX, CONFIG_FILE, CONVERSATION_HOOK_NAMES, CORE_CONFIG_DIR, CORE_VERSION, DEFAULT_BIND_ADDRESS, DEFAULT_PORTS, LEGACY_TOOLS_MARKERS, META_PORT, PLATFORM_COMPONENTS, RUNNER_PORT, SERVER_PORT, SOUL_MARKERS, STALE_LOCK_MS, VERSION_STAMP_PATTERN, WATCHER_PORT, WORKSPACE_CONFIG_DEFAULTS, WORKSPACE_CONFIG_FILE, WORKSPACE_FILES, analyzeMemory, appendJsonl, atomicWrite, buildEffectiveConfig, checkNodeVersion, connectionFail, coreConfigSchema, createConfigApplyHandler, createConfigQueryHandler, createGoogleAuth, createPluginToolset, createServiceCli, createServiceManager, createStatusHandler, ensureDir, fail, fetchJson, fetchWithTimeout, formatBeginMarker, formatEndMarker, generateJsonSchema, generateWorkspaceJsonSchema, getArg, getBindAddress, getChannelWorkspace, getComponentConfigDir, getComponentConfigPath, getConfigRoot, getCoreConfigDir, getCoreConfigFile, getEffectiveServiceName, getErrorMessage, getPackageRoot, getPackageVersion, getServiceState, getServiceUrl, getWorkspacePath, init, isTransientError, jeevesComponentDescriptorSchema, loadEnvFile, loadWorkspaceConfig, nowIso, ok, onPluginDispose, parseArgs, parseManaged, postJson, promptContextOptionsSchema, readJson, readJsonl, recordRegisteredHooks, registerComponentConfigPath, registerPromptContext, rejectWindowsDrivePath, removeManagedBlock, renderManagedBlock, resetInit, resolveConfigValue, resolveOptionalPluginSetting, resolvePluginSetting, resolveWorkspacePath, run, runScript, runWithRetry, saveCache, sleepAsync, sleepMs, substituteEnvVars, upsertManagedBlock, uuid, validateConversationHooks, validateSkillFrontmatter, withFileLock, workspaceConfigSchema, writeJsonAtomic, writeJsonl };
+export { AGENTS_MARKERS, COMPONENT_CONFIG_PREFIX, CONFIG_FILE, CONVERSATION_HOOK_NAMES, CORE_CONFIG_DIR, CORE_VERSION, DEFAULT_BIND_ADDRESS, DEFAULT_PORTS, LEGACY_TOOLS_MARKERS, META_PORT, PLATFORM_COMPONENTS, RUNNER_PORT, SERVER_PORT, SOUL_MARKERS, STALE_LOCK_MS, VERSION_STAMP_PATTERN, WATCHER_PORT, WORKSPACE_CONFIG_DEFAULTS, WORKSPACE_CONFIG_FILE, WORKSPACE_FILES, analyzeMemory, appendJsonl, atomicWrite, buildEffectiveConfig, checkNodeVersion, connectionFail, coreConfigSchema, createConfigApplyHandler, createConfigQueryHandler, createGoogleAuth, createPluginToolset, createServiceCli, createServiceManager, createStatusHandler, ensureDir, fail, fetchJson, fetchWithTimeout, formatBeginMarker, formatEndMarker, generateJsonSchema, generateWorkspaceJsonSchema, getArg, getBindAddress, getChannelWorkspace, getComponentConfigDir, getComponentConfigPath, getConfigRoot, getCoreConfigDir, getCoreConfigFile, getEffectiveServiceName, getErrorMessage, getPackageRoot, getPackageVersion, getServiceState, getServiceUrl, getWorkspacePath, init, isTransientError, jeevesComponentDescriptorSchema, loadEnvFile, loadWorkspaceConfig, nowIso, ok, onPluginDispose, parseArgs, parseManaged, pluginToolsetOptionsSchema, postJson, promptContextOptionsSchema, readJson, readJsonl, recordRegisteredHooks, registerComponentConfigPath, registerPromptContext, rejectWindowsDrivePath, removeManagedBlock, renderManagedBlock, resetInit, resolveConfigValue, resolveOptionalPluginSetting, resolvePluginSetting, resolveWorkspacePath, run, runScript, runWithRetry, saveCache, sleepAsync, sleepMs, substituteEnvVars, upsertManagedBlock, uuid, validateConversationHooks, validateSkillFrontmatter, withFileLock, workspaceConfigSchema, writeJsonAtomic, writeJsonl };

package/package.json

@@ -133,7 +133,7 @@
   },
   "type": "module",
   "types": "dist/index.d.ts",
-  "version": "0.6.0-2",
+  "version": "0.6.0-4",
   "allowScripts": {
     "lefthook": true
   }