@ayoxx/kundex 0.1.9 → 2.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ayoxx/kundex",
-  "version": "0.1.9",
-  "description": "Kundex — a terminal-based AI coding agent CLI and SDK, powered by Groq.",
+  "version": "2.0.0",
+  "description": "Kundex — a terminal-based AI coding agent CLI and SDK, powered by Mistral and Heavstal AI.",
   "type": "module",
   "bin": {
     "kundex": "./bin/kundex.mjs"

package/src/config.ts

@@ -33,8 +33,24 @@ export function saveConfig(config: Partial<KundexConfig>): KundexConfig {
   return merged;
 }
 
-export const KUNDEX_BASE_URL = "https://kundex-api.onrender.com";
+export const KUNDEX_BASE_URL = "https://api.kundex.com.ng";
 
-export function resolveBaseUrl(_config: KundexConfig): string | null {
-  return KUNDEX_BASE_URL;
+/**
+ * Resolves the base URL to use for API calls.
+ *
+ * Priority:
+ *   1. KUNDEX_BASE_URL environment variable (useful for local dev)
+ *   2. Stored baseUrl from config (~/.kundex/config.json)
+ *   3. Hard-coded default: https://api.kundex.com.ng
+ *
+ * Previously, this function ignored the stored baseUrl completely.
+ * That made `kundex config set baseUrl <url>` a no-op, which broke
+ * local development and self-hosted deployments.
+ */
+export function resolveBaseUrl(config: KundexConfig): string | null {
+  return (
+    process.env.KUNDEX_BASE_URL?.trim() ||
+    config.baseUrl?.trim() ||
+    KUNDEX_BASE_URL
+  );
 }

package/src/index.ts

@@ -1,41 +1,340 @@
-import { loadConfig, resolveBaseUrl } from "./config";
+import { loadConfig, saveConfig, resolveBaseUrl } from "./config";
 import { runLogin } from "./login";
 import { runRepl } from "./repl";
+import { Kundex } from "./sdk";
+
+const VERSION = "1.0.0";
+
+// ─── Help text ────────────────────────────────────────────────────────────────
+
+const HELP = `
+\x1b[1m\x1b[36mkundex\x1b[0m — AI coding agent CLI  v${VERSION}
+
+\x1b[1mUsage:\x1b[0m
+  kundex [command] [options]
+
+\x1b[1mAuthentication:\x1b[0m
+  login                            Save your Kundex API key
+  logout                           Remove saved credentials
+
+\x1b[1mAgent:\x1b[0m
+  (no command)                     Start the interactive AI coding agent REPL
+  run <message>                    Run a single agent turn (non-interactive)
+
+\x1b[1mModels:\x1b[0m
+  models                           List available models
+
+\x1b[1mConfiguration:\x1b[0m
+  config show                      Show current configuration
+  config set <key> <val>           Set a config value
+    Keys: model, baseUrl
+
+\x1b[1mOther:\x1b[0m
+  help, --help, -h                 Show this help
+  version, --version, -v           Show version
+
+\x1b[1mExamples:\x1b[0m
+  kundex login
+  kundex                                       # start REPL in current directory
+  kundex run "Fix all TypeScript errors"
+  kundex models
+  kundex config set model codestral-latest
+  kundex config set baseUrl https://api.kundex.com.ng
+`.trim();
+
+// ─── Colour helpers ───────────────────────────────────────────────────────────
+
+const c = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  cyan: "\x1b[36m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  red: "\x1b[31m",
+};
+
+function ok(msg: string) { console.log(`${c.green}${c.bold}  ✓${c.reset} ${msg}`); }
+function errMsg(msg: string) { console.error(`${c.red}${c.bold}  ✗${c.reset} ${msg}`); }
+function dim(msg: string) { console.log(`${c.dim}  ${msg}${c.reset}`); }
+function header(msg: string) { console.log(`\n${c.bold}${c.cyan}  ${msg}${c.reset}`); }
+
+// ─── Commands ─────────────────────────────────────────────────────────────────
+
+const PROVIDER_DISPLAY: Record<string, string> = {
+  heavstal: "Heavstal",
+  mistral:  "Mistral",
+};
+
+async function cmdModels(config: ReturnType<typeof loadConfig>, baseUrl: string) {
+  const kundex = new Kundex({ apiKey: config.apiKey!, baseUrl });
+  header("Available models");
+  try {
+    const models = await kundex.models.list();
+    if (!models.length) { dim("No models found."); return; }
+    const nameWidth     = Math.max(...models.map((m) => m.name.length), 4);
+    const idWidth       = Math.max(...models.map((m) => m.id.length), 2);
+    const providerWidth = Math.max(...models.map((m) => (m.provider?.length ?? 0)), 8);
+    console.log(`\n  ${c.dim}${"Name".padEnd(nameWidth)}  ${"ID".padEnd(idWidth)}  ${"Provider".padEnd(providerWidth)}  Context${c.reset}`);
+    console.log(`  ${c.dim}${"─".repeat(nameWidth + idWidth + providerWidth + 18)}${c.reset}`);
+
+    const grouped: Record<string, typeof models> = {};
+    const order: string[] = [];
+    for (const m of models) {
+      const p = m.provider ?? "other";
+      if (!grouped[p]) { grouped[p] = []; order.push(p); }
+      grouped[p].push(m);
+    }
+
+    for (const provider of order) {
+      for (const m of grouped[provider]) {
+        const ctx = m.contextWindow >= 1_000_000
+          ? `${(m.contextWindow / 1_000_000).toFixed(1)}M`
+          : m.contextWindow >= 1000
+            ? `${(m.contextWindow / 1000).toFixed(0)}k`
+            : String(m.contextWindow);
+        const providerLabel = (PROVIDER_DISPLAY[m.provider ?? ""] ?? m.provider ?? "").padEnd(providerWidth);
+        console.log(
+          `  ${c.bold}${m.name.padEnd(nameWidth)}${c.reset}` +
+          `  ${c.dim}${m.id.padEnd(idWidth)}${c.reset}` +
+          `  ${c.cyan}${providerLabel}${c.reset}` +
+          `  ${c.dim}${ctx}${c.reset}`,
+        );
+      }
+    }
+    console.log();
+  } catch (e) {
+    errMsg(`Failed to list models: ${(e as Error).message}`);
+    process.exitCode = 1;
+  }
+}
+
+// ── Run (single-turn non-interactive) ─────────────────────────────────────────
+
+async function cmdRun(
+  config: ReturnType<typeof loadConfig>,
+  baseUrl: string,
+  message: string,
+  args: string[],
+) {
+  if (!message) {
+    errMsg("Usage: kundex run <message>");
+    process.exitCode = 1;
+    return;
+  }
+
+  let model = config.defaultModel ?? "codestral-latest";
+  let cwd = process.cwd();
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--model" && args[i + 1]) model = args[++i];
+    else if (args[i] === "--cwd" && args[i + 1]) cwd = args[++i];
+  }
+
+  const kundex = new Kundex({ apiKey: config.apiKey!, baseUrl });
+
+  try {
+    const session = await kundex.agent.createSession({ cwd, model });
+    const sessionId = session.id;
+
+    process.stdout.write(`\n`);
+    const { executeToolCall } = await import("./tools");
+
+    let turn = await kundex.agent.streamMessage(
+      { sessionId, message },
+      (delta) => process.stdout.write(delta),
+    );
+
+    while (!turn.done && turn.toolCalls && turn.toolCalls.length > 0) {
+      for (const call of turn.toolCalls) {
+        const { result, isError } = await executeToolCall(cwd, call);
+        turn = await kundex.agent.submitToolResult(
+          { sessionId, toolCallId: call.id, result, isError },
+          (delta) => process.stdout.write(delta),
+        );
+      }
+    }
+
+    process.stdout.write("\n");
+  } catch (e) {
+    errMsg(`Agent error: ${(e as Error).message}`);
+    process.exitCode = 1;
+  }
+}
+
+// ─── Config commands ──────────────────────────────────────────────────────────
+
+function cmdConfigShow(config: ReturnType<typeof loadConfig>, baseUrl: string) {
+  header("Current configuration");
+  console.log();
+  const rows = [
+    ["API key",  config.apiKey ? `${config.apiKey.slice(0, 8)}…` : "(not set)"],
+    ["Base URL", baseUrl],
+    ["Model",    config.defaultModel ?? "(default)"],
+  ];
+  for (const [k, v] of rows) {
+    console.log(`  ${c.dim}${k.padEnd(12)}${c.reset}  ${c.bold}${v}${c.reset}`);
+  }
+  console.log();
+}
+
+function cmdConfigSet(key: string, value: string) {
+  const allowed = ["model", "baseUrl"];
+  if (!allowed.includes(key)) {
+    errMsg(`Unknown config key "${key}". Allowed keys: ${allowed.join(", ")}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const map: Record<string, keyof ReturnType<typeof loadConfig>> = {
+    model: "defaultModel",
+    baseUrl: "baseUrl",
+  };
+
+  saveConfig({ [map[key]]: value });
+  ok(`Set ${key} = ${value}`);
+}
+
+function cmdLogout() {
+  saveConfig({ apiKey: null, baseUrl: null, defaultModel: null });
+  ok("Logged out. Run `kundex login` to authenticate again.");
+}
+
+// ─── API key prompt ──────────────────────────────────────────────────────────
+
+async function promptForApiKey(): Promise<string | null> {
+  const readline = await import("node:readline/promises");
+  const rl = readline.default.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    console.log(`\n${c.bold}${c.cyan}  Welcome to Kundex!${c.reset}`);
+    console.log(`${c.dim}  You need an API key to use the agent.${c.reset}`);
+    console.log(`${c.dim}  Get one at: https://kundex.com.ng/dashboard/api-keys${c.reset}\n`);
+    const answer = await rl.question(`${c.bold}  Enter your API key: ${c.reset}`);
+    const apiKey = answer.trim();
+    if (!apiKey) {
+      console.log(`${c.dim}  No key entered. Run \`kundex login\` later to set one.${c.reset}\n`);
+      return null;
+    }
+    saveConfig({ apiKey });
+    ok("API key saved.");
+    return apiKey;
+  } finally {
+    rl.close();
+  }
+}
+
+// ─── Main ─────────────────────────────────────────────────────────────────────
 
 async function main(): Promise<void> {
-  const [, , command] = process.argv;
+  const args = process.argv.slice(2);
+  const [command, sub, ...rest] = args;
 
-  if (command === "login") {
-    await runLogin();
+  // Version
+  if (command === "version" || command === "--version" || command === "-v") {
+    console.log(`kundex v${VERSION}`);
     return;
   }
 
+  // Help
   if (command === "help" || command === "--help" || command === "-h") {
-    console.log(
-      [
-        "kundeX — terminal AI coding agent.",
-        "",
-        "Usage:",
-        "  kundex login   Save your API key and API base URL",
-        "  kundex         Start the agent REPL in the current directory",
-      ].join("\n"),
-    );
+    console.log(HELP);
     return;
   }
 
-  const config = loadConfig();
+  // No command — start REPL, prompting for API key if needed
+  if (!command) {
+    let config = loadConfig();
+    const baseUrl = resolveBaseUrl(config);
+
+    if (!config.apiKey) {
+      const key = await promptForApiKey();
+      if (!key) {
+        console.log(HELP);
+        return;
+      }
+      config = loadConfig();
+    }
+
+    if (config.apiKey && baseUrl) {
+      await runRepl(config, config.apiKey, baseUrl);
+      return;
+    }
+    console.log(HELP);
+    return;
+  }
+
+  // Login / logout
+  if (command === "login") {
+    await runLogin();
+    return;
+  }
+  if (command === "logout") {
+    cmdLogout();
+    return;
+  }
+
+  // Load config — required for all remaining commands
+  let config = loadConfig();
   const baseUrl = resolveBaseUrl(config);
 
   if (!config.apiKey || !baseUrl) {
-    console.error('Not logged in. Run "kundex login" first.');
-    process.exitCode = 1;
+    if (!config.apiKey) {
+      const key = await promptForApiKey();
+      if (!key) {
+        process.exitCode = 1;
+        return;
+      }
+      config = loadConfig();
+    }
+    if (!config.apiKey || !resolveBaseUrl(config)) {
+      errMsg('Not logged in. Run "kundex login" first.');
+      process.exitCode = 1;
+      return;
+    }
+  }
+
+  // Models
+  if (command === "models") {
+    await cmdModels(config, resolveBaseUrl(config)!);
+    return;
+  }
+
+  // Config
+  if (command === "config") {
+    if (sub === "show" || !sub) {
+      cmdConfigShow(config, resolveBaseUrl(config)!);
+    } else if (sub === "set") {
+      const [key, value] = rest;
+      if (!key || !value) {
+        errMsg("Usage: kundex config set <key> <value>");
+        process.exitCode = 1;
+      } else {
+        cmdConfigSet(key, value);
+      }
+    } else {
+      errMsg(`Unknown config subcommand "${sub}". Use: show, set`);
+      process.exitCode = 1;
+    }
     return;
   }
 
-  await runRepl(config, config.apiKey, baseUrl);
+  // Run (single-turn agent)
+  if (command === "run") {
+    const allArgs = [sub, ...rest].filter(Boolean);
+    const flagStart = allArgs.findIndex((a) => a.startsWith("--"));
+    const messageParts = flagStart >= 0 ? allArgs.slice(0, flagStart) : allArgs;
+    const flagArgs = flagStart >= 0 ? allArgs.slice(flagStart) : [];
+    const message = messageParts.join(" ").trim();
+
+    await cmdRun(config, resolveBaseUrl(config)!, message, flagArgs);
+    return;
+  }
+
+  // Unknown command — suggest help
+  errMsg(`Unknown command "${command}". Run \`kundex help\` to see available commands.`);
+  process.exitCode = 1;
 }
 
-main().catch((err) => {
-  console.error(err instanceof Error ? err.message : err);
+main().catch((e) => {
+  console.error(`${c.red}  Fatal: ${e instanceof Error ? e.message : e}${c.reset}`);
   process.exitCode = 1;
 });

package/src/repl.ts

@@ -1,7 +1,7 @@
 import readline from "node:readline/promises";
 import path from "node:path";
 import { execSync } from "node:child_process";
-import { Kundex, type AgentTurn } from "./sdk";
+import { Kundex, type AgentTurn, type AgentSession } from "./sdk";
 import { executeToolCall } from "./tools";
 import type { KundexConfig } from "./config";
 
@@ -18,14 +18,13 @@ const c = {
   blue:    "\x1b[34m",
   magenta: "\x1b[35m",
   white:   "\x1b[37m",
-  // Syntax-highlight colours (256-colour palette)
-  kw:      "\x1b[38;5;204m",  // keywords     – salmon/red
-  str:     "\x1b[38;5;150m",  // strings      – light green
-  num:     "\x1b[38;5;141m",  // numbers      – light purple
-  comment: "\x1b[38;5;244m",  // comments     – grey
-  fn:      "\x1b[38;5;117m",  // functions    – light blue
-  type_:   "\x1b[38;5;215m",  // types/decorators – orange
-  punct:   "\x1b[38;5;250m",  // punctuation  – light grey
+  kw:      "\x1b[38;5;204m",
+  str:     "\x1b[38;5;150m",
+  num:     "\x1b[38;5;141m",
+  comment: "\x1b[38;5;244m",
+  fn:      "\x1b[38;5;117m",
+  type_:   "\x1b[38;5;215m",
+  punct:   "\x1b[38;5;250m",
 };
 
 // ─── Per-language syntax highlighter (ANSI, no deps) ─────────────────────────
@@ -56,33 +55,26 @@ const KEYWORDS: Record<string, string[]> = {
 function buildRules(lang: string): LangRule[] {
   const kws = KEYWORDS[lang] || KEYWORDS["javascript"];
   return [
-    // Comments
     { pattern: /(#.*$|\/\/.*$|\/\*[\s\S]*?\*\/|"""[\s\S]*?"""|'''[\s\S]*?''')/gm, color: c.comment },
-    // Strings
     { pattern: /("(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|`(?:[^`\\]|\\.)*`)/g, color: c.str },
-    // Numbers
     { pattern: /\b(\d+\.?\d*(?:e[+-]?\d+)?)\b/g, color: c.num },
-    // Keywords (built from per-language list)
     { pattern: new RegExp(`\\b(${kws.join("|")})\\b`, "g"), color: c.kw },
-    // Function calls
     { pattern: /\b([a-zA-Z_]\w*)\s*(?=\()/g, color: c.fn },
-    // Type annotations (CamelCase identifiers)
     { pattern: /\b([A-Z][a-zA-Z0-9_]*)\b/g, color: c.type_ },
   ];
 }
 
-/** Apply regex-based ANSI syntax highlighting to a code string. */
 function syntaxHighlight(code: string, lang: string): string {
-  const l = lang.toLowerCase().replace(/^(tsx?|jsx?)$/, lang.includes("ts") || lang.includes("tsx") ? "typescript" : "javascript");
-  const normalised = ["python","py"].includes(l) ? "python"
-    : ["sh","shell","zsh"].includes(l) ? "bash"
+  const l = lang.toLowerCase();
+  const normalised = ["tsx","ts"].includes(l) ? "typescript"
+    : ["jsx","js","mjs"].includes(l) ? "javascript"
+    : ["python","py"].includes(l) ? "python"
+    : ["sh","shell","zsh","bash"].includes(l) ? "bash"
     : ["rs"].includes(l) ? "rust"
     : l;
 
   const rules = buildRules(normalised in KEYWORDS ? normalised : "javascript");
 
-  // We work character-by-character with a simple placeholder approach:
-  // collect all matches with their positions, sort them, then reconstruct.
   type Span = { start: number; end: number; color: string };
   const spans: Span[] = [];
 
@@ -97,7 +89,6 @@ function syntaxHighlight(code: string, lang: string): string {
 
   if (spans.length === 0) return code;
 
-  // Sort by start; discard overlapping spans (first wins)
   spans.sort((a, b) => a.start - b.start);
   const merged: Span[] = [];
   let cursor = 0;
@@ -144,7 +135,6 @@ function printReply(text: string) {
   while ((match = codeBlockRe.exec(text)) !== null) {
     const before = text.slice(last, match.index);
     if (before.trim()) {
-      // Wrap plain text at ~100 chars
       before.split("\n").forEach(line => {
         process.stdout.write(`  ${line}\n`);
       });
@@ -166,15 +156,17 @@ function printReply(text: string) {
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 const HELP = `
 ${c.bold}Commands:${c.reset}
-  /help         Show this help
-  /model        Show the model for this session
-  /clear        Start a fresh agent session
-  /exit         Quit kundex
+  /help               Show this help
+  /model              Show the model for this session
+  /clear              Start a fresh agent session
+  /exit               Quit kundex
 
 ${c.bold}Tips:${c.reset}
-  • The agent can read, edit and search files, run commands, and use git.
-  • You will be asked to confirm any writes or shell commands before they run.
+  • The agent can read files, search code, run commands, and use git.
+  • You will be asked to confirm any shell commands before they run.
+  • Responses stream in real-time — text appears as the model generates it.
   • Code blocks are syntax-highlighted in the terminal.
+  • Press Ctrl+C to abort a running request.
 `;
 
 function safeGitStatus(cwd: string): string | undefined {
@@ -196,11 +188,27 @@ function safeFileTree(cwd: string): string | undefined {
   }
 }
 
+function createSpinner(label: string) {
+  const frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+  let frame = 0;
+  const timer = setInterval(() => {
+    process.stdout.write(`\r${c.dim}  ${frames[frame++ % frames.length]} ${label}${c.reset}  `);
+  }, 80);
+
+  return {
+    clear() {
+      clearInterval(timer);
+      process.stdout.write("\r\x1b[2K");
+    },
+  };
+}
+
 async function handleTurn(
   kundex: Kundex,
   cwd: string,
   sessionId: number,
   turn: AgentTurn,
+  signal?: AbortSignal,
 ): Promise<void> {
   let current = turn;
 
@@ -210,16 +218,36 @@ async function handleTurn(
       if (isError) {
         process.stdout.write(`${c.red}  ✗ ${call.name}: ${result}${c.reset}\n`);
       }
-      current = await kundex.agent.submitToolResult({
-        sessionId,
-        toolCallId: call.id,
-        result,
-        isError,
-      });
+
+      const sp = createSpinner("processing tool result…");
+      let followUpText = "";
+
+      try {
+        current = await kundex.agent.submitToolResult(
+          { sessionId, toolCallId: call.id, result, isError },
+          (delta) => {
+            if (!followUpText) {
+              sp.clear();
+              process.stdout.write("\n");
+            }
+            followUpText += delta;
+            process.stdout.write(delta);
+          },
+          signal,
+        );
+      } finally {
+        sp.clear();
+      }
+
+      if (followUpText && !followUpText.endsWith("\n")) {
+        process.stdout.write("\n");
+      }
     }
   }
 
-  if (current.reply) {
+  if (current.reply && !turn.toolCalls?.length) {
+    process.stdout.write(`\n${c.dim}${"─".repeat(60)}${c.reset}\n\n`);
+  } else if (current.reply) {
     printReply(current.reply);
   }
 }
@@ -238,7 +266,7 @@ ${c.bold}${c.cyan}  ╚═╝  ╚═╝ ╚═════╝ ╚═╝  ╚═
   ${c.dim}cwd:${c.reset}   ${c.bold}${shortCwd}${c.reset}
   ${c.dim}model:${c.reset} ${c.bold}${model}${c.reset}
 
-  Type ${c.cyan}/help${c.reset} for commands.
+  Type ${c.cyan}/help${c.reset} for commands, ${c.cyan}Ctrl+C${c.reset} to stop a running request.
 `);
 }
 
@@ -246,20 +274,36 @@ ${c.bold}${c.cyan}  ╚═╝  ╚═╝ ╚═════╝ ╚═╝  ╚═
 export async function runRepl(config: KundexConfig, apiKey: string, baseUrl: string): Promise<void> {
   const cwd = process.cwd();
   const kundex = new Kundex({ apiKey, baseUrl });
-  const model = config.defaultModel ?? "openai/gpt-oss-120b";
+  const model = config.defaultModel ?? "codestral-latest";
 
   printBanner(cwd, model);
 
   let session = await kundex.agent.createSession({ cwd, model });
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
 
+  let currentAbort: AbortController | null = null;
+
+  const sigintHandler = () => {
+    if (currentAbort && !currentAbort.signal.aborted) {
+      currentAbort.abort();
+      process.stdout.write(`\n${c.yellow}  ⚡ Stopped.${c.reset}\n\n`);
+      currentAbort = null;
+    } else {
+      console.log(`\n${c.dim}Goodbye!${c.reset}\n`);
+      rl.close();
+      process.exit(0);
+    }
+  };
+
+  process.on("SIGINT", sigintHandler);
+
   try {
     for (;;) {
       const raw = await rl.question(`${c.bold}${c.cyan}kundex${c.reset} ${c.dim}▸${c.reset} `);
       const input = raw.trim();
       if (!input) continue;
 
-      if (input === "/exit") {
+      if (input === "/exit" || input === "/quit") {
         console.log(`\n${c.dim}Goodbye!${c.reset}\n`);
         break;
       }
@@ -274,23 +318,56 @@ export async function runRepl(config: KundexConfig, apiKey: string, baseUrl: str
         continue;
       }
 
+      // ── Agent message ────────────────────────────────────────────────────────
+      currentAbort = new AbortController();
+      const { signal } = currentAbort;
+      const spinner = createSpinner("thinking…");
+      let streamedAnyText = false;
+
       try {
-        process.stdout.write(`\n${c.dim}  thinking...${c.reset}\n`);
-        const turn = await kundex.agent.sendMessage({
-          sessionId: session.id,
-          message: input,
-          context: {
-            gitStatus: safeGitStatus(cwd),
-            fileTree: safeFileTree(cwd),
-            openFiles: [],
+        const turn = await kundex.agent.streamMessage(
+          {
+            sessionId: session.id,
+            message: input,
+            context: {
+              gitStatus: safeGitStatus(cwd),
+              fileTree: safeFileTree(cwd),
+            },
+          },
+          (delta) => {
+            if (!streamedAnyText) {
+              spinner.clear();
+              process.stdout.write("\n");
+              streamedAnyText = true;
+            }
+            process.stdout.write(delta);
           },
-        });
-        await handleTurn(kundex, cwd, session.id, turn);
+          signal,
+        );
+
+        spinner.clear();
+
+        if (turn.toolCalls?.length) {
+          await handleTurn(kundex, cwd, session.id, turn, signal);
+        } else if (streamedAnyText) {
+          process.stdout.write(`\n${c.dim}${"─".repeat(60)}${c.reset}\n\n`);
+        } else if (turn.reply) {
+          printReply(turn.reply);
+        }
       } catch (err) {
-        console.error(`\n${c.red}  error: ${(err as Error).message}${c.reset}\n`);
+        spinner.clear();
+        const e = err as Error;
+        if (e.name === "AbortError") {
+          // Already printed "⚡ Stopped" via sigintHandler
+        } else {
+          console.error(`\n${c.red}  error: ${e.message}${c.reset}\n`);
+        }
+      } finally {
+        currentAbort = null;
       }
     }
   } finally {
+    process.off("SIGINT", sigintHandler);
     rl.close();
   }
 }

package/src/sdk.ts

@@ -21,6 +21,8 @@ export interface ChatUsage {
 export interface ModelInfo {
   id: string;
   name: string;
+  /** Which inference provider serves this model (e.g. "heavstal", "mistral"). */
+  provider?: string;
   contextWindow: number;
   inputPricePerMTok: number;
   outputPricePerMTok: number;
@@ -34,6 +36,33 @@ export interface AgentTurn {
   usage: ChatUsage | null;
 }
 
+export interface AgentSession {
+  id: number;
+  cwd: string;
+  model: string;
+  name: string;
+  description: string;
+  language: string;
+  wsStatus: string;
+  pinned: boolean;
+  lastOpenedAt: string | null;
+  lastModifiedAt: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface WorkspaceFile {
+  id: number;
+  sessionId: number;
+  path: string;
+  name: string;
+  mimeType: string;
+  size: number;
+  content?: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
 export interface KundexOptions {
   apiKey: string;
   baseUrl: string;
@@ -49,7 +78,7 @@ export interface KundexOptions {
  */
 export class Kundex {
   private apiKey: string;
-  private baseUrl: string;
+  readonly baseUrl: string;
 
   constructor(opts: KundexOptions) {
     if (!opts.apiKey) throw new Error("Kundex: apiKey is required");
@@ -76,9 +105,37 @@ export class Kundex {
     return (await res.json()) as T;
   }
 
+  private async requestGet<T>(pathname: string): Promise<T> {
+    const res = await fetch(`${this.baseUrl}${pathname}`, {
+      method: "GET",
+      headers: { authorization: `Bearer ${this.apiKey}` },
+    });
+
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new Error(`Kundex API error (${res.status}): ${text || res.statusText}`);
+    }
+
+    return (await res.json()) as T;
+  }
+
+  private async requestDelete(pathname: string): Promise<void> {
+    const res = await fetch(`${this.baseUrl}${pathname}`, {
+      method: "DELETE",
+      headers: { authorization: `Bearer ${this.apiKey}` },
+    });
+
+    if (!res.ok && res.status !== 204) {
+      const text = await res.text().catch(() => "");
+      throw new Error(`Kundex API error (${res.status}): ${text || res.statusText}`);
+    }
+  }
+
   models = {
     list: async (): Promise<ModelInfo[]> => {
-      const res = await fetch(`${this.baseUrl}/v1/models`);
+      const res = await fetch(`${this.baseUrl}/v1/models`, {
+        headers: { authorization: `Bearer ${this.apiKey}` },
+      });
       if (!res.ok) throw new Error(`Kundex API error (${res.status})`);
       return (await res.json()) as ModelInfo[];
     },
@@ -109,6 +166,7 @@ export class Kundex {
         tools?: KundexToolDefinition[];
       },
       onDelta: (text: string) => void,
+      signal?: AbortSignal,
     ): Promise<{ finishReason: string; usage: ChatUsage | null }> => {
       const res = await fetch(`${this.baseUrl}/v1/chat/completions`, {
         method: "POST",
@@ -117,6 +175,7 @@ export class Kundex {
           authorization: `Bearer ${this.apiKey}`,
         },
         body: JSON.stringify({ ...params, stream: true }),
+        signal,
       });
 
       if (!res.ok || !res.body) {
@@ -130,25 +189,32 @@ export class Kundex {
       let finishReason = "stop";
       let usage: ChatUsage | null = null;
 
-      for (;;) {
-        const { done, value } = await reader.read();
-        if (done) break;
-        buffer += decoder.decode(value, { stream: true });
-        const lines = buffer.split("\n");
-        buffer = lines.pop() ?? "";
-
-        for (const line of lines) {
-          const trimmed = line.trim();
-          if (!trimmed.startsWith("data:")) continue;
-          const payload = trimmed.slice(5).trim();
-          if (!payload) continue;
-          const json = JSON.parse(payload);
-          if (json.delta) onDelta(json.delta);
-          if (json.done) {
-            finishReason = json.finishReason ?? finishReason;
-            usage = json.usage ?? usage;
+      try {
+        for (;;) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          buffer += decoder.decode(value, { stream: true });
+          const lines = buffer.split("\n");
+          buffer = lines.pop() ?? "";
+
+          for (const line of lines) {
+            const trimmed = line.trim();
+            if (trimmed.startsWith(":")) continue; // heartbeat comment
+            if (!trimmed.startsWith("data:")) continue;
+            const payload = trimmed.slice(5).trim();
+            if (!payload || payload === "[DONE]") continue;
+            try {
+              const json = JSON.parse(payload);
+              if (json.delta) onDelta(json.delta);
+              if (json.done) {
+                finishReason = json.finishReason ?? finishReason;
+                usage = json.usage ?? usage;
+              }
+            } catch { /* ignore bad JSON */ }
           }
         }
+      } finally {
+        try { reader.cancel(); } catch { /* ignore */ }
       }
 
       return { finishReason, usage };
@@ -156,23 +222,242 @@ export class Kundex {
   };
 
   agent = {
-    createSession: (params: { cwd: string; model?: string }) =>
-      this.request<{ id: number; cwd: string; model: string; createdAt: string }>(
-        "/v1/agent/session",
-        params,
+    createSession: (params: {
+      cwd: string;
+      model?: string;
+      name?: string;
+      description?: string;
+      language?: string;
+    }) =>
+      this.request<AgentSession>("/v1/agent/session", params),
+
+    listSessions: () =>
+      this.requestGet<AgentSession[]>("/v1/agent/sessions"),
+
+    getSession: (id: number) =>
+      this.requestGet<AgentSession>(`/v1/agent/sessions/${id}`),
+
+    deleteSession: (id: number) =>
+      this.requestDelete(`/v1/agent/sessions/${id}`),
+
+    getMessages: (id: number) =>
+      this.requestGet<{ sessionId: number; messages: unknown[] }>(`/v1/agent/sessions/${id}/messages`),
+
+    /**
+     * Send a message to the agent and stream the response.
+     *
+     * The server sends SSE events — this method handles the typed format
+     * emitted by the backend:
+     *   { type: "delta",  delta: string }
+     *   { type: "done",   reply?, toolCalls?, done, usage? }
+     *   { type: "error",  error: string }
+     *
+     * Invokes onDelta as text tokens arrive so the caller can print them
+     * incrementally.
+     *
+     * Returns the completed AgentTurn including any tool calls.
+     */
+    streamMessage: async (
+      params: {
+        sessionId: number;
+        message: string;
+        context?: { fileTree?: string; gitStatus?: string; openFiles?: string[] };
+      },
+      onDelta: (text: string) => void,
+      signal?: AbortSignal,
+    ): Promise<AgentTurn> => {
+      const endpoint = "/v1/agent/message";
+      const res = await fetch(`${this.baseUrl}${endpoint}`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${this.apiKey}`,
+        },
+        body: JSON.stringify(params),
+        signal,
+      });
+
+      if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        throw new Error(`Kundex API error (${res.status}): ${text || res.statusText}`);
+      }
+
+      const reader = res.body?.getReader();
+      if (!reader) throw new Error("No response body from server");
+
+      const decoder = new TextDecoder();
+      let buffer = "";
+      let reply = "";
+      let toolCalls: AgentTurn["toolCalls"] = null;
+      let usage: AgentTurn["usage"] = null;
+
+      try {
+        for (;;) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          buffer += decoder.decode(value, { stream: true });
+          const lines = buffer.split("\n");
+          buffer = lines.pop() ?? "";
+
+          for (const line of lines) {
+            const trimmed = line.trim();
+            if (trimmed.startsWith(":")) continue; // heartbeat comment
+            if (!trimmed.startsWith("data:")) continue;
+            const payload = trimmed.slice(5).trim();
+            if (!payload || payload === "[DONE]") continue;
+
+            try {
+              const ev = JSON.parse(payload);
+
+              if (ev.type === "delta" && typeof ev.delta === "string") {
+                reply += ev.delta;
+                onDelta(ev.delta);
+                continue;
+              }
+              if (ev.type === "done") {
+                return {
+                  sessionId: params.sessionId,
+                  reply: ev.reply !== undefined ? (ev.reply ?? reply) : reply,
+                  toolCalls: ev.toolCalls ?? ev.tool_calls ?? null,
+                  done: ev.done ?? true,
+                  usage: ev.usage ?? usage,
+                };
+              }
+              if (ev.type === "error") {
+                throw new Error(ev.error ?? "Agent error");
+              }
+
+              // Legacy format fallback
+              if (typeof ev.delta === "string") {
+                reply += ev.delta;
+                onDelta(ev.delta);
+              }
+              if (ev.done === true) {
+                return {
+                  sessionId: params.sessionId,
+                  reply: ev.reply ?? reply,
+                  toolCalls: ev.tool_calls ?? ev.toolCalls ?? null,
+                  done: true,
+                  usage: ev.usage ?? usage,
+                };
+              }
+            } catch (parseErr) {
+              if (parseErr instanceof SyntaxError) continue;
+              throw parseErr;
+            }
+          }
+        }
+      } finally {
+        try { reader.cancel(); } catch { /* ignore */ }
+      }
+
+      // Stream ended without a done event; return what we have
+      return { sessionId: params.sessionId, reply, toolCalls, done: true, usage };
+    },
+
+    submitToolResult: async (
+      params: {
+        sessionId: number;
+        toolCallId: string;
+        result: string;
+        isError?: boolean;
+      },
+      onDelta: (text: string) => void,
+      signal?: AbortSignal,
+    ): Promise<AgentTurn> => {
+      const res = await fetch(`${this.baseUrl}/v1/agent/tool-result`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${this.apiKey}`,
+        },
+        body: JSON.stringify(params),
+        signal,
+      });
+
+      if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        throw new Error(`Kundex API error (${res.status}): ${text || res.statusText}`);
+      }
+
+      const reader = res.body?.getReader();
+      if (!reader) throw new Error("No response body from server");
+
+      const decoder = new TextDecoder();
+      let buffer = "";
+      let reply = "";
+      let toolCalls: AgentTurn["toolCalls"] = null;
+      let usage: AgentTurn["usage"] = null;
+
+      try {
+        for (;;) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          buffer += decoder.decode(value, { stream: true });
+          const lines = buffer.split("\n");
+          buffer = lines.pop() ?? "";
+
+          for (const line of lines) {
+            const trimmed = line.trim();
+            if (trimmed.startsWith(":")) continue;
+            if (!trimmed.startsWith("data:")) continue;
+            const payload = trimmed.slice(5).trim();
+            if (!payload || payload === "[DONE]") continue;
+
+            try {
+              const ev = JSON.parse(payload);
+              if (ev.type === "delta" && typeof ev.delta === "string") {
+                reply += ev.delta;
+                onDelta(ev.delta);
+                continue;
+              }
+              if (ev.type === "done") {
+                return {
+                  sessionId: params.sessionId,
+                  reply: ev.reply !== undefined ? (ev.reply ?? reply) : reply,
+                  toolCalls: ev.toolCalls ?? ev.tool_calls ?? null,
+                  done: ev.done ?? true,
+                  usage: ev.usage ?? usage,
+                };
+              }
+              if (ev.type === "error") throw new Error(ev.error ?? "Agent error");
+              if (typeof ev.delta === "string") { reply += ev.delta; onDelta(ev.delta); }
+              if (ev.done === true) {
+                return {
+                  sessionId: params.sessionId,
+                  reply: ev.reply ?? reply,
+                  toolCalls: ev.tool_calls ?? ev.toolCalls ?? null,
+                  done: true,
+                  usage: ev.usage ?? usage,
+                };
+              }
+            } catch (parseErr) {
+              if (parseErr instanceof SyntaxError) continue;
+              throw parseErr;
+            }
+          }
+        }
+      } finally {
+        try { reader.cancel(); } catch { /* ignore */ }
+      }
+
+      return { sessionId: params.sessionId, reply, toolCalls, done: true, usage };
+    },
+  };
+
+  files = {
+    list: (wsId: number) =>
+      this.requestGet<{ files: WorkspaceFile[] }>(`/v1/workspace/${wsId}/files`),
+
+    get: (wsId: number, path: string) =>
+      this.requestGet<WorkspaceFile>(
+        `/v1/workspace/${wsId}/files/content?path=${encodeURIComponent(path)}`,
       ),
 
-    sendMessage: (params: {
-      sessionId: number;
-      message: string;
-      context?: { fileTree?: string; gitStatus?: string; openFiles?: string[] };
-    }) => this.request<AgentTurn>("/v1/agent/message", params),
-
-    submitToolResult: (params: {
-      sessionId: number;
-      toolCallId: string;
-      result: string;
-      isError?: boolean;
-    }) => this.request<AgentTurn>("/v1/agent/tool-result", params),
+    upsert: (wsId: number, params: { path: string; name: string; content: string; mimeType?: string }) =>
+      this.request<{ file: WorkspaceFile }>(`/v1/workspace/${wsId}/files`, params),
+
+    delete: (wsId: number, path: string) =>
+      this.requestDelete(`/v1/workspace/${wsId}/files?path=${encodeURIComponent(path)}`),
   };
 }

package/src/tools.ts

@@ -25,7 +25,6 @@ const c = {
   blue: "\x1b[34m",
   magenta: "\x1b[35m",
   white: "\x1b[37m",
-  bgDark: "\x1b[48;5;235m",
 };
 
 function header(label: string, value: string) {
@@ -34,34 +33,6 @@ function header(label: string, value: string) {
   );
 }
 
-function printDiff(oldContent: string | null, newContent: string, filePath: string) {
-  const oldLines = oldContent ? oldContent.split("\n") : [];
-  const newLines = newContent.split("\n");
-  const maxLines = Math.max(oldLines.length, newLines.length);
-  const LIMIT = 60;
-  const shown = Math.min(maxLines, LIMIT);
-
-  console.log(`\n${c.bold}${c.white}  ┌─ ${filePath} ─────────────────────────${c.reset}`);
-  for (let i = 0; i < shown; i++) {
-    const o = oldLines[i];
-    const n = newLines[i];
-    if (o === undefined) {
-      process.stdout.write(`${c.green}  + ${(i + 1).toString().padStart(4)}  ${n ?? ""}${c.reset}\n`);
-    } else if (n === undefined) {
-      process.stdout.write(`${c.red}  - ${(i + 1).toString().padStart(4)}  ${o ?? ""}${c.reset}\n`);
-    } else if (o !== n) {
-      process.stdout.write(`${c.red}  - ${(i + 1).toString().padStart(4)}  ${o}${c.reset}\n`);
-      process.stdout.write(`${c.green}  + ${(i + 1).toString().padStart(4)}  ${n}${c.reset}\n`);
-    } else {
-      process.stdout.write(`${c.dim}    ${(i + 1).toString().padStart(4)}  ${o}${c.reset}\n`);
-    }
-  }
-  if (maxLines > LIMIT) {
-    console.log(`${c.dim}  ... ${maxLines - LIMIT} more lines omitted${c.reset}`);
-  }
-  console.log(`${c.bold}${c.white}  └──────────────────────────────────────${c.reset}\n`);
-}
-
 async function confirm(prompt: string): Promise<boolean> {
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
   try {
@@ -86,35 +57,6 @@ async function readFileTool(cwd: string, args: { path: string }): Promise<string
   return fs.readFile(full, "utf-8");
 }
 
-async function writeFileTool(cwd: string, args: { path: string; content: string }): Promise<string> {
-  const full = resolveInCwd(cwd, args.path);
-  const lines = args.content.split("\n").length;
-  const bytes = Buffer.byteLength(args.content, "utf-8");
-
-  console.log(`\n${c.bold}${c.magenta}  ◆ write_file${c.reset} ${c.dim}${args.path}${c.reset}`);
-  console.log(`${c.dim}     ${lines} lines  ·  ${bytes} bytes${c.reset}`);
-
-  // Show diff vs existing file
-  let oldContent: string | null = null;
-  try {
-    oldContent = await fs.readFile(full, "utf-8");
-    console.log(`${c.dim}     (modifying existing file)${c.reset}`);
-  } catch {
-    console.log(`${c.dim}     (creating new file)${c.reset}`);
-  }
-
-  printDiff(oldContent, args.content, args.path);
-
-  const approved = await confirm(`Write ${bytes} bytes to "${args.path}"?`);
-  if (!approved) return "User declined to write this file.";
-
-  await fs.mkdir(path.dirname(full), { recursive: true });
-  await fs.writeFile(full, args.content, "utf-8");
-
-  console.log(`${c.green}${c.bold}  ✓ Wrote ${args.path}${c.reset} ${c.dim}(${bytes} bytes)${c.reset}\n`);
-  return `Wrote ${bytes} bytes to ${args.path}`;
-}
-
 async function runCommandTool(cwd: string, args: { command: string }): Promise<string> {
   console.log(`\n${c.bold}${c.yellow}  ◆ run_command${c.reset} ${c.dim}${args.command}${c.reset}`);
   const approved = await confirm(`Run: ${c.bold}${args.command}${c.reset}?`);
@@ -150,13 +92,7 @@ async function runCommandTool(cwd: string, args: { command: string }): Promise<s
 
 async function gitTool(cwd: string, args: { args: string[] }): Promise<string> {
   const cmd = `git ${args.args.join(" ")}`;
-  const isMutating = !["status", "diff", "log", "show", "branch"].includes(args.args[0]);
-
   header("git", cmd);
-  if (isMutating) {
-    const approved = await confirm(`Run: ${c.bold}${cmd}${c.reset}?`);
-    if (!approved) return "User declined to run this git command.";
-  }
 
   return new Promise((resolve) => {
     exec(cmd, { cwd, timeout: 30_000, maxBuffer: 1024 * 1024 }, (err, stdout, stderr) => {
@@ -178,7 +114,6 @@ async function listDirectoryTool(cwd: string, args: { path: string }): Promise<s
     if (e.isSymbolicLink()) return `  ${c.cyan}${e.name}@${c.reset}`;
     return `  ${e.name}`;
   });
-  // Print inline preview
   lines.forEach(l => process.stdout.write(l + "\n"));
   return entries
     .map(e => (e.isDirectory() ? `${e.name}/` : e.name))
@@ -189,8 +124,6 @@ async function searchFilesTool(
   cwd: string,
   args: { pattern: string; glob?: string }
 ): Promise<string> {
-  // Validate inputs: pattern must be a non-empty string; glob (if provided)
-  // must only contain safe filename characters to prevent shell expansion.
   if (!args.pattern || typeof args.pattern !== "string") {
     return "Search failed: pattern must be a non-empty string.";
   }
@@ -202,7 +135,6 @@ async function searchFilesTool(
 
   header("search_files", `"${args.pattern}"${args.glob ? ` in ${args.glob}` : ""}`);
 
-  // Build the argument array passed directly to execFile — no shell involved.
   const grepArgs: string[] = [
     "-rn",
     "--color=never",
@@ -211,13 +143,11 @@ async function searchFilesTool(
   if (args.glob) {
     grepArgs.push(`--include=${args.glob}`);
   }
-  // Pattern and path as positional args (not shell-interpolated)
   grepArgs.push(args.pattern, ".");
 
   return new Promise((resolve) => {
     execFile("grep", grepArgs, { cwd, timeout: 15_000, maxBuffer: 1024 * 1024 }, (err, stdout, stderr) => {
       if (err && (err as NodeJS.ErrnoException & { code: number }).code === 1) {
-        // grep exits 1 when no matches are found — not an error
         resolve("No matches found.");
         return;
       }
@@ -244,8 +174,6 @@ export async function executeToolCall(cwd: string, call: ToolCall): Promise<Tool
     switch (call.name) {
       case "read_file":
         return { result: await readFileTool(cwd, args), isError: false };
-      case "write_file":
-        return { result: await writeFileTool(cwd, args), isError: false };
       case "run_command":
         return { result: await runCommandTool(cwd, args), isError: false };
       case "git":