@haywoodmarx/agent-pager 0.1.0

package/dist/src/implementations/orca/terminal.js

@@ -0,0 +1,154 @@
+import { execFile } from "node:child_process";
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { ProtocolError } from "../../broker/protocol.js";
+import { isPlainObject } from "../../shared/guards.js";
+import { shellQuote } from "../../shared/shell.js";
+import { spawnForegroundProcess, spawnInheritedSession } from "../../launch/terminal.js";
+const execFileAsync = promisify(execFile);
+/** Launch terminal plans through the Orca terminal client. */
+export class OrcaTerminalProvider {
+    /** Identifies this terminal provider. */
+    name = "orca";
+    /** Prefers the externally hosted terminal over inherited local stdio. */
+    interactivePriority = 100;
+    #operations = [];
+    #command;
+    #currentTerminalHandle;
+    #handoffRoot;
+    #spawnProcess;
+    /**
+     * 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) {
+        this.#command = options.command;
+        this.#currentTerminalHandle = options.currentTerminalHandle;
+        this.#handoffRoot = options.handoffRoot;
+        this.#spawnProcess = options.spawnProcess;
+    }
+    /**
+     * Report every terminal operation this provider has recorded.
+     * @returns - Operations in the order they occurred.
+     */
+    get operations() {
+        return this.#operations;
+    }
+    /**
+     * Report whether the configured terminal executable can answer locally.
+     * @returns - Whether the provider executable is present and runnable.
+     */
+    async available() {
+        try {
+            await execFileAsync(this.#command, ["status", "--json"]);
+            return true;
+        }
+        catch (error) {
+            return (typeof error === "object" &&
+                error !== null &&
+                "stdout" in error &&
+                typeof error.stdout === "string" &&
+                error.stdout.length > 0);
+        }
+    }
+    /**
+     * Launch one implementation-owned plan in an Orca terminal.
+     * @param request - Neutral terminal launch request.
+     * @returns - Started terminal session and explicit controls.
+     */
+    async launch(request) {
+        if (this.#currentTerminalHandle)
+            return this.#launchInCurrentTerminal(request, this.#currentTerminalHandle);
+        const handoffDirectory = this.#handoffRoot ?? mkdtempSync(join(tmpdir(), "pager-terminal-"));
+        mkdirSync(handoffDirectory, { recursive: true });
+        const environmentPath = join(handoffDirectory, `${safeFileName(request.agentId)}.env`);
+        // Sensitive environment values are handed off through this mode-0600 file sourced inside the
+        // pane, never through the terminal creation command or diagnostics.
+        writeFileSync(environmentPath, sensitiveEnvironmentFile(request.plan.sensitiveEnvironment), { mode: 0o600 });
+        const command = [
+            ...Object.entries(request.plan.environment).map(([key, value]) => `${safeEnvironmentKey(key)}=${shellQuote(value)}`),
+            shellQuote(request.plan.command),
+            ...request.plan.args.map((argument) => shellQuote(argument)),
+        ].join(" ");
+        const shellCommand = [
+            `cd ${shellQuote(request.plan.workspacePath)}`,
+            `. ${shellQuote(environmentPath)}`,
+            command,
+        ].join(" && ");
+        const { stdout } = await execFileAsync(this.#command, [
+            "terminal",
+            "create",
+            "--worktree",
+            "active",
+            "--title",
+            request.plan.title,
+            "--command",
+            shellCommand,
+            "--json",
+        ]);
+        const parsed = JSON.parse(stdout);
+        const result = isPlainObject(parsed) ? parsed.result : undefined;
+        const terminal = isPlainObject(result) ? result.terminal : undefined;
+        const handle = isPlainObject(terminal) ? terminal.handle : undefined;
+        if (typeof handle !== "string" || handle.length === 0) {
+            throw new ProtocolError("validation_failed", "terminal creation did not return a handle");
+        }
+        this.#operations.push({
+            type: "terminal_create",
+            detail: { agentId: request.agentId, handle, command: request.plan.command },
+        });
+        return {
+            provider: this.name,
+            taskCompletion: {
+                supported: true,
+                run: (taskId) => {
+                    this.#operations.push({ type: "task_complete", detail: { agentId: request.agentId, taskId } });
+                    return Promise.resolve();
+                },
+            },
+        };
+    }
+    #launchInCurrentTerminal(request, handle) {
+        const { child, exit } = spawnInheritedSession(this.#spawnProcess, request);
+        this.#operations.push({
+            type: "terminal_reuse",
+            detail: { agentId: request.agentId, handle, command: request.plan.command },
+        });
+        return Promise.resolve({
+            provider: this.name,
+            ...(child.pid === undefined ? {} : { pid: child.pid }),
+            taskCompletion: { supported: false },
+            exit,
+        });
+    }
+}
+/**
+ * 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 function createTerminalProvider(environment) {
+    return new OrcaTerminalProvider({
+        command: environment.ORCA_CLI_COMMAND ?? "orca",
+        ...(environment.ORCA_TERMINAL_HANDLE ? { currentTerminalHandle: environment.ORCA_TERMINAL_HANDLE } : {}),
+        spawnProcess: spawnForegroundProcess,
+    });
+}
+function sensitiveEnvironmentFile(environment) {
+    return `${Object.entries(environment)
+        .map(([key, value]) => `export ${safeEnvironmentKey(key)}=${shellQuote(value)}`)
+        .join("\n")}\n`;
+}
+function safeEnvironmentKey(value) {
+    if (!/^[A-Z_][A-Z0-9_]*$/u.test(value)) {
+        throw new ProtocolError("validation_failed", "implementation supplied an invalid environment key");
+    }
+    return value;
+}
+function safeFileName(value) {
+    return value.replace(/[^A-Za-z0-9_.-]/gu, "_");
+}

package/dist/src/implementations/pi/broker-client.d.ts

@@ -0,0 +1,56 @@
+import { type AgentId } from "../../broker/protocol.js";
+import { type BrokerIdentity, type BrokerRequest } from "../../messaging/delivery-client.js";
+/** Options for {@link registerPiAgent}. */
+export type RegisterPiAgentOptions = {
+    /** HTTP operation used to reach the loopback broker. */
+    request: BrokerRequest;
+    /** Shared broker MCP endpoint. */
+    brokerUrl: string;
+    /** Absolute Pi working directory. */
+    workspacePath: string;
+    /** Stable Pi session identity used as the initial alias. */
+    sessionName: string;
+    /** Resumable key that rejoins this conversation's identity after a restart. */
+    sessionKey?: string | undefined;
+};
+/**
+ * Register a directly started Pi session through the unauthenticated broker boundary.
+ * @param options - Broker request seam, endpoint, and the Pi session's registration identity.
+ * @returns - Registered identity with separate messaging and delivery attachments.
+ */
+export declare function registerPiAgent({ request, brokerUrl, workspacePath, sessionName, sessionKey, }: RegisterPiAgentOptions): Promise<BrokerIdentity>;
+/** Authenticated messaging and delivery operations used by the Pi extension. */
+export declare class PiBrokerClient {
+    #private;
+    private constructor();
+    /**
+     * Consume a Pi identity's messaging and delivery reservations.
+     * @param brokerUrl - Shared broker MCP endpoint.
+     * @param identity - Reserved or directly registered broker identity.
+     * @param request - HTTP operation used to reach the loopback broker.
+     * @param sessionKey - Resumable conversation key, which the broker may resolve to another identity.
+     * @returns - Connected client whose identity is the one the broker resolved, not the one requested.
+     */
+    static connect(brokerUrl: string, identity: BrokerIdentity, request: BrokerRequest, sessionKey?: string): Promise<PiBrokerClient>;
+    /**
+     * Invoke one model-callable Pager MCP tool.
+     * @param name - Public MCP tool name.
+     * @param args - Validated Pi tool arguments.
+     * @returns - Decoded broker tool result.
+     */
+    callTool(name: string, args: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Present an inbox address on every later delivery-channel request, including each heartbeat.
+     * @param address - Address text the session's inbox produced.
+     */
+    presentDeliveryAddress(address: string): void;
+    /** Renew both independently fenced broker attachment leases. */
+    heartbeat(): Promise<void>;
+    /** Tell the broker Pi is shutting down, ending both attachments so the session name is free at once. */
+    detach(): Promise<void>;
+    /**
+     * Return the authenticated broker identity.
+     * @returns - Identity the broker resolved, which differs from the requested one after adoption.
+     */
+    agentId(): AgentId;
+}

package/dist/src/implementations/pi/broker-client.js

@@ -0,0 +1,156 @@
+import { ATTACH_HEADER, isAgentId } from "../../broker/protocol.js";
+import { adoptRotation, asRecord, BrokerDeliveryClient, exactRecord, registerAgent, rpcEnvelope, } from "../../messaging/delivery-client.js";
+import { PAGER_VERSION } from "../../version.js";
+/**
+ * Register a directly started Pi session through the unauthenticated broker boundary.
+ * @param options - Broker request seam, endpoint, and the Pi session's registration identity.
+ * @returns - Registered identity with separate messaging and delivery attachments.
+ */
+export async function registerPiAgent({ request, brokerUrl, workspacePath, sessionName, sessionKey, }) {
+    return registerAgent(request, brokerUrl, {
+        workspacePath,
+        implementationId: "pi",
+        sessionName,
+        ...(sessionKey ? { sessionKey } : {}),
+    });
+}
+/** Authenticated messaging and delivery operations used by the Pi extension. */
+export class PiBrokerClient {
+    #brokerUrl;
+    #agentId;
+    #request;
+    #messaging;
+    #delivery;
+    constructor(brokerUrl, agentId, request, messaging, delivery) {
+        this.#brokerUrl = brokerUrl;
+        this.#agentId = agentId;
+        this.#request = request;
+        this.#messaging = messaging;
+        this.#delivery = delivery;
+    }
+    /**
+     * Consume a Pi identity's messaging and delivery reservations.
+     * @param brokerUrl - Shared broker MCP endpoint.
+     * @param identity - Reserved or directly registered broker identity.
+     * @param request - HTTP operation used to reach the loopback broker.
+     * @param sessionKey - Resumable conversation key, which the broker may resolve to another identity.
+     * @returns - Connected client whose identity is the one the broker resolved, not the one requested.
+     */
+    static async connect(brokerUrl, identity, request, sessionKey) {
+        const messaging = await initializeMessaging(request, brokerUrl, identity.messagingReservation, sessionKey);
+        const delivery = await BrokerDeliveryClient.attach({
+            brokerUrl,
+            agentId: identity.agentId,
+            reservation: identity.deliveryReservation,
+            request,
+            sessionKey,
+        });
+        return new PiBrokerClient(brokerUrl, messaging.agentId ?? delivery.agentId(), request, messaging, delivery);
+    }
+    /**
+     * Invoke one model-callable Pager MCP tool.
+     * @param name - Public MCP tool name.
+     * @param args - Validated Pi tool arguments.
+     * @returns - Decoded broker tool result.
+     */
+    async callTool(name, args) {
+        const response = await this.#request(this.#brokerUrl, {
+            method: "POST",
+            headers: messagingHeaders(this.#messaging),
+            body: JSON.stringify({
+                jsonrpc: "2.0",
+                id: crypto.randomUUID(),
+                method: "tools/call",
+                params: { name, arguments: args },
+            }),
+        });
+        this.#messaging = adoptRotation(this.#messaging, response);
+        const envelope = await rpcEnvelope(response, "Broker MCP tool call");
+        const result = exactRecord(envelope.result, "Broker MCP tool result", ["content", "isError"]);
+        if (!Array.isArray(result.content) || result.content.length !== 1) {
+            throw new Error("Broker MCP tool result has invalid content");
+        }
+        const content = exactRecord(result.content[0], "Broker MCP tool content", ["type", "text"]);
+        if (content.type !== "text" || typeof content.text !== "string") {
+            throw new Error("Broker MCP tool result has invalid text content");
+        }
+        const decoded = JSON.parse(content.text);
+        if (result.isError === true) {
+            const failure = asRecord(decoded);
+            throw new Error(typeof failure?.message === "string" ? failure.message : "Broker MCP tool failed");
+        }
+        return decoded;
+    }
+    /**
+     * Present an inbox address on every later delivery-channel request, including each heartbeat.
+     * @param address - Address text the session's inbox produced.
+     */
+    presentDeliveryAddress(address) {
+        this.#delivery.presentDeliveryAddress(address);
+    }
+    /** Renew both independently fenced broker attachment leases. */
+    async heartbeat() {
+        await Promise.all([this.callTool("whoami", {}), this.#delivery.heartbeat()]);
+    }
+    /** Tell the broker Pi is shutting down, ending both attachments so the session name is free at once. */
+    async detach() {
+        await this.#delivery.detach();
+    }
+    /**
+     * Return the authenticated broker identity.
+     * @returns - Identity the broker resolved, which differs from the requested one after adoption.
+     */
+    agentId() {
+        return this.#agentId;
+    }
+}
+async function initializeMessaging(request, brokerUrl, reservation, sessionKey) {
+    const response = await request(brokerUrl, {
+        method: "POST",
+        headers: attachHeaders(reservation, sessionKey),
+        body: JSON.stringify({
+            jsonrpc: "2.0",
+            id: crypto.randomUUID(),
+            method: "initialize",
+            params: {
+                protocolVersion: "2025-03-26",
+                capabilities: {},
+                clientInfo: { name: "pager-pi", version: PAGER_VERSION },
+            },
+        }),
+    });
+    await rpcEnvelope(response, "Broker MCP initialization");
+    const session = messagingSession(response);
+    const initialized = await request(brokerUrl, {
+        method: "POST",
+        headers: messagingHeaders(session),
+        body: JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" }),
+    });
+    if (!initialized.ok)
+        throw new Error(`Broker MCP initialization acknowledgement failed (${String(initialized.status)})`);
+    return adoptRotation(session, initialized);
+}
+function messagingSession(response) {
+    const sessionId = response.headers.get("mcp-session-id");
+    const epoch = response.headers.get("x-pager-epoch");
+    const resumeToken = response.headers.get("x-pager-resume-token");
+    const agentId = response.headers.get("x-pager-agent-id");
+    if (!sessionId || !epoch || !resumeToken)
+        throw new Error("Broker attachment omitted session headers");
+    return { sessionId, epoch, resumeToken, ...(isAgentId(agentId) ? { agentId } : {}) };
+}
+function attachHeaders(reservation, sessionKey) {
+    return {
+        "content-type": "application/json",
+        [ATTACH_HEADER]: reservation,
+        ...(sessionKey ? { "x-pager-session-key": sessionKey } : {}),
+    };
+}
+function messagingHeaders(session) {
+    return {
+        "content-type": "application/json",
+        "mcp-session-id": session.sessionId,
+        "x-pager-epoch": session.epoch,
+        ...(session.resumeToken ? { "x-pager-resume-token": session.resumeToken } : {}),
+    };
+}

package/dist/src/implementations/pi/environment.d.ts

@@ -0,0 +1,8 @@
+/** Names the broker endpoint supplied to the Pi extension. */
+export declare const PI_BROKER_URL_ENVIRONMENT = "PAGER_MCP_URL";
+/** Names the reserved broker identity supplied to the Pi extension. */
+export declare const PI_AGENT_ID_ENVIRONMENT = "PAGER_AGENT_ID";
+/** Names the single-use messaging attachment supplied to the Pi extension. */
+export declare const PI_MESSAGING_RESERVATION_ENVIRONMENT = "PAGER_PI_MESSAGING_ATTACH_RESERVATION";
+/** Names the single-use delivery attachment supplied to the Pi extension. */
+export declare const PI_DELIVERY_RESERVATION_ENVIRONMENT = "PAGER_PI_DELIVERY_ATTACH_RESERVATION";

package/dist/src/implementations/pi/environment.js

@@ -0,0 +1,9 @@
+import { PAGER_AGENT_ID_ENVIRONMENT, PAGER_MCP_URL_ENVIRONMENT } from "../../launch/environment.js";
+/** Names the broker endpoint supplied to the Pi extension. */
+export const PI_BROKER_URL_ENVIRONMENT = PAGER_MCP_URL_ENVIRONMENT;
+/** Names the reserved broker identity supplied to the Pi extension. */
+export const PI_AGENT_ID_ENVIRONMENT = PAGER_AGENT_ID_ENVIRONMENT;
+/** Names the single-use messaging attachment supplied to the Pi extension. */
+export const PI_MESSAGING_RESERVATION_ENVIRONMENT = "PAGER_PI_MESSAGING_ATTACH_RESERVATION";
+/** Names the single-use delivery attachment supplied to the Pi extension. */
+export const PI_DELIVERY_RESERVATION_ENVIRONMENT = "PAGER_PI_DELIVERY_ATTACH_RESERVATION";

package/dist/src/implementations/pi/extension.d.ts

@@ -0,0 +1,57 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { RuntimeEnvironment } from "../../launch/environment.js";
+import { type BrokerEndpoints } from "../../launch/on-demand.js";
+import { type PagerInbox, type PagerInboxOpener } from "../../messaging/inbox-socket.js";
+import { PiBrokerClient } from "./broker-client.js";
+import type { BrokerRequest } from "../../messaging/delivery-client.js";
+import { type PiHostSlot } from "./host-slots.js";
+type ScheduledTask = {
+    cancel(): void;
+};
+type PiExtensionRuntime = {
+    client?: PiBrokerClient;
+    connectionKey?: string;
+    directCwd: string | undefined;
+    inbox?: PagerInbox;
+    /** Set once opening the inbox failed; the process then receives no deliveries, and is not retried. */
+    inboxFailed?: true;
+    /** Injects one delivery into the current session; absent between sessions. */
+    inject?: (content: string) => void;
+    tasks: ScheduledTask[];
+};
+/** Owns repeating background work started by the Pi extension. */
+export interface PiExtensionScheduler {
+    /**
+     * Start repeating work until cancellation.
+     * @param intervalMs - Period between invocations in milliseconds.
+     * @param task - Invoked without being awaited, so a task that starts asynchronous work guards its
+     * own overlap.
+     * @returns - Stops further invocations; a call already in flight is not interrupted.
+     */
+    repeat(intervalMs: number, task: () => void): () => void;
+}
+/** Supplies all external operations used by the Pi extension. */
+export type PiExtensionDependencies = {
+    /** Reads service configuration without opening the broker database. */
+    readEnvironment(): RuntimeEnvironment;
+    /** Starts or adopts the shared broker service. */
+    ensureService(environment: RuntimeEnvironment): Promise<BrokerEndpoints>;
+    /** Supplies launch identity and runtime selection values. */
+    processEnv: NodeJS.ProcessEnv;
+    /** Performs one broker HTTP request. */
+    fetch: BrokerRequest;
+    /** Owns the attachment heartbeat cadence. */
+    scheduler: PiExtensionScheduler;
+    /** Opens the inbox the broker pushes this process's deliveries to. */
+    openInbox: PagerInboxOpener;
+    /** Shares this extension's runtime across duplicate loaded copies of the module. */
+    runtimeSlot: PiHostSlot<PiExtensionRuntime>;
+};
+/**
+ * Construct the Pager Pi extension around explicit host dependencies.
+ * @param dependencies - Service, HTTP, environment, and scheduling operations.
+ * @returns - Pi extension factory that registers broker tools and session lifecycle hooks.
+ */
+export declare function createPiExtension(dependencies: PiExtensionDependencies): (pi: ExtensionAPI) => void;
+declare const _default: (pi: ExtensionAPI) => void;
+export default _default;