@karmaniverous/jeeves 0.6.0-3 → 0.6.0-5

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-2` placeholder is replaced by
+ * The `0.6.0-4` 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-2';
+const CORE_VERSION = '0.6.0-4';
 
 /**
  * Shared internal utility functions.

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,13 @@ 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 (required, so each plugin consciously
+ *   chooses its service URL). Pass the plugin's `apiUrl` (string or lazy
+ *   resolver); with `apiUrl` unset, 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 +1645,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-2` placeholder is replaced by
+ * The `0.6.0-4` 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-2';
+const CORE_VERSION = '0.6.0-4';
 
 /**
  * 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,16 @@ const PROBE_TIMEOUT_MS = 5000;
  * Create the standard plugin tool set from a component descriptor.
  *
  * @param descriptor - The component descriptor.
+ * @param options - Tool options (required, so each plugin consciously
+ *   chooses its service URL). Pass the plugin's `apiUrl` (string or lazy
+ *   resolver); with `apiUrl` unset, 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 +2494,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 +2523,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 +2551,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 +3291,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-3",
+  "version": "0.6.0-5",
   "allowScripts": {
     "lefthook": true
   }