u-foo 2.5.8 → 2.5.9

package/README.md

@@ -61,6 +61,7 @@ Installed binaries:
 | `uclaude` | Claude Code wrapper with ufoo bootstrap and bus identity. |
 | `ucodex` | Codex wrapper with ufoo bootstrap and bus identity. |
 | `uagy` | Antigravity wrapper with ufoo bootstrap and bus identity. |
+| `ukimi` | Kimi Code wrapper with ufoo bootstrap and bus identity. |
 | `ucode` | Native ufoo coding-agent CLI/TUI. |
 
 ## Quick Start
@@ -88,6 +89,7 @@ Or launch wrappers directly inside a project:
 uclaude
 ucodex
 uagy
+ukimi
 ucode
 ```
 

package/README.zh-CN.md

@@ -59,6 +59,7 @@ npm link
 | `uclaude` | Claude Code 包装器，注入 ufoo bootstrap 和 bus 身份。 |
 | `ucodex` | Codex 包装器，注入 ufoo bootstrap 和 bus 身份。 |
 | `uagy` | Antigravity 包装器，注入 ufoo bootstrap 和 bus 身份。 |
+| `ukimi` | Kimi Code 包装器，注入 ufoo bootstrap 和 bus 身份。 |
 | `ucode` | 原生 ufoo coding-agent CLI/TUI。 |
 
 ## 快速开始
@@ -86,6 +87,7 @@ ufoo
 uclaude
 ucodex
 uagy
+ukimi
 ucode
 ```
 
@@ -155,7 +157,7 @@ ufoo -g
 /open /path/to/project
 ```
 
-`uclaude`、`ucodex`、`uagy`、`ucode` 这些直接包装器仍然可用，但 ufoo 的
+`uclaude`、`ucodex`、`uagy`、`ukimi`、`ucode` 这些直接包装器仍然可用，但 ufoo 的
 主要工作流是在 chat 里完成。
 
 ### 初始化与维护

package/bin/ufoo.js

@@ -143,6 +143,9 @@ async function main() {
       } else if (agentType === "codex") {
         scriptName = "ucodex.js";
         displayName = "ucodex";
+      } else if (agentType === "kimi") {
+        scriptName = "ukimi.js";
+        displayName = "ukimi";
       } else {
         console.error(`Error: Unable to determine agent type for ${subscriberId}`);
         process.exitCode = 1;
@@ -182,11 +185,13 @@ async function main() {
       scriptName = "uclaude.js";
     } else if (targetLower === "ucodex" || targetLower === "codex" || targetLower === "openai") {
       scriptName = "ucodex.js";
+    } else if (targetLower === "ukimi" || targetLower === "kimi" || targetLower === "kimi-cli" || targetLower === "kimi-code") {
+      scriptName = "ukimi.js";
     } else {
       // Not a valid agent type - might be an offline agent nickname
       console.error(`Error: Agent '${target}' is not online and is not a valid agent type`);
       console.error("");
-      console.error("Valid agent types: ucode, uclaude, ucodex");
+      console.error("Valid agent types: ucode, uclaude, ucodex, ukimi");
       console.error("");
       console.error("To see online agents, run: ufoo bus status");
       process.exitCode = 1;

package/bin/ukimi.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * ukimi: Launch Kimi Code CLI (kimi) and auto-join event bus
+ *
+ * Usage: ukimi [kimi args...]
+ *
+ * Differences vs uclaude:
+ *   - kimi has no --append-system-prompt style flag, so the default
+ *     bootstrap is delivered via post-launch PTY injection (same model as
+ *     ucodex's UFOO_STARTUP_BOOTSTRAP_TEXT path).
+ *   - Session resume uses kimi's own session ids via `--session <id>`.
+ */
+
+const AgentLauncher = require("../src/agents/launch/launcher");
+const { resolveDefaultManualBootstrap } = require("../src/agents/prompts/defaultBootstrap");
+
+function extractUfooParamsFromArgs(args = []) {
+  const nextArgs = [];
+  let nickname = "";
+  let role = "";
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = String(args[i] || "");
+    if (arg === "--nickname") {
+      if (i + 1 < args.length) {
+        nickname = String(args[i + 1]).trim();
+        i += 1;
+      }
+      continue;
+    }
+    if (arg.startsWith("--nickname=")) {
+      nickname = arg.slice("--nickname=".length).trim();
+      continue;
+    }
+    if (arg === "--role") {
+      if (i + 1 < args.length) {
+        role = String(args[i + 1]).trim();
+        i += 1;
+      }
+      continue;
+    }
+    if (arg.startsWith("--role=")) {
+      role = arg.slice("--role=".length).trim();
+      continue;
+    }
+    nextArgs.push(args[i]);
+  }
+  return { args: nextArgs, nickname, role };
+}
+
+const { args: cleanArgs, nickname, role } = extractUfooParamsFromArgs(process.argv.slice(2));
+if (nickname) {
+  process.env.UFOO_NICKNAME = nickname;
+}
+if (role) {
+  process.env.UFOO_PROMPT_PROFILE = role;
+}
+
+const launcher = new AgentLauncher("kimi", "kimi");
+const resolved = resolveDefaultManualBootstrap({
+  projectRoot: process.cwd(),
+  agentType: "kimi",
+  args: cleanArgs,
+  env: process.env,
+});
+
+for (const [key, value] of Object.entries(resolved.env || {})) {
+  process.env[key] = String(value);
+}
+
+launcher.launch(resolved.args);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "u-foo",
-  "version": "2.5.8",
+  "version": "2.5.9",
   "description": "Multi-Agent Workspace Protocol. Just add u. claude → uclaude, codex → ucodex.",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://ufoo.dev",
@@ -20,6 +20,7 @@
     "uclaude": "bin/uclaude.js",
     "ucodex": "bin/ucodex.js",
     "uagy": "bin/uagy.js",
+    "ukimi": "bin/ukimi.js",
     "ucode": "bin/ucode.js"
   },
   "files": [

package/src/agents/activity/activityDetector.js

@@ -53,6 +53,13 @@ const INPUT_PATTERNS = {
     /Yes, and run (?:in|without) sandbox/i, // Terminal command approval (sandbox toggle)
     /\bn\b\s*-\s*Don't run/i,          // y/n/edit confirmation
   ],
+  // kimi (Kimi Code CLI) ink-style approval menus (verified against 0.27.0).
+  kimi: [
+    /Run this command\?/,              // Bash command approval question
+    /Approve once[\s\S]*Approve for this session/, // Approval option list
+    /Reject with feedback/,            // Approval option (reject path)
+    /↑\/↓ select · .*choose · ↵ confirm/, // Interactive menu navigation bar (option count varies)
+  ],
 };
 
 // Agent-specific FATAL patterns that immediately move the agent into BLOCKED

package/src/agents/launch/launcher.js

@@ -209,8 +209,9 @@ function computeInjectedSubmitDelayMs(agentType, text) {
   const normalizedAgent = String(agentType || "").trim().toLowerCase();
   const input = typeof text === "string" ? text : "";
   // Agy uses an ink-style TUI like claude-code, so it needs a similar grace
-  // window before the input handler picks up injected text.
-  const isInkStyle = normalizedAgent === "claude-code" || normalizedAgent === "agy";
+  // window before the input handler picks up injected text. Kimi Code is an
+  // Ink TUI as well and gets the same treatment.
+  const isInkStyle = normalizedAgent === "claude-code" || normalizedAgent === "agy" || normalizedAgent === "kimi";
   let delayMs = isInkStyle ? 350 : 200;
   if (input.includes("\n")) {
     delayMs += isInkStyle ? 250 : 120;
@@ -244,10 +245,10 @@ async function injectPtyCommand(wrapper, agentType, commandText, source = "injec
   const normalizedAgentType = String(agentType || "").trim().toLowerCase();
   const submitDelayMs = computeInjectedSubmitDelayMs(agentType, text);
   wrapper.write(text);
-  // claude-code and agy both run ink-style TUIs that accept a bare CR to
-  // submit. codex needs the Esc-prefix trick to flush its multi-byte input
+  // claude-code, agy and kimi all run ink-style TUIs that accept a bare CR
+  // to submit. codex needs the Esc-prefix trick to flush its multi-byte input
   // handler before the CR.
-  const isInkStyle = normalizedAgentType === "claude-code" || normalizedAgentType === "agy";
+  const isInkStyle = normalizedAgentType === "claude-code" || normalizedAgentType === "agy" || normalizedAgentType === "kimi";
   if (isInkStyle) {
     await sleep(submitDelayMs);
     wrapper.write("\r");

package/src/agents/launch/readyDetector.js

@@ -108,6 +108,25 @@ class ReadyDetector {
     return false;
   }
 
+  /**
+   * Detect kimi (Kimi Code CLI) ready markers.
+   *
+   * kimi renders an ink-style TUI (verified against 0.27.0 via PTY capture):
+   *   - A status footer "... @: mention files" that only appears once the
+   *     prompt box is mounted (most reliable signal — post-boot only).
+   *   - The welcome banner "Welcome to Kimi Code!" as fallback, in case the
+   *     statusline render changes (e.g. narrow terminal).
+   */
+  _detectKimiReady(text) {
+    if (text.includes("@: mention files")) {
+      return true;
+    }
+    if (text.includes("Welcome to Kimi Code!")) {
+      return true;
+    }
+    return false;
+  }
+
   /**
    * 检测ufoo-code/ucode的ready标记
    */
@@ -158,6 +177,8 @@ class ReadyDetector {
       isReady = this._detectCodexReady(this.buffer);
     } else if (this.agentType === "agy") {
       isReady = this._detectAgyReady(this.buffer);
+    } else if (this.agentType === "kimi") {
+      isReady = this._detectKimiReady(this.buffer);
     } else if (this.agentType === "ufoo" || this.agentType === "ucode" || this.agentType === "ufoo-code") {
       isReady = this._detectUfooCodeReady(this.buffer);
     }

package/src/agents/prompts/defaultBootstrap.js

@@ -58,7 +58,9 @@ function buildDefaultStartupBootstrapPrompt({ agentType = "", projectRoot = "" }
       ? "Codex"
       : (normalizedAgent === "ufoo-code"
         ? "ucode"
-        : (normalizedAgent === "agy" ? "Agy" : "agent")));
+        : (normalizedAgent === "agy"
+          ? "Agy"
+          : (normalizedAgent === "kimi" ? "Kimi" : "agent"))));
 
   const segments = [
     `Session bootstrap for ${displayAgent}.`,
@@ -253,11 +255,11 @@ function resolveDefaultManualBootstrap({
   const normalizedAgent = asTrimmedString(agentType).toLowerCase();
   const currentEnv = env && typeof env === "object" ? env : {};
   const currentArgs = Array.isArray(args) ? args.slice() : [];
-  const hasCodexStartupBootstrap = normalizedAgent === "codex"
+  const hasStartupBootstrap = (normalizedAgent === "codex" || normalizedAgent === "kimi")
     && Boolean(currentEnv.UFOO_STARTUP_BOOTSTRAP_TEXT);
   if (
     currentEnv.UFOO_SKIP_DEFAULT_BOOTSTRAP === "1"
-    || hasCodexStartupBootstrap
+    || hasStartupBootstrap
     || hasMetaCommandArgs(currentArgs)
   ) {
     return { args: currentArgs, env: {}, mode: "skip" };
@@ -328,6 +330,21 @@ function resolveDefaultManualBootstrap({
     };
   }
 
+  if (normalizedAgent === "kimi") {
+    // kimi has no --append-system-prompt or positional initial-prompt flag,
+    // so the bootstrap always goes out via post-launch PTY injection (the
+    // launcher reads UFOO_STARTUP_BOOTSTRAP_TEXT, same as the codex path).
+    const promptText = buildDefaultStartupBootstrapPrompt({ agentType: normalizedAgent, projectRoot });
+    return {
+      args: currentArgs,
+      env: {
+        UFOO_STARTUP_BOOTSTRAP_TEXT: promptText,
+      },
+      mode: "post-launch-inject",
+      promptText,
+    };
+  }
+
   if (normalizedAgent === "agy") {
     const promptText = buildDefaultStartupBootstrapPrompt({ agentType: normalizedAgent, projectRoot });
     // If the user passed -i / --prompt-interactive, fold the bootstrap into

package/src/agents/providers/credentials/index.js

@@ -104,3 +104,10 @@ module.exports = {
   toLegacyResolvedAuth,
   buildUpstreamAuthFromCredential,
 };
+
+// Attached lazily after the shared helpers so the circular require from
+// ./kimi (which pulls buildCredentialDescriptor from here) always resolves.
+Object.defineProperty(module.exports, "kimi", {
+  enumerable: true,
+  get: () => require("./kimi"),
+});

package/src/agents/providers/credentials/kimi.js

@@ -0,0 +1,342 @@
+"use strict";
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const {
+  buildCredentialDescriptor,
+} = require("./index");
+
+const KIMI_OAUTH_TOKEN_URL = "https://auth.kimi.com/api/oauth/token";
+const KIMI_OAUTH_CLIENT_ID = "17e5f671-d194-4dfb-9706-5516cb48c098";
+const DEFAULT_REFRESH_WINDOW_MS = 300 * 1000;
+const DEFAULT_LOCK_TIMEOUT_MS = 3000;
+const DEFAULT_LOCK_RETRY_MS = 25;
+const DEFAULT_STALE_LOCK_MS = 30 * 1000;
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function defaultKimiHome(env = process.env) {
+  const configured = String(env.KIMI_CODE_HOME || "").trim();
+  if (configured) return configured;
+  return path.join(os.homedir(), ".kimi-code");
+}
+
+function resolveKimiCredentialPaths(options = {}) {
+  const env = options.env || process.env;
+  const home = String(options.home || options.configDir || defaultKimiHome(env)).trim() || defaultKimiHome(env);
+  const explicitCredentialPath = String(options.credentialPath || "").trim();
+  const credentialPath = explicitCredentialPath || path.join(home, "credentials", "kimi-code.json");
+  return {
+    home,
+    credentialPath,
+    lockPath: `${credentialPath}.lock`,
+  };
+}
+
+function firstString(...values) {
+  for (const value of values) {
+    if (typeof value === "string" && value.trim()) return value.trim();
+  }
+  return "";
+}
+
+// kimi CLI stores expires_at as Unix epoch seconds (e.g. 1784486687); accept
+// epoch millis and ISO strings as well so hand-rolled fixtures keep working.
+function parseKimiExpiresAtMs(value) {
+  if (typeof value === "number" && Number.isFinite(value) && value > 0) {
+    return value > 1e12 ? Math.floor(value) : Math.floor(value * 1000);
+  }
+  const text = String(value || "").trim();
+  if (!text) return NaN;
+  if (/^\d+(?:\.\d+)?$/.test(text)) {
+    const num = Number(text);
+    return num > 1e12 ? Math.floor(num) : Math.floor(num * 1000);
+  }
+  return Date.parse(text);
+}
+
+function parseKimiCredentialFile(raw = {}) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    const err = new Error("Kimi credential payload must be a JSON object");
+    err.code = "KIMI_AUTH_INVALID";
+    throw err;
+  }
+
+  const accessToken = firstString(raw.access_token, raw.accessToken);
+  const refreshToken = firstString(raw.refresh_token, raw.refreshToken);
+  if (!accessToken && !refreshToken) {
+    const err = new Error("Unsupported Kimi credential schema");
+    err.code = "KIMI_AUTH_SCHEMA_UNSUPPORTED";
+    throw err;
+  }
+
+  const expiresAtMs = parseKimiExpiresAtMs(
+    raw.expires_at !== undefined ? raw.expires_at : raw.expiresAt
+  );
+
+  return {
+    schemaVersion: "kimi-code-credentials-v1",
+    raw,
+    accessToken,
+    refreshToken,
+    tokenType: firstString(raw.token_type, raw.tokenType, "Bearer"),
+    scope: firstString(raw.scope),
+    expiresAt: Number.isFinite(expiresAtMs) ? new Date(expiresAtMs).toISOString() : "",
+    expiresAtMs,
+  };
+}
+
+async function withLockFile(lockPath, options = {}, fn) {
+  const fsModule = options.fsModule || fs;
+  const timeoutMs = Number.isFinite(options.timeoutMs) ? options.timeoutMs : DEFAULT_LOCK_TIMEOUT_MS;
+  const retryMs = Number.isFinite(options.retryMs) ? options.retryMs : DEFAULT_LOCK_RETRY_MS;
+  const staleMs = Number.isFinite(options.staleMs) ? options.staleMs : DEFAULT_STALE_LOCK_MS;
+  const sleepFn = typeof options.sleep === "function" ? options.sleep : sleep;
+  const startedAt = Date.now();
+
+  fsModule.mkdirSync(path.dirname(lockPath), { recursive: true, mode: 0o700 });
+
+  while ((Date.now() - startedAt) <= timeoutMs) {
+    let fd = null;
+    try {
+      fd = fsModule.openSync(lockPath, "wx", 0o600);
+      try {
+        return await fn();
+      } finally {
+        try { fsModule.closeSync(fd); } catch {}
+        try { fsModule.unlinkSync(lockPath); } catch {}
+      }
+    } catch (err) {
+      if (!err || err.code !== "EEXIST") throw err;
+      try {
+        const stat = fsModule.statSync(lockPath);
+        if ((Date.now() - stat.mtimeMs) > staleMs) {
+          fsModule.unlinkSync(lockPath);
+          continue;
+        }
+      } catch {}
+      // eslint-disable-next-line no-await-in-loop
+      await sleepFn(retryMs);
+    }
+  }
+
+  const err = new Error(`Timed out waiting for Kimi OAuth lock: ${lockPath}`);
+  err.code = "KIMI_AUTH_LOCK_TIMEOUT";
+  throw err;
+}
+
+class KimiUpstreamCredentialResolver {
+  constructor(options = {}) {
+    this.fs = options.fsModule || fs;
+    this.env = options.env || process.env;
+    this.fetchImpl = options.fetchImpl || global.fetch;
+    this.now = typeof options.now === "function" ? options.now : () => Date.now();
+    this.paths = resolveKimiCredentialPaths(options);
+    this.refreshWindowMs = Number.isFinite(options.refreshWindowMs) ? options.refreshWindowMs : DEFAULT_REFRESH_WINDOW_MS;
+    this.autoRefresh = options.autoRefresh !== false;
+    this.refreshRetries = Number.isInteger(options.refreshRetries) && options.refreshRetries > 0
+      ? options.refreshRetries
+      : 2;
+    this.sleep = typeof options.sleep === "function" ? options.sleep : sleep;
+    this.lockTimeoutMs = Number.isFinite(options.lockTimeoutMs) ? options.lockTimeoutMs : DEFAULT_LOCK_TIMEOUT_MS;
+    this.lockRetryMs = Number.isFinite(options.lockRetryMs) ? options.lockRetryMs : DEFAULT_LOCK_RETRY_MS;
+    this.lockStaleMs = Number.isFinite(options.lockStaleMs) ? options.lockStaleMs : DEFAULT_STALE_LOCK_MS;
+  }
+
+  resolvePaths() {
+    return { ...this.paths };
+  }
+
+  readCredentialFile() {
+    const raw = JSON.parse(this.fs.readFileSync(this.paths.credentialPath, "utf8"));
+    return parseKimiCredentialFile(raw);
+  }
+
+  writeCredentialFile(raw) {
+    const text = `${JSON.stringify(raw, null, 2)}\n`;
+    const tmpPath = `${this.paths.credentialPath}.tmp-${process.pid}-${Date.now()}`;
+    this.fs.mkdirSync(path.dirname(this.paths.credentialPath), { recursive: true, mode: 0o700 });
+    this.fs.writeFileSync(tmpPath, text, { encoding: "utf8", mode: 0o600 });
+    this.fs.renameSync(tmpPath, this.paths.credentialPath);
+    try { this.fs.chmodSync(this.paths.credentialPath, 0o600); } catch {}
+  }
+
+  async refreshTokens(refreshToken) {
+    if (typeof this.fetchImpl !== "function") {
+      const err = new Error("fetch is unavailable for Kimi token refresh");
+      err.code = "KIMI_AUTH_REFRESH_UNAVAILABLE";
+      throw err;
+    }
+
+    let lastErr = null;
+    for (let attempt = 0; attempt < this.refreshRetries; attempt += 1) {
+      try {
+        const body = new URLSearchParams({
+          client_id: KIMI_OAUTH_CLIENT_ID,
+          grant_type: "refresh_token",
+          refresh_token: refreshToken,
+        });
+        const response = await this.fetchImpl(KIMI_OAUTH_TOKEN_URL, {
+          method: "POST",
+          headers: {
+            "content-type": "application/x-www-form-urlencoded",
+            accept: "application/json",
+          },
+          body: body.toString(),
+        });
+        const text = await response.text();
+        if (!response.ok) {
+          const err = new Error(`Kimi token refresh failed (${response.status}): ${text.slice(0, 500)}`);
+          err.code = "KIMI_AUTH_REFRESH_FAILED";
+          err.status = response.status;
+          throw err;
+        }
+        const payload = JSON.parse(text);
+        if (!payload || typeof payload !== "object" || !payload.access_token) {
+          const err = new Error("Kimi token refresh response did not include access_token");
+          err.code = "KIMI_AUTH_REFRESH_SCHEMA_UNSUPPORTED";
+          throw err;
+        }
+        const expiresIn = Number(payload.expires_in);
+        const expiresAtMs = Number.isFinite(expiresIn) && expiresIn > 0
+          ? this.now() + Math.floor(expiresIn * 1000)
+          : NaN;
+        return {
+          accessToken: firstString(payload.access_token),
+          refreshToken: firstString(payload.refresh_token, refreshToken),
+          tokenType: firstString(payload.token_type, "Bearer"),
+          scope: firstString(payload.scope),
+          expiresAt: Number.isFinite(expiresAtMs) ? new Date(expiresAtMs).toISOString() : "",
+          expiresAtMs,
+        };
+      } catch (err) {
+        lastErr = err;
+        if (err && err.code === "KIMI_AUTH_REFRESH_SCHEMA_UNSUPPORTED") {
+          throw err;
+        }
+      }
+    }
+
+    const err = new Error(lastErr && lastErr.message ? lastErr.message : "Kimi token refresh failed");
+    err.code = lastErr && lastErr.code ? lastErr.code : "KIMI_AUTH_REFRESH_FAILED";
+    err.cause = lastErr;
+    throw err;
+  }
+
+  async refreshCredentialRecord(record) {
+    if (!record || !record.refreshToken) {
+      const err = new Error("Kimi OAuth credential is expired and has no refresh token");
+      err.code = "KIMI_AUTH_REFRESH_UNAVAILABLE";
+      throw err;
+    }
+
+    return withLockFile(this.paths.lockPath, {
+      fsModule: this.fs,
+      timeoutMs: this.lockTimeoutMs,
+      retryMs: this.lockRetryMs,
+      staleMs: this.lockStaleMs,
+      sleep: this.sleep,
+    }, async () => {
+      const currentRecord = this.readCredentialFile();
+      const currentDescriptor = this.buildResolvedCredential(currentRecord);
+      if (currentDescriptor.state === "fresh") {
+        return currentRecord;
+      }
+      if (!currentRecord.refreshToken) {
+        const err = new Error("Kimi OAuth credential is expired and has no refresh token");
+        err.code = "KIMI_AUTH_REFRESH_UNAVAILABLE";
+        throw err;
+      }
+
+      const refreshed = await this.refreshTokens(currentRecord.refreshToken);
+      const nextRaw = currentRecord.raw && typeof currentRecord.raw === "object" && !Array.isArray(currentRecord.raw)
+        ? { ...currentRecord.raw }
+        : {};
+      nextRaw.access_token = refreshed.accessToken;
+      nextRaw.refresh_token = refreshed.refreshToken || currentRecord.refreshToken || "";
+      if (refreshed.tokenType) nextRaw.token_type = refreshed.tokenType;
+      if (refreshed.scope) nextRaw.scope = refreshed.scope;
+      if (Number.isFinite(refreshed.expiresAtMs)) {
+        nextRaw.expires_at = Math.floor(refreshed.expiresAtMs / 1000);
+      }
+      this.writeCredentialFile(nextRaw);
+      return this.readCredentialFile();
+    });
+  }
+
+  buildResolvedCredential(record) {
+    return buildCredentialDescriptor({
+      provider: "kimi",
+      credentialKind: "oauth",
+      source: "credential-file",
+      accessToken: record.accessToken,
+      refreshToken: record.refreshToken,
+      tokenType: record.tokenType || "Bearer",
+      expiresAt: record.expiresAt,
+      expiresAtMs: record.expiresAtMs,
+      refreshable: Boolean(record.refreshToken),
+      credentialPath: this.paths.credentialPath,
+      schemaVersion: record.schemaVersion,
+      nowMs: this.now(),
+      refreshWindowMs: this.refreshWindowMs,
+      metadata: {
+        scope: record.scope,
+      },
+    });
+  }
+
+  async resolveCredentials() {
+    let record;
+    try {
+      record = this.readCredentialFile();
+    } catch (err) {
+      if (err && err.code === "ENOENT") {
+        const missing = new Error("Kimi credential file not found; run `kimi` once to sign in");
+        missing.code = "KIMI_AUTH_UNAVAILABLE";
+        throw missing;
+      }
+      throw err;
+    }
+    const descriptor = this.buildResolvedCredential(record);
+    if (
+      this.autoRefresh
+      && descriptor.refreshable
+      && (descriptor.state === "expired" || descriptor.state === "near_expiry")
+    ) {
+      const refreshedRecord = await this.refreshCredentialRecord(record);
+      return this.buildResolvedCredential(refreshedRecord);
+    }
+    return descriptor;
+  }
+}
+
+async function resolveKimiUpstreamCredentials(options = {}) {
+  const resolver = new KimiUpstreamCredentialResolver(options);
+  return resolver.resolveCredentials();
+}
+
+// Synchronous, network-free read used by resolveRuntimeConfig: returns the
+// credential descriptor (fresh or not) or null when the file is unusable.
+function readKimiAccessToken(options = {}) {
+  try {
+    const resolver = new KimiUpstreamCredentialResolver({ ...options, autoRefresh: false });
+    const record = resolver.readCredentialFile();
+    return resolver.buildResolvedCredential(record);
+  } catch {
+    return null;
+  }
+}
+
+module.exports = {
+  KimiUpstreamCredentialResolver,
+  resolveKimiUpstreamCredentials,
+  resolveKimiCredentialPaths,
+  parseKimiCredentialFile,
+  parseKimiExpiresAtMs,
+  readKimiAccessToken,
+  KIMI_OAUTH_TOKEN_URL,
+  KIMI_OAUTH_CLIENT_ID,
+};