@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/ko-KR/dispatch.md

@@ -0,0 +1,146 @@
+---
+title: "파견"
+description: "작업 공간 제어 플레인: 비밀 저장소, 통합 허브, 앱 간 위임, Slack용 중앙 받은 편지함, 이메일, Telegram, WhatsApp."
+---
+
+# 파견
+
+Dispatch는 작업 공간의 다른 모든 앱 앞에 위치하며 비밀, 통합, 메시징 및 앱 간 위임을 처리하는 중앙 앱입니다. 이는 **작업 공간 제어 플레인**입니다. 즉, 팀이 대화하는 단일 에이전트, 단일 위치 자격 증명, 주어진 요청을 처리해야 하는 전문 앱을 결정하는 단일 라우터입니다.
+
+> **템플릿 디스패치와 패키지 `@agent-native/dispatch` 비교.** 이 페이지에서는 디스패치 앱/템플릿 개념, 즉 기능과 원하는 이유를 다룹니다. `@agent-native/dispatch` npm 패키지는 디스패치 템플릿의 서버 로직(Vault, 통합, 대상, 예약된 작업 및 앱 간 위임)을 이를 확장하는 작업 공간용 드롭인 패키지로 번들로 제공하는 별도로 게시된 런타임입니다. 스캐폴드 앱 자체(경로, 화면, 상담사 안내)에 대해서는 [Dispatch template](/docs/template-dispatch)를 참조하세요.
+
+Dispatch가 없으면 다중 앱 작업 공간의 모든 앱은 자체 Slack 봇, 자체 비밀 저장소, 자체 예약 작업, 작업 공간 지침의 자체 복사본 등 동일한 배관을 다시 구현하게 됩니다. 하나의 API 키를 순환하면 10개의 재배포가 이루어집니다. 새 정책을 추가하면 10번의 복사-붙여넣기가 수행됩니다. Dispatch는 이 모든 것을 하나의 앱에 중앙 집중화하므로 다른 앱은 해당 도메인에 계속 집중할 수 있습니다.
+
+```an-diagram title="Dispatch as the workspace control plane" summary="One inbox, one vault, one MCP gateway, and shared resources sit in front of the domain apps, which Dispatch reaches as A2A peers."
+{
+  "html": "<div class=\"dsp-hub\"><div class=\"diagram-node\">Users &amp; external agents<br><small class=\"diagram-muted\">Slack · email · Telegram · WhatsApp · MCP</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-panel dsp-control\" data-rough><span class=\"diagram-pill accent\">Dispatch &mdash; control plane</span><div class=\"dsp-caps\"><span class=\"diagram-pill\">Central inbox</span><span class=\"diagram-pill\">Secret vault</span><span class=\"diagram-pill\">Cross-app delegation</span><span class=\"diagram-pill\">MCP gateway</span><span class=\"diagram-pill\">Workspace resources</span></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"dsp-peers\"><div class=\"diagram-box\" data-rough>Mail</div><div class=\"diagram-box\" data-rough>Calendar</div><div class=\"diagram-box\" data-rough>Analytics</div></div><small class=\"diagram-muted\">domain apps &mdash; A2A peers</small></div>",
+  "css": ".dsp-hub{display:flex;flex-direction:column;align-items:center;gap:10px}.dsp-hub .dsp-control{display:flex;flex-direction:column;align-items:center;gap:10px;width:100%}.dsp-hub .dsp-caps{display:flex;gap:8px;flex-wrap:wrap;justify-content:center}.dsp-hub .dsp-peers{display:flex;gap:10px;flex-wrap:wrap;justify-content:center}"
+}
+```
+
+## 배송을 원하실 때 {#when}
+
+다음 중 하나라도 해당되면 파견을 요청하세요:
+
+- 메일, 캘린더, 분석, 콘텐츠 등 [multi-app workspace](/docs/multi-app-workspace)를 실행 중이며 앱당 하나의 Slack 봇을 원하지 않습니다.
+- **"에이전트"를 위한 하나의 받은편지함**을 원하면 사용자가 단일 봇에 DM을 보내고 적절한 전문 앱이 뒤에서 작업을 선택할 수 있습니다.
+- 여러 앱에 필요한 **작업 공간 전체 비밀**(스트라이프 키, OpenAI 키, 타사 API 토큰)이 있고 모든 `.env`에 값을 복사하는 대신 하나의 저장소를 원합니다.
+- 중요한 변경 사항(저장된 대상, 정책 편집) 앞에 **런타임 승인 흐름**을 두어 관리자가 아닌 사람이 요청할 수 있고 관리자가 코드 배포 없이 승인할 수 있기를 원합니다.
+- 작업 공간의 앱이 상속하는 **공유 skills, 지침, 에이전트 프로필 및 MCP 서버**를 원합니다. 한 번 변경하면 모두에 도달할 수 있습니다.
+
+단일 템플릿을 독립형으로 실행하는 경우 Dispatch가 필요하지 않습니다. 각 템플릿은 자체 메시징 통합을 직접 연결할 수 있습니다. 독립 실행형 설정은 [Messaging](/docs/messaging)를 참조하세요.
+
+## 디스패치가 하는 일 {#what-it-does}
+
+7가지 기능은 모두 다른 앱에서 사용하는 것과 동일한 작업 공간 데이터베이스 위에 위치합니다.
+
+| 능력                    | 귀하에게 제공되는 것                                                                               | 설정                                                       |
+| ----------------------- | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
+| **중앙 받은편지함**     | Slack, 이메일, Telegram, WhatsApp 모두 공유 메모리 + 도구를 사용하여 하나의 에이전트에 연결됩니다. | **설정 → 메시지** ([Messaging](/docs/messaging))           |
+| **비밀 금고**           | 각 자격 증명을 한 번 저장합니다. 모든 앱에서 한 곳으로 회전                                        | **Vault** + 액세스 모드(모든 앱 또는 수동)                 |
+| **교차 앱 위임**        | A2A를 통해 올바른 전문가 앱으로 요청을 라우팅하고 스레드 내에서 응답                               | 자동([A2A](/docs/a2a-protocol))                            |
+| **통합 MCP 게이트웨이** | 외부 에이전트용 MCP 커넥터 1개는 부여된 모든 작업 공간 앱에 연결됩니다.                            | [External Agents](/docs/external-agents)                   |
+| **작업공간 리소스**     | skills/지침/프로필을 한 번 작성하세요. 앱은 런타임에 이를 상속받습니다.                            | **리소스** ([Workspace](/docs/workspace#global-resources)) |
+| **꿈**                  | 과거 실행/피드백을 검토하고 귀하가 승인할 수 있는 지속적인 개선 제안                               | **꿈** 탭                                                  |
+| **승인 흐름**           | 인라인 관리자 검토 뒤에 있는 게이트의 민감한 런타임 변경                                           | **파견 승인 정책**                                         |
+
+각각에 대한 자세한 내용은 아래에 나와 있습니다.
+
+### 중앙 받은편지함
+
+Slack, 이메일, Telegram 및 WhatsApp은 모두 Dispatch의 에이전트 루프로 유입됩니다. **설정 → 메시징**에서 각 플랫폼을 한 번 연결하면 모든 채널이 동일한 메모리와 도구를 사용하여 동일한 에이전트에 연결됩니다. Slack DM과 `agent@yourcompany.com`로 보낸 이메일은 연결이 끊긴 두 개의 봇이 아니라 하나의 대화 기록에서 두 개의 표면으로 끝납니다. 자격 증명 및 웹훅 URL는 [Messaging](/docs/messaging)를 참조하세요.
+
+### 비밀 금고
+
+Dispatch의 볼트에 자격 증명을 한 번 저장합니다. 기본적으로 Vault 액세스는 **모든 앱**입니다. 저장된 모든 키는 모든 Workspace 앱에서 사용할 수 있으며 `sync-vault-to-app`는 전체 Vault를 대상 앱에 푸시합니다. 더 엄격한 분리가 필요한 작업공간에서는 저장소를 **수동** 모드로 전환할 수 있습니다. 여기서는 동기화하기 전에 명시적인 앱별 권한 부여가 필요합니다. 관리자가 아닌 사람도 앱에 대한 비밀을 **요청**할 수 있습니다. 관리자가 **승인**하면 비밀이 생성되고 수동 워크플로에서는 승인이 생성됩니다. 모든 읽기, 승인, 동기화 및 순환은 감사 로그에 캡처됩니다. 이것이 10개의 PR 대신 10개의 앱에서 "OpenAI 키 회전"을 원클릭 작업으로 만드는 이유입니다.
+
+### 교차 앱 위임
+
+Dispatch는 작업 공간의 다른 앱을 A2A 피어로 자동 검색합니다. 수동 등록이나 앱별 구성이 필요하지 않습니다. 사용자가 Slack에서 "지난주 가입 요약"을 요청하면 Dispatch는 이를 분석 요청으로 인식하고 [A2A](/docs/a2a-protocol)를 통해 분석 앱을 호출합니다. "Alice에게 답장 작성"을 요청하면 메일 앱으로 라우팅됩니다. Dispatch는 원래 스레드에 최종 답변을 다시 게시합니다. 행동 규칙은 파견 담당자의 지시에 따릅니다. 즉, 도메인 작업은 도메인 앱에 속합니다. 파견은 전문가가 아닌 조정자입니다.
+
+### 통합 MCP 게이트웨이
+
+디스패치는 외부 에이전트를 위한 단일 MCP 커넥터일 수 있습니다. Claude, ChatGPT, Codex 또는 커서에 `https://dispatch.agent-native.com/_agent-native/mcp`를 한 번 추가하면 앱당 하나의 커넥터 대신 하나의 인증이 부여된 모든 작업 영역 앱에 도달합니다. 전체 연결 흐름, 앱 부여, OAuth 및 인라인 MCP 앱 미리보기는 [External Agents](/docs/external-agents)를 참조하세요.
+
+```an-api
+{
+  "method": "POST",
+  "path": "/_agent-native/mcp",
+  "summary": "Unified MCP gateway endpoint",
+  "description": "The single MCP connector URL external agents add (e.g. `https://dispatch.agent-native.com/_agent-native/mcp`). One authorization here reaches every **granted** workspace app instead of wiring one connector per app. App grants, OAuth, and inline MCP App previews are covered in [External Agents](/docs/external-agents).",
+  "auth": "Standard remote MCP OAuth, handled by the framework. The granted-app set scopes which workspace apps the connector can reach.",
+  "responses": [
+    { "status": "200", "description": "MCP JSON-RPC response — tools, resources, and MCP App UI resources aggregated across granted workspace apps." }
+  ]
+}
+```
+
+### 작업공간 리소스
+
+Skills, 가드레일 지침, 에이전트 프로필 및 참조 리소스는 Dispatch에서 한 번 작성하고 나머지 작업 공간에서 상속할 수 있습니다. **모든 앱** 범위의 리소스는 전역적입니다. Dispatch는 이를 작업 공간 범위에 한 번 저장하고 모든 앱 에이전트는 런타임에 이를 읽습니다. 각 앱에 복사되지 않으며 수동 작업 영역-리소스 동기화 단계가 없습니다. 앱 공유 리소스와 개인 리소스는 로컬에서 작업공간 기본값을 재정의하거나 범위를 좁힐 수 있습니다.
+
+표준 경로 테이블, 스타터 팩 및 재정의 모델은 [Workspace — Global resources](/docs/workspace#global-resources)를 참조하세요.
+
+MCP 서버 리소스는 JSON를 사용하며 의도적으로 HTTP 전용입니다. 토큰을 저장하세요
+Vault를 발송하고 해당 키를 대상 앱에 부여하거나 동기화하고 참조
+`${keys.NAME}`가 포함된 헤더에서 생성되므로 원시 자격 증명은 절대
+리소스 본문.
+
+**리소스** 페이지에는 관리자가 어떤 파일이 있는지 빠르게 확인하고, 기존 파일을 덮어쓰지 않고 누락된 스타터 파일을 복원하고, 내용을 편집할 수 있도록 권장 스타터 팩이 강조 표시됩니다. 선택한 앱/사용자에 대한 효과적인 런타임 스택을 미리 보려면 리소스를 확장하세요. 각 앱 카드에는 해당 앱이 수신하는 내용을 정확하게 보여주는 **컨텍스트** 보기도 있습니다.
+
+### 꿈
+
+Dispatch Dreams는 이전 에이전트 실행, 피드백, 평가 및 반복적인 실패를 검토하여 지속적인 개선을 제안합니다. 드림 보고서는 자동 재작성이 아닌 검토 표면입니다. 개인 메모리 업데이트, 오래된 메모리 정리, 공유 `LEARNINGS.md` 편집, 작업 공간 지침/기술/지식/에이전트 리소스 또는 반복 작업을 제안할 수 있으며 각 제안은 이를 정당화하는 실행으로 다시 연결됩니다. 공유 지침 및 팀 전체 리소스는 적용하기 전에 검토가 필요하며, 특히 증거가 인바운드 Slack, 이메일, Telegram, WhatsApp 또는 웹 콘텐츠에서 나온 경우 더욱 그렇습니다.
+
+쓰기를 제안하기 전에 Dreams Universe는 개인 기억 지수, 기존 `memory/*.md` 노트 및 공유 `LEARNINGS.md`와 증거를 비교합니다. 수업이 이미 캡처된 경우 보고서에는 해당 수업을 건너뛴 것으로 기록됩니다. 관련된 개인 추억이 오래되어 보이는 경우 제안은 복사본을 만드는 대신 기존 메모를 대상으로 합니다.
+
+디스패치의 **Dreams** 탭에서 시작하세요. 먼저 수동 패스를 실행하고 제안 검토 시트를 열어 현재 대상을 제안된 콘텐츠 및 소스 증거와 비교한 다음 유지하려는 변경 사항만 적용합니다. 보고서가 지속적으로 유용해지면 Dispatch는 공유 또는 지침 수준 변경 사항을 자동 적용하지 않고 계속해서 제안을 생성하는 반복되는 꿈의 작업을 만들 수 있습니다.
+
+### 승인 흐름
+
+디스패치는 관리자 검토 뒤에 민감한 런타임 변경 사항을 차단할 수 있습니다. 오늘은 **저장된 대상**(에이전트가 적극적으로 보낼 수 있는 Slack 채널 및 이메일 주소), 공유/팀 **꿈의 제안**, 전체 앱 **워크스페이스 리소스** 생성/업데이트/삭제 및 **디스패치 승인 정책** 자체에 대해 다룹니다. 정책이 활성화되면 변경 사항이 대기열에 추가되고 상담원은 채팅에서 직접 인라인 승인 미리보기를 표시합니다. 관리자는 대화를 종료하지 않고도 승인하거나 거부할 수 있습니다.
+
+## Slack 메시지가 Dispatch를 통해 흐르는 방식 {#flow}
+
+하나의 예시를 끝까지 살펴보세요. 사용자가 봇에게 DM을 보냅니다: _"지난주 가입을 요약합니다."_
+
+1. **Slack → 웹훅.** Dispatch 앱에서 Slack `POST`를 `/_agent-native/integrations/slack/webhook`로 보냅니다. 핸들러는 서명을 확인하고 **`integration_pending_tasks`에 행을 삽입**한 다음 자체 대상 `POST`를 자체 프로세서에 실행하고 Slack가 재시도하지 않도록 즉시 `200`를 반환합니다.
+2. **신선한 프로세서 실행.** 프로세서 엔드포인트는 자체 전체 시간 제한이 있는 새로운 기능 실행에서 실행됩니다. 작업을 원자적으로 요청하고 에이전트 루프를 시작합니다.
+3. **디스패치 에이전트가 결정합니다.** 에이전트는 메시지를 읽고 "가입"을 분석 의도로 인식하고 분석 앱의 [A2A endpoint](/docs/a2a-protocol)에 대해 `call-agent`를 호출합니다. 실제 SQL 작업은 그곳에서 실행됩니다.
+4. **스레드에 답변이 게시되었습니다.** 분석 에이전트가 결과를 반환합니다. Dispatch는 이를 형식화하고 연결된 ID가 있는 경우 이를 사용하여 사용자가 작성한 것과 동일한 Slack 스레드에 다시 게시합니다(따라서 에이전트는 작업공간 소유자가 아닌 요청자의 권한으로 작동합니다).
+5. **무엇이든 죽으면 복구됩니다.** 프로세서가 비행 중에 충돌하는 경우(A2A 시간 초과, 다운스트림 에이전트 오류, 기능 정지) 재시도 작업은 60초마다 중단된 작업을 스윕하고 프로세서를 다시 실행합니다. 작업이 `failed`로 표시되기 전에 최대 3번의 시도가 가능합니다.
+
+```an-diagram title="A Slack message through Dispatch" summary="Slack enqueues into SQL, a fresh execution drains it, the Dispatch agent delegates the domain work over A2A, and the reply lands back in the originating thread. A 60s retry job recovers anything that dies mid-flight."
+{
+  "html": "<div class=\"dsp-flow\"><div class=\"dsp-row\"><div class=\"diagram-node\">Slack DM<br><small class=\"diagram-muted\">\"summarize last week's signups\"</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough><strong>/slack/webhook</strong><br><small class=\"diagram-muted\">verify + INSERT pending task</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill ok\">200</div></div><div class=\"dsp-row\"><div class=\"diagram-box\" data-rough><strong>fresh processor</strong><br><small class=\"diagram-muted\">claim task · start agent loop</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">Dispatch agent decides</span><small class=\"diagram-muted\">analytics intent &rarr; call-agent</small></div></div><div class=\"dsp-row\"><div class=\"diagram-box\" data-rough>Analytics app<br><small class=\"diagram-muted\">A2A peer · runs the SQL work</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill ok\">reply posted in thread</div></div><div class=\"diagram-panel dsp-retry\" data-rough><span class=\"diagram-pill warn\">recovery</span> <span class=\"diagram-muted\">if the processor crashes &mdash; A2A timeout, downstream error, freeze &mdash; the 60s retry job re-fires it (&le;3 attempts) so the Slack reply still arrives</span> <span class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&#8635;</span></div></div>",
+  "css": ".dsp-flow{display:flex;flex-direction:column;gap:12px}.dsp-flow .dsp-row{display:flex;align-items:center;gap:10px;flex-wrap:wrap}.dsp-flow .center{display:flex;flex-direction:column;align-items:center;gap:4px}.dsp-flow .dsp-retry{display:flex;align-items:center;gap:8px;flex-wrap:wrap}"
+}
+```
+
+이메일, 텔레그램, WhatsApp에도 동일한 흐름이 적용됩니다. 어댑터만 변경됩니다.
+
+## 신뢰성 스토리 {#reliability}
+
+전체 파이프라인은 플랫폼별 백그라운드 실행 API에 의존하지 않고 모든 서버리스 호스트(Netlify, Vercel, Cloudflare Workers)에서 생존하도록 구축되었습니다.
+
+- **웹훅 → SQL 큐 → 신규 실행 프로세서.** 에이전트 루프는 웹훅 핸들러 내에서 실행되지 않습니다. 핸들러의 유일한 작업은 200을 확인하고, 대기열에 추가하고, 반환하는 것입니다. 별도의 새로 실행은 대기열을 비우므로 느린 에이전트 실행으로 인해 인바운드 웹후크가 묶이거나 플랫폼이 재시도하게 되는 일은 절대 없습니다.
+- **A2A 연속 폴링.** Dispatch가 다른 앱에 위임하면 제한된 시간 초과로 다운스트림 작업을 폴링합니다. 다운스트림 에이전트가 너무 오래 걸리거나 충돌하는 경우 Dispatch는 계속을 기록하고 재시도 작업이 이를 선택합니다. 사용자의 Slack 응답은 여전히 도착합니다.
+- **자동 서명된 교차 앱 A2A.** 호스팅된 다중 앱 작업 영역은 배포 시 앱별 A2A 자격 증명을 자동 생성하므로 동일한 작업 영역에 있는 앱은 JWT 비밀을 붙여넣지 않고도 서로 호출할 수 있습니다. Dispatch의 에이전트 검색 레이어는 작업 공간 데이터베이스에서 해당 자격 증명을 읽어 새로 추가된 앱이 자동으로 호출 가능한 피어로 표시됩니다.
+
+## 설정 {#setup}
+
+세 가지 짧은 단계:
+
+1. **Dispatch가 포함된 작업 공간을 스캐폴드합니다.** `npx @agent-native/core@latest create my-company-platform`를 실행하고 원하는 도메인 템플릿과 함께 `dispatch`를 선택합니다. Dispatch는 `apps/dispatch`에 있으며 나머지 앱은 그 옆에 있습니다. [Multi-App Workspace](/docs/multi-app-workspace)를 참조하세요.
+2. **메시징 연결.** Dispatch에서 **설정 → 메시징**을 열고 Slack, 이메일, 텔레그램 또는 WhatsApp에 대한 연결을 클릭합니다. 양식 필드는 [Messaging](/docs/messaging) 문서의 환경 변수와 일치합니다. 각 플랫폼에 필요한 사항은 여기를 참조하세요.
+3. **다른 앱을 추가합니다.** 각 도메인 앱의 작업 영역 루트에서 `npx @agent-native/core@latest add-app`를 실행합니다. Dispatch의 `list-workspace-apps`에서 A2A 동료로 자동 표시됩니다. 수동 등록이나 에이전트 카드 편집이 필요하지 않습니다. 파견은 요원 카드에 접근할 수 있게 되는 즉시 그들에게 위임을 시작합니다.
+
+그런 다음 자격 증명을 Vault에 추가하고 (선택적으로) **리소스** 아래에서 전역 작업 공간 리소스를 작성합니다. 액세스 모드에 따라 Vault 키를 계속 동기화하거나 부여할 수 있습니다. 모든 앱 작업 ​​영역 리소스는 자동으로 상속됩니다. 앱별 비밀 격리가 필요한 경우 개별 앱을 부여하기 전에 Vault 액세스 설정을 수동으로 전환하세요.
+
+## 참조 {#see-also}
+
+- [Dispatch template](/docs/template-dispatch) — 전체 작업 카탈로그 및 에이전트 가이드가 포함된 실제 스캐폴드 앱
+- [Messaging](/docs/messaging) — Slack, 이메일, 텔레그램, WhatsApp 연결
+- [A2A Protocol](/docs/a2a-protocol) — 내부적으로 앱 간 위임이 작동하는 방식
+- [Multi-App Workspace](/docs/multi-app-workspace) — Dispatch가 구축된 배포 형태
+- [Workspace Governance](/docs/workspace-management) — Dispatch의 런타임 거버넌스와 쌍을 이루는 git/GitHub 거버넌스

package/docs/content/locales/ko-KR/drop-in-agent.md

@@ -0,0 +1,260 @@
+---
+title: "드롭인 에이전트"
+description: "<AgentPanel>, <AgentSidebar> 및 sendToAgentChat()을 사용하여 상담원 채팅 + 작업 공간을 React 앱에 마운트하세요."
+---
+
+# 드롭인 에이전트
+
+> **개발자 페이지.** 이 페이지는 React 앱에 에이전트를 내장하는 개발자를 위한 것입니다. 에이전트 작업에 대한 최종 사용자 경험은 [Using Your Agent](/docs/using-your-agent)를 참조하세요.
+
+처음부터 에이전트 네이티브를 구축할 필요는 없습니다. 상담원 채팅, 작업 공간 탭, CLI 터미널, 음성 입력 및 모든 관련 인프라는 앱에 드롭하는 소수의 React 구성 요소로 제공됩니다.
+
+> **전제 조건:** 서버는 `agent-chat-plugin`를 실행해야 합니다(모든 템플릿에 자동으로 마운트됨). 처음부터 시작하는 경우 [Server](/docs/server)를 참조하세요.
+>
+> 튜토리얼 대신 공개 API 지도가 필요합니까? [Component API](/docs/components)를 참조하세요.
+
+## 구성요소 개요 {#components}
+
+| 구성요소              | 무엇인가요                                                                             | 다음 경우에 사용                                                    |
+| --------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| `<AgentSidebar>`      | 루트 앱 레이아웃을 래핑하고 전체 에이전트가 포함된 전환 가능한 측면 패널을 추가합니다. | 모든 화면에서 앱과 함께 에이전트를 사용할 수 있기를 원합니다.       |
+| `<AgentToggleButton>` | `<AgentSidebar>` 열기/닫기(헤더에 넣기)                                                | `<AgentSidebar>`와 페어링                                           |
+| `<AgentPanel>`        | 원시 패널 자체 — 채팅 + CLI + 작업 공간 탭                                             | 레이아웃 또는 전담 에이전트 페이지에 대한 완전한 제어를 원하는 경우 |
+| `<AgentChatSurface>`  | 사전 연결된 패널/페이지 채팅 화면                                                      | 사이드바 래퍼 없이 채팅을 원합니다                                  |
+| `<AssistantChat>`     | 작성기/기록 후크가 있는 하위 수준 채팅 렌더러                                          | 표준 대화 UI에 맞춤 크롬이 필요합니다                               |
+| `sendToAgentChat()`   | 프로그래밍 방식으로 채팅에 메시지 보내기                                               | 인라인으로 실행하는 대신 에이전트에 직접 작업을 수행하는 버튼       |
+| `useActionMutation()` | 작업 주위의 유형 안전 프런트엔드 래퍼                                                  | UI는 에이전트 도구가 실행하는 것과 동일한 작업을 실행해야 합니다.   |
+
+이 모든 것은 `@agent-native/core/client`에서 내보내집니다.
+
+```an-diagram title="The mount model" summary="<AgentSidebar> wraps your existing layout. Your routes render in the main area; the agent panel mounts beside them. <AgentPanel> is the same panel without the wrapper."
+{
+  "html": "<div class=\"diagram-mount\"><div class=\"diagram-box sidebar\" data-rough><span class=\"diagram-pill accent\">&lt;AgentSidebar&gt;</span><div class=\"inner\"><div class=\"diagram-node main\">Your app<br><small class=\"diagram-muted\">children: header + &lt;Outlet/&gt;</small></div><div class=\"diagram-node panel\">Agent panel<br><small class=\"diagram-muted\">chat &middot; CLI &middot; workspace</small></div></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&harr;</div><div class=\"diagram-card alt\"><span class=\"diagram-pill\">&lt;AgentPanel&gt;</span><small class=\"diagram-muted\">same panel, no wrapper &mdash; you own the layout</small></div></div>",
+  "css": ".diagram-mount{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-mount .sidebar{display:flex;flex-direction:column;gap:8px;padding:14px}.diagram-mount .inner{display:flex;gap:10px}.diagram-mount .main{flex:2}.diagram-mount .panel{flex:1}.diagram-mount .alt{display:flex;flex-direction:column;gap:6px;padding:14px}.diagram-mount .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## 80% 사례: `<AgentSidebar>` {#sidebar}
+
+가장 일반적인 설정은 모든 화면의 오른쪽에서 열리는 사이드바입니다.
+기존 루트 레이아웃을 `<AgentSidebar>`로 래핑합니다. 당신이 전달하는 무엇이든
+어린이는 기본 앱 영역에 머물러 있습니다. 상담원 채팅은 측면 패널입니다.
+
+```an-annotated-code title="Wrapping the root layout with <AgentSidebar>"
+{
+  "filename": "app/root.tsx",
+  "language": "tsx",
+  "code": "import { Outlet } from \"react-router\";\nimport { AgentSidebar, AgentToggleButton } from \"@agent-native/core/client\";\n\nexport default function Root() {\n  return (\n    <AgentSidebar\n      emptyStateText=\"How can I help?\"\n      suggestions={[\n        \"Summarize my inbox\",\n        \"Draft a reply to the latest email\",\n        \"Show me yesterday's signup numbers\",\n      ]}\n      dynamicSuggestions\n      defaultSidebarWidth={420}\n      position=\"right\"\n    >\n      <header>\n        <AgentToggleButton />\n      </header>\n\n      <main>\n        <Outlet />\n      </main>\n    </AgentSidebar>\n  );\n}",
+  "annotations": [
+    { "lines": "6", "label": "Wrapper", "note": "`<AgentSidebar>` wraps your whole layout. It adds the toggleable side panel; everything you pass as children stays in the main app area." },
+    { "lines": "8-12", "label": "Starter prompts", "note": "`suggestions` render as clickable chips on the empty chat." },
+    { "lines": "13", "label": "Context-aware chips", "note": "`dynamicSuggestions` merges screen-aware prompts (e.g. \"Summarize this selection\") with your static ones. On by default." },
+    { "lines": "18-20", "label": "Toggle button", "note": "Put `<AgentToggleButton />` anywhere in your header to open and close the panel." },
+    { "lines": "22-24", "label": "Your app", "note": "`<Outlet/>` (your routes) renders in the main area, untouched." }
+  ]
+}
+```
+
+그렇습니다. 이제 사용자는 채팅 기록, 작업 공간 탭, CLI 터미널, 음성 입력 및 전체 화면 모드를 포함하여 모든 페이지에 전환 가능한 에이전트를 갖게 됩니다. `localStorage`를 통해 다시 로드해도 상태가 유지됩니다.
+
+### 소품
+
+- **`children`** — 앱의 일반 레이아웃 및 경로입니다. 주요 영역에서 렌더링됩니다. 상담사 패널은 데스크톱에서는 옆에, 모바일/전체 화면에서는 그 위에 설치됩니다.
+- **`emptyStateText`** — 채팅에 메시지가 없을 때 표시되는 인사말입니다. 기본값: `"How can I help you?"`.
+- **`suggestions`** — 비어 있으면 클릭 가능한 칩으로 렌더링되는 시작 프롬프트.
+- **`dynamicSuggestions`** — 상황 인식 프롬프트 칩이 `suggestions`와 병합되었습니다. 기본적으로 활성화되어 있습니다. 정적 제안만 표시하려면 `false`를 전달하고, 맞춤설정하려면 `{ max, includeStatic, getSuggestions }`를 전달하세요.
+- **`defaultSidebarWidth`** — 초기 픽셀 너비(마운트 전용, 사용자 크기 조정 및 저장된 값 재정의). 기본값: `380`.
+- **`position`** — `"left"` 또는 `"right"`. 기본값: `"right"`.
+- **`defaultOpen`** — 사이드바가 열리기 시작하는지 여부(데스크톱에만 해당). 기본값: `false`.
+
+## 나머지 20%: `<AgentPanel>` {#panel}
+
+전용 `/chat` 경로, 관리하는 측면 열에 포함된 패널 또는 팝업 등 레이아웃에 대한 완전한 제어가 필요한 경우 `<AgentPanel>`를 직접 렌더링하세요.
+
+```tsx
+// app/routes/agent.tsx
+import { AgentPanel } from "@agent-native/core/client";
+
+export default function AgentRoute() {
+  return (
+    <div className="h-screen">
+      <AgentPanel defaultMode="chat" className="h-full" />
+    </div>
+  );
+}
+```
+
+`<AgentPanel>`는 사이드바 래퍼, 축소 버튼 또는 상태 지속성 없이 원시 탭(Chat / CLI / Workspace)을 제공합니다. 원하는 곳에 두십시오. 레이아웃을 처리합니다.
+
+### 선택한 소품
+
+- **`defaultMode`** — `"chat"` 또는 `"cli"`. 기본값: `"chat"`.
+- **`className`** — 외부 컨테이너의 CSS 클래스.
+- **`onCollapse`** — 제공된 경우 헤더에 축소 버튼이 나타납니다.
+- **`isFullscreen`** / **`onToggleFullscreen`** — Claude 스타일 중앙 열을 원하는 경우 외부 전체 화면 상태를 연결합니다.
+- **`storageKey`** — `localStorage` 키의 네임스페이스입니다. 동일한 페이지에서 여러 패널(다른 앱 인스턴스 또는 작업 공간)을 렌더링할 때 유용합니다.
+
+전체 소품: `@agent-native/core/client`의 `AgentPanelProps`.
+
+## 프로그래밍 메시지: `sendToAgentChat()` {#send}
+
+인라인 `llm()` 호출을 실행하는 대신 에이전트에 직접 작업을 전달하는 버튼 - [ladder](/docs/what-is-agent-native#the-ladder)의 안티 패턴:
+
+```tsx
+import { sendToAgentChat } from "@agent-native/core/client";
+
+<Button
+  onClick={() =>
+    sendToAgentChat({
+      message: "Generate a chart showing signups by source",
+      context: `Dashboard ID: ${dashboardId}, date range: last 30 days`,
+      submit: true,
+    })
+  }
+>
+  Generate chart
+</Button>;
+```
+
+### 옵션
+
+- **`message`** — 채팅에 표시되는 프롬프트입니다.
+- **`context`** — 프롬프트에 추가된 숨겨진 컨텍스트(선택한 텍스트, 커서 위치, 현재 엔터티 ID — 상담원은 알아야 하지만 사용자는 두 번 볼 수 없는 모든 것).
+- **`submit`** — 자동 실행을 위한 `true`, 미리 채우고 대기하는 `false`. 프로젝트 기본값을 사용하려면 생략하세요.
+- **`newTab`** — 이 프롬프트에 대해 별도의 채팅 스레드를 생성하세요.
+- **`background`** — `newTab`를 사용하면 새 스레드에 초점을 맞추지 않고 실행됩니다. 숨겨진 실행은 `RunsTray`에서 추적됩니다.
+- **`openSidebar`** — 백그라운드/무음 전송을 위해 `false`로 설정됩니다. 기본값은 사용자가 응답을 볼 수 있도록 사이드바를 엽니다.
+- **`type`** — `"content"`(기본값)는 내장된 앱 에이전트에서 작업을 유지합니다. `"code"`는 코드 편집 프레임으로 라우팅됩니다(에이전트가 작성한 코드 변경 사항은 [Frames](/docs/frames) 참조).
+
+`sendToAgentChat`는 채팅 실행을 추적하는 데 사용할 수 있는 안정적인 `tabId`를 반환합니다.
+
+조용한 작업을 위해서는 `newTab`, `background` 및 `openSidebar: false`를 페어링하세요.
+
+```ts
+sendToAgentChat({
+  message: "Summarize the selected thread and save the summary",
+  context: `Thread id: ${threadId}`,
+  submit: true,
+  newTab: true,
+  background: true,
+  openSidebar: false,
+});
+```
+
+이것은 여전히 도구, actions, 스레드 상태 및 실행을 사용한 전체 에이전트 실행입니다.
+추적. 단순히 사용자의 현재 사이드바 상태에서 포커스를 빼앗지는 않습니다.
+
+동일한 경로가 MCP 앱으로 삽입된 경우 제출
+`sendToAgentChat()` 통화는 지원되는 호스트 채팅으로 전달됩니다. 참조
+MCP 앱 브리지 동작을 위한 [Client](/docs/client#sendtoagentchat).
+
+로드 상태를 원하면 `useSendToAgentChat()` 후크를 사용하세요. `send`와 `isGenerating`를 모두 반환합니다.
+
+```ts
+import { useSendToAgentChat } from "@agent-native/core/client";
+
+const { send, isGenerating } = useSendToAgentChat();
+```
+
+## 스톡 사이드바가 맞지 않을 때 {#custom-chat-ui}
+
+`<AgentSidebar>` 및 `<AgentPanel>`는 대부분의 앱을 포괄합니다.
+에이전트 주변의 레이아웃 또는 에이전트와의 대화를 강화하려는 경우
+다른 곳에서 만든 경우 레이어를 드롭다운하세요. 하지만 프레임워크가 계속 소유하게 하세요
+런타임, actions 및 SQL 지원 상태:
+
+- **표준 런타임에 크롬을 소유하세요.** `<AgentChatSurface>`를 사용하세요
+  전용 채팅 경로 또는 사용자 정의 헤더를 원하는 경우 `<AssistantChat>`
+  탭 및 표준 대화 주변의 빈 상태. 전체 레이어 맵 —
+  가져오기 경로가 포함된 모든 구성요소, 후크, 작성기 및 어댑터는 여기에 있습니다.
+  [Component API](/docs/components#agent-chat-ui).
+- **자신만의 에이전트 런타임을 가져오세요.** 다른 곳에서 구축한 에이전트가
+  Agent-Native가 작곡가, 대본, 도구를 유지하면서 대화에 힘을 실어주세요
+  카드, 승인 및 기본 위젯은 `AgentChatRuntime`를
+  `<AssistantChat runtime={...} />`. 커넥터
+  (`createHttpAgentChatRuntime()` 및 OpenAI / Claude / Vercel AI / AG-UI
+  도우미) 및 이벤트 계약은
+  [Native Chat UI — BYO agent runtimes](/docs/native-chat-ui#byo-agent-runtimes).
+
+어떤 레이어를 선택하든 actions 및 SQL 지원 앱 상태를 계약으로 유지하세요.
+제품 UI에서 `/_agent-native/agent-chat`로 직접 게시하지 마세요. 만약
+실제 사용자 정의 표면에는 명명된 도우미가 없습니다. 먼저 해당 도우미를 추가하세요.
+클라이언트 코드는 두 번째 임시 전송을 학습하지 않습니다.
+
+## UI: `useActionMutation()`의 형식 안전 actions {#use-action-mutation}
+
+UI가 에이전트 도구가 실행하는 것과 동일한 작업을 실행해야 하는 경우([ladder](/docs/what-is-agent-native#rung-three)의 3번 단계) `useActionMutation`를 사용하세요.
+
+```tsx
+import { useActionMutation } from "@agent-native/core/client";
+
+const { mutate, isPending } = useActionMutation("reply-to-email");
+
+<Button onClick={() => mutate({ emailId, body: "Thanks!" })}>
+  Send Reply
+</Button>;
+```
+
+유형이 안전한 인수는 `defineAction()`의 zod 스키마에서 나옵니다. 전체 동작 시스템은 [Actions](/docs/actions)를 참조하세요.
+
+```an-callout
+{
+  "tone": "decision",
+  "body": "**`useActionMutation` vs `sendToAgentChat`.** Run the operation directly with `useActionMutation` when the user clicked a deterministic button (\"Send reply\"). Hand it to `sendToAgentChat` when the work needs the agent's reasoning, tools, or multi-step planning. Never call an inline `llm()` from UI — that is rung 1 of the [ladder](/docs/what-is-agent-native#the-ladder)."
+}
+```
+
+## 선택 + 커서 인식 {#selection}
+
+에이전트는 애플리케이션 상태에서 `navigation` 및 `selection` 키를 통해 사용자가 선택한 내용(텍스트, 셀, 슬라이드, 연락처)을 볼 수 있습니다. 또한 빈 채팅에서는 해당 키를 사용하여 현재 화면에 관련성이 있는 경우 "이 선택 항목 요약" 또는 "이 슬라이드 개선"과 같은 동적 제안을 제공합니다. Cmd-I(또는 유사)를 사용하여 선택한 범위를 채팅에 컨텍스트로 보내려면 [Context Awareness](/docs/context-awareness)를 참조하세요.
+
+## 모두 합치기 {#putting-it-together}
+
+일반적인 드롭인 설정:
+
+```tsx
+// app/root.tsx
+import {
+  AgentSidebar,
+  AgentToggleButton,
+  sendToAgentChat,
+} from "@agent-native/core/client";
+
+export default function Root() {
+  return (
+    <AgentSidebar suggestions={["Draft a reply", "Summarize selection"]}>
+      <Header>
+        <AgentToggleButton />
+      </Header>
+
+      <Main>
+        <YourRoutes />
+      </Main>
+    </AgentSidebar>
+  );
+}
+```
+
+```tsx
+// Anywhere else in the app
+<Button
+  onClick={() =>
+    sendToAgentChat({
+      message: "Summarize this thread",
+      context: `Thread id: ${threadId}`,
+      submit: true,
+    })
+  }
+>
+  Summarize
+</Button>
+```
+
+사용자는 헤더에 있는 채팅 버튼을 보고 이를 열고 상담원과 대화할 수 있습니다. 일회성 LLM 호출을 실행하는 대신 버튼이 동일한 에이전트에 직접 작동합니다.
+
+## 다음 단계
+
+- [**Actions**](/docs/actions) — `defineAction()` 및 `useActionMutation()`
+- [**Context Awareness**](/docs/context-awareness) — 선택, 탐색, 보기 화면
+- [**Workspace**](/docs/workspace) — 작업 공간 탭에 포함된 내용(skills, 메모리, MCP 서버, 예약된 작업)
+- [**Voice Input**](/docs/voice-input) — 채팅 작성기의 마이크

package/docs/content/locales/ko-KR/durable-resume.md

@@ -0,0 +1,65 @@
+---
+title: "튼튼한 이력서"
+description: "호스팅 에이전트 실행이 중단되었다가 다시 시작되면 완료된 부작용 도구 호출은 다시 실행되지 않습니다. 내구성 있는 원장에서 파생된 도구 호출 저널이 중복 전송, 요금 및 티켓을 차단합니다."
+---
+
+# 튼튼한 이력서
+
+> **대상:** 프레임워크가 어떻게 실행되는지 이해하고 싶은 사람
+> 회복은 중복된 부작용을 방지합니다. 이것은 내장된 동작입니다.
+> 연결할 것이 없습니다.
+
+호스팅 에이전트 실행이 중단됩니다. 서버리스 기능이 스트림 중간에 하드 타임아웃에 도달하고, 게이트웨이가 45초에 연결을 끊고, 소켓이 끊기고, 플랫폼이 콜드 스타트됩니다. 프레임워크는 대화 접두어를 저장하고 LLM 호출("중단한 위치부터 계속")을 다시 실행하여 이미 이러한 문제를 복구합니다. 그러나 복구 자체에는 장점이 있습니다. 중단된 시도가 **이미 이메일을 보냈거나 티켓을 생성**한 경우 순진한 이력서를 통해 다시 시도할 수 있습니다.
+
+튼튼한 이력서가 그 격차를 줄여줍니다. 재개 시 프레임워크는 이미 완료된 부작용 도구 호출을 알고 두 레이어에서 다시 실행을 거부합니다.
+
+```an-diagram title="Two layers block duplicate side effects on resume" summary="The journal reads the durable ledger and classifies prior calls; layer 1 tells the model, layer 2 hard-blocks a re-dispatched write that matches a completed entry."
+{
+  "html": "<div class=\"diagram-durable\"><div class=\"diagram-box\" data-rough>Run-event ledger<br><small class=\"diagram-muted\">tool_start / tool_done</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><strong>Tool-call journal</strong><small class=\"diagram-ok\">completed = start+done</small><small class=\"diagram-warn\">interrupted = start, no done</small></div><div class=\"diagram-col\"><div class=\"diagram-pill\">Layer 1 · prompt note &rarr; model</div><div class=\"diagram-pill accent\">Layer 2 · hard-block re-dispatched write</div></div></div>",
+  "css": ".diagram-durable{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-durable .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-durable .diagram-arrow{font-size:22px;line-height:1}.diagram-durable .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## 도구 호출 일지 {#journal}
+
+저널은 **내구성 있는 실행 이벤트 원장에 대한 순수 읽기**입니다. 핫 경로에 새로운 기록 후크가 없습니다. 현재 차례에 대해 이미 기록된 도구 호출을 분류합니다.
+
+- **완료** — `tool_done`와 일치하는 `tool_start`. 호출이 실행되고 부작용이 발생했으며 결과가 기록되었습니다. **재실행하지 마세요.**
+- **중단됨** — `tool_done`와 일치하는 **없음**이 있는 `tool_start`. 통화가 시작되었고 부작용이 발생했을 수도 있고 발생하지 않았을 수도 있으며 중단으로 인해 결과가 발생했습니다. 결과는 알 수 없습니다.
+
+일치하는 것은 내구성이 뛰어난 회전이 다른 곳에서 어떻게 재구성되는지를 반영합니다. `tool_done`는 동일한 도구 이름에 대해 아직 열려 있는 가장 오래된 `tool_start`와 쌍을 이룹니다(공구당 FIFO). `clear` 이벤트(폐기된 부분 출력)는 턴별 집계를 재설정하므로 버려진 부분이 팬텀 공개 호출을 남기지 않습니다.
+
+## 레이어 1: 프롬프트 수준 저널 노트 {#prompt-note}
+
+실행이 재개되면(소프트 시간 초과, 게이트웨이 시간 초과 또는 재개 가능한 전송 오류) 프레임워크는 "중단한 위치부터 계속" 넛지 바로 뒤에 **구조화된 저널 메모**를 재개 프롬프트에 추가합니다. 메모는 일반 텍스트로 모델에 다음 내용을 알려줍니다.
+
+- 이 도구는 **이미 완료됨**(짧은 결과 포함)을 호출하여 이를 재사용하고 다시 실행하지 **않습니다**
+- 어떤 도구 호출이 **알 수 없는 결과로 중단되었으므로** 성공 또는 실패를 가정하기 전에 상태를 확인합니다.
+
+일지가 비어 있으면(도구 활동이 없는 차례 또는 깔끔한 연속) 추가 항목이 추가되지 않으며 재개 동작은 이전과 같이 바이트 단위로 이루어집니다. 참고 사항은 최선의 노력입니다. 실패한 원장 읽기는 성공할 수 있는 복구를 결코 차단하지 않습니다.
+
+## 레이어 2: 도구 레이어 하드 블록 {#hard-block}
+
+즉시 메모는 권고 사항입니다. 예의바르게 행동하는 모델은 이를 따르지만 모델이 보장되는 것은 아닙니다. 따라서 루프는 도구 계층에서도 이를 시행합니다.
+
+루프가 재개된 청크에서 실행되기 전에 저널의 스냅샷을 한 번 생성합니다(이 논리적 턴의 **이전** 청크만 캡처). 모델이 도구 이름 **및 입력**이 완료된 저널 항목과 일치하는 **쓰기** 도구를 다시 디스패치하면 루프가 단락됩니다. 즉, 이전에 중단된 시도에서 호출이 이미 완료되었으며 중복 부작용을 피하기 위해 다시 실행되지 않았다는 메모와 함께 작업을 실행하는 대신 저널링된 결과를 반환합니다.
+
+주요 속성:
+
+- **쓰기 도구만 해당.** 읽기 전용(`readOnly` / GET) actions는 차단되지 않습니다. 다시 읽기는 안전하고 멱등성을 갖습니다.
+- **컨텐츠 주소 지정.** 일치 항목은 도구 이름 + 입력 서명이므로 차례의 다른 위치에 있는 재개된 통화는 여전히 일치합니다. _다른_ 호출(다른 인수)은 새로운 것으로 간주되어 정상적으로 실행됩니다.
+- **한 번만 사용.** 완료된 각 항목은 일치할 때 청구되므로 동일한 차례에 있는 완전히 구별되는 두 개의 동일한 신규 호출이 저널에 기록된 하나의 완료 시 단락되지 않습니다.
+- **신선한 전화는 건드리지 않습니다.** 첫 번째 전화에는 빈 일지가 표시됩니다. 일반 실행에서는 아무런 변화가 없습니다.
+
+```an-callout
+{
+  "tone": "success",
+  "body": "Together the two layers mean an interrupted run that already had a real side effect resumes **without repeating it** — no duplicate emails, charges, or tickets — while genuinely new work still runs. Read-only actions are never blocked; re-reading is always safe."
+}
+```
+
+## 관련
+
+- [**Real-Time Sync**](/docs/real-time-collaboration) — 내구성 실행 원장이 클라이언트로 스트리밍되고 재연결 시 재생되는 방법
+- [**Actions**](/docs/actions) — `readOnly`는 읽기를 다시 실행해도 안전한 것으로 표시합니다. 다른 모든 것은 부작용으로 간주됩니다.
+- [**In-Loop Processors**](/docs/processors) — 또 다른 루프 내부 경화 솔기