Agent Ecosystem
하나의 계층화된 거버넌스 루프입니다. 각 컴포넌트는 정확히 하나의 관심사를 소유하며, 서로의 상태 머신을 임포트하지 않고 오직 타입화된 JSON 계약을 통해서만 결합합니다.
불변 $shame 목표는 shame-deterministic-instruction-obedience-v1
(skills/shame/immutable_goal.json)입니다: 프로젝트 에이전트가 명시적 지시를 무시하지 못하도록 지시 복종과 완료 보고를 타입화된 pydantic 검증 계약, 결정론적 확장 게이트, 보존된 에이전틱 평가로 변환합니다. 산문은 표시용일 뿐이며 성공을 결정할 수 없습니다. 아래에 명명된 모든 생태계 멤버는 자신의 경계에서 반드시 이 목표를 보존해야 합니다.
그래프
$create-svg로 렌더링됩니다(scene.yml이 소스이며, skills/create-svg/run.sh render skills/agent-ecosystem/scene.yml skills/agent-ecosystem/ecosystem.svg로 재생성).
기계 판독 가능한 멤버십 매니페스트는 members.json입니다(scripts/membership.py validate로 검증; 보존된 평가가 최신 상태를 유지).
생성하는 위 SVG와 아래 mermaid 블록은 비규범적(non-normative) 일러스트레이션이며, 소유권 테이블과 멤버의 ## Ecosystem 섹션이 규범적 토폴로지입니다.
flowchart TB
subgraph SHAPE[생성 형상화]
PONY[ponytail\nYAGNI 사다리, 리셉트 없음]
end
subgraph TURN[턴 레이어 - Pi 세션]
SHAME[shame 확장\npi.agent_status.v1\n검증, 컴파일, 삼키기]
TRIAGE[triage-error\n실패 어휘\n코드, 원인, 다음 명령]
end
subgraph WORK[워크플로 레이어]
ASK[ask\n의도를 DAG 계약으로 컴파일]
TAU[tau\nDAG 실행, 승인 소유\n타입화된 노드 리셉트, goal_hash]
end
subgraph OPS[운영 레이어]
WD[project-watchdog\ncron 디스패치, 임대,
증명 게이트, 틱 리셉트]
HERDR[ops-herdr 브릿지\n인박스, 정지,
TTL 데드레터]
end
MEM[(Memory\n학습 예제,
분류 해결,
프로젝트 지식)]
PONY -.-> SHAME
SHAME -->|failed.triage.code| TRIAGE
SHAME -->|needs_* 컴파일 명령| ASK
ASK -->|tau.dag_contract.v1| TAU
TAU -->|노드 리셉트 / handoff v2가 상태 전달| SHAME
WD -->|ticket_repair via ask| ASK
WD -->|판정 읽기| TAU
HERDR -->|데드레터 분류 코드| TRIAGE
SHAME -->|레이블 예제| MEM
TRIAGE -->|생성된 코드| MEM
TAU -->|실행 후 불량 노드 리셉트 내보내기| MEM
소유권 테이블
| 컴포넌트 | 소유 | 방출 | 소비 | $shame 불변 목표를 위한 MUST |
|---|---|---|---|---|
| 프로젝트 에이전트 | 턴 경계에서의 지시 복종 | pi.agent_status.v1 보고 | 운영자 지시, 도구 결과, 리셉트 | 보호된 작업을 타입화된 상태 데이터로 보고해야 하며, continuing.not_done[].next_command를 사용하여 에이전트가 실행할 수 있는 미완료 작업을 표시하고, 산문/커밋/리뷰어 의견을 완료 증거로 취급하지 않아야 합니다. |
| triage-error | 실패 어휘 (failure_codes.json) | {code, cause, next_command} | 모든 레이어의 원시 오류 텍스트 | 하나의 원시 신호가 하나의 카탈로그 또는 생성된 코드에 매핑되어야 하며, 모호한 터미널 레이블이 유효한 결정이 될 수 없습니다. |
| shame | 턴 상태 (pi.agent_status.v1) 및 shame.immutable_goal.v1 | 상태 객체, 불변 목표, 학습 예제 | 분류 코드, 인간 레이블 | 상태 진실을 pydantic 검증, 산문 표시 전용, 평가 게이트로 유지해야 합니다. |
| lazy-report-shame-shame-shame 확장 | Pi message_end 시행 | 거부 패킷, 렌더링된 상태, 후속 명령 | 최종 상태 JSON, 연속 원장 | 누락/무효 상태 JSON을 거부하고, 모델이 작성한 상태 산문을 제거하며, 검증된 데이터에서 렌더링하고, 컴파일된 연속/에스컬레이션 명령을 대기열에 추가해야 합니다. |
| status-json-check.mjs | 최종 상태 추출 및 검증기 호출 | 검증된 상태 객체를 포함한 검사 결과 | 어시스턴트 텍스트 | 정규식, 산문 제목, 마크다운, HTML 또는 LLM 판단으로 상태 유효성을 결정해서는 안 됩니다. |
| agent_status_schema.py | pydantic 상태 적법성 | 구문 분석 성공/실패 | 최종 상태 JSON | extra=forbid, 타입화된 상태 페이로드, 정식 분류 코드, continuing에서만 not_done을 사용하여 유효하지 않은 상태를 표현 불가능하게 만들어야 합니다. |
| compile-status-command.mjs | 타입화된 상태-명령 컴파일 | 정확한 후속 명령 또는 명령 없음 | pydantic 검증 상태 객체 | continuing/needs_* 페이로드를 기계적으로 컴파일하고 터미널/인간 상태를 자동 명령 없음으로 컴파일해야 합니다. |
| agentic-evals | 보존된 회귀 증거 | 준비 보고서 | 픽스처 및 명령 | 정규식/산문 상태 정책이 반환되거나 pydantic 상태 불변이 약화되면 실패해야 합니다. |
| ask | 의도-DAG 컴파일 | tau.dag_contract.v1, 복구 패킷 | 상태 에스컬레이션 페이로드 | 비공식 에스컬레이션 산문 대신 타입화된 needs_* 페이로드를 소비해야 합니다. |
| tau | DAG 실행 및 승인 | 노드 리셉트, tau.agent_handoff.v1/v2, 목표 해시 | DAG 계약, 포함된 상태 객체 | 불변 목표 해시와 타입화된 승인 리셉트를 소유해야 하며, 리뷰어 산문이 승인을 대체할 수 없습니다. |
| project-watchdog | 스케줄 디스패치 | 틱 리셉트, 증명 게이트, 잠금, 연속 원장 | GitHub 티켓, tau 판정 | 티켓/게이트/다음 단계가 해결되지 않은 상태에서 done이 실패할 수 있도록 기계 판독 가능한 미해결 작업을 노출해야 합니다. |
| ops-herdr | 세션 간 전송 | 인박스 레코드, 데드레터 | 분류 코드 | 세션 간 실패/상태를 분류 코드가 포함된 타입화된 인박스 또는 데드레터 레코드로 전달해야 합니다. |
| ponytail | 생성 최소주의 | ponytail: 부채 주석(리셉트 아님) | 리셉트 세계에서 아무것도 | 상태, 리셉트, 증명 또는 평가 요구 사항을 재정의하지 않아야 합니다. |
| Memory | 회상 | 저장/회상 읽기 응답(봉투 리셉트 아님; 회상은 관찰이며, 절대 래핑되지 않음) | 모든 지속성 | shame 예제, 분류 해결, 프로젝트 지식을 읽기 응답과 함께 저장해야 하며, 회상은 완료 리셉트가 아닌 관찰입니다. |
| agent-ecosystem | 컴포넌트 소유권 및 리셉트 경계 | pi.receipt_envelope.v1 검증 | 경계 페이로드 | 소유권 맵을 게시하고 권한 변경 경계에서 봉투 래핑을 요구해야 합니다. |
| goal-helper | 증명 중심 목표 형상 | 불변 목표 프롬프트/체크리스트 | 인간 목표 텍스트 | 성공을 기본 증명, 완료 기준, 허용 범위, 금지된 드리프트, 재시도 예산, 중지 조건에 연결해야 합니다. |
pi.receipt_envelope.v1 - 경계 봉투
오직 권한 변경 경계(dispatch, handoff, acceptance, escalation, closure, durable failure)에서만 페이로드를 봉투에 래핑하세요. 내부 객체는 래핑되지 않은 상태로 유지됩니다(검토된 YAGNI 판결: 범용 이벤트 버스 없음, 모든 아티팩트에 봉투 없음).
{
"schema": "pi.receipt_envelope.v1",
"receipt_id": "stable-id",
"payload_schema": "pi.agent_status.v1",
"producer": "shame",
"emitted_at": "RFC3339",
"goal_hash": "sha256:<64hex> (optional)",
"parent_refs": [
{"receipt_id": "id", "expected_schema": "s", "expected_producer": "p", "digest": "sha256:<64hex> (optional)"}
],
"triage_code": "catalog or minted code (optional)",
"payload": {}
}
다음으로 검증:
skills/agent-ecosystem/run.sh validate <envelope.json>
echo '{...}' | skills/agent-ecosystem/run.sh validate -
scripts/receipt_envelope.py(pydantic, extra=forbid)가 시행하는 규칙:
triage_code는 있을 경우, triage-error 카탈로그 코드 또는 생성된*_unclassified_<8hex>코드여야 합니다.pi.agent_status.v1.failure와 동일한 규칙입니다.goal_hash및parent_refs[].digest는sha256:+ 64자 소문자 16진수여야 합니다.parent_refs는goal_hash가 필요합니다: 공유 목표가 없는 증거 엣지는 신뢰할 수 없으며 검증에 실패합니다.- Pydantic은 STRUCTURE만 증명합니다. 참조 RESOLUTION은 별도의 소비자 측 단계이며 네 가지 필수 검사가 필요합니다: 참조된 리셉트가 존재함; 스키마가
expected_schema와 일치함; 프로듀서가expected_producer와 일치함;resolved_parent.goal_hash == envelope.goal_hash(존재하는 해시는 비교되기 전까지 공유 목표가 아님). 다이제스트 검증은digest가 설정된 경우 적용됩니다. 구조적으로 유효한 봉투가 아직 신뢰할 수 있는 봉투는 아닙니다. payload.schema는 모든 래핑된 페이로드에서 REQUIRED이며 봉투payload_schema와 같아야 합니다. 익명 페이로드는 검증에 실패합니다.extra=forbid스키마에 대한 필드 세트 변경은 설계상 파괴적입니다. 새로운 스키마 버전이 필요하며, 제자리 편집은 허용되지 않습니다.
공유 JSON 필드 규칙
아래 필드는 실제 공유 표면입니다. 컴포넌트가 소유자와 동일한 이름, 형상 및 의미를 방출하거나 검증할 때 해당 필드를 "공유"합니다.
| 필드 | 형상 | 소유자 | 공유 대상 |
|---|---|---|---|
schema | 버전 ID, 예: pi.agent_status.v1 | 각 스키마 소유자 | 모든 계약 객체; 버전 범프는 추가 또는 새 이름 |
code (triage) | 카탈로그 항목 또는 <prefix>_unclassified_<8hex> | triage-error | shame failure.triage.code, 봉투 triage_code, herdr 데드레터, ask 복구 패킷 |
cause / next_command | 일반 문자열 / 정확한 실행 가능 명령 | triage-error | triage 분류의 모든 소비자; next_command는 또한 shame continuing 계속 진행 필드 |
goal_hash | sha256: + 64자 소문자 16진수 | tau (불변 목표 패킷) | shame 상태(선택), 봉투(선택), 모든 tau 노드 리셉트 |
verified[] | {command, result} 쌍 | shame | 상태 객체가 포함된 모든 곳의 done 상태 증명 |
proof[] | 구체적 경로/URL/ID; pi.agent_status.v1의 로컬 경로는 done이 통과하기 전에 존재해야 함 | shame | 상태 객체; watchdog 증명 게이트는 동일한 아티팩트를 명명 |
parent_refs[] | {receipt_id, expected_schema, expected_producer, digest?} | agent-ecosystem 봉투 | 에스컬레이션 증거(needs_webgpt의 임시 경로 대체) |
producer / receipt_id / emitted_at | 문자열 / 안정적 ID / RFC3339 | agent-ecosystem 봉투 | 모든 경계 래핑 리셉트 |
payload_schema | 버전 ID; 페이로드가 선언할 때 payload.schema와 같아야 함 | agent-ecosystem 봉투 | 모든 경계 래핑 리셉트 |
| 터미널 판정 | PASS FAIL BLOCKED NEEDS_ATTENTION | tau | ask 조인, watchdog 증명 게이트, 스트림 모니터 |
recoverable / not_this | bool / 제외 목록 | triage-error 카탈로그 | 재시도 vs 에스컬레이션을 결정하는 소비자 |
triage-error 규칙(여기서 규범적, 구현은 해당 위치)
- 하나의 원시 신호는 하나의
{code, cause, next_command}에 매핑됩니다. 레이어 경계의 일반 코드는 버그이지 분류가 아닙니다. - 카탈로그 항목은
skills/triage-error/failure_codes.json에{code, layer, match[], cause, next_command, recoverable, not_this[]}로 존재합니다. 매칭은 결정론적입니다: 정규화는 정확히" ".join(text.lower().split())(소문자, 모든 공백 실행을 단일 공백으로 축소, 끝 트림)입니다. 항목은 해당match[]토큰(역시 소문자) 중 ANY가 정규화된 신호의 부분 문자열일 때 일치합니다.--layer가 주어지면 다른layer의 항목은 건너뜁니다. 파일 순서에서 첫 번째 일치 항목이 승리합니다. 정규식 절대, LLM 판단 절대. 터미널 분류로 금지됨(증상이지 원인이 아니며, 기본 신호에서 재분류되어야 함):NEEDS_ATTENTION,BLOCKED,browser_handler_timeout,unknown_error,generic_failure, 그리고 모든 단순 터미널 판정 단어. - 일치하지 않는 신호는
<layer-or-unknown>_unclassified_<8hex>를 생성하며, 여기서 8자 16진수는 정규화된 신호 텍스트에 대한 sha256의 처음 8자입니다. 따라서 동일한 신호는 항상 동일한 코드를 생성합니다. 생성은 티켓 + agentic-eval + 메모리 루프를 엽니다. 반복 임계값: 동일한 생성 코드의 두 번째 관찰은 프로모션 또는 별칭 지정을 트리거합니다. 별칭 표현: 카탈로그 파일의 최상위aliases맵은 생성된 코드를 정식 코드로 매핑합니다. 생성은 정규화된 신호에 대해 결정론적이므로, 반복 신호는 동일한 코드를 다시 생성하고 분류기는 맵을 통해 정식 항목으로 해결합니다(aliased_from으로 기록). 생성된 코드는 두 번째 정식 ID가 아닙니다. 티켓/평가/메모리 부작용은 생성된 코드당 멱등적입니다(코드 문자열로 키됨). - 실패를 명명하는 모든 생태계 컴포넌트는 카탈로그 또는 생성된 코드를 사용합니다. pydantic 검증기(상태 스키마, 봉투) 모두 구문 분석 시 이를 시행하므로, 모호한 레이블은 유효한 객체에 존재할 수 없습니다.
디자인 판결(외부 검토에서)
- 엄격함은 DECISIONS에 적용되며 observations에는 적용되지 않습니다. 원시 증거는 관대하게 유지하고, 승인된 결과는 엄격하게 유지하세요. 타입화된
unknown관찰은 합법적입니다. 모호한 결정은 그렇지 않습니다. - 생성된
*_unclassified_*코드는 임시 수명 주기를 가집니다: 반복될 때 카탈로그로 프로모션하거나 기존 코드에 별칭 지정하세요. 절대 확산시키지 마세요. - 스키마 변경은 추가적입니다. 형상을 깨는 변경은 새 버전(
tau.agent_handoff.v2패턴)을 얻으며, 제자리 편집은 절대 허용되지 않습니다. - 구축하지 말 것: 범용 거버넌스 이벤트 버스; ponytail 주석, Memory 회상 또는 내부 재시도에 대한 리셉트.
멤버십
스킬 또는 확장 기능은 SKILL.md에 ## Ecosystem 섹션을 추가하여 생태계에 가입합니다. 이 섹션은 어떤 스키마를 생성하고, 소비하며, 어떤 경계 이벤트를 봉투에 래핑하는지 명시합니다. 현재 멤버: shame, triage-error, tau, ask, project-watchdog, ops-herdr. Ponytail은 설계상 인접합니다.