@harness-control/runner 0.1.0

package/dist/connection/runner-connection.js

@@ -0,0 +1,631 @@
+import { WorkspaceManager } from "../workspaces/index.js";
+import { createHash } from "node:crypto";
+import { HCP_MESSAGE_MAX_ENCODED_BYTES, HCP_VERSION, createHcpEnvelope, parseHcpEnvelope, parseJsonHcpMessage, } from "@harness-control/protocol";
+import WebSocket from "ws";
+import { HarnessAdapterError } from "../harnesses/adapters.js";
+import { HarnessSessionError, HarnessSessionManager } from "../harnesses/index.js";
+import { ProviderInstanceRegistry } from "../host/provider-registry.js";
+import { LocalActionDispatcher } from "../local-actions/dispatcher.js";
+import { LocalCapabilityExecutor } from "../local-actions/executors.js";
+export class RunnerConnection {
+    #config;
+    #workspaces;
+    #runnerVersion;
+    #connectionTokenProvider;
+    #onLog;
+    #harnessSessions;
+    #stateStore;
+    #localActionDispatcher;
+    #reconnectInitialDelayMs;
+    #reconnectMaxDelayMs;
+    #socket;
+    #heartbeatTimer;
+    #reconnectTimer;
+    #reconnectAttempt = 0;
+    #closing = false;
+    #commandRecords = new Map();
+    #localActionRecords = new Map();
+    #localActionMismatchRecords = new Map();
+    constructor(options) {
+        this.#config = options.config;
+        this.#runnerVersion = options.runnerVersion;
+        this.#connectionTokenProvider = options.connectionTokenProvider;
+        this.#onLog = options.onLog ?? (() => undefined);
+        this.#harnessSessions = options.harnessSessions ?? new HarnessSessionManager(options.config);
+        this.#stateStore = this.#harnessSessions.stateStore();
+        this.#workspaces = new WorkspaceManager(options.config, options.configPath, this.#harnessSessions);
+        this.#localActionDispatcher = new LocalActionDispatcher({
+            executor: new LocalCapabilityExecutor(this.#harnessSessions.localCapabilityEngine()),
+            resolveContext: (payload) => this.#harnessSessions.resolveLocalActionContext(payload),
+            emitEvents: (sessionId, turnId, events) => this.#harnessSessions.recordLocalActionEvents(sessionId, turnId, events),
+        });
+        this.#reconnectInitialDelayMs = options.reconnect?.initialDelayMs ?? 1_000;
+        this.#reconnectMaxDelayMs = options.reconnect?.maxDelayMs ?? 30_000;
+    }
+    async connect() {
+        this.#closing = false;
+        await this.#openSocket();
+    }
+    async #openSocket() {
+        const connectionToken = this.#connectionTokenProvider
+            ? await this.#connectionTokenProvider()
+            : undefined;
+        const socket = new WebSocket(this.#config.control_plane_url, {
+            ...(connectionToken ? { headers: { authorization: `Bearer ${connectionToken}` } } : {}),
+        });
+        this.#socket = socket;
+        socket.on("message", (data) => {
+            this.#handleMessage(data.toString()).catch((error) => {
+                this.#onLog(error instanceof Error ? error.message : "Failed to handle control plane message.");
+            });
+        });
+        socket.on("close", () => {
+            if (this.#socket === socket) {
+                this.#socket = undefined;
+            }
+            this.#stopHeartbeat();
+            this.#onLog("Runner disconnected from control plane.");
+            if (!this.#closing) {
+                this.#scheduleReconnect();
+            }
+        });
+        socket.on("error", (error) => {
+            if (this.#socket === socket) {
+                this.#onLog(`Runner connection error: ${error.message}`);
+            }
+        });
+        await new Promise((resolve, reject) => {
+            socket.once("open", () => {
+                this.#reconnectAttempt = 0;
+                this.#sendHello();
+                resolve();
+            });
+            socket.once("error", reject);
+        });
+    }
+    async close() {
+        this.#closing = true;
+        this.#stopHeartbeat();
+        this.#stopReconnect();
+        await new Promise((resolve) => {
+            if (!this.#socket || this.#socket.readyState === WebSocket.CLOSED) {
+                resolve();
+                return;
+            }
+            this.#socket.once("close", () => {
+                resolve();
+            });
+            this.#socket.close();
+        });
+    }
+    #sendHello() {
+        const retainedEvents = this.#harnessSessions.retainedEventRanges();
+        const payload = {
+            runner_id: this.#config.runner_id,
+            host_id: this.#config.host_id ?? this.#config.runner_id,
+            runner_version: this.#runnerVersion,
+            supported_protocol_versions: [HCP_VERSION],
+            capabilities: [
+                "providers",
+                "workspaces",
+                "mcp_streamable_http",
+                "local_filesystem",
+                "local_git",
+                "local_shell",
+                "local_dev_server",
+                "durable_at_least_once",
+                "session_snapshots",
+            ],
+            ...(retainedEvents ? { retained_events: retainedEvents } : {}),
+        };
+        this.#send(createHcpEnvelope("host.hello", payload));
+    }
+    async #handleMessage(raw) {
+        if (Buffer.byteLength(raw, "utf8") > HCP_MESSAGE_MAX_ENCODED_BYTES) {
+            this.#sendNack("unknown", {
+                code: "message_too_large",
+                message: `Control plane message exceeds ${HCP_MESSAGE_MAX_ENCODED_BYTES} encoded bytes.`,
+                retryable: false,
+            });
+            return;
+        }
+        let envelope;
+        try {
+            envelope = parseJsonHcpMessage(raw);
+        }
+        catch (error) {
+            this.#sendParseNack(raw, error);
+            return;
+        }
+        switch (envelope.type) {
+            case "host.accepted":
+                await this.#handleAccepted(envelope);
+                return;
+            case "host.rejected":
+                this.#onLog(`Control plane rejected runner: ${envelope.payload.reason}`);
+                await this.close();
+                return;
+            case "host.workspaces.request": {
+                const result = await this.#workspaces.execute(envelope.id, envelope.payload);
+                this.#send(createHcpEnvelope("host.workspaces.result", result));
+                await this.#sendCapabilities();
+                return;
+            }
+            case "host.workspaces.result":
+                return;
+            case "harness.session.start":
+                await this.#handleCommand(envelope, (message) => this.#handleSessionStart(message));
+                return;
+            case "harness.session.snapshot.request":
+                await this.#handleCommand(envelope, (message) => ({
+                    events: [],
+                    snapshotPayload: this.#harnessSessions.sessionSnapshot(message.id, message.payload.session_id),
+                }));
+                return;
+            case "harness.turn.send":
+                await this.#handleCommand(envelope, (message) => this.#handleTurnSend(message));
+                return;
+            case "harness.turn.cancel":
+                await this.#handleCommand(envelope, (message) => this.#handleTurnCancel(message));
+                return;
+            case "harness.session.stop":
+                await this.#handleCommand(envelope, (message) => this.#handleSessionStop(message));
+                return;
+            case "harness.approval.respond":
+            case "harness.input.respond":
+            case "tool_servers.detach":
+                await this.#handleCommand(envelope, () => {
+                    throw new HarnessAdapterError("unsupported_command", `${envelope.type} is not implemented by this runner.`);
+                });
+                return;
+            case "local.action.request":
+                await this.#handleLocalAction(envelope);
+                return;
+            case "hcp.command.ack":
+            case "hcp.command.nack":
+            case "host.hello":
+            case "host.heartbeat":
+            case "host.capabilities.updated":
+            case "host.replay.unavailable":
+            case "harness.session.snapshot":
+            case "local.action.response":
+            case "local.action.error":
+            case "harness.event":
+                this.#onLog(`Ignoring inbound ${envelope.type}; it is not a runner command.`);
+                return;
+            default:
+                const unsupportedEnvelope = envelope;
+                this.#sendNack(commandIdFor(unsupportedEnvelope), {
+                    code: "unsupported_message_type",
+                    message: `${unsupportedEnvelope.type} is not supported as an inbound runner command.`,
+                    retryable: false,
+                });
+        }
+    }
+    async #handleAccepted(envelope) {
+        this.#onLog(`Control plane accepted ${envelope.payload.protocol_version}.`);
+        await this.#sendCapabilities();
+        this.#replayRequestedEvents(envelope.payload.resume);
+        this.#startHeartbeat(envelope.payload.heartbeat_interval_seconds);
+    }
+    #replayRequestedEvents(cursor) {
+        if (!cursor) {
+            return;
+        }
+        const replay = this.#harnessSessions.replayEventsAfter(cursor);
+        for (const unavailable of replay.unavailable) {
+            this.#send(createHcpEnvelope("host.replay.unavailable", unavailable));
+        }
+        for (const event of replay.events) {
+            this.#send(createHcpEnvelope("harness.event", event));
+        }
+    }
+    async #handleCommand(envelope, handler) {
+        const commandId = commandIdFor(envelope);
+        const commandHash = hashCommandPayload(envelope);
+        const persistedReceipt = this.#stateStore.getCommandReceipt(commandId);
+        const existingRecord = this.#commandRecords.get(commandId) ?? (persistedReceipt ? commandRecordFromReceipt(persistedReceipt) : undefined);
+        if (existingRecord !== undefined) {
+            if (existingRecord.payloadHash === commandHash) {
+                if (existingRecord.outcome === "pending") {
+                    const settledRecord = await existingRecord.completion;
+                    if (settledRecord.outcome === "ack") {
+                        this.#sendAck(commandId, true);
+                        if (settledRecord.snapshotPayload) {
+                            this.#send(createHcpEnvelope("harness.session.snapshot", settledRecord.snapshotPayload));
+                        }
+                    }
+                    else {
+                        this.#sendNackPayload(settledRecord.nackPayload);
+                    }
+                    return;
+                }
+                if (existingRecord.outcome === "ack") {
+                    this.#sendAck(commandId, true);
+                    if (existingRecord.snapshotPayload) {
+                        this.#send(createHcpEnvelope("harness.session.snapshot", existingRecord.snapshotPayload));
+                    }
+                }
+                else {
+                    this.#sendNackPayload(existingRecord.nackPayload);
+                }
+                return;
+            }
+            this.#sendNack(commandId, {
+                code: "duplicate_command_payload_mismatch",
+                message: `Command '${commandId}' was already seen with a different payload.`,
+                retryable: false,
+            });
+            return;
+        }
+        let settleCommand;
+        const completion = new Promise((resolve) => {
+            settleCommand = resolve;
+        });
+        this.#commandRecords.set(commandId, {
+            payloadHash: commandHash,
+            outcome: "pending",
+            completion,
+        });
+        try {
+            const execution = await handler(envelope);
+            const result = Array.isArray(execution) ? { events: execution } : execution;
+            const settledAt = new Date().toISOString();
+            const record = {
+                payloadHash: commandHash,
+                outcome: "ack",
+                ...(result.snapshotPayload ? { snapshotPayload: result.snapshotPayload } : {}),
+            };
+            this.#commandRecords.set(commandId, record);
+            this.#stateStore.setCommandReceipt(commandId, {
+                payloadHash: commandHash,
+                outcome: "ack",
+                settledAt,
+                ...(result.snapshotPayload ? { snapshotPayload: result.snapshotPayload } : {}),
+            });
+            settleCommand(record);
+            this.#sendAck(commandId, false);
+            if (result.snapshotPayload) {
+                this.#send(createHcpEnvelope("harness.session.snapshot", result.snapshotPayload));
+            }
+            for (const event of result.events) {
+                this.#send(createHcpEnvelope("harness.event", event));
+            }
+        }
+        catch (error) {
+            const nackPayload = createNackPayload(commandId, toHcpError(error));
+            const record = {
+                payloadHash: commandHash,
+                outcome: "nack",
+                nackPayload,
+            };
+            this.#commandRecords.set(commandId, record);
+            this.#stateStore.setCommandReceipt(commandId, {
+                payloadHash: commandHash,
+                outcome: "nack",
+                settledAt: new Date().toISOString(),
+                nackPayload,
+            });
+            settleCommand(record);
+            this.#sendNackPayload(nackPayload);
+        }
+    }
+    async #handleSessionStart(envelope) {
+        this.#localActionDispatcher.markSessionActive(envelope.payload.session_id);
+        return await this.#harnessSessions.startSession(envelope.payload);
+    }
+    #handleTurnSend(envelope) {
+        const completion = this.#harnessSessions.sendTurn(envelope.payload, (event) => this.#sendEventIfConnected(event));
+        completion
+            .then((events) => {
+            for (const event of events) {
+                this.#sendEventIfConnected(event);
+            }
+        })
+            .catch((error) => {
+            const failedEvent = this.#harnessSessions.recordTurnFailure(envelope.payload.session_id, envelope.payload.turn_id, error);
+            this.#sendEventIfConnected(failedEvent);
+        });
+        return [];
+    }
+    #handleTurnCancel(envelope) {
+        return this.#harnessSessions.cancelTurn(envelope.payload.session_id, envelope.payload.turn_id);
+    }
+    async #handleSessionStop(envelope) {
+        const events = await this.#harnessSessions.stopSession(envelope.payload.session_id, envelope.payload.reason);
+        await this.#localActionDispatcher.stopDevServersForSession(envelope.payload.session_id);
+        return events;
+    }
+    async #handleLocalAction(envelope) {
+        const requestId = envelope.payload.request_id;
+        const payloadHash = hashCommandPayload(envelope);
+        const persistedReceipt = this.#stateStore.getLocalActionReceipt(requestId);
+        const existingRecord = this.#localActionRecords.get(requestId) ??
+            (persistedReceipt ? localActionRecordFromReceipt(persistedReceipt) : undefined);
+        if (existingRecord !== undefined) {
+            if (existingRecord.payloadHash === payloadHash) {
+                if (existingRecord.outcome === "pending") {
+                    const settledRecord = await existingRecord.completion;
+                    this.#sendLocalActionRecord(settledRecord);
+                    return;
+                }
+                this.#sendLocalActionRecord(existingRecord);
+                return;
+            }
+            const mismatchKey = `${requestId}:${payloadHash}`;
+            const existingMismatchRecord = this.#localActionMismatchRecords.get(mismatchKey);
+            if (existingMismatchRecord) {
+                this.#sendLocalActionRecord(existingMismatchRecord);
+                return;
+            }
+            const mismatchOutcome = this.#localActionDispatcher.duplicatePayloadMismatch(envelope.payload);
+            const mismatchRecord = mismatchOutcome.type === "response"
+                ? {
+                    payloadHash,
+                    requestPayload: envelope.payload,
+                    outcome: "response",
+                    payload: mismatchOutcome.payload,
+                }
+                : {
+                    payloadHash,
+                    requestPayload: envelope.payload,
+                    outcome: "error",
+                    payload: mismatchOutcome.payload,
+                };
+            this.#localActionMismatchRecords.set(mismatchKey, mismatchRecord);
+            for (const event of mismatchOutcome.events) {
+                this.#send(createHcpEnvelope("harness.event", event));
+            }
+            this.#sendLocalActionRecord(mismatchRecord);
+            return;
+        }
+        let settleLocalAction;
+        const completion = new Promise((resolve) => {
+            settleLocalAction = resolve;
+        });
+        this.#localActionRecords.set(requestId, {
+            payloadHash,
+            requestPayload: envelope.payload,
+            outcome: "pending",
+            completion,
+        });
+        const outcome = await this.#localActionDispatcher.dispatch(envelope.payload);
+        const record = outcome.type === "response"
+            ? {
+                payloadHash,
+                requestPayload: envelope.payload,
+                outcome: "response",
+                payload: outcome.payload,
+            }
+            : {
+                payloadHash,
+                requestPayload: envelope.payload,
+                outcome: "error",
+                payload: outcome.payload,
+            };
+        this.#localActionRecords.set(requestId, record);
+        const persistedRecord = record.outcome === "response"
+            ? {
+                payloadHash,
+                requestPayload: envelope.payload,
+                outcome: "response",
+                settledAt: new Date().toISOString(),
+                payload: record.payload,
+            }
+            : {
+                payloadHash,
+                requestPayload: envelope.payload,
+                outcome: "error",
+                settledAt: new Date().toISOString(),
+                payload: record.payload,
+            };
+        this.#stateStore.setLocalActionReceipt(requestId, persistedRecord);
+        settleLocalAction(record);
+        for (const event of outcome.events) {
+            this.#send(createHcpEnvelope("harness.event", event));
+        }
+        this.#sendLocalActionRecord(record);
+    }
+    async #sendCapabilities() {
+        const registry = new ProviderInstanceRegistry(this.#config, await this.#harnessSessions.providerDriverStatuses());
+        const payload = { ...registry.snapshot(), workspace_management: this.#workspaces.snapshot() };
+        this.#send(createHcpEnvelope("host.capabilities.updated", payload));
+    }
+    #startHeartbeat(intervalSeconds) {
+        this.#stopHeartbeat();
+        const intervalMs = Math.max(1, intervalSeconds) * 1000;
+        this.#heartbeatTimer = setInterval(() => {
+            const payload = {
+                host_id: this.#config.host_id ?? this.#config.runner_id,
+                status: "online",
+                active_sessions: this.#harnessSessions.activeSessionCount(),
+            };
+            this.#send(createHcpEnvelope("host.heartbeat", payload));
+        }, intervalMs);
+    }
+    #stopHeartbeat() {
+        if (this.#heartbeatTimer) {
+            clearInterval(this.#heartbeatTimer);
+            this.#heartbeatTimer = undefined;
+        }
+    }
+    #scheduleReconnect() {
+        if (this.#reconnectTimer) {
+            return;
+        }
+        const delayMs = Math.min(this.#reconnectMaxDelayMs, this.#reconnectInitialDelayMs * 2 ** this.#reconnectAttempt);
+        this.#reconnectAttempt += 1;
+        this.#reconnectTimer = setTimeout(() => {
+            this.#reconnectTimer = undefined;
+            if (this.#closing) {
+                return;
+            }
+            this.#openSocket().catch((error) => {
+                this.#onLog(error instanceof Error ? error.message : "Runner reconnect failed.");
+                if (!this.#closing) {
+                    this.#scheduleReconnect();
+                }
+            });
+        }, delayMs);
+    }
+    #stopReconnect() {
+        if (this.#reconnectTimer) {
+            clearTimeout(this.#reconnectTimer);
+            this.#reconnectTimer = undefined;
+        }
+    }
+    #send(envelope) {
+        if (!this.#socket || this.#socket.readyState !== WebSocket.OPEN) {
+            throw new Error("Runner is not connected to the control plane.");
+        }
+        this.#socket.send(JSON.stringify(envelope));
+    }
+    #sendEventIfConnected(event) {
+        if (!this.#socket || this.#socket.readyState !== WebSocket.OPEN) {
+            return;
+        }
+        this.#socket.send(JSON.stringify(createHcpEnvelope("harness.event", event)));
+    }
+    #sendNack(commandId, error) {
+        this.#sendNackPayload(createNackPayload(commandId, error));
+    }
+    #sendNackPayload(payload) {
+        this.#send(createHcpEnvelope("hcp.command.nack", payload));
+    }
+    #sendAck(commandId, duplicate) {
+        const payload = {
+            command_id: commandId,
+            accepted_at: new Date().toISOString(),
+            duplicate,
+        };
+        this.#send(createHcpEnvelope("hcp.command.ack", payload));
+    }
+    #sendLocalActionRecord(record) {
+        if (record.outcome === "response") {
+            this.#send(createHcpEnvelope("local.action.response", record.payload));
+            return;
+        }
+        this.#send(createHcpEnvelope("local.action.error", record.payload));
+    }
+    #sendParseNack(raw, error) {
+        let receivedMessageId = "unknown";
+        let payloadHash;
+        try {
+            const envelope = parseHcpEnvelope(JSON.parse(raw));
+            receivedMessageId = envelope.id;
+            payloadHash = createHash("sha256").update(stableStringify(envelope.payload)).digest("hex");
+        }
+        catch (parseError) {
+            if (!(parseError instanceof Error)) {
+                throw parseError;
+            }
+            receivedMessageId = "unknown";
+        }
+        const nackPayload = createNackPayload(receivedMessageId, {
+            code: "invalid_message",
+            message: error instanceof Error ? error.message : "Control plane message failed validation.",
+            retryable: false,
+        });
+        if (payloadHash !== undefined) {
+            const record = {
+                payloadHash,
+                outcome: "nack",
+                nackPayload,
+            };
+            this.#commandRecords.set(receivedMessageId, record);
+            this.#stateStore.setCommandReceipt(receivedMessageId, {
+                payloadHash,
+                outcome: "nack",
+                settledAt: new Date().toISOString(),
+                nackPayload,
+            });
+        }
+        this.#sendNackPayload(nackPayload);
+    }
+}
+function toHcpError(error) {
+    if (error instanceof HarnessSessionError) {
+        return {
+            code: error.code,
+            message: error.message,
+            retryable: false,
+        };
+    }
+    if (error instanceof HarnessAdapterError) {
+        return {
+            code: error.code,
+            message: error.message,
+            retryable: false,
+        };
+    }
+    if (error instanceof Error) {
+        return {
+            code: "runner_error",
+            message: error.message,
+            retryable: false,
+        };
+    }
+    return {
+        code: "runner_error",
+        message: "Runner command failed.",
+        retryable: false,
+    };
+}
+function commandRecordFromReceipt(receipt) {
+    return receipt.outcome === "ack"
+        ? {
+            payloadHash: receipt.payloadHash,
+            outcome: "ack",
+            ...(receipt.snapshotPayload ? { snapshotPayload: receipt.snapshotPayload } : {}),
+        }
+        : {
+            payloadHash: receipt.payloadHash,
+            outcome: "nack",
+            nackPayload: receipt.nackPayload,
+        };
+}
+function localActionRecordFromReceipt(receipt) {
+    return receipt.outcome === "response"
+        ? {
+            payloadHash: receipt.payloadHash,
+            requestPayload: receipt.requestPayload,
+            outcome: "response",
+            payload: receipt.payload,
+        }
+        : {
+            payloadHash: receipt.payloadHash,
+            requestPayload: receipt.requestPayload,
+            outcome: "error",
+            payload: receipt.payload,
+        };
+}
+function createNackPayload(commandId, error) {
+    return {
+        command_id: commandId,
+        rejected_at: new Date().toISOString(),
+        error,
+    };
+}
+function commandIdFor(envelope) {
+    if (typeof envelope.payload === "object" && envelope.payload !== null && "command_id" in envelope.payload) {
+        const commandId = envelope.payload.command_id;
+        if (typeof commandId === "string" && commandId.length > 0) {
+            return commandId;
+        }
+    }
+    return envelope.id;
+}
+function hashCommandPayload(envelope) {
+    return createHash("sha256").update(stableStringify(envelope.payload)).digest("hex");
+}
+function stableStringify(value) {
+    if (value === null || typeof value !== "object") {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+    }
+    const entries = Object.entries(value).sort(([left], [right]) => left.localeCompare(right));
+    return `{${entries.map(([key, entryValue]) => `${JSON.stringify(key)}:${stableStringify(entryValue)}`).join(",")}}`;
+}
+//# sourceMappingURL=runner-connection.js.map

package/dist/harnesses/adapters/providers/claude-runtime.d.ts

@@ -0,0 +1,5 @@
+import { query, type Query } from "@anthropic-ai/claude-agent-sdk";
+import { type NativeTurn } from "./native-turn.js";
+export type ClaudeQueryFactory = (input: Parameters<typeof query>[0]) => Query;
+export declare function createClaudeTurn(queryFactory?: ClaudeQueryFactory): NativeTurn;
+//# sourceMappingURL=claude-runtime.d.ts.map