runtimeuse 0.2.0

package/src/artifact-manager.ts

@@ -0,0 +1,170 @@
+import fs from "fs";
+import path from "path";
+import chokidar from "chokidar";
+import ignore, { type Ignore } from "ignore";
+import { uploadFile } from "./storage.js";
+import type { UploadTracker } from "./upload-tracker.js";
+import type {
+  ArtifactUploadRequestMessage,
+  ArtifactUploadResponseMessage,
+} from "./types.js";
+import { DEFAULT_ARTIFACT_IGNORE } from "./constants.js";
+import { defaultLogger, type Logger } from "./logger.js";
+
+type ArtifactType = ArtifactUploadRequestMessage["artifact_type"];
+
+const EXTENSION_TO_TYPE: Record<string, ArtifactType> = {
+  ".webm": "video",
+  ".png": "screenshot",
+  ".ndjson": "tool_calls",
+  ".js": "javascript",
+  ".ts": "javascript",
+  ".py": "python",
+  ".sh": "shellscript",
+};
+
+export interface ArtifactManagerConfig {
+  artifactsDir: string;
+  uploadTracker: UploadTracker;
+  send: (message: ArtifactUploadRequestMessage) => void;
+}
+
+export class ArtifactManager {
+  private readonly watcher: ReturnType<typeof chokidar.watch>;
+  private readonly pendingRequests = new Map<
+    string,
+    { promise: Promise<void>; resolve: () => void }
+  >();
+  private readonly artifactsDir: string;
+  private readonly uploadTracker: UploadTracker;
+  private readonly send: (message: ArtifactUploadRequestMessage) => void;
+  private ig: Ignore = ignore();
+  private logger: Logger = defaultLogger;
+  private loggingLevel: "info" | "debug" = "info";
+
+  constructor(config: ArtifactManagerConfig) {
+    this.artifactsDir = config.artifactsDir;
+    this.uploadTracker = config.uploadTracker;
+    this.send = config.send;
+
+    this.reloadIgnorePatterns();
+
+    this.watcher = chokidar.watch(config.artifactsDir, {
+      awaitWriteFinish: true,
+      alwaysStat: true,
+    });
+
+    this.watcher.on("add", (p, s) => this.onFileEvent(p, s));
+    this.watcher.on("change", (p, s) => this.onFileEvent(p, s));
+  }
+
+  private reloadIgnorePatterns(): void {
+    this.ig = ignore();
+    const ignorePath = path.join(this.artifactsDir, ".artifactignore");
+    if (fs.existsSync(ignorePath)) {
+      this.ig.add(fs.readFileSync(ignorePath, "utf-8"));
+      this.logger.log(`Loaded .artifactignore from ${ignorePath}`);
+    } else {
+      this.ig.add(DEFAULT_ARTIFACT_IGNORE);
+    }
+  }
+
+  setLogger(logger: Logger): void {
+    this.logger = logger;
+  }
+
+  async handleUploadResponse(
+    message: ArtifactUploadResponseMessage,
+  ): Promise<void> {
+    this.logger.log(
+      `Uploading artifact: ${message.filename} ${message.filepath}`,
+    );
+
+    const promise = uploadFile(
+      message.filepath,
+      message.presigned_url,
+      message.content_type,
+      this.logger,
+    );
+    this.uploadTracker.track(promise);
+
+    try {
+      await promise;
+    } catch (error) {
+      if (error instanceof Error && error.name === "ENOENT") {
+        this.logger.log(`Artifact file not found: ${message.filepath}`);
+        return;
+      }
+      throw error;
+    }
+
+    const pending = this.pendingRequests.get(message.filename);
+    if (pending) {
+      pending.resolve();
+      this.pendingRequests.delete(message.filename);
+    }
+  }
+
+  async waitForPendingRequests(timeoutMs: number): Promise<void> {
+    const promises = [...this.pendingRequests.values()].map((r) => r.promise);
+    if (promises.length === 0) return;
+    this.logger.log(`Waiting for ${promises.length} artifact round-trips...`);
+    await Promise.race([
+      Promise.allSettled(promises),
+      new Promise<void>((r) => setTimeout(r, timeoutMs)),
+    ]);
+  }
+
+  async stopWatching(): Promise<void> {
+    await this.watcher.close();
+  }
+
+  private onFileEvent(filePath: string, stats?: fs.Stats): void {
+    if (this.loggingLevel === "debug") {
+      this.logger.log(
+        `Artifact event: ${filePath}. Size: ${stats?.size ?? 0} bytes`,
+      );
+    }
+
+    if (path.basename(filePath) === ".artifactignore") {
+      this.reloadIgnorePatterns();
+      return;
+    }
+
+    if (!stats?.isFile() || !stats.size) {
+      if (this.loggingLevel === "debug") {
+        this.logger.debug(`Skipping: ${filePath}`);
+      }
+      return;
+    }
+
+    const relativePath = path.relative(this.artifactsDir, filePath);
+    if (!relativePath.startsWith("..") && this.ig.ignores(relativePath)) {
+      if (this.loggingLevel === "debug") {
+        this.logger.debug(`Skipping ignored artifact: ${relativePath}`);
+      }
+      return;
+    }
+
+    this.requestUpload(filePath);
+  }
+
+  private requestUpload(filePath: string): void {
+    const filename = path.basename(filePath);
+    const ext = path.extname(filePath);
+
+    let resolve!: () => void;
+    const promise = new Promise<void>((r) => {
+      resolve = r;
+    });
+    this.pendingRequests.set(filename, { promise, resolve });
+
+    this.logger.log(`Requesting upload for artifact: ${filename}`);
+    this.send({
+      message_type: "artifact_upload_request_message",
+      artifact_type: EXTENSION_TO_TYPE[ext] ?? "other",
+      filename,
+      filepath: filePath,
+    });
+  }
+}

package/src/claude-handler.ts

@@ -0,0 +1,95 @@
+import { query } from "@anthropic-ai/claude-agent-sdk";
+import type {
+  AgentHandler,
+  AgentInvocation,
+  AgentResult,
+  MessageSender,
+} from "./agent-handler.js";
+
+function extractTextFromContent(content: unknown[]): string {
+  const parts: string[] = [];
+  for (const block of content) {
+    if (
+      typeof block === "object" &&
+      block !== null &&
+      "type" in block &&
+      block.type === "text" &&
+      "text" in block
+    ) {
+      parts.push(String(block.text));
+    }
+  }
+  return parts.join("\n");
+}
+
+export const claudeHandler: AgentHandler = {
+  async run(
+    invocation: AgentInvocation,
+    sender: MessageSender,
+  ): Promise<AgentResult> {
+    const abortController = new AbortController();
+
+    const onAbort = () => abortController.abort();
+    invocation.signal.addEventListener("abort", onAbort, { once: true });
+
+    try {
+      const conversation = query({
+        prompt: invocation.userPrompt,
+        options: {
+          systemPrompt: invocation.systemPrompt,
+          model: invocation.model,
+          outputFormat: invocation.outputFormat,
+          abortController,
+          cwd: process.cwd(),
+          env: { ...process.env, ...invocation.env },
+          tools: { type: "preset", preset: "claude_code" },
+          permissionMode: "bypassPermissions",
+          allowDangerouslySkipPermissions: true,
+        },
+      });
+
+      let structuredOutput: Record<string, unknown> = {};
+      const metadata: Record<string, unknown> = {};
+
+      for await (const message of conversation) {
+        if (message.type === "assistant") {
+          const text = extractTextFromContent(
+            message.message?.content ?? [],
+          );
+          if (text) {
+            sender.sendAssistantMessage([text]);
+          }
+        } else if (message.type === "result") {
+          metadata.duration_ms = message.duration_ms;
+          metadata.duration_api_ms = message.duration_api_ms;
+          metadata.num_turns = message.num_turns;
+          metadata.total_cost_usd = message.total_cost_usd;
+          metadata.usage = message.usage;
+          metadata.session_id = message.session_id;
+
+          if (message.subtype === "success") {
+            if (message.structured_output != null) {
+              structuredOutput =
+                message.structured_output as Record<string, unknown>;
+            } else {
+              structuredOutput = { result: message.result };
+            }
+          } else {
+            structuredOutput = {
+              error: message.subtype,
+              errors: "errors" in message ? message.errors : [],
+            };
+            sender.sendErrorMessage(
+              `Agent ended with ${message.subtype}`,
+              metadata,
+            );
+          }
+        }
+      }
+
+      return { structuredOutput, metadata };
+    } finally {
+      invocation.signal.removeEventListener("abort", onAbort);
+    }
+  },
+};

package/src/cli.ts

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+
+import { execSync } from "child_process";
+import path from "path";
+import { RuntimeUseServer } from "./server.js";
+import { openaiHandler } from "./openai-handler.js";
+import { claudeHandler } from "./claude-handler.js";
+import type { AgentHandler } from "./agent-handler.js";
+
+const BUILTIN_AGENTS = ["openai", "claude"] as const;
+type BuiltinAgent = (typeof BUILTIN_AGENTS)[number];
+
+function usage(): never {
+  console.log(`Usage: runtimeuse [options]
+
+Options:
+  --handler <path>           Path to a custom JS/TS module exporting an AgentHandler
+  --agent <openai|claude>    Built-in agent SDK to use (default: openai)
+  --port <number>            WebSocket server port (default: 8080)
+  --default-model <name>     Default model identifier
+  -h, --help                 Show this help message`);
+  process.exit(0);
+}
+
+function parseArgs(args: string[]): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "-h" || arg === "--help") {
+      usage();
+    }
+    if (arg.startsWith("--") && i + 1 < args.length) {
+      const key = arg.slice(2);
+      result[key] = args[++i];
+    }
+  }
+  return result;
+}
+
+function checkClaudeCli(): void {
+  try {
+    execSync("claude --version", { stdio: "ignore" });
+  } catch {
+    console.error(
+      "Error: the Claude handler requires the Claude CLI (`claude`) to be installed.\n" +
+        "Install it with: npm install -g @anthropic-ai/claude-code\n" +
+        "Or use the OpenAI handler with --agent openai (default)",
+    );
+    process.exit(1);
+  }
+}
+
+function getBuiltinHandler(agent: BuiltinAgent): AgentHandler {
+  if (agent === "claude") {
+    checkClaudeCli();
+    return claudeHandler;
+  }
+  return openaiHandler;
+}
+
+async function loadHandler(handlerPath: string): Promise<AgentHandler> {
+  const resolved = path.resolve(handlerPath);
+  const mod = await import(resolved);
+  const handler: AgentHandler | undefined =
+    mod.default?.run ? mod.default : mod.handler;
+
+  if (!handler?.run) {
+    console.error(
+      `Error: module at ${handlerPath} must export an AgentHandler (as default or named "handler")`,
+    );
+    process.exit(1);
+  }
+  return handler;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  let handler: AgentHandler;
+  if (args.handler) {
+    handler = await loadHandler(args.handler);
+  } else {
+    const agent = (args.agent ?? "openai") as BuiltinAgent;
+    if (!BUILTIN_AGENTS.includes(agent)) {
+      console.error(
+        `Error: unknown agent "${args.agent}". Choose one of: ${BUILTIN_AGENTS.join(", ")}`,
+      );
+      process.exit(1);
+    }
+    handler = getBuiltinHandler(agent);
+  }
+
+  const port = args.port ? parseInt(args.port, 10) : undefined;
+
+  const server = new RuntimeUseServer({
+    handler,
+    port,
+    defaultModel: args["default-model"],
+  });
+
+  await server.start();
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});