@phnx-labs/agents-cli 1.20.14 → 1.20.16

package/dist/lib/session/sync/sync.js

@@ -0,0 +1,251 @@
+/**
+ * Cross-machine session sync orchestration.
+ *
+ *  PUSH  this machine's transcripts (changed since last tick) to its own R2
+ *        prefix, then publish a manifest. Single-writer prefixes mean no two
+ *        machines ever write the same object — zero remote contention.
+ *
+ *  PULL  every other machine's manifest, fetch changed transcripts, CRDT-union
+ *        copies of the same session, and write the result into the local mirror
+ *        (a scan root). The existing scanner indexes it; sessions present in the
+ *        live home always win, so the mirror only fills in remote-origin sessions.
+ *
+ * Invariants:
+ *  - Live home transcripts are only ever READ + uploaded, never rewritten.
+ *  - Union is idempotent, so once sets match nothing is transferred (quiescence).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { R2Client } from './r2.js';
+import { loadR2Config, machineId } from './config.js';
+import { SYNC_AGENTS, listLocalTranscripts, localSessionIds, mirrorPath, objectKey, manifestKey, SESSIONS_PREFIX, } from './agents.js';
+import { mergeTranscripts, transcriptStats } from './crdt.js';
+import { emptyManifest, parseManifest, hashContent, loadLedger, saveLedger, ledgerUnchanged, ledgerRecord, loadLocalManifest, saveLocalManifest, loadPullState, savePullState, sourceSignature, } from './manifest.js';
+const nowIso = () => new Date().toISOString();
+function specById(id) {
+    return SYNC_AGENTS.find(s => s.id === id);
+}
+/** Upload this machine's changed transcripts and publish its manifest. */
+async function pushOwn(r2, me, opts, result) {
+    const ledger = loadLedger();
+    const prev = loadLocalManifest();
+    const manifest = emptyManifest(me, nowIso());
+    for (const spec of SYNC_AGENTS) {
+        const agentManifest = {};
+        for (const t of listLocalTranscripts(spec)) {
+            let stat;
+            try {
+                stat = fs.statSync(t.absPath);
+            }
+            catch {
+                continue;
+            }
+            const prevEntry = prev?.agents?.[spec.id]?.[t.sessionId];
+            if (prevEntry && ledgerUnchanged(ledger, t.absPath, stat.size, stat.mtimeMs)) {
+                agentManifest[t.sessionId] = prevEntry; // unchanged: reuse, no read, no upload
+                result.pushSkipped++;
+                continue;
+            }
+            let content;
+            try {
+                content = fs.readFileSync(t.absPath, 'utf-8');
+            }
+            catch {
+                continue;
+            }
+            const hash = hashContent(content);
+            const { lastTs } = transcriptStats(content);
+            const entry = { relKey: t.relKey, size: stat.size, hash, lastTs };
+            try {
+                await r2.put(objectKey(me, spec.id, t.sessionId), content, 'application/x-ndjson');
+                ledgerRecord(ledger, t.absPath, stat.size, stat.mtimeMs, hash);
+                agentManifest[t.sessionId] = entry;
+                result.pushed++;
+                if (opts.verbose)
+                    opts.log?.(`  push ${spec.id}/${t.sessionId.slice(0, 8)} (${stat.size}B)`);
+            }
+            catch (err) {
+                result.errors.push(`push ${spec.id}/${t.sessionId}: ${err.message}`);
+            }
+        }
+        if (Object.keys(agentManifest).length > 0)
+            manifest.agents[spec.id] = agentManifest;
+    }
+    try {
+        await r2.put(manifestKey(me), JSON.stringify(manifest), 'application/json');
+        saveLocalManifest(manifest);
+        saveLedger(ledger);
+    }
+    catch (err) {
+        result.errors.push(`manifest publish: ${err.message}`);
+    }
+}
+/**
+ * Decide which remote sessions need fetching this tick. Pure: no I/O.
+ * Skips sessions we hold locally (home wins) and sessions whose source set is
+ * unchanged since we last materialized them (pull-state hit → quiescence).
+ */
+export function selectSessionsToFetch(copies, localIdsByAgent, pullState) {
+    const pending = [];
+    for (const [agentId, byAgent] of copies) {
+        const localIds = localIdsByAgent.get(agentId) ?? new Set();
+        for (const [sessionId, list] of byAgent) {
+            if (localIds.has(sessionId))
+                continue;
+            const sig = sourceSignature(list.map(c => c.entry.hash));
+            if (pullState[`${agentId}/${sessionId}`] === sig)
+                continue;
+            pending.push({ agentId, sessionId, copies: list, sig });
+        }
+    }
+    return pending;
+}
+/**
+ * Resolve the mirror destination + merged content for one session. Pure.
+ * The canonical path comes from the lexicographically-smallest machine so every
+ * puller derives an identical location; the content is the CRDT union of copies.
+ */
+export function resolveMirrorWrite(spec, copies, contents) {
+    const canonical = [...copies].sort((a, b) => (a.machine < b.machine ? -1 : a.machine > b.machine ? 1 : 0))[0];
+    const content = contents.length === 1 ? contents[0] : mergeTranscripts(contents);
+    return {
+        dest: mirrorPath(spec, canonical.machine, canonical.entry.relKey),
+        content,
+        merged: contents.length > 1,
+    };
+}
+/**
+ * Decide how to reconcile one session's fetched copies. Pure: no I/O.
+ *
+ * `fetched` is positionally aligned to `copies` — a `null` slot means that
+ * copy's object wasn't retrievable this tick (R2 404 / LIST→GET consistency
+ * lag / a transient get error). If ANY listed copy is missing, returns `null`:
+ * the caller must then skip the mirror write AND skip stamping pull-state, so
+ * the session is retried next tick. Writing a partial set instead would
+ * materialize a non-converged union and — because pull-state would record the
+ * full source signature — abandon the missing branch forever (the bug this
+ * guards: a signature match in selectSessionsToFetch never re-fetches it).
+ */
+export function reconcileCopies(spec, copies, fetched) {
+    const contents = [];
+    for (const text of fetched) {
+        if (text === null)
+            return null; // incomplete fetch — retry next tick
+        contents.push(text);
+    }
+    if (contents.length === 0)
+        return null;
+    return resolveMirrorWrite(spec, copies, contents);
+}
+/** Fetch other machines' manifests, union changed sessions into the mirror. */
+async function pullAndReconcile(r2, me, opts, result) {
+    const prefixes = await r2.listPrefixes(SESSIONS_PREFIX); // sessions/<machine>/
+    const machines = prefixes
+        .map(p => p.slice(SESSIONS_PREFIX.length).replace(/\/$/, ''))
+        .filter(m => m && m !== me);
+    // agentId -> sessionId -> copies across machines
+    const copies = new Map();
+    for (const m of machines) {
+        let manifest = null;
+        try {
+            const text = await r2.get(manifestKey(m));
+            manifest = text ? parseManifest(text) : null;
+        }
+        catch (err) {
+            result.errors.push(`fetch manifest ${m}: ${err.message}`);
+        }
+        if (!manifest)
+            continue;
+        for (const [agentId, sessions] of Object.entries(manifest.agents)) {
+            if (!specById(agentId))
+                continue;
+            let byAgent = copies.get(agentId);
+            if (!byAgent)
+                copies.set(agentId, (byAgent = new Map()));
+            for (const [sessionId, entry] of Object.entries(sessions)) {
+                const list = byAgent.get(sessionId) ?? [];
+                list.push({ machine: m, entry });
+                byAgent.set(sessionId, list);
+            }
+        }
+    }
+    const pullState = loadPullState();
+    const localIdsByAgent = new Map();
+    for (const agentId of copies.keys()) {
+        const spec = specById(agentId);
+        if (spec)
+            localIdsByAgent.set(agentId, localSessionIds(spec));
+    }
+    const pending = selectSessionsToFetch(copies, localIdsByAgent, pullState);
+    let candidates = 0;
+    for (const byAgent of copies.values())
+        candidates += byAgent.size;
+    result.pullSkipped += candidates - pending.length; // local-owned or unchanged
+    for (const { agentId, sessionId, copies: list, sig } of pending) {
+        const spec = specById(agentId);
+        // Download each copy (could be a fork across >1 machine), keeping the
+        // result positionally aligned to `list` — null marks a copy we couldn't
+        // fetch this tick (404 / consistency lag / error).
+        const fetched = [];
+        for (const c of list) {
+            try {
+                fetched.push(await r2.get(objectKey(c.machine, agentId, sessionId)));
+            }
+            catch (err) {
+                result.errors.push(`get ${c.machine}/${sessionId}: ${err.message}`);
+                fetched.push(null);
+            }
+        }
+        // null ⇒ an incomplete fetch: skip the write AND the pull-state stamp so we
+        // retry next tick instead of persisting a partial union / abandoning a branch.
+        const resolved = reconcileCopies(spec, list, fetched);
+        if (!resolved)
+            continue;
+        const { dest, content, merged } = resolved;
+        try {
+            let existing = null;
+            try {
+                existing = fs.readFileSync(dest, 'utf-8');
+            }
+            catch { /* not present yet */ }
+            if (existing !== content) {
+                fs.mkdirSync(path.dirname(dest), { recursive: true });
+                fs.writeFileSync(dest, content, 'utf-8');
+                if (merged)
+                    result.merged++;
+                result.pulled++;
+                if (opts.verbose) {
+                    opts.log?.(`  pull ${agentId}/${sessionId.slice(0, 8)} <- ${list.map(c => c.machine).join('+')}`);
+                }
+            }
+            else {
+                result.pullSkipped++;
+            }
+            pullState[`${agentId}/${sessionId}`] = sig;
+        }
+        catch (err) {
+            result.errors.push(`write mirror ${sessionId}: ${err.message}`);
+        }
+    }
+    savePullState(pullState);
+}
+/** Run one full sync cycle: push this machine's changes, pull everyone else's. */
+export async function syncSessions(opts = {}) {
+    const cfg = loadR2Config();
+    const me = machineId();
+    const r2 = new R2Client(cfg);
+    const result = {
+        machine: me,
+        pushed: 0,
+        pushSkipped: 0,
+        pulled: 0,
+        merged: 0,
+        pullSkipped: 0,
+        errors: [],
+    };
+    if (opts.push !== false)
+        await pushOwn(r2, me, opts, result);
+    if (opts.pull !== false)
+        await pullAndReconcile(r2, me, opts, result);
+    return result;
+}

package/dist/lib/shims.d.ts

@@ -77,7 +77,7 @@ export interface ConflictInfo {
  *         top-level entry add/remove — deep edits to plugin contents won't
  *         trigger auto-resync, run `agents sync` for that.
  */
-export declare const SHIM_SCHEMA_VERSION = 18;
+export declare const SHIM_SCHEMA_VERSION = 19;
 /**
  * Generate the full bash shim script for the given agent. The returned string
  * is written to ~/.agents/shims/{cliCommand} and made executable.

package/dist/lib/shims.js

@@ -202,7 +202,7 @@ async function promptConflictStrategy(conflictInfos) {
  *         top-level entry add/remove — deep edits to plugin contents won't
  *         trigger auto-resync, run `agents sync` for that.
  */
-export const SHIM_SCHEMA_VERSION = 18;
+export const SHIM_SCHEMA_VERSION = 19;
 /** Internal marker string used to embed the schema version in shim scripts. */
 const SHIM_VERSION_MARKER = 'agents-shim-version:';
 function shellQuote(value) {
@@ -414,6 +414,22 @@ elif [ "$AGENT" = "kimi" ]; then
     # Last resort: whatever is on PATH
     BINARY=$(command -v kimi 2>/dev/null || echo "")
   fi
+# Droid (Factory AI) special case: the official installer drops a standalone
+# native binary at ~/.local/bin/droid — there is no npm package and nothing
+# lands in node_modules/.bin. Resolve the fixed install path directly. The
+# PATH fallback explicitly refuses anything under our own shims dir: that path
+# IS this dispatcher, so exec'ing it would re-enter and spin in an infinite
+# re-exec loop (the bug this branch fixes).
+elif [ "$AGENT" = "droid" ]; then
+  DROID_BINARY="$HOME/.local/bin/droid"
+  if [ -x "$DROID_BINARY" ]; then
+    BINARY="$DROID_BINARY"
+  else
+    BINARY=$(command -v droid 2>/dev/null || echo "")
+    case "$BINARY" in
+      "$AGENTS_USER_DIR/.cache/shims/"*) BINARY="" ;;
+    esac
+  fi
 else
   BINARY="$VERSION_DIR/node_modules/.bin/$CLI_COMMAND"
 fi
@@ -685,7 +701,10 @@ export function ensureVersionedAliasCurrent(agent, version) {
         createVersionedAlias(agent, version);
         return 'created';
     }
-    if (!isVersionedAliasCurrent(agent, version)) {
+    // Upgrade-only (newest-wins), same rationale as ensureShimCurrent: never
+    // downgrade an alias stamped by a newer install sharing the shims dir.
+    const onDisk = readVersionedAliasSchemaVersion(agent, version);
+    if (onDisk === null || onDisk < VERSIONED_ALIAS_SCHEMA_VERSION) {
         createVersionedAlias(agent, version);
         return 'updated';
     }
@@ -1278,7 +1297,14 @@ export function ensureShimCurrent(agent) {
         createShim(agent);
         return 'created';
     }
-    if (!isShimCurrent(agent)) {
+    // Upgrade-only (newest-wins): regenerate only when the on-disk shim is
+    // unversioned/unreadable (null) or OLDER than this binary. Never downgrade a
+    // shim stamped by a NEWER agents-cli install. Two installs at different
+    // SHIM_SCHEMA_VERSION sharing ~/.agents/.cache/shims/ (e.g. a dev build on
+    // PATH alongside a Hermes-bundled published copy) otherwise ping-pong —
+    // rewriting every shim on each alternating launch and adding boot latency.
+    const onDisk = readShimSchemaVersion(agent);
+    if (onDisk === null || onDisk < SHIM_SCHEMA_VERSION) {
         createShim(agent);
         return 'updated';
     }

package/dist/lib/state.d.ts

@@ -247,6 +247,24 @@ export declare function recordVersionResources(_agent: AgentId, _version: string
  * Pass all resource types you want to initialize in one call to batch the write.
  */
 export declare function ensureVersionResourcePatterns(agent: AgentId, version: string, updates: Partial<Record<Exclude<keyof VersionResources, 'rulesPreset'>, ResourcePattern[]>>): void;
+/**
+ * Insert `<alias>:*` at the canonical position (after the system/user/other-extra
+ * includes, before `project:*`), unless the alias is already referenced — as an
+ * include (`alias:...`) or an exclude (`!alias:...`). Returns a new array when it
+ * changes, otherwise the same reference (so callers can detect no-ops cheaply).
+ */
+export declare function withAlias(list: ResourcePattern[], alias: string): ResourcePattern[];
+/** Strip every reference to `<alias>:...` / `!<alias>:...` from a selector list. */
+export declare function withoutAlias(list: ResourcePattern[], alias: string): ResourcePattern[];
+/**
+ * Backfill (add=true) or strip (add=false) an extra-repo alias across every
+ * already-installed version's selectors. New versions get the alias via
+ * `defaultPatterns()` at scaffold time; this keeps existing versions in sync
+ * when an extra repo is registered/enabled or removed. Only touches selector
+ * lists that are already set — an unset list is left for `defaultPatterns()`.
+ * Returns the number of (agent, version) pairs changed.
+ */
+export declare function applyExtraAliasToVersions(alias: string, add: boolean): number;
 export declare function getVersionResources(agent: AgentId, version: string): VersionResources | null;
 /** Active rules preset for an agent@version. Defaults to "default" when unset. */
 export declare function getActiveRulesPreset(agent: AgentId, version: string): string;

package/dist/lib/state.js

@@ -711,6 +711,79 @@ export function ensureVersionResourcePatterns(agent, version, updates) {
     if (changed)
         writeMeta(meta);
 }
+/**
+ * Resource types that resolve across the extra-repo layer. Mirrors
+ * `defaultPatterns()`: extras feed commands/skills/hooks/subagents/plugins/
+ * workflows, but never permissions (`system:*`) or mcp (`user:*`).
+ */
+const EXTRA_ELIGIBLE_TYPES = [
+    'commands', 'skills', 'hooks', 'subagents', 'plugins', 'workflows',
+];
+/**
+ * Insert `<alias>:*` at the canonical position (after the system/user/other-extra
+ * includes, before `project:*`), unless the alias is already referenced — as an
+ * include (`alias:...`) or an exclude (`!alias:...`). Returns a new array when it
+ * changes, otherwise the same reference (so callers can detect no-ops cheaply).
+ */
+export function withAlias(list, alias) {
+    const prefix = `${alias}:`;
+    if (list.some(p => p === `${alias}:*` || p.startsWith(prefix) || p.startsWith(`!${prefix}`))) {
+        return list;
+    }
+    const next = [...list];
+    const projIdx = next.findIndex(p => p === 'project:*' || p.startsWith('project:'));
+    if (projIdx >= 0)
+        next.splice(projIdx, 0, `${alias}:*`);
+    else
+        next.push(`${alias}:*`);
+    return next;
+}
+/** Strip every reference to `<alias>:...` / `!<alias>:...` from a selector list. */
+export function withoutAlias(list, alias) {
+    const prefix = `${alias}:`;
+    const next = list.filter(p => !(p.startsWith(prefix) || p.startsWith(`!${prefix}`)));
+    return next.length === list.length ? list : next;
+}
+/**
+ * Backfill (add=true) or strip (add=false) an extra-repo alias across every
+ * already-installed version's selectors. New versions get the alias via
+ * `defaultPatterns()` at scaffold time; this keeps existing versions in sync
+ * when an extra repo is registered/enabled or removed. Only touches selector
+ * lists that are already set — an unset list is left for `defaultPatterns()`.
+ * Returns the number of (agent, version) pairs changed.
+ */
+export function applyExtraAliasToVersions(alias, add) {
+    const meta = readMeta();
+    if (!meta.versions)
+        return 0;
+    let changed = false;
+    let count = 0;
+    for (const versions of Object.values(meta.versions)) {
+        if (!versions)
+            continue;
+        for (const vr of Object.values(versions)) {
+            if (!vr)
+                continue;
+            let touched = false;
+            for (const type of EXTRA_ELIGIBLE_TYPES) {
+                const cur = vr[type];
+                if (!Array.isArray(cur) || cur.length === 0)
+                    continue;
+                const next = add ? withAlias(cur, alias) : withoutAlias(cur, alias);
+                if (next !== cur) {
+                    vr[type] = next;
+                    touched = true;
+                    changed = true;
+                }
+            }
+            if (touched)
+                count++;
+        }
+    }
+    if (changed)
+        writeMeta(meta);
+    return count;
+}
 export function getVersionResources(agent, version) {
     const meta = readMeta();
     return meta.versions?.[agent]?.[version] || null;

package/dist/lib/teams/parsers.js

@@ -2,7 +2,7 @@
  * Agent event stream parsers.
  *
  * Normalizes the heterogeneous JSON event formats emitted by each agent CLI
- * (Claude, Codex, Gemini, Cursor, OpenCode, Grok, Antigravity) into a unified
+ * (Claude, Codex, Gemini, Cursor, OpenCode, Grok, Antigravity, Kimi) into a unified
  * event schema with consistent types: init, message, tool_use, bash,
  * file_read, file_write, file_create, file_delete, result, error, and others.
  */
@@ -31,6 +31,9 @@ export function normalizeEvents(agentType, raw) {
     else if (agentType === 'antigravity') {
         return normalizeAntigravity(raw);
     }
+    else if (agentType === 'kimi') {
+        return normalizeKimi(raw);
+    }
     // droid (Factory AI) intentionally falls through to the generic normalizer
     // below: its `-o stream-json` JSONL event schema is not yet verified against
     // a live run (the documented `debug` format differs from stream-json). Events
@@ -908,6 +911,161 @@ function normalizeGrok(raw) {
             timestamp: timestamp,
         }];
 }
+// --- Kimi parsing ---
+// Kimi's `--output-format stream-json` emits one JSON object per line with a
+// simple `role`-based schema:
+//   - {"role":"assistant","content":"..."}                          → final message
+//   - {"role":"assistant","tool_calls":[{"function":{"name":"Bash","arguments":"<json>"}}]} → tool use
+//   - {"role":"tool","tool_call_id":"...","content":"..."}            → tool result
+//   - {"role":"meta","type":"session.resume_hint","session_id":"..."} → init / session id
+// Tool arguments are JSON-stringified inside `function.arguments` and must be
+// parsed before extracting paths/commands. Verified against live `kimi` runs.
+function normalizeKimi(raw) {
+    const timestamp = new Date().toISOString();
+    if (!raw || typeof raw !== 'object') {
+        return [{
+                type: 'unknown',
+                agent: 'kimi',
+                raw: raw,
+                timestamp: timestamp,
+            }];
+    }
+    const role = typeof raw.role === 'string' ? raw.role : '';
+    // Assistant message (final answer or tool-call request).
+    if (role === 'assistant') {
+        const events = [];
+        if (typeof raw.content === 'string' && raw.content) {
+            events.push({
+                type: 'message',
+                agent: 'kimi',
+                content: raw.content,
+                complete: true,
+                timestamp: timestamp,
+            });
+        }
+        const toolCalls = Array.isArray(raw.tool_calls) ? raw.tool_calls : [];
+        for (const toolCall of toolCalls) {
+            const fn = toolCall?.function || {};
+            const toolName = typeof fn.name === 'string' ? fn.name : 'unknown';
+            let toolArgs = {};
+            if (typeof fn.arguments === 'string') {
+                try {
+                    toolArgs = JSON.parse(fn.arguments);
+                }
+                catch {
+                    toolArgs = { _raw: fn.arguments };
+                }
+            }
+            else if (fn.arguments && typeof fn.arguments === 'object') {
+                toolArgs = fn.arguments;
+            }
+            const filePath = toolArgs?.path || toolArgs?.file_path || '';
+            const command = toolArgs?.command || '';
+            // Map known tools to structured events. If a known tool is missing the
+            // fields we need (e.g. unparseable arguments), fall back to tool_use so
+            // the event is still visible in summaries rather than dropped.
+            let normalized = null;
+            if (toolName === 'Bash' && command) {
+                const bashEvents = [{
+                        type: 'bash',
+                        agent: 'kimi',
+                        tool: toolName,
+                        command: command,
+                        timestamp: timestamp,
+                    }];
+                const [filesRead, filesWritten, filesDeleted] = extractFileOpsFromBash(command);
+                for (const p of filesRead) {
+                    bashEvents.push({ type: 'file_read', agent: 'kimi', tool: 'bash', path: p, command, timestamp });
+                }
+                for (const p of filesWritten) {
+                    bashEvents.push({ type: 'file_write', agent: 'kimi', tool: 'bash', path: p, command, timestamp });
+                }
+                for (const p of filesDeleted) {
+                    bashEvents.push({ type: 'file_delete', agent: 'kimi', tool: 'bash', path: p, command, timestamp });
+                }
+                normalized = bashEvents;
+            }
+            else if (toolName === 'Read' && filePath) {
+                normalized = [{
+                        type: 'file_read',
+                        agent: 'kimi',
+                        tool: toolName,
+                        path: filePath,
+                        timestamp: timestamp,
+                    }];
+            }
+            else if (toolName === 'Edit' && filePath) {
+                normalized = [{
+                        type: 'file_write',
+                        agent: 'kimi',
+                        tool: toolName,
+                        path: filePath,
+                        timestamp: timestamp,
+                    }];
+            }
+            else if (toolName === 'Write' && filePath) {
+                normalized = [{
+                        type: 'file_create',
+                        agent: 'kimi',
+                        tool: toolName,
+                        path: filePath,
+                        timestamp: timestamp,
+                    }];
+            }
+            if (normalized) {
+                events.push(...normalized);
+            }
+            else {
+                events.push({
+                    type: 'tool_use',
+                    agent: 'kimi',
+                    tool: toolName,
+                    args: toolArgs,
+                    timestamp: timestamp,
+                });
+            }
+        }
+        return events.length > 0 ? events : [];
+    }
+    // Tool result (response to an assistant tool_call).
+    if (role === 'tool') {
+        const content = typeof raw.content === 'string' ? raw.content : '';
+        const success = raw.isError !== true && !(content && content.startsWith('Error:'));
+        return [{
+                type: 'tool_result',
+                agent: 'kimi',
+                tool_call_id: typeof raw.tool_call_id === 'string' ? raw.tool_call_id : null,
+                success: success,
+                content: content,
+                timestamp: timestamp,
+            }];
+    }
+    // Meta events (session lifecycle).
+    if (role === 'meta') {
+        const metaType = typeof raw.type === 'string' ? raw.type : '';
+        if (metaType === 'session.resume_hint') {
+            return [{
+                    type: 'init',
+                    agent: 'kimi',
+                    session_id: typeof raw.session_id === 'string' ? raw.session_id : null,
+                    timestamp: timestamp,
+                }];
+        }
+        return [{
+                type: 'meta',
+                agent: 'kimi',
+                meta_type: metaType,
+                raw: raw,
+                timestamp: timestamp,
+            }];
+    }
+    return [{
+            type: raw.type || 'unknown',
+            agent: 'kimi',
+            raw: raw,
+            timestamp: timestamp,
+        }];
+}
 // --- Antigravity parsing ---
 // Intentionally conservative. Antigravity's `agy` binary advertises an
 // `--output-format json` flag in its docs, but the released binary errors with

package/dist/lib/usage.d.ts

@@ -85,6 +85,24 @@ export declare function getUsageInfoByIdentity(inputs: UsageIdentityInput[]): Pr
 export declare function getUsageInfoForIdentity(input: UsageIdentityInput): Promise<UsageInfo>;
 /** Format a one-line usage summary with compact bars for inline display. */
 export declare function formatUsageSummary(plan: string | null, snapshot: UsageSnapshot | null, planWidth?: number): string;
+/**
+ * Derive an account's real throttle state from its live usage windows — the
+ * same signal `agents usage` shows and balanced rotation trusts
+ * (`getRoutingUsedPercent` in rotate.ts). A window at 100% utilization means
+ * the account is throttled until that window resets.
+ *
+ * Returns `null` when there is no snapshot, so callers render no badge rather
+ * than a misleading one. This deliberately never consults
+ * `cachedExtraUsageDisabledReason`: that field describes why pay-as-you-go
+ * overage is disabled (`out_of_credits` = no overage credits purchased,
+ * `org_level_disabled` = an admin turned overage off), NOT whether the account
+ * can do work right now. A Pro account at 5% weekly usage with overage disabled
+ * is fully usable, yet that flag would mislabel it "out of credits".
+ *
+ * The model-specific `sonnet_week` sub-limit is excluded: hitting it throttles
+ * one model, not the account, so it shouldn't flip the whole row to throttled.
+ */
+export declare function deriveUsageStatusFromSnapshot(snapshot: UsageSnapshot | null | undefined): 'available' | 'rate_limited' | null;
 /**
  * Compact colored badge for the account's overall usage status. Renders only
  * when the account is throttled — `available` and `null` return ''.

package/dist/lib/usage.js

@@ -201,6 +201,31 @@ export function formatUsageSummary(plan, snapshot, planWidth = 3) {
     }
     return parts.join('  ');
 }
+/**
+ * Derive an account's real throttle state from its live usage windows — the
+ * same signal `agents usage` shows and balanced rotation trusts
+ * (`getRoutingUsedPercent` in rotate.ts). A window at 100% utilization means
+ * the account is throttled until that window resets.
+ *
+ * Returns `null` when there is no snapshot, so callers render no badge rather
+ * than a misleading one. This deliberately never consults
+ * `cachedExtraUsageDisabledReason`: that field describes why pay-as-you-go
+ * overage is disabled (`out_of_credits` = no overage credits purchased,
+ * `org_level_disabled` = an admin turned overage off), NOT whether the account
+ * can do work right now. A Pro account at 5% weekly usage with overage disabled
+ * is fully usable, yet that flag would mislabel it "out of credits".
+ *
+ * The model-specific `sonnet_week` sub-limit is excluded: hitting it throttles
+ * one model, not the account, so it shouldn't flip the whole row to throttled.
+ */
+export function deriveUsageStatusFromSnapshot(snapshot) {
+    if (!snapshot || snapshot.windows.length === 0)
+        return null;
+    const blocking = snapshot.windows.filter((window) => window.key !== 'sonnet_week');
+    const windows = blocking.length > 0 ? blocking : snapshot.windows;
+    const maxUsed = Math.max(...windows.map((window) => window.usedPercent));
+    return maxUsed >= 100 ? 'rate_limited' : 'available';
+}
 /**
  * Compact colored badge for the account's overall usage status. Renders only
  * when the account is throttled — `available` and `null` return ''.