kimiflare 0.49.0 → 0.50.0

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;
 }
@@ -8415,6 +8450,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 +8473,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 +8601,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 +8624,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 +8642,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;
@@ -17960,9 +18036,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 +19589,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 +20072,7 @@ var init_app = __esm({
 init_config();
 init_lsp_config();
 init_loop();
+init_errors();
 init_system_prompt();
 init_executor();
 init_update_check();
@@ -20359,6 +20425,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");