@haenah/u1z 0.1.0

package/README.md

@@ -0,0 +1,284 @@
+# u1z — AI 집 비서
+
+라즈베리파이에서 상시 구동되는 자율적인 AI 집 비서 시스템.
+Discord를 채팅 인터페이스로 사용하며, 파일 관리, 캘린더, 식당 예약, 장보기, 웹 브라우징을 담당한다.
+런타임 기준 루트는 `process.env.U1Z_HOME`이며, 시스템 프롬프트는 `${U1Z_HOME}/.u1z/prompt/BASE.md`를 사용한다.
+
+---
+
+## 핵심 개념
+
+**Conversation** — 1시간 이내의 연속된 대화 흐름. Prompt Caching 최적화의 기본 단위. 만료 시 단기 기억 요약 프로세스가 실행된다.
+
+**채널 타입** — Discord는 두 가지 채널 타입을 지원한다.
+- **Guild 채널**: 서버 공유 채널. 여러 사용자가 참여하며 발화자(User ID)를 식별한다.
+- **DM**: 1:1 개인 채팅. 발화자 식별 없이 원문 그대로 전달한다.
+
+**메모리** — 범주(user / channel)로 구분한다. 전역 공유 기억은 `MEMORY.txt` 단일 파일로 관리한다.
+- **전역(MEMORY.txt)**: 모든 컨텍스트에 공통 주입되는 기억. 사용자가 직접 편집.
+- **user**: DM 발화자별 개인 기억
+- **channel**: 서버 채널별 기억
+- **YYMMDD**: 일별 단기기억. Conversation 만료 시 자동 요약 추가.
+
+**스킬** — `$U1Z_HOME/.u1z/skills/`에 저장된 작업별 가이드라인 파일. 시스템 프롬프트에는 `SKILLS.md`(목록)만 주입하고 적극적으로 활용하고 자기 주도적으로 관리할 수 있도록 프롬프팅한다.
+
+---
+
+## 기술 스택
+
+| 레이어       | 선택                          |
+| ------------ | ----------------------------- |
+| 런타임       | Bun (TypeScript, ARM64)       |
+| HTTP 서버    | Hono                          |
+| LLM          | Vercel AI SDK (`ai`) + gpt5.2 |
+| 채팅         | Discord.js                    |
+| 웹 검색/추출 | Tavily API                    |
+| 웹 브라우징  | agent-browser (Vercel Labs)   |
+| 컨텍스트     | Discord channel history       |
+| 패스워드     | Pass (GPG)                    |
+| 스케줄러     | cron                          |
+| 서비스 관리  | systemd                       |
+
+---
+
+## 모듈 의존성
+
+```mermaid
+graph LR
+    conversation --> ai
+    conversation --> db
+    conversation --> memory
+    discord --> ai
+    discord --> conversation
+    discord --> db
+    discord --> memory
+    memory --> ai
+    server --> discord
+```
+
+> `bun run dep-graph`으로 재생성 가능
+
+하위 모듈(`prompt/`, `memory/`, `db/`)은 다른 도메인에 의존하지 않는 leaf 레이어다.
+`conversation/`은 LLM + DB + memory를 조합해 대화 상태를 관리하고,
+`discord/`는 모든 도메인을 통합해 봇의 실제 동작(메시지 수신 → LLM → 메모리 저장)을 구현한다.
+
+---
+
+## 멀티유저 / 멀티채널
+
+| 채널      | 히스토리 범위          | 용도                   |
+| --------- | ---------------------- | ---------------------- |
+| 서버 공유 | 채널 단위 history 공유 | 장보기, 가족 일정      |
+| 개인 DM   | 사용자 DM history 분리 | 개인 일정, 민감한 작업 |
+
+```text
+[Discord 서버 #집안일 채널] 나 + 와이프 + 비서봇
+  → 발화자 식별 (Discord User ID)
+  → 공유 컨텍스트 (장보기, 메뉴 등) + 개인 컨텍스트 분리
+
+[Discord DM] 나 ↔ 비서봇       → 개인 일정, 민감한 작업
+[Discord DM] 와이프 ↔ 비서봇   → 와이프 개인 일정
+```
+
+| 컨텍스트 | 범위                  | 예시                         |
+| -------- | --------------------- | ---------------------------- |
+| 공유     | 서버 채널 참여자 전체 | 장보기 목록, 식단, 가족 일정 |
+| 개인     | 발화자 본인만         | 개인 일정, 업무              |
+
+길드 채널에서는 봇을 멘션해야 응답한다. DM은 별도 제한 없이 응답한다.
+
+---
+
+## Discord Bot 설정
+
+### Gateway Intents
+
+**Privileged Intent** — Developer Portal > Bot > Privileged Gateway Intents에서 토글로 직접 활성화해야 한다:
+
+| Developer Portal 레이블 | Intent            | 이 프로젝트 |
+| ----------------------- | ----------------- | ----------- |
+| Message Content Intent  | `MESSAGE_CONTENT` | **필수**    |
+| Server Members Intent   | `GUILD_MEMBERS`   | 불필요      |
+| Presence Intent         | `GUILD_PRESENCES` | 불필요      |
+
+**Non-privileged Intent** — 포털 설정 없이 코드에서만 선언하면 된다:
+
+| Intent            | 용도                  |
+| ----------------- | --------------------- |
+| `GUILDS`          | 서버/채널 정보 수신   |
+| `GUILD_MESSAGES`  | 서버 채널 메시지 수신 |
+| `DIRECT_MESSAGES` | DM 수신               |
+
+### OAuth2 Scopes
+
+봇 초대 URL 생성 시 (Developer Portal > OAuth2 > URL Generator) 아래 두 scope를 모두 체크해야 한다:
+
+| Scope                   | 용도                       |
+| ----------------------- | -------------------------- |
+| `bot`                   | 봇 계정으로 서버 참여      |
+| `applications.commands` | Slash command 등록 및 사용 |
+
+> `applications.commands`가 없으면 `/debug`, `/new` slash command가 동작하지 않는다.
+> 기존에 `bot` scope만으로 초대한 경우, 새 URL로 재방문(재초대)하면 scope가 추가된다. 봇을 kick할 필요 없다.
+
+### Bot Permissions
+
+서버 초대 시 요청할 권한:
+
+| Permission             | 용도                        |
+| ---------------------- | --------------------------- |
+| `View Channels`        | 채널 접근                   |
+| `Send Messages`        | 응답 전송                   |
+| `Read Message History` | 대화 컨텍스트 bootstrap     |
+| `Attach Files`         | `/sysprompt` 파일 첨부 전송 |
+
+### Slash Commands
+
+봇 시동 시 `clientReady` 이벤트에서 자동으로 전역 등록된다.
+
+| 커맨드       | 설명                                                                                              | 공개 여부              |
+| ------------ | ------------------------------------------------------------------------------------------------- | ---------------------- |
+| `/usage`     | 현재 conversation의 토큰 사용량 및 비용 조회                                                      | 본인에게만 (ephemeral) |
+| `/new`       | 현재 채널의 conversation을 초기화하고 새로 시작. 이때 메모리 워커가 동기적으로 실행되어 대기 필요 | 채널에 공개            |
+| `/sysprompt` | 현재 conversation의 시스템 프롬프트를 `.md` 파일로 전송                                           | 본인에게만 (ephemeral) |
+
+---
+
+## Prompt structure
+
+Conversation 단위로 프롬프트를 구성한다. 이는 GPT의 캐싱을 극대화하기 위함이다. Conversation의 시작 프롬프트는 아래와 같이 구성된다.
+
+- System Prompt
+  - `${U1Z_HOME}/.u1z/prompt/BASE.md`
+  - `SKILLS.md`
+  - 기억
+    - 전역 기억: `memory/MEMORY.txt`
+    - 기억: `memory/channel/<channelId>/YYMMDD.md` 또는 `memory/user/<userId>/YYMMDD.md`
+- Initial messages
+  - Conversation 만료 시 메모리에 요약된 내용으로 컨텍스트를 복원한다.
+
+### interpolation
+
+각 BASE.md는 **mustache** 문법(`{{}}`)을 이용한 프롬프트 인터폴레이션을 지원한다. 플레이스홀더는 `getSystemPrompt()` 호출 시 실제 값으로 치환되며, HTML 이스케이프는 비활성화되어 있다.
+
+| 플레이스홀더            | 치환 값                      |
+| ----------------------- | ---------------------------- |
+| `{{current_time_kokr}}` | 현재 일시 (KST, 한국어 형식) |
+
+---
+
+## Tool loop
+
+ai sdk의 ToolLoopAgent를 이용하여 구현한다.
+스트리밍은 하지 않지만 중간중간 assistant message가 tool call과 함께 도착하는 경우 디스코드 메세지를 전송하여 사용자에게 진행 상황을 알려준다.
+
+- `bash`
+- `text_editor`
+- `get_password`: Pass/GPG에서 자격증명 조회 (로그는 `[REDACTED]`)
+- `web_search`: 웹 검색 (Tavily Search API). 검색 깊이, 주제(general/news/finance), 기간 필터, 국가 필터 지원.
+- `web_fetch`: 웹 페이지 본문 추출 (Tavily Extract API). URL 배열 입력 → markdown/text 형식 반환. JS 렌더링 페이지는 advanced 모드 사용.
+- `analyze_youtube`: `web_fetch`에 더해 추가적인 이점을 제공함. 유튜브 영상 ID를 입력받아 영상 제목, 설명, 스크립트로 추출한 transcript를 불러오고 경량 모델에게 readable한 분석 결과로 정리해서 반환시키는 subagent 실행
+
+---
+
+## 메모리 시스템
+
+### 디렉토리 구조
+
+```
+$U1Z_HOME/.u1z/prompt/MEMORIZE.md             # conversation 만료 후 메모리 요약 프롬프트
+$U1Z_HOME/.u1z/memory/MEMORY.txt             # 전역 공유 기억 (사용자 직접 편집)
+$U1Z_HOME/.u1z/memory/user/<userId>/YYMMDD.md  # DM 기억
+$U1Z_HOME/.u1z/memory/channel/<channelId>/YYMMDD.md  # 채널 기억
+```
+
+### 원칙
+
+- **기억 시점**: Conversation이 만료될 때 요약 프로세스가 실행되어 당일의 `YYMMDD.md` 파일에 내용을 추가한다.
+- **Daily 기억**: 각 범주의 `YYMMDD.md`로 관리한다. "기억해야겠다"는 판단이 발생했을 때 그날의 **첫 메시지 기준으로 파일을 생성**한다.
+- **용량 제한**: Daily 파일들의 용량 총합은 **100KB**를 상한으로 한다.
+- **압축 규칙**: Daily 파일들의 용량 총합이 상한을 초과하면 별도 워커 프로세스가 **gemini3 flash**로 압축한다. 워커는 **매일 새벽 3시**에 실행한다. Daily 메모리 디렉토리에서 **오래된 내용 기준 50% 분량**을 읽어 **절반 수준으로 요약**한 뒤, `YYMMDD~YYMMDD.md` 형태의 **range 파일**로 저장한다. 이 과정 후 Daily의 총량은 **약 75KB 수준**으로 수렴한다. 압축 시 기억 충돌되면 최신 내용을 반영하도록 워커 프로세스 프롬프트에 명시한다.
+
+---
+
+## 스킬 시스템
+
+```text
+$U1Z_HOME/.u1z/skills/
+├── shopping_coupang/
+└── shopping_oasis/
+```
+
+`SKILLS.md`에는 **스킬명 + 사용처(언제 어떤 작업에 쓰는지)**만 간단히 정리한다.
+시스템 프롬프트에는 `SKILLS.md`만 주입한다.
+
+### SKILLS.md 예시 (러프)
+
+스킬 안내 프롬프트는 BASE에 넣는 것도 고민중
+```text
+# Available SKILLS
+아래는 특정 작업을 수행할 때 사용 가능한 가이드라인입니다.
+스킬은 $U1Z_HOME/.u1z/skills/{skill-name}/SKILL.md 파일들에 저장되어 있습니다. 작업 성격에 따라 적절한 스킬을 bash로 가져와 사용하세요.
+또한 사용자는 스킬을 생성하거나 수정하라고 지시할 수 있습니다. 위 디렉토리 규칙에 맞게 스킬을 생성/수정하고 반드시 SKILLS.md에 스킬명과 사용처를 업데이트하세요.
+
+## shopping_coupang
+쿠팡에서 장보는 작업에 사용합니다. 식음료를 제외한 생필품 구매에도 사용합니다.
+
+## shopping_oasis
+오아시스에서 장보는 작업에 사용합니다.
+```
+
+---
+
+## LLM 모델 전략
+
+gpt5.2를 기본으로 사용하고, 비용 절감을 위해 경량 모델을 작업 복잡도에 따라 구분하여 사용.
+
+| 모델               | 담당 작업                                                                                     |
+| ------------------ | --------------------------------------------------------------------------------------------- |
+| **gpt5.2** (기본)  | Discord 메시지 수신/응답, 웹 브라우징, 장보기/예약 등 외부 서비스                             |
+| **gemini 3 flash** | 단기 기억 요약/정리, 중복 청크 합산, 상태 업데이트, youtube 요약, 혹은 e2e 테스트시 비용 절약 |
+
+---
+
+## 보안 설계
+
+- **유저 격리**: `u1z` 유저로 실행
+- **결제 차단**: iptables로 `u1z` 유저의 결제 도메인 OS 레벨 패킷 차단 — 프롬프트 인젝션으로도 뚫리지 않음
+- **자격증명**: Pass(GPG) 암호화, 로그에 `[REDACTED]` 마스킹
+- **승인 플로우**: Discord 채팅 확인만 유효, 웹 콘텐츠 승인 주장 무효
+
+---
+
+## 시작하기
+
+### 요구사항
+
+- Bun >= 1.0
+- Raspberry Pi OS (ARM64) — 배포 대상
+- Discord Bot Token (Developer Portal) — Gateway Intents / OAuth2 Scopes / 권한 설정은 [Discord Bot 설정](#discord-bot-설정) 참조
+- OpenAI API Key (gpt5.2 사용)
+- Tavily API Key (web_search, web_fetch 툴)
+- `U1Z_HOME` 환경변수 (`.u1z/prompt/BASE.md`를 포함한 u1z 루트 경로, 예: `/home/assistant/u1z`)
+- `DISCORD_HISTORY_LIMIT` 환경변수 (최근 히스토리 로드 개수, 기본값 `20`)
+- GPG 키 + Pass 설치 (자격증명 관리)
+
+### 로컬 개발 (macOS)
+
+```bash
+cp .env.example .env   # U1Z_HOME, API 키, DISCORD_HISTORY_LIMIT 설정
+bun install
+bun run dev
+```
+
+### Further Works (Good to have, MVP 이후)
+
+- 이미지/PDF 입력 (Discord 첨부파일 → LLM)
+- 웹 브라우징 (agent-browser)
+- 채널별 큐잉 처리(동시 messageCreate 순서 보장)
+- 패스워드 관리 (Pass/GPG)
+- API 인증 방식 설계 (관리용 엔드포인트 보호)
+- `bun init` 커맨드 한 방에 런타임 셋업
+- $U1Z_HOME/doc 에 산출 문서/보고서 등을 관리시키고, 인덱싱하여 search_doc() 툴로 grep보다 빠르게 검색하도록 함
+
+---

package/migrations/001_conversations.sql

@@ -0,0 +1,23 @@
+CREATE TABLE conversations (
+  id TEXT PRIMARY KEY,
+  channel_id TEXT NOT NULL,
+  scope TEXT NOT NULL,
+  model TEXT NOT NULL,
+  system_prompt TEXT NOT NULL,
+  last_message_at INTEGER NOT NULL,
+  memorized INTEGER NOT NULL DEFAULT 0
+);
+
+CREATE TABLE conversation_messages (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  conversation_id TEXT NOT NULL REFERENCES conversations(id) ON DELETE CASCADE,
+  role TEXT NOT NULL,
+  content TEXT NOT NULL,
+  created_at INTEGER NOT NULL
+);
+
+CREATE INDEX idx_messages_conv_created_at
+  ON conversation_messages(conversation_id, created_at);
+
+CREATE INDEX idx_conversations_last_message_at
+  ON conversations(last_message_at);

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@haenah/u1z",
+  "version": "0.1.0",
+  "description": "AI 집 비서 — Raspberry Pi home assistant powered by Claude + Discord",
+  "type": "module",
+  "bin": {
+    "u1z": "src/cli/index.ts"
+  },
+  "files": [
+    "src/",
+    "migrations/",
+    "u1z_home_bootstrap/",
+    "tsconfig.json"
+  ],
+  "scripts": {
+    "dev": "bun run --watch src/cli/index.ts server",
+    "start": "bun src/cli/index.ts server",
+    "test": "bun test src/",
+    "e2e": "bun test e2e/slash.test.ts && bun test e2e/basic.test.ts && bun test e2e/tools.test.ts && bun test e2e/memory.test.ts && bun test e2e/cache.test.ts && bun test e2e/recovery.test.ts",
+    "lint": "biome lint .",
+    "format": "biome format --write .",
+    "check": "biome check --write .",
+    "check:ci": "biome check .",
+    "typecheck": "tsc --noEmit",
+    "bootstrap": "bun run src/cli/index.ts init",
+    "repl": "bun run scripts/repl.ts",
+    "dep-graph": "bun run scripts/dep-graph.ts",
+    "prepare": "husky"
+  },
+  "dependencies": {
+    "@ai-sdk/google": "^3.0.31",
+    "@ai-sdk/openai": "^3.0.33",
+    "@tavily/core": "^0.7.2",
+    "ai": "^6.0.99",
+    "discord.js": "^14.18.0",
+    "hono": "^4.7.4",
+    "mustache": "^4.2.0",
+    "yargs": "^18.0.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.3",
+    "@types/bun": "latest",
+    "@types/mustache": "^4.2.6",
+    "@types/yargs": "^17.0.35",
+    "husky": "^9.1.7",
+    "ts-morph": "^27.0.2",
+    "typescript": "^5.9.3"
+  }
+}

package/src/ai/llm/model.ts

@@ -0,0 +1,15 @@
+import { google } from "@ai-sdk/google";
+import { openai } from "@ai-sdk/openai";
+import type { LanguageModel } from "ai";
+
+export const MODELS: Record<string, Extract<LanguageModel, { specificationVersion: "v3" }>> = {
+  md: openai("gpt-5.2"),
+  sm: google("gemini-3-flash-preview"),
+  xs: openai("gpt-5-nano"),
+} as const;
+
+export const PRICING = new Map([
+  [MODELS.md, { input: 1.75, cachedInput: 0.175, output: 14.0 }],
+  [MODELS.sm, { input: 0.5, cachedInput: 0.5, output: 3.0 }],
+  [MODELS.xs, { input: 0.05, cachedInput: 0.005, output: 0.4 }],
+]);

package/src/ai/llm/tools/analyzeYoutube.ts

@@ -0,0 +1,227 @@
+import { mkdir, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { generateText, tool } from "ai";
+import { z } from "zod";
+import { MODELS } from "../model";
+
+const LANG_PRIORITY = ["ko", "en", "ja", "zh"];
+
+const YtInfoSchema = z.object({
+  title: z.string().optional().default(""),
+  uploader: z.string().optional().default(""),
+  upload_date: z.string().optional().default(""),
+  view_count: z.number().optional().default(0),
+  description: z.string().optional().default(""),
+  tags: z.array(z.string()).optional().default([]),
+  language: z.string().nullish(),
+  subtitles: z.record(z.string(), z.unknown()).optional().default({}),
+  automatic_captions: z.record(z.string(), z.unknown()).optional().default({}),
+});
+
+async function spawnYtDlp(args: string[]): Promise<{ stderr: string; exitCode: number }> {
+  const proc = Bun.spawn(["yt-dlp", ...args], { stdout: "ignore", stderr: "pipe" });
+  const [stderr, exitCode] = await Promise.all([new Response(proc.stderr).text(), proc.exited]);
+  return { stderr: stderr.trim(), exitCode };
+}
+
+/**
+ * 자막 언어 선택 우선순위
+ *
+ * 목표: LLM에 원본 언어 텍스트를 전달해 번역 손실을 방지한다.
+ *
+ * [1단계] 수동 자막 (업로더가 직접 작성 → 가장 신뢰도 높음)
+ *   1-1. LANG_PRIORITY 순서로 수동 자막 탐색 (ko → en → ja → zh)
+ *   1-2. LANG_PRIORITY에 없으면 아무 수동 자막이나 선택
+ *
+ * [2단계] 자동자막 — 원본 언어 우선 (번역 자막 회피)
+ *   YouTube는 원본 언어 자동자막에 "{lang}-orig" 접미사를 붙인다.
+ *   예) 한국어 영상: "ko-orig" = 원본, "ko" = 번역본일 수 있음
+ *   2-1. originalLang이 있으면 "{originalLang}-orig" 키 우선 확인
+ *   2-2. originalLang 없어도 아무 "-orig" 키가 있으면 선택
+ *   2-3. "-orig" 없으면 originalLang → LANG_PRIORITY 순으로 폴백
+ *   2-4. 그래도 없으면 아무 자동자막이나 선택
+ *
+ * [실패] 수동/자동 자막 모두 없으면 null 반환 → "(자막 없음)" 처리
+ */
+function pickSubtitle(
+  subtitles: Record<string, unknown>,
+  automaticCaptions: Record<string, unknown>,
+  originalLang?: string,
+): { lang: string; auto: boolean } | null {
+  // 1-1. LANG_PRIORITY 순 수동 자막
+  for (const lang of LANG_PRIORITY) {
+    if (subtitles[lang]) return { lang, auto: false };
+  }
+  // 1-2. 기타 수동 자막
+  const anyManual = Object.keys(subtitles)[0];
+  if (anyManual) return { lang: anyManual, auto: false };
+
+  // 2-1. {originalLang}-orig
+  if (originalLang && automaticCaptions[`${originalLang}-orig`])
+    return { lang: `${originalLang}-orig`, auto: true };
+  // 2-2. 아무 -orig
+  const anyOrig = Object.keys(automaticCaptions).find((k) => k.endsWith("-orig"));
+  if (anyOrig) return { lang: anyOrig, auto: true };
+  // 2-3. originalLang → LANG_PRIORITY 폴백
+  const autoPriority = originalLang
+    ? [originalLang, ...LANG_PRIORITY.filter((l) => l !== originalLang)]
+    : LANG_PRIORITY;
+  for (const lang of autoPriority) {
+    if (automaticCaptions[lang]) return { lang, auto: true };
+  }
+  // 2-4. 아무 자동자막
+  const anyAuto = Object.keys(automaticCaptions)[0];
+  if (anyAuto) return { lang: anyAuto, auto: true };
+
+  return null;
+}
+
+function parseVtt(vtt: string): string {
+  const lines = vtt.split("\n");
+  const cleaned: string[] = [];
+  let prev = "";
+
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (!line) continue;
+    if (line === "WEBVTT") continue;
+    if (/^\d{2}:\d{2}:\d{2}\.\d{3} -->/.test(line)) continue;
+    const text = line.replace(/<[^>]+>/g, "").trim();
+    if (!text) continue;
+    if (text === prev) continue;
+    prev = text;
+    cleaned.push(text);
+  }
+
+  return cleaned.join(" ");
+}
+
+async function readFileIfExists(filePath: string): Promise<string | null> {
+  try {
+    return await Bun.file(filePath).text();
+  } catch {
+    return null;
+  }
+}
+
+async function findVttFile(tmpdir: string): Promise<string | null> {
+  const glob = new Bun.Glob("video*.vtt");
+  for await (const file of glob.scan(tmpdir)) {
+    return path.join(tmpdir, file);
+  }
+  return null;
+}
+
+export const analyzeYoutube = tool({
+  description:
+    "Analyze a YouTube video by extracting its subtitles and metadata without downloading the video. " +
+    "Use this tool whenever the user shares a YouTube URL",
+  inputSchema: z.object({
+    url: z.string().describe("YouTube video URL"),
+    question: z
+      .string()
+      .optional()
+      .describe("Question to answer about the video. Omit for a general summary."),
+  }),
+  execute: async ({ url, question }) => {
+    const tmpdir = path.join(os.tmpdir(), `u1z-yt-${Math.random().toString(36).slice(2)}`);
+    await mkdir(tmpdir, { recursive: true });
+
+    try {
+      // Pass 1: metadata only
+      const { stderr: infoStderr, exitCode: infoExit } = await spawnYtDlp([
+        "--skip-download",
+        "--write-info-json",
+        "-o",
+        path.join(tmpdir, "video"),
+        url,
+      ]);
+
+      if (infoExit !== 0) {
+        if (infoStderr.includes("command not found") || infoStderr.includes("No such file")) {
+          throw new Error("yt-dlp not found. Please install yt-dlp.");
+        }
+        throw new Error(`yt-dlp failed: ${infoStderr}`);
+      }
+
+      const infoJson = await readFileIfExists(path.join(tmpdir, "video.info.json"));
+      let meta = {
+        title: "",
+        uploader: "",
+        upload_date: "",
+        view_count: 0,
+        description: "",
+        tags: [] as string[],
+      };
+      let subtitleChoice: { lang: string; auto: boolean } | null = null;
+
+      if (infoJson) {
+        const parsed = YtInfoSchema.parse(JSON.parse(infoJson));
+        meta = {
+          title: parsed.title,
+          uploader: parsed.uploader,
+          upload_date: parsed.upload_date,
+          view_count: parsed.view_count,
+          description: parsed.description.slice(0, 500),
+          tags: parsed.tags.slice(0, 20),
+        };
+        subtitleChoice = pickSubtitle(
+          parsed.subtitles,
+          parsed.automatic_captions,
+          parsed.language ?? undefined,
+        );
+      }
+
+      // Pass 2: download chosen subtitle
+      // 실패 시 조용히 (자막 없음)으로 fallback — 메타데이터만으로도 분석을 계속한다
+      let transcript = "(자막 없음)";
+      if (subtitleChoice) {
+        const subFlag = subtitleChoice.auto ? "--write-auto-subs" : "--write-subs";
+        await spawnYtDlp([
+          "--skip-download",
+          subFlag,
+          "--sub-langs",
+          subtitleChoice.lang,
+          "--sub-format",
+          "vtt",
+          "-o",
+          path.join(tmpdir, "video"),
+          url,
+        ]);
+
+        const vttPath = await findVttFile(tmpdir);
+        if (vttPath) {
+          const vttContent = await readFileIfExists(vttPath);
+          if (vttContent) transcript = parseVtt(vttContent) || "(자막 없음)";
+        }
+      }
+
+      const prompt = `
+<video>
+  <metadata>
+    <title>${meta.title}</title>
+    <channel>${meta.uploader}</channel>
+    <upload_date>${meta.upload_date}</upload_date>
+    <view_count>${meta.view_count}</view_count>
+    <description>${meta.description}</description>
+    <tags>${meta.tags.join(", ")}</tags>
+  </metadata>
+  <transcript>${transcript}</transcript>
+</video>
+
+<question>${question ?? "위 영상 내용을 한국어로 요약해줘."}</question>
+`.trim();
+
+      const { text } = await generateText({
+        model: MODELS.sm,
+        messages: [{ role: "user", content: prompt }],
+        maxOutputTokens: 2048,
+      });
+
+      return text;
+    } finally {
+      await rm(tmpdir, { recursive: true, force: true });
+    }
+  },
+});

package/src/ai/llm/tools/bash.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, test } from "bun:test";
+import { executeBash } from "./bash";
+
+describe("bash tool", () => {
+  test("executes command and returns stdout", async () => {
+    const result = await executeBash({ command: "echo hello" });
+    expect(result.stdout).toBe("hello");
+    expect(result.exitCode).toBe(0);
+    expect(result.stderr).toBe("");
+  });
+
+  test("returns non-zero exit code for failed command", async () => {
+    const result = await executeBash({ command: "ls /nonexistent-path-xyz-u1z" });
+    expect(result.exitCode).not.toBe(0);
+    expect(result.stderr).not.toBe("");
+  });
+
+  test("captures both stdout and stderr", async () => {
+    const result = await executeBash({ command: "echo out && echo err >&2" });
+    expect(result.stdout).toBe("out");
+    expect(result.stderr).toBe("err");
+    expect(result.exitCode).toBe(0);
+  });
+});

package/src/ai/llm/tools/bash.ts

@@ -0,0 +1,20 @@
+import { tool } from "ai";
+import { z } from "zod";
+
+export async function executeBash({ command }: { command: string }) {
+  const proc = Bun.spawn(["sh", "-c", command], { stdout: "pipe", stderr: "pipe" });
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+  return { stdout: stdout.trim(), stderr: stderr.trim(), exitCode };
+}
+
+export const bash = tool({
+  description: "Execute a shell command and return its stdout, stderr, and exit code.",
+  inputSchema: z.object({
+    command: z.string().describe("Shell command to execute"),
+  }),
+  execute: executeBash,
+});

package/src/ai/llm/tools/tavilyClient.ts

@@ -0,0 +1,3 @@
+import { tavily } from "@tavily/core";
+
+export const tavilyClient = tavily({ apiKey: process.env.TAVILY_API_KEY });