@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/traces/phenotype.js

@@ -1,20 +1,3 @@
-/**
- * Failure phenotype classifier + outcome taxonomy for the traces insight engine.
- *
- * Both functions are pure: they take a redacted {@link SessionDetail} (the same
- * shape the traces sync writes to `sessions/<id>.json`) and return a decision
- * derived only from the already-derived step/gap/meta signal. They never read
- * raw transcript text and never fabricate a signal that is not in the data.
- *
- * The rubrics are expressed as data-driven tables of conditions, not as
- * if/else-by-name chains. Each table row is a named phenotype/outcome with a
- * declarative predicate; the classifier walks the table in priority order and
- * returns the first match, or the honest lower-confidence default when no
- * high-confidence signal is present.
- */
-// ---------------------------------------------------------------------------
-// Tool / program category tables
-// ---------------------------------------------------------------------------
 const READ_PLAN_TOOLS = new Set([
     'Read',
     'read_file',
@@ -57,9 +40,6 @@ const OUTCOME_SIGNALS = [
     { type: 'env', pattern: /\bssh.*key\b|\bclone\b.*\bfailed\b/i },
     { type: 'revert', pattern: /\brevert\b|\bgit checkout\b|\breset\s+--hard\b/i },
 ];
-// ---------------------------------------------------------------------------
-// Step helpers
-// ---------------------------------------------------------------------------
 function isToolStep(step) {
     return step.kind === 'tool';
 }
@@ -104,8 +84,6 @@ function signalCounts(session) {
     for (const step of session.steps) {
         const text = stepText(step);
         for (const signal of OUTCOME_SIGNALS) {
-            // Merge/test signals must come from an actual shell/exec step, otherwise
-            // a grep pattern or read_file detail false-positives as a landing signal.
             if ((signal.type === 'merge' || signal.type === 'test') && !isShellStep(step))
                 continue;
             if (signal.pattern.test(text))
@@ -114,17 +92,6 @@ function signalCounts(session) {
     }
     return counts;
 }
-// ---------------------------------------------------------------------------
-// Phenotype predicates
-// ---------------------------------------------------------------------------
-/**
- * Failure-to-act: the agent stalled or produced no meaningful tool use.
- *
- * Rubric:
- * - zero tool calls and ≤2 turns, or
- * - all substantive steps are `thinking`/human-facing, or
- * - the session ended on a human-facing ask with no follow-up tool work.
- */
 function isFailureToAct(session) {
     if (session.meta.tools === 0 && session.meta.turns <= 2)
         return true;
@@ -137,12 +104,6 @@ function reasonFailureToAct(session) {
     }
     return 'no substantive tool steps';
 }
-/**
- * Out-of-order: a write/edit happened before any read/plan of the target.
- *
- * Rubric: the first substantive step is a write/edit and no earlier read/plan
- * or search step exists.
- */
 function isOutOfOrder(session) {
     const firstWrite = firstStepOrdinalOf(session, (s) => WRITE_EDIT_TOOLS.has(s.tool ?? s.lane));
     if (firstWrite === undefined)
@@ -156,41 +117,12 @@ function reasonOutOfOrder(session) {
     const tool = session.steps.find((s) => WRITE_EDIT_TOOLS.has(s.tool ?? s.lane));
     return `write/edit step ${tool?.tool ?? tool?.lane ?? ''} preceded any read/plan`;
 }
-/**
- * The **work signature** of a step — what work it represents, so a later success
- * can be matched back to the specific failure it resolves. For a shell step this
- * is the effective program (`bun`, `git`, `gh`, …, from `TrajectoryStep.program`),
- * so a failed `bun test` is resolved by a later `bun test` but NOT by an incidental
- * `ls`. For any other tool it is the tool identity, so a failed `Edit` is resolved
- * by a later successful `Edit`, not by an unrelated `Read`. A shell step whose
- * command did not parse (no `program`) degrades to the bare tool name, matching
- * the pre-`program` behavior only for that unparseable minority.
- */
 function workSignature(step) {
     const tool = step.tool ?? step.lane;
     if (SHELL_TOOLS.has(tool) && step.program)
         return `${tool}:${step.program}`;
     return tool;
 }
-/**
- * Did a run that hit tool errors nonetheless *recover and finish*?
- *
- * The causal recovery test: a **substantive** tool step (not a human-facing
- * `AskUserQuestion` / `SendMessage` / `wait`) SUCCEEDED strictly AFTER the last
- * error's ordinal, AND that success resolves the failed work — its
- * {@link workSignature} matches an errored step's. A later success of *unrelated*
- * work does NOT count: a `bun test` failure followed by an incidental `ls` leaves
- * the failed test unresolved, so the run stays errored, even though the `ls`
- * succeeded after it. A punt to a human is excluded twice over — human-facing
- * tools are outside the substantive set, and they never match a failed signature.
- *
- * This is the single source of truth for "did this finish", shared by the
- * false-termination phenotype below and `sync.ts`'s `deriveRunOutcome` — so a
- * run's console outcome and its failure phenotype can never disagree about
- * whether it recovered. It reads only the derived steps, never `meta.outcome`,
- * precisely so `deriveRunOutcome` can call it while it is still *computing*
- * `meta.outcome`.
- */
 export function recoveredAfterErrors(session) {
     const substantive = substantiveSteps(session);
     if (substantive.length === 0)
@@ -211,14 +143,6 @@ export function recoveredAfterErrors(session) {
         !HUMAN_FACING_TOOLS.has(s.tool ?? s.lane) &&
         failedSignatures.has(workSignature(s)));
 }
-/**
- * False-termination: the session stopped with an unresolved error.
- *
- * Rubric:
- * - meta outcome is `errored`, and
- * - at least one step outcome is `error`, and
- * - the run did not causally recover ({@link recoveredAfterErrors}).
- */
 function isFalseTermination(session) {
     if (session.meta.outcome !== 'errored')
         return false;
@@ -236,23 +160,6 @@ function reasonFalseTermination(session) {
     }
     return 'errored with no successful recovery after the last error';
 }
-/**
- * Premature-completion: declared done without a verification step for an
- * engineering task.
- *
- * Rubric:
- * - meta outcome is `completed`, and
- * - the session performed write/edit work, and
- * - no test/build/lint verification step ran.
- *
- * `errorCount` is deliberately NOT a signal here. Under truthful outcomes
- * (PHNX-3387) a `completed` run CAN carry `errorCount > 0` — that is precisely a
- * recover-then-succeed run, where the errors were *resolved*, not left hanging.
- * Keying prematurity off `errorCount > 0` would mislabel every such recovery as
- * premature. (Under the pre-PHNX-3387 `errorCount > 0 ? errored : completed`
- * derivation this branch was unreachable — a `completed` run always had
- * `errorCount === 0` — so dropping it changes nothing for a clean-completed run.)
- */
 function isPrematureCompletion(session) {
     if (session.meta.outcome !== 'completed')
         return false;
@@ -270,30 +177,18 @@ function isPrematureCompletion(session) {
 function reasonPrematureCompletion(_session) {
     return 'engineering work completed without a test/build/lint verification step';
 }
-/** Ordered rubric: the first matching phenotype wins. */
 const PHENOTYPE_RULES = [
     { key: 'failure-to-act', score: isFailureToAct, reason: reasonFailureToAct },
     { key: 'out-of-order', score: isOutOfOrder, reason: reasonOutOfOrder },
     { key: 'false-termination', score: isFalseTermination, reason: reasonFalseTermination },
     { key: 'premature-completion', score: isPrematureCompletion, reason: reasonPrematureCompletion },
 ];
-// ---------------------------------------------------------------------------
-// Outcome predicates
-// ---------------------------------------------------------------------------
-/** High-confidence merge when explicit merge command/signal exists and session completed. */
 function isMerged(session) {
-    // Only a shell/exec step can produce a real merge signal; grep patterns and
-    // read_file details must not count.
     return session.meta.outcome === 'completed' && hasSignal(session, 'merge', SHELL_TOOLS);
 }
 function mergedReason(session) {
     return 'explicit merge signal present and session completed';
 }
-/**
- * Tests-green when a test/build/lint step returned ok, or when the session
- * completed cleanly with test steps whose individual outcomes are unknown
- * (e.g. Grok-derived sessions that record spanMs=0 and never pair results).
- */
 function isTestsGreen(session) {
     if (session.meta.outcome !== 'completed')
         return false;
@@ -308,7 +203,6 @@ function isTestsGreen(session) {
     const lastTest = testSteps[testSteps.length - 1];
     if (lastTest.outcome === 'ok')
         return true;
-    // Infer from a clean completion when step-level outcomes are not available.
     return session.meta.errorCount === 0;
 }
 function testsGreenConfidence(session) {
@@ -327,7 +221,6 @@ function testsGreenReason(session) {
         ? 'last test/build/lint step returned ok'
         : 'completed cleanly with test steps (step outcomes unavailable)';
 }
-/** Human-takeover when the final tool action asks the human. */
 function isHumanTakeover(session) {
     const tools = session.steps.filter((s) => isToolStep(s));
     if (tools.length === 0)
@@ -340,14 +233,6 @@ function humanTakeoverReason(session) {
     const last = tools[tools.length - 1];
     return `final tool step is ${last.tool ?? last.lane}`;
 }
-/**
- * Invalid-env when setup/environment failures dominate the session.
- *
- * Rubric:
- * - ≥2 env errors and they make up at least half of all errors, or
- * - ≥3 env steps with ≥50% error rate in an errored session, or
- * - the first substantive error is an env/setup error and no recovery follows it.
- */
 function isInvalidEnv(session) {
     const envSteps = session.steps.filter((s) => {
         const text = stepText(s);
@@ -384,7 +269,6 @@ function invalidEnvReason(session) {
     }
     return 'environment/setup failures dominated the early session and blocked recovery';
 }
-/** Abandoned when the session errored and stalled without recovery. */
 function isAbandoned(session) {
     if (session.meta.outcome !== 'errored')
         return false;
@@ -402,7 +286,6 @@ function abandonedReason(session) {
     const hasStall = session.gaps.some((g) => g.durationMs >= 120_000);
     return hasStall ? 'errored with a long stall and no recovery' : 'errored with no successful recovery';
 }
-/** Partial: progress was made but no landing or test signal is present. */
 function isPartial(_session) {
     return true;
 }
@@ -420,10 +303,6 @@ function partialReason(session) {
 function ruleConfidence(rule, session) {
     return typeof rule.confidence === 'function' ? rule.confidence(session) : rule.confidence;
 }
-/**
- * Ordered rubric: the first matching outcome wins. `partial` is the
- * lower-confidence default when no high/medium-confidence signal is present.
- */
 const OUTCOME_RULES = [
     { key: 'merged', confidence: 'high', score: isMerged, reason: mergedReason },
     { key: 'tests-green', confidence: testsGreenConfidence, score: isTestsGreen, reason: testsGreenReason },
@@ -432,26 +311,9 @@ const OUTCOME_RULES = [
     { key: 'abandoned', confidence: 'medium', score: isAbandoned, reason: abandonedReason },
     { key: 'partial', confidence: 'low', score: isPartial, reason: partialReason },
 ];
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-/**
- * Classify the failure phenotype of a session from its derived trajectory.
- *
- * Definitions (from agent-failure research):
- * - `false-termination`  — stopped with an unresolved error (did not causally recover).
- * - `premature-completion` — declared done with no verification step for the
- *   engineering work.
- * - `out-of-order` — a write/edit step occurred before any read/plan of the
- *   target.
- * - `failure-to-act` — stalled or produced no meaningful tool use.
- *
- * Returns `null` when none of the failure phenotypes apply.
- */
 export function classifyPhenotype(session) {
     return classifyPhenotypeDetailed(session).phenotype;
 }
-/** Detailed phenotype result with a human-readable reason. */
 export function classifyPhenotypeDetailed(session) {
     for (const rule of PHENOTYPE_RULES) {
         if (rule.score(session)) {
@@ -460,26 +322,14 @@ export function classifyPhenotypeDetailed(session) {
     }
     return { phenotype: null, reason: 'no failure phenotype matched' };
 }
-/**
- * Derive the coarse outcome of a session from its end state + tool signals.
- *
- * `merged` and `tests-green` are high-confidence only when an explicit signal
- * is present in the derived steps. When that signal is genuinely not in the
- * data, the function returns the honest lower-confidence value (`partial` for
- * completed work without a landing signal, `abandoned` for errored/unresolved
- * work, `invalid-env` for setup-dominant failures, `human-takeover` when the
- * session ends on a human-facing ask).
- */
 export function deriveOutcome(session) {
     return deriveOutcomeDetailed(session).outcome;
 }
-/** Detailed outcome result with confidence and a human-readable reason. */
 export function deriveOutcomeDetailed(session) {
     for (const rule of OUTCOME_RULES) {
         if (rule.score(session)) {
             return { outcome: rule.key, confidence: ruleConfidence(rule, session), reason: rule.reason(session) };
         }
     }
-    // `partial` is the exhaustive default; this line is unreachable but keeps TS happy.
     return { outcome: 'partial', confidence: 'low', reason: 'no outcome signal matched' };
 }

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

@@ -10,7 +10,6 @@ interface ProvisionTracesOptions extends ProvisionOptions {
     phoenixIdBase: string;
     domain?: string;
 }
-/** Provision the complete isolated traces deployment using the canonical Worker template. */
 export declare function provisionTraces(opts: ProvisionTracesOptions): Promise<{
     baseUrl: string;
 }>;

package/dist/lib/traces/provision.js

@@ -1,18 +1,13 @@
-// Cloudflare orchestration for the private agents-traces store. The generic
-// request primitives live in cloudflare/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 '../cloudflare/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. */
 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 } : {};

package/dist/lib/traces/schema2-build.d.ts

@@ -1,42 +1,8 @@
-/**
- * schema2-build — the PRODUCER's per-tool mappers + `buildSessionDetailV2`
- * (PHNX-3442 step 2, increments 2-4).
- *
- * Populates the `SessionStepV2` discriminated union (schema2.ts) from the parsed
- * session events, reusing the SAME infrastructure the schema-1 path already uses:
- *
- *   - the callId pairing loop (`pairSteps` in session/trajectory.ts) — so a step's
- *     (use event, result event) triple is recovered without a duplicate loop;
- *   - bash unwrap/tokenize/classify (`session/bash-command.ts`) + the effective
- *     program resolver (`effectiveProgram`);
- *   - the meta / whereItWentWrong / surfacedToolFailures / active-time helpers
- *     factored out of sync.ts (`buildDetailMeta`, `buildWhereItWentWrong`, …).
- *
- * The command/patch/output PARSING lives here; the worker stores the shard
- * opaquely and the console reads the union directly and never reparses (spec §5).
- *
- * category / risk / categoryMetrics are DELIBERATELY omitted from the schema-2
- * detail: the shipped consumer (`decodeSessionDetail` → coerceCategory/Risk/Metrics)
- * backfills them to the same neutral defaults it uses for schema-1, so computing
- * them here would be inventing session-level signal this step does not own.
- */
-import { type BashCategory as ClassifierCategory } from '../session/bash-command.js';
-import { type SessionTrajectory } from '../session/trajectory.js';
-import type { SessionEvent } from '../session/types.js';
+import { type BashCategory as ClassifierCategory } from '@phnx-labs/sessions-cli/reader';
+import { type SessionTrajectory } from '@phnx-labs/sessions-cli/reader';
+import type { SessionEvent } from '@phnx-labs/sessions-cli/reader';
 import type { BashAction, BashCategory, SessionStepV2 } from './schema2.js';
 import { activeMsFromTrajectory, type SessionDetail } from './sync.js';
-/**
- * SessionDetailV2 — the schema-2 shard this producer emits.
- *
- * `category` / `risk` / `categoryMetrics` are DELIBERATELY OMITTED. The consumer's
- * `SessionDetailV2` declares them, but its `decodeSchema2` backfills neutral
- * defaults via `coerceCategory`/`coerceRisk`/`coerceMetrics` (never throws) — the
- * same defaulting it applies to schema-1 shards today. This producer does not yet
- * author those fields (their provenance is the prix/api PHNX-3351 hosted backend,
- * not agents-cli), so emitting them here would fabricate classification. Omission
- * is the honest choice and is asserted as a tested contract in
- * `schema2-fixture.test.ts`. Wire real category/risk here once its source is settled.
- */
 export interface SessionDetailV2 {
     schema: 2;
     id: string;
@@ -51,35 +17,12 @@ export interface SessionDetailV2 {
         detail?: string;
     }>;
 }
-/**
- * `unwrapCommand` (bash-command.ts) strips VAR=/sudo/cd&&/npx/loops/subshells but
- * NOT an interpreter wrapper like `/bin/zsh -lc "…"`, `bash -lc '…'`, or `sh -c …`
- * — the exact shape the managed runner wraps every command in. Peel that first,
- * then hand the inner payload to the existing unwrapper so all the wrappers it DOES
- * know still apply. One extra rule, at the source, not a fork of unwrapCommand.
- */
 export declare function unwrapShellExec(command: string): string;
-/**
- * Map a classifier `BashCategory` (the rich vcs|build-test|install|… taxonomy) to
- * the coarse schema-2 `BashCategory` (build|test|git|network|other). `build-test`
- * needs the argv/subcommand to decide build vs test — `bun test` is test, `bun
- * build` is build — so this takes the tokenized argv too.
- */
 export declare function mapBashCategory(cat: ClassifierCategory, argv: string[]): BashCategory;
-/** Build the per-segment BashAction list for a bash command. */
 export declare function buildBashActions(unwrapped: string): BashAction[];
 interface BuildDetailV2Options {
     redact?: boolean;
     knownSecrets?: readonly string[];
 }
-/**
- * Build the schema-2 per-session detail from a pre-built trajectory and its raw
- * events. The trajectory supplies meta/gaps/whereItWentWrong/surfacedToolFailures
- * (via the shared sync.ts helpers) and the truncation count; the raw events supply
- * the per-tool detail the schema-1 flat step could not carry.
- *
- * Re-pairs the events with `pairSteps` (the SAME loop buildTrajectory ran) to
- * recover each step's (use event, result event) triple, then dispatches per tool.
- */
 export declare function buildSessionDetailV2(traj: SessionTrajectory, events: SessionEvent[], options?: BuildDetailV2Options): SessionDetailV2;
 export { activeMsFromTrajectory };