@phnx-labs/agents-cli 1.22.46 → 1.22.49

package/dist/lib/tmux/session.js

@@ -10,10 +10,110 @@
  * `tmux list-sessions` and prunes stale entries on the fly.
  */
 import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
 import { runTmux, TmuxCommandError } from './binary.js';
 import { ensureTmuxDir, getDefaultSocketPath, getSessionMetaPath } from './paths.js';
 /** Tmux session names must not contain `.` or `:` — those are reserved for window/pane addressing. */
 const VALID_NAME = /^[A-Za-z0-9_-]{1,64}$/;
+/**
+ * Ten times tmux's 2,000-line default, while keeping per-pane memory bounded:
+ * history storage scales with pane width, so a 200-column pane retains at most
+ * four million grid cells rather than an unbounded agent transcript.
+ */
+export const AGENTS_TMUX_HISTORY_LIMIT = 20_000;
+/**
+ * Bump when the generated startup config changes, so an ALREADY-RUNNING server
+ * picks the new settings up. tmux reads `-f` only when it actually starts a
+ * server: a second `new-session -f other.conf` against a live server exits 0
+ * and silently applies nothing (verified against tmux 3.4). Since agents-cli
+ * uses one long-lived shared socket, the normal state at upgrade is a running
+ * server — so without this reconcile every existing machine would get none of
+ * these defaults, silently. Same shape as AGENT_HOOK_SCHEMA below.
+ */
+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')}"`;
+}
+/**
+ * tmux loads `-f` instead of its normal user config, so put agents-cli's
+ * defaults first and explicitly source the first user config tmux would have
+ * selected afterward. Configuration files execute in order; this makes these
+ * settings defaults while preserving every option or binding the user sets.
+ */
+function writeStartupConfig(env) {
+    const effectiveEnv = env ?? process.env;
+    const home = effectiveEnv.HOME ?? os.homedir();
+    const candidates = [
+        path.join(home, '.tmux.conf'),
+        ...(effectiveEnv.XDG_CONFIG_HOME
+            ? [path.join(effectiveEnv.XDG_CONFIG_HOME, 'tmux', 'tmux.conf')]
+            : []),
+        path.join(home, '.config', 'tmux', 'tmux.conf'),
+    ];
+    // tmux's own start_cfg() sources EVERY entry of TMUX_CONF that exists, not
+    // just the first — a user with both ~/.tmux.conf and ~/.config/tmux/tmux.conf
+    // gets both. Sourcing only the first would silently drop the second and break
+    // the "never override a user-set value" contract this file exists to keep.
+    const userConfigs = candidates.filter((candidate) => fs.existsSync(candidate));
+    const startupConfig = path.join(ensureTmuxDir(), `startup-${process.pid}-${startupConfigSequence++}.conf`);
+    const lines = [
+        // Stamp the schema HERE as well as in reconcileServerConfig. Without it a
+        // cold start leaves the option unset, the post-new-session check sees a
+        // stale stamp, and the reconcile re-sources the user's config a second time
+        // on launch #1 — firing any run-shell side effect (TPM) twice.
+        `set-option -g ${CONFIG_SCHEMA_OPTION} ${AGENTS_TMUX_CONFIG_SCHEMA}`,
+        'set-option -g mouse on',
+        'set-option -s set-clipboard on',
+        `set-option -g history-limit ${AGENTS_TMUX_HISTORY_LIMIT}`,
+        'bind-key -T copy-mode MouseDragEnd1Pane send-keys -X copy-selection-no-clear',
+        'bind-key -T copy-mode-vi MouseDragEnd1Pane send-keys -X copy-selection-no-clear',
+    ];
+    for (const userConfig of userConfigs) {
+        lines.push(`source-file -q ${tmuxConfigArgument(userConfig)}`);
+    }
+    fs.writeFileSync(startupConfig, `${lines.join('\n')}\n`, { mode: 0o600 });
+    return startupConfig;
+}
+/** Build the atomic server-configuration + session-creation command. */
+export function buildCreateSessionArgs(opts, startupConfig) {
+    const args = [
+        '-f', startupConfig,
+        'set-option', '-g', 'remain-on-exit', 'on', ';',
+        'new-session', '-d', '-s', opts.name, '-P', '-F', '#{pane_id}',
+    ];
+    if (opts.width)
+        args.push('-x', String(opts.width));
+    if (opts.height)
+        args.push('-y', String(opts.height));
+    if (opts.cwd)
+        args.push('-c', opts.cwd);
+    // Separator + child command. tmux passes the rest verbatim to exec, so no
+    // shell escaping is required — array args end-to-end.
+    if (opts.cmd) {
+        args.push('--', 'sh', '-c', opts.cmd);
+    }
+    return args;
+}
 export class TmuxSessionError extends Error {
     cause;
     constructor(message, cause) {
@@ -44,6 +144,41 @@ export async function hasSession(name, socket) {
     });
     return res.code === 0;
 }
+/** Which AGENTS_TMUX_CONFIG_SCHEMA a live server has applied; undefined when none. */
+async function appliedConfigSchema(socket) {
+    const res = await runTmux({
+        socket,
+        args: ['show-options', '-gv', CONFIG_SCHEMA_OPTION],
+        throwOnError: false,
+    }).catch(() => null);
+    if (!res || res.code !== 0)
+        return undefined;
+    const n = Number(res.stdout.trim());
+    return Number.isFinite(n) ? n : undefined;
+}
+/**
+ * Apply the generated startup config to an already-running server and stamp it.
+ * Failure is surfaced, not swallowed: a server left without these settings is
+ * the silent no-op this exists to prevent.
+ */
+async function reconcileServerConfig(socket, env) {
+    const conf = writeStartupConfig(env);
+    try {
+        const res = await runTmux({ socket, args: ['source-file', conf], throwOnError: false, env });
+        if (res.code !== 0) {
+            throw new TmuxSessionError(`could not apply agents-cli tmux settings to the running server (${res.stderr.trim() || `exit ${res.code}`})`);
+        }
+        await runTmux({
+            socket,
+            args: ['set-option', '-g', CONFIG_SCHEMA_OPTION, String(AGENTS_TMUX_CONFIG_SCHEMA)],
+            throwOnError: false,
+            env,
+        }).catch(() => { });
+    }
+    finally {
+        fs.rmSync(conf, { force: true });
+    }
+}
 /**
  * Create a new detached session. Throws when the name is already taken unless
  * `replace` or `attachExisting` is set.
@@ -58,6 +193,13 @@ export async function createSession(opts) {
     const existed = await hasSession(opts.name, socket);
     if (existed) {
         if (opts.attachExisting) {
+            // Reuse of a live session is precisely the already-running-server case,
+            // so it needs the same reconcile the create path gets — otherwise
+            // `agents tmux new --attach-existing` silently keeps a pre-fix server
+            // with none of these settings.
+            if ((await appliedConfigSchema(socket)) !== AGENTS_TMUX_CONFIG_SCHEMA) {
+                await reconcileServerConfig(socket, opts.env);
+            }
             const meta = readSessionMeta(opts.name);
             return meta ?? {
                 name: opts.name,
@@ -71,28 +213,32 @@ export async function createSession(opts) {
         }
         await killSession(opts.name, socket);
     }
-    // Set remain-on-exit BEFORE the child command can finish — a fast-exiting
+    // Configure the agents-cli tmux server BEFORE the child command can finish — a fast-exiting
     // cmd (e.g. `echo BRIEF && true`) would otherwise collapse the only session,
     // exit the server, and the follow-up `set-option` would race with "no
     // server running". Server-wide (`-g`) is applied in the same tmux
     // invocation as new-session so they share one server lifetime.
     // `-P -F '#{pane_id}'` prints the new session's first pane id on stdout so we
     // can record the exact `%N` handle without a follow-up `list-panes`.
-    const args = ['set-option', '-g', 'remain-on-exit', 'on', ';', 'new-session', '-d', '-s', opts.name, '-P', '-F', '#{pane_id}'];
-    if (opts.width)
-        args.push('-x', String(opts.width));
-    if (opts.height)
-        args.push('-y', String(opts.height));
-    if (opts.cwd)
-        args.push('-c', opts.cwd);
-    // Separator + child command. tmux passes the rest verbatim to exec, so no
-    // shell escaping is required — array args end-to-end.
-    if (opts.cmd) {
-        args.push('--', 'sh', '-c', opts.cmd);
+    const startupConfig = writeStartupConfig(opts.env);
+    const args = buildCreateSessionArgs(opts, startupConfig);
+    let res;
+    try {
+        res = await runTmux({ socket, args, env: opts.env });
+    }
+    finally {
+        fs.rmSync(startupConfig, { force: true });
     }
-    const res = await runTmux({ socket, args, env: opts.env });
     // Only the new-session command in the `;`-chained invocation emits output.
     const pane = /^%\d+$/.test(res.stdout.trim()) ? res.stdout.trim() : undefined;
+    // If the server was ALREADY running, its `-f` was ignored, so the config above
+    // never applied. Re-source it — the generated file ends by sourcing the user's
+    // own tmux.conf, so re-applying preserves the same precedence a cold start
+    // gives. Gated on a generation stamp so a user config with side effects (tpm's
+    // run-shell, for one) is not re-executed on every single launch.
+    if (existed || (await appliedConfigSchema(socket)) !== AGENTS_TMUX_CONFIG_SCHEMA) {
+        await reconcileServerConfig(socket, opts.env);
+    }
     // Keep the agent pane around after its process exits (so runInTmux can read
     // the exit status and capture the final error), but do NOT keep that behavior
     // for user-created splits. Apply remain-on-exit to the agent pane only, then
@@ -102,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,
@@ -402,8 +563,17 @@ export async function setSessionHook(name, hook, command, socket, timeoutMs) {
  *        variant could stall the hook on a loaded CI runner, letting the dead
  *        split survive until the test's wait timeout expired (flake in CI shard
  *        3: pane-guarded pane-died hook / user split exit).
+ *   v6 — the agent-pane branch is now `session_attached`-aware: with a client
+ *        attached it `detach-client`s (the interactive path, so runInTmux's
+ *        attach returns and reads the exit status, EXEC-23b unchanged); with NO
+ *        client it `kill-session`s outright. A `remain-on-exit` pane with no
+ *        attach client to reap it otherwise lingers as a dead husk until the
+ *        daemon's periodic `reapDeadTmuxPanes` sweep — so a run whose terminal
+ *        was closed, or a `/exit` after the user detached, left an idle-looking
+ *        dead session on the socket. Killing it the instant the agent exits is
+ *        the "one close tears down every layer" contract (#5a).
  */
-export const AGENT_HOOK_SCHEMA = 5;
+export const AGENT_HOOK_SCHEMA = 6;
 /** Per-session tmux user-option that records which AGENT_HOOK_SCHEMA a session's hook is at. */
 const HOOK_SCHEMA_OPTION = '@ag_hook_schema';
 /**
@@ -416,21 +586,28 @@ const HOOK_SCHEMA_OPTION = '@ag_hook_schema';
  */
 const TMUX_HOOK_REPAIR_TIMEOUT_MS = 5_000;
 /**
- * The guarded `pane-died` hook. Detach the client ONLY when the agent pane dies
- * (so the blocking attach in runInTmux returns and the exit status can be read);
- * a user split's death runs the else-branch, closing just that split. The
- * else-branch goes through `run-shell -b -C` with an explicit `-t #{hook_pane}`
- * target: tmux format-expands the command at fire time and executes it inside
- * the server command queue in the background, so the event pane is always the
- * one killed without launching a second tmux client against the same socket and
- * without stalling the hook on a loaded runner. A bare `kill-pane` relied on
- * the hook context supplying a "current pane", while an external self-client
- * could race the server under load. Single source of truth: both the
- * spawn-wrap (exec.ts) and the daemon reconcile build the hook here, so the
- * two can never drift.
+ * The guarded `pane-died` hook. When the AGENT pane dies, tear the whole session
+ * down — but HOW depends on whether a client is attached:
+ *   - attached (`#{session_attached}`): `detach-client` so the blocking attach in
+ *     runInTmux returns and `resolveAfterAttach` reads the exit status off the
+ *     still-`remain-on-exit` dead pane, then kills the session (EXEC-23b, unchanged);
+ *   - no client: `kill-session` outright. Without this the dead pane sits under
+ *     `remain-on-exit` as an idle-looking husk until the daemon's periodic
+ *     `reapDeadTmuxPanes` sweep — the "second exit" / orphaned-idle session bug
+ *     when a wrapped agent exits with nobody attached (a closed terminal, or a
+ *     `/exit` after the user detached). `detach-client` on an unattached session
+ *     is a no-op, so the old hook left the husk; `kill-session` ends it at once.
+ * A user split's death still runs the else-branch, closing just that split via
+ * `run-shell -b -C` with an explicit `-t #{hook_pane}` target: tmux format-expands
+ * the command at fire time and executes it inside the server command queue in the
+ * background, so the event pane is always the one killed without launching a second
+ * tmux client against the same socket and without stalling the hook on a loaded
+ * runner. Single source of truth: both the spawn-wrap (exec.ts) and the daemon
+ * reconcile build the hook here, so the two can never drift.
  */
 export function agentPaneDiedHook(sessionName, agentPane) {
-    return `if -F '#{==:#{hook_pane},${agentPane}}' 'detach-client -s =${sessionName}' 'run-shell -b -C "kill-pane -t #{hook_pane}"'`;
+    const agentPaneAction = `if -F '#{session_attached}' 'detach-client -s =${sessionName}' 'kill-session -t =${sessionName}'`;
+    return `if -F '#{==:#{hook_pane},${agentPane}}' "${agentPaneAction}" 'run-shell -b -C "kill-pane -t #{hook_pane}"'`;
 }
 /** Stamp a session's hook-schema marker to the current version. */
 export async function markSessionHookSchema(name, socket, timeoutMs) {

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}` };
+}