runtimeuse 0.2.0

package/src/download-handler.test.ts

@@ -0,0 +1,183 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+vi.mock("fs", async () => {
+  const actual = await vi.importActual<typeof import("fs")>("fs");
+  return {
+    ...actual,
+    default: {
+      ...actual,
+      existsSync: vi.fn(() => true),
+      mkdirSync: vi.fn(),
+      createWriteStream: vi.fn(() => ({
+        on: vi.fn(),
+        write: vi.fn(),
+        end: vi.fn(),
+        close: vi.fn(),
+      })),
+      unlinkSync: vi.fn(),
+    },
+  };
+});
+
+vi.mock("child_process", () => ({
+  execFileSync: vi.fn(),
+}));
+
+vi.mock("node:stream/promises", () => ({
+  pipeline: vi.fn().mockResolvedValue(undefined),
+}));
+
+vi.mock("node:stream", () => ({
+  Readable: { fromWeb: vi.fn().mockReturnValue("mock-stream") },
+}));
+
+const mockFetch = vi.fn().mockResolvedValue({
+  ok: true,
+  body: "mock-body",
+  status: 200,
+  statusText: "OK",
+});
+vi.stubGlobal("fetch", mockFetch);
+
+import fs from "fs";
+import { execFileSync } from "child_process";
+import DownloadHandler from "./download-handler.js";
+import { pipeline } from "node:stream/promises";
+import type { Logger } from "./logger.js";
+
+const mockLogger: Logger = {
+  log: vi.fn(),
+  error: vi.fn(),
+  debug: vi.fn(),
+};
+
+describe("DownloadHandler", () => {
+  let handler: DownloadHandler;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    handler = new DownloadHandler(mockLogger);
+    mockFetch.mockResolvedValue({
+      ok: true,
+      body: "mock-body",
+      status: 200,
+      statusText: "OK",
+    });
+  });
+
+  describe("directory creation", () => {
+    it("creates working directory when it does not exist", async () => {
+      vi.mocked(fs.existsSync).mockReturnValueOnce(false);
+
+      await handler.download(
+        "https://example.com/files/test.tar.gz",
+        "/tmp/workdir",
+      );
+
+      expect(fs.mkdirSync).toHaveBeenCalledWith("/tmp/workdir", {
+        recursive: true,
+      });
+    });
+
+    it("skips directory creation when working directory exists", async () => {
+      vi.mocked(fs.existsSync).mockReturnValueOnce(true);
+
+      await handler.download(
+        "https://example.com/files/test.tar.gz",
+        "/tmp/workdir",
+      );
+
+      expect(fs.mkdirSync).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("file download", () => {
+    it("downloads a file via fetch to the working directory", async () => {
+      await handler.download(
+        "https://example.com/files/script.sh",
+        "/tmp/workdir",
+      );
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        "https://example.com/files/script.sh",
+      );
+      expect(pipeline).toHaveBeenCalled();
+    });
+
+    it("throws on non-ok response", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        status: 404,
+        statusText: "Not Found",
+        body: null,
+      });
+
+      await expect(
+        handler.download("https://example.com/files/missing.sh", "/tmp/workdir"),
+      ).rejects.toThrow("Download failed: 404 Not Found");
+    });
+
+    it("throws when response has no body", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        statusText: "OK",
+        body: null,
+      });
+
+      await expect(
+        handler.download("https://example.com/files/empty.sh", "/tmp/workdir"),
+      ).rejects.toThrow("Download failed: no response body");
+    });
+  });
+
+  describe("zip handling", () => {
+    it("unzips .zip files using execFileSync and removes the archive", async () => {
+      await handler.download(
+        "https://example.com/files/tests.zip",
+        "/tmp/workdir",
+      );
+
+      expect(execFileSync).toHaveBeenCalledWith("unzip", [
+        "-o",
+        "/tmp/workdir/tests.zip",
+        "-d",
+        "/tmp/workdir",
+      ]);
+      expect(fs.unlinkSync).toHaveBeenCalledWith("/tmp/workdir/tests.zip");
+    });
+
+    it("does not unzip non-zip files", async () => {
+      await handler.download(
+        "https://example.com/files/data.tar.gz",
+        "/tmp/workdir",
+      );
+
+      expect(execFileSync).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("logging", () => {
+    it("logs the download operation", async () => {
+      await handler.download(
+        "https://example.com/files/test.sh",
+        "/tmp/workdir",
+      );
+
+      expect(mockLogger.log).toHaveBeenCalledWith(
+        expect.stringContaining("Downloading file test.sh"),
+      );
+    });
+
+    it("logs unzip operation for zip files", async () => {
+      await handler.download(
+        "https://example.com/files/archive.zip",
+        "/tmp/workdir",
+      );
+
+      expect(mockLogger.log).toHaveBeenCalledWith(
+        expect.stringContaining("Unzipping file archive.zip"),
+      );
+    });
+  });
+});

package/src/download-handler.ts

@@ -0,0 +1,45 @@
+import path from "path";
+import fs from "fs";
+import { execFileSync } from "child_process";
+import { pipeline } from "node:stream/promises";
+import { Readable } from "node:stream";
+import { Logger } from "./logger.js";
+
+class DownloadHandler {
+  private readonly logger: Logger;
+  constructor(logger: Logger) {
+    this.logger = logger;
+  }
+
+  async download(downloadUrl: string, workingDir: string): Promise<void> {
+    if (!fs.existsSync(workingDir)) {
+      fs.mkdirSync(workingDir, { recursive: true });
+    }
+    const fileUrl = new URL(downloadUrl);
+    const filename = decodeURIComponent(path.basename(fileUrl.pathname));
+    const filepath = path.join(workingDir, filename);
+
+    this.logger.log(`Downloading file ${filename} to ${filepath}`);
+
+    const response = await fetch(downloadUrl);
+    if (!response.ok) {
+      throw new Error(
+        `Download failed: ${response.status} ${response.statusText}`,
+      );
+    }
+    if (!response.body) {
+      throw new Error("Download failed: no response body");
+    }
+
+    const fileStream = fs.createWriteStream(filepath);
+    await pipeline(Readable.fromWeb(response.body as any), fileStream);
+
+    if (path.extname(filepath) === ".zip") {
+      this.logger.log(`Unzipping file ${filename}`);
+      execFileSync("unzip", ["-o", filepath, "-d", workingDir]);
+      fs.unlinkSync(filepath);
+    }
+  }
+}
+
+export default DownloadHandler;

package/src/index.ts

@@ -0,0 +1,59 @@
+// Core abstractions
+export type {
+  AgentHandler,
+  AgentInvocation,
+  AgentResult,
+  MessageSender,
+} from "./agent-handler.js";
+
+// Built-in handlers
+export { openaiHandler } from "./openai-handler.js";
+export { claudeHandler } from "./claude-handler.js";
+
+// Server
+export { RuntimeUseServer } from "./server.js";
+export type { RuntimeUseServerConfig } from "./server.js";
+
+// Session
+export { WebSocketSession } from "./session.js";
+export type { SessionConfig } from "./session.js";
+
+// Artifact management
+export { ArtifactManager } from "./artifact-manager.js";
+export type { ArtifactManagerConfig } from "./artifact-manager.js";
+
+// Upload
+export { UploadTracker } from "./upload-tracker.js";
+export { uploadFile } from "./storage.js";
+
+// Commands & downloads
+export { default as CommandHandler } from "./command-handler.js";
+export type { CommandResult } from "./command-handler.js";
+export { default as DownloadHandler } from "./download-handler.js";
+
+// Protocol types
+export type {
+  IncomingMessage,
+  OutgoingMessage,
+  InvocationMessage,
+  CancelMessage,
+  ResultMessage,
+  AssistantMessage,
+  ArtifactUploadRequestMessage,
+  ArtifactUploadResponseMessage,
+  ErrorMessage,
+  StreamEndMessage,
+  Command,
+  RuntimeEnvironmentDownloadable,
+} from "./types.js";
+
+// Utilities
+export { redactSecrets, sleep } from "./utils.js";
+export { createLogger, defaultLogger } from "./logger.js";
+export type { Logger } from "./logger.js";
+
+// Constants
+export {
+  DEFAULT_ARTIFACTS_DIR,
+  DEFAULT_ARTIFACT_IGNORE,
+} from "./constants.js";

package/src/logger.ts

@@ -0,0 +1,20 @@
+export interface Logger {
+  log(...args: unknown[]): void;
+  error(...args: unknown[]): void;
+  debug(...args: unknown[]): void;
+}
+
+export function createLogger(sourceId: string): Logger {
+  const prefix = `[${sourceId}]`;
+  return {
+    log: (...args: unknown[]) => console.log(prefix, ...args),
+    error: (...args: unknown[]) => console.error(prefix, ...args),
+    debug: (...args: unknown[]) => console.debug(prefix, ...args),
+  };
+}
+
+export const defaultLogger: Logger = {
+  log: (...args: unknown[]) => console.log(...args),
+  error: (...args: unknown[]) => console.error(...args),
+  debug: (...args: unknown[]) => console.debug(...args),
+};

package/src/openai-handler.ts

@@ -0,0 +1,120 @@
+import zod from "zod";
+
+import {
+  Agent,
+  run as runAgent,
+  codeInterpreterTool,
+  webSearchTool,
+  AgentOutputType,
+} from "@openai/agents";
+import type {
+  AgentHandler,
+  AgentInvocation,
+  AgentResult,
+  MessageSender,
+} from "./agent-handler.js";
+
+export const openaiHandler: AgentHandler = {
+  async run(
+    invocation: AgentInvocation,
+    sender: MessageSender,
+  ): Promise<AgentResult> {
+    Object.assign(process.env, invocation.env);
+
+    const strictSchema = ensureStrictSchema(invocation.outputFormat.schema);
+    const outputType = zod.fromJSONSchema(strictSchema) as AgentOutputType;
+
+    const agent = new Agent({
+      name: "runtimeuse-agent",
+      instructions: invocation.systemPrompt,
+      outputType,
+      model: invocation.model,
+      tools: [codeInterpreterTool(), webSearchTool()],
+    });
+
+    const result = await runAgent(agent, invocation.userPrompt, {
+      signal: invocation.signal,
+      stream: true,
+    });
+
+    let currentText = "";
+    for await (const event of result) {
+      if (
+        event.type === "raw_model_stream_event" &&
+        "delta" in event.data &&
+        typeof event.data.delta === "string"
+      ) {
+        currentText += event.data.delta;
+      } else if (
+        event.type === "run_item_stream_event" &&
+        event.name === "message_output_created"
+      ) {
+        if (currentText) {
+          sender.sendAssistantMessage([currentText]);
+          currentText = "";
+        }
+      }
+    }
+
+    await result.completed;
+
+    if (currentText) {
+      sender.sendAssistantMessage([currentText]);
+    }
+
+    let structuredOutput: Record<string, unknown> = {};
+    const finalOutput = result.finalOutput;
+
+    if (typeof finalOutput === "string") {
+      try {
+        structuredOutput = JSON.parse(finalOutput);
+      } catch {
+        structuredOutput = { result: finalOutput };
+      }
+    } else if (finalOutput != null && typeof finalOutput === "object") {
+      structuredOutput = finalOutput as Record<string, unknown>;
+    }
+
+    const metadata: Record<string, unknown> = {};
+    const usage = result.state?.usage;
+    if (usage) {
+      metadata.usage = {
+        inputTokens: usage.inputTokens,
+        outputTokens: usage.outputTokens,
+        totalTokens: usage.totalTokens,
+      };
+    }
+
+    return { structuredOutput, metadata };
+  },
+};
+
+function ensureStrictSchema(
+  schema: Record<string, unknown>,
+): Record<string, unknown> {
+  const result = { ...schema };
+  if (result.type === "object") {
+    result.additionalProperties = false;
+    if (
+      result.properties &&
+      typeof result.properties === "object" &&
+      !Array.isArray(result.properties)
+    ) {
+      const props: Record<string, unknown> = {};
+      for (const [key, value] of Object.entries(
+        result.properties as Record<string, unknown>,
+      )) {
+        props[key] =
+          value && typeof value === "object" && !Array.isArray(value)
+            ? ensureStrictSchema(value as Record<string, unknown>)
+            : value;
+      }
+      result.properties = props;
+    }
+  }
+  if (result.items && typeof result.items === "object") {
+    result.items = ensureStrictSchema(result.items as Record<string, unknown>);
+  }
+  delete result.title;
+  return result;
+}

package/src/server.ts

@@ -0,0 +1,68 @@
+import { WebSocketServer, WebSocket } from "ws";
+import type { AgentHandler } from "./agent-handler.js";
+import { WebSocketSession, type SessionConfig } from "./session.js";
+import { UploadTracker } from "./upload-tracker.js";
+import { defaultLogger, type Logger } from "./logger.js";
+
+export interface RuntimeUseServerConfig {
+  handler: AgentHandler;
+  port?: number;
+  defaultModel?: string;
+  uploadTimeoutMs?: number;
+  artifactWaitMs?: number;
+  postInvocationDelayMs?: number;
+  logger?: Logger;
+}
+
+export class RuntimeUseServer {
+  private readonly wss: WebSocketServer;
+  private readonly config: RuntimeUseServerConfig;
+  private readonly logger: Logger;
+
+  constructor(config: RuntimeUseServerConfig) {
+    this.config = config;
+    this.logger = config.logger ?? defaultLogger;
+    this.wss = new WebSocketServer({ port: config.port ?? 8080 });
+
+    this.wss.on("connection", (ws: WebSocket) => {
+      this.handleConnection(ws);
+    });
+  }
+
+  private handleConnection(ws: WebSocket): void {
+    const uploadTracker = new UploadTracker();
+    const sessionConfig: SessionConfig = {
+      handler: this.config.handler,
+      uploadTracker,
+      defaultModel: this.config.defaultModel,
+      uploadTimeoutMs: this.config.uploadTimeoutMs,
+      artifactWaitMs: this.config.artifactWaitMs,
+      postInvocationDelayMs: this.config.postInvocationDelayMs,
+      logger: this.config.logger,
+    };
+    const session = new WebSocketSession(ws, sessionConfig);
+    session.run().catch((error) => {
+      this.logger.error("Session error:", error);
+    });
+  }
+
+  async start(): Promise<void> {
+    return new Promise((resolve) => {
+      this.wss.on("listening", () => {
+        this.logger.log(
+          `RuntimeUse server listening on port ${this.config.port ?? 8080}`,
+        );
+        resolve();
+      });
+    });
+  }
+
+  async stop(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.wss.close((err) => {
+        if (err) reject(err);
+        else resolve();
+      });
+    });
+  }
+}