@companyhelm/runner 0.0.12 → 0.0.13

package/dist/service/app_server.js

@@ -0,0 +1,441 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AppServerService = void 0;
+const async_queue_js_1 = require("../utils/async_queue.js");
+const NOOP_APP_SERVER_LOGGER = { debug: () => undefined };
+const TURN_COMPLETION_NOTIFICATION_DRAIN_MS = 500;
+const NOOP_APP_SERVER_LOG_CONTEXT_PROVIDER = () => ({});
+class AppServerTimeoutError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AppServerTimeoutError";
+    }
+}
+function hasTag(message) {
+    return typeof message === "object" && message !== null && "type" in message;
+}
+function isResponseMessage(message) {
+    return (typeof message === "object" &&
+        message !== null &&
+        "id" in message &&
+        !("method" in message) &&
+        !("type" in message));
+}
+function isServerNotificationMessage(message) {
+    return (typeof message === "object" &&
+        message !== null &&
+        "method" in message &&
+        "params" in message);
+}
+function formatUnknownError(value) {
+    if (value instanceof Error) {
+        return value.message;
+    }
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+function isAlreadyInitializedError(value) {
+    if (!(value instanceof Error)) {
+        return false;
+    }
+    return value.message.toLowerCase().includes("already initialized");
+}
+function isModelListResponse(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const data = value.data;
+    const nextCursor = value.nextCursor;
+    return Array.isArray(data) && (typeof nextCursor === "string" || nextCursor === null);
+}
+function isJsonObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasMessageShape(value) {
+    return isJsonObject(value) && ("method" in value || "id" in value || "result" in value || "error" in value);
+}
+class AppServerService {
+    constructor(transport, clientName, logger, logContextProvider) {
+        this.stream = null;
+        this.pumpTask = null;
+        this.messageQueue = new async_queue_js_1.AsyncQueue();
+        this.pendingRequests = new Map();
+        this.pendingResponses = new Map();
+        this.nextRequestId = 1;
+        this.stderrLines = [];
+        this.stdoutBuffer = Buffer.alloc(0);
+        this.framing = "unknown";
+        this.transport = transport;
+        this.clientName = clientName;
+        this.logger = logger ?? NOOP_APP_SERVER_LOGGER;
+        this.logContextProvider = logContextProvider ?? NOOP_APP_SERVER_LOG_CONTEXT_PROVIDER;
+    }
+    async start() {
+        await this.transport.start();
+        this.stream = this.transport.receiveOutput();
+        this.pumpTask = this.pumpMessages();
+        await this.initialize();
+    }
+    async stop() {
+        const pump = this.pumpTask;
+        this.pumpTask = null;
+        this.stream = null;
+        this.rejectAllPendingRequests(new Error("app-server stopped"));
+        this.pendingResponses.clear();
+        this.messageQueue.close();
+        this.stdoutBuffer = Buffer.alloc(0);
+        this.framing = "unknown";
+        await this.transport.stop();
+        if (pump) {
+            await pump;
+        }
+    }
+    async listModels(cursor, limit) {
+        const result = await this.request("model/list", { cursor, limit }, 10000);
+        if (!isModelListResponse(result)) {
+            throw new Error("app-server returned an invalid model/list payload");
+        }
+        return result;
+    }
+    async startThread(params) {
+        return this.request("thread/start", params, 15000);
+    }
+    async startThreadWithResponse(params, requestId) {
+        return this.requestWithResponse("thread/start", params, 15000, requestId);
+    }
+    async resumeThread(params) {
+        return this.request("thread/resume", params, 15000);
+    }
+    async readThread(params) {
+        return this.request("thread/read", params, 15000);
+    }
+    async startTurn(params) {
+        return this.request("turn/start", params, 15000);
+    }
+    async steerTurn(params) {
+        return this.request("turn/steer", params, 15000);
+    }
+    async interruptTurn(params) {
+        return this.request("turn/interrupt", params, 15000);
+    }
+    async waitForTurnCompletion(threadId, turnId, onNotification, timeoutMs = 2 * 60 * 60000) {
+        const deadline = Date.now() + timeoutMs;
+        let completionStatus = null;
+        let completionDrainDeadline = 0;
+        while (true) {
+            const now = Date.now();
+            const activeDeadline = completionStatus
+                ? Math.min(deadline, completionDrainDeadline)
+                : deadline;
+            if (now >= activeDeadline) {
+                break;
+            }
+            const remaining = Math.max(1, activeDeadline - now);
+            const message = await this.popMessageWithTimeout(remaining);
+            if (!message) {
+                break;
+            }
+            if (hasTag(message)) {
+                if (message.type === "parse_error") {
+                    throw new Error(`Failed to parse app-server message: ${message.reason}`);
+                }
+                if (message.type === "stderr") {
+                    const trimmed = message.payload.trim();
+                    if (trimmed.length > 0) {
+                        this.stderrLines.push(trimmed);
+                    }
+                }
+                continue;
+            }
+            if (isResponseMessage(message)) {
+                continue;
+            }
+            if (!isServerNotificationMessage(message)) {
+                continue;
+            }
+            if (onNotification) {
+                await onNotification(message);
+            }
+            if (message.method === "error" &&
+                message.params.threadId === threadId &&
+                message.params.turnId === turnId) {
+                if (message.params.willRetry) {
+                    continue;
+                }
+                throw new Error(message.params.error.message);
+            }
+            if (message.method === "turn/completed" &&
+                message.params.threadId === threadId &&
+                message.params.turn.id === turnId) {
+                const status = message.params.turn.status;
+                if (status === "completed" || status === "interrupted" || status === "failed") {
+                    completionStatus = status;
+                    completionDrainDeadline = Date.now() + TURN_COMPLETION_NOTIFICATION_DRAIN_MS;
+                }
+            }
+        }
+        if (completionStatus) {
+            return completionStatus;
+        }
+        throw new AppServerTimeoutError(`Timed out waiting for completion of turn '${turnId}' in thread '${threadId}'.`);
+    }
+    async initialize() {
+        const params = {
+            clientInfo: {
+                name: this.clientName,
+                title: null,
+                version: "0.0.1",
+            },
+            capabilities: {
+                experimentalApi: true,
+                optOutNotificationMethods: [],
+            },
+        };
+        const attempts = 5;
+        for (let attempt = 1; attempt <= attempts; attempt += 1) {
+            try {
+                await this.request("initialize", params, 3000);
+                return;
+            }
+            catch (error) {
+                if (isAlreadyInitializedError(error)) {
+                    return;
+                }
+                if (!(error instanceof AppServerTimeoutError) || attempt === attempts) {
+                    throw error;
+                }
+            }
+        }
+    }
+    async request(method, params, timeoutMs) {
+        const response = await this.requestWithResponse(method, params, timeoutMs);
+        return response.result;
+    }
+    async requestWithResponse(method, params, timeoutMs, requestId) {
+        const resolvedRequestId = requestId ?? this.nextRequestId++;
+        const request = {
+            method,
+            id: resolvedRequestId,
+            params,
+        };
+        await this.sendMessage(request);
+        const response = await this.waitForResponseMessage(resolvedRequestId, timeoutMs);
+        return {
+            id: response.id,
+            result: response.result,
+        };
+    }
+    async sendMessage(message) {
+        const payload = JSON.stringify(message);
+        this.logger.debug(`[app-server][outgoing]${this.formatDebugContext()} ${payload}`);
+        await this.transport.sendRaw(`${payload}\n`);
+    }
+    async pumpMessages() {
+        if (!this.stream) {
+            return;
+        }
+        try {
+            for await (const event of this.stream) {
+                if (event.type === "stdout") {
+                    this.consumeStdout(event.payload);
+                    continue;
+                }
+                if (event.type === "stderr") {
+                    this.messageQueue.push({ type: "stderr", payload: event.payload });
+                    continue;
+                }
+                this.rejectAllPendingRequests(new Error(event.reason));
+                this.messageQueue.push({
+                    type: "parse_error",
+                    payload: "",
+                    reason: event.reason,
+                });
+            }
+        }
+        finally {
+            this.messageQueue.close();
+        }
+    }
+    consumeStdout(chunk) {
+        this.stdoutBuffer = Buffer.concat([this.stdoutBuffer, chunk]);
+        while (true) {
+            if (this.framing === "unknown") {
+                if (this.stdoutBuffer.length === 0) {
+                    return;
+                }
+                const head = this.stdoutBuffer.toString("utf8", 0, Math.min(this.stdoutBuffer.length, 64));
+                if (head.startsWith("Content-Length:")) {
+                    this.framing = "content-length";
+                }
+                else if (this.stdoutBuffer.includes(0x0a)) {
+                    this.framing = "newline";
+                }
+                else {
+                    return;
+                }
+            }
+            if (this.framing === "content-length") {
+                const payload = this.tryParseContentLengthFrame();
+                if (!payload) {
+                    return;
+                }
+                this.processPayload(payload);
+                continue;
+            }
+            const payload = this.tryParseNewlineFrame();
+            if (!payload) {
+                return;
+            }
+            this.processPayload(payload);
+        }
+    }
+    tryParseContentLengthFrame() {
+        const crlfDelimiter = Buffer.from("\r\n\r\n");
+        const lfDelimiter = Buffer.from("\n\n");
+        let headerEnd = this.stdoutBuffer.indexOf(crlfDelimiter);
+        let delimiterBytes = 4;
+        if (headerEnd < 0) {
+            headerEnd = this.stdoutBuffer.indexOf(lfDelimiter);
+            delimiterBytes = 2;
+        }
+        if (headerEnd < 0) {
+            return null;
+        }
+        const headerText = this.stdoutBuffer.subarray(0, headerEnd).toString("utf8");
+        const match = /Content-Length:\s*(\d+)/i.exec(headerText);
+        if (!match) {
+            this.stdoutBuffer = this.stdoutBuffer.subarray(headerEnd + delimiterBytes);
+            this.messageQueue.push({
+                type: "parse_error",
+                payload: headerText,
+                reason: "missing Content-Length header",
+            });
+            return null;
+        }
+        const contentLength = Number.parseInt(match[1], 10);
+        const bodyStart = headerEnd + delimiterBytes;
+        const bodyEnd = bodyStart + contentLength;
+        if (this.stdoutBuffer.length < bodyEnd) {
+            return null;
+        }
+        const payload = this.stdoutBuffer.subarray(bodyStart, bodyEnd).toString("utf8");
+        this.stdoutBuffer = this.stdoutBuffer.subarray(bodyEnd);
+        return payload;
+    }
+    tryParseNewlineFrame() {
+        const newlineIndex = this.stdoutBuffer.indexOf(0x0a);
+        if (newlineIndex < 0) {
+            return null;
+        }
+        const line = this.stdoutBuffer.subarray(0, newlineIndex).toString("utf8").replace(/\r$/, "");
+        this.stdoutBuffer = this.stdoutBuffer.subarray(newlineIndex + 1);
+        if (!line.trim()) {
+            return "";
+        }
+        return line;
+    }
+    processPayload(payload) {
+        if (!payload.trim()) {
+            return;
+        }
+        this.logger.debug(`[app-server][incoming]${this.formatDebugContext()} ${payload}`);
+        let parsed;
+        try {
+            parsed = JSON.parse(payload);
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : "invalid JSON";
+            this.messageQueue.push({ type: "parse_error", payload, reason });
+            return;
+        }
+        if (!hasMessageShape(parsed)) {
+            this.rejectAllPendingRequests(new Error("message does not match expected app-server envelope"));
+            this.messageQueue.push({
+                type: "parse_error",
+                payload,
+                reason: "message does not match expected app-server envelope",
+            });
+            return;
+        }
+        const message = parsed;
+        if (isResponseMessage(message)) {
+            this.routeResponseMessage(message);
+            return;
+        }
+        this.messageQueue.push(message);
+    }
+    async popMessageWithTimeout(timeoutMs) {
+        return this.messageQueue.popWithTimeout(timeoutMs);
+    }
+    routeResponseMessage(message) {
+        const pendingRequest = this.pendingRequests.get(message.id);
+        if (!pendingRequest) {
+            this.pendingResponses.set(message.id, message);
+            return;
+        }
+        this.pendingRequests.delete(message.id);
+        clearTimeout(pendingRequest.timeout);
+        if (message.error !== undefined) {
+            pendingRequest.reject(new Error(`app-server returned an error for request ${String(message.id)}: ${formatUnknownError(message.error)}`));
+            return;
+        }
+        pendingRequest.resolve(message);
+    }
+    rejectAllPendingRequests(error) {
+        for (const [requestId, pendingRequest] of this.pendingRequests.entries()) {
+            this.pendingRequests.delete(requestId);
+            clearTimeout(pendingRequest.timeout);
+            pendingRequest.reject(new Error(`request ${String(requestId)} failed: ${error.message}`));
+        }
+    }
+    async waitForResponseMessage(requestId, timeoutMs) {
+        const immediateResponse = this.pendingResponses.get(requestId);
+        if (immediateResponse) {
+            this.pendingResponses.delete(requestId);
+            if (immediateResponse.error !== undefined) {
+                throw new Error(`app-server returned an error for request ${String(requestId)}: ${formatUnknownError(immediateResponse.error)}`);
+            }
+            return immediateResponse;
+        }
+        return new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                this.pendingRequests.delete(requestId);
+                reject(new AppServerTimeoutError(`Timed out waiting for response to request ${String(requestId)}`));
+            }, timeoutMs);
+            const pendingRequest = {
+                timeout,
+                resolve: (message) => {
+                    resolve(message);
+                },
+                reject: (error) => {
+                    reject(error);
+                },
+            };
+            this.pendingRequests.set(requestId, pendingRequest);
+            const bufferedResponse = this.pendingResponses.get(requestId);
+            if (!bufferedResponse) {
+                return;
+            }
+            this.pendingResponses.delete(requestId);
+            this.pendingRequests.delete(requestId);
+            clearTimeout(timeout);
+            if (bufferedResponse.error !== undefined) {
+                reject(new Error(`app-server returned an error for request ${String(requestId)}: ${formatUnknownError(bufferedResponse.error)}`));
+                return;
+            }
+            resolve(bufferedResponse);
+        });
+    }
+    formatDebugContext() {
+        const { threadId, sdkThreadId } = this.logContextProvider();
+        return `[thread: ${this.normalizeDebugContextValue(threadId)}][sdkThread: ${this.normalizeDebugContextValue(sdkThreadId)}]`;
+    }
+    normalizeDebugContextValue(value) {
+        return typeof value === "string" ? value : "";
+    }
+}
+exports.AppServerService = AppServerService;

package/dist/service/buffered_client_message_sender.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BufferedClientMessageSender = exports.BufferedGrpcEventSender = void 0;
+function toErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+class BufferedGrpcEventSender {
+    constructor(options) {
+        this.bufferedEvents = [];
+        this.channel = null;
+        this.flushing = false;
+        this.droppedEvents = 0;
+        this.maxBufferedEvents = Math.max(1, options.maxBufferedEvents);
+        this.logger = options.logger;
+        this.eventName = options.eventName ?? "event";
+    }
+    bind(channel) {
+        this.channel = channel;
+        if (this.bufferedEvents.length > 0) {
+            this.logger.debug(`Bound command channel and attempting to flush ${this.bufferedEvents.length} buffered gRPC ${this.eventName}(s).`);
+        }
+        void this.flush();
+    }
+    unbind(channel) {
+        if (!channel || this.channel === channel) {
+            this.channel = null;
+        }
+    }
+    async send(event) {
+        this.enqueue(event);
+        await this.flush();
+    }
+    getBufferedEventCount() {
+        return this.bufferedEvents.length;
+    }
+    getDroppedEventCount() {
+        return this.droppedEvents;
+    }
+    enqueue(event) {
+        if (this.bufferedEvents.length >= this.maxBufferedEvents) {
+            this.droppedEvents += 1;
+            if (this.droppedEvents === 1 || this.droppedEvents % 100 === 0) {
+                this.logger.warn(`Dropping gRPC ${this.eventName} because outbound buffer reached ${this.maxBufferedEvents} entries ` +
+                    `(dropped=${this.droppedEvents}).`);
+            }
+            return;
+        }
+        this.bufferedEvents.push(event);
+    }
+    async flush() {
+        if (this.flushing) {
+            return;
+        }
+        this.flushing = true;
+        try {
+            while (this.channel && this.bufferedEvents.length > 0) {
+                const nextEvent = this.bufferedEvents[0];
+                try {
+                    await this.channel.send(nextEvent);
+                    this.bufferedEvents.shift();
+                }
+                catch (error) {
+                    this.logger.warn(`Failed to send buffered gRPC ${this.eventName}: ${toErrorMessage(error)}`);
+                    this.channel = null;
+                    break;
+                }
+            }
+        }
+        finally {
+            this.flushing = false;
+        }
+    }
+}
+exports.BufferedGrpcEventSender = BufferedGrpcEventSender;
+class BufferedClientMessageSender extends BufferedGrpcEventSender {
+    constructor(options) {
+        super({
+            ...options,
+            eventName: "client message",
+        });
+    }
+    getBufferedMessageCount() {
+        return this.getBufferedEventCount();
+    }
+    getDroppedMessageCount() {
+        return this.getDroppedEventCount();
+    }
+}
+exports.BufferedClientMessageSender = BufferedClientMessageSender;