@strayl/agent 0.1.0

package/INTEGRATION-PLAN.md

@@ -0,0 +1,385 @@
+# Интеграция strayl-agent SDK в strayl-app
+
+## Текущая архитектура (что заменяем)
+
+```
+Frontend (React)
+  → SSE POST /api/chat/stream (Next.js serverless, 800s maxDuration)
+    → createCodeAgent() — LangGraph agent работает IN-PROCESS
+    → Daytona SDK вызывает sandbox удалённо (exec, read, write через API)
+    → SSE events стримятся обратно
+    → EventBuffer сохраняет events в DB для reconnect
+```
+
+**Проблемы**: Agent умирает при timeout Vercel. LangGraph/deepagents — 200+ deps, постоянные патчи. Agent вне sandbox — все API ключи в env серверлесс функции.
+
+## Новая архитектура
+
+```
+Frontend (React)
+  → SSE POST /api/chat/stream (Next.js serverless, thin proxy)
+    → Daytona PTY: запускает `node agent.js --prompt "..." --model pro` ВНУТРИ sandbox
+    → PTY onData → парсит JSON-per-line → SSE events обратно фронтенду
+    → EventBuffer сохраняет events в DB (reconnect без изменений)
+```
+
+**Ключевое изменение**: Serverless функция больше НЕ запускает LangGraph. Она только:
+1. Создаёт/находит sandbox (как сейчас)
+2. Запускает `node agent.js` через PTY (как exec tool)
+3. Парсит stdout → SSE events
+4. Обрабатывает HITL (пишет файлы в sandbox)
+5. Пишет events в EventBuffer для reconnect
+
+**Agent SDK** уже установлен в sandbox snapshot (`strayl-sandbox`). Никакой npm install не нужен.
+
+---
+
+## Фаза 1: Sandbox Snapshot
+
+### 1.1 Обновить strayl-sandbox Docker image
+
+Добавить в snapshot:
+```dockerfile
+# Pre-install strayl-agent SDK
+COPY strayl-agent/dist/agent.js /opt/strayl/agent.js
+```
+
+Один файл 470KB, zero deps. При обновлении SDK — пересобрать snapshot.
+
+### 1.2 Env vars для sandbox
+
+При создании sandbox добавить:
+```typescript
+envVars: {
+  // Существующие
+  CHAT_ID: chatId,
+  PROJECT_SLUG: projectSlug,
+  BRANCH_NAME: branchName,
+  ...devEnvVars,
+  // Новые для SDK
+  STRAYL_SESSION_TOKEN: sessionToken,  // Auth для proxy
+  STRAYL_API_URL: "https://api.strayl.dev",
+  STRAYL_USERNAME: username,
+  STRAYL_PROJECT_SLUG: projectSlug,
+}
+```
+
+Не передаём: OPENROUTER_API_KEY, GEMINI_API_KEY, TAVILY_API_KEY — они живут только в api.strayl.dev.
+
+---
+
+## Фаза 2: Agent Runner (замена LangGraph)
+
+### 2.1 Новый файл: `strayl-app/lib/agent-runner.ts`
+
+```typescript
+/**
+ * Запускает strayl-agent SDK внутри sandbox через Daytona PTY.
+ * Парсит JSON-per-line stdout → вызывает callback для каждого event.
+ */
+export async function runAgentInSandbox(config: {
+  sandboxId: string;
+  prompt: string;
+  model: string;
+  mode: "normal" | "plan" | "implement";
+  sessionId: string;           // agent session (for checkpoints)
+  sessionToken: string;        // auth token for proxy
+  username: string;
+  projectSlug: string;
+  blockedTools?: string[];
+  maxIterations?: number;
+  images?: string[];           // R2 URLs → download in sandbox before start
+  previousSummary?: string;
+  restoreCheckpoint?: string;  // checkpoint file path
+  onEvent: (event: AgentEvent) => void;
+  onHitlRequest: (request: HitlRequest) => Promise<HitlResponse>;
+}): Promise<{ exitCode: number }> {
+
+  // Build CLI args
+  const args = [
+    "--model", config.model,
+    "--mode", config.mode,
+    "--prompt", config.prompt,
+    "--session-id", config.sessionId,
+    "--work-dir", "workspace",
+    "--hitl-dir", "/tmp/hitl",
+  ];
+  if (config.blockedTools?.length) {
+    args.push("--blocked-tools", config.blockedTools.join(","));
+  }
+  if (config.maxIterations) {
+    args.push("--max-iterations", String(config.maxIterations));
+  }
+  if (config.previousSummary) {
+    args.push("--previous-summary", config.previousSummary);
+  }
+  if (config.restoreCheckpoint) {
+    args.push("--restore-checkpoint", config.restoreCheckpoint);
+  }
+
+  const command = `node /opt/strayl/agent.js ${args.map(a => shellEscape(a)).join(" ")}`;
+
+  const daytona = getDaytona();
+  const sandbox = await daytona.get(config.sandboxId);
+
+  let lineBuffer = ""; // Buffer for incomplete JSON lines
+
+  // PTY — bidirectional: stdout for events, stdin for commands
+  const ptyHandle = await sandbox.process.createPty({
+    id: `agent-${config.sessionId}`,
+    cols: 200,
+    rows: 50,
+    onData: (data: Uint8Array) => {
+      const text = new TextDecoder().decode(data);
+      lineBuffer += text;
+
+      // Parse complete lines
+      const lines = lineBuffer.split("\n");
+      lineBuffer = lines.pop() || ""; // Keep incomplete last line in buffer
+
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed) continue;
+        try {
+          const event = JSON.parse(trimmed);
+          config.onEvent(event);
+        } catch {
+          // Not JSON — raw PTY noise, ignore
+        }
+      }
+    },
+  });
+
+  await ptyHandle.waitForConnection();
+
+  // Start the agent
+  await ptyHandle.sendInput(
+    new TextEncoder().encode(`cd workspace && ${command}\nexit $?\n`)
+  );
+
+  // Return send function so caller can communicate with agent
+  const sendToAgent = (cmd: object) => {
+    ptyHandle.sendInput(
+      new TextEncoder().encode(JSON.stringify(cmd) + "\n")
+    );
+  };
+
+  return { ptyHandle, sendToAgent };
+}
+```
+
+**Communication with running agent via PTY stdin:**
+
+```typescript
+// HITL response (user answered a question)
+sendToAgent({
+  type: "hitl-response",
+  id: "original-tool-call-id",
+  decision: "edit",
+  data: { answer: "blue" }
+});
+
+// User sends new message while agent is working
+sendToAgent({
+  type: "inject",
+  text: "actually change the color to red"
+});
+
+// User confirms plan
+sendToAgent({ type: "confirm-plan" });
+
+// User cancels
+sendToAgent({ type: "cancel" });
+
+// User rolls back to checkpoint
+sendToAgent({ type: "rollback", iteration: 5 });
+```
+```
+
+### 2.2 Маппинг events
+
+SDK events → существующие SSE events фронтенда (минимальные изменения в UI):
+
+| SDK event | SSE event (текущий) | Изменения в UI |
+|-----------|-------------------|----------------|
+| `session-start` | `run-started` | Добавить маппинг |
+| `text-delta` | `text-delta` | Без изменений |
+| `reasoning-delta` | `reasoning-delta` | Без изменений |
+| `tool-call-start` | `tool-call` | Переименовать |
+| `tool-result` | `tool-result` | Без изменений |
+| `exec-log` | `exec_log` | snake_case → as-is |
+| `file-complete` | `file-content-delta` | Адаптировать |
+| `hitl-request` | `interrupted` | Маппинг args → HITL UI |
+| `activity` | **НОВЫЙ** | Индикатор в UI |
+| `todos-update` | **НОВЫЙ** | Todo panel |
+| `session-end` | `run-finished` | Маппинг exit_reason |
+| `usage-update` | `credits-update` | Конвертация tokens → credits |
+| `plan-confirmed` | `plan-confirmed` | Без изменений |
+| `mode-changed` | **НОВЫЙ** | Mode indicator |
+| `checkpoint-saved` | — | Не стримить, только для DB |
+| `summarizing`/`summarized` | `summarization-complete` | Маппинг |
+
+---
+
+## Фаза 3: Замена route.ts
+
+### 3.1 Упрощение `/api/chat/stream/route.ts`
+
+Текущий файл: **1200+ строк**. Новый: **~300 строк**.
+
+Что остаётся:
+- Auth check
+- Create/find sandbox
+- Git setup (clone, branch) — без изменений
+- Credit gate
+- EventBuffer → DB
+- SSE stream setup + heartbeat
+
+Что удаляется:
+- `createCodeAgent()` и весь LangGraph
+- `extractStreamingFileContent()` — SDK делает это сам
+- Все tool-specific обработчики
+- `beforeModel`/`wrapToolCall` middleware
+- Checkpointer (SDK сохраняет свои checkpoints в sandbox)
+
+Что добавляется:
+- `runAgentInSandbox()` вызов
+- Event маппинг SDK → SSE
+- HITL bridge (frontend → file in sandbox)
+
+### 3.2 HITL Flow (через PTY stdin, не файлы)
+
+```
+1. Agent вызывает askUser → SDK emits hitl-request → PTY stdout → JSON line
+2. route.ts парсит → SSE "interrupted" с type=ask-user, options=[...]
+3. Frontend показывает UI → юзер выбирает
+4. Frontend POST /api/chat/stream с resume={decisions: [...]}
+5. route.ts → sendToAgent({ type: "hitl-response", id, decision, data })
+   → PTY stdin → agent's StdinListener парсит → agent продолжает
+```
+
+**Не нужен** файловый HITL transport (exec call) — PTY stdin быстрее и проще.
+Файловый HITL остаётся как fallback в SDK, но proxy его не использует.
+
+### 3.3 Plan Mode Flow
+
+```
+1. Frontend отправляет message с planMode=true
+2. route.ts запускает: node agent.js --mode plan --prompt "..."
+3. Agent исследует, вызывает writePlan → hitl-request → PTY stdout
+4. route.ts → SSE "interrupted" с type=plan, content=...
+5. Frontend показывает план → юзер подтверждает
+6. route.ts → sendToAgent({ type: "confirm-plan" }) → PTY stdin
+7. SDK делает context reset → продолжает в implement mode
+```
+
+### 3.4 Inject (юзер пишет во время работы агента)
+
+```
+1. Юзер пишет "actually make it red" пока агент работает
+2. Frontend POST /api/chat/stream с inject=true
+3. route.ts → sendToAgent({ type: "inject", text: "actually make it red" })
+4. SDK добавляет в контекст → agent увидит на следующей итерации
+```
+
+---
+
+## Фаза 4: Reconnect (без изменений!)
+
+EventBuffer остаётся как есть:
+- route.ts буферит events и POST'ит в DB через API
+- `/api/chat/events/[runId]` — polling endpoint без изменений
+- Frontend `use-agent-stream.ts` — reconnect через sessionStorage без изменений
+- `_seq` из SDK events используется напрямую
+
+Единственное изменение: маппинг event types в EventBuffer.
+
+---
+
+## Фаза 5: Frontend Changes
+
+### 5.1 `use-agent-stream.ts`
+
+Минимальные изменения:
+- Добавить обработку `activity` events → новый стейт `currentActivity`
+- Добавить обработку `mode-changed` events
+- Маппинг SDK event names → существующие UI event names (adapter слой)
+- HITL resume: без изменений (тот же POST /api/chat/stream с resume)
+
+### 5.2 Новый компонент: `ActivityIndicator`
+
+```tsx
+function ActivityIndicator({ activity }: { activity: ActivityType }) {
+  const labels: Record<ActivityType, string> = {
+    "creating-todos": "Creating to-do list...",
+    "asking-user": "Formulating question...",
+    "planning": "Writing plan...",
+    "reading-file": "Reading file...",
+    "writing-file": "Writing file...",
+    "running-command": "Running command...",
+    // ...
+  };
+  return <div className="activity-pill">{labels[activity]}</div>;
+}
+```
+
+### 5.3 Удалить из фронтенда
+
+- Все `file-content-delta` parsing (SDK стримит готовые events)
+- `extractStreamingFileContent` клиентский код
+- Plan mode toggle logic → упрощается (SDK управляет mode)
+
+---
+
+## Фаза 6: Удаление LangGraph
+
+После полной интеграции:
+
+### Удалить файлы:
+- `strayl-app/langgraph/` — весь каталог (~30 файлов)
+- `strayl-app/langgraph/backends/daytona.ts` — DaytonaSandboxBackend
+- `strayl-app/langgraph/tools/` — все инструменты (теперь в SDK)
+- `strayl-app/langgraph/agent.ts` — createCodeAgent (1500+ строк)
+- `strayl-app/patches/` — все patch-package файлы
+
+### Удалить зависимости из package.json:
+```
+@langchain/core
+@langchain/langgraph
+@langchain/openai
+deepagents
+patch-package
+```
+
+### Ожидаемый результат:
+- `node_modules/` уменьшается на 200+ пакетов
+- route.ts: 1200 строк → ~300 строк
+- Нет patch-package, нет хаков
+- Agent переживает timeout Vercel (живёт в sandbox)
+- API ключи не в sandbox env
+
+---
+
+## Порядок реализации
+
+1. **Sandbox snapshot** — добавить agent.js в image (30 мин)
+2. **agent-runner.ts** — новый файл, запуск SDK через PTY (2-3 часа)
+3. **route.ts v2** — переписать с agent-runner вместо LangGraph (4-6 часов)
+4. **Event adapter** — маппинг SDK events → SSE events (1-2 часа)
+5. **HITL bridge** — файловый transport через sandbox exec (1-2 часа)
+6. **Frontend adapter** — activity events + minor event name changes (2-3 часа)
+7. **Testing** — E2E: new chat → agent runs → tools work → HITL → plan mode (2-3 часа)
+8. **Cleanup** — удалить LangGraph, patches, old tools (1 час)
+
+---
+
+## Риски и Mitigation
+
+| Риск | Mitigation |
+|------|-----------|
+| PTY output buffering (неполные JSON lines) | Буферизация в agent-runner: собирать строки до `\n` |
+| Sandbox timeout (agent работает долго) | `autoStopInterval: 60` + heartbeat через PTY |
+| HITL latency | PTY stdin — мгновенно, не нужен exec call |
+| Agent crash in sandbox | PTY exit code ≠ 0 → SSE "run-finished" с error |
+| Concurrent stdin + stdout | PTY handles both natively, no race condition |
+| SDK version mismatch | Embed version in agent.js, check on start |

package/build.ts

@@ -0,0 +1,14 @@
+import { build } from "esbuild";
+
+await build({
+  entryPoints: ["src/index.ts"],
+  bundle: true,
+  platform: "node",
+  target: "node20",
+  format: "esm",
+  outfile: "dist/agent.js",
+  external: ["fsevents"],
+  minify: true,
+  sourcemap: true,
+  banner: { js: "#!/usr/bin/env node" },
+});