jishushell 0.4.24 → 0.4.30

package/dist/services/app/provide-resolver.js

@@ -0,0 +1,112 @@
+import { getAdvertisedHostForPort, getGatewayPort, getInstanceRuntime, } from "../instance-manager.js";
+function isServiceTask(task) {
+    return (task.role ?? "service") === "service";
+}
+function pickTask(spec, provide) {
+    if (typeof provide.task === "string" && provide.task) {
+        return spec.tasks?.find((t) => t.name === provide.task);
+    }
+    return spec.tasks?.find(isServiceTask);
+}
+function hostPortOf(p) {
+    // host_port wins when defined (container yaml with host:container mapping);
+    // otherwise plain `port` is the host port too (process-mode tasks).
+    if (typeof p.host_port === "number" && p.host_port > 0)
+        return p.host_port;
+    if (typeof p.port === "number" && p.port > 0)
+        return p.port;
+    return undefined;
+}
+function pickPort(task, provide) {
+    const ports = Array.isArray(task.ports) ? task.ports : [];
+    if (ports.length === 0)
+        return undefined;
+    // 1. Explicit portName disambiguation (multi-port-same-number rare case).
+    const portName = provide.portName;
+    if (typeof portName === "string" && portName) {
+        const named = ports.find((p) => p.name === portName);
+        return named ? hostPortOf(named) : undefined;
+    }
+    // 2. Match by provide.port number against task port's host-side number.
+    if (typeof provide.port === "number") {
+        const matched = ports.find((p) => hostPortOf(p) === provide.port);
+        if (matched)
+            return hostPortOf(matched);
+        // provide.port specified but no matching task port — caller declared
+        // a port that does not exist on this task. Honor declared value as a
+        // best-effort fallback so registry stays populated; the entry will
+        // fail health probing later if the port isn't actually listening.
+        return provide.port;
+    }
+    // 3. No provide.port — first port on the chosen task.
+    return hostPortOf(ports[0]);
+}
+/**
+ * Try to read the actual allocated host port from the instance's runtime
+ * spec. Currently only the gateway port is reliably tracked per-instance
+ * (see `extractGatewayPort` in instance-manager); other ports fall back
+ * to the spec value.
+ *
+ * For multi-port instances, runtime.ports[] is consulted by name match.
+ */
+function readRuntimePort(instanceId, taskName, portName, declaredHostPort) {
+    const runtime = getInstanceRuntime(instanceId);
+    if (!runtime)
+        return declaredHostPort;
+    // First: gateway port via the well-defined helper. Only useful when the
+    // requested port is the gateway port (named "gateway" or matching the
+    // declared spec port that the gateway helper resolves).
+    if (portName === "gateway" || taskName === "gateway") {
+        const gw = getGatewayPort(instanceId);
+        if (gw > 0)
+            return gw;
+    }
+    // Second: scan runtime.ports[] by name when present (RuntimeSpec shape).
+    const runtimePorts = Array.isArray(runtime.ports) ? runtime.ports : [];
+    if (portName) {
+        const named = runtimePorts.find((p) => p?.name === portName);
+        if (named && Number.isInteger(named.hostPort) && named.hostPort > 0) {
+            return named.hostPort;
+        }
+    }
+    // Match by declared host port — runtime allocation may have reassigned
+    // it; the runtime entry name should still match the port spec name.
+    if (typeof declaredHostPort === "number") {
+        const matched = runtimePorts.find((p) => Number.isInteger(p?.hostPort) && p.hostPort > 0);
+        if (matched && runtimePorts.length === 1)
+            return matched.hostPort;
+    }
+    return declaredHostPort;
+}
+/**
+ * Resolve the provide's actual endpoint for a given instance.
+ *
+ * - Returns null for url-only provides (cannot enter capability registry,
+ *   §5.1 boundary).
+ * - Returns null when no port can be determined from spec or runtime.
+ */
+export function resolveProvideEndpoint(instanceId, spec, provide) {
+    // url-only provide — out of capability registry scope (see §5.1).
+    if (typeof provide.url === "string" && provide.url.trim())
+        return null;
+    const task = pickTask(spec, provide);
+    if (!task)
+        return null;
+    const declared = pickPort(task, provide);
+    if (typeof declared !== "number" || declared <= 0)
+        return null;
+    const portName = provide.portName ?? findPortName(task, declared);
+    const actual = readRuntimePort(instanceId, task.name, portName, declared) ?? declared;
+    const host = getAdvertisedHostForPort(actual);
+    return {
+        host,
+        hostPort: actual,
+        ...(provide.path ? { path: provide.path } : {}),
+    };
+}
+function findPortName(task, hostPort) {
+    const ports = Array.isArray(task.ports) ? task.ports : [];
+    const matched = ports.find((p) => hostPortOf(p) === hostPort);
+    return matched?.name;
+}
+//# sourceMappingURL=provide-resolver.js.map

package/dist/services/app/provide-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provide-resolver.js","sourceRoot":"","sources":["../../../src/services/app/provide-resolver.ts"],"names":[],"mappings":"AAgBA,OAAO,EACL,wBAAwB,EACxB,cAAc,EACd,kBAAkB,GACnB,MAAM,wBAAwB,CAAC;AAQhC,SAAS,aAAa,CAAC,IAAa;IAClC,OAAO,CAAC,IAAI,CAAC,IAAI,IAAI,SAAS,CAAC,KAAK,SAAS,CAAC;AAChD,CAAC;AAED,SAAS,QAAQ,CAAC,IAAa,EAAE,OAAmB;IAClD,IAAI,OAAO,OAAO,CAAC,IAAI,KAAK,QAAQ,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;QACrD,OAAO,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC;AACzC,CAAC;AAED,SAAS,UAAU,CAAC,CAAc;IAChC,4EAA4E;IAC5E,oEAAoE;IACpE,IAAI,OAAO,CAAC,CAAC,SAAS,KAAK,QAAQ,IAAI,CAAC,CAAC,SAAS,GAAG,CAAC;QAAE,OAAO,CAAC,CAAC,SAAS,CAAC;IAC3E,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,CAAC,IAAI,GAAG,CAAC;QAAE,OAAO,CAAC,CAAC,IAAI,CAAC;IAC5D,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,QAAQ,CAAC,IAAa,EAAE,OAAmB;IAClD,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IAC1D,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAEzC,0EAA0E;IAC1E,MAAM,QAAQ,GAAI,OAAe,CAAC,QAAQ,CAAC;IAC3C,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,EAAE,CAAC;QAC7C,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC;QACrD,OAAO,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC/C,CAAC;IAED,wEAAwE;IACxE,IAAI,OAAO,OAAO,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QACrC,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;QAClE,IAAI,OAAO;YAAE,OAAO,UAAU,CAAC,OAAO,CAAC,CAAC;QACxC,qEAAqE;QACrE,qEAAqE;QACrE,mEAAmE;QACnE,kEAAkE;QAClE,OAAO,OAAO,CAAC,IAAI,CAAC;IACtB,CAAC;IAED,sDAAsD;IACtD,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AAC9B,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,eAAe,CACtB,UAAkB,EAClB,QAA4B,EAC5B,QAA4B,EAC5B,gBAAoC;IAEpC,MAAM,OAAO,GAAG,kBAAkB,CAAC,UAAU,CAAC,CAAC;IAC/C,IAAI,CAAC,OAAO;QAAE,OAAO,gBAAgB,CAAC;IAEtC,wEAAwE;IACxE,sEAAsE;IACtE,wDAAwD;IACxD,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QACrD,MAAM,EAAE,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC;QACtC,IAAI,EAAE,GAAG,CAAC;YAAE,OAAO,EAAE,CAAC;IACxB,CAAC;IAED,yEAAyE;IACzE,MAAM,YAAY,GAAU,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IAC9E,IAAI,QAAQ,EAAE,CAAC;QACb,MAAM,KAAK,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,KAAK,QAAQ,CAAC,CAAC;QAC7D,IAAI,KAAK,IAAI,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,KAAK,CAAC,QAAQ,GAAG,CAAC,EAAE,CAAC;YACpE,OAAO,KAAK,CAAC,QAAQ,CAAC;QACxB,CAAC;IACH,CAAC;IACD,uEAAuE;IACvE,oEAAoE;IACpE,IAAI,OAAO,gBAAgB,KAAK,QAAQ,EAAE,CAAC;QACzC,MAAM,OAAO,GAAG,YAAY,CAAC,IAAI,CAC/B,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC,QAAQ,GAAG,CAAC,CACvD,CAAC;QACF,IAAI,OAAO,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,OAAO,CAAC,QAAQ,CAAC;IACpE,CAAC;IACD,OAAO,gBAAgB,CAAC;AAC1B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CACpC,UAAkB,EAClB,IAAa,EACb,OAAmB;IAEnB,kEAAkE;IAClE,IAAI,OAAO,OAAO,CAAC,GAAG,KAAK,QAAQ,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE;QAAE,OAAO,IAAI,CAAC;IAEvE,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACrC,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IAEvB,MAAM,QAAQ,GAAG,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACzC,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAE/D,MAAM,QAAQ,GAAI,OAAe,CAAC,QAAQ,IAAI,YAAY,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAC3E,MAAM,MAAM,GAAG,eAAe,CAAC,UAAU,EAAE,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,CAAC,IAAI,QAAQ,CAAC;IAEtF,MAAM,IAAI,GAAG,wBAAwB,CAAC,MAAM,CAAC,CAAC;IAC9C,OAAO;QACL,IAAI;QACJ,QAAQ,EAAE,MAAM;QAChB,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAChD,CAAC;AACJ,CAAC;AAED,SAAS,YAAY,CAAC,IAAa,EAAE,QAAgB;IACnD,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IAC1D,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC;IAC9D,OAAO,OAAO,EAAE,IAAI,CAAC;AACvB,CAAC"}

package/dist/services/capability-endpoint-validator.d.ts

@@ -0,0 +1,41 @@
+/**
+ * §12 of the app-interconnect design — `validateCapabilityEndpoint`.
+ *
+ * Runs in the transactor's Validate step (§10.3 step 1d), once per resolved
+ * binding, before any persist hook touches durable state. Catches three
+ * classes of registry tampering / drift that the LLM-proxy SSRF guard
+ * (`validateUpstreamUrl`) does NOT cover for non-`proxy-upstream` paths:
+ *
+ *   1. **Fresh re-resolve mismatch**: re-resolve the provider's endpoint
+ *      from its spec, compare host/port/path against the registry entry.
+ *      If they diverge, the registry was tampered after registration.
+ *   2. **Out-of-LAN host**: provider must be on loopback or a private
+ *      LAN range (reuses `isPrivateHost` from llm-proxy/ssrf).
+ *   3. **Protocol whitelist by category**: each category locks the set
+ *      of allowed protocols (see PROTOCOL_WHITELIST below).
+ *
+ * Failure throws `ConnectionError("INVALID_CAPABILITY_ENDPOINT", 400)`.
+ *
+ * **All five inputs are provider-side**, never consumer-side. Callers
+ * looking up the provider spec/provide from the registry entry are
+ * responsible for the lookup; this module only validates.
+ *
+ * Capabilities matching `*-terminal` are skipped entirely — terminals
+ * have no network endpoint to validate.
+ */
+import type { AppSpec, AppProvide } from "../types.js";
+import type { CapabilityEntry } from "./capability-registry.js";
+export type EndpointCategory = "llm" | "search" | "browser" | "mcp" | "default";
+/**
+ * Validate that `registryEntry` is safe to apply for the given category.
+ * Throws `INVALID_CAPABILITY_ENDPOINT (400)` on any failure; returns void
+ * on success.
+ */
+export declare function validateCapabilityEndpoint(providerSpec: AppSpec, providerInstanceId: string, providerProvide: AppProvide, registryEntry: CapabilityEntry, category: EndpointCategory): void;
+/**
+ * Look up the `providerProvide` block from a registry entry, by matching
+ * `entry.capability` against `spec.provides[].capability`. Returns
+ * `undefined` if no match — caller decides whether that's a hard error or
+ * a soft "skip validation" path (e.g. legacy instances with synthesized specs).
+ */
+export declare function findProviderProvide(spec: AppSpec, capability: string): AppProvide | undefined;

package/dist/services/capability-endpoint-validator.js

@@ -0,0 +1,104 @@
+import { resolveProvideEndpoint } from "./app/provide-resolver.js";
+import { isPrivateHost } from "./llm-proxy/ssrf.js";
+import { ConnectionError } from "./connection-resolver.js";
+const PROTOCOL_WHITELIST = {
+    llm: new Set(["http", "https"]),
+    search: new Set(["http", "https"]),
+    browser: new Set(["ws", "wss", "http", "https"]),
+    mcp: new Set(["http", "https", "ws", "sse"]),
+    default: new Set(["http", "https", "ws", "wss", "tcp"]),
+};
+/**
+ * Validate that `registryEntry` is safe to apply for the given category.
+ * Throws `INVALID_CAPABILITY_ENDPOINT (400)` on any failure; returns void
+ * on success.
+ */
+export function validateCapabilityEndpoint(providerSpec, providerInstanceId, providerProvide, registryEntry, category) {
+    const cap = providerProvide.capability ?? registryEntry.capability;
+    // *-terminal capabilities have no reachable endpoint; skip entirely.
+    if (/-terminal$/.test(cap))
+        return;
+    // 1. Fresh re-resolve — registryEntry must match what the provider's
+    //    spec currently resolves to. If anything has been tampered (host,
+    //    port, path) the resolved address in apply hooks would already be
+    //    pointing somewhere unexpected; reject before write.
+    //
+    //    Legacy carve-out: `loadCapabilitySpecForLegacyInstance` returns a
+    //    synthetic spec with `tasks: []` (it strips runtime to prevent
+    //    nomad-job reconstruction from drifting from the live instance, see
+    //    runtime/migrations.ts). For those specs `resolveProvideEndpoint`
+    //    cannot produce an endpoint at all; we degrade gracefully — drop
+    //    the fresh-resolve check, keep the host / protocol / visibility
+    //    checks below. Registry tampering on legacy instances is still
+    //    bounded by host-must-be-LAN + protocol whitelist.
+    const hasTasks = Array.isArray(providerSpec.tasks) && providerSpec.tasks.length > 0;
+    if (hasTasks) {
+        const fresh = resolveProvideEndpoint(providerInstanceId, providerSpec, providerProvide);
+        if (!fresh) {
+            throw new ConnectionError("INVALID_CAPABILITY_ENDPOINT", 400, `Cannot re-resolve endpoint for provider '${providerInstanceId}' capability '${cap}'`, { providerInstanceId, capability: cap, reason: "fresh-resolve-failed" });
+        }
+        const freshPath = fresh.path ?? "";
+        const registryPath = registryEntry.path ?? "";
+        if (fresh.host !== registryEntry.host ||
+            fresh.hostPort !== registryEntry.hostPort ||
+            freshPath !== registryPath) {
+            throw new ConnectionError("INVALID_CAPABILITY_ENDPOINT", 400, `Registry endpoint for provider '${providerInstanceId}' capability '${cap}' does not match a fresh resolve from spec`, {
+                providerInstanceId,
+                capability: cap,
+                reason: "fresh-resolve-mismatch",
+                registry: { host: registryEntry.host, hostPort: registryEntry.hostPort, path: registryPath },
+                fresh: { host: fresh.host, hostPort: fresh.hostPort, path: freshPath },
+            });
+        }
+    }
+    // 1b. Spec vs registry protocol 一致性检查。
+    //     spec 侧 protocol 来自 providerProvide.protocol（两种 spec 都带该字段），
+    //     registry 侧来自 registryEntry.protocol。若两者不一致说明 registry 在注册
+    //     后被篡改（或写入时出错），consumer 端将被导向错误协议，需要拒绝。
+    //     legacy synthetic spec（hasTasks=false）同样执行该检查，因为 provide.protocol
+    //     字段存在于 provide 块上，而非 task 上。
+    //
+    //     trim()+toLowerCase() 必须与 `app-manager.normalizeProvideProtocol` 完全
+    //     对齐，否则 yaml 里 `protocol: " http "` 之类的写法会让 spec 侧拿到带空格
+    //     的值，而 registerCapabilities 已经把 registry 侧 normalize 成 "http"，
+    //     两者比对会误判为篡改。
+    const specProtocol = (providerProvide.protocol ?? "http").trim().toLowerCase();
+    const registryProtocol = String(registryEntry.protocol ?? "").trim().toLowerCase();
+    if (specProtocol !== registryProtocol) {
+        throw new ConnectionError("INVALID_CAPABILITY_ENDPOINT", 400, `Registry protocol '${registryProtocol}' for provider '${providerInstanceId}' capability '${cap}' does not match spec protocol '${specProtocol}'`, {
+            providerInstanceId,
+            capability: cap,
+            reason: "protocol-spec-mismatch",
+            details: { specProtocol, registryProtocol },
+        });
+    }
+    // 2. Host must be loopback or LAN. We're only ever supposed to bind
+    //    Connections-tab providers to local apps; a public hostname here is
+    //    either a misconfiguration or active SSRF.
+    if (!isPrivateHost(registryEntry.host)) {
+        throw new ConnectionError("INVALID_CAPABILITY_ENDPOINT", 400, `Provider host '${registryEntry.host}' is not in the loopback/LAN range`, { providerInstanceId, capability: cap, reason: "host-not-private", host: registryEntry.host });
+    }
+    // 3. Protocol must be in the category-specific whitelist.
+    const allowed = PROTOCOL_WHITELIST[category] ?? PROTOCOL_WHITELIST.default;
+    const protocol = String(registryEntry.protocol ?? "").toLowerCase();
+    if (!protocol || !allowed.has(protocol)) {
+        throw new ConnectionError("INVALID_CAPABILITY_ENDPOINT", 400, `Protocol '${protocol || "(empty)"}' is not allowed for category '${category}'`, {
+            providerInstanceId,
+            capability: cap,
+            reason: "protocol-not-whitelisted",
+            protocol,
+            category,
+            allowed: Array.from(allowed),
+        });
+    }
+}
+/**
+ * Look up the `providerProvide` block from a registry entry, by matching
+ * `entry.capability` against `spec.provides[].capability`. Returns
+ * `undefined` if no match — caller decides whether that's a hard error or
+ * a soft "skip validation" path (e.g. legacy instances with synthesized specs).
+ */
+export function findProviderProvide(spec, capability) {
+    return spec.provides?.find((p) => p.capability === capability);
+}
+//# sourceMappingURL=capability-endpoint-validator.js.map

package/dist/services/capability-endpoint-validator.js.map

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

package/dist/services/capability-health.d.ts

@@ -0,0 +1,16 @@
+import type { CapabilityEntry, CapabilityStatus } from "./capability-registry.js";
+/**
+ * Probe an entry. Cached for 30s per (instanceId, capability) pair.
+ */
+export declare function probe(entry: CapabilityEntry): Promise<CapabilityStatus>;
+/**
+ * Force-refresh the cached probe for a specific entry. Called after
+ * provider start/stop transitions so the UI sees the new status without
+ * waiting for the 30s TTL.
+ */
+export declare function invalidate(entry: CapabilityEntry): void;
+/**
+ * Drop the entire probe cache — used during tests and when registry is
+ * rebuilt at startup.
+ */
+export declare function clearCache(): void;

package/dist/services/capability-health.js

@@ -0,0 +1,121 @@
+/**
+ * Capability health prober (§5.6).
+ *
+ * Probes a registered capability endpoint to confirm the provider is
+ * actually listening, before the resolver hands its address to consumers
+ * via Connections binding. Prevents stale registry entries from breaking
+ * downstream apps (e.g. an Ollama instance that was registered then died
+ * — without health probing the consumer would dial a closed port).
+ *
+ * Probe strategy is derived from the entry's protocol when no explicit
+ * `health` spec is provided on the provide:
+ *   - http/https → HEAD on `path || "/"` with 5s timeout
+ *   - ws/wss     → TCP connect on hostPort
+ *   - tcp        → TCP connect on hostPort
+ *   - terminal/  → no-op probe (always "unknown" → status not changed)
+ *     other     → no-op probe
+ *
+ * Results are cached for 30s per capability+instance to avoid hammering
+ * providers on every Connections UI refresh.
+ */
+import { request as httpRequest } from "http";
+import { request as httpsRequest } from "https";
+import { connect as tcpConnect } from "net";
+const PROBE_TIMEOUT_MS = 5_000;
+const CACHE_TTL_MS = 30_000;
+const _cache = new Map();
+function cacheKey(entry) {
+    return `${entry.instanceId}::${entry.capability}`;
+}
+async function probeHttp(entry) {
+    return new Promise((resolve) => {
+        const isHttps = entry.protocol === "https";
+        const lib = isHttps ? httpsRequest : httpRequest;
+        const path = entry.path && entry.path !== "/" ? entry.path : "/";
+        const req = lib({
+            host: entry.host,
+            port: entry.hostPort,
+            method: "HEAD",
+            path,
+            timeout: PROBE_TIMEOUT_MS,
+        }, (res) => {
+            // Any HTTP response (even 404) means the provider is listening.
+            res.resume();
+            // 5xx responses suggest the provider is up but unhealthy. Treat
+            // them as "running" anyway — the failure mode of "consumer can't
+            // talk to provider" surfaces through the consumer's own error
+            // path; the registry only certifies the port is open.
+            resolve("running");
+        });
+        req.on("timeout", () => {
+            req.destroy();
+            resolve("stopped");
+        });
+        req.on("error", () => resolve("stopped"));
+        req.end();
+    });
+}
+async function probeTcp(entry) {
+    return new Promise((resolve) => {
+        const sock = tcpConnect({ host: entry.host, port: entry.hostPort });
+        let resolved = false;
+        const finish = (status) => {
+            if (resolved)
+                return;
+            resolved = true;
+            try {
+                sock.destroy();
+            }
+            catch { /* noop */ }
+            resolve(status);
+        };
+        sock.setTimeout(PROBE_TIMEOUT_MS);
+        sock.once("connect", () => finish("running"));
+        sock.once("timeout", () => finish("stopped"));
+        sock.once("error", () => finish("stopped"));
+    });
+}
+/**
+ * Probe an entry. Cached for 30s per (instanceId, capability) pair.
+ */
+export async function probe(entry) {
+    const key = cacheKey(entry);
+    const hit = _cache.get(key);
+    if (hit && Date.now() - hit.ts < CACHE_TTL_MS)
+        return hit.status;
+    let status = "unknown";
+    const protocol = (entry.protocol || "").toLowerCase();
+    switch (protocol) {
+        case "http":
+        case "https":
+            status = await probeHttp(entry);
+            break;
+        case "tcp":
+        case "ws":
+        case "wss":
+            status = await probeTcp(entry);
+            break;
+        default:
+            // terminal / mcp / sse / unknown — no portable probe; trust registry.
+            status = entry.status;
+            break;
+    }
+    _cache.set(key, { status, ts: Date.now() });
+    return status;
+}
+/**
+ * Force-refresh the cached probe for a specific entry. Called after
+ * provider start/stop transitions so the UI sees the new status without
+ * waiting for the 30s TTL.
+ */
+export function invalidate(entry) {
+    _cache.delete(cacheKey(entry));
+}
+/**
+ * Drop the entire probe cache — used during tests and when registry is
+ * rebuilt at startup.
+ */
+export function clearCache() {
+    _cache.clear();
+}
+//# sourceMappingURL=capability-health.js.map

package/dist/services/capability-health.js.map

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

package/dist/services/capability-registry.d.ts

@@ -0,0 +1,106 @@
+export type CapabilityStatus = "running" | "stopped" | "unknown";
+/**
+ * Single provider entry in the registry. v3.4.x extends the legacy 5-field
+ * shape (instanceId / hostPort / address / path / registered_at) to ~10
+ * fields so the Connections UI can render rich metadata without re-querying
+ * each provider's spec.
+ */
+export interface CapabilityEntry {
+    instanceId: string;
+    name?: string;
+    capability: string;
+    host: string;
+    hostPort: number;
+    path?: string;
+    address: string;
+    protocol: string;
+    visibility?: "external" | "internal" | string;
+    status: CapabilityStatus;
+    lastSeenRunningAt?: string;
+    registeredAt: string;
+    /**
+     * §17 (PR 8) — when present, MCP-binding adapters expose this
+     * capability through the jishushell MCP firewall using the schema
+     * here, instead of letting the upstream MCP package's `tools/list`
+     * descriptions reach the LLM. Copied verbatim from the producing
+     * spec's `provides[].tool_schema` at registerProvider time.
+     */
+    toolSchema?: import("../types.js").ToolSchema;
+    /**
+     * §6 (PR B) — auth config for consumers of this capability. Copied
+     * verbatim from the producing spec's `provides[].auth` at registerProvider
+     * time. Absent = no auth required.
+     */
+    auth?: import("../types.js").AppProvideAuth;
+}
+/**
+ * Legacy shape kept side-by-side during PR 1-3 transition.
+ */
+interface LegacyCapabilityEntry {
+    instanceId: string;
+    hostPort: number;
+    address: string;
+    path?: string;
+    registered_at: string;
+}
+interface CapabilityRegistryFile {
+    /**
+     * v3.4.x new shape: a capability may have multiple providers (e.g. two
+     * Ollama instances). UI lets users pick among candidates.
+     */
+    providersByCapability?: Record<string, CapabilityEntry[]>;
+    /**
+     * Legacy shape: single entry per capability, last-writer-wins. PR 1 keeps
+     * it dual-written; PR 3 removes it.
+     */
+    capabilities?: Record<string, LegacyCapabilityEntry>;
+}
+/**
+ * Read the registry, migrating any legacy-only entries on the fly. Always
+ * returns both shapes populated — the compat layer relies on this.
+ */
+export declare function readRegistry(): CapabilityRegistryFile;
+/**
+ * Compat-view accessor: returns the **first** provider for a capability in
+ * legacy 5-field shape. PR 3 sub-step 3f deletes this function once all
+ * call sites are switched to `getProviderEntry` / `listProviders`.
+ */
+export declare function getCapabilityEntry(capability: string): LegacyCapabilityEntry | undefined;
+/**
+ * List all providers for a capability. Used by Connections UI candidate
+ * dropdown and PR 3 multi-candidate resolution.
+ */
+export declare function listProviders(capability: string): CapabilityEntry[];
+/**
+ * Locate a specific provider by composite key. The `(instanceId, capability)`
+ * pair is required (v3.1 §5.3) because one instance may publish multiple
+ * capabilities (`ollama-binary` provides both `ollama-api` and
+ * `ollama-terminal`); `instanceId` alone is not unique.
+ */
+export declare function getProviderEntry(instanceId: string, capability: string): CapabilityEntry | undefined;
+/**
+ * Register or update a single provider entry. Writes to both the new
+ * `providersByCapability` list and the legacy `capabilities` map (compat
+ * layer; PR 3 sub-step 3f drops the legacy write).
+ */
+export declare function registerProvider(entry: CapabilityEntry): void;
+/**
+ * Mark all providers from a given instance as `stopped` instead of deleting
+ * them, so the Connections UI can still show them as candidates (greyed out).
+ * Replaces the previous `unregisterCapabilities` semantics on stop (§5.4).
+ */
+export declare function setProviderStatus(instanceId: string, status: CapabilityStatus): void;
+/**
+ * Remove all providers for an instance permanently — used for uninstall /
+ * delete, NOT for stop (§5.4). After PR 3 sub-step 3c this is the only
+ * path that strips entries from the registry.
+ */
+export declare function unregisterProviders(instanceId: string): void;
+/**
+ * Snapshot of the full registry (read-only). UI / suggestion engine consumes.
+ * Same dedup semantics as `listProviders` so callers iterating the snapshot
+ * (e.g. category-prefix candidate matching in `routes/instances.ts`) don't
+ * leak duplicates.
+ */
+export declare function snapshot(): CapabilityRegistryFile;
+export {};