Pixel Agent 운영 매뉴얼

Pixel Agent 운영 매뉴얼

Pixel Agent 는 하나의 Studio 런에서 일하는 AgentSquad 를 실시간으로 보고 조종하는 운영자 화면입니다. 에이전트 하나하나가 색으로 표현된 픽셀(pixel) 로 나타나고, 그 옆에 런/에이전트/워크스페이스의 여러 표면과 10가지 제어 동작이 붙어 있습니다.

이 매뉴얼은 화면을 어떻게 읽고 어떻게 쓰는지만 다룹니다. 모든 필드/동작은 실제 백엔드 코드에서 그대로 가져왔습니다(추측한 필드는 없습니다).

• 읽기(데이터) 출처: GET /control-plane/studio/observability-feed?project_slug=&run_id=&limit= → TeamRunObservabilityFeed.to_payload() (backend/src/fractalops/application/access/features/studio/observability/team_run_observability_feed.py)
• 픽셀 상태 사전(vocabulary): studio_read_model_contracts.py 의 session_state_projection
• 쓰기(제어) 출처: portal_route_control_plane.py 의 POST /control-plane/studio/runs/{run_id}/control 과 POST /control-plane/studio/runs/{run_id}/sessions/{session_id}/control

가장 먼저 기억할 것

픽셀의 색은 빠르게 읽기 위한 시각 신호일 뿐이고, 권위 있는 값은 페이로드의 pixel_state 문자열입니다. 색이 헷갈리면 항상 pixel_state 와 (블록일 때) wall.recommended_action 을 보세요.

1. 이 화면이 무엇인가

Pixel Agent 는 한 프로젝트의 한 런 에 한정된 실시간 관찰·제어 표면입니다. 핵심 성질:

• 프로젝트 단위 격리. 워크스페이스 미러는 isolation: "per_project" 라는 상수 계약 표식을 달고 나옵니다. 형제 프로젝트의 샌드박스가 절대 섞여 들어오지 않습니다(피드는 레지스트리가 이미 이 프로젝트로 필터링한 리스만 투영합니다).
• 읽기는 절대 막히지 않음. 모든 표면은 best-effort + empty-typed 입니다. 라이브 프로브/세션 하나가 깨져도 그 표면만 기본값으로 떨어지고 화면 전체는 계속 뜹니다.
• 결정적(deterministic). 신선도(freshness) 같은 시간 값은 피드가 wall-clock 을 읽어 만드는 게 아니라 이미 저장된 타임스탬프의 MAX 입니다. 화면은 그 값을 브라우저 시계와 비교해 “30초 전 / 2시간 전”을 렌더링합니다.
• 라이브 채널. 피드는 live_channel_topic (portal_live_events:tenant:<tenant>:run:<run_id>)을 함께 내려, Portal 이 같은 토픽의 실시간 이벤트를 구독할 수 있게 합니다.

페이로드 최상위에는 다음이 들어 있습니다: run_id, project_slug, live_channel_topic, live_events, pixel_agents, runtime_logs, execution_workspace_mirror, delivery, source_ref, proposal, queue, lineage, delivery_feedback, evidence, progress, run_cost, latest_activity_at, 그리고 카운트들(event_count, pixel_agent_count, runtime_log_count).

2. 픽셀 상태 (pixel_state) 읽기

각 에이전트 픽셀의 상태값은 pixel_state 입니다. 사전은 session_state_projection 이 만들며, 런 단위 진행 표면(progress)이 같은 값을 버킷으로 셉니다. 아래 색은 의미 전달용 관례(권위 값은 pixel_state)입니다.

pixel_state	색(관례)	의미	운영자 행동
idle	회색	유휴. 작업 없음, 또는 완료된 세션의 기본 표시(완료는 progress.completed 로 따로 셈)	대개 무동작. 떠야 할 일이 안 떠 있으면 dispatch(retry_prompt)로 다음 행동을 밀어줌
active / in_conversation	파랑	에이전트가 다른 에이전트와 대화/협업 중(dialogue_target_agent_id 참고)	무동작. 대화가 멈춰 보이면 reply_thread/comment_agent로 메시지
waiting / awaiting_reply	노랑	무언가를 기다림. 흔히 첫 툴 사용 대기(tempo_phase: waiting_first_tool) 또는 상대 답신 대기	tempo_phase/last_update_at을 보고, 너무 오래면 wake(nudge_agent)로 깨움
moving	초록	라이브로 실제 툴 진행 중(가장 건강한 상태)	무동작. 그대로 두기
blocked	빨강	벽(wall)에 막힘. 운영자 1순위 관심 상태	wall.message로 원인 확인 → wall.recommended_action을 그대로 실행(아래 4장)
resolved	진회색/완료	세션이 종결됨. progress.completed 로 집계	무동작

blocked 가 보이면

blocked 픽셀은 항상 wall 묶음을 같이 가집니다(code, message, recommended_action). message 는 정책의 사람이 읽을 수 있는 설명이고, recommended_action 은 컨트롤 플레인이 디스패치할 정규화된 다음 행동 종류입니다. 즉 빨간 픽셀은 곧 “원클릭 처방”입니다(4장 참고).

progress 표면이 같은 사전으로 런 전체를 한눈에 버킷팅합니다: total_agents = active + waiting + blocked + moving + idle + completed. 정확히 한 버킷에만 들어가며 완료는 idle 보다 우선합니다(완료된 세션이 idle 픽셀로 그려지더라도 터미널 표식으로 completed 로 셈).

3. Live-now 스트립 + 런 표면

Live-now 스트립

상단 스트립은 라이브성을 기준으로 런을 정렬해(활성/큐 우선) 지금 손이 필요한 런을 먼저 보여줍니다. 정렬 기준은 queue.state(아래)이고, 플릿(전체 런) 비교는 GET /control-plane/studio/runs(fleet board)에서 옵니다.

런 표면(run surfaces)

한 런의 상태를 묶어 보여주는 표면들입니다. 모두 비어 있을 수 있으며(empty-typed) 기본값을 가집니다.

• delivery — PR/프리뷰/closer 결과. status(delivered/blocker/none/unknown), pr_url, pr_owner, pr_repo, pr_number, preview_url, share_token, closer_state. PR 이 있으면 delivered, 막힌 세션이 있으면 blocker.
• source_ref — 스쿼드가 그라운딩하는 GitHub 레포. repos[](각 slug/branch/default_branch), mode(oci ▸ github_array ▸ bundle ▸ none 우선순위), oci_version, hud_shared. OCI 아티팩트가 클러스터에 있으면 oci, 깃허브-배열 클론이면 github_array, 레거시 자유텍스트 번들이면 bundle. github_array/oci 는 런 생성 시 HUD 로 자동 공유됩니다(hud_shared).
• proposal — 변이 게이트 바인딩(헌법상 Proposal Plane). proposal_id, work_kind, boundary, bound. bound 는 런이 proposal 에 묶여 있는지(proposal_id 보유) 를 나타내는 헌법적 상태입니다.
• queue — 런 스케줄링. state(queued/running/idle/blocked/unknown), queued_at, heartbeat_age_seconds(없으면 -1).
• lineage — DataHub/Semantics 그래프 투영. projected, impact_node_count(없으면 -1), datahub_url. 카탈로그/리니지 enrichment 이며 증명 권위는 아닙니다.
• delivery_feedback — 배포→플래너 품질 평결. quality(good/needs_changes/unknown), accepted, notes_count. 리뷰어가 변경을 요구하면 needs_changes 가 우선(더 행동을 요하는 평결이 이김), 병합/수락이면 good.
• evidence — Chronicle evidence 등 증명 표면. proof_count(중복 제거), has_chronicle, scope. Chronicle evidence 는 장기 증명 권위입니다.
• progress — 위 2장의 버킷 집계. total_agents, active, waiting, blocked, moving, idle, completed.
• freshness — latest_activity_at. 런의 이벤트+세션 타임스탬프 중 최댓값. “N초 전 갱신” 칩의 근거.
• run_cost — 런 비용 합계. total_cost_usd(per-agent 비용의 합, 양수만), agent_count_with_cost(비용을 실제 보고한 에이전트 수).

4. 에이전트 상세 (per-agent)

픽셀 하나를 펼치면 그 에이전트(PixelAgentMirrorState)의 다음이 보입니다:

• 지금 무엇을 하나 — current_step(현재 단계), current_tool_name(현재 툴), live_status.
• 템포 — tempo_phase: 에이전트의 실행 국면. 예: waiting_first_tool, prompt_dispatching, agent_running, delivery_evidence_seen, terminal.
• 벽(wall) + 처방 — wall_code 와 wall 묶음:
  • wall.code — 원시 벽 코드
  • wall.message — 벽 정책의 사람이 읽는 설명(wall_control_message)
  • wall.recommended_action — 컨트롤러의 다음-행동 종류(컨트롤 플레인이 디스패치할 정규화된 행동). 이것이 막힌 에이전트의 원클릭 처방입니다. 비어 있으면 막히지 않은 것.
• 실행 프로세스 — agent_process_provider(예: codex), agent_process_model(예: fractalops-codex), agent_process_effort(예: medium), agent_process_speed(예: normal). repoint(아래)로 런 중에 바꿀 수 있는 바로 그 값들입니다.
• 메일박스/대화/스레드 — mailbox_count(대기 메일 수), dialogue_target_agent_id(지금 대화 상대), active_thread_id(활성 스레드). 메시지 계열 제어(comment_agent/reply_thread)의 대상.
• 무장(Armory) 로드아웃 — armory_loadout: mcp_server_ids(MCP 서버), tool_names(서버별 활성 툴 패턴, 없으면 mcp__<server>__* 와일드카드), execution_profile, bundles. 에이전트가 무엇으로 무장했는지.
• 신선도/정체 — last_update_at: 세션의 가장 최근 저장 타임스탬프(MAX). 화면이 브라우저 시계와 비교해 “active 30s” vs “blocked 2h”(정체 감지)를 렌더링합니다.
• 에이전트 비용/효율 — process_metrics: total_cost_usd(기본 0.0), duration_ms(미상 -1), num_turns(미상 -1). 런너가 결과를 보고하기 전엔 비어 있고, 절대 값을 지어내지 않습니다.

5. 제어 동작 (10가지 동사)

제어는 두 엔드포인트에 StudioControlIntentIn(필수 verb)을 POST 하는 방식입니다:

• 런 단위: POST /control-plane/studio/runs/{run_id}/control — 허용 동사: replay_blockers, cleanup_run, verify_wave, retry_prompt
• 세션 단위: POST /control-plane/studio/runs/{run_id}/sessions/{session_id}/control — 허용 동사: intervene, queue_request, retry_prompt, handoff_agent, comment_agent, reply_thread, nudge_agent, pause_session, stop_session, restart_workspace, create_task_card, create_followup_task, resolve_task_card, switch_agent_process, yolo_loop_break

접근은 principal 게이트

두 제어 라우트는 require_portal_access(can_operate_studio(...)) 로 보호됩니다. Studio 운영 권한이 없는 뷰어는 제어할 수 없고 403 studio_operator_access_denied 를 받습니다. 읽기(observability-feed)는 shell 읽기 권한이면 됩니다.

운영자가 일상적으로 쓰는 10가지 동작과, 각 동작 뒤의 실제 동사:

운영자 동작	실제 verb (엔드포인트)	하는 일	언제
pause	pause_session (세션)	세션을 일시정지	잠깐 멈추고 싶을 때
resume	queue_request (세션, wake_target)	다음 요청을 큐에 넣고 컨트롤러 상태를 active 로 되돌려 재개	일시정지/유휴 세션을 다시 굴릴 때
stop	stop_session (세션)	세션을 정지	한 에이전트만 끝낼 때
cancel	cleanup_run (런)	런을 정리/종료	런 전체를 접을 때
dispatch	retry_prompt(런/세션), intervene(세션)	다음 행동을 강제 디스패치(retry_prompt) / 컨트롤러 메시지로 조향(intervene)	떠야 할 일이 안 뜰 때, 방향을 바로잡을 때
handoff	handoff_agent (세션)	다른 에이전트로 작업을 라우팅(필요 시 대상 세션 생성)	역할 간 인수인계
message	comment_agent(메일박스), reply_thread(스레드) (세션)	에이전트에게 메일박스/스레드 메시지 전달	지시·답신·맥락 주입
repoint	switch_agent_process (세션)	런 중에 실행 프로세스를 탄력적으로 교체: agent_process_provider / agent_process_model / agent_process_effort(+agent_process_speed)를 바꾸면 다음 턴부터 그 프로세스로 실행	모델/노력/속도를 중간에 갈아끼울 때(예: 막힌 에이전트를 더 강한 모델로)
verify	verify_wave (런)	증명 게이트(verify wave) 가동	배포물의 proof 를 확인/요구할 때
wake	nudge_agent(세션), replay_blockers(런)	정체된 에이전트를 깨우기(nudge) / 런의 블로커를 재생(replay)	waiting/정체가 길거나, 막힌 에이전트를 한 번에 풀 때

추가로 같은 표면에 실재하는 동사들: create_task_card / create_followup_task / resolve_task_card (태스크 카드 수명주기), restart_workspace(워크스페이스 재시작), yolo_loop_break(YOLO 재루프 중단).

막힌 에이전트 처방 흐름

빨간 픽셀 → wall.message 로 원인 읽기 → wall.recommended_action 이 가리키는 행동을 위 표에서 찾아 해당 verb 로 디스패치. 대부분의 처방은 wake(nudge_agent)·dispatch(retry_prompt)·handoff_agent· verify_wave 중 하나로 떨어집니다.

6. 워크스페이스 미러 (execution_workspace_mirror)

이 런이 도는 실행 워크스페이스(샌드박스/DevPod)의 상태를 프로젝트 단위로 격리해 보여줍니다. 최상위에 project_slug, isolation: "per_project", workspace_count, 그리고 workspaces[].

각 워크스페이스 항목:

• 신원/위치 — workspace_name, provider(예: daytona), namespace, target_branch, workspace_scope.
• 상태 — workspace_status(영속 상태) 와 live_status. live_status 는 라이브 프로브 결과가 이기고, 프로브가 없으면 workspace_status 에서 파생합니다(피드는 프로브에 절대 막히지 않음). 사전: connected / pending / stopped / missing / unknown.
• 슬롯 — active_slot_count, max_active_slots(동시 실행 슬롯 점유/상한).
• 타이밍 — warm_until_at, suspend_after_at, last_verified_at, resume_estimate_seconds(재개 예상 초).
• 재사용/복구/인수인계 — 런의 세션들과 상관(correlate)해 채우는 enrichment: reuse(워크스페이스 재사용/캐시 히트 여부), recovery_reason(마지막 (재)구체화를 부른 복구/리프레시 사유), handoff_target(이 워크스페이스에서 스쿼드가 향하는 repo@branch). 상관되는 세션이 없으면 비어 있음.

7. 로그 독 (runtime_logs + live_events)

화면 하단의 시간순 활동 타임라인입니다. 두 줄기가 있습니다:

• runtime_logs (TeamRunRuntimeLogLine) — 세션 메타데이터에서 투영한 줄들. source(예: studio/session, studio/activity, studio/assistant-message, studio/delivery, daytona/runner, daytona/runner-stdout, daytona/tempo, daytona/wall, daytona/slot, daytona/ownership 등), level(info/warn/error), message, created_at, 그리고 신뢰도 표식: evidence_scope(current_state vs diagnostic_excerpt), current_signal, warning.
• live_events (TeamRunObservabilityEvent) — 라이브 이벤트(툴/라우트 이벤트, 인수인계 등). event_kind, event_name, route, tool_name, summary, pixel_state, target_agent_id, thread_id, task_card_id, created_at.

진단 발췌 vs 현재 상태

daytona/runner-stdout·daytona/runner-stderr 같은 줄은 evidence_scope: "diagnostic_excerpt", current_signal: false 로 표시되고 warning 이 붙습니다. 현재 상태가 아니라 런너 진단 발췌라는 뜻이니, 현재 상태는 studio/session·studio/delivery 줄로 판단하세요. JSON 런너 이벤트는 한 줄로 압축되고, 무해한 git 부트스트랩 잡음(HEAD is now at ..., Cloning into ..., hint: 등)은 걸러집니다.

빠른 사용 순서

1. Live-now 스트립에서 손이 필요한 런을 고른다(활성/큐 우선, queue.state).
2. progress 로 런 건강을 한눈에 본다(빨강=blocked 가 몇인지).
3. 빨간 픽셀을 펼쳐 wall.message 읽고 wall.recommended_action 대로 5장 표에서 verb 디스패치.
4. 노랑(waiting) 이 오래면 last_update_at/tempo_phase 확인 후 wake(nudge_agent).
5. 모델/노력이 약해 막힌 듯하면 repoint(switch_agent_process)로 중간 교체.
6. 배포가 보이면 delivery(PR/프리뷰)·evidence·verify_wave 로 증명을 닫는다.
7. 막히면 로그 독에서 studio/session·studio/delivery 줄(진단 발췌 아님)로 사실을 확인한다.