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 연결을 중계한다.

```text
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와 같은 실행 의미로 합치지 않는다.

```text
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`](README.md): 현재 저장소가 app runtime이 아닌 agent-ops 공통 원본이라고 명시한다. 저장소 역할 확장은 의식적인 결정이어야 한다.
- [`agent-ops/rules/common/philosophy.md`](agent-ops/rules/common/philosophy.md): runtime과 LLM 책임, Roadmap과 실행 상태 경계.
- [`agent-ops/bin/sync.sh`](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`](../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`](../iop-s0/agent-contract/inner/iop-agent-cli-runtime.md): standalone/local control 계약.
- [`../iop-s0/proto/iop/agent.proto`](../iop-s0/proto/iop/agent.proto): typed envelope, `command_id`, snapshot, event sequence와 replay.
- [`../iop-s0/apps/agent/internal/localcontrol/server.go`](../iop-s0/apps/agent/internal/localcontrol/server.go): Unix socket, permission, same-UID peer credential 경계.
- [`../iop-s0/apps/agent/internal/localcontrol/service.go`](../iop-s0/apps/agent/internal/localcontrol/service.go): status와 project start/stop/resume port.
- [`../iop-s0/apps/agent/internal/taskloop/workflow.go`](../iop-s0/apps/agent/internal/taskloop/workflow.go): agent-ops Plan/Review/Milestone artifact 의존성이 집중된 workflow adapter.
- [`../iop-s0/packages/go/agentruntime/types.go`](../iop-s0/packages/go/agentruntime/types.go): 기존 유한 실행 Provider와 agent durable control의 의미 차이.

### IOP Node/Edge gateway 후보

- [`../iop-s0/apps/node/README.md`](../iop-s0/apps/node/README.md): 기존 Edge–Node transport, logical session, mTLS 미연결 상태.
- [`../iop-s0/proto/iop/runtime.proto`](../iop-s0/proto/iop/runtime.proto): `RunRequest`, `RunEvent`, `NodeCommand`, `ProviderTunnel`; 새 durable agent control을 억지로 넣지 않아야 하는 기존 wire.
- [`../iop-s0/apps/node/internal/transport/session.go`](../iop-s0/apps/node/internal/transport/session.go): 기존 단일 Edge–Node session의 message family multiplex.
- [`../iop-s0/proto/iop/control.proto`](../iop-s0/proto/iop/control.proto): `EdgeDomainAgentSummary`, `EdgeCommandRequest/Response/Event` scaffold.
- [`../iop-s0/apps/edge/internal/service/status_provider.go`](../iop-s0/apps/edge/internal/service/status_provider.go): `GetDomainAgents()`가 현재 비어 있는 integration point.
- [`../iop-s0/apps/edge/internal/service/control_command.go`](../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`](../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`](../iop-s0/agent-roadmap/phase/automation-runtime-bridge/milestones/remote-terminal-bridge-poc.md): remote terminal을 별도 기능으로 유지하는 경계.

### OTO 연결 패턴

- [`../oto/proto/oto/runner.proto`](../oto/proto/oto/runner.proto): registration, capability, heartbeat, push run/cancel, report 계약.
- [`../oto/apps/runner/lib/oto/agent/registration_client.dart`](../oto/apps/runner/lib/oto/agent/registration_client.dart): 현재 outbound session abstraction.
- [`../oto/apps/runner/lib/oto/agent/agent_runner.dart`](../oto/apps/runner/lib/oto/agent/agent_runner.dart): push job loop와 현재 cancel 한계.
- [`../oto/apps/runner/lib/oto/agent/edge_registration_client.dart`](../oto/apps/runner/lib/oto/agent/edge_registration_client.dart): legacy direct IOP Edge client임을 파일 자체가 명시한다.
- [`../oto/services/core/internal/runnersocket/server.go`](../oto/services/core/internal/runnersocket/server.go): runner registry, push, duplicate connection과 report ownership 패턴.
- [`../oto/services/core/internal/runnerregistry/registry.go`](../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`만 검증한다.