<a id="module-map"></a>
# 모듈 지도

상위 경로: [Norma 시스템 지도](../README.md#system-map) → 모듈 지도

```mermaid
flowchart TD
  A[agentcore] --> H[harness]
  H --> L[llm]
  H --> T[tool]
  H --> P[permission]
  H --> K[hook contract]
  A --> C[compaction / transcript / memory]
  A --> X[plan / skill]
  X --> T
  M[mcp] --> T
  G[subagent / coordinator] --> H
  N[noaadapter] --> A
  N --> O[noa core]

  click A "#agentcore-harness" "agentcore와 harness"
  click L "#llm" "llm"
  click T "#tool-permission-hook" "tool, permission, hook"
  click C "#context-packages" "context packages"
  click X "#extension-packages" "extensions"
  click G "#coordination-packages" "coordination"
  click N "#noa-stack" "Noa stack"
```

<a id="agentcore-harness"></a>
## `agentcore`와 `harness`

| 항목 | `agentcore` | `harness` |
|---|---|---|
| 책임 | host options를 stateful `Session`으로 조립 | Prompt 한 번의 state machine과 event stream |
| 진입점 | `NewSession`, `Session.Prompt`, `Resume`, `Close`, `Run` | `Query`, `QueryInput`, `QueryDeps`, `Event`, `Terminal` |
| 소유 상태 | messages, usage, session ID, recorder, task manager, unlock/controller | 해당 Prompt의 phase, turn, request view, running tool calls |
| 입력 변경 | memory/hook context와 reminder 조립 | compaction/view, recovery, settlement message |
| 호출자 책임 | 같은 Session의 Prompt 직렬화, terminal 소비, Close | event iterator 완전 소비, dependency와 callback thread safety |

`agentcore.NewSession`은 nil `Tools`에만 defaults를 적용하고 optional package의 tool을 append한다. `Session.Prompt`가 `QueryInput`을 만들고 `KindResult`를 받아야 최종 messages와 usage를 Session에 commit한다. `harness.Query`는 provider 호출, streamed block 누적, scheduler, context recovery와 종료 reason을 소유한다. [Session 구성](evidence:agentcore-newsession) [Prompt](evidence:agentcore-prompt) [harness 근거](evidence:harness-query)

<a id="llm"></a>
## `llm`

`llm.Provider`는 streaming `Stream`과 non-streaming `Complete`를 제공한다. 내부 `Message`/`ContentBlock`은 text, thinking, tool use/result를 표현하며 built-in adapter는 Anthropic Messages, OpenAI Chat Completions, OpenAI Responses wire format을 이 모델로 변환한다. `boundary.go`는 compact boundary 뒤 history 선택과 tool-use/result pairing을 정리하고 retry/rate-limit helper는 요청 establishment 앞에 놓인다. [provider 근거](evidence:llm-provider) [boundary 근거](evidence:llm-boundary) [retry 근거](evidence:llm-retry)

제공 계약과 소비 기능은 [provider 계약](../contracts/README.md#provider-contract), 실제 request 반복은 [provider 기능](../runtime/extensions-and-coordination.md#providers)에 있다.

<a id="tool-permission-hook"></a>
## `tool`, `permission`, `hook`

`tool.CoreTool`이 capability metadata와 call을 제공하고 `Registry`가 name lookup/schema 노출을 맡는다. `permission.Evaluate`는 deny-priority 정책과 live mode를 적용한다. `hook.Registry`는 lifecycle callback을 순차 호출하지만 callback timeout, panic recovery와 자체 locking은 제공하지 않는다. harness가 세 package를 [direct tool pipeline](../runtime/tools-and-permissions.md#permission-pipeline)으로 결합한다. [tool 근거](evidence:tool-contract) [permission 근거](evidence:permission) [hook 근거](evidence:hooks)

`tool` package 안에는 file/search/Bash, background task, opt-in PTY, web, deferred dispatcher, Todo와 AskUser 구현도 함께 있다. 같은 package라는 사실이 같은 보안 성질을 뜻하지 않으므로 [기본 도구 경계](../runtime/tools-and-permissions.md#builtin-boundaries)에서 capability별로 본다.

<a id="context-packages"></a>
## `compaction`, `transcript`, `memory`

| package | 내부 흐름 | 지속성·실패 경계 |
|---|---|---|
| `compaction` | threshold → micro compact → provider summary → boundary message | in-memory history를 바꾸며 provider summary 실패/circuit breaker가 있음 |
| `transcript` | append JSONL record → reconstruct messages/usage | append-only 파일, fsync/lock/corrupt-tail repair 없음 |
| `memory` | Markdown/frontmatter scan·save → `MEMORY.md` index → keyword relevance | file/index가 단일 transaction이 아니며 ASCII keyword 방식 |

세 package는 모두 context와 관련 있지만 권위 상태가 다르다. 자세한 관계는 [상태 소유권](../runtime/context-and-resume.md#state-ownership)에 있다. [compaction 근거](evidence:compaction) [transcript 근거](evidence:transcript-record) [memory 근거](evidence:memory-schema)

<a id="extension-packages"></a>
## `mcp`, `skill`, `plan`

- `mcp`는 in-process tools와 stdio JSON-RPC client를 `CoreTool`로 감싼다. dynamic refresh와 모든 content 종류를 보존하지 않는다.
- `skill`은 `SKILL.md`를 읽고 선택한 instruction을 independent user message로 주입하며 optional MCP names를 unlock한다.
- `plan`은 permission mode를 보유하고 `EnterPlanMode`/`ExitPlanMode`가 read-only exploration과 승인 후 target mode 전이를 만든다.

세 모듈은 [확장 기능](../runtime/extensions-and-coordination.md#mcp)에서 tool registry와 permission을 소비한다. [MCP 근거](evidence:mcp-tools) [skill 근거](evidence:skills) [plan 근거](evidence:plan)

<a id="coordination-packages"></a>
## `subagent`, `coordinator`

`subagent`는 `Agent` tool call을 새 child `harness.Query`로 바꾸고 conversation과 optional sidechain transcript를 분리한다. `coordinator`는 이 tool을 조립하는 LLM-driven 경로와 goroutine/semaphore 기반 `RunParallel` 경로를 제공한다. 공유 provider/tool/filesystem과 누락된 parent option 상속 때문에 security isolation primitive는 아니다. [subagent 근거](evidence:subagent) [coordinator 근거](evidence:coordinator)

<a id="noa-stack"></a>
## `noa`와 `noaadapter`

`noa`는 host type과 I/O를 모르는 pure compression core다. message refs, range/tier 판정, pruning, nudge와 compression state를 계산한다. `noaadapter`는 `llm.Message` projection, archive/state file, `Compress` tool과 `agentcore.Options` wiring을 제공한다. [Noa 상세](noa.md#enablement)에서 두 층의 transaction과 model-visible view를 분리한다. [core 근거](evidence:noa-pipeline) [adapter 근거](evidence:noa-enable)

## package 전수 색인

| package/실행 단위 | 주 책임 | 기능 소비자 |
|---|---|---|
| `agentcore`, `harness` | session 조립과 loop | 모든 embedding host |
| `llm` | provider-neutral model과 wire adapters | harness, compaction, host |
| `tool`, `permission`, `hook` | capability, 정책, lifecycle | harness, optional modules |
| `compaction`, `transcript`, `memory` | context·기록·장기 memory | agentcore |
| `mcp`, `skill`, `plan` | extension과 mode | agentcore/host |
| `subagent`, `coordinator` | child execution과 fan-out | host/coordinator agent |
| `noa`, `noaadapter` | advanced context projection | opt-in host/agentcore |
| `cmd/agentcore` | demo CLI | 사람 operator |
| `examples/*` | wiring examples | SDK adopter; production policy 아님 |

저장소에는 물리 DB, migration, server route, queue/cron/worker registration이 없다. `Provider`의 외부 HTTP 호출과 MCP JSON-RPC는 **소비 계약**이며 Norma가 제공하는 서비스 API로 분류하지 않는다.