@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/ko-KR/native-chat-ui.md

@@ -0,0 +1,321 @@
+---
+title: "기본 채팅 UI"
+description: "액션 선언 기본 채팅 렌더러, 재사용 가능한 DataTable/DataChart 출력, BYO 에이전트 런타임이 Agent-Native 채팅에 연결되는 방법"
+---
+
+# 기본 채팅 UI
+
+기본 채팅 UI는 자사 에이전트 출력을 위한 인앱 렌더링 경로입니다. 안
+액션은 구조화된 JSON를 반환하고 채팅 런타임은 명시적인 위젯을 인식합니다.
+판별하고 `<AssistantChat>`는
+대화.
+일반 앱 채팅.
+
+사용자가 에이전트가 있는 출력을 검사해야 하는 경우 기본 채팅 UI를 사용하세요.
+이미 말하고 있습니다: 쿼리 결과, 응답 통찰력, 설정 요약
+승인/거부 제어 또는 앱 보기 링크. [MCP Apps](/docs/mcp-apps) 사용
+Claude, ChatGPT, Copilot 또는 Cursor와 같은 외부 호스트가 렌더링되어야 하는 경우
+앱의 인라인 경로
+
+```an-diagram title="The native render path" summary="An action returns JSON; the runtime matches an explicit widget discriminant or chatUI.renderer; AssistantChat mounts a real React component. No iframe, no HTML execution."
+{
+  "html": "<div class=\"diagram-render\"><div class=\"diagram-node\">Action runs<br><small class=\"diagram-muted\">returns structured JSON</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\">Match</span><small class=\"diagram-muted\">explicit widget &middot; chatUI.renderer</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">&lt;AssistantChat&gt;<br><small class=\"diagram-muted\">mounts a React widget</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card col\"><div class=\"diagram-pill ok\">DataTable</div><div class=\"diagram-pill ok\">DataChart</div><div class=\"diagram-pill ok\">DataInsights</div></div></div>",
+  "css": ".diagram-render{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-render .center{display:flex;flex-direction:column;align-items:center;gap:4px;padding:14px}.diagram-render .col{display:flex;flex-direction:column;gap:6px;padding:12px}.diagram-render .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## 작업 선언 위젯 {#action-declared-widgets}
+
+기본 경로에는 명시적인 두 부분이 있습니다:
+
+- `outputSchema`는 작업의 응답 형태를 검증합니다.
+- `chatUI.renderer`는 검증된 결과에 대해 기본 React 렌더러를 선택합니다.
+
+내장 데이터 렌더러는 `widget`와 함께 일반 JSON 결과를 사용합니다.
+일치하는 페이로드:
+
+| 위젯              | 필수 페이로드                 | 렌더링 형식                            |
+| ----------------- | ----------------------------- | -------------------------------------- |
+| `"data-table"`    | `table`                       | 재사용 가능한 기본 데이터 테이블       |
+| `"data-chart"`    | `chartSeries`                 | 기본 막대, 선 또는 영역 차트           |
+| `"data-insights"` | `table` 및/또는 `chartSeries` | 차트/표 출력이 포함된 통합 통찰력 카드 |
+
+서버 actions는 다음에서 서버 안전 도우미와 스키마를 가져와야 합니다.
+`@agent-native/core/data-widgets`; 클라이언트 코드는
+`@agent-native/core/client/chat` 또는 `@agent-native/core/client`.
+
+```ts
+import { defineAction } from "@agent-native/core/action";
+import { ACTION_CHAT_UI_DATA_INSIGHTS_RENDERER } from "@agent-native/core/action-ui";
+import {
+  createDataInsightsWidgetResult,
+  dataInsightsWidgetResultSchema,
+} from "@agent-native/core/data-widgets";
+
+export default defineAction({
+  description: "Analyze form responses.",
+  readOnly: true,
+  outputSchema: dataInsightsWidgetResultSchema,
+  chatUI: {
+    renderer: ACTION_CHAT_UI_DATA_INSIGHTS_RENDERER,
+    title: "Response insights",
+  },
+  run: async () =>
+    createDataInsightsWidgetResult({
+      title: "Response insights",
+      display: {
+        title: "42 responses",
+        description: "Completion rate rose this week.",
+        primaryAction: {
+          label: "Open response insights",
+          href: "/response-insights",
+        },
+      },
+      chartSeries: {
+        type: "bar",
+        title: "Responses by day",
+        xKey: "day",
+        series: [{ key: "responses", label: "Responses" }],
+        data: [
+          { day: "Mon", responses: 8 },
+          { day: "Tue", responses: 13 },
+        ],
+      },
+      table: {
+        title: "Top answers",
+        columns: [
+          { key: "answer", label: "Answer" },
+          { key: "count", label: "Count", align: "right" },
+        ],
+        rows: [
+          { answer: "Yes", count: 31 },
+          { answer: "No", count: 11 },
+        ],
+        totalRows: 2,
+      },
+    }),
+});
+```
+
+```an-callout
+{
+  "tone": "success",
+  "body": "The renderer only takes over when the action declares `chatUI` **or** the result carries an explicit known `widget` discriminant. It never shape-infers arbitrary objects and never executes HTML or JavaScript from tool results — so a native widget can't become an injection vector."
+}
+```
+
+사용자가 차트, 그래프, 표, 추세 또는 요약 보고서를 요청하면 앱 에이전트
+은 이러한 기본 렌더러 중 하나를 선언하는 작업을 선호해야 합니다. 결승전
+보조 텍스트는 간략하게 유지되어야 하며 위젯이 데이터를 전달할 수 있도록 해야 합니다. 복사하지 마세요
+사용자가 명시적으로 텍스트를 요청하지 않는 한 마크다운 테이블에 동일한 행
+내보내기.
+
+도메인 작업이 없지만 에이전트가 이미 압축을 검색한 경우
+truthful data, it can call the framework `render-data-widget` action with the
+동일한 `data-table`, `data-chart` 또는 `data-insights` JSON 모양. 이 작업만
+위젯을 검증하고 렌더링합니다. 이는 데이터 소스가 아니므로 사용해서는 안 됩니다.
+자리표시자 측정항목을 고안합니다.
+
+## DataTable 출력 {#data-table}
+
+`table`는 의도적으로 단순하므로 actions 목록, SQL, 분석 및 설정이 가능합니다.
+재사용:
+
+```ts
+{
+  title?: string;
+  columns: Array<{ key: string; label: string; align?: "left" | "right" }>;
+  rows: Array<Record<string, unknown>>;
+  totalRows?: number;
+  sampledRows?: number;
+  truncated?: boolean;
+}
+```
+
+안정적인 열 키와 JSON-안전한 행 값을 선호하세요. `totalRows`를 사용하세요,
+`sampledRows` 및 `truncated` 작업이 더 큰 조각을 표시할 때
+결과 세트.
+
+## DataChart 출력 {#data-chart}
+
+`chartSeries`는 상담원 답변에 사용되는 일반적인 차트 모양을 지원합니다.
+각 템플릿이 자체 채팅 렌더러를 제공하도록 요구:
+
+```ts
+{
+  type: "bar" | "line" | "area";
+  title?: string;
+  xKey: string;
+  series: Array<{ key: string; label: string; color?: string }>;
+  data: Array<Record<string, unknown>>;
+  sampled?: boolean;
+}
+```
+
+차트 데이터를 간결하게 유지하세요. 대규모 데이터 세트의 경우 작업 및 링크로 집계
+`display.primaryAction` 또는 작업 `link` 메타데이터를 사용하여 전체 앱 보기
+
+## 네이티브 위젯과 MCP 앱 {#native-vs-mcp-apps}
+
+기본 채팅 위젯과 MCP 앱은 상호 보완적입니다.
+
+- **네이티브 위젯**은 앱의 자체 채팅 런타임을 위한 것입니다. 조치 결과는
+  JSON, 프레임워크는 내장된 React 위젯을 렌더링합니다.
+- **MCP 앱**은 외부 호스트용입니다. 이 작업은 `mcpApp`를 선언하며 일반적으로
+  `link`, 호스트는 지원되는 경우 실제 앱 경로를 인라인으로 렌더링합니다.
+- **딥 링크**는 범용 폴백으로 남아 있습니다. `link` 동작을 사용하거나
+  `display.primaryAction` 그래서 CLI 클라이언트, 이전 MCP 호스트 및 일반 기록
+  독자는 전체 앱 보기를 열 수 있습니다.
+
+네이티브 위젯 페이로드와 MCP 앱 메타데이터가 모두 존재하는 경우 인앱
+채팅은 기본 위젯을 선호합니다. 외부 호스트는 MCP 앱 리소스 또는
+딥 링크 대체.
+
+## 사용자 정의 네이티브 렌더러 {#custom-native-renderers}
+
+정확한 렌더러 ID로 제품별 구성요소를 등록한 후 해당 ID를 선언하세요.
+작업 중:
+
+```tsx
+import { registerActionChatRenderer } from "@agent-native/core/client/chat";
+
+registerActionChatRenderer({
+  id: "crm.deal-card",
+  renderer: "crm.deal-card",
+  Component: ({ context }) => <DealCard result={context.resultJson} />,
+});
+```
+
+```ts
+export default defineAction({
+  description: "Show a deal card.",
+  outputSchema: dealCardSchema,
+  chatUI: { renderer: "crm.deal-card" },
+  run: async () => ({ dealId: "deal_123", amount: 42000 }),
+});
+```
+
+자사 앱 UI에 사용하세요. `mcpApp`에 크로스 호스트 iframe UI를 유지하고
+채팅에서 원시 SQL가 아닌 입력된 읽기 actions 뒤에 임의 쿼리가 실행됩니다.
+
+## BYO 에이전트 런타임 {#byo-agent-runtimes}
+
+`AgentChatRuntime`는 채팅 셸을 위한 자체 에이전트 가져오기 계약이며,
+이 섹션은 표준 참조입니다. 다른 곳에서 구축한 에이전트를 사용할 수 있습니다
+정규화된 이벤트를 Agent-Native의 대화 UI로 스트리밍하면서
+공유 작성기, 성적표 렌더링, 도구 카드, 승인, 기본 위젯
+및 주변 앱 레이아웃. [Drop-in Agent](/docs/drop-in-agent#custom-chat-ui)
+런타임 스토리 및 [Component API](/docs/components#agent-chat-ui)에 대한 튜토리얼 포인트
+가져오기 경로와 함께 각 커넥터와 어댑터를 나열합니다. 계약 자체는
+아래에 설명되어 있습니다.
+
+```an-diagram title="BYO runtime keeps the Agent-Native chat shell" summary="Your external agent streams normalized events through a connector; Agent-Native keeps the composer, transcript, tool cards, approvals, and native widgets."
+{
+  "html": "<div class=\"diagram-byo\"><div class=\"diagram-box\" data-rough>Your agent<br><small class=\"diagram-muted\">OpenAI &middot; Claude &middot; Vercel AI &middot; AG-UI &middot; HTTP</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">connector</span><small class=\"diagram-muted\">normalized message-* / tool-* events</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card col\"><div class=\"diagram-pill\">&lt;AssistantChat runtime=&hellip; /&gt;</div><small class=\"diagram-muted\">composer &middot; transcript &middot; tool cards</small><small class=\"diagram-muted\">approvals &middot; native widgets</small></div></div>",
+  "css": ".diagram-byo{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-byo .center{display:flex;flex-direction:column;align-items:center;gap:4px;padding:14px}.diagram-byo .col{display:flex;flex-direction:column;gap:6px;padding:14px}.diagram-byo .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+모든 커넥터는 `@agent-native/core/client/chat`(및 루트)에서 내보내집니다.
+`@agent-native/core/client` 항목). 에이전트가 작동할 때 일반 HTTP 런타임을 사용하세요.
+SSE 또는 NDJSON 런타임 이벤트를 반환하는 POST 엔드포인트를 노출할 수 있습니다.
+
+```tsx
+import {
+  AssistantChat,
+  createHttpAgentChatRuntime,
+} from "@agent-native/core/client/chat";
+
+const runtime = createHttpAgentChatRuntime({
+  id: "external:mastra",
+  label: "Mastra",
+  endpoint: "/api/mastra/chat",
+  headers: async () => ({
+    Authorization: `Bearer ${await getAgentToken()}`,
+  }),
+});
+
+export function SupportChat() {
+  return <AssistantChat runtime={runtime} threadId="support" />;
+}
+```
+
+엔드포인트가 이미 일반 에이전트 프로토콜을 스트리밍하는 경우 일치하는 프로토콜을 사용하세요.
+커넥터를 연결하고 사용자 정의 매퍼 작성을 건너뜁니다.
+
+```ts
+import {
+  createAgUiChatRuntime,
+  createClaudeAgentChatRuntime,
+  createOpenAIAgentsChatRuntime,
+  createOpenAIResponsesChatRuntime,
+  createVercelAiChatRuntime,
+} from "@agent-native/core/client/chat";
+
+const openAiAgentsRuntime = createOpenAIAgentsChatRuntime({
+  endpoint: "/api/openai-agents/chat",
+});
+
+const openAiResponsesRuntime = createOpenAIResponsesChatRuntime({
+  endpoint: "/api/openai-responses/chat",
+});
+
+const claudeAgentRuntime = createClaudeAgentChatRuntime({
+  endpoint: "/api/claude-agent/chat",
+});
+
+const vercelAiRuntime = createVercelAiChatRuntime({
+  endpoint: "/api/vercel-ai/chat",
+});
+
+const agUiRuntime = createAgUiChatRuntime({
+  endpoint: "/api/ag-ui/chat",
+});
+```
+
+엔드포인트는 정규화된 이벤트 형태를 직접 스트리밍할 수 있습니다.
+
+```text
+data: {"type":"message-start","message":{"id":"m1","role":"assistant","content":[]}}
+data: {"type":"message-delta","messageId":"m1","delta":{"type":"text","text":"Hello"}}
+data: {"type":"tool-start","toolCall":{"id":"t1","name":"query","input":{"q":"forms"}}}
+data: {"type":"tool-done","toolCallId":"t1","toolName":"query","status":"completed","resultText":"34 rows"}
+data: {"type":"done","reason":"complete"}
+```
+
+매우 간단한 에이전트의 경우 JSON 응답 `{ "text": "..." }`가 허용되며
+단일 보조 메시지로 변환됩니다. 더 풍부한 상담원을 위해 스트리밍
+`message-*`, `tool-*`, `approval-request`, `status`, `artifact`, `file`,
+`usage`, `error` 및 `done` 이벤트. 도구 결과에는 `mcpApp` 또는
+`chatUI` 메타데이터이므로 작업으로 선언된 기본 위젯은 여전히 메타데이터 없이 렌더링됩니다.
+iframe.
+
+내장된 Agent-Native 전송을 런타임 개체로 사용하려면 다음을 사용하세요.
+
+```ts
+import { createAgentNativeChatRuntime } from "@agent-native/core/client/chat";
+
+const runtime = createAgentNativeChatRuntime({
+  threadId: "forms-chat",
+  mode: "act",
+});
+```
+
+전체가 필요할 때만 `<AssistantChat createAdapter={...} />`를 사용하세요
+assistant-ui 어댑터 제어. 제품을 사용할 때 `PromptComposer`만 사용하세요.
+외부 녹취록 전체를 소유하고 있으며 Agent-Native의 작곡가만 원합니다
+필드.
+
+OpenAI, AG-UI, Claude 에이전트 SDK 및 Vercel AI SDK 스트림은 표준을 사용할 수 있습니다.
+커넥터 도우미. ACP는 코딩 에이전트/편집기 상호 운용성을 유지하지만
+최종 사용자를 위한 일반 앱 채팅 런타임. A2UI는 여기서 지원되지 않습니다.
+성숙해지면 동일한 명시적 런타임/위젯 계약에 적응해야 합니다.
+
+## 관련 문서 {#related-docs}
+
+- [Actions](/docs/actions) — 기본 위젯 데이터를 반환하는 작업을 정의합니다.
+- [Agent Surfaces](/docs/agent-surfaces) — 헤드리스, 채팅, 사이드카 또는 전체 앱이 필요한지 결정하세요.
+- [Drop-in Agent](/docs/drop-in-agent) — 표준 채팅 런타임 마운트를 위한 튜토리얼
+- [Component API](/docs/components) — 채팅 레이어, 런타임 및 도구 렌더러를 위한 내보내기별 API 맵입니다.
+- [MCP Apps](/docs/mcp-apps) — 외부 MCP 호스트를 위한 인라인 UI.
+- [Key Concepts](/docs/key-concepts#protocols) — 프로토콜 상태 및 위치 지정.

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

@@ -0,0 +1,231 @@
+---
+title: "알림"
+description: "플러그인 가능한 채널이 포함된 인앱 알림(받은 편지함, 웹훅 또는 사용자 정의)"
+---
+
+# 알림
+
+하나의 기능, 다양한 목적지. 서버측 코드(액션, 자동화, 플러그인)에서 `notify()`를 호출하면 이벤트가 사용자의 인앱 받은 편지함에 도착하고 등록된 모든 채널로 전달됩니다. 호스트 템플릿이 헤더에 드롭되는 벨 앤 드롭다운 UI 구성 요소와 함께 제공됩니다.
+
+알림은 앱의 벨 받은 편지함에 대한 단방향 경고입니다(웹후크 팬아웃 포함). Slack/email/Telegram/WhatsApp에서 상담원과 *대화*하려면 [Messaging](/docs/messaging)를 참조하세요.
+
+```ts
+import { notify } from "@agent-native/core/notifications";
+
+await notify(
+  { severity: "info", title: "Booking confirmed", body: "Jane at 3pm" },
+  { owner: "steve@builder.io" },
+);
+```
+
+```an-diagram title="One call, many destinations" summary="notify() always writes the owner-scoped inbox row, fans out to every registered channel in parallel (best-effort), then emits notification.sent on the event bus."
+{
+  "html": "<div class=\"diagram-notify\"><div class=\"diagram-node\">notify(input, { owner })<br><small class=\"diagram-muted\">any server code &middot; action, automation, plugin</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel fan\" data-rough><div class=\"fan-row\"><span class=\"diagram-pill accent\">inbox</span><div class=\"diagram-box\" data-rough>notifications table &rarr; bell UI<br><small class=\"diagram-muted\">always on &middot; owner-scoped</small></div></div><div class=\"fan-row\"><span class=\"diagram-pill\">webhook</span><div class=\"diagram-box\" data-rough>POST JSON to NOTIFICATIONS_WEBHOOK_URL<br><small class=\"diagram-muted\">best-effort</small></div></div><div class=\"fan-row\"><span class=\"diagram-pill\">custom</span><div class=\"diagram-box\" data-rough>registerNotificationChannel(...)<br><small class=\"diagram-muted\">best-effort &middot; runs in parallel</small></div></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill ok\">notification.sent</span><small class=\"diagram-muted\">event bus &middot; automations can chain</small></div></div>",
+  "css": ".diagram-notify{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-notify .fan{display:flex;flex-direction:column;gap:10px;padding:14px}.diagram-notify .fan-row{display:flex;align-items:center;gap:10px}.diagram-notify .diagram-card{display:flex;flex-direction:column;gap:6px;padding:12px 14px}.diagram-notify .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## 심각도 {#severities}
+
+| 심각도     | 사용                         |
+| ---------- | ---------------------------- |
+| `info`     | 확인, 진행 이정표, FYI       |
+| `warning`  | 사용자가 곧 살펴봐야 할 사항 |
+| `critical` | 즉각적인 주의가 필요합니다   |
+
+심각도는 드롭다운의 배지 스타일을 결정하고 긴급 상황에 따라 분기할 수 있도록 채널로 전달됩니다.
+
+## 내장 채널 {#channels}
+
+| 채널      | 배달                                              | 필수                                                            |
+| --------- | ------------------------------------------------- | --------------------------------------------------------------- |
+| `inbox`   | `notifications` 테이블에 유지됩니다. 종 UI를 운전 | 항상 켜짐 — 기본 요소의 일부.                                   |
+| `webhook` | POST JSON를 구성된 URL로                          | 시작 시 `NOTIFICATIONS_WEBHOOK_URL` 환경 변수가 설정되었습니다. |
+
+웹훅 채널은 소유자의 임시 [secrets](/docs/security)에 대해 URL 및 `NOTIFICATIONS_WEBHOOK_AUTH` 모두에서 `${keys.NAME}` 참조를 확인하므로 원시 값이 에이전트의 컨텍스트에 입력되지 않습니다. 키별 URL 허용 목록이 시행됩니다. 이는 자동화 `web-request` 도구에서 사용하는 것과 동일한 규칙입니다.
+
+```an-diagram title="Channels and severity" summary="inbox is always on; webhook needs an env var; custom channels register at startup. Severity drives badge styling and is passed through to every channel."
+{
+  "html": "<div class=\"diagram-channels\"><div class=\"diagram-panel col\" data-rough><strong>Channels</strong><div class=\"diagram-box\" data-rough>inbox<br><small class=\"diagram-muted\">always on &mdash; part of the primitive</small></div><div class=\"diagram-box\" data-rough>webhook<br><small class=\"diagram-muted\">needs NOTIFICATIONS_WEBHOOK_URL</small></div><div class=\"diagram-box\" data-rough>custom<br><small class=\"diagram-muted\">registerNotificationChannel()</small></div></div><div class=\"diagram-panel col\" data-rough><strong>Severity drives the badge</strong><div class=\"sev-row\"><span class=\"diagram-pill\">info</span><span class=\"diagram-muted\">confirmations, FYI</span></div><div class=\"sev-row\"><span class=\"diagram-pill warn\">warning</span><span class=\"diagram-muted\">look at soon</span></div><div class=\"sev-row\"><span class=\"diagram-pill accent\">critical</span><span class=\"diagram-muted\">needs immediate attention</span></div></div></div>",
+  "css": ".diagram-channels{display:flex;gap:16px;flex-wrap:wrap;align-items:flex-start}.diagram-channels .col{display:flex;flex-direction:column;gap:10px;padding:14px;min-width:240px}.diagram-channels .sev-row{display:flex;align-items:center;gap:10px}"
+}
+```
+
+## API {#api}
+
+### `notify(input, meta)` {#notify}
+
+알림을 전달합니다. 명시적으로 제외되지 않는 한 항상 받은 편지함에 유지됩니다. 추가로 등록된 채널은 최선을 다해 병렬로 실행됩니다.
+
+```ts
+await notify(
+  {
+    severity: "critical",
+    title: "Database offline",
+    body: "Primary dropped connections",
+    metadata: { runbookUrl: "https://runbooks/db-offline" },
+    channels: ["inbox", "webhook"], // optional allowlist; omit to run all
+  },
+  { owner: "ops@company.com" },
+);
+```
+
+`meta.owner`가 필요합니다. 사용자만 벨에서 알림을 볼 수 있도록 알림 범위를 지정합니다.
+
+### `registerNotificationChannel(channel)` {#register}
+
+모든 서버 플러그인에서 맞춤 채널을 등록하세요.
+
+```ts
+import { registerNotificationChannel } from "@agent-native/core/notifications";
+
+registerNotificationChannel({
+  name: "slack-ops",
+  async deliver(input, meta) {
+    await fetch(process.env.OPS_SLACK_WEBHOOK!, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        text: `*${input.severity.toUpperCase()}* — ${input.title}\n${input.body ?? ""}`,
+        owner: meta.owner,
+      }),
+    });
+  },
+});
+```
+
+채널 이름은 고유합니다. 다시 등록하면 이전 채널이 대체됩니다. `deliver()`는 최선의 노력입니다. 던지기는 오류를 기록하지만 다른 채널이나 받은 편지함 행을 차단하지는 않습니다.
+
+### 목록 및 읽기 {#read}
+
+```ts
+import {
+  listNotifications,
+  countUnread,
+  markNotificationRead,
+  markAllNotificationsRead,
+  deleteNotification,
+} from "@agent-native/core/notifications";
+
+const rows = await listNotifications("steve@builder.io", {
+  unreadOnly: true,
+  limit: 50,
+});
+const unread = await countUnread("steve@builder.io");
+await markNotificationRead(rows[0].id, "steve@builder.io");
+await markAllNotificationsRead("steve@builder.io");
+await deleteNotification(rows[0].id, "steve@builder.io");
+```
+
+각 기능은 소유자 범위로, 사용자 간 읽기, 사용자 간 쓰기가 불가능합니다.
+
+## NotificationChannel 인터페이스 {#channel-interface}
+
+```ts
+interface NotificationChannel {
+  name: string;
+  deliver(
+    input: NotificationInput,
+    meta: NotificationMeta,
+  ): void | Promise<void>;
+}
+
+interface NotificationInput {
+  severity: "info" | "warning" | "critical";
+  title: string;
+  body?: string;
+  metadata?: Record<string, unknown>;
+  channels?: string[];
+}
+
+interface NotificationMeta {
+  owner: string;
+}
+```
+
+## HTTP API {#http}
+
+core-routes 플러그인에 의해 `/_agent-native/notifications/*`에 마운트되었습니다. 모든 경로의 범위는 인증된 세션의 이메일로 지정됩니다.
+
+| 방법     | 경로                                                |
+| -------- | --------------------------------------------------- |
+| `GET`    | `/_agent-native/notifications?unread=true&limit=50` |
+| `GET`    | `/_agent-native/notifications/count`                |
+| `POST`   | `/_agent-native/notifications/:id/read`             |
+| `POST`   | `/_agent-native/notifications/read-all`             |
+| `DELETE` | `/_agent-native/notifications/:id`                  |
+
+```an-api title="List notifications" summary="The route behind listNotifications() — scoped to the authenticated session's email."
+{
+  "method": "GET",
+  "path": "/_agent-native/notifications?unread=true&limit=50",
+  "summary": "List recent notifications for the current user",
+  "auth": "Authenticated session; results are scoped to the session's email.",
+  "params": [
+    { "name": "unread", "in": "query", "type": "boolean", "required": false, "description": "When true, returns only unread notifications." },
+    { "name": "limit", "in": "query", "type": "number", "required": false, "description": "Max rows to return." }
+  ],
+  "responses": [
+    { "status": "200", "description": "Owner-scoped notification rows, newest first." }
+  ]
+}
+```
+
+## UI 구성 요소 {#ui}
+
+```tsx
+import { NotificationsBell } from "@agent-native/core/client/notifications";
+
+export function HeaderBar() {
+  return (
+    <header className="flex items-center gap-2">
+      {/* … */}
+      <NotificationsBell browserNotifications />
+    </header>
+  );
+}
+```
+
+읽지 않은 배지가 있는 종 모양 아이콘. 클릭하면 최근 알림 드롭다운이 열립니다. shadcn 시맨틱 토큰을 사용하고 호스트 템플릿의 밝은/어두운 테마에 적응합니다.
+
+`browserNotifications`를 전달하여 읽지 않은 모든 새 항목에 대해 시스템 `new Notification(...)` 팝업도 실행합니다. 이는 사용자 탭이 백그라운드에 있을 때 유용합니다. 드롭다운은 사용자가 권한을 부여할 때까지 "활성화" 프롬프트를 렌더링합니다. 알림 `tag` 필드를 통해 ID별로 중복이 방지됩니다.
+
+## 에이전트 도구 {#agent-tools}
+
+단일 `manage-notifications` 도구가 모든 템플릿에 등록됩니다. `action` 매개변수는 작업을 선택합니다:
+
+| 액션   | 매개변수                                                              | 목적                                            |
+| ------ | --------------------------------------------------------------------- | ----------------------------------------------- |
+| `send` | `severity` (필수), `title` (필수), `body`, `metadataJson`, `channels` | 사용자의 받은편지함과 등록된 채널에 알림 보내기 |
+| `list` | `unreadOnly`, `limit` (최대 200, 기본값 20)                           | 컨텍스트에 대한 최근 알림 나열                  |
+
+자동화([Automations](/docs/automations) 참조)는 본문에 `action=send`가 포함된 `manage-notifications`를 호출할 수 있습니다. 이는 외부 이벤트를 사용자가 볼 수 있는 경고로 전환하는 표준 패턴입니다.
+
+## 이벤트 버스 {#event-bus}
+
+모든 성공적인 전달은 [event bus](/docs/automations#event-bus)에서 `notification.sent`를 방출합니다:
+
+```json
+{
+  "notificationId": "n-123",
+  "severity": "critical",
+  "title": "DB offline",
+  "body": "Primary dropped connections",
+  "deliveredChannels": ["inbox", "webhook"]
+}
+```
+
+자동화로 이를 차단할 수 있습니다. _"중요한 알림이 발생하면 호출도 진행됩니다."_
+
+## 작동 방식 {#internals}
+
+- **소유자 범위** — 모든 행에는 `owner` 열이 있습니다. 모든 쿼리는 이를 필터링합니다. 모든 경로는 인증된 세션의 이메일을 사용합니다. 사용자는 서로의 알림을 볼 수 없습니다.
+- **폴 통합** — 모든 변이는 `recordChange()`를 호출하므로 [`useDbSync`](/docs/client)를 사용하는 템플릿은 추가 배선 없이 자동 무효화됩니다.
+- **최선의 팬아웃** — 채널 오류가 포착되어 기록됩니다. 하나의 실패한 채널이 다른 채널이나 받은편지함 쓰기를 차단하지 않습니다.
+- **Fire-and-forget** — 받은 편지함 쓰기가 완료된 후 `notify()`가 반환됩니다. 맞춤 채널은 백그라운드에서 실행됩니다.
+
+## 다음 단계
+
+- [**Automations**](/docs/automations) — `notify()`의 가장 일반적인 호출자
+- [**Security**](/docs/security) — 웹훅 채널을 구동하는 `${keys.NAME}` 대체
+- [**Server plugins**](/docs/server) — 시작 시 맞춤 채널이 등록되는 곳