Provider, extension과 coordination

Provider, extension과 coordination · 관계

이 대상이 사용하는 구현·계약·의존 · 3개

구현 담당 · llm · · llm-provider
계약 사용 · Provider와 message contract · · llm-provider
계약 사용 · Model HTTP · built-in provider가 외부 model HTTP operation을 소비 · llm-anthropic · llm-openai-chat · llm-openai-responses

상위 경로: Norma 시스템 지도 → 기능 지도 → Provider와 확장

llm.Provider는 Stream과 Complete를 공통 contract로 둔다. built-in adapter는 Anthropic Messages, OpenAI Chat Completions, OpenAI Responses format을 내부 content blocks와 stream events로 정규화한다. model name, endpoint, API key, reasoning/thinking와 output cap field는 host config가 정한다. provider 근거

format	기본 endpoint source	output/reasoning 차이
`anthropic`	config → `ANTHROPIC_BASE_URL` → public default	Anthropic system cache boundary, thinking signature
`openai`	config → `OPENAI_BASE_URL` → public default	Chat Completions, 선택 `max_completion_tokens`
`openai-responses`	같은 OpenAI source	Responses request/stream translation
custom	host `Provider` 구현	contract 충족과 오류/usage fidelity가 host 책임

adapter가 normalized event를 만든다는 사실은 endpoint 호환성이나 thinking/tool block의 무손실 보장을 뜻하지 않는다. MessagesForAPI는 마지막 compaction boundary 뒤 messages를 취하고 orphan tool pairs를 정리한다. message boundary 근거

Retry와 rate limit

model request establishment의 network error, 408/429/500/502/503/504는 기본 최대 3회 retry되며 0.5s→1s→2s, 최대 8s backoff를 사용한다. fixed interval과 retry count를 설정할 수 있다. stream body를 읽기 시작한 뒤 끊기면 자동 재개하지 않는다. OpenAI empty response의 전체-request retry는 별도 설정이다. retry 근거

provider rate limiter는 같은 provider instance를 공유하는 callers 전체에 per-second/per-minute token bucket을 적용한다. logical request 한 번을 세고 내부 retry는 추가 count하지 않는다. cancel된 reservation은 반환하지 않아 더 보수적으로 남는다. 이것은 model API rate이며 target traffic rate limiting과 관계없다.

MCP

MCP · 관계

이 대상이 사용하는 구현·계약·의존 · 1개

구현 담당 · mcp, skill, plan · · mcp-tools · mcp-handshake

전체 관계 1개 · 종류 선택·관계도

mcp.InProcessServer와 stdio Client.Tools는 MCP tool을 mcp__<server>__<tool> 이름의 CoreTool로 감싼다. stdio client는 initialize와 tools/list를 수행하고 calls를 JSON-RPC로 전달한다. MCP 근거

child process는 host environment와 cwd를 사용한다.
wrapping tool의 permission metadata는 호출 때 적용되지만 server 내부 effect scope는 별도다.
returned text 중심으로 변환하며 image/resource/structured content fidelity가 제한된다.
initial list 뒤 dynamic tool refresh는 확인되지 않았다.
client process close는 Session.Close와 별도 lifecycle이다.

Skill

Skill · 관계

이 대상이 사용하는 구현·계약·의존 · 1개

구현 담당 · mcp, skill, plan · · skills

전체 관계 1개 · 종류 선택·관계도

skill.LoadDir은 child directory의 SKILL.md YAML frontmatter와 Markdown body를 읽어 Registry를 만든다. Skill tool은 선택한 instructions를 Result.Extra의 별도 user message로 넣고 declared MCP names를 optional callback으로 unlock한다. skill 근거

skill instruction은 system message나 signed policy가 아니다. unreadable/malformed entry는 load 과정에서 skip/축소될 수 있고 source trust, content digest, sandbox를 검증하지 않는다. compaction은 skill message를 boundary 뒤에 재주입할 수 있으므로 untrusted skill은 장기 prompt injection 경로다.

Plan mode

Plan mode · 관계

이 대상이 사용하는 구현·계약·의존 · 1개

구현 담당 · mcp, skill, plan · · plan

전체 관계 1개 · 종류 선택·관계도

plan.Controller는 live permission mode를 보유하고 EnterPlanMode와 ExitPlanMode를 제공한다. plan에서는 read-only tool만 허용된다. Exit tool은 permission상 read-only지만 approver를 호출하고 승인되면 default acceptEdits 또는 target mode로 전환한다. approver가 nil이면 자동 승인한다. plan 근거

그림 크게 보기

Mermaid 원문

stateDiagram-v2
  [*] --> Normal
  Normal --> Plan: EnterPlanMode
  Plan --> Plan: Exit rejected
  Plan --> TargetMode: Exit approved

mode는 tool call마다 다시 읽힌다. 같은 assistant response에서 Exit가 먼저 완료되고 뒤의 mutating call이 대기 중이면 새 mode로 실행될 수 있다. model response 전체가 승인 transaction은 아니다. 예제 security-audit은 parent가 ModePlan인데 Agent tool은 read-only가 아니어서 현재 구성에서는 delegation이 permission에서 거부된다.

Subagent 격리의 범위

Subagent 격리의 범위 · 관계

이 대상이 사용하는 구현·계약·의존 · 1개

구현 담당 · subagent, coordinator · · subagent · coordinator

전체 관계 1개 · 종류 선택·관계도

subagent.NewTool은 agent type/prompt/workdir를 받아 새 child harness.Query를 실행한다. child conversation과 optional transcript sidechain은 분리되고 recursion depth 기본값은 3이다. subagent 근거

그림 크게 보기

Mermaid 원문

flowchart TD
  P[Parent conversation] -->|Agent tool| C[Child Query]
  C --> CC[Child conversation]
  C -->|shared reference| X[Provider / tool instances / hooks / filesystem]
  C --> S[(sidechain transcript)]

상속·공유	별도 또는 누락
provider, selected/shared CoreTool instances, hooks, WorkingDir	child conversation, optional tool subset, system prompt
parent registry pointer when no subset	parent allow/deny, BashEnv, Tasks, compactor, output caps, MaxDuration
shared dispatcher closure가 가리키는 UnlockSet 가능	parent schema filter와 plan mode 값의 자동 상속
host filesystem/network	child usage와 terminal reason의 parent aggregate

따라서 “isolated”는 대화 context 수준이다. 보안 격리는 independent process/container, credentials, filesystem과 brokered network가 담당해야 한다.

Coordinator의 두 경로

coordinator.Config은 다음 두 실행 방식을 제공한다. coordinator 근거

방식	실제 실행	병렬성	반환 한계
LLM-driven `AgentTool`	coordinator model이 child task 생성	Agent tool이 exclusive라 한 response에서는 직렬	worker output을 model이 다시 소비
programmatic `RunParallel`	task마다 goroutine + semaphore	`MaxParallel` 기본 4	입력 순서 Result, terminal reason은 error로 축약

worker default permission은 acceptEdits이고 MaxTurns == 0은 tool-turn 제한 없음이다. config에는 child hard duration, transcript, compactor, per-child egress와 total cost accounting이 없다. persistent frontier, lease, semantic dedup와 finding validation은 coordinator가 아니라 host control plane 책임이다.

이동한 문서 주소

등록된 주소만 자동 이동합니다. 아래에서 새 위치를 선택할 수 있습니다.

runtime/extensions-and-coordination.md#provider%EC%99%80-%ED%99%95%EC%9E%A5%EC%A1%B0%EC%A0%95-%EA%B8%B0%EB%8A%A5 → Provider, extension과 coordination · Provider, extension과 coordination

상위 영역: 기능 지도

전체로 돌아가기 · Markdown 원본