@phnx-labs/agents-cli 1.22.51 → 1.22.53

package/dist/lib/traces/segments.js

@@ -0,0 +1,301 @@
+/**
+ * Group-by dimensions + time-to-first-tool latency for the traces insight
+ * engine (the console's Issue bar).
+ *
+ * Pure functions, no I/O. Classifiers are DATA-DRIVEN TABLES — a new task type
+ * or timing bucket is a row, not a new if/else-by-name arm. The integrator
+ * (`insights.ts` / `sync.ts`) tags each session; this file does not write the
+ * shard.
+ *
+ * Input is the redacted `SessionDetail` from `agents traces sync` plus the
+ * SyncRow fields the detail strips (prompt, gitBranch, files). Structural —
+ * `SessionDetail` is a valid `SegmentSession`.
+ */
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+export const TASK_TYPES = ['bugfix', 'feature', 'refactor', 'test', 'chore', 'other'];
+export const FAILURE_TIMINGS = ['early', 'mid', 'late'];
+// ---------------------------------------------------------------------------
+// Tables — the classifiers. Add a row; do not add an if/else-by-name arm.
+// ---------------------------------------------------------------------------
+/**
+ * Tool name → file action. Lowercased. Write-family is a new file; Edit-family
+ * is a patch. Anything else is ignored for diff-shape.
+ */
+export const FILE_ACTION_TOOLS = [
+    { action: 'new', tools: ['write', 'write_file', 'create_file', 'create'] },
+    { action: 'edit', tools: ['edit', 'strreplace', 'apply_patch', 'applypatch', 'notebookedit'] },
+];
+/** Path heuristics for a test-only diff. */
+const TEST_PATH_PATTERN = /(?:^|\/)(?:__tests__|testdata|test)\/|\.(?:test|spec)\.[cm]?[jt]sx?$|_test\.(?:go|py|rs)$/i;
+/** Path heuristics for a chore-only diff (lockfiles, CI, docs). */
+const CHORE_PATH_PATTERN = /(?:^|\/)(?:package(?:-lock)?\.json|bun\.lockb?|pnpm-lock\.yaml|yarn\.lock|Cargo\.lock|go\.sum|Dockerfile|Makefile|\.github\/|CHANGELOG[^/]*|README[^/]*|\.gitignore)$/i;
+const DIFF_SHAPE_MATCHERS = [
+    {
+        key: 'testOnly',
+        match: (files) => files.length > 0 && files.every((f) => TEST_PATH_PATTERN.test(f.path)),
+    },
+    {
+        key: 'newOnly',
+        match: (files) => files.length > 0 && files.every((f) => f.action === 'new'),
+    },
+    {
+        key: 'choreOnly',
+        match: (files) => files.length > 0 && files.every((f) => CHORE_PATH_PATTERN.test(f.path)),
+    },
+];
+/**
+ * Task-type rules, first match wins. Prompt/branch keywords outrank diff shape
+ * except where `shape` is set (test-only files, chore-only files, all-new files).
+ *
+ * Order is the product priority: test-only work is not a "feature"; a `fix/`
+ * branch is a bugfix even if files are new; chore lockfile edits are not features.
+ */
+export const TASK_TYPE_RULES = [
+    {
+        type: 'test',
+        patterns: [
+            /\bunit tests?\b/,
+            /\bintegration tests?\b/,
+            /\btestdata\b/,
+            /\bcoverage\b/,
+            /\b(?:add|write|update|fix)\s+tests?\b/,
+            /\btest[- ]only\b/,
+            /(?:^|\/)tests?\//,
+            /^test\//,
+            /\.(?:test|spec)\./,
+        ],
+        shape: 'testOnly',
+    },
+    {
+        type: 'bugfix',
+        patterns: [
+            /\bbugfix(?:es)?\b/,
+            /\bhot[- ]?fix(?:es)?\b/,
+            /\bfixes\b/,
+            /\bfixing\b/,
+            /\bfix\b/,
+            /\bbugs?\b/,
+            /\bregression\b/,
+            /\bcrash(?:es|ed|ing)?\b/,
+            /\bbroken\b/,
+            /(?:^|\/)fix(?:es)?\//,
+            /^bugfix\//,
+        ],
+    },
+    {
+        type: 'refactor',
+        patterns: [
+            /\brefactor(?:s|ing|ed)?\b/,
+            /\bclean[- ]?ups?\b/,
+            /\bextract(?:s|ing|ed)?\b/,
+            /\brename(?:s|d|ing)?\b/,
+            /(?:^|\/)refactor\//,
+        ],
+    },
+    {
+        type: 'chore',
+        patterns: [
+            /\bchore\b/,
+            /\bdependenc(?:y|ies)\b/,
+            /\bbump\b/,
+            /\blint(?:ing|er)?\b/,
+            /\bformat(?:ting)?\b/,
+            /(?:^|\/)chore\//,
+            /\b(?:ci|cd)[-_/]/,
+        ],
+        shape: 'choreOnly',
+    },
+    {
+        type: 'feature',
+        patterns: [
+            /\bfeat(?:ure)?s?\b/,
+            /\bimplement(?:s|ing|ed)?\b/,
+            /\bnew feature\b/,
+            /(?:^|\/)feat(?:ure)?\//,
+        ],
+        shape: 'newOnly',
+    },
+];
+/**
+ * Normalized position of the first failing step inside the session span.
+ * Early failures cascade — highest-signal bucket. Exclusive upper bound.
+ */
+export const FAILURE_TIMING_BUCKETS = [
+    { timing: 'early', maxExclusive: 1 / 3 },
+    { timing: 'mid', maxExclusive: 2 / 3 },
+    { timing: 'late', maxExclusive: Number.POSITIVE_INFINITY },
+];
+const AGENT_FIELDS = {
+    model: [
+        (s) => s.meta?.model,
+        (s) => s.model,
+    ],
+    harness: [
+        (s) => s.meta?.agent,
+        (s) => s.harness,
+        (s) => s.agent,
+    ],
+};
+// ---------------------------------------------------------------------------
+// Public functions
+// ---------------------------------------------------------------------------
+/** Model × harness unit — the #1 group-by axis. */
+export function deriveAgent(session) {
+    return {
+        model: firstPresent(AGENT_FIELDS.model.map((read) => read(session))),
+        harness: firstPresent(AGENT_FIELDS.harness.map((read) => read(session))),
+    };
+}
+/**
+ * Classify the session's work from the opening prompt + diff shape (files
+ * touched, new vs edit, test-only). First matching table row wins.
+ */
+export function classifyTaskType(session) {
+    const haystack = taskHaystack(session);
+    const shape = inferDiffShape(session);
+    for (const rule of TASK_TYPE_RULES) {
+        if (rule.patterns.some((pattern) => pattern.test(haystack)))
+            return rule.type;
+        if (rule.shape && shape[rule.shape])
+            return rule.type;
+    }
+    return 'other';
+}
+/**
+ * Bucket the FIRST failing step by its normalized position in the session
+ * span (`firstFailure.startMs / spanMs`). Sessions with no failing step
+ * return null — they do not belong on the failure-timing axis.
+ */
+export function failureTiming(session) {
+    const firstFailure = (session.steps ?? []).find((step) => step.outcome === 'error');
+    if (!firstFailure)
+        return null;
+    const span = sessionSpanMs(session);
+    const position = span > 0 ? firstFailure.startMs / span : 0;
+    return FAILURE_TIMING_BUCKETS.find((bucket) => position < bucket.maxExclusive)?.timing ?? null;
+}
+/**
+ * Time-to-first-tool latency from `steps[0].startMs` across sessions that
+ * recorded at least one step. Nearest-rank percentiles (same formula as the
+ * traces index stats) so p99 on `/tmp/traces-real` lands at ~128s.
+ */
+export function computeLatency(sessions) {
+    const samples = [];
+    for (const session of sessions) {
+        const steps = session.steps ?? [];
+        if (steps.length === 0)
+            continue;
+        const startMs = steps[0]?.startMs;
+        if (typeof startMs !== 'number' || !Number.isFinite(startMs))
+            continue;
+        samples.push(startMs);
+    }
+    return {
+        firstToolMs: {
+            p50: percentileNearest(samples, 0.5),
+            p90: percentileNearest(samples, 0.9),
+            p99: percentileNearest(samples, 0.99),
+            max: samples.length === 0 ? 0 : Math.max(...samples),
+        },
+    };
+}
+/** All three group-by dimensions for one session. */
+export function deriveDimensions(session) {
+    return {
+        agent: deriveAgent(session),
+        taskType: classifyTaskType(session),
+        failureTiming: failureTiming(session),
+    };
+}
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+function firstPresent(values) {
+    for (const value of values) {
+        if (typeof value === 'string' && value.length > 0)
+            return value;
+    }
+    return 'unknown';
+}
+function taskHaystack(session) {
+    const filePaths = inferFiles(session).map((file) => file.path);
+    const writeLabels = (session.steps ?? [])
+        .filter((step) => fileActionForTool(step.tool) !== undefined)
+        .map((step) => step.label ?? '');
+    return [
+        session.prompt,
+        session.gitBranch,
+        session.topic,
+        session.label,
+        session.meta?.repo,
+        ...filePaths,
+        ...writeLabels,
+    ]
+        .filter((value) => typeof value === 'string' && value.length > 0)
+        .join('\n')
+        .toLowerCase();
+}
+function inferFiles(session) {
+    if (session.files && session.files.length > 0)
+        return session.files;
+    const files = [];
+    for (const step of session.steps ?? []) {
+        const action = fileActionForTool(step.tool);
+        if (!action)
+            continue;
+        const path = filePathFromLabel(step.label);
+        if (!path)
+            continue;
+        files.push({ path, action });
+    }
+    return files;
+}
+function fileActionForTool(tool) {
+    if (!tool)
+        return undefined;
+    const name = tool.toLowerCase();
+    for (const row of FILE_ACTION_TOOLS) {
+        if (row.tools.includes(name))
+            return row.action;
+    }
+    return undefined;
+}
+/** Best-effort path from a redacted Write/Edit label (`path/to/file.ts`). */
+function filePathFromLabel(label) {
+    if (!label)
+        return undefined;
+    const match = label.match(/(?:^|[\s`'"])(\/?[\w.@-]+(?:\/[\w.@-]+)+\.[A-Za-z][\w.]*)/);
+    return match?.[1];
+}
+function inferDiffShape(session) {
+    const files = inferFiles(session);
+    const shape = { files, testOnly: false, newOnly: false, choreOnly: false };
+    for (const matcher of DIFF_SHAPE_MATCHERS) {
+        shape[matcher.key] = matcher.match(files);
+    }
+    return shape;
+}
+function sessionSpanMs(session) {
+    const declared = session.meta?.spanMs ?? session.spanMs ?? 0;
+    if (declared > 0)
+        return declared;
+    let max = 0;
+    for (const step of session.steps ?? []) {
+        max = Math.max(max, step.startMs + (step.durationMs ?? 0));
+    }
+    return max;
+}
+/**
+ * Nearest-rank percentile, ratio in (0, 1]. Same index rule as
+ * `sync.ts`'s private `percentile` — linear interpolation (`lib/percentile.ts`)
+ * would report ~71s for p99 on the 738-session corpus; the published figure is
+ * 128s / 2m8s.
+ */
+function percentileNearest(values, ratio) {
+    if (values.length === 0)
+        return 0;
+    const sorted = [...values].sort((a, b) => a - b);
+    return sorted[Math.min(sorted.length - 1, Math.ceil(sorted.length * ratio) - 1)];
+}

package/dist/lib/traces/sync.d.ts

@@ -21,6 +21,8 @@
  */
 import { type SessionTrajectory } from '../session/trajectory.js';
 import { type BucketStats, type DriftSignal, type TraceFailureCause, type TraceTopicGroup } from './classify.js';
+import { type FailurePattern } from './insights.js';
+import type { LatencyInsight } from './segments.js';
 export interface SyncOpts {
     /** Limit to N sessions (for testing / --dry-run); no limit when undefined. */
     limit?: number;
@@ -82,6 +84,12 @@ export interface TracesIndexShard {
     bucketHistory: BucketStats[][];
     /** Movement signals for buckets with ≥3 days of history. */
     driftSignals: DriftSignal[];
+    /** Cross-session failure clusters ranked by wasted time, from computeInsights(). Top-K, bounded. */
+    failurePatterns: FailurePattern[];
+    /** Sum of wastedMs across every cluster (not just the top-K rows above) — the headline number. */
+    wastedMsTotal: number;
+    /** Time-to-first-tool percentiles across this device's sessions. */
+    latency: LatencyInsight;
 }
 export interface IndexedSession {
     id: string;
@@ -93,6 +101,21 @@ export interface IndexedSession {
     severity: number;
     flags: string[];
 }
+/** A row from `tool_calls`. `ordinal`/`timestamp` order calls within a session for computeInsights(). */
+export interface ToolCallRow {
+    session_id: string;
+    ordinal: number;
+    timestamp: string;
+    tool: string;
+    outcome: string;
+    exit_code: number | null;
+    status_code: number | null;
+    error_code: string | null;
+    error: string | null;
+    parse_error: string | null;
+}
+/** Human description of a failed call, keyed by (tool, desc, cause) for grouping. Exported for computeInsights(). */
+export declare function failureDescription(call: ToolCallRow, cause: TraceFailureCause): string;
 /** Build the redacted rich console shard from indexed metadata and derived caches. */
 export declare function buildIndexShard(rows: SyncRow[], device: string, owner: string, prevShard?: TracesIndexShard | null): TracesIndexShard;
 /** Per-session drill-down detail the console consumes (sessions/<id>.json). */
@@ -116,6 +139,16 @@ export interface SessionDetail {
     /** Steps dropped from `steps` when a run was too long — surfaced so truncation is never silent. */
     truncatedSteps: number;
     whereItWentWrong: string | null;
+    /**
+     * Failed tool steps, surfaced even when `meta.outcome === 'completed'` — a run
+     * can finish without throwing while a tool call inside it failed (the
+     * LangSmith trap: a green run-level status hiding a real failure).
+     */
+    surfacedToolFailures: Array<{
+        tool?: string;
+        label: string;
+        detail?: string;
+    }>;
 }
 /**
  * Map the derived trajectory to the console's SessionDetail shape, stripping

package/dist/lib/traces/sync.js

@@ -30,6 +30,7 @@ import { knownSecretValuesFromEnv, redactSecrets } from '../redact.js';
 import { getRuntimeStateDir } from '../state.js';
 import { resolveTracesBackend } from './backend.js';
 import { classifyCause, classifyTopic, computeDriftSignal, } from './classify.js';
+import { computeInsights } from './insights.js';
 /** Push derived, redacted trajectories for this device to the traces store. */
 export async function syncTraces(opts = {}) {
     const dryRun = opts.dryRun === true;
@@ -210,7 +211,8 @@ function percentile(values, ratio) {
     const sorted = [...values].sort((a, b) => a - b);
     return sorted[Math.min(sorted.length - 1, Math.ceil(sorted.length * ratio) - 1)];
 }
-function failureDescription(call, cause) {
+/** Human description of a failed call, keyed by (tool, desc, cause) for grouping. Exported for computeInsights(). */
+export function failureDescription(call, cause) {
     if (cause === 'guard')
         return /main-branch-guard/i.test(`${call.error_code ?? ''} ${call.error ?? ''}`)
             ? 'main branch guard' : 'git guard';
@@ -254,7 +256,7 @@ export function buildIndexShard(rows, device, owner, prevShard) {
     for (let i = 0; i < ids.length; i += 400) {
         const chunk = ids.slice(i, i + 400);
         calls.push(...db.prepare(`
-      SELECT session_id, tool, outcome, exit_code, status_code, error_code, error, parse_error
+      SELECT session_id, ordinal, timestamp, tool, outcome, exit_code, status_code, error_code, error, parse_error
       FROM tool_calls
       WHERE session_id IN (${chunk.map(() => '?').join(',')})
     `).all(...chunk));
@@ -359,6 +361,7 @@ export function buildIndexShard(rows, device, owner, prevShard) {
     const prevHistory = prevShard?.bucketHistory ?? [];
     const bucketHistory = [...prevHistory, todayStats].slice(-14);
     const driftSignals = computeDriftSignal(prevHistory, todayStats);
+    const patternInsights = computeInsights(rows, calls, prevShard);
     return {
         schema: 1,
         device,
@@ -379,6 +382,9 @@ export function buildIndexShard(rows, device, owner, prevShard) {
         },
         bucketHistory,
         driftSignals,
+        failurePatterns: patternInsights.failurePatterns,
+        wastedMsTotal: patternInsights.wastedMsTotal,
+        latency: patternInsights.latency,
     };
 }
 /** Plain-language summary of the friction in a run, or null when it ran clean. */
@@ -426,6 +432,9 @@ export function buildSessionDetail(traj) {
         gaps: traj.gaps,
         truncatedSteps: traj.truncatedSteps,
         whereItWentWrong: buildWhereItWentWrong(traj),
+        surfacedToolFailures: traj.steps
+            .filter((step) => step.outcome === 'error')
+            .map((step) => ({ tool: step.tool, label: step.label, detail: step.detail })),
     };
 }
 async function getIndexShard(backend, device) {

package/dist/lib/types.d.ts

@@ -820,7 +820,11 @@ export interface Meta {
     /** Preferred provider account per harness. Explicit --account wins. */
     accounts?: {
         defaults?: Partial<Record<AgentId, string>>;
-        /** Named harness-owned identities. Metadata only; OAuth credentials stay in the harness home. */
+        /**
+         * Named harness-owned identities. Metadata only; OAuth credentials stay in
+         * the harness home. Central-synced via agents.yaml; labels bind to
+         * `(agent, identityKey)`.
+         */
         native?: Record<string, {
             id: string;
             name: string;
@@ -832,6 +836,26 @@ export interface Meta {
         /** Exact installation/custom-harness target -> stable account id. */
         bindings?: Record<string, string>;
     };
+    /**
+     * Device-scoped slice of {@link Meta.accounts}, written as `accounts:` in
+     * `~/.agents/devices/<machine>/agents.yaml` (PHNX-3315). Holds this box's own
+     * `scope: 'device'` native identities and the bindings that target them, so a
+     * per-box login no longer rewrites the fleet-shared central `agents.yaml` (and
+     * its identity PII no longer lands on that one file). The effective account
+     * view is the union of central (fleet-shared `defaults` + `scope:'version'`
+     * natives) and every device doc's block; only this machine writes this key.
+     */
+    deviceAccounts?: {
+        native?: Record<string, {
+            id: string;
+            name: string;
+            agent: AgentId;
+            identityKey: string;
+            identityLabel?: string;
+            scope: 'version' | 'device';
+        }>;
+        bindings?: Record<string, string>;
+    };
     agents?: Partial<Record<AgentId, string>>;
     /**
      * Per-agent preferred ISOLATED version — which copy a bare `agents run <agent>`
@@ -1012,6 +1036,15 @@ export interface Meta {
      * are never copied. `inline` hosts carry their own address/user.
      */
     hosts?: Record<string, HostEntry>;
+    /**
+     * Device-scoped agent-host registry, written as `hosts:` in
+     * `~/.agents/devices/<machine>/agents.yaml` (PHNX-3315). Locally-discovered
+     * SSH hosts and inline registrations land here so one box's enrollment no
+     * longer rewrites the fleet-shared `hosts:` map (the source of pull conflicts).
+     * The effective host view is the union across every device doc (plus any
+     * lingering central legacy entries); only this machine writes this key.
+     */
+    deviceHosts?: Record<string, HostEntry>;
     /**
      * Declarative fleet profile (`agents apply` / `ag apply`). Additive to the
      * schema — project `agents:` version-pins are untouched. Declares which agents
@@ -1022,6 +1055,19 @@ export interface Meta {
      * Full shape in `lib/fleet/types.ts` (FleetManifest).
      */
     fleet?: import('./fleet/types.js').FleetManifest;
+    /**
+     * Device-scoped slice of {@link Meta.fleet}: THIS box's own discovery
+     * decisions and dismissals, written as `fleet:` in
+     * `~/.agents/devices/<machine>/agents.yaml` (PHNX-3315). Each box records only
+     * its own choices here, so N boxes no longer rewrite one shared
+     * `fleet.discovery`/`fleet.ignored` map (the guaranteed pull conflict). The
+     * effective fleet view is computed as a UNION across every device doc (plus
+     * lingering central legacy) at read time; only this machine writes this key.
+     */
+    deviceFleet?: {
+        discovery?: Record<string, 'approved' | 'ignored'>;
+        ignored?: import('./fleet/types.js').IgnoredDeviceEntry[];
+    };
     /** Artifact share endpoint (Cloudflare R2 + Worker). Set by `agents artifacts
      * setup`/`join`; syncs fleet-wide via `agents repo push/pull`. The write token
      * lives in the `share` secrets bundle, not here. */

package/dist/lib/watchdog/runner.js

@@ -146,7 +146,13 @@ function planDelivery(session, chosenText, block, allowGhosttyFocus) {
     // silently dropping a nudge into a spool it will never read.
     if (route.kind === 'mailbox' && isOpenQuestionBlock(block))
         return { via: 'mailbox', mailboxId };
-    return { via: 'refuse', reason: route.kind === 'refuse' ? route.reason : resolution.reason };
+    return {
+        via: 'refuse',
+        // answer-router's refuse reason already bakes in the recovery hint; the
+        // resolver's reason does not, so carry hint separately for the caller.
+        reason: route.kind === 'refuse' ? route.reason : resolution.reason,
+        hint: route.kind === 'refuse' ? undefined : resolution.hint,
+    };
 }
 /** Default open-block reader — the same lookup `agents message` uses. */
 function defaultOpenBlockFor(session) {
@@ -596,7 +602,9 @@ export async function runWatchdogTick(opts = {}) {
                     flags[sid] = { reason: `rotate: ${resolution.reason}`, host: session.host, atMs: nowMs };
                     outcomes.push({
                         ...base, decision: 'skip', addressable: false,
-                        reason: `rate-limited but un-addressable — ${resolution.reason}`,
+                        reason: resolution.hint
+                            ? `rate-limited but un-addressable — ${resolution.reason} — ${resolution.hint}`
+                            : `rate-limited but un-addressable — ${resolution.reason}`,
                     });
                     continue;
                 }
@@ -737,7 +745,11 @@ export async function runWatchdogTick(opts = {}) {
                             const machineHost = session.provenance?.host ?? 'unknown';
                             const runtime = session.kind;
                             try {
-                                const declaredBlock = buildDeclaredBlock({ sessionId: session.sessionId, mailboxId, host: machineHost, runtime, cwd: session.cwd }, { text: `Session genuinely needs Muqsit and is un-addressable — ${decision.reason}. Needs attention.` });
+                                const declaredBlock = buildDeclaredBlock({ sessionId: session.sessionId, mailboxId, host: machineHost, runtime, cwd: session.cwd }, {
+                                    text: resolution.hint
+                                        ? `Session genuinely needs Muqsit and is un-addressable — ${decision.reason}. Needs attention. ${resolution.hint}`
+                                        : `Session genuinely needs Muqsit and is un-addressable — ${decision.reason}. Needs attention.`,
+                                });
                                 publishBlockFn(declaredBlock);
                                 ledgerUpdates[session.sessionId] = nowMs;
                             }
@@ -769,7 +781,9 @@ export async function runWatchdogTick(opts = {}) {
             flags[session.sessionId] = { reason: plan.reason, host: session.host, atMs: nowMs };
             outcomes.push({
                 ...base, decision: 'skip', addressable: false,
-                reason: `nudge-worthy but un-addressable — ${plan.reason}`,
+                reason: plan.hint
+                    ? `nudge-worthy but un-addressable — ${plan.reason} — ${plan.hint}`
+                    : `nudge-worthy but un-addressable — ${plan.reason}`,
                 nudgeText: chosenText,
             });
             continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.22.51",
+  "version": "1.22.53",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",