runtimeuse 0.2.0

package/dist/utils.js

@@ -0,0 +1,32 @@
+export async function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Recursively redact secret values from an arbitrary data structure.
+ * Any string that contains a secret will have that secret replaced with [REDACTED].
+ */
+export function redactSecrets(value, secrets) {
+    if (secrets.length === 0)
+        return value;
+    if (typeof value === "string") {
+        let redacted = value;
+        for (const secret of secrets) {
+            if (secret && redacted.includes(secret)) {
+                redacted = redacted.replaceAll(secret, "[REDACTED]");
+            }
+        }
+        return redacted;
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => redactSecrets(item, secrets));
+    }
+    if (value !== null && typeof value === "object") {
+        const result = {};
+        for (const [key, val] of Object.entries(value)) {
+            result[key] = redactSecrets(val, secrets);
+        }
+        return result;
+    }
+    return value;
+}
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,EAAU;IACpC,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAI,KAAQ,EAAE,OAAiB;IAC1D,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAEvC,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,IAAI,QAAQ,GAAW,KAAK,CAAC;QAC7B,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,IAAI,MAAM,IAAI,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;gBACxC,QAAQ,GAAG,QAAQ,CAAC,UAAU,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;YACvD,CAAC;QACH,CAAC;QACD,OAAO,QAAa,CAAC;IACvB,CAAC;IAED,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,aAAa,CAAC,IAAI,EAAE,OAAO,CAAC,CAAM,CAAC;IAChE,CAAC;IAED,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,MAAM,MAAM,GAA4B,EAAE,CAAC;QAC3C,KAAK,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YAC/C,MAAM,CAAC,GAAG,CAAC,GAAG,aAAa,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAC5C,CAAC;QACD,OAAO,MAAW,CAAC;IACrB,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/utils.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=utils.test.d.ts.map

package/dist/utils.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.test.d.ts","sourceRoot":"","sources":["../src/utils.test.ts"],"names":[],"mappings":""}

package/dist/utils.test.js

@@ -0,0 +1,92 @@
+import { describe, it, expect } from "vitest";
+import { redactSecrets } from "./utils.js";
+describe("redactSecrets", () => {
+    describe("strings", () => {
+        it("replaces a secret within a string", () => {
+            expect(redactSecrets("token is abc123", ["abc123"])).toBe("token is [REDACTED]");
+        });
+        it("replaces multiple occurrences of the same secret", () => {
+            expect(redactSecrets("abc123 and abc123", ["abc123"])).toBe("[REDACTED] and [REDACTED]");
+        });
+        it("replaces multiple different secrets", () => {
+            expect(redactSecrets("key=SECRET1 pass=SECRET2", ["SECRET1", "SECRET2"])).toBe("key=[REDACTED] pass=[REDACTED]");
+        });
+        it("returns string unchanged when no secrets match", () => {
+            expect(redactSecrets("nothing here", ["xyz"])).toBe("nothing here");
+        });
+        it("skips empty-string secrets", () => {
+            expect(redactSecrets("hello", [""])).toBe("hello");
+        });
+    });
+    describe("arrays", () => {
+        it("redacts secrets inside array elements", () => {
+            expect(redactSecrets(["key=SECRET", "ok"], ["SECRET"])).toEqual([
+                "key=[REDACTED]",
+                "ok",
+            ]);
+        });
+        it("handles nested arrays", () => {
+            expect(redactSecrets([["SECRET"]], ["SECRET"])).toEqual([
+                ["[REDACTED]"],
+            ]);
+        });
+    });
+    describe("objects", () => {
+        it("redacts secrets in object values", () => {
+            expect(redactSecrets({ token: "my-SECRET-value", count: 5 }, ["SECRET"])).toEqual({ token: "my-[REDACTED]-value", count: 5 });
+        });
+        it("redacts secrets in deeply nested objects", () => {
+            const input = {
+                level1: {
+                    level2: {
+                        value: "contains SECRET here",
+                    },
+                },
+            };
+            expect(redactSecrets(input, ["SECRET"])).toEqual({
+                level1: {
+                    level2: {
+                        value: "contains [REDACTED] here",
+                    },
+                },
+            });
+        });
+        it("handles mixed objects with arrays", () => {
+            const input = {
+                args: ["--token=SECRET", "--verbose"],
+                env: { API_KEY: "SECRET" },
+            };
+            expect(redactSecrets(input, ["SECRET"])).toEqual({
+                args: ["--token=[REDACTED]", "--verbose"],
+                env: { API_KEY: "[REDACTED]" },
+            });
+        });
+    });
+    describe("non-string primitives", () => {
+        it("returns numbers unchanged", () => {
+            expect(redactSecrets(42, ["42"])).toBe(42);
+        });
+        it("returns booleans unchanged", () => {
+            expect(redactSecrets(true, ["true"])).toBe(true);
+        });
+        it("returns null unchanged", () => {
+            expect(redactSecrets(null, ["null"])).toBeNull();
+        });
+        it("returns undefined unchanged", () => {
+            expect(redactSecrets(undefined, ["undefined"])).toBeUndefined();
+        });
+    });
+    describe("edge cases", () => {
+        it("returns value unchanged when secrets list is empty", () => {
+            const input = { key: "value" };
+            expect(redactSecrets(input, [])).toBe(input);
+        });
+        it("handles overlapping secrets (longer secret first)", () => {
+            expect(redactSecrets("my-secret-key", ["my-secret-key", "secret"])).toBe("[REDACTED]");
+        });
+        it("handles overlapping secrets (shorter secret first)", () => {
+            expect(redactSecrets("my-secret-key", ["secret", "my-secret-key"])).toBe("my-[REDACTED]-key");
+        });
+    });
+});
+//# sourceMappingURL=utils.test.js.map

package/dist/utils.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.test.js","sourceRoot":"","sources":["../src/utils.test.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "runtimeuse",
+  "version": "0.2.0",
+  "description": "AI agent runtime with WebSocket protocol, artifact handling, and secret management",
+  "license": "BSL-1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "runtimeuse": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "dev-publish": "bash scripts/dev-publish.sh"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.73",
+    "@openai/agents": "^0.6.0",
+    "archiver": "^7.0.1",
+    "chokidar": "^5.0.0",
+    "ignore": "^7.0.5",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/archiver": "^7.0.0",
+    "@types/node": "^22.10.0",
+    "@types/ws": "^8.5.13",
+    "typescript": "^5.7.0",
+    "vitest": "^4.0.18"
+  }
+}

package/scripts/dev-publish.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ENV_FILE="$SCRIPT_DIR/../.env"
+if [ -f "$ENV_FILE" ]; then
+  set -a
+  source "$ENV_FILE"
+  set +a
+fi
+
+S3_BUCKET="${S3_BUCKET:?S3_BUCKET env var is required (set in .env or pass inline)}"
+S3_PREFIX="${S3_PREFIX:-local-dev}"
+PRESIGN_EXPIRY="${PRESIGN_EXPIRY:-3600}"
+TIMESTAMP=$(date +%Y%m%d-%H%M%S)
+ZIP_NAME="runtimeuse-dev-${TIMESTAMP}.zip"
+PROJECT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+STAGING_DIR=$(mktemp -d)
+
+cleanup() { rm -rf "$STAGING_DIR" "$PROJECT_DIR/$ZIP_NAME"; }
+trap cleanup EXIT
+
+echo "Building..."
+npm run build --prefix "$PROJECT_DIR"
+
+echo "Staging package..."
+cp "$PROJECT_DIR/package.json" "$STAGING_DIR/"
+cp -r "$PROJECT_DIR/dist" "$STAGING_DIR/dist"
+(cd "$STAGING_DIR" && npm install --omit=dev --ignore-scripts)
+
+echo "Creating zip..."
+(cd "$STAGING_DIR" && zip -qr "$PROJECT_DIR/$ZIP_NAME" .)
+
+S3_KEY="${S3_PREFIX}/${ZIP_NAME}"
+echo "Uploading to s3://${S3_BUCKET}/${S3_KEY}..."
+aws s3 cp "$PROJECT_DIR/$ZIP_NAME" "s3://${S3_BUCKET}/${S3_KEY}"
+
+URL=$(aws s3 presign "s3://${S3_BUCKET}/${S3_KEY}" --expires-in "$PRESIGN_EXPIRY")
+
+echo ""
+echo "Download URL (expires in ${PRESIGN_EXPIRY}s):"
+echo "$URL"
+echo ""
+echo "Quick start:"
+echo "  curl -L \"$URL\" -o runtimeuse.zip && unzip -o runtimeuse.zip -d runtimeuse && node runtimeuse/dist/cli.js & echo \"RuntimeUse WS server started (PID \$!)\""

package/src/agent-handler.ts

@@ -0,0 +1,26 @@
+import type { Logger } from "./logger.js";
+
+export interface AgentInvocation {
+  systemPrompt: string;
+  userPrompt: string;
+  outputFormat: { type: "json_schema"; schema: Record<string, unknown> };
+  model: string;
+  secrets: string[];
+  env: Record<string, string>;
+  signal: AbortSignal;
+  logger: Logger;
+}
+
+export interface AgentResult {
+  structuredOutput: Record<string, unknown>;
+  metadata?: Record<string, unknown>;
+}
+
+export interface MessageSender {
+  sendAssistantMessage(textBlocks: string[]): void;
+  sendErrorMessage(error: string, metadata?: Record<string, unknown>): void;
+}
+
+export interface AgentHandler {
+  run(invocation: AgentInvocation, sender: MessageSender): Promise<AgentResult>;
+}

package/src/artifact-manager.test.ts

@@ -0,0 +1,320 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+const mockWatcher = {
+  on: vi.fn().mockReturnThis(),
+  close: vi.fn().mockResolvedValue(undefined),
+};
+
+vi.mock("chokidar", () => ({
+  default: { watch: vi.fn(() => mockWatcher) },
+}));
+
+vi.mock("./storage.js", () => ({
+  uploadFile: vi.fn().mockResolvedValue(true),
+}));
+
+vi.mock("fs", async () => {
+  const actual = await vi.importActual<typeof import("fs")>("fs");
+  return {
+    ...actual,
+    default: {
+      ...actual,
+      existsSync: vi.fn(() => false),
+      readFileSync: vi.fn(() => ""),
+      createWriteStream: vi.fn(),
+    },
+  };
+});
+
+import fs from "fs";
+import chokidar from "chokidar";
+import {
+  ArtifactManager,
+  type ArtifactManagerConfig,
+} from "./artifact-manager.js";
+import { UploadTracker } from "./upload-tracker.js";
+import { uploadFile } from "./storage.js";
+
+function createManager(overrides: Partial<ArtifactManagerConfig> = {}) {
+  const send = vi.fn();
+  const uploadTracker = new UploadTracker();
+  const config: ArtifactManagerConfig = {
+    artifactsDir: "/tmp/artifacts",
+    uploadTracker,
+    send,
+    ...overrides,
+  };
+  const manager = new ArtifactManager(config);
+  return { manager, send, uploadTracker };
+}
+
+function getHandler(event: string) {
+  const call = mockWatcher.on.mock.calls.find((c: unknown[]) => c[0] === event);
+  if (!call) throw new Error(`No handler for "${event}"`);
+  return call[1] as (path: string, stats?: any) => void;
+}
+
+const fileStats = (size = 1024) => ({ isFile: () => true, size });
+const dirStats = () => ({ isFile: () => false, size: 4096 });
+
+describe("ArtifactManager", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockWatcher.on.mockReturnThis();
+    mockWatcher.close.mockResolvedValue(undefined);
+  });
+
+  describe("constructor", () => {
+    it("creates a chokidar watcher on the artifacts directory", () => {
+      createManager();
+      expect(chokidar.watch).toHaveBeenCalledWith("/tmp/artifacts", {
+        awaitWriteFinish: true,
+        alwaysStat: true,
+      });
+    });
+
+    it("registers add and change handlers", () => {
+      createManager();
+      const events = mockWatcher.on.mock.calls.map((c: unknown[]) => c[0]);
+      expect(events).toContain("add");
+      expect(events).toContain("change");
+    });
+  });
+
+  describe("file event handling", () => {
+    it("sends upload request for a new file", () => {
+      const { send } = createManager();
+      getHandler("add")("/tmp/artifacts/screenshot.png", fileStats());
+
+      expect(send).toHaveBeenCalledWith({
+        message_type: "artifact_upload_request_message",
+        artifact_type: "screenshot",
+        filename: "screenshot.png",
+        filepath: "/tmp/artifacts/screenshot.png",
+      });
+    });
+
+    it("sends upload request for a changed file", () => {
+      const { send } = createManager();
+      getHandler("change")("/tmp/artifacts/video.webm", fileStats());
+
+      expect(send).toHaveBeenCalledWith(
+        expect.objectContaining({
+          artifact_type: "video",
+          filename: "video.webm",
+        }),
+      );
+    });
+
+    it.each([
+      ["/a/video.webm", "video"],
+      ["/a/shot.png", "screenshot"],
+      ["/a/calls.ndjson", "tool_calls"],
+      ["/a/script.js", "javascript"],
+      ["/a/script.py", "python"],
+      ["/a/run.sh", "shellscript"],
+      ["/a/data.txt", "other"],
+      ["/a/readme.md", "other"],
+    ])("maps %s to artifact type %s", (filepath, expectedType) => {
+      const { send } = createManager();
+      getHandler("add")(filepath, fileStats());
+      expect(send).toHaveBeenCalledWith(
+        expect.objectContaining({ artifact_type: expectedType }),
+      );
+    });
+
+    it("skips directories", () => {
+      const { send } = createManager();
+      getHandler("add")("/tmp/artifacts/subdir", dirStats());
+      expect(send).not.toHaveBeenCalled();
+    });
+
+    it("skips empty files", () => {
+      const { send } = createManager();
+      getHandler("add")("/tmp/artifacts/empty.png", fileStats(0));
+      expect(send).not.toHaveBeenCalled();
+    });
+
+    it("skips files with no stats", () => {
+      const { send } = createManager();
+      getHandler("add")("/tmp/artifacts/mystery.png", undefined);
+      expect(send).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("handleUploadResponse", () => {
+    it("uploads the file via presigned URL", async () => {
+      const { manager } = createManager();
+      getHandler("add")("/tmp/artifacts/shot.png", fileStats());
+
+      await manager.handleUploadResponse({
+        message_type: "artifact_upload_response_message",
+        filename: "shot.png",
+        filepath: "/tmp/artifacts/shot.png",
+        presigned_url: "https://s3.example.com/upload",
+        content_type: "image/png",
+      });
+
+      expect(uploadFile).toHaveBeenCalledWith(
+        "/tmp/artifacts/shot.png",
+        "https://s3.example.com/upload",
+        "image/png",
+        expect.any(Object),
+      );
+    });
+
+    it("resolves the pending request after upload", async () => {
+      const { manager } = createManager();
+      getHandler("add")("/tmp/artifacts/shot.png", fileStats());
+
+      const waitPromise = manager.waitForPendingRequests(5000);
+
+      await manager.handleUploadResponse({
+        message_type: "artifact_upload_response_message",
+        filename: "shot.png",
+        filepath: "/tmp/artifacts/shot.png",
+        presigned_url: "https://s3.example.com/upload",
+        content_type: "image/png",
+      });
+
+      await waitPromise;
+    });
+
+    it("swallows ENOENT errors", async () => {
+      const enoent = new Error("File not found");
+      enoent.name = "ENOENT";
+      vi.mocked(uploadFile).mockRejectedValueOnce(enoent);
+
+      const { manager } = createManager();
+      getHandler("add")("/tmp/artifacts/gone.png", fileStats());
+
+      await expect(
+        manager.handleUploadResponse({
+          message_type: "artifact_upload_response_message",
+          filename: "gone.png",
+          filepath: "/tmp/artifacts/gone.png",
+          presigned_url: "https://s3.example.com/upload",
+          content_type: "image/png",
+        }),
+      ).resolves.toBeUndefined();
+    });
+
+    it("rethrows non-ENOENT errors", async () => {
+      vi.mocked(uploadFile).mockRejectedValueOnce(new Error("network error"));
+
+      const { manager } = createManager();
+      getHandler("add")("/tmp/artifacts/shot.png", fileStats());
+
+      await expect(
+        manager.handleUploadResponse({
+          message_type: "artifact_upload_response_message",
+          filename: "shot.png",
+          filepath: "/tmp/artifacts/shot.png",
+          presigned_url: "https://s3.example.com/upload",
+          content_type: "image/png",
+        }),
+      ).rejects.toThrow("network error");
+    });
+  });
+
+  describe("waitForPendingRequests", () => {
+    it("resolves immediately when no pending requests", async () => {
+      const { manager } = createManager();
+      await manager.waitForPendingRequests(1000);
+    });
+
+    it("times out if requests are not completed", async () => {
+      const { manager } = createManager();
+      getHandler("add")("/tmp/artifacts/shot.png", fileStats());
+
+      const start = Date.now();
+      await manager.waitForPendingRequests(50);
+      expect(Date.now() - start).toBeGreaterThanOrEqual(40);
+    });
+  });
+
+  describe("stopWatching", () => {
+    it("closes the chokidar watcher", async () => {
+      const { manager } = createManager();
+      await manager.stopWatching();
+      expect(mockWatcher.close).toHaveBeenCalled();
+    });
+  });
+
+  describe(".artifactignore", () => {
+    it("skips files matching .artifactignore patterns", () => {
+      vi.mocked(fs.existsSync).mockReturnValueOnce(true);
+      vi.mocked(fs.readFileSync).mockReturnValueOnce("*.log\ntmp/\n");
+
+      const { send } = createManager();
+      getHandler("add")("/tmp/artifacts/debug.log", fileStats());
+      expect(send).not.toHaveBeenCalled();
+    });
+
+    it("skips files in ignored directories", () => {
+      vi.mocked(fs.existsSync).mockReturnValueOnce(true);
+      vi.mocked(fs.readFileSync).mockReturnValueOnce("tmp/\n");
+
+      const { send } = createManager();
+      getHandler("add")("/tmp/artifacts/tmp/output.png", fileStats());
+      expect(send).not.toHaveBeenCalled();
+    });
+
+    it("allows files not matching .artifactignore patterns", () => {
+      vi.mocked(fs.existsSync).mockReturnValueOnce(true);
+      vi.mocked(fs.readFileSync).mockReturnValueOnce("*.log\n");
+
+      const { send } = createManager();
+      getHandler("add")("/tmp/artifacts/screenshot.png", fileStats());
+      expect(send).toHaveBeenCalledWith(
+        expect.objectContaining({ filename: "screenshot.png" }),
+      );
+    });
+
+    it("uploads all files when no .artifactignore exists", () => {
+      vi.mocked(fs.existsSync).mockReturnValueOnce(false);
+
+      const { send } = createManager();
+      getHandler("add")("/tmp/artifacts/debug.log", fileStats());
+      expect(send).toHaveBeenCalled();
+    });
+
+    it("reloads patterns when .artifactignore is added at runtime", () => {
+      const { send } = createManager();
+
+      getHandler("add")("/tmp/artifacts/debug.log", fileStats());
+      expect(send).toHaveBeenCalledTimes(1);
+
+      vi.mocked(fs.existsSync).mockReturnValueOnce(true);
+      vi.mocked(fs.readFileSync).mockReturnValueOnce("*.log\n");
+      getHandler("add")("/tmp/artifacts/.artifactignore", fileStats());
+
+      send.mockClear();
+      getHandler("add")("/tmp/artifacts/debug.log", fileStats());
+      expect(send).not.toHaveBeenCalled();
+    });
+
+    it("reloads patterns when .artifactignore is modified at runtime", () => {
+      vi.mocked(fs.existsSync).mockReturnValueOnce(true);
+      vi.mocked(fs.readFileSync).mockReturnValueOnce("*.log\n");
+      const { send } = createManager();
+
+      getHandler("add")("/tmp/artifacts/screenshot.png", fileStats());
+      expect(send).toHaveBeenCalledTimes(1);
+
+      vi.mocked(fs.existsSync).mockReturnValueOnce(true);
+      vi.mocked(fs.readFileSync).mockReturnValueOnce("*.log\n*.png\n");
+      getHandler("change")("/tmp/artifacts/.artifactignore", fileStats());
+
+      send.mockClear();
+      getHandler("add")("/tmp/artifacts/screenshot.png", fileStats());
+      expect(send).not.toHaveBeenCalled();
+    });
+
+    it("does not upload the .artifactignore file itself", () => {
+      const { send } = createManager();
+      getHandler("add")("/tmp/artifacts/.artifactignore", fileStats());
+      expect(send).not.toHaveBeenCalled();
+    });
+  });
+});