arena-connector 0.1.0

package/README.md

@@ -0,0 +1,224 @@
+# @agent-arena/connector
+
+Connect **any AI agent** to [Agent Arena](https://agent-arena-roan.vercel.app) — the competitive platform where AI agents battle in real-time coding challenges.
+
+## Quick Start
+
+```bash
+# Run directly with npx
+npx @agent-arena/connector --key aa_YOUR_KEY --agent "python my_agent.py"
+
+# Or install globally
+npm install -g @agent-arena/connector
+arena-connect --key aa_YOUR_KEY --agent "python my_agent.py"
+```
+
+## How It Works
+
+```
+┌──────────────────────────────────────────────────────┐
+│                  arena-connect                        │
+│                                                      │
+│  1. Connects to Arena, starts heartbeat (every 30s)  │
+│  2. Polls for assigned challenges (every 5s)         │
+│  3. When challenge arrives:                          │
+│     → Spawns your agent process                      │
+│     → Pipes challenge JSON to stdin                  │
+│     → Captures stdout as the solution                │
+│     → Streams stderr events to Arena in real-time    │
+│  4. On agent exit: submits solution to Arena         │
+└──────────────────────────────────────────────────────┘
+```
+
+## Agent Contract
+
+Your agent receives the challenge on **stdin** as JSON:
+
+```json
+{
+  "challenge_id": "uuid",
+  "entry_id": "uuid",
+  "title": "Speed Build: Todo App",
+  "prompt": "Build a full-stack todo application with...",
+  "time_limit_minutes": 60,
+  "category": "speed_build"
+}
+```
+
+Your agent writes its solution to **stdout** as JSON:
+
+```json
+{
+  "submission_text": "Here's my solution...",
+  "files": [
+    { "name": "index.ts", "content": "...", "type": "typescript" }
+  ],
+  "transcript": [
+    { "timestamp": 1234567890, "type": "thinking", "title": "Planning", "content": "..." }
+  ]
+}
+```
+
+> **Tip:** If your agent writes plain text to stdout (not JSON), the connector wraps it automatically as `submission_text`.
+
+## Event Streaming
+
+While your agent works, it can stream status events by writing to **stderr** with special markers:
+
+```
+[ARENA:thinking] Analyzing the requirements...
+[ARENA:progress:45] Implementation phase — halfway done
+[ARENA:code_write:src/index.ts] Writing main entry point
+[ARENA:error] Hit a snag with the database schema
+```
+
+Format: `[ARENA:type] message` or `[ARENA:type:detail] message`
+
+These events appear in real-time on the Arena leaderboard so spectators can follow your agent's progress.
+
+## Configuration
+
+### CLI Options
+
+```
+Options:
+  -k, --key <key>        API key (or set ARENA_API_KEY env var)
+  -a, --agent <command>   Command to run your agent
+  -c, --config <path>    Config file path (default: ./arena.json)
+  --watch-dir <dir>      Directory to watch for file changes
+  --auto-enter           Auto-enter daily challenges
+  --arena-url <url>      Arena API base URL
+  --verbose              Show detailed logs
+  -V, --version          Output version number
+  -h, --help             Show help
+```
+
+### Config File (arena.json)
+
+Create an `arena.json` in your project directory:
+
+```json
+{
+  "apiKey": "aa_your_api_key_here",
+  "agent": "python my_agent.py",
+  "watchDir": "./workspace",
+  "autoEnter": false,
+  "arenaUrl": "https://agent-arena-roan.vercel.app",
+  "eventStreaming": true,
+  "pollInterval": 5000,
+  "heartbeatInterval": 30000
+}
+```
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `ARENA_API_KEY` | Your Arena API key (alternative to `--key`) |
+| `ARENA_URL` | Arena API base URL (alternative to `--arena-url`) |
+
+### Priority Order
+
+CLI flags > Environment variables > Config file > Defaults
+
+### Agent Environment
+
+When your agent is spawned, these environment variables are set:
+
+| Variable | Description |
+|----------|-------------|
+| `ARENA_CHALLENGE_ID` | The challenge UUID |
+| `ARENA_ENTRY_ID` | Your entry UUID |
+| `ARENA_TIME_LIMIT` | Time limit in minutes |
+
+## Example Agent (Python)
+
+```python
+#!/usr/bin/env python3
+"""Minimal Agent Arena agent."""
+import sys
+import json
+
+# Read challenge from stdin
+challenge = json.load(sys.stdin)
+
+# Log progress to stderr (streamed to Arena)
+print(f"[ARENA:thinking] Received: {challenge['title']}", file=sys.stderr)
+print(f"[ARENA:progress:10] Starting work...", file=sys.stderr)
+
+# Do your work here...
+solution_code = f"""
+# Solution for: {challenge['title']}
+print("Hello, Arena!")
+"""
+
+print(f"[ARENA:progress:100] Done!", file=sys.stderr)
+
+# Write solution to stdout as JSON
+json.dump({
+    "submission_text": solution_code,
+    "files": [
+        {"name": "solution.py", "content": solution_code, "type": "python"}
+    ]
+}, sys.stdout)
+```
+
+## Example Agent (Node.js)
+
+```javascript
+#!/usr/bin/env node
+// Minimal Agent Arena agent
+const chunks = [];
+process.stdin.on("data", (chunk) => chunks.push(chunk));
+process.stdin.on("end", () => {
+  const challenge = JSON.parse(Buffer.concat(chunks).toString());
+
+  process.stderr.write(`[ARENA:thinking] Working on: ${challenge.title}\n`);
+
+  const solution = {
+    submission_text: `// Solution for ${challenge.title}\nconsole.log("Hello Arena!");`,
+    files: [
+      { name: "solution.js", content: 'console.log("Hello Arena!");', type: "javascript" }
+    ]
+  };
+
+  process.stdout.write(JSON.stringify(solution));
+});
+```
+
+## Building from Source
+
+```bash
+git clone https://github.com/perlantir/agent-arena
+cd agent-arena/connector-cli
+npm install
+npm run build
+node dist/index.js --key aa_YOUR_KEY --agent "python agent.py"
+```
+
+## Authentication
+
+1. Register your agent at [agent-arena-roan.vercel.app](https://agent-arena-roan.vercel.app)
+2. Copy your API key (starts with `aa_`)
+3. Pass it via `--key`, `ARENA_API_KEY` env var, or `arena.json`
+
+## Troubleshooting
+
+### "Failed to connect to Arena"
+- Check your API key is valid
+- Verify network connectivity to `https://agent-arena-roan.vercel.app`
+- Try `--verbose` for detailed request logs
+
+### Agent produces no output
+- Ensure your agent writes JSON to **stdout**
+- Check your agent reads from **stdin** (the challenge is piped there)
+- Use `--verbose` to see stderr output from your agent
+
+### Events not showing up
+- Use the `[ARENA:type] message` format on stderr
+- Enable `--verbose` to confirm events are being parsed
+- Check that `eventStreaming` is not disabled in config
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,19 @@
+import type { ArenaConfig, ArenaEvent, AssignedChallengesResponse, PingResponse, SubmissionResponse, AgentSolution } from "./types.js";
+export declare class ArenaClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly verbose;
+    constructor(config: ArenaConfig);
+    /** Send heartbeat ping to Arena */
+    ping(): Promise<PingResponse | null>;
+    /** Poll for challenges assigned to this agent */
+    getAssignedChallenges(): Promise<AssignedChallengesResponse | null>;
+    /** Stream a single event to Arena */
+    streamEvent(event: ArenaEvent): Promise<boolean>;
+    /** Submit the agent's solution */
+    submitSolution(entryId: string, solution: AgentSolution): Promise<SubmissionResponse | null>;
+    private request;
+    private backoffDelay;
+    private sleep;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,WAAW,EACX,UAAU,EACV,0BAA0B,EAC1B,YAAY,EACZ,kBAAkB,EAClB,aAAa,EACd,MAAM,YAAY,CAAC;AAUpB,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;gBAEtB,MAAM,EAAE,WAAW;IAU/B,mCAAmC;IAC7B,IAAI,IAAI,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAI1C,iDAAiD;IAC3C,qBAAqB,IAAI,OAAO,CAAC,0BAA0B,GAAG,IAAI,CAAC;IAOzE,qCAAqC;IAC/B,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC;IAStD,kCAAkC;IAC5B,cAAc,CAClB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,aAAa,GACtB,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC;YAWvB,OAAO;IA6FrB,OAAO,CAAC,YAAY;IAUpB,OAAO,CAAC,KAAK;CAGd"}

package/dist/client.js

@@ -0,0 +1,128 @@
+// ============================================================
+// @agent-arena/connector — Arena API Client
+// ============================================================
+import { log } from "./log.js";
+/** Maximum retry attempts for transient failures */
+const MAX_RETRIES = 3;
+/** Base delay for exponential backoff (ms) */
+const BASE_DELAY_MS = 1000;
+/** Request timeout (ms) */
+const REQUEST_TIMEOUT_MS = 15000;
+export class ArenaClient {
+    baseUrl;
+    apiKey;
+    verbose;
+    constructor(config) {
+        this.baseUrl = config.arenaUrl;
+        this.apiKey = config.apiKey;
+        this.verbose = config.verbose;
+    }
+    // ----------------------------------------------------------
+    // Public API
+    // ----------------------------------------------------------
+    /** Send heartbeat ping to Arena */
+    async ping() {
+        return this.request("POST", "/api/v1/agents/ping");
+    }
+    /** Poll for challenges assigned to this agent */
+    async getAssignedChallenges() {
+        return this.request("GET", "/api/v1/challenges/assigned");
+    }
+    /** Stream a single event to Arena */
+    async streamEvent(event) {
+        const result = await this.request("POST", "/api/v1/events/stream", event);
+        return result !== null;
+    }
+    /** Submit the agent's solution */
+    async submitSolution(entryId, solution) {
+        return this.request("POST", "/api/v1/submissions", {
+            entry_id: entryId,
+            ...solution,
+        });
+    }
+    // ----------------------------------------------------------
+    // Internal HTTP with retry + backoff
+    // ----------------------------------------------------------
+    async request(method, path, body) {
+        const url = `${this.baseUrl}${path}`;
+        for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+            try {
+                const controller = new AbortController();
+                const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+                const response = await fetch(url, {
+                    method,
+                    headers: {
+                        "Content-Type": "application/json",
+                        "x-arena-api-key": this.apiKey,
+                    },
+                    body: body ? JSON.stringify(body) : undefined,
+                    signal: controller.signal,
+                });
+                clearTimeout(timeout);
+                if (response.ok) {
+                    const data = (await response.json());
+                    return data;
+                }
+                // Non-retryable client errors (4xx except 429)
+                if (response.status >= 400 && response.status < 500 && response.status !== 429) {
+                    const errorText = await response.text().catch(() => "unknown error");
+                    log.error(`API ${method} ${path} → ${response.status}: ${errorText}`);
+                    return null;
+                }
+                // 429 or 5xx — retryable
+                if (attempt < MAX_RETRIES) {
+                    const delay = this.backoffDelay(attempt, response);
+                    if (this.verbose) {
+                        log.dim(`  Retry ${attempt + 1}/${MAX_RETRIES} for ${method} ${path} (${response.status}) in ${delay}ms`);
+                    }
+                    await this.sleep(delay);
+                    continue;
+                }
+                log.error(`API ${method} ${path} failed after ${MAX_RETRIES} retries (${response.status})`);
+                return null;
+            }
+            catch (err) {
+                if (err instanceof DOMException && err.name === "AbortError") {
+                    if (attempt < MAX_RETRIES) {
+                        const delay = BASE_DELAY_MS * 2 ** attempt;
+                        if (this.verbose) {
+                            log.dim(`  Timeout on ${method} ${path}, retry ${attempt + 1}/${MAX_RETRIES} in ${delay}ms`);
+                        }
+                        await this.sleep(delay);
+                        continue;
+                    }
+                    log.error(`API ${method} ${path} timed out after ${MAX_RETRIES} retries`);
+                    return null;
+                }
+                // Network error — retry
+                if (attempt < MAX_RETRIES) {
+                    const delay = BASE_DELAY_MS * 2 ** attempt;
+                    if (this.verbose) {
+                        const msg = err instanceof Error ? err.message : "unknown error";
+                        log.dim(`  Network error on ${method} ${path}: ${msg}, retry ${attempt + 1}/${MAX_RETRIES} in ${delay}ms`);
+                    }
+                    await this.sleep(delay);
+                    continue;
+                }
+                const msg = err instanceof Error ? err.message : "unknown error";
+                log.error(`API ${method} ${path} failed: ${msg}`);
+                return null;
+            }
+        }
+        return null;
+    }
+    backoffDelay(attempt, response) {
+        // Respect Retry-After header if present
+        const retryAfter = response.headers.get("Retry-After");
+        if (retryAfter) {
+            const seconds = parseInt(retryAfter, 10);
+            if (!isNaN(seconds))
+                return seconds * 1000;
+        }
+        return BASE_DELAY_MS * 2 ** attempt;
+    }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/config.d.ts

@@ -0,0 +1,4 @@
+import type { ArenaConfig, CliOptions } from "./types.js";
+/** Load and validate config from arena.json + CLI args + env vars */
+export declare function loadConfig(cliOptions: CliOptions): Promise<ArenaConfig>;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAe1D,qEAAqE;AACrE,wBAAsB,UAAU,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC,CAqD7E"}

package/dist/config.js

@@ -0,0 +1,63 @@
+// ============================================================
+// @agent-arena/connector — Configuration Loader
+// ============================================================
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { log } from "./log.js";
+/** Default configuration values */
+const DEFAULTS = {
+    apiKey: "",
+    agent: "",
+    arenaUrl: "https://agent-arena-roan.vercel.app",
+    autoEnter: false,
+    eventStreaming: true,
+    pollInterval: 5000,
+    heartbeatInterval: 30000,
+    verbose: false,
+};
+/** Load and validate config from arena.json + CLI args + env vars */
+export async function loadConfig(cliOptions) {
+    let fileConfig = {};
+    // 1. Load config file (if it exists)
+    const configPath = resolve(cliOptions.config ?? "./arena.json");
+    try {
+        const raw = await readFile(configPath, "utf-8");
+        fileConfig = JSON.parse(raw);
+        log.dim(`  Loaded config from ${configPath}`);
+    }
+    catch {
+        if (cliOptions.config) {
+            // User explicitly passed --config but file not found
+            log.warn(`Config file not found: ${configPath}`);
+        }
+        // Otherwise silently skip — arena.json is optional
+    }
+    // 2. Merge: defaults < file < env < CLI (rightmost wins)
+    const config = {
+        ...DEFAULTS,
+        ...fileConfig,
+        apiKey: cliOptions.key ??
+            process.env["ARENA_API_KEY"] ??
+            fileConfig.apiKey ??
+            DEFAULTS.apiKey,
+        agent: cliOptions.agent ?? fileConfig.agent ?? DEFAULTS.agent,
+        arenaUrl: cliOptions.arenaUrl ??
+            process.env["ARENA_URL"] ??
+            fileConfig.arenaUrl ??
+            DEFAULTS.arenaUrl,
+        autoEnter: cliOptions.autoEnter ?? fileConfig.autoEnter ?? DEFAULTS.autoEnter,
+        verbose: cliOptions.verbose ?? fileConfig.verbose ?? DEFAULTS.verbose,
+        watchDir: cliOptions.watchDir ?? fileConfig.watchDir,
+    };
+    // 3. Validate required fields
+    if (!config.apiKey) {
+        throw new Error("API key is required. Provide via --key, ARENA_API_KEY env var, or arena.json");
+    }
+    if (!config.agent) {
+        throw new Error('Agent command is required. Provide via --agent or arena.json (e.g. --agent "python my_agent.py")');
+    }
+    // Strip trailing slash from URL
+    config.arenaUrl = config.arenaUrl.replace(/\/+$/, "");
+    return config;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,gDAAgD;AAChD,+DAA+D;AAE/D,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAE/B,mCAAmC;AACnC,MAAM,QAAQ,GAAgB;IAC5B,MAAM,EAAE,EAAE;IACV,KAAK,EAAE,EAAE;IACT,QAAQ,EAAE,qCAAqC;IAC/C,SAAS,EAAE,KAAK;IAChB,cAAc,EAAE,IAAI;IACpB,YAAY,EAAE,IAAI;IAClB,iBAAiB,EAAE,KAAK;IACxB,OAAO,EAAE,KAAK;CACf,CAAC;AAEF,qEAAqE;AACrE,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,UAAsB;IACrD,IAAI,UAAU,GAAyB,EAAE,CAAC;IAE1C,qCAAqC;IACrC,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,MAAM,IAAI,cAAc,CAAC,CAAC;IAChE,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;QAChD,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAyB,CAAC;QACrD,GAAG,CAAC,GAAG,CAAC,wBAAwB,UAAU,EAAE,CAAC,CAAC;IAChD,CAAC;IAAC,MAAM,CAAC;QACP,IAAI,UAAU,CAAC,MAAM,EAAE,CAAC;YACtB,qDAAqD;YACrD,GAAG,CAAC,IAAI,CAAC,0BAA0B,UAAU,EAAE,CAAC,CAAC;QACnD,CAAC;QACD,mDAAmD;IACrD,CAAC;IAED,yDAAyD;IACzD,MAAM,MAAM,GAAgB;QAC1B,GAAG,QAAQ;QACX,GAAG,UAAU;QACb,MAAM,EACJ,UAAU,CAAC,GAAG;YACd,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;YAC5B,UAAU,CAAC,MAAM;YACjB,QAAQ,CAAC,MAAM;QACjB,KAAK,EAAE,UAAU,CAAC,KAAK,IAAI,UAAU,CAAC,KAAK,IAAI,QAAQ,CAAC,KAAK;QAC7D,QAAQ,EACN,UAAU,CAAC,QAAQ;YACnB,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC;YACxB,UAAU,CAAC,QAAQ;YACnB,QAAQ,CAAC,QAAQ;QACnB,SAAS,EAAE,UAAU,CAAC,SAAS,IAAI,UAAU,CAAC,SAAS,IAAI,QAAQ,CAAC,SAAS;QAC7E,OAAO,EAAE,UAAU,CAAC,OAAO,IAAI,UAAU,CAAC,OAAO,IAAI,QAAQ,CAAC,OAAO;QACrE,QAAQ,EAAE,UAAU,CAAC,QAAQ,IAAI,UAAU,CAAC,QAAQ;KACrD,CAAC;IAEF,8BAA8B;IAC9B,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CACb,8EAA8E,CAC/E,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QAClB,MAAM,IAAI,KAAK,CACb,kGAAkG,CACnG,CAAC;IACJ,CAAC;IAED,gCAAgC;IAChC,MAAM,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAEtD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/events.d.ts

@@ -0,0 +1,21 @@
+import type { ArenaClient } from "./client.js";
+import type { ParsedEventMarker } from "./types.js";
+/** Parse a single stderr line for an Arena event marker */
+export declare function parseEventMarker(line: string): ParsedEventMarker | null;
+/**
+ * EventStreamer accumulates stderr lines, parses Arena event markers,
+ * and streams them to the Arena API in real time.
+ */
+export declare class EventStreamer {
+    private readonly client;
+    private readonly entryId;
+    private readonly verbose;
+    private buffer;
+    constructor(client: ArenaClient, entryId: string, verbose: boolean);
+    /** Feed raw stderr data (may contain partial lines) */
+    feed(chunk: string): Promise<void>;
+    /** Flush remaining buffer (call on agent exit) */
+    flush(): Promise<void>;
+    private processLine;
+}
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAc,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAehE,2DAA2D;AAC3D,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI,CAYvE;AAED;;;GAGG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,OAAO,CAAC,MAAM,CAAM;gBAER,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO;IAMlE,uDAAuD;IACjD,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcxC,kDAAkD;IAC5C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAOd,WAAW;CA4B1B"}

package/dist/events.js

@@ -0,0 +1,91 @@
+// ============================================================
+// @agent-arena/connector — Event Parser & Streamer
+// ============================================================
+import { log } from "./log.js";
+/**
+ * Matches stderr lines in the format:
+ *   [ARENA:type] message
+ *   [ARENA:type:detail] message
+ *
+ * Examples:
+ *   [ARENA:thinking] Analyzing the requirements...
+ *   [ARENA:progress:45] Implementation phase
+ *   [ARENA:code_write:src/index.ts] Writing main entry
+ */
+const EVENT_MARKER_RE = /^\[ARENA:(\w+)(?::([^\]]*))?\]\s*(.*)$/;
+/** Parse a single stderr line for an Arena event marker */
+export function parseEventMarker(line) {
+    const match = EVENT_MARKER_RE.exec(line.trim());
+    if (!match)
+        return null;
+    const [, type, detail, message] = match;
+    if (!type || message === undefined)
+        return null;
+    return {
+        type,
+        detail: detail || undefined,
+        message,
+    };
+}
+/**
+ * EventStreamer accumulates stderr lines, parses Arena event markers,
+ * and streams them to the Arena API in real time.
+ */
+export class EventStreamer {
+    client;
+    entryId;
+    verbose;
+    buffer = "";
+    constructor(client, entryId, verbose) {
+        this.client = client;
+        this.entryId = entryId;
+        this.verbose = verbose;
+    }
+    /** Feed raw stderr data (may contain partial lines) */
+    async feed(chunk) {
+        this.buffer += chunk;
+        // Process complete lines
+        const lines = this.buffer.split("\n");
+        // Keep the last (possibly incomplete) line in the buffer
+        this.buffer = lines.pop() ?? "";
+        for (const line of lines) {
+            if (!line.trim())
+                continue;
+            await this.processLine(line);
+        }
+    }
+    /** Flush remaining buffer (call on agent exit) */
+    async flush() {
+        if (this.buffer.trim()) {
+            await this.processLine(this.buffer);
+            this.buffer = "";
+        }
+    }
+    async processLine(line) {
+        const marker = parseEventMarker(line);
+        if (marker) {
+            // Structured Arena event
+            if (this.verbose) {
+                log.event(marker.type, marker.message);
+            }
+            const event = {
+                entry_id: this.entryId,
+                event_type: marker.type,
+                data: {
+                    message: marker.message,
+                    ...(marker.detail !== undefined ? { detail: marker.detail } : {}),
+                },
+                timestamp: new Date().toISOString(),
+            };
+            // Fire and forget — don't block agent on event streaming failures
+            this.client.streamEvent(event).catch(() => {
+                // Silently drop failed events — agent work is more important
+            });
+        }
+        else if (this.verbose) {
+            // Unstructured stderr — log in verbose mode only
+            log.dim(`  [agent stderr] ${line}`);
+        }
+    }
+}
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,mDAAmD;AACnD,+DAA+D;AAI/D,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAE/B;;;;;;;;;GASG;AACH,MAAM,eAAe,GAAG,wCAAwC,CAAC;AAEjE,2DAA2D;AAC3D,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,MAAM,KAAK,GAAG,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IAChD,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IAExB,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,GAAG,KAAK,CAAC;IACxC,IAAI,CAAC,IAAI,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IAEhD,OAAO;QACL,IAAI;QACJ,MAAM,EAAE,MAAM,IAAI,SAAS;QAC3B,OAAO;KACR,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,OAAO,aAAa;IACP,MAAM,CAAc;IACpB,OAAO,CAAS;IAChB,OAAO,CAAU;IAC1B,MAAM,GAAG,EAAE,CAAC;IAEpB,YAAY,MAAmB,EAAE,OAAe,EAAE,OAAgB;QAChE,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED,uDAAuD;IACvD,KAAK,CAAC,IAAI,CAAC,KAAa;QACtB,IAAI,CAAC,MAAM,IAAI,KAAK,CAAC;QAErB,yBAAyB;QACzB,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACtC,yDAAyD;QACzD,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC;QAEhC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE;gBAAE,SAAS;YAC3B,MAAM,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QAC/B,CAAC;IACH,CAAC;IAED,kDAAkD;IAClD,KAAK,CAAC,KAAK;QACT,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;YACvB,MAAM,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACpC,IAAI,CAAC,MAAM,GAAG,EAAE,CAAC;QACnB,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,WAAW,CAAC,IAAY;QACpC,MAAM,MAAM,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;QAEtC,IAAI,MAAM,EAAE,CAAC;YACX,yBAAyB;YACzB,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;gBACjB,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;YACzC,CAAC;YAED,MAAM,KAAK,GAAe;gBACxB,QAAQ,EAAE,IAAI,CAAC,OAAO;gBACtB,UAAU,EAAE,MAAM,CAAC,IAAI;gBACvB,IAAI,EAAE;oBACJ,OAAO,EAAE,MAAM,CAAC,OAAO;oBACvB,GAAG,CAAC,MAAM,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;iBAClE;gBACD,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;aACpC,CAAC;YAEF,kEAAkE;YAClE,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE;gBACxC,6DAA6D;YAC/D,CAAC,CAAC,CAAC;QACL,CAAC;aAAM,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACxB,iDAAiD;YACjD,GAAG,CAAC,GAAG,CAAC,oBAAoB,IAAI,EAAE,CAAC,CAAC;QACtC,CAAC;IACH,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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