jishushell 0.4.24 → 0.4.30

package/dist/services/connection-transactor.js

@@ -0,0 +1,341 @@
+/**
+ * connection-transactor — PUT /connections atomic 5-step flow (§10.3).
+ *
+ *   1. Validate     — resolveConnections runtime mode + per-binding checks
+ *   2. Snapshot     — capture instance.json plus the side-effect files that
+ *                     persist hooks may write through: provider.env (LLM
+ *                     proxy-upstream), mcporter.json (MCP),
+ *                     openclaw.json (LLM proxy-upstream + adapter
+ *                     applyConnectionEnv), and Hermes config.yaml / .env.
+ *                     Snapshot now covers OpenClaw (V2 + legacy),
+ *                     Hermes (V2 + legacy), and generic app-dir consumers.
+ *   3. Apply hooks  — invoke PERSIST_HOOKS for each resolved binding in
+ *                     deterministic order (default-env → search → browser
+ *                     → llm → mcp). On any failure, jump to step 5.
+ *   4. Persist      — read-modify-write instance.json: replace `connections`
+ *                     map only, keep other fields (notably the
+ *                     `connections-env` written by step 3 hooks for generic
+ *                     apps without an adapter).
+ *   5. Rollback     — reverse-order recovery from snapshots: restore each
+ *                     side-effect file (or unlink if it didn't exist
+ *                     pre-apply) before restoring instance.json.
+ *
+ * Returns either { ok: true, resolved, pending } or a structured error.
+ */
+import { existsSync, readFileSync, writeFileSync, unlinkSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { INSTANCES_DIR, APPS_DIR } from "../config.js";
+import { resolveConnections, ConnectionError } from "./connection-resolver.js";
+import { PERSIST_HOOKS, UNPERSIST_HOOKS } from "./connection-apply.js";
+import { categoryFromProviderCapability } from "./connection-resolver.js";
+import * as capabilityRegistry from "./capability-registry.js";
+import { withInstanceLock } from "../utils/instance-lock.js";
+const APPLY_ORDER = ["default", "search", "browser", "llm", "mcp"];
+export async function applyConnections(input) {
+    // Serialize against startApp/stopApp/restartApp on the same consumer
+    // instance. Without this, a concurrent stop can flip a bound provider
+    // to status:stopped between Validate (step 1) and Apply (step 3),
+    // leaving instance.json + side-effect files inconsistent.
+    return withInstanceLock(input.instance.id, () => applyConnectionsImpl(input));
+}
+async function applyConnectionsImpl(input) {
+    const { instance, spec, newConnections, saveInstanceJson, readInstanceJson, adapter } = input;
+    // ── Step 1: Validate ──────────────────────────────────────────────────
+    // Resolve the *new* connections in runtime mode so missing-required /
+    // ambiguous / invalid-binding all surface as ConnectionError before we
+    // touch any state.
+    const candidate = {
+        ...instance,
+        connections: newConnections,
+    };
+    const { resolved } = resolveConnections(spec, candidate, "runtime");
+    // ── Step 1d: validateCapabilityEndpoint per binding (§12) ─────────────
+    // Catches registry tampering / drift before any persist hook fires:
+    //   - Fresh re-resolve must match the registry entry (host/port/path)
+    //   - Provider host must be on loopback or LAN
+    //   - Protocol must be in the category whitelist
+    // Only applies to entries whose provider spec we can resolve; legacy
+    // instances without a synthesized spec degrade gracefully (skip).
+    await validateResolvedEndpoints(resolved);
+    // ── Step 2: Snapshot ──────────────────────────────────────────────────
+    // 覆盖 OpenClaw (V2+legacy)、Hermes (V2+legacy)、generic app-dir 三类
+    // consumer 的具体写入路径；详见 snapshotSideEffectFiles。
+    const snapshot = {
+        instanceJson: await readInstanceJson(instance.id),
+        files: snapshotSideEffectFiles(instance.id),
+    };
+    // ── Step 2b: Compute shrunk slots ─────────────────────────────────────
+    // PERSIST_HOOKS only sees slots that *currently* have a binding. When
+    // the user removes a binding (sets the slot to null or drops it from the
+    // map) we need to undo the durable state the prior persist hook wrote —
+    // otherwise unbinding LLM_ENDPOINT leaves x-jishushell.proxy.upstream
+    // pointing at the gone provider, etc. `shrunkSlots` enumerates exactly
+    // those: present-and-non-null in the on-disk connections, missing or
+    // null in `newConnections`.
+    const previousConnections = (snapshot.instanceJson?.connections ?? {});
+    const shrunkSlots = [];
+    for (const [slot, prior] of Object.entries(previousConnections)) {
+        if (prior == null)
+            continue; // already empty — nothing to undo
+        const next = newConnections?.[slot];
+        if (next != null)
+            continue; // still bound (or rebound) — persist hook handles it
+        const req = spec.requires?.find((r) => r.inject_as === slot);
+        const cap = req?.capability ?? "";
+        const fromToken = cap && (UNPERSIST_HOOKS[cap] ? cap : null);
+        const fromProvide = !fromToken ? categoryFromProviderCapability(cap) : null;
+        shrunkSlots.push({ slot, category: fromToken ?? fromProvide ?? "default" });
+    }
+    // ── Step 3: Apply hooks ───────────────────────────────────────────────
+    const ctx = makeApplyContext({ adapter, saveInstanceJson });
+    const appliedHooks = [];
+    try {
+        // 3a: unpersist removed slots BEFORE persisting new ones — if the user
+        //     swapped one LLM provider for another, persist's overwrite already
+        //     handles it; this loop only fires for slots that genuinely went
+        //     away, so it's safe to run first. Failures here are logged and
+        //     swallowed so a stale env var or stale upstream config doesn't
+        //     block legitimate new bindings; the rollback step still recovers
+        //     the full snapshot if a later persist throws.
+        for (const { slot, category } of shrunkSlots) {
+            const hook = UNPERSIST_HOOKS[category];
+            if (!hook)
+                continue;
+            try {
+                await hook(candidate, slot, ctx);
+            }
+            catch (e) {
+                console.warn(`[connection-transactor] unpersist ${category}/${slot} for ${instance.id} failed: ${e?.message ?? e}`);
+            }
+        }
+        for (const category of APPLY_ORDER) {
+            const hook = PERSIST_HOOKS[category];
+            if (!hook)
+                continue;
+            for (const binding of resolved) {
+                if (binding.category !== category)
+                    continue;
+                await hook(candidate, binding, ctx);
+                appliedHooks.push(binding);
+            }
+        }
+    }
+    catch (e) {
+        await rollback(input, snapshot);
+        if (e instanceof ConnectionError)
+            throw e;
+        throw new ConnectionError("CONNECTION_APPLY_FAILED", 500, `Connection apply failed: ${e?.message ?? e}`, { applied: appliedHooks.map((b) => b.slot) });
+    }
+    // ── Step 4: Persist connections ───────────────────────────────────────
+    // Read-modify-write so we don't clobber `connections-env` that step 3
+    // hooks may have written for generic apps without an adapter.
+    try {
+        await saveInstanceJson(instance.id, (cur) => ({
+            ...cur,
+            connections: newConnections,
+        }));
+    }
+    catch (e) {
+        await rollback(input, snapshot);
+        throw new ConnectionError("CONNECTION_PERSIST_FAILED", 500, `Failed to persist connections: ${e?.message ?? e}`);
+    }
+    return { resolved };
+}
+function makeApplyContext(opts) {
+    return {
+        registry: capabilityRegistry,
+        adapter: opts.adapter,
+        async writeConnectionEnv(instance, env) {
+            if (Object.keys(env).length === 0)
+                return;
+            if (opts.adapter && typeof opts.adapter.applyConnectionEnv === "function") {
+                await opts.adapter.applyConnectionEnv(instance.id, env);
+                return;
+            }
+            // Generic container app — persist into instance.json["connections-env"].
+            await opts.saveInstanceJson(instance.id, (cur) => ({
+                ...cur,
+                "connections-env": {
+                    ...(cur["connections-env"] ?? {}),
+                    ...env,
+                },
+            }));
+        },
+    };
+}
+/**
+ * Test-only export so unit tests can exercise the snapshot/restore path
+ * without spinning up the full transactor. Production code should not
+ * import these names directly.
+ */
+export const __testing__ = {
+    snapshotSideEffectFiles: (instanceId) => snapshotSideEffectFiles(instanceId),
+    applyFileSnapshots: (snapshots) => applyFileSnapshots(snapshots),
+    validateResolvedEndpoints: (resolved) => validateResolvedEndpoints(resolved),
+};
+/**
+ * Walk every resolved binding and validate each provider entry's endpoint
+ * via `validateCapabilityEndpoint` (§12). Looks the provider spec up
+ * either through the app-manager (app-installed providers) or through the
+ * legacy synthesizer (instance-backed providers). When neither lookup
+ * yields a spec, the entry is left un-validated rather than rejected —
+ * the design's protection target is registry tampering after legitimate
+ * registration, and there's no spec to compare against in the missing case.
+ */
+async function validateResolvedEndpoints(resolved) {
+    if (resolved.length === 0)
+        return;
+    const { validateCapabilityEndpoint, findProviderProvide } = await import("./capability-endpoint-validator.js");
+    const { getApp } = await import("./app/app-manager.js");
+    const { loadCapabilitySpecForLegacyInstance } = await import("./runtime/migrations.js");
+    const legacyInstanceManager = await import("./instance-manager.js");
+    for (const binding of resolved) {
+        const category = binding.category;
+        for (const entry of binding.entries) {
+            // Look up the provider spec. Two paths:
+            //   1. App-installed provider — `getApp(entry.instanceId).spec`
+            //   2. Legacy instance-backed provider — synthesize from agent template
+            let providerSpec = null;
+            let isLegacySynthetic = false;
+            const appRecord = getApp(entry.instanceId);
+            if (appRecord) {
+                providerSpec = appRecord.spec;
+            }
+            else {
+                const meta = legacyInstanceManager.getInstance(entry.instanceId);
+                providerSpec = loadCapabilitySpecForLegacyInstance(meta);
+                isLegacySynthetic = !!providerSpec;
+            }
+            if (!providerSpec) {
+                // No spec we can validate against AND no live instance to synthesize
+                // one from. The registry entry is orphaned — treat as a hard reject
+                // so a tampered registry can't sneak past the validator simply by
+                // pointing at an instanceId that no longer exists.
+                const { ConnectionError } = await import("./connection-resolver.js");
+                throw new ConnectionError("INVALID_CAPABILITY_ENDPOINT", 400, `Provider '${entry.instanceId}' has no installed app or live instance — registry entry is orphaned`, {
+                    providerInstanceId: entry.instanceId,
+                    capability: entry.capability,
+                    reason: "provider-spec-missing",
+                });
+            }
+            const provide = findProviderProvide(providerSpec, entry.capability);
+            if (!provide) {
+                if (isLegacySynthetic) {
+                    // Legacy synthetic specs are minimal (id/name/requires/provides
+                    // only). If the agent template hasn't declared this capability
+                    // there's nothing to validate against — degrade rather than
+                    // reject so we don't break working bindings on older instances.
+                    continue;
+                }
+                // App-installed provider whose spec doesn't declare this capability.
+                // Either the registry was tampered to forge a capability the spec
+                // doesn't expose, or the spec drifted out of sync. Either way the
+                // safe move is to reject — apply hooks would otherwise consume a
+                // registry-supplied host/port/protocol with no spec confirmation.
+                const { ConnectionError } = await import("./connection-resolver.js");
+                throw new ConnectionError("INVALID_CAPABILITY_ENDPOINT", 400, `Provider '${entry.instanceId}' app spec does not declare capability '${entry.capability}'`, {
+                    providerInstanceId: entry.instanceId,
+                    capability: entry.capability,
+                    reason: "capability-not-in-spec",
+                });
+            }
+            validateCapabilityEndpoint(providerSpec, entry.instanceId, provide, entry, category);
+        }
+    }
+}
+/**
+ * Capture raw bytes of files that PERSIST_HOOKS may write through. Used to
+ * roll back partial mutations when a later hook throws. Files that did not
+ * exist at snapshot time are recorded with `bytes: null` and unlinked on
+ * rollback so we don't leave behind half-written state.
+ *
+ * 覆盖三类 consumer 的所有已知写入路径：
+ *   - OpenClaw：provider.env / openclaw.json / mcporter.json（V2 + legacy）
+ *   - Hermes：agent-home/config.yaml + agent-home/.env（V2 + legacy）
+ *   - Generic app-dir：apps/<id>/instance.json
+ *
+ * 路径前缀来自 INSTANCES_DIR / APPS_DIR（均读 JISHUSHELL_HOME 环境变量），
+ * 不存在的路径记为 bytes:null，回滚时做 unlink 而非写入。
+ */
+function snapshotSideEffectFiles(instanceId) {
+    const legacyHome = join(INSTANCES_DIR, instanceId);
+    const v2Home = join(APPS_DIR, instanceId);
+    const candidates = [
+        // ── Per-instance secret bag (LLM proxy-upstream) ──
+        join(legacyHome, "provider.env"),
+        // ── OpenClaw-native config (V2 + legacy layouts) ──
+        join(legacyHome, "openclaw-home", ".openclaw", "openclaw.json"),
+        join(v2Home, "openclaw-home", ".openclaw", "openclaw.json"),
+        // ── MCP server registry consumed by the OpenClaw runtime ──
+        join(legacyHome, "openclaw-home", ".openclaw", "workspace", "config", "mcporter.json"),
+        join(v2Home, "openclaw-home", ".openclaw", "workspace", "config", "mcporter.json"),
+        // ── Hermes adapter writes (V2 layout): config.yaml + .env via
+        //    applyConnectionEnv. Without these in the snapshot, a partial MCP
+        //    apply for the search slot leaves a half-written config.yaml when
+        //    a later LLM hook fails. Path matches `resolveHermesPaths`.
+        join(v2Home, "agent-home", "config.yaml"),
+        join(v2Home, "agent-home", ".env"),
+        // ── Hermes legacy layout (pre-V2 instances) ──
+        join(legacyHome, "agent-home", "config.yaml"),
+        join(legacyHome, "agent-home", ".env"),
+        // ── Generic app-dir consumer (e.g. OpenWebUI) — instance.json
+        //    holds the persisted `connections-env` map written by the
+        //    openai-env hook for non-adapter apps. Already covered by
+        //    `snapshot.instanceJson`, but listed here as an extra safety net
+        //    so a partial direct write at apps/<id>/instance.json (outside
+        //    the saveInstanceJson code path) still rolls back. ──
+        join(v2Home, "instance.json"),
+    ];
+    const out = [];
+    for (const path of candidates) {
+        try {
+            out.push({ path, bytes: existsSync(path) ? readFileSync(path) : null });
+        }
+        catch (e) {
+            console.warn(`[connection-transactor] snapshot read failed for ${path}: ${e?.message ?? e}`);
+            out.push({ path, bytes: null });
+        }
+    }
+    return out;
+}
+/**
+ * Restore each file to its snapshotted bytes. Files whose snapshot recorded
+ * `bytes: null` (didn't exist pre-apply) are unlinked. Errors are logged
+ * per-file so a single failed restore doesn't block the rest.
+ */
+function applyFileSnapshots(snapshots) {
+    for (const file of snapshots) {
+        try {
+            if (file.bytes === null) {
+                if (existsSync(file.path))
+                    unlinkSync(file.path);
+            }
+            else {
+                try {
+                    mkdirSync(dirname(file.path), { recursive: true });
+                }
+                catch { /* dir likely exists */ }
+                writeFileSync(file.path, file.bytes);
+            }
+        }
+        catch (e) {
+            console.error(`[connection-transactor] rollback file restore failed for ${file.path}: ${e?.message ?? e}`);
+        }
+    }
+}
+async function rollback(input, snapshot) {
+    // Restore side-effect files first so their state is consistent before the
+    // instance.json `connections` map is rewound. Failures are logged but not
+    // propagated — at this point the caller has already seen a CONNECTION_*
+    // error and we want to give every later restore step a chance to run.
+    applyFileSnapshots(snapshot.files);
+    try {
+        // Single read-modify-write that overlays the snapshot on the current
+        // instance.json — atomic rollback for the single-file state.
+        await input.saveInstanceJson(input.instance.id, () => snapshot.instanceJson);
+    }
+    catch (e) {
+        console.error(`[connection-transactor] rollback failed: ${e?.message ?? e}`);
+    }
+}
+//# sourceMappingURL=connection-transactor.js.map

package/dist/services/connection-transactor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-transactor.js","sourceRoot":"","sources":["../../src/services/connection-transactor.ts"],"names":[],"mappings":"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"}

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

@@ -133,6 +133,19 @@ 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>;
+/**
+ * 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 panel proxy gets a 502.
+ *
+ * This function mirrors the logic of `getGatewayHost` 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(appId: 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

package/dist/services/instance-manager.js

@@ -133,13 +133,22 @@ const _pendingPorts = new Set();
 export function extractGatewayPort(runtime, agentType) {
     if (!runtime)
         return null;
-    // Primary: RuntimeSpec.ports[] declaration — first gateway-labeled port wins.
+    // Primary: RuntimeSpec.ports[] declaration. Prefer a port literally named
+    // "gateway" (the convention OpenClaw / Hermes templates use); otherwise
+    // fall back to the first declared port. This makes the helper work for
+    // generic V2 apps (SearXNG = "http", Open WebUI = "http", Ollama =
+    // "ollama", etc.) without forcing every template to rename its port.
     const ports = Array.isArray(runtime.ports) ? runtime.ports : [];
     for (const port of ports) {
         if (port?.name === "gateway" && Number.isInteger(port.hostPort) && port.hostPort > 0) {
             return port.hostPort;
         }
     }
+    for (const port of ports) {
+        if (Number.isInteger(port?.hostPort) && port.hostPort > 0) {
+            return port.hostPort;
+        }
+    }
     // Fall back to the adapter's legacy reader. Default agentType "openclaw".
     try {
         const adapter = getAdapter(agentType || "openclaw");
@@ -467,7 +476,8 @@ export function listInstances() {
                 // even though the backup chain still holds valid content on disk.
                 const meta = safeReadJson(metaPath, `instance:${name}`);
                 if (meta) {
-                    deduped.set(name, backfillInstanceMeta(meta));
+                    const normalised = backfillInstanceMeta(meta);
+                    deduped.set(name, normalised);
                     continue;
                 }
                 // safeReadJson → null can mean any of (a) primary missing + no
@@ -497,8 +507,10 @@ export function getInstance(instanceId) {
     // is still served from the .bak chain. Returning null on "truly gone"
     // (no primary, no backups) keeps the existing 404 behavior intact.
     const meta = safeReadJson(metaPath, `instance:${instanceId}`);
-    if (meta)
-        return backfillInstanceMeta(meta);
+    if (meta) {
+        const normalised = backfillInstanceMeta(meta);
+        return normalised;
+    }
     // safeReadJson swallows every read error internally, which is exactly
     // wrong for the EACCES case — a root-owned primary would silently
     // return null and callers would report "Instance not found" instead
@@ -876,26 +888,68 @@ export function getGatewayPort(instanceId) {
 const _gwHostCache = new Map();
 const GW_HOST_CACHE_TTL = 30000;
 export function getListeningHostForPort(port) {
-    let result = "127.0.0.1";
-    try {
-        const out = execFileSync("ss", ["-tlnH", "sport", "=", ":" + safePort(port)], {
-            encoding: "utf-8",
-            timeout: 3000,
-            stdio: ["pipe", "pipe", "pipe"],
-        });
-        for (const line of out.split("\n")) {
-            let match = line.match(/\s([\d.]+):(\d+)\s/);
-            if (!match)
-                match = line.match(/\s\[([0-9a-fA-F:]+)\]:(\d+)\s/);
-            if (match && match[2] === String(port)) {
-                const addr = match[1];
-                result = addr === "0.0.0.0" ? "127.0.0.1" : addr;
-                break;
+    // Linux: ss is universal and parses cleanly. macOS/BSD ships lsof but
+    // not ss, so without this fallback execFileSync throws ENOENT, the
+    // catch block silently returns 127.0.0.1, and any caller that fans
+    // out to the wrong host fails (the capability HTTP proxy in
+    // `proxyProvidedCapability`, the gateway-host fallback for raw_exec
+    // instances, etc.). On macOS docker driver mode the actual published
+    // host can be e.g. 10.188.0.21 via `host_network = "external"`, never
+    // loopback — so silently picking 127.0.0.1 leaves the panel fetching
+    // a host nothing is listening on.
+    const safe = safePort(port);
+    const fromSs = () => {
+        try {
+            const out = execFileSync("ss", ["-tlnH", "sport", "=", ":" + safe], {
+                encoding: "utf-8",
+                timeout: 3000,
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+            for (const line of out.split("\n")) {
+                let match = line.match(/\s([\d.]+):(\d+)\s/);
+                if (!match)
+                    match = line.match(/\s\[([0-9a-fA-F:]+)\]:(\d+)\s/);
+                if (match && match[2] === String(port))
+                    return match[1];
             }
         }
-    }
-    catch { /* fall through */ }
-    return result;
+        catch { /* ss not available or no match */ }
+        return null;
+    };
+    const fromLsof = () => {
+        try {
+            // `-FnP` keeps numeric output (no name resolution, no /etc/services).
+            // Lines beginning with `n` carry the bind address: e.g. `n10.188.0.21:8080`,
+            // `n127.0.0.1:8080`, `n[::1]:8080`, or `n*:8080` for wildcard binds.
+            const out = execFileSync("lsof", ["-nP", "-iTCP:" + safe, "-sTCP:LISTEN", "-FnP"], {
+                encoding: "utf-8",
+                timeout: 3000,
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+            for (const line of out.split("\n")) {
+                if (!line.startsWith("n"))
+                    continue;
+                const body = line.slice(1);
+                // IPv6 form: [::1]:8080 → strip brackets
+                const v6 = body.match(/^\[([0-9a-fA-F:]+)\]:(\d+)$/);
+                if (v6 && v6[2] === String(port))
+                    return v6[1];
+                const idx = body.lastIndexOf(":");
+                if (idx <= 0)
+                    continue;
+                const addr = body.slice(0, idx);
+                const portPart = body.slice(idx + 1);
+                if (portPart === String(port))
+                    return addr === "*" ? "0.0.0.0" : addr;
+            }
+        }
+        catch { /* lsof unavailable or no match */ }
+        return null;
+    };
+    const detected = (process.platform === "linux" ? fromSs() : fromLsof()) ?? fromLsof() ?? fromSs();
+    if (!detected)
+        return "127.0.0.1";
+    return detected === "0.0.0.0" ? "127.0.0.1" : detected;
 }
 function getPrimaryIpv4Address() {
     try {
@@ -941,7 +995,13 @@ export async function getGatewayHost(instanceId) {
                 }
             }
             catch { /* use fallback prefix */ }
-            const jid = `${prefix}${instanceId}`;
+            // Avoid double-prefix when the instance ID already carries the
+            // adapter prefix (e.g. apps stored as `openclaw-c1` whose Nomad
+            // job name is also `openclaw-c1`). Without this guard we'd ask
+            // Nomad for `openclaw-openclaw-c1`, get 0 allocs, and fall back
+            // to the 127.0.0.1 default — which silently breaks the gateway
+            // proxy on docker driver where the real HostIP differs.
+            const jid = instanceId.startsWith(prefix) ? instanceId : `${prefix}${instanceId}`;
             const headers = { "Content-Type": "application/json" };
             const token = getNomadToken();
             if (token)
@@ -1007,6 +1067,60 @@ export async function getGatewayHost(instanceId) {
     _gwHostCache.set(instanceId, { host: result, ts: Date.now() });
     return result;
 }
+const _appPortHostCache = new Map();
+const APP_PORT_HOST_CACHE_TTL = 30000;
+/**
+ * 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 panel proxy gets a 502.
+ *
+ * This function mirrors the logic of `getGatewayHost` but matches by port
+ * *value* rather than by the "gateway" label, making it suitable for
+ * arbitrary capability ports exposed by app tasks.
+ */
+export async function getHostForAppPort(appId, port) {
+    const cacheKey = `${appId}:${port}`;
+    const cached = _appPortHostCache.get(cacheKey);
+    if (cached && Date.now() - cached.ts < APP_PORT_HOST_CACHE_TTL)
+        return cached.host;
+    let result = "127.0.0.1";
+    try {
+        const { getNomadDriver, getNomadAddr, getNomadToken } = await import("../config.js");
+        if (getNomadDriver() === "docker") {
+            const headers = { "Content-Type": "application/json" };
+            const token = getNomadToken();
+            if (token)
+                headers["X-Nomad-Token"] = token;
+            const resp = await fetch(`${getNomadAddr()}/v1/job/${encodeURIComponent(appId)}/allocations`, { headers, signal: AbortSignal.timeout(5000) });
+            if (resp.ok) {
+                const allocs = await resp.json();
+                const alloc = allocs.find((a) => a.ClientStatus === "running")
+                    ?? allocs.find((a) => a.ClientStatus === "pending");
+                if (alloc) {
+                    const detail = await fetch(`${getNomadAddr()}/v1/allocation/${encodeURIComponent(alloc.ID)}`, { headers, signal: AbortSignal.timeout(5000) });
+                    if (detail.ok) {
+                        const d = await detail.json();
+                        // Bridge / host-network mode: ports listed under Shared.Ports
+                        const sharedPorts = d?.AllocatedResources?.Shared?.Ports ?? [];
+                        const matched = sharedPorts.find((p) => p.Value === port || p.To === port);
+                        if (matched?.HostIP && matched.HostIP !== "0.0.0.0") {
+                            result = matched.HostIP;
+                        }
+                    }
+                }
+            }
+        }
+    }
+    catch { /* fall through to ss-based detection */ }
+    if (result === "127.0.0.1") {
+        result = getListeningHostForPort(port);
+    }
+    _appPortHostCache.set(cacheKey, { host: result, ts: Date.now() });
+    return result;
+}
 /**
  * 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