api-contract.md

domain	technical
audience	chief lead member
keywords	api contract
last-updated	2026-03-01

API Contract

기본 규약

• API는 JSON(application/json)을 사용하고 필드 네이밍은 camelCase를 기본으로 한다.
• 신규 일반 API는 /api/v1/...를 기본 경로로 사용한다.
• 런타임 제어 API는 호환성 이유로 /api/runtime/*를 예외 경로로 유지한다.

HTTP 오류 응답 규약

• 현재 Runtime HTTP 오류 응답 포맷은 아래 2개 필드를 사용한다.
• requestId는 WebSocket 오류(runtime:error)에서 제공한다.

{
  "errorCode": "VALIDATION_ERROR",
  "message": "workdir를 지정해 주세요."
}

오류 코드:

• VALIDATION_ERROR (400)
• FORBIDDEN (403)
• NOT_FOUND (404)
• INTERNAL_ERROR (500)

Runtime API (Web <-> MCP)

HTTP

GET /api/runtime/health

{
  "ok": true,
  "now": "2026-02-20T07:00:00.000Z"
}

GET /api/runtime/status?workdir=<absolute-path>

• workdir는 선택값이다.
• workdir가 없으면 서버는 현재 실행 중 런타임의 workdir을 사용한다.
• 현재 실행 중 런타임이 없고 workdir도 없으면 VALIDATION_ERROR를 반환한다.

POST /api/runtime/init

요청:

{
  "workdir": "/path/to/workdir",
  "reset": false
}

• reset=true이면 기존 /path/to/workdir/.agentCompany를 삭제 후 재초기화한다.
• 초기화 시 tasks/queue.json은 샘플 데이터 없이 빈 배열([])로 생성한다.
• 초기화 시 원본 knowledge-base/ 트리를 /path/to/workdir/.agentCompany/docs로 미러 복사한다(AGENTS.md 제외).

POST /api/runtime/start

요청:

{
  "workdir": "/path/to/workdir"
}

• start는 기존 워크스페이스를 재사용하며, docs 미러 재복사를 수행하지 않는다.
• 워크스페이스가 초기화되지 않았으면 VALIDATION_ERROR를 반환한다.

POST /api/runtime/stop

요청:

{
  "workdir": "/path/to/workdir"
}

• workdir는 선택값이다.
• 실행 중 런타임이 없는 상태에서 workdir 없이 호출하면 빈 스냅샷을 반환한다.

GET /api/runtime/providers

응답:

{
  "providers": [
    {
      "provider": "codex",
      "binary": "codex",
      "installed": true,
      "creatable": true
    }
  ]
}

GET /api/runtime/agent-guidelines?workdir=<absolute-path>

응답:

{
  "workdir": "/path/to/workdir",
  "docsRoot": "/path/to/workdir/.agentCompany/docs",
  "orgLevels": ["chief", "lead", "member"],
  "roles": [
    {
      "roleName": "strategy-chief",
      "orgLevel": "chief",
      "sourcePath": "/path/to/workdir/.agentCompany/docs/agents/roles/strategy-chief.md"
    }
  ]
}

GET /api/runtime/mode?workdir=<absolute-path>

응답:

{
  "workdir": "/path/to/workdir",
  "operatingMode": "governed",
  "availableModes": ["governed", "silicon-valley"],
  "initialized": true,
  "configPath": "/path/to/workdir/.agentCompany/config.json"
}

POST /api/runtime/mode

요청:

{
  "workdir": "/path/to/workdir",
  "operatingMode": "silicon-valley"
}

규칙:

• operatingMode는 governed|silicon-valley 중 하나여야 한다.
• 워크스페이스가 초기화되지 않은 경우(설정 파일 부재) VALIDATION_ERROR를 반환한다.
• 모드 변경은 새 사이클 시작 시점(모든 task status=pending)에서만 허용한다.

GET /api/runtime/metrics?workdir=<absolute-path>&limit=<number>

응답:

{
  "workdir": "/path/to/workdir",
  "count": 2,
  "sourcePath": "/path/to/workdir/.agentCompany/logs/metrics.ndjson",
  "events": [
    {
      "eventType": "mode.changed",
      "timestamp": "2026-02-21T03:20:00.000Z",
      "workdir": "/path/to/workdir",
      "operatingMode": "silicon-valley"
    }
  ]
}

규칙:

• limit 기본값은 200이며 최대 2000까지 허용한다.
• 파일이 없으면 빈 배열(events: [])을 반환한다.

POST /api/runtime/agents

요청:

{
  "workdir": "/path/to/workdir",
  "type": "codex",
  "displayName": "Codex Builder",
  "personaSummary": "구현 중심",
  "orgLevel": "member",
  "roleName": "implementation-engineer",
  "primaryGoal": "기능 구현",
  "reportsTo": "lead-agent-uuid"
}

규칙:

• orgLevel은 chief|lead|member 중 하나여야 한다.
• roleName은 빈 문자열일 수 없다.
• reportsTo는 선택값이다.
• lead는 chief 아래에만 배치 가능하다.
• member는 lead 아래에만 배치 가능하다.

PATCH /api/runtime/agents/{agentId}

요청 필드는 부분 업데이트를 허용한다.

• orgLevel, roleName은 독립 필드로 업데이트한다.
• reportsTo는 선택값이며 null로 전달하면 그룹 배치를 해제한다.

GET /api/runtime/org-chart?workdir=<absolute-path>

응답:

{
  "workdir": "/path/to/workdir",
  "generatedAt": "2026-02-21T01:20:00.000Z",
  "operatingMode": "governed",
  "orgLevels": ["chief", "lead", "member"],
  "nodes": [
    {
      "agentId": "agent-uuid",
      "displayName": "Strategy Chief",
      "agentType": "claude",
      "orgLevel": "chief",
      "roleName": "strategy-chief",
      "primaryGoal": "범위/DoD 확정",
      "groupId": "chief-agent-uuid",
      "teamId": null,
      "reportsTo": null,
      "approvableTransitions": ["PLAN->WORK", "REVIEW->COMPOUND"]
    }
  ],
  "groups": [
    {
      "groupId": "chief-agent-uuid",
      "groupName": "Strategy Chief Group",
      "rootAgentId": "chief-agent-uuid",
      "chiefAgentId": "chief-agent-uuid",
      "leadAgentIds": ["lead-agent-uuid"],
      "memberAgentIds": ["member-agent-uuid"],
      "agentIds": ["chief-agent-uuid", "lead-agent-uuid", "member-agent-uuid"]
    }
  ],
  "approvalRules": [
    {
      "fromStage": "PLAN",
      "toStage": "WORK",
      "transitionKey": "PLAN->WORK",
      "requiredOrgLevels": ["chief"],
      "requiresUserApproval": false
    }
  ]
}

POST /api/runtime/directives

요청:

{
  "workdir": "/path/to/workdir",
  "instruction": "이번 주 결제 이탈률을 20% 줄이는 실행안을 수립하고 진행해줘",
  "priority": "high",
  "operatingMode": "governed",
  "riskLevel": "low",
  "targetChiefs": ["chief-product", "chief-tech"],
  "dueBy": "2026-02-22T12:00:00Z"
}

규칙:

• CEO Dashboard 공개 진입점이다.
• 헤더 x-agent-company-user-role=ceo가 필요하다.
• targetChiefs는 orgLevel=chief 에이전트로 해석 가능해야 한다.
• lead/member를 직접 수신자로 지정하면 FORBIDDEN을 반환한다.
• 생성 성공 시 지시 상태는 submitted로 기록한다.

응답:

{
  "ok": true,
  "directiveId": "directive-uuid",
  "status": "submitted",
  "requestId": "req-1234",
  "message": "CEO 지시를 등록하고 chief 라우팅을 시작했습니다."
}

GET /api/runtime/directives?workdir=<absolute-path>&status=<submitted|routed|briefing|delegated|in-progress|reviewing|completed|blocked|canceled>&limit=<number>

응답:

{
  "workdir": "/path/to/workdir",
  "count": 1,
  "directives": [
    {
      "directiveId": "directive-uuid",
      "instruction": "이번 주 결제 이탈률을 20% 줄이는 실행안",
      "priority": "high",
      "status": "routed",
      "targetChiefs": ["chief-product", "chief-tech"],
      "createdAt": "2026-02-22T01:00:00Z",
      "updatedAt": "2026-02-22T01:10:00Z"
    }
  ]
}

규칙:

• workdir는 필수값이다.
• limit 기본값은 50이며 최대 500까지 허용한다.
• status는 선택값이며 지정 시 해당 상태만 필터링한다.

POST /api/runtime/directives/{directiveId}/chief-briefs

요청:

{
  "workdir": "/path/to/workdir",
  "chiefAgentId": "agent-uuid",
  "scope": "결제 실패 상위 원인 3개 개선",
  "nonScope": "결제 수단 신규 도입은 제외",
  "dod": "이탈률 20% 개선 검증 로그 제출",
  "riskLevel": "low"
}

규칙:

• chiefAgentId는 orgLevel=chief여야 한다.
• directiveId 상태가 routed 또는 briefing일 때만 생성 가능하다.
• scope, nonScope, dod는 빈 문자열일 수 없다.

응답:

{
  "ok": true,
  "briefId": "chief-brief-uuid",
  "status": "draft",
  "requestId": "req-1234"
}

POST /api/runtime/chief-briefs/{briefId}/work-orders

요청:

{
  "workdir": "/path/to/workdir",
  "directiveId": "directive-uuid",
  "ownerAgentId": "agent-uuid",
  "workId": "checkout-drop-r1",
  "summary": "결제 실패율 개선 구현",
  "dueBy": "2026-02-24T12:00:00Z"
}

규칙:

• ownerAgentId는 orgLevel=lead|chief여야 한다.
• orgLevel=chief는 lead 비활성 + 저위험일 때만 허용한다.
• 상위 briefId가 승인 상태가 아니면 work-order를 만들 수 없다.
• 생성된 work-order는 directiveId와 반드시 연결되어야 한다.

응답:

{
  "ok": true,
  "workOrderId": "work-order-uuid",
  "status": "queued",
  "requestId": "req-1234"
}

GET /api/runtime/scaling/policy?workdir=<absolute-path>

응답:

{
  "workdir": "/path/to/workdir",
  "policy": {
    "minMembers": 1,
    "maxMembers": 6,
    "targetThroughputPerMember": 2,
    "evaluationIntervalSec": 60,
    "cooldownSec": 600
  }
}

POST /api/runtime/scaling/policy

요청:

{
  "workdir": "/path/to/workdir",
  "minMembers": 1,
  "maxMembers": 8,
  "targetThroughputPerMember": 2,
  "evaluationIntervalSec": 60,
  "cooldownSec": 600
}

규칙:

• minMembers는 1 이상이어야 한다.
• maxMembers는 minMembers 이상이어야 한다.
• evaluationIntervalSec는 최소 10 이상이어야 한다.
• cooldownSec는 최소 60 이상이어야 한다.
• chief는 자동 스케일 대상에서 제외한다.

응답:

{
  "ok": true,
  "requestId": "req-1234",
  "message": "역할 탄력 정책을 저장했습니다."
}

GET /api/runtime/scaling/status?workdir=<absolute-path>&chiefGroupId=<id>

응답:

{
  "workdir": "/path/to/workdir",
  "chiefGroupId": "chief-agent-uuid",
  "queueDepth": 4,
  "inProgressWorkOrders": 3,
  "riskHighCount": 1,
  "lead": {
    "required": true,
    "active": true
  },
  "members": {
    "desired": 3,
    "active": 2,
    "draining": 0
  },
  "lastEvaluatedAt": "2026-02-22T01:00:00Z"
}

POST /api/runtime/scaling/reconcile

요청:

{
  "workdir": "/path/to/workdir",
  "chiefGroupId": "chief-agent-uuid",
  "reason": "queue-depth-threshold"
}

규칙:

• 서버는 현재 backlog/SLA/risk를 평가해 lead/member만 증감해야 한다.
• chief 비활성/축소는 허용하지 않는다.
• 스케일다운은 drain 완료 전에는 적용 완료로 간주하지 않는다.

응답:

{
  "ok": true,
  "requestId": "req-1234",
  "appliedDecisions": [
    {
      "roleType": "member",
      "action": "up",
      "delta": 1
    }
  ]
}

POST /api/runtime/approval/validate

요청:

{
  "workdir": "/path/to/workdir",
  "directiveId": "directive-uuid",
  "workId": "landing-auth-r3",
  "fromStage": "WORK",
  "toStage": "REVIEW",
  "approverAgentId": "agent-uuid",
  "riskLevel": "low"
}

규칙:

• riskLevel은 선택값이며 low|high|unknown을 허용한다.
• directiveId는 필수값이다.
• workId는 필수값이다.
• lead 비활성 + 저위험 작업이면 chief를 승인권자로 허용할 수 있다.

응답:

{
  "ok": true,
  "allowed": true,
  "transitionKey": "WORK->REVIEW",
  "operatingMode": "governed",
  "requiredOrgLevels": ["lead", "chief"],
  "requiresUserApproval": false,
  "approver": {
    "agentId": "agent-uuid",
    "displayName": "Delivery Lead",
    "orgLevel": "lead",
    "roleName": "delivery-lead"
  },
  "reason": "전결 통과"
}

POST /api/runtime/approval/user

요청:

{
  "workdir": "/path/to/workdir",
  "directiveId": "directive-uuid",
  "workId": "landing-auth-r3",
  "transitionKey": "COMPOUND->CYCLE_END",
  "approved": true,
  "note": "릴리즈 종료 승인"
}

규칙:

• transitionKey는 현재 COMPOUND->CYCLE_END만 허용한다.
• directiveId와 workId는 동일 사이클로 매핑 가능해야 한다.
• approved=true가 기록되어야 COMPOUND->CYCLE_END 진행이 가능하다.
• 이벤트에는 operatingMode, policyHash를 함께 기록한다.
• 헤더 x-agent-company-user-id가 필요하다.
• 헤더 x-agent-company-user-role=ceo가 필요하다.
• 서버 환경변수 AGENT_COMPANY_USER_APPROVAL_TOKEN이 설정된 경우:
  • 헤더 x-agent-company-user-token이 필요하며 해당 값과 일치해야 한다.
• 서버 환경변수가 미설정/빈 값인 경우:
  • x-agent-company-user-token 없이도 x-agent-company-user-id로 승인 이벤트를 기록할 수 있다(로컬 개발 기본 경로).

응답:

{
  "ok": true,
  "requestId": "req-1234",
  "transitionKey": "COMPOUND->CYCLE_END",
  "message": "CEO(사용자) 최종 승인을 기록했습니다."
}

POST /api/runtime/messages

요청:

{
  "workdir": "/path/to/workdir",
  "directiveId": "directive-uuid",
  "workId": "landing-auth-r3",
  "fromPrincipalType": "agent",
  "fromAgent": "lead-qa",
  "toAgent": "chief-tech",
  "channel": "review",
  "operatingMode": "governed",
  "riskLevel": "low",
  "summary": "회귀 테스트 완료, 릴리즈 승인 필요",
  "requiredAction": "PLAN->WORK 승인",
  "requiredApprover": "chief-tech",
  "dueBy": "2026-02-20T12:00:00Z"
}

규칙:

• fromAgent를 제외한 모든 필드는 필수값이다.
• channel은 directive|plan|work|review|risk만 허용한다.
• operatingMode는 런타임 현재 모드와 일치해야 한다.
• riskLevel은 low|high|unknown만 허용한다.
• riskLevel=high이면 requiredApprover는 chief 계층을 포함해야 한다.
• dueBy는 RFC3339 UTC 타임스탬프여야 한다.
• fromAgent, toAgent는 현재 workdir에 등록된 에이전트(id/roleName/displayName)로 해석 가능해야 한다.
• fromAgent와 toAgent는 서로 달라야 한다.
• fromPrincipalType=agent일 때만 fromAgent를 필수로 강제한다.
• fromPrincipalType=ceo-user이면 toAgent는 chief 계층만 허용한다.

응답:

{
  "ok": true,
  "requestId": "req-1234",
  "message": "에이전트 메시지를 수신하고 스키마 검증/기록했습니다."
}

교차 Workdir 협업 API (Draft)

아래 API는 knowledge-base/technical/cross-workdir-collaboration.md 기준의 설계 초안이다. 현재 문서는 계약 초안을 정의하며, 서버 구현 시 세부 필드는 하위 호환 원칙으로 확정한다.

POST /api/runtime/handoffs

요청:

{
  "sourceWorkdir": "/path/to/workdir-a",
  "targetWorkdir": "/path/to/workdir-b",
  "handoffWorkId": "auth-platform-r1",
  "fromAgent": "chief-tech",
  "toAgent": "lead-platform",
  "operatingMode": "governed",
  "riskLevel": "high",
  "summary": "A 프로젝트 인증 모듈을 B 프로젝트 플랫폼 규격에 맞춰 검증 요청",
  "requiredAction": "WORK->REVIEW 전환 검증",
  "requiredApprover": "chief-platform",
  "dueBy": "2026-02-24T12:00:00Z",
  "evidenceLogPath": "knowledge-base/history/reviews/auth-platform-r1-review.md",
  "idempotencyKey": "handoff-auth-platform-r1-001"
}

규칙:

• 모든 필드는 필수값이다.
• sourceWorkdir와 targetWorkdir는 서로 달라야 한다.
• operatingMode는 governed|silicon-valley만 허용한다.
• riskLevel은 low|high|unknown만 허용한다.
• fromAgent는 sourceWorkdir의 에이전트로, toAgent는 targetWorkdir의 에이전트로 해석 가능해야 한다.
• riskLevel=high이면 requiredApprover는 chief 계층을 포함해야 한다.
• dueBy는 RFC3339 UTC 타임스탬프여야 한다.
• idempotencyKey는 동일 요청 재전송 시 중복 생성을 막기 위해 사용한다.

응답:

{
  "ok": true,
  "handoffId": "handoff-uuid",
  "status": "requested",
  "requestId": "req-1234",
  "message": "교차 workdir 협업 요청을 기록했습니다."
}

GET /api/runtime/handoffs?workdir=<absolute-path>&status=<requested|accepted|in-progress|completed|rejected|blocked>&limit=<number>

응답:

{
  "workdir": "/path/to/workdir-a",
  "count": 1,
  "handoffs": [
    {
      "handoffId": "handoff-uuid",
      "sourceWorkdir": "/path/to/workdir-a",
      "targetWorkdir": "/path/to/workdir-b",
      "handoffWorkId": "auth-platform-r1",
      "status": "requested",
      "operatingMode": "governed",
      "riskLevel": "high",
      "requiredApprover": "chief-platform",
      "createdAt": "2026-02-22T01:00:00Z",
      "updatedAt": "2026-02-22T01:00:00Z"
    }
  ]
}

규칙:

• workdir는 필수값이다.
• limit 기본값은 50이며 최대 500까지 허용한다.
• status는 선택값이며 지정 시 해당 상태만 필터링한다.

POST /api/runtime/handoffs/{handoffId}/approve

요청:

{
  "workdir": "/path/to/workdir-b",
  "approverAgentId": "agent-uuid",
  "approved": true,
  "note": "플랫폼 정책 검토 완료"
}

규칙:

• workdir는 targetWorkdir와 일치해야 한다.
• approverAgentId는 targetWorkdir의 에이전트로 해석 가능해야 한다.
• 승인 권한 검증은 orgLevel과 riskLevel을 함께 사용한다.
• riskLevel=high이고 정책에서 사용자 승인이 요구되면 POST /api/runtime/approval/user를 추가로 통과해야 한다.

응답:

{
  "ok": true,
  "handoffId": "handoff-uuid",
  "status": "accepted",
  "requestId": "req-1234",
  "message": "교차 workdir 협업 승인을 기록했습니다."
}

POST /api/runtime/handoffs/{handoffId}/complete

요청:

{
  "workdir": "/path/to/workdir-b",
  "completedByAgentId": "agent-uuid",
  "outcomeSummary": "요청된 검증 완료, 릴리즈 차단 이슈 없음",
  "evidenceLogPath": "knowledge-base/history/reviews/auth-platform-r1-review.md"
}

응답:

{
  "ok": true,
  "handoffId": "handoff-uuid",
  "status": "completed",
  "requestId": "req-1234",
  "message": "교차 workdir 협업 완료를 기록했습니다."
}

추적 이벤트 타입:

• handoff.requested
• handoff.approved
• handoff.rejected
• handoff.started
• handoff.completed
• handoff.blocked

Directive 추적 이벤트 타입:

• directive.submitted
• directive.routed
• chief.brief.created
• work-order.assigned
• directive.closed

Scaling 추적 이벤트 타입:

• scaling.evaluated
• scaling.up
• scaling.down
• lead.activated
• lead.deactivated

POST /api/runtime/command (Internal-only)

요청:

{
  "workdir": "/path/to/workdir",
  "agent": "agent-uuid-or-role-id",
  "provider": "codex",
  "language": "Korean",
  "command": "버그 원인 분석해줘"
}

규칙:

• CEO Dashboard의 직접 호출 경로로 사용하면 안 된다.
• 내부 오케스트레이션 경로(directive -> chief-brief -> work-order)에서만 허용한다.
• 헤더 x-agent-company-call-path=internal-orchestrator가 필요하다.
• provider는 선택값이며 누락 시 agent 값을 대체 사용한다.
• 최종 provider는 claude|gemini|codex 중 하나로 해석 가능해야 한다.
• language는 선택값이며 최대 64자다.
• command가 args:로 시작하면 CLI 인자 모드로 실행한다.
• language 지시문은 프롬프트 모드에서만 자동 부착되고 args: 모드에서는 부착되지 않는다.

응답:

{
  "ok": true,
  "requestId": "req-1234"
}

RuntimeSnapshot 응답 스키마

{
  "workdir": "/path/to/workdir",
  "initialized": true,
  "isRunning": false,
  "directiveState": {},
  "runtimeState": {},
  "liveState": {},
  "events": [],
  "stdout": [],
  "stderr": []
}

WebSocket

• 경로: /ws/runtime

클라이언트 구독 메시지:

{
  "type": "runtime:subscribe",
  "requestId": "req-1234",
  "payload": {
    "workdir": "/path/to/workdir"
  }
}

호환성 규칙:

• payload.workdir 대신 top-level workdir도 허용한다.
• 동일 requestId 재전송은 중복 처리하지 않는다.

서버 이벤트 타입:

• runtime:connected
• runtime:subscribed
• runtime:snapshot
• runtime:log
• runtime:agent_stream
• runtime:directive
• runtime:scaling
• runtime:error

runtime:agent_stream payload:

{
  "workdir": "/path/to/workdir",
  "agent": "agent-uuid-or-role-id",
  "stream": "stdout",
  "content": "line",
  "requestId": "req-1234",
  "timestamp": "2026-02-20T07:00:00.000Z"
}

• stream 값은 stdout|stderr|system을 사용한다.
• 명령 시작/종료/타임아웃 같은 시스템 메시지는 system 스트림으로 전달한다.

runtime:directive payload:

{
  "workdir": "/path/to/workdir",
  "directiveId": "directive-uuid",
  "status": "routed",
  "chiefAgentIds": ["agent-uuid"],
  "requestId": "req-1234",
  "timestamp": "2026-02-20T07:00:00.000Z"
}

runtime:scaling payload:

{
  "workdir": "/path/to/workdir",
  "chiefGroupId": "chief-agent-uuid",
  "roleType": "member",
  "action": "up",
  "delta": 1,
  "reason": "queue-depth-threshold",
  "requestId": "req-1234",
  "timestamp": "2026-02-20T07:00:00.000Z"
}

Envelope 규약

모든 WebSocket 메시지는 아래 envelope를 따른다.

{
  "type": "runtime:snapshot",
  "version": "1.0",
  "requestId": "req-5678",
  "timestamp": "2026-02-20T07:00:00.000Z",
  "payload": {}
}

추적 규칙:

• envelope requestId는 서버 이벤트 단위 식별자다.
• 명령 실행 상관관계는 runtime:agent_stream.payload.requestId를 기준으로 추적한다.
• 스케일링 상관관계는 runtime:scaling.payload.requestId를 기준으로 추적한다.

변경 관리

• Runtime HTTP/WS 스키마 변경 시 본 문서를 먼저 갱신한다.
• 인증/실행 정책이 변경되면 knowledge-base/technical/agent-communication-auth.md를 함께 갱신한다.
• CEO 지시 라우팅 정책이 변경되면 knowledge-base/operations/ceo-command-orchestration.md를 함께 갱신한다.
• 역할 탄력 정책이 변경되면 knowledge-base/governance/approval-rules/role-capacity-scaling.md를 함께 갱신한다.