@roamcode.ai/server 1.0.0

package/dist/providers/codex-thread-resolver.js

@@ -0,0 +1,322 @@
+import { isAbsolute } from "node:path";
+import { z } from "zod";
+import { codexThreadResolutionCoordinator } from "./codex-thread-coordinator.js";
+import { isCodexThreadPersistence } from "./codex-thread-persistence.js";
+import { ProviderError } from "./types.js";
+const DEFAULT_DEADLINE_MS = 5_000;
+const DEFAULT_POLL_INTERVAL_MS = 100;
+const DEFAULT_MAX_INVENTORY_ITEMS = 1_000;
+const DEFAULT_CREATION_SKEW_MS = 5_000;
+const MAX_THREAD_ID = 2_048;
+const DEFAULT_CANCELLATION_ACK_MS = 1_000;
+const ThreadSourceSchema = z.union([
+    z.enum(["cli", "vscode", "exec", "appServer", "unknown"]),
+    z.object({ custom: z.string().max(256) }),
+    z.object({ subAgent: z.unknown() }),
+]);
+const ThreadSchema = z.object({
+    id: z.string().min(1).max(MAX_THREAD_ID),
+    cwd: z.string().min(1).max(4_096),
+    source: ThreadSourceSchema,
+    createdAt: z.number().int().safe().nonnegative(),
+});
+const ThreadListResponseSchema = z.object({
+    data: z.array(ThreadSchema).max(500),
+    nextCursor: z.string().min(1).max(2_048).nullable().optional(),
+});
+function unavailable() {
+    return new ProviderError("RESUME_IDENTITY_UNAVAILABLE", "Codex resume identity is unavailable");
+}
+function positiveInteger(value, fallback) {
+    return value !== undefined && Number.isSafeInteger(value) && value > 0 ? value : fallback;
+}
+function validThreadId(id) {
+    return (id.trim().length > 0 &&
+        id.length <= MAX_THREAD_ID &&
+        !/[\p{Cc}\p{Zl}\p{Zp}]/u.test(id) &&
+        !id.trimStart().startsWith("-"));
+}
+function normalizeProtocolTimestamp(value) {
+    const milliseconds = value < 1_000_000_000_000 ? value * 1_000 : value;
+    return Number.isSafeInteger(milliseconds) && milliseconds >= 0 ? milliseconds : undefined;
+}
+function defaultSleep(milliseconds, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(unavailable());
+            return;
+        }
+        const timer = setTimeout(done, milliseconds);
+        function done() {
+            signal?.removeEventListener("abort", aborted);
+            resolve();
+        }
+        function aborted() {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", aborted);
+            reject(unavailable());
+        }
+        signal?.addEventListener("abort", aborted, { once: true });
+    });
+}
+export function resetCodexThreadResolutionCoordinatorForTests() {
+    codexThreadResolutionCoordinator.resetForTests();
+}
+class ResolverDeadline {
+    callerSignal;
+    controller = new AbortController();
+    timer;
+    abortFromCaller;
+    constructor(milliseconds, callerSignal) {
+        this.callerSignal = callerSignal;
+        if (callerSignal?.aborted) {
+            this.controller.abort();
+        }
+        else if (callerSignal) {
+            this.abortFromCaller = () => this.controller.abort();
+            callerSignal.addEventListener("abort", this.abortFromCaller, { once: true });
+        }
+        this.timer = setTimeout(() => this.controller.abort(), milliseconds);
+    }
+    get signal() {
+        return this.controller.signal;
+    }
+    run(operation) {
+        if (this.signal.aborted)
+            return Promise.reject(unavailable());
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const finish = (callback) => {
+                if (settled)
+                    return;
+                settled = true;
+                this.signal.removeEventListener("abort", aborted);
+                callback();
+            };
+            const aborted = () => finish(() => reject(unavailable()));
+            this.signal.addEventListener("abort", aborted, { once: true });
+            try {
+                Promise.resolve(operation()).then((value) => finish(() => resolve(value)), () => finish(() => reject(unavailable())));
+            }
+            catch {
+                finish(() => reject(unavailable()));
+            }
+        });
+    }
+    dispose() {
+        clearTimeout(this.timer);
+        if (this.abortFromCaller)
+            this.callerSignal?.removeEventListener("abort", this.abortFromCaller);
+    }
+}
+/** Shared assertion used by the provider's generated resume argv regression. */
+export function assertExactCodexResumeArgs(args) {
+    if (args.some((arg) => arg === "--last" || arg.startsWith("--last="))) {
+        throw new ProviderError("RESUME_IDENTITY_UNAVAILABLE", "Codex resume requires an exact safe session id");
+    }
+}
+/** Creates the bounded current-protocol `thread/list` reader used by resolver snapshots and polls. */
+export function createCodexThreadInventory(rpc, options) {
+    const maxPages = positiveInteger(options.maxPages, 20);
+    const maxItems = positiveInteger(options.maxItems, DEFAULT_MAX_INVENTORY_ITEMS);
+    return async () => {
+        if (!isAbsolute(options.cwd) || options.cwd.length > 4_096)
+            throw unavailable();
+        const entries = [];
+        const seenCursors = new Set();
+        let cursor = null;
+        try {
+            for (let page = 0; page < maxPages; page += 1) {
+                const response = await rpc.request("thread/list", {
+                    cursor,
+                    limit: 100,
+                    archived: false,
+                    cwd: options.cwd,
+                    sourceKinds: ["cli"],
+                    sortKey: "created_at",
+                    sortDirection: "desc",
+                }, ThreadListResponseSchema);
+                if (entries.length + response.data.length > maxItems)
+                    throw unavailable();
+                entries.push(...response.data);
+                const next = response.nextCursor ?? null;
+                if (next === null)
+                    return entries;
+                if (seenCursors.has(next))
+                    throw unavailable();
+                seenCursors.add(next);
+                cursor = next;
+            }
+        }
+        catch {
+            throw unavailable();
+        }
+        throw unavailable();
+    };
+}
+export class CodexThreadResolver {
+    inventory;
+    now;
+    sleep;
+    deadlineMs;
+    pollIntervalMs;
+    maxInventoryItems;
+    creationSkewMs;
+    cancellationAckMs;
+    maxPolls;
+    constructor(options) {
+        this.inventory = options.inventory;
+        this.now = options.now ?? (() => Date.now());
+        this.sleep = options.sleep ?? defaultSleep;
+        this.deadlineMs = positiveInteger(options.deadlineMs, DEFAULT_DEADLINE_MS);
+        this.pollIntervalMs = positiveInteger(options.pollIntervalMs, DEFAULT_POLL_INTERVAL_MS);
+        this.maxInventoryItems = positiveInteger(options.maxInventoryItems, DEFAULT_MAX_INVENTORY_ITEMS);
+        this.creationSkewMs = positiveInteger(options.creationSkewMs, DEFAULT_CREATION_SKEW_MS);
+        this.cancellationAckMs = positiveInteger(options.cancellationAckMs, DEFAULT_CANCELLATION_ACK_MS);
+        this.maxPolls = Math.min(10_000, Math.ceil(this.deadlineMs / this.pollIntervalMs) + 2);
+    }
+    async resolveAfterSpawn(options) {
+        if (!isAbsolute(options.cwd) ||
+            options.cwd.length > 4_096 ||
+            /[\p{Cc}\p{Zl}\p{Zp}]/u.test(options.cwd) ||
+            typeof options.spawn !== "function" ||
+            !isCodexThreadPersistence(options.persistence)) {
+            throw unavailable();
+        }
+        const deadlineAt = this.now() + this.deadlineMs;
+        const deadline = new ResolverDeadline(this.deadlineMs, options.signal);
+        let release;
+        try {
+            release = await codexThreadResolutionCoordinator.acquire(deadline.signal);
+            return await this.resolveLocked(options, deadline, deadlineAt);
+        }
+        catch {
+            throw unavailable();
+        }
+        finally {
+            release?.();
+            deadline.dispose();
+        }
+    }
+    async resolveLocked(options, deadline, deadlineAt) {
+        this.throwIfCancelled(deadline.signal);
+        const before = await this.readInventory(deadline);
+        const beforeIds = new Set(before.map((thread) => thread.id));
+        const startedAt = this.now();
+        let lease;
+        let spawnAttempted = false;
+        let completed = false;
+        try {
+            spawnAttempted = true;
+            lease = options.spawn(deadline.signal);
+            if (!lease || !(lease.started instanceof Promise) || typeof lease.cancel !== "function")
+                throw unavailable();
+            await deadline.run(() => lease.started);
+            for (let poll = 0; poll < this.maxPolls; poll += 1) {
+                this.throwIfCancelled(deadline.signal);
+                const current = await this.readInventory(deadline);
+                const observedAt = this.now();
+                if (observedAt > deadlineAt)
+                    throw unavailable();
+                const candidates = this.candidates(current, beforeIds, options.cwd, startedAt, observedAt);
+                if (candidates.length > 1)
+                    throw unavailable();
+                const candidate = candidates[0];
+                if (candidate) {
+                    try {
+                        options.persistence.markProvisional(candidate.id);
+                        this.throwIfCancelled(deadline.signal);
+                        if (this.now() > deadlineAt)
+                            throw unavailable();
+                        const fresh = await this.readInventory(deadline);
+                        const crossCheckedAt = this.now();
+                        if (crossCheckedAt > deadlineAt)
+                            throw unavailable();
+                        const crossChecked = this.candidates(fresh, beforeIds, options.cwd, startedAt, crossCheckedAt);
+                        if (crossChecked.length !== 1 || !this.sameIdentity(candidate, crossChecked[0]))
+                            throw unavailable();
+                        options.persistence.commit(candidate.id);
+                        completed = true;
+                        return candidate.id;
+                    }
+                    catch {
+                        try {
+                            options.persistence.clear(candidate.id);
+                        }
+                        catch {
+                            // The resolver still fails closed; the capability contract requires storage to mark the id unusable.
+                        }
+                        throw unavailable();
+                    }
+                }
+                const now = this.now();
+                if (now >= deadlineAt)
+                    throw unavailable();
+                try {
+                    await deadline.run(() => this.sleep(Math.min(this.pollIntervalMs, deadlineAt - now), deadline.signal));
+                }
+                catch {
+                    throw unavailable();
+                }
+            }
+            throw unavailable();
+        }
+        finally {
+            if (lease && !completed) {
+                await codexThreadResolutionCoordinator.acknowledgeCancellation(lease, this.cancellationAckMs);
+            }
+            else if (spawnAttempted && !completed) {
+                codexThreadResolutionCoordinator.poisonUnknownSpawnOutcome();
+            }
+        }
+    }
+    async readInventory(deadline) {
+        let raw;
+        try {
+            raw = await deadline.run(() => this.inventory());
+        }
+        catch {
+            throw unavailable();
+        }
+        if (!Array.isArray(raw) || raw.length > this.maxInventoryItems)
+            throw unavailable();
+        const normalized = [];
+        const ids = new Set();
+        for (const value of raw) {
+            const parsed = ThreadSchema.safeParse(value);
+            if (!parsed.success || !validThreadId(parsed.data.id) || ids.has(parsed.data.id))
+                throw unavailable();
+            const createdAtMs = normalizeProtocolTimestamp(parsed.data.createdAt);
+            if (createdAtMs === undefined)
+                throw unavailable();
+            ids.add(parsed.data.id);
+            normalized.push({
+                id: parsed.data.id,
+                cwd: parsed.data.cwd,
+                source: parsed.data.source,
+                createdAtMs,
+            });
+        }
+        return normalized;
+    }
+    candidates(inventory, beforeIds, cwd, startedAt, observedAt) {
+        const earliest = startedAt - this.creationSkewMs;
+        const latest = Math.min(startedAt + this.deadlineMs + this.creationSkewMs, observedAt + this.creationSkewMs);
+        return inventory.filter((thread) => !beforeIds.has(thread.id) &&
+            validThreadId(thread.id) &&
+            thread.cwd === cwd &&
+            thread.source === "cli" &&
+            thread.createdAtMs >= earliest &&
+            thread.createdAtMs <= latest);
+    }
+    sameIdentity(left, right) {
+        return (left.id === right.id &&
+            left.cwd === right.cwd &&
+            left.source === right.source &&
+            left.createdAtMs === right.createdAtMs);
+    }
+    throwIfCancelled(signal) {
+        if (signal?.aborted)
+            throw unavailable();
+    }
+}

package/dist/providers/options.d.ts

@@ -0,0 +1,7 @@
+import { ProviderError } from "./types.js";
+import type { ClaudeSessionOptions, ProviderId, ProviderSessionOptions } from "./types.js";
+export declare class ProviderOptionsError extends ProviderError {
+    constructor(message: string);
+}
+export declare function parseProviderOptions(provider: ProviderId, raw: unknown): ProviderSessionOptions;
+export declare function parseLegacyClaudeArgs(args: readonly string[]): ClaudeSessionOptions;

package/dist/providers/options.js

@@ -0,0 +1,155 @@
+import { z } from "zod";
+import { ProviderError } from "./types.js";
+const MAX_MODEL_LENGTH = 128;
+const MAX_PROFILE_LENGTH = 128;
+const MAX_PATH_LENGTH = 4096;
+const MAX_ADD_DIRS = 32;
+const MAX_LEGACY_ARGS = 128;
+const MAX_LEGACY_ARG_LENGTH = 4096;
+const modelToken = z
+    .string()
+    .min(1)
+    .max(MAX_MODEL_LENGTH)
+    .regex(/^[A-Za-z0-9][A-Za-z0-9._:/\u005b\u005d-]*$/, "must be a safe model token");
+const profileToken = z
+    .string()
+    .min(1)
+    .max(MAX_PROFILE_LENGTH)
+    .regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/, "must be a safe profile token");
+const effortToken = z
+    .string()
+    .min(1)
+    .max(128)
+    .regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/, "must be a safe effort token");
+const pathToken = z
+    .string()
+    .min(1)
+    .max(MAX_PATH_LENGTH)
+    .regex(/^\/[^\x00-\x1f\x7f]*$/, "must be an absolute path without control characters");
+const addDirs = z.array(pathToken).max(MAX_ADD_DIRS);
+const claudeOptionsSchema = z
+    .object({
+    model: modelToken.optional(),
+    effort: effortToken.optional(),
+    permissionMode: z.enum(["default", "acceptEdits", "plan", "bypassPermissions"]).optional(),
+    dangerouslySkip: z.boolean().optional(),
+    addDirs: addDirs.optional(),
+})
+    .strict()
+    .superRefine((options, context) => {
+    if (options.dangerouslySkip === true && options.permissionMode !== undefined) {
+        context.addIssue({
+            code: "custom",
+            message: "dangerouslySkip and permissionMode are mutually exclusive",
+        });
+    }
+});
+const codexOptionsSchema = z
+    .object({
+    model: modelToken.optional(),
+    reasoningEffort: effortToken.optional(),
+    sandbox: z.enum(["read-only", "workspace-write", "danger-full-access"]).optional(),
+    approvalPolicy: z.enum(["untrusted", "on-request", "never"]).optional(),
+    profile: profileToken.optional(),
+    webSearch: z.boolean().optional(),
+    dangerouslyBypassApprovalsAndSandbox: z.boolean().optional(),
+    addDirs: addDirs.optional(),
+})
+    .strict()
+    .superRefine((options, context) => {
+    if (options.dangerouslyBypassApprovalsAndSandbox === true &&
+        (options.sandbox !== undefined || options.approvalPolicy !== undefined)) {
+        context.addIssue({
+            code: "custom",
+            message: "dangerouslyBypassApprovalsAndSandbox is mutually exclusive with sandbox and approvalPolicy",
+        });
+    }
+});
+const legacyArgSchema = z
+    .string()
+    .max(MAX_LEGACY_ARG_LENGTH)
+    .refine((arg) => !arg.includes("\0"), {
+    message: "must not contain a null byte",
+});
+const legacyArgsSchema = z.array(legacyArgSchema).max(MAX_LEGACY_ARGS);
+export class ProviderOptionsError extends ProviderError {
+    constructor(message) {
+        super("INVALID_PROVIDER_OPTIONS", message);
+        this.name = "ProviderOptionsError";
+    }
+}
+function invalidOptions(error) {
+    const detail = error.issues.map((issue) => issue.message).join("; ");
+    return new ProviderOptionsError(`Invalid provider options: ${detail}`);
+}
+export function parseProviderOptions(provider, raw) {
+    try {
+        if (provider === "claude") {
+            return { provider, ...claudeOptionsSchema.parse(raw) };
+        }
+        if (provider === "codex") {
+            return { provider, ...codexOptionsSchema.parse(raw) };
+        }
+    }
+    catch (error) {
+        if (error instanceof z.ZodError)
+            throw invalidOptions(error);
+        throw error;
+    }
+    throw new ProviderOptionsError(`Invalid provider options: unknown provider ${String(provider)}`);
+}
+function requireValue(args, index, flag) {
+    const value = args[index + 1];
+    if (value === undefined || value.startsWith("--")) {
+        throw new ProviderOptionsError(`Invalid provider options: ${flag} requires a value`);
+    }
+    return value;
+}
+export function parseLegacyClaudeArgs(args) {
+    let parsedArgs;
+    try {
+        parsedArgs = legacyArgsSchema.parse(args);
+    }
+    catch (error) {
+        if (error instanceof z.ZodError)
+            throw invalidOptions(error);
+        throw error;
+    }
+    const raw = {};
+    const parsedAddDirs = [];
+    const legacyArgs = [];
+    for (let index = 0; index < parsedArgs.length; index += 1) {
+        const arg = parsedArgs[index];
+        if (arg === "--") {
+            legacyArgs.push(...parsedArgs.slice(index));
+            break;
+        }
+        switch (arg) {
+            case "--model":
+                raw.model = requireValue(parsedArgs, index, arg);
+                index += 1;
+                break;
+            case "--effort":
+                raw.effort = requireValue(parsedArgs, index, arg);
+                index += 1;
+                break;
+            case "--permission-mode":
+                raw.permissionMode = requireValue(parsedArgs, index, arg);
+                index += 1;
+                break;
+            case "--dangerously-skip-permissions":
+                raw.dangerouslySkip = true;
+                break;
+            case "--add-dir":
+                parsedAddDirs.push(requireValue(parsedArgs, index, arg));
+                index += 1;
+                break;
+            default:
+                legacyArgs.push(arg);
+        }
+    }
+    if (parsedAddDirs.length > 0)
+        raw.addDirs = parsedAddDirs;
+    const parsed = parseProviderOptions("claude", raw);
+    return legacyArgs.length > 0 ? { ...parsed, legacyArgs } : parsed;
+}

package/dist/providers/provider-artifacts.d.ts

@@ -0,0 +1,3 @@
+import type { ProviderProcessContext } from "./types.js";
+export declare function cleanupProviderArtifacts(paths: readonly string[]): void;
+export declare function writeProviderArtifact0600(path: string, content: string, context: ProviderProcessContext, ownedPaths: string[]): boolean;

package/dist/providers/provider-artifacts.js

@@ -0,0 +1,30 @@
+import { chmodSync, unlinkSync, writeFileSync } from "node:fs";
+export function cleanupProviderArtifacts(paths) {
+    for (const path of paths) {
+        try {
+            unlinkSync(path);
+        }
+        catch {
+            /* already gone */
+        }
+    }
+}
+export function writeProviderArtifact0600(path, content, context, ownedPaths) {
+    try {
+        context.registerCleanupPaths?.([path]);
+    }
+    catch (error) {
+        cleanupProviderArtifacts([path]);
+        throw error;
+    }
+    ownedPaths.push(path);
+    try {
+        writeFileSync(path, content, { mode: 0o600 });
+        chmodSync(path, 0o600);
+        return true;
+    }
+    catch {
+        cleanupProviderArtifacts([path]);
+        return false;
+    }
+}

package/dist/providers/registry.d.ts

@@ -0,0 +1,7 @@
+import { type AgentProvider, type ProviderId } from "./types.js";
+export declare class ProviderRegistry {
+    private readonly byId;
+    constructor(providers: readonly AgentProvider[]);
+    get(id: ProviderId): AgentProvider;
+    list(): AgentProvider[];
+}

package/dist/providers/registry.js

@@ -0,0 +1,23 @@
+import { ProviderError } from "./types.js";
+export class ProviderRegistry {
+    byId;
+    constructor(providers) {
+        const byId = new Map();
+        for (const provider of providers) {
+            if (byId.has(provider.id)) {
+                throw new ProviderError("PROVIDER_UNAVAILABLE", `duplicate provider id: ${provider.id}`);
+            }
+            byId.set(provider.id, provider);
+        }
+        this.byId = byId;
+    }
+    get(id) {
+        const provider = this.byId.get(id);
+        if (!provider)
+            throw new ProviderError("PROVIDER_UNAVAILABLE", `provider unavailable: ${id}`);
+        return provider;
+    }
+    list() {
+        return [...this.byId.values()];
+    }
+}

package/dist/providers/types.d.ts

@@ -0,0 +1,95 @@
+import type { AttachSpawnOptions } from "../config.js";
+export type ProviderId = "claude" | "codex";
+export interface ProviderAvailability {
+    terminalAvailable: boolean;
+    metadataAvailable: boolean;
+    version?: string;
+    detail?: string;
+}
+export declare class ProviderError extends Error {
+    readonly code: "PROVIDER_UNAVAILABLE" | "INVALID_PROVIDER_OPTIONS" | "RESUME_IDENTITY_UNAVAILABLE" | "OSS_PROVIDER_DEFERRED";
+    constructor(code: "PROVIDER_UNAVAILABLE" | "INVALID_PROVIDER_OPTIONS" | "RESUME_IDENTITY_UNAVAILABLE" | "OSS_PROVIDER_DEFERRED", message: string);
+}
+export type ClaudeSessionOptions = {
+    provider: "claude";
+    model?: string;
+    effort?: string;
+    permissionMode?: "default" | "acceptEdits" | "plan" | "bypassPermissions";
+    dangerouslySkip?: boolean;
+    addDirs?: string[];
+    legacyArgs?: string[];
+};
+export type CodexSessionOptions = {
+    provider: "codex";
+    model?: string;
+    reasoningEffort?: string;
+    sandbox?: "read-only" | "workspace-write" | "danger-full-access";
+    approvalPolicy?: "untrusted" | "on-request" | "never";
+    profile?: string;
+    webSearch?: boolean;
+    dangerouslyBypassApprovalsAndSandbox?: boolean;
+    addDirs?: string[];
+};
+export type ProviderSessionOptions = ClaudeSessionOptions | CodexSessionOptions;
+export type LaunchIntent = "fresh" | "resume";
+export interface ProcessSpec {
+    executable: string;
+    args: string[];
+    env: NodeJS.ProcessEnv;
+    cleanupPaths: string[];
+    /** Revalidates ephemeral launch proof immediately before the terminal process is spawned. */
+    preSpawnCheck?: () => void | Promise<void>;
+    integration?: {
+        attachments: "ready" | "degraded";
+        activity: "ready" | "degraded";
+        detail?: string;
+    };
+}
+export interface CodexProfileLaunchProof {
+    readonly profile: string;
+    readonly codexHome: string;
+    readonly assertUnchanged: () => Promise<void>;
+}
+export interface ProviderProcessContext {
+    roamSessionId: string;
+    cwd: string;
+    intent: LaunchIntent;
+    options: ProviderSessionOptions;
+    providerSessionId?: string;
+    /** Late-bound after listen so both providers share the real loopback MCP callback configuration. */
+    attach?: AttachSpawnOptions;
+    /** Transfer temporary-artifact ownership as soon as paths exist, so a later build rejection is cleanable. */
+    registerCleanupPaths?(paths: readonly string[]): void;
+}
+export type ProviderRuntimeSignal = {
+    type: "working";
+} | {
+    type: "blocked";
+} | {
+    type: "idle";
+} | {
+    type: "provider-session-id";
+    id: string;
+};
+export interface ProviderRuntimeSignalParser {
+    push(chunk: string): ProviderRuntimeSignal[];
+}
+export interface ProviderRuntimeMetadata {
+    model?: string;
+    effort?: string;
+}
+export interface AgentProvider {
+    readonly id: ProviderId;
+    readonly displayName: string;
+    readonly resumeIdentity: "optional" | "required";
+    probe(): Promise<ProviderAvailability>;
+    buildProcess(context: ProviderProcessContext): Promise<ProcessSpec>;
+    /** Stateful parsers must be created per spawned process; providers are registry singletons. */
+    createRuntimeSignalParser?(): ProviderRuntimeSignalParser;
+    runtimeSignals(chunk: string): ProviderRuntimeSignal[];
+    classifyPane(pane: string): "working" | "blocked" | "idle";
+    /** Read provider-owned live model/effort chrome from a captured pane. Optional because not every TUI
+     * exposes these values. A missing/invalid result must leave launch metadata untouched. */
+    runtimeMetadata?(pane: string): ProviderRuntimeMetadata | undefined;
+    cleanup(paths: readonly string[]): void;
+}

package/dist/providers/types.js

@@ -0,0 +1,8 @@
+export class ProviderError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "ProviderError";
+    }
+}