kimiflare 0.49.0 → 0.50.1

package/README.md

@@ -77,6 +77,107 @@ kimiflare -p "..." --dangerously-allow-all          # auto-approve mutating tool
 kimiflare -p "..." --reasoning                      # include chain-of-thought in stderr
 ```
 
+### Headless SDK
+
+Use KimiFlare programmatically from your own application — no TUI required.
+
+```ts
+import { createAgentSession } from "kimiflare/sdk";
+
+const { session } = await createAgentSession({
+  cwd: "/path/to/project",
+  config: {
+    accountId: process.env.CLOUDFLARE_ACCOUNT_ID,
+    apiToken: process.env.CLOUDFLARE_API_TOKEN,
+    model: "@cf/moonshotai/kimi-k2.6",
+  },
+});
+
+// Stream every event: text deltas, tool calls, tasks, usage
+session.subscribe((event) => {
+  console.log(event.type, event);
+});
+
+// Send a prompt
+await session.prompt("Refactor auth to JWT + Redis");
+
+// Mid-flight correction while the agent is still running
+await session.steer("Use Redis instead of in-memory store");
+
+// After the turn finishes
+await session.followUp("Also add unit tests");
+
+// Clean up
+session.dispose();
+```
+
+**Key features:**
+- `subscribe()` — receive typed events (`text_delta`, `tool_call`, `tool_result`, `task_update`, `usage`, `error`, `done`, etc.)
+- `prompt()` / `steer()` / `followUp()` — full conversation lifecycle
+- `pause()` / `resume()` — graceful preemption
+- `getStatus()` / `getUsage()` — inspect session state
+- Custom `permissionHandler` — decide programmatically whether to allow mutating tools
+- Optional `memoryEnabled`, `lspEnabled`, `costAttribution` flags
+
+#### SDK Authentication
+
+The SDK needs a Cloudflare **Account ID** and **API Token** to call Workers AI directly. Credentials are resolved in this priority order:
+
+1. **Explicit `config` object** (recommended for apps)
+2. **Environment variables**: `CLOUDFLARE_ACCOUNT_ID` / `CF_ACCOUNT_ID`, `CLOUDFLARE_API_TOKEN` / `CF_API_TOKEN`
+3. **Config file**: `~/.config/kimiflare/config.json`
+
+**For Electron / desktop apps**, we recommend storing credentials in the OS keychain (e.g. Electron `safeStorage` or `keytar`) and passing them explicitly:
+
+```ts
+import { createAgentSession } from "kimiflare/sdk";
+
+const accountId = await keytar.getPassword("kimiflare", "accountId");
+const apiToken = await keytar.getPassword("kimiflare", "apiToken");
+
+const { session } = await createAgentSession({
+  cwd: projectPath,
+  config: { accountId, apiToken },
+});
+```
+
+**For zero-credential onboarding**, use KimiFlare Cloud mode. The user authenticates via GitHub device flow and a Cloudflare Worker proxies AI requests. Your app never sees raw Cloudflare credentials — only a GitHub token and `remoteWorkerUrl`.
+
+#### RPC mode (subprocess)
+
+If you need process isolation or a non-Node consumer, run KimiFlare in JSONL-over-stdio RPC mode:
+
+```sh
+node bin/kimiflare.mjs --mode rpc
+```
+
+```ts
+import { spawn } from "node:child_process";
+
+const proc = spawn("npx", ["kimiflare", "--mode", "rpc"], {
+  cwd: projectPath,
+  stdio: ["pipe", "pipe", "pipe"],
+});
+
+// Read events
+proc.stdout.on("data", (chunk) => {
+  for (const line of chunk.toString().split("\n")) {
+    if (!line.trim()) continue;
+    const event = JSON.parse(line);
+    console.log(event.type, event);
+  }
+});
+
+// Send commands
+proc.stdin.write(JSON.stringify({ type: "new_session" }) + "\n");
+proc.stdin.write(JSON.stringify({ type: "prompt", message: "Hello" }) + "\n");
+
+// Resolve a permission request
+proc.stdin.write(
+  JSON.stringify({ type: "resolve_permission", requestId: "req_0", decision: "allow" }) + "\n"
+);
+```
+
 ### Image understanding
 
 ```sh

package/dist/index.js

@@ -453,6 +453,34 @@ var init_sse = __esm({
 function isCloudQuotaExhaustedError(err) {
   return err instanceof KimiApiError && err.httpStatus === 429 && /token quota exhausted/i.test(err.message);
 }
+function humanizeCloudflareError(err) {
+  const { code, httpStatus, message: message2 } = err;
+  if (code === 3040) {
+    return "Cloudflare Workers AI is at capacity. Retrying automatically\u2026";
+  }
+  if (httpStatus === 429) {
+    return "Rate limit hit. Please wait a moment and try again.";
+  }
+  if (httpStatus === 403 || code === 1e4) {
+    return "Authentication failed. Check that your Cloudflare API token has the 'Workers AI' permission.\nGet a new token: https://dash.cloudflare.com/profile/api-tokens";
+  }
+  if (httpStatus === 401) {
+    return "Authentication required. Please check your API token or run `kimiflare auth cloud` if using cloud mode.";
+  }
+  if (httpStatus === 400) {
+    if (message2.includes("invalid escaped character")) {
+      return "API rejected request (invalid JSON in conversation history). Run /clear to reset if it persists.";
+    }
+    if (message2.includes("Invalid model ID")) {
+      return message2;
+    }
+    return "Bad request. The conversation may be too long or contain invalid characters. Run /compact or /clear.";
+  }
+  if (httpStatus && httpStatus >= 500) {
+    return "Cloudflare servers are experiencing issues. Retrying automatically\u2026";
+  }
+  return message2.replace(/\{[\s\S]*?\}/g, "(see logs for details)");
+}
 var KimiApiError;
 var init_errors = __esm({
   "src/util/errors.ts"() {
@@ -620,7 +648,7 @@ async function* runKimi(opts2) {
         parsed = JSON.parse(text);
       } catch {
       }
-      const err = extractCloudflareError(parsed);
+      const err = extractCloudflareError(parsed, text);
       const rawMsg = err?.message ?? `HTTP ${res.status}: ${text.slice(0, 300)}`;
       const msg = cleanErrorMessage(rawMsg);
       const apiErr = new KimiApiError(`kimiflare: ${msg}`, err?.code, res.status);
@@ -827,16 +855,23 @@ function validateJsonArguments(raw) {
     return "{}";
   }
 }
-function extractCloudflareError(parsed) {
-  if (!parsed || typeof parsed !== "object") return null;
-  const cf = parsed;
-  if (cf.success === false && Array.isArray(cf.errors) && cf.errors.length > 0) {
-    return { code: cf.errors[0]?.code, message: cf.errors[0]?.message };
+function extractCloudflareError(parsed, rawText) {
+  if (parsed && typeof parsed === "object") {
+    const cf = parsed;
+    if (cf.success === false && Array.isArray(cf.errors) && cf.errors.length > 0) {
+      return { code: cf.errors[0]?.code, message: cf.errors[0]?.message };
+    }
+    const oai = parsed;
+    if (oai.object === "error" && typeof oai.message === "string") {
+      const codeNum = typeof oai.code === "number" ? oai.code : void 0;
+      return { code: codeNum, message: oai.message };
+    }
   }
-  const oai = parsed;
-  if (oai.object === "error" && typeof oai.message === "string") {
-    const codeNum = typeof oai.code === "number" ? oai.code : void 0;
-    return { code: codeNum, message: oai.message };
+  if (rawText) {
+    const msgMatch = rawText.match(/"message"\s*:\s*"([^"]+)"/);
+    if (msgMatch?.[1]) {
+      return { message: msgMatch[1] };
+    }
   }
   return null;
 }
@@ -3314,8 +3349,8 @@ var init_write = __esm({
       },
       needsPermission: true,
       render: (args) => ({
-        title: `write ${collapsePath(args.path, process.cwd())} (${args.content.length} chars)`,
-        diff: { path: args.path, before: "", after: args.content }
+        title: `write ${collapsePath(String(args.path ?? ""), process.cwd())} (${String(args.content ?? "").length} chars)`,
+        diff: { path: String(args.path ?? ""), before: "", after: String(args.content ?? "") }
       }),
       async run(args, ctx) {
         const abs = resolvePath(ctx.cwd, args.path);
@@ -3367,8 +3402,8 @@ var init_edit = __esm({
       },
       needsPermission: true,
       render: (args) => ({
-        title: `edit ${collapsePath(args.path, process.cwd())}${args.replace_all ? " (replace_all)" : ""}`,
-        diff: { path: args.path, before: args.old_string, after: args.new_string }
+        title: `edit ${collapsePath(String(args.path ?? ""), process.cwd())}${args.replace_all ? " (replace_all)" : ""}`,
+        diff: { path: String(args.path ?? ""), before: String(args.old_string ?? ""), after: String(args.new_string ?? "") }
       }),
       async run(args, ctx) {
         const abs = resolvePath(ctx.cwd, args.path);
@@ -3516,7 +3551,7 @@ var init_bash = __esm({
         additionalProperties: false
       },
       needsPermission: true,
-      render: (args) => ({ title: formatBashTitle(args.command) }),
+      render: (args) => ({ title: formatBashTitle(String(args.command ?? "")) }),
       run: (args, ctx) => runBash(args, ctx)
     };
   }
@@ -3542,7 +3577,7 @@ var init_glob = __esm({
         additionalProperties: false
       },
       needsPermission: false,
-      render: (args) => ({ title: `glob ${args.pattern}${args.path ? ` in ${collapsePath(args.path, process.cwd())}` : ""}` }),
+      render: (args) => ({ title: `glob ${args.pattern ?? ""}${args.path ? ` in ${collapsePath(String(args.path), process.cwd())}` : ""}` }),
       async run(args, ctx) {
         const root = args.path ? resolvePath(ctx.cwd, args.path) : ctx.cwd;
         const entries = await fg(args.pattern, {
@@ -3660,7 +3695,7 @@ var init_grep = __esm({
         additionalProperties: false
       },
       needsPermission: false,
-      render: (args) => ({ title: `grep ${args.pattern}${args.glob ? ` (${args.glob})` : ""}` }),
+      render: (args) => ({ title: `grep ${args.pattern ?? ""}${args.glob ? ` (${args.glob})` : ""}` }),
       async run(args, ctx) {
         const root = args.path ? resolvePath(ctx.cwd, args.path) : ctx.cwd;
         const mode = args.output_mode ?? "content";
@@ -3692,7 +3727,7 @@ var init_web_fetch = __esm({
         additionalProperties: false
       },
       needsPermission: false,
-      render: (args) => ({ title: `GET ${args.url}` }),
+      render: (args) => ({ title: `GET ${args.url ?? ""}` }),
       async run(args) {
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
@@ -3827,7 +3862,7 @@ var init_web_search = __esm({
         additionalProperties: false
       },
       needsPermission: false,
-      render: (args) => ({ title: `search web: ${args.query}` }),
+      render: (args) => ({ title: `search web: ${args.query ?? ""}` }),
       async run(args) {
         const count = Math.min(Math.max(args.count ?? DEFAULT_RESULTS, 1), MAX_RESULTS);
         try {
@@ -3913,7 +3948,7 @@ var init_github = __esm({
         additionalProperties: false
       },
       needsPermission: false,
-      render: (args) => ({ title: `GitHub PR ${args.owner}/${args.repo}#${args.number}` }),
+      render: (args) => ({ title: `GitHub PR ${args.owner ?? ""}/${args.repo ?? ""}#${args.number ?? ""}` }),
       async run(args, ctx) {
         const token = getToken(ctx);
         const pr = await githubFetch(`/repos/${args.owner}/${args.repo}/pulls/${args.number}`, token);
@@ -3955,7 +3990,7 @@ var init_github = __esm({
         additionalProperties: false
       },
       needsPermission: false,
-      render: (args) => ({ title: `GitHub issue ${args.owner}/${args.repo}#${args.number}` }),
+      render: (args) => ({ title: `GitHub issue ${args.owner ?? ""}/${args.repo ?? ""}#${args.number ?? ""}` }),
       async run(args, ctx) {
         const token = getToken(ctx);
         const issue = await githubFetch(`/repos/${args.owner}/${args.repo}/issues/${args.number}`, token);
@@ -4002,7 +4037,7 @@ var init_github = __esm({
       },
       needsPermission: false,
       render: (args) => ({
-        title: `GitHub code ${args.owner}/${args.repo}/${args.path}${args.ref ? `@${args.ref}` : ""}`
+        title: `GitHub code ${args.owner ?? ""}/${args.repo ?? ""}/${args.path ?? ""}${args.ref ? `@${args.ref}` : ""}`
       }),
       async run(args, ctx) {
         const token = getToken(ctx);
@@ -4080,7 +4115,7 @@ var init_browser = __esm({
       },
       needsPermission: false,
       render: (args) => ({
-        title: `browser ${args.url}${args.screenshot ? " (screenshot)" : ""}`
+        title: `browser ${args.url ?? ""}${args.screenshot ? " (screenshot)" : ""}`
       }),
       async run(args, ctx) {
         let playwright;
@@ -4206,10 +4241,13 @@ var init_tasks = __esm({
         required: ["tasks"]
       },
       needsPermission: false,
-      render: (args) => ({
-        title: `tasks (${args.tasks.length} items)`,
-        body: args.tasks.map((t) => `${t.status === "completed" ? "\u2713" : t.status === "in_progress" ? "\u25B8" : "\xB7"} ${t.title}`).join("\n")
-      }),
+      render: (args) => {
+        const tasks = Array.isArray(args.tasks) ? args.tasks : [];
+        return {
+          title: `tasks (${tasks.length} items)`,
+          body: tasks.map((t) => `${t.status === "completed" ? "\u2713" : t.status === "in_progress" ? "\u25B8" : "\xB7"} ${t.title}`).join("\n")
+        };
+      },
       run: async (args, ctx) => {
         let tasks;
         try {
@@ -4260,7 +4298,7 @@ var init_memory = __esm({
       needsPermission: false,
       render: (args) => ({
         title: "memory_remember",
-        body: `[${args.category}] ${args.content} (importance: ${args.importance})`
+        body: `[${args.category ?? "unknown"}] ${args.content ?? ""} (importance: ${args.importance ?? 1})`
       }),
       run: async (args, ctx) => {
         if (!isMemoryCtx(ctx) || !ctx.memoryManager) {
@@ -4315,7 +4353,7 @@ var init_memory = __esm({
       needsPermission: false,
       render: (args) => ({
         title: "memory_recall",
-        body: `Query: "${args.query}"`
+        body: `Query: "${args.query ?? ""}"`
       }),
       run: async (args, ctx) => {
         if (!isMemoryCtx(ctx) || !ctx.memoryManager) {
@@ -4360,7 +4398,7 @@ var init_memory = __esm({
       needsPermission: false,
       render: (args) => ({
         title: "memory_forget",
-        body: `Forgetting memory ${args.memory_id}`
+        body: `Forgetting memory ${args.memory_id ?? ""}`
       }),
       run: async (args, ctx) => {
         if (!isMemoryCtx(ctx) || !ctx.memoryManager) {
@@ -4920,7 +4958,7 @@ function makeExpandArtifactTool(store) {
       additionalProperties: false
     },
     needsPermission: false,
-    render: (args) => ({ title: `expand ${args.artifact_id}` }),
+    render: (args) => ({ title: `expand ${args.artifact_id ?? ""}` }),
     run: async (args) => {
       const raw = store.retrieve(args.artifact_id);
       if (!raw) {
@@ -8415,6 +8453,9 @@ function usageDir2() {
 function usagePath2() {
   return join18(usageDir2(), "usage.json");
 }
+function historyPath() {
+  return join18(usageDir2(), "history.jsonl");
+}
 function today2() {
   return (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
 }
@@ -8435,6 +8476,35 @@ async function saveLog(log2) {
   await mkdir9(usageDir2(), { recursive: true });
   await writeFile10(usagePath2(), JSON.stringify(log2, null, 2), "utf8");
 }
+async function loadHistory() {
+  try {
+    const raw = await readFile13(historyPath(), "utf8");
+    const lines = raw.split("\n").filter((l) => l.trim());
+    const entries = [];
+    for (const line of lines) {
+      try {
+        const parsed = JSON.parse(line);
+        if (parsed.date) entries.push(parsed);
+      } catch {
+      }
+    }
+    return entries;
+  } catch {
+  }
+  return [];
+}
+async function upsertHistoryDay(day) {
+  const entries = await loadHistory();
+  const idx = entries.findIndex((e) => e.date === day.date);
+  if (idx >= 0) {
+    entries[idx] = day;
+  } else {
+    entries.push(day);
+  }
+  const lines = entries.map((e) => JSON.stringify(e)).join("\n") + "\n";
+  await mkdir9(usageDir2(), { recursive: true });
+  await writeFile10(historyPath(), lines, "utf8");
+}
 function getOrCreateDay(log2, date) {
   let day = log2.days.find((d) => d.date === date);
   if (!day) {
@@ -8534,9 +8604,18 @@ async function recordUsage(sessionId, usage, gateway) {
     session.gatewayLogs = [...session.gatewayLogs ?? [], gatewaySnapshot].slice(-100);
   }
   await saveLog(log2);
+  await upsertHistoryDay(day);
+}
+function mergeDays(usageDays, historyDays) {
+  const map = /* @__PURE__ */ new Map();
+  for (const d of historyDays) map.set(d.date, d);
+  for (const d of usageDays) map.set(d.date, d);
+  return Array.from(map.values()).sort((a, b) => a.date < b.date ? -1 : a.date > b.date ? 1 : 0);
 }
 async function getCostReport(sessionId) {
   const log2 = pruneUsageLog(await loadLog2());
+  const history = await loadHistory();
+  const allDays = mergeDays(log2.days, history);
   const date = today2();
   const currentMonth = date.slice(0, 7);
   const session = sessionId ? log2.sessions.find((s) => s.id === sessionId) ?? { date, promptTokens: 0, completionTokens: 0, cachedTokens: 0, cost: 0 } : { date, promptTokens: 0, completionTokens: 0, cachedTokens: 0, cost: 0 };
@@ -8548,7 +8627,7 @@ async function getCostReport(sessionId) {
     cachedTokens: 0,
     cost: 0
   };
-  for (const d of log2.days) {
+  for (const d of allDays) {
     if (d.date.startsWith(currentMonth)) {
       monthUsage.promptTokens += d.promptTokens;
       monthUsage.completionTokens += d.completionTokens;
@@ -8566,7 +8645,7 @@ async function getCostReport(sessionId) {
     cachedTokens: 0,
     cost: 0
   };
-  for (const d of log2.days) {
+  for (const d of allDays) {
     allTime.promptTokens += d.promptTokens;
     allTime.completionTokens += d.completionTokens;
     allTime.cachedTokens += d.cachedTokens;
@@ -9654,7 +9733,9 @@ import { createTwoFilesPatch } from "diff";
 import { jsx as jsx2, jsxs } from "react/jsx-runtime";
 function DiffView({ path, before, after, maxLines = 40 }) {
   const theme = useTheme();
-  const patch = createTwoFilesPatch(path, path, before, after, "", "", { context: 2 });
+  const safeBefore = before ?? "";
+  const safeAfter = after ?? "";
+  const patch = createTwoFilesPatch(path, path, safeBefore, safeAfter, "", "", { context: 2 });
   const raw = patch.split("\n").slice(4);
   const lines = raw.filter((l) => {
     if (l.startsWith("--- ") || l.startsWith("+++ ")) return false;
@@ -10669,7 +10750,11 @@ import SelectInput from "ink-select-input";
 import { jsx as jsx8, jsxs as jsxs7 } from "react/jsx-runtime";
 function PermissionModal({ tool, args, onDecide }) {
   const theme = useTheme();
-  const render2 = tool.render?.(args);
+  let render2;
+  try {
+    render2 = tool.render?.(args);
+  } catch {
+  }
   const items = [
     { label: "Allow once", value: "allow" },
     { label: "Allow for this session", value: "allow_session" },
@@ -17960,9 +18045,10 @@ ${wcagWarnings.join("\n")}` }
           { kind: "cloud_quota_exhausted", key: mkKey(), used, limit, expiresAt }
         ]);
       } else {
+        const displayText = e instanceof KimiApiError ? humanizeCloudflareError(e) : `init failed: ${e.message}`;
         setEvents((es) => [
           ...es,
-          { kind: "error", key: mkKey(), text: `init failed: ${e.message}` }
+          { kind: "error", key: mkKey(), text: displayText }
         ]);
       }
     } finally {
@@ -19512,23 +19598,11 @@ ${lines.join("\n")}` }]);
                 { kind: "cloud_quota_exhausted", key: mkKey(), used, limit, expiresAt }
               ]);
             } else {
-              const isInvalidJson400 = e instanceof KimiApiError && e.httpStatus === 400 && e.message.includes("invalid escaped character");
-              if (isInvalidJson400) {
-                messagesRef.current.pop();
-                setEvents((es) => [
-                  ...es,
-                  {
-                    kind: "error",
-                    key: mkKey(),
-                    text: "API rejected request (invalid JSON in conversation history). Retrying may work; run /clear to reset if it persists."
-                  }
-                ]);
-              } else {
-                setEvents((es) => [
-                  ...es,
-                  { kind: "error", key: mkKey(), text: e.message ?? String(e) }
-                ]);
-              }
+              const displayText2 = e instanceof KimiApiError ? humanizeCloudflareError(e) : e.message ?? String(e);
+              setEvents((es) => [
+                ...es,
+                { kind: "error", key: mkKey(), text: displayText2 }
+              ]);
             }
             cleanupTurn();
           }
@@ -20007,6 +20081,7 @@ var init_app = __esm({
 init_config();
 init_lsp_config();
 init_loop();
+init_errors();
 init_system_prompt();
 init_executor();
 init_update_check();
@@ -20359,6 +20434,13 @@ async function runPrintMode(opts2) {
       process.exitCode = 42;
       return;
     }
+    if (err instanceof KimiApiError) {
+      process.stderr.write(`
+\x1B[31mError: ${humanizeCloudflareError(err)}\x1B[0m
+`);
+      process.exitCode = 1;
+      return;
+    }
     throw err;
   }
   process.stdout.write("\n");