jishushell 0.6.5 → 0.6.18

package/dist/services/instances/manager.d.ts

@@ -0,0 +1,231 @@
+type ConfigChangeListener = (instanceId: string) => void;
+export declare function onConfigChange(listener: ConfigChangeListener): () => void;
+/**
+ * Fire the config-change listener fan-out. Integrations 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;
+export declare const INSTANCE_NEEDS_MIGRATION_CODE = "INSTANCE_NEEDS_MIGRATION";
+export declare class CanonicalRuntimePortRequiredError extends Error {
+    code: string;
+    statusCode: number;
+    instanceId: string;
+    constructor(instanceId: string);
+}
+export declare function isCanonicalRuntimePortRequiredError(error: unknown): error is CanonicalRuntimePortRequiredError;
+/**
+ * Read the primary externally reachable host port out of a persisted runtime record.
+ *
+ * Runtime hot paths only trust canonical `runtime.ports[].hostPort`.
+ * Legacy env/args fallbacks are repair-only readers owned by the migrator or
+ * integration repair code and must not be consulted here.
+ */
+export declare function extractPrimaryHostPort(runtime: Record<string, any> | undefined, _integrationKind?: 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
+ * loopback-only service would then be invisible to JishuShell, so port
+ * allocation could assign the same host port to a new instance and the
+ * workload 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 allocateHostPort}.
+ *
+ * The returned object models the canonical reserve / commit / release
+ * allocator lifecycle. The caller MUST call exactly one of:
+ *   - `commit()` after the chosen `port` is durably persisted into the
+ *     instance's `runtime.ports[].hostPort` (success path).
+ *   - `release()` on every failure path before the durable write succeeds.
+ *
+ * `skipped` is the ordered list of ports the allocator 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 seed port was taken and the caller can surface a
+ * toast to the user explaining the shift.
+ */
+export type HostPortAllocation = {
+    instanceId: string;
+    port: number;
+    skipped: number[];
+    commit: () => number;
+    release: () => void;
+};
+/**
+ * Kind-agnostic host-port allocator (canonical port model).
+ *
+ * Walks upward from `defaultPort` until a free host port is found that is
+ * neither held by any canonical runtime port on an existing instance, nor by
+ * a pending reservation, nor by any listener on the host. The historical
+ * Callers may use it for every external runtime port.
+ *
+ * Concurrent callers coordinate through `_pendingPorts`: each candidate port
+ * is reserved BEFORE the async `isPortInUse` probe so concurrent calls cannot
+ * select the same port during the await gap. The returned allocation owns
+ * the lifecycle from there: the caller
+ * MUST call `commit()` once the chosen port is durably persisted, or
+ * `release()` on any failure path. Calling neither leaks the reservation
+ * slot until process restart.
+ */
+export declare function allocateHostPort(instanceId: string, defaultPort: number, replacingHostPort?: number, options?: {
+    ignoreIncompleteCanonicalInstanceIds?: ReadonlySet<string>;
+}): Promise<HostPortAllocation>;
+/**
+ * Legacy by-port release helper.
+ *
+ * Production code MUST use the `commit()` / `release()` methods on the
+ * {@link HostPortAllocation} returned from {@link allocateHostPort};
+ * those make the success-vs-failure split explicit, which is the Step 2
+ * canonical contract. This function is kept only as a test/facade compatibility
+ * export for older call sites that still talk to the allocator by port number.
+ * Normal production code should not need it.
+ */
+export declare function releasePendingPort(port: number): void;
+/**
+ * When jishushell runs as root (e.g. systemd service), returns the actual
+ * non-root user that should own instance files and run workload processes.
+ * Returns null when not running as root or when no suitable non-root user is found.
+ */
+export declare function resolveServiceUser(): {
+    username: string;
+    uid: number;
+    gid: number;
+} | null;
+/**
+ * When running as root, chown a file (and its .bak) to the service user so the
+ * workload 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;
+/**
+ * Toggle the opt-in "privileged" (native-install-like) profile on an
+ * OpenClaw instance's docker task. Default (false / absent) keeps the
+ * hardened container (cap_drop=ALL, no-new-privileges, read-only rootfs).
+ * When enabled, `OpenClawAdapter.buildNomadTask` relaxes those so the agent
+ * has native-install-like permissions. Persisted in `instance.json` runtime
+ * so it survives restarts and is reapplied on every Nomad job submit.
+ * Returns false when the instance does not exist. Caller must restart the
+ * instance for the change to take effect.
+ */
+export declare function setInstancePrivileged(instanceId: string, privileged: boolean): boolean;
+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>;
+/** Dispatch wrapper for `AppIntegration.isChannelPluginInstalled`. */
+export declare function isChannelPluginInstalled(instanceId: string, channelId: string): boolean;
+export declare function saveFeishuCredentials(instanceId: string, creds: {
+    appId: string;
+    appSecret: string;
+    domain: string;
+    channelKey?: string;
+}): void;
+export declare function saveWeixinCredentials(instanceId: string, creds: {
+    accountId: string;
+    token: string;
+    baseUrl: string;
+    userId: string;
+}): void;
+export declare function getWeixinAccounts(instanceId: string): Array<{
+    accountId: string;
+    userId?: string;
+    savedAt?: string;
+}>;
+export declare function getInstanceRuntime(instanceId: string): Record<string, any>;
+export declare function getRuntimeEnvFiles(instanceId: string): string[];
+export declare function getPrimaryHostPort(instanceId: string): number;
+export declare function getListeningHostForPort(port: number): string;
+export declare function getPrimaryIpv4Address(): string;
+export declare function getAdvertisedHostForPort(port: number): string;
+export declare function getConnectHostForPort(port: number): string;
+export declare function getPrimaryHostForInstance(instanceId: string): Promise<string>;
+/**
+ * Resolve the host IP for a specific port belonging to an app's Nomad job.
+ *
+ * On macOS with Colima + docker driver the container port is bound *inside*
+ * the VM, not on the host.  `ss` (or `netstat`) run on the macOS host see
+ * nothing on that port, so `getListeningHostForPort` returns 127.0.0.1 and
+ * the core proxy gets a 502.
+ *
+ * This function mirrors the logic of `getPrimaryHostForInstance` but matches by port
+ * *value* rather than by the "gateway" label, making it suitable for
+ * arbitrary capability ports exposed by app tasks.
+ */
+export declare function getHostForAppPort(instanceId: string, port: number): 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:18095/` is unparseable.
+ */
+export declare function urlHost(host: string): string;
+export declare function findInstancesSharingIntegrationHome(instanceId: string): string[];
+/**
+ * Re-pick the primary host port for an existing instance and rewrite only the
+ * persisted host-side mapping in `runtime.ports[].hostPort`.
+ *
+ * Used when {@link isPortInUse} reports that the previously-assigned
+ * `hostPort` has been taken by something else between create-time and
+ * start-time (e.g. 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, and the in-container process
+ * listener keeps the same `containerPort`.
+ *
+ * Lifecycle: this is the canonical Step 2 reserve / commit / release flow:
+ *   - `allocateHostPort(...)` reserves a candidate hostPort.
+ *   - On successful durable persist (`safeWriteJson` of `instance.json`),
+ *     `alloc.commit()` retires the reservation; durable ownership has taken
+ *     over via `runtime.ports[].hostPort`.
+ *   - On any thrown failure, `alloc.release()` frees the slot so concurrent
+ *     / retried reallocations can reuse the port.
+ *
+ * Domain note: this function intentionally only rewrites `hostPort`.
+ * Integration-specific `reallocateRuntimePort` implementations and the
+ * generic AppSpec fallback must both preserve the workload's
+ * `containerPort`.
+ *
+ * Scope note: this is a primary-port helper for single-gateway integration
+ * runtimes and legacy compatibility paths. Generic multi-port AppSpec
+ * preflight must not use it as a full conflict check; it should iterate every
+ * external `runtime.ports[]` entry and call `reallocateRuntimeHostPort(...)`
+ * for the specific conflicting task/port.
+ */
+export declare function reallocatePrimaryHostPort(instanceId: string): Promise<{
+    from: number;
+    to: number;
+    skipped: number[];
+}>;
+export declare function reallocateRuntimeHostPort(instanceId: string, portRef: {
+    taskName?: string;
+    name: string;
+}): Promise<{
+    from: number;
+    to: number;
+    skipped: number[];
+}>;
+export declare function findInstancesSharingPrimaryHostPort(instanceId: string): string[];
+export declare function getRuntimeEnv(instanceId: string): Record<string, string>;
+export { instanceDir as getInstanceDir };