@phnx-labs/agents-cli 1.21.2 → 1.21.3

package/dist/lib/git.js

@@ -371,6 +371,42 @@ export function readRepoState(repoPath) {
     const dirty = porcelain != null && porcelain.length > 0;
     return { branch, head, dirty };
 }
+/** Memoized per repoRoot — a resolveResource()/listResources()/plugin-discovery
+ *  call that touches many resources from the SAME DotAgents repo must not shell
+ *  out to git once per resource. */
+const _snapshotShaCache = new Map();
+/**
+ * The short HEAD sha of the git repo at `repoRoot` (`git -C <repoRoot>
+ * rev-parse --short HEAD`), for provenance — "which commit of this DotAgents
+ * repo was this resource/plugin resolved from". `undefined` when `repoRoot`
+ * isn't a git repo (or has no commits yet), never a throw.
+ *
+ * Deliberately synchronous + resolved once and cached: callers (resources.ts,
+ * plugins.ts) attach this as a lazy getter on the resolved object, so a
+ * consumer that never inspects provenance never pays for the git shell-out —
+ * see {@link ResolvedResource.snapshotSha} / {@link DiscoveredPlugin.snapshotSha}.
+ */
+export function resolveSnapshotSha(repoRoot) {
+    const cached = _snapshotShaCache.get(repoRoot);
+    if (cached !== undefined || _snapshotShaCache.has(repoRoot))
+        return cached;
+    let sha;
+    try {
+        const raw = execFileSync('git', ['-C', repoRoot, 'rev-parse', '--short', 'HEAD'], {
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).toString().trim();
+        sha = raw || undefined;
+    }
+    catch {
+        sha = undefined;
+    }
+    _snapshotShaCache.set(repoRoot, sha);
+    return sha;
+}
+/** Test seam: clear the memoized snapshot-sha cache between test cases. */
+export function _resetSnapshotShaCacheForTest() {
+    _snapshotShaCache.clear();
+}
 /**
  * Get the current GitHub username using gh CLI.
  * Returns null if gh is not installed or user is not authenticated.

package/dist/lib/hooks/profile.js

@@ -12,6 +12,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { getLogsDir } from '../state.js';
+import { percentile } from '../percentile.js';
 /**
  * Load every `hook.fire` event from the last `days` daily log files.
  * Lines that aren't JSON or aren't `hook.fire` events are silently skipped —
@@ -53,20 +54,6 @@ export function loadHookFireEvents(days = 7, logsDir = getLogsDir()) {
     }
     return events;
 }
-/** Percentile of a sorted-ascending array. p in [0,100]. Linear interpolation. */
-function percentile(sorted, p) {
-    if (sorted.length === 0)
-        return 0;
-    if (sorted.length === 1)
-        return sorted[0];
-    const rank = (p / 100) * (sorted.length - 1);
-    const lo = Math.floor(rank);
-    const hi = Math.ceil(rank);
-    if (lo === hi)
-        return sorted[lo];
-    const frac = rank - lo;
-    return sorted[lo] * (1 - frac) + sorted[hi] * frac;
-}
 /** Aggregate fire events into a per-hook profile, sorted by p99 desc. */
 export function aggregateHookProfile(events) {
     const byHook = new Map();

package/dist/lib/percentile.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Percentile of a sorted-ascending array, linear interpolation. p in [0,100].
+ *
+ * Deliberately its own file with zero imports: `perf/db.ts` (the SQLite
+ * warehouse), `hooks/profile.ts` (the legacy JSONL hook profile), and
+ * `routines.ts` (routineStats) all need this exact formula, but `routines.ts`
+ * and `hooks/profile.ts` must NOT pull in `perf/db.ts`'s `../sqlite.js`
+ * dependency just to round a percentile — sqlite is a heavier, perf-warehouse-
+ * specific dependency that has no business loading into every routines- or
+ * hooks-touching code path.
+ */
+export declare function percentile(sorted: number[], p: number): number;

package/dist/lib/percentile.js

@@ -0,0 +1,24 @@
+/**
+ * Percentile of a sorted-ascending array, linear interpolation. p in [0,100].
+ *
+ * Deliberately its own file with zero imports: `perf/db.ts` (the SQLite
+ * warehouse), `hooks/profile.ts` (the legacy JSONL hook profile), and
+ * `routines.ts` (routineStats) all need this exact formula, but `routines.ts`
+ * and `hooks/profile.ts` must NOT pull in `perf/db.ts`'s `../sqlite.js`
+ * dependency just to round a percentile — sqlite is a heavier, perf-warehouse-
+ * specific dependency that has no business loading into every routines- or
+ * hooks-touching code path.
+ */
+export function percentile(sorted, p) {
+    if (sorted.length === 0)
+        return 0;
+    if (sorted.length === 1)
+        return sorted[0];
+    const rank = (p / 100) * (sorted.length - 1);
+    const lo = Math.floor(rank);
+    const hi = Math.ceil(rank);
+    if (lo === hi)
+        return sorted[lo];
+    const frac = rank - lo;
+    return sorted[lo] * (1 - frac) + sorted[hi] * frac;
+}

package/dist/lib/perf/db.d.ts

@@ -8,14 +8,13 @@ import Database from '../sqlite.js';
 import type { AggregateOptions, PerfAggregateRow } from './types.js';
 export type { AggregateOptions, PerfAggregateRow, PerfSample } from './types.js';
 export { recordSample, shortSessionId, resolveSpoolPath } from './spool.js';
+export { percentile } from '../percentile.js';
 export declare const PERF_SCHEMA_VERSION = 1;
 export declare const DEFAULT_RETENTION_DAYS = 30;
 /** Test seam — redirect the warehouse path (like AGENTS_EVENTS_PATH). */
 export declare function _resetPerfDbForTest(overridePath?: string | null): void;
 /** Drain the NDJSON spool into samples. Idempotent; truncates on success. */
 export declare function drainSpool(db?: Database.Database): number;
-/** Percentile of a sorted-ascending array. p in [0,100]. */
-export declare function percentile(sorted: number[], p: number): number;
 /**
  * Aggregate samples by (kind, label) with p50/p95/p99. Drains the spool first.
  *

package/dist/lib/perf/db.js

@@ -10,8 +10,10 @@ import Database from '../sqlite.js';
 import { getPerfDbPath, getPerfDir } from '../state.js';
 import { localMachineId } from '../session/origin-machine.js';
 import { resolveProjectKey } from '../project-key.js';
+import { percentile } from '../percentile.js';
 import { resolveSpoolPath, shortSessionId, _resetPerfSpoolForTest } from './spool.js';
 export { recordSample, shortSessionId, resolveSpoolPath } from './spool.js';
+export { percentile } from '../percentile.js';
 export const PERF_SCHEMA_VERSION = 1;
 export const DEFAULT_RETENTION_DAYS = 30;
 const SCHEMA = `
@@ -186,20 +188,6 @@ function maybeRetain(db) {
         // ignore
     }
 }
-/** Percentile of a sorted-ascending array. p in [0,100]. */
-export function percentile(sorted, p) {
-    if (sorted.length === 0)
-        return 0;
-    if (sorted.length === 1)
-        return sorted[0];
-    const rank = (p / 100) * (sorted.length - 1);
-    const lo = Math.floor(rank);
-    const hi = Math.ceil(rank);
-    if (lo === hi)
-        return sorted[lo];
-    const frac = rank - lo;
-    return sorted[lo] * (1 - frac) + sorted[hi] * frac;
-}
 /**
  * Aggregate samples by (kind, label) with p50/p95/p99. Drains the spool first.
  *

package/dist/lib/plugins.js

@@ -14,7 +14,7 @@ import * as yaml from 'yaml';
 import { execFileSync } from 'child_process';
 import { getPluginsDir, getTrashPluginsDir, getExtraPluginsDir, getProjectPluginsDir, getSystemPluginsDir } from './state.js';
 import { IS_WINDOWS, isWindowsAbsolutePath, homeDir } from './platform/index.js';
-import { assertSafeGitTransport } from './git.js';
+import { assertSafeGitTransport, resolveSnapshotSha } from './git.js';
 import { listInstalledVersions, getVersionHomePath } from './versions.js';
 import { AGENTS, agentConfigDirName } from './agents.js';
 import { capableAgents, isCapable } from './capabilities.js';
@@ -90,6 +90,13 @@ export function discoverPlugins(opts = {}) {
     return out;
 }
 export function buildDiscoveredPlugin(pluginRoot, manifest, spec = { kind: 'user' }) {
+    // Every marketplace kind lays plugins out as `<repo>/plugins/<name>`, so the
+    // repo root is always the grandparent of pluginRoot — true for user
+    // (~/.agents), system (~/.agents/.system), each extra repo, and the project
+    // repo (<cwd>/.agents) alike. Deriving it here means every caller of
+    // buildDiscoveredPlugin (discoverPluginsInDir, inspectPluginCapabilities, …)
+    // gets provenance for free with no signature change.
+    const repoRoot = path.dirname(path.dirname(pluginRoot));
     return {
         name: manifest.name,
         root: pluginRoot,
@@ -107,6 +114,10 @@ export function buildDiscoveredPlugin(pluginRoot, manifest, spec = { kind: 'user
         monitors: discoverPluginMonitors(pluginRoot),
         hasMcp: fs.existsSync(path.join(pluginRoot, '.mcp.json')),
         hasSettings: pluginHasNonPermissionSettings(pluginRoot),
+        repoRoot,
+        get snapshotSha() {
+            return resolveSnapshotSha(repoRoot);
+        },
     };
 }
 /**

package/dist/lib/resources.d.ts

@@ -16,6 +16,22 @@ export interface ResolvedResource {
      * or the alias name (e.g. 'rush') for extra repos registered in agents.yaml.
      */
     source: string;
+    /**
+     * Absolute path to the DotAgents repo root this resource resolved from (the
+     * project/user/system/extra-repo dir — one level above the `kind`
+     * subdirectory). DotAgents repos are git-tracked (plugins.ts), so this pairs
+     * with {@link snapshotSha} to answer "which commit of which repo".
+     */
+    repoRoot: string;
+    /**
+     * Short HEAD sha of `repoRoot`'s git checkout, lazily resolved (a getter,
+     * not computed at construction) and memoized per repoRoot
+     * (`git.ts` `resolveSnapshotSha`) — a caller that never inspects provenance
+     * never pays for the git shell-out, and resolving many resources from the
+     * same repo pays for exactly one. `undefined` when `repoRoot` isn't a git
+     * repo (or has no commits).
+     */
+    readonly snapshotSha: string | undefined;
 }
 /**
  * True when `rawName` (a filename with its extension already stripped) names a

package/dist/lib/resources.js

@@ -15,6 +15,16 @@ import { WorkflowsHandler } from './resources/workflows.js';
 import { isCapable } from './capabilities.js';
 import { getProjectAgentsDir, getUserAgentsDir, getSystemAgentsDir, getEnabledExtraRepos, } from './state.js';
 import { isNameActiveInResourceProfile } from './resource-profiles.js';
+import { resolveSnapshotSha } from './git.js';
+/** Build a ResolvedResource with a lazy, memoized `snapshotSha` getter. */
+function withProvenance(base) {
+    return {
+        ...base,
+        get snapshotSha() {
+            return resolveSnapshotSha(base.repoRoot);
+        },
+    };
+}
 function profiledKind(kind) {
     switch (kind) {
         case 'commands':
@@ -70,19 +80,19 @@ export function resolveResource(kind, name, cwd) {
     const projectDir = getProjectAgentsDir(cwd);
     const extraRepos = getEnabledExtraRepos();
     const candidates = [
-        ...(projectDir ? [[path.join(projectDir, kind), 'project']] : []),
-        [path.join(getUserAgentsDir(), kind), 'user'],
-        [path.join(getSystemAgentsDir(), kind), 'system'],
-        ...extraRepos.map((e) => [path.join(e.dir, kind), e.alias]),
+        ...(projectDir ? [[path.join(projectDir, kind), 'project', projectDir]] : []),
+        [path.join(getUserAgentsDir(), kind), 'user', getUserAgentsDir()],
+        [path.join(getSystemAgentsDir(), kind), 'system', getSystemAgentsDir()],
+        ...extraRepos.map((e) => [path.join(e.dir, kind), e.alias, e.dir]),
     ];
-    for (const [dir, source] of candidates) {
+    for (const [dir, source, repoRoot] of candidates) {
         if (!fs.existsSync(dir))
             continue;
         // Try exact name (for directories like skills/subagents)
         const exactPath = path.join(dir, name);
         if (fs.existsSync(exactPath)) {
             if (resourceIsActive(kind, name, source)) {
-                return { name, path: exactPath, source };
+                return withProvenance({ name, path: exactPath, source, repoRoot });
             }
             continue;
         }
@@ -94,7 +104,7 @@ export function resolveResource(kind, name, cwd) {
             const withExt = exactPath + ext;
             if (fs.existsSync(withExt)) {
                 if (resourceIsActive(kind, name, source)) {
-                    return { name, path: withExt, source };
+                    return withProvenance({ name, path: withExt, source, repoRoot });
                 }
                 continue;
             }
@@ -113,12 +123,12 @@ export function listResources(kind, cwd) {
     const projectDir = getProjectAgentsDir(cwd);
     const extraRepos = getEnabledExtraRepos();
     const roots = [
-        ...(projectDir ? [[path.join(projectDir, kind), 'project']] : []),
-        [path.join(getUserAgentsDir(), kind), 'user'],
-        [path.join(getSystemAgentsDir(), kind), 'system'],
-        ...extraRepos.map((e) => [path.join(e.dir, kind), e.alias]),
+        ...(projectDir ? [[path.join(projectDir, kind), 'project', projectDir]] : []),
+        [path.join(getUserAgentsDir(), kind), 'user', getUserAgentsDir()],
+        [path.join(getSystemAgentsDir(), kind), 'system', getSystemAgentsDir()],
+        ...extraRepos.map((e) => [path.join(e.dir, kind), e.alias, e.dir]),
     ];
-    for (const [dir, source] of roots) {
+    for (const [dir, source, repoRoot] of roots) {
         if (!fs.existsSync(dir))
             continue;
         let entries;
@@ -143,11 +153,12 @@ export function listResources(kind, cwd) {
             if (!resourceIsActive(kind, rawName, source))
                 continue;
             seen.add(rawName);
-            results.push({
+            results.push(withProvenance({
                 name: rawName,
                 path: path.join(dir, entry.name),
                 source,
-            });
+                repoRoot,
+            }));
         }
     }
     return results;

package/dist/lib/routines.js

@@ -16,6 +16,7 @@ import { atomicWriteFileSync } from './fs-atomic.js';
 import { ALL_AGENT_IDS } from './agents.js';
 import { machineId, normalizeHost } from './machine-id.js';
 import { resolveActor } from './actor.js';
+import { percentile } from './percentile.js';
 export const HOST_STRATEGIES = ['local', 'host', 'fleet', 'cloud'];
 /** Canonical set of accepted GitHub trigger events — single source for validation. */
 export const GITHUB_TRIGGER_EVENTS = [
@@ -964,20 +965,6 @@ export function getLatestCompletedRun(jobName) {
     }
     return null;
 }
-/** Percentile of a sorted-ascending array (linear interpolation). p in [0,100]. */
-function percentile(sorted, p) {
-    if (sorted.length === 0)
-        return 0;
-    if (sorted.length === 1)
-        return sorted[0];
-    const rank = (p / 100) * (sorted.length - 1);
-    const lo = Math.floor(rank);
-    const hi = Math.ceil(rank);
-    if (lo === hi)
-        return sorted[lo];
-    const frac = rank - lo;
-    return sorted[lo] * (1 - frac) + sorted[hi] * frac;
-}
 /**
  * Fold a job's run history (`listRuns`) into a duration + outcome summary.
  * `missed` fires (no process ever ran) carry no `duration` and are excluded

package/dist/lib/runner.js

@@ -66,7 +66,14 @@ const ROUTINE_TRANSCRIPT_SPECS = {
     gemini: [{ root: ['.gemini', 'tmp'], ext: '.json' }],
     antigravity: [{ root: ['.gemini', 'antigravity-cli', 'conversations'], ext: '.db' }],
     droid: [{ root: ['.factory', 'sessions'], ext: '.jsonl' }],
-    kimi: [{ root: ['.kimi-code', 'sessions'], ext: '.json' }],
+    // Kimi splits a session across two files (session/discover.ts:4382-4384):
+    // state.json (title/timestamps) and agents/main/wire.jsonl (the actual
+    // conversation). Both extensions are needed — .json alone archives only
+    // the metadata shell and silently drops every message.
+    kimi: [
+        { root: ['.kimi-code', 'sessions'], ext: '.json' },
+        { root: ['.kimi-code', 'sessions'], ext: '.jsonl' },
+    ],
     grok: [{ root: ['.grok', 'sessions'], ext: '.json' }],
 };
 /** Stable working directory for routine children, independent of the daemon's launch cwd. */

package/dist/lib/session/db.d.ts

@@ -11,7 +11,7 @@ import type { SessionAgentId, SessionMeta } from './types.js';
 /** Current schema version; bumped when migrations are added. Exported so tests
  * assert against the constant instead of hardcoding a number that every bump
  * then has to chase (docs/05-sessions.md calls the constant the source of truth). */
-export declare const SCHEMA_VERSION = 22;
+export declare const SCHEMA_VERSION = 24;
 /** Raw row shape returned from the sessions table. */
 export interface SessionRow {
     id: string;
@@ -54,6 +54,9 @@ export interface SessionRow {
     linear_project_url: string | null;
     actor: string | null;
     initiated_by: string | null;
+    /** NULL means "not yet computed" (a row scanned before this field existed) — see rowToMeta. */
+    used_browser: number | null;
+    used_computer: number | null;
 }
 /** File stat snapshot used to detect changes between scan runs. */
 export interface ScanStamp {
@@ -88,6 +91,18 @@ export interface QueryOptions {
      * with NULLs sorted last so unpriced rows never crowd out real data.
      */
     sortBy?: 'timestamp' | 'cost' | 'duration';
+    /**
+     * Only sessions that invoked this skill (#12), joined against
+     * session_resource_usage.kind='skill'. Matches either the full stored name
+     * (bare, or `plugin:name` for a plugin skill) or just the short name after
+     * the colon — `--skill design` finds a session that used `rush:design`.
+     */
+    skill?: string;
+    /**
+     * Only sessions that used a skill or slash-command owned by this plugin
+     * (#12), joined against session_resource_usage.plugin.
+     */
+    plugin?: string;
 }
 /** Open (or return the cached) sessions database, applying migrations as needed. */
 export declare function getDB(): Database.Database;