iop/HANDOFF.md

Handoff: Chronos Standalone Agent Runtime과 Node Domain-Agent Gateway

• 작성일: 2026-07-31
• 현재 타겟: 새 Chronos 프로젝트의 최종 아키텍처 확정안 검토와 이후 Milestone 설계 준비
• 다음 세션 첫 진입점: 이 문서
• 상태: 프로젝트명·저장소 경계·gateway 방향 확정, 새 저장소·구현·이전·로드맵 생성 미착수
• 기록 위치: Chronos 저장소가 아직 없으므로 이 파일만 iop 루트에 임시 handoff로 둔다. Chronos 초기화 후 canonical handoff와 Roadmap은 Chronos로 옮긴다.

사용자 확정 사항

1. 현재 /config/workspace/iop-s0의 IOP Agent CLI Runtime Milestone은 기존 범위대로 끝까지 완료한다. 지금 구조를 중간에 재편하거나 새 원격 gateway 범위를 끌어오지 않는다.
2. agentic-framework는 문서·셸 중심의 가벼운 공통 agent-ops 프레임워크로 그대로 유지한다. 어디든 설치 가능한 현재 성격을 보존하고 application runtime을 추가하지 않는다.
3. 새 독립 프로젝트의 이름은 Chronos로 확정한다. 저장소·CLI·daemon의 기본 이름은 각각 chronos, chronos, chronosd로 사용한다.
4. 아래의 단계 2 이후 작업은 새 Chronos 프로젝트를 장기 기준 저장소이자 Roadmap/Milestone source of truth로 삼는다.
5. 다음 세션은 우선 Chronos의 최종 아키텍처와 책임 경계만 확정한다. 이 handoff에서는 새 저장소, Milestone, 구현 plan, 코드 이전을 생성하지 않는다.
6. 확정안이 정리된 뒤 Chronos 저장소에 Roadmap/Milestone을 만들고, IOP·OTO 코드 변경은 해당 Milestone이 가리키는 cross-repo 구현 작업으로 관리한다.

프로젝트 이름과 상징

프로젝트명은 Chronos로 확정한다.

사용자가 기존 skill/runtime에 일을 맡겨 실제로 얻은 가장 큰 가치는 자신의 시간이 크게 늘어난 것이다. Chronos는 단순 scheduler 명칭이 아니라 다음 경험을 상징한다.

일의 시간을 Chronos에게 맡기고, 내 시간을 되찾는다.

Chronos가 작업을 Plan → Work → Review → Recovery 순서로 계속 진행하는 동안 사용자는 작업을 상시 감시하지 않는다. 이름은 체계적으로 흐르는 작업 시간과 사용자에게 반환되는 시간을 함께 뜻한다.

• 영문 문구: Chronos — Take your time back.
• 한국어 문구: 일은 맡기고, 시간은 되찾다.
• 저장소 기본명: chronos
• CLI 기본명: chronos
• daemon 기본명: chronosd
• runtime package/product family: chronos-runtime
• Node bridge kind 후보: chronos-agent

동명의 scheduler·workflow·AI 제품이 존재한다는 점은 인지하고 선택했다. 내부/초기 프로젝트명은 Chronos로 유지하고, 공개 배포 시점에만 조직 prefix, package namespace, domain·상표 충돌을 별도 검토한다. 다음 세션이 충돌만을 이유로 이름을 다시 열지 않는다.

최종 방향

현재 /config/workspace/iop-s0에서 완성할 iop-agent 구현을 선행 source로 삼아, 완료 후 standalone daemon/runtime의 제품 소유권을 새 Chronos 프로젝트로 이전한다. Chronos는 Node에 내장하지 않는다. 로컬 사용에서 Node는 필수가 아니다. IOP 관리 환경에서만 Node가 선택적 domain-agent gateway가 되어 기존 outbound Edge 연결과 로컬 Chronos 연결을 중계한다.

Local standalone

CLI / Skill / Flutter / Unity
              ↕ versioned local control
Chronos daemon (`chronosd`)
              ↕
workflow runtime과 durable state

IOP managed

Control Plane → Edge → 기존 Node outbound session
                         ↕
                 Node agent_bridge gateway
                         ↕ local typed connection
                  동일한 Chronos daemon

책임은 다음과 같이 고정한다.

소유자	책임
agentic-framework	어디든 설치 가능한 agent-ops 공통 규칙·skill·sync framework. Chronos runtime을 포함하지 않음
Chronos	standalone runtime core, CLI/daemon, local control, workflow adapter, durable state/replay, scoped execution, Roadmap lifecycle 조합
IOP Node	로컬 agent discovery/registration, capability·health, admission, request correlation, bounded relay, timeout/backpressure, Edge 연결 중계
IOP Edge/Control Plane	원격 principal authorization, Node/agent routing, command/event summary, audit와 운영 표면
OTO	pipeline/job/artifact/log 의미와 실행 상태의 원본
Flutter/Unity	runtime client. CLI를 감싸지 않고 versioned local proto-socket 계열 계약을 직접 사용

Node는 workflow artifact, Plan/Review 해석, project state, OTO job state의 원본을 소유하지 않는다. Node 또는 Edge 연결이 끊겨도 이미 수락된 standalone 작업은 계속되어야 한다.

Provider 경계

외부에서는 하나의 provider/resource 계열로 발견할 수 있지만, 기존 model/CLI provider와 같은 실행 의미로 합치지 않는다.

agent_bridge provider framework
  ├─ kind: chronos-agent
  └─ kind: oto-runner

공유 가능한 것은 다음 lifecycle뿐이다.

• versioned registration과 stable instance identity
• capability catalog와 availability/health
• command correlation과 idempotency
• ordered event, result, cancel/stop
• disconnect/reconnect와 snapshot/replay
• capacity, timeout, bounded queue와 audit metadata

Chronos의 Plan/Review/Milestone 상태와 OTO의 pipeline/job/artifact payload는 kind별 typed driver가 소유한다. 자유형 terminal output, model prompt/delta, HTTP ProviderTunnel body로 변환하지 않는다.

Node의 기존 terminal/CLI 기능은 설치·bootstrap·업데이트·비상 진단 후보일 뿐 정상 제어면이 아니다. chronosd를 terminal에서 실행하고 stdout을 파싱하는 구조는 singleton ownership, command correlation, cancel/resume, event ordering과 crash recovery를 중복 구현하게 하므로 폐기한다.

제품 사용 표면

같은 runtime을 다음 범위로 독립 사용 가능해야 한다.

• Plan/Review cycle만 실행
• 하나의 Milestone 범위만 실행
• 여러 Milestone을 포함한 전체 Roadmap lifecycle 실행
• 로컬 CLI에서 수동 시작·상태·중단·재개
• agent용 Skill이 CLI 또는 안정된 client interface를 통해 같은 기능 사용
• Flutter/Unity가 local control 계약으로 상태·event·control 사용
• IOP 관리 환경에서 Node gateway를 통한 선택적 원격 상태·제어

Plan/Review cycle의 상태 의미와 artifact 규칙은 공통 core가 소유한다. 실행 위치에 따라 adapter를 분리한다.

• 로컬 workflow: plan, work, review를 동일 사용자 장비의 standalone runtime이 수행한다.
• remote user-agent workflow: plan, work, review 요청과 결과가 모두 원격 사용자 agent를 통과한다. 공통 cycle을 사용하지만 transport, executor, retry, attention/승인 경로는 별도 adapter다.

따라서 실행 지점이 같다는 이유로 두 workflow를 하나의 pipeline 구현으로 강제하지 않는다. 공통 core는 cycle state와 transition을 제공하고, local/remote adapter가 각 수행 방식을 제공한다.

OTO에서 흡수할 것과 버릴 것

OTO에서 제품화할 핵심은 agent가 outbound 장기 session으로 등록 → capability 보고 → server push 수신 → heartbeat/report하는 연결 패턴이다.

흡수한다.

• session abstraction
• protocol/capability version registration
• heartbeat와 disconnect 처리
• duplicate connection 교체
• server-push command와 typed report
• execution ownership 검사

그대로 가져오지 않는다.

• legacy OTO→IOP Edge direct registration code
• OTO domain proto를 Chronos에도 공통 적용
• 빈 값 여부만 확인하는 enrollment token
• TLS, reconnect/backoff, 실제 cancel 집행이 빠진 현재 한계
• Node가 OTO scheduler나 artifact/log store가 되는 구조

OTO와 Chronos는 같은 agent_bridge framework 아래 서로 다른 driver/instance로 둔다.

로컬 연결과 보안 경계

현재 iop-agent local control에서 검증 중인 Unix socket 0600, owner-only state root 0700, 동일 effective UID peer 경계를 Chronos 이전 후에도 보존한다. 이 경계를 원격 통합을 위해 느슨하게 만들지 않는다.

초기 후보는 두 단계다.

1. 같은 사용자 MVP: Node companion/connector가 Chronos의 owner-only local socket을 사용한다.
2. system Node 또는 다중 사용자 제품형: 사용자 agent가 Node가 소유한 local gateway로 outbound 등록하고 session을 유지한다. Unix domain socket/Windows named pipe가 목표이며, 공통 transport가 준비되지 않은 초기 구현은 127.0.0.1 only + ephemeral port + short-lived credential을 사용할 수 있다.

어느 경우든 사용자 장비에 외부 inbound port를 추가하지 않는다. 원격 traffic은 기존 Node→Edge outbound session 하나로 multiplex한다.

production remote mutation 전 필수 gate:

• Edge–Node transport authentication/confidentiality
• remote principal → local owner/project/workspace scope authorization
• operation allowlist와 audit
• stable command_id를 이용한 duplicate convergence
• ordered event relay와 cursor replay
• replay 범위를 벗어나면 fresh snapshot으로 복구
• node online, bridge connected, agent available, project running 상태 구분
• 원격 UI start/focus와 임의 shell/path/protobuf forwarding 기본 금지

현재 Edge–Node transport에는 mTLS helper가 실제 transport에 연결되지 않았으므로, 이 gate 전에는 production project.start/stop/resume을 열지 않는다.

보류·분리 항목

• local LLM 감시/advisor는 현시점 over-spec으로 보류한다. 결정적 runtime monitoring에는 LLM을 넣지 않는다.
• remote terminal은 별도 기능이다. Node agent gateway와 합치지 않는다.
• Flutter/Unity는 CLI 제어가 아니라 proto-socket 계열 계약을 사용한다.
• remote coding 유지보수는 별도 Desktop Agent를 만들지 않고 향후 Chronos의 remote user-agent workflow adapter로 흡수한다.
• Node가 Chronos process, workflow, durable state를 기본 소유하거나 Edge reconnect 시 종료시키지 않는다.
• direct specialized agent→Edge protocol은 현재 기본 경로로 부활시키지 않는다.
• Node와 Chronos의 겹쳐 보이는 코드를 성급히 공통 package로 추출하지 않는다. shared contract/SDK만 먼저 고정하고 실제로 host-neutral한 구현 경계가 증명된 뒤 추출한다.

단계 기준

이전 대화에서 사용한 번호는 다음을 뜻한다.

1. /config/workspace/iop-s0의 현재 IOP Agent CLI Runtime 완료
2. Agent Runtime Ownership Extraction
   • 완료된 standalone runtime 소유권을 새 Chronos 프로젝트로 이전
   • 제품·CLI·daemon 명칭을 chronos, chronos, chronosd로 정리
   • local CLI/socket/offline 사용성 보존
   • versioned control contract/SDK 경계 고정
3. Scoped Agent Task Execution Surface
   • Plan/Review, Milestone, Roadmap 범위별 독립 실행과 종료 경계
4. Node External Agent Provider Foundation
   • agent_bridge registration, discovery, health, typed command/event/replay
5. Edge Managed Agent Routing & Security
   • Edge–Node remote control wire, authorization, audit, reconnect
6. Roadmap Lifecycle Orchestration
   • 3번 scope를 조합하되 작은 범위 사용성을 보존
7. OTO Provider Adapter
8. Remote User-Agent Workflow Bridge

2번 이후 Roadmap/Milestone은 새 Chronos 저장소에서 관리한다. 4, 5, 7번은 구현 파일이 IOP/OTO에 있더라도 Chronos Milestone에서 cross-repo 대상과 검증을 명시한다.

3번과 6번의 local lifecycle 설계는 Node gateway와 독립적으로 진행할 수 있다. 원격 mutation만 5번 보안 gate를 선행한다.

다음 세션 실행 순서

1. 이 문서와 아래 필수 탐색 경로만 먼저 읽는다.
2. agentic-framework는 변경하지 않고 경량 공통 프레임워크로 유지한다. Chronos runtime, Roadmap, project rule을 이 저장소에 추가하지 않는다.
3. 새 Chronos 저장소의 위치·module namespace·초기 scaffold는 최종 아키텍처 확정 뒤 결정한다. 아직 /config/workspace/chronos가 존재한다고 가정하지 않는다.
4. 최종 아키텍처 문서에서 다음을 결정 가능한 형태로 고정한다.
   • component/process topology
   • repository와 package ownership
   • versioned contract source와 generated SDK 배포
   • local/managed deployment mode
   • identity/authorization
   • command/event/replay/cancel failure semantics
   • Node/Edge/agent disconnect 시 lifecycle
5. 사용자에게 최종안을 확인받은 뒤 Chronos 저장소를 초기화하고 create-roadmap을 사용해 2번 이후 Milestone을 생성한다.
6. Chronos 저장소가 생기면 이 문서의 확정 사항을 그 저장소의 canonical handoff/architecture 입력으로 이전한다. agentic-framework에는 Chronos runtime·Roadmap을 남기지 않는다.
7. 현재 /config/workspace/iop-s0 checkout은 Milestone 완료 정합화 전까지 수정, 이동, 정리하지 않는다. 1번 완료 evidence가 생긴 뒤 extraction 범위를 산정한다.

필수 탐색 경로

유지할 agentic-framework 경계

• README.md: 현재 저장소가 app runtime이 아닌 agent-ops 공통 원본이라고 명시한다. 저장소 역할 확장은 의식적인 결정이어야 한다.
• agent-ops/rules/common/philosophy.md: runtime과 LLM 책임, Roadmap과 실행 상태 경계.
• agent-ops/bin/sync.sh: push 대상은 agent-ops 공통 영역으로 제한된다. Chronos는 이 sync payload가 아니라 별도 소비 프로젝트다.

현재 iop-agent 구현과 계약

• ../iop-s0/agent-roadmap/phase/automation-runtime-bridge/milestones/iop-agent-cli-runtime.md: 현재 Milestone 범위, 제외 항목, 완료 전 남은 작업.
• ../iop-s0/agent-contract/inner/iop-agent-cli-runtime.md: standalone/local control 계약.
• ../iop-s0/proto/iop/agent.proto: typed envelope, command_id, snapshot, event sequence와 replay.
• ../iop-s0/apps/agent/internal/localcontrol/server.go: Unix socket, permission, same-UID peer credential 경계.
• ../iop-s0/apps/agent/internal/localcontrol/service.go: status와 project start/stop/resume port.
• ../iop-s0/apps/agent/internal/taskloop/workflow.go: agent-ops Plan/Review/Milestone artifact 의존성이 집중된 workflow adapter.
• ../iop-s0/packages/go/agentruntime/types.go: 기존 유한 실행 Provider와 agent durable control의 의미 차이.

IOP Node/Edge gateway 후보

• ../iop-s0/apps/node/README.md: 기존 Edge–Node transport, logical session, mTLS 미연결 상태.
• ../iop-s0/proto/iop/runtime.proto: RunRequest, RunEvent, NodeCommand, ProviderTunnel; 새 durable agent control을 억지로 넣지 않아야 하는 기존 wire.
• ../iop-s0/apps/node/internal/transport/session.go: 기존 단일 Edge–Node session의 message family multiplex.
• ../iop-s0/proto/iop/control.proto: EdgeDomainAgentSummary, EdgeCommandRequest/Response/Event scaffold.
• ../iop-s0/apps/edge/internal/service/status_provider.go: GetDomainAgents()가 현재 비어 있는 integration point.
• ../iop-s0/apps/edge/internal/service/control_command.go: 현재 agent.command가 제한적 scaffold인 상태.
• ../iop-s0/agent-roadmap/phase/control-plane-portal-ops/milestones/multi-edge-operations.md: OTO/build-deploy를 Edge-owned domain-agent summary로 노출한다는 기존 결정.
• ../iop-s0/agent-roadmap/phase/automation-runtime-bridge/milestones/remote-terminal-bridge-poc.md: remote terminal을 별도 기능으로 유지하는 경계.

OTO 연결 패턴

• ../oto/proto/oto/runner.proto: registration, capability, heartbeat, push run/cancel, report 계약.
• ../oto/apps/runner/lib/oto/agent/registration_client.dart: 현재 outbound session abstraction.
• ../oto/apps/runner/lib/oto/agent/agent_runner.dart: push job loop와 현재 cancel 한계.
• ../oto/apps/runner/lib/oto/agent/edge_registration_client.dart: legacy direct IOP Edge client임을 파일 자체가 명시한다.
• ../oto/services/core/internal/runnersocket/server.go: runner registry, push, duplicate connection과 report ownership 패턴.
• ../oto/services/core/internal/runnerregistry/registry.go: capability/version 검사와 현재 enrollment 검증 한계.

보조 컨텍스트

• 이전 Codex context ID: 019fb30f-08e6-7643-bc73-ef72a3199dcb
• 위 context를 조회할 수 있으면 보조 근거로만 사용한다. 이 handoff의 사용자 확정 사항과 책임 경계를 우선한다.

작업 상태와 검증

• 이번 세션에서 구현, migration, Milestone/SDD/contract 생성은 하지 않았다.
• /config/workspace/agentic-framework는 main, 기준 commit afd34c3이며 handoff 이동 후 clean 상태다.
• /config/workspace/iop는 feature/provider-usage-attribution-hot-path이며 이동 전 clean 상태였다. 현재 변경은 untracked HANDOFF.md 한 건뿐이다.
• 새 Chronos 저장소는 아직 생성하지 않았다.
• /config/workspace/iop-s0는 feature/iop-agent-cli-runtime, HEAD 4e420910이며 원격 브랜치와 동일한 clean 상태다. Milestone 완료 정합화 전에는 해당 checkout을 임의로 수정하거나 이동하지 않는다.
• /config/workspace/oto는 master, 기준 commit ae2b14f였고 확인 당시 clean 상태였다.
• 문서 작업이므로 코드 테스트는 실행하지 않는다. git diff --check만 검증한다.