jishushell 0.4.10 → 0.4.24-beta.2

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

@@ -1,6 +1,62 @@
 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 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>;
+/**
+ * Result of {@link allocateGatewayPort}.
+ *
+ * `skipped` is the ordered list of ports we walked past because they were
+ * already configured on another instance, already pending for a concurrent
+ * allocation, or held by a real listener on the host. When non-empty it
+ * means the default port was taken and the caller can surface a toast to
+ * the user explaining the shift.
+ */
+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
@@ -12,48 +68,45 @@ 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 function listInstances(): Record<string, any>[];
+export declare function getInstance(instanceId: string): Record<string, any> | null;
+export declare function updateInstance(instanceId: string, name?: string, description?: string): Record<string, any> | null;
+export declare function updateInstanceMeta(instanceId: string, patch: Record<string, any>): void;
+export declare function deleteInstance(instanceId: string, purgeBackups?: boolean): Promise<{
+    ok: boolean;
+    warnings?: string[];
+}>;
+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>): 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>;
 /**
- * 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.
+ * @deprecated Use `getAdapter(agentType).isChannelPluginInstalled(id, channelId)` instead.
  */
-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.
+ * @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 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, cloneOptions?: {
+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 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): {
-    ok: boolean;
-    warnings?: string[];
-};
-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 getOpenclawHome(instanceId: string): string;
 export declare function saveFeishuCredentials(instanceId: string, creds: {
     appId: string;
@@ -67,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;
@@ -80,8 +130,49 @@ 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
+ * use. Bare names ("gateway.local") and IPv4 ("127.0.0.1") contain no colon
+ * and pass through unchanged; anything with a colon is an IPv6 literal and
+ * MUST be bracketed before being concatenated with a port, otherwise
+ * `http://::1:18789/` is unparseable.
+ */
+export declare function urlHost(host: string): string;
 export declare function findInstancesSharingOpenclawHome(instanceId: string): string[];
+/**
+ * Re-pick a gateway port for an existing instance and rewrite its persisted
+ * runtime metadata (`runtime.args` and `runtime.env.OPENCLAW_GATEWAY_PORT`).
+ *
+ * Used when {@link isPortInUse} reports that the previously-assigned port has
+ * been taken by something else between create-time and start-time (e.g. a
+ * host-side openclaw started by the user, an unrelated service that grabbed
+ * the port at boot, or a Docker race on the next allocation). The Nomad job
+ * spec is rebuilt from instance metadata on every submit, so updating
+ * `instance.json` here is sufficient — no other files need patching.
+ */
+export declare function reallocateGatewayPort(instanceId: string): Promise<{
+    from: number;
+    to: number;
+    skipped: number[];
+}>;
 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;