fireqa-agent 0.1.0

package/dist/auth/api-key.d.ts

@@ -0,0 +1,2 @@
+import { ConfigStore } from "../config/store.js";
+export declare function loginWithApiKey(store: ConfigStore): Promise<void>;

package/dist/auth/api-key.js

@@ -0,0 +1,39 @@
+import readline from "readline";
+import os from "os";
+export async function loginWithApiKey(store) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const token = await new Promise((resolve) => {
+        rl.question("API Key를 입력하세요 (fqa_...): ", (answer) => {
+            rl.close();
+            resolve(answer.trim());
+        });
+    });
+    if (!token.startsWith("fqa_")) {
+        console.error("올바른 API Key 형식이 아닙니다. fqa_로 시작해야 합니다.");
+        process.exit(1);
+    }
+    const config = store.load();
+    const res = await fetch(`${config.server}/api/agent/connections`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${token}`,
+        },
+        body: JSON.stringify({
+            name: `${process.env.USER ?? "agent"}@${os.hostname()}`,
+            metadata: {
+                cli: config.cli,
+                os: process.platform,
+                nodeVersion: process.version,
+            },
+        }),
+    });
+    if (!res.ok) {
+        const err = await res.json().catch(() => ({ error: "알 수 없는 오류" }));
+        console.error(`인증 실패: ${err.error}`);
+        process.exit(1);
+    }
+    store.setToken(token);
+    const data = await res.json();
+    console.log(`인증 성공! 에이전트 "${data.name}" 등록됨.`);
+}

package/dist/auth/oauth.d.ts

@@ -0,0 +1,2 @@
+import { ConfigStore } from "../config/store.js";
+export declare function loginWithOAuth(store: ConfigStore): Promise<void>;

package/dist/auth/oauth.js

@@ -0,0 +1,63 @@
+import { exec } from "child_process";
+const POLL_INTERVAL = 3000;
+const MAX_WAIT_MS = 5 * 60 * 1000;
+export async function loginWithOAuth(store) {
+    const config = store.load();
+    // Step 1: Create device auth
+    const createRes = await fetch(`${config.server}/api/auth/device`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ action: "create" }),
+    });
+    if (!createRes.ok) {
+        console.error("인증 요청 생성에 실패했습니다.");
+        process.exit(1);
+    }
+    const { deviceCode } = (await createRes.json());
+    const verificationUrl = `${config.server}/auth/device?code=${deviceCode}&source=agent`;
+    console.log("\nFireQA 인증 페이지를 브라우저에서 열고 있습니다...");
+    openBrowser(verificationUrl);
+    console.log(`\n자동으로 열리지 않으면 아래 URL을 직접 여세요:\n  ${verificationUrl}\n`);
+    console.log("FireQA 계정으로 로그인 후 에이전트 연결을 승인하세요.");
+    console.log("\n승인을 기다리는 중... (최대 5분)\n");
+    const deadline = Date.now() + MAX_WAIT_MS;
+    while (Date.now() < deadline) {
+        await sleep(POLL_INTERVAL);
+        try {
+            const pollRes = await fetch(`${config.server}/api/auth/device?code=${deviceCode}`);
+            if (pollRes.status === 202) {
+                // Still pending
+                process.stdout.write(".");
+                continue;
+            }
+            if (pollRes.ok) {
+                const data = (await pollRes.json());
+                if (data.status === "approved" && data.token) {
+                    store.setToken(data.token);
+                    console.log("\n\n인증 성공!");
+                    if (data.email) {
+                        console.log(`계정: ${data.email}`);
+                    }
+                    return;
+                }
+            }
+            // Error or expired
+            console.error("\n인증이 만료되었거나 거부되었습니다. 다시 시도해주세요.");
+            process.exit(1);
+        }
+        catch {
+            // Network error, retry
+        }
+    }
+    console.error("\n인증 시간이 초과되었습니다. 다시 시도해주세요.");
+    process.exit(1);
+}
+function openBrowser(url) {
+    const cmd = process.platform === "darwin" ? `open "${url}"` :
+        process.platform === "win32" ? `start "" "${url}"` :
+            `xdg-open "${url}"`;
+    exec(cmd, () => { }); // 실패해도 무시 (수동 URL 안내가 폴백)
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { ConfigStore } from "./config/store.js";
+import { loginWithApiKey } from "./auth/api-key.js";
+import { CLI_ADAPTERS } from "./runner/adapters.js";
+const program = new Command();
+const store = new ConfigStore();
+program
+    .name("fireqa-agent")
+    .description("FireQA Agent — connect your AI CLI to FireQA")
+    .version("0.1.0");
+program
+    .command("login")
+    .description("FireQA에 인증 (기본: OAuth, --api-key: API Key 사용)")
+    .option("--api-key", "API Key로 직접 인증")
+    .action(async (options) => {
+    if (options.apiKey) {
+        await loginWithApiKey(store);
+    }
+    else {
+        const { loginWithOAuth } = await import("./auth/oauth.js");
+        await loginWithOAuth(store);
+    }
+});
+program
+    .command("config")
+    .description("현재 설정 표시")
+    .action(() => {
+    const config = store.load();
+    const display = {
+        ...config,
+        auth: config.auth
+            ? { token: config.auth.token.slice(0, 12) + "..." }
+            : undefined,
+    };
+    console.log(JSON.stringify(display, null, 2));
+});
+program
+    .command("config:set <key> <value>")
+    .description("설정값 변경 (cli, server, pollingIntervalMs)")
+    .action((key, value) => {
+    const numericKeys = ["pollingIntervalMs", "maxConcurrentTasks"];
+    const parsed = numericKeys.includes(key) ? parseInt(value, 10) : value;
+    store.save({ [key]: parsed });
+    console.log(`${key} = ${parsed}`);
+});
+program
+    .command("start")
+    .description("에이전트 시작 — FireQA 작업 큐를 폴링하고 CLI를 실행")
+    .option("--cli-type <type>", "사용할 LLM CLI 타입 (claude | codex | gemini)", "claude")
+    .action(async (options) => {
+    const cliType = Object.keys(CLI_ADAPTERS).find(v => v === options.cliType) ?? "claude";
+    store.save({ cliType, cli: CLI_ADAPTERS[cliType].defaultCommand });
+    const { startAgent } = await import("./runner/task-poller.js");
+    await startAgent(store);
+});
+program.parse();

package/dist/config/store.d.ts

@@ -0,0 +1,20 @@
+import type { CliType } from "../runner/adapters.js";
+export type AgentMode = "self_hosted" | "hosted";
+export type AgentConfig = {
+    server: string;
+    auth?: {
+        token: string;
+    };
+    cliType: CliType;
+    cli: string;
+    pollingIntervalMs: number;
+    maxConcurrentTasks: number;
+    mode: AgentMode;
+};
+export declare class ConfigStore {
+    private configPath;
+    constructor(configDir?: string);
+    load(): AgentConfig;
+    save(partial: Partial<AgentConfig>): void;
+    setToken(token: string): void;
+}

package/dist/config/store.js

@@ -0,0 +1,53 @@
+import fs from "fs";
+import path from "path";
+import os from "os";
+const DEFAULTS = {
+    server: "https://fireqa.vercel.app",
+    cliType: "claude",
+    cli: "claude",
+    pollingIntervalMs: 3000,
+    maxConcurrentTasks: 1,
+    mode: "self_hosted",
+};
+export class ConfigStore {
+    configPath;
+    constructor(configDir) {
+        const dir = configDir ?? path.join(os.homedir(), ".fireqa");
+        this.configPath = path.join(dir, "config.json");
+    }
+    load() {
+        // 환경변수 우선 (hosted 모드에서 Docker ENV로 주입)
+        const envOverrides = {};
+        if (process.env.FIREQA_SERVER)
+            envOverrides.server = process.env.FIREQA_SERVER;
+        if (process.env.FIREQA_TOKEN)
+            envOverrides.auth = { token: process.env.FIREQA_TOKEN };
+        if (process.env.FIREQA_CLI)
+            envOverrides.cli = process.env.FIREQA_CLI;
+        if (process.env.FIREQA_MODE)
+            envOverrides.mode = process.env.FIREQA_MODE;
+        if (process.env.FIREQA_POLLING_INTERVAL)
+            envOverrides.pollingIntervalMs = parseInt(process.env.FIREQA_POLLING_INTERVAL, 10);
+        let fileConfig = {};
+        try {
+            const raw = fs.readFileSync(this.configPath, "utf-8");
+            fileConfig = JSON.parse(raw);
+        }
+        catch {
+            // 파일 없으면 무시
+        }
+        return { ...DEFAULTS, ...fileConfig, ...envOverrides };
+    }
+    save(partial) {
+        const current = this.load();
+        const merged = { ...current, ...partial };
+        const dir = path.dirname(this.configPath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        fs.writeFileSync(this.configPath, JSON.stringify(merged, null, 2));
+    }
+    setToken(token) {
+        this.save({ auth: { token } });
+    }
+}

package/dist/reporter/api-client.d.ts

@@ -0,0 +1,23 @@
+import type { AgentConfig } from "../config/store.js";
+import type { ParsedChunk } from "../runner/output-parser.js";
+export declare class ApiClient {
+    private baseUrl;
+    private token;
+    constructor(config: AgentConfig);
+    private headers;
+    registerConnection(name: string, metadata: Record<string, unknown>): Promise<{
+        id: string;
+    }>;
+    heartbeat(connectionId: string): Promise<{
+        cancelledTaskIds: string[];
+    }>;
+    disconnect(connectionId: string): Promise<void>;
+    getNextTask(connectionId: string): Promise<unknown | null>;
+    updateTaskStatus(taskId: string, status: string, extra?: {
+        errorMessage?: string;
+        sessionId?: string;
+    }): Promise<void>;
+    sendOutput(taskId: string, chunks: ParsedChunk[]): Promise<void>;
+    flushPendingOutputs(): Promise<void>;
+    sendResult(taskId: string, result: unknown, sessionId?: string): Promise<void>;
+}

package/dist/reporter/api-client.js

@@ -0,0 +1,147 @@
+import fs from "fs";
+import fsp from "fs/promises";
+import path from "path";
+import os from "os";
+// 전송 실패 시 임시 저장할 디렉토리
+const PENDING_DIR = path.join(os.homedir(), ".fireqa", "pending");
+// 지수 백오프 재시도 후 실패 시 디스크에 저장하고 에러를 throw
+async function retrySendOutput(url, headers, body, taskId, chunks) {
+    const delays = [1000, 2000, 4000];
+    let lastError = null;
+    for (let attempt = 0; attempt <= delays.length; attempt++) {
+        if (attempt > 0) {
+            await sleep(delays[attempt - 1]);
+        }
+        try {
+            const res = await fetch(url, { method: "POST", headers, body });
+            if (res.ok)
+                return;
+            lastError = new Error(`HTTP ${res.status}`);
+        }
+        catch (err) {
+            lastError = err instanceof Error ? err : new Error(String(err));
+        }
+    }
+    // 모든 재시도 실패 — 디스크에 저장
+    try {
+        fs.mkdirSync(PENDING_DIR, { recursive: true });
+        const filename = `${taskId}-${Date.now()}.json`;
+        fs.writeFileSync(path.join(PENDING_DIR, filename), JSON.stringify({ taskId, chunks, timestamp: Date.now() }));
+    }
+    catch {
+        // 디스크 쓰기 실패는 무시
+    }
+    throw lastError ?? new Error("sendOutput failed");
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export class ApiClient {
+    baseUrl;
+    token;
+    constructor(config) {
+        this.baseUrl = config.server;
+        this.token = config.auth?.token ?? "";
+    }
+    headers() {
+        return {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${this.token}`,
+        };
+    }
+    async registerConnection(name, metadata) {
+        const res = await fetch(`${this.baseUrl}/api/agent/connections`, {
+            method: "POST",
+            headers: this.headers(),
+            body: JSON.stringify({ name, metadata }),
+        });
+        if (!res.ok)
+            throw new Error(`등록 실패: ${res.status}`);
+        return res.json();
+    }
+    async heartbeat(connectionId) {
+        const res = await fetch(`${this.baseUrl}/api/agent/connections/${connectionId}`, {
+            method: "PUT",
+            headers: this.headers(),
+            body: JSON.stringify({}),
+        });
+        if (!res.ok)
+            throw new Error(`heartbeat 실패: ${res.status}`);
+        return res.json();
+    }
+    async disconnect(connectionId) {
+        await fetch(`${this.baseUrl}/api/agent/connections/${connectionId}`, {
+            method: "DELETE",
+            headers: this.headers(),
+        });
+    }
+    async getNextTask(connectionId) {
+        const res = await fetch(`${this.baseUrl}/api/agent/tasks/next?connectionId=${connectionId}`, { headers: this.headers() });
+        if (!res.ok)
+            throw new Error(`작업 수령 실패: ${res.status}`);
+        const data = await res.json();
+        return data.task;
+    }
+    async updateTaskStatus(taskId, status, extra) {
+        const res = await fetch(`${this.baseUrl}/api/agent/tasks/${taskId}/status`, {
+            method: "PUT",
+            headers: this.headers(),
+            body: JSON.stringify({ status, ...extra }),
+        });
+        if (!res.ok)
+            throw new Error(`상태 변경 실패: ${res.status}`);
+    }
+    async sendOutput(taskId, chunks) {
+        const timestamped = chunks.map((c) => ({
+            ...c,
+            timestamp: new Date().toISOString(),
+        }));
+        const url = `${this.baseUrl}/api/agent/tasks/${taskId}/output`;
+        const body = JSON.stringify({ chunks: timestamped });
+        // 실패 시 1s/2s/4s 재시도, 모두 실패하면 ~/.fireqa/pending/ 에 저장
+        await retrySendOutput(url, this.headers(), body, taskId, timestamped);
+    }
+    // 에이전트 시작 시 미전송 파일을 재전송
+    async flushPendingOutputs() {
+        let entries;
+        try {
+            entries = (await fsp.readdir(PENDING_DIR)).filter((f) => f.endsWith(".json"));
+        }
+        catch {
+            return; // 디렉토리 없으면 종료
+        }
+        const EXPIRY_MS = 7 * 24 * 60 * 60 * 1000;
+        const now = Date.now();
+        for (const file of entries) {
+            const filePath = path.join(PENDING_DIR, file);
+            try {
+                const raw = await fsp.readFile(filePath, "utf-8");
+                const data = JSON.parse(raw);
+                if (data.timestamp && now - data.timestamp > EXPIRY_MS) {
+                    await fsp.unlink(filePath);
+                    continue;
+                }
+                const res = await fetch(`${this.baseUrl}/api/agent/tasks/${data.taskId}/output`, {
+                    method: "POST",
+                    headers: this.headers(),
+                    body: JSON.stringify({ chunks: data.chunks }),
+                });
+                if (res.ok || res.status === 404) {
+                    await fsp.unlink(filePath);
+                }
+            }
+            catch {
+                // 실패 시 다음 시작 때 재시도
+            }
+        }
+    }
+    async sendResult(taskId, result, sessionId) {
+        const res = await fetch(`${this.baseUrl}/api/agent/tasks/${taskId}/result`, {
+            method: "POST",
+            headers: this.headers(),
+            body: JSON.stringify({ result, sessionId }),
+        });
+        if (!res.ok)
+            throw new Error(`결과 전송 실패: ${res.status}`);
+    }
+}

package/dist/runner/adapters.d.ts

@@ -0,0 +1,20 @@
+import { type ParsedChunk } from "./output-parser.js";
+export type CliType = "claude" | "codex" | "gemini";
+export declare const CLI_ADAPTERS: Record<CliType, {
+    label: string;
+    defaultCommand: string;
+    installUrl: string;
+    loginHint: string;
+}>;
+export type SpawnResult = {
+    exitCode: number;
+    chunks: ParsedChunk[];
+    fullOutput: string;
+};
+export declare function spawnCli(cliType: CliType, command: string, prompt: string, options?: {
+    sessionId?: string;
+    mcpTools?: string[];
+    onChunk?: (chunk: ParsedChunk) => void;
+    signal?: AbortSignal;
+    env?: Record<string, string>;
+}): Promise<SpawnResult>;

package/dist/runner/adapters.js

@@ -0,0 +1,119 @@
+import { spawn } from "child_process";
+import { parseStreamJsonLine } from "./output-parser.js";
+export const CLI_ADAPTERS = {
+    claude: {
+        label: "Claude Code",
+        defaultCommand: "claude",
+        installUrl: "https://docs.anthropic.com/claude-code",
+        loginHint: "claude auth login",
+    },
+    codex: {
+        label: "Codex CLI",
+        defaultCommand: "codex",
+        installUrl: "https://github.com/openai/codex",
+        loginHint: "codex login",
+    },
+    gemini: {
+        label: "Gemini CLI",
+        defaultCommand: "gemini",
+        installUrl: "https://github.com/google-gemini/gemini-cli",
+        loginHint: "gemini auth",
+    },
+};
+function buildArgs(cliType, prompt, sessionId) {
+    switch (cliType) {
+        case "claude":
+            return {
+                args: [
+                    "--print", prompt,
+                    "--output-format", "stream-json",
+                    ...(sessionId ? ["--resume", sessionId] : []),
+                ],
+                stdinPrompt: null,
+            };
+        case "codex": {
+            const args = ["exec", "--json"];
+            if (sessionId)
+                args.push("resume", sessionId, "-");
+            else
+                args.push("-");
+            return { args, stdinPrompt: prompt };
+        }
+        case "gemini":
+            return {
+                args: [
+                    "--output-format", "stream-json",
+                    "--approval-mode", "yolo",
+                    "--sandbox=none",
+                    "--prompt", prompt,
+                    ...(sessionId ? ["--resume", sessionId] : []),
+                ],
+                stdinPrompt: null,
+            };
+    }
+}
+export async function spawnCli(cliType, command, prompt, options) {
+    const { args, stdinPrompt } = buildArgs(cliType, prompt, options?.sessionId);
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            stdio: ["pipe", "pipe", "pipe"],
+            env: options?.env ? { ...process.env, ...options.env } : process.env,
+        });
+        if (stdinPrompt) {
+            child.stdin?.write(stdinPrompt);
+            child.stdin?.end();
+        }
+        const chunks = [];
+        let fullOutput = "";
+        let buffer = "";
+        child.stdout?.on("data", (data) => {
+            const text = data.toString();
+            fullOutput += text;
+            buffer += text;
+            const lines = buffer.split("\n");
+            buffer = lines.pop() ?? "";
+            for (const line of lines) {
+                const trimmed = line.trim();
+                if (!trimmed)
+                    continue;
+                const parsed = parseStreamJsonLine(trimmed);
+                if (parsed) {
+                    chunks.push(parsed);
+                    options?.onChunk?.(parsed);
+                }
+            }
+        });
+        child.stderr?.on("data", (data) => {
+            const errText = data.toString().trim();
+            if (errText) {
+                const errChunk = { type: "error", content: errText };
+                chunks.push(errChunk);
+                options?.onChunk?.(errChunk);
+            }
+        });
+        let killTimer;
+        const abortHandler = () => {
+            child.kill("SIGTERM");
+            killTimer = setTimeout(() => {
+                if (!child.killed)
+                    child.kill("SIGKILL");
+            }, 5000);
+        };
+        options?.signal?.addEventListener("abort", abortHandler);
+        child.on("close", (code) => {
+            clearTimeout(killTimer);
+            options?.signal?.removeEventListener("abort", abortHandler);
+            if (buffer.trim()) {
+                const parsed = parseStreamJsonLine(buffer.trim());
+                if (parsed) {
+                    chunks.push(parsed);
+                    options?.onChunk?.(parsed);
+                }
+            }
+            resolve({ exitCode: code ?? 1, chunks, fullOutput });
+        });
+        child.on("error", (err) => {
+            reject(new Error(`CLI 실행 실패: ${err.message}`));
+        });
+    });
+}

package/dist/runner/output-parser.d.ts

@@ -0,0 +1,7 @@
+export type ParsedChunk = {
+    type: "text" | "tool_use" | "tool_result" | "error";
+    content: string;
+    tool?: string;
+    sessionId?: string;
+};
+export declare function parseStreamJsonLine(line: string): ParsedChunk | null;

package/dist/runner/output-parser.js

@@ -0,0 +1,27 @@
+export function parseStreamJsonLine(line) {
+    try {
+        const data = JSON.parse(line);
+        if (data.type === "assistant") {
+            if (data.subtype === "text" && data.text) {
+                return { type: "text", content: data.text };
+            }
+            if (data.subtype === "tool_use" && data.tool_name) {
+                return { type: "tool_use", content: data.tool_name, tool: data.tool_name };
+            }
+        }
+        if (data.type === "tool_result") {
+            return { type: "tool_result", content: String(data.content ?? "").slice(0, 500) };
+        }
+        if (data.type === "result") {
+            return {
+                type: "text",
+                content: String(data.result ?? ""),
+                sessionId: data.session_id ?? undefined, // 다음 작업의 --resume에 사용
+            };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/runner/task-poller.d.ts

@@ -0,0 +1,2 @@
+import { ConfigStore } from "../config/store.js";
+export declare function startAgent(store: ConfigStore): Promise<void>;

package/dist/runner/task-poller.js

@@ -0,0 +1,294 @@
+import { ApiClient } from "../reporter/api-client.js";
+import { spawnCli, CLI_ADAPTERS } from "./adapters.js";
+import { execSync } from "child_process";
+import { readFileSync } from "fs";
+import os from "os";
+// 실행 중인 작업의 AbortController를 추적하여 heartbeat에서 취소 신호를 전달
+const runningTasks = new Map();
+// 네트워크 재연결을 위한 exponential backoff 계산
+const MAX_BACKOFF_MS = 60_000;
+const BASE_DELAY_MS = 1_000;
+function getBackoffDelay(consecutiveFailures) {
+    if (consecutiveFailures === 0)
+        return 0;
+    const delay = Math.min(BASE_DELAY_MS * Math.pow(2, consecutiveFailures - 1), MAX_BACKOFF_MS);
+    return delay + Math.random() * 1000; // jitter
+}
+let _agentVersion = "";
+function getAgentVersion() {
+    if (_agentVersion)
+        return _agentVersion;
+    try {
+        const pkgPath = new URL("../../package.json", import.meta.url);
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+        _agentVersion = pkg.version ?? "0.1.0";
+    }
+    catch {
+        _agentVersion = "0.1.0";
+    }
+    return _agentVersion;
+}
+function checkCliInstalled(cli) {
+    try {
+        execSync(`which ${cli}`, { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function startAgent(store) {
+    const config = store.load();
+    if (!config.auth?.token) {
+        console.error("먼저 로그인하세요: fireqa-agent login");
+        process.exit(1);
+    }
+    const adapter = CLI_ADAPTERS[config.cliType];
+    if (!checkCliInstalled(config.cli)) {
+        console.error(`${adapter.label} (${config.cli})가 설치되어 있지 않습니다.`);
+        console.error(`설치: ${adapter.installUrl}`);
+        console.error(`로그인: ${adapter.loginHint}`);
+        process.exit(1);
+    }
+    // hosted 모드: 서버 컨테이너에서 실행, 짧은 polling/heartbeat 간격
+    if (config.mode === "hosted") {
+        await startHostedWorker(config);
+        return;
+    }
+    const api = new ApiClient(config);
+    const agentName = `${process.env.USER ?? "agent"}@${os.hostname()}`;
+    let connection;
+    try {
+        connection = await api.registerConnection(agentName, {
+            cli: config.cli,
+            os: process.platform,
+            nodeVersion: process.version,
+            version: getAgentVersion(),
+        });
+    }
+    catch (err) {
+        console.error(`에이전트 등록 실패: ${err instanceof Error ? err.message : err}`);
+        process.exit(1);
+    }
+    console.log(`FireQA에 연결됨. 작업 대기 중... (${config.server})`);
+    // 이전 실행에서 미전송된 출력 데이터 재전송 시도
+    await api.flushPendingOutputs().catch(() => { });
+    console.log("미전송 데이터 확인 완료");
+    const cleanup = async () => {
+        console.log("\n에이전트 종료 중...");
+        await api.disconnect(connection.id).catch(() => { });
+        process.exit(0);
+    };
+    process.on("SIGINT", cleanup);
+    process.on("SIGTERM", cleanup);
+    // 10초마다 heartbeat — cancelledTaskIds를 받아 실행 중인 작업 중단
+    let heartbeatFailures = 0;
+    const heartbeatTimer = setInterval(async () => {
+        try {
+            const res = await api.heartbeat(connection.id);
+            heartbeatFailures = 0;
+            if (res.cancelledTaskIds && res.cancelledTaskIds.length > 0) {
+                for (const taskId of res.cancelledTaskIds) {
+                    const controller = runningTasks.get(taskId);
+                    if (controller) {
+                        controller.abort("cancelled");
+                        console.log(`작업 취소 신호 전송: ${taskId}`);
+                    }
+                }
+            }
+        }
+        catch {
+            heartbeatFailures++;
+            if (heartbeatFailures > 3) {
+                console.warn(`heartbeat 연속 실패 (${heartbeatFailures}회)`);
+            }
+        }
+    }, 10_000);
+    let pollingFailures = 0;
+    while (true) {
+        try {
+            const task = await api.getNextTask(connection.id);
+            pollingFailures = 0;
+            if (task) {
+                console.log(`작업 수령: [${task.type}] ${task.prompt.slice(0, 50)}...`);
+                await executeTask(config, api, task);
+            }
+        }
+        catch (err) {
+            if (err instanceof Error && err.message.includes("401")) {
+                console.error("인증 실패. API Key를 확인하세요.");
+                clearInterval(heartbeatTimer);
+                process.exit(1);
+            }
+            pollingFailures++;
+            const backoff = getBackoffDelay(pollingFailures);
+            if (pollingFailures === 1) {
+                console.warn("서버 연결 실패. 재연결 시도 중...");
+            }
+            if (backoff > 0) {
+                await sleep(backoff);
+                continue; // backoff 후 바로 재시도 (아래 pollingIntervalMs 대기 건너뜀)
+            }
+        }
+        await sleep(config.pollingIntervalMs);
+    }
+}
+// Figma MCP 가용성을 캐싱 (에이전트 수명 동안 유효)
+let figmaMcpAvailable = null;
+function checkFigmaMcp(cli) {
+    if (figmaMcpAvailable !== null)
+        return figmaMcpAvailable;
+    try {
+        const output = execSync(`${cli} mcp list 2>/dev/null`, { encoding: "utf-8", timeout: 5000 });
+        figmaMcpAvailable = output.toLowerCase().includes("figma");
+    }
+    catch {
+        figmaMcpAvailable = true; // 명령어 실패 시 검증 건너뜀 (soft fail)
+    }
+    return figmaMcpAvailable;
+}
+async function executeTask(config, api, task) {
+    // Figma MCP 미설정 감지: figma 도구가 필요한 작업인데 MCP가 없으면 사전 차단
+    const needsFigma = task.mcpTools?.some((t) => t.includes("figma")) &&
+        task.context?.figmaFileKey;
+    if (needsFigma && !checkFigmaMcp(config.cli)) {
+        await api.updateTaskStatus(task.id, "failed", {
+            errorMessage: "Figma MCP가 설정되어 있지 않습니다. 'claude mcp add figma' 명령으로 설정해주세요.",
+        });
+        console.error(`작업 실패: ${task.id} — Figma MCP 미설정`);
+        return;
+    }
+    await api.updateTaskStatus(task.id, "running");
+    const controller = new AbortController();
+    runningTasks.set(task.id, controller);
+    const timeout = setTimeout(() => controller.abort("timeout"), task.timeoutMs);
+    let chunkBuffer = [];
+    const flushInterval = setInterval(async () => {
+        if (chunkBuffer.length > 0) {
+            const toSend = [...chunkBuffer];
+            chunkBuffer = [];
+            await api.sendOutput(task.id, toSend).catch(() => { });
+        }
+    }, 500);
+    try {
+        const result = await spawnCli(config.cliType, config.cli, task.prompt, {
+            sessionId: task.sessionId ?? undefined,
+            mcpTools: task.mcpTools,
+            onChunk: (chunk) => { chunkBuffer.push(chunk); },
+            signal: controller.signal,
+        });
+        clearInterval(flushInterval);
+        if (chunkBuffer.length > 0) {
+            await api.sendOutput(task.id, chunkBuffer).catch(() => { });
+        }
+        if (result.exitCode === 0) {
+            // result 청크에서 sessionId 추출 (세션 연속성: 다음 작업에서 --resume에 사용)
+            const sessionId = result.chunks
+                .filter((c) => c.sessionId)
+                .at(-1)?.sessionId;
+            await api.sendResult(task.id, { output: result.fullOutput }, sessionId);
+            console.log(`작업 완료: ${task.id}`);
+        }
+        else {
+            await api.updateTaskStatus(task.id, "failed", {
+                errorMessage: `CLI exited with code ${result.exitCode}`,
+            });
+            console.error(`작업 실패: ${task.id} (exit code: ${result.exitCode})`);
+        }
+    }
+    catch (err) {
+        clearInterval(flushInterval);
+        const message = err instanceof Error ? err.message : "알 수 없는 오류";
+        if (controller.signal.aborted) {
+            const reason = controller.signal.reason;
+            if (reason === "cancelled") {
+                // 서버에서 이미 cancelled로 변경했으므로 상태 업데이트 불필요
+                console.log(`작업 취소됨: ${task.id}`);
+            }
+            else {
+                await api.updateTaskStatus(task.id, "timed_out", { errorMessage: "작업 시간 초과" });
+                console.error(`작업 시간 초과: ${task.id}`);
+            }
+        }
+        else {
+            await api.updateTaskStatus(task.id, "failed", { errorMessage: message });
+            console.error(`작업 실패: ${task.id} — ${message}`);
+        }
+    }
+    finally {
+        clearTimeout(timeout);
+        clearInterval(flushInterval);
+        runningTasks.delete(task.id);
+    }
+}
+async function startHostedWorker(config) {
+    const api = new ApiClient(config);
+    await api.flushPendingOutputs().catch(() => { });
+    let connection;
+    try {
+        connection = await api.registerConnection("hosted-worker", {
+            cli: config.cli,
+            os: process.platform,
+            nodeVersion: process.version,
+            version: getAgentVersion(),
+            mode: "hosted",
+        });
+    }
+    catch (err) {
+        console.error(`호스티드 워커 등록 실패: ${err instanceof Error ? err.message : err}`);
+        process.exit(1);
+    }
+    console.log(`호스티드 워커 연결됨 (${config.server})`);
+    const cleanup = async () => {
+        await api.disconnect(connection.id).catch(() => { });
+        process.exit(0);
+    };
+    process.on("SIGINT", cleanup);
+    process.on("SIGTERM", cleanup);
+    // hosted 모드: 5초 heartbeat
+    let heartbeatFailures = 0;
+    const heartbeatTimer = setInterval(async () => {
+        try {
+            const res = await api.heartbeat(connection.id);
+            heartbeatFailures = 0;
+            if (res.cancelledTaskIds?.length > 0) {
+                for (const taskId of res.cancelledTaskIds) {
+                    const controller = runningTasks.get(taskId);
+                    if (controller) {
+                        controller.abort("cancelled");
+                        console.log(`작업 취소 신호: ${taskId}`);
+                    }
+                }
+            }
+        }
+        catch {
+            heartbeatFailures++;
+            if (heartbeatFailures > 5) {
+                console.error("heartbeat 연속 실패. 워커 종료.");
+                clearInterval(heartbeatTimer);
+                process.exit(1);
+            }
+        }
+    }, 5_000);
+    // hosted 모드: 1초 간격 polling, 연속 실행
+    while (true) {
+        try {
+            const task = await api.getNextTask(connection.id);
+            if (task) {
+                console.log(`작업 수령: [${task.type}] ${task.prompt.slice(0, 50)}...`);
+                await executeTask(config, api, task);
+            }
+        }
+        catch (err) {
+            if (err instanceof Error && err.message.includes("401")) {
+                console.error("인증 실패. 워커 종료.");
+                clearInterval(heartbeatTimer);
+                process.exit(1);
+            }
+        }
+        await sleep(1000);
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "fireqa-agent",
+  "version": "0.1.0",
+  "description": "FireQA Agent CLI — connect your AI CLI (Claude Code, Codex, Gemini) to FireQA",
+  "type": "module",
+  "bin": {
+    "fireqa-agent": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/cli.ts",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "fireqa",
+    "agent",
+    "cli",
+    "claude-code",
+    "codex",
+    "gemini",
+    "qa",
+    "test-automation"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^13.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.0.0"
+  }
+}