@bivy/bivy 0.0.0 → 0.1.0-staging.2

package/dist/runtime/local-model-store.js

@@ -0,0 +1,194 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+// Bivy's app-owned local/custom model registry — the source of truth for
+// user-provided model endpoints (Ollama, LM Studio, vLLM, SGLang, and any
+// OpenAI-compatible / self-hosted inference server).
+//
+// This module is deliberately PI-FREE (no import from any @earendil-works
+// package, not even a type), mirroring credential-store.ts. Bivy owns the
+// storage and the registry shape; Pi consumes it as just another agent via a
+// derived projection into its own `models.json` (see server.ts writePiModelsProjection).
+//
+// The registry holds NON-SECRET configuration ONLY: base URLs, API shape, and
+// model metadata (context window, cost, reasoning capability). It never stores
+// API keys — those live in Bivy's encrypted credential vault
+// (credential-store.ts), keyed by the same provider id, and are stitched back
+// in only when projecting Pi's models.json. The registry rides the existing
+// encrypted control-plane push so custom endpoints follow the account across
+// nodes and devices; the keys ride the credential half of that same push.
+import fs from "node:fs";
+import path from "node:path";
+const FILE_NAME = "local-models.json";
+const DEFAULT_BASE_URL = "http://localhost:11434/v1";
+const DEFAULT_API = "openai-completions";
+function configPath(dir) {
+    return path.join(dir, FILE_NAME);
+}
+/** Normalize a provider id the way every path expects (slug-safe). */
+export function normalizeProviderId(id) {
+    return (String(id ?? "")
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-") // non-slug runs collapse to a single dash
+        .replace(/^-+|-+$/g, "") // no leading/trailing dashes
+        || "local");
+}
+function normalizeModel(raw) {
+    const id = String(raw?.id ?? "").trim();
+    if (!id)
+        return null;
+    return {
+        id,
+        name: raw?.name ? String(raw.name) : undefined,
+        reasoning: !!raw?.reasoning,
+        input: Array.isArray(raw?.input) && raw.input.length ? raw.input.map((x) => String(x)) : ["text"],
+        contextWindow: Number(raw?.contextWindow) || 128000,
+        maxTokens: Number(raw?.maxTokens) || 16384,
+        cost: raw?.cost && typeof raw.cost === "object"
+            ? {
+                input: Number(raw.cost.input) || 0,
+                output: Number(raw.cost.output) || 0,
+                cacheRead: Number(raw.cost.cacheRead) || 0,
+                cacheWrite: Number(raw.cost.cacheWrite) || 0,
+            }
+            : { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    };
+}
+/** Coerce arbitrary input into a normalized provider (drops empty models). */
+export function normalizeProvider(id, raw) {
+    const models = Array.isArray(raw?.models)
+        ? raw.models.map(normalizeModel).filter((m) => !!m)
+        : [];
+    const provider = {
+        id: normalizeProviderId(id),
+        baseUrl: String(raw?.baseUrl ?? "").trim() || DEFAULT_BASE_URL,
+        api: String(raw?.api ?? "").trim() || DEFAULT_API,
+        models,
+    };
+    if (raw?.name)
+        provider.name = String(raw.name);
+    if (raw?.compat && typeof raw.compat === "object")
+        provider.compat = raw.compat;
+    // Any incoming `apiKey` is intentionally dropped — keys live in the vault.
+    return provider;
+}
+export function loadLocalModels(dir) {
+    const file = configPath(dir);
+    if (!fs.existsSync(file))
+        return { providers: {} };
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (!parsed || typeof parsed !== "object")
+            return { providers: {} };
+        const providersRaw = parsed.providers;
+        if (!providersRaw || typeof providersRaw !== "object")
+            return { providers: {} };
+        const providers = {};
+        for (const [id, spec] of Object.entries(providersRaw)) {
+            const norm = normalizeProvider(id, spec);
+            providers[norm.id] = norm;
+        }
+        return { providers };
+    }
+    catch {
+        return { providers: {} };
+    }
+}
+export function saveLocalModels(dir, cfg) {
+    fs.mkdirSync(dir, { recursive: true });
+    const safe = { providers: (cfg && cfg.providers) || {} };
+    const file = configPath(dir);
+    fs.writeFileSync(file, `${JSON.stringify(safe, null, 2)}\n`, { mode: 0o600 });
+    try {
+        fs.chmodSync(file, 0o600);
+    }
+    catch {
+        /* best effort */
+    }
+}
+/** Insert or update one provider; returns the normalized id and full config. */
+export function upsertLocalProvider(dir, id, spec) {
+    const cfg = loadLocalModels(dir);
+    const pid = normalizeProviderId(id);
+    const prev = cfg.providers[pid];
+    // Merge onto any existing entry so a partial save (e.g. just a new model)
+    // doesn't clobber the base URL. Explicit fields in `spec` win.
+    const merged = normalizeProvider(pid, { ...(prev ?? {}), ...(spec ?? {}) });
+    cfg.providers[pid] = merged;
+    saveLocalModels(dir, cfg);
+    return { id: pid, config: cfg };
+}
+export function removeLocalProviderEntry(dir, id) {
+    const cfg = loadLocalModels(dir);
+    delete cfg.providers[normalizeProviderId(id)];
+    saveLocalModels(dir, cfg);
+    return cfg;
+}
+/** Redacted list for the UI. `hasKey(id)` reports vault key presence (the store
+ *  itself holds no keys), defaulting to false when no resolver is supplied. */
+export function listLocalProviderSummaries(dir, hasKey = () => false) {
+    const cfg = loadLocalModels(dir);
+    return Object.values(cfg.providers)
+        .map((p) => ({
+        id: p.id,
+        name: p.name,
+        baseUrl: p.baseUrl,
+        api: p.api,
+        hasKey: hasKey(p.id),
+        modelCount: p.models.length,
+        models: p.models.map((m) => ({ id: m.id, name: m.name || m.id })),
+    }))
+        .sort((a, b) => (a.name || a.id).localeCompare(b.name || b.id));
+}
+/** Raw registry map for the control-plane sync payload. */
+export function exportLocalModels(dir) {
+    return loadLocalModels(dir).providers;
+}
+/**
+ * Merge a synced snapshot into the local registry. Non-destructive per the same
+ * philosophy as credential import: incoming providers are applied on top; the
+ * caller decides removals by re-pushing a snapshot without them (see server
+ * sync). Returns true if anything actually changed.
+ */
+export function importLocalModels(dir, incoming) {
+    if (!incoming || typeof incoming !== "object")
+        return false;
+    const cfg = loadLocalModels(dir);
+    let changed = false;
+    for (const [id, spec] of Object.entries(incoming)) {
+        if (!spec || typeof spec !== "object")
+            continue;
+        const norm = normalizeProvider(id, spec);
+        if (JSON.stringify(cfg.providers[norm.id]) !== JSON.stringify(norm)) {
+            cfg.providers[norm.id] = norm;
+            changed = true;
+        }
+    }
+    if (changed)
+        saveLocalModels(dir, cfg);
+    return changed;
+}
+/**
+ * Project the Bivy registry into the shape Pi's ModelRuntime reads from
+ * `models.json`. Pi only ever consumed custom/local providers from this file,
+ * so a full regeneration from Bivy's registry is faithful and keeps Pi a pure
+ * downstream consumer (never the source of truth).
+ */
+export function toPiModelsConfig(cfg, resolveKey = () => undefined) {
+    const providers = {};
+    for (const [id, p] of Object.entries(cfg.providers)) {
+        providers[id] = {
+            name: p.name,
+            baseUrl: p.baseUrl,
+            api: p.api,
+            // Key comes from the vault; local servers ignore it, so "local" is a safe
+            // default when none is stored (Ollama, LM Studio, vLLM, …).
+            apiKey: resolveKey(id) || "local",
+            ...(p.compat ? { compat: p.compat } : {}),
+            // Stamp each model with the provider's api so Pi dispatches to the right
+            // implementation (e.g. azure-openai-responses) even when a model omits it.
+            models: p.models.map((m) => ({ api: p.api, ...m })),
+        };
+    }
+    return { providers };
+}

package/dist/runtime/location-registry.js

@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+/**
+ * Node-local registry: each daemon knows only its own entries. This is exactly
+ * today's behavior (no cross-daemon sharing) and the safe default while the flag
+ * is off. A shared implementation replaces it to unlock statelessness — same
+ * interface, so no call site changes. Values are shallow-copied in and out so a
+ * caller's later mutation can't alias a stored entry.
+ */
+export class InMemoryLocationRegistry {
+    byKey = new Map();
+    async record(key, value) {
+        if (!key)
+            throw new Error("location key is required");
+        this.byKey.set(key, { ...value });
+    }
+    async lookup(key) {
+        const found = this.byKey.get(key);
+        return found ? { ...found } : undefined;
+    }
+    async forget(key) {
+        this.byKey.delete(key);
+    }
+    /** Number of recorded entries (test/introspection aid). */
+    get size() {
+        return this.byKey.size;
+    }
+}

package/dist/runtime/model-catalog.js

@@ -0,0 +1,97 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+// Unified model catalog — aggregated across agents, not sourced from pi alone.
+//
+// Each agent runtime optionally exposes a session-less `listCatalog()` (its
+// providers + models). Bivy unions them here into one catalog, deduped by
+// provider/model, and stamps each provider with auth state from Bivy's own vault
+// — so the "Models & providers" surface reflects what *any* installed agent can
+// run, with pi as just one (rich) contributor. New api-key providers are
+// supported dynamically (the provider→env mapping is generic); OAuth providers
+// are those in Bivy's native registry.
+import { createCredentialVault } from "./credential-store.js";
+import { isNativeOAuthProvider } from "./oauth/model-oauth-providers.js";
+async function catalogOf(runtime) {
+    if (!runtime.listCatalog)
+        return [];
+    try {
+        return await runtime.listCatalog();
+    }
+    catch {
+        // A runtime that can't enumerate its catalog (CLI missing, offline) simply
+        // contributes nothing rather than breaking the aggregate.
+        return [];
+    }
+}
+/**
+ * Aggregate the model catalog across the given agent runtimes and stamp Bivy's
+ * vault auth state onto each provider. Runtimes are queried concurrently; a
+ * failing one is skipped.
+ */
+export async function aggregateModelCatalog(runtimes, credsDir) {
+    const [perAgent, stored] = await Promise.all([
+        Promise.all(runtimes.map(async (runtime) => ({ agent: runtime.id, providers: await catalogOf(runtime) }))),
+        createCredentialVault(credsDir).list().catch(() => []),
+    ]);
+    const configured = new Set(stored.map((info) => info.providerId));
+    const byProvider = new Map();
+    const seenModel = new Map();
+    for (const { agent, providers } of perAgent) {
+        for (const provider of providers) {
+            const id = provider.id.trim().toLowerCase();
+            if (!id)
+                continue;
+            let entry = byProvider.get(id);
+            if (!entry) {
+                entry = { id, name: provider.name || id, oauth: isNativeOAuthProvider(id), configured: configured.has(id), agents: [], models: [] };
+                byProvider.set(id, entry);
+                seenModel.set(id, new Set());
+            }
+            if (provider.oauth)
+                entry.oauth = true;
+            if (!entry.agents.includes(agent))
+                entry.agents.push(agent);
+            const models = seenModel.get(id);
+            for (const model of provider.models) {
+                if (models.has(model.id))
+                    continue;
+                models.add(model.id);
+                entry.models.push(model);
+            }
+        }
+    }
+    return [...byProvider.values()]
+        .map((provider) => ({ ...provider, models: provider.models.sort((a, b) => a.name.localeCompare(b.name)) }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+ * Merge an authoritative per-provider auth status (from the base agent, which
+ * knows env vs stored) with the cross-agent catalog. Base rows keep their status
+ * and gain `agents`/`models`; providers only other agents know about are appended
+ * with the catalog's vault-derived status. Pure — the whole reason it's testable.
+ */
+export function mergeProviderCatalog(base, catalog) {
+    const byId = new Map();
+    for (const row of base)
+        byId.set(row.id, { ...row, agents: [], models: [] });
+    for (const provider of catalog) {
+        const existing = byId.get(provider.id);
+        if (existing) {
+            existing.agents = provider.agents;
+            existing.models = provider.models;
+            if (provider.oauth)
+                existing.oauth = true;
+        }
+        else {
+            byId.set(provider.id, {
+                id: provider.id,
+                name: provider.name,
+                oauth: provider.oauth,
+                configured: provider.configured,
+                agents: provider.agents,
+                models: provider.models,
+            });
+        }
+    }
+    return [...byId.values()].sort((a, b) => a.name.localeCompare(b.name));
+}

package/dist/runtime/model-namer.js

@@ -0,0 +1,85 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+// Node-level fallback session namer.
+//
+// A runtime's own adapter names a session with its own model (PiSession.suggestName,
+// ClaudeSession.suggestName). The generic CLI agents (codex, opencode, aider, …) run
+// the "dumb-pipe" ProcessRuntime, which has no model — so as a node-level fallback
+// Bivy resolves the CLI's selected provider/model against Pi's model registry (Bivy
+// has no model catalog of its own; Pi's registry is the borrowed model metadata) and
+// asks it for a title using whatever credential the shared vault holds.
+//
+// This is deliberately the ONLY place outside the Pi adapter that touches the Pi
+// inference SDK, kept under src/runtime/ so the core daemon (src/server.ts) stays
+// free of any @earendil-works import.
+import { completeSimple } from "@earendil-works/pi-ai/compat";
+import { ModelRegistry } from "@earendil-works/pi-coding-agent";
+import { createPiModelRuntime } from "./pi-oauth.js";
+function cleanSessionName(value) {
+    return value
+        .replace(/[\r\n"'`]/g, " ")
+        .replace(/\p{Control}/gu, "")
+        .replace(/\s+/g, " ")
+        .trim()
+        .replace(/[.?!,:;\-–—]+$/g, "")
+        .slice(0, 60)
+        .trim();
+}
+/**
+ * A CLI can report its model in provider-qualified (`anthropic/claude-…`) or bare
+ * form; try the given provider/id first, then a `provider/id` split, so the
+ * registry lookup succeeds for either convention.
+ */
+function selectedModelCandidates(provider, id) {
+    const cleanProvider = provider?.trim();
+    const cleanId = id?.trim();
+    if (!cleanProvider || !cleanId)
+        return [];
+    const out = [{ provider: cleanProvider, id: cleanId }];
+    const slash = cleanId.indexOf("/");
+    if (slash > 0) {
+        const prefixedProvider = cleanId.slice(0, slash);
+        const bareId = cleanId.slice(slash + 1);
+        if (prefixedProvider && bareId)
+            out.push({ provider: prefixedProvider, id: bareId });
+    }
+    return out.filter((candidate, index) => out.findIndex((x) => x.provider === candidate.provider && x.id === candidate.id) === index);
+}
+/**
+ * Title a session with the provider/model the user selected for it, resolved via
+ * Pi's model registry against the shared vault's credentials. Returns undefined
+ * when the model can't be resolved, no credential is configured, or the request
+ * fails — the caller keeps its deterministic title / node-level fallback.
+ */
+export async function suggestNameFromSelectedModel(opts) {
+    const prompt = opts.firstPrompt.trim();
+    if (!prompt)
+        return undefined;
+    try {
+        const registry = new ModelRegistry(await createPiModelRuntime({ credsDir: opts.credsDir, piDir: opts.piDir }));
+        let model;
+        for (const candidate of selectedModelCandidates(opts.provider, opts.id)) {
+            model = registry.find(candidate.provider, candidate.id);
+            if (model)
+                break;
+        }
+        if (!model)
+            return undefined;
+        const auth = await registry.getApiKeyAndHeaders(model);
+        if (!auth.ok)
+            return undefined;
+        const response = await completeSimple(model, {
+            systemPrompt: "Name chat sessions from the user's entire first message, not just its first line. Return only a concise title, 2-6 words. No quotes, punctuation, prefixes, or explanations.",
+            messages: [{ role: "user", content: `Create a short title for this coding-agent session using the full first message below:\n\n${prompt.slice(0, 4000)}`, timestamp: Date.now() }],
+        }, { apiKey: auth.apiKey, headers: auth.headers, env: auth.env, temperature: 0.2, maxTokens: 24, reasoning: "minimal", sessionId: `${opts.sessionId}:name` });
+        const text = response.content
+            .filter((part) => part.type === "text")
+            .map((part) => part.text)
+            .join(" ");
+        return cleanSessionName(text) || undefined;
+    }
+    catch (error) {
+        console.warn("Selected-model session naming failed", error);
+        return undefined;
+    }
+}

package/dist/runtime/native-process-scan.js

@@ -0,0 +1,102 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+// Best-effort "is there a live process for this discovered session" check (see
+// issue #156's "detect live external processes and offer follow/read-only or
+// safe takeover"). Bivy has no attach/IPC channel into a bare `claude`/`codex`
+// a user launched outside it, so this can only ever be a heuristic: match a
+// running process whose command name is one of the provider's binaries AND
+// whose current working directory equals the discovered session's cwd. A false
+// negative (missed live process) just means adoption proceeds as if idle; a
+// false positive only costs an extra confirmation. Never used for anything
+// security-sensitive — display/gating only.
+//
+// The process listing is injectable so callers (and tests) never depend on the
+// real OS: `hasLiveProcessForCwd`'s default lister shells out to `ps`, which is
+// unavailable/unreliable on some platforms and always best-effort (wrapped in
+// try/catch, empty on any failure).
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * List processes currently running on this node. Linux: reads `/proc` for an
+ * exact cwd via `/proc/<pid>/cwd`. Other platforms: falls back to `ps -axo
+ * pid=,comm=` with no cwd (so cwd-based matching below always reports "not
+ * live" there rather than guessing). Never throws; returns [] on any failure.
+ */
+export function listOsProcesses() {
+    try {
+        if (process.platform === "linux")
+            return listLinuxProcesses();
+        return listProcessesViaPs();
+    }
+    catch {
+        return [];
+    }
+}
+function listLinuxProcesses() {
+    const out = [];
+    let entries;
+    try {
+        entries = fs.readdirSync("/proc");
+    }
+    catch {
+        return out;
+    }
+    for (const entry of entries) {
+        if (!/^\d+$/.test(entry))
+            continue;
+        const pid = Number(entry);
+        let comm;
+        try {
+            comm = fs.readFileSync(`/proc/${entry}/comm`, "utf8").trim();
+        }
+        catch {
+            continue; // process exited mid-scan, or unreadable — skip it
+        }
+        let cwd;
+        try {
+            cwd = fs.readlinkSync(`/proc/${entry}/cwd`);
+        }
+        catch {
+            cwd = undefined; // permission denied (another user's process) — command-only match
+        }
+        out.push({ pid, command: comm, cwd });
+    }
+    return out;
+}
+/** macOS/other POSIX fallback: `ps` reports the command name only, no cwd. */
+function listProcessesViaPs() {
+    const result = spawnSync("ps", ["-axo", "pid=,comm="], { encoding: "utf8" });
+    if (result.status !== 0 || !result.stdout)
+        return [];
+    const out = [];
+    for (const line of result.stdout.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        const match = /^(\d+)\s+(.+)$/.exec(trimmed);
+        if (!match)
+            continue;
+        const command = match[2].split(/[\\/]/).pop() ?? match[2];
+        out.push({ pid: Number(match[1]), command });
+    }
+    return out;
+}
+/**
+ * Best-effort: is one of `binNames` currently running with cwd === `cwd`?
+ * Returns false (never throws) when the cwd can't be determined for any
+ * candidate process on this platform — an unproven match is treated as "not
+ * live" rather than risking a false "active" that would block adoption.
+ */
+export function hasLiveProcessForCwd(cwd, binNames, lister = listOsProcesses) {
+    if (!cwd)
+        return false;
+    const target = path.resolve(cwd);
+    const names = new Set(binNames.map((n) => n.toLowerCase()));
+    try {
+        return lister().some((p) => p.cwd != null && names.has(p.command.toLowerCase()) && path.resolve(p.cwd) === target);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/runtime/native-session-discovery.js

@@ -0,0 +1,103 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+// Capability-driven discovery/adoption of provider-native sessions (issue #156).
+//
+// This module is deliberately runtime-agnostic and side-effect-free: it never
+// touches a filesystem or spawns a process itself — that stays inside each
+// runtime's own `discoverNativeSessions()` (src/runtime/codex-sessions.ts,
+// src/runtime/claude-code.ts). What lives here is the shared policy every
+// runtime shares: aggregate discoveries across capable runtimes, drop ones
+// Bivy already manages, and decide how an adoption should proceed. Pure logic
+// is easy to test with fake runtimes and fixtures, which is exactly what issue
+// #156 asks for ("tests use provider fixtures for path discovery, dedupe,
+// resume, non-default homes, and unsupported runtimes").
+import { sessionIdentityKey } from "../session-identity.js";
+/** Build the set of identity keys for every session Bivy already manages, in
+ *  the same `ref:<path>` / `id:<id>` scheme session-identity.ts uses — so a
+ *  discovered session that resolves to the same durable conversation (whether
+ *  by on-disk path or by provider session id) is recognized as already-managed
+ *  regardless of which runtime variant (e.g. `codex` vs `codex-approvals`)
+ *  originally opened it. */
+function managedIdentityKeys(managed) {
+    const keys = new Set();
+    for (const session of managed) {
+        keys.add(sessionIdentityKey({ id: session.id }));
+        if (session.path)
+            keys.add(sessionIdentityKey({ path: session.path }));
+    }
+    return keys;
+}
+/** True when `session` resolves to a conversation Bivy already manages —
+ *  either by its provider ref (an id-based runtime's resume token) or by its
+ *  on-disk transcript path, when known. */
+export function isAlreadyManaged(session, managedKeys) {
+    if (managedKeys.has(sessionIdentityKey({ id: session.ref })))
+        return true;
+    if (session.file && managedKeys.has(sessionIdentityKey({ path: session.file })))
+        return true;
+    return false;
+}
+/**
+ * Collect discoverable sessions across every capable runtime, deduped against
+ * Bivy-managed sessions AND against each other (two runtime variants over the
+ * same provider store — e.g. `codex` exec vs `codex-approvals` — must not
+ * surface the same on-disk session twice). Best-effort per runtime: one
+ * adapter's discovery failing (a missing/unreadable store) never blanks the
+ * whole list, mirroring listAllSessions()'s "best effort per agent" contract.
+ * Sorted newest-first.
+ */
+export async function collectDiscoveredSessions(runtimes, managed) {
+    const managedKeys = managedIdentityKeys(managed);
+    const seen = new Set();
+    const out = [];
+    for (const runtime of runtimes) {
+        if (!runtime.capabilities.nativeSessionDiscovery || !runtime.discoverNativeSessions)
+            continue;
+        let discovered;
+        try {
+            discovered = (await runtime.discoverNativeSessions()) ?? [];
+        }
+        catch {
+            continue; // best-effort: a broken adapter shouldn't blank every other one
+        }
+        for (const session of discovered) {
+            if (isAlreadyManaged(session, managedKeys))
+                continue;
+            // Cross-runtime value dedupe (same on-disk session surfaced by two
+            // runtime variants): key on the transcript path when known, else the ref.
+            const valueKey = session.file ? `file:${session.file}` : `ref:${session.runtimeId}:${session.ref}`;
+            if (seen.has(valueKey))
+                continue;
+            seen.add(valueKey);
+            out.push(session);
+        }
+    }
+    return out.sort((a, b) => (b.updatedAt ?? 0) - (a.updatedAt ?? 0));
+}
+/**
+ * Decide how importing `session` should proceed, given the OWNING runtime's
+ * capabilities. Three outcomes:
+ *  - "follow-only": a live external process was detected. Bivy has no channel
+ *    to safely take over an arbitrary foreign process, so adoption is refused
+ *    and only read-only following (readMessages) is offered.
+ *  - "native-resume": the runtime can adopt this session with full native
+ *    context (capabilities.nativeSessionAdoption + resume + session.resumable).
+ *  - "seeded": adoption is possible but not a true resume — a fresh session
+ *    seeded from a summary of the prior conversation. Always carries a
+ *    disclosure the caller must show before importing.
+ */
+export function planNativeAdoption(session, capabilities) {
+    if (session.active) {
+        return {
+            mode: "follow-only",
+            disclosure: "This session has a live process running outside Bivy. Close it in its own terminal, then adopt it here — or follow it read-only without adopting.",
+        };
+    }
+    if (capabilities.nativeSessionAdoption && capabilities.resume && session.resumable) {
+        return { mode: "native-resume" };
+    }
+    return {
+        mode: "seeded",
+        disclosure: "Native resume isn't available for this session. Importing starts a new Bivy session seeded with a summary of the prior conversation; the original session is left untouched.",
+    };
+}