@datename/fastcode-termux 0.0.0-stage → 0.1.6-beta

package/src/lib/diagnostics.ts

@@ -0,0 +1,195 @@
+/**
+ * Environment diagnostics for mobile / Termux troubleshooting.
+ *
+ * `fastcode doctor` prints the values below so a broken mobile install can be
+ * diagnosed without opening the TUI: Node version, Termux detection, whether
+ * stdout is a real terminal, the config root, and which provider keys exist.
+ */
+import { existsSync, statSync } from "node:fs";
+import { totalmem, freemem, tmpdir as osTmpdir } from "node:os";
+import { detectPlatform, platformLabel } from "./platform.js";
+import { readPackageMeta } from "./pkg.js";
+import { shouldUseStableTerminalUi } from "./uiMode.js";
+import { getPaths } from "../config/paths.js";
+import { loadConfig, resolveApiKey, resolveProviderKey } from "../config/store.js";
+import { PROVIDERS } from "../providers/index.js";
+import { listInstalledSkills } from "../skills/manager.js";
+import { listInstalledPlugins } from "../plugins/manager.js";
+import { findUnclosedSessions, fsyncMode, loggingEnabled, listSessions, sessionCacheLimitBytes } from "../session/log.js";
+import { isTrusted } from "../config/trust.js";
+import { DEFAULT_DENY_PATTERNS, loopExemptTools } from "../agent/guards.js";
+import { toolOutputLimit } from "../agent/limits.js";
+import { compactionConfigFromEnv, heapExceeded } from "../agent/compaction.js";
+import { shellPoolStats } from "../agent/shell-session.js";
+import { resolveToolProtocol, toolCapabilityKey } from "../agent/protocol-mode.js";
+import { getModelMeta, modelMetaOverridePath } from "./model-meta.js";
+const NODE_REQUIRED = "18.17";
+function readVersion() {
+    return readPackageMeta().version;
+}
+function nodeIsSupported() {
+    const [major = 0, minor = 0] = process.versions.node.split(".").map(Number);
+    const [reqMajor = 0, reqMinor = 0] = NODE_REQUIRED.split(".").map(Number);
+    return major > reqMajor || (major === reqMajor && minor >= reqMinor);
+}
+export function collectDiagnostics() {
+    const config = loadConfig();
+    let paths;
+    try {
+        paths = getPaths();
+    }
+    catch {
+        paths = undefined;
+    }
+    const provider = PROVIDERS.find((p) => p.id === config.providerId);
+    const keyLookup = provider && provider.authEnv.length > 0
+        ? resolveApiKey(provider.id, config.model, provider.authEnv)
+        : { status: "ok" as const };
+    const keyPresent = Boolean(provider) && (provider.authEnv.length === 0 || keyLookup.status === "ok");
+    let skillsInstalled = 0;
+    let pluginsInstalled = 0;
+    try {
+        skillsInstalled = listInstalledSkills().length;
+    }
+    catch {
+        // A broken skills dir must not break the whole report.
+    }
+    try {
+        pluginsInstalled = listInstalledPlugins().length;
+    }
+    catch {
+        // Same for plugins.
+    }
+    const platform = detectPlatform();
+    const compaction = compactionConfigFromEnv();
+    const shells = shellPoolStats();
+    let authMode = "missing";
+    try {
+        if (paths?.auth && existsSync(paths.auth))
+            authMode = (statSync(paths.auth).mode & 0o777).toString(8).padStart(4, "0");
+    }
+    catch {
+        authMode = "unreadable";
+    }
+    return {
+        version: readVersion(),
+        node: process.version,
+        nodeRequired: NODE_REQUIRED,
+        nodeOk: nodeIsSupported(),
+        platform,
+        platformLabel: platformLabel(),
+        termux: platform === "termux",
+        termuxVersion: process.env["TERMUX_VERSION"] ?? null,
+        stableUi: shouldUseStableTerminalUi(),
+        tty: Boolean(process.stdout.isTTY),
+        configRoot: paths?.root,
+        configFile: paths?.config,
+        authFile: paths?.auth,
+        authMode,
+        tmpdir: process.env["TMPDIR"] || osTmpdir(),
+        memTotalMb: totalmem() / 1024 / 1024,
+        memFreeMb: freemem() / 1024 / 1024,
+        providerId: config.providerId,
+        model: config.model,
+        keyPresent,
+        keyStatus: provider ? keyLookup.status : "missing",
+        keyEnv: provider?.authEnv?.[0],
+        skillsInstalled,
+        pluginsInstalled,
+        enabledSkills: (config.enabledSkills ?? []).length,
+        enabledPlugins: (config.enabledPlugins ?? []).length,
+        sessionLogEnabled: loggingEnabled(),
+        sessionCacheMb: Math.round(sessionCacheLimitBytes() / (1024 * 1024)),
+        sessionFsync: fsyncMode(),
+        unclosedSessions: findUnclosedSessions().length,
+        sessionsDir: paths?.sessions,
+        sessionsCount: listSessions().length,
+        sessionsBytes: listSessions().reduce((sum, entry) => sum + entry.bytes, 0),
+        trustFile: paths?.trust,
+        trusted: isTrusted(process.cwd()),
+        shellDenyPatterns: DEFAULT_DENY_PATTERNS.length,
+        allowDangerous: ["1", "true", "yes", "on"].includes((process.env["FASTCODE_ALLOW_DANGEROUS"] ?? "").trim().toLowerCase()),
+        toolOutputLimit: toolOutputLimit(),
+        tokenBudget: positiveEnv("FASTCODE_TOKEN_BUDGET"),
+        costBudgetUsd: positiveEnv("FASTCODE_COST_BUDGET_USD"),
+        compactionEnabled: compaction.enabled,
+        compactionRatio: compaction.localThresholdRatio,
+        compactionHeapMb: compaction.heapLimitMb,
+        compactionHeapUsedMb: process.memoryUsage().heapUsed / 1024 / 1024,
+        compactionForced: heapExceeded(compaction),
+        serverCompactionAware: compaction.serverCompactionAware,
+        shellActive: shells.active,
+        shellPool: shells.pool,
+        shellSpawns: shells.spawns,
+        shellMaxSpawn: shells.maxSpawnPerTurn,
+        sseIdleMs: positiveEnv("FASTCODE_SSE_IDLE_MS") || 25_000,
+        toolProtocol: resolveToolProtocol(config, config.providerId, config.model),
+        toolProtocolMode: (process.env["FASTCODE_TOOL_PROTOCOL"] ?? "legacy").trim().toLowerCase(),
+        toolCapability: config.capabilities?.toolCalling?.[toolCapabilityKey(config.providerId, config.model)] ?? "unknown",
+        loopExempt: Array.from(loopExemptTools()),
+        modelMetaFile: modelMetaOverridePath(),
+        modelMeta: getModelMeta(config.providerId, config.model),
+        providers: PROVIDERS.map((p) => ({
+            id: p.id,
+            label: p.label,
+            env: p.authEnv,
+            keyPresent: p.authEnv.length === 0 || Boolean(resolveProviderKey(p.id, p.authEnv).key),
+        })),
+    };
+}
+function positiveEnv(name) {
+    const value = Number(process.env[name]);
+    return Number.isFinite(value) && value > 0 ? value : 0;
+}
+export function formatDiagnostics(info) {
+    const lines = [];
+    lines.push(`FastCode ${info.version} — environment check`);
+    lines.push("");
+    lines.push(`  node          ${info.node}  (needs >= ${info.nodeRequired})  [${info.nodeOk ? "ok" : "TOO OLD"}]`);
+    lines.push(`  platform      ${info.platformLabel}${info.termux ? " (Termux)" : ""}`);
+    lines.push(`  terminal      ${info.tty ? "interactive TTY" : "NOT a TTY — the TUI needs a real terminal"}`);
+    lines.push(`  stable UI     ${info.stableUi ? "on (anti-flicker)" : "off"}`);
+    lines.push("  config root   " + (info.configRoot ?? "(unavailable)"));
+    lines.push("  config file   " + (info.configFile ?? "(unavailable)"));
+    lines.push("  keys file     " + (info.authFile ?? "(unavailable)") + "   mode " + info.authMode + (info.authMode !== "missing" && info.authMode !== "0600" ? "  [WARN: expected 0600]" : ""));
+    lines.push("  tmpdir        " + info.tmpdir + (info.termux && !String(info.tmpdir).startsWith("/data/data/com.termux") ? "  [WARN: use $PREFIX/tmp]" : ""));
+    lines.push("  memory        " + info.memFreeMb.toFixed(0) + "MB free / " + info.memTotalMb.toFixed(0) + "MB total");
+    lines.push("  trusted cwd   " + (info.trusted ? "yes" : "NO - agent tools ask first or stay off") + "   (" + (info.trustFile ?? "?") + ")");
+    lines.push("  session log   " + (info.sessionLogEnabled ? "on" : "off") + "   cache cap " + info.sessionCacheMb + "MB, " + info.sessionsCount + " file(s), " + (info.sessionsBytes / 1024 / 1024).toFixed(2) + "MB used");
+    lines.push("  session fsync " + info.sessionFsync + "   unclosed " + info.unclosedSessions + "   " + (info.sessionsDir ?? "(unavailable)"));
+    lines.push("  shell guard   " + info.shellDenyPatterns + " deny patterns" + (info.allowDangerous ? "   [FASTCODE_ALLOW_DANGEROUS is ON]" : ""));
+    lines.push("  tool output   " + info.toolOutputLimit + " chars max (streaming cap)");
+    lines.push(`  budgets       ${info.tokenBudget > 0 ? "tokens ≤ " + info.tokenBudget : "token budget off"} · ${info.costBudgetUsd > 0 ? "$" + info.costBudgetUsd : "cost budget off"}`);
+    lines.push(`  compaction    ${info.compactionEnabled ? "on" : "off"} · ${Math.round(info.compactionRatio * 100)}% · heap ${info.compactionHeapUsedMb.toFixed(1)}/${info.compactionHeapMb}MB${info.compactionForced ? " [FORCED]" : ""}${info.serverCompactionAware ? " · server-aware" : ""}`);
+    lines.push(`  shell pool    ${info.shellActive} active · ${info.shellPool} resident · ${info.shellSpawns} spawns · cap ${info.shellMaxSpawn}/turn`);
+    lines.push(`  loop exempt   ${info.loopExempt.length > 0 ? info.loopExempt.join(", ") : "(none)"}`);
+    lines.push(`  model meta    ctx ${info.modelMeta.contextWindow} · ~${info.modelMeta.charsPerToken} chars/token · ${info.modelMeta.supportsTools ? "tools" : "no tools"} · ${info.modelMetaFile}`);
+    lines.push(`  sse timeout   ${info.sseIdleMs}ms idle`);
+    lines.push(`  tool protocol ${info.toolProtocol} (${info.toolProtocolMode}) · cached ${info.toolCapability}`);
+    lines.push(`  provider      ${info.providerId} · model ${info.model}`);
+    let apiKeyStatus;
+    if (info.keyPresent)
+        apiKeyStatus = "present";
+    else if (info.keyStatus === "unbound")
+        apiKeyStatus = `UNBOUND — a stored ${info.providerId} key isn't tied to a model; re-bind with /login ${info.providerId} ${info.model} <key>`;
+    else
+        apiKeyStatus = `MISSING — set ${info.keyEnv ?? "the provider env var"} or /login ${info.providerId} ${info.model} <key>`;
+    lines.push(`  api key       ${apiKeyStatus}`);
+    lines.push(`  skills        ${info.skillsInstalled} installed, ${info.enabledSkills} enabled`);
+    lines.push(`  plugins       ${info.pluginsInstalled} installed, ${info.enabledPlugins} enabled`);
+    lines.push("");
+    lines.push("  provider keys:");
+    for (const p of info.providers) {
+        lines.push(`    ${p.keyPresent ? "●" : "○"} ${p.id.padEnd(12)} ${p.env.join(" / ") || "(no key needed)"}`);
+    }
+    if (info.termux) {
+        lines.push("");
+        lines.push("  Termux tips:");
+        lines.push("    - pkg install nodejs git");
+        lines.push("    - keep the session alive with: termux-wake-lock");
+        lines.push("    - add an extra-keys row for Esc/Ctrl in ~/.termux/termux.properties");
+        lines.push("    - long tasks: export TMPDIR=$PREFIX/tmp and use termux-wake-lock");
+        lines.push(`    - Android 12+ caps phantom processes (~32); background shells are pooled (${info.shellPool} resident, cap ${info.shellMaxSpawn}/turn)`);
+    }
+    return lines.join("\n");
+}

package/src/lib/http.ts

@@ -0,0 +1,132 @@
+/**
+ * Tiny fetch helpers. We standardize on globalThis.fetch (Node 18+).
+ *
+ * The `streamSSE` helper parses Server-Sent Events for any provider that uses
+ * the OpenAI-style `data: {...}\n\n` chunk format. Non-SSE providers (e.g.
+ * Anthropic's older streaming) handle their own parsing.
+ */
+export async function fetchJson(url: string, init: any = {}): Promise<any> {
+    const res = await fetch(url, {
+        ...init,
+        headers: { "content-type": "application/json", accept: "application/json", ...(init.headers ?? {}) },
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        throw new Error(`${res.status} ${res.statusText}: ${body.slice(0, 500)}`);
+    }
+    return (await res.json());
+}
+export class NetworkStallError extends Error {
+    readonly code = "NETWORK_STALL";
+    readonly bytesReceived: number;
+    constructor(message: string, bytesReceived = 0) {
+        super(message);
+        this.name = "NetworkStallError";
+        this.bytesReceived = bytesReceived;
+    }
+}
+export interface StreamSseOptions {
+    idleTimeoutMs?: number;
+    totalTimeoutMs?: number;
+}
+/** Async iterator over SSE events from a streaming HTTP response. */
+export async function* streamSSE(res, options: StreamSseOptions = {}) {
+    if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        throw new Error(`${res.status} ${res.statusText}: ${body.slice(0, 500)}`);
+    }
+    if (!res.body)
+        throw new Error("Empty response body");
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder("utf-8");
+    const envIdle = Number(process.env["FASTCODE_SSE_IDLE_MS"]);
+    const idleMs = positive(options.idleTimeoutMs, positive(envIdle, 25_000));
+    const totalMs = positive(options.totalTimeoutMs, 0);
+    const startedAt = Date.now();
+    let bytesReceived = 0;
+    let buffer = "";
+    while (true) {
+        const remaining = totalMs > 0 ? totalMs - (Date.now() - startedAt) : Number.POSITIVE_INFINITY;
+        if (remaining <= 0)
+            throw new NetworkStallError(`SSE total timeout after ${totalMs}ms`, bytesReceived);
+        const boundedByTotal = remaining <= idleMs;
+        const waitMs = boundedByTotal ? Math.max(1, remaining) : idleMs;
+        let timer: ReturnType<typeof setTimeout> | undefined;
+        const timeout = new Promise<never>((_resolve, reject) => {
+            timer = setTimeout(() => {
+                reject(new NetworkStallError(boundedByTotal
+                    ? `SSE total timeout after ${totalMs}ms`
+                    : `SSE idle timeout after ${idleMs}ms (no data received; set FASTCODE_SSE_IDLE_MS to wait longer)`, bytesReceived));
+            }, waitMs);
+        });
+        let chunk;
+        try {
+            chunk = await Promise.race([reader.read(), timeout]);
+        }
+        catch (err) {
+            await reader.cancel().catch(() => undefined);
+            throw err;
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+        const { value, done } = chunk;
+        if (done)
+            break;
+        bytesReceived += value?.byteLength ?? 0;
+        // Normalize CR/LF so both "\n\n" and "\r\n\r\n" frame separators
+        // are detected, including a CR/LF split across two chunks.
+        buffer = (buffer + decoder.decode(value, { stream: true })).replace(/\r\n?/g, "\n");
+        let sep = buffer.indexOf("\n\n");
+        while (sep !== -1) {
+            const chunkText = buffer.slice(0, sep);
+            buffer = buffer.slice(sep + 2);
+            const ev = parseSseChunk(chunkText);
+            if (ev)
+                yield ev;
+            sep = buffer.indexOf("\n\n");
+        }
+    }
+    // Flush trailing event without final \n\n (some servers do this).
+    const trailing = buffer.trim();
+    if (trailing) {
+        const ev = parseSseChunk(trailing);
+        if (ev)
+            yield ev;
+    }
+}
+export async function probeConnectivity(url: string, timeoutMs = 3000): Promise<boolean> {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), positive(timeoutMs, 3000));
+    try {
+        const res = await fetch(url, { signal: controller.signal });
+        await res.body?.cancel().catch(() => undefined);
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function positive(value, fallback) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : fallback;
+}
+function parseSseChunk(chunk) {
+    let event;
+    const dataLines = [];
+    for (const lineRaw of chunk.split("\n")) {
+        const line = lineRaw.replace(/\r$/, "");
+        if (!line || line.startsWith(":"))
+            continue;
+        if (line.startsWith("event:"))
+            event = line.slice(6).trim();
+        else if (line.startsWith("data:"))
+            dataLines.push(line.slice(5).trimStart());
+    }
+    if (dataLines.length === 0)
+        return undefined;
+    return { event, data: dataLines.join("\n") };
+}

package/src/lib/markdown.ts

@@ -0,0 +1,32 @@
+/**
+ * Markdown → ANSI rendering for terminal output.
+ *
+ * We use marked + marked-terminal because it gives us proper code-fence
+ * syntax highlighting (via cli-highlight) without us hand-rolling a
+ * markdown parser. The result is a fully-formatted ANSI string we can
+ * print directly inside an Ink <Text>.
+ */
+import { marked } from "marked";
+import { markedTerminal } from "marked-terminal";
+let configured = false;
+function configure() {
+    if (configured)
+        return;
+    marked.use(markedTerminal({
+        reflowText: false,
+        tab: 2,
+    }) as any);
+    configured = true;
+}
+export function renderMarkdown(md) {
+    configure();
+    try {
+        const out = marked.parse(md) as string;
+        // marked-terminal sometimes appends a stray trailing newline; trim only
+        // trailing whitespace so we don't lose meaningful blank lines.
+        return out.replace(/\s+$/, "");
+    }
+    catch {
+        return md;
+    }
+}

package/src/lib/model-meta.ts

@@ -0,0 +1,138 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export interface ModelMeta {
+  contextWindow: number;
+  supportsTools: boolean;
+  charsPerToken: number;
+  maxOutputTokens?: number;
+}
+
+export interface EstTokenOptions {
+  providerId?: string;
+  model?: string;
+  charsPerToken?: number;
+}
+
+export const UNKNOWN_MODEL_META: ModelMeta = {
+  contextWindow: 32_768,
+  supportsTools: false,
+  charsPerToken: 2.5,
+};
+
+const PROVIDER_META: Record<string, ModelMeta> = {
+  anthropic: { contextWindow: 1_000_000, supportsTools: true, charsPerToken: 3.8, maxOutputTokens: 64_000 },
+  openai: { contextWindow: 400_000, supportsTools: true, charsPerToken: 3.8, maxOutputTokens: 32_000 },
+  google: { contextWindow: 1_048_576, supportsTools: true, charsPerToken: 3.6, maxOutputTokens: 65_536 },
+  deepseek: { contextWindow: 128_000, supportsTools: true, charsPerToken: 1.7, maxOutputTokens: 8_192 },
+  openrouter: { contextWindow: 128_000, supportsTools: true, charsPerToken: 2.5, maxOutputTokens: 16_384 },
+  groq: { contextWindow: 128_000, supportsTools: true, charsPerToken: 3.8, maxOutputTokens: 8_192 },
+  mistral: { contextWindow: 128_000, supportsTools: true, charsPerToken: 3.8, maxOutputTokens: 8_192 },
+  xai: { contextWindow: 256_000, supportsTools: true, charsPerToken: 3.8, maxOutputTokens: 16_384 },
+  moonshot: { contextWindow: 256_000, supportsTools: true, charsPerToken: 2.0, maxOutputTokens: 16_384 },
+  zhipu: { contextWindow: 128_000, supportsTools: true, charsPerToken: 1.7, maxOutputTokens: 8_192 },
+  qwen: { contextWindow: 128_000, supportsTools: true, charsPerToken: 1.7, maxOutputTokens: 8_192 },
+  ollama: { contextWindow: 32_768, supportsTools: true, charsPerToken: 2.5, maxOutputTokens: 4_096 },
+  custom: { contextWindow: 32_768, supportsTools: false, charsPerToken: 2.5 },
+};
+
+const MODEL_OVERRIDES: Record<string, Partial<ModelMeta>> = {
+  "claude-haiku-5.5": { contextWindow: 200_000 },
+  "claude-haiku-4.5": { contextWindow: 200_000 },
+  "claude-sonnet-5": { contextWindow: 1_000_000 },
+  "claude-opus-5": { contextWindow: 1_000_000 },
+  "claude-sonnet-4.6": { contextWindow: 1_000_000 },
+  "claude-opus-4.6": { contextWindow: 1_000_000 },
+  "gpt-4o": { contextWindow: 128_000 },
+  "gpt-4o-mini": { contextWindow: 128_000 },
+  "gpt-4.1": { contextWindow: 1_000_000 },
+  o3: { contextWindow: 200_000 },
+  "o4-mini": { contextWindow: 200_000 },
+  "gemini-3.5-flash-lite": { contextWindow: 1_048_576 },
+  "gemini-3.1-flash-lite": { contextWindow: 1_048_576 },
+  "deepseek-v4-pro": { contextWindow: 128_000, charsPerToken: 1.7 },
+  "deepseek-flash": { contextWindow: 128_000, charsPerToken: 1.7 },
+  "glm-5.3": { contextWindow: 128_000, charsPerToken: 1.7 },
+  "glm-5.2": { contextWindow: 128_000, charsPerToken: 1.7 },
+  "qwen3.8-max": { contextWindow: 128_000, charsPerToken: 1.7 },
+  "qwen3.8-flash": { contextWindow: 128_000, charsPerToken: 1.7 },
+  "kimi-k3": { contextWindow: 256_000, charsPerToken: 2.0 },
+  "grok-4.7": { contextWindow: 256_000, charsPerToken: 3.8 },
+  "mistral-large-latest": { contextWindow: 128_000, charsPerToken: 3.8 },
+};
+
+let overrideCache: Record<string, Partial<ModelMeta>> | undefined;
+
+export function modelMetaOverridePath(): string {
+  const root = process.env["FASTCODE_HOME"] ?? join(homedir(), ".fastcode");
+  return join(root, "model-meta.json");
+}
+
+export function clearModelMetaCache(): void {
+  overrideCache = undefined;
+}
+
+function loadOverrides(): Record<string, Partial<ModelMeta>> {
+  if (overrideCache)
+    return overrideCache;
+  const file = modelMetaOverridePath();
+  if (!existsSync(file)) {
+    overrideCache = {};
+    return overrideCache;
+  }
+  try {
+    const raw = JSON.parse(readFileSync(file, "utf8"));
+    overrideCache = raw && typeof raw === "object" && !Array.isArray(raw) ? raw : {};
+  }
+  catch {
+    overrideCache = {};
+  }
+  return overrideCache;
+}
+
+function usable(meta: Partial<ModelMeta> | undefined): meta is Partial<ModelMeta> {
+  return Boolean(meta) && typeof meta === "object";
+}
+
+function apply(base: ModelMeta, ...layers: Array<Partial<ModelMeta> | undefined>): ModelMeta {
+  const next = { ...base };
+  for (const layer of layers) {
+    if (!usable(layer))
+      continue;
+    if (typeof layer.contextWindow === "number" && layer.contextWindow > 0)
+      next.contextWindow = Math.floor(layer.contextWindow);
+    if (typeof layer.charsPerToken === "number" && layer.charsPerToken > 0)
+      next.charsPerToken = layer.charsPerToken;
+    if (typeof layer.supportsTools === "boolean")
+      next.supportsTools = layer.supportsTools;
+    if (typeof layer.maxOutputTokens === "number" && layer.maxOutputTokens > 0)
+      next.maxOutputTokens = Math.floor(layer.maxOutputTokens);
+  }
+  return next;
+}
+
+export function getModelMeta(providerId?: string, model?: string): ModelMeta {
+  const provider = providerId && PROVIDER_META[providerId] ? PROVIDER_META[providerId] : UNKNOWN_MODEL_META;
+  const overrides = loadOverrides();
+  const keys = [
+    providerId && model ? `${providerId}/${model}` : undefined,
+    providerId && model ? `${providerId}::${model}` : undefined,
+    model,
+  ].filter((key): key is string => Boolean(key));
+  const layers = keys.map((key) => overrides[key]);
+  return apply(provider, model ? MODEL_OVERRIDES[model] : undefined, ...layers);
+}
+
+export function estTokens(text: string, options: number | EstTokenOptions = {}): number {
+  if (!text)
+    return 0;
+  const ratio = typeof options === "number"
+    ? options
+    : options.charsPerToken ?? getModelMeta(options.providerId, options.model).charsPerToken;
+  return Math.ceil(text.length / Math.max(0.1, ratio));
+}
+
+export function estMessagesTokens(messages: Array<{ content: string }>, options: EstTokenOptions = {}): number {
+  return messages.reduce((sum, message) => sum + estTokens(message.content ?? "", options), 0);
+}

package/src/lib/native-tools.ts

@@ -0,0 +1,32 @@
+import type { NativeToolCall } from "../types.js";
+
+export type ToolCallAccumulator = Map<number, NativeToolCall>;
+
+export interface ToolCallDelta {
+    index?: number;
+    id?: string;
+    function?: { name?: string; arguments?: string };
+}
+
+export function mergeToolCallDelta(accumulator: ToolCallAccumulator, delta: ToolCallDelta): void {
+    const index = typeof delta.index === "number" && Number.isFinite(delta.index) ? delta.index : accumulator.size;
+    const entry = accumulator.get(index) ?? { id: "", name: "", arguments: "" };
+    if (typeof delta.id === "string" && delta.id)
+        entry.id = delta.id;
+    if (typeof delta.function?.name === "string" && delta.function.name)
+        entry.name = delta.function.name;
+    if (typeof delta.function?.arguments === "string")
+        entry.arguments += delta.function.arguments;
+    accumulator.set(index, entry);
+}
+
+export function finalizeToolCalls(accumulator: ToolCallAccumulator): NativeToolCall[] {
+    return Array.from(accumulator.entries())
+        .sort((a, b) => a[0] - b[0])
+        .filter(([, call]) => Boolean(call.name))
+        .map(([index, call]) => ({
+            id: call.id || `call_${index}`,
+            name: call.name,
+            arguments: call.arguments || "{}",
+        }));
+}