evot-agent 0.5.3 → 0.6.0

package/README.md

@@ -7,7 +7,7 @@ evot에서 Vot에게 "내 컴퓨터 브라우저로 ○○ 수집해줘"라고
 
 ## 요구사항
 
-- Node 18+
+- Node 22+
 - Google Chrome
 - **백엔드(택1)** — 별도 API 키 불필요:
   - **Claude (기본)**: Claude Code 로그인(구독). 모델 크리덴셜은 로컬 Claude Code 로그인을 그대로 사용. (또는 `ANTHROPIC_API_KEY`)
@@ -37,7 +37,7 @@ npx evot-agent connect <code>      # 예: npx evot-agent connect ABCD2345
 
 ```bash
 npm install -g evot-agent
-evot-agent start                 # 기본 1분마다 폴링
+evot-agent start                 # 상시 연결(초인종). 막히면 폴링 폴백
 evot-agent install               # macOS 전용: 로그인 시 자동 시작 + 백그라운드 상주
 evot-agent uninstall             # 상주 등록 해제
 ```
@@ -52,7 +52,9 @@ evot-agent uninstall             # 상주 등록 해제
 - **다른 쓰레드로**: "...and put the results in my 'Research' thread" → 이름으로 대상 쓰레드 지정.
 - **루틴**: 루틴 지시문에 같은 식으로 쓰면 스케줄 도래 시 자동 큐잉·실행.
 
-폴링 주기는 `--interval <초>` 또는 `EVOT_AGENT_POLL_SECONDS` env로 조절(최소 30초).
+잡이 생기면 서버가 Realtime으로 깨우므로 보통 1초 안에 시작한다. WebSocket이 막힌 환경에서는
+long-poll 폴백으로 내려가며, 그 주기는 `--interval <초>` 또는 `EVOT_AGENT_POLL_SECONDS`로
+조절한다(최소 30초). `EVOT_AGENT_FORCE_POLL=1`이면 초인종을 끄고 폴백만 쓴다(진단용).
 결과는 evot 웹에서 쓰레드 새로고침 시 보이고, 텔레그램 연동 시 완료/실패 알림이 온다.
 로그(상주 등록 시): `~/.evot-agent/logs/agent.log`
 

package/bin/evot-agent.js

@@ -13,10 +13,12 @@ Usage:
 
 Normal use is "start": leave it running, then ask a Vot (in chat or a routine) to
 "use my computer's browser to …". evot queues the task; this daemon picks it up and
-appends the result as a cell in the target thread.
+appends the result as a cell in the target log. Tasks that need a decision from you
+pause and wait for your answer in evot, then carry on where they left off.
 
-  start polling: default every 60s (1 min). To change it use --interval,
-  or set EVOT_AGENT_POLL_SECONDS. Minimum 30s.
+  start keeps a live connection to evot, so tasks begin within a second. If that
+  connection is blocked (some corporate networks), it falls back to polling; use
+  --interval or EVOT_AGENT_POLL_SECONDS to pace the fallback (minimum 30s).
 
 Backend (which model drives the browser): defaults to Claude (uses your Claude Code
 login). To use Codex instead (uses your ChatGPT "codex login"), add --backend codex

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "evot-agent",
-  "version": "0.5.3",
+  "version": "0.6.0",
   "type": "module",
-  "description": "Local browser agent for evot — browses sites with Claude or Codex and appends results as cells.",
+  "description": "Local agent for evot — runs tasks on your computer with Claude or Codex and reports back into your notes.",
   "license": "MIT",
   "bin": {
     "evot-agent": "bin/evot-agent.js"
@@ -14,7 +14,7 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
   "scripts": {
     "start": "node bin/evot-agent.js"
@@ -23,6 +23,7 @@
     "@anthropic-ai/claude-agent-sdk": "0.3.202",
     "@openai/codex-sdk": "0.144.1",
     "@playwright/mcp": "0.0.77",
+    "@supabase/supabase-js": "^2.116.0",
     "playwright-core": "1.61.1"
   }
 }

package/src/backends/claude.js

@@ -64,6 +64,32 @@ export async function runClaudeJob(job) {
       strictMcpConfig: true,
       // MCP 툴은 프롬프트 없이 실행되도록 자동 승인 유지.
       allowedTools: ["mcp__playwright"],
+      // 두 번째 겹: Playwright 외 툴 호출은 hook에서 거부한다. disallowedTools는 이름 목록이라
+      // SDK가 새 내장 툴(REPL·Monitor·Workflow 등)을 추가하면 그대로 뚫리고, bypassPermissions라
+      // 확인 없이 실행된다. hook은 permissionMode와 무관하게 돌고 툴 목록은 건드리지 않으므로
+      // tools:[] 때처럼 Playwright가 사라지는 회귀는 없다(허용 접두어는 allowedTools와 동일).
+      hooks: {
+        PreToolUse: [
+          {
+            hooks: [
+              async (input) => {
+                const name = typeof input?.tool_name === "string" ? input.tool_name : "";
+                if (name.startsWith("mcp__playwright__")) return { continue: true };
+                console.warn(`[evot-agent] blocked tool call: ${name || "(unknown)"}`);
+                return {
+                  continue: true,
+                  hookSpecificOutput: {
+                    hookEventName: "PreToolUse",
+                    permissionDecision: "deny",
+                    permissionDecisionReason:
+                      "evot-agent: only Playwright browser tools are allowed",
+                  },
+                };
+              },
+            ],
+          },
+        ],
+      },
     },
   })) {
     if (message.type === "assistant") {

package/src/backends/code.js

@@ -0,0 +1,272 @@
+import { mkdir } from "node:fs/promises";
+import { query } from "@anthropic-ai/claude-agent-sdk";
+import { CODE_WORKSPACE_DIR } from "../config.js";
+
+/**
+ * kind:'code' 잡 — 유저 작업 폴더에서 도는 에이전트 루프.
+ *
+ * browse 잡(backends/claude.js)과 **정책이 정반대**라 파일을 나눈다. browse는 신뢰할 수 없는
+ * 웹 페이지를 읽으므로 bypassPermissions + 툴 3중 잠금(Playwright만)이지만, 여기는 유저 본인이
+ * 자기 셀에서 낸 지시를 자기 폴더에서 실행하는 것이라 툴을 열되 **권한을 유저에게 되묻는다**.
+ * 두 파일을 합치면 한쪽 정책이 다른 쪽으로 새기 때문에 공유는 프롬프트 상수 수준에서만 한다.
+ *
+ * 유저에게 묻는 두 경로 (2026-09-13 실측으로 확정 — 자세한 근거는
+ * backend/.claude/plans/2026-09-13-로컬-에이전트-phase0-왕복채널-플랜.md §1-A):
+ *
+ *  1) AskUserQuestion → PreToolUse 훅이 defer → 프로세스가 tool_deferred로 **끝난다**.
+ *     서버에 waiting(mode:'deferred')로 보고하고 종료. 유저가 답하면 서버가 pending_resume으로
+ *     올리고, 데몬이 다시 claim해 session_id로 --resume 한다. 노트북을 닫아도 안전한 경로다.
+ *  2) 권한 프롬프트(폴더 밖 쓰기·일반 셸 명령) → canUseTool로 올라온다. 여기서는 프로세스를
+ *     살려 둔 채 waiting(mode:'live')로 보고하고 답을 기다린다. defer가 안 되는 경로라서다
+ *     (defer는 한 턴에 툴 호출이 하나일 때만 유효하다).
+ */
+
+// 한 번의 실행이 붙들 수 있는 최대 시간. maxTurns를 쓰지 않는 이유: 턴 상한에 걸리면
+// error_max_turns로 끝나면서 **결과 텍스트가 0자**가 된다(MAKi 실측). 사람을 기다리는 동안은
+// 이 시계를 멈춘다 — 답이 늦다고 작업을 죽이면 왕복 구조 자체가 무의미해진다.
+const RUN_BUDGET_MS = 30 * 60 * 1000;
+
+// browse의 SYSTEM_APPEND와 별개. 여기서 강조할 것은 "질문은 한 번만"과 "폴더 밖으로 나가지 마라".
+// 질문 강조가 필요한 이유: defer는 모델에게 툴 내부 오류처럼 보여서, 그냥 두면 같은 턴에서
+// 재시도하며 "The interactive question tool keeps failing"류의 변명을 답에 남긴다(실측).
+const CODE_SYSTEM_APPEND = [
+  "You are running on the user's own computer, launched from a note in evot.",
+  "",
+  "ASKING THE USER:",
+  "- When you need the user to decide something, call AskUserQuestion EXACTLY ONCE and stop.",
+  "- It may look like the tool failed with an internal error. It did not. Do NOT retry it and",
+  "  do NOT apologize for it: the user answers elsewhere (in their note) and your session is",
+  "  resumed automatically with their answer.",
+  "- Never guess an answer you decided to ask for.",
+  "",
+  "SCOPE:",
+  "- Stay inside your working directory. Anything outside it, and any shell command, has to be",
+  "  approved by the user, which interrupts them — so do not reach outside without a real reason.",
+  "- If an action is refused, say plainly what you could not do instead of working around it.",
+  "",
+  "ANSWERING:",
+  "- Finish with a short summary of what you actually changed or found. No preamble.",
+].join("\n");
+
+/** 서버가 실어 보낸 답을 AskUserQuestion의 updatedInput 형태로 바꾼다. */
+function toQuestionInput(input, answer) {
+  const out = { questions: input?.questions ?? [] };
+  if (answer.answers) out.answers = answer.answers;
+  if (answer.response) out.response = answer.response;
+  return out;
+}
+
+/**
+ * 들고 있는 답이 지금 이 질문에 대한 것인가.
+ *
+ * 재개 직후 모델이 **같은 질문을 한 번 더 부르는** 일이 잦다(실측: 대기 중이던 툴이 canUseTool로
+ * 먼저 replay되고, 그 뒤 모델이 다시 AskUserQuestion을 호출한다). 답을 1회용으로 태우면 그
+ * 두 번째 호출이 또 defer돼서, 할 일을 다 해놓고도 잡이 끝나지 않는다.
+ * 반대로 무조건 재사용하면 **진짜 새 질문**에 엉뚱한 답이 붙는다.
+ * 그래서 질문 텍스트로 대조한다 — 답의 키(=질문 텍스트) 중 하나라도 겹치면 같은 질문으로 본다.
+ * 자유 응답(response)은 특정 질문에 매인 값이 아니라 어느 질문에나 쓴다.
+ */
+function answerFitsQuestions(input, answer) {
+  if (!answer) return false;
+  if (answer.response) return true;
+  const asked = (input?.questions ?? []).map((q) => q?.question).filter(Boolean);
+  const answered = Object.keys(answer.answers ?? {});
+  return asked.some((q) => answered.includes(q));
+}
+
+/**
+ * @param {object} job  agent-sync가 내려준 잡 (id, instruction, cwd, session_id, answer)
+ * @param {object} deps
+ * @param {(jobId: string) => Promise<{answer?: object, cancelled?: boolean}>} deps.waitForAnswer
+ *        유저 답이 올 때까지 기다린다(long-poll + 초인종). 취소면 {cancelled:true}.
+ * @param {(args: {jobId: string, sessionId: string|null, pendingTool: object}) => Promise<unknown>} deps.reportWaiting
+ *        "물을 게 생겨 멈췄다"를 서버에 알린다. 서버 통신을 주입받는 이유는 sync.js와의 순환
+ *        import을 피하고(waitForAnswer도 같은 이유), 이 모듈을 서버 없이 시험할 수 있게 하기 위해서다.
+ * @returns {Promise<{status:'success'|'error'|'waiting', text?:string, sessionId:string|null}>}
+ */
+export async function runCodeJob(job, { waitForAnswer, reportWaiting }) {
+  const cwd = job.cwd || CODE_WORKSPACE_DIR;
+  await mkdir(cwd, { recursive: true });
+
+  let sessionId = job.session_id ?? null;
+  // 서버가 실어 보낸 답(재개 잡). 이 실행 동안 들고 있다가 **질문이 맞을 때만** 쓴다
+  // (answerFitsQuestions 주석 참고). 새 질문이면 서버가 waiting 보고 때 answer를 비우므로
+  // 다음 실행으로 새어 나가지 않는다.
+  const pendingAnswer = job.answer ?? null;
+
+  let deferredTool = null;
+  let cancelled = false;
+  let finalText = "";
+  let isError = false;
+  const blockedTools = [];
+
+  // 실행 예산 시계. 사람을 기다리는 구간에서는 멈춘다.
+  const ac = new AbortController();
+  let budgetTimer = setTimeout(() => ac.abort(), RUN_BUDGET_MS);
+  const pauseClock = () => clearTimeout(budgetTimer);
+  const resumeClock = () => {
+    budgetTimer = setTimeout(() => ac.abort(), RUN_BUDGET_MS);
+  };
+
+  /** 유저에게 물어보고 답을 받아온다(권한 프롬프트 = live 경로). */
+  async function askUserLive(pendingTool) {
+    await reportWaiting({ jobId: job.id, sessionId, pendingTool });
+    pauseClock();
+    try {
+      return await waitForAnswer(job.id);
+    } finally {
+      resumeClock();
+    }
+  }
+
+  try {
+    for await (const message of query({
+      prompt: job.instruction,
+      options: {
+        cwd,
+        abortController: ac,
+        ...(sessionId ? { resume: sessionId } : {}),
+        // acceptEdits: 작업 폴더 안 편집은 묻지 않고, 폴더 밖·셸은 묻는다.
+        // 'auto'를 쓰지 않는 이유 — 실측(2026-09-13, CLI 2.1.202)에서 폴더 밖 쓰기와
+        // `rm -rf`까지 묻지 않고 승인해 사실상 bypass였다.
+        permissionMode: "acceptEdits",
+        // browse 백엔드와 같은 격리 원칙: 유저 전역 훅·MCP·claude.ai 커넥터를 끌어오지 않는다.
+        settingSources: [],
+        strictMcpConfig: true,
+        systemPrompt: { type: "preset", preset: "claude_code", append: CODE_SYSTEM_APPEND },
+        hooks: {
+          PreToolUse: [
+            {
+              hooks: [
+                async (input) => {
+                  if (input?.tool_name !== "AskUserQuestion") return { continue: true };
+                  if (answerFitsQuestions(input.tool_input, pendingAnswer)) {
+                    return {
+                      continue: true,
+                      hookSpecificOutput: {
+                        hookEventName: "PreToolUse",
+                        permissionDecision: "allow",
+                        updatedInput: toQuestionInput(input.tool_input, pendingAnswer),
+                      },
+                    };
+                  }
+                  // 답이 없으면 여기서 프로세스를 끝낸다(tool_deferred). 서버 보고는 루프 밖에서.
+                  return {
+                    continue: true,
+                    hookSpecificOutput: {
+                      hookEventName: "PreToolUse",
+                      permissionDecision: "defer",
+                      permissionDecisionReason: "evot: waiting for the user in their note",
+                    },
+                  };
+                },
+              ],
+            },
+          ],
+        },
+        // ★ canUseTool을 넘기지 않으면 AskUserQuestion이 툴 목록에서 아예 빠진다(실측).
+        //   권한 프롬프트 수신 창구이기도 하다.
+        canUseTool: async (toolName, input, opts) => {
+          // (1) AskUserQuestion — 재개 직후엔 훅이 아니라 이쪽으로 먼저 온다(실측).
+          if (toolName === "AskUserQuestion") {
+            if (answerFitsQuestions(input, pendingAnswer)) {
+              return { behavior: "allow", updatedInput: toQuestionInput(input, pendingAnswer) };
+            }
+            // defer가 무시되는 경우(한 턴에 툴 호출 여러 개)의 폴백 — live로 기다린다.
+            const res = await askUserLive({
+              id: opts?.toolUseID ?? null,
+              name: toolName,
+              mode: "live",
+              input,
+            });
+            if (res?.cancelled) {
+              cancelled = true;
+              return { behavior: "deny", message: "The user cancelled this task." };
+            }
+            if (res?.answer) {
+              return { behavior: "allow", updatedInput: toQuestionInput(input, res.answer) };
+            }
+            return { behavior: "deny", message: "No answer from the user." };
+          }
+
+          // (2) 권한 프롬프트 — 폴더 밖 쓰기, 일반 셸 명령 등.
+          const res = await askUserLive({
+            id: opts?.toolUseID ?? null,
+            name: toolName,
+            mode: "live",
+            input,
+            reason: opts?.decisionReason ?? null,
+            blocked_path: opts?.blockedPath ?? null,
+            suggestions: opts?.suggestions ?? null,
+          });
+          if (res?.cancelled) {
+            cancelled = true;
+            return { behavior: "deny", message: "The user cancelled this task." };
+          }
+          if (res?.answer?.decision === "allow") {
+            return { behavior: "allow", updatedInput: input };
+          }
+          // 거부는 모델이 읽는다 — 무엇을 못 했는지 답에 남기도록 이유를 함께 준다.
+          blockedTools.push(toolName);
+          const why = res?.answer?.message
+            ? `The user declined: ${res.answer.message}`
+            : "The user declined this action on their computer.";
+          return { behavior: "deny", message: `${why} Do what you can without it, and say what you could not do.` };
+        },
+      },
+    })) {
+      if (message.type === "system" && message.subtype === "init") {
+        // 재개 시에도 같은 값이 온다. 첫 실행에선 여기서만 세션 uuid를 알 수 있다.
+        sessionId = message.session_id ?? sessionId;
+      } else if (message.type === "assistant") {
+        for (const b of message.message?.content ?? []) {
+          if (b.type === "text" && b.text.trim()) process.stdout.write(".");
+        }
+      } else if (message.type === "result") {
+        // 판정은 stop_reason으로 한다 — terminal_reason은 같은 상황에서 값이 갈린다(실측).
+        if (message.stop_reason === "tool_deferred") {
+          deferredTool = message.deferred_tool_use ?? null;
+        }
+        isError = message.subtype !== "success" || message.is_error === true;
+        finalText = message.result ?? "";
+      }
+    }
+  } finally {
+    clearTimeout(budgetTimer);
+  }
+  process.stdout.write("\n");
+
+  if (cancelled) {
+    return { status: "error", text: "Cancelled on your computer.", sessionId };
+  }
+
+  // 질문에서 멈췄다 — 이 실행의 어시스턴트 텍스트는 버린다. 결과가 아니라 변명일 뿐이라
+  // (모델이 defer를 툴 오류로 읽는다) 셀에 남기면 유저가 실패로 오해한다.
+  if (deferredTool) {
+    await reportWaiting({
+      jobId: job.id,
+      sessionId,
+      pendingTool: {
+        id: deferredTool.id ?? null,
+        name: deferredTool.name ?? "AskUserQuestion",
+        mode: "deferred",
+        input: deferredTool.input ?? {},
+      },
+    });
+    return { status: "waiting", sessionId };
+  }
+
+  if (isError) {
+    const err = new Error(finalText.trim() || "The agent stopped without producing a result.");
+    err.sessionId = sessionId;
+    throw err;
+  }
+
+  let text = finalText.trim();
+  if (blockedTools.length > 0) {
+    // 거부된 툴은 모델이 답에서 잘 언급하지 않아 "무시했다"로 보인다(MAKi 실측). 꼬리를 붙인다.
+    const uniq = [...new Set(blockedTools)].join(", ");
+    text += `\n\n_Not allowed on this computer: ${uniq}_`;
+  }
+  return { status: "success", text, sessionId };
+}

package/src/config.js

@@ -5,14 +5,30 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 export const AGENT_DIR = join(homedir(), ".evot-agent");
 export const TOKEN_PATH = join(AGENT_DIR, "token.json");
 export const PROFILE_DIR = join(AGENT_DIR, "profile");
+// code 잡(작업 폴더에서 도는 에이전트)의 기본 작업 폴더. 잡이 cwd를 주지 않으면 여기서 돈다.
+export const CODE_WORKSPACE_DIR = join(AGENT_DIR, "workspace");
+
+// 서버에 밝히는 데몬 버전(X-Evot-Agent-Version). agent-sync가 이 값으로 code 잡을 내려보낼지
+// 정한다 — 구버전 데몬은 kind를 몰라 code 잡을 browse로 잘못 실행하므로 서버가 막는다.
+// package.json과 손으로 맞춘다(데몬은 번들되지 않아 import assertion을 쓰지 않는다).
+export const AGENT_VERSION = "0.6.0";
 
 // evot 백엔드 엔드포인트 주소(자격증명 아님). 유저는 아무것도 입력하지 않는다.
 // agent-redeem/agent-report는 verify_jwt=false라 게이트웨이에 anon key가 필요 없다
-// (텔레그램 봇이 telegram-webhook을 anon key 없이 호출하는 것과 동일). → 로컬엔 anon key를 두지 않는다.
+// (텔레그램 봇이 telegram-webhook을 anon key 없이 호출하는 것과 동일).
 // (스테이징 등 다른 프로젝트에 붙일 때만 env로 덮어쓴다.)
 export const SUPABASE_URL =
   process.env.EVOT_SUPABASE_URL ?? "https://vzkikgdagvxoovmzrrpc.supabase.co";
 
+// Realtime 초인종(서버→데몬 깨우기) 구독 전용 공개 키.
+// **자격증명이 아니다** — 웹앱이 브라우저에 그대로 싣는 publishable 키와 같은 값이고, 이 키로는
+// 잡을 읽을 수 없다(AgentJob은 RLS 정책 0개 + service_role 전용 grant). 깨어난 뒤 실제 잡은
+// 기존 evat_ 토큰으로 agent-sync를 불러 가져온다. 구독 토픽에 실리는 것도 job_id뿐이다.
+// 위 주석의 "로컬엔 anon key를 두지 않는다"가 여기서 바뀐 셈인데, 이유는 "필요가 없어서"였지
+// "비밀이라서"가 아니었다. 초인종에는 WebSocket 연결이 필요해 게이트웨이 키를 쓴다.
+export const SUPABASE_PUBLISHABLE_KEY =
+  process.env.EVOT_SUPABASE_KEY ?? "sb_publishable_dvIijfq1hJbtUUcLGXCNZw_wjp3KYdM";
+
 /** evot에서 발급한 전용 토큰. 계정 비밀번호/세션은 저장하지 않는다. */
 export async function loadToken() {
   let raw;

package/src/report.js

@@ -8,12 +8,22 @@ import { SUPABASE_URL, loadToken } from "./config.js";
  * - 큐 경로(데몬): jobId만 넘긴다. 서버가 잡에서 log_id를 찾아 셀을 만들고 잡 상태를 done/failed로 갱신.
  * - 수동 경로(run): logId를 넘긴다. (Phase 1 호환)
  */
-export async function reportResult({ logId, jobId, text, segments, title, status = "success" }) {
+export async function reportResult({
+  logId,
+  jobId,
+  text,
+  segments,
+  title,
+  status = "success",
+  sessionId,
+}) {
   const token = await loadToken();
 
   const body = { text, title, status };
   if (jobId) body.job_id = jobId;
   if (logId) body.log_id = logId;
+  // Claude Code 세션 uuid — 서버가 재개(--resume) 키로 보관한다. browse 잡은 안 보낸다.
+  if (sessionId) body.session_id = sessionId;
   // 섹션(설명+이미지 URL) 전달 — 서버가 votResponse 서브셀·이미지 저장에 사용.
   // 구서버는 이 필드를 무시하고 text만 쓴다(하위호환).
   if (Array.isArray(segments) && segments.length > 0) body.segments = segments;
@@ -36,3 +46,36 @@ export async function reportResult({ logId, jobId, text, segments, title, status
   }
   return data.cell_id;
 }
+
+/**
+ * "유저에게 물을 게 생겨서 멈췄다"를 서버에 알린다 → 잡이 waiting으로 바뀌고, 유저가 답하면
+ * 트리거가 데몬을 깨운다. 결과 보고가 아니므로 셀도 알림도 만들어지지 않는다.
+ *
+ * pendingTool.mode가 이후 경로를 가른다:
+ *  - "deferred": AskUserQuestion을 PreToolUse 훅이 defer해 **프로세스가 이미 끝났다**.
+ *                답이 오면 서버가 pending_resume으로 올리고, 데몬이 다시 claim해 --resume 한다.
+ *  - "live":     권한 프롬프트라 canUseTool 안에서 **아직 기다린다**. 답만 집어가면 이어진다.
+ */
+export async function reportWaiting({ jobId, sessionId, pendingTool }) {
+  const token = await loadToken();
+
+  const res = await fetch(`${SUPABASE_URL}/functions/v1/agent-report`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${token}`,
+    },
+    body: JSON.stringify({
+      job_id: jobId,
+      status: "waiting",
+      session_id: sessionId ?? null,
+      pending_tool: pendingTool,
+    }),
+  });
+
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    throw new Error(`agent-report(waiting) failed (${res.status}): ${data.error ?? "unknown"}`);
+  }
+  return data;
+}

package/src/sync.js

@@ -1,12 +1,33 @@
-import { SUPABASE_URL, loadToken } from "./config.js";
+import { createClient } from "@supabase/supabase-js";
+import {
+  AGENT_VERSION,
+  SUPABASE_PUBLISHABLE_KEY,
+  SUPABASE_URL,
+  loadToken,
+} from "./config.js";
 import { describeJobFailure, runBrowseJob } from "./browse.js";
-import { reportResult } from "./report.js";
+import { runCodeJob } from "./backends/code.js";
+import { reportResult, reportWaiting } from "./report.js";
 
-// 폴링 주기: --interval <sec> > EVOT_AGENT_POLL_SECONDS > 기본 60초(1분). 최소 30초.
-// 잡 생성(루틴 발동·대화)부터 실행까지의 지연을 폴링 대기가 지배해서 600초에서 낮췄다.
-// 더 줄여도 앞단의 cron(1분 주기)과 vot-react 추론 시간에 묻혀 체감 이득이 없다.
-const DEFAULT_INTERVAL_SEC = 60;
+// 데몬은 이제 폴링이 아니라 **초인종**으로 깨어난다: 잡이 생기면 DB 트리거가 Realtime broadcast를
+// 쏘고(agent-wake:<user_id>), 데몬이 그걸 받아 즉시 agent-sync를 부른다. 지연이 최대 60초에서
+// 1초대로 줄고, 평소 호출은 0이 된다(폴링을 5초로 줄이면 데몬 한 대가 하루 17,280번 부른다 —
+// 부담은 DB가 아니라 Edge Function 호출 수였다).
+//
+// WebSocket이 막힌 환경(회사 프록시 등)에서는 구독이 실패하고 long-poll 폴백으로 내려간다.
+// 그 경우 agent-sync가 최대 25초 기다렸다 답하므로, 폴링이어도 호출 수는 예전의 1/25 수준이다.
+
+// 초인종이 붙어 있을 때의 하트비트 주기. 이 호출이 last_seen_at을 갱신하고, 그 값이 곧
+// "지금 돌고 있는가"의 유일한 근거다(서버 판정 창 5분 — vot-react AGENT_ONLINE_WINDOW_MS).
+const HEARTBEAT_MS = 4 * 60 * 1000;
+// 폴백 모드에서 한 주기의 최소 길이. agent-sync의 long-poll(25초)이 대부분을 채운다.
+const DEFAULT_INTERVAL_SEC = 30;
 const MIN_INTERVAL_SEC = 30;
+// 사람을 기다리는 최대 시간. 이보다 오래 답이 없으면 그 툴 호출을 접는다(프로세스를 영원히
+// 붙들지 않기 위한 상한 — 잡 자체는 waiting으로 남아 나중에 답하면 재개된다).
+const ANSWER_WAIT_MAX_MS = 6 * 60 * 60 * 1000;
+// 오류 후 재시도 간격(폭주 방지).
+const ERROR_BACKOFF_MS = 5_000;
 
 function resolveIntervalSec(cliSec) {
   const fromEnv = Number(process.env.EVOT_AGENT_POLL_SECONDS);
@@ -20,15 +41,17 @@ function resolveIntervalSec(cliSec) {
 
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 
-/** agent-sync 폴링 — pending 잡을 claim해 돌려받는다. 401은 code로 구분해 던진다. */
-async function fetchJobs(token) {
+/** agent-sync 호출. 401은 code로 구분해 던진다(토큰 폐기 → 데몬 정상 종료). */
+async function syncCall(token, body) {
   const res = await fetch(`${SUPABASE_URL}/functions/v1/agent-sync`, {
     method: "POST",
     headers: {
       "Content-Type": "application/json",
       Authorization: `Bearer ${token}`,
+      // 서버는 이 값으로 code 잡을 내려보낼지 정한다(구버전 데몬 보호).
+      "X-Evot-Agent-Version": AGENT_VERSION,
     },
-    body: "{}",
+    body: JSON.stringify(body),
   });
   const data = await res.json().catch(() => ({}));
   if (res.status === 401) {
@@ -39,16 +62,122 @@ async function fetchJobs(token) {
   if (!res.ok) {
     throw new Error(`agent-sync failed (${res.status}): ${data.error ?? "unknown"}`);
   }
-  return Array.isArray(data.jobs) ? data.jobs : [];
+  return data;
+}
+
+/**
+ * 유저 답을 기다린다(권한 프롬프트 = live 경로). 서버가 한 번에 최대 25초 잡아 두므로
+ * 이 루프는 사실상 대기다. 초인종이 답을 알리면 서버 쪽 long-poll이 즉시 풀린다.
+ */
+async function waitForAnswer(token, jobId) {
+  const deadline = Date.now() + ANSWER_WAIT_MAX_MS;
+  for (;;) {
+    let data;
+    try {
+      data = await syncCall(token, { job_id: jobId });
+    } catch (err) {
+      if (err.code === 401) throw err;
+      // 일시적 네트워크 오류로 유저 답을 잃지 않도록 물러섰다 재시도한다.
+      console.error(`Waiting for your answer (will retry): ${err.message}`);
+      await sleep(ERROR_BACKOFF_MS);
+      if (Date.now() >= deadline) return {};
+      continue;
+    }
+    if (data.cancelled) return { cancelled: true };
+    if (data.answer) return { answer: data.answer };
+    if (data.gone) return {};
+    if (Date.now() >= deadline) return {};
+  }
+}
+
+/**
+ * 깨우기 신호. 대기 중이 아닐 때 온 신호도 흘리지 않도록 pending으로 들고 있는다
+ * (잡 실행 중에 다음 잡이 들어오는 흔한 경우).
+ */
+function createWaker() {
+  let pending = false;
+  let resolve = null;
+  return {
+    signal() {
+      if (resolve) {
+        const r = resolve;
+        resolve = null;
+        r("wake");
+      } else {
+        pending = true;
+      }
+    },
+    wait(ms) {
+      if (pending) {
+        pending = false;
+        return Promise.resolve("wake");
+      }
+      return new Promise((res) => {
+        const timer = setTimeout(() => {
+          resolve = null;
+          res("timeout");
+        }, ms);
+        resolve = (v) => {
+          clearTimeout(timer);
+          res(v);
+        };
+      });
+    },
+  };
 }
 
 /** 잡 1건 실행 → 결과(또는 실패 사유)를 job_id로 보고. 보고는 서버가 셀 생성 + 잡 상태 갱신. */
-async function runJob(job, localBackend) {
-  console.log(`\nJob ${job.id}: ${String(job.instruction ?? "").slice(0, 80)}`);
+async function runJob(job, localBackend, token) {
+  const kind = job.kind ?? "browse";
+  console.log(`\nJob ${job.id} (${kind}): ${String(job.instruction ?? "").slice(0, 80)}`);
+
+  if (kind === "code") {
+    // 우선순위: 로컬 오버라이드 > 서버(웹 토글)가 지정한 백엔드 > claude.
+    const backend = localBackend ?? job.backend ?? "claude";
+    if (backend !== "claude") {
+      // Codex SDK의 thread.run에는 대화형 승인·defer가 없어 이 왕복을 만들 수 없다.
+      await reportResult({
+        jobId: job.id,
+        text: `This task needs the Claude runtime. Switch the runtime to Claude in evot Settings, or start the agent with --backend claude.`,
+        title: "Local task",
+        status: "error",
+      });
+      console.error(`Job ${job.id} skipped: code jobs need the Claude runtime.`);
+      return;
+    }
+    try {
+      const { status, text, sessionId } = await runCodeJob(job, {
+        waitForAnswer: (jobId) => waitForAnswer(token, jobId),
+        reportWaiting,
+      });
+      if (status === "waiting") {
+        // code.js가 이미 waiting을 보고했다. 여기서 더 할 일이 없다 — 유저가 답하면 초인종이 온다.
+        console.log(`Job ${job.id} is waiting for your answer in evot.`);
+        return;
+      }
+      await reportResult({ jobId: job.id, text, title: "Local task", status, sessionId });
+      console.log(`Reported job ${job.id}.`);
+    } catch (err) {
+      console.error(`Job ${job.id} failed: ${err.message}`);
+      try {
+        await reportResult({
+          jobId: job.id,
+          text: err.message,
+          title: "Local task",
+          status: "error",
+          sessionId: err.sessionId,
+        });
+      } catch (reportErr) {
+        console.error(`Failed to report job ${job.id}: ${reportErr.message}`);
+      }
+    }
+    return;
+  }
+
+  // ── browse 잡(기존 Computer Use) — 정책·프롬프트가 완전히 다른 경로다 ──
   let text;
   let segments;
   let status = "success";
-  // 우선순위: 로컬 오버라이드(--backend/env) > 서버(웹 토글)가 지정한 job.backend > 기본 claude.
   const backend = localBackend ?? job.backend;
   try {
     ({ text, segments } = await runBrowseJob(
@@ -76,18 +205,61 @@ async function runJob(job, localBackend) {
 }
 
 /**
- * 데몬 모드: 주기적으로 폴링해 잡을 실행한다. 연결(전용 토큰) 안 됐으면 즉시 실패.
+ * 데몬 모드. 초인종(Realtime)으로 깨어나 잡을 실행하고, 구독이 안 되면 long-poll로 폴백한다.
  * claim은 한 번에 1건씩 내려오므로, 잡이 남아 있는 동안은 대기 없이 연속으로 소진한다.
  */
 export async function runStart(opts = {}) {
   const token = await loadToken(); // 미연결이면 여기서 throw
-  const intervalSec = resolveIntervalSec(opts.intervalSec);
+  const intervalMs = resolveIntervalSec(opts.intervalSec) * 1000;
   // 로컬 오버라이드: --backend 플래그 > EVOT_AGENT_BACKEND env. 둘 다 없거나 빈 문자열이면
   // undefined → 잡별로 서버(웹 토글)가 준 backend를 따른다(|| 로 빈 문자열도 미설정 취급).
   const localBackend = opts.backend || process.env.EVOT_AGENT_BACKEND || undefined;
-  console.log(
-    `evot-agent is running. Polling every ${intervalSec}s for tasks. Press Ctrl+C to stop.`,
-  );
+  // 검증·문제 진단용: 초인종을 끄고 폴백 경로만 태운다.
+  const forcePoll = process.env.EVOT_AGENT_FORCE_POLL === "1";
+
+  const waker = createWaker();
+  let realtimeOk = false;
+  let subscribedTopic = null;
+  let supabase = null;
+
+  function ensureSubscription(topic) {
+    if (forcePoll || !topic || topic === subscribedTopic) return;
+    subscribedTopic = topic;
+    supabase ??= createClient(SUPABASE_URL, SUPABASE_PUBLISHABLE_KEY);
+    supabase
+      .channel(topic)
+      .on("broadcast", { event: "wake" }, () => waker.signal())
+      .subscribe((status) => {
+        const wasOk = realtimeOk;
+        realtimeOk = status === "SUBSCRIBED";
+        if (realtimeOk && !wasOk) {
+          console.log("Connected to evot. Tasks will start within a second.");
+          // 구독이 붙는 사이 들어온 잡이 있을 수 있다.
+          waker.signal();
+        } else if (!realtimeOk && wasOk) {
+          console.log(`Live connection lost (${status}). Falling back to polling.`);
+        }
+      });
+  }
+
+  console.log("evot-agent is running. Press Ctrl+C to stop.");
+
+  // 부트스트랩: **대기 없는** 첫 호출로 wake_topic을 받아 구독부터 붙인다.
+  // 이 한 번을 건너뛰고 곧장 루프에 들어가면, 잡이 없을 때 첫 long-poll(25초)이 끝나야
+  // 구독이 시작된다 — 그 사이엔 초인종이 없는 셈이라 "1초 안에 시작"이 지켜지지 않는다.
+  try {
+    const first = await syncCall(token, {});
+    ensureSubscription(first.wake_topic);
+    // 구독이 붙을 짧은 여유. 붙으면 아래 루프가 long-poll 대신 초인종을 기다린다.
+    for (let i = 0; i < 20 && !realtimeOk && !forcePoll; i++) await sleep(100);
+  } catch (err) {
+    if (err.code === 401) {
+      console.error(`\nToken rejected: ${err.message}`);
+      console.error(`Reconnect with "evot-agent connect <code>" (get a code from evot.io).`);
+      return;
+    }
+    console.error(`Could not reach evot (will retry): ${err.message}`);
+  }
 
   let stop = false;
   process.on("SIGINT", () => {
@@ -100,14 +272,20 @@ export async function runStart(opts = {}) {
   });
 
   while (!stop) {
+    const cycleStart = Date.now();
     try {
-      // 잡이 없을 때까지 연속으로 가져와 실행(대기 없이 소진).
-      while (!stop) {
-        const jobs = await fetchJobs(token);
+      // 잡이 없을 때까지 연속으로 가져와 실행.
+      // 초인종이 붙어 있으면 즉답(빈 응답)으로 끝내고 아래에서 대기하고, 폴백이면 서버가
+      // 최대 25초 잡아 두는 long-poll로 부른다.
+      for (;;) {
+        if (stop) break;
+        const data = await syncCall(token, { wait: !realtimeOk });
+        ensureSubscription(data.wake_topic);
+        const jobs = Array.isArray(data.jobs) ? data.jobs : [];
         if (jobs.length === 0) break;
         for (const job of jobs) {
           if (stop) break;
-          await runJob(job, localBackend);
+          await runJob(job, localBackend, token);
         }
       }
     } catch (err) {
@@ -116,10 +294,25 @@ export async function runStart(opts = {}) {
         console.error(`Reconnect with "evot-agent connect <code>" (get a code from evot.io).`);
         return;
       }
-      console.error(`Poll error (will retry next tick): ${err.message}`);
+      console.error(`Sync error (will retry): ${err.message}`);
+      await sleep(ERROR_BACKOFF_MS);
     }
     if (stop) break;
-    await sleep(intervalSec * 1000);
+
+    if (realtimeOk) {
+      // 깨우거나, 하트비트 주기가 되거나.
+      await waker.wait(HEARTBEAT_MS);
+    } else {
+      // long-poll이 이미 대부분을 소비했다. 유저가 주기를 길게 잡았으면 그만큼만 더 쉰다.
+      const rest = intervalMs - (Date.now() - cycleStart);
+      if (rest > 0) await waker.wait(rest);
+    }
+  }
+
+  try {
+    await supabase?.removeAllChannels();
+  } catch {
+    // 종료 경로라 무시한다.
   }
   console.log("evot-agent stopped.");
 }