@soddong/agentic-runtime 0.16.0

package/docs/usage.md

@@ -0,0 +1,774 @@
+# @soddong/agentic-runtime 사용 매뉴얼
+
+## 1. 목적
+
+본 문서는 사용자가 `@soddong/agentic-runtime`을 설치하고 `agentic` CLI 실행을 확인하는 절차를 설명합니다.
+
+운영환경 사용자는 구축 환경의 build, pack, publish 절차를 알 필요가 없습니다.
+
+## 2. 설치 전제
+
+| 항목 | 기준 |
+| --- | --- |
+| NPM Registry | 기본값: `https://registry.npmjs.org/` |
+| 인증 | publish 권한이 필요한 경우에만 `~/.npmrc`에 npm token 설정 |
+| package | `@soddong/agentic-runtime` |
+| CLI | `agentic` |
+
+토큰 실값은 문서, source, CI log에 기록하지 않습니다.
+
+```text
+//registry.npmjs.org/:_authToken=${NPM_TOKEN}
+```
+
+## 3. 설치
+
+registry 설정을 먼저 확인합니다.
+
+```bash
+npm config get registry
+```
+
+공식 registry를 기본값으로 사용할 경우:
+
+```bash
+npm config set registry https://registry.npmjs.org/ --location=user
+```
+
+```bash
+npm install @soddong/agentic-runtime@0.16.0
+```
+
+registry를 명시해야 하는 경우:
+
+```bash
+npm install @soddong/agentic-runtime@0.16.0 --registry=https://registry.npmjs.org/
+```
+
+Windows PowerShell:
+
+```powershell
+npm install @soddong/agentic-runtime@0.16.0 --registry=https://registry.npmjs.org/
+```
+
+## 4. 실행 확인
+
+```bash
+npx agentic --version
+npx agentic --help
+```
+
+Windows PowerShell:
+
+```powershell
+npx agentic --version
+npx agentic --help
+```
+
+기대 결과:
+
+```text
+@soddong/agentic-runtime 0.16.0
+```
+
+## 5. 현재 지원 명령
+
+```bash
+agentic help
+agentic version
+agentic init
+agentic setup
+agentic docs
+agentic config
+agentic run
+agentic execution list
+agentic execution latest
+agentic execution show
+agentic execution summary
+agentic hook record
+agentic db init
+agentic db status
+agentic adapter install
+agentic adapter status
+agentic agent register
+agentic agent context
+agentic module register
+agentic module list
+agentic bundle install
+agentic bundle apply
+agentic bundle list
+agentic bundle status
+agentic seed import
+agentic seed apply
+agentic seed status
+agentic project create
+agentic project status
+```
+
+## 6. 예정 명령
+
+```text
+agentic validate
+agentic render
+```
+
+## 7. 프로젝트 초기화
+
+사용자 프로젝트 루트에서 실행합니다.
+
+```bash
+npx agentic init
+```
+
+생성 결과:
+
+```text
+agentic.config.json
+.agentic/
+  AGENTS.md
+  README.md
+  bin/
+    agentic-hook.mjs
+  data/
+  logs/
+  modules/
+```
+
+현재 설정 상태를 확인합니다.
+
+```bash
+npx agentic config
+```
+
+설치된 패키지 문서 위치를 확인합니다.
+
+```bash
+npx agentic docs
+```
+
+Codex, Kiro, Claude Code adapter까지 한 번에 준비하려면 다음을 실행합니다.
+
+```bash
+npx agentic setup --adapter codex
+npx agentic setup --adapter kiro
+npx agentic setup --adapter claude-code
+```
+
+`adapter install`을 먼저 실행해도 됩니다. 프로젝트가 아직 초기화되지 않았으면 `adapter install`이 내부에서 `init`과 `db init`을 먼저 수행한 뒤 adapter 설치까지 진행합니다.
+
+```bash
+npx agentic adapter install kiro
+```
+
+`.agentic/AGENTS.md`는 @soddong/agentic-runtime managed block으로 관리됩니다.
+
+```md
+<!-- agentic-runtime:start version=0.16.0 -->
+...
+<!-- agentic-runtime:end -->
+```
+
+`init`, `setup`, `adapter install`은 이 block의 version을 확인합니다. 기존 block version이 현재 runtime보다 낮으면 사용자 작성 영역은 보존하고 managed block만 갱신합니다. 사용자 고유 지침은 managed block 밖에 작성합니다.
+
+Agent hook은 성능을 위해 `npx`를 매번 호출하지 않고 project-local wrapper를 사용합니다.
+
+```bash
+node .agentic/bin/agentic-hook.mjs --source kiro --event PromptSubmit
+```
+
+파일 생성만 검증하려면 다음을 실행합니다.
+
+```bash
+npx agentic setup --adapter codex --prepare-only
+```
+
+## 8. Runtime Execution 기록
+
+사용자 지시를 runtime execution으로 기록합니다.
+
+```bash
+npx agentic run "요구사항을 검토해 주세요."
+```
+
+Windows PowerShell:
+
+```powershell
+npx agentic run "요구사항을 검토해 주세요."
+```
+
+현재 `agentic run`은 router 또는 개별 Agent module 실행 전 단계의 공통 기록 기능입니다.
+
+저장되는 정보:
+
+| 정보 | 테이블 |
+| --- | --- |
+| 사용자 지시 | `agentic_user_requests` |
+| 실행 단위 | `agentic_execution_runs` |
+| 실행 로그 | `agentic_execution_logs` |
+| 실행 결과 | `agentic_execution_outputs` |
+
+`agentic init`은 `.agentic/AGENTS.md` 템플릿을 생성합니다.
+consumer 프로젝트의 루트 `AGENTS.md`에는 이 내용을 반영해, Agentic Platform 관련 지시가 먼저 `npx agentic run "<사용자 지시문>"`으로 기록되도록 운영 정책을 둡니다.
+
+## 9. Agent Routing API
+
+`@soddong/agentic-runtime`은 concrete domain package를 직접 의존하지 않습니다. 예를 들어 runtime이 `@soddong/agentic-domain-document`를 직접 import하지 않습니다.
+
+대신 agent package가 manifest를 등록하면 runtime은 등록된 manifest를 기준으로 route decision을 수행합니다.
+
+```ts
+import {
+  registerAgentManifest,
+  routeRegisteredAgents
+} from "@soddong/agentic-runtime";
+import { createAgentManifest } from "@soddong/agentic-capability-agent-client";
+
+const manifest = createAgentManifest({
+  agentId: "document-agent",
+  packageName: "agentic-agent-document",
+  packageVersion: "0.1.0",
+  moduleLayer: "application",
+  capabilities: [
+    {
+      capabilityId: "document.create",
+      description: "문서 초안을 생성합니다.",
+      keywords: ["문서", "초안", "작성"]
+    }
+  ]
+});
+
+registerAgentManifest(manifest);
+
+const decision = routeRegisteredAgents({
+  requestText: "요구사항 정의서 초안을 작성해줘"
+});
+
+console.log(decision.selectedAgentId);
+```
+
+1차 routing은 keyword/example 기반 rule scoring입니다. LLM router와 embedding router는 후속 확장 대상입니다.
+
+## 10. Runtime Execution 이력 조회
+
+저장된 사용자 지시, 실행 상태, 로그, 결과는 다음 명령으로 조회합니다.
+
+```bash
+npx agentic execution list --range today
+npx agentic execution latest
+npx agentic execution show <run-id>
+npx agentic execution summary --range 7d
+```
+
+Windows PowerShell:
+
+```powershell
+npx agentic execution list --range today
+npx agentic execution latest
+npx agentic execution show <run-id>
+npx agentic execution summary --range 7d
+```
+
+Agent나 자동화 도구가 사용하기 쉬운 JSON 출력도 지원합니다.
+
+```bash
+npx agentic execution list --range 7d --format json
+npx agentic execution summary --range today --format json
+npx agentic execution latest --range today --status succeeded --format json
+```
+
+이전 지시, 이전 결과, 마지막 완료 작업을 묻는 경우에는 현재 실행 중인 자기 run을 피하기 위해 `--status succeeded`를 우선 사용합니다.
+
+현재 실행 중인 작업을 묻는 경우에는 `--status running`, 실패 이력을 묻는 경우에는 `--status failed`를 사용합니다.
+
+주요 조회 옵션:
+
+```text
+--range 1h|6h|24h|today|yesterday|7d|30d|this-week|last-week|this-month|last-month
+--from YYYY-MM-DD
+--to YYYY-MM-DD
+--source codex|kiro|claude-code
+--status succeeded
+--limit 20
+--format text|json
+```
+
+Execution timestamp는 UTC 기준으로 저장합니다. SQLite `CURRENT_TIMESTAMP`로 저장된 timezone 없는 `DATETIME` 문자열도 UTC로 해석합니다.
+
+조회 range는 rolling range와 calendar range를 구분합니다.
+
+| range | 기준 |
+| --- | --- |
+| `1h`, `6h`, `24h` | 현재 시각 기준 rolling range |
+| `7d`, `30d` | 현재 시각 기준 rolling range |
+| `today`, `yesterday` | KST calendar day |
+| `this-week`, `last-week` | KST calendar week, 월요일 시작 |
+| `this-month`, `last-month` | KST calendar month |
+
+예를 들어 `today`가 `2026-06-26 KST`이면 SQL 비교 boundary는 `2026-06-25 15:00:00 UTC`부터 `2026-06-26 15:00:00 UTC`까지입니다.
+
+사용자가 이전 지시, 작업 현황, 최근 결과를 질문하는 경우 Agent는 execution 이력을 우선 조회한 뒤 답변해야 합니다.
+
+## 11. Codex Adapter
+
+Codex adapter는 전역 Codex plugin bridge를 통해 사용자 지시와 turn 결과를 execution DB에 기록합니다. 표준 selector는 `agentic-runtime-codex@agentic-runtime`이며, 실제 기록은 현재 작업 디렉터리에 `agentic.config.json`과 `.agentic/bin/agentic-hook.mjs`가 있는 프로젝트에서만 수행합니다.
+
+```bash
+npx agentic adapter install codex
+npx agentic adapter status codex
+```
+
+Windows PowerShell:
+
+```powershell
+npx agentic adapter install codex
+npx agentic adapter status codex
+```
+
+이미 설치된 Codex adapter 파일을 현재 `@soddong/agentic-runtime` 버전 기준으로 갱신하려면 `--force`를 사용합니다.
+
+```bash
+npx agentic adapter install codex --force
+codex plugin list
+```
+
+설치 시 생성되는 주요 파일:
+
+```text
+plugins/
+  agentic-runtime-codex/
+    .codex-plugin/
+      plugin.json
+    hooks/
+      hooks.json
+    skills/
+      agentic-runtime-usage/
+        SKILL.md
+.agents/
+  plugins/
+    marketplace.json
+```
+
+Codex adapter의 1차 기록 범위:
+
+| Codex hook | 저장 내용 |
+| --- | --- |
+| `UserPromptSubmit` | 사용자 prompt 원문, 실행 run 시작 |
+| `Stop` | turn 종료 결과 text 또는 payload JSON, 실행 run 종료 |
+
+Codex가 hook 신뢰 승인을 요구하면 사용자가 hook 내용을 확인하고 승인해야 합니다.
+
+Codex hook command는 프로젝트 로컬 wrapper인 `.agentic/bin/agentic-hook.mjs`가 있을 때만 기록을 수행합니다. wrapper가 없는 프로젝트에서는 성공 상태로 no-op 처리하므로, Codex plugin 등록이 남아 있어도 @soddong/agentic-runtime 미초기화 프로젝트의 turn이 hook 실패로 중단되지 않습니다.
+
+같은 `agentic-runtime-codex` plugin을 여러 marketplace에서 동시에 활성화하지 않습니다. 중복 등록이 있으면 hook이 중복 실행될 수 있으므로 `agentic-runtime-codex@agentic-runtime` 하나만 전역 bridge로 유지합니다.
+
+Codex CLI로 직접 설치 상태를 확인하거나 재시도할 때는 다음 명령을 사용합니다.
+
+```bash
+codex plugin marketplace list
+codex plugin list
+codex plugin add agentic-runtime-codex@agentic-runtime
+```
+
+## 12. Kiro Adapter
+
+Kiro adapter는 Kiro CLI/IDE에서 사용자 지시와 Agent turn 종료를 execution DB에 기록하기 위한 설정을 생성합니다.
+
+지원 범위:
+
+| 대상 | 생성/수정 파일 | 비고 |
+| --- | --- | --- |
+| Kiro CLI V3 Early Access | `.kiro/hooks/agentic-runtime.json` | standalone hook 파일, `UserPromptSubmit`/`Stop` trigger 사용 |
+| Kiro CLI V2 | `.kiro/agents/kiro_with_hooks.json` | agent config의 embedded `hooks` 필드 사용 |
+| Kiro IDE | `.kiro/hooks/*.kiro.hook` | IDE 호환용 보조 파일 |
+
+```bash
+npx agentic adapter install kiro
+npx agentic adapter status kiro
+```
+
+Windows PowerShell:
+
+```powershell
+npx agentic adapter install kiro
+npx agentic adapter status kiro
+```
+
+이미 생성된 Kiro adapter 파일을 현재 `@soddong/agentic-runtime` 버전 기준으로 갱신하려면 `--force`를 사용합니다.
+
+```bash
+npx agentic adapter install kiro --force
+```
+
+Kiro CLI V2에서 hook agent를 기본값으로 지정하려면 `--set-default`를 명시합니다. 이 옵션은 사용자 Kiro 설정을 변경할 수 있으므로 기본 설치에서는 실행하지 않습니다.
+
+```bash
+npx agentic adapter install kiro --set-default
+```
+
+`--set-default`는 내부적으로 `kiro-cli agent set-default kiro_with_hooks`를 실행합니다. `kiro` 명령이 아니라 `kiro-cli` 명령이어야 하며, agent 이름은 `kito_with_hooks`가 아니라 `kiro_with_hooks`입니다.
+
+직접 확인:
+
+```bash
+kiro-cli agent set-default kiro_with_hooks
+kiro-cli --agent kiro_with_hooks
+```
+
+설치 시 생성되는 주요 파일:
+
+```text
+.kiro/
+  agents/
+    kiro_with_hooks.json
+  hooks/
+    agentic-runtime.json
+    agentic-runtime-prompt-submit.kiro.hook
+    agentic-runtime-agent-stop.kiro.hook
+  steering/
+    agentic-runtime.md
+plugins/
+  agentic-runtime-kiro/
+    README.md
+    hooks/
+      kiro-hook-guide.md
+```
+
+등록되는 command:
+
+| 구분 | Event/Trigger | Command |
+| --- | --- | --- |
+| Kiro CLI V3 | `UserPromptSubmit` | `node .agentic/bin/agentic-hook.mjs --source kiro --event PromptSubmit` |
+| Kiro CLI V3 | `Stop` | `node .agentic/bin/agentic-hook.mjs --source kiro --event AgentStop` |
+| Kiro CLI V2 | `userPromptSubmit` | `node .agentic/bin/agentic-hook.mjs --source kiro --event PromptSubmit` |
+| Kiro CLI V2 | `stop` | `node .agentic/bin/agentic-hook.mjs --source kiro --event AgentStop` |
+| Kiro IDE | Prompt Submit | `node .agentic/bin/agentic-hook.mjs --source kiro --event PromptSubmit` |
+| Kiro IDE | Agent Stop | `node .agentic/bin/agentic-hook.mjs --source kiro --event AgentStop` |
+
+Kiro CLI V3는 현재 Early Access이며 `kiro-cli --v3`로 opt-in 하는 구조입니다. CLI V2는 기존 agent config embedded hook을 사용합니다. Kiro IDE에서 `.kiro/hooks/*.kiro.hook` 파일을 인식하지 못하면 Kiro UI에서 생성된 파일 내용을 기준으로 hook 등록 상태를 확인합니다.
+
+Kiro CLI V2에서 hook을 적용하려면 다음 중 하나로 실행합니다.
+
+```bash
+kiro-cli --agent kiro_with_hooks
+kiro-cli agent set-default kiro_with_hooks
+```
+
+상세 설명:
+
+```bash
+cat plugins/agentic-runtime-kiro/hooks/kiro-hook-guide.md
+```
+
+Kiro 기록 확인:
+
+```bash
+npx agentic adapter status kiro
+npx agentic execution latest --source kiro --format json
+npx agentic execution list --range today --source kiro
+```
+
+## 13. Claude Code Adapter
+
+Claude Code adapter는 `.claude/settings.json`에 command hook을 자동 병합해 사용자 지시와 turn 종료를 execution DB에 기록합니다.
+
+```bash
+npx agentic adapter install claude-code
+npx agentic adapter status claude-code
+```
+
+Windows PowerShell:
+
+```powershell
+npx agentic adapter install claude-code
+npx agentic adapter status claude-code
+```
+
+이미 생성된 Claude Code adapter 파일을 현재 `@soddong/agentic-runtime` 버전 기준으로 갱신하려면 `--force`를 사용합니다.
+
+```bash
+npx agentic adapter install claude-code --force
+```
+
+설치 시 생성 또는 수정되는 주요 파일:
+
+```text
+.claude/
+  settings.json
+  rules/
+    agentic-runtime.md
+plugins/
+  agentic-runtime-claude-code/
+    README.md
+```
+
+`.claude/settings.json`에 등록되는 hook:
+
+| Claude Code hook | Command |
+| --- | --- |
+| UserPromptSubmit | `node .agentic/bin/agentic-hook.mjs --source claude-code --event UserPromptSubmit` |
+| Stop | `node .agentic/bin/agentic-hook.mjs --source claude-code --event Stop` |
+
+Claude Code 기록 확인:
+
+```bash
+npx agentic execution latest --source claude-code --format json
+npx agentic execution list --range today --source claude-code
+```
+
+## 14. SQLite 초기화
+
+사용자 프로젝트 루트에서 실행합니다.
+
+```bash
+npx agentic db init
+npx agentic db status
+```
+
+생성되는 기본 DB 파일:
+
+```text
+.agentic/platform.sqlite
+```
+
+초기 생성 테이블:
+
+```text
+agentic_runtime_metadata
+agentic_schema_migrations
+agentic_project_modules
+agentic_user_requests
+agentic_execution_runs
+agentic_execution_logs
+agentic_execution_outputs
+```
+
+## 15. Module Registry
+
+실행 프로젝트에서 사용할 Agentic package는 명시적으로 등록합니다.
+
+```bash
+npx agentic module register sample-agent-package 0.0.1 application
+npx agentic module list
+```
+
+Windows PowerShell:
+
+```powershell
+npx agentic module register sample-agent-package 0.0.1 application
+npx agentic module list
+```
+
+layer 값은 다음 중 하나입니다.
+
+```text
+runtime
+domain
+capability
+application
+support
+```
+
+등록 정보는 `agentic_project_modules` 테이블에 저장됩니다.
+
+## 16. Project Bundle Registry
+
+methodology seed bundle provider package가 설치되어 있으면 runtime에 bundle 설치 상태를 등록할 수 있습니다.
+
+```bash
+npx agentic bundle install @soddong/agentic-methodology-ai-agent-sdlc --bundle ai-agent-sdlc-build-planning
+npx agentic bundle apply @soddong/agentic-methodology-ai-agent-sdlc --bundle ai-agent-sdlc-build-planning
+npx agentic bundle list
+npx agentic bundle status
+```
+
+Windows PowerShell:
+
+```powershell
+npx agentic bundle install @soddong/agentic-methodology-ai-agent-sdlc --bundle ai-agent-sdlc-build-planning
+npx agentic bundle apply @soddong/agentic-methodology-ai-agent-sdlc --bundle ai-agent-sdlc-build-planning
+npx agentic bundle list
+npx agentic bundle status
+```
+
+`bundle install`은 1차에서 다음까지만 수행합니다.
+
+```text
+- installed package의 bundle loader 호출
+- bundle validator 호출
+- agentic_project_modules 등록/갱신
+- agentic_project_bundles 등록/갱신
+```
+
+실제 methodology, artifact, document domain DB 반영은 `seed import`로 계획을 만든 뒤 `seed apply`에서 target package handler를 통해 수행합니다.
+
+`bundle apply`는 운영/consumer 사용성을 줄이기 위한 통합 명령입니다.
+
+```bash
+npx agentic bundle apply @soddong/agentic-methodology-ai-agent-sdlc --bundle ai-agent-sdlc-build-planning
+```
+
+package 설치까지 함께 수행하려면 다음 옵션을 사용합니다.
+
+```bash
+npx agentic bundle apply @soddong/agentic-methodology-ai-agent-sdlc \
+  --bundle ai-agent-sdlc-build-planning \
+  --install-required
+```
+
+이 명령은 다음을 순서대로 수행합니다.
+
+```text
+1. agentic project init/db init 보장
+2. --install-required 지정 시 bundle provider package npm install
+3. bundle install
+4. --install-required 지정 시 bundle manifest의 requires.packages npm install
+5. bundle manifest의 requires.packages 자동 module register
+6. seed import dry-run plan 생성
+7. seed apply 실행
+```
+
+기본 `bundle apply`는 npm package 자동 설치를 수행하지 않습니다. 필요한 package를 직접 설치한 뒤 적용하려면 다음 흐름을 사용합니다.
+
+```bash
+npm install \
+  @soddong/agentic-runtime \
+  @soddong/agentic-methodology-ai-agent-sdlc \
+  @soddong/agentic-domain-methodology \
+  @soddong/agentic-domain-artifact-standard \
+  @soddong/agentic-contract-validation \
+  @soddong/agentic-domain-artifact
+```
+
+required package 누락 또는 단순 version range 불일치를 seed 적용 전에 차단하려면 다음 옵션을 사용합니다.
+
+```bash
+npx agentic bundle apply @soddong/agentic-methodology-ai-agent-sdlc \
+  --bundle ai-agent-sdlc-build-planning \
+  --strict-required
+```
+
+## 17. Seed Import Plan
+
+installed bundle을 기준으로 domain package 반영 계획을 dry-run으로 생성합니다.
+
+```bash
+npx agentic seed import --bundle ai-agent-sdlc-build-planning
+npx agentic seed apply --bundle ai-agent-sdlc-build-planning
+npx agentic seed status
+```
+
+Windows PowerShell:
+
+```powershell
+npx agentic seed import --bundle ai-agent-sdlc-build-planning
+npx agentic seed apply --bundle ai-agent-sdlc-build-planning
+npx agentic seed status
+```
+
+`seed import`는 다음 정보를 생성합니다.
+
+```text
+- seed import run
+- target package별 import item
+- target package 준비 상태
+- blocked/warning 사유
+- bundle validation result snapshot
+```
+
+target package가 설치 또는 등록되지 않았으면 해당 item은 `blocked`로 표시합니다. `seed import` 단계는 dry-run이며 domain DB에는 쓰지 않습니다.
+
+`seed apply`는 생성된 import plan을 기준으로 target package의 `applyAgenticSeed` handler를 호출합니다.
+
+```bash
+npx agentic seed apply --run <seed-import-run-id>
+npx agentic seed apply --bundle ai-agent-sdlc-build-planning
+```
+
+target package가 준비되지 않았거나 handler가 없으면 item은 `blocked`로 남습니다. handler가 실패하면 item은 `failed`로 기록됩니다. 1차 구현은 global rollback을 수행하지 않고 item별 상태를 runtime DB에 기록합니다.
+
+## 18. Execution Project Lifecycle
+
+`seed apply`가 성공한 bundle은 execution project로 생성할 수 있습니다. 이 단계는 workflow engine 실행이 아니라, bundle의 stage/activity와 primary output artifact 기준을 runtime DB에 snapshot으로 등록하는 lifecycle scaffold입니다.
+
+```bash
+npx agentic project create \
+  --bundle ai-agent-sdlc-build-planning \
+  --code my-build-planning \
+  --name "My Build Planning Project"
+```
+
+상태 조회:
+
+```bash
+npx agentic project status --code my-build-planning
+npx agentic project status --code my-build-planning --format json
+```
+
+`project status`는 다음 정보를 보여줍니다.
+
+```text
+- project status
+- stage별 activity 완료 현황
+- 전체 activity 수
+- 예상 output artifact 수
+- 생성된 artifact instance 수
+```
+
+## 19. Agent module 실행 API
+
+Agent module 개발자는 `@soddong/agentic-runtime`이 제공하는 실행 래퍼를 사용할 수 있습니다.
+
+```ts
+import { runAgentRuntimeClient } from "@soddong/agentic-runtime";
+
+const agent = {
+  manifest: {
+    agentId: "sample-agent",
+    packageName: "sample-agent-package",
+    packageVersion: "0.1.0",
+    moduleLayer: "application",
+    capabilities: [
+      {
+        capabilityId: "sample.review",
+        description: "요구사항을 검토합니다.",
+        keywords: ["요구사항", "검토"]
+      }
+    ]
+  },
+  run(input, context) {
+    context.logger.info("Agent request received", {
+      requestText: input.requestText
+    });
+
+    return {
+      outputType: "json",
+      contentJson: {
+        ok: true
+      }
+    };
+  }
+};
+
+await runAgentRuntimeClient(agent, {
+  requestText: "요구사항을 검토해 주세요."
+});
+```
+
+실행 후 `@soddong/agentic-runtime`은 다음 정보를 SQLite에 기록합니다.
+
+| 정보 | 테이블 |
+| --- | --- |
+| 사용자 지시 | `agentic_user_requests` |
+| 실행 상태 | `agentic_execution_runs` |
+| 실행 로그 | `agentic_execution_logs` |
+| 실행 결과 | `agentic_execution_outputs` |
+
+## 19. 문제 확인
+
+| 증상 | 확인 |
+| --- | --- |
+| package를 찾을 수 없음 | 공식 npm registry publish 여부와 `npm config get registry` 결과 확인 |
+| 인증 실패 | 사용자 홈 `.npmrc`의 npm auth token 확인 |
+| 사설 registry 접근 시도 | `npm config get registry` 확인 |
+| `npx agentic` 실패 | `node_modules/.bin/agentic` 생성 여부 확인 |
+| Codex prompt가 기록되지 않음 | `npx agentic adapter status codex`와 Codex hook trust 상태 확인 |