@haywoodmarx/agent-pager 0.1.0

package/dist/src/implementations/opencode/manifest.js

@@ -0,0 +1,93 @@
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { ATTACH_HEADER } from "../../broker/protocol.js";
+import { deliverToPagerInbox, parsePagerInboxAddress, writePagerInbox, } from "../../messaging/inbox-socket.js";
+import { implementationId } from "../registry.js";
+import { BUN_PATH_ENVIRONMENT, resolveBunExecutable } from "../../launch/runtime.js";
+import { harnessSessionKey } from "../session-key.js";
+import { OPENCODE_AGENT_ID_ENVIRONMENT, OPENCODE_BROKER_URL_ENVIRONMENT, OPENCODE_DELIVERY_RESERVATION_ENVIRONMENT, OPENCODE_MESSAGING_RESERVATION_ENVIRONMENT, } from "./environment.js";
+/**
+ * Construct the built-in OpenCode implementation provider.
+ * @param ports - Version reader, launch-file, and inbox ports.
+ * @returns - Provider owning OpenCode integration behavior.
+ */
+export function createOpenCodeImplementationProvider({ readVersion, launchFiles, writeInbox, }) {
+    const version = readVersion();
+    return {
+        descriptor: {
+            id: implementationId("opencode"),
+            displayName: "OpenCode",
+            version: version ? { known: true, value: version } : { known: false },
+            capabilities: ["launch", "notification", "session-identity"],
+        },
+        launch: {
+            supported: true,
+            buildPlan: (request) => {
+                const bunPath = launchFiles.runtimePath();
+                const configPath = launchFiles.writeLaunchConfig(JSON.stringify({
+                    $schema: "https://opencode.ai/config.json",
+                    plugin: [new URL("./plugin.js", import.meta.url).href],
+                    mcp: {
+                        pager: {
+                            type: "remote",
+                            url: request.brokerUrl,
+                            headers: { [ATTACH_HEADER]: `{env:${OPENCODE_MESSAGING_RESERVATION_ENVIRONMENT}}` },
+                        },
+                    },
+                }, null, 2));
+                return Promise.resolve({
+                    command: "opencode",
+                    args: [...request.passthroughArgs],
+                    environment: {
+                        OPENCODE_CONFIG: configPath,
+                        [OPENCODE_AGENT_ID_ENVIRONMENT]: request.agentId,
+                        [OPENCODE_BROKER_URL_ENVIRONMENT]: request.brokerUrl,
+                        [BUN_PATH_ENVIRONMENT]: bunPath,
+                    },
+                    sensitiveEnvironment: {
+                        [OPENCODE_MESSAGING_RESERVATION_ENVIRONMENT]: request.reservation,
+                        [OPENCODE_DELIVERY_RESERVATION_ENVIRONMENT]: request.deliveryReservation,
+                    },
+                    workspacePath: request.workspacePath,
+                    title: "Pager — OpenCode",
+                });
+            },
+        },
+        sessionIdentity: {
+            supported: true,
+            sessionKey: ({ environment, hostSessionId }) => harnessSessionKey("opencode", hostSessionId ?? environment.OPENCODE_SESSION_ID),
+        },
+        hostRegistration: { supported: false },
+        notification: {
+            supported: true,
+            mode: "host-push",
+            parseAddress: parsePagerInboxAddress,
+            deliver: (address, wake) => deliverToPagerInbox(writeInbox, address, wake),
+        },
+    };
+}
+function installedVersion() {
+    try {
+        return execFileSync("opencode", ["--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+function systemLaunchFilesPort() {
+    return {
+        runtimePath: () => resolveBunExecutable(),
+        writeLaunchConfig: (content) => {
+            const configPath = join(mkdtempSync(join(tmpdir(), "pager-opencode-")), "mcp-config.json");
+            writeFileSync(configPath, content);
+            return configPath;
+        },
+    };
+}
+export default createOpenCodeImplementationProvider({
+    readVersion: installedVersion,
+    launchFiles: systemLaunchFilesPort(),
+    writeInbox: writePagerInbox,
+});

package/dist/src/implementations/opencode/plugin-api.d.ts

@@ -0,0 +1,120 @@
+/** Minimal OpenCode plugin API used by the Pager implementation. */
+export type OpenCodePlugin = (context: OpenCodePluginContext) => Promise<OpenCodePluginHooks>;
+/** Supplies the OpenCode client operations used by the plugin. */
+export type OpenCodePluginContext = {
+    /** Names the session working directory used for workspace registration. */
+    directory: string;
+    /** Exposes application logging and session operations. */
+    client: {
+        /** Exposes application diagnostics. */
+        app: {
+            /** Writes one structured plugin log entry. */
+            log(input: {
+                body: {
+                    service: string;
+                    level: "info" | "warn";
+                    message: string;
+                };
+            }): Promise<unknown>;
+        };
+        /** Publishes commands to the active OpenCode TUI. */
+        tui: {
+            /** Publishes one validated TUI event in the current workspace. */
+            publish(input: {
+                body: {
+                    type: "tui.command.execute";
+                    properties: {
+                        command: "app.exit";
+                    };
+                };
+                query: {
+                    directory: string;
+                };
+            }): Promise<{
+                data?: boolean;
+                error?: unknown;
+            }>;
+        };
+        /** Adds messaging tools to a running editor session. */
+        mcp: {
+            /** Registers one remote MCP endpoint for the active workspace. */
+            add(input: {
+                body: {
+                    name: string;
+                    config: {
+                        type: "remote";
+                        url: string;
+                        headers: Record<string, string>;
+                        oauth: false;
+                    };
+                };
+                query: {
+                    directory: string;
+                };
+            }): Promise<{
+                error?: unknown;
+            }>;
+        };
+        /** Exposes session lookup and asynchronous prompt delivery. */
+        session: {
+            /** Resolves a session and its optional parent. */
+            get(input: {
+                path: {
+                    id: string;
+                };
+            }): Promise<{
+                error?: unknown;
+                data?: {
+                    id: string;
+                    parentID?: string;
+                };
+            }>;
+            /** Delivers one asynchronous system prompt to a session. */
+            promptAsync(input: {
+                path: {
+                    id: string;
+                };
+                body: {
+                    system: string;
+                    parts: Array<{
+                        type: "text";
+                        text: string;
+                    }>;
+                };
+            }): Promise<{
+                error?: unknown;
+            }>;
+        };
+    };
+};
+/** Defines one model-callable tool returned by an OpenCode plugin. */
+export type OpenCodeToolDefinition = {
+    /** Explains when and why the model should call the tool. */
+    description: string;
+    /** Defines the tool's accepted arguments. */
+    args: Record<string, never>;
+    /** Executes the tool and returns model-visible text. */
+    execute(args: Record<string, never>, context: unknown): Promise<string>;
+};
+/** Defines hooks returned to the OpenCode plugin host. */
+export type OpenCodePluginHooks = {
+    /** Publishes model-callable tools local to this plugin. */
+    tool?: Record<string, OpenCodeToolDefinition>;
+    /** Tracks a session after a user chat message. */
+    "chat.message"?: (input: {
+        sessionID: string;
+    }) => Promise<void>;
+    /** Observes session lifecycle events. */
+    event?: (input: {
+        event: {
+            type: string;
+            properties: {
+                info: {
+                    id: string;
+                };
+            };
+        };
+    }) => Promise<void>;
+    /** Releases the inbox, heartbeat, and adapter resources. */
+    dispose?: () => Promise<void>;
+};

package/dist/src/implementations/opencode/plugin-api.js

@@ -0,0 +1 @@
+export {};

package/dist/src/implementations/opencode/plugin.d.ts

@@ -0,0 +1,38 @@
+import type { RuntimeEnvironment } from "../../launch/environment.js";
+import { type BrokerEndpoints } from "../../launch/on-demand.js";
+import { type PagerInboxOpener } from "../../messaging/inbox-socket.js";
+import type { OpenCodePlugin } from "./plugin-api.js";
+/** Owns repeating background work so a host or a test decides when it runs. */
+export interface PluginScheduler {
+    /**
+     * Start repeating work until the returned cancellation runs.
+     * @param intervalMs - Delay between attempts in milliseconds.
+     * @param task - Work invoked on each attempt.
+     * @returns - Cancellation that stops further attempts.
+     */
+    repeat(intervalMs: number, task: () => void): () => void;
+}
+/** Names every collaborator the editor-hosted plugin uses. */
+export type PluginDependencies = {
+    /** Resolves user configuration without depending on the editor's working directory. */
+    readEnvironment(): RuntimeEnvironment;
+    /** Adopts or starts the shared broker service. */
+    ensureService(environment: RuntimeEnvironment): Promise<BrokerEndpoints>;
+    /** Supplies the launch identity and heartbeat policy published by the launching process. */
+    processEnv: NodeJS.ProcessEnv;
+    /** Performs one broker HTTP request. */
+    fetch(url: string, init: RequestInit): Promise<Response>;
+    /** Owns the attachment heartbeat cadence. */
+    scheduler: PluginScheduler;
+    /** Opens the inbox the broker pushes this session's deliveries to. */
+    openInbox: PagerInboxOpener;
+};
+/**
+ * Construct the broker-backed plugin around explicit service discovery dependencies.
+ * @param dependencies - Configuration and on-demand service operations used before adapter startup.
+ * @returns - OpenCode plugin that prefers launch identity and otherwise self-registers lazily.
+ */
+export declare function createAgentMessagingPlugin(dependencies: PluginDependencies): OpenCodePlugin;
+/** Broker-backed OpenCode implementation plugin. */
+export declare const AgentMessagingPlugin: OpenCodePlugin;
+export default AgentMessagingPlugin;

package/dist/src/implementations/opencode/plugin.js

@@ -0,0 +1,303 @@
+import { tmpdir } from "node:os";
+import { ATTACH_HEADER, isAgentId } from "../../broker/protocol.js";
+import { adapterHeartbeatIntervalMs } from "../../configuration-defaults.js";
+import { implementationId } from "../registry.js";
+import { ensureBrokerService } from "../../launch/on-demand.js";
+import { readEmbeddedRuntimeEnvironment, resolveBunExecutable } from "../../launch/runtime.js";
+import { BrokerDeliveryClient, exactRecord, registerAgent } from "../../messaging/delivery-client.js";
+import { openPagerInbox } from "../../messaging/inbox-socket.js";
+import { OpenCodeInboundAdapter } from "./adapter.js";
+import { createOpenCodeSelfCloseTool } from "./self-close-tool.js";
+import { harnessSessionKey } from "../session-key.js";
+import { OPENCODE_AGENT_ID_ENVIRONMENT, OPENCODE_BROKER_URL_ENVIRONMENT, OPENCODE_DELIVERY_RESERVATION_ENVIRONMENT, } from "./environment.js";
+/**
+ * Construct the broker-backed plugin around explicit service discovery dependencies.
+ * @param dependencies - Configuration and on-demand service operations used before adapter startup.
+ * @returns - OpenCode plugin that prefers launch identity and otherwise self-registers lazily.
+ */
+export function createAgentMessagingPlugin(dependencies) {
+    return async (context) => {
+        const { client } = context;
+        let stopRuntime = () => { };
+        const localHooks = {
+            tool: {
+                close_opencode_session: createOpenCodeSelfCloseTool(client, context.directory, () => {
+                    stopRuntime();
+                }),
+            },
+        };
+        const environmentBrokerUrl = dependencies.processEnv[OPENCODE_BROKER_URL_ENVIRONMENT];
+        const environmentReservation = dependencies.processEnv[OPENCODE_DELIVERY_RESERVATION_ENVIRONMENT];
+        const environmentAgentId = dependencies.processEnv[OPENCODE_AGENT_ID_ENVIRONMENT];
+        const launchIdentityPresent = Boolean(environmentBrokerUrl || environmentReservation || environmentAgentId);
+        let brokerUrl;
+        let reservation;
+        let agentId;
+        let identityPath;
+        if (launchIdentityPresent) {
+            if (!environmentBrokerUrl || !environmentReservation || !isAgentId(environmentAgentId)) {
+                await log(client, "warn", "Broker adapter is inactive because launch identity is incomplete.");
+                return localHooks;
+            }
+            brokerUrl = environmentBrokerUrl;
+            reservation = environmentReservation;
+            agentId = environmentAgentId;
+            identityPath = "launch";
+        }
+        else {
+            try {
+                brokerUrl = (await dependencies.ensureService(dependencies.readEnvironment())).mcpUrl;
+                identityPath = "self-registration";
+            }
+            catch (error) {
+                await log(client, "warn", error instanceof Error ? error.message : "Broker service could not be started");
+                return localHooks;
+            }
+        }
+        await log(client, "info", `Broker-backed OpenCode adapter configured through ${identityPath}.`);
+        let adapter;
+        let deliveryClient;
+        let connecting;
+        let inbox;
+        let inboxOpening;
+        // Concurrent chat turns share one self-registration: a second registration for the same
+        // conversation displaces the first's reservations, and the messaging one is single-use.
+        let registering;
+        const selfRegister = async (sessionName) => {
+            const sessionKey = harnessSessionKey(implementationId("opencode"), sessionName);
+            const registered = await registerAgent((input, init) => dependencies.fetch(input, init), brokerUrl, {
+                workspacePath: context.directory,
+                implementationId: implementationId("opencode"),
+                sessionName,
+                ...(sessionKey ? { sessionKey } : {}),
+            });
+            const added = await client.mcp.add({
+                body: {
+                    name: "pager",
+                    config: {
+                        type: "remote",
+                        url: brokerUrl,
+                        headers: { [ATTACH_HEADER]: registered.messagingReservation },
+                        oauth: false,
+                    },
+                },
+                query: { directory: context.directory },
+            });
+            if (added.error)
+                throw new Error("Broker messaging tools could not be added");
+            reservation = registered.deliveryReservation;
+            agentId = registered.agentId;
+        };
+        const initializeIdentity = async (sessionName) => {
+            if (adapter)
+                return adapter;
+            if (!reservation || !agentId) {
+                registering ??= selfRegister(sessionName).catch((error) => {
+                    registering = undefined;
+                    throw error;
+                });
+                await registering;
+            }
+            else {
+                await claimConversation(sessionName);
+            }
+            adapter = new OpenCodeInboundAdapter({
+                resolveSession: async (sessionId) => {
+                    const result = await client.session.get({ path: { id: sessionId } });
+                    return result.error ? undefined : result.data;
+                },
+                prompt: async (sessionId, system, text) => {
+                    const result = await client.session.promptAsync({
+                        path: { id: sessionId },
+                        body: { system, parts: [{ type: "text", text }] },
+                    });
+                    if (result.error)
+                        throw new Error(JSON.stringify(result.error));
+                },
+            });
+            return adapter;
+        };
+        /**
+         * Tell the broker which conversation a launched identity belongs to, once it is connected.
+         *
+         * OpenCode attaches the messaging channel itself from a config file written before this
+         * conversation existed, so the key cannot ride along at attach time the way it does elsewhere. When
+         * the key already belongs to an identity, the broker hands back fresh attachments for it and this
+         * process moves across, replacing the messaging server the launch configured.
+         * @param sessionName - Conversation identifier reported by OpenCode.
+         */
+        const claimConversation = async (sessionName) => {
+            const sessionKey = harnessSessionKey(implementationId("opencode"), sessionName);
+            if (!sessionKey)
+                return;
+            const claimed = adoptionResult(await call("adopt_session_key", { sessionKey }));
+            if (!claimed.adopted)
+                return;
+            const added = await client.mcp.add({
+                body: {
+                    name: "pager",
+                    config: {
+                        type: "remote",
+                        url: brokerUrl,
+                        headers: { [ATTACH_HEADER]: claimed.reservation },
+                        oauth: false,
+                    },
+                },
+                query: { directory: context.directory },
+            });
+            if (added.error)
+                throw new Error("Broker messaging tools could not be moved to the resumed identity");
+            reservation = claimed.deliveryReservation;
+            agentId = claimed.agentId;
+            deliveryClient = undefined;
+            connecting = undefined;
+        };
+        const connectDeliveryClient = async () => {
+            if (deliveryClient)
+                return deliveryClient;
+            if (!reservation || !agentId)
+                throw new Error("Broker identity has not registered");
+            const identity = agentId;
+            const attachReservation = reservation;
+            connecting ??= BrokerDeliveryClient.attach({
+                brokerUrl,
+                agentId: identity,
+                reservation: attachReservation,
+                request: (input, init) => dependencies.fetch(input, init),
+            })
+                .then((connected) => {
+                if (inbox)
+                    connected.presentDeliveryAddress(inbox.address);
+                deliveryClient = connected;
+                return connected;
+            })
+                .finally(() => {
+                connecting = undefined;
+            });
+            return connecting;
+        };
+        const call = async (tool, args) => {
+            const connected = await connectDeliveryClient();
+            return connected.call(tool, args);
+        };
+        /**
+         * Open the inbox once a session can take deliveries, and register it with the broker at once.
+         *
+         * A failure is reported and not retried: the session keeps its messaging tools but receives no
+         * delivery, and its messages wait for a later session.
+         */
+        const openInbox = async () => {
+            inboxOpening ??= (async () => {
+                const deliver = (content) => adapter ? adapter.deliver(content) : Promise.reject(new Error("No OpenCode session is tracked"));
+                let opened;
+                try {
+                    opened = await dependencies.openInbox(deliver);
+                }
+                catch (error) {
+                    await log(client, "warn", `Pager inbox could not be opened, so this session receives no messages: ${error instanceof Error ? error.message : String(error)}`);
+                    return;
+                }
+                // dispose() may have run and closed nothing while this open was still in flight, since it
+                // could only close the inbox this assignment is about to publish; close it now instead of
+                // leaking the socket and its temporary directory for the rest of the process.
+                if (runtimeStopped) {
+                    opened.close();
+                    return;
+                }
+                inbox = opened;
+                const connected = await connectDeliveryClient();
+                connected.presentDeliveryAddress(inbox.address);
+                await connected.heartbeat();
+            })();
+            await inboxOpening;
+        };
+        const logFailure = (error) => log(client, "warn", error instanceof Error ? error.message : "Broker request failed");
+        const stopHeartbeat = dependencies.scheduler.repeat(adapterHeartbeatIntervalMs(dependencies.processEnv), () => {
+            if (reservation && agentId)
+                void connectDeliveryClient()
+                    .then((connected) => connected.heartbeat())
+                    .catch(logFailure);
+        });
+        let runtimeStopped = false;
+        stopRuntime = () => {
+            if (runtimeStopped)
+                return;
+            runtimeStopped = true;
+            stopHeartbeat();
+            adapter?.stop();
+            inbox?.close();
+        };
+        // A launched identity is held from the moment OpenCode's MCP client attaches its messaging channel,
+        // before any chat turn, so the delivery channel this plugin ends it over is attached now too.
+        if (identityPath === "launch")
+            void connectDeliveryClient().catch(logFailure);
+        return {
+            ...localHooks,
+            "chat.message": async ({ sessionID }) => {
+                try {
+                    const activeAdapter = await initializeIdentity(sessionID);
+                    await activeAdapter.trackSession(sessionID);
+                    if (activeAdapter.currentSession())
+                        await openInbox();
+                }
+                catch (error) {
+                    await logFailure(error);
+                }
+            },
+            event: ({ event }) => {
+                if (event.type === "session.deleted")
+                    adapter?.removeSession(event.properties.info.id);
+                return Promise.resolve();
+            },
+            dispose: async () => {
+                stopRuntime();
+                // Ends the messaging attachment too, which this plugin does not hold. A failed notice leaves the
+                // lease to lapse, as after a crash.
+                const connected = await (connecting ?? Promise.resolve(deliveryClient)).catch(() => undefined);
+                await connected?.detach().catch(() => undefined);
+            },
+        };
+    };
+}
+const defaultDependencies = {
+    readEnvironment: () => readEmbeddedRuntimeEnvironment(process.env, resolveBunExecutable),
+    ensureService: (environment) => ensureBrokerService(environment),
+    processEnv: process.env,
+    fetch: (url, init) => globalThis.fetch(url, init),
+    scheduler: {
+        repeat: (intervalMs, task) => {
+            const handle = setInterval(task, intervalMs);
+            return () => {
+                clearInterval(handle);
+            };
+        },
+    },
+    openInbox: (accept) => openPagerInbox(accept, tmpdir()),
+};
+/** Broker-backed OpenCode implementation plugin. */
+export const AgentMessagingPlugin = createAgentMessagingPlugin(defaultDependencies);
+function adoptionResult(value) {
+    const result = exactRecord(value, "Broker session-key adoption result", [
+        "adopted",
+        "agentId",
+        "reservation",
+        "deliveryReservation",
+    ]);
+    if (result.adopted !== true)
+        return { adopted: false };
+    if (!isAgentId(result.agentId) ||
+        typeof result.reservation !== "string" ||
+        typeof result.deliveryReservation !== "string") {
+        throw new Error("Broker session-key adoption returned an invalid identity");
+    }
+    return {
+        adopted: true,
+        agentId: result.agentId,
+        reservation: result.reservation,
+        deliveryReservation: result.deliveryReservation,
+    };
+}
+function log(client, level, message) {
+    return client.app.log({ body: { service: "pager", level, message } }).then(() => undefined);
+}
+export default AgentMessagingPlugin;

package/dist/src/implementations/opencode/self-close-tool.d.ts

@@ -0,0 +1,9 @@
+import type { OpenCodePluginContext, OpenCodeToolDefinition } from "./plugin-api.js";
+/**
+ * Construct the OpenCode-local tool that requests the host TUI's orderly exit command.
+ * @param client - OpenCode client that publishes TUI commands.
+ * @param directory - Workspace whose TUI receives the exit command.
+ * @param beforeShutdown - Synchronous cleanup that prevents plugin work from delaying exit.
+ * @returns - Argument-free model tool that coalesces concurrent shutdown requests.
+ */
+export declare function createOpenCodeSelfCloseTool(client: OpenCodePluginContext["client"], directory: string, beforeShutdown: () => void): OpenCodeToolDefinition;

package/dist/src/implementations/opencode/self-close-tool.js

@@ -0,0 +1,31 @@
+/**
+ * Construct the OpenCode-local tool that requests the host TUI's orderly exit command.
+ * @param client - OpenCode client that publishes TUI commands.
+ * @param directory - Workspace whose TUI receives the exit command.
+ * @param beforeShutdown - Synchronous cleanup that prevents plugin work from delaying exit.
+ * @returns - Argument-free model tool that coalesces concurrent shutdown requests.
+ */
+export function createOpenCodeSelfCloseTool(client, directory, beforeShutdown) {
+    let closing;
+    return {
+        description: "Gracefully close this OpenCode session after assigned work is complete and no further response is needed.",
+        args: {},
+        execute: () => {
+            closing ??= requestOpenCodeExit(client, directory, beforeShutdown).catch((error) => {
+                closing = undefined;
+                throw error;
+            });
+            return closing;
+        },
+    };
+}
+async function requestOpenCodeExit(client, directory, beforeShutdown) {
+    beforeShutdown();
+    const result = await client.tui.publish({
+        body: { type: "tui.command.execute", properties: { command: "app.exit" } },
+        query: { directory },
+    });
+    if (result.error || result.data !== true)
+        throw new Error("OpenCode rejected its graceful exit command");
+    return "Graceful OpenCode shutdown requested.";
+}

package/dist/src/implementations/orca/terminal.d.ts

@@ -0,0 +1,48 @@
+import type { ForegroundProcessSpawner, TerminalLaunch, TerminalProvider, TerminalSession } from "../../launch/launch.js";
+/** Identifies the kind of terminal operation this provider recorded. */
+export type OrcaOperationType = "terminal_create" | "task_complete" | "terminal_reuse";
+/** Launch terminal plans through the Orca terminal client. */
+export declare class OrcaTerminalProvider implements TerminalProvider {
+    #private;
+    /** Identifies this terminal provider. */
+    readonly name = "orca";
+    /** Prefers the externally hosted terminal over inherited local stdio. */
+    readonly interactivePriority = 100;
+    /**
+     * Construct the provider around an explicit Orca executable.
+     * @param options - `command` is the Orca executable. A `currentTerminalHandle` makes launches run as a
+     * foreground child of this process through `spawnProcess` instead of creating a terminal.
+     * `handoffRoot` holds the owner-only environment files and defaults to a fresh temporary directory.
+     */
+    constructor(options: {
+        command: string;
+        currentTerminalHandle?: string;
+        handoffRoot?: string;
+        spawnProcess: ForegroundProcessSpawner;
+    });
+    /**
+     * Report every terminal operation this provider has recorded.
+     * @returns - Operations in the order they occurred.
+     */
+    get operations(): ReadonlyArray<{
+        type: OrcaOperationType;
+        detail: unknown;
+    }>;
+    /**
+     * Report whether the configured terminal executable can answer locally.
+     * @returns - Whether the provider executable is present and runnable.
+     */
+    available(): Promise<boolean>;
+    /**
+     * Launch one implementation-owned plan in an Orca terminal.
+     * @param request - Neutral terminal launch request.
+     * @returns - Started terminal session and explicit controls.
+     */
+    launch(request: TerminalLaunch): Promise<TerminalSession>;
+}
+/**
+ * Construct the terminal provider from process configuration owned by this implementation.
+ * @param environment - Process environment carrying the optional Orca executable override.
+ * @returns - Configured Orca terminal provider.
+ */
+export declare function createTerminalProvider(environment: NodeJS.ProcessEnv): TerminalProvider;