@agent-native/core 0.88.0 → 0.90.2

package/corpus/core/docs/content/locales/ko-KR/data-programs.mdx

@@ -0,0 +1,329 @@
+---
+title: "데이터 프로그램"
+description: "에이전트가 작성하고 저장한 JS 스크립트로, 서버 측에서 데이터를 가져오고 조인하고 집계하며, SQL에 캐시되고 dashboard 패널에 의해 렌더링됩니다 — 일회성 run-code 쿼리와 하드코딩된 provider action 사이의 실시간 데이터 절충안입니다."
+search: "data program emit rows schema providerFetch dashboard panel program source refresh TTL viewer-scoped cache save-data-program run-data-program"
+---
+
+# 데이터 프로그램
+
+**데이터 프로그램(data program)**은 이름이 지정되고 저장된, 에이전트가 작성한 JS 스크립트로, 데이터를 가져오고, 조인하고, 필터링하거나 집계합니다 — `providerFetch` / `providerFetchAll` / `providerSearchAll`을 통한 provider API, `appAction`을 통한 app 데이터, 또는 Resources 기반 workspace 파일을 사용하며, 결과와 함께 `emit(rows, schema)`를 정확히 한 번 호출합니다. 결과는 SQL에 캐시되며, 어떤 차트/테이블 컴포넌트든 이를 렌더링할 수 있고, 페이지 뷰마다가 아니라 여러분이 선택한 정책에 따라 갱신됩니다.
+
+[`run-code`](/docs/actions)가 사용 가능한 곳이라면 어디서든 자동으로 사용할 수 있습니다 — app별로 마운트하거나 설정할 필요가 없습니다. 여러분의 app에 이미 run-code가 활성화되어 있다면, `save-data-program`, `preview-data-program`, `run-data-program`, `list-data-programs`, `get-data-program`, `delete-data-program`은 이미 등록된 actions입니다.
+
+<Diagram id="doc-block-dp-overview" title={"일회성 쿼리에서 실시간 패널로"} summary={"run-code 스크립트는 emit()을 호출하는 순간 저장된 프로그램이 됩니다. 어떤 dashboard 패널이든 여기에 바인딩할 수 있으며, 이후 캐시/갱신 정책이 이어받습니다."}>
+
+```html
+<div class="dp-flow">
+  <div class="diagram-card" data-rough>
+    <span class="diagram-pill">run-code script</span
+    ><small class="diagram-muted">providerFetch, joins, aggregation</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-panel">
+    <span class="diagram-pill accent">emit(rows, schema)</span
+    ><small class="diagram-muted"
+      >save-data-program dry-runs, then persists</small
+    >
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-box" data-rough>
+    data_program_runs<br /><small class="diagram-muted"
+      >cached per (program, params, viewer)</small
+    >
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-card">
+    <span class="diagram-pill">대시보드 패널</span
+    ><small class="diagram-muted"><code>source: "program"</code></small>
+  </div>
+</div>
+```
+
+```css
+.dp-flow {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  flex-wrap: wrap;
+}
+.dp-flow .diagram-card,
+.dp-flow .diagram-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 14px 16px;
+  min-width: 180px;
+}
+.dp-flow .diagram-arrow {
+  font-size: 20px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+## 이것이 존재하는 이유 {#why}
+
+저장된 데이터 프로그램이 없으면, "X의 실시간 뷰를 만들기"는 대개 두 가지 나쁜 결말 중 하나로 끝나곤 합니다.
+
+- **vendor/쿼리 형태별 하드코딩된 action.** 취약하며, 모든 고객의 커스텀 속성, provider 간 join, 또는 미처 생각하지 못한 임의의 필터를 예측할 수 없습니다.
+- **매 페이지 뷰마다 동일한 가져오기/join 로직을 처음부터 다시 실행.** 느리며, 누군가 차트를 볼 때마다 동일한 provider API 쿼터를 다시 소모합니다.
+
+데이터 프로그램은 그 중간 지점입니다. 가져오기/join/집계 로직을 일반적인 `run-code`로 한 번 작성하고, 저장한 다음, 실제로 얼마나 자주 재실행이 필요한지는 캐시와 갱신 정책이 결정하도록 합니다.
+
+## 언제 사용해야 하는가 {#when-to-use-one}
+
+| 상황                                                                                                                                              | 선택할 것                                                                           |
+| ------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| 표준 롤업에 이미 일급 action이 있는 경우(미리 만들어진 `hubspot-deals` 필터, 내장 메트릭 등)                                                      | 기존 action — 프로그램으로 감싸지 마세요                                            |
+| 다시는 보지 않을 일회성 채팅 질문                                                                                                                 | 단순 `run-code` 또는 `provider-api-request` — 바로 답하고, 아무것도 저장하지 마세요 |
+| 확장 기능이 자체 UI를 가진 작은, 사용자별 인터랙티브 위젯을 필요로 하는 경우                                                                      | [확장 기능(Extensions)](/docs/extensions) — 데이터 프로그램은 자체 UI가 없습니다    |
+| 코호트에 임의의 속성 필터, 커스텀 값에 대한 IN 검색, 또는 두 provider 간 join이 필요하고 **동시에** 누군가 최신 데이터로 다시 보고 싶어 하는 경우 | 데이터 프로그램                                                                     |
+| dashboard 패널이 그 조인/집계된 결과를 보여주고 캐시 정책에 따라 갱신되어야 하는 경우                                                             | `"program"` 패널에 바인딩된 데이터 프로그램                                         |
+
+다른 run-code 형태 옵션과의 비교:
+
+|                                      | 일회성 `run-code`      | 하드코딩된 provider action                      | 데이터 프로그램                           |
+| ------------------------------------ | ---------------------- | ----------------------------------------------- | ----------------------------------------- |
+| **호출 간 지속되는가**               | 아니오                 | 해당 없음(그 자체가 소스 코드)                  | 예 — 저장된 행 + 결과 캐시                |
+| **결과가 캐시/갱신되는가**           | 아니오, 매번 재실행    | 내장 캐싱 없음                                  | 예 — `refreshMode`/`refreshTtlMs`         |
+| **임의의 필터/join을 처리하는가**    | 예, 하지만 이후 폐기됨 | 아니오 — action의 schema가 노출하는 것으로 제한 | 예 — 여전히 일반 코드                     |
+| **dashboard 패널에 바인딩 가능한가** | 아니오                 | 그것을 위한 패널 소스가 만들어진 경우에만       | 예 — 범용 `"program"` 소스                |
+| **배포가 필요한가**                  | 아니오                 | 예(새 action = 코드 변경)                       | 아니오 — 에이전트가 실행 시점에 생성      |
+| **읽기 시점에 사용되는 자격 증명**   | 호출자의 것            | 호출자의 것                                     | **뷰어의 것**, 읽기마다 해석됨(아래 참조) |
+
+## 작성 워크플로 {#authoring-workflow}
+
+1. **먼저 채팅에서 프로토타입을 만듭니다.** 가져오기/join/집계 로직을 일반 `run-code` 스크립트로 작성하고, 기대한 행을 반환하는지 확인합니다.
+2. **결과를 반환하거나 출력하는 대신, 마지막에 `emit(rows, schema?)`를 정확히 한 번 호출하도록 변경합니다.**
+3. **`save-data-program`으로 저장합니다.** 이는 영구 저장하기 전에 **`defaultParams`로 코드의 dry-run을 실행**하며, 실패하면 구조화된 오류로 저장을 거부하므로 깨진 프로그램이 저장되는 일은 없습니다. 성공하면 `{ programId, rowCount, columns, sampleRows }`를 반환합니다 — 사용자에게 "준비됐다"고 말하기 전에 이를 프로그램이 예상한 행을 실제로 생성한다는 증거로 취급하세요.
+4. **dashboard 패널을 여기에 바인딩하거나**, 여러분 자신의 읽기 경로에서 직접 `run-data-program`을 호출하세요. 이 프리미티브 자체에는 dashboard 전용 배선이 내장되어 있지 않습니다 — analytics 템플릿의 `"program"` 패널 소스(아래)는 하나의 채택 사례일 뿐, 필수 패턴이 아닙니다.
+5. **저장하지 않고 반복하려면** `preview-data-program({ code, params? })`을 사용하세요 — 동일한 dry-run 경로이며, 저장되는 행은 없습니다.
+
+### 현실적인 예제
+
+한 app이 지원 provider에서 가져온 "최근 고가치 지원 티켓"의 실시간 테이블을, 어떤 내장 action도 노출하지 않는 임계값으로 필터링해서 보여주고 싶다고 가정해 봅시다.
+
+```ts
+// The program's stored `code` — ordinary run-code, with one emit() call.
+const minValue = Number(params.minValue || 5000);
+
+const tickets = await providerFetchAll("acme-support", "/v1/tickets", {
+  query: { status: "open" },
+  itemsPath: "data",
+  pagination: {
+    cursorParam: "cursor",
+    nextCursorPath: "next_cursor",
+    maxPages: 10,
+  },
+});
+
+const rows = (tickets.items || [])
+  .filter((t) => Number(t.contract_value || 0) >= minValue)
+  .map((t) => ({
+    ticket_id: t.id,
+    subject: t.subject,
+    account: t.account_name,
+    contract_value: Number(t.contract_value || 0),
+    opened_at: t.created_at,
+  }));
+
+emit(rows, [
+  { name: "ticket_id", type: "string" },
+  { name: "subject", type: "string" },
+  { name: "account", type: "string" },
+  { name: "contract_value", type: "number" },
+  { name: "opened_at", type: "string" },
+]);
+```
+
+저장하기:
+
+```ts
+await appAction("save-data-program", {
+  name: "high-value-open-tickets",
+  title: "High-Value Open Tickets",
+  description:
+    "Open support tickets above a configurable contract-value threshold.",
+  code: "/* the script above */",
+  defaultParams: { minValue: 5000 },
+  refreshMode: "ttl",
+  refreshTtlMs: 300_000,
+});
+```
+
+응답에는 `{ programId, rowCount, columns, sampleRows }`가 포함됩니다 — dry-run의 완료 증거입니다. 이후 `run-data-program({ programId, params: { minValue: 10000 } })`은 다른 임계값으로 이를 재실행하거나(또는 캐시를 제공하며), dashboard 패널도 동일한 방식으로 `programId`에 바인딩할 수 있습니다.
+
+## 샌드박스 표면 {#sandbox-surface}
+
+데이터 프로그램은 `run-code`와 완전히 동일한 `executeSandboxCode` 샌드박스에서 실행됩니다 — 이 프리미티브를 위한 새로운 샌드박싱, 자격 증명, SSRF, 쿼터 관련 코드는 존재하지 않습니다. 동일한 전역 객체(`providerFetch`, `providerFetchAll`, `providerSearchAll`, `appAction`, `webFetch`, `workspace*` Resources 헬퍼)에 더해, 프레임워크가 주입하는 작은 서문에서 두 가지가 추가됩니다.
+
+- **`params`** — 이번 실행의 params를 담은 **동결된** 전역 객체(`defaultParams`가 `run-data-program`이나 패널 디스크립터에 전달된 값과 병합된 것). 읽는 것은 괜찮지만, 변경하려 하면 오류가 발생합니다.
+- **`emit(rows, schema?)`** — 마지막에 **정확히 한 번** 호출하세요. 두 번째 호출은 오류를 발생시킵니다. `rows`는 일반 객체의 배열이어야 합니다. `schema`는 제공될 경우 `{ name: string, type: string }[]`이며, 생략되면 처음 50개 행에서 추론됩니다(샘플 내에서 행들이 기본 타입에 대해 일치하지 않으면 해당 열은 `"json"`이 되고, 그렇지 않으면 `"number"` / `"string"` / `"boolean"`이 됩니다). `console.log`는 디버깅을 위해 완전히 자유롭게 사용할 수 있습니다 — 러너는 결합된 stdout/stderr를 캡처하고, 결과를 파싱할 때 `emit()`이 작성한 센티널 줄만 제거합니다.
+
+모든 실행에 적용되는 상한(프로그램별로 설정 불가):
+
+| 한도                                             | 값                                                                                                                                                             |
+| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 최대 출력 행 수                                  | 10,000 — 이를 초과하는 행은 삭제되며, `truncated: true`                                                                                                        |
+| 최대 출력 결과 크기                              | 4 MiB — 크기에 맞추기 위해 끝에서부터 행이 삭제됩니다. 단일 행이 상한을 초과하면 안전하게 잘라낼 수 있는 것이 없으므로 강경한 `result_too_large` 실패가 됩니다 |
+| app당 최대 활성(보관되지 않은) 프로그램 수       | 200 — 공간을 확보하려면 사용하지 않는 것을 보관 처리하세요                                                                                                     |
+| 최소 갱신 TTL                                    | 60,000 ms                                                                                                                                                      |
+| (프로그램, params, 뷰어)별로 보관되는 실행 행 수 | 최근 5개 — 오래된 것은 매 쓰기마다 자동으로 정리됩니다                                                                                                         |
+
+잘림은 항상 명시적입니다(결과 내 `truncated: true`) — 조용한 손실은 결코 없습니다.
+
+## Params와 dashboard 패널 바인딩 {#params-and-panel-binding}
+
+프로그램은 선택적인 `paramsSchema`(허용되는 params를 설명하는 JSON Schema)와 `defaultParams`를 선언할 수 있습니다. dashboard는 패널의 쿼리 필드에 쿼리 문자열 대신 작은 JSON 디스크립터를 배치하여 `"program"` 패널 소스를 채택합니다.
+
+```json
+{ "programId": "dp_a1b2c3d4e5f6", "params": { "minValue": 10000 } }
+```
+
+패널은 다른 어떤 패널 소스와도 정확히 동일한 차트/테이블 컴포넌트를 통해 렌더링됩니다 — 패널이 받는 것은 항상 `{ rows, schema }`뿐입니다. 패널을 프로그램에 바인딩하는 것은 단지 "어떤 저장된 프로그램에, 어떤 params 재정의로"일 뿐이며, 다른 어디에도 중복된 dashboard 전용 실행 경로는 존재하지 않습니다.
+
+## 갱신, TTL, 캐싱 시맨틱 {#refresh-and-caching}
+
+각 `(programId, paramsHash)` 쌍은 `data_program_runs`에 자체 실행 이력을 가지며, `paramsHash`는 params뿐 아니라 **뷰어**도 포함합니다(이유는 보안 섹션 참조). 각 읽기마다 발생하는 일:
+
+| 상황                                                                                            | 동작                                                                                                                                                                    |
+| ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 신선한 캐시(`refreshTtlMs`보다 최신이거나, `refreshMode: "manual"`이면서 이전 성공이 있는 경우) | 캐시된 행을 즉시 반환, `cacheHit: true`                                                                                                                                 |
+| 캐시가 TTL보다 오래된 경우                                                                      | 동기적으로 재실행됩니다 — 패널 뷰로 트리거된 읽기는 25초, 에이전트/수동 호출은 120초의 예산을 가지며, 성공 시 캐시를 교체합니다                                         |
+| `refreshMode: "manual"`                                                                         | 자동으로 갱신되지 않습니다. 명시적인 `forceRefresh: true`(또는 UI의 수동 갱신 action)만이 재실행합니다                                                                  |
+| 아직 캐시가 없는 경우                                                                           | 일반적인 첫 가져오기처럼 동기적으로 실행됩니다                                                                                                                          |
+| `background: true` 프로그램, 신선한 캐시가 없는 경우                                            | 마지막으로 성공한 실행 결과를 `stale: true`와 함께 즉시 제공하고, 내구성 있는 백그라운드 실행을 큐에 넣습니다(10분 예산). 이후 호출은 실행이 완료되면 결과를 확정합니다 |
+| 백그라운드 프로그램이 아직 실행 중이고 이전 성공이 없는 경우                                    | `background_pending` 실패 — "아직 계산 중"이라는 명시적 상태를 표시해야 하며, 빈 결과는 결코 안 됩니다                                                                  |
+| 실행이 실패하는 경우(타임아웃, 샌드박스 오류, 잘못된 `emit()` 형태)                             | 구조화된 `{ code, message }` 실패. 이전 성공이 존재하면 `lastGoodRun`으로 첨부되어, 패널이 비어 있는 대신 오래된 데이터를 제공할 수 있습니다                            |
+| 프로그램이 보관 처리된 경우(`delete-data-program`을 통한 소프트 삭제)                           | 명시적인 `archived` 실패 — 조용한 빈 패널은 결코 없습니다                                                                                                               |
+
+`background: true`는 포그라운드 타임아웃을 일상적으로 초과하는 프로그램(대규모 다중 provider join, 깊은 페이지네이션 등)에만 사용하세요. 그 외 모든 경우는 포그라운드로 유지해야 합니다 — 추론하기 더 간단하고 더 빠르게 신선한 데이터를 제공합니다.
+
+### 캐시가 뷰어별로 범위 지정되는 이유 {#per-viewer-cache}
+
+프로그램 내부의 `providerFetch`는 **호출 중인 뷰어 자신의 요청 컨텍스트**를 사용하여 인증을 해석합니다 — 프로그램 작성자의 것이 결코 아닙니다. 이는 호출이 에이전트에서 오든, `run-data-program` 호출에서 오든, 팀원이 보고 있는 dashboard 패널에서 오든 마찬가지입니다. 동일한 프로그램을 동일한 params로 실행하는 두 명의 다른 뷰어는 정당하게 서로 다른 두 결과를 얻을 수 있습니다. 한 명은 HubSpot 키가 설정되어 있고 다른 한 명은 없거나, 행 수준의 provider 권한이 사람마다 다를 수 있습니다.
+
+이 때문에 `hashDataProgramParams`는 정규화된 params와 함께 호출자의 신원을 캐시 키에 포함시킵니다. 이는 **공유 dashboard**에서 가장 중요합니다. 만약 캐시가 params만으로 키가 지정되었다면, 패널을 처음 보는 사람이 그 캐시된 결과를 생성한 자격 증명이 없는 뷰어를 포함해 다른 모든 뷰어가 보게 될 것을 조용히 결정해 버리게 됩니다. 뷰어별 범위 지정은 자격 증명이 없는 팀원이 다른 사람의 데이터가 아니라 그 패널에서 자기 자신의 인증 오류를 보게 된다는 것을 의미합니다.
+
+## 보안 모델 {#security}
+
+<Callout id="doc-block-dp-security" tone="success">
+
+**원시 provider 토큰은 결코 모델이나 브라우저에 도달하지 않습니다.** 샌드박스를 벗어나는 유일한 것은 `emit()` 호출이 생성하는 `{ rows, schema }`뿐입니다 — 다른 모든 run-code 실행, 다른 모든 dashboard 패널 소스와 동일한 신뢰 경계입니다.
+
+</Callout>
+
+- **서버 측 전용.** 데이터 프로그램의 코드는 서버의 `executeSandboxCode` 내부에서만 실행됩니다. 저장된 소스도, 그것이 다루는 어떤 자격 증명도 브라우저나 모델로 전송되지 않습니다 — 전송되는 것은 오직 출력된 행/schema와 압축된 실행 메타데이터(행 수, 열, 샘플 행)뿐입니다.
+- **자격 증명은 항상 호출 중인 뷰어의 것이며, 프로그램의 원래 작성자의 것이 결코 아닙니다.** 이것이 캐시 키도 결정하는 이유는 위의 [갱신, TTL, 캐싱 시맨틱](#per-viewer-cache)을 참조하세요.
+- **`allowPublic: false`는 기본값이 아니라 엄격한 불변 조건입니다.** 데이터 프로그램은 [확장 기능](/docs/extensions#security)과 동일한 방식으로 공유 레지스트리에 등록되며, 공개 공유는 비활성화되어 있습니다. 공개된 프로그램은 인증된 어떤 사용자든 자기 자신의 토큰으로 임의의 저장된 코드를 실행하게 할 수 있습니다 — 프로그램을 공유한다는 것은 여러분의 조직으로 범위가 한정되며, 항상 "팀원이 캐시된 결과를 보고 재실행을 트리거할 수 있다"는 것만을 의미하지, "일반 인터넷이 이를 실행할 수 있다"는 것을 의미하지 않습니다.
+- **변경 및 실행 관련 actions는 샌드박스화된 확장 기능/iframe 브리지에서 도구로 호출할 수 없습니다.** `save-data-program`, `preview-data-program`, `run-data-program`, `delete-data-program`은 모두 `toolCallable: false`입니다 — 오직 에이전트나 서버 측 읽기 경로만이 이를 호출할 수 있으며, 연 사람의 세션 아래 있는 확장 기능 iframe에서는 결코 호출할 수 없습니다. `list-data-programs`와 `get-data-program`은 읽기 전용이며, 다른 모든 ownable 리소스와 동일한 공유 헬퍼를 통해 접근이 범위 지정됩니다.
+- **프로그램은 그것을 생성한 app으로 범위가 한정됩니다.** 조회에 `appId`를 전달한다는 것은, 공유 데이터베이스 배포에서 한 app에서 생성된 프로그램이 다른 app의 에이전트 채팅에서 실행될 수 없음을 의미합니다. 호출자가 그렇지 않으면 행 수준(owner/org/share) 접근 권한을 가지고 있더라도 마찬가지입니다.
+- **신뢰하는 프로그램에만 바인딩하거나 보세요.** 실행은 항상 뷰어 자신의 자격 증명을 사용하므로, 공유된 프로그램의 결과를 보는 것은 다른 사람의 확장 기능을 여는 것과 정확히 같습니다 — 신뢰해야 할 것은 코드 자체이지, 단순한 접근 권한 부여가 아닙니다.
+
+## Risk Meeting 실전 예제 {#risk-meeting-example}
+
+analytics 템플릿에는 구체적이고 실행 가능한 사례 연구가 포함되어 있습니다. `ensure-risk-meeting-dashboard` action은 두 개의 데이터 프로그램과 2패널 "Risk Meeting" dashboard를 멱등적으로 설치하며, 하드코딩된 action이 모든 고객에 대해 예측할 수 없는 세 가지를 보여줍니다.
+
+<FileTree
+  id="doc-block-dp-risk-meeting-files"
+  title={"Risk Meeting 설치 프로그램"}
+  entries={[
+    {
+      path: "templates/analytics/actions/ensure-risk-meeting-dashboard.ts",
+      note: "멱등 action: 안정적인 이름으로 두 프로그램을 모두 업데이트한 다음, id로 dashboard를 업데이트",
+    },
+    {
+      path: "templates/analytics/seeds/data-programs/risk-meeting-cohort.js",
+      note: "저장된 프로그램 페이로드 — 빌드 소스 파일이 아니라 순수 JS 텍스트",
+    },
+    {
+      path: "templates/analytics/seeds/data-programs/risk-meeting-pylon-early-warning.js",
+      note: "보완적인 조기 경고 프로그램",
+    },
+  ]}
+/>
+
+**`risk-meeting-cohort.js`** — 임의의 `risk_status` 속성(미리 만들어진 action이 예측할 수 없는, 커스텀 값에 대한 IN 검색)으로 설정 가능한 CRM 딜 코호트를 검색하고, 일괄 연관 관계 조회를 통해 각 딜의 회사를 해석하고, 각 회사의 도메인을 해석하고, 관련 없는 두 번째 provider의 계정 감정(sentiment)을 가져와 도메인으로 두 데이터를 조인합니다.
+
+```js
+// params: { riskStatuses?: string[], enterpriseOnly?: boolean }
+const riskStatuses = params.riskStatuses?.length
+  ? params.riskStatuses
+  : ["On the Radar", "Churn Risk", "Confirmed Churn", "No Save Attempted"];
+
+// 1. Arbitrary property IN-search — not expressible through a canned filter.
+const dealSearch = await providerFetchAll("crm-provider", "/deals/search", {
+  method: "POST",
+  body: {
+    filterGroups: [
+      {
+        filters: [
+          { propertyName: "risk_status", operator: "IN", values: riskStatuses },
+        ],
+      },
+    ],
+  },
+  itemsPath: "results",
+  pagination: {
+    cursorBodyPath: "after",
+    nextCursorPath: "paging.next.after",
+    maxPages: 20,
+  },
+});
+
+// 2-3. Batched deal -> company -> domain resolution (elided here; see the
+// real seed file for the full batching helper).
+
+// 4. A second, unrelated provider — zero bespoke glue action required.
+const accounts = await providerFetchAll("support-provider", "/accounts", {
+  itemsPath: "data",
+  pagination: {
+    cursorParam: "cursor",
+    nextCursorPath: "pagination.cursor",
+    maxPages: 20,
+  },
+});
+
+// 5. Join + emit.
+const rows = dealSearch.items.map((deal) => ({
+  deal_id: deal.id,
+  risk_status: deal.properties.risk_status,
+  arr: Number(deal.properties.total_contract_value || 0),
+  // ...domain lookup + sentiment join...
+}));
+
+emit(rows, [
+  { name: "deal_id", type: "string" },
+  { name: "risk_status", type: "string" },
+  { name: "arr", type: "number" },
+]);
+```
+
+**`risk-meeting-pylon-early-warning.js`** — 보완적인 뷰: 지원 감정에 의해 이미 위험으로 표시되었지만 위의 CRM 코호트에는 **아직** 나타나지 않은 계정들. 이 격차 — CRM 신호보다 앞서가는 지원 신호 — 는 한 provider의 코호트를 다른 provider의 코호트에서 제외해야 하며, 이는 단일 vendor의 action으로는 표현할 수 없는 종류의 provider 간 집합 로직입니다.
+
+두 프로그램 모두 `ensure-risk-meeting-dashboard`에 의해 설치되고 최신 상태로 유지되며, 이 action은 다음을 수행합니다.
+
+- 각 프로그램을 안정적인 `name`으로 업데이트하므로, 설치 프로그램을 재실행하면 동일한 행이 중복되는 대신 업데이트됩니다.
+- 설치 시점에 CRM/지원 자격 증명이 필요하지 않습니다 — provider 인증은 패널이 실제로 렌더링되거나 `run-data-program`이 호출될 때만 뷰어별로 해석되며, 위의 뷰어별 캐시 범위 지정과 일치합니다.
+- `source: "program"`을 사용하는 패널을 가진 2패널 dashboard를 구축하며, 각각 해당 프로그램의 id에 바인딩됩니다.
+
+완전히 주석이 달린 소스는 `data-programs` skill을 참조하세요.
+
+## 다른 app이 패널 소스를 채택하는 방법 {#adopting-the-panel-source}
+
+`"program"` dashboard 패널 소스는 이 프리미티브의 하나의 채택 사례로, 호스트 app 자체의 패널 쿼리 레이어에 완전히 구현되어 있습니다 — dashboard 전용의 어떤 것도 `@agent-native/core/data-programs` 자체에는 내장되어 있지 않습니다. analytics 템플릿의 구현은 여러분 자신의 것을 연결할 때 유용한 참고 자료입니다.
+
+- 패널의 `sql` 컬럼은 쿼리 문자열 대신 작은 JSON 디스크립터 — `{ programId, params? }` — 를 담습니다.
+- 패널을 렌더링하면 `triggeredBy: "panel_view"`와 현재 뷰어의 신원을 사용해 `runDataProgram`을 호출하므로, 뷰어별 캐시와 자격 증명 해석이 자동으로 적용됩니다.
+- 성공하면 패널은 `{ rows, schema }`를 받습니다 — 이는 다른 모든 패널 소스가 반환하는 것과 동일한 형태이므로, 기존 차트/테이블 컴포넌트를 통해 수정 없이 흘러갑니다.
+- 실패하면 `lastGoodRun`이 존재하는 한 깨진 패널보다 우선됩니다. 이전 성공이 전혀 없을 때만 패널이 구조화된 오류를 표시합니다(`access_denied`, `archived`, `background_pending`과 같은 일반적인 코드에 대해서는 더 친숙한 문구가 제공됩니다).
+
+어떤 app이든 자체 dashboard/테이블을 위해 동일한 채택을 구현할 수 있습니다. 여러분 자신의 읽기 경로에서 `run-data-program`(동일한 서버 프로세스 내부라면 `runDataProgram`을 직접)을 호출하고, 반환된 `rows`/`schema`를 여러분 자신의 렌더링 컴포넌트에 전달하세요.
+
+## 관련 문서 {#related}
+
+- [확장 기능](/docs/extensions) — 데이터 프로그램이 보안 태세와 공유 모델을 공유하지만 자체 UI를 가진 샌드박스화된 mini-app 프리미티브.
+- [Actions](/docs/actions) — 데이터 프로그램이 구축되는 기반이 되는 `run-code` 규약과 샌드박스 전역 객체(`providerFetch`, `appAction` 등).
+- [공유 및 개인정보 보호](/docs/sharing) — 데이터 프로그램이 사용하는, 조직 내부로 한정되며 결코 공개되지 않는 공유 모델.
+- [보안](/docs/security) — 프레임워크의 자격 증명 처리 및 접근 범위 지정 불변 조건.

package/corpus/core/docs/content/locales/ko-KR/deployment.mdx

@@ -384,24 +384,23 @@ openssl rand -hex 32
 ## 제작 에이전트 도구 {#production-agent-tools}
 
 프로덕션 에이전트는 다음에서 앱에 등록된 actions와 프레임워크 도구를 얻습니다.
-상담원 채팅 플러그인. 데이터베이스 쓰기는 원시 DB이므로 기본적으로 활성화됩니다.
-도구의 범위는 인증된 사용자/조직으로 지정되지만 앱 소유자는 범위를 좁힐 수 있습니다
-배포가 더욱 독선적이어야 하는 경우:
+상담원 채팅 플러그인. SQL 검사는 기본적으로 활성화되며, 데이터베이스 쓰기는
+앱이 raw write tools를 명시적으로 켜지 않는 한 typed app actions를 통해 수행됩니다.
 
 ```ts
 // server/plugins/agent-chat.ts
 export default createAgentChatPlugin({
-  // Default: "write" (also true)
+  // Default: "read"
   databaseTools: "read", // "write" | "read" | "off"
   extensionTools: false,
 });
 ```
 
-- `databaseTools: "write"` — 기본값. `db-schema`, `db-query`,
-  `db-exec` 및 `db-patch`. 쓰기 범위는 현재 사용자/조직으로 지정되며
-  스키마 변경이 차단되었습니다.
-- `databaseTools: "read"` — `db-schema` 및 `db-query`만 등록합니다. 요원
-  SQL로 데이터를 검사하지만 쓰기에는 입력된 앱 actions를 사용해야 합니다.
+- `databaseTools: "read"` — 기본값. `db-schema`와 `db-query`만 등록합니다.
+  에이전트는 SQL로 데이터를 검사하지만 쓰기에는 typed app actions를 사용해야 합니다.
+- `databaseTools: "write"` 또는 `true` — 의도적인 raw SQL 유지보수를 위해
+  `db-exec`와 `db-patch`도 등록합니다. 쓰기는 현재 사용자/조직으로 scoped되고
+  스키마 변경은 차단됩니다.
 - `databaseTools: "off"` 또는 `false` — 원시 데이터베이스 도구를 제거합니다.
   에이전트 표면이므로 앱의 actions가 유일한 데이터 액세스 경로입니다.
 - `extensionTools: false` — 프레임워크 확장 관리 actions를 제거하고

package/corpus/core/docs/content/locales/ko-KR/extensions.mdx

@@ -34,7 +34,7 @@ QuickBooks Online을 사용해 본 적이 있다면 모델을 본 적이 있을
     <div class="ext-helpers">
       <span class="diagram-pill">appAction</span
       ><span class="diagram-pill">appFetch</span
-      ><span class="diagram-pill">dbQuery / dbExec</span
+      ><span class="diagram-pill">dbQuery</span
       ><span class="diagram-pill">extensionData</span
       ><span class="diagram-pill">extensionFetch</span>
     </div>
@@ -220,17 +220,17 @@ Sketch — 연락처 메모(이메일을 보내는 사람과 연결된 메모
 
 iframe 샌드박스 내부의 모든 확장 프로그램에는 `window`에 다음 도우미가 있습니다.
 
-| 도우미                                           | 목적                                               | 예                                                        |
-| ------------------------------------------------ | -------------------------------------------------- | --------------------------------------------------------- |
-| `appAction(name, params)`                        | 호스트 템플릿의 actions 중 하나를 호출하세요       | `appAction('list-emails', { view: 'inbox' })`             |
-| `appFetch(path, options)`                        | `/_agent-native/*`에서 허용된 프레임워크 끝점 호출 | `appFetch('/_agent-native/application-state/navigation')` |
-| `dbQuery(sql, args)`                             | SQL에서 읽기(사용자에게 자동 범위 지정)            | `dbQuery('SELECT id, name FROM tools')`                   |
-| `dbExec(sql, args)`                              | SQL에 쓰기                                         | `dbExec('INSERT INTO ...')`                               |
-| `extensionFetch(url, options)`                   | 비밀이 있는 보안 프록시를 통해 외부 API에 접근     | `extensionFetch('https://api.github.com/user')`           |
-| `extensionData.set(collection, id, data, opts?)` | 확장자별 데이터 유지(사용자/조직 범위 지정)        | `extensionData.set('notes', id, { text: '...' })`         |
-| `extensionData.list(collection, opts?)`          | 지속된 항목 나열                                   | `extensionData.list('notes', { scope: 'all' })`           |
-| `extensionData.get(collection, id, opts?)`       | 단일 항목 가져오기                                 | `extensionData.get('notes', 'note-1')`                    |
-| `extensionData.remove(collection, id, opts?)`    | 지속된 항목 삭제                                   | `extensionData.remove('notes', 'note-1')`                 |
+| 도우미                                           | 목적                                                  | 예                                                        |
+| ------------------------------------------------ | ----------------------------------------------------- | --------------------------------------------------------- |
+| `appAction(name, params)`                        | 호스트 템플릿의 actions 중 하나를 호출하세요          | `appAction('list-emails', { view: 'inbox' })`             |
+| `appFetch(path, options)`                        | `/_agent-native/*`에서 허용된 프레임워크 끝점 호출    | `appFetch('/_agent-native/application-state/navigation')` |
+| `dbQuery(sql, args)`                             | SQL에서 읽기(사용자에게 자동 범위 지정)               | `dbQuery('SELECT id, name FROM tools')`                   |
+| `dbExec(sql, args)`                              | Legacy trusted SQL writes for editor/admin extensions | Prefer `appAction` for app data writes                    |
+| `extensionFetch(url, options)`                   | 비밀이 있는 보안 프록시를 통해 외부 API에 접근        | `extensionFetch('https://api.github.com/user')`           |
+| `extensionData.set(collection, id, data, opts?)` | 확장자별 데이터 유지(사용자/조직 범위 지정)           | `extensionData.set('notes', id, { text: '...' })`         |
+| `extensionData.list(collection, opts?)`          | 지속된 항목 나열                                      | `extensionData.list('notes', { scope: 'all' })`           |
+| `extensionData.get(collection, id, opts?)`       | 단일 항목 가져오기                                    | `extensionData.get('notes', 'note-1')`                    |
+| `extensionData.remove(collection, id, opts?)`    | 지속된 항목 삭제                                      | `extensionData.remove('notes', 'note-1')`                 |
 
 세 가지 경험 법칙:
 
@@ -395,7 +395,7 @@ extensions/
 
 - `extensionData`는 비활성화되지 않는 한 작은 런타임 상태에 사용할 수 있습니다.
 - `appAction` 호출은 `permissions.appActions`에 명시적으로 나열되어야 합니다.
-- `dbQuery`, `dbExec`, `extensionFetch`는 현재 차단되었습니다.
+- `dbQuery`, `extensionFetch`는 현재 차단되었습니다.
 - SQL 지원 업데이트, 삭제, 공유 및 기록 actions는 다음 메시지를 반환합니다.
   로컬 항목 파일을 다시 가리킵니다.
 
@@ -428,6 +428,8 @@ extensions/
 
 경험 법칙: **한 명의 사용자 또는 한 팀을 위한 것이라면 확장입니다.** 템플릿의 모든 사용자가 이를 받아야 한다면 실제 기능으로 제공하세요.
 
+커스텀 위젯 UI 대신 네이티브 차트와 테이블에 데이터를 공급해야 하는 커스텀 데이터 가져오기의 경우, [데이터 프로그램](/docs/data-programs)을 참조하세요 — 확장 기능 iframe 없이 dashboard 패널이 직접 바인딩하는, 저장되고 갱신 가능한 `run-code` 스크립트입니다.
+
 ## 보안 {#security}
 
 <Callout id="doc-block-frp4nq" tone="success">
@@ -442,7 +444,7 @@ extensions/
 - **`${keys.NAME}` 템플릿을 통한 서버 측 비밀 주입** - 실제 키 값은 브라우저에 도달하지 않습니다.
 - **도메인 잠금 비밀** — 각 키는 URL 허용 목록에 바인딩됩니다. 프록시가 다른 호스트에 대한 요청을 거부합니다.
 - **사설망 보호** — 확장 프로그램은 내부 주소에 접근할 수 없습니다.
-- **인증 필요** — 확장 프로그램은 로그인한 사용자에 대해서만 실행되며 `dbQuery` / `dbExec` 호출은 자동으로 범위가 지정됩니다.
+- **인증 필요** — 확장 프로그램은 로그인한 사용자에 대해서만 실행되며 `dbQuery` 호출은 자동으로 범위가 지정됩니다.
 
 ## 이름 지정에 대해 알아야 할 몇 가지 사항 {#naming-back-compat}
 

package/corpus/core/docs/content/locales/ko-KR/key-concepts.mdx

@@ -239,21 +239,18 @@ export const forms = table("forms", {
 ```
 
 ```bash
-# 신속한 데이터베이스 검사 및 일회성 유지 관리를 위한 핵심 조치
+# 신속한 데이터베이스 검사를 위한 핵심 조치
 pnpm action db-schema                                       # show all tables
 pnpm action db-query --sql "SELECT * FROM forms"
-pnpm action db-exec --sql "UPDATE forms SET status = ? WHERE id = ?" --args '["closed","form-1"]'
-# 큰 텍스트 열의 외과적 find/replace — 전체 값이 아닌 차이점을 보냅니다.
-pnpm action db-patch --table documents --column content \
-  --where "id='doc-1'" --find "old heading" --replace "new heading"
 ```
 
-프로덕션 에이전트 채팅 플러그인은 기본적으로 원시 데이터베이스 쓰기를 활성화합니다.
-(`databaseTools: "write"`) 상담원이 기다리지 않고 앱 소유 데이터를 수정할 수 있도록
-새로 입력된 작업입니다. 이러한 쓰기는 인증된 사용자/조직으로 범위가 지정됩니다. 설정
-`databaseTools: "read"`는 `db-schema` / `db-query` 검사만 유지하거나
-`databaseTools: "off"` / `false`는 모든 데이터에 대해 입력된 앱 actions를 요구합니다
-액세스.
+프로덕션 에이전트 채팅 플러그인은 raw SQL 도구를 기본적으로 읽기 전용으로 둡니다
+(`databaseTools: "read"`). 에이전트는 `db-schema` / `db-query`로 앱 소유
+데이터를 검사하고, 쓰기는 typed app actions를 통해 수행합니다.
+스코프가 적용된 `db-exec` / `db-patch`도 노출해야 하는 의도적인
+유지 관리 화면에서만 `databaseTools: "write"`(또는 `true`)를 설정합니다.
+모든 데이터 접근에 typed app actions를 요구하려면 `databaseTools: "off"` /
+`false`를 설정합니다.
 
 ## 에이전트 채팅 브리지 {#agent-chat-bridge}
 
@@ -437,6 +434,7 @@ UI는 경로 변경 시 이를 기록합니다. 상담원은 조치를 취하기
 
 - **[Dispatch](/docs/dispatch)** — 작업 공간 제어 플레인: 공유 받은 편지함, 비밀 금고, 예약된 작업 및 A2A를 통해 전문 앱에 위임하는 오케스트레이터.
 - **[Extensions](/docs/extensions)** — 에이전트가 런타임 시 생성하는 샌드박스형 Alpine.js 미니 앱, 소스 변경 또는 마이그레이션 없음.
+- **[데이터 프로그램](/docs/data-programs)** — 에이전트가 작성하고 저장한 `run-code` 스크립트로, 하드코딩된 provider action 대신 캐시되고 갱신 가능한 결과를 dashboard 패널에 제공합니다.
 - **[A2A Protocol](/docs/a2a-protocol)** — 동일한 작업 공간에 있는 앱이 JSON-RPC를 통해 서로를 검색하고 호출하는 방법
 
 ## 무료로 얻는 것 {#what-you-get-for-free}

package/corpus/core/docs/content/locales/ko-KR/real-time-collaboration.mdx

@@ -258,11 +258,8 @@ export default createCollabPlugin({
 ### 4. 클라이언트 후크를 사용하세요
 
 ```ts
-import {
-  useCollaborativeDoc,
-  emailToColor,
-  emailToName,
-} from "@agent-native/core/client";
+import { useCollaborativeDoc } from "@agent-native/core/client";
+import { emailToColor, emailToName } from "@agent-native/toolkit/collab-ui";
 
 const TAB_ID = generateTabId(); // or Math.random().toString(36)
 
@@ -364,12 +361,14 @@ pnpm action edit-document --id doc123 --find "delete me" --replace ""
 
 ```ts
 import {
-  PresenceBar,
-  LiveCursorOverlay,
-  RemoteSelectionRings,
   useCollaborativeDoc,
   usePresence,
 } from "@agent-native/core/client/collab";
+import {
+  PresenceBar,
+  LiveCursorOverlay,
+  RemoteSelectionRings,
+} from "@agent-native/toolkit/collab-ui";
 ```
 
 서버 측 에이전트 존재 도우미는 하위 수준 공동 작업 패키지에 유지됩니다.
@@ -455,7 +454,7 @@ setPresence({ cursor: { x: 0.4, y: 0.7 }, selection: "#hero" });
 원격 커서를 컨테이너 요소 위에 절대 위치 레이블로 렌더링합니다.
 
 ```tsx
-import { LiveCursorOverlay } from "@agent-native/core/client";
+import { LiveCursorOverlay } from "@agent-native/toolkit/collab-ui";
 
 // cursor positions stored as { x, y } normalized 0–1 under presence.cursor
 <div ref={containerRef} style={{ position: "relative" }}>
@@ -475,7 +474,7 @@ import { LiveCursorOverlay } from "@agent-native/core/client";
 원격으로 선택된 요소 위에 색상 외곽선 링 + 이름 태그를 렌더링합니다.
 
 ```tsx
-import { RemoteSelectionRings } from "@agent-native/core/client";
+import { RemoteSelectionRings } from "@agent-native/toolkit/collab-ui";
 
 <div ref={containerRef} style={{ position: "relative" }}>
   {content}