@agent-native/core 0.76.5 → 0.76.6

package/corpus/core/docs/content/locales/ko-KR/harness-agents.md

@@ -0,0 +1,349 @@
+---
+title: "하네스 에이전트"
+description: "자체 루프, 샌드박스, 기본 도구 및 재개 가능한 SQL 지원 세션을 사용하여 Claude 코드, Codex, Pi 및 기타 전체 코딩 하네스를 Agent-Native 내부에 내장된 에이전트로 실행하세요."
+search: "하네스 에이전트 AgentHarness ai-sdk HarnessAgent Claude 코드 Codex Pi Cursor Mastra 임베디드 코딩 에이전트 해결AgentHarness startAgentHarnessRun 재개 가능한 세션 샌드박스 호스트 도구"
+---
+
+# 하네스 에이전트
+
+> **대상:** 전체 코딩 런타임을 연결하는 호스트 작성자(Claude 코드,
+> Codex, Pi)를 에이전트로 Agent-Native에 넣습니다. 앱을 구축하시나요? 시작
+> [Creating Templates](/docs/creating-templates).
+
+하네스 에이전트는 전체 에이전트 런타임입니다(Claude 코드, Codex, Pi 등).
+자체 루프, 작업 공간, 기본 파일 도구, 세션 상태, 압축을 소유
+승인 모델 및 샌드박스 동작. Agent-Native는 이를 통해
+**`AgentHarness`** `@agent-native/core/agent/harness`의 기판, 스트리밍
+이벤트를 일반 기록으로 변환하고 기본 세션을 유지하므로 스레드
+일시 중지 및 재개가 가능합니다.
+
+내장된 채팅 에이전트와 직접 채팅을 가져오는 것과는 다릅니다.
+런타임. 내장 에이전트와 `AgentEngine`는 단일 모델 왕복용입니다.
+`runAgentLoop` 아래. 하네스는 `AgentEngine` 제공자가 아닙니다. 하네스는 다음을 실행합니다.
+자체 루프가 엔드투엔드이므로 Agent-Native는 이를 단일이 아닌 세션으로 구동합니다
+모델 통화.
+
+```an-diagram title="A harness owns its loop; Agent-Native drives the session" summary="The AgentHarness substrate creates/resumes the native session, streams its events into the normal transcript, and persists resumeState in SQL between turns."
+{
+  "html": "<div class=\"diagram-harness\"><div class=\"diagram-box\" data-rough><strong>AgentHarness substrate</strong><small class=\"diagram-muted\">@agent-native/core/agent/harness</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><strong>Native harness loop</strong><small class=\"diagram-muted\">Claude Code · Codex · Pi — own tools, sandbox, compaction</small></div><div class=\"diagram-col\"><div class=\"diagram-pill accent\">events &rarr; transcript</div><div class=\"diagram-pill ok\">resumeState &rarr; SQL session</div></div></div>",
+  "css": ".diagram-harness{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-harness .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-harness .diagram-arrow{font-size:22px;line-height:1}.diagram-harness .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## 어떤 코딩 문서를 원하나요? {#which-doc}
+
+| 원하는 것은...                                                           | 사용                                         |
+| ------------------------------------------------------------------------ | -------------------------------------------- |
+| 자체 루프 + 도구를 사용하여 Claude 코드 / Codex / Pi **에이전트**로 실행 | **하네스 에이전트**(이 페이지)               |
+| Claude-Code/Codex 스타일 **코딩 작업 공간 UI** 렌더링                    | [Agent-Native Code UI](/docs/code-agents-ui) |
+| 에이전트의 **`run-code` 도구**를 실행하는 백엔드 교체                    | [Adapters](/docs/sandbox-adapters)           |
+| 상담원이 통화할 수 있도록 CLI 도구(`gh`, `ffmpeg`)를 래핑합니다.         | [Adapters](/docs/sandbox-adapters)           |
+
+인접한 표면: Agent-Native 채팅 뒤의 다른 곳에 구축한 에이전트 배치
+UI 및 [`AgentChatRuntime`](/docs/native-chat-ui#byo-agent-runtimes); 하자
+[External Agents](/docs/external-agents)를 통해 외부 MCP 호스트가 앱에 호출됩니다.
+스폰 배경/하위 에이전트는 [Custom Agents & Teams](/docs/agent-teams)로 실행됩니다.
+
+## 내장 하네스 {#built-in}
+
+`registerBuiltinAgentHarnesses()`는 AI SDK가 지원하는 3개의 어댑터를 등록합니다.
+`HarnessAgent`:
+
+| 이름                         | 런타임      | 샌드박스   | 승인       |
+| ---------------------------- | ----------- | ---------- | ---------- |
+| `ai-sdk-harness:claude-code` | Claude 코드 | 그렇습니다 | 그렇습니다 |
+| `ai-sdk-harness:codex`       | Codex       | 그렇습니다 | 아니요     |
+| `ai-sdk-harness:pi`          | 파이        | 아니요     | 그렇습니다 |
+
+런타임 패키지는 **선택적 피어 종속성**이며 느리게 로드되므로
+하네스를 전혀 사용하지 않는 앱은 비용을 지불하지 않습니다. 각 어댑터에는
+`installPackage` 힌트(예: `@ai-sdk/harness@canary
+@ai-sdk/harness-codex@canary`); `resolveAgentHarness`는 명확한 설치를 발생시킵니다.
+패키지가 누락된 경우 오류가 발생하고 `isAgentHarnessPackageInstalled(entry)`
+먼저 확인해 보세요.
+
+`registerBuiltinAgentHarnesses()`는 [ACP](#acp) 하니스도 등록합니다
+(`acp`, `acp:gemini`, `acp:claude-code`).
+
+## ACP 요원 {#acp}
+
+Agent-Native는 [ACP](https://agentclientprotocol.com)(에이전트 클라이언트) 역할을 할 수 있습니다.
+프로토콜) **클라이언트** 및 로컬 코딩 에이전트 구동 — Gemini CLI, Claude 코드,
+또는 ACP 호환 에이전트 — 동일한 기판을 통해. 에이전트는
+stdio를 통해 개행으로 구분된 JSON-RPC를 말하는 로컬 하위 프로세스입니다. ACP의 편집자
+←에이전트 모델이 바로 이 모양입니다.
+
+이 어댑터의 범위는 **로컬 코딩**입니다. 하위 프로세스는
+상위 환경이므로 에이전트는 이미 가지고 있는 로컬 CLI 로그인을 재사용합니다.
+(예: 사용자 홈 디렉토리의 `gemini` 또는 `claude` 인증). 그것은
+호스팅 또는 샌드박스 전송이며 채팅/A2A 전송이 아닙니다.
+[Agent Surfaces](/docs/agent-surfaces)를 참조하세요.
+
+| 이름              | 기본 명령                                      | 재개 가능\* |
+| ----------------- | ---------------------------------------------- | ----------- |
+| `acp`             | _(구성을 통해 `command`/`args` 공급)_          | 그렇습니다  |
+| `acp:gemini`      | `npx -y @google/gemini-cli --experimental-acp` | 그렇습니다  |
+| `acp:claude-code` | `npx -y @zed-industries/claude-code-acp`       | 그렇습니다  |
+
+\*에이전트가 `loadSession` 기능을 광고하고
+그렇지 않으면 새로운 세션으로 저하됩니다.
+
+```ts
+import {
+  registerBuiltinAgentHarnesses,
+  resolveAgentHarness,
+} from "@agent-native/core/agent/harness";
+
+registerBuiltinAgentHarnesses();
+
+// A built-in preset (command/args are overridable through the resolve config):
+const adapter = resolveAgentHarness("acp:gemini");
+
+// Or any ACP agent by command:
+const custom = resolveAgentHarness("acp", {
+  command: "gemini",
+  args: ["--experimental-acp"],
+});
+```
+
+프로토콜 전송(`@zed-industries/agent-client-protocol`)은 선택 사항입니다
+AI SDK와 마찬가지로 `installPackage` 힌트를 통해 지연 로드된 종속성
+하네스. 에이전트 바이너리 자체(`@google/gemini-cli`,
+`@zed-industries/claude-code-acp`, …)는 별도의 외부 CLI입니다. 사전 설정
+`npx`를 통해 실행하면 에이전트 ACP 때문에 명령/인수를 재정의할 수 있습니다.
+진입 플래그는 여전히 진화하고 있습니다.
+
+`permissionMode`는 도구 호출을 사용하여 ACP `session/request_permission`에 매핑됩니다.
+에이전트 보고서 종류: 읽기는 항상 실행되고 편집은 `allow-edits`에서 실행되며
+`allow-all`를 제외한 모든 위험한 메시지가 표시됩니다. 승인은 일반적인 현상으로 나타납니다
+`approval-request` 이벤트. 어댑터는 `fs/read_text_file` 및
+세션 작업 공간에 대한 `fs/write_text_file`(이스케이프 경로 거부
+it) 및 쓰기는 `file-change` 이벤트를 발생시킵니다. 터미널 메소드는 광고되지 않습니다.
+따라서 에이전트는 자체 셸을 사용합니다.
+
+## Codex 인증: 코드 UI 대 하네스 샌드박스 {#codex-auth}
+
+두 개의 Codex 표면이 있으며 서로 다르게 인증됩니다.
+
+- **Agent-Native 코드 / 데스크톱**은 사용자 컴퓨터에서 `codex exec`를 실행합니다. 만일
+  사용자가 `codex login`를 실행했습니다. 이 로컬 실행은 ChatGPT를 재사용합니다.
+  구독 또는 API 키 인증은 설치된 Codex CLI 보고서를 통해
+  `codex login status`.
+- **`ai-sdk-harness:codex`**는 Codex를 구동하는 `@ai-sdk/harness-codex`를 로드합니다.
+  `@openai/codex-sdk`를 통해 하네스 샌드박스 내부. 조용히 하지 않습니다
+  샌드박스가 원격일 수 있으므로 사용자의 데스크톱 `~/.codex` 로그인을 상속합니다.
+  또는 고립되어 있습니다. 신뢰할 수 있는/비공개 샌드박스의 경우 `codexCliAuth: true`를 선택하세요.
+  Agent-Native는 로컬 Codex CLI 인증 파일을 샌드박스에 복사합니다.
+  하네스가 시작됩니다. 호스팅 또는 공유 샌드박스의 경우 API-키/게이트웨이를 구성하세요.
+  대신 인증하세요.
+
+따라서 어떤 패키지가 Codex OAuth 경로를 전달하는지 묻는다면: 로컬 코딩용
+세션, `@agent-native/core`/데스크탑 플러스 설치 사용
+`@openai/codex` CLI 및 `codex login`. 샌드박스 `ai-sdk-harness:codex`의 경우
+해당 로그인을 샌드박스에 복사할 때 명시적인 `codexCliAuth` 옵트인을 사용하세요
+허용됩니다.
+
+```ts
+const adapter = resolveAgentHarness("ai-sdk-harness:codex", {
+  codexCliAuth: true,
+});
+```
+
+`codexCliAuth: true`는 `CODEX_HOME/auth.json` 또는 `~/.codex/auth.json`를 읽습니다. 에게
+다른 로컬 로그인을 가리키고 통과
+`{ codexCliAuth: { codexHome: "/path/to/.codex" } }` 또는
+`{ codexCliAuth: { authJsonPath: "/path/to/auth.json" } }`.
+
+## 등록 및 해결 {#register-resolve}
+
+```ts
+import {
+  registerBuiltinAgentHarnesses,
+  resolveAgentHarness,
+} from "@agent-native/core/agent/harness";
+
+registerBuiltinAgentHarnesses();
+const adapter = resolveAgentHarness("ai-sdk-harness:codex");
+```
+
+`resolveAgentHarness(name, config?)`는 `AgentHarnessAdapter`를 반환합니다.
+옵션 `config`는 AI SDK 어댑터용 어댑터 공장으로 전달됩니다.
+`AiSdkHarnessAdapterOptions`(`label`, `description`,
+`permissionMode`, `harnessOptions`, `agentOptions` 및 Codex 전용
+`codexCliAuth`). `listAgentHarnesses()`를 사용하여 등록된 내용을 열거하세요.
+선택기.
+
+## 턴 실행 {#run-a-turn}
+
+`startAgentHarnessRun`는 하네스 세션을 공유 실행 관리자에 연결합니다.
+수명주기. 기본 세션을 생성(또는 재사용)하고 유지하며
+각 하네스 이벤트를 기록 이벤트로 변환하고
+턴이 완료되면 재개 가능한 상태입니다.
+
+```ts
+import { startAgentHarnessRun } from "@agent-native/core/agent/harness";
+
+const run = startAgentHarnessRun({
+  runId,
+  threadId,
+  adapter,
+  input: { prompt },
+  createSession: {
+    sessionId,
+    resumeState, // opaque value from a previous turn, if resuming
+    instructions,
+    sandbox, // required for sandboxed harnesses — see Sandbox Adapters
+    permissionMode: "allow-reads",
+    tools, // a narrow, intentional set of host tools (see below)
+  },
+  ownerEmail,
+  orgId,
+});
+```
+
+`startAgentHarnessRun`는 실행 관리자에서 `ActiveRun`를 반환하므로 차례
+기존 실행 경로, 기록, 취소를 통해 표시
+다른 에이전트가 실행됩니다. `createSession` 대신 이미 생성된 `session`를 전달하세요.
+메모리에 보관 중인 세션을 계속하려면
+
+## 세션 및 재개 {#sessions}
+
+하네스는 수명이 긴 기본 세션 상태를 소유합니다. Agent-Native는 SQL에서 이를 유지합니다
+따라서 스레드는 차례, 프로세스 및 배포 전반에 걸쳐 생존할 수 있습니다. `resumeState`
+**불투명** — Agent-Native는 이를 저장하고 돌려주지만 결코 검사하거나
+해석합니다.
+
+```an-diagram title="Resume across turns, processes, and deploys" summary="Each turn detaches an opaque resumeState into SQL; the next turn feeds it back into createSession instead of replaying chat history."
+{
+  "html": "<div class=\"diagram-resume\"><div class=\"diagram-node\" data-rough>Turn N<br><small class=\"diagram-muted\">streamTurn</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>detach &rarr; resumeState<br><small class=\"diagram-muted\">opaque · SQL harness session</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\" data-rough>Turn N+1<br><small class=\"diagram-muted\">createSession.resumeState</small></div></div>",
+  "css": ".diagram-resume{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-resume .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+```ts
+import {
+  getLatestAgentHarnessSessionForThread,
+  listAgentHarnessSessions,
+} from "@agent-native/core/agent/harness";
+
+const last = await getLatestAgentHarnessSessionForThread(threadId);
+// Feed last?.resumeState into createSession.resumeState on the next turn.
+```
+
+상점에는 `saveAgentHarnessSession`, `updateAgentHarnessSession`도 노출됩니다.
+`getAgentHarnessSession`, `getAgentHarnessSessionByRunId`,
+`markAgentHarnessSessionStopped` 및 `ensureAgentHarnessSessionTables`.
+`startAgentHarnessRun`는 저장/업데이트/중지 경로를 호출합니다. 그들에게 다가가세요
+사용자 정의 호스트에서만 직접
+
+## 호스트 도구 및 권한 {#host-tools}
+
+하네스는 자체 기본 도구(읽기, 편집, 쓰기, 셸 등)를 제공하므로
+파일 편집을 호스트 도구로 다시 노출하지 **않습니다**. **좁은
+Agent-Native actions부터 `createSession.tools`까지의 의도적인 세트**
+하네스가 특정 앱 작업에 도달하고 `defineAction`를 유지하기를 원함
+인증, 요청 컨텍스트, 시간 초과, 잘림 및 읽기 전용 메타데이터는 다음과 같은 경우 그대로
+그렇습니다.
+
+`permissionMode`는 승인 없이 하네스가 수행할 수 있는 작업을 게이트합니다:
+
+| 모드          | 의미                                                    |
+| ------------- | ------------------------------------------------------- |
+| `allow-reads` | 기본값. 읽기 실행; 편집 및 위험한 actions 프롬프트      |
+| `allow-edits` | 읽기 및 편집이 실행됩니다. 기타 위험한 actions 프롬프트 |
+| `allow-all`   | 승인 게이팅 없음                                        |
+
+하네스가 승인을 위해 일시 중지되면 `approval-request` 이벤트가 발생하고
+세션은 보류 중인 승인이 기록된 `idle`로 표시되므로 UI는
+그것을 표면화하고 사용자의 결정에 따라 재개합니다. 참조
+승인 표면용 [Human Approval](/docs/human-approval).
+
+## 이벤트 {#events}
+
+하네스 세션은 `AgentHarnessEvent` 값을 스트리밍하며, 이는 Agent-Native
+다음을 사용하여 표준 `AgentChatEvent` 스트림으로 변환
+`agentHarnessEventToAgentChatEvents`. 이벤트 유니온은 `text-delta`를 다루고 있습니다.
+`thinking-delta`, `activity`, `tool-start`, `tool-done`(
+네이티브 위젯용 `mcpApp` 페이로드), `approval-request`, `file-change`,
+`compaction`, `usage`, `error` 및 `done`. 도구 결과는
+동일한 번역, 작업으로 선언된 기본 위젯은 여전히 렌더링됩니다.
+[Native Chat UI](/docs/native-chat-ui).
+
+## 백그라운드 실행 및 UI {#background-runs}
+
+하네스는 공유된 `BackgroundAgentRun` 형태로 프로젝트를 실행합니다.
+`createAgentHarnessBackgroundAgentController()`를 통해 사용할 수 있습니다
+기존 운행 경로는 `goalId=agent-harness`입니다. 이는 장기간 실행되는 Claude를 의미합니다
+코드 또는 Codex 세션이 동일한 백그라운드 실행 및 기록 표면에 나타납니다.
+`listAgentHarnessBackgroundRuns`를 사용하여 에이전트 팀 및 기타 어댑터로
+`listAgentHarnessBackgroundTranscriptEvents`, `getAgentHarnessBackgroundRun` 및
+사용자 정의 호스트에 `stopAgentHarnessBackgroundRun`를 사용할 수 있습니다.
+
+## 맞춤형 어댑터 {#custom-adapters}
+
+내장된 런타임이 아닌 런타임을 래핑하려면 다음을 구현하세요.
+`AgentHarnessAdapter`를 선택하여 등록하세요. 어댑터는 해당 기능을 선언하고
+세션을 생성합니다. 세션은 `streamTurn` 및 선택적 `continueTurn`를 노출합니다.
+`approve`, `detach`, `stop` 및 `destroy`.
+
+```ts
+import {
+  registerAgentHarness,
+  type AgentHarnessAdapter,
+} from "@agent-native/core/agent/harness";
+
+const myHarness: AgentHarnessAdapter = {
+  name: "acme:my-coder",
+  label: "Acme Coder",
+  description: "Runs the Acme coding agent.",
+  installPackage: "@acme/coder",
+  capabilities: {
+    sandbox: true,
+    resumable: true,
+    approvals: true,
+    hostTools: true,
+    fileEvents: true,
+  },
+  async createSession(opts) {
+    // Build your native session and adapt it to AgentHarnessSession.
+    return createAcmeSession(opts);
+  },
+};
+
+registerAgentHarness({
+  name: myHarness.name,
+  label: myHarness.label,
+  description: myHarness.description,
+  installPackage: myHarness.installPackage,
+  capabilities: myHarness.capabilities,
+  create: () => myHarness,
+});
+```
+
+`createSession`에서 동적 가져오기를 사용하여 런타임 패키지를 선택적으로 유지하고
+`installPackage` 힌트. 브리지 지원 코딩 하네스의 경우 실제
+에서 임의의 코딩 에이전트를 실행하는 대신 샌드박스/작업 공간 공급자
+호스트 프로세스 - [Sandbox Adapters](/docs/sandbox-adapters)를 참조하세요. AI SDK 어댑터
+(`createAiSdkHarnessAdapter`, `@ai-sdk/harness`의 `HarnessAgent` 지원)은
+공개 추상화가 아닌 이 계약의 구현 중 하나입니다.
+
+## 하지 마세요 {#donts}
+
+- Claude 코드, Codex, 커서, Mastra 또는 Pi를 `AgentEngine`로 추가하지 마세요. 그들은
+  자신의 루프를 소유합니다. `AgentEngine.stream()`에서 하나를 실행하면 루프가 두 번 실행됩니다.
+  세션 수명 주기 의미가 손실됩니다.
+- 매 턴마다 전체 Agent-Native 채팅 기록을 하네스에 재생하지 마세요. 이력서
+  대신 `resumeState`를 사용한 하네스 세션
+- `resumeState`를 `application_state`에 저장하지 마세요. 하네스에 속합니다
+  세션 SQL 테이블.
+- 기본적으로 모든 앱 작업을 모든 하네스 세션에 노출하지 마세요. 건네주세요
+  작고 의도적인 도구 세트
+
+## 관련 문서 {#related-docs}
+
+- [Native Chat UI](/docs/native-chat-ui) — `AgentChatRuntime`와 UI 채팅 뒤에 자신의 에이전트를 배치하세요.
+- [Agent Surfaces](/docs/agent-surfaces) — 헤드리스, 채팅, 사이드카 또는 전체 앱을 선택하세요.
+- [Agent-Native Code UI](/docs/code-agents-ui) — 재사용 가능한 코딩 작업 공간
+- [Custom Agents & Teams](/docs/agent-teams) — 백그라운드 실행 및 하위 에이전트 위임.
+- [Sandbox Adapters](/docs/sandbox-adapters) — 코딩 하네스를 위한 플러그형 실행 백엔드.
+- [Human Approval](/docs/human-approval) — 승인 표면 하니스 실행에 사용됩니다.

package/corpus/core/docs/content/locales/ko-KR/human-approval.md

@@ -0,0 +1,88 @@
+---
+title: "Human-In-The-Loop 승인"
+description: "결과가 높은 작업이 실행되기 전에 에이전트를 일시 중지합니다. defineAction의 needApproval 게이트는 승인_필요 이벤트를 내보내고 사람이 승인한 다음에만 도구가 실행됩니다."
+---
+
+# Human-In-The-Loop 승인
+
+대부분의 actions는 그냥 실행되어야 합니다. 이메일 보내기, 카드 청구, 계정 삭제 등 몇 가지 작업은 외부로 노출되어 취소하기 어렵고 에이전트가 자동으로 수행하는 것을 원하지 않습니다. 이를 위해 `defineAction`에는 옵트인 **승인 게이트**가 있습니다. 에이전트가 작업을 호출하려고 하면 루프가 일시 중지되고 인간에게 승인/거부 어포던스가 표시되며 인간이 특정 호출을 승인한 후에 _만_ 작업이 실행됩니다.
+
+> [!WARNING]
+> 승인을 거의 받지 마십시오. 모든 게이트 작업은 에이전트 루프의 강제 중지입니다. 이는 실행을 중단하고 사람의 왕복을 요구합니다. 실제로 결과가 높고 실행 취소가 어렵고 외부를 향한 작업에만 `needsApproval`를 사용하십시오. 읽기 또는 일상적인 쓰기를 제어하고 있다면 잘못 알고 있는 것입니다. 기본값은 **해제**이며 거의 모든 작업에서 이를 해제해야 합니다.
+
+## `needsApproval` 게이트 {#needs-approval}
+
+`defineAction`에 `needsApproval`를 설정합니다. 부울 또는 조건자를 허용합니다:
+
+```an-annotated-code title="Gating the one consequential action"
+{
+  "filename": "actions/send-email.ts",
+  "language": "ts",
+  "code": "export default defineAction({\n  description: \"Send an email via Gmail.\",\n  schema: z.object({\n    to: z.string(),\n    subject: z.string(),\n    body: z.string(),\n  }),\n  // Sending is outward-facing and hard to undo, so the agent can never send\n  // without a human approving the specific call. Drafting/queueing is\n  // unaffected — only the real send is gated.\n  needsApproval: true,\n  run: async (args) => {\n    /* ...actually send... */\n  },\n});",
+  "annotations": [
+    { "lines": "10", "label": "The whole gate", "note": "One flag. With it truthy and the call unapproved, the loop stops before `run` — the model never reaches the side effect on its own." },
+    { "lines": "11-13", "label": "run() is untouched", "note": "The handler stays the same. Approval is enforced by the loop around it, not by anything inside `run`." }
+  ]
+}
+```
+
+- **`needsApproval: true`** — 항상 승인이 필요합니다.
+- **`needsApproval: (args, ctx) => boolean | Promise<boolean>`** — 조건자가 true를 반환하는 경우에만 승인이 필요합니다. 조건부 게이트(예: 외부 수신자에게만 해당되거나 달러 기준액 이상인 경우에만:
+
+  ``ts
+  needsApproval: (args) => !args.to.endsWith("@your-company.com"),
+
+  ```
+
+  술어를 순수하고 빠르게 유지하세요. **실패 종료**: 조건자가 발생하면 프레임워크는 결과가 높은 작업을 자동으로 실행하는 대신 이를 "승인 필요"로 처리합니다.
+  ```
+
+`needsApproval`가 생략되면 동작은 바이트 단위로 변경되지 않습니다. 즉, 공통 경로에 추가 비용이 없습니다.
+
+이는 레거시 `parameters` 스타일 actions 및 스키마 기반 actions와 인앱 에이전트, 하위 에이전트, A2A 및 MCP 호출자(모든 에이전트 표면이 동일한 루프를 통해 라우팅됨)에 대해 동일하게 작동합니다.
+
+## 루프가 일시 중지되는 방법 {#loop}
+
+에이전트가 제한 작업을 호출하고 이 특정 호출이 아직 승인되지 않은 **경우** 루프는 `run()`를 실행하지 **않습니다**. 대신:
+
+1. 게이트를 해결합니다. 술어의 경우 `needsApproval(input, ctx)`를 호출합니다. 던지기는 "승인해야 함"(실패 시 닫힘)으로 처리됩니다.
+2. `tool_start` 이벤트를 내보낸 후(UI가 호출을 표시함) 바로 **`approval_required`** 이벤트를 내보낸 다음 턴을 중지합니다. 해당 작업의 부작용은 절대 발생하지 않습니다.
+
+`approval_required` 이벤트는 클라이언트가 어포던스를 렌더링하는 데 필요한 모든 것을 전달합니다.
+
+| 필드          | 유형     | 참고                                                                           |
+| ------------- | -------- | ------------------------------------------------------------------------------ |
+| `tool`        | `string` | 에이전트가 호출을 시도한 작업 이름입니다.                                      |
+| `input`       | 객체     | 에이전트가 전달한 인수입니다.                                                  |
+| `approvalKey` | `string` | **안정적인 키** 클라이언트는 *이 정확한 호출*을 승인하기 위해 다시 응답합니다. |
+| `toolCallId`  | `string` | 사용 가능한 경우 모델 측 도구 호출 ID입니다.                                   |
+
+`approvalKey`는 도구 이름과 해당 입력에서 결정적으로 파생되므로 동일한 논리적 호출은 항상 동일한 키를 생성합니다. 모델은 이를 보거나 설정하지 않습니다. 이는 순전히 프레임워크와 인간의 승인 어포던스 간의 핸드셰이크입니다.
+
+일시 중지된 도구는 모델에 회전이 일시 중지되었으며 재시도하지 않음을 알리는 결과를 반환하므로 모델이 회전하지 않습니다.
+
+## 인간이 승인하는 방법 {#approve}
+
+`approval_required`에서 채팅 UI는 일시 중지된 도구 호출에 대해 **승인/거부** 어포던스를 렌더링합니다. 이는 `AssistantChat`에서 자동으로 연결되므로 템플릿별로 빌드하지 않습니다.
+
+- **승인**은 `approvedToolCalls: [approvalKey]`에 통화 키를 포함하는 차례(일반적인 연속 메시지)를 다시 발행합니다. 재발급된 차례에서 게이트는 승인된 세트의 키를 확인하고 해당 특정 호출이 정상적으로 실행되도록 합니다.
+- **거부**는 어포던스를 로컬에서 무시합니다. 아무것도 재발행되지 않으므로 작업이 실행되지 않습니다.
+
+`approvedToolCalls`는 채팅 요청(`AgentChatRequest.approvedToolCalls`)의 필드입니다. 존재하지 않는 키는 일시 중지된 상태로 유지됩니다. 한 호출을 승인해도 다른 호출은 무조건 승인되지 않습니다. 키에 콘텐츠 주소가 지정되어 있으므로 승인을 통해 *해당 인수를 사용한 호출*이 승인됩니다. 나중에 모델이 다른 전송을 제안하면 이는 새로운 키와 새로운 승인이 됩니다.
+
+## 엔드 투 엔드 {#flow}
+
+```an-diagram title="The approval interrupt" summary="A gated call pauses the turn before run() fires. Approval re-issues the turn carrying the call's key; only then does the side effect happen."
+{
+  "html": "<div class=\"diagram-approve\"><div class=\"diagram-box\" data-rough>Agent calls send-email</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-panel warn\" data-rough><strong>Gate truthy, call not yet approved</strong><small class=\"diagram-muted\">loop emits tool_start + approval_required { tool, input, approvalKey }</small><span class=\"diagram-pill warn\">turn pauses &mdash; run() did NOT execute</span></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box\" data-rough>Human clicks Approve in chat<br><small class=\"diagram-muted\">client re-issues the turn with approvedToolCalls: [approvalKey]</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-panel ok\" data-rough><span class=\"diagram-pill ok\">Gate sees the key &rarr; run() executes &rarr; email sends</span></div></div>",
+  "css": ".diagram-approve{display:flex;flex-direction:column;align-items:center;gap:8px}.diagram-approve .diagram-panel{display:flex;flex-direction:column;gap:6px;align-items:center;padding:12px 16px;text-align:center}.diagram-approve .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+프레임워크에서 이 게이트를 정식으로(의도적으로 드물게) 사용하는 것은 메일 템플릿의 `send-email` 작업으로, `needsApproval: true`를 설정하여 에이전트가 자유롭게 초안을 작성하고 대기열에 추가할 수 있지만 사람이 특정 전송을 승인하지 않으면 실제로 메시지를 보낼 수는 없습니다.
+
+## 관련
+
+- [**Actions**](/docs/actions#needs-approval) — 반환 값 검증을 위한 `outputSchema`를 포함한 전체 `defineAction` 표면.
+- [**Security**](/docs/security) — 승인 게이트에 도달하는 시기와 모델에서 작업을 숨기는 시기.
+- [**Mail template**](/docs/template-mail) — `send-email`는 참고 예시입니다.

package/corpus/core/docs/content/locales/ko-KR/internationalization.md

@@ -1,15 +1,18 @@
 ---
 title: "국제화"
-description: "공유 locale 카탈로그, 언어 선택기, 브라우저 언어 fallback, locale-aware docs 콘텐츠로 Agent Native 앱을 현지화합니다."
+description: "공유 로케일 카탈로그, 언어 선택기, 브라우저 언어 대체 및 로케일 인식 문서 콘텐츠를 사용하여 Agent Native 앱을 현지화합니다."
 ---
 
 # 국제화
 
-Agent Native 앱은 공유 `@agent-native/core/client/i18n` 런타임으로 framework 및 template UI를 현지화할 수 있습니다. framework는 사용자의 언어 선택을 SQL settings에 저장하고 actions로 노출하며, 앱에 번역되지 않은 문자열이 있으면 English로 fallback합니다.
+Agent Native 앱은 공유를 통해 프레임워크 및 템플릿 UI를 현지화할 수 있습니다.
+`@agent-native/core/client/i18n` 런타임. 프레임워크는 사용자의
+SQL 설정에서 언어 선택, actions로 노출 및 대체
+앱이 아직 문자열을 번역하지 않은 경우 영어입니다.
 
-## 런타임 {#runtime}
+## 런타임
 
-`AppProviders`를 통해 provider를 사용합니다.
+`AppProviders`를 통해 공급자 사용:
 
 ```tsx
 import { AppProviders, getLocaleInitScript } from "@agent-native/core/client";
@@ -27,11 +30,14 @@ const LOCALE_INIT_SCRIPT = getLocaleInitScript();
 </AppProviders>;
 ```
 
-`getLocaleInitScript()`는 React hydration 전에 초기 `lang`, `dir`, `window.__AGENT_NATIVE_LOCALE__`를 설정합니다. 공개 SSR route는 `@agent-native/core/server`에서 `resolveLocaleFromRequest()`를 호출하고 해결된 locale/catalog를 script에 전달해 hydration mismatch를 피할 수 있습니다.
+`getLocaleInitScript()`는 초기 `lang`, `dir` 및
+React가 수화되기 전의 `window.__AGENT_NATIVE_LOCALE__`. 공개 SSR 경로는
+`@agent-native/core/server`에서 `resolveLocaleFromRequest()`를 호출하고
+수화 불일치를 방지하기 위해 해당 스크립트에 로케일/카탈로그를 해결했습니다.
 
-## 카탈로그 {#catalogs}
+## 카탈로그
 
-현지화된 각 template은 `app/i18n/` 아래에 카탈로그를 둡니다.
+각 현지화된 템플릿은 `app/i18n/` 아래에 카탈로그를 보관합니다:
 
 ```ts
 // app/i18n/index.ts
@@ -52,44 +58,76 @@ export const i18nCatalog = {
 } satisfies AgentNativeI18nCatalog;
 ```
 
-항상 `en-US`를 bundle에 포함하세요. English가 아닌 카탈로그는 dynamic import로 불러와 사용자가 활성 locale만 다운로드하게 합니다. 지원 locale codes는 `en-US`, `zh-CN`, `es-ES`, `fr-FR`, `de-DE`, `ja-JP`, `ko-KR`, `pt-BR`, `hi-IN`, `ar-SA`입니다.
+항상 `en-US`를 번들로 묶으세요. 영어가 아닌 카탈로그를 동적 가져오기하여 사용자만
+활성 로캘을 다운로드합니다. 지원되는 로캘 코드는 `en-US`, `zh-CN`,
+`es-ES`, `fr-FR`, `de-DE`, `ja-JP`, `ko-KR`, `pt-BR`, `hi-IN` 및 `ar-SA`.
 
-## UI {#ui}
+## UI
 
-인터페이스 문자열에는 `useT()`를 사용하고 settings에는 `<LanguagePicker />`를 둡니다.
+인터페이스 문자열에 `useT()`를 사용하고 앱 문자열에 `<LanguagePicker />`를 넣습니다.
+`/settings` 페이지. 사이드바 앱은 앱 사이드바에 **설정**을 노출해야 합니다.
+헤더 언어 아이콘은 바로가기일 뿐입니다.
 
 ```tsx
-import { LanguagePicker, useT } from "@agent-native/core/client";
+import {
+  LanguagePicker,
+  openAgentSettings,
+  useT,
+} from "@agent-native/core/client";
 
-function SettingsLanguageCard() {
+function SettingsPage() {
   const t = useT();
   return (
     <>
       <h2>{t("settings.languageTitle")}</h2>
       <LanguagePicker label={t("settings.languageLabel")} />
+
+      <h2>{t("settings.agentTitle")}</h2>
+      <p>{t("settings.agentDescription")}</p>
+      <button type="button" onClick={() => openAgentSettings()}>
+        {t("settings.openAgentSettings")}
+      </button>
     </>
   );
 }
 ```
 
-날짜, 숫자, 상대 시간, 목록에는 `useFormatters()`를 사용하세요. locale에 민감한 날짜나 숫자 formatting을 번역 문자열 안에 넣지 마세요.
+"에이전트 설정" 컨트롤은 오른쪽 에이전트 사이드바의 설정 탭을 열어야 합니다.
+모델, API 키, 자동화, 음성 및 기타 프레임워크 수준 제어의 경우
+앱은 자체 설정 페이지에서 중요한 프레임워크 설정을 복제할 수 있습니다.
+설정이 앱의 중심이지만 사이드바 설정 탭은 그대로 유지되는 경우
+진실의 근원.
+
+날짜, 숫자, 상대 시간 및 목록에는 `useFormatters()`를 사용하세요. 넣지 마세요
+번역 문자열 내 로케일 구분 날짜/숫자 형식.
 
-## Docs 사이트 콘텐츠 {#docs-site-content}
+## 문서 사이트 콘텐츠 {#docs-site-content}
 
-공개 docs 페이지는 같은 core provider를 사용하지만 `persistPreference={false}`로 설정해 익명 docs 트래픽이 SQL settings actions가 아니라 localStorage와 브라우저 언어를 사용하게 합니다. English 원본은 `packages/core/docs/content/*.md`에 남습니다. 현지화된 페이지 override는 `packages/core/docs/content/locales/<locale>/<slug>.md`에 둡니다.
+공개 문서 페이지는 동일한 핵심 공급자를 사용하지만
+`persistPreference={false}`이므로 익명 문서 트래픽은 localStorage를 사용하며
+SQL 설정 actions 대신 브라우저 언어. 영어 출처는
+`packages/core/docs/content/*.md`. 현지화된 페이지는
+`packages/core/docs/content/locales/<locale>/<slug>.md`.
 
-앱 카탈로그와 같은 BCP-47 locale codes를 사용하세요. English 원본과 같은 slug를 유지하고, 번역된 heading에는 `{#anchor}`로 안정적인 anchor를 보존하며, routes, action names, protocol fields, env vars, provider names는 번역하지 마세요. 특정 locale에 번역 Markdown이 없으면 그 페이지는 English로 fallback하고 navigation과 chrome은 계속 현지화됩니다.
+앱 카탈로그와 동일한 BCP-47 로캘 코드를 사용합니다.
+영어 소스, 번역된 제목에 `{#anchor}`를 사용하여 안정적인 앵커 유지,
+경로, 작업 이름, 프로토콜 필드, 환경 변수 및 공급자 이름은 그대로 둡니다
+번역되지 않았습니다. 로케일에 페이지에 대해 번역된 Markdown가 없으면 문서 사이트
+탐색 및 크롬을 현지화하는 동안 해당 페이지는 영어로 대체됩니다.
 
-## Actions 및 지속성 {#actions-and-persistence}
+## Actions와 지속성
 
-모든 앱은 다음을 상속합니다.
+모든 앱은 다음을 상속합니다:
 
 - `get-localization-preference` — 현재 사용자의 `{ locale }` 읽기
-- `set-localization-preference` — `"system"` 또는 지원 locale 설정
+- `set-localization-preference` — `"system"` 또는 지원되는 로캘 설정
 
-지속 값은 user-scoped SQL settings의 `localization`에 저장됩니다. `localStorage`는 pre-hydration과 익명 fallback에만 사용됩니다. 활성 locale은 ambient context로 application state에 반영되어 agents가 현재 UI 언어를 볼 수 있습니다.
+지속성 값은 `localization` 아래의 사용자 범위 SQL 설정에 있습니다.
+`localStorage`는 사전 수화 및 익명 대체에만 사용됩니다. 활동적인
+로케일은 에이전트가 볼 수 있도록 주변 컨텍스트로 애플리케이션 상태에 미러링됩니다.
+현재 인터페이스 언어
 
-## Guard {#guard}
+## 가드
 
 실행:
 
@@ -97,6 +135,11 @@ function SettingsLanguageCard() {
 pnpm guard:i18n-catalogs
 ```
 
-guard는 지원 locale filename, key parity, placeholder parity, stale keys, 그리고 `Intl.PluralRules`를 통한 CLDR plural categories를 검증합니다. 구조만 확인하며 번역 품질은 확인하지 않습니다. 노출도가 높은 문자열은 사람의 검토가 필요합니다.
+경비원은 지원되는 로케일 파일 이름, 키 패리티, 자리 표시자 패리티를 확인합니다.
+부실 키 및 `Intl.PluralRules`를 통한 CLDR 복수 카테고리. 확인합니다
+번역 품질이 아닌 구조; 가시성이 높은 문자열에는 여전히 사람이 필요합니다
+검토.
 
-action names, routes, enum values, app-state keys, database values, protocol fields, env var names, provider names 같은 안정적인 식별자는 번역하지 마세요.
+작업 이름, 경로, 열거형 값과 같은 안정적인 식별자를 번역하지 마세요.
+앱 상태 키, 데이터베이스 값, 프로토콜 필드, 환경 변수 이름 또는 공급자
+이름.