@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/ko-KR/recurring-jobs.md

@@ -0,0 +1,142 @@
+---
+title: "반복 작업"
+description: "Cron 예약 메시지는 에이전트가 일일 다이제스트, 주간 보고서, 시간별 폴링 등 자체적으로 실행된다는 메시지를 표시합니다."
+---
+
+# 반복 작업
+
+**반복 작업**은 크론 일정에 따라 실행되는 프롬프트입니다. 에이전트가 자체적으로 작업을 수행하는 방식입니다. "매일 아침 7시에 밤샘 이메일 요약", "매주 월요일 지난 주의 가입 번호를 Slack에 게시", "매시간 오래된 초안을 검색하여 삭제합니다."
+
+반복 작업은 정해진 시간에 실행됩니다. _이벤트_(예약 생성, 이메일 수신)에 반응하려면 — 동일한 `jobs/` 파일 형식과 조건 — [Automations](/docs/automations)를 참조하세요.
+
+작업은 `jobs/<name>.md`의 [workspace](/docs/workspace)에 있습니다. YAML 머리말이 있는 Markdown 파일입니다. 등록도 없고 배선도 없습니다. 파일을 드롭하면 프레임워크가 이를 선택합니다.
+
+## 작업 파일 {#job-file}
+
+```an-annotated-code title="jobs/morning-digest.md"
+{
+  "filename": "jobs/morning-digest.md",
+  "language": "markdown",
+  "code": "---\nschedule: \"0 7 * * *\"\nenabled: true\nrunAs: creator\n---\n\n# Morning digest\n\nSummarize the emails received overnight. Group by sender domain.\nPin the top 3 threads that look like they need a reply today to the\n\"Needs reply\" label. Draft replies for any that are obvious.",
+  "annotations": [
+    { "lines": "2", "label": "When", "note": "Standard 5-field cron — `0 7 * * *` is every day at 07:00." },
+    { "lines": "3", "label": "Pause switch", "note": "Flip to `false` to stop the job without deleting it." },
+    { "lines": "4", "label": "Identity", "note": "`creator` runs with the owner's identity and `ANTHROPIC_API_KEY`; `shared` uses the org's key." },
+    { "lines": "7-12", "label": "The prompt", "note": "The body is just a prompt — the agent runs it at each firing with all its normal tools and workspace context." }
+  ]
+}
+```
+
+그렇습니다. 본문은 예약된 각 실행 시 에이전트가 실행하는 프롬프트입니다. 에이전트는 actions, skills, 메모리, 연결된 MCP 서버, 하위 에이전트 등 대화형 채팅에서와 동일한 모든 도구 및 작업 공간 컨텍스트에 액세스할 수 있습니다.
+
+## 머리말 {#frontmatter}
+
+| 필드         | 유형                          | 기본값      | 설명                                                                                                             |
+| ------------ | ----------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------- |
+| `schedule`   | 크론 표현                     | _(필수)_    | 표준 5필드 크론. `"0 7 * * *"` = 매일 07:00; `"0 */4 * * *"` = 4시간마다.                                        |
+| `enabled`    | 부울                          | `true`      | 작업을 삭제하지 않고 일시 중지하려면 `false`로 전환하세요.                                                       |
+| `runAs`      | `"creator"` \| `"shared"`     | `"creator"` | `"creator"`는 작업 소유자의 ID와 `ANTHROPIC_API_KEY`를 사용하여 실행됩니다. `"shared"`는 조직의 키를 사용합니다. |
+| `createdBy`  | 이메일                        | _(자동)_    | 작업 공간 UI를 통해 또는 에이전트에 의해 작업이 생성될 때 채워집니다.                                            |
+| `orgId`      | 문자열                        | _(자동)_    | 조직 범위; 작성자의 활성 조직에서 상속됩니다.                                                                    |
+| `lastRun`    | ISO 타임스탬프                | _(관리)_    | 각 실행 후 스케줄러에 의해 작성됩니다.                                                                           |
+| `lastStatus` | `"success"` \| `"error"` \| … | _(관리)_    | 최신 결과.                                                                                                       |
+| `lastError`  | 문자열                        | _(관리)_    | 마지막 실행이 실패한 경우 오류 메시지.                                                                           |
+| `nextRun`    | ISO 타임스탬프                | _(관리)_    | `schedule`에서 계산됩니다. 스케줄러가 다음에 실행할 시기를 결정하는 데 사용됩니다.                               |
+
+`last*` 및 `nextRun` 필드는 스케줄러에 의해 작성됩니다. 이를 읽어 기록을 볼 수 있지만 직접 편집하지 마십시오. 다음 실행 시 덮어쓰게 됩니다.
+
+## 크론 구문 {#cron}
+
+표준 5필드 크론(분, 시간, 일, 월, 요일):
+
+| 크론           | 의미              |
+| -------------- | ----------------- |
+| `*/5 * * * *`  | 5분마다           |
+| `0 * * * *`    | 매시 정각         |
+| `0 */4 * * *`  | 4시간마다         |
+| `0 7 * * *`    | 매일 07:00        |
+| `0 9 * * 1`    | 매주 월요일 09:00 |
+| `0 17 * * 1-5` | 평일 17:00        |
+| `0 0 1 * *`    | 매월 1일          |
+
+프레임워크에는 리소스 및 스케줄러 계층에서 내부적으로 사용되는 cron 문자열을 검증하고 렌더링하기 위한 cron 유틸리티(`isValidCron()` 및 `describeCron()`)가 포함되어 있습니다.
+
+## 작업 생성 {#creating}
+
+### 작업공간 탭에서
+
+`+` → 작업 공간 패널의 **예약된 작업**. 프롬프트와 일정을 입력하세요. `jobs/<slug>.md`로 저장하고 다음 일치하는 틱에서 실행을 시작합니다.
+
+### 에이전트에게 요청
+
+> "매일 아침 7시에 읽지 않은 이메일을 요약하는 예약된 작업을 만듭니다."
+
+에이전트가 파일을 작성합니다.
+
+### 손으로
+
+프레임워크의 리소스 APIs를 통해 `jobs/`에 Markdown 파일을 삭제합니다.
+
+```ts
+import { resourcePut } from "@agent-native/core/resources";
+
+await resourcePut(
+  ownerEmail,
+  "jobs/morning-digest.md",
+  `---
+schedule: "0 7 * * *"
+enabled: true
+---
+Summarize overnight emails.`,
+);
+```
+
+## 스케줄러 실행 방법 {#how-scheduler-runs}
+
+스케줄러는 프로세스 내에서 실행되는 프레임워크 플러그인(내부 `processRecurringJobs()` 루틴)입니다. `setInterval`는 서버가 실행되는 위치에 관계없이 에이전트 채팅 플러그인 내에서 60초마다(10초의 시작 지연) 실행됩니다.
+
+```an-diagram title="One scheduler tick" summary="Every 60s the scheduler finds due jobs, runs each as a fresh agent thread, and writes the outcome back to the job file."
+{
+  "html": "<div class=\"sched\"><div class=\"diagram-box accent\"><code>setInterval</code> &bull; 60s &#8635;</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">1 &middot; scan</span><small class=\"diagram-muted\">list every enabled <code>jobs/*.md</code> across all owners</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">2 &middot; due?</span><small class=\"diagram-muted\">compare <code>nextRun</code> to now</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card accent\"><span class=\"diagram-pill accent\">3 &middot; run</span><small class=\"diagram-muted\">fresh agent thread, job body as the user message &mdash; actions, SQL, A2A, email</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card ok\"><span class=\"diagram-pill ok\">4 &middot; record</span><small class=\"diagram-muted\">write <code>lastRun</code> / <code>lastStatus</code> / <code>lastError</code>, recompute <code>nextRun</code></small></div></div>",
+  "css": ".sched{display:flex;flex-direction:column;gap:6px;max-width:520px}.sched .diagram-card{display:flex;flex-direction:column;gap:2px;padding:10px 14px}.sched .diagram-box{align-self:flex-start}.sched .diagram-arrow{font-size:18px;align-self:center}"
+}
+```
+
+```an-callout
+{ "tone": "risk", "body": "**Scale-to-zero caveat.** The scheduler is in-process, so on serverless hosts jobs only fire while an instance is warm. If reliable scheduling matters, keep an instance warm with keep-alive pings or use an always-on host (Fly, Render, a VPS)." }
+```
+
+## 작업 디버깅 {#debugging}
+
+- 작업 공간에서 `jobs/<name>.md`를 엽니다. 머리말에는 `lastRun`, `lastStatus`, `lastError`, `nextRun`가 표시됩니다.
+- **기다리지 않고 테스트하세요.** 강제 발사 도구가 없습니다. 요청 시 동일한 작업을 수행하려면 작업 프롬프트를 에이전트 채팅에 붙여넣고 실행되도록 하거나 스케줄러가 다음 틱에서 이를 선택할 수 있도록 일시적으로 일정을 다음 분으로 설정합니다(그런 다음 실제 크론을 복원합니다).
+- **일시 중지:** `enabled: false`를 뒤집습니다. 파일은 그대로 유지되고 실행이 중지됩니다.
+
+## 에이전트 도구 {#agent-tool}
+
+단일 `manage-jobs` 도구가 모든 템플릿에 등록됩니다. `action` 매개변수는 작업을 선택합니다:
+
+| 액션     | 매개변수                                                     | 목적                                                       |
+| -------- | ------------------------------------------------------------ | ---------------------------------------------------------- |
+| `create` | `name`, `schedule`, `instructions`(필수); `scope`, `runAs`   | 새 반복 작업 만들기                                        |
+| `list`   | `scope`(`personal`, `shared` 또는 모두)                      | 상태(일정, 활성화, 마지막/다음 실행)와 함께 모든 작업 나열 |
+| `update` | `name`(필수); `schedule`, `instructions`, `enabled`, `runAs` | 기존 작업 편집                                             |
+| `delete` | `name` (필수)                                                | 작업 삭제 — 항상 먼저 사용자에게 확인                      |
+
+**개인 범위와 공유 범위.** 각 작업은 개인 범위(작성자에게만 실행되고 표시됨) 또는 공유/조직 범위(작성자를 대신하여 실행되지만 조직 구성원에게 표시됨)에 있습니다. `scope` 및 `runAs` 매개변수는 생성 시 이를 제어합니다. 조직 관리자는 공유 작업을 업데이트하거나 삭제할 수 있습니다. 관리자가 아닌 회원은 자신의 회원만 관리할 수 있습니다.
+
+## 스케줄링 패키지와 다름 {#vs-scheduling-package}
+
+반복 작업을 `@agent-native/scheduling`와 혼동하지 마십시오:
+
+- **반복 작업(이 페이지)** — cron-scheduled _prompts_ 에이전트가 백그라운드에서 실행됩니다. 프레임워크 수준. 작업 공간에 거주합니다. 모든 에이전트 기반 앱에서 실행됩니다.
+- **`@agent-native/scheduling`** — 달력/예약 기능(이벤트 유형, 이용 가능 기간, 예약) 구축을 위한 재사용 가능한 도메인 패키지입니다. `calendar` 템플릿과 맞춤형 일정 관리 화면을 강화합니다.
+
+반복 작업은 "에이전트가 스스로 작동하도록 하려면 어떻게 해야 합니까?"입니다. 일정 패키지는 "캘린더 앱을 어떻게 구축하나요?"입니다. 다양한 우려 사항.
+
+## 다음 단계
+
+- [**Automations**](/docs/automations) — 동일한 `jobs/` 형식에 이벤트 트리거 및 조건 추가
+- [**Workspace**](/docs/workspace) — 작업이 skills, 메모리 및 사용자 정의 에이전트와 함께 존재하는 곳
+- [**Actions**](/docs/actions) — 작업이 호출하는 도구
+- [**Agent Teams**](/docs/agent-teams) — 작업은 종종 병렬 작업을 수행하기 위해 하위 에이전트를 생성합니다

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

@@ -0,0 +1,79 @@
+---
+title: "라우팅"
+description: "React 라우터 v7을 사용한 에이전트 기반 앱을 위한 파일 기반 라우팅 — 페이지, 동적 매개변수 및 탐색."
+---
+
+# 라우팅
+
+에이전트 네이티브 앱은 `@react-router/fs-routes`에서 `flatRoutes()`를 통한 파일 기반 라우팅과 함께 **React 라우터 v7**을 사용합니다. `app/routes/`의 모든 파일은 URL가 됩니다. 템플릿은 점 표기법 규칙을 사용합니다. 점은 단일 파일 이름 내에서 URL 세그먼트를 구분합니다.
+
+## 파일 기반 라우팅 {#file-based-routing}
+
+### 파일 → URL 매핑
+
+| 파일                  | URL                 | 참고                                   |
+| --------------------- | ------------------- | -------------------------------------- |
+| `_index.tsx`          | `/`                 | 색인 경로                              |
+| `settings.tsx`        | `/settings`         | 간단한 페이지                          |
+| `inbox.$threadId.tsx` | `/inbox/:threadId`  | 점 = `/`, `$` = 동적 매개변수          |
+| `_app.tsx`            | (URL 세그먼트 없음) | 경로 없는 레이아웃 — 접두사 `_`        |
+| `inbox/route.tsx`     | `/inbox`            | 폴더 형식 - `route.tsx`가 인덱스입니다 |
+
+동적 매개변수의 경우 세그먼트 앞에 `$`를 붙입니다. 경로 없는 레이아웃 경로(URL 세그먼트 없음)로 만들려면 접두사 `_`를 붙입니다. 템플릿은 `flatRoutes()`를 사용합니다. 위의 점 표기법 파일이 기본입니다. 중첩 폴더 형식 `inbox/route.tsx`도 작동합니다.
+
+```an-diagram title="Pathless layout wraps the pages" summary="A _app.tsx layout (no URL segment) renders the shared shell once; matched pages render inside its <Outlet/>, so the agent sidebar never remounts on navigation."
+{
+"html": "<div class=\"diagram-layout\" data-rough><div class=\"diagram-shell\"><span class=\"diagram-pill accent\">_app.tsx</span><small class=\"diagram-muted\">pathless layout · persistent shell + agent sidebar</small><div class=\"diagram-outlet\" data-rough><small class=\"diagram-muted\">&lt;Outlet/&gt; — the matched page</small><div class=\"diagram-row\"><span class=\"diagram-pill\">_index.tsx &rarr; /</span><span class=\"diagram-pill\">settings.tsx &rarr; /settings</span><span class=\"diagram-pill\">inbox.$threadId.tsx &rarr; /inbox/:threadId</span></div></div></div></div>",
+"css": ".diagram-layout .diagram-shell{display:flex;flex-direction:column;gap:8px;padding:16px}.diagram-layout .diagram-outlet{display:flex;flex-direction:column;gap:8px;padding:14px;margin-top:6px}.diagram-layout .diagram-row{display:flex;flex-wrap:wrap;gap:8px;margin-top:4px}"
+}
+
+```
+
+## 새 페이지 추가 {#adding-a-page}
+
+파일 생성 및 기본 구성 요소 내보내기:
+
+```tsx
+// app/routes/settings.tsx
+export function meta() {
+  return [{ title: "Settings" }];
+}
+
+export default function SettingsPage() {
+  return <div>Settings</div>;
+}
+```
+
+그렇습니다. React 라우터가 자동으로 선택하므로 등록이 필요하지 않습니다.
+
+## 동적 매개변수 {#dynamic-params}
+
+```tsx
+// app/routes/inbox/$threadId.tsx
+import { useParams } from "react-router";
+
+export default function ThreadPage() {
+  const { threadId } = useParams();
+  return <div>Thread: {threadId}</div>;
+}
+```
+
+## 탐색 {#navigation}
+
+클라이언트 측 탐색에는 `<Link>`를 사용하고 프로그래밍 방식 탐색에는 `useNavigate()`를 사용하세요.
+
+```tsx
+import { Link, useNavigate } from "react-router";
+
+// In JSX
+<Link to="/settings">Settings</Link>;
+
+// Programmatic
+const navigate = useNavigate();
+navigate(`/inbox/${threadId}`);
+```
+
+## 다음 단계
+
+- [**Client**](/docs/client) — 에이전트 기반 브라우저 후크 및 유틸리티
+- [**Server**](/docs/server) — 파일 기반 서버 경로 및 `/_agent-native/` 네임스페이스

package/docs/content/locales/ko-KR/sandbox-adapters.md

@@ -0,0 +1,227 @@
+---
+title: "어댑터"
+description: "프레임워크의 두 어댑터 이음새: 샌드박스 어댑터는 에이전트의 실행 코드 도구를 실행하는 백엔드를 교환하고 CLI 어댑터는 에이전트에 명령줄 도구에 대한 구조화된 액세스를 제공합니다."
+search: "어댑터 샌드박스 어댑터 cli 어댑터 실행 코드 SandboxAdapter CliAdapter ShellCliAdapter 내구성 러너 원격 샌드박스 에지 서버리스 child_process"
+---
+
+# 어댑터
+
+> **누구를 위한 것입니까:** 런타임을 확장하는 호스트 작성자. 앱 개발자는 거의 없습니다
+> 이것이 필요합니다. 기본값은 기본적으로 작동합니다.
+
+Agent-Native에는 좁은 뒤에 있는 문제를 고려하는 두 개의 어댑터 이음새가 있습니다.
+교체 가능한 인터페이스:
+
+- **샌드박스 어댑터**는 에이전트의 `run-code` 도구를 실행하는 백엔드를 교체합니다 —
+  기본적으로 로컬 하위 프로세스 또는 Docker/원격/내구성 있는 실행기
+- **CLI 어댑터**는 에이전트에게 명령줄 도구에 대한 구조화된 액세스를 제공합니다.
+  (`gh`, `ffmpeg`, `stripe`) 검색, 가용성 확인 및
+  일관된 결과 형태.
+
+둘 다 하나의 런타임 제약 조건을 공유합니다. 즉, Node.js 시스템 바인딩에 의존하며
+에지/작업자 런타임에서는 실행되지 않습니다. — [Edge and serverless](#edge-serverless)를 참조하세요.
+
+## 어떤 코딩 문서를 원하나요? {#which-doc}
+
+| 당신이 원하는 것은...                                                    | 사용                                         |
+| ------------------------------------------------------------------------ | -------------------------------------------- |
+| 에이전트의 **`run-code` 도구**를 실행하는 백엔드 교체                    | **샌드박스 어댑터**(이 페이지)               |
+| 상담원이 통화할 수 있도록 CLI 도구(`gh`, `ffmpeg`)를 래핑합니다.         | **CLI 어댑터** (이 페이지)                   |
+| Claude-Code/Codex 스타일 **코딩 작업 공간 UI** 렌더링                    | [Agent-Native Code UI](/docs/code-agents-ui) |
+| 자체 루프 + 도구를 사용하여 Claude 코드 / Codex / Pi **에이전트**로 실행 | [Harness Agents](/docs/harness-agents)       |
+
+# 샌드박스 어댑터
+
+`run-code` 도구는 격리된 환경에서 에이전트 제공 JavaScript를 실행합니다. **샌드박스 어댑터**는 에이전트 루프, `run-code.ts`, 로컬 호스트 브리지, 환경 스크럽 또는 출력 형식을 건드리지 않고도 백엔드(기본적으로 로컬 하위 프로세스 또는 Docker/원격/내구성 러너)를 교체할 수 있도록 해당 도구에서 _실행_ 문제를 고려하지 않습니다.
+
+## 이음새가 있는 이유 {#why}
+
+기본 백엔드는 잠긴 로컬 노드 하위 프로세스를 생성합니다. 이는 호스팅 프로세스에 의해 제한됩니다. 호스팅된 플랫폼에서는 에이전트 루프의 소프트 실행 한도(시간 초과/연속 스래시 전 ~40초)를 공유합니다. 원격 또는 내구성이 뛰어난 어댑터는 해당 한도를 초과할 수 있는 수단입니다. 요청 수명 주기와 관계없이 완료될 때까지 대규모 데이터 작업을 실행합니다.
+
+계약을 좁게 유지한다는 것은 원격 어댑터가 동일한 보안 상태를 상속한다는 것을 의미합니다. 상위 프로세스는 비밀이 포함된 모든 것에 대한 소유권을 유지합니다. 즉, 샌드박스 모듈을 빌드하고, localhost 브리지(요청 컨텍스트를 보유하고 호스트 허용 목록 + SSRF 가드를 적용함)를 실행하고, 환경을 스크러빙하고 출력 형식을 지정합니다. 어댑터는 이미 준비된 **비밀이 아닌** 모듈 소스와 리소스 제한만 수신합니다. 어댑터는 이를 *실행*하고 stdout/stderr/exit 상태를 캡처하는 역할만 담당합니다.
+
+```an-diagram title="The parent keeps the secrets; the adapter only runs code" summary="run-code builds the module and runs the loopback bridge; the adapter receives a non-secret module + limits and returns stdout/stderr/exit."
+{
+  "html": "<div class=\"diagram-sandbox\"><div class=\"diagram-box\" data-rough><strong>Parent process</strong><small class=\"diagram-muted\">builds module · loopback bridge · env scrub · output format</small></div><div class=\"diagram-col\"><div class=\"diagram-pill accent\">non-secret module + limits &rarr;</div><div class=\"diagram-pill ok\">&larr; stdout / stderr / exitCode</div><div class=\"diagram-pill\">&harr; bridge calls (127.0.0.1)</div></div><div class=\"diagram-panel center\" data-rough><strong>SandboxAdapter.run</strong><small class=\"diagram-muted\">local child · Docker · remote · durable</small></div></div>",
+  "css": ".diagram-sandbox{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-sandbox .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-sandbox .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## 인터페이스 {#interface}
+
+심은 `packages/core/src/coding-tools/sandbox/` — `adapter.ts`(계약), `index.ts`(선택: `getSandboxAdapter()` / `registerSandboxAdapter()`) 및 `local-child-process-adapter.ts`(기본값)의 코어에 있습니다. `run-code.ts`에 의해 패키지 내로 배선됩니다. 호스트는 `index.ts` 등록 도우미를 통해(또는 Docker 백엔드의 경우 이러한 파일을 직접 편집하는 [blueprint](/docs/blueprint-installer)를 통해) 다른 백엔드에 연결됩니다.
+
+```an-file-tree title="The sandbox seam in core"
+{
+  "title": "packages/core/src/coding-tools/sandbox/",
+  "entries": [
+    { "path": "adapter.ts", "note": "the SandboxAdapter contract (SandboxRunRequest / SandboxRunResult)" },
+    { "path": "index.ts", "note": "selection: getSandboxAdapter() / registerSandboxAdapter()" },
+    { "path": "local-child-process-adapter.ts", "note": "the default backend — locked-down Node child process" },
+    { "path": "../run-code.ts", "note": "wires the seam; never changes when you swap backends" }
+  ]
+}
+```
+
+모든 백엔드는 `SandboxAdapter`를 구현합니다.
+
+```ts
+interface SandboxAdapter {
+  /** Stable id, surfaced for diagnostics and adapter selection. */
+  readonly id: string;
+  /** Execute one prepared sandbox module and capture its output. */
+  run(request: SandboxRunRequest): Promise<SandboxRunResult>;
+}
+```
+
+요청과 결과는 의도적으로 작고 불투명합니다.
+
+```ts
+interface SandboxRunRequest {
+  /**
+   * The complete ESM module source to execute. Already wraps the user's code
+   * and embeds the loopback bridge URL/token; the adapter does NOT parse or
+   * rewrite it.
+   */
+  moduleSource: string;
+  /**
+   * Scrubbed environment — only safe POSIX vars (PATH/HOME/TMPDIR/…), never app
+   * secrets. Adapters must not augment this with the parent's own environment.
+   */
+  env: Record<string, string>;
+  /** Hard wall-clock timeout in milliseconds. The adapter must enforce it. */
+  timeoutMs: number;
+  /**
+   * Loopback port of the parent's bridge server (reachable over 127.0.0.1). A
+   * remote adapter that can't reach the parent's loopback must tunnel or proxy
+   * this to support bridge-backed globals (`appAction`, `providerFetch`, …).
+   */
+  bridgePort: number;
+}
+
+interface SandboxRunResult {
+  stdout: string;
+  stderr: string;
+  /** `0` on clean exit, non-zero on failure, `null` when killed by a signal. */
+  exitCode: number | null;
+  /** True when the run was killed for exceeding `timeoutMs`. */
+  timedOut: boolean;
+}
+```
+
+## 기본값: `LocalChildProcessAdapter` {#default}
+
+기본적으로 `getSandboxAdapter()`는 `LocalChildProcessAdapter`(`id: "local-child-process"`)를 반환합니다. 이는 과거 `run-code` 동작을 바이트 단위로 보존합니다.
+
+- 준비된 모듈 소스는 새로운 임시 디렉토리에 기록됩니다.
+- 하위 항목은 `TMPDIR`/`TEMP`/`TMP`가 샌드박스 디렉터리 내부를 가리키는 스크러빙된 환경(비밀 없음)으로 실행됩니다.
+- 노드 권한 모델을 사용할 수 있는 경우(노드 20의 `--permission` 또는 `--experimental-permission`) 하위 항목은 임시 디렉토리 외부의 파일 시스템 액세스와 하위 프로세스, 작업자 및 기본 애드온이 거부됩니다. 아웃바운드 네트워크는 권한 모델에 의해 차단되지 _않지만_ 하지만 환경 스크럽은 그러한 요청에 자격 증명이 없으며 모든 인증된 호출이 상위 루프백 브리지를 통과함을 의미합니다.
+- 시간 초과로 인해 `SIGTERM`가 전송되고 2초의 유예 기간 후에 `SIGKILL`가 전송됩니다.
+- 임시 파일은 실행 후 최선을 다해 정리됩니다.
+
+> [!WARNING]
+> 기본 어댑터는 에지/작업자 런타임에 존재하지 않는 `node:child_process`를 사용합니다. 표준 Node.js 환경에서 `run-code`를 실행하거나 원격 어댑터를 등록하세요. [Edge and serverless](#edge-serverless)를 참조하세요.
+
+## 어댑터 선택 {#selection}
+
+해결 순서 - 명시적으로 등록된 어댑터가 우선합니다. 그렇지 않으면 env var가 내장된 항목을 선택합니다. 그렇지 않으면 로컬 기본값이 사용됩니다:
+
+```text
+registerSandboxAdapter(adapter)  →  AGENT_NATIVE_SANDBOX  →  local default
+```
+
+### `AGENT_NATIVE_SANDBOX` 환경 변수 {#env}
+
+ID별로 내장 어댑터를 선택합니다. 현재는 `local`(기본값)만 연결되어 있습니다. 알 수 없는 값은 실행에 실패하지 않고 로컬로 대체됩니다.
+
+```bash
+AGENT_NATIVE_SANDBOX=local   # the default — explicit
+```
+
+### `registerSandboxAdapter()` {#register}
+
+호스트 프로세스는 솔기의 `index.ts`를 통한 모든 후속 `run-code` 호출에 대해 백엔드를 재정의합니다. 예를 들어 원격 컨테이너에서 모든 호출을 실행합니다.
+
+```ts
+import {
+  registerSandboxAdapter,
+  type SandboxAdapter,
+} from "./coding-tools/sandbox/index.js";
+
+class RemoteSandboxAdapter implements SandboxAdapter {
+  readonly id = "remote";
+  async run(request) {
+    // Ship request.moduleSource to the durable runner, enforce request.timeoutMs,
+    // proxy bridge calls back to request.bridgePort, and return stdout/stderr/exitCode.
+  }
+}
+
+registerSandboxAdapter(new RemoteSandboxAdapter());
+// Pass `null` to clear the override and fall back to env-var / default resolution.
+```
+
+## 튼튼한 러너를 위한 솔기 {#durable}
+
+이 인터페이스는 의도적으로 미래의 원격/내구성 샌드박스를 위한 이음새입니다. 원격 또는 내구성 있는 어댑터(Docker, Vercel-Sandbox 스타일 실행기 또는 대기 중인 백그라운드 작업자)는 다음을 수행합니다.
+
+1. out-of-process 런타임에 대해 `SandboxAdapter.run`를 구현합니다.
+2. 루프백 브리지(또는 프록시 브리지가 상위 브리지로 다시 호출)를 터널링합니다.
+3. 요청 수명 주기와 관계없이 대규모 데이터 작업을 완료할 수 있습니다. 이는 로컬 하위 프로세스 어댑터를 제한하는 호스팅된 최대 40초 코드 실행 한도를 초과합니다.
+
+새로운 `AGENT_NATIVE_SANDBOX` 값(예: `remote`) 및/또는 `registerSandboxAdapter()`를 통해 등록하세요. 에이전트 루프와 `run-code.ts`는 절대 변경되지 않습니다.
+
+> [!TIP]
+> `agent-native add sandbox docker` 청사진은 이 솔기에 대해 Docker 어댑터를 구현하기 위한 완전하고 독립적인 레시피를 내보냅니다. [Blueprint Installer](/docs/blueprint-installer)를 참조하세요.
+
+# CLI 어댑터
+
+다른 어댑터 이음매는 단일 명령줄 도구(`gh`, `ffmpeg`, `stripe`, `aws`)를 래핑하므로 에이전트는 이를 검색하고 설치 여부를 확인한 후 일관된 stdout/stderr/exit-code 결과로 실행할 수 있습니다. 모든 CLI 어댑터는 `CliAdapter`를 구현합니다:
+
+```ts
+import type { CliAdapter, CliResult } from "@agent-native/core/adapters/cli";
+
+interface CliAdapter {
+  name: string; // "gh", "stripe", "ffmpeg"
+  description: string; // What the agent sees during discovery
+  isAvailable(): Promise<boolean>;
+  execute(args: string[]): Promise<CliResult>;
+}
+
+interface CliResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+```
+
+대부분의 CLI의 경우 `ShellCliAdapter`는 합리적인 기본값으로 바이너리를 래핑하고 `CliRegistry`는 런타임 검색을 위해 어댑터를 수집합니다.
+
+```ts
+import { CliRegistry, ShellCliAdapter } from "@agent-native/core/adapters/cli";
+
+const cliRegistry = new CliRegistry();
+cliRegistry.register(
+  new ShellCliAdapter({
+    command: "gh",
+    description: "GitHub CLI — manage repos, PRs, issues, and releases",
+  }),
+);
+
+await cliRegistry.describe(); // [{ name, description, available }] for discovery
+const gh = cliRegistry.get("gh");
+const result = await gh?.execute(["pr", "list", "--json", "title,url"]);
+```
+
+CLI 호출을 `defineAction`로 래핑하여 작업 표면에 노출합니다. `ShellCliAdapter` 옵션, 사용자 정의 어댑터 및 작업 래핑 패턴에 대한 [CLI Adapters](/docs/cli-adapters) 빠른 참조를 확인하세요.
+
+## 에지 및 서버리스 {#edge-serverless}
+
+> [!WARNING]
+> 두 어댑터 이음매 모두 Node.js 시스템 바인딩을 사용합니다. 샌드박스 `LocalChildProcessAdapter` 및 CLI 어댑터(`ShellCliAdapter` 및 사용자 지정 어댑터)는 Cloudflare Workers 또는 Netlify Edge Functions와 같은 에지/작업자 런타임에 **존재하지 않는** `node:child_process`(`execFile` / `spawn`)를 사용합니다. 이러한 에지 사전 설정에 서버 경로를 배포하는 경우 이러한 어댑터를 실행하면 런타임 예외가 발생합니다. 표준 Node.js 환경(기존 서버 컨테이너 또는 서버리스 노드 기능)에서 어댑터 엔드포인트 및 작업을 실행하거나 샌드박스 솔기의 경우 프로세스에서 벗어난 작업을 제공하는 원격 어댑터를 등록하세요.
+
+## 다음 단계
+
+- [**CLI Adapters**](/docs/cli-adapters) — CLI 솔기에 대한 빠른 참조
+- [**Blueprint Installer**](/docs/blueprint-installer) — `agent-native add sandbox docker`는 Docker 어댑터 레시피를 인쇄합니다.
+- [**Agent Teams**](/docs/agent-teams) — 하위 에이전트에 무거운 작업 위임
+- [**Security**](/docs/security) — 환경 스크럽 및 브리지 허용 목록 상태