@termfleet/core 0.1.0

package/dist/registry.js

@@ -0,0 +1,406 @@
+import { asError } from "@termfleet/core/lib/errors.js";
+import { readFile, writeFile } from "node:fs/promises";
+import { isLocalProviderUrl, isSsrfReservedProviderHost, normalizeProviderOrigin } from "./contracts/provider-url.js";
+import { mergeRegistryProviders, normalizeRegistryPayload, normalizeRegistryRegistrationResponse, providerAliases } from "./contracts/registry.js";
+export class ProviderRegistry {
+    localRegistryFile;
+    remoteRegistryUrls;
+    remoteCacheTtlMs;
+    onRemoteReadError;
+    remoteRegistryCache = {
+        expiresAt: 0,
+        providers: []
+    };
+    remoteRegistryRead;
+    // Per-token cache for the signed-in provider list. The token-less cache above
+    // is org-agnostic; an authenticated read is org-scoped, so it is keyed by
+    // token. Without this, the console's 5s poll hit the registry Worker on every
+    // tick (one signed-in tab ≈ 17k Worker requests/day) — a primary contributor
+    // to tripping the Worker's daily request cap. Successful reads cache for the
+    // TTL and concurrent reads dedupe; errors are NOT cached and NOT served stale,
+    // so a revoked token still surfaces as an auth failure to the caller.
+    remoteTokenCache = new Map();
+    remoteTokenRead = new Map();
+    lastRegistryReadFailure = "";
+    // Serializes every local-registry read-modify-write. The file is the whole
+    // registry rewritten in one shot, so two concurrent writers (the identity
+    // sweep fans out over all records at once, plus registrations/deletes) would
+    // each read the same `previous` and clobber the other's change — last writer
+    // wins, the rest are lost. Chaining each mutation behind the previous one
+    // closes that lost-update race; pure reads (`readLocal`/`list`) stay lock-free.
+    localWriteChain = Promise.resolve();
+    constructor(options) {
+        this.localRegistryFile = options.localRegistryFile;
+        const remoteCandidates = options.remoteRegistryUrls?.length
+            ? options.remoteRegistryUrls
+            : options.remoteRegistryUrl
+                ? [options.remoteRegistryUrl]
+                : [];
+        this.remoteRegistryUrls = uniqueStrings(remoteCandidates.map((url) => url.trim()).filter((url) => url.length > 0));
+        this.remoteCacheTtlMs = options.remoteCacheTtlMs ?? 30_000;
+        this.onRemoteReadError = options.onRemoteReadError;
+    }
+    async list(options = {}) {
+        const localProviders = await this.readLocal();
+        const remoteProviders = await this.readRemoteForList(options.authToken);
+        return mergeRegistryProviders([
+            ...localProviders,
+            ...decorateRegistryProviders(options.runtimeProviders ?? [], "console-memory"),
+            ...remoteProviders
+        ]);
+    }
+    async listRemoteWithToken(authToken) {
+        if (!authToken) {
+            return await this.fetchRemote(authToken);
+        }
+        const now = Date.now();
+        const cached = this.remoteTokenCache.get(authToken);
+        if (cached && cached.expiresAt > now) {
+            return cached.providers;
+        }
+        const inFlight = this.remoteTokenRead.get(authToken);
+        if (inFlight) {
+            return inFlight;
+        }
+        const read = this.fetchRemote(authToken)
+            .then((providers) => {
+            for (const [token, entry] of this.remoteTokenCache) {
+                if (entry.expiresAt <= now) {
+                    this.remoteTokenCache.delete(token);
+                }
+            }
+            this.remoteTokenCache.set(authToken, { expiresAt: Date.now() + this.remoteCacheTtlMs, providers });
+            return providers;
+        })
+            .finally(() => {
+            this.remoteTokenRead.delete(authToken);
+        });
+        this.remoteTokenRead.set(authToken, read);
+        return read;
+    }
+    async resolveProvider(target, options = {}) {
+        const normalizedTarget = normalizeProviderTarget(target);
+        const providers = await this.list(options);
+        const matchGroups = [
+            providers.filter((provider) => providerAliases(provider).includes(target.toLowerCase())),
+            providers.filter((provider) => providerId(provider) === target.toLowerCase()),
+            providers.filter((provider) => provider.label?.toLowerCase() === target.toLowerCase()),
+            providers.filter((provider) => provider.baseUrl === normalizedTarget)
+        ];
+        for (const matches of matchGroups) {
+            if (matches.length === 1 && matches[0]) {
+                return matches[0];
+            }
+            if (matches.length > 1) {
+                throw new Error(`Provider target "${target}" matched multiple providers: ${matches.map(formatProviderTargetMatch).join(", ")}.`);
+            }
+        }
+        throw new Error(`Provider target "${target}" was not found in the registry.`);
+    }
+    async register(provider) {
+        if (isLocalProviderUrl(provider.baseUrl)) {
+            return await this.writeLocal(provider);
+        }
+        return await this.writeRemote(provider);
+    }
+    async registerLocal(provider) {
+        if (!isLocalProviderUrl(provider.baseUrl)) {
+            throw new Error("Local registry providers must use localhost or loopback URLs.");
+        }
+        return await this.writeLocal(provider);
+    }
+    async registerRemote(provider, options = {}) {
+        if (isLocalProviderUrl(provider.baseUrl)) {
+            throw new Error("Remote registry providers must use a LAN, tunnel, or remote URL.");
+        }
+        if (isSsrfReservedProviderHost(provider.baseUrl)) {
+            throw new Error("Remote provider URL must not be a link-local or cloud-metadata address.");
+        }
+        return await this.writeRemote(provider, options);
+    }
+    async removeRemote(baseUrl, options = {}) {
+        const normalizedBaseUrl = normalizeProviderOrigin(baseUrl);
+        if (isLocalProviderUrl(normalizedBaseUrl)) {
+            throw new Error("Shared registry providers must use a LAN, tunnel, or remote URL.");
+        }
+        return await this.deleteRemote(normalizedBaseUrl, options);
+    }
+    async removeLocal(baseUrl) {
+        const normalizedBaseUrl = normalizeProviderOrigin(baseUrl);
+        let removed = { baseUrl: normalizedBaseUrl };
+        await this.withLocalLock(async () => {
+            const previous = await this.readLocal();
+            removed = previous.find((candidate) => candidate.baseUrl === normalizedBaseUrl) ?? { baseUrl: normalizedBaseUrl };
+            await this.writeLocalFile(previous.filter((candidate) => candidate.baseUrl !== normalizedBaseUrl));
+        });
+        return removed;
+    }
+    async readLocal() {
+        try {
+            const payload = JSON.parse(await readFile(this.localRegistryFile, "utf8"));
+            return decorateRegistryProviders(normalizeRegistryPayload(payload), "local-registry");
+        }
+        catch (error) {
+            const nodeError = error;
+            if (nodeError.code === "ENOENT" || asError(error).message.includes("ENOENT")) {
+                return [];
+            }
+            throw error;
+        }
+    }
+    async writeLocal(provider) {
+        const normalized = normalizeRegistryPayload([provider])[0];
+        if (!normalized) {
+            throw new Error("Registry provider payload is required.");
+        }
+        await this.withLocalLock(async () => {
+            const previous = await this.readLocal();
+            // Merge ONTO the existing same-baseUrl record (normalized last so its
+            // explicit fields win) rather than dropping it — otherwise a bare pointer
+            // re-registration would erase the learned instanceId/owner and re-orphan
+            // the machine to its address key until the next probe re-stamps it.
+            await this.writeLocalFile(mergeRegistryProviders([...previous, normalized]));
+        });
+        return {
+            ...normalized,
+            registrySource: "local-registry"
+        };
+    }
+    // Atomically stamp a learned instanceId onto a record. Enforces the registry
+    // invariant that no two records share a serial: if another machine already
+    // owns this instanceId, the stamp is REFUSED and its baseUrl returned so the
+    // caller can warn — two providers minting the same id (a copied
+    // .termfleet-instance file, a baked image) would otherwise collapse onto one
+    // layout key and silently share appearance. Reads fresh inside the lock, so it
+    // can't lose a sibling stamp (the sweep fans out), clobber another field, or
+    // resurrect a record a racing delete removed.
+    async stampInstanceId(baseUrl, instanceId) {
+        let outcome = { stamped: false };
+        await this.withLocalLock(async () => {
+            const records = await this.readLocal();
+            const conflict = records.find((candidate) => candidate.baseUrl !== baseUrl && candidate.instanceId === instanceId);
+            if (conflict) {
+                outcome = { conflictWith: conflict.baseUrl, stamped: false };
+                return;
+            }
+            const index = records.findIndex((candidate) => candidate.baseUrl === baseUrl);
+            const existing = records[index];
+            if (!existing || existing.instanceId === instanceId) {
+                return;
+            }
+            const updated = [...records];
+            updated[index] = { ...existing, instanceId };
+            await this.writeLocalFile(mergeRegistryProviders(updated));
+            outcome = { stamped: true };
+        });
+        return outcome;
+    }
+    withLocalLock(operation) {
+        const result = this.localWriteChain.then(operation);
+        // Keep the chain alive past a failed mutation so one error doesn't wedge
+        // every later write; the failure still propagates to its own caller.
+        this.localWriteChain = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    async writeLocalFile(providers) {
+        await writeFile(this.localRegistryFile, `${JSON.stringify({ providers: providers.map(stripRegistrySource) }, null, 2)}\n`);
+    }
+    async readRemote(authToken) {
+        if (authToken) {
+            return await this.fetchRemote(authToken);
+        }
+        const now = Date.now();
+        if (this.remoteRegistryCache.expiresAt > now) {
+            return this.remoteRegistryCache.providers;
+        }
+        if (this.remoteRegistryRead) {
+            return this.remoteRegistryRead;
+        }
+        this.remoteRegistryRead = this.fetchRemote()
+            .then((providers) => {
+            this.remoteRegistryCache = {
+                expiresAt: Date.now() + this.remoteCacheTtlMs,
+                providers
+            };
+            this.lastRegistryReadFailure = "";
+            return providers;
+        })
+            .catch((error) => {
+            const message = asError(error).message;
+            if (message !== this.lastRegistryReadFailure) {
+                this.onRemoteReadError?.(message);
+                this.lastRegistryReadFailure = message;
+            }
+            this.remoteRegistryCache = {
+                expiresAt: Date.now() + this.remoteCacheTtlMs,
+                providers: this.remoteRegistryCache.providers
+            };
+            return this.remoteRegistryCache.providers;
+        })
+            .finally(() => {
+            this.remoteRegistryRead = undefined;
+        });
+        return this.remoteRegistryRead;
+    }
+    async readRemoteForList(authToken) {
+        try {
+            return await this.readRemote(authToken);
+        }
+        catch (error) {
+            const message = asError(error).message;
+            if (message !== this.lastRegistryReadFailure) {
+                this.onRemoteReadError?.(message);
+                this.lastRegistryReadFailure = message;
+            }
+            return this.remoteRegistryCache.providers;
+        }
+    }
+    assertRemoteConfigured() {
+        if (this.remoteRegistryUrls.length === 0) {
+            throw new Error("No shared registry is configured. Set TERMFLEET_REGISTRY_URL to a registry server URL to use shared providers.");
+        }
+    }
+    async fetchRemote(authToken) {
+        // No shared registry configured ⇒ local-only, no outbound request.
+        if (this.remoteRegistryUrls.length === 0) {
+            return [];
+        }
+        let lastError;
+        for (const remoteRegistryUrl of this.remoteRegistryUrls) {
+            try {
+                const response = await fetch(remoteRegistryUrl, {
+                    headers: authToken ? { authorization: `Bearer ${authToken}` } : undefined,
+                    signal: AbortSignal.timeout(2500)
+                });
+                if (!response.ok) {
+                    throw new Error(formatRemoteRegistryHttpError(remoteRegistryUrl, response.status, await response.text()));
+                }
+                return decorateRegistryProviders(normalizeRegistryPayload(await response.json())
+                    .filter((provider) => !isLocalProviderUrl(provider.baseUrl)), "remote-registry");
+            }
+            catch (error) {
+                lastError = remoteRegistryError(remoteRegistryUrl, "read", error);
+            }
+        }
+        throw asError(lastError);
+    }
+    async writeRemote(provider, options = {}) {
+        const normalized = normalizeRegistryPayload([provider])[0];
+        if (!normalized) {
+            throw new Error("Registry provider payload is required.");
+        }
+        this.assertRemoteConfigured();
+        let lastError;
+        for (const remoteRegistryUrl of this.remoteRegistryUrls) {
+            try {
+                const response = await fetch(remoteRegistryUrl, {
+                    body: JSON.stringify(normalized),
+                    headers: {
+                        ...(options.authToken ? { authorization: `Bearer ${options.authToken}` } : {}),
+                        "content-type": "application/json"
+                    },
+                    method: "POST"
+                });
+                if (!response.ok) {
+                    throw new Error(formatRemoteRegistryHttpError(remoteRegistryUrl, response.status, await response.text(), "registration"));
+                }
+                const responsePayload = await response.json().catch(() => normalized);
+                return {
+                    ...normalizeRegistryRegistrationResponse(responsePayload, normalized),
+                    registrySource: "remote-registry"
+                };
+            }
+            catch (error) {
+                lastError = remoteRegistryError(remoteRegistryUrl, "registration", error);
+            }
+        }
+        throw asError(lastError);
+    }
+    async deleteRemote(baseUrl, options = {}) {
+        this.assertRemoteConfigured();
+        let lastError;
+        for (const remoteRegistryUrl of this.remoteRegistryUrls) {
+            try {
+                const url = new URL(remoteRegistryUrl);
+                url.searchParams.set("baseUrl", baseUrl);
+                const response = await fetch(url, {
+                    headers: options.authToken ? { authorization: `Bearer ${options.authToken}` } : undefined,
+                    method: "DELETE"
+                });
+                if (!response.ok) {
+                    throw new Error(formatRemoteRegistryHttpError(remoteRegistryUrl, response.status, await response.text(), "unregistration"));
+                }
+                const responsePayload = await response.json().catch(() => ({ baseUrl }));
+                const [removed] = normalizeRegistryPayload([responsePayload]);
+                this.remoteRegistryCache = {
+                    expiresAt: 0,
+                    providers: this.remoteRegistryCache.providers.filter((provider) => provider.baseUrl !== baseUrl)
+                };
+                return {
+                    ...(removed ?? { baseUrl }),
+                    registrySource: "remote-registry"
+                };
+            }
+            catch (error) {
+                lastError = remoteRegistryError(remoteRegistryUrl, "unregistration", error);
+            }
+        }
+        throw asError(lastError);
+    }
+}
+function uniqueStrings(values) {
+    const seen = new Set();
+    return values.filter((value) => {
+        if (seen.has(value))
+            return false;
+        seen.add(value);
+        return true;
+    });
+}
+export function decorateRegistryProviders(providers, registrySource) {
+    return providers.map((provider) => ({
+        ...provider,
+        registrySource
+    }));
+}
+function stripRegistrySource(provider) {
+    const { registrySource: _registrySource, ...rest } = provider;
+    return rest;
+}
+export function providerId(provider) {
+    return (provider.label ?? provider.baseUrl)
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+function formatProviderTargetMatch(provider) {
+    return provider.label ? `${provider.label} (${provider.baseUrl})` : provider.baseUrl;
+}
+export function normalizeProviderTarget(target) {
+    try {
+        return normalizeProviderOrigin(target);
+    }
+    catch {
+        return target;
+    }
+}
+function formatRemoteRegistryHttpError(remoteRegistryUrl, status, body, operation = "read") {
+    const message = body.trim();
+    if (status === 502 && /ECONNREFUSED|Local server error/i.test(message)) {
+        const url = new URL(remoteRegistryUrl);
+        return [
+            `Shared registry ${operation} failed: ${url.origin} is reachable, but its backing registry server is not running.`,
+            "The registry tunnel is forwarding to a local port that refused the connection.",
+            "Start the backing registry server on the tunnel target, for example:",
+            "  npx tsx src/cli.ts serve-registry --host 127.0.0.1 --port 7401 --file .termfleet-remote-registry.json"
+        ].join("\n");
+    }
+    return `Shared registry ${operation} failed: ${remoteRegistryUrl} returned ${status}${message ? `: ${message}` : ""}`;
+}
+function remoteRegistryError(remoteRegistryUrl, operation, error) {
+    const message = asError(error).message;
+    if (message.includes(remoteRegistryUrl)) {
+        return new Error(message);
+    }
+    return new Error(`Shared registry ${operation} failed: ${remoteRegistryUrl}: ${message}`);
+}

package/dist/session-attention.d.ts

@@ -0,0 +1,24 @@
+import type { SessionLifecycleState } from "./session-lifecycle.js";
+export type SessionLiveness = "background" | "ended" | "running" | "waiting";
+export declare function livenessForState(state: SessionLifecycleState): Exclude<SessionLiveness, "ended">;
+export type AttentionLabel = "asking" | "awaiting_me" | "ended" | "errored" | "stuck" | "working";
+export declare const ATTENTION_RANK: Record<AttentionLabel, number>;
+export declare const STUCK_IDLE_SECONDS = 300;
+export declare function computeAttention(options: {
+    idleSeconds?: number;
+    liveness: SessionLiveness;
+    signal?: "asking" | "errored";
+}): AttentionLabel;
+export declare const NEEDS_ATTENTION: ReadonlySet<AttentionLabel>;
+export type AttentionRow = {
+    agentSessionId: string;
+    attention: AttentionLabel;
+    cwd?: string;
+    terminalId?: string;
+    title: string;
+    windowId?: number;
+};
+export type AttentionTransition = AttentionRow & {
+    from: AttentionLabel | "new";
+};
+export declare function attentionTransitions(previous: Map<string, AttentionLabel>, rows: AttentionRow[], firstTick: boolean): AttentionTransition[];

package/dist/session-attention.js

@@ -0,0 +1,54 @@
+// Collapse the raw lifecycle observation into normalized liveness (the live cases).
+export function livenessForState(state) {
+    if (state === "session_running")
+        return "running";
+    if (state === "session_stopped_background_running")
+        return "background";
+    return "waiting";
+}
+export const ATTENTION_RANK = { asking: 1, awaiting_me: 2, ended: 5, errored: 0, stuck: 3, working: 4 };
+// A foreground-running session whose transcript hasn't moved in this long looks
+// busy but is likely wedged (long tool hang / crash without exit). Heuristic.
+export const STUCK_IDLE_SECONDS = 300;
+// `signal` (errored/asking) is the finer pane read from the lifecycle and overrides
+// the coarse liveness when present — a crash or a pending choice needs the human now.
+export function computeAttention(options) {
+    if (options.liveness !== "ended") {
+        if (options.signal === "errored")
+            return "errored";
+        if (options.signal === "asking")
+            return "asking";
+    }
+    if (options.liveness === "ended")
+        return "ended";
+    if (options.liveness === "waiting")
+        return "awaiting_me";
+    if (options.liveness === "running" && (options.idleSeconds ?? 0) >= STUCK_IDLE_SECONDS)
+        return "stuck";
+    return "working";
+}
+// The attention states that warrant interrupting the human. Notify fires only on a
+// transition INTO one of these — not every poll, and not for working/ended.
+export const NEEDS_ATTENTION = new Set(["errored", "asking", "awaiting_me", "stuck"]);
+// Diff the current rows against the last-seen attention per session and return the
+// ones that just entered a needs-attention state. Mutates `previous` to the new
+// state. The first tick only seeds the baseline (no spam on startup).
+export function attentionTransitions(previous, rows, firstTick) {
+    const transitions = [];
+    for (const row of rows) {
+        const prior = previous.get(row.agentSessionId);
+        previous.set(row.agentSessionId, row.attention);
+        if (firstTick || prior === row.attention || !NEEDS_ATTENTION.has(row.attention))
+            continue;
+        transitions.push({
+            agentSessionId: row.agentSessionId,
+            attention: row.attention,
+            ...(row.cwd ? { cwd: row.cwd } : {}),
+            from: prior ?? "new",
+            ...(row.terminalId ? { terminalId: row.terminalId } : {}),
+            title: row.title,
+            ...(row.windowId !== undefined ? { windowId: row.windowId } : {})
+        });
+    }
+    return transitions;
+}

package/dist/session-lifecycle.d.ts

@@ -0,0 +1,83 @@
+export type SessionLifecycleState = "session_running" | "session_stopped_background_running" | "session_waiting";
+export type PaneLifecycle = {
+    paneId: string;
+    target: string;
+    rootPid: number;
+    currentSessionId: string | null;
+    sessionIds: string[];
+};
+export type SessionAttentionSignal = "asking" | "errored";
+export type SessionLifecycle = {
+    sessionId: string;
+    agentSessionId?: string;
+    provider: string;
+    attachedPaneId: string | null;
+    lastPaneId: string | null;
+    firstSeenAt: string;
+    lastSeenAt: string;
+    state: SessionLifecycleState;
+    signal?: SessionAttentionSignal;
+    mainPid?: number;
+    backgroundLeaseDir?: string;
+    background: BackgroundWorkItem[];
+};
+export type LifecycleSnapshot = {
+    observedAt: string;
+    panes: PaneLifecycle[];
+    sessions: SessionLifecycle[];
+};
+export type LifecycleStore = {
+    panes: Map<string, PaneLifecycle>;
+    sessions: Map<string, SessionLifecycle>;
+};
+export type PaneProcessObservation = {
+    backgroundLeaseDir?: string;
+    contents?: string;
+    paneId: string;
+    target: string;
+    rootPid: number;
+};
+export type ProcessTreeRow = {
+    pid: number;
+    ppid: number;
+    pgid?: number;
+    stat?: string;
+    command: string;
+    args: string;
+};
+export type BackgroundWorkItem = {
+    args?: string;
+    command?: string;
+    description?: string;
+    pid: number;
+    ppid?: number;
+    pgid?: number;
+    processStartTime?: string;
+    source: "descendant" | "explicit-lease" | "leased-descendant";
+};
+type BackgroundLeaseFile = {
+    args?: unknown;
+    command?: unknown;
+    description?: unknown;
+    pid?: unknown;
+    processStartTime?: unknown;
+};
+export declare function snapshotProcessTreeAsync(rootPids?: number[]): Promise<Map<number, ProcessTreeRow>>;
+export declare function snapshotProcessTree(rootPids?: number[]): Map<number, ProcessTreeRow>;
+export declare function snapshotDescendantPids(rootPids: number[]): number[];
+export declare function createLifecycleStore(): LifecycleStore;
+export type ObserveIo = {
+    leasesByDir: Map<string, BackgroundLeaseFile[]>;
+    startTimes: Map<number, string>;
+};
+export declare function observeLifecycle(options: {
+    io?: ObserveIo;
+    now?: Date;
+    panes: PaneProcessObservation[];
+    processRows: Map<number, ProcessTreeRow>;
+    store?: LifecycleStore;
+}): LifecycleSnapshot;
+export declare function classifyAttentionSignal(contents?: string): SessionAttentionSignal | undefined;
+export declare function gatherProcessStartTimes(): Promise<Map<number, string>>;
+export declare function gatherBackgroundLeases(dirs: Array<string | undefined>): Promise<Map<string, BackgroundLeaseFile[]>>;
+export {};