jishushell 0.4.17 → 0.4.24-beta.2

package/dist/services/instance-manager.d.ts

@@ -1,15 +1,34 @@
-import type { AppSpec } from "../types.js";
 type ConfigChangeListener = (instanceId: string) => void;
 export declare function onConfigChange(listener: ConfigChangeListener): () => void;
-declare function instanceDir(instanceId: string): string;
+/**
+ * Fire the config-change listener fan-out. Adapters call this after
+ * `saveNativeConfig()` so LLM proxy / config editors pick up the change.
+ */
+export declare function notifyConfigChange(instanceId: string): void;
+export declare function instanceDir(instanceId: string): string;
+export declare function instanceMetaPath(instanceId: string): string;
+export declare function defaultModelEnvFile(instanceId: string): string;
+export declare function normalizePath(p: string): string;
+/**
+ * Read the gateway port out of a persisted runtime record. Tries
+ * `runtime.ports[]` first (generic framework contract); on miss,
+ * asks the runtime adapter for its legacy fallback (e.g. OpenClaw's
+ * `env.OPENCLAW_GATEWAY_PORT` / `args --port N`).
+ */
+export declare function extractGatewayPort(runtime: Record<string, any> | undefined, agentType?: string): number | null;
 /**
  * Probes whether a port is currently held by any process on the host.
  *
- * Binds `0.0.0.0:port` — under the Linux default socket semantics, this fails
- * with EADDRINUSE whenever another listener holds the port on `0.0.0.0`, on
- * any specific interface (e.g. `127.0.0.1`), or via Docker's published port
- * map. An IPv6-only listener on `::1` is not detected, but that edge case
- * never comes up in the Nomad+Docker path this project uses.
+ * Binds four addresses concurrently — `0.0.0.0`, `127.0.0.1`, `::` (v6-only),
+ * and `::1` — and treats the port as busy if any probe returns EADDRINUSE.
+ * The single-`0.0.0.0` probe used by the earlier revision was sufficient on
+ * Linux (where binding `0.0.0.0` conflicts with any pre-existing loopback
+ * listener on the same port) but silently passed on macOS, where BSD socket
+ * semantics let a wildcard v4 bind coexist with a `127.0.0.1` listener. A
+ * user running a natively-installed openclaw bound to `127.0.0.1:18789`
+ * would then be invisible to jishushell, so port allocation would assign
+ * 18789 to a new instance and the gateway would silently fail to bind at
+ * start time. Probing the loopback addresses directly closes that gap.
  */
 export declare function isPortInUse(port: number): Promise<boolean>;
 /**
@@ -25,6 +44,19 @@ export type GatewayPortAllocation = {
     port: number;
     skipped: number[];
 };
+/**
+ * Kind-agnostic gateway port allocator. Callers (adapters) pass their own
+ * `defaultPort` — the framework no longer hardcodes OpenClaw / Hermes base
+ * ports here. Walks upward from `defaultPort` until a free port is found
+ * that is neither held by an existing instance nor by any process on the
+ * host. Concurrent callers coordinate via `_pendingPorts`.
+ *
+ * Caller must release the allocated port via {@link releasePendingPort}
+ * after persisting it into instance metadata (or on failure).
+ */
+export declare function allocateGatewayPort(instanceId: string, defaultPort: number): Promise<GatewayPortAllocation>;
+/** Release a port previously reserved by {@link allocateGatewayPort}. */
+export declare function releasePendingPort(port: number): void;
 export declare function getResolvedOpenclawBin(): string;
 /**
  * When jishushell runs as root (e.g. systemd service), returns the actual
@@ -36,40 +68,18 @@ export declare function resolveServiceUser(): {
     uid: number;
     gid: number;
 } | null;
+/**
+ * When running as root, chown a file (and its .bak) to the service user so the
+ * openclaw process (running as that user) can read/write its own data files.
+ * No-op when not running as root.
+ */
+export declare function chownToServiceUser(...paths: string[]): void;
 export declare function parseEnvFile(path: string): Record<string, string>;
 export declare function updateEnvFile(path: string, updates: Record<string, string>): void;
 export declare function inferProviderApiKeyEnvName(providerId: string): string;
-export declare const CHANNEL_PLUGIN_MAP: Record<string, string>;
-/**
- * Dissociate a cloned/imported config from its source instance's IM bindings.
- *
- * Mutates the given config in place:
- *   - Deletes the entire `channels` block (same channel cannot serve multiple
- *     instances, so every inherited enabled/credential/account entry must go).
- *   - Deletes matching IM entries from `plugins.entries` so the plugin loader
- *     does not try to boot a channel whose config no longer exists.
- *
- * Used by both domain clone (`createInstance`'s `cloneFrom` path) and the
- * backup import paths (`importInstance`, `createFromBackup`) so that a new
- * instance never inherits a half-configured IM binding.
- */
-export declare function stripImBindings(config: Record<string, any>): void;
-/** Check if a channel plugin is installed for an instance. */
-export declare function isChannelPluginInstalled(instanceId: string, channelId: string): boolean;
-/**
- * Install a single channel plugin.
- * Docker mode: runs install inside the running container via docker exec.
- * Host mode (fallback): spawns the host openclaw binary directly.
- */
-export declare function installChannelPlugin(instanceId: string, channelId: string): Promise<void>;
 export declare function listInstances(): Record<string, any>[];
 export declare function getInstance(instanceId: string): Record<string, any> | null;
-export declare function createInstance(instanceId: string, name: string, description?: string, cloneFrom?: string, openclawHome?: string, appSpec?: AppSpec, cloneOptions?: {
-    include_sessions?: boolean;
-    include_memory?: boolean;
-}): Promise<Record<string, any>>;
 export declare function updateInstance(instanceId: string, name?: string, description?: string): Record<string, any> | null;
-/** Update instance.json metadata fields (shallow merge at top level). */
 export declare function updateInstanceMeta(instanceId: string, patch: Record<string, any>): void;
 export declare function deleteInstance(instanceId: string, purgeBackups?: boolean): Promise<{
     ok: boolean;
@@ -77,7 +87,26 @@ export declare function deleteInstance(instanceId: string, purgeBackups?: boolea
 }>;
 export declare function getConfig(instanceId: string): Record<string, any> | null;
 export declare function getStoredConfig(instanceId: string): Record<string, any> | null;
-export declare function saveConfig(instanceId: string, config: Record<string, any>): boolean;
+export declare function saveConfig(instanceId: string, config: Record<string, any>): Promise<boolean>;
+/**
+ * @deprecated Use `getAdapter("openclaw").channelPluginMap` instead.
+ * Provides the OpenClaw channel-plugin map via a Proxy so old direct-
+ * property reads (e.g. `CHANNEL_PLUGIN_MAP.feishu`) keep working.
+ */
+export declare const CHANNEL_PLUGIN_MAP: Record<string, string>;
+/**
+ * @deprecated Use `getAdapter(agentType).isChannelPluginInstalled(id, channelId)` instead.
+ */
+export declare function isChannelPluginInstalled(instanceId: string, channelId: string): boolean;
+/**
+ * @deprecated Use `getAdapter(agentType).createInstance({ instanceId, name, description, ... })` instead.
+ * Retained for unit tests and legacy scripts; forwards to the
+ * OpenClawAdapter's `createInstance` method.
+ */
+export declare function createInstance(instanceId: string, name: string, description: string, cloneFrom?: string, agentHome?: string, cloneOptions?: {
+    include_sessions?: boolean;
+    include_memory?: boolean;
+}): Promise<Record<string, any>>;
 export declare function getOpenclawHome(instanceId: string): string;
 export declare function saveFeishuCredentials(instanceId: string, creds: {
     appId: string;
@@ -91,9 +120,6 @@ export declare function saveWeixinCredentials(instanceId: string, creds: {
     baseUrl: string;
     userId: string;
 }): void;
-/**
- * Get connected WeChat accounts for an instance.
- */
 export declare function getWeixinAccounts(instanceId: string): Array<{
     accountId: string;
     userId?: string;
@@ -104,6 +130,8 @@ export declare function getLegacyOpenclawConfigPath(instanceId: string): string;
 export declare function getInstanceRuntime(instanceId: string): Record<string, any>;
 export declare function getRuntimeEnvFiles(instanceId: string): string[];
 export declare function getGatewayPort(instanceId: string): number;
+export declare function getListeningHostForPort(port: number): string;
+export declare function getAdvertisedHostForPort(port: number): string;
 export declare function getGatewayHost(instanceId: string): Promise<string>;
 /**
  * Wrap an IPv6 literal in brackets for safe URL host-component / Host-header
@@ -133,3 +161,18 @@ export declare function reallocateGatewayPort(instanceId: string): Promise<{
 export declare function findInstancesSharingGatewayPort(instanceId: string): string[];
 export declare function getRuntimeEnv(instanceId: string): Record<string, string>;
 export { instanceDir as getInstanceDir };
+/**
+ * Compatibility shim: allocate a gateway port for a new instance and return
+ * just the port number. Wraps `allocateGatewayPort`, which takes a seed port
+ * and returns `{ port, skipped }`. Non-OpenClaw app managers don't have an
+ * agentType-specific default port yet, so we seed with 18789 (OpenClaw's
+ * default) — the allocator walks upward until it finds a free slot so the
+ * actual port chosen is independent of the seed.
+ */
+export declare function defaultGatewayPort(instanceId: string): Promise<number>;
+/**
+ * Compatibility shim: release a pending port reservation.
+ * Mirrors the cli-branch `releasePort(port)` helper on top of the framework's
+ * existing `releasePendingPort`.
+ */
+export declare function releasePort(port: number): void;