@phnx-labs/agents-cli 1.22.47 → 1.22.49

package/dist/lib/traces/sync.js

@@ -0,0 +1,447 @@
+/**
+ * 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 fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { getDB, readSessionInsights, readSessionTopics, writeSessionInsights, writeSessionTopics, } from '../session/db.js';
+import { parseSession } from '../session/parse.js';
+import { buildTrajectory } from '../session/trajectory.js';
+import { computeInsightFacets } from '../session/insights.js';
+import { knownSecretValuesFromEnv, redactSecrets } from '../redact.js';
+import { getRuntimeStateDir } from '../state.js';
+import { resolveTracesBackend } from './backend.js';
+import { classifyCause, classifyTopic, computeDriftSignal, } from './classify.js';
+/** Push derived, redacted trajectories for this device to the traces store. */
+export async function syncTraces(opts = {}) {
+    const dryRun = opts.dryRun === true;
+    const outDir = opts.outDir;
+    if (dryRun && !outDir) {
+        throw new Error('traces sync --dry-run requires --out <dir>');
+    }
+    // A dry-run computes locally and writes to disk: no Phoenix backend needed.
+    const backend = dryRun ? null : resolveTracesBackend();
+    const owner = backend?.userId ?? 'local';
+    const ledger = readSyncLedger();
+    const db = getDB();
+    const device = localDevice();
+    // Scope to this machine only — the DB can contain peer rows mirrored from the
+    // fleet; uploading those under this device's prefix would corrupt the index.
+    // NULL machine rows are legacy local sessions (pre-machine-field). A dry-run
+    // ignores the incremental watermark so the export covers every session.
+    const sinceMtime = dryRun ? 0 : (ledger.lastSyncMtime ?? 0);
+    const rows = db
+        .prepare('SELECT * FROM sessions WHERE (machine = ? OR machine IS NULL) AND file_mtime_ms > ? ORDER BY file_mtime_ms ASC')
+        .all(device, sinceMtime);
+    const limited = opts.limit !== undefined ? rows.slice(0, opts.limit) : rows;
+    const knownSecrets = knownSecretValuesFromEnv();
+    let uploaded = 0;
+    let skipped = 0;
+    let errors = 0;
+    // Advance the watermark only to the max mtime of successfully uploaded sessions
+    // so failures are retried on the next run.
+    let maxSuccessMtime = ledger.lastSyncMtime ?? 0;
+    if (dryRun && outDir) {
+        fs.mkdirSync(path.join(outDir, 'sessions'), { recursive: true });
+    }
+    for (const row of limited) {
+        if (!row.file_path) {
+            skipped++;
+            maxSuccessMtime = Math.max(maxSuccessMtime, row.file_mtime_ms ?? 0);
+            continue;
+        }
+        let traj;
+        try {
+            const session = rowToMeta(row);
+            const events = parseSession(row.file_path, row.agent);
+            traj = buildTrajectory(events, session, { redact: true, knownSecrets });
+        }
+        catch {
+            errors++;
+            continue;
+        }
+        try {
+            if (dryRun && outDir) {
+                fs.writeFileSync(path.join(outDir, 'sessions', `${row.id}.json`), JSON.stringify(buildSessionDetail(traj)));
+            }
+            else {
+                await putSessionTrace(backend, device, row.id, traj);
+            }
+            uploaded++;
+            maxSuccessMtime = Math.max(maxSuccessMtime, row.file_mtime_ms ?? 0);
+        }
+        catch {
+            errors++;
+        }
+    }
+    if (!opts.skipIndex) {
+        try {
+            const allRows = db
+                .prepare('SELECT * FROM sessions WHERE machine = ? OR machine IS NULL')
+                .all(device);
+            // Seed rolling bucket history from the previous shard so drift signals accumulate.
+            let prevShard = null;
+            if (dryRun && outDir) {
+                const prevPath = path.join(outDir, 'index.json');
+                try {
+                    prevShard = JSON.parse(fs.readFileSync(prevPath, 'utf8'));
+                }
+                catch { /* first run — no prior shard */ }
+            }
+            else if (backend) {
+                prevShard = await getIndexShard(backend, device);
+            }
+            const shard = buildIndexShard(allRows, device, owner, prevShard);
+            if (dryRun && outDir) {
+                fs.writeFileSync(path.join(outDir, 'index.json'), JSON.stringify(shard, null, 2));
+            }
+            else {
+                await putIndexShard(backend, device, owner, shard);
+            }
+        }
+        catch {
+            // index PUT/write failure is not fatal — the per-session data is already written
+        }
+    }
+    // A dry-run never advances the incremental watermark: it is a read-only export.
+    if (!dryRun) {
+        writeSyncLedger({ lastSyncMtime: maxSuccessMtime });
+    }
+    return { uploaded, skipped, errors };
+}
+function percentile(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)];
+}
+function failureDescription(call, cause) {
+    if (cause === 'guard')
+        return /main-branch-guard/i.test(`${call.error_code ?? ''} ${call.error ?? ''}`)
+            ? 'main branch guard' : 'git guard';
+    if (cause === 'hook')
+        return 'auto-mode hook denial';
+    if (call.status_code != null)
+        return `HTTP ${call.status_code}`;
+    if (call.exit_code != null)
+        return `exit ${call.exit_code}`;
+    if (call.error_code)
+        return 'tool error code';
+    if (call.parse_error)
+        return 'parse error';
+    return 'tool error';
+}
+function attentionFlags(errorCount, facets) {
+    const flags = [];
+    if (errorCount > 0)
+        flags.push(`${errorCount} error${errorCount === 1 ? '' : 's'}`);
+    const friction = facets?.frictionSignals ?? {};
+    const corrections = facets?.correctionSignals ?? {};
+    const retryCount = Object.entries(friction)
+        .filter(([key]) => key.startsWith('failed tool loop:'))
+        .reduce((sum, [, count]) => sum + count, 0);
+    if (retryCount > 0)
+        flags.push('retry loop');
+    const stall = Object.entries(friction).find(([key, count]) => key.startsWith('silent stall:') && count > 0);
+    if (stall)
+        flags.push(stall[0].replace('silent stall: ', 'stalled '));
+    const correctionCount = Object.values(corrections).reduce((sum, count) => sum + count, 0);
+    if (correctionCount > 0)
+        flags.push(`${correctionCount} correction${correctionCount === 1 ? '' : 's'}`);
+    return flags;
+}
+/** Build the redacted rich console shard from indexed metadata and derived caches. */
+export function buildIndexShard(rows, device, owner, prevShard) {
+    const db = getDB();
+    const knownSecrets = knownSecretValuesFromEnv();
+    const ids = rows.map((row) => row.id);
+    const calls = [];
+    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
+      FROM tool_calls
+      WHERE session_id IN (${chunk.map(() => '?').join(',')})
+    `).all(...chunk));
+    }
+    const toolMix = new Map();
+    const errorCounts = new Map();
+    for (const call of calls) {
+        const mix = toolMix.get(call.session_id) ?? {};
+        mix[call.tool] = (mix[call.tool] ?? 0) + 1;
+        toolMix.set(call.session_id, mix);
+        if (call.outcome === 'error') {
+            errorCounts.set(call.session_id, (errorCounts.get(call.session_id) ?? 0) + 1);
+        }
+    }
+    const topics = readSessionTopics(ids);
+    const missingTopics = rows.filter((row) => !topics.has(row.id)).map((row) => {
+        const topic = classifyTopic({
+            cwd: row.cwd,
+            gitBranch: row.git_branch,
+            topic: row.topic,
+            label: row.label,
+            toolMix: toolMix.get(row.id),
+        });
+        topics.set(row.id, topic);
+        return { id: row.id, fileMtimeMs: row.file_mtime_ms, fileSize: row.file_size, topic };
+    });
+    writeSessionTopics(missingTopics);
+    const insights = readSessionInsights(ids);
+    const missingInsights = [];
+    for (const row of rows.filter((candidate) => !insights.has(candidate.id))) {
+        try {
+            const events = parseSession(row.file_path, row.agent);
+            const facets = computeInsightFacets(events);
+            insights.set(row.id, facets);
+            missingInsights.push({
+                id: row.id,
+                fileMtimeMs: row.file_mtime_ms,
+                fileSize: row.file_size,
+                facets,
+            });
+        }
+        catch {
+            continue;
+        }
+    }
+    writeSessionInsights(missingInsights);
+    const needsAttention = rows.flatMap((row) => {
+        const facets = insights.get(row.id);
+        const errorCount = errorCounts.get(row.id) ?? 0;
+        const flags = attentionFlags(errorCount, facets);
+        if (flags.length === 0)
+            return [];
+        const friction = Object.values(facets?.frictionSignals ?? {}).reduce((sum, count) => sum + count, 0);
+        const corrections = Object.values(facets?.correctionSignals ?? {}).reduce((sum, count) => sum + count, 0);
+        return [{
+                id: row.id,
+                title: redactSecrets(row.label ?? row.topic ?? topics.get(row.id)?.label ?? 'Untitled session', knownSecrets),
+                repo: row.project ?? (row.cwd ? path.basename(row.cwd) : 'unknown'),
+                device,
+                agent: row.agent,
+                model: row.model ?? 'unknown',
+                severity: errorCount * 2 + friction * 3 + corrections * 2,
+                flags,
+            }];
+    }).sort((a, b) => b.severity - a.severity || a.id.localeCompare(b.id));
+    const topicCounts = new Map();
+    for (const topic of topics.values()) {
+        const current = topicCounts.get(topic.key) ?? { ...topic, count: 0 };
+        current.count++;
+        topicCounts.set(topic.key, current);
+    }
+    const failedCalls = calls.filter((call) => call.outcome === 'error');
+    const byCause = { real: 0, guard: 0, hook: 0 };
+    const failureCounts = new Map();
+    for (const call of failedCalls) {
+        const cause = classifyCause(call);
+        const desc = failureDescription(call, cause);
+        byCause[cause]++;
+        const key = `${call.tool}\u0000${desc}\u0000${cause}`;
+        const current = failureCounts.get(key) ?? { tool: call.tool, desc, cause, count: 0 };
+        current.count++;
+        failureCounts.set(key, current);
+    }
+    const durations = rows.flatMap((row) => row.duration_ms == null ? [] : [row.duration_ms]);
+    // Build today's per-bucket stats for the rolling drift window.
+    const todayDate = new Date().toISOString().slice(0, 10);
+    const todayStats = [...topicCounts.values()].map(({ key }) => {
+        const sessionsInBucket = [...topics.entries()]
+            .filter(([, t]) => t.key === key)
+            .map(([id]) => id);
+        const bucketCalls = calls.filter((c) => sessionsInBucket.includes(c.session_id));
+        const bucketErrors = bucketCalls.filter((c) => c.outcome === 'error').length;
+        const errorRate = bucketCalls.length === 0 ? 0 : bucketErrors / bucketCalls.length;
+        const stallCount = sessionsInBucket.filter((id) => {
+            const facets = insights.get(id);
+            return Object.entries(facets?.frictionSignals ?? {})
+                .some(([k, v]) => k.startsWith('silent stall:') && v > 0);
+        }).length;
+        const stallRate = sessionsInBucket.length === 0 ? 0 : stallCount / sessionsInBucket.length;
+        return { key, date: todayDate, count: topicCounts.get(key).count, errorRate, stallRate };
+    });
+    const prevHistory = prevShard?.bucketHistory ?? [];
+    const bucketHistory = [...prevHistory, todayStats].slice(-14);
+    const driftSignals = computeDriftSignal(prevHistory, todayStats);
+    return {
+        schema: 1,
+        device,
+        syncedAt: Date.now(),
+        owner,
+        stats: {
+            sessionsImported: rows.length,
+            medianMs: percentile(durations, 0.5),
+            p90Ms: percentile(durations, 0.9),
+            needAttention: needsAttention.length,
+            toolErrorRate: calls.length === 0 ? 0 : failedCalls.length / calls.length,
+        },
+        needsAttention,
+        topics: [...topicCounts.values()].sort((a, b) => b.count - a.count || a.key.localeCompare(b.key)),
+        failures: {
+            byToolError: [...failureCounts.values()].sort((a, b) => b.count - a.count || a.tool.localeCompare(b.tool)),
+            byCause,
+        },
+        bucketHistory,
+        driftSignals,
+    };
+}
+/** Plain-language summary of the friction in a run, or null when it ran clean. */
+function buildWhereItWentWrong(traj) {
+    const errorSteps = traj.steps.filter((s) => s.outcome === 'error');
+    const biggestGap = traj.gaps.reduce((max, g) => (!max || g.durationMs > max.durationMs ? g : max), null);
+    const parts = [];
+    if (errorSteps.length > 0) {
+        const first = errorSteps[0];
+        const who = first.tool ?? first.lane;
+        parts.push(`${errorSteps.length} tool error${errorSteps.length === 1 ? '' : 's'} (first: ${who} — ${first.label})`);
+    }
+    if (biggestGap && biggestGap.durationMs >= 60_000) {
+        parts.push(`stalled ${Math.round(biggestGap.durationMs / 60_000)}m`);
+    }
+    if (parts.length === 0)
+        return null;
+    return `This run hit ${parts.join('; ')}.`;
+}
+/**
+ * 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 function buildSessionDetail(traj) {
+    const s = traj.session;
+    const stats = traj.stats;
+    const repo = s.project ?? (s.cwd ? path.basename(s.cwd) : 'unknown');
+    return {
+        schema: 1,
+        id: s.id,
+        meta: {
+            spanMs: traj.spanMs,
+            turns: (stats.userTurns ?? 0) + (stats.assistantTurns ?? 0),
+            tools: stats.toolCount ?? 0,
+            errorCount: traj.errorCount,
+            tokens: stats.outputTokens ?? 0,
+            costUsd: s.costUsd ?? 0,
+            outcome: traj.errorCount > 0 ? 'errored' : 'completed',
+            repo,
+            agent: s.agent,
+            model: s.model ?? 'unknown',
+        },
+        steps: traj.steps,
+        gaps: traj.gaps,
+        truncatedSteps: traj.truncatedSteps,
+        whereItWentWrong: buildWhereItWentWrong(traj),
+    };
+}
+async function getIndexShard(backend, device) {
+    const url = `${backend.baseUrl}/${backend.userId}/${device}/index.json`;
+    try {
+        const res = await fetch(url, {
+            headers: { authorization: `Bearer ${backend.token}` },
+        });
+        if (!res.ok)
+            return null;
+        return await res.json();
+    }
+    catch {
+        return null;
+    }
+}
+async function putSessionTrace(backend, device, sessionId, traj) {
+    const url = `${backend.baseUrl}/${backend.userId}/${device}/sessions/${sessionId}.json`;
+    const res = await fetch(url, {
+        method: 'PUT',
+        headers: {
+            authorization: `Bearer ${backend.token}`,
+            'content-type': 'application/json; charset=utf-8',
+        },
+        body: JSON.stringify(buildSessionDetail(traj)),
+    });
+    if (!res.ok) {
+        throw new Error(`PUT ${url} → ${res.status}`);
+    }
+}
+async function putIndexShard(backend, device, owner, shard) {
+    const full = { ...shard, device, owner, syncedAt: Date.now() };
+    const url = `${backend.baseUrl}/${backend.userId}/${device}/index.json`;
+    const res = await fetch(url, {
+        method: 'PUT',
+        headers: {
+            authorization: `Bearer ${backend.token}`,
+            'content-type': 'application/json; charset=utf-8',
+        },
+        body: JSON.stringify(full),
+    });
+    if (!res.ok) {
+        throw new Error(`PUT ${url} → ${res.status}`);
+    }
+}
+function ledgerPath() {
+    return path.join(getRuntimeStateDir(), 'traces-sync.json');
+}
+export function readSyncLedger() {
+    try {
+        const raw = fs.readFileSync(ledgerPath(), 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
+export function writeSyncLedger(ledger) {
+    const p = ledgerPath();
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, JSON.stringify(ledger, null, 2) + '\n', 'utf8');
+}
+// ---------------------------------------------------------------------------
+// Local device name
+// ---------------------------------------------------------------------------
+function localDevice() {
+    return (process.env['AGENTS_SYNC_MACHINE_ID'] ?? os.hostname()).toLowerCase().replace(/\.local$/, '');
+}
+/** Minimal subset of rowToMeta needed to satisfy buildTrajectory's SessionMeta param. */
+function rowToMeta(row) {
+    const SESSION_RUN_MODES = ['plan', 'edit', 'auto', 'skip'];
+    return {
+        id: row.id,
+        shortId: row.short_id,
+        agent: row.agent,
+        origin: row.origin === 'routine' ? 'routine' : 'cli',
+        routineName: row.routine_name ?? undefined,
+        routineRunId: row.routine_run_id ?? undefined,
+        timestamp: row.timestamp,
+        lastActivity: row.last_activity ?? undefined,
+        project: row.project ?? undefined,
+        cwd: row.cwd ?? undefined,
+        filePath: row.file_path,
+        gitBranch: row.git_branch ?? undefined,
+        messageCount: row.message_count ?? undefined,
+        tokenCount: row.token_count ?? undefined,
+        outputTokens: row.output_tokens ?? undefined,
+        inputTokens: row.input_tokens ?? undefined,
+        cacheReadTokens: row.cache_read_tokens ?? undefined,
+        cacheWriteTokens: row.cache_write_tokens ?? undefined,
+        costUsd: row.cost_usd ?? undefined,
+        costUsdNoCache: row.cost_usd_nocache ?? undefined,
+        durationMs: row.duration_ms ?? undefined,
+        model: row.model ?? undefined,
+        toolCallCount: row.tool_call_count ?? undefined,
+        version: row.version ?? undefined,
+        account: row.account ?? undefined,
+        accountKey: row.account_key ?? undefined,
+        accountOrg: row.account_org ?? undefined,
+        mode: SESSION_RUN_MODES.includes(row.mode ?? '') ? row.mode : undefined,
+        topic: row.topic ?? undefined,
+        label: row.label ?? undefined,
+        machine: row.machine ?? undefined,
+    };
+}

package/dist/lib/traces/worker-template.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Render the traces Worker source. Pure — bindings are wired at deploy time.
+ */
+export declare function renderTracesWorkerScript(): string;

package/dist/lib/traces/worker-template.js

@@ -0,0 +1,159 @@
+// The Cloudflare Worker that fronts the R2 traces bucket.
+//
+// SECURITY: unlike agents-share, there is NO public GET path here. Every route
+// — PUT and GET — requires a Phoenix bearer. The caller must be the record's
+// owner (path prefix == verified userId). A missing bearer → 401; a wrong
+// owner → 403; public cache headers are NEVER emitted.
+//
+// Routes (all require Phoenix bearer + userId owner match):
+//   PUT  /<userId>/<device>/index.json            — per-device stats shard
+//   PUT  /<userId>/<device>/sessions/<id>.json    — per-session SessionDetail
+//   GET  /<userId>/...                            — returns the stored object
+//   GET  /                                        — 200 description (no data)
+//
+// Emitted as a string so it compiles into dist/** and ships with no
+// package.json#files change. `provisionTraces.ts` uploads this verbatim as an
+// ES-module Worker with a BUCKET (R2) binding + a PHOENIX_ID_BASE secret.
+/**
+ * Render the traces Worker source. Pure — bindings are wired at deploy time.
+ */
+export function renderTracesWorkerScript() {
+    return `// GENERATED by agents-cli agents traces — do not edit; edit
+// src/lib/traces/worker-template.ts and re-provision.
+export const hooks = {
+  verifyPhoenixToken: defaultVerifyPhoenixToken,
+};
+
+export default {
+  async fetch(request, env) {
+    const url = new URL(request.url);
+    const path = decodeURIComponent(url.pathname.replace(/^\\/+/, ''));
+
+    if (!path) {
+      return new Response(
+        'agents traces — PUT /<userId>/<device>/index.json or sessions/<id>.json to upload; GET the same path to read. All routes require a Phoenix bearer.',
+        { status: 200, headers: { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'private, no-store' } },
+      );
+    }
+
+    if (request.method === 'PUT') {
+      return handlePut(request, env, path);
+    }
+
+    if (request.method === 'GET' || request.method === 'HEAD') {
+      return handleGet(request, env, path);
+    }
+
+    return json({ error: 'method not allowed' }, 405);
+  },
+};
+
+async function handlePut(request, env, path) {
+  const auth = await authorizeWrite(request, env);
+  if (auth.error) return auth.error;
+
+  const segments = path.split('/').filter(Boolean);
+  const expected = auth.owner;
+  if (!expected || segments[0] !== expected) {
+    return json({ error: 'namespace mismatch', owner: expected }, 403);
+  }
+
+  const contentType = request.headers.get('content-type') || 'application/json; charset=utf-8';
+  await env.BUCKET.put(path, request.body, {
+    httpMetadata: { contentType },
+    customMetadata: {
+      owner: auth.owner,
+      uploadedAt: new Date().toISOString(),
+    },
+  });
+
+  const headers = new Headers();
+  headers.set('cache-control', 'private, no-store');
+  return new Response(JSON.stringify({ ok: true, key: path }), {
+    status: 200,
+    headers,
+  });
+}
+
+async function handleGet(request, env, path) {
+  const auth = await authorizeRead(request, env, path);
+  if (auth.error) return auth.error;
+
+  const object = await env.BUCKET.get(path);
+  if (!object) return json({ error: 'not found' }, 404);
+
+  const headers = new Headers(object.httpMetadata ?? {});
+  headers.set('cache-control', 'private, no-store');
+  return new Response(object.body, { headers });
+}
+
+// Require a Phoenix bearer that owns the path prefix.
+async function authorizeRead(request, env, path) {
+  const claims = await hooks.verifyPhoenixToken(request, env);
+  if (!claims) return { error: json({ error: 'unauthorized' }, 401) };
+  const ownerId = path.split('/').filter(Boolean)[0] || '';
+  if (!ownerId || ownerId !== claims.userId) {
+    return { error: json({ error: 'forbidden' }, 403) };
+  }
+  return { claims };
+}
+
+// Two legitimate principals for writes: static WRITE_TOKEN first (BYO),
+// otherwise Phoenix bearer. 401 when neither authenticates.
+async function authorizeWrite(request, env) {
+  const presented = (request.headers.get('authorization') || '').replace(/^Bearer\\s+/i, '');
+  if (!presented) return { error: json({ error: 'unauthorized' }, 401) };
+  if (env.WRITE_TOKEN && safeEqual(presented, env.WRITE_TOKEN)) {
+    return { kind: 'byo', owner: env.TRACES_NAMESPACE || 'byo' };
+  }
+  const claims = await hooks.verifyPhoenixToken(request, env);
+  if (claims && typeof claims.userId === 'string' && claims.userId) {
+    return { kind: 'phoenix', owner: claims.userId };
+  }
+  return { error: json({ error: 'unauthorized' }, 401) };
+}
+
+async function defaultVerifyPhoenixToken(request, env) {
+  const presented = (request.headers.get('authorization') || '').replace(/^Bearer\\s+/i, '');
+  if (!presented) return null;
+  const base = typeof env.PHOENIX_ID_BASE === 'string' ? env.PHOENIX_ID_BASE.replace(/\\/+$/, '') : '';
+  if (!base) return null;
+  let res;
+  try {
+    res = await fetch(base + '/api/v1/auth/me', {
+      method: 'GET',
+      headers: { Authorization: 'Bearer ' + presented },
+    });
+  } catch {
+    return null;
+  }
+  if (!res.ok) return null;
+  let body;
+  try {
+    body = await res.json();
+  } catch {
+    return null;
+  }
+  if (!body || typeof body.userId !== 'string' || !body.userId) return null;
+  return { userId: body.userId, email: typeof body.email === 'string' ? body.email : '' };
+}
+
+function json(body, status = 200) {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: {
+      'content-type': 'application/json; charset=utf-8',
+      'cache-control': 'private, no-store',
+    },
+  });
+}
+
+// Constant-time comparison so timing attacks can't probe a static WRITE_TOKEN.
+function safeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}
+`;
+}

package/dist/lib/types.d.ts

@@ -29,6 +29,20 @@ export declare const RUN_AUTO_KEYWORD = "auto";
  * process.env (which exec.ts `runAutoDefaultsToAffinity` reads) never sees them.
  */
 export declare const RUN_AUTO_HOST_RESOLVED_ENV = "AGENTS_RUN_AUTO_HOST_RESOLVED";
+/**
+ * Env var a host dispatcher exports into the remote SHELL when it opens an
+ * INTERACTIVE `--device` run: tells the remote CLI that this agent's stdio is a
+ * network link, so the run must be detached (tmux-wrapped) to outlive it.
+ *
+ * Rides the same shell-export prelude as {@link RUN_AUTO_HOST_RESOLVED_ENV},
+ * and for the same reason — exec.ts `resolveTmuxWrap` reads the remote CLI's own
+ * `process.env`, which `--env` flags (they reach only the spawned AGENT) never
+ * touch.
+ *
+ * Set ONLY on the interactive path. A headless `--device` dispatch is already
+ * detached with setsid by `launchDetached`, so it neither needs nor gets this.
+ */
+export declare const REMOTE_INTERACTIVE_ENV = "AGENTS_REMOTE_INTERACTIVE";
 /** Per-agent run strategy config. */
 export interface AgentRunConfig {
     strategy?: RunStrategy;
@@ -958,30 +972,15 @@ export interface Meta {
      */
     hooks?: Record<string, ManifestHook>;
     /**
-     * Browser profile definitions keyed by profile name. Portable user config
-     * that syncs with `agents repo push/pull`. Runtime state (chrome-data, pids)
-     * lives separately in ~/.agents/.cache/browser/<profile>/.
-     */
-    browser?: Record<string, BrowserProfileConfig>;
-    /**
-     * Machine-local browser profiles — written to `config:`-adjacent
-     * `browser:` in `~/.agents/devices/<machine>/agents.yaml`, never the synced
-     * file.
-     *
-     * The auto-detected `default` profile lives here because it is inherently
-     * machine-specific: it carries an absolute `binary:` path and a port chosen by
-     * scanning THIS machine. Sharing it fleet-wide meant a macOS box wrote
-     * `/Applications/...`, a Linux box found it unlaunchable and rewrote
-     * `/usr/bin/chromium-browser`, and the two flipped the tracked agents.yaml back
-     * and forth on every `agents browser start` — the single largest source of
-     * churn on that file. User-created named profiles stay central and still sync.
+     * Browser profiles declared by this machine. Written as `browser:` in
+     * `~/.agents/devices/<machine>/agents.yaml`. The fleet registry is the union
+     * of every device file; central `agents.yaml` is not a browser-profile store.
      */
     deviceBrowser?: Record<string, BrowserProfileConfig>;
     /**
      * User-scope config block (`config:` in central agents.yaml). Holds the
      * user-scope keys from the device-config registry (`lib/device-config.ts`) —
-     * currently `interactiveHost` and `usagePrimaryHost`. Syncs fleet-wide via
-     * `agents repo push/pull`.
+     * currently `interactiveHost`. Syncs fleet-wide via `agents repo push/pull`.
      * Device-scope keys live in the per-device doc
      * `devices/<name>/agents.yaml` `config:` block, layered over the fleet-wide
      * defaults in {@link Meta.fleet} (`fleet.defaults.config`).

package/dist/lib/types.js

@@ -22,6 +22,20 @@ export const RUN_AUTO_KEYWORD = 'auto';
  * process.env (which exec.ts `runAutoDefaultsToAffinity` reads) never sees them.
  */
 export const RUN_AUTO_HOST_RESOLVED_ENV = 'AGENTS_RUN_AUTO_HOST_RESOLVED';
+/**
+ * Env var a host dispatcher exports into the remote SHELL when it opens an
+ * INTERACTIVE `--device` run: tells the remote CLI that this agent's stdio is a
+ * network link, so the run must be detached (tmux-wrapped) to outlive it.
+ *
+ * Rides the same shell-export prelude as {@link RUN_AUTO_HOST_RESOLVED_ENV},
+ * and for the same reason — exec.ts `resolveTmuxWrap` reads the remote CLI's own
+ * `process.env`, which `--env` flags (they reach only the spawned AGENT) never
+ * touch.
+ *
+ * Set ONLY on the interactive path. A headless `--device` dispatch is already
+ * detached with setsid by `launchDetached`, so it neither needs nor gets this.
+ */
+export const REMOTE_INTERACTIVE_ENV = 'AGENTS_REMOTE_INTERACTIVE';
 /** Every canonical mode in declaration order. Useful for iteration / validation. */
 export const ALL_MODES = ['plan', 'edit', 'auto', 'skip'];
 /** Canonical system repo cloned into ~/.agents/.system/. */