@kal-elsam/kairo-runtime 0.16.0 → 0.17.0

package/src/global/conversation/session-store.js

@@ -0,0 +1,75 @@
+// Persists KairoSession — right now just the project's current WorkMode
+// ("ask" | "plan" | "agent") plus identity/timestamps — under the same
+// global `~/.harness/sessions/<projectKey>/` tree transcript-store.js
+// already uses (see that file's header for why: matches Claude Code/Codex/
+// OpenCode's own convention, never inside the project's own working
+// directory). Deliberately a SEPARATE file from transcript.json rather than
+// merging the two: messages are already durably persisted there, and this
+// file only needs to exist/change when the mode itself changes — keeping
+// them separate means switching modes never needs to read-modify-write the
+// (potentially large) transcript, and a mode read never needs to parse it.
+
+import { mkdir, readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { harnessHomePaths } from "../paths.js";
+import { projectKeyForPath } from "../next/project-key.js";
+import { writeAtomicJson } from "../runtime/write-atomic-json.js";
+
+export const SESSION_SCHEMA = "kairo.session/v1";
+export const WORK_MODES = ["ask", "plan", "agent"];
+const DEFAULT_MODE = "ask";
+
+function sessionPath(homeDir, projectRoot) {
+  const { sessionsDir } = harnessHomePaths(homeDir);
+  return join(sessionsDir, projectKeyForPath(projectRoot), "session.json");
+}
+
+function freshSession(projectRoot) {
+  const now = new Date().toISOString();
+  return { schema: SESSION_SCHEMA, id: projectKeyForPath(projectRoot), mode: DEFAULT_MODE, createdAt: now, updatedAt: now };
+}
+
+/**
+ * Reads the persisted KairoSession for a project. Fails closed to a fresh
+ * default session (mode "ask") on a missing or malformed file — this is
+ * also how every session that existed before WorkMode was introduced
+ * "migrates": it simply reads as ASK, the safest, strictly read-only
+ * default, the first time it's read after this shipped.
+ * @param {string} homeDir
+ * @param {string} projectRoot
+ * @returns {Promise<{schema: string, id: string, mode: "ask"|"plan"|"agent", createdAt: string, updatedAt: string}>}
+ */
+export async function readSession(homeDir, projectRoot, deps = {}) {
+  const read = deps.readFile ?? readFile;
+  try {
+    const raw = await read(sessionPath(homeDir, projectRoot), "utf8");
+    const doc = JSON.parse(raw);
+    if (doc?.schema !== SESSION_SCHEMA || typeof doc.id !== "string" || !WORK_MODES.includes(doc.mode)) {
+      return freshSession(projectRoot);
+    }
+    return doc;
+  } catch {
+    return freshSession(projectRoot);
+  }
+}
+
+/**
+ * Persists a new WorkMode for this project's session — pure local state,
+ * never provider I/O, so switching modes (Shift+Tab, `/plan`) stays
+ * instant. Read-modify-write against the existing session so `id`/
+ * `createdAt` survive a mode change untouched.
+ * @param {string} homeDir
+ * @param {string} projectRoot
+ * @param {"ask"|"plan"|"agent"} mode
+ */
+export async function writeSessionMode(homeDir, projectRoot, mode, deps = {}) {
+  if (!WORK_MODES.includes(mode)) throw new Error(`Unknown work mode "${mode}"`);
+  const mkdirImpl = deps.mkdir ?? mkdir;
+  const writeJson = deps.writeAtomicJson ?? writeAtomicJson;
+  const existing = await readSession(homeDir, projectRoot, deps);
+  const path = sessionPath(homeDir, projectRoot);
+  const doc = { ...existing, schema: SESSION_SCHEMA, mode, updatedAt: new Date().toISOString() };
+  await mkdirImpl(dirname(path), { recursive: true });
+  await writeJson(path, doc);
+  return doc;
+}

package/src/global/conversation/transcript-store.js

@@ -0,0 +1,79 @@
+// Persists the `kairo start` chat transcript so it survives a restart — the
+// whole reason a chat CLI is useful is that you don't lose the conversation.
+//
+// This lives under the global `~/.harness/sessions/<projectKey>/` tree, the
+// same home Kairo already uses for run history and work snapshots — NOT
+// inside the project's own working directory. Verified against Claude Code
+// (`~/.claude/projects/`), Codex (`~/.codex/sessions/`), and OpenCode
+// (`~/.local/share/opencode/storage`): none of them store session history
+// inside the repo itself, all three key it by project path under the user's
+// home. Writing this into the repo would risk it landing in git and would
+// collide across separate clones of the same project.
+
+import { mkdir, readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { harnessHomePaths } from "../paths.js";
+import { projectKeyForPath } from "../next/project-key.js";
+import { writeAtomicJson } from "../runtime/write-atomic-json.js";
+
+export const TRANSCRIPT_SCHEMA = "kairo.transcript/v1";
+
+// A CLI session's transcript isn't meant to grow forever; bound it so the
+// file (and every future read-modify-write) stays cheap, while still
+// keeping far more real history than the old fixed on-screen cap of 8.
+const MAX_STORED_ENTRIES = 500;
+
+function transcriptPath(homeDir, projectRoot) {
+  const { sessionsDir } = harnessHomePaths(homeDir);
+  return join(sessionsDir, projectKeyForPath(projectRoot), "transcript.json");
+}
+
+/**
+ * Reads the persisted transcript for a project. Fails closed to an empty
+ * list on a missing or malformed file — a corrupt history file must never
+ * block the chat from starting.
+ * @param {string} homeDir
+ * @param {string} projectRoot
+ * @returns {Promise<Array<{role: "user"|"kairo", text: string, at: string}>>}
+ */
+export async function readTranscript(homeDir, projectRoot, deps = {}) {
+  const read = deps.readFile ?? readFile;
+  try {
+    const raw = await read(transcriptPath(homeDir, projectRoot), "utf8");
+    const doc = JSON.parse(raw);
+    if (doc?.schema !== TRANSCRIPT_SCHEMA || !Array.isArray(doc.entries)) return [];
+    return doc.entries.filter((entry) => entry && typeof entry.text === "string"
+      && (entry.role === "user" || entry.role === "kairo"));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Appends one entry and persists the whole (bounded) transcript. Read-
+ * modify-write is fine here: this is interactive human typing speed, not a
+ * high-frequency log. A write failure never throws into the chat flow —
+ * the caller decides whether/how to surface it.
+ * @param {string} homeDir
+ * @param {string} projectRoot
+ * @param {{role: "user"|"kairo", text: string}} entry
+ */
+export async function appendTranscriptEntry(homeDir, projectRoot, entry, deps = {}) {
+  const mkdirImpl = deps.mkdir ?? mkdir;
+  const writeJson = deps.writeAtomicJson ?? writeAtomicJson;
+  const path = transcriptPath(homeDir, projectRoot);
+  const existing = await readTranscript(homeDir, projectRoot, deps);
+  const entries = [...existing, { role: entry.role, text: entry.text, at: new Date().toISOString() }]
+    .slice(-MAX_STORED_ENTRIES);
+  await mkdirImpl(dirname(path), { recursive: true });
+  await writeJson(path, { schema: TRANSCRIPT_SCHEMA, entries });
+}
+
+/** Persists an empty transcript — used by `/clear`, so a cleared chat stays cleared across a restart. */
+export async function clearTranscript(homeDir, projectRoot, deps = {}) {
+  const mkdirImpl = deps.mkdir ?? mkdir;
+  const writeJson = deps.writeAtomicJson ?? writeAtomicJson;
+  const path = transcriptPath(homeDir, projectRoot);
+  await mkdirImpl(dirname(path), { recursive: true });
+  await writeJson(path, { schema: TRANSCRIPT_SCHEMA, entries: [] });
+}

package/src/global/conversation/ui.js

@@ -0,0 +1,195 @@
+import { createServer } from "node:http";
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { createConversationService } from "./service.js";
+
+const MAX_BODY_BYTES = 64 * 1024;
+
+function equalToken(actual, expected) {
+  const left = Buffer.from(String(actual ?? ""));
+  const right = Buffer.from(String(expected));
+  return left.length === right.length && timingSafeEqual(left, right);
+}
+
+function sendJson(response, status, value) {
+  const body = JSON.stringify(value);
+  response.writeHead(status, {
+    "content-type": "application/json; charset=utf-8",
+    "content-length": Buffer.byteLength(body),
+    "cache-control": "no-store",
+    "x-content-type-options": "nosniff"
+  });
+  response.end(body);
+}
+
+function readJson(request) {
+  return new Promise((resolve, reject) => {
+    let body = "";
+    request.setEncoding("utf8");
+    request.on("data", (chunk) => {
+      body += chunk;
+      if (Buffer.byteLength(body) > MAX_BODY_BYTES) {
+        const error = new Error("Request body too large.");
+        error.statusCode = 413;
+        reject(error);
+        request.destroy();
+      }
+    });
+    request.on("end", () => {
+      try { resolve(body ? JSON.parse(body) : {}); }
+      catch { const error = new Error("Invalid JSON body."); error.statusCode = 400; reject(error); }
+    });
+    request.on("error", reject);
+  });
+}
+
+export function renderConversationHtml(token) {
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src 'unsafe-inline'; script-src 'unsafe-inline'; connect-src 'self'">
+<title>Kairo Conversation</title><style>
+:root{color-scheme:dark;font:15px system-ui;background:#111;color:#eee}body{max-width:900px;margin:0 auto;padding:24px}textarea{width:100%;min-height:90px;background:#1d1d1d;color:#fff;border:1px solid #555;padding:10px;box-sizing:border-box}button{margin:8px 8px 0 0;padding:8px 12px}.card{border:1px solid #444;border-radius:8px;padding:14px;margin:12px 0}.muted{color:#aaa}.error{color:#ff9b9b}.ok{color:#9ee6a8}pre{white-space:pre-wrap;background:#181818;padding:12px}</style></head><body>
+<h1>Kairo Conversation</h1><p class="muted">Approval and execution are separate. Execution starts only after explicit confirmation.</p>
+<form id="architect"><label for="task">Architecture task</label><textarea id="task" required></textarea><br><button>Create plan with Codex</button></form>
+<p id="status" class="muted"></p><section id="timeline"></section>
+<script>const TOKEN=${JSON.stringify(token)};
+const statusEl=document.getElementById('status'), timeline=document.getElementById('timeline');
+let latestSnapshot={timeline:[]};
+async function api(path,options={}){const response=await fetch(path,{...options,headers:{authorization:'Bearer '+TOKEN,'content-type':'application/json',...(options.headers||{})}});const data=await response.json();if(!response.ok)throw new Error(data.error||'Request failed');return data}
+function activeTeamRoles(){const strategy=latestSnapshot.projectStrategy;if(!strategy||strategy.status!=='active'||!Array.isArray(strategy.projectTeam))return[];return strategy.projectTeam.map(e=>e.role)}
+async function handleExecute(id){
+  const roles=activeTeamRoles();
+  if(roles.length===0){statusEl.textContent='No active project team — run /project (or the conversation CLI) to analyze and approve one before executing.';statusEl.className='error';return}
+  const role=window.prompt('Which role is this task for?\\n'+roles.join(', '),roles[0]);
+  if(!role||!roles.includes(role)){statusEl.textContent='Execution cancelled.';return}
+  statusEl.textContent='Asking PROJECT TEAM who should execute this…';
+  let decision;
+  try{decision=await api('/api/plans/'+encodeURIComponent(id)+'/preview?role='+encodeURIComponent(role))}
+  catch(e){statusEl.textContent=e.message;statusEl.className='error';return}
+  if(!decision.confirmationTarget){statusEl.textContent=decision.why||'Cannot auto-execute this plan.';statusEl.className='error';return}
+  const confirmText=decision.decision==='ROUTED'
+    ? ('Execute "'+id+'" with '+decision.provider+' · '+(decision.model||'default')+'? '+decision.why)
+    : ('Assigned model unavailable for '+decision.role+'. Suggested alternative: '+(decision.suggestedAlternative&&decision.suggestedAlternative.provider)+' · '+(decision.suggestedAlternative&&decision.suggestedAlternative.model&&(decision.suggestedAlternative.model.displayName||decision.suggestedAlternative.model.modelId))+'. Confirm this alternative?');
+  if(!window.confirm(confirmText)){statusEl.textContent='Execution cancelled.';return}
+  statusEl.textContent='Executing…';
+  await api('/api/plans/'+encodeURIComponent(id)+'/execute',{method:'POST',body:JSON.stringify({confirmationTarget:decision.confirmationTarget})});
+}
+function button(label,action,id){const b=document.createElement('button');b.textContent=label;b.onclick=async()=>{
+  try{
+    if(action==='execute'){await handleExecute(id);await refresh();return}
+    statusEl.textContent=label+'…';
+    const options=action==='show'?{}:{method:'POST',body:'{}'};
+    const result=await api('/api/plans/'+encodeURIComponent(id)+'/'+action,options);
+    if(action==='show'){const pre=document.createElement('pre');pre.textContent=result.planMarkdown||'No plan artifact yet.';b.parentElement.appendChild(pre)}
+    await refresh()
+  }catch(e){statusEl.textContent=e.message;statusEl.className='error'}
+};return b}
+async function refresh(){const data=await api('/api/snapshot');latestSnapshot=data;timeline.replaceChildren();for(const plan of data.timeline){const card=document.createElement('article');card.className='card';const title=document.createElement('strong');title.textContent=plan.taskId+' · '+plan.state;card.append(title,document.createElement('br'));const note=document.createElement('span');note.className='muted';note.textContent=plan.execution.message;card.append(note,document.createElement('br'));if(plan.planReady)card.append(button('Open plan','show',plan.taskId));if(plan.state==='awaiting_approval'){card.append(button('Approve','approve',plan.taskId),button('Reject','reject',plan.taskId))}if(plan.state==='approved'&&plan.execution.state==='not_started')card.append(button('Execute','execute',plan.taskId));if(plan.execution.active)card.append(button('Cancel run','cancel',plan.taskId));timeline.append(card)}statusEl.textContent='';statusEl.className='muted'}
+document.getElementById('architect').onsubmit=async(event)=>{event.preventDefault();const task=document.getElementById('task').value.trim();if(!task)return;statusEl.textContent='Codex is planning in read-only mode…';try{await api('/api/architect',{method:'POST',body:JSON.stringify({task})});document.getElementById('task').value='';await refresh()}catch(e){statusEl.textContent=e.message;statusEl.className='error'}};refresh().catch(e=>{statusEl.textContent=e.message;statusEl.className='error'});setInterval(()=>refresh().catch(()=>{}),2000);</script></body></html>`;
+}
+
+function requestAllowed(request, port, token, url) {
+  const allowedHosts = new Set([`127.0.0.1:${port}`, `localhost:${port}`]);
+  if (!allowedHosts.has(request.headers.host)) return { ok: false, status: 403, error: "Invalid Host header." };
+  const allowedOrigins = new Set([`http://127.0.0.1:${port}`, `http://localhost:${port}`]);
+  if (request.headers.origin && !allowedOrigins.has(request.headers.origin)) {
+    return { ok: false, status: 403, error: "Invalid Origin header." };
+  }
+  const bearer = String(request.headers.authorization ?? "").replace(/^Bearer\s+/i, "");
+  const supplied = url.pathname === "/" ? url.searchParams.get("token") : bearer;
+  if (!equalToken(supplied, token)) return { ok: false, status: 401, error: "Invalid UI token." };
+  return { ok: true };
+}
+
+const GET_PLAN_ACTIONS = new Set(["show", "preview"]);
+
+function routeFor(method, pathname) {
+  if (method === "GET" && pathname === "/") return { action: "html" };
+  if (method === "GET" && pathname === "/api/snapshot") return { action: "snapshot" };
+  if (method === "POST" && pathname === "/api/architect") return { action: "architect" };
+  const match = pathname.match(/^\/api\/plans\/([a-z0-9][a-z0-9-]{0,95})\/(show|preview|approve|reject|execute|cancel)$/);
+  if (!match) return null;
+  if (GET_PLAN_ACTIONS.has(match[2]) !== (method === "GET")) return null;
+  return { action: match[2], taskId: match[1] };
+}
+
+export async function startLocalConversationUi({ cwd, port = 0, token, service } = {}) {
+  const authToken = token ?? randomBytes(24).toString("hex");
+  const app = service ?? createConversationService();
+  let boundPort = port;
+  const server = createServer(async (request, response) => {
+    const url = new URL(request.url ?? "/", `http://127.0.0.1:${boundPort}`);
+    const gate = requestAllowed(request, boundPort, authToken, url);
+    if (!gate.ok) return sendJson(response, gate.status, { error: gate.error });
+    const route = routeFor(request.method, url.pathname);
+    if (!route) return sendJson(response, 404, { error: "Unknown endpoint." });
+    try {
+      if (route.action === "html") {
+        const html = renderConversationHtml(authToken);
+        response.writeHead(200, {
+          "content-type": "text/html; charset=utf-8", "cache-control": "no-store",
+          "x-frame-options": "DENY", "x-content-type-options": "nosniff"
+        });
+        response.end(html);
+      } else if (route.action === "snapshot") sendJson(response, 200, await app.snapshot({ cwd }));
+      else if (route.action === "architect") {
+        const body = await readJson(request);
+        if (typeof body.task !== "string" || !body.task.trim() || body.task.length > 20_000) {
+          return sendJson(response, 400, { error: "Task must be a non-empty string up to 20000 characters." });
+        }
+        sendJson(response, 200, await app.submitArchitecture({ cwd, task: body.task, model: body.model ?? null }));
+      } else if (route.action === "show") sendJson(response, 200, await app.showPlan({ cwd, taskId: route.taskId }));
+      else if (route.action === "preview") {
+        // A real ProjectExecutionPreview — read-only, same as
+        // service.planExecution() itself: never reserves quota or starts
+        // a run. The browser fetches this before ever asking to confirm.
+        // PROJECT TEAM is the sole authority for execution — role is
+        // required; an omitted/empty one surfaces service.js's own clear
+        // "requires an explicit role" error as a 400, never silently
+        // falls back to guessing from the task's text.
+        const role = url.searchParams.get("role");
+        sendJson(response, 200, await app.planExecution({ cwd, taskId: route.taskId, role }));
+      } else if (route.action === "approve" || route.action === "reject") {
+        sendJson(response, 200, await app.decidePlan({
+          cwd, taskId: route.taskId, decision: route.action === "approve" ? "approved" : "rejected"
+        }));
+      } else if (route.action === "execute") {
+        // The browser only ever sends a `confirmationTarget` it just
+        // fetched from /preview — never a free-form provider/model choice.
+        // executePlan revalidates that target against a freshly recomputed
+        // route before reserving anything, and now requires it outright
+        // (see service.js's own doc) — a missing or falsy confirmationTarget
+        // (e.g. a caller hand-crafting the request, or forwarding a
+        // blocked preview's null target) surfaces service.js's own clear
+        // error as a 400, never silently substitutes anything.
+        const body = await readJson(request);
+        sendJson(response, 202, await app.executePlan({ cwd, taskId: route.taskId, confirmationTarget: body?.confirmationTarget }));
+      } else sendJson(response, 200, await app.cancelExecution({ cwd, taskId: route.taskId }));
+    } catch (error) {
+      if (!response.headersSent) sendJson(response, error.statusCode ?? 400, { error: error.message ?? String(error) });
+    }
+  });
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(port, "127.0.0.1", resolve);
+  });
+  boundPort = server.address().port;
+  return {
+    server,
+    token: authToken,
+    port: boundPort,
+    url: `http://127.0.0.1:${boundPort}/?token=${authToken}`,
+    close: () => new Promise((resolve, reject) => server.close((error) => error ? reject(error) : resolve()))
+  };
+}
+
+export async function runUiCli(options, deps = {}) {
+  const ui = await (deps.start ?? startLocalConversationUi)({ cwd: options.cwd, port: options.port ?? 0 });
+  console.log(`Kairo UI: ${ui.url}`);
+  if (deps.waitForShutdown) return deps.waitForShutdown(ui);
+  await new Promise((resolve) => {
+    const stop = () => { process.off("SIGINT", stop); process.off("SIGTERM", stop); resolve(); };
+    process.on("SIGINT", stop);
+    process.on("SIGTERM", stop);
+  });
+  await ui.close();
+}