kcg-code 0.0.0-stage → 0.1.0

package/src/server/db/schema.ts

@@ -0,0 +1,221 @@
+/**
+ * Skema SQLite & migrasi idempoten untuk `Session_Store` (headless).
+ * Dipisah dari `db.ts` agar komposisi root tetap ramping dan evolusi skema
+ * (menambah tabel/kolom) punya satu tempat.
+ */
+import type { Database } from "bun:sqlite";
+
+export const SCHEMA = `
+CREATE TABLE IF NOT EXISTS projects (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL UNIQUE,
+  path TEXT NOT NULL UNIQUE,
+  instructions TEXT,
+  created_at INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS sessions (
+  id TEXT PRIMARY KEY,
+  project_id TEXT NOT NULL REFERENCES projects(id),
+  agent_type TEXT NOT NULL,
+  cwd TEXT NOT NULL,
+  status TEXT NOT NULL CHECK (status IN ('running','stopped','crashed')),
+  oc_session_id TEXT,
+  model TEXT,
+  agent TEXT,
+  title TEXT,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL
+);
+
+-- Append-only: tidak pernah UPDATE/DELETE, hanya INSERT (Requirement 3.3)
+CREATE TABLE IF NOT EXISTS session_status_history (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  session_id TEXT NOT NULL REFERENCES sessions(id),
+  status TEXT NOT NULL,
+  changed_at INTEGER NOT NULL
+);
+
+-- Append-only: pesan percakapan terstruktur (Requirement 3.1, 3.2)
+CREATE TABLE IF NOT EXISTS messages (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  session_id TEXT NOT NULL REFERENCES sessions(id),
+  message_id TEXT NOT NULL,
+  role TEXT NOT NULL CHECK (role IN ('user','assistant')),
+  parts_json TEXT NOT NULL,
+  created_at INTEGER NOT NULL,
+  UNIQUE(session_id, message_id)
+);
+CREATE INDEX IF NOT EXISTS idx_messages_session_created ON messages(session_id, created_at);
+
+CREATE TABLE IF NOT EXISTS prompts (
+  id TEXT PRIMARY KEY,
+  session_id TEXT NOT NULL REFERENCES sessions(id),
+  kind TEXT NOT NULL DEFAULT 'permission',
+  type TEXT NOT NULL CHECK (type IN ('confirmation','menu')),
+  custom INTEGER NOT NULL DEFAULT 0,
+  title TEXT,
+  options_json TEXT,
+  status TEXT NOT NULL CHECK (status IN ('pending','resolved')),
+  created_at INTEGER NOT NULL,
+  resolved_at INTEGER
+);
+CREATE INDEX IF NOT EXISTS idx_prompts_session_status ON prompts(session_id, status);
+
+-- Kunci aplikasi (lock screen). Satu baris (id = 1). Hash argon2id — sandi
+-- asli tidak pernah disimpan. lock_kind NULL = kunci belum diatur.
+CREATE TABLE IF NOT EXISTS auth_settings (
+  id INTEGER PRIMARY KEY CHECK (id = 1),
+  lock_kind TEXT CHECK (lock_kind IN ('pin','password')),
+  lock_hash TEXT,
+  nickname TEXT,
+  avatar_mime TEXT,
+  avatar BLOB,
+  avatar_preset TEXT,
+  avatar_version INTEGER NOT NULL DEFAULT 0,
+  auto_lock_minutes INTEGER NOT NULL DEFAULT 15,
+  updated_at INTEGER NOT NULL
+);
+
+-- Sesi login per perangkat. Yang disimpan hanya SHA-256 dari token cookie,
+-- sehingga bocornya DB tidak memberi sesi yang bisa dipakai.
+CREATE TABLE IF NOT EXISTS auth_sessions (
+  id TEXT PRIMARY KEY,
+  token_hash TEXT NOT NULL UNIQUE,
+  user_agent TEXT,
+  created_at INTEGER NOT NULL,
+  last_seen_at INTEGER NOT NULL,
+  expires_at INTEGER NOT NULL
+);
+
+-- Passkey (WebAuthn) — cara buka kunci TAMBAHAN di samping PIN/password.
+-- Hanya kunci publik yang disimpan (bukan rahasia). rp_id = domain tempat
+-- passkey didaftarkan; passkey hanya berlaku di domain yang sama.
+CREATE TABLE IF NOT EXISTS auth_passkeys (
+  id TEXT PRIMARY KEY,
+  credential_id TEXT NOT NULL UNIQUE,
+  public_key BLOB NOT NULL,
+  counter INTEGER NOT NULL DEFAULT 0,
+  transports TEXT,
+  rp_id TEXT NOT NULL,
+  name TEXT NOT NULL,
+  device_type TEXT,
+  backed_up INTEGER NOT NULL DEFAULT 0,
+  created_at INTEGER NOT NULL,
+  last_used_at INTEGER
+);
+CREATE INDEX IF NOT EXISTS idx_auth_passkeys_rp ON auth_passkeys(rp_id);
+
+-- Tunnel publik (<username>.<domain>) lewat API kcgcode-rp + frpc.
+-- Satu baris (id = 1). device_token (dari device flow, bisa dicabut di VPS)
+-- & tunnel_secret tidak pernah dikirim ke browser; enabled = tunnel
+-- dinyalakan ulang saat start.
+CREATE TABLE IF NOT EXISTS tunnel_account (
+  id INTEGER PRIMARY KEY CHECK (id = 1),
+  email TEXT,
+  username TEXT,
+  subdomain TEXT,
+  device_id TEXT,
+  device_token TEXT,
+  tunnel_secret TEXT,
+  enabled INTEGER NOT NULL DEFAULT 0,
+  updated_at INTEGER NOT NULL
+);
+`;
+
+/** Menambah kolom bila belum ada (migrasi DB lama yang idempoten). */
+function ensureColumn(db: Database, table: string, column: string, ddl: string): void {
+  const cols = db.query(`PRAGMA table_info(${table})`).all() as { name: string }[];
+  if (!cols.some((c) => c.name === column)) db.exec(ddl);
+}
+
+/**
+ * Menjalankan seluruh migrasi idempoten: membuat tabel yang belum ada lalu
+ * menambah kolom dari skema lama (versi PTY) yang masih dipakai.
+ */
+export function runMigrations(db: Database): void {
+  db.exec(SCHEMA);
+  ensureColumn(
+    db,
+    "sessions",
+    "oc_session_id",
+    "ALTER TABLE sessions ADD COLUMN oc_session_id TEXT",
+  );
+  ensureColumn(
+    db,
+    "prompts",
+    "kind",
+    "ALTER TABLE prompts ADD COLUMN kind TEXT NOT NULL DEFAULT 'permission'",
+  );
+  ensureColumn(db, "prompts", "title", "ALTER TABLE prompts ADD COLUMN title TEXT");
+  // Question saja: boleh jawab bebas (flag `custom` skema question opencode).
+  ensureColumn(
+    db,
+    "prompts",
+    "custom",
+    "ALTER TABLE prompts ADD COLUMN custom INTEGER NOT NULL DEFAULT 0",
+  );
+  // Question saja: boleh pilih lebih dari satu opsi (flag `multiple` skema
+  // question opencode) — kartu history tetap tampil sebagai multi-select.
+  ensureColumn(
+    db,
+    "prompts",
+    "multiple",
+    "ALTER TABLE prompts ADD COLUMN multiple INTEGER NOT NULL DEFAULT 0",
+  );
+  // Multi-question: JSON seluruh pertanyaan request (null = pertanyaan
+  // tunggal, field legacy title/options cukup).
+  ensureColumn(
+    db,
+    "prompts",
+    "questions_json",
+    "ALTER TABLE prompts ADD COLUMN questions_json TEXT",
+  );
+  // Agent (mode) opencode pilihan Session — null = default opencode (build).
+  ensureColumn(db, "sessions", "agent", "ALTER TABLE sessions ADD COLUMN agent TEXT");
+  // Model pilihan per Session (JSON `{providerID, modelID}`), NULL = default.
+  ensureColumn(db, "sessions", "model", "ALTER TABLE sessions ADD COLUMN model TEXT");
+  // Judul Session hasil generate opencode (SSE `session.updated`), NULL = belum ada.
+  ensureColumn(db, "sessions", "title", "ALTER TABLE sessions ADD COLUMN title TEXT");
+  // Custom instruction per Project (dikirim sebagai `system`), NULL = tidak ada.
+  ensureColumn(db, "projects", "instructions", "ALTER TABLE projects ADD COLUMN instructions TEXT");
+  // Remote access: provider terpilih (kcg = layanan bawaan, lhr = localhost.run)
+  // + status nyala localhost.run (dinyalakan ulang otomatis saat start).
+  ensureColumn(
+    db,
+    "tunnel_account",
+    "provider",
+    "ALTER TABLE tunnel_account ADD COLUMN provider TEXT NOT NULL DEFAULT 'kcg'",
+  );
+  ensureColumn(
+    db,
+    "tunnel_account",
+    "lhr_enabled",
+    "ALTER TABLE tunnel_account ADD COLUMN lhr_enabled INTEGER NOT NULL DEFAULT 0",
+  );
+  // Avatar bawaan (id preset ikon). Eksklusif dengan foto upload `avatar`.
+  ensureColumn(
+    db,
+    "auth_settings",
+    "avatar_preset",
+    "ALTER TABLE auth_settings ADD COLUMN avatar_preset TEXT",
+  );
+  // Onboarding (welcome screen) selesai — NULL = instalasi baru.
+  const hadOnboarded = (
+    db.query("PRAGMA table_info(auth_settings)").all() as { name: string }[]
+  ).some((c) => c.name === "onboarded_at");
+  ensureColumn(
+    db,
+    "auth_settings",
+    "onboarded_at",
+    "ALTER TABLE auth_settings ADD COLUMN onboarded_at INTEGER",
+  );
+  if (!hadOnboarded) {
+    // Instalasi LAMA (sudah punya kunci / profil / project sebelum fitur ini)
+    // tidak perlu melihat welcome screen — tandai selesai saat migrasi.
+    db.exec(`UPDATE auth_settings SET onboarded_at = updated_at
+             WHERE onboarded_at IS NULL
+               AND (lock_kind IS NOT NULL OR nickname IS NOT NULL
+                    OR EXISTS (SELECT 1 FROM projects))`);
+  }
+}

package/src/server/db/sessions.ts

@@ -0,0 +1,239 @@
+/**
+ * Repository Sessions + riwayat statusnya. Status history bukan domain
+ * terpisah melainkan sub-entitas agregat Session (tabel-nya pun
+ * `session_status_history`), sehingga transaksi yang menyentuh keduanya
+ * (`updateSessionStatus`) dan cascade delete tinggal di sini.
+ */
+import type { Database } from "bun:sqlite";
+import type { Session, SessionModel, SessionStatus } from "../../types";
+import type { Result, SimpleResult } from "../result";
+import { errResult, mapSession, type SessionRow } from "./rows";
+
+/** Satu entri riwayat status (append-only). */
+export interface StatusHistoryEntry {
+  sessionId: string;
+  status: SessionStatus;
+  changedAt: number;
+}
+
+export function sessionExists(db: Database, sessionId: string): unknown {
+  return db.query("SELECT id FROM sessions WHERE id = ?").get(sessionId);
+}
+
+export function createSessionRepo(db: Database) {
+  const q = {
+    projectById: db.query("SELECT id FROM projects WHERE id = ?"),
+    insertSession: db.query(
+      "INSERT INTO sessions (id, project_id, agent_type, cwd, status, oc_session_id, model, agent, title, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+    ),
+    getSession: db.query("SELECT * FROM sessions WHERE id = ?"),
+    getSessionByOcId: db.query("SELECT * FROM sessions WHERE oc_session_id = ?"),
+    listSessions: db.query("SELECT * FROM sessions ORDER BY created_at ASC, id ASC"),
+    updateSessionStatus: db.query("UPDATE sessions SET status = ?, updated_at = ? WHERE id = ?"),
+    updateSessionOcId: db.query(
+      "UPDATE sessions SET oc_session_id = ?, updated_at = ? WHERE id = ?",
+    ),
+    updateSessionModel: db.query("UPDATE sessions SET model = ?, updated_at = ? WHERE id = ?"),
+    updateSessionAgent: db.query("UPDATE sessions SET agent = ?, updated_at = ? WHERE id = ?"),
+    updateSessionTitle: db.query("UPDATE sessions SET title = ?, updated_at = ? WHERE id = ?"),
+    deleteSessionMessages: db.query("DELETE FROM messages WHERE session_id = ?"),
+    deleteSessionPrompts: db.query("DELETE FROM prompts WHERE session_id = ?"),
+    deleteSessionHistory: db.query("DELETE FROM session_status_history WHERE session_id = ?"),
+    deleteSessionRow: db.query("DELETE FROM sessions WHERE id = ?"),
+    insertHistory: db.query(
+      "INSERT INTO session_status_history (session_id, status, changed_at) VALUES (?, ?, ?)",
+    ),
+    getHistory: db.query(
+      "SELECT session_id, status, changed_at FROM session_status_history WHERE session_id = ? ORDER BY id ASC",
+    ),
+  };
+
+  function findRow(sessionId: string): SessionRow | null {
+    return q.getSession.get(sessionId) as SessionRow | null;
+  }
+
+  return {
+    insertSession(session: Session): Result<Session> {
+      try {
+        if (!q.projectById.get(session.projectId)) return errResult("PROJECT_NOT_FOUND");
+        q.insertSession.run(
+          session.id,
+          session.projectId,
+          session.agentType,
+          session.cwd,
+          session.status,
+          session.ocSessionId,
+          session.model ? JSON.stringify(session.model) : null,
+          session.agent ?? null,
+          session.title ?? null,
+          session.createdAt,
+          session.updatedAt,
+        );
+        return { ok: true, data: session };
+      } catch (e) {
+        return errResult(`SESSION_WRITE_FAILED: ${(e as Error).message}`);
+      }
+    },
+
+    updateSessionStatus(
+      sessionId: string,
+      status: SessionStatus,
+      changedAt = Date.now(),
+    ): Result<Session> {
+      try {
+        if (!findRow(sessionId)) return errResult("SESSION_NOT_FOUND");
+        const tx = db.transaction(() => {
+          q.updateSessionStatus.run(status, changedAt, sessionId);
+          q.insertHistory.run(sessionId, status, changedAt);
+        });
+        tx();
+        const updated = mapSession(findRow(sessionId) as SessionRow);
+        return { ok: true, data: updated };
+      } catch (e) {
+        return errResult(`SESSION_UPDATE_FAILED: ${(e as Error).message}`);
+      }
+    },
+
+    /**
+     * Perbarui `oc_session_id` tanpa mengubah status — dipakai `resumeSession`
+     * saat Session lama menunjuk oc session yang sudah tidak dikenal server
+     * (mis. storage opencode dibersihkan) dan perlu memakai sesi remote baru.
+     */
+    updateSessionOcId(sessionId: string, ocSessionId: string | null): Result<Session> {
+      try {
+        if (!findRow(sessionId)) return errResult("SESSION_NOT_FOUND");
+        q.updateSessionOcId.run(ocSessionId, Date.now(), sessionId);
+        return { ok: true, data: mapSession(findRow(sessionId) as SessionRow) };
+      } catch (e) {
+        return errResult(`SESSION_UPDATE_FAILED: ${(e as Error).message}`);
+      }
+    },
+
+    /**
+     * Perbarui model pilihan Session tanpa mengubah status — dipakai rute
+     * `PUT /api/sessions/:id/model`. `null` berarti kembali ke default opencode.
+     */
+    updateSessionModel(sessionId: string, model: SessionModel | null): Result<Session> {
+      try {
+        if (!findRow(sessionId)) return errResult("SESSION_NOT_FOUND");
+        q.updateSessionModel.run(model ? JSON.stringify(model) : null, Date.now(), sessionId);
+        return { ok: true, data: mapSession(findRow(sessionId) as SessionRow) };
+      } catch (e) {
+        return errResult(`SESSION_UPDATE_FAILED: ${(e as Error).message}`);
+      }
+    },
+
+    /**
+     * Perbarui agent (mode) pilihan Session tanpa mengubah status — dipakai
+     * rute `PUT /api/sessions/:id`. `null` berarti kembali ke agent default
+     * opencode (biasanya `build`).
+     */
+    updateSessionAgent(sessionId: string, agent: string | null): Result<Session> {
+      try {
+        if (!findRow(sessionId)) return errResult("SESSION_NOT_FOUND");
+        q.updateSessionAgent.run(agent ?? null, Date.now(), sessionId);
+        return { ok: true, data: mapSession(findRow(sessionId) as SessionRow) };
+      } catch (e) {
+        return errResult(`SESSION_UPDATE_FAILED: ${(e as Error).message}`);
+      }
+    },
+
+    /**
+     * Simpan judul Session hasil generate opencode (SSE `session.updated`).
+     * Tanpa mengubah status; dipanggil berulang aman (judul sama dioverwrite).
+     */
+    updateSessionTitle(sessionId: string, title: string): Result<Session> {
+      try {
+        if (!findRow(sessionId)) return errResult("SESSION_NOT_FOUND");
+        q.updateSessionTitle.run(title, Date.now(), sessionId);
+        return { ok: true, data: mapSession(findRow(sessionId) as SessionRow) };
+      } catch (e) {
+        return errResult(`SESSION_UPDATE_FAILED: ${(e as Error).message}`);
+      }
+    },
+
+    getSession(sessionId: string): Result<Session> {
+      try {
+        const row = findRow(sessionId);
+        if (!row) return errResult("SESSION_NOT_FOUND");
+        return { ok: true, data: mapSession(row) };
+      } catch (e) {
+        return errResult(`SESSION_READ_FAILED: ${(e as Error).message}`);
+      }
+    },
+
+    getSessionByOcId(ocSessionId: string): Result<Session> {
+      try {
+        const row = q.getSessionByOcId.get(ocSessionId) as SessionRow | null;
+        if (!row) return errResult("SESSION_NOT_FOUND");
+        return { ok: true, data: mapSession(row) };
+      } catch (e) {
+        return errResult(`SESSION_READ_FAILED: ${(e as Error).message}`);
+      }
+    },
+
+    listSessions(): Session[] {
+      return (q.listSessions.all() as SessionRow[]).map(mapSession);
+    },
+
+    /**
+     * Hapus Session beserta seluruh baris anaknya (messages, prompts,
+     * riwayat status) dalam satu transaksi. Gagal di tengah jalan di-rollback
+     * agar data tidak setengah terhapus.
+     */
+    deleteSession(sessionId: string): SimpleResult {
+      try {
+        if (!findRow(sessionId)) return errResult("SESSION_NOT_FOUND");
+        const tx = db.transaction(() => {
+          q.deleteSessionMessages.run(sessionId);
+          q.deleteSessionPrompts.run(sessionId);
+          q.deleteSessionHistory.run(sessionId);
+          q.deleteSessionRow.run(sessionId);
+        });
+        tx();
+        return { ok: true };
+      } catch (e) {
+        return errResult(`SESSION_DELETE_FAILED: ${(e as Error).message}`);
+      }
+    },
+
+    // ---------------- Riwayat status (append-only) ----------------
+
+    insertStatusHistory(
+      sessionId: string,
+      status: SessionStatus,
+      changedAt = Date.now(),
+    ): Result<StatusHistoryEntry> {
+      try {
+        if (!sessionExists(db, sessionId)) return errResult("SESSION_NOT_FOUND");
+        q.insertHistory.run(sessionId, status, changedAt);
+        return { ok: true, data: { sessionId, status, changedAt } };
+      } catch (e) {
+        return errResult(`HISTORY_WRITE_FAILED: ${(e as Error).message}`);
+      }
+    },
+
+    getStatusHistory(sessionId: string): Result<StatusHistoryEntry[]> {
+      try {
+        if (!sessionExists(db, sessionId)) return errResult("SESSION_NOT_FOUND");
+        const rows = q.getHistory.all(sessionId) as {
+          session_id: string;
+          status: string;
+          changed_at: number;
+        }[];
+        return {
+          ok: true,
+          data: rows.map((r) => ({
+            sessionId: r.session_id,
+            status: r.status as SessionStatus,
+            changedAt: r.changed_at,
+          })),
+        };
+      } catch (e) {
+        return errResult(`HISTORY_READ_FAILED: ${(e as Error).message}`);
+      }
+    },
+  };
+}
+
+export type SessionRepo = ReturnType<typeof createSessionRepo>;

package/src/server/db/tunnel.ts

@@ -0,0 +1,124 @@
+/**
+ * Repository akun tunnel (`tunnel_account`, id = 1): hasil device flow
+ * kcgcode-rp — device token, subdomain, dan tunnel_secret frpc.
+ */
+import type { Database } from "bun:sqlite";
+
+export interface TunnelAccount {
+  email: string;
+  username: string;
+  subdomain: string;
+  deviceId: string;
+  deviceToken: string;
+  tunnelSecret: string;
+}
+
+/** Penyedia remote access: layanan bawaan KCG Code atau localhost.run. */
+export type TunnelProvider = "kcg" | "lhr";
+
+export interface TunnelSettings {
+  account: TunnelAccount | null;
+  /** Tunnel dinyalakan -> dijalankan ulang otomatis saat kcgcode start. */
+  enabled: boolean;
+  /** Penyedia yang dipilih pengguna (hanya satu yang aktif). */
+  provider: TunnelProvider;
+  /** localhost.run dinyalakan -> dijalankan ulang otomatis saat start. */
+  lhrEnabled: boolean;
+  updatedAt: number;
+}
+
+interface Row {
+  email: string | null;
+  username: string | null;
+  subdomain: string | null;
+  device_id: string | null;
+  device_token: string | null;
+  tunnel_secret: string | null;
+  enabled: number;
+  provider: string | null;
+  lhr_enabled: number | null;
+  updated_at: number;
+}
+
+function mapRow(r: Row): TunnelSettings {
+  const { email, username, subdomain, device_id, device_token, tunnel_secret } = r;
+  return {
+    account:
+      email && username && subdomain && device_id && device_token && tunnel_secret
+        ? {
+            email,
+            username,
+            subdomain,
+            deviceId: device_id,
+            deviceToken: device_token,
+            tunnelSecret: tunnel_secret,
+          }
+        : null,
+    enabled: r.enabled === 1,
+    provider: r.provider === "lhr" ? "lhr" : "kcg",
+    lhrEnabled: r.lhr_enabled === 1,
+    updatedAt: r.updated_at,
+  };
+}
+
+export function createTunnelRepo(db: Database) {
+  const q = {
+    ensure: db.query("INSERT OR IGNORE INTO tunnel_account (id, updated_at) VALUES (1, ?)"),
+    get: db.query(
+      `SELECT email, username, subdomain, device_id, device_token, tunnel_secret, enabled,
+              provider, lhr_enabled, updated_at FROM tunnel_account WHERE id = 1`,
+    ),
+    setAccount: db.query(
+      `UPDATE tunnel_account SET email = ?, username = ?, subdomain = ?, device_id = ?,
+              device_token = ?, tunnel_secret = ?, updated_at = ? WHERE id = 1`,
+    ),
+    setSecret: db.query("UPDATE tunnel_account SET tunnel_secret = ?, updated_at = ? WHERE id = 1"),
+    setEnabled: db.query("UPDATE tunnel_account SET enabled = ?, updated_at = ? WHERE id = 1"),
+    setProvider: db.query("UPDATE tunnel_account SET provider = ?, updated_at = ? WHERE id = 1"),
+    setLhrEnabled: db.query(
+      "UPDATE tunnel_account SET lhr_enabled = ?, updated_at = ? WHERE id = 1",
+    ),
+  };
+
+  function ensure(now: number): void {
+    q.ensure.run(now);
+  }
+
+  return {
+    getTunnelSettings(now: number): TunnelSettings {
+      ensure(now);
+      return mapRow(q.get.get() as Row);
+    },
+    /** Simpan akun (null = sign out). */
+    setTunnelAccount(account: TunnelAccount | null, now: number): void {
+      ensure(now);
+      q.setAccount.run(
+        account?.email ?? null,
+        account?.username ?? null,
+        account?.subdomain ?? null,
+        account?.deviceId ?? null,
+        account?.deviceToken ?? null,
+        account?.tunnelSecret ?? null,
+        now,
+      );
+    },
+    setTunnelSecret(secret: string, now: number): void {
+      ensure(now);
+      q.setSecret.run(secret, now);
+    },
+    setTunnelEnabled(enabled: boolean, now: number): void {
+      ensure(now);
+      q.setEnabled.run(enabled ? 1 : 0, now);
+    },
+    setTunnelProvider(provider: TunnelProvider, now: number): void {
+      ensure(now);
+      q.setProvider.run(provider, now);
+    },
+    setLhrEnabled(enabled: boolean, now: number): void {
+      ensure(now);
+      q.setLhrEnabled.run(enabled ? 1 : 0, now);
+    },
+  };
+}
+
+export type TunnelRepo = ReturnType<typeof createTunnelRepo>;

package/src/server/host.ts

@@ -0,0 +1,12 @@
+/**
+ * Alamat bind server. Default loopback `127.0.0.1` sehingga hanya dapat
+ * diakses dari mesin ini; ubah lewat `KCG_HOST` (atau `--host` di CLI).
+ *
+ * Catatan: server tidak memakai otentikasi. Bind ke `0.0.0.0` membuat
+ * siapa pun di jaringan yang sama dapat mengontrol agent di mesin ini.
+ */
+export const DEFAULT_HOSTNAME = "127.0.0.1";
+
+export function resolveHostname(env: Record<string, string | undefined> = process.env): string {
+  return env.KCG_HOST ?? DEFAULT_HOSTNAME;
+}

package/src/server/result.ts

@@ -0,0 +1,15 @@
+/**
+ * Primitif tipe server-only (pola kcgcode: tipe internal server dipisah
+ * dari tipe domain FE yang hidup di `src/types/`). Tidak untuk dipakai
+ * frontend.
+ */
+
+/** Hasil operasi tanpa payload (ok / gagal dengan kode error). */
+export type SimpleResult = { ok: boolean; error?: string };
+
+/**
+ * Tipe hasil diskriminasi yang dipakai seluruh layer domain:
+ * `{ ok: true; data } | { ok: false; error }` — bukan `throw`,
+ * sesuai `design.md` — Error Handling.
+ */
+export type Result<T> = { ok: true; data: T } | { ok: false; error: string };