kcg-code 0.0.0-stage → 0.2.0

package/src/server/services/session-manager.ts

@@ -0,0 +1,1439 @@
+/**
+ * Session_Manager — lifecycle Session & orkestrasi headless opencode.
+ *
+ * Menggantikan versi PTY/TUI:
+ * - `createSession` memastikan server `opencode serve` untuk Project lalu
+ *   membuat Session di server headless (`POST /session`) — bukan spawn PTY.
+ * - Output bukan chunk terminal, melainkan `SessionMessage` terstruktur yang
+ *   disimpan di `messages` dan diteruskan via hook `onMessage`.
+ * - Prompt dikirim lewat `prompt_async` (204) dan turn ditutup oleh event
+ *   `session.idle` Session akar; pesan assistant dirakit dari parts SSE.
+ *   Sebelumnya balasan `POST /message` yang menggantung dipakai, sehingga turn
+ *   panjang (sub-agent) gagal tersimpan saat koneksi HTTP-nya putus.
+ * - Interactive_Prompt berasal dari event SSE terstruktur:
+ *   `permission.asked` (-> confirmation) dan `question.asked` (-> menu) —
+ *   `prompt-detector.ts` (regex atas teks TUI) dihapus. Varian `*.v2.asked`
+ *   ikut ditangani (skema opencode mengekspos keduanya) dengan penamaan field
+ *   berbeda: v2 memakai `action`/`resources`, v1 `permission`/`patterns`.
+ * - Sub-agent (`task`) dijalankan opencode sebagai Session terpisah dengan
+ *   `parentID`; `session.created` memetakan child tersebut ke Session lokal
+ *   induk agar prompt izin & streaming-nya tidak terbuang.
+ * - `resolvePrompt` menjawab lewat `POST /permission/{id}/reply` /
+ *   `POST /question/{id}/reply|reject` — bukan menulis `y\n` ke PTY.
+ *
+ * Prinsip error tetap sama: fungsi publik mengembalikan
+ * `{ ok: true, data } | { ok: false, error }`, dan Session berstatus
+ * `running` hanya setelah berhasil dibuat di server headless.
+ */
+import { randomUUID } from "node:crypto";
+import { existsSync, statSync } from "node:fs";
+import path from "node:path";
+import type { SessionStore } from "../../db";
+import { modelFacingMime } from "../../lib/attachments";
+import type {
+  AgentType,
+  InteractivePrompt,
+  MessagePart,
+  PromptResponse,
+  Session,
+  SessionContext,
+  SessionMessage,
+  SessionModel,
+  SessionStatus,
+} from "../../types";
+import type { Result, SimpleResult } from "../result";
+import type { AttachmentManager } from "./attachments";
+import { EMPTY_GIT_INFO, readGitInfo } from "./git-info";
+import type {
+  AgentOption,
+  McpServerInfo,
+  ModelOption,
+  OpenCodeClient,
+  OpenCodeEvent,
+  OpenCodeFileRef,
+  SkillInfo,
+} from "./opencode-client";
+import { OC_REQUEST_GONE } from "./opencode-client";
+import type { OpenCodeServerManager } from "./opencode-server";
+import {
+  deriveSessionTitle,
+  describeSessionError,
+  eventField as field,
+  friendlySendError,
+  isPlaceholderTitle,
+  permissionGroupKey,
+  promptFromPermission,
+  promptFromQuestion,
+  retryStatusMessage,
+} from "./session-events";
+import { TurnStream } from "./turn-stream";
+
+export const MAX_FREE_TEXT_LENGTH = 10000;
+/**
+ * Batas IDLE turn (jaring pengaman bila `session.idle` tak kunjung datang).
+ * Bukan batas total: timer di-reset tiap ada tanda hidup opencode (part
+ * streaming, pesan assistant, status busy/retry) — turn panjang yang sehat
+ * (reasoning panjang, tool lambat, sub-agent, retry provider) tidak dipotong;
+ * hanya keheningan TOTAL selama durasi ini yang memicu fail.
+ */
+export const TURN_IDLE_TIMEOUT_MS = 300_000;
+export const SHUTDOWN_BUDGET_MS = 5000;
+
+/**
+ * Tipe CLI_Agent yang dikenal. `claude-code` hanya aktif bila
+ * `claudeServers` diinjeksi (lihat `SessionManagerOptions`).
+ */
+export const SUPPORTED_AGENT_TYPES: readonly AgentType[] = ["opencode", "claude-code"];
+
+export interface CreateSessionRequest {
+  agentType: AgentType;
+  projectId: string;
+  /** Model pilihan user; null/undefined = model default opencode. */
+  model?: SessionModel | null;
+  /** Agent (mode) pilihan user; null/undefined = default opencode. */
+  agent?: string | null;
+}
+
+export type CreateSessionResult = { ok: true; session: Session } | { ok: false; error: string };
+
+export type { SimpleResult };
+
+/** Default jeda refresh skill tertunda setelah turn terakhir selesai. */
+const SKILL_REFRESH_DELAY_MS = 1500;
+
+export interface SessionManagerOptions {
+  store: SessionStore;
+  servers: OpenCodeServerManager;
+  /**
+   * Backend Claude Code (Agent SDK) dengan kontrak yang sama dengan
+   * `servers`. Tidak diisi -> Session `claude-code` ditolak.
+   */
+  claudeServers?: OpenCodeServerManager;
+  /**
+   * Penyimpanan lampiran gambar (upload dari perangkat). Bila tidak diisi,
+   * fitur gambar dinonaktifkan — pesan dengan `images` ditolak.
+   */
+  attachments?: AttachmentManager;
+  now?: () => number;
+  shutdownBudgetMs?: number;
+  /**
+   * Batas idle turn (ms) — jaring pengaman bila `session.idle` tak kunjung
+   * datang. Di-reset tiap ada tanda hidup; bukan batas total turn.
+   */
+  turnIdleTimeoutMs?: number;
+  setTimeoutFn?: (cb: () => void, ms: number) => unknown;
+  clearTimeoutFn?: (handle: unknown) => void;
+  /** Hook pesan baru — disambungkan ke WebSocket_Gateway. */
+  onMessage?: (message: SessionMessage) => void;
+  /**
+   * Hook part pesan yang sedang di-stream (SSE `message.part.updated`).
+   * `messageId` = id pesan assistant di opencode yang sedang dibangun.
+   */
+  onMessagePart?: (sessionId: string, messageId: string, part: MessagePart) => void;
+  /**
+   * Hook potongan teks streaming (SSE `message.part.delta`) — token model
+   * tiba lewat event ini; lihat `TurnStream.acceptDelta`.
+   */
+  onMessagePartDelta?: (
+    sessionId: string,
+    messageId: string,
+    partId: string,
+    field: string,
+    delta: string,
+  ) => void;
+  /** Hook Interactive_Prompt baru — disambungkan ke WebSocket_Gateway. */
+  onPrompt?: (prompt: InteractivePrompt) => void;
+  /**
+   * Hook prompt kembar yang ikut ter-resolve lewat fan-out jawaban kartu
+   * grup (lihat `permissionGroupKey`) — agar kartu kembar hilang dari UI
+   * client lain tanpa menunggu reattach.
+   */
+  onPromptResolved?: (sessionId: string, promptId: string) => void;
+  /** Hook perubahan status Session — disambungkan ke WebSocket_Gateway. */
+  onStatusChange?: (sessionId: string, status: SessionStatus) => void;
+  /**
+   * Hook judul Session baru hasil generate opencode (SSE `session.updated`
+   * setelah prompt pertama) — disambungkan ke WebSocket_Gateway agar daftar
+   * Session di Client ikut terbarui tanpa reload.
+   */
+  onTitleChange?: (sessionId: string, title: string) => void;
+  /** Hook Session dihapus permanen — disambungkan ke WebSocket_Gateway. */
+  onDeleted?: (sessionId: string) => void;
+  /** Hook error asinkron (mis. balasan model gagal) — disambungkan ke gateway. */
+  onError?: (sessionId: string, message: string) => void;
+  /**
+   * Hook perubahan status turn — `true` saat model mulai merespon (turn
+   * streaming aktif), `false` saat turn selesai/dibatalkan. Disambungkan ke
+   * gateway agar Client tahu kapan tombol stop (interrupt) perlu tampil.
+   */
+  onTurnChange?: (sessionId: string, active: boolean) => void;
+  /**
+   * Refresh skill yang sempat tertunda (turn aktif saat skill dipasang) baru
+   * saja dijalankan otomatis untuk Project ini.
+   */
+  onSkillsRefreshed?: (projectId: string) => void;
+  /** Jeda refresh skill tertunda setelah turn terakhir selesai (ms). */
+  skillRefreshDelayMs?: number;
+}
+
+export interface SessionManager {
+  createSession(req: CreateSessionRequest): Promise<CreateSessionResult>;
+  listSessions(): Session[];
+  getSession(sessionId: string): Result<Session>;
+  stopSession(sessionId: string): SimpleResult;
+  /**
+   * Hentikan balasan model yang sedang berlangsung (interrupt ala opencode):
+   * turn remote di-abort, parts yang sudah ter-stream disimpan, tapi Session
+   * TETAP `running` — user bisa langsung kirim pesan baru tanpa Start ulang.
+   */
+  interruptSession(sessionId: string): SimpleResult;
+  /**
+   * Hapus Session permanen: pastikan server headless opencode hidup (spawn
+   * ulang bila perlu) lalu hapus session remote di sana (beserta riwayat
+   * pesannya), kemudian baris Session di Session_Store.
+   */
+  deleteSession(sessionId: string): Promise<SimpleResult>;
+  /**
+   * Menghidupkan kembali Session yang `stopped`/`crashed` — memakai ocSessionId
+   * lama bila masih dikenal server headless, memakai sesi remote baru bila
+   * tidak, lalu status kembali `running`.
+   */
+  resumeSession(sessionId: string): Promise<SimpleResult>;
+  /**
+   * Lepaskan seluruh sumber daya milik satu Project sebelum Project dihapus:
+   * hapus tiap Session-nya (termasuk sesi remote opencode & lampiran) lalu
+   * hentikan server headless Project. Gagal pada salah satu Session ->
+   * error diteruskan tanpa melanjutkan, agar tidak ada sesi yatim.
+   */
+  releaseProject(projectId: string): Promise<SimpleResult>;
+  /** Daftar model yang tersedia pada server headless milik Project. */
+  listModels(projectId: string, agentType?: AgentType): Promise<Result<ModelOption[]>>;
+  /**
+   * Daftar agent (mode) opencode milik Project — primary/all saja, siap
+   * ditampilkan di pemilih mode composer.
+   */
+  listAgents(projectId: string, agentType?: AgentType): Promise<Result<AgentOption[]>>;
+  /** Status MCP server yang terkonfigurasi untuk Project. */
+  listMcp(projectId: string, agentType?: AgentType): Promise<Result<McpServerInfo[]>>;
+  /** Skill yang terdaftar untuk Project (global, folder Project, bawaan). */
+  listSkills(projectId: string, agentType?: AgentType): Promise<Result<SkillInfo[]>>;
+  /**
+   * Muat ulang daftar skill server headless Project setelah skill dipasang.
+   * Bila ada turn aktif di Project, refresh ditunda (`refreshed: false`) agar
+   * chat yang berjalan tidak terganggu — lalu dijalankan OTOMATIS begitu
+   * seluruh turn di Project selesai (`onSkillsRefreshed`). Server yang belum
+   * hidup tidak perlu di-refresh. Claude Code selalu langsung `refreshed`.
+   */
+  refreshSkills(projectId: string, agentType?: AgentType): Promise<Result<{ refreshed: boolean }>>;
+  /** Project dengan refresh skill tertunda (menunggu turn selesai). */
+  hasPendingSkillRefresh(projectId: string): boolean;
+  /** Cari file project untuk autocomplete `@file` di composer. */
+  findFiles(projectId: string, query: string, agentType?: AgentType): Promise<Result<string[]>>;
+  /**
+   * Konteks kerja Session untuk panel kanan: perubahan file di worktree,
+   * cabang git, dan task list (`todowrite`) agent.
+   */
+  sessionContext(sessionId: string): Promise<Result<SessionContext>>;
+  /** Ganti model pilihan Session (`null` = kembali ke default opencode). */
+  setSessionModel(sessionId: string, model: SessionModel | null): SimpleResult;
+  /**
+   * Ganti agent (mode) pilihan Session — `build`, `plan`, atau agent kustom
+   * (`null` = default opencode). Berlaku pada prompt berikutnya.
+   */
+  setSessionAgent(sessionId: string, agent: string | null): SimpleResult;
+  /**
+   * Kirim input bebas. `files` = path relatif project (`@file`); `images` =
+   * id lampiran di Attachment_Store (gambar upload dari perangkat).
+   */
+  sendFreeTextInput(
+    sessionId: string,
+    text: string,
+    files?: string[],
+    images?: string[],
+  ): Promise<SimpleResult>;
+  resolvePrompt(
+    sessionId: string,
+    promptId: string,
+    response: PromptResponse,
+  ): Promise<SimpleResult>;
+  reconcileOnStartup(): void;
+  shutdown(): Promise<void>;
+}
+
+/**
+ * Membuat instance Session_Manager terikat pada `store` dan `servers`.
+ * `servers` (OpenCode_Server), `now`, dan timer dapat diinjeksi untuk test.
+ */
+export function createSessionManager(opts: SessionManagerOptions): SessionManager {
+  const store = opts.store;
+  const servers = opts.servers;
+  const claudeServers = opts.claudeServers;
+
+  /** Server manager backend milik tipe CLI_Agent. */
+  function serversFor(agentType: AgentType): OpenCodeServerManager {
+    return agentType === "claude-code" && claudeServers ? claudeServers : servers;
+  }
+
+  /** Kunci subscription/exit per backend + Project (keduanya bisa hidup). */
+  function backendKey(agentType: AgentType, projectId: string): string {
+    return agentType === "claude-code" ? `claude-code:${projectId}` : projectId;
+  }
+  const attachments = opts.attachments;
+  const now = opts.now ?? Date.now;
+  const shutdownBudgetMs = opts.shutdownBudgetMs ?? SHUTDOWN_BUDGET_MS;
+  const turnIdleTimeoutMs = opts.turnIdleTimeoutMs ?? TURN_IDLE_TIMEOUT_MS;
+  const setTimeoutFn = opts.setTimeoutFn ?? ((cb: () => void, ms: number) => setTimeout(cb, ms));
+  const clearTimeoutFn =
+    opts.clearTimeoutFn ??
+    ((handle: unknown) => clearTimeout(handle as ReturnType<typeof setTimeout>));
+  const onMessage = opts.onMessage;
+  const onPrompt = opts.onPrompt;
+  const onPromptResolved = opts.onPromptResolved;
+  const onStatusChange = opts.onStatusChange;
+  const onTitleChange = opts.onTitleChange;
+  const onDeleted = opts.onDeleted;
+  const onError = opts.onError;
+
+  /**
+   * Project yang refresh skill-nya tertunda karena ada turn aktif saat skill
+   * dipasang. Dijalankan otomatis begitu seluruh turn di Project selesai.
+   */
+  const pendingSkillRefresh = new Set<string>();
+  /** Timer refresh tertunda per Project (dibatalkan bila turn baru dimulai). */
+  const skillRefreshTimers = new Map<string, unknown>();
+  /** Jeda setelah turn terakhir selesai sebelum dispose (biarkan event penutup tuntas). */
+  const skillRefreshDelayMs = opts.skillRefreshDelayMs ?? SKILL_REFRESH_DELAY_MS;
+  const onSkillsRefreshed = opts.onSkillsRefreshed;
+
+  const onTurnChange = (sessionId: string, active: boolean): void => {
+    opts.onTurnChange?.(sessionId, active);
+    const projectId = store.getSession(sessionId);
+    if (!projectId.ok || !pendingSkillRefresh.has(projectId.data.projectId)) return;
+    if (active) {
+      // Turn baru dimulai sebelum timer jalan -> tunda lagi.
+      cancelScheduledSkillRefresh(projectId.data.projectId);
+    } else {
+      scheduleSkillRefresh(projectId.data.projectId);
+    }
+  };
+
+  /**
+   * Pemetaan ocSessionId (opencode) -> id Session lokal.
+   *
+   * Selain Session yang dibuat lewat `POST /session`, map ini juga memuat
+   * child session yang dibuat opencode sendiri saat model memanggil `task`
+   * (sub-agent). Child session punya `sessionID` sendiri di SSE, sehingga tanpa
+   * pemetaan ini event-nya (termasuk `permission.asked`) akan terbuang.
+   */
+  const ocToSession = new Map<string, string>();
+  /** Kebalikan `ocToSession`: id Session lokal -> seluruh ocSessionId miliknya. */
+  const sessionOcIds = new Map<string, Set<string>>();
+  /** Backend+Project yang event-nya sudah disubscribe (lihat `backendKey`). */
+  const activeSubscriptions = new Map<string, { active: boolean; unsubscribe: () => void }>();
+  /** Serialisasi kirim pesan per Session agar turn tidak tumpang tindih. */
+  const inflight = new Map<string, Promise<void>>();
+  /** Backend+Project yang sudah diproses saat server-nya keluar (hindari duplikasi). */
+  const exitNotified = new Set<string>();
+  const onMessagePart = opts.onMessagePart;
+  const onMessagePartDelta = opts.onMessagePartDelta;
+
+  /** State turn streaming per Session (finish/discard/fail + timer idle). */
+  const turns = new TurnStream({
+    store,
+    now,
+    onMessage,
+    onMessagePart,
+    onMessagePartDelta,
+    onError,
+    onTurnChange,
+    // Turn menunggu keputusan user (kartu permission/question pending) bukan
+    // keheningan — timer idle ditunda sampai kartu dijawab atau turn ditutup.
+    shouldFireIdle: (sessionId) => store.listPendingPrompts(sessionId).length === 0,
+    setTimeoutFn,
+    clearTimeoutFn,
+  });
+
+  function updateStatus(sessionId: string, status: SessionStatus, changedAt: number): void {
+    const res = store.updateSessionStatus(sessionId, status, changedAt);
+    if (res.ok) onStatusChange?.(sessionId, status);
+  }
+
+  function updatePromptResolved(promptId: string): void {
+    store.updatePromptStatus(promptId, "resolved", now());
+  }
+
+  /** Catat pemetaan ocSessionId -> Session lokal (juga untuk cleanup). */
+  function mapOcSession(ocSessionId: string, sessionId: string): void {
+    ocToSession.set(ocSessionId, sessionId);
+    let owned = sessionOcIds.get(sessionId);
+    if (!owned) {
+      owned = new Set<string>();
+      sessionOcIds.set(sessionId, owned);
+    }
+    owned.add(ocSessionId);
+  }
+
+  /** Lepas seluruh ocSessionId (induk + child) milik satu Session lokal. */
+  function unmapOcSessions(sessionId: string): void {
+    const owned = sessionOcIds.get(sessionId);
+    if (!owned) return;
+    for (const ocId of owned) ocToSession.delete(ocId);
+    sessionOcIds.delete(sessionId);
+  }
+
+  /**
+   * Daftarkan child session (sub-agent `task`) ke Session lokal induknya.
+   *
+   * opencode membuat session baru untuk setiap sub-agent dengan `parentID`
+   * menunjuk session pemanggil. Event-nya (`permission.asked`, `message.*`)
+   * memakai `sessionID` child, jadi tanpa pemetaan ini prompt izin sub-agent
+   * tidak akan pernah sampai ke Client dan turn menggantung sampai timeout.
+   * Rantai bersarang ikut tertangani karena induk sudah lebih dulu terpetakan.
+   */
+  function registerChildSession(ev: OpenCodeEvent): void {
+    const info = field(ev, "info");
+    if (typeof info !== "object" || info === null) return;
+    const { id, parentID } = info as { id?: unknown; parentID?: unknown };
+    if (typeof id !== "string" || typeof parentID !== "string") return;
+    if (ocToSession.has(id)) return; // sudah terpetakan (mis. session induk)
+    const sessionId = ocToSession.get(parentID);
+    if (!sessionId) return; // induk bukan Session milik KCG Code — abaikan
+    mapOcSession(id, sessionId);
+  }
+
+  /**
+   * Handler event SSE dari satu server (per Project).
+   * Selain permission/question, kini memproses streaming:
+   * - `session.created` dengan `parentID` -> petakan child sub-agent ke induk.
+   * - `message.updated` role=assistant -> catat id pesan assistant (turn).
+   * - `message.part.updated` -> forward part ke Client (via onMessagePart).
+   * - `message.part.delta` -> potongan teks streaming (via onMessagePartDelta).
+   */
+  function handleEvent(_projectId: string, ev: OpenCodeEvent): void {
+    if (ev.type === "session.created") {
+      registerChildSession(ev);
+      return;
+    }
+    if (ev.type === "session.updated") {
+      // Judul Session dibuat otomatis opencode setelah prompt pertama
+      // (summarization). Hanya Session AKAR yang dipetakan yang diproses —
+      // child sub-agent tidak mewakili percakapan user.
+      const info = field(ev, "info");
+      if (typeof info !== "object" || info === null) return;
+      const { id, title } = info as { id?: unknown; title?: unknown };
+      if (typeof id !== "string" || typeof title !== "string") return;
+      if (title.trim() === "") return;
+      // Placeholder (`New session - <ISO>`, judul lama "KCG Code Session")
+      // bukan judul percakapan — abaikan agar tidak menimpa judul sementara.
+      // Judul hasil opencode selalu menggantikan judul sementara lokal.
+      if (isPlaceholderTitle(title)) return;
+      const sessionId = ocToSession.get(id);
+      if (sessionId === undefined) return;
+      // Hanya Session akar: judul child sub-agent bukan judul percakapan
+      // user (guard yang sama dengan `session.idle` di bawah).
+      const cur = store.getSession(sessionId);
+      if (!cur.ok || cur.data.ocSessionId !== id) return;
+      if (cur.data.title === title) return;
+      if (!store.updateSessionTitle(sessionId, title).ok) return;
+      onTitleChange?.(sessionId, title);
+      return;
+    }
+    if (ev.type === "session.idle") {
+      const ocId = field(ev, "sessionID", "sessionId");
+      if (typeof ocId !== "string") return;
+      const sessionId = ocToSession.get(ocId);
+      if (!sessionId) return;
+      // Sub-agent idle lebih dulu dari induknya; hanya idle Session akar yang
+      // menandai turn selesai, jika tidak turn terpotong di tengah.
+      const cur = store.getSession(sessionId);
+      if (!cur.ok || cur.data.ocSessionId !== ocId) return;
+      turns.finish(sessionId);
+      return;
+    }
+    if (ev.type === "session.error") {
+      const ocId = field(ev, "sessionID", "sessionId");
+      if (typeof ocId !== "string") return;
+      const sessionId = ocToSession.get(ocId);
+      if (!sessionId) return;
+      const err = field(ev, "error");
+      const errName =
+        typeof err === "object" && err !== null ? (err as { name?: unknown }).name : undefined;
+      // MessageAbortedError = turn dibatalkan (interrupt user / reject prompt).
+      // Bukan kegagalan: parts yang sudah ter-stream disimpan tanpa banner error.
+      const aborted = errName === "MessageAbortedError";
+      const message = describeSessionError(ev);
+      if (turns.has(sessionId)) {
+        if (aborted) turns.finish(sessionId);
+        else turns.noteError(sessionId, message);
+      } else if (!aborted) {
+        // Tanpa turn aktif, abort berarti turn sudah ditutup interrupt/stop -
+        // jangan tampilkan banner "Pemrosesan prompt dibatalkan" ke Client.
+        onError?.(sessionId, message);
+      }
+      return;
+    }
+    if (ev.type === "session.status") {
+      // Saat provider model error yang bisa di-retry (rate limit, kredit habis,
+      // cooldown, 5xx), opencode memancarkan `status: { type: "retry", ... }`
+      // alih-alih langsung gagal — turn TETAP berjalan selama backoff retry.
+      // Tanpa banner ini Client menunggu diam-diam sampai retry habis atau
+      // batas idle turn. Status apa pun (busy/retry) adalah tanda hidup:
+      // reset timer idle agar turn panjang tidak dipotong.
+      const ocId = field(ev, "sessionID", "sessionId");
+      if (typeof ocId !== "string") return;
+      const sessionId = ocToSession.get(ocId);
+      if (!sessionId) return;
+      turns.keepAlive(sessionId);
+      const status = field(ev, "status");
+      const message = retryStatusMessage(status);
+      if (message) onError?.(sessionId, message);
+      return;
+    }
+    if (ev.type === "message.updated") {
+      const ocId = field(ev, "sessionID", "sessionId");
+      if (typeof ocId !== "string") return;
+      const sessionId = ocToSession.get(ocId);
+      if (!sessionId) return;
+      const info = field(ev, "info");
+      if (info && typeof info === "object") {
+        const role = (info as { role?: unknown }).role;
+        const id = (info as { id?: unknown }).id;
+        if (role === "assistant" && typeof id === "string") {
+          turns.noteAssistantMessage(sessionId, id);
+        }
+      }
+      return;
+    }
+    if (ev.type === "message.part.updated") {
+      const ocId = field(ev, "sessionID", "sessionId");
+      if (typeof ocId !== "string") return;
+      const sessionId = ocToSession.get(ocId);
+      if (!sessionId) return;
+      const part = field(ev, "part");
+      if (typeof part !== "object" || part === null) return;
+      const p = part as MessagePart & { messageID?: unknown };
+      const messageId = p.messageID;
+      if (typeof messageId !== "string") return;
+      turns.acceptPart(sessionId, messageId, p);
+      return;
+    }
+    if (ev.type === "message.part.delta") {
+      const ocId = field(ev, "sessionID", "sessionId");
+      if (typeof ocId !== "string") return;
+      const sessionId = ocToSession.get(ocId);
+      if (!sessionId) return;
+      const messageId = field(ev, "messageID", "messageId");
+      const partId = field(ev, "partID", "partId");
+      const name = field(ev, "field");
+      const delta = field(ev, "delta");
+      if (
+        typeof messageId !== "string" ||
+        typeof partId !== "string" ||
+        typeof name !== "string" ||
+        typeof delta !== "string"
+      ) {
+        return;
+      }
+      turns.acceptDelta(sessionId, messageId, partId, name, delta);
+      return;
+    }
+    // v1 & v2 memakai id request yang sama (`per_...`), dan `prompts.id` adalah
+    // PRIMARY KEY — jadi bila server memancarkan keduanya, insert kedua gagal
+    // dan kartu tidak terduplikasi.
+    if (ev.type === "permission.asked" || ev.type === "permission.v2.asked") {
+      const ocId = field(ev, "sessionID", "sessionId");
+      if (typeof ocId !== "string") return;
+      const sessionId = ocToSession.get(ocId);
+      if (!sessionId) return;
+      // Turn sedang MENUNGGU keputusan user — bukan sunyi: reset timer idle
+      // agar turn tidak dipotong saat user lambat menjawab kartu izin.
+      turns.keepAlive(sessionId);
+      const prompt = promptFromPermission(ev, sessionId, now());
+      if (!store.insertPrompt(prompt).ok) return; // duplikat -> abaikan
+      onPrompt?.(prompt);
+      return;
+    }
+    if (ev.type === "question.asked" || ev.type === "question.v2.asked") {
+      const ocId = field(ev, "sessionID", "sessionId");
+      if (typeof ocId !== "string") return;
+      const sessionId = ocToSession.get(ocId);
+      if (!sessionId) return;
+      // Sama seperti permission: menunggu jawaban user = tanda hidup.
+      turns.keepAlive(sessionId);
+      const prompt = promptFromQuestion(ev, sessionId, now());
+      if (!store.insertPrompt(prompt).ok) return;
+      onPrompt?.(prompt);
+    }
+  }
+
+  /**
+   * Pastikan server Project hidup; subscribe event SSE bila belum aktif.
+   * `refreshConfig` = true: bila file config opencode berubah, server
+   * di-restart dulu (dipakai listModels/listAgents agar daftar ikut
+   * terbaca ulang — `opencode serve` tidak hot-reload config). Setelah
+   * restart, subscription SSE lama dibuang dan diganti milik server baru.
+   */
+  async function ensureServerFor(
+    projectId: string,
+    projectPath: string,
+    opts: { refreshConfig?: boolean; agentType?: AgentType } = {},
+  ): Promise<Result<{ client: OpenCodeClient }>> {
+    const agentType = opts.agentType ?? "opencode";
+    const backend = serversFor(agentType);
+    const key = backendKey(agentType, projectId);
+    const prevClient = backend.getServer(projectId)?.client;
+    const ensure = opts.refreshConfig
+      ? backend.ensureFreshServer(projectId, projectPath)
+      : backend.ensureServer(projectId, projectPath);
+    const res = await ensure;
+    if (!res.ok) return { ok: false, error: res.error };
+    const handle = res.data;
+    // Server headless dapat diganti (crash lalu ensure ulang, resume, atau
+    // restart config). Bila client berbeda dari sebelumnya, subscription
+    // lama tidak lagi menempel — buang dan subscribe ulang ke instance baru.
+    const sub = activeSubscriptions.get(key);
+    if (prevClient && handle.client !== prevClient) {
+      sub?.unsubscribe();
+      activeSubscriptions.delete(key);
+    }
+    if (!activeSubscriptions.get(key)?.active) {
+      const prev = activeSubscriptions.get(key);
+      prev?.unsubscribe();
+      const unsubscribe = handle.client.subscribeEvents((ev) => handleEvent(projectId, ev));
+      activeSubscriptions.set(key, { active: true, unsubscribe });
+    }
+    // Server baru (atau hasil restart) — izinkan event exit berikutnya diproses.
+    exitNotified.delete(key);
+    return { ok: true, data: { client: handle.client } };
+  }
+
+  function enqueue(sessionId: string, task: () => Promise<void>): void {
+    const prev = inflight.get(sessionId) ?? Promise.resolve();
+    const next = prev.then(task).finally(() => {
+      if (inflight.get(sessionId) === next) inflight.delete(sessionId);
+    });
+    inflight.set(sessionId, next);
+  }
+
+  async function createSession(req: CreateSessionRequest): Promise<CreateSessionResult> {
+    // (1) tipe CLI_Agent didukung (Requirement 1.3)
+    if (
+      !SUPPORTED_AGENT_TYPES.includes(req.agentType) ||
+      (req.agentType === "claude-code" && !claudeServers)
+    ) {
+      return { ok: false, error: "UNSUPPORTED_AGENT_TYPE" };
+    }
+    // (2) Project ada di Session_Store (Requirement 10.10)
+    const projectRes = store.getProjectById(req.projectId);
+    if (!projectRes.ok) return { ok: false, error: "PROJECT_NOT_FOUND" };
+    const project = projectRes.data;
+    // (3) direktori kerja Project masih ada di filesystem (Requirement 10.11)
+    let dirExists = false;
+    try {
+      dirExists = existsSync(project.path) && statSync(project.path).isDirectory();
+    } catch {
+      dirExists = false;
+    }
+    if (!dirExists) return { ok: false, error: "PROJECT_DIR_NOT_FOUND" };
+
+    // (4) pastikan server headless untuk Project (spawn bila perlu)
+    const serverRes = await ensureServerFor(project.id, project.path, {
+      agentType: req.agentType,
+    });
+    if (!serverRes.ok) return { ok: false, error: serverRes.error };
+    const client = serverRes.data.client;
+
+    // (5) validasi model pilihan terhadap daftar provider server (Req: pilih
+    //     model). `null` = pakai default opencode. Daftar provider gagal
+    //     diambil -> ditolak agar Session tidak lahir dengan model mati.
+    const model: SessionModel | null = req.model ?? null;
+    if (model) {
+      const models = await client.listModels();
+      if (!models.ok) return { ok: false, error: models.error };
+      const known = models.data.some(
+        (m) => m.providerID === model.providerID && m.modelID === model.modelID,
+      );
+      if (!known) return { ok: false, error: "MODEL_NOT_FOUND" };
+    }
+
+    // (6) buat Session di server headless — TANPA judul, agar opencode
+    //     meng-generate judul dari prompt pertama (lihat lib/session-title.ts).
+    const created = await client.createSession();
+    if (!created.ok) return { ok: false, error: created.error };
+
+    const sessionId = randomUUID();
+    const createdAt = now();
+    // Judul awal opencode berupa placeholder (`New session - <ISO>`) — tidak
+    // disimpan. Judul datang dari SSE `session.updated`; sementara itu
+    // `sendFreeTextInput` memberi judul turunan prompt pertama.
+    const remoteTitle =
+      typeof created.data.title === "string" && !isPlaceholderTitle(created.data.title)
+        ? created.data.title
+        : null;
+    const session: Session = {
+      id: sessionId,
+      projectId: project.id,
+      agentType: req.agentType,
+      cwd: project.path,
+      status: "running",
+      ocSessionId: created.data.id,
+      title: remoteTitle,
+      model,
+      agent: req.agent ?? null,
+      createdAt,
+      updatedAt: createdAt,
+    };
+    const ins = store.insertSession(session);
+    if (!ins.ok) {
+      // Abort session remote agar tidak jadi yatim bila persistensi gagal.
+      void client.abortSession(created.data.id);
+      return ins;
+    }
+    mapOcSession(created.data.id, sessionId);
+    return { ok: true, session };
+  }
+
+  function listSessions(): Session[] {
+    return store.listSessions();
+  }
+
+  function getSession(sessionId: string): Result<Session> {
+    return store.getSession(sessionId);
+  }
+
+  function stopSession(sessionId: string): SimpleResult {
+    const cur = store.getSession(sessionId);
+    if (!cur.ok) return { ok: false, error: "SESSION_NOT_FOUND" };
+    if (cur.data.status !== "running") return { ok: false, error: "SESSION_NOT_RUNNING" };
+    // Abort turn berjalan (best-effort, tidak menunggu).
+    if (cur.data.ocSessionId) {
+      const handle = serversFor(cur.data.agentType).getServer(cur.data.projectId);
+      void handle?.client.abortSession(cur.data.ocSessionId);
+    }
+    // Simpan parts yang sudah terkumpul sebelum Session ditutup.
+    turns.finish(sessionId);
+    // Lepas induk + seluruh child sub-agent milik Session ini.
+    unmapOcSessions(sessionId);
+    updateStatus(sessionId, "stopped", now());
+    return { ok: true };
+  }
+
+  /**
+   * Hentikan balasan model yang sedang berlangsung (interrupt ala opencode):
+   * - Turn remote di-abort (best-effort, tidak menunggu).
+   * - Parts yang sudah ter-stream DIBUANG (tidak disimpan) — user membatalkan
+   *   balasan, sehingga respon parsial tidak boleh muncul di riwayat/UI.
+   * - Session TETAP `running` dan pemetaan SSE dipertahankan — user bisa
+   *   langsung mengirim pesan baru tanpa Start ulang.
+   * Idempoten: tanpa turn aktif tidak ada yang berubah (tetap `ok`).
+   */
+  function interruptSession(sessionId: string): SimpleResult {
+    const cur = store.getSession(sessionId);
+    if (!cur.ok) return { ok: false, error: "SESSION_NOT_FOUND" };
+    // Abort turn berjalan (best-effort, tidak menunggu).
+    if (cur.data.status === "running" && cur.data.ocSessionId) {
+      const handle = serversFor(cur.data.agentType).getServer(cur.data.projectId);
+      void handle?.client.abortSession(cur.data.ocSessionId);
+    }
+    // Buang turn parsial (tidak disimpan) + broadcast turn tidak aktif.
+    turns.discard(sessionId);
+    return { ok: true };
+  }
+
+  /**
+   * Menghidupkan kembali Session yang `stopped`/`crashed` dengan riwayat
+   * percakapan utuh:
+   *
+   * 1. Server headless Project di-ensure (spawn ulang bila sudah mati) —
+   *    storage session opencode bertahan di disk project, sehingga ocSessionId
+   *    lama biasanya masih dikenal server baru.
+   * 2. ocSessionId diverifikasi via `GET /session/{id}`. Bila masih ada,
+   *    dipakai lagi (riwayat server opencode tetap nyambung). Bila tidak,
+   *    dibuat sesi remote baru dan `oc_session_id` di DB diperbarui — pesan
+   *    lama di Session_Store tidak tersentuh.
+   * 3. Pemetaan SSE diaktifkan kembali lalu status -> `running`.
+   */
+  async function resumeSession(sessionId: string): Promise<SimpleResult> {
+    const cur = store.getSession(sessionId);
+    if (!cur.ok) return { ok: false, error: "SESSION_NOT_FOUND" };
+    if (cur.data.status === "running") return { ok: false, error: "SESSION_ALREADY_RUNNING" };
+    const project = store.getProjectById(cur.data.projectId);
+    if (!project.ok) return { ok: false, error: "PROJECT_NOT_FOUND" };
+
+    // (1) Pastikan server headless Project hidup (spawn ulang bila perlu).
+    const serverRes = await ensureServerFor(project.data.id, project.data.path, {
+      agentType: cur.data.agentType,
+    });
+    if (!serverRes.ok) return { ok: false, error: serverRes.error };
+
+    // (2) Verifikasi ocSessionId lama; bila tidak dikenal -> sesi remote baru.
+    let ocSessionId = cur.data.ocSessionId;
+    if (ocSessionId) {
+      const remote = await serverRes.data.client.getSession(ocSessionId);
+      if (remote.ok) {
+        mapOcSession(ocSessionId, sessionId);
+      } else {
+        ocSessionId = null;
+      }
+    }
+    if (!ocSessionId) {
+      // Sesi remote baru (yang lama hilang). Tanpa judul: bila Session belum
+      // punya judul, opencode akan meng-generate-nya dari prompt berikutnya.
+      const created = await serverRes.data.client.createSession();
+      if (!created.ok) return { ok: false, error: created.error };
+      ocSessionId = created.data.id;
+      mapOcSession(ocSessionId, sessionId);
+      const upd = store.updateSessionOcId(sessionId, ocSessionId);
+      if (!upd.ok) return { ok: false, error: upd.error };
+    }
+
+    // (3) Status kembali running.
+    updateStatus(sessionId, "running", now());
+    return { ok: true };
+  }
+
+  /**
+   * Lepaskan seluruh sumber daya milik satu Project — dipakai rute
+   * `DELETE /api/projects/:id` sebelum baris Project dihapus:
+   *
+   * 1. Setiap Session milik Project dihapus lewat `deleteSession` sehingga
+   *    sesi remote opencode, lampiran gambar, dan baris anaknya ikut bersih.
+   *    Kegagalan menghentikan proses (error diteruskan) supaya tidak ada
+   *    session opencode yatim — user bisa mencoba lagi.
+   * 2. Server headless Project dihentikan; tanpa Session ia tidak lagi
+   *    dipakai dan tidak perlu terus memakan memori.
+   */
+  async function releaseProject(projectId: string): Promise<SimpleResult> {
+    if (!store.getProjectById(projectId).ok) return { ok: false, error: "PROJECT_NOT_FOUND" };
+    for (const session of store.listProjectSessions(projectId)) {
+      const res = await deleteSession(session.id);
+      if (!res.ok) return res;
+    }
+    await servers.stopServer(projectId);
+    await claudeServers?.stopServer(projectId);
+    // Subscription SSE ikut dilepas — server-nya sudah tidak ada.
+    for (const agentType of SUPPORTED_AGENT_TYPES) {
+      const key = backendKey(agentType, projectId);
+      const sub = activeSubscriptions.get(key);
+      if (sub) {
+        sub.unsubscribe();
+        activeSubscriptions.delete(key);
+      }
+      exitNotified.delete(key);
+    }
+    return { ok: true };
+  }
+
+  /**
+   * Daftar model yang tersedia untuk Project — server headless Project
+   * di-ensure lebih dulu (spawn bila perlu) karena provider/model dibaca dari
+   * konfigurasi opencode pada direktori Project. Bila file config opencode
+   * berubah sejak server hidup, proses di-restart agar daftar ikut terbaru
+   * (opencode serve tidak hot-reload config). Restart ditahan bila ada
+   * Session `running` agar turn yang sedang berjalan tidak terputus.
+   */
+  async function listModels(
+    projectId: string,
+    agentType: AgentType = "opencode",
+  ): Promise<Result<ModelOption[]>> {
+    const project = store.getProjectById(projectId);
+    if (!project.ok) return { ok: false, error: "PROJECT_NOT_FOUND" };
+    const hasRunning = store.listProjectSessions(projectId).some((s) => s.status === "running");
+    const serverRes = await ensureServerFor(project.data.id, project.data.path, {
+      refreshConfig: !hasRunning,
+      agentType,
+    });
+    if (!serverRes.ok) return { ok: false, error: serverRes.error };
+    return serverRes.data.client.listModels();
+  }
+
+  /**
+   * Daftar agent (mode) untuk Project — server headless Project di-ensure
+   * lebih dulu karena daftar agent dibaca dari konfigurasi opencode di
+   * direktori Project (agent kustom user ikut masuk). Config yang berubah
+   * memicu restart server agar daftar ikut terbaru (dengan guard yang sama
+   * seperti `listModels`).
+   */
+  async function listAgents(
+    projectId: string,
+    agentType: AgentType = "opencode",
+  ): Promise<Result<AgentOption[]>> {
+    const project = store.getProjectById(projectId);
+    if (!project.ok) return { ok: false, error: "PROJECT_NOT_FOUND" };
+    const hasRunning = store.listProjectSessions(projectId).some((s) => s.status === "running");
+    const serverRes = await ensureServerFor(project.data.id, project.data.path, {
+      refreshConfig: !hasRunning,
+      agentType,
+    });
+    if (!serverRes.ok) return { ok: false, error: serverRes.error };
+    return serverRes.data.client.listAgents();
+  }
+
+  /**
+   * Status MCP server Project — server headless di-ensure lebih dulu karena
+   * daftar MCP dibaca dari config opencode di direktori Project. Config yang
+   * berubah memicu restart (guard sama dengan `listModels`).
+   */
+  async function listMcp(
+    projectId: string,
+    agentType: AgentType = "opencode",
+  ): Promise<Result<McpServerInfo[]>> {
+    const project = store.getProjectById(projectId);
+    if (!project.ok) return { ok: false, error: "PROJECT_NOT_FOUND" };
+    const hasRunning = store.listProjectSessions(projectId).some((s) => s.status === "running");
+    const serverRes = await ensureServerFor(project.data.id, project.data.path, {
+      refreshConfig: !hasRunning,
+      agentType,
+    });
+    if (!serverRes.ok) return { ok: false, error: serverRes.error };
+    return serverRes.data.client.listMcp();
+  }
+
+  /**
+   * Skill yang terdaftar untuk Project. Skill di dalam folder Project
+   * ditandai `project` sehingga UI dapat membedakannya dari skill global.
+   */
+  async function listSkills(
+    projectId: string,
+    agentType: AgentType = "opencode",
+  ): Promise<Result<SkillInfo[]>> {
+    const project = store.getProjectById(projectId);
+    if (!project.ok) return { ok: false, error: "PROJECT_NOT_FOUND" };
+    const serverRes = await ensureServerFor(project.data.id, project.data.path, { agentType });
+    if (!serverRes.ok) return { ok: false, error: serverRes.error };
+    return serverRes.data.client.listSkills(project.data.path);
+  }
+
+  function projectBusy(projectId: string): boolean {
+    return store.listSessions().some((s) => s.projectId === projectId && turns.has(s.id));
+  }
+
+  function cancelScheduledSkillRefresh(projectId: string): void {
+    const t = skillRefreshTimers.get(projectId);
+    if (t !== undefined) {
+      clearTimeoutFn(t);
+      skillRefreshTimers.delete(projectId);
+    }
+  }
+
+  /** Jadwalkan refresh tertunda bila Project sudah tidak punya turn aktif. */
+  function scheduleSkillRefresh(projectId: string): void {
+    if (projectBusy(projectId)) return;
+    cancelScheduledSkillRefresh(projectId);
+    const handle = setTimeoutFn(() => {
+      skillRefreshTimers.delete(projectId);
+      void runPendingSkillRefresh(projectId);
+    }, skillRefreshDelayMs);
+    skillRefreshTimers.set(projectId, handle);
+  }
+
+  async function runPendingSkillRefresh(projectId: string): Promise<void> {
+    if (!pendingSkillRefresh.has(projectId)) return;
+    // Turn baru sempat dimulai -> tunggu turn berikutnya selesai.
+    if (projectBusy(projectId)) return;
+    const handle = servers.getServer(projectId);
+    if (!handle) {
+      // Server sudah berhenti -> skill terbaca saat server di-spawn lagi.
+      pendingSkillRefresh.delete(projectId);
+      onSkillsRefreshed?.(projectId);
+      return;
+    }
+    const res = await handle.client.disposeInstance();
+    if (!res.ok) {
+      // Tetap tertunda; dicoba lagi setelah turn berikutnya selesai.
+      console.warn(`[kcg-code] refresh skill tertunda Project ${projectId} gagal:`, res.error);
+      return;
+    }
+    pendingSkillRefresh.delete(projectId);
+    onSkillsRefreshed?.(projectId);
+  }
+
+  async function refreshSkills(
+    projectId: string,
+    agentType: AgentType = "opencode",
+  ): Promise<Result<{ refreshed: boolean }>> {
+    const project = store.getProjectById(projectId);
+    if (!project.ok) return { ok: false, error: "PROJECT_NOT_FOUND" };
+    // Claude Code: daftar skill dibaca langsung dari disk dan proses `claude`
+    // memuat skill sendiri — tidak ada cache server yang perlu dibuang.
+    if (agentType === "claude-code") return { ok: true, data: { refreshed: true } };
+    const handle = servers.getServer(projectId);
+    // Server belum hidup -> skill terbaca saat server di-spawn nanti.
+    if (!handle) {
+      pendingSkillRefresh.delete(projectId);
+      return { ok: true, data: { refreshed: true } };
+    }
+    if (projectBusy(projectId)) {
+      pendingSkillRefresh.add(projectId);
+      return { ok: true, data: { refreshed: false } };
+    }
+    cancelScheduledSkillRefresh(projectId);
+    const res = await handle.client.disposeInstance();
+    if (!res.ok) {
+      console.warn(`[kcg-code] refresh skill Project ${projectId} gagal:`, res.error);
+      // Coba lagi otomatis setelah turn berikutnya selesai.
+      pendingSkillRefresh.add(projectId);
+      return { ok: true, data: { refreshed: false } };
+    }
+    pendingSkillRefresh.delete(projectId);
+    return { ok: true, data: { refreshed: true } };
+  }
+
+  function hasPendingSkillRefresh(projectId: string): boolean {
+    return pendingSkillRefresh.has(projectId);
+  }
+
+  /**
+   * Cari file di Project untuk autocomplete `@file` — index pencarian
+   * milik server headless opencode (sesuai perilaku `@` di opencode TUI).
+   * `query` kosong juga valid (mengembalikan daftar awal).
+   */
+  /**
+   * Konteks kerja Session (panel kanan). Ketiga sumbernya independen dan
+   * SELALU dibaca bersamaan; kegagalan salah satu tidak menggagalkan yang
+   * lain (mis. repo bukan git -> `git` kosong, task list tetap tampil).
+   * Session yang tidak berjalan -> hanya info git (server opencode tidak
+   * dinyalakan hanya untuk mengisi panel).
+   */
+  async function sessionContext(sessionId: string): Promise<Result<SessionContext>> {
+    const cur = store.getSession(sessionId);
+    if (!cur.ok) return { ok: false, error: "SESSION_NOT_FOUND" };
+    const cwd = cur.data.cwd;
+    const handle = serversFor(cur.data.agentType).getServer(cur.data.projectId);
+    // Task list disimpan per session REMOTE (opencode `ses_...` / UUID Claude).
+    const remoteId = cur.data.ocSessionId ?? sessionId;
+
+    const [git, todos, changes, mcp] = await Promise.all([
+      readGitInfo(cwd).catch(() => EMPTY_GIT_INFO),
+      handle ? handle.client.listTodos(remoteId) : Promise.resolve(null),
+      handle ? handle.client.fileStatus() : Promise.resolve(null),
+      handle ? handle.client.listMcp() : Promise.resolve(null),
+    ]);
+
+    return {
+      ok: true,
+      data: {
+        git,
+        todos: todos?.ok ? todos.data : [],
+        changes: changes?.ok ? changes.data : [],
+        mcp: mcp?.ok ? mcp.data : [],
+        /** Panel perlu tahu data tool belum tersedia vs memang kosong. */
+        live: handle !== undefined && handle !== null,
+      },
+    };
+  }
+
+  async function findFiles(
+    projectId: string,
+    query: string,
+    agentType: AgentType = "opencode",
+  ): Promise<Result<string[]>> {
+    const project = store.getProjectById(projectId);
+    if (!project.ok) return { ok: false, error: "PROJECT_NOT_FOUND" };
+    const serverRes = await ensureServerFor(project.data.id, project.data.path, { agentType });
+    if (!serverRes.ok) return { ok: false, error: serverRes.error };
+    return serverRes.data.client.findFiles(query);
+  }
+
+  /**
+   * Ganti model pilihan Session. Berlaku untuk prompt berikutnya (prompt_async
+   * selalu mengirim model tersimpan di Session), jadi tidak perlu restart.
+   */
+  function setSessionModel(sessionId: string, model: SessionModel | null): SimpleResult {
+    const cur = store.getSession(sessionId);
+    if (!cur.ok) return { ok: false, error: "SESSION_NOT_FOUND" };
+    const upd = store.updateSessionModel(sessionId, model);
+    return upd.ok ? { ok: true } : { ok: false, error: upd.error };
+  }
+
+  /**
+   * Ganti agent (mode) pilihan Session. Berlaku untuk prompt berikutnya
+   * (prompt_async selalu mengirim agent tersimpan di Session).
+   */
+  function setSessionAgent(sessionId: string, agent: string | null): SimpleResult {
+    const cur = store.getSession(sessionId);
+    if (!cur.ok) return { ok: false, error: "SESSION_NOT_FOUND" };
+    if (agent !== null && agent.trim() === "") return { ok: false, error: "INVALID_AGENT" };
+    const upd = store.updateSessionAgent(sessionId, agent);
+    return upd.ok ? { ok: true } : { ok: false, error: upd.error };
+  }
+
+  /**
+   * Hapus Session permanen:
+   *
+   * 1. Turn yang sedang stream difinalisasi & pemetaan SSE dilepas.
+   * 2. Pastikan server headless Project hidup — spawn ulang bila mati — lalu
+   *    `DELETE /session/{id}`: data session (termasuk seluruh pesan) ikut
+   *    dihapus di sisi opencode. Penghapusan remote bersifat wajib: bila
+   *    server tidak bisa di-spawn ulang atau menolak hapus, error diteruskan
+   *    dan data lokal TIDAK dihapus — supaya tidak ada session opencode yang
+   *    jadi yatim tanpa sepengetahuan user (bisa dicoba lagi kemudian).
+   * 3. Baris Session + seluruh baris anaknya dihapus dari Session_Store.
+   */
+  async function deleteSession(sessionId: string): Promise<SimpleResult> {
+    const cur = store.getSession(sessionId);
+    if (!cur.ok) return { ok: false, error: "SESSION_NOT_FOUND" };
+
+    turns.finish(sessionId);
+    // Bila masih running, abort turn remote agar model berhenti dieksekusi.
+    if (cur.data.status === "running" && cur.data.ocSessionId) {
+      const runningHandle = serversFor(cur.data.agentType).getServer(cur.data.projectId);
+      void runningHandle?.client.abortSession(cur.data.ocSessionId);
+    }
+    unmapOcSessions(sessionId);
+
+    // (2) Hapus di server headless — wajib: server di-spawn ulang bila mati
+    //     agar data remote tidak tertinggal. Server hasil spawn dibiarkan
+    //     hidup (bukan di-stop) karena mungkin sedang dipakai operasi lain
+    //     dan hanya akan dihentikan saat shutdown.
+    const ocSessionId = cur.data.ocSessionId;
+    if (ocSessionId) {
+      let client = serversFor(cur.data.agentType).getServer(cur.data.projectId)?.client;
+      if (!client) {
+        const project = store.getProjectById(cur.data.projectId);
+        if (!project.ok) return { ok: false, error: project.error };
+        const serverRes = await ensureServerFor(project.data.id, project.data.path, {
+          agentType: cur.data.agentType,
+        });
+        if (!serverRes.ok) return { ok: false, error: serverRes.error };
+        client = serverRes.data.client;
+      }
+      const remote = await client.deleteSession(ocSessionId);
+      if (!remote.ok) return { ok: false, error: remote.error };
+    }
+
+    // (3) Hapus lokal (transaksional: messages, prompts, history, session).
+    const res = store.deleteSession(sessionId);
+    if (res.ok) {
+      // Lampiran gambar milik Session ikut dibersihkan (best effort).
+      attachments?.removeSession(sessionId);
+      onDeleted?.(sessionId);
+    }
+    return res;
+  }
+
+  async function sendFreeTextInput(
+    sessionId: string,
+    text: string,
+    files: string[] = [],
+    images: string[] = [],
+  ): Promise<SimpleResult> {
+    // Pesan berupa teks bebas dan/atau gambar: teks kosong diizinkan bila ada
+    // gambar terlampir (mis. kirim gambar saja), selainnya wajib non-kosong.
+    const hasText = text.trim().length > 0;
+    const hasImages = images.length > 0;
+    if (!hasText && !hasImages) {
+      return { ok: false, error: "TEXT_EMPTY" };
+    }
+    if (hasText && text.length > MAX_FREE_TEXT_LENGTH) {
+      return { ok: false, error: "TEXT_TOO_LONG" };
+    }
+    const cur = store.getSession(sessionId);
+    if (!cur.ok) return { ok: false, error: "SESSION_NOT_FOUND" };
+    if (cur.data.status !== "running") return { ok: false, error: "SESSION_NOT_ACTIVE" };
+    const ocSessionId = cur.data.ocSessionId;
+    if (!ocSessionId) return { ok: false, error: "SESSION_NOT_ACTIVE" };
+
+    // Pastikan server masih hidup SEBELUM menyimpan echo user.
+    const handle = serversFor(cur.data.agentType).getServer(cur.data.projectId);
+    if (!handle) return { ok: false, error: "SESSION_NOT_ACTIVE" };
+
+    // Gambar upload dipetakan ke info + path absolut. Kegagalan resolve
+    // (id tidak dikenal / sudah dihapus) menolak pengiriman tanpa echo.
+    const imageInfos: { id: string; filename: string; mime: string; absPath: string }[] = [];
+    for (const id of images) {
+      const info = attachments?.info(sessionId, id);
+      if (!info?.ok) return { ok: false, error: "ATTACHMENT_NOT_FOUND" };
+      imageInfos.push(info.data);
+    }
+
+    // Echo pesan user (disimpan + dikirim ke Client) sebelum menunggu balasan.
+    // Referensi @file ikut di-echo sebagai part `file` mime text/plain;
+    // gambar upload sebagai part `file` mime image/* dengan `attachmentId`
+    // agar renderer dapat memuat bytes lewat HTTP. Path relatif project
+    // diubah ke file URL absolut — opencode mem-parse `url` dengan URL()
+    // sehingga `file://rel/path` (host=rel) ditolak di Linux; host kosong
+    // (`file:///abs/path`) valid.
+    const promptFiles: OpenCodeFileRef[] = [];
+    const userParts: MessagePart[] = [{ type: "text", text }];
+    for (const filename of files) {
+      const url = `file://${path.resolve(cur.data.cwd, filename)}`;
+      userParts.push({ type: "file", mime: "text/plain", filename, url });
+      promptFiles.push({ filename, mime: "text/plain", url });
+    }
+    /** Lampiran biner (zip, audio, …): tidak dikirim sebagai part. */
+    const pathOnly: { filename: string; absPath: string }[] = [];
+    for (const info of imageInfos) {
+      // Jaring pengaman: `file://` harus menunjuk path absolut (host kosong).
+      // `file://rel/path` membuat host="rel" yang ditolak opencode.
+      const url = `file://${path.resolve(info.absPath)}`;
+      // Echo selalu memakai mime asli (renderer memilih thumbnail / kartu).
+      userParts.push({
+        type: "file",
+        mime: info.mime,
+        filename: info.filename,
+        url,
+        attachmentId: info.id,
+      });
+      // Ke model: hanya mime yang diterima provider (gambar/PDF/teks). Mime
+      // lain merusak turn (dan riwayat) dengan "functionality not supported".
+      const modelMime = modelFacingMime(info.mime, info.filename);
+      if (modelMime) promptFiles.push({ filename: info.filename, mime: modelMime, url });
+      else pathOnly.push({ filename: info.filename, absPath: path.resolve(info.absPath) });
+    }
+    const userMessage: SessionMessage = {
+      id: `usr_${randomUUID()}`,
+      sessionId,
+      role: "user",
+      parts: userParts,
+      createdAt: now(),
+    };
+    if (!store.insertMessage(userMessage).ok) return { ok: false, error: "MESSAGE_WRITE_FAILED" };
+    onMessage?.(userMessage);
+
+    // Judul SEMENTARA sampai opencode mengirim judul hasil generate
+    // (`session.updated`, biasanya beberapa detik). Bila masih placeholder /
+    // null, turunkan dari teks prompt pertama. Gambar saja -> "Image".
+    if (isPlaceholderTitle(cur.data.title)) {
+      const candidate = deriveSessionTitle(text) ?? (hasImages ? "Image" : null);
+      if (candidate && store.updateSessionTitle(sessionId, candidate).ok) {
+        onTitleChange?.(sessionId, candidate);
+      }
+    }
+
+    // Turn sebelumnya yang belum idle ditutup dulu agar parts-nya tidak
+    // tercampur ke turn baru dan tidak hilang.
+    turns.finish(sessionId);
+
+    // Mulai turn streaming: parts dari SSE `message.part.updated` di-forward.
+    // Jaring pengaman bila `session.idle` tidak pernah datang (mis. server
+    // mati di tengah turn): batas IDLE, di-reset tiap tanda hidup — parts
+    // yang sudah terkumpul tetap disimpan saat dipicu.
+    turns.begin(sessionId, turnIdleTimeoutMs, friendlySendError("TURN_TIMEOUT"));
+
+    // Custom instruction Project dibaca saat kirim (bukan saat Session dibuat)
+    // agar perubahan instruksi langsung berlaku di prompt berikutnya.
+    const projectRes = store.getProjectById(cur.data.projectId);
+    const system = projectRes.ok ? (projectRes.data.instructions ?? null) : null;
+
+    // File biner dirujuk lewat path agar model bisa memakai tool (bash/read)
+    // bila perlu; teks yang tampil di bubble tetap teks asli pengguna.
+    const promptText =
+      pathOnly.length === 0
+        ? text
+        : [
+            text,
+            "Attached files (saved on disk, not shown inline):",
+            ...pathOnly.map((f) => `- ${f.filename}: ${f.absPath}`),
+          ]
+            .filter((line) => line !== "")
+            .join("\n");
+
+    enqueue(sessionId, async () => {
+      try {
+        // `prompt_async` balas 204 begitu prompt diterima; hasil turn tiba
+        // lewat SSE dan ditutup oleh `session.idle`.
+        const res = await handle.client.promptAsync(
+          ocSessionId,
+          promptText,
+          cur.data.model,
+          promptFiles,
+          cur.data.agent,
+          system,
+        );
+        if (!res.ok) {
+          turns.fail(sessionId, friendlySendError(res.error ?? "OC_PROMPT_ASYNC_FAILED"));
+        }
+      } catch (e) {
+        turns.fail(sessionId, friendlySendError(`SEND_FAILED: ${(e as Error).message}`));
+      }
+    });
+
+    return { ok: true };
+  }
+
+  async function resolvePrompt(
+    sessionId: string,
+    promptId: string,
+    response: PromptResponse,
+  ): Promise<SimpleResult> {
+    const p = store.getPrompt(promptId);
+    if (!p.ok) return { ok: false, error: "PROMPT_NOT_FOUND" };
+    if (p.data.sessionId !== sessionId) return { ok: false, error: "PROMPT_NOT_FOUND" };
+    if (p.data.status !== "pending") return { ok: false, error: "PROMPT_ALREADY_RESOLVED" };
+
+    const cur = store.getSession(sessionId);
+    if (!cur.ok) return { ok: false, error: "SESSION_NOT_FOUND" };
+    const handle = serversFor(cur.data.agentType).getServer(cur.data.projectId);
+    if (!handle) return { ok: false, error: "SESSION_NOT_ACTIVE" };
+
+    // Kumpulkan request pending yang identik (grup kartu yang sama di UI):
+    // jawaban satu kartu diteruskan ke seluruh anggota grup. Tanpa ini,
+    // kartu kembar yang tertinggal di server membuat turn berikutnya
+    // menggantung menunggu keputusan yang sudah diambil user.
+    const targets = store
+      .listPendingPrompts(sessionId)
+      .filter((q) => q.id !== promptId && permissionGroupKey(q) === permissionGroupKey(p.data));
+
+    /**
+     * Reply satu request permission. `always` = "Always allow" — opencode
+     * mengingat pola yang disetujui sehingga request identik berikutnya tidak
+     * lagi menampilkan kartu.
+     */
+    const replyPermission = (id: string, r: PromptResponse): Promise<SimpleResult> => {
+      if (r === "approve") return handle.client.replyPermission(id, "once");
+      if (r === "always") return handle.client.replyPermission(id, "always");
+      if (r === "deny" || r === "cancel") {
+        // Cancel == tolak (tanpa meneruskan input), setara deny di mode TUI.
+        return handle.client.replyPermission(id, "reject");
+      }
+      return Promise.resolve({ ok: false, error: "INVALID_PROMPT_RESPONSE" });
+    };
+
+    let res: SimpleResult;
+    if (p.data.kind === "permission") {
+      res = await replyPermission(promptId, response);
+    } else {
+      // kind === "question" — opsi harus bagian dari daftar (Requirement 6.6).
+      // Opsi tidak dikenal TIDAK ditolak keras bila daftar tersimpan tidak
+      // cocok dengan opsi live (baris DB lama / skema server berubah):
+      // diteruskan apa adanya ke opencode yang tahu daftar sebenarnya —
+      // menolak di sini membuat tombol opsi terasa mati tanpa feedback.
+      if (typeof response === "object" && response !== null) {
+        if ("answers" in response) {
+          // Multi-question: SATU array label per pertanyaan — diteruskan
+          // apa adanya ke reply API (skema Question.Reply).
+          res = await handle.client.replyQuestion(promptId, response.answers);
+        } else if ("options" in response) {
+          // Multi-select: kirim seluruh label terpilih (urut tampilan).
+          res = await handle.client.replyQuestion(promptId, [response.options]);
+        } else {
+          res = await handle.client.replyQuestion(promptId, [[response.option]]);
+        }
+      } else if (response === "cancel") {
+        res = await handle.client.rejectQuestion(promptId);
+      } else {
+        return { ok: false, error: "INVALID_PROMPT_RESPONSE" };
+      }
+    }
+    if (!res.ok) {
+      if (res.error === OC_REQUEST_GONE) {
+        // opencode tidak lagi menunggu request ini (404): sudah dijawab dari
+        // klien lain, dibatalkan karena turn di-abort, atau server opencode
+        // di-restart. Tanpa penutupan di sini, baris DB tetap `pending`:
+        // kartu tidak bisa dijawab MAUPUN di-Skip (keduanya kena 404) dan
+        // composer tetap tersembunyi — session terkunci. Tutup prompt (dan
+        // kembarannya) secara lokal supaya UI pulih.
+        updatePromptResolved(promptId);
+        for (const twin of targets) {
+          updatePromptResolved(twin.id);
+          onPromptResolved?.(sessionId, twin.id);
+        }
+        return { ok: false, error: "PROMPT_EXPIRED" };
+      }
+      return { ok: false, error: res.error };
+    }
+    updatePromptResolved(promptId);
+    // Jawaban question cukup lewat reply API — tidak di-echo ke riwayat chat
+    // agar transcript bersih (agent tetap menerima jawabannya).
+    // Fan-out best-effort ke kartu kembar; kegagalan satu request tidak
+    // menggagalkan jawaban utama yang sudah diterima server.
+    for (const twin of targets) {
+      const twinRes =
+        p.data.kind === "permission"
+          ? await replyPermission(twin.id, response)
+          : typeof response === "object" && response !== null
+            ? "answers" in response
+              ? await handle.client.replyQuestion(twin.id, response.answers)
+              : "options" in response
+                ? await handle.client.replyQuestion(twin.id, [response.options])
+                : await handle.client.replyQuestion(twin.id, [[response.option]])
+            : await handle.client.rejectQuestion(twin.id);
+      if (twinRes.ok) {
+        updatePromptResolved(twin.id);
+        onPromptResolved?.(sessionId, twin.id);
+      }
+    }
+    return { ok: true };
+  }
+
+  /** Requirement 2.4: seluruh Session `running` tanpa server -> `crashed`. */
+  function reconcileOnStartup(): void {
+    for (const s of store.listSessions()) {
+      if (s.status === "running") {
+        updateStatus(s.id, "crashed", now());
+      }
+    }
+  }
+
+  /**
+   * Requirement 2.3: simpan status terakhir Session `running` dalam budget
+   * waktu, lalu hentikan seluruh server headless.
+   */
+  async function shutdown(): Promise<void> {
+    // Refresh skill tertunda tidak relevan lagi: server dihentikan, skill
+    // terbaca saat server di-spawn berikutnya.
+    for (const projectId of [...skillRefreshTimers.keys()]) cancelScheduledSkillRefresh(projectId);
+    pendingSkillRefresh.clear();
+    const running = store.listSessions().filter((s) => s.status === "running");
+    const results = running.map((s) => store.insertStatusHistory(s.id, "running", now()));
+    await raceWithTimeout(Promise.resolve(results), shutdownBudgetMs);
+    await Promise.all([servers.stopAll(), claudeServers?.stopAll()]);
+  }
+
+  /** Balapan dengan timer budget; timer selalu dibersihkan setelah selesai. */
+  async function raceWithTimeout<T>(p: Promise<T>, ms: number): Promise<T> {
+    let timer: unknown;
+    const timeout: Promise<T> = new Promise((_resolve, reject) => {
+      timer = setTimeoutFn(() => reject(new Error("shutdown budget exceeded")), ms);
+    });
+    try {
+      return await Promise.race([p, timeout]);
+    } finally {
+      if (timer !== undefined) clearTimeoutFn(timer);
+    }
+  }
+
+  // Saat server keluar tak terduga, tandai Session project tsb `crashed`.
+  const onBackendExit = (agentType: AgentType) => (projectId: string) => {
+    const key = backendKey(agentType, projectId);
+    if (exitNotified.has(key)) return;
+    exitNotified.add(key);
+    const crashedAt = now();
+    for (const s of store.listSessions()) {
+      if (s.projectId === projectId && s.agentType === agentType && s.status === "running") {
+        // Server mati di tengah turn: selamatkan parts yang sudah ter-stream.
+        turns.finish(s.id);
+        updateStatus(s.id, "crashed", crashedAt);
+        unmapOcSessions(s.id);
+      }
+    }
+  };
+  servers.onServerExit(onBackendExit("opencode"));
+  claudeServers?.onServerExit(onBackendExit("claude-code"));
+
+  return {
+    createSession,
+    listSessions,
+    getSession,
+    stopSession,
+    interruptSession,
+    resumeSession,
+    deleteSession,
+    releaseProject,
+    listModels,
+    listAgents,
+    listMcp,
+    listSkills,
+    refreshSkills,
+    hasPendingSkillRefresh,
+    setSessionModel,
+    setSessionAgent,
+    findFiles,
+    sessionContext,
+    sendFreeTextInput,
+    resolvePrompt,
+    reconcileOnStartup,
+    shutdown,
+  };
+}