ARTEX 현재 시스템 문서
전체 문서
이 페이지 목차

도구 catalog·조립·승인 모듈

도구 catalog·조립·승인 모듈 · 관계

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

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

이 모듈은 역할별 base capability, DB catalog, Skill/MCP visibility, runtime gate, intercept를 한 호출 경로로 연결한다. 이름이 source에 존재함, session prompt에 schema가 보임, 호출 gate를 통과함, 실행이 성공함, 결과가 증거로 남음은 서로 다른 상태다. 고정 이름과 역할별 기본값은 도구 전수표가 소유한다.

역할별 조립 순서

역할별 조립 순서 · 관계

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

  • 계약 사용 · tools · tool assembly가 persisted catalog를 소비 · core-edge-9

이 대상을 사용하는 기능·모듈·계약 · 1개

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

agent key + task context

domain 후보 + Norma base

agent MCP / Skill visibility

visible Skill registry

direct-visible enabled MCP

Skill metadata가 gate한 MCP

orchestration · platform · retest · traffic · custom

base + extra merge

tools rows

enabled + binding + schema/default resolve

coverage · capture · search · shell 조건

deferred schema + unlock set

permission hook + ARTEX interceptor

Go handler · process · HTTP · MCP

activity · tool_usage · intercept trace

그림 크게 보기
Mermaid 원문
flowchart TD
  Role[agent key + task context] --> Base[domain 후보 + Norma base]
  Role --> Visibility[(agent MCP / Skill visibility)]
  Visibility --> Skills[visible Skill registry]
  Visibility --> DirectMCP[direct-visible enabled MCP]
  Skills --> GatedMCP[Skill metadata가 gate한 MCP]
  Host[orchestration · platform · retest · traffic · custom] --> Merge[base + extra merge]
  Base --> Merge
  DirectMCP --> Merge
  GatedMCP --> Merge
  Skills --> Merge
  Merge --> Catalog[(tools rows)]
  Catalog --> Resolve[enabled + binding + schema/default resolve]
  Resolve --> Runtime[coverage · capture · search · shell 조건]
  Runtime --> Deferred[deferred schema + unlock set]
  Deferred --> Guard[permission hook + ARTEX interceptor]
  Guard --> Execute[Go handler · process · HTTP · MCP]
  Execute --> Observe[activity · tool_usage · intercept trace]

  click Catalog "../contracts/db/agent-runtime.md#table-tools" "tools table"
  click Deferred "#deferred" "deferred와 Skill gate"
  click Guard "#intercept" "승인 경로"
  1. Mainagent/planner/worker/goals가 code-defined domain 후보를 만들고, 해당 run이 Norma base/optional tool을 선택한다.
  2. Server가 agent row와 visibility를 읽어 visible Skill을 registry 하나로 합치고 enabled MCP에 연결한다.
  3. Traffic capture 상태에 맞는 traffic handler, 고정 host handler, callable custom tool을 모든 agent 후보에 합친다.
  4. ToolResolve가 tools row가 있는 domain/host/custom 이름을 enabled와 agent binding으로 거르고 description/schema/default를 적용한다. DB 조회가 실패하면 code 후보를 그대로 돌려준다.
  5. DB에 binding됐지만 base에 없던 domain handler는 server registry에서 주입한다. Task-less agent가 task 전용 handler를 얻어도 필요한 exploration context가 없으면 호출 때 실패한다.
  6. Interactive shell과 Bash environment hint를 합성하고 finding workflow guidance, deferred name/unlock set, panic guard를 붙인다.
  7. Norma session이 WebFetch, TodoWrite, background, web search, deferred helper를 option에 따라 더한 뒤 hook을 거쳐 실행한다. server assembly agent assembly

Seed는 새 row의 기본값과 제한된 one-shot migration을 정할 뿐이다. 이미 편집한 binding/enabled를 매 부팅 code default로 되돌리지 않으므로 실제 DB와 fresh-DB 기본표가 다를 수 있다.

Capability 종류와 실행 경계

Capability 종류와 실행 경계 · 관계

이 대상을 사용하는 기능·모듈·계약 · 1개

전체 관계 1개 · 종류 선택·관계도
종류 실행 위치 주요 효과 성립 조건·한계
ARTEX domain Go process + PostgreSQL/file store graph, asset, scope, fact, finding, task state read/write handler context와 DB binding이 모두 필요; transaction 밖 side effect는 함께 rollback되지 않음
ARTEX host Server/Manager process cross-task 제어, platform 설정, retest, traffic read 일부는 capture 또는 conversation context가 필수
Norma file/shell agent workdir의 host filesystem/process file edit, command, long-running/background process workdir 경계와 child/remote side effect를 별도 확인
Norma Grep agent workdir + optional npm global prefix content search; PATH에 rg가 없으면 첫 호출이 global package 설치를 시도할 수 있음 read-only metadata와 실제 bootstrap 효과가 다름; 상세
WebFetch/web_search SDK HTTP/search provider 외부 요청과 search quota 소비 recording proxy와 search proxy 경로가 다를 수 있음
custom shell callable 아님 설치된 CLI hint를 Bash 설명에 추가 enabled + role binding만 반영
custom command Norma Bash handler DB template 기반 host command rendered command, workdir/env/timeout/output 제한을 검토
custom script configured Python process DB code 실행, JSON parameter를 stdin으로 전달 python_interpreter와 code/timeout/output 제한을 검토
custom http ARTEX HTTP client rendered external request non-empty schema 필수; redirect, response cap, target policy 확인
MCP stdio child 또는 remote HTTP/SSE server server가 선언한 tool effect ARTEX 밖의 실행·log·rollback은 MCP server 계약
Skill local SKILL.md를 읽는 Skill meta-tool model 지침 주입, metadata로 연결한 MCP unlock 지침은 deterministic authorization이 아님

Callable 고정 ARTEX 이름 51개와 Norma 이름 24개, custom kind의 상세 목록은 도구 전수표를 본다. custom tool execution

Grep metadata와 bootstrap 효과

Grep metadata와 bootstrap 효과 · 관계

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

이 대상을 사용하는 기능·모듈·계약 · 1개

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

Norma permission engine은 Grep의 ReadOnly=true와 allowReadOnly를 보고 self-allow할 수 있고 harness는 concurrent-safe로 schedule할 수 있다. 최초 resolver는 내부에서 npm install -g @vscode/ripgrep를 직접 실행하므로 이 child command는 Bash tool, ARTEX intercept, tool usage, traffic recorder의 독립 호출로 보이지 않는다. sync.Once가 동시 최초 호출의 resolution 자체는 직렬화하지만 network/global-prefix mutation을 read-only로 바꾸지는 않는다.

Default는 auto-install 허용이다. NORMA_RIPGREP_NO_INSTALL이 non-empty이면 기존 rg는 쓰되 설치하지 않고, NORMA_DISABLE_RIPGREP이 non-empty이면 기존 rg까지 건너뛰어 pure-Go 구현을 쓴다. npm 부재, 권한·network·registry·binary resolution 실패는 조용히 pure-Go로 fallback하므로 검색 성공만으로 global install이 없었다고 판단할 수 없다. 설정 값 운영 경계

Deferred schema와 Skill unlock

Deferred schema와 Skill unlock · 관계

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

  • 계약 사용 · tools · deferred unlock이 tool catalog schema를 소비 · core-edge-10

이 대상을 사용하는 기능·모듈·계약 · 1개

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

직접 visible이고 visible Skill metadata에 연결되지 않은 MCP tool은 session 시작부터 global deferred로 unlock된다. Visible Skill의 mcps가 지정한 server tool은 direct visibility와 관계없이 locked 상태로 시작하고 그 Skill을 호출해야 열린다. Resume은 transcript의 이전 Skill call을 replay해 unlock set을 복구한다. Custom command/script/http의 deferred 값은 Skill과 연결되지 않은 global deferred이므로 시작부터 호출 gate가 열려 있고 schema만 숨긴다. deferred assembly

Deferred는 prompt/schema 크기와 직접 호출 surface를 줄인다. Agent binding, target scope authorization, intercept, 원격 server의 자체 권한을 대신하지 않는다. SearchExtraTools/ExecuteExtraTool은 deferred 이름이 있을 때만 SDK가 추가한다.

DB catalog가 적용하는 값

DB catalog가 적용하는 값 · 관계

이 대상을 사용하는 기능·모듈·계약 · 1개

전체 관계 1개 · 종류 선택·관계도
row/value 적용 적용되지 않는 것
enabled, agents domain·seeded host·custom 후보의 다음 assembly 노출 이미 조립된 session을 원자적으로 회수하지 않음
description, schema model-facing 계약 교체 Go/MCP handler 의미를 교체하지 않음
schema property default model이 빠뜨린 scalar input의 호출 전 보정 handler가 지원하지 않는 field를 구현하지 않음
deferred callable custom schema의 초기 노출 경로 실행 권한이나 Skill gate로 바꾸지 않음
custom kind, exec, timeout/output custom handler 선택과 side effect shell kind를 callable로 만들지 않음

SDK generic tool, Skill meta-tool, MCP tool은 통상 대응 tools row가 없어 ToolResolve를 그대로 통과한다. Traffic/orchestration/platform/retest tool은 startup에서 system row를 seed하므로 catalog filter가 적용된다. 이름 충돌과 stale row를 포함한 최종 판단은 row와 현재 handler registry를 함께 봐야 한다. catalog wiring

Tool intercept·승인·실행 trace

Tool intercept·승인·실행 trace · 관계

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

이 대상을 사용하는 기능·모듈·계약 · 1개

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

ARTEX Guard는 Norma hook event의 tool name/input과 task/session review context를 Interceptor에 넘긴다. Enabled-tool set에 없는 이름은 이 정책면에서 그대로 진행된다. 대상 이름이면 ordered rule, optional LLM judge, user decision에 따라 allow, deny, ask를 결정하고, 승인된 호출만 handler로 간다. Exact settings와 기본값은 runtime settings에 있다. Guard Interceptor

intercept 대상 아님

대상 이름

allow rule 또는 default allow

deny rule

ask rule

rule miss + judge enabled

allow verdict 또는 fail action=allow

deny verdict 또는 deny timeout

ask verdict

사용자 approve

reject · cancel · expiry

target_check

executing

evaluate

denied

pending

judge

completed

failed

그림 크게 보기
Mermaid 원문
stateDiagram-v2
  [*] --> target_check
  target_check --> executing: intercept 대상 아님
  target_check --> evaluate: 대상 이름
  evaluate --> executing: allow rule 또는 default allow
  evaluate --> denied: deny rule
  evaluate --> pending: ask rule
  evaluate --> judge: rule miss + judge enabled
  judge --> executing: allow verdict 또는 fail action=allow
  judge --> denied: deny verdict 또는 deny timeout
  judge --> pending: ask verdict
  pending --> executing: 사용자 approve
  pending --> denied: reject · cancel · expiry
  executing --> completed
  executing --> failed

Trace는 tool-use id, input digest, rule/model/user decision, execution result를 연결한다. Concurrent candidate가 모호하면 임의 실행 result를 승인 row에 붙이지 않는다. Approval history가 있다는 사실만으로 MCP나 child process의 후속 side effect가 완료됐다고 볼 수 없다. execution trace

Optional LLM judge

Optional LLM judge · 관계

이 대상을 사용하는 기능·모듈·계약 · 1개

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

Judge는 rule miss 때만 고정 JSON verdict protocol로 별도 provider/profile을 호출한다. 기본값은 disabled이고 timeout 15초, failure action allow, ask timeout 300초, ask-timeout action deny다. Provider 오류, timeout, unparsable response는 configured failure action으로 간다. 그래서 high-impact command는 model judge의 가용성에 기대기보다 deterministic rule로 먼저 막아야 한다. judge implementation

기록면

기록면 · 관계

이 대상을 사용하는 기능·모듈·계약 · 1개

전체 관계 1개 · 종류 선택·관계도
기록면 포함 빠질 수 있는 것
activity tool use/result, text, usage, worker/session metadata process 밖에서 이어지는 side effect
intercept trace/history 판정 input digest, rule/model/user decision, execution correlation enabled-tool set 밖 capability
tool_usage tool key, agent/task/session usage insert 실패, 원격 MCP 내부 세부 호출
LLM records/usage model request/response/usage ensure table 실패, provider 내부 retry
traffic store recording proxy를 통과한 HTTP direct DNS/raw socket, MCP server-side request, tunnel/pass 경로

실패·불일치 조건

실패·불일치 조건 · 관계

이 대상을 사용하는 기능·모듈·계약 · 1개

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

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

전체로 돌아가기 · Markdown 원본

검색을 열면 색인을 읽습니다.

등록한 문서 본문에서 검색합니다.