@agentprojectcontext/apx 1.15.5 → 1.16.0

package/src/cli/terminal-chat/renderer.js

@@ -9,6 +9,7 @@ export const C = {
   altOn: "\x1b[?1049h",
   altOff: "\x1b[?1049l",
   showCursor: "\x1b[?25h",
+  hideCursor: "\x1b[?25l",
   setBgBlack: "\x1b]11;#000000\x07",
   resetBg: "\x1b]111\x07",
   bg: "\x1b[48;2;0;0;0m",
@@ -27,6 +28,27 @@ export const C = {
   noItalic: "\x1b[23m",
 };
 
+// ---------------------------------------------------------------------------
+// Output buffer — all rendering writes here; flushed once per frame.
+// This eliminates flash: the terminal sees clear+draw as a single atomic op.
+// ---------------------------------------------------------------------------
+let _buf = "";
+
+function _w(s) {
+  _buf += s;
+}
+
+function _moveTo(row, col) {
+  _buf += `\x1b[${Math.max(1, row + 1)};${Math.max(1, col + 1)}H`;
+}
+
+function _writeAt(row, col, text, width, bg = C.bg) {
+  _moveTo(row, col);
+  _buf += bg + padAnsi(text, width) + C.bg;
+}
+
+// ---------------------------------------------------------------------------
+
 export function titlecase(value) {
   const clean = String(value || "").trim();
   if (!clean) return "";
@@ -66,25 +88,11 @@ function terminalSize() {
   };
 }
 
+// Legacy direct-write moveTo used for final cursor positioning after flush
 function moveTo(row, col) {
   readline.cursorTo(process.stdout, Math.max(0, col), Math.max(0, row));
 }
 
-function writeAt(row, col, text, width, bg = C.bg) {
-  moveTo(row, col);
-  process.stdout.write(bg + padAnsi(text, width) + C.bg);
-}
-
-function clearFull() {
-  const { width, height } = terminalSize();
-  process.stdout.write(C.bg + "\x1b[2J\x1b[3J\x1b[H");
-  for (let row = 0; row < height; row++) {
-    process.stdout.write(C.bg + " ".repeat(width));
-    if (row < height - 1) process.stdout.write("\n");
-  }
-  process.stdout.write("\x1b[H" + C.bg);
-}
-
 function centerLeft(width, contentWidth) {
   return Math.max(0, Math.floor((width - contentWidth) / 2));
 }
@@ -122,7 +130,7 @@ function renderLogo(termWidth, top) {
     const line = lines[i];
     const left = centerLeft(termWidth, visible(line));
     const color = i < 2 ? C.dim : i < 4 ? C.muted : C.text;
-    writeAt(top + i, left, C.bold + color + line + C.normal, visible(line));
+    _writeAt(top + i, left, C.bold + color + line + C.normal, visible(line));
   }
 }
 
@@ -164,11 +172,11 @@ function renderPromptBlock(state, chatWidth) {
     : C.muted + C.italic + fit(placeholder, contentWidth) + C.noItalic;
   const metaLine = renderModeMeta(currentModeIdx, activeAgent, activeModel, contentWidth);
 
-  writeAt(top, left, C.primary + "┃" + C.panel + " " + " ".repeat(contentWidth), boxWidth, C.bg);
-  writeAt(top + 1, left, C.primary + "┃" + C.panel + " " + padAnsi(promptLine, contentWidth), boxWidth, C.bg);
-  writeAt(top + 2, left, C.primary + "┃" + C.panel + " " + " ".repeat(contentWidth), boxWidth, C.bg);
-  writeAt(top + 3, left, C.primary + "┃" + C.panel + " " + padAnsi(metaLine, contentWidth), boxWidth, C.bg);
-  writeAt(top + 4, left, C.primary + "╹" + C.panel + " " + " ".repeat(contentWidth), boxWidth, C.bg);
+  _writeAt(top, left, C.primary + "┃" + C.panel + " " + " ".repeat(contentWidth), boxWidth, C.bg);
+  _writeAt(top + 1, left, C.primary + "┃" + C.panel + " " + padAnsi(promptLine, contentWidth), boxWidth, C.bg);
+  _writeAt(top + 2, left, C.primary + "┃" + C.panel + " " + " ".repeat(contentWidth), boxWidth, C.bg);
+  _writeAt(top + 3, left, C.primary + "┃" + C.panel + " " + padAnsi(metaLine, contentWidth), boxWidth, C.bg);
+  _writeAt(top + 4, left, C.primary + "╹" + C.panel + " " + " ".repeat(contentWidth), boxWidth, C.bg);
 
   const hotkeys =
     C.bold + C.text + "tab" + C.normal + C.muted + " agents  " +
@@ -181,7 +189,7 @@ function renderPromptBlock(state, chatWidth) {
       : "") +
     C.bold + C.text + "enter" + C.normal + C.muted + " send";
   const hotkeyLeft = Math.max(left, left + boxWidth - visible(hotkeys));
-  writeAt(top + 5, hotkeyLeft, hotkeys, visible(hotkeys), C.bg);
+  _writeAt(top + 5, hotkeyLeft, hotkeys, visible(hotkeys), C.bg);
 
   return { row: top + 1, col: left + 2 + visible(beforeCursor) };
 }
@@ -282,7 +290,6 @@ function transcriptLines(transcript, width) {
         addLine(lines, margin + C.primary + "┃" + C.panel + " " + C.text + padAnsi(chunk, inner), C.bg);
       }
       if (item.meta) {
-        // Show QUEUED badge with distinct highlight color
         const badgeText = item.meta === "queued"
           ? C.warning + C.bold + "QUEUED" + C.normal + C.muted + "  click to send/remove"
           : C.muted + item.meta;
@@ -315,7 +322,7 @@ function transcriptLines(transcript, width) {
       const isQuestion = trace.tool === "ask_questions";
       const label = isQuestion ? C.warning + C.bold + "QUESTION" : C.muted + "TOOL";
       const name = isQuestion ? "" : C.text + trace.tool;
-      
+
       if (isQuestion && trace.args?.questions) {
         addLine(lines, "", C.bg);
         addLine(lines, margin + label + C.muted + " (…)" + C.bg, C.bg);
@@ -354,11 +361,11 @@ function renderChat(state, chatWidth, height, promptTop) {
   const slice = lines.slice(start, start + maxRows);
 
   for (let i = 0; i < slice.length && i < maxRows; i++) {
-    writeAt(i, 0, slice[i].text, chatWidth - 1, slice[i].bg);
+    _writeAt(i, 0, slice[i].text, chatWidth - 1, slice[i].bg);
   }
 
   if (offset > 0 && maxRows > 1) {
-    writeAt(0, 0, C.muted + `↑ ${offset} lines above bottom`, chatWidth - 1, C.bg);
+    _writeAt(0, 0, C.muted + `↑ ${offset} lines above bottom`, chatWidth - 1, C.bg);
   }
 }
 
@@ -369,37 +376,37 @@ function renderSidebar(state) {
   const sideWidth = Math.min(34, Math.max(28, Math.floor(width * 0.3)));
   const left = width - sideWidth;
   for (let row = 0; row < height; row++) {
-    writeAt(row, left, "", sideWidth, C.panel);
+    _writeAt(row, left, "", sideWidth, C.panel);
   }
 
   const contentWidth = sideWidth - 4;
   const totalTokens = state.usage.input + state.usage.output;
 
-  writeAt(1, left + 2, C.text + C.bold + "Sesión" + C.normal, contentWidth, C.panel);
-  writeAt(2, left + 2, C.muted + fit(state.sessionTitle || "chat local", contentWidth), contentWidth, C.panel);
-  writeAt(3, left + 2, C.muted + "agent " + C.text + state.activeAgent, contentWidth, C.panel);
-  writeAt(4, left + 2, C.muted + "app " + C.text + `APX ${state.version}`, contentWidth, C.panel);
+  _writeAt(1, left + 2, C.text + C.bold + "Sesión" + C.normal, contentWidth, C.panel);
+  _writeAt(2, left + 2, C.muted + fit(state.sessionTitle || "chat local", contentWidth), contentWidth, C.panel);
+  _writeAt(3, left + 2, C.muted + "agent " + C.text + state.activeAgent, contentWidth, C.panel);
+  _writeAt(4, left + 2, C.muted + "app " + C.text + `APX ${state.version}`, contentWidth, C.panel);
 
-  writeAt(6, left + 2, C.text + C.bold + "Modelo" + C.normal, contentWidth, C.panel);
+  _writeAt(6, left + 2, C.text + C.bold + "Modelo" + C.normal, contentWidth, C.panel);
   const modelLines = wrapText(state.activeModel || "(none)", contentWidth).slice(0, 2);
   modelLines.forEach((line, index) => {
-    writeAt(7 + index, left + 2, C.muted + line, contentWidth, C.panel);
+    _writeAt(7 + index, left + 2, C.muted + line, contentWidth, C.panel);
   });
 
-  writeAt(10, left + 2, C.text + C.bold + "Contexto" + C.normal, contentWidth, C.panel);
-  writeAt(11, left + 2, C.muted + `${totalTokens.toLocaleString()} tokens total`, contentWidth, C.panel);
-  writeAt(12, left + 2, C.muted + `${state.usage.input.toLocaleString()} in · ${state.usage.output.toLocaleString()} out`, contentWidth, C.panel);
-  writeAt(13, left + 2, C.muted + `${state.usage.percent}% usado`, contentWidth, C.panel);
-  writeAt(14, left + 2, C.muted + "$0.00 spent", contentWidth, C.panel);
+  _writeAt(10, left + 2, C.text + C.bold + "Contexto" + C.normal, contentWidth, C.panel);
+  _writeAt(11, left + 2, C.muted + `${totalTokens.toLocaleString()} tokens total`, contentWidth, C.panel);
+  _writeAt(12, left + 2, C.muted + `${state.usage.input.toLocaleString()} in · ${state.usage.output.toLocaleString()} out`, contentWidth, C.panel);
+  _writeAt(13, left + 2, C.muted + `${state.usage.percent}% usado`, contentWidth, C.panel);
+  _writeAt(14, left + 2, C.muted + "$0.00 spent", contentWidth, C.panel);
 
-  writeAt(16, left + 2, C.text + C.bold + "LSP" + C.normal, contentWidth, C.panel);
-  writeAt(17, left + 2, C.muted + "LSPs are disabled", contentWidth, C.panel);
+  _writeAt(16, left + 2, C.text + C.bold + "LSP" + C.normal, contentWidth, C.panel);
+  _writeAt(17, left + 2, C.muted + "LSPs are disabled", contentWidth, C.panel);
 
   const cwdLines = wrapText(process.cwd(), contentWidth).slice(-4);
   let row = Math.max(19, height - cwdLines.length - 4);
-  writeAt(row++, left + 2, C.text + C.bold + "Directorio" + C.normal, contentWidth, C.panel);
-  for (const line of cwdLines) writeAt(row++, left + 2, C.muted + line, contentWidth, C.panel);
-  writeAt(height - 1, left + 2, C.success + "• " + C.text + "APX" + C.muted + ` ${state.version}`, contentWidth, C.panel);
+  _writeAt(row++, left + 2, C.text + C.bold + "Directorio" + C.normal, contentWidth, C.panel);
+  for (const line of cwdLines) _writeAt(row++, left + 2, C.muted + line, contentWidth, C.panel);
+  _writeAt(height - 1, left + 2, C.success + "• " + C.text + "APX" + C.muted + ` ${state.version}`, contentWidth, C.panel);
 
   return { left, width: sideWidth };
 }
@@ -415,17 +422,17 @@ function renderPaletteOverlay(state) {
   const left = centerLeft(width, boxWidth);
   const top = Math.max(1, Math.floor((height - boxHeight) / 2));
 
-  writeAt(top, left, C.text + C.bold + " " + title + C.normal, boxWidth, C.panel);
-  writeAt(top + 1, left, C.dim + "▀".repeat(boxWidth), boxWidth, C.panel);
+  _writeAt(top, left, C.text + C.bold + " " + title + C.normal, boxWidth, C.panel);
+  _writeAt(top + 1, left, C.dim + "▀".repeat(boxWidth), boxWidth, C.panel);
   for (let i = 0; i < state.paletteOptions.length; i++) {
     const active = i === state.paletteSelection;
     const marker = active ? "›" : " ";
     const bg = active ? C.panel2 : C.panel;
     const fg = active ? C.primary + C.bold : C.text;
-    writeAt(top + 2 + i, left, fg + ` ${marker} ${state.paletteOptions[i]}` + C.normal, boxWidth, bg);
+    _writeAt(top + 2 + i, left, fg + ` ${marker} ${state.paletteOptions[i]}` + C.normal, boxWidth, bg);
   }
-  writeAt(top + 2 + state.paletteOptions.length, left, C.dim + "▄".repeat(boxWidth), boxWidth, C.panel);
-  writeAt(
+  _writeAt(top + 2 + state.paletteOptions.length, left, C.dim + "▄".repeat(boxWidth), boxWidth, C.panel);
+  _writeAt(
     top + 3 + state.paletteOptions.length,
     left,
     C.muted + "↑↓ select  " + C.text + C.bold + "enter" + C.normal + C.muted + " choose  " + C.text + C.bold + "esc" + C.normal + C.muted + " close",
@@ -444,18 +451,18 @@ function renderMsgActionsOverlay(state) {
   const left = centerLeft(width, boxWidth);
   const top = Math.max(1, Math.floor((height - boxHeight) / 2));
 
-  writeAt(top, left, C.text + C.bold + " " + title + C.normal, boxWidth, C.panel);
-  writeAt(top + 1, left, C.muted + " " + C.italic + preview + C.noItalic, boxWidth, C.panel);
-  writeAt(top + 2, left, C.dim + "▀".repeat(boxWidth), boxWidth, C.panel);
+  _writeAt(top, left, C.text + C.bold + " " + title + C.normal, boxWidth, C.panel);
+  _writeAt(top + 1, left, C.muted + " " + C.italic + preview + C.noItalic, boxWidth, C.panel);
+  _writeAt(top + 2, left, C.dim + "▀".repeat(boxWidth), boxWidth, C.panel);
   for (let i = 0; i < opts.length; i++) {
     const active = i === state.msgActionsSelection;
     const marker = active ? "›" : " ";
     const bg = active ? C.panel2 : C.panel;
     const fg = active ? C.primary + C.bold : C.text;
-    writeAt(top + 3 + i, left, fg + ` ${marker} ${opts[i]}` + C.normal, boxWidth, bg);
+    _writeAt(top + 3 + i, left, fg + ` ${marker} ${opts[i]}` + C.normal, boxWidth, bg);
   }
-  writeAt(top + 3 + opts.length, left, C.dim + "▄".repeat(boxWidth), boxWidth, C.panel);
-  writeAt(
+  _writeAt(top + 3 + opts.length, left, C.dim + "▄".repeat(boxWidth), boxWidth, C.panel);
+  _writeAt(
     top + 4 + opts.length,
     left,
     C.muted + "↑↓ select  " + C.text + C.bold + "enter" + C.normal + C.muted + " choose  " + C.text + C.bold + "esc" + C.normal + C.muted + " close",
@@ -465,7 +472,9 @@ function renderMsgActionsOverlay(state) {
 }
 
 export function renderTerminalChat(state) {
-  clearFull();
+  // Reset buffer — clear screen and home cursor in ONE atomic write (no flash)
+  _buf = C.bg + "\x1b[2J\x1b[H";
+
   const { width, height } = terminalSize();
   const sidebar = state.hasStarted ? renderSidebar(state) : null;
   const chatWidth = sidebar ? sidebar.left : width;
@@ -481,5 +490,11 @@ export function renderTerminalChat(state) {
 
   if (state.inCommandPalette) renderPaletteOverlay(state);
   if (state.inMsgActions) renderMsgActionsOverlay(state);
-  if (!state.inCommandPalette && !state.inMsgActions) moveTo(cursor.row, cursor.col);
+
+  // Position cursor in buffer before final flush
+  _buf += `\x1b[${Math.max(1, cursor.row + 1)};${Math.max(1, cursor.col + 1)}H`;
+
+  // Single atomic write — terminal renders entire frame at once, no flash
+  process.stdout.write(_buf);
+  _buf = "";
 }

package/src/cli-ts/commands/agent.ts

@@ -0,0 +1,173 @@
+import type { CommandModule, Argv, ArgumentsCamelCase } from "yargs";
+import { getHttp } from "../http.js";
+import { println, error, success, dim, highlight, table } from "../ui.js";
+
+interface GlobalArgs { project?: string }
+
+async function resolveProjectId(project?: string): Promise<string> {
+  const http = await getHttp();
+  const projects = (await http.get("/projects")) as Array<{ id: string; name: string; path: string }>;
+  if (!projects?.length) throw new Error("No projects registered. Run: apx init");
+  if (project) {
+    const match = projects.find(
+      (p) => p.id === project || p.name === project || p.path === project || p.path?.endsWith("/" + project),
+    );
+    if (!match) throw new Error(`Project not found: ${project}`);
+    return match.id;
+  }
+  return projects[0]!.id;
+}
+
+// ---------- list ----------
+
+const listCmd: CommandModule = {
+  command: "list",
+  aliases: ["ls"],
+  describe: "List agents in the current project",
+  handler: async (args: ArgumentsCamelCase<GlobalArgs>) => {
+    try {
+      const http = await getHttp();
+      const pid = await resolveProjectId(args.project as string | undefined);
+      const agents = (await http.get(`/projects/${pid}/agents`)) as Array<{
+        slug: string; role?: string; model?: string; description?: string;
+      }>;
+      if (!agents?.length) { println(dim("No agents found.")); return; }
+      table(
+        agents.map((a) => ({
+          Slug: a.slug,
+          Role: a.role || "-",
+          Model: a.model || "-",
+          Description: a.description ? a.description.slice(0, 50) : "-",
+        })),
+        ["Slug", "Role", "Model", "Description"],
+      );
+    } catch (err: unknown) {
+      error(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    }
+  },
+};
+
+// ---------- get / show ----------
+
+const getCmd: CommandModule = {
+  command: "get <slug>",
+  aliases: ["show"],
+  describe: "Show agent details and memory",
+  builder: (yargs: Argv) =>
+    yargs.positional("slug", { type: "string", demandOption: true, describe: "Agent slug" }),
+  handler: async (args: ArgumentsCamelCase<Record<string, unknown>>) => {
+    try {
+      const project = args.project as string | undefined;
+      const slug = args.slug as string;
+      const http = await getHttp();
+      const pid = await resolveProjectId(project);
+      const agent = (await http.get(`/projects/${pid}/agents/${slug}`)) as Record<string, unknown>;
+      process.stdout.write(JSON.stringify(agent, null, 2) + "\n");
+    } catch (err: unknown) {
+      error(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    }
+  },
+};
+
+// ---------- add / create ----------
+
+const addCmd: CommandModule = {
+  command: "add <slug>",
+  aliases: ["create"],
+  describe: "Create a new agent",
+  builder: (yargs: Argv) =>
+    yargs
+      .positional("slug", { type: "string", demandOption: true, describe: "Agent slug (identifier)" })
+      .option("role", { type: "string", describe: "Agent role (system prompt)" })
+      .option("model", { type: "string", describe: "LLM model (e.g. claude-sonnet-4-6)" })
+      .option("description", { alias: "d", type: "string", describe: "Short description" })
+      .option("skills", { type: "string", describe: "Comma-separated skill list" })
+      .option("language", { type: "string", describe: "Language code (e.g. en, es)" })
+      .option("tools", { type: "string", describe: "Comma-separated allowed tools" }),
+  handler: async (args: ArgumentsCamelCase<Record<string, unknown>>) => {
+    try {
+      const project = args.project as string | undefined;
+      const slug = args.slug as string;
+      const role = args.role as string | undefined;
+      const model = args.model as string | undefined;
+      const description = args.description as string | undefined;
+      const skills = args.skills as string | undefined;
+      const language = args.language as string | undefined;
+      const tools = args.tools as string | undefined;
+      const http = await getHttp();
+      const pid = await resolveProjectId(project);
+      const agent = await http.post(`/projects/${pid}/agents`, {
+        slug,
+        role,
+        model,
+        description,
+        skills: skills?.split(",").map((s) => s.trim()).filter(Boolean),
+        language,
+        tools: tools?.split(",").map((t) => t.trim()).filter(Boolean),
+      });
+      success(`Agent created: ${highlight(slug)}`);
+      process.stdout.write(JSON.stringify(agent, null, 2) + "\n");
+    } catch (err: unknown) {
+      error(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    }
+  },
+};
+
+// ---------- memory ----------
+
+const memoryCmd: CommandModule = {
+  command: "memory <slug>",
+  describe: "Read or write agent memory",
+  builder: (yargs: Argv) =>
+    yargs
+      .positional("slug", { type: "string", demandOption: true, describe: "Agent slug" })
+      .option("append", { type: "boolean", default: false, describe: "Append stdin to memory" })
+      .option("replace", { type: "boolean", default: false, describe: "Replace memory with stdin" }),
+  handler: async (args: ArgumentsCamelCase<Record<string, unknown>>) => {
+    try {
+      const project = args.project as string | undefined;
+      const slug = args.slug as string;
+      const append = args.append as boolean;
+      const replace = args.replace as boolean;
+      const http = await getHttp();
+      const pid = await resolveProjectId(project);
+      if (append || replace) {
+        const chunks: Buffer[] = [];
+        for await (const chunk of process.stdin) chunks.push(chunk as Buffer);
+        const body = Buffer.concat(chunks).toString();
+        if (append) {
+          const existing = (await http.get(`/projects/${pid}/agents/${slug}/memory`)) as { body: string };
+          await http.put(`/projects/${pid}/agents/${slug}/memory`, { body: (existing.body || "") + "\n" + body });
+        } else {
+          await http.put(`/projects/${pid}/agents/${slug}/memory`, { body });
+        }
+        success("Memory updated.");
+      } else {
+        const mem = (await http.get(`/projects/${pid}/agents/${slug}/memory`)) as { body: string };
+        process.stdout.write(mem.body || "");
+      }
+    } catch (err: unknown) {
+      error(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    }
+  },
+};
+
+// ---------- parent ----------
+
+export const agentCmd: CommandModule = {
+  command: "agent",
+  aliases: ["agents"],
+  describe: "Manage APC agents",
+  builder: (yargs: Argv) =>
+    yargs
+      .command(listCmd)
+      .command(getCmd)
+      .command(addCmd)
+      .command(memoryCmd)
+      .demandCommand(1, "Specify an agent subcommand"),
+  handler: () => {},
+};

package/src/cli-ts/commands/chat.ts

@@ -0,0 +1,119 @@
+import type { CommandModule, Argv, ArgumentsCamelCase } from "yargs";
+import { getHttp, type StreamEvent } from "../http.js";
+import { error, println, dim } from "../ui.js";
+import { createInterface } from "node:readline";
+
+interface GlobalArgs { project?: string }
+
+async function resolveProjectId(project?: string): Promise<string> {
+  const http = await getHttp();
+  const projects = (await http.get("/projects")) as Array<{ id: string; name: string; path: string }>;
+  if (!projects?.length) throw new Error("No projects registered. Run: apx init");
+  if (project) {
+    const match = projects.find(
+      (p) => p.id === project || p.name === project || p.path === project || p.path?.endsWith("/" + project),
+    );
+    if (!match) throw new Error(`Project not found: ${project}`);
+    return match.id;
+  }
+  return projects[0]!.id;
+}
+
+export const chatCmd: CommandModule = {
+  command: "chat [agent]",
+  describe: "Start an interactive multi-turn chat with an agent",
+  builder: (yargs: Argv) =>
+    yargs
+      .positional("agent", {
+        type: "string",
+        default: "default",
+        describe: "Agent slug (defaults to super-agent)",
+      })
+      .option("model", { type: "string", describe: "Override model" })
+      .option("conversation", {
+        alias: "c",
+        type: "string",
+        describe: "Continue an existing conversation ID",
+      }),
+  handler: async (
+    args: ArgumentsCamelCase<Record<string, unknown>>,
+  ) => {
+    try {
+      const project = args.project as string | undefined;
+      const agent = args.agent as string;
+      const model = args.model as string | undefined;
+      const http = await getHttp();
+      const pid = await resolveProjectId(project);
+      let conversationId = args.conversation as string | undefined;
+
+      if (!process.stdin.isTTY) {
+        // Non-interactive: read one prompt from stdin
+        const chunks: Buffer[] = [];
+        for await (const chunk of process.stdin) chunks.push(chunk as Buffer);
+        const prompt = Buffer.concat(chunks).toString().trim();
+        if (!prompt) throw new Error("No prompt provided via stdin.");
+        const result = (await http.post(`/projects/${pid}/agents/${agent}/chat`, {
+          prompt,
+          model,
+          conversation_id: conversationId,
+        })) as { conversation_id: string; text: string };
+        process.stdout.write(result.text + "\n");
+        return;
+      }
+
+      // Interactive REPL
+      println(dim(`APX Chat — agent: ${agent}  (type /exit or ctrl+c to quit)`));
+
+      const rl = createInterface({ input: process.stdin, output: process.stderr, terminal: true });
+      rl.setPrompt("\x1b[96m> \x1b[0m");
+      rl.prompt();
+
+      rl.on("line", async (line) => {
+        const text = line.trim();
+        if (!text) { rl.prompt(); return; }
+        if (text === "/exit" || text === "/quit") { rl.close(); return; }
+
+        rl.pause();
+        try {
+          // Try streaming first
+          let responded = false;
+          try {
+            const result = await http.streamPost(
+              `/projects/${pid}/super-agent/chat/stream`,
+              { prompt: text, model, previousMessages: [] },
+              (ev: StreamEvent) => {
+                if (ev.type === "chunk" && typeof ev.chunk === "string") {
+                  process.stdout.write(ev.chunk);
+                  responded = true;
+                }
+              },
+            ) as { text?: string };
+            if (!responded && result?.text) process.stdout.write(result.text);
+            process.stdout.write("\n");
+          } catch {
+            // Fall back to non-streaming agent chat
+            const result = (await http.post(`/projects/${pid}/agents/${agent}/chat`, {
+              prompt: text,
+              model,
+              conversation_id: conversationId,
+            })) as { conversation_id: string; text: string };
+            conversationId = result.conversation_id;
+            process.stdout.write(result.text + "\n");
+          }
+        } catch (err: unknown) {
+          error(err instanceof Error ? err.message : String(err));
+        }
+        rl.resume();
+        rl.prompt();
+      });
+
+      rl.on("close", () => {
+        println(dim("\nGoodbye."));
+        process.exit(0);
+      });
+    } catch (err: unknown) {
+      error(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    }
+  },
+};

package/src/cli-ts/commands/daemon.ts

@@ -0,0 +1,112 @@
+import type { CommandModule, Argv, ArgumentsCamelCase } from "yargs";
+import { getHttp } from "../http.js";
+import { println, error, success, dim } from "../ui.js";
+import { spawn } from "node:child_process";
+
+// ---------- status ----------
+
+const statusCmd: CommandModule = {
+  command: "status",
+  describe: "Show daemon status",
+  handler: async () => {
+    try {
+      const http = await getHttp();
+      const health = (await http.get("/health")) as {
+        status: string; version?: string; uptime_s?: number;
+      };
+      success(`Daemon running  version=${health.version ?? "?"}  uptime=${health.uptime_s ?? "?"}s`);
+    } catch {
+      error("Daemon is not running.");
+      process.exit(1);
+    }
+  },
+};
+
+// ---------- start ----------
+
+const startCmd: CommandModule = {
+  command: "start",
+  describe: "Start the APX daemon in the background",
+  handler: async () => {
+    try {
+      const http = await getHttp();
+      await http.get("/health");
+      println(dim("Daemon is already running."));
+    } catch {
+      const daemon = spawn("apx-daemon", [], {
+        detached: true,
+        stdio: "ignore",
+      });
+      daemon.unref();
+      success("Daemon started.");
+    }
+  },
+};
+
+// ---------- stop ----------
+
+const stopCmd: CommandModule = {
+  command: "stop",
+  describe: "Gracefully stop the APX daemon",
+  handler: async () => {
+    try {
+      const http = await getHttp();
+      await http.post("/admin/shutdown", {});
+      success("Daemon stopped.");
+    } catch (err: unknown) {
+      error(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    }
+  },
+};
+
+// ---------- logs ----------
+
+const logsCmd: CommandModule = {
+  command: "logs",
+  describe: "Stream daemon logs",
+  builder: (yargs: Argv) =>
+    yargs.option("tail", {
+      alias: "n",
+      type: "number",
+      default: 50,
+      describe: "Number of lines to show",
+    }),
+  handler: async (args: ArgumentsCamelCase<Record<string, unknown>>) => {
+    try {
+      const tail = (args.tail as number) ?? 50;
+      const { homedir } = await import("node:os");
+      const { createReadStream } = await import("node:fs");
+      const { createInterface } = await import("node:readline");
+      const logPath = `${homedir()}/.apx/daemon.log`;
+      try {
+        const rl = createInterface({ input: createReadStream(logPath), crlfDelay: Infinity });
+        const lines: string[] = [];
+        for await (const line of rl) lines.push(line);
+        const tailLines = lines.slice(-tail);
+        tailLines.forEach((l) => println(l));
+      } catch {
+        error(`Log file not found: ${logPath}`);
+        process.exit(1);
+      }
+    } catch (err: unknown) {
+      error(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    }
+  },
+};
+
+// ---------- parent ----------
+
+export const daemonCmd: CommandModule = {
+  command: "daemon",
+  describe: "Manage the APX background daemon",
+  builder: (yargs: Argv) =>
+    yargs
+      .command(statusCmd)
+      .command(startCmd)
+      .command(stopCmd)
+      .command(logsCmd)
+      .demandCommand(1, "Specify a daemon subcommand"),
+  handler: () => {},
+};