통합과 운영 경계

상위 경로: Norma 시스템 지도 → 통합과 운영

Norma는 daemon이나 배포 서비스가 아니라 Go library다. host binary가 provider credentials, prompt, tools, permission UI, process/filesystem/network 경계, persistence와 shutdown을 소유한다. cmd/agentcore와 examples는 wiring 예시이며 production policy가 아니다. README 근거 Session 구성

go.mod는 go 1.26.3을 선언해 README의 “Go 1.23+”와 다르다. 이 snapshot을 build/test할 때는 module directive를 기준으로 한다. module graph의 외부 entry 9개(직접 4, graph-only transitive 5), package 선택 여부와 examples 5개는 dependency와 examples에 있다. module graph 근거

최소 embedding은 terminal을 보존하는 event loop까지 포함한다.

sess := agentcore.NewSession(agentcore.Options{
    Provider:       provider,
    SystemPrompt:   []string{systemPrompt},
    Tools:          approvedTools,
    PermissionMode: permission.ModeDefault,
    CanUseTool:     approve,
    Transcript:     transcriptStore,
    SessionID:      safeRunID,
    MaxTurns:       40,
    MaxDuration:    30 * time.Minute,
})
defer sess.Close()

for ev, err := range sess.Prompt(runCtx, task) {
    if err != nil { return err }
    if ev.Kind == harness.KindResult {
        persistTerminal(ev.Terminal)
    }
}

구성 책임

trusted absolute paths에서 WorkingDir, SessionID, output/archive roots를 만들고 model/user text로 path를 직접 구성하지 않는다. credentials는 Bash/MCP child가 물려받는 전체 environment 대신 tool별 최소 환경으로 전달한다.

준비와 첫 실행

1. 고정 source root와 go.mod가 같은 snapshot인지 확인한다.
2. Go toolchain이 module directive를 지원하는지 go version으로 확인한다.
3. 사용하는 provider format의 endpoint/model/credential을 secret channel로 준비한다.
4. 최소 tool 목록과 permission mode/callback을 명시한다. nil Tools가 defaults를 넣는 점을 의도적으로 선택한다.
5. WorkingDir와 transcript/output/memory/Noa root를 trusted path로 만들고 권한·보존 정책을 적용한다.
6. caller context deadline, MaxTurns/Duration, model request rate와 target action rate를 각각 설정한다.
7. synthetic prompt와 read-only custom tool로 event/terminal/recording을 확인한 뒤 mutating capability를 연다.

첫 Grep 전에 rg를 image/PATH에 설치하거나 NORMA_DISABLE_RIPGREP=1 또는 NORMA_RIPGREP_NO_INSTALL=1을 설정한다. 아무 조치도 없고 rg가 없으면 읽기 전용·self-allow로 등록된 Grep이 permission callback 밖에서 npm install -g @vscode/ripgrep을 실행할 수 있으며, 이 bootstrap에는 context timeout/cancel이 없다. trigger와 silent fallback은 Grep bootstrap operation에 있다. 구현 근거

demo CLI를 로컬에서 build하는 정의 명령은 다음과 같다.

CLI 근거

cd reference/src/Norma
go build -o agentcore ./cmd/agentcore

실제 provider 호출은 credential과 비용·외부 effect를 발생시키므로 문서 생성 과정에서는 실행하지 않았다. flags, stdout/stderr, signal/EOF와 exit semantics는 CLI 동작 계약에 있다.

종료, 중단과 복구

Session.Close는 background task manager를 cleanup하지만 MCP stdio client는 별도 close가 필요하다. context를 무시하는 custom tool은 SDK가 timeout result를 만든 뒤에도 계속 실행할 수 있으므로 OS-level supervisor가 필요하다.

정상/비정상 종료에서 확인할 순서는 다음과 같다.

1. Prompt iterator의 terminal 수신 여부와 reason/error를 기록한다.
2. action broker에서 running/unknown actions를 표시하고 외부 effect를 조회한다.
3. background tasks, PTY sessions와 process groups를 중단한다.
4. MCP clients와 다른 host-owned resources를 닫는다.
5. transcript writer error, output spill, Noa state/archive warning을 확인한다.
6. 재개할 run에는 last durable state와 reconciliation 결과를 남긴다.

이 snapshot의 재검증

2026-10-07 KST에 고정 local source에서 다음을 실행했다.

go test ./... -count=1

실행 환경은 go1.26.3 linux/amd64, 결과는 exit 1이다. package별 결과와 8개 top-level failure/panic은 홈의 테스트 상태에 기록했다. 동적 LLM/MCP/network/long-session 실행은 하지 않았다.

문서 설명의 정적 risk 중 별도 reproduction이 필요한 항목은 다음과 같다.

• stream error/consumer 중단과 이미 시작한 orphan tool effect
• hook rewrite 뒤 schema/permission bypass
• untrusted SessionID/path traversal과 cleanup 범위
• WebFetch proxy failure 뒤 direct-intended fallback과 environment proxy 재상속 분기
• hidden/deferred inner tool의 direct/wrapper authorization 차이
• context를 무시하는 tool의 timeout 이후 실행

현재 SDK 채택 경계

Norma가 현재 제공하는 재사용 가능한 primitive는 provider-neutral event loop, tool contract/scheduler, permission modes, replaceable context interface, transcript primitive와 extension adapters다. 다음 책임은 구현에 없으므로 host가 별도 소유해야 한다.

• 승인된 target scope, redirect/DNS와 rate를 실행 직전에 강제하는 broker
• action idempotency, before/after provenance와 immutable evidence
• asset/hypothesis/finding state와 duplicate suppression
• persistent frontier, lease, retry policy와 hard deadlines
• finding reproducibility와 human-review workflow
• agent별 filesystem/process/network isolation
• model/tool/child 전체 cost와 policy-version accounting

이 경계는 미래 아키텍처 제안이 아니라 현재 public types와 실행 경로에서 확인되는 책임 분리다. Norma permission/hook만으로 위 control-plane 보장을 주장할 수 없다.

소스 사용 경계

고정 Norma tree에는 LICENSE, LICENSE.*, COPYING 파일이 없다. 공개 저장소이고 ARTEX가 Go module로 참조한다는 사실은 복제·수정·재배포 권리를 자동 부여하지 않는다. 이 snapshot은 분석 근거이며, implementation dependency나 파생 코드로 사용할 때 upstream 권리 조건을 별도로 확인해야 한다.

상위 영역: Norma 현재 시스템 지도

전체로 돌아가기 · Markdown 원본