kcg-code 0.0.0-stage → 0.1.0

package/src/server/services/ws-transport.ts

@@ -0,0 +1,121 @@
+/**
+ * Transport WebSocket — adaptor koneksi + dispatch pesan Client -> Gateway.
+ *
+ * Dipisah dari `websocket-gateway.ts` (yang mengurus registrasi & broadcast)
+ * agar tiap berkas satu tanggung jawab:
+ * - `bunWsSubscriber` menyamarkan `ServerWebSocket` Bun menjadi `Subscriber`.
+ * - `dispatchClientMessage` mem-parsing teks JSON dari Client lalu meneruskan
+ *   ke gateway sesuai `type` (attach/input/prompt_response/stop/interrupt).
+ */
+import type { ServerWebSocket } from "bun";
+import type { PromptResponse } from "../../types";
+import type { Subscriber, WebSocketGateway } from "./websocket-gateway";
+
+/** Adaptor ServerWebSocket Bun ke `Subscriber` (untuk wiring di `app.ts`). */
+export function bunWsSubscriber<T>(ws: ServerWebSocket<T>): Subscriber {
+  return {
+    send(msg) {
+      ws.send(JSON.stringify(msg));
+    },
+    close() {
+      ws.close(1000);
+    },
+  };
+}
+
+function isPromptResponse(r: unknown): r is PromptResponse {
+  if (r === "approve" || r === "always" || r === "deny" || r === "cancel") return true;
+  if (typeof r !== "object" || r === null) return false;
+  // Single choice `{ option }`.
+  if (typeof (r as { option?: unknown }).option === "string") return true;
+  // Multi-select `{ options: string[] }`.
+  const options = (r as { options?: unknown }).options;
+  if (Array.isArray(options) && options.every((s) => typeof s === "string")) return true;
+  // Multi-question `{ answers: string[][] }` — satu array label per pertanyaan.
+  const answers = (r as { answers?: unknown }).answers;
+  if (
+    Array.isArray(answers) &&
+    answers.every((a) => Array.isArray(a) && (a as unknown[]).every((s) => typeof s === "string"))
+  ) {
+    return true;
+  }
+  return false;
+}
+
+function invalidMessage(sub: Subscriber, detail: string): void {
+  sub.send({ type: "error", code: "INVALID_MESSAGE", message: detail });
+}
+
+/**
+ * Mem-parsing pesan Client dan meneruskan ke gateway sesuai `type`.
+ * Pesan JSON rusak / payload salah bentuk -> `error` INVALID_MESSAGE.
+ */
+export function dispatchClientMessage(
+  gateway: WebSocketGateway,
+  sub: Subscriber,
+  raw: string,
+): void {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    invalidMessage(sub, "Pesan JSON tidak valid");
+    return;
+  }
+  if (typeof parsed !== "object" || parsed === null) {
+    invalidMessage(sub, "Pesan harus berupa objek JSON");
+    return;
+  }
+  const msg = parsed as Record<string, unknown>;
+  switch (msg.type) {
+    case "attach":
+      if (typeof msg.sessionId === "string") gateway.attach(sub, msg.sessionId);
+      else invalidMessage(sub, "attach membutuhkan sessionId string");
+      break;
+    case "input":
+      if (
+        typeof msg.sessionId === "string" &&
+        typeof msg.text === "string" &&
+        (msg.files === undefined ||
+          (Array.isArray(msg.files) && msg.files.every((f) => typeof f === "string"))) &&
+        (msg.images === undefined ||
+          (Array.isArray(msg.images) && msg.images.every((f) => typeof f === "string")))
+      ) {
+        gateway.input(sub, msg.sessionId, msg.text, msg.files, msg.images);
+      } else {
+        invalidMessage(sub, "input membutuhkan sessionId dan text string");
+      }
+      break;
+    case "prompt_response":
+      if (
+        typeof msg.sessionId === "string" &&
+        typeof msg.promptId === "string" &&
+        isPromptResponse(msg.response)
+      ) {
+        gateway.promptResponse(sub, msg.sessionId, msg.promptId, msg.response);
+      } else {
+        invalidMessage(sub, "prompt_response membutuhkan sessionId, promptId, dan response valid");
+      }
+      break;
+    case "stop":
+      if (typeof msg.sessionId === "string") {
+        gateway.stop(sub, msg.sessionId);
+      } else {
+        invalidMessage(sub, "stop membutuhkan sessionId string");
+      }
+      break;
+    case "interrupt":
+      if (typeof msg.sessionId === "string") {
+        gateway.interrupt(sub, msg.sessionId);
+      } else {
+        invalidMessage(sub, "interrupt membutuhkan sessionId string");
+      }
+      break;
+    default:
+      sub.send({
+        type: "error",
+        code: "UNKNOWN_MESSAGE_TYPE",
+        message: "Tipe pesan tidak dikenal",
+      });
+  }
+}

package/src/types/context.ts

@@ -0,0 +1,69 @@
+/**
+ * Konteks kerja Session untuk panel kanan ("Environment / Task list /
+ * Reference"). Dipakai server (`sessionContext`) maupun UI, jadi bentuknya
+ * hanya didefinisikan di sini.
+ *
+ * Sumber datanya tiga hal yang berbeda:
+ * - `changes` + `git` : keadaan worktree project (opencode `GET /file/status`
+ *   dan perintah `git` baca di cwd Session).
+ * - `todos`           : task list agent (`todowrite`, `GET /session/{id}/todo`).
+ * - `mcp`             : MCP server Project & status koneksinya (`GET /mcp`).
+ * - Reference (file yang dibuka tool) TIDAK ada di sini: itu diturunkan di
+ *   klien dari parts pesan yang sudah dimiliki timeline (`lib/references.ts`),
+ *   sehingga tidak perlu request tambahan.
+ */
+
+/** Satu file yang berubah di worktree. */
+export interface FileChange {
+  path: string;
+  added: number;
+  removed: number;
+  status: "added" | "deleted" | "modified";
+}
+
+/** Satu item task list agent. */
+export interface TodoItem {
+  content: string;
+  /** `pending` | `in_progress` | `completed` | `cancelled` (string bebas). */
+  status: string;
+  /** `high` | `medium` | `low` (string bebas). */
+  priority: string;
+}
+
+/** Keadaan Git worktree Session. */
+export interface GitState {
+  /** Cabang aktif; null = detached HEAD / bukan repo git / belum ada commit. */
+  branch: string | null;
+  /** Commit lokal yang belum dipush; null = cabang tanpa upstream. */
+  ahead: number | null;
+  /** Commit upstream yang belum ditarik; null = cabang tanpa upstream. */
+  behind: number | null;
+  hasRemote: boolean;
+}
+
+/** Satu MCP server Project (subset status opencode `GET /mcp`). */
+export interface McpServerState {
+  name: string;
+  status:
+    | "connected"
+    | "disabled"
+    | "failed"
+    | "needs_auth"
+    | "needs_client_registration"
+    | "unknown";
+  /** Pesan error bila `status === "failed"`. */
+  error: string | null;
+}
+
+export interface SessionContext {
+  git: GitState;
+  changes: FileChange[];
+  todos: TodoItem[];
+  /** MCP server Project beserta status koneksinya. */
+  mcp: McpServerState[];
+  /**
+   * Server opencode Session sedang hidup. `false` -> `todos`/`changes` kosong
+   * karena belum bisa dibaca, BUKAN karena memang tidak ada.
+   */
+  live: boolean;
+}

package/src/types/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Tipe domain bersama KCG Code — satu file per domain (pola `src/types/`
+ * kcgcode) dengan barrel agar `@/types` tetap menjadi satu pintu import.
+ *
+ * Khusus server (bukan domain FE): `Result<T>` / `SimpleResult` hidup di
+ * `src/server/result.ts` — jangan diimpor dari sini.
+ */
+export * from "./context";
+export * from "./message";
+export * from "./project";
+export * from "./prompt";
+export * from "./session";
+export * from "./turns";

package/src/types/message.ts

@@ -0,0 +1,58 @@
+/**
+ * Tipe pesan percakapan terstruktur (headless mode).
+ *
+ * Output_Stream chunk PTY/TUI digantikan `SessionMessage` (role + parts)
+ * yang berasal dari API headless opencode.
+ */
+/**
+ * Satu part pesan opencode (subset skema `Part` OpenAPI): `text`, `reasoning`,
+ * `tool`, `step-start`, `step-finish`, `file`, `agent`, `subtask`, dll.
+ * Dibiarkan toleran (indeks dinamis) agar renderer frontend tahan terhadap
+ * bentuk part baru dari opencode. Field `state` (tool call) dipakai renderer
+ * untuk label target tool (mis. `state.input.filePath`).
+ *
+ * Field `file` (mime/filename/url/attachmentId) dipakai untuk part `file`:
+ * echo `@file` teks maupun gambar yang di-upload. `attachmentId` adalah id
+ * lampiran di Attachment_Store KCG (gambar), dipakai renderer untuk memuat
+ * bytes lewat route HTTP `/api/uploads/...`.
+ */
+export interface MessagePart {
+  type: string;
+  id?: string;
+  text?: string;
+  tool?: string;
+  /** MIME part `file` (mis. `text/plain` untuk @file, `image/png` untuk gambar). */
+  mime?: string;
+  /** Nama file part `file` (nama asli / path relatif project). */
+  filename?: string;
+  /** URL file part (`file:///abs/path` dibaca opencode, bukan browser). */
+  url?: string;
+  /** Id lampiran gambar di Attachment_Store (gambar upload dari perangkat). */
+  attachmentId?: string;
+  /**
+   * State tool call dari opencode: `status` (pending/running/error/done),
+   * `input` (argumen tool, mis. `filePath` untuk read/edit), dan `output`
+   * (hasil). Dipakai renderer untuk menampilkan target tiap tool call.
+   */
+  state?: { input?: Record<string, unknown>; output?: unknown };
+  /**
+   * Timing asli dari opencode (ReasoningPart, TextPart, ToolState).
+   * `start`/`end` adalah Unix ms. Hadir di part yang sudah selesai di-stream;
+   * saat masih di-stream `end` bisa undefined.
+   */
+  time?: { start?: number; end?: number; created?: number };
+  [k: string]: unknown;
+}
+
+/** Satu pesan percakapan terstruktur (user atau assistant). */
+export interface SessionMessage {
+  /** Id pesan (dari opencode `msg_...` atau id lokal untuk echo user). */
+  id: string;
+  /** Id Session lokal KCG Code. */
+  sessionId: string;
+  role: "user" | "assistant";
+  parts: MessagePart[];
+  createdAt: number;
+  /** Pesan sementara yang masih di-stream dari server headless (SSE). */
+  streaming?: boolean;
+}

package/src/types/project.ts

@@ -0,0 +1,16 @@
+/**
+ * Tipe domain Project — direpresentasikan sebagai direktori kerja di dalam
+ * Sandbox_Root (Requirement 10).
+ */
+export interface Project {
+  id: string;
+  name: string;
+  path: string;
+  createdAt: number;
+  /**
+   * Custom instruction Project — dikirim sebagai `system` di setiap prompt
+   * ke opencode (ditambahkan di atas AGENTS.md / instruksi bawaan).
+   * `null`/kosong = tanpa instruksi tambahan.
+   */
+  instructions?: string | null;
+}

package/src/types/prompt.ts

@@ -0,0 +1,118 @@
+/**
+ * Satu pertanyaan dalam request tool `question` opencode. Satu request bisa
+ * membaca BEBERAPA pertanyaan (multi-question); pertanyaan pertama tetap
+ * disalin ke field legacy `title`/`options`/`multiple`/`custom` di
+ * `InteractivePrompt` agar kode lama tetap bekerja.
+ */
+export interface PromptQuestion {
+  /** Teks pertanyaan yang tampil ke user. */
+  question: string | null;
+  /** Label pendek (header) dari skema opencode — opsional. */
+  header?: string | null;
+  options: PromptOption[] | null;
+  /** Boleh pilih lebih dari satu opsi (default false). */
+  multiple?: boolean;
+  /** Boleh jawab bebas selain opsi terdaftar (default true). */
+  custom?: boolean;
+}
+
+/**
+ * Tipe Interactive_Prompt (permission/question).
+ *
+ * `InteractivePrompt` bersumber dari event terstruktur opencode
+ * (`permission.asked` / `question.asked`) lewat field `kind` — bukan hasil
+ * regex atas teks TUI (`prompt-detector.ts` dihapus).
+ */
+export type PromptType = "confirmation" | "menu";
+
+/**
+ * Satu opsi question opencode: label yang dikirim balik sebagai jawaban
+ * plus keterangan tampilan (skema tool `question`: `{label, description?}`).
+ * String polos (data lama / varian event tanpa `description`) dinormalisasi
+ * jadi `{ label }` — lihat `normalizePromptOptions` di bawah.
+ */
+export interface PromptOption {
+  label: string;
+  description: string | null;
+}
+
+/**
+ * Normalisasi opsi question ke `PromptOption[]`:
+ * - `{ label, description? }` (skema question opencode) -> dipakai apa adanya.
+ * - string polos (DB lama) -> `{ label, description: null }`.
+ * Entri tanpa label valid di-skip.
+ */
+export function normalizePromptOptions(raw: unknown): PromptOption[] {
+  if (!Array.isArray(raw)) return [];
+  const out: PromptOption[] = [];
+  for (const o of raw) {
+    if (typeof o === "string") {
+      if (o.trim() !== "") out.push({ label: o, description: null });
+    } else if (typeof o === "object" && o !== null) {
+      const label = (o as { label?: unknown }).label;
+      if (typeof label === "string" && label.trim() !== "") {
+        const description = (o as { description?: unknown }).description;
+        out.push({
+          label,
+          description:
+            typeof description === "string" && description.trim() !== "" ? description : null,
+        });
+      }
+    }
+  }
+  return out;
+}
+
+export type PromptStatus = "pending" | "resolved";
+
+/** Sumber Interactive_Prompt: izin tool (permission) atau pertanyaan (question). */
+export type PromptKind = "permission" | "question";
+
+export interface InteractivePrompt {
+  /** Id request opencode (`per_...` / `que_...`) — dipakai untuk reply. */
+  id: string;
+  sessionId: string;
+  kind: PromptKind;
+  type: PromptType;
+  /** Teks pertanyaan (question) atau deskripsi izin (permission). */
+  title: string | null;
+  /** Opsi question (menu). null = bukan menu / tanpa opsi. */
+  options: PromptOption[] | null;
+  /**
+   * Question saja: boleh pilih LEBIH dari satu opsi (skema tool `question`
+   * opencode, default false — single choice). Jawaban tetap dikirim sebagai
+   * array label via reply API.
+   */
+  multiple?: boolean;
+  /**
+   * Question saja: SELURUH pertanyaan dalam request (multi-question).
+   * undefined/[] = data lama — pertanyaan tunggal ada di field legacy di
+   * atas (title/options/multiple/custom).
+   */
+  questions?: PromptQuestion[];
+  /**
+   * Question saja: user boleh mengetik jawaban bebas selain opsi yang
+   * terdaftar (flag `custom` di skema question opencode, default true).
+   */
+  custom?: boolean;
+  status: PromptStatus;
+  createdAt: number;
+  resolvedAt: number | null;
+}
+
+/**
+ * Respon user atas Interactive_Prompt.
+ * - question single choice: `{ option }`.
+ * - question multi-select: `{ options: string[] }` (label terpilih, urut
+ *   sesuai tampilan; minimal satu).
+ * - question multi-question: `{ answers: string[][] }` — SATU array label per
+ *   pertanyaan, urut sesuai `questions` (jawaban bebas masuk sebagai label).
+ */
+export type PromptResponse =
+  | "approve"
+  | "always"
+  | "deny"
+  | "cancel"
+  | { option: string }
+  | { options: string[] }
+  | { answers: string[][] };

package/src/types/session.ts

@@ -0,0 +1,52 @@
+/**
+ * Tipe domain Session (headless mode).
+ *
+ * `Session.ocSessionId` menyimpan id Session di server headless opencode
+ * (`ses_...`) sebagai pemetaan ke id Session lokal — perubahan dari versi
+ * PTY/TUI.
+ */
+export type AgentType = "opencode" | "claude-code";
+
+export type SessionStatus = "running" | "stopped" | "crashed";
+
+/**
+ * Model LLM pilihan untuk Session (dipakai saat mengirim prompt).
+ * `null` = biarkan opencode memakai model default-nya.
+ */
+export interface SessionModel {
+  providerID: string;
+  modelID: string;
+}
+
+/**
+ * Agent (mode) opencode pilihan untuk Session — dibaca dari `GET /agent`
+ * server headless, dipakai saat mengirim prompt (body `agent`).
+ * `null` = biarkan opencode memakai agent default-nya (biasanya `build`).
+ */
+export interface SessionAgent {
+  name: string;
+  mode: "primary" | "subagent" | "all";
+  description: string | null;
+}
+
+export interface Session {
+  id: string;
+  projectId: string;
+  agentType: AgentType;
+  cwd: string;
+  status: SessionStatus;
+  /** Id Session di server headless opencode (`ses_...`); null sebelum dibuat. */
+  ocSessionId: string | null;
+  /**
+   * Judul Session — dibuat otomatis oleh opencode setelah prompt pertama
+   * (summarization), diterima via SSE `session.updated`. null = belum ada
+   * (UI menampilkan fallback "New session").
+   */
+  title: string | null;
+  /** Model LLM pilihan; null = model default opencode. */
+  model: SessionModel | null;
+  /** Agent (mode) pilihan; null = agent default opencode (build). */
+  agent: string | null;
+  createdAt: number;
+  updatedAt: number;
+}

package/src/types/turns.ts

@@ -0,0 +1,47 @@
+/**
+ * Model tampilan percakapan (timeline SessionView).
+ *
+ * Tipe-tipe ini adalah hasil transformasi `SessionMessage` menjadi segmen /
+ * kelompok yang siap dirender — transformasinya (fungsi murni, teruji lewat
+ * `bun test`) hidup di `src/lib/turns.ts`, sedangkan konsumen render berada
+ * di `src/components/sessions/`.
+ */
+import type { MessagePart, SessionMessage } from "./message";
+
+/** Satu segmen render turn assistant (urut sesuai alur kerja model). */
+export type TurnSegment =
+  | { kind: "reasoning"; key: string; part: MessagePart }
+  | { kind: "tool"; key: string; part: MessagePart }
+  | { kind: "error"; key: string; part: MessagePart }
+  | {
+      kind: "text";
+      key: string;
+      text: string /** Jawaban akhir turn (bukan interim). */;
+      final: boolean;
+    };
+
+/**
+ * Kelompokkan segmen satu turn menjadi blok berurutan untuk render in-order.
+ * Setiap blok berisi kluster steps (reasoning/tool) opsional diikuti teks/error
+ * opsional. Ini memungkinkan pola multi-round:
+ *   [thinking] → [text] → [thinking] → [text]
+ * dirender sebagai beberapa "Thought process" terpisah, bukan satu blok di atas.
+ */
+export interface TurnBlock {
+  /** Key unik blok (dari key segmen pertama). */
+  key: string;
+  steps: Extract<TurnSegment, { kind: "reasoning" | "tool" }>[];
+  /** Teks atau error setelah kluster steps ini (bisa null kalau blok masih streaming). */
+  content: Extract<TurnSegment, { kind: "text" | "error" }> | null;
+}
+
+/** Sekelompok pesan assistant berurutan dari satu turn balasan model. */
+export interface AssistantTurnGroup {
+  kind: "assistant";
+  /** Id pesan pertama — dipakai sebagai key React & key collapsible turn. */
+  id: string;
+  messages: SessionMessage[];
+}
+
+/** Kelompok pesan untuk render timeline: user selalu sendiri, assistant satu turn. */
+export type MessageGroup = { kind: "user"; message: SessionMessage } | AssistantTurnGroup;

package/src/ws-protocol.ts

@@ -0,0 +1,93 @@
+/**
+ * Protokol pesan WebSocket bersama Client <-> Server (versi headless).
+ *
+ * Perubahan dari versi PTY/TUI:
+ * - `history` kini membawa `messages` (SessionMessage terstruktur) dan
+ *   `prompts` (pending) — bukan chunk Output_Stream.
+ * - `output`/`resize` dihapus; digantikan `message`, `stop` (hentikan Session)
+ *   dan `interrupt` (hentikan balasan model saja — Session tetap berjalan).
+ * - `turn_active` memberi tahu Client kapan model sedang merespon (turn
+ *   streaming aktif) sehingga tombol stop/interrupt bisa ditampilkan.
+ */
+import type {
+  InteractivePrompt,
+  MessagePart,
+  PromptResponse,
+  SessionMessage,
+  SessionStatus,
+} from "./types";
+
+/** Pesan Client -> Server. */
+export type ClientMessage =
+  | { type: "attach"; sessionId: string }
+  | {
+      type: "input";
+      sessionId: string;
+      text: string;
+      /** Path relatif project untuk referensi `@file` (dibaca sebagai teks). */
+      files?: string[];
+      /** Id lampiran gambar di Attachment_Store KCG (upload dari perangkat). */
+      images?: string[];
+    }
+  | { type: "prompt_response"; sessionId: string; promptId: string; response: PromptResponse }
+  | { type: "stop"; sessionId: string }
+  /**
+   * Hentikan balasan model yang sedang berlangsung (interrupt ala opencode):
+   * turn di-abort tapi Session tetap `running` sehingga bisa langsung kirim
+   * pesan baru. Beda dari `stop` yang menonaktifkan Session.
+   */
+  | { type: "interrupt"; sessionId: string };
+
+/** Pesan Server -> Client. */
+export type ServerMessage =
+  | {
+      type: "history";
+      sessionId: string;
+      messages: SessionMessage[];
+      prompts: InteractivePrompt[];
+    }
+  | { type: "message"; sessionId: string; message: SessionMessage }
+  /** Part pesan yang sedang di-stream (SSE `message.part.updated`). */
+  | { type: "message_part"; sessionId: string; messageId: string; part: MessagePart }
+  /**
+   * Potongan teks baru untuk satu part (SSE `message.part.delta`): tambahkan
+   * `delta` ke `part[field]` (biasanya `text`). Token model tiba lewat sini.
+   */
+  | {
+      type: "message_part_delta";
+      sessionId: string;
+      messageId: string;
+      partId: string;
+      field: string;
+      delta: string;
+    }
+  | { type: "prompt"; sessionId: string; prompt: InteractivePrompt }
+  | { type: "prompt_resolved"; sessionId: string; promptId: string }
+  | { type: "session_status"; sessionId: string; status: SessionStatus }
+  /** Judul Session baru hasil generate opencode — daftar Session ikut terbarui. */
+  | { type: "session_title"; sessionId: string; title: string }
+  /** Status turn: `active: true` = model sedang merespon; `false` = berhenti. */
+  | { type: "turn_active"; sessionId: string; active: boolean }
+  /** Session dihapus permanen — subscriber harus meninggalkan halamannya. */
+  | { type: "session_deleted"; sessionId: string }
+  /**
+   * Daftar Project/Session berubah (dibuat / dihapus) dari perangkat mana
+   * pun — dikirim ke semua koneksi; sidebar & daftar memuat ulang datanya.
+   */
+  | { type: "data_changed" }
+  | { type: "error"; code: string; message: string };
+
+/** Kode error umum pada pesan `error`. */
+export const ErrorCodes = {
+  SESSION_NOT_FOUND: "SESSION_NOT_FOUND",
+  PROMPT_NOT_FOUND: "PROMPT_NOT_FOUND",
+  PROMPT_ALREADY_RESOLVED: "PROMPT_ALREADY_RESOLVED",
+  /** Reply prompt gagal diproses server opencode (mis. reply 404/400). */
+  PROMPT_FAILED: "PROMPT_FAILED",
+  /** Agent tidak lagi menunggu jawaban; prompt ditutup & kartu dihapus. */
+  PROMPT_EXPIRED: "PROMPT_EXPIRED",
+  INVALID_RESPONSE: "INVALID_RESPONSE",
+  SESSION_NOT_RUNNING: "SESSION_NOT_RUNNING",
+  INVALID_TEXT: "INVALID_TEXT",
+  ATTACHMENT_NOT_FOUND: "ATTACHMENT_NOT_FOUND",
+} as const;