kcg-code 0.0.0-stage → 0.1.0

package/src/lib/permission-info.ts

@@ -0,0 +1,101 @@
+/**
+ * Penjelasan izin tool untuk manusia — logika murni (tanpa DOM, diuji).
+ *
+ * Server menyimpan judul permission sebagai satu string ringkas hasil
+ * `describePermission`: `"<permission> — `pola1` — `pola2`"` (mis.
+ * ``external_directory — `/home/u/.config/opencode/*` ``). String itu
+ * akurat tapi tidak ramah: nama permission internal opencode + pola glob
+ * mentah. Helper ini memecahnya menjadi:
+ * - `label`  : kalimat singkat apa yang diminta agent ("Access a folder
+ *              outside the project").
+ * - `targets`: pola yang terdampak, tanpa backtick.
+ * - `risk`   : seberapa hati-hati pengguna perlu (menentukan warna kartu).
+ *
+ * Daftar permission mengikuti skema `PermissionConfig` opencode. Permission
+ * yang tidak dikenal (versi opencode lebih baru) tetap tampil dengan nama
+ * aslinya — tidak pernah disembunyikan.
+ */
+
+export type PermissionRisk = "low" | "medium" | "high";
+
+export interface PermissionInfo {
+  /** Nama permission opencode apa adanya (mis. `external_directory`). */
+  permission: string | null;
+  /** Kalimat ramah tentang apa yang diminta. */
+  label: string;
+  /** Pola/path/perintah yang terdampak (tanpa backtick). */
+  targets: string[];
+  risk: PermissionRisk;
+}
+
+interface PermissionMeta {
+  label: string;
+  risk: PermissionRisk;
+}
+
+/**
+ * Permission opencode -> label & risiko.
+ * - high   : bisa mengubah sistem / keluar dari batas project.
+ * - medium : mengubah file project / menjalankan agent lain / akses jaringan.
+ * - low    : hanya membaca.
+ */
+const PERMISSIONS: Record<string, PermissionMeta> = {
+  bash: { label: "Run a shell command", risk: "high" },
+  external_directory: { label: "Access a folder outside the project", risk: "high" },
+  doom_loop: { label: "Keep going after repeating the same step", risk: "medium" },
+  edit: { label: "Edit files", risk: "medium" },
+  task: { label: "Start a sub-agent", risk: "medium" },
+  webfetch: { label: "Fetch a web page", risk: "medium" },
+  websearch: { label: "Search the web", risk: "medium" },
+  skill: { label: "Use a skill", risk: "medium" },
+  read: { label: "Read files", risk: "low" },
+  list: { label: "List folder contents", risk: "low" },
+  glob: { label: "Search for files", risk: "low" },
+  grep: { label: "Search inside files", risk: "low" },
+  lsp: { label: "Use the language server", risk: "low" },
+  todowrite: { label: "Update the task list", risk: "low" },
+  question: { label: "Ask you a question", risk: "low" },
+};
+
+/** Judul fallback server saat event tidak membawa nama permission. */
+const FALLBACK_TITLES = new Set(["Izin tool", "Tool permission"]);
+
+/** Ubah `snake_case` menjadi kalimat ("external_directory" -> "External directory"). */
+function humanize(name: string): string {
+  const spaced = name.replace(/[_-]+/g, " ").trim();
+  return spaced.charAt(0).toUpperCase() + spaced.slice(1);
+}
+
+/**
+ * Pecah judul permission server menjadi info yang bisa dibaca manusia.
+ * Format masukan: `"<permission>"`, `"<permission> — `a` — `b`"`, atau
+ * judul fallback / null.
+ */
+export function parsePermissionTitle(title: string | null): PermissionInfo {
+  const raw = (title ?? "").trim();
+  if (raw === "" || FALLBACK_TITLES.has(raw)) {
+    return { permission: null, label: "Use a tool", targets: [], risk: "medium" };
+  }
+
+  const [head = "", ...rest] = raw.split(" — ");
+  const permission = head.trim();
+  // Pola dibungkus backtick oleh server; buang backtick-nya. Bagian tanpa
+  // backtick tetap diterima (format lama / pihak lain).
+  const targets = rest
+    .map((part) =>
+      part
+        .trim()
+        .replace(/^`(.*)`$/s, "$1")
+        .trim(),
+    )
+    .filter((t) => t !== "");
+
+  const meta = PERMISSIONS[permission.toLowerCase()];
+  return {
+    permission,
+    label: meta?.label ?? humanize(permission),
+    targets,
+    // Permission tak dikenal: anggap sedang — jangan meremehkan risikonya.
+    risk: meta?.risk ?? "medium",
+  };
+}

package/src/lib/project-extensions.ts

@@ -0,0 +1,74 @@
+/**
+ * Helper tampilan panel samping halaman Project (MCP & skill) — logika murni
+ * tanpa DOM, dipisah agar dapat diuji `bun test`.
+ */
+import type {
+  McpServerInfo,
+  McpStatus,
+  SkillInfo,
+  SkillSource,
+} from "@/server/services/opencode-client";
+
+/** Label status MCP untuk UI. */
+export const MCP_STATUS_LABEL: Record<McpStatus, string> = {
+  connected: "Connected",
+  disabled: "Disabled",
+  failed: "Failed",
+  needs_auth: "Needs auth",
+  needs_client_registration: "Needs registration",
+  unknown: "Unknown",
+};
+
+/** Warna titik status MCP (sepadan dengan titik status Session). */
+export const MCP_STATUS_DOT: Record<McpStatus, string> = {
+  connected: "bg-emerald-500",
+  disabled: "bg-muted-foreground/40",
+  failed: "bg-destructive",
+  needs_auth: "bg-amber-500",
+  needs_client_registration: "bg-amber-500",
+  unknown: "bg-muted-foreground/40",
+};
+
+/** Ringkasan singkat untuk header seksi MCP ("2 of 3 connected"). */
+export function describeMcpSummary(servers: readonly McpServerInfo[]): string {
+  if (servers.length === 0) return "None configured";
+  const connected = servers.filter((s) => s.status === "connected").length;
+  return `${connected} of ${servers.length} connected`;
+}
+
+/** Label asal skill. */
+export const SKILL_SOURCE_LABEL: Record<SkillSource, string> = {
+  project: "This project",
+  global: "Global",
+  builtin: "Built-in",
+};
+
+export interface SkillGroup {
+  source: SkillSource;
+  label: string;
+  skills: SkillInfo[];
+}
+
+/**
+ * Kelompokkan skill per asal: Project dulu (paling relevan), lalu global,
+ * lalu bawaan. Kelompok kosong dibuang; urutan dalam kelompok dipertahankan.
+ */
+export function groupSkills(skills: readonly SkillInfo[]): SkillGroup[] {
+  const order: SkillSource[] = ["project", "global", "builtin"];
+  return order
+    .map((source) => ({
+      source,
+      label: SKILL_SOURCE_LABEL[source],
+      skills: skills.filter((s) => s.source === source),
+    }))
+    .filter((g) => g.skills.length > 0);
+}
+
+/** Filter skill berdasarkan kata kunci (nama atau deskripsi, case-insensitive). */
+export function filterSkills(skills: readonly SkillInfo[], query: string): SkillInfo[] {
+  const q = query.trim().toLowerCase();
+  if (q === "") return [...skills];
+  return skills.filter(
+    (s) => s.name.toLowerCase().includes(q) || (s.description ?? "").toLowerCase().includes(q),
+  );
+}

package/src/lib/project-overview.ts

@@ -0,0 +1,117 @@
+/**
+ * Ringkasan Project untuk homepage — logika murni (tanpa DOM / fetch).
+ *
+ * Homepage (`pages/projects/ProjectsPage.tsx`) menggabungkan `GET /api/projects`
+ * dengan `GET /api/sessions` agar setiap Project bisa langsung "dilanjutkan":
+ * jumlah Session, Session yang sedang berjalan, dan Session terakhir yang
+ * disentuh. Dipisah ke `lib/` supaya bisa diuji `bun test` (pola yang sama
+ * dengan `lib/routes.ts`).
+ */
+
+import type { Project, Session } from "@/types";
+
+/** Project + agregat Session miliknya, siap dirender di daftar homepage. */
+export interface ProjectOverview {
+  project: Project;
+  /** Jumlah Session milik Project ini. */
+  sessionCount: number;
+  /** Jumlah Session berstatus `running`. */
+  runningCount: number;
+  /**
+   * Session yang paling baru diperbarui (`updatedAt` terbesar) — target tombol
+   * "Lanjutkan"; `null` bila Project belum punya Session.
+   */
+  lastSession: Session | null;
+  /**
+   * Waktu aktivitas terakhir: `updatedAt` Session terbaru, atau `createdAt`
+   * Project bila belum ada Session. Dipakai untuk urutan daftar.
+   */
+  lastActivityAt: number;
+}
+
+/**
+ * Gabungkan Project dengan Session-nya, terurut dari aktivitas terbaru.
+ * Session dengan `projectId` yang tidak dikenal diabaikan.
+ */
+export function buildProjectOverviews(
+  projects: readonly Project[],
+  sessions: readonly Session[],
+): ProjectOverview[] {
+  const byProject = new Map<string, Session[]>();
+  for (const session of sessions) {
+    const bucket = byProject.get(session.projectId);
+    if (bucket === undefined) byProject.set(session.projectId, [session]);
+    else bucket.push(session);
+  }
+
+  const overviews = projects.map((project) => {
+    const own = byProject.get(project.id) ?? [];
+    let lastSession: Session | null = null;
+    let runningCount = 0;
+    for (const session of own) {
+      if (session.status === "running") runningCount += 1;
+      if (lastSession === null || session.updatedAt > lastSession.updatedAt) {
+        lastSession = session;
+      }
+    }
+    return {
+      project,
+      sessionCount: own.length,
+      runningCount,
+      lastSession,
+      lastActivityAt: lastSession?.updatedAt ?? project.createdAt,
+    };
+  });
+
+  // Aktivitas terbaru di atas; nama (case-insensitive) sebagai tie-break agar
+  // urutan stabil dan tidak berubah-ubah antar refresh.
+  return overviews.sort((a, b) => {
+    if (b.lastActivityAt !== a.lastActivityAt) return b.lastActivityAt - a.lastActivityAt;
+    return a.project.name.localeCompare(b.project.name, undefined, { sensitivity: "base" });
+  });
+}
+
+/**
+ * Filter daftar berdasarkan kata kunci (cocok pada nama atau path, tanpa
+ * membedakan huruf besar/kecil). Query kosong/whitespace -> daftar utuh.
+ */
+export function filterProjectOverviews(
+  overviews: readonly ProjectOverview[],
+  query: string,
+): ProjectOverview[] {
+  const needle = query.trim().toLowerCase();
+  if (needle === "") return [...overviews];
+  return overviews.filter(
+    ({ project }) =>
+      project.name.toLowerCase().includes(needle) || project.path.toLowerCase().includes(needle),
+  );
+}
+
+/** Total Session yang sedang berjalan di seluruh Project. */
+export function totalRunningSessions(overviews: readonly ProjectOverview[]): number {
+  return overviews.reduce((sum, o) => sum + o.runningCount, 0);
+}
+
+/**
+ * Short relative label for activity time ("just now", "3 hours ago").
+ * `now` diinjeksi agar deterministik saat diuji.
+ */
+export function formatRelativeTime(ts: number, now: number = Date.now()): string {
+  const diff = now - ts;
+  if (diff < 0) return "just now";
+
+  const minute = 60_000;
+  const hour = 60 * minute;
+  const day = 24 * hour;
+
+  if (diff < minute) return "just now";
+  if (diff < hour) return `${Math.floor(diff / minute)} minutes ago`;
+  if (diff < day) return `${Math.floor(diff / hour)} hours ago`;
+  if (diff < 7 * day) return `${Math.floor(diff / day)} days ago`;
+
+  return new Date(ts).toLocaleDateString(undefined, {
+    day: "2-digit",
+    month: "short",
+    year: "numeric",
+  });
+}

package/src/lib/prompts.ts

@@ -0,0 +1,87 @@
+/**
+ * Interactive_Prompt — logika murni (tanpa DOM).
+ *
+ * Dipisah dari `PromptCard.tsx` agar dapat diuji `bun test` (unit test 24.6):
+ * - `getPromptActions`: aksi yang dirender untuk sebuah prompt.
+ * - `groupPrompts`: beberapa permission identik (kind + title sama) menjadi
+ *   SATU kartu (bug kartu nyepam).
+ */
+import type { InteractivePrompt, PromptQuestion, PromptResponse } from "@/types";
+
+export type PromptActionVariant = "default" | "destructive" | "outline";
+
+export interface PromptAction {
+  key: string;
+  label: string;
+  response: PromptResponse;
+  variant: PromptActionVariant;
+  /** Ikon khusus (mis. "shield-check" untuk Always allow). */
+  icon?: "shield-check";
+}
+
+/**
+ * Aksi yang dirender untuk sebuah Interactive_Prompt (murni — diuji di 24.6).
+ * Untuk `confirmation`: Approve, Always allow, Deny, dan Cancel; Cancel
+ * memakai respon yang sama dengan Deny (Requirement 8.5).
+ *
+ * Menu MULTI-SELECT tidak memakai aksi per opsi — jawaban dikumpulkan lewat
+ * checkbox lalu dikirim sekaligus `{ options: string[] }` (lihat PromptCard).
+ */
+export function getPromptActions(prompt: InteractivePrompt): PromptAction[] {
+  if (prompt.type === "menu") {
+    return (prompt.options ?? []).map((option) => ({
+      key: `option-${option.label}`,
+      label: option.label,
+      response: { option: option.label },
+      variant: "outline",
+    }));
+  }
+  return [
+    { key: "approve", label: "Approve", response: "approve", variant: "default" },
+    {
+      key: "always",
+      label: "Always allow",
+      response: "always",
+      variant: "outline",
+      icon: "shield-check",
+    },
+    { key: "deny", label: "Deny", response: "deny", variant: "destructive" },
+    // Requirement 8.5: Cancel diperlakukan sebagai respon Deny yang sama.
+    { key: "cancel", label: "Cancel", response: "deny", variant: "outline" },
+  ];
+}
+
+/**
+ * Daftar pertanyaan yang dirender kartu — multi-question memakai field
+ * `questions`; pertanyaan tunggal diwrap dari field legacy.
+ * Murni (diuji tanpa DOM) agar konsisten dengan helper lain di file ini.
+ */
+export function getPromptQuestions(prompt: InteractivePrompt): PromptQuestion[] {
+  if (prompt.questions && prompt.questions.length > 0) return prompt.questions;
+  if (prompt.kind !== "question") return [];
+  return [
+    {
+      question: prompt.title,
+      options: prompt.options ?? null,
+      multiple: prompt.multiple === true ? true : undefined,
+      custom: prompt.custom === true ? true : undefined,
+    },
+  ];
+}
+
+/**
+ * Kelompokkan prompt pending yang identik (kind + title sama) menjadi satu
+ * kartu. Kunci sama dengan sisi server (`permissionGroupKey`) agar kartu yang
+ * dijawab user persis grup yang di-fan-out server. Urutan kemunculan
+ * anggota pertama dipertahankan.
+ */
+export function groupPrompts(prompts: readonly InteractivePrompt[]): InteractivePrompt[][] {
+  const groups = new Map<string, InteractivePrompt[]>();
+  for (const p of prompts) {
+    const key = `${p.kind}\u0000${p.title ?? ""}`;
+    const g = groups.get(key);
+    if (g) g.push(p);
+    else groups.set(key, [p]);
+  }
+  return [...groups.values()];
+}

package/src/lib/references.ts

@@ -0,0 +1,106 @@
+/**
+ * Daftar "Reference": file project yang DIBACA agent untuk menjawab.
+ *
+ * Diturunkan dari parts pesan yang SUDAH dimiliki timeline (tidak ada request
+ * tambahan): tiap pembacaan file dikumpulkan tanpa duplikat, TERBARU DI ATAS.
+ *
+ * "Terbaru" = pembacaan terakhir, bukan pertama: file yang dibaca lagi naik
+ * kembali ke atas. Jadi bagian atas daftar selalu mencerminkan apa yang
+ * sedang dikerjakan agent saat ini.
+ *
+ * Yang dihitung "dibaca":
+ * - Tool `read` dengan target satu file.
+ * - Referensi `@file` dari pengguna (part `file` TANPA `attachmentId`) — isi
+ *   file itu dibaca untuk menjawab.
+ *
+ * Yang TIDAK dihitung:
+ * - Tool penulis (`write`, `edit`, `patch`, …). Reference menjawab "konteks
+ *   apa yang dipakai agent", bukan "apa yang diubah". File yang dibaca lalu
+ *   diubah tetap muncul — karena ia DIBACA; file yang hanya ditulis tidak.
+ * - `bash`, `grep`, `glob`, `list`, `webfetch`, dll — targetnya pola/perintah,
+ *   bukan satu file.
+ * - Lampiran upload pengguna (part `file` dengan `attachmentId`): sudah tampil
+ *   di bubble pesannya sendiri dan bukan file project.
+ * - Path di luar project, direktori (berakhiran `/`), dan pola glob.
+ */
+import type { MessagePart, SessionMessage } from "@/types";
+import { toolTarget } from "./turns";
+
+/** Tool yang membaca isi satu file. */
+const READ_TOOLS = new Set(["read"]);
+
+export interface FileReference {
+  /** Path relatif terhadap root project. */
+  path: string;
+}
+
+/** Nama file terakhir dari sebuah path (untuk tampilan ringkas). */
+export function baseName(p: string): string {
+  return p.split("/").filter(Boolean).pop() ?? p;
+}
+
+/** Path tampak seperti pola glob / direktori, bukan satu file. */
+function isPatternOrDir(p: string): boolean {
+  return p.endsWith("/") || /[*?{}[\]]/.test(p);
+}
+
+/**
+ * Normalisasi target tool menjadi path relatif project, atau null bila bukan
+ * file project (di luar `cwd`, glob, direktori, kosong).
+ */
+export function toProjectPath(target: string, cwd: string | null): string | null {
+  const raw = target.trim();
+  if (raw === "" || isPatternOrDir(raw)) return null;
+
+  let rel = raw;
+  if (raw.startsWith("/")) {
+    // Absolut: hanya diterima bila berada di dalam worktree project.
+    if (cwd === null || cwd === "") return null;
+    const base = cwd.endsWith("/") ? cwd : `${cwd}/`;
+    if (!raw.startsWith(base)) return null;
+    rel = raw.slice(base.length);
+  }
+  rel = rel.replace(/^\.\//, "");
+  // `..` keluar dari project -> bukan file project.
+  if (rel === "" || rel.startsWith("../")) return null;
+  return rel;
+}
+
+/**
+ * Kumpulkan file yang dibaca di seluruh pesan satu Session, terbaru di atas.
+ * `cwd` dipakai untuk mengubah path absolut menjadi relatif; null -> path
+ * absolut diabaikan.
+ */
+export function collectReferences(
+  messages: readonly SessionMessage[],
+  cwd: string | null = null,
+): FileReference[] {
+  // Map mempertahankan urutan sisip: hapus lalu sisip ulang = pindahkan ke
+  // akhir. Setelah selesai, akhir Map = pembacaan paling baru -> dibalik.
+  const byRecency = new Map<string, FileReference>();
+  for (const message of messages) {
+    for (const part of message.parts) {
+      const path = readPath(part, cwd);
+      if (path === null) continue;
+      byRecency.delete(path);
+      byRecency.set(path, { path });
+    }
+  }
+  return [...byRecency.values()].reverse();
+}
+
+/** Path file project yang DIBACA oleh satu part, atau null. */
+function readPath(part: MessagePart, cwd: string | null): string | null {
+  // Echo `@file` dari pengguna: part `file` tanpa `attachmentId` (lampiran
+  // upload selalu punya `attachmentId` dan bukan file project).
+  if (part.type === "file") {
+    if (typeof part.attachmentId === "string") return null;
+    const name = typeof part.filename === "string" ? part.filename : "";
+    return toProjectPath(name, cwd);
+  }
+  if (part.type !== "tool") return null;
+  const tool = typeof part.tool === "string" ? part.tool.toLowerCase() : "";
+  if (!READ_TOOLS.has(tool)) return null;
+  const target = toolTarget(part);
+  return target === null ? null : toProjectPath(target, cwd);
+}

package/src/lib/routes.ts

@@ -0,0 +1,115 @@
+/**
+ * Route URL KCG Code — logika murni (tanpa DOM / History API).
+ *
+ * Dipisah dari `hooks/useRouter.ts` agar dapat diuji dengan `bun test`
+ * (pola yang sama dengan `useTheme.ts`). Server (`src/server/app.ts`)
+ * menyajikan shell SPA hanya untuk rute halaman yang terdaftar di
+ * `src/index.ts` (lihat `spaPaths`), sehingga React tinggal memetakan
+ * `location.pathname` -> view lewat `parseRoute()`.
+ */
+
+/** Route hasil parsing `location.pathname`. */
+export type AppRoute =
+  | { name: "projects" }
+  | { name: "project"; projectId: string }
+  | { name: "session"; projectId: string; sessionId: string }
+  | { name: "skills" }
+  | { name: "settings"; section: SettingsSection; anchor?: string }
+  | { name: "not-found" };
+
+/**
+ * Sub-halaman Settings (`/settings/:section`). Tab yang tampil hanya
+ * profile/security/workspace/remote; `about` dibuka dari ikon di judul.
+ */
+export const SETTINGS_SECTIONS = ["profile", "security", "workspace", "remote", "about"] as const;
+export type SettingsSection = (typeof SETTINGS_SECTIONS)[number];
+
+/**
+ * Alias URL lama -> section + anchor. `devices` kini bagian dari Security
+ * (grup "Signed-in devices"); URL lamanya tetap berfungsi.
+ */
+const SETTINGS_ALIASES: Record<string, { section: SettingsSection; anchor: string }> = {
+  devices: { section: "security", anchor: "devices" },
+};
+
+function isSettingsSection(value: string): value is SettingsSection {
+  return (SETTINGS_SECTIONS as readonly string[]).includes(value);
+}
+
+/** URL daftar Project. */
+export function projectsPath(): string {
+  return "/";
+}
+
+/** URL daftar Session milik sebuah Project. */
+export function projectPath(projectId: string): string {
+  return `/projects/${projectId}`;
+}
+
+/** URL Session view milik sebuah Project. */
+export function sessionPath(projectId: string, sessionId: string): string {
+  return `/projects/${projectId}/sessions/${sessionId}`;
+}
+
+/**
+ * URL halaman Skills. `projectId` (opsional) jadi query `?project=` agar
+ * Project tersebut otomatis terpilih saat halaman dibuka.
+ */
+export function skillsPath(projectId?: string | null): string {
+  return projectId ? `/skills?project=${encodeURIComponent(projectId)}` : "/skills";
+}
+
+/** URL halaman Settings; tanpa `section` = `/settings` (dibuka sebagai Profile). */
+export function settingsPath(section?: SettingsSection): string {
+  return section ? `/settings/${section}` : "/settings";
+}
+
+/** Ambil id Project dari query string halaman Skills (`?project=`). */
+export function parseSkillsProject(search: string): string | null {
+  const id = new URLSearchParams(search).get("project");
+  return id !== null && id.length > 0 ? id : null;
+}
+
+/**
+ * Pemetaan `pathname` -> `AppRoute`. Segment id dianggap opaque — id
+ * Project/Session berupa UUID sehingga aman tanpa decoding. Trailing slash
+ * diabaikan (`/projects/x/` sama dengan `/projects/x`).
+ */
+export function parseRoute(pathname: string): AppRoute {
+  const segments = pathname
+    .replace(/\/+$/, "")
+    .split("/")
+    .filter((segment) => segment.length > 0);
+
+  if (segments.length === 0) return { name: "projects" };
+  if (segments[0] === "skills" && segments.length === 1) return { name: "skills" };
+  if (segments[0] === "settings") {
+    if (segments.length === 1) return { name: "settings", section: "profile" };
+    const section = segments[1];
+    if (segments.length === 2 && section !== undefined && isSettingsSection(section)) {
+      return { name: "settings", section };
+    }
+    // `Object.hasOwn`: hindari kunci prototipe (mis. "/settings/constructor").
+    const alias =
+      segments.length === 2 && section !== undefined && Object.hasOwn(SETTINGS_ALIASES, section)
+        ? SETTINGS_ALIASES[section]
+        : undefined;
+    if (alias) return { name: "settings", section: alias.section, anchor: alias.anchor };
+    return { name: "not-found" };
+  }
+  if (segments[0] !== "projects") return { name: "not-found" };
+
+  const projectId = segments[1];
+  if (projectId === undefined || projectId.length === 0) return { name: "not-found" };
+
+  if (segments.length === 2) return { name: "project", projectId };
+
+  if (segments[2] === "sessions" && segments.length === 4) {
+    const sessionId = segments[3];
+    if (sessionId !== undefined && sessionId.length > 0) {
+      return { name: "session", projectId, sessionId };
+    }
+  }
+
+  return { name: "not-found" };
+}

package/src/lib/session-handoff.ts

@@ -0,0 +1,25 @@
+/**
+ * Serah-terima homepage -> Session view agar perpindahan tanpa jeda:
+ * Session yang baru dibuat (`POST /api/sessions`) dititipkan di memori
+ * sehingga `SessionPage` bisa langsung merender tanpa `GET /api/sessions`
+ * (tidak ada kilatan "Loading…" di tengah animasi).
+ *
+ * Hanya di memori (per tab, per kunjungan): refresh halaman kembali ke jalur
+ * normal (fetch). Dibaca dengan `peek` (aman untuk StrictMode yang memanggil
+ * initializer dua kali) lalu dibersihkan oleh pemakai setelah mount.
+ */
+import type { Session } from "@/types";
+
+const seeded = new Map<string, Session>();
+
+export function seedSession(session: Session): void {
+  seeded.set(session.id, session);
+}
+
+export function peekSeededSession(sessionId: string): Session | null {
+  return seeded.get(sessionId) ?? null;
+}
+
+export function clearSeededSession(sessionId: string): void {
+  seeded.delete(sessionId);
+}

package/src/lib/session-status.ts

@@ -0,0 +1,45 @@
+/**
+ * Pemetaan status Session & koneksi WS ke label/visual UI (murni, tanpa DOM).
+ *
+ * Dipakai header chat (`SessionHeader`) dan daftar Session (`SessionList`),
+ * agar warna titik & teks status tidak didefinisikan ganda.
+ */
+import type { WsConnectionStatus } from "@/hooks/useWebSocket";
+import type { SessionStatus } from "@/types";
+
+/** Warna titik status Session (sepadan di header chat & baris daftar). */
+export const SESSION_STATUS_DOT: Record<SessionStatus, string> = {
+  running: "bg-emerald-500",
+  stopped: "bg-muted-foreground/50",
+  crashed: "bg-destructive",
+};
+
+/** Label teks status Session (dipakai badge di daftar Session). */
+export const SESSION_STATUS_LABEL: Record<SessionStatus, string> = {
+  running: "Running",
+  stopped: "Stopped",
+  crashed: "Crashed",
+};
+
+/** Variant Badge shadcn untuk sebuah status Session. */
+export function sessionStatusVariant(
+  status: SessionStatus,
+): "default" | "secondary" | "destructive" {
+  if (status === "running") return "default";
+  if (status === "crashed") return "destructive";
+  return "secondary";
+}
+
+/** Label status koneksi WS untuk UI (mis. subtitle header chat). */
+export function wsStatusLabel(status: WsConnectionStatus): string {
+  switch (status) {
+    case "connected":
+      return "connected";
+    case "connecting":
+      return "connecting…";
+    case "reconnecting":
+      return "reconnecting…";
+    default:
+      return "disconnected";
+  }
+}