@phnx-labs/agents-cli 1.22.47 → 1.22.49

package/dist/lib/tmux/session.js

@@ -34,6 +34,22 @@ export const AGENTS_TMUX_HISTORY_LIMIT = 20_000;
 export const AGENTS_TMUX_CONFIG_SCHEMA = 1;
 /** Server-scoped user-option recording which AGENTS_TMUX_CONFIG_SCHEMA is applied. */
 const CONFIG_SCHEMA_OPTION = '@ag_tmux_config_schema';
+/**
+ * Session-scoped user options naming WHICH agent session a wrapper session runs,
+ * so a status bar (or any tmux format) can show it without shelling out:
+ * `#{@ag_session_id}` / `#{@ag_agent}`.
+ *
+ * The session NAME cannot serve this purpose. runInTmux builds it from
+ * `(options.sessionId ?? randomUUID()).slice(0, 8)` (exec.ts), so a run with no
+ * pre-assigned id still gets 8 hex characters — indistinguishable from a real
+ * short session id but resolving to nothing. Only claude currently takes a
+ * forced `--session-id`, so on a box running both, `ag-claude-<real>` and
+ * `ag-codex-<fabricated>` look identical. These options are stamped ONLY from
+ * `labels.sessionId`, which is set only when the id is genuine — absent rather
+ * than wrong, so a consumer can fall back instead of displaying a fake handle.
+ */
+const SESSION_ID_OPTION = '@ag_session_id';
+const AGENT_NAME_OPTION = '@ag_agent';
 let startupConfigSequence = 0;
 function tmuxConfigArgument(value) {
     return `"${value.replace(/([\\"$])/g, '\\$1')}"`;
@@ -232,6 +248,21 @@ export async function createSession(opts) {
     if (pane) {
         await runTmux({ socket, args: ['set-option', '-pt', pane, 'remain-on-exit', 'on', ';', 'set-option', '-g', 'remain-on-exit', 'off'], throwOnError: false }).catch(() => { });
     }
+    // Stamp the agent identity onto the session so tmux formats can read it.
+    // Best-effort: a failure here must not fail a launch that otherwise worked,
+    // and an unset option simply renders empty in a format.
+    const identityArgs = [];
+    if (opts.labels?.sessionId) {
+        identityArgs.push('set-option', '-t', opts.name, SESSION_ID_OPTION, opts.labels.sessionId);
+    }
+    if (opts.labels?.agent) {
+        if (identityArgs.length)
+            identityArgs.push(';');
+        identityArgs.push('set-option', '-t', opts.name, AGENT_NAME_OPTION, opts.labels.agent);
+    }
+    if (identityArgs.length) {
+        await runTmux({ socket, args: identityArgs, throwOnError: false }).catch(() => { });
+    }
     const meta = {
         name: opts.name,
         socket,

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

@@ -0,0 +1,29 @@
+/**
+ * TracesBackend — token-source seam for `agents traces sync`.
+ *
+ * Managed path: signed in to Phoenix (`readSession() != null`), no BYO
+ * override. Token is the Phoenix access_token; endpoint is the live
+ * `traces.agents-cli.sh` Worker. Zero Cloudflare setup.
+ *
+ * BYO path (future): TRACES_BASE_URL + TRACES_WRITE_TOKEN env vars. Not
+ * exposed in the CLI for M1 — follow-on milestone, same pattern as
+ * `agents artifacts setup`.
+ */
+export declare const DEFAULT_TRACES_DOMAIN = "traces.agents-cli.sh";
+export interface TracesBackend {
+    /** Public base URL of the traces Worker, no trailing slash. */
+    baseUrl: string;
+    /** Bearer sent as `Authorization`. Phoenix access_token. */
+    token: string;
+    /** Phoenix userId — the R2 namespace prefix. */
+    userId: string;
+}
+/**
+ * Resolve the backend for the current machine. Throws when not signed in.
+ *
+ * BYO override env vars (for testing / self-hosted):
+ *   AGENTS_TRACES_BASE_URL — Worker URL, no trailing slash
+ *   AGENTS_TRACES_WRITE_TOKEN — static write token (bypasses Phoenix auth)
+ */
+export declare function resolveTracesBackend(): TracesBackend;
+export declare function managedTracesBaseUrl(): string;

package/dist/lib/traces/backend.js

@@ -0,0 +1,46 @@
+/**
+ * TracesBackend — token-source seam for `agents traces sync`.
+ *
+ * Managed path: signed in to Phoenix (`readSession() != null`), no BYO
+ * override. Token is the Phoenix access_token; endpoint is the live
+ * `traces.agents-cli.sh` Worker. Zero Cloudflare setup.
+ *
+ * BYO path (future): TRACES_BASE_URL + TRACES_WRITE_TOKEN env vars. Not
+ * exposed in the CLI for M1 — follow-on milestone, same pattern as
+ * `agents artifacts setup`.
+ */
+import { readSession } from '../identity/client.js';
+export const DEFAULT_TRACES_DOMAIN = 'traces.agents-cli.sh';
+/**
+ * Resolve the backend for the current machine. Throws when not signed in.
+ *
+ * BYO override env vars (for testing / self-hosted):
+ *   AGENTS_TRACES_BASE_URL — Worker URL, no trailing slash
+ *   AGENTS_TRACES_WRITE_TOKEN — static write token (bypasses Phoenix auth)
+ */
+export function resolveTracesBackend() {
+    const envBase = (process.env['AGENTS_TRACES_BASE_URL'] ?? '').replace(/\/+$/, '').trim();
+    const envToken = (process.env['AGENTS_TRACES_WRITE_TOKEN'] ?? '').trim();
+    if (envBase && envToken) {
+        return { baseUrl: envBase, token: envToken, userId: 'byo' };
+    }
+    const session = readSession();
+    if (!session) {
+        throw new Error("Not signed in. Run 'agents auth login' to sync traces to your Phoenix account.");
+    }
+    if (!session.access_token) {
+        throw new Error("Session has no access token. Run 'agents auth login' again.");
+    }
+    const userId = (session.userId ?? '').trim();
+    if (!userId) {
+        throw new Error("Signed in but the session has no user id. Run 'agents auth login' again.");
+    }
+    return {
+        baseUrl: managedTracesBaseUrl(),
+        token: session.access_token,
+        userId,
+    };
+}
+export function managedTracesBaseUrl() {
+    return `https://${DEFAULT_TRACES_DOMAIN}`;
+}

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

@@ -0,0 +1,52 @@
+export type TraceTopicGroup = 'code' | 'research' | 'review' | 'content' | 'ops';
+export type TraceFailureCause = 'real' | 'guard' | 'hook';
+/** Per-bucket aggregate stats for one day, stored in the rolling bucketHistory. */
+export interface BucketStats {
+    key: string;
+    date: string;
+    count: number;
+    /** Tool-error count / total tool calls in this session set (0–1). */
+    errorRate: number;
+    /** Sessions with ≥1 stall friction signal / total sessions in bucket (0–1). */
+    stallRate: number;
+}
+/** Movement signal for one topic bucket compared to its 7-day rolling average. */
+export interface DriftSignal {
+    bucket: string;
+    /** current errorRate − 7d average (positive = degrading). */
+    errorDelta: number;
+    /** current stallRate − 7d average (positive = degrading). */
+    stallDelta: number;
+    severity: 'degrading' | 'stable' | 'improving';
+}
+export interface TopicEvidence {
+    cwd?: string | null;
+    gitBranch?: string | null;
+    topic?: string | null;
+    label?: string | null;
+    toolMix?: Record<string, number>;
+}
+export interface ClassifiedTopic {
+    group: TraceTopicGroup;
+    key: string;
+    label: string;
+}
+export interface ToolCallFailure {
+    tool: string;
+    exit_code?: number | null;
+    status_code?: number | null;
+    error_code?: string | null;
+    error?: string | null;
+    parse_error?: string | null;
+    outcome?: string | null;
+}
+/** Classify a session from metadata and aggregate tool names; never reads transcript text. */
+export declare function classifyTopic(input: TopicEvidence): ClassifiedTopic;
+/** Bucket a failed tool call without inspecting raw tool input or transcript text. */
+export declare function classifyCause(call: ToolCallFailure): TraceFailureCause;
+/**
+ * Compare today's per-bucket stats to the last 7 days of history and return
+ * movement signals. Buckets with fewer than 3 historical days are skipped —
+ * not enough signal to distinguish noise from drift.
+ */
+export declare function computeDriftSignal(history: BucketStats[][], today: BucketStats[]): DriftSignal[];

package/dist/lib/traces/classify.js

@@ -0,0 +1,72 @@
+function normalizedEvidence(input) {
+    return [input.cwd, input.gitBranch, input.topic, input.label]
+        .filter((value) => typeof value === 'string')
+        .join(' ')
+        .toLowerCase();
+}
+/** Classify a session from metadata and aggregate tool names; never reads transcript text. */
+export function classifyTopic(input) {
+    const text = normalizedEvidence(input);
+    const tools = Object.keys(input.toolMix ?? {}).map((tool) => tool.toLowerCase());
+    const hasTool = (pattern) => tools.some((tool) => pattern.test(tool));
+    if (/\b(review|audit|pr[-_/ ]?review|code[-_/ ]?review)\b/.test(text)
+        || hasTool(/review|comment/)) {
+        return { group: 'review', key: 'code-review', label: 'Code review' };
+    }
+    if (/\b(research|investigat|analysis|benchmark|paper|docs?)\b/.test(text)
+        || hasTool(/web_search|search_query|webfetch|browser/)) {
+        return { group: 'research', key: 'research', label: 'Research' };
+    }
+    if (/\b(blog|copy|content|post|article|script|caption)\b/.test(text)) {
+        return { group: 'content', key: 'content', label: 'Content' };
+    }
+    if (/\b(deploy|release|infra|ci|ops|fleet|daemon|provision)\b/.test(text)
+        || hasTool(/ssh|deploy|computer/)) {
+        return { group: 'ops', key: 'operations', label: 'Operations' };
+    }
+    if (/\b(test|fix|bug|feat|refactor|implement|code)\b/.test(text)
+        || hasTool(/edit|write|apply_patch|exec|bash|shell/)) {
+        return { group: 'code', key: 'engineering', label: 'Engineering' };
+    }
+    return { group: 'research', key: 'general', label: 'General' };
+}
+/** Bucket a failed tool call without inspecting raw tool input or transcript text. */
+export function classifyCause(call) {
+    const evidence = [call.error_code, call.error, call.parse_error]
+        .filter((value) => typeof value === 'string')
+        .join(' ')
+        .toLowerCase();
+    if (/\b(?:git-guard|main-branch-guard)\b/.test(evidence))
+        return 'guard';
+    if (/permission\b.*\bdenied\b.*\b(?:auto[- ]mode|classifier)\b/.test(evidence)) {
+        return 'hook';
+    }
+    return 'real';
+}
+const DRIFT_THRESHOLD = 0.20;
+/**
+ * Compare today's per-bucket stats to the last 7 days of history and return
+ * movement signals. Buckets with fewer than 3 historical days are skipped —
+ * not enough signal to distinguish noise from drift.
+ */
+export function computeDriftSignal(history, today) {
+    const signals = [];
+    for (const stat of today) {
+        const pastStats = history
+            .flatMap((day) => day.filter((b) => b.key === stat.key))
+            .slice(-7);
+        if (pastStats.length < 3)
+            continue;
+        const avgError = pastStats.reduce((sum, b) => sum + b.errorRate, 0) / pastStats.length;
+        const avgStall = pastStats.reduce((sum, b) => sum + b.stallRate, 0) / pastStats.length;
+        const errorDelta = stat.errorRate - avgError;
+        const stallDelta = stat.stallRate - avgStall;
+        const severity = errorDelta > DRIFT_THRESHOLD || stallDelta > DRIFT_THRESHOLD
+            ? 'degrading'
+            : errorDelta < -DRIFT_THRESHOLD || stallDelta < -DRIFT_THRESHOLD
+                ? 'improving'
+                : 'stable';
+        signals.push({ bucket: stat.key, errorDelta, stallDelta, severity });
+    }
+    return signals.sort((a, b) => b.errorDelta - a.errorDelta);
+}

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

@@ -0,0 +1,10 @@
+/** Isolated Cloudflare resources for the private Phoenix trace store. */
+export interface TracesConfig {
+    baseUrl: string;
+    accountId: string;
+    workerName: string;
+    bucketName: string;
+    domain?: string;
+}
+export declare const DEFAULT_WORKER_NAME = "agents-traces";
+export declare const DEFAULT_BUCKET_NAME = "agents-traces";

package/dist/lib/traces/config.js

@@ -0,0 +1,2 @@
+export const DEFAULT_WORKER_NAME = 'agents-traces';
+export const DEFAULT_BUCKET_NAME = 'agents-traces';

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

@@ -0,0 +1,19 @@
+import { type CloudflareRequester } from '../share/provision.js';
+interface ProvisionOptions {
+    request?: CloudflareRequester;
+}
+/** Bind the Phoenix identity base URL used to verify every trace read and write. */
+export declare function setPhoenixIdBaseSecret(apiToken: string, accountId: string, workerName: string, phoenixIdBase: string, opts?: ProvisionOptions): Promise<void>;
+export interface ProvisionTracesOptions extends ProvisionOptions {
+    apiToken: string;
+    accountId: string;
+    workerName: string;
+    bucketName: string;
+    phoenixIdBase: string;
+    domain?: string;
+}
+/** Provision the complete isolated traces deployment using the canonical Worker template. */
+export declare function provisionTraces(opts: ProvisionTracesOptions): Promise<{
+    baseUrl: string;
+}>;
+export {};

package/dist/lib/traces/provision.js

@@ -0,0 +1,30 @@
+// Cloudflare orchestration for the private agents-traces store. The generic
+// request primitives live in share/provision; only the isolated traces resource
+// choices and Worker template belong here.
+import { randomBytes } from 'node:crypto';
+import { addCustomDomain, createBucket, deployWorker, enableWorkersDev, findZoneId, putWorkerSecret, } from '../share/provision.js';
+import { DEFAULT_TRACES_DOMAIN } from './backend.js';
+import { renderTracesWorkerScript } from './worker-template.js';
+/** Bind the Phoenix identity base URL used to verify every trace read and write. */
+export async function setPhoenixIdBaseSecret(apiToken, accountId, workerName, phoenixIdBase, opts = {}) {
+    const normalized = phoenixIdBase.replace(/\/+$/, '').trim();
+    if (!normalized)
+        throw new Error('PHOENIX_ID_BASE is required to verify trace requests.');
+    await putWorkerSecret(apiToken, accountId, workerName, 'PHOENIX_ID_BASE', normalized, opts);
+}
+/** Provision the complete isolated traces deployment using the canonical Worker template. */
+export async function provisionTraces(opts) {
+    const domain = opts.domain ?? DEFAULT_TRACES_DOMAIN;
+    const requestOpts = opts.request ? { request: opts.request } : {};
+    await createBucket(opts.apiToken, opts.accountId, opts.bucketName, requestOpts);
+    await deployWorker(opts.apiToken, opts.accountId, opts.workerName, renderTracesWorkerScript(), opts.bucketName, requestOpts);
+    await putWorkerSecret(opts.apiToken, opts.accountId, opts.workerName, 'WRITE_TOKEN', randomBytes(32).toString('hex'), requestOpts);
+    await setPhoenixIdBaseSecret(opts.apiToken, opts.accountId, opts.workerName, opts.phoenixIdBase, requestOpts);
+    const workersDevSubdomain = await enableWorkersDev(opts.apiToken, opts.accountId, opts.workerName, requestOpts);
+    const zoneId = await findZoneId(opts.apiToken, domain, requestOpts);
+    if (!zoneId) {
+        return { baseUrl: `https://${opts.workerName}.${workersDevSubdomain}.workers.dev` };
+    }
+    await addCustomDomain(opts.apiToken, opts.accountId, opts.workerName, zoneId, domain, requestOpts);
+    return { baseUrl: `https://${domain}` };
+}

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

@@ -0,0 +1,150 @@
+/**
+ * Incremental sync of derived, redacted SessionTrajectory blobs to the
+ * agents-traces R2 store.
+ *
+ * Security invariant: only the derived signal (steps + gaps + stats +
+ * errorCount + programTimeShare) is uploaded — no raw transcript text.
+ * redactSecrets() is called inside buildTrajectory() before we PUT.
+ *
+ * Sync gate: `sessions.db` `file_mtime_ms` is the source of truth.  A ledger
+ * at `getRuntimeStateDir()/traces-sync.json` records the last sync timestamp
+ * per device so re-runs skip unchanged sessions.
+ */
+import { type SessionTrajectory } from '../session/trajectory.js';
+import { type BucketStats, type DriftSignal, type TraceFailureCause, type TraceTopicGroup } from './classify.js';
+export interface SyncOpts {
+    /** Limit to N sessions (for testing / --dry-run); no limit when undefined. */
+    limit?: number;
+    /** When true, skip uploading the per-device index shard. */
+    skipIndex?: boolean;
+    /**
+     * Compute the derived shards from this device's real sessions.db and WRITE
+     * them to `outDir` instead of uploading. No Phoenix auth, no worker, no
+     * network — a local export for verifying the real signal. Ignores the
+     * incremental watermark so the export reflects every session.
+     */
+    dryRun?: boolean;
+    /** Directory to write `index.json` + `sessions/<id>.json` when `dryRun` is set. */
+    outDir?: string;
+}
+export interface SyncResult {
+    uploaded: number;
+    skipped: number;
+    errors: number;
+}
+/** Push derived, redacted trajectories for this device to the traces store. */
+export declare function syncTraces(opts?: SyncOpts): Promise<SyncResult>;
+export interface TracesIndexShard {
+    schema: 1;
+    device: string;
+    syncedAt: number;
+    owner: string;
+    stats: {
+        sessionsImported: number;
+        medianMs: number;
+        p90Ms: number;
+        needAttention: number;
+        toolErrorRate: number;
+    };
+    needsAttention: IndexedSession[];
+    topics: Array<{
+        key: string;
+        label: string;
+        count: number;
+        group: TraceTopicGroup;
+    }>;
+    failures: {
+        byToolError: Array<{
+            tool: string;
+            desc: string;
+            cause: TraceFailureCause;
+            count: number;
+        }>;
+        byCause: Record<TraceFailureCause, number>;
+    };
+    /** Rolling 14-day window of per-bucket daily stats. Each inner array is one day. */
+    bucketHistory: BucketStats[][];
+    /** Movement signals for buckets with ≥3 days of history. */
+    driftSignals: DriftSignal[];
+}
+export interface IndexedSession {
+    id: string;
+    title: string;
+    repo: string;
+    device: string;
+    agent: string;
+    model: string;
+    severity: number;
+    flags: 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). */
+export interface SessionDetail {
+    schema: 1;
+    id: string;
+    meta: {
+        spanMs: number;
+        turns: number;
+        tools: number;
+        errorCount: number;
+        tokens: number;
+        costUsd: number;
+        outcome: string;
+        repo: string;
+        agent: string;
+        model: string;
+    };
+    steps: SessionTrajectory['steps'];
+    gaps: SessionTrajectory['gaps'];
+    /** Steps dropped from `steps` when a run was too long — surfaced so truncation is never silent. */
+    truncatedSteps: number;
+    whereItWentWrong: string | null;
+}
+/**
+ * Map the derived trajectory to the console's SessionDetail shape, stripping
+ * local-machine PII (full cwd, account) that would expose filesystem paths if
+ * written to R2. `repo` is the cwd basename only.
+ */
+export declare function buildSessionDetail(traj: SessionTrajectory): SessionDetail;
+interface SyncLedger {
+    lastSyncMtime?: number;
+}
+export declare function readSyncLedger(): SyncLedger;
+export declare function writeSyncLedger(ledger: SyncLedger): void;
+export interface SyncRow {
+    id: string;
+    short_id: string;
+    agent: string;
+    origin: string | null;
+    routine_name: string | null;
+    routine_run_id: string | null;
+    version: string | null;
+    account: string | null;
+    account_key: string | null;
+    account_org: string | null;
+    mode: string | null;
+    timestamp: string;
+    last_activity: string | null;
+    project: string | null;
+    cwd: string | null;
+    git_branch: string | null;
+    topic: string | null;
+    label: string | null;
+    message_count: number | null;
+    token_count: number | null;
+    output_tokens: number | null;
+    input_tokens: number | null;
+    cache_read_tokens: number | null;
+    cache_write_tokens: number | null;
+    cost_usd: number | null;
+    cost_usd_nocache: number | null;
+    duration_ms: number | null;
+    model: string | null;
+    tool_call_count: number | null;
+    file_path: string;
+    file_mtime_ms: number | null;
+    file_size: number | null;
+    machine: string | null;
+}
+export {};