@agent-native/core 0.76.5 → 0.76.6

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

@@ -0,0 +1,106 @@
+---
+title: "인루프 프로세서"
+description: "모델의 스트리밍된 출력과 도구 호출을 중간에 관찰하고 중단할 수 있는 루프 내부 관찰자/가드레일 후크 — 실시간 가드레일 및 완료 증명 게이트의 이음매."
+---
+
+# 인루프 프로세서
+
+`Processor`는 에이전트 실행을 위한 루프 내부 **관찰자/가드레일**입니다. 모델의 스트리밍된 출력을 관찰하고 도구는 _실행이 진행됨에 따라_ 요청을 호출하고 자체 스크래치 상태를 유지하며 "완료"가 요청되기 전에 실행을 **중단**할 수 있습니다. 이는 실시간 가드레일(허용되지 않는 출력 미드스트림 차단) 및 완료 증명/커버리지 게이트(모델이 수행할 작업을 검사하고 중지)에 대한 구조적 전제 조건입니다.
+
+```an-diagram title="Where the three hooks fire in the run" summary="processOutputStream watches every chunk, processOutputStep gates tool calls per response, processOutputResult records a verdict at the end. Any hook can abort with a TripWire."
+{
+  "html": "<div class=\"diagram-proc\"><div class=\"diagram-node\" data-rough>stream chunks<br><small class=\"diagram-muted\">processOutputStream</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\" data-rough>per model response<br><small class=\"diagram-muted\">processOutputStep — gate tool calls</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\" data-rough>run end<br><small class=\"diagram-muted\">processOutputResult — verdict</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-pill warn\">abort() &rarr; TripWire &rarr; tripwire event</div></div>",
+  "css": ".diagram-proc{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-proc .diagram-arrow{font-size:22px;line-height:1}.diagram-proc .diagram-pill{flex-basis:100%}"
+}
+```
+
+> [!WARNING]
+> 프로세서는 **구성**이지 도구나 작업이 아니며 저작 DSL도 아닙니다. 프로세서는 자체 스트림 범위 상태와 `abort()`만 관찰하고 변경합니다. 앱 동작을 정의하거나 actions를 대체하거나 모델에 나타나지 않습니다. 앱 작업은 [actions](/docs/actions)에 속합니다.
+
+## 후크 {#hooks}
+
+프로세서는 세 가지 선택적 수명 주기 후크의 하위 집합을 구현합니다(형태는 Mastra의 출력 프로세서에서 차용함).
+
+| 훅                    | 화재…                                                    | 사용 목적…                                             |
+| --------------------- | -------------------------------------------------------- | ------------------------------------------------------ |
+| `processOutputStream` | 모델이 생성되는 동안 스트리밍된 청크당(텍스트/사고 델타) | 완전한 회전이 시작되기 전에 출력에 반응                |
+| `processOutputStep`   | 도구 실행 시 모델 응답당 한 번                           | 모델이 곧 실행될 도구 호출을 검사합니다. 문을 닫으세요 |
+| `processOutputResult` | 실행 종료 시 한 번, 최종 보조 텍스트와 함께              | 완성된 답변에 대한 평결/완료 증거 기록                 |
+
+각 프로세서는 단일 실행 내의 모든 후크 호출에서 지속되고 다른 프로세서의 상태로부터 **격리**되는 자체 변경 가능한 실행 범위 `state` 개체를 가져옵니다.
+
+```ts
+import type { Processor } from "@agent-native/core";
+
+const noSecretsInOutput: Processor = {
+  name: "no-secrets",
+  processOutputStream({ part, abort }) {
+    if (part.type === "text" && /sk-live_/.test(part.text)) {
+      abort("Model attempted to emit a live secret token.", {
+        kind: "secret-leak",
+      });
+    }
+  },
+};
+
+const coverageGate: Processor = {
+  name: "proof-of-done",
+  processOutputStep({ toolCalls, state }) {
+    // Track what the model has actually done this run...
+    for (const call of toolCalls) {
+      (state.ran ??= new Set<string>()).add(call.name);
+    }
+  },
+  processOutputResult({ text, state }) {
+    // ...and record a verdict over the final answer.
+    const ran = state.ran as Set<string> | undefined;
+    state.verdict = ran?.has("run-tests") ? "verified" : "unverified";
+  },
+};
+```
+
+## `TripWire`로 중단 {#tripwire}
+
+후크는 **`TripWire`**를 발생시키는 `abort(reason, meta?)`를 호출하여 실행을 중단합니다. 루프는 이를 포착하고 단일 **`tripwire` 이벤트**를 발생시키고 완전히 중지한 후 최종 보조 메시지로 이유를 표시합니다.
+
+```ts
+import { TripWire } from "@agent-native/core";
+```
+
+`tripwire` 이벤트는 다음을 수행합니다:
+
+| 필드        | 유형     | 참고                                                 |
+| ----------- | -------- | ---------------------------------------------------- |
+| `reason`    | `string` | 사람이 읽을 수 있는 이유가 `abort`에 전달되었습니다. |
+| `processor` | `string` | `name`를 선언할 때 중단된 프로세서의 이름.           |
+
+`TripWire`는 또한 선택적 구조화된 `meta`와 `instanceof`가 확인하는 프로그래밍 방식 소비자에 대한 원래 `processor` 이름을 전달합니다. 중단은 정상적으로 이루어지기 때문에 `processOutputResult`는 (중단된) 최종 텍스트에 대해 계속 실행되므로 실행이 중단된 경우에도 완료 증명 프로세서가 결과를 기록할 수 있습니다.
+
+## 프로세서 배선 {#wiring}
+
+프로세서는 `runAgentLoop`의 `processors` 배열을 통해 코드로 구성됩니다.
+
+```ts
+await runAgentLoop({
+  engine,
+  model,
+  systemPrompt,
+  tools,
+  messages,
+  actions,
+  send,
+  signal,
+  processors: [noSecretsInOutput, coverageGate],
+});
+```
+
+**사용하지 않을 때 오버헤드가 없습니다.** 루프는 하나 이상의 프로세서가 제공되는 경우에만 프로세서 체인을 구축합니다. `processors`가 생략되거나 비어 있으면 이음매 코드가 실행되지 않으며 루프는 바이트 단위로 변경되지 않습니다. 후크는 등록 순서에 따라 실행되며 동기화되거나 비동기화될 수 있습니다.
+
+> [!NOTE]
+> 루프 수준 이음매는 현재 제공 가능하며 하위 에이전트, A2A, MCP 및 테스트에서 직접 호출할 수 있습니다. HTTP 채팅 핸들러를 통해 `processors`를 스레딩하는 것(요청별 확인자가 `runAgentLoop`를 직접 호출하지 않고 구성할 수 있도록)은 아직 연결되지 않은 편리한 배관입니다. 지금은 `runAgentLoop` 호출 사이트에서 프로세서를 구성하세요.
+
+## 관련
+
+- [**Durable Resume**](/docs/durable-resume) — 완료된 부작용을 다시 실행하지 않고 루프가 중단을 견디는 방법
+- [**Custom Agents & Teams**](/docs/agent-teams) — 하위 에이전트는 동일한 루프를 실행하며 자체 프로세서를 보유할 수 있습니다.
+- [**Observability**](/docs/observability) — 실행 추적과 함께 프로세서 결과를 기록합니다.

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

@@ -0,0 +1,199 @@
+---
+title: "진행 상황"
+description: "장기 실행 에이전트 작업에 대한 실시간 진행 신호 — 시작, 업데이트, 완료"
+---
+
+# 진행 상황
+
+긴 상담원 작업이 스피너 뒤에 숨겨서는 안 됩니다. `progress_runs`는 상담원에게 *"작업 중이고 45% 완료되었습니다. 현재 단계는 다음과 같습니다"*를 알릴 수 있는 방법을 제공합니다. 이 단계는 UI가 퍼센트 막대가 있는 부동 실행 트레이로 렌더링됩니다.
+
+```ts
+import {
+  startRun,
+  updateRunProgress,
+  completeRun,
+} from "@agent-native/core/progress";
+
+const run = await startRun({
+  owner: "steve@builder.io",
+  title: "Triage 128 unread emails",
+  step: "Fetching inbox",
+});
+
+for (let i = 1; i <= total; i++) {
+  await updateRunProgress(run.id, run.owner, {
+    percent: Math.round((i / total) * 100),
+    step: `Classifying ${i}/${total}`,
+  });
+}
+
+await completeRun(run.id, run.owner, "succeeded");
+```
+
+[notifications](/docs/notifications)와 별개의 우려 사항: 알림은 한 번 실행되고(_"X가 발생했습니다"_) 진행 상태는 연속 상태입니다(_"X는 45% 완료"_). 두 개의 작성 — `completeRun` 다음에 `notify(..., severity: "info")`가 트레이를 보고 있지 않더라도 작업이 완료되면 사용자에게 알려줍니다.
+
+## 수명주기 {#lifecycle}
+
+| 상태        | 전환                            |
+| ----------- | ------------------------------- |
+| `running`   | 초기 — `startRun`에 의해 설정됨 |
+| `succeeded` | 해피패스 터미널                 |
+| `failed`    | 오류 터미널                     |
+| `cancelled` | 사용자가 방해했습니다           |
+
+```an-diagram title="Run lifecycle" summary="startRun opens a running row; updateRunProgress patches it; completeRun moves it to one terminal status and stamps completed_at."
+{
+  "html": "<div class=\"diagram-run\"><div class=\"diagram-box\" data-rough>startRun()</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel running\" data-rough><span class=\"diagram-pill accent\">running</span><small class=\"diagram-muted\">updateRunProgress() &#8635; percent + step</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col terminal\"><span class=\"diagram-pill ok\">succeeded</span><span class=\"diagram-pill warn\">failed</span><span class=\"diagram-pill\">cancelled</span><small class=\"diagram-muted\">completeRun() &rarr; sets completed_at</small></div></div>",
+  "css": ".diagram-run{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-run .diagram-panel{display:flex;flex-direction:column;gap:6px;padding:12px 16px}.diagram-run .terminal{display:flex;flex-direction:column;gap:6px;align-items:flex-start}.diagram-run .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+종료 상태는 `completed_at`로 설정됩니다. UI 트레이에는 `running` 행만 표시됩니다. 완료된 행은 `action=list` 쿼리에 대해 데이터베이스에 유지됩니다.
+
+## API {#api}
+
+### `startRun(input)` {#start}
+
+런을 생성합니다. 생성된 ID와 함께 전체 `AgentRun`를 반환합니다.
+
+```ts
+const run = await startRun({
+  owner: "steve@builder.io",
+  title: "Ingest 1M rows",
+  step: "Opening CSV",
+  metadata: { jobId: "abc123", artifactPath: "s3://..." },
+});
+```
+
+이벤트 버스에서 `run.progress.started`를 방출합니다.
+
+### `updateRunProgress(id, owner, input)` {#update}
+
+실행 중인 실행의 필드를 패치합니다. 생략된 필드는 변경되지 않습니다.
+
+```ts
+await updateRunProgress(run.id, run.owner, {
+  percent: 75,
+  step: "Writing to target DB",
+});
+```
+
+이벤트 버스에서 `run.progress.updated`를 방출합니다. 실행이 존재하지 않거나 호출자가 소유하지 않은 경우 업데이트된 `AgentRun` 또는 `null`를 반환합니다.
+
+### `completeRun(id, owner, status, extras?)` {#complete}
+
+단말기 상태로 전환됩니다. `succeeded`는 암시적으로 `percent=100`를 설정합니다.
+
+```ts
+await completeRun(run.id, run.owner, "succeeded", {
+  step: "All 1M rows ingested",
+  metadata: { totalDurationMs: 98_123 },
+});
+```
+
+또한 터미널 상태와 함께 `run.progress.updated`를 내보냅니다.
+
+### 목록 {#list}
+
+```ts
+import { listRuns, getRun, deleteRun } from "@agent-native/core/progress";
+
+const active = await listRuns("steve@builder.io", { activeOnly: true });
+const run = await getRun("run-id", "steve@builder.io");
+await deleteRun("run-id", "steve@builder.io");
+```
+
+## HTTP API {#http}
+
+core-routes 플러그인에 의해 `/_agent-native/runs/*`에 마운트되었습니다. **HTTP를 통한 읽기 전용** - 에이전트가 표준 작성자이므로 쓰기는 에이전트 도구를 통해 수행됩니다. 모든 경로는 소유자 범위입니다.
+
+| 방법     | 경로                              |
+| -------- | --------------------------------- |
+| `GET`    | `/_agent-native/runs?active=true` |
+| `GET`    | `/_agent-native/runs/:id`         |
+| `DELETE` | `/_agent-native/runs/:id`         |
+
+```an-api title="List active runs" method="GET" path="/_agent-native/runs"
+{
+  "method": "GET",
+  "path": "/_agent-native/runs",
+  "summary": "List the caller's runs. The RunsTray polls this with active=true.",
+  "description": "Read-only and owner-scoped — every row has an `owner` column and every query filters on it, so callers only ever see their own runs. Writes (start/update/complete) go through the agent's `manage-progress` tool, not HTTP.",
+  "auth": "Session cookie (owner-scoped)",
+  "params": [
+    { "name": "active", "in": "query", "type": "boolean", "required": false, "description": "When true, returns only `running` rows." }
+  ],
+  "responses": [
+    { "status": "200", "description": "Array of AgentRun rows owned by the caller." }
+  ]
+}
+```
+
+## UI 구성 요소 {#ui}
+
+```tsx
+import { RunsTray } from "@agent-native/core/client/progress";
+
+export function HeaderBar() {
+  return (
+    <header className="flex items-center gap-2">
+      {/* … */}
+      <RunsTray />
+    </header>
+  );
+}
+```
+
+인라인 헤더 위젯 - 알림 벨 옆에 마운트합니다. 달리기가 활성화되면 스피너 아이콘 + 카운트 배지를 표시합니다. 클릭하면 실행당 하나의 실시간 백분율 막대가 있는 드롭다운이 열립니다. 활성 실행이 없을 때 트리거를 완전히 숨깁니다. `pollMs`마다 `/_agent-native/runs?active=true`를 폴링합니다(기본값 3초). shadcn 시맨틱 토큰을 사용하고 밝은 테마와 어두운 테마에 맞게 조정됩니다.
+
+## 에이전트 도구 {#agent-tool}
+
+단일 `manage-progress` 도구가 모든 템플릿에 등록됩니다. `action` 매개변수는 작업을 선택합니다:
+
+| 액션       | 목적                                                                 |
+| ---------- | -------------------------------------------------------------------- |
+| `start`    | 긴 작업을 마친 후 전화를 겁니다. runId를 반환합니다.                 |
+| `update`   | `percent` 및/또는 `step`를 사용하여 작업 중에 주기적으로 호출합니다. |
+| `complete` | 터미널 — `succeeded`, `failed`, `cancelled` 중 하나.                 |
+| `list`     | 최근 실행을 검사합니다(`active=true`로 필터링).                      |
+
+### 실행 시작 시기 {#when-to-start}
+
+- ~5초 이상 무엇이든 사용하세요. 맥락이 없는 스피너는 정지된 느낌을 받습니다.
+- 매 반복이 아닌 자연스러운 체크포인트에서 업데이트합니다. 5~10%이면 충분합니다.
+- **항상** 오류 경로를 포함하여 `action=complete`를 사용하여 `manage-progress`를 호출합니다. 고아 `running` 행은 행이 없는 것보다 나쁩니다.
+- 완료 시 `notify`와 페어링하여 사용자가 트레이를 적극적으로 보고 있지 않을 때 결과를 볼 수 있습니다.
+
+## 이벤트 버스 {#event-bus}
+
+[event bus](/docs/automations#event-bus)에서 두 가지 이벤트가 발생합니다:
+
+| 이벤트                 | 페이로드                           |
+| ---------------------- | ---------------------------------- |
+| `run.progress.started` | `{ runId, title, step? }`          |
+| `run.progress.updated` | `{ runId, percent, step, status }` |
+
+[Automations](/docs/automations)는 다음 항목을 구독할 수 있습니다. 예를 들어 _"실행이 5분 이상 걸리면 알려주세요"_:
+
+```yaml
+---
+triggerType: event
+event: run.progress.updated
+condition: "status is failed"
+mode: agentic
+---
+Notify me that run {{runId}} has failed.
+```
+
+## 작동 방식 {#internals}
+
+- **소유자 범위** — 모든 행에는 `owner` 열이 있습니다. 모든 쿼리는 이를 필터링합니다. 사용자는 자신의 달리기만 볼 수 있습니다.
+- **폴링 통합** — 모든 변이는 `recordChange()`를 호출하므로 [`useDbSync`](/docs/client)를 사용하는 템플릿은 추가 배선 없이 자동 무효화됩니다.
+- **테이블 이름** — 프레임워크에는 내부 상담원-채팅 차례 수명 주기 추적을 위한 `agent_runs` 테이블도 있습니다. 진행 프리미티브는 `progress_runs`를 사용하여 두 가지 문제를 별도로 유지합니다.
+- **비율 고정** — 값은 `[0, 100]`로 고정되고 쓰기 시 정수로 반올림됩니다.
+
+## 다음 단계
+
+- [**Notifications**](/docs/notifications) — `manage-progress`(`action=complete`)와 페어링하여 작업이 완료되면 사용자에게 알려줍니다.
+- [**Automations**](/docs/automations) — `run.progress.updated`를 통한 워치독 느린 실행
+- [**Client**](/docs/client) — 실시간 캐시 무효화를 위한 `useDbSync`

package/corpus/core/docs/content/locales/ko-KR/pure-agent-apps.md

@@ -0,0 +1,39 @@
+---
+title: "순수 에이전트 앱"
+description: "에이전트가 전체 제품인 앱: 앱-에이전트 루프가 현관이고 UI는 사람이 필요할 때만 추가됩니다."
+---
+
+# 순수 에이전트 앱
+
+순수 에이전트 앱은 에이전트 네이티브의 최소한의 끝입니다. 앱-에이전트 루프는
+대시보드가 아닌 제품입니다. 터미널, Slack, 이메일, a
+예정된 작업, 다른 상담원 또는 채팅 — "읽지 않은 이메일 요약", "게시
+Slack"에 대한 일일 측정항목 - 에이전트는 어디에서나 작동하고 결과를 반환합니다.
+속합니다. actions, 세션, 앱 상태, 기록 등은 여전히 실제 앱입니다.
+설정, 자격 증명 및 공유 기록은 모두 SQL에 있습니다.
+
+```an-diagram title="The app-agent loop is the front door" summary="Many entry points reach one agent loop over SQL-backed actions and state; results return to wherever the request came from. UI is added only when humans need to supervise."
+{
+  "html": "<div class=\"diagram-pure\"><div class=\"diagram-col\"><div class=\"diagram-pill\">Terminal</div><div class=\"diagram-pill\">Slack · email</div><div class=\"diagram-pill\">Scheduled job</div><div class=\"diagram-pill\">Another agent (A2A)</div><div class=\"diagram-pill\">Chat</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">App-agent loop</span><small class=\"diagram-muted\">actions · sessions · app state in SQL</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Result returns<br><small class=\"diagram-muted\">to where it belongs</small></div></div>",
+  "css": ".diagram-pure{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-pure .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-pure .diagram-arrow{font-size:22px;line-height:1}.diagram-pure .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+작업이 백그라운드에서 실행될 때 이 모양에 도달하면 출력이
+앱, 도메인은 일회성이거나 프로토타입을 만드는 중입니다. 상담원은 여전히 UI가 필요합니다 —
+대시보드가 아니라 사람이 감독하고 구성하고 조종하는 장소 —
+이것이 순수 에이전트 앱조차도 일반적으로 내장된 Chat 셸을 마운트하는 이유입니다.
+
+**헤드리스** 제품 형태입니다. 전체 결정 가이드, 제공되는 내용
+상자, 비계, 저장소 액세스 및 실행 공유가 이제 한 곳에서 제공됩니다.
+
+→ [**Agent Surfaces — Headless agent**](/docs/agent-surfaces#headless)
+
+## 다음 단계
+
+- [**Agent Surfaces — Headless**](/docs/agent-surfaces#headless) — 전체 헤드리스 의사 결정 가이드 및 API
+- [**Getting Started**](/docs/getting-started) — 채팅 앱이나 헤드리스 에이전트를 먼저 생성
+- [**Dispatch**](/docs/template-dispatch) — 훌륭한 순수 에이전트 시작점이 되는 작업 공간 템플릿
+- [**Messaging the agent**](/docs/messaging) — 사용자가 웹, Slack, 텔레그램, 이메일을 통해 에이전트와 대화하는 방법
+- [**Recurring Jobs**](/docs/recurring-jobs) — 에이전트가 자체적으로 실행되는 예약된 프롬프트
+- [**Actions**](/docs/actions) — 순수 에이전트가 호출할 도구