jishushell 0.6.5 → 0.6.18

package/dist/services/connections/resolver.js

@@ -0,0 +1,289 @@
+/**
+ * Layer 2 — resolveConnections (§6.3 of the app interconnection design).
+ *
+ * Drop-in replacement for the legacy `capability-service.resolveRequires(spec)`.
+ * The new function takes both the consumer spec and the consumer instance
+ * (so it can read `instance.connections` UI bindings), and runs in one of
+ * two modes:
+ *
+ *   - "preCreate": install / clone / summary path. It resolves
+ *     only canonical `instance.connections` bindings and collects unbound
+ *     slots into `pending`; it never guesses a provider from the registry.
+ *   - "runtime": startInstance path. Persisted bindings are honored; required
+ *     slots without a persisted binding throw a connection error instead of
+ *     picking a provider from the registry; mismatched bindings throw
+ *     `INVALID_BINDING (400)`.
+ *
+ * The return shape `{ resolved, pending }` lets each caller decide what to
+ * do (write env, throw, write to task event for UI display).
+ *
+ * Step 4 boundary: runtime/status/proxy/capability hot paths must not use the
+ * capability registry as a fallback fact source. The only remaining automatic
+ * binding behavior lives in `materializeInstallTimeConnections()`, which writes
+ * an explicit `instance.connections` snapshot during create/install.
+ *
+ * `instance.connections` is a Core-managed binding fact ("which consumer slot
+ * is bound to which provider capability"). It is not runtime attestation that
+ * the app is currently using the delivered env/proxy token/key; app-local
+ * provider settings remain unmanaged unless an integration reconciles them.
+ */
+import * as capabilityRegistry from "../capabilities/registry.js";
+import { capabilityMatchesRequire, categoryFromCapabilityName, isCategoryToken as isCapabilityKindToken, isContractRequire, providerKindFromCapabilityName, resolveCapabilityContract, } from "../capabilities/contract.js";
+// ── Category whitelist (§4.1) ────────────────────────────────────────────
+export function isCategoryToken(s) {
+    return isCapabilityKindToken(s);
+}
+/**
+ * Extract the category of a provide-side capability name. Returns the
+ * category token when the name is `<token>-something`; null for legacy exact
+ * names like `ollama-api`.
+ */
+export function categoryFromProviderCapability(cap) {
+    return categoryFromCapabilityName(cap);
+}
+/**
+ * For LLM `proxy-upstream` mode: convert a provide capability like
+ * `llm-ollama` to the providerKind token (`ollama` / `vllm` / `sglang` /
+ * `custom`) the embedded llm-proxy expects on `x-jishushell.proxy.upstream.providerId`.
+ */
+export function providerKindFromCapability(cap) {
+    return providerKindFromCapabilityName(cap);
+}
+// ── Errors with stable code field ────────────────────────────────────────
+export class ConnectionError extends Error {
+    code;
+    statusCode;
+    details;
+    constructor(code, statusCode, message, details) {
+        super(message);
+        this.code = code;
+        this.statusCode = statusCode;
+        if (details)
+            this.details = details;
+    }
+}
+// ── validateBoundEntries (§6.3) ──────────────────────────────────────────
+export function entryMatchesRequire(req, entry) {
+    return capabilityMatchesRequire(req, entry);
+}
+function validateBoundEntries(req, entries) {
+    const cardinality = req.cardinality ?? "one";
+    for (const entry of entries) {
+        if (!entryMatchesRequire(req, entry)) {
+            throw new ConnectionError("INVALID_BINDING", 400, `Slot '${req.inject_as}' bound to provider '${entry.instanceId}' with capability '${entry.capability}', which does not match require '${req.capability}'`, { slot: req.inject_as, expected: req.capability, got: entry.capability });
+        }
+    }
+    if (cardinality === "one" && entries.length !== 1) {
+        throw new ConnectionError("INVALID_BINDING", 400, `Slot '${req.inject_as}' has cardinality:one but ${entries.length} providers bound`, { slot: req.inject_as, count: entries.length });
+    }
+    if (cardinality === "many" && entries.length === 0) {
+        throw new ConnectionError("INVALID_BINDING", 400, `Slot '${req.inject_as}' has cardinality:many but no providers bound`, { slot: req.inject_as });
+    }
+}
+// ── Helpers for category derivation ─────────────────────────────────────
+function categoryFor(req, entries) {
+    const reqContract = resolveCapabilityContract(req);
+    if (reqContract)
+        return reqContract.kind;
+    for (const e of entries) {
+        if (e.kind)
+            return e.kind;
+        const cat = categoryFromProviderCapability(e.capability);
+        if (cat)
+            return cat;
+    }
+    return "default";
+}
+function allRegistryEntries() {
+    return Object.values(capabilityRegistry.snapshot().providersByCapability ?? {}).flatMap((list) => list);
+}
+function enumerateCandidatesForRequire(req) {
+    const seen = new Set();
+    const out = [];
+    for (const entry of allRegistryEntries()) {
+        if (!entryMatchesRequire(req, entry))
+            continue;
+        const key = `${entry.instanceId}\0${entry.capability}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(entry);
+    }
+    return out;
+}
+// ── Main API ─────────────────────────────────────────────────────────────
+/**
+ * Resolve all `requires` on `spec` against the registry + the instance's
+ * persisted bindings.
+ *
+ * @param spec     Consumer app spec (`requires[]` is the input)
+ * @param instance Consumer app instance shape — may be a stub
+ *                 `{ connections: {} }` during clone / install
+ *                 (preCreate mode) or the live instance.json (runtime).
+ * @param mode     Affects error semantics: preCreate never throws on
+ *                 missing/ambiguous; runtime throws.
+ */
+export function resolveConnections(spec, instance, mode) {
+    const resolved = [];
+    const pending = [];
+    if (!spec.requires || spec.requires.length === 0) {
+        return { resolved, pending };
+    }
+    const connectionsMap = instance.connections ?? {};
+    for (const req of spec.requires) {
+        const isRequired = req.required !== false;
+        const cardinality = req.cardinality ?? "one";
+        const persisted = connectionsMap[req.inject_as];
+        // ── User explicit disconnect ───────────────────────────────────────
+        if (persisted === null) {
+            if (isRequired && mode === "runtime") {
+                throw new ConnectionError("MISSING_REQUIRED_CONNECTION", 412, `Required connection '${req.inject_as}' (${req.capability}) is explicitly disconnected`, { slot: req.inject_as, capability: req.capability });
+            }
+            pending.push({
+                slot: req.inject_as,
+                capability: req.capability,
+                required: isRequired,
+                reason: "user-disconnected",
+            });
+            continue;
+        }
+        // ── User-driven binding (UI) ───────────────────────────────────────
+        if (persisted) {
+            const entries = collectEntriesFromBinding(persisted);
+            validateBoundEntries(req, entries);
+            // Status check (running) — preCreate skips since instance not yet
+            // alive, runtime requires running provider.
+            if (mode === "runtime") {
+                for (const entry of entries) {
+                    if (entry.status !== "running") {
+                        throw new ConnectionError("PROVIDER_NOT_RUNNING", 409, `Provider '${entry.instanceId}' for slot '${req.inject_as}' is not running (status=${entry.status})`, { slot: req.inject_as, providerId: entry.instanceId, status: entry.status });
+                    }
+                }
+            }
+            resolved.push({
+                slot: req.inject_as,
+                capability: req.capability,
+                category: categoryFor(req, entries),
+                required: isRequired,
+                apply: req.apply,
+                cardinality,
+                entries,
+                source: "persisted-binding",
+            });
+            continue;
+        }
+        const candidates = enumerateCandidatesForRequire(req);
+        const running = candidates.filter((entry) => entry.status === "running");
+        if (running.length > 1) {
+            if (isRequired && mode === "runtime") {
+                throw new ConnectionError("AMBIGUOUS_CONNECTION", 409, `Slot '${req.inject_as}' (${req.capability}) has ${running.length} candidates; user must pick one in Connections tab`, { slot: req.inject_as, capability: req.capability, count: running.length });
+            }
+            pending.push({
+                slot: req.inject_as,
+                capability: req.capability,
+                required: isRequired,
+                reason: "ambiguous",
+            });
+            continue;
+        }
+        if (running.length === 1 || candidates.length > 0) {
+            // A provider exists but there is no canonical binding. This is not a
+            // runtime fact: start/proxy/status must not silently pick it. The user
+            // (or install/create materialization) must write `instance.connections`.
+            if (isRequired && mode === "runtime") {
+                throw new ConnectionError("USER_SELECTION_REQUIRED", 409, `Required slot '${req.inject_as}' (${req.capability}) has candidate provider(s); user must bind in Connections tab`, { slot: req.inject_as, capability: req.capability, count: candidates.length });
+            }
+            pending.push({
+                slot: req.inject_as,
+                capability: req.capability,
+                required: isRequired,
+                reason: "needs-ui-binding",
+            });
+            continue;
+        }
+        // No candidates at all.
+        if (isRequired && mode === "runtime") {
+            throw new ConnectionError("MISSING_REQUIRED_CONNECTION", 412, `Required connection '${req.inject_as}' (${req.capability}) has no candidates`, { slot: req.inject_as, capability: req.capability });
+        }
+        pending.push({
+            slot: req.inject_as,
+            capability: req.capability,
+            required: isRequired,
+            reason: "no-candidate",
+        });
+    }
+    return { resolved, pending };
+}
+/**
+ * Create/install boundary only.
+ *
+ * This preserves the old "single running exact provider works out of the box"
+ * UX by materializing it into `instance.connections` before the instance is
+ * first persisted. The materialized connection becomes the canonical fact that
+ * later runtime/status/proxy/capability paths read. Do not call this from hot
+ * paths: registry enumeration here is a one-shot install-time convenience, not
+ * a new fallback source of truth.
+ */
+export function materializeInstallTimeConnections(spec, existingConnections = {}) {
+    const connections = { ...existingConnections };
+    for (const req of spec.requires ?? []) {
+        if (Object.prototype.hasOwnProperty.call(connections, req.inject_as))
+            continue;
+        if (isContractRequire(req))
+            continue;
+        const running = enumerateCandidatesForRequire(req)
+            .filter((entry) => entry.status === "running");
+        if (running.length !== 1)
+            continue;
+        const selected = running[0];
+        connections[req.inject_as] =
+            (req.cardinality ?? "one") === "many"
+                ? { kind: "many", providers: [{ providerId: selected.instanceId, capability: selected.capability }] }
+                : { kind: "single", providerId: selected.instanceId, capability: selected.capability };
+    }
+    const result = resolveConnections(spec, { connections }, "preCreate");
+    return { connections, ...result };
+}
+function collectEntriesFromBinding(binding) {
+    if (!binding)
+        return [];
+    if (binding.kind === "single") {
+        const entry = capabilityRegistry.getProviderEntry(binding.providerId, binding.capability);
+        if (entry)
+            return [entry];
+        throw new ConnectionError("INVALID_PROVIDER_ID", 400, `Bound providerId '${binding.providerId}' (capability '${binding.capability}') not found in registry`, { providerId: binding.providerId, capability: binding.capability });
+    }
+    // many
+    const entries = [];
+    const missing = [];
+    for (const ref of binding.providers ?? []) {
+        const entry = capabilityRegistry.getProviderEntry(ref.providerId, ref.capability);
+        if (entry)
+            entries.push(entry);
+        else
+            missing.push(ref);
+    }
+    if (missing.length > 0) {
+        throw new ConnectionError("INVALID_PROVIDER_ID", 400, `${missing.length} bound providers not found in registry`, { missing });
+    }
+    return entries;
+}
+/**
+ * Convenience helper: resolved → flat env map (for default-ENV legacy
+ * fallback path used in install Phase 1, see §6.4 lazy materialization).
+ * Only entries with category=="default" are projected; LLM/MCP/Search/Browser
+ * categories use their own apply hooks (PR 4) and are skipped here.
+ */
+export function resolvedToLegacyEnv(resolved) {
+    const out = {};
+    for (const r of resolved) {
+        if (r.category !== "default")
+            continue;
+        if (r.entries.length === 0)
+            continue;
+        // For multi-entry default ENV: join addresses with comma (rare path).
+        out[r.slot] = r.entries.map((e) => e.address).join(",");
+    }
+    return out;
+}
+//# sourceMappingURL=resolver.js.map

package/dist/services/connections/resolver.js.map

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

package/dist/services/connections/suggestions.d.ts

@@ -0,0 +1,27 @@
+export interface ConnectionSuggestion {
+    id: string;
+    consumerInstanceId: string;
+    consumerName: string;
+    instanceId: string;
+    slot: string;
+    capability: string;
+    candidate: {
+        providerId: string;
+        capability: string;
+        name?: string;
+        protocol: string;
+        status: string;
+        hostPort: number;
+        path?: string;
+    };
+    reason: string;
+}
+export declare function computeSuggestions(): ConnectionSuggestion[];
+/**
+ * Mark a suggestion as dismissed. Persisted on the consumer instance so
+ * subsequent computeSuggestions() invocations skip it for the TTL window.
+ *
+ * `id` follows the format `${consumerInstanceId}::${slot}::...` — the
+ * leading two segments are enough to identify the slot to dismiss.
+ */
+export declare function dismissSuggestion(id: string): Promise<void>;

package/dist/services/connections/suggestions.js

@@ -0,0 +1,124 @@
+/**
+ * Panel-only Suggestions engine — scans every app instance for unbound `requires`
+ * slots that *could* be filled from the current capability registry, and
+ * emits one suggestion per (consumer, slot, candidate). The Dashboard
+ * polls this so the user gets a low-friction "you can connect X to Y"
+ * prompt without having to dig into each instance.
+ *
+ * Dismissals are stored on the consumer's `instance.json.dismissedSuggestions`
+ * (per-slot, 30-day TTL).
+ */
+import * as capabilityRegistry from "../capabilities/registry.js";
+import * as instanceManager from "../instances/manager.js";
+import { getInstanceInstallRecord } from "../app-common/service.js";
+import { resolveConnections } from "./resolver.js";
+import { capabilityMatchesRequire } from "../capabilities/contract.js";
+import { readCanonicalSpecForInstance } from "../app-common/instance-store.js";
+import { resolveExecutionOwnerFromMetadata } from "../app-common/execution-owner.js";
+import { getIntegration } from "../integrations/index.js";
+import { safeReadJson, safeWriteJson } from "../../utils/safe-json.js";
+const DISMISS_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+export function computeSuggestions() {
+    const out = [];
+    const allInstances = instanceManager.listInstances();
+    for (const inst of allInstances) {
+        const instanceId = String(inst.id ?? "");
+        let spec = getInstanceInstallRecord(instanceId)?.spec ?? null;
+        if (!spec) {
+            spec = readCanonicalSpecForInstance(instanceId);
+            if (!spec)
+                continue;
+        }
+        const persisted = (inst.connections ?? {});
+        const dismissed = (inst.dismissedSuggestions ?? []);
+        const dismissedSlots = new Set(dismissed
+            .filter((d) => new Date(d.until).getTime() > Date.now())
+            .map((d) => d.slot));
+        let pending = [];
+        try {
+            const r = resolveConnections(spec, { connections: persisted }, "preCreate");
+            pending = r.pending;
+        }
+        catch {
+            continue;
+        }
+        for (const p of pending) {
+            if (dismissedSlots.has(p.slot))
+                continue;
+            const req = (spec.requires ?? []).find((item) => item.inject_as === p.slot);
+            if (!req)
+                continue;
+            const candidates = enumerateCandidates(req);
+            // Same agent-on-agent guard as the Connections-tab dropdown: agent
+            // consumers of `llm` should never be offered another agent's
+            // `llm-agent` (would chain agent → agent → real model).
+            const owner = resolveExecutionOwnerFromMetadata(instanceId, inst);
+            const consumerIsAgent = owner.type === "integration"
+                && getIntegration(owner.integrationKind).manifest?.connectionRole === "agent";
+            const running = candidates.filter((e) => {
+                if (e.status !== "running")
+                    return false;
+                if (e.instanceId === inst.id)
+                    return false;
+                if (consumerIsAgent && req.capability === "llm" && e.capability === "llm-agent")
+                    return false;
+                return true;
+            });
+            if (running.length === 0)
+                continue;
+            // Single candidate → suggest it; multiple → suggest the running ones.
+            const top = running[0];
+            out.push({
+                id: `${inst.id}::${p.slot}::${top.instanceId}::${top.capability}`,
+                consumerInstanceId: inst.id,
+                consumerName: inst.name ?? inst.id,
+                instanceId,
+                slot: p.slot,
+                capability: p.capability,
+                candidate: {
+                    providerId: top.instanceId,
+                    capability: top.capability,
+                    name: top.name,
+                    protocol: top.protocol,
+                    status: top.status,
+                    hostPort: top.hostPort,
+                    path: top.path,
+                },
+                reason: p.reason,
+            });
+        }
+    }
+    return out;
+}
+function enumerateCandidates(req) {
+    const file = capabilityRegistry.snapshot();
+    const out = [];
+    for (const list of Object.values(file.providersByCapability ?? {})) {
+        for (const entry of list) {
+            if (capabilityMatchesRequire(req, entry))
+                out.push(entry);
+        }
+    }
+    return out;
+}
+/**
+ * Mark a suggestion as dismissed. Persisted on the consumer instance so
+ * subsequent computeSuggestions() invocations skip it for the TTL window.
+ *
+ * `id` follows the format `${consumerInstanceId}::${slot}::...` — the
+ * leading two segments are enough to identify the slot to dismiss.
+ */
+export async function dismissSuggestion(id) {
+    const parts = id.split("::");
+    if (parts.length < 2)
+        throw new Error(`Invalid suggestion id: ${id}`);
+    const [consumerInstanceId, slot] = parts;
+    const path = instanceManager.instanceMetaPath(consumerInstanceId);
+    const cur = (safeReadJson(path, `instance:${consumerInstanceId}`) ?? {});
+    const list = Array.isArray(cur.dismissedSuggestions) ? cur.dismissedSuggestions : [];
+    const filtered = list.filter((d) => d.slot !== slot);
+    filtered.push({ slot, until: new Date(Date.now() + DISMISS_TTL_MS).toISOString() });
+    cur.dismissedSuggestions = filtered;
+    safeWriteJson(path, cur);
+}
+//# sourceMappingURL=suggestions.js.map

package/dist/services/connections/suggestions.js.map

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

package/dist/services/connections/transactor.d.ts

@@ -0,0 +1,39 @@
+import type { ResolvedConnection } from "./resolver.js";
+import type { ApplyContext } from "./apply.js";
+import type { AppSpec, InstanceConnections } from "../../types.js";
+import type { AppInstance } from "../instances/types.js";
+export interface TransactorInput {
+    instance: AppInstance;
+    spec: AppSpec;
+    newConnections: InstanceConnections;
+    /** Persist instance.json — supplied by caller (route handler). */
+    saveInstanceJson: (id: string, mutator: (cur: AppInstance) => AppInstance) => Promise<void>;
+    readInstanceJson: (id: string) => Promise<AppInstance>;
+    /** AppIntegration for integration-managed consumers; null for generic apps. */
+    integration: ApplyContext["integration"];
+}
+export interface TransactorResult {
+    resolved: ResolvedConnection[];
+}
+/**
+ * Raw-bytes snapshot of a side-effect file. `bytes === null` means the file
+ * did not exist at snapshot time — rollback should `unlink` it.
+ */
+interface FileSnapshot {
+    path: string;
+    bytes: Buffer | null;
+    /** Set when the file existed but could not be read (e.g. EACCES). Rollback skips these entries to avoid destroying data. */
+    readError?: boolean;
+}
+export declare function applyConnections(input: TransactorInput): Promise<TransactorResult>;
+/**
+ * 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 declare const __testing__: {
+    snapshotSideEffectFiles: (paths: string[]) => FileSnapshot[];
+    applyFileSnapshots: (snapshots: FileSnapshot[]) => void;
+    validateResolvedEndpoints: (resolved: ResolvedConnection[]) => Promise<void>;
+};
+export {};