@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/session/team-filter.js

@@ -1,269 +0,0 @@
-/**
- * Classification and filtering of team-spawned sessions.
- *
- * Sessions launched by `agents teams` carry an 'sdk-cli' entrypoint and
- * optionally have a meta.json with handle/mode info. This module determines
- * whether a session is team-origin and splits session lists into visible
- * and hidden groups for the picker UI.
- */
-import * as fs from 'fs';
-import * as os from 'os';
-import * as path from 'path';
-import { sanitizeForTerminal } from './parse.js';
-import { getTeamsAgentsDir } from '../state.js';
-const HOME = os.homedir();
-// Default path; tests can override via AGENTS_TEAMS_DIR env var.
-/** Resolve the directory containing per-session team metadata files. */
-function teamsAgentsDir() {
-    return process.env.AGENTS_TEAMS_DIR ?? getTeamsAgentsDir();
-}
-/**
- * Determine whether `session` was spawned by `agents teams`.
- *
- * Primary signal is `session.isTeamOrigin`, captured at scan time from the
- * JSONL `entrypoint` field ('sdk-cli' for team spawns, 'cli' for real CLI).
- * When a team meta.json exists we additionally enrich with handle/mode/team and
- * the orchestrator that spawned it — but its absence no longer demotes a
- * session: older team runs whose meta dir was cleaned up still get recognized
- * via the entrypoint flag.
- *
- * Returns the TeamOrigin metadata when the session is team-origin, or null
- * when it is a normal interactive session.
- */
-export function classifyTeamSession(session) {
-    const origin = teamOriginIndex().get(session.id);
-    if (origin)
-        return origin;
-    if (session.isTeamOrigin) {
-        return { handle: session.id.slice(0, 8), source: 'entrypoint' };
-    }
-    return null;
-}
-/**
- * Parse one teammate `meta.json` into a {@link TeamOrigin}. Degrades to a bare
- * handle when the file is unreadable or malformed — a teammate whose record we
- * can't parse is still a teammate.
- */
-function readTeamOrigin(metaPath, agentId) {
-    try {
-        const meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
-        const str = (v) => (typeof v === 'string' && v ? v : undefined);
-        return {
-            origin: {
-                handle: str(meta.name) ?? agentId.slice(0, 8),
-                mode: str(meta.mode),
-                team: str(meta.task_name),
-                parentSessionId: str(meta.parent_session_id),
-                startedAt: str(meta.started_at),
-                source: 'meta',
-            },
-            sessionId: str(meta.remote_session_id),
-        };
-    }
-    catch {
-        // An unreadable meta.json still lives under the teams agents dir, so the
-        // session IS a teammate — mark the source accordingly, just without fields.
-        return { origin: { handle: agentId.slice(0, 8), source: 'meta' } };
-    }
-}
-/**
- * A team name / handle as it is safe to render: a real string, terminal escapes
- * stripped, or undefined.
- *
- * These values reach the row and the preview pane, and for a peer's row they are
- * whatever JSON that machine sent — `parseRemoteList` copies the object through
- * without inspecting its fields, so neither the type nor the content is ours to
- * assume. A non-string `spawnedTeam` used to throw out of `teamBadge`, which runs
- * on every row, taking down the whole listing rather than one entry.
- */
-export function safeTeamText(value) {
-    if (typeof value !== 'string' || value === '')
-        return undefined;
-    return sanitizeForTerminal(value);
-}
-/** Cached teammate index; the directory is small (teams GC it after 7 days). */
-let originIndexCache = null;
-/** Drop the cached teammate index — for tests that rewrite AGENTS_TEAMS_DIR. */
-export function _resetTeamOriginIndex() {
-    originIndexCache = null;
-}
-/**
- * Every teammate record, keyed by the session ids it can be reached under.
- *
- * A teammate's directory name is its **agent id**, which is only sometimes the
- * id of the transcript it produced: the harness mints its own session id, and
- * the spawn records it separately as `remote_session_id`. Keying the lookup on
- * the directory name alone therefore missed most teammates — on a live box, 14
- * of 16 records were reachable only by `remote_session_id` — so a teammate row
- * could not name its team however good the record was. Both keys are registered.
- *
- * Read once per process rather than per row: the old per-session `existsSync` +
- * `readFileSync` cost a pair of syscalls for every row in the pool, which the
- * interactive browser re-pays on each hotkey.
- */
-function teamOriginIndex() {
-    if (originIndexCache)
-        return originIndexCache;
-    const dir = teamsAgentsDir();
-    const index = new Map();
-    let entries;
-    try {
-        entries = fs.readdirSync(dir);
-    }
-    catch {
-        entries = [];
-    }
-    for (const agentId of entries) {
-        const metaPath = path.join(dir, agentId, 'meta.json');
-        if (!fs.existsSync(metaPath))
-            continue;
-        const { origin, sessionId } = readTeamOrigin(metaPath, agentId);
-        index.set(agentId, origin);
-        if (sessionId)
-            index.set(sessionId, origin);
-    }
-    originIndexCache = index;
-    return index;
-}
-/**
- * Attach `teamOrigin` to every team-spawned row in `sessions`, from the shared
- * teammate index rather than a stat per row.
- */
-export function enrichTeamOrigins(sessions) {
-    const index = teamOriginIndex();
-    return sessions.map((session) => {
-        // A peer's rows are classified on the peer (its meta.json is on its disk, not
-        // ours) and ride across in the --json fan-out already populated. Re-deriving
-        // here would find no local record and downgrade a named teammate to a bare id.
-        if (session.teamOrigin)
-            return session;
-        const origin = index.get(session.id) ??
-            (session.isTeamOrigin ? { handle: session.id.slice(0, 8), source: 'entrypoint' } : null);
-        return origin ? { ...session, teamOrigin: origin } : session;
-    });
-}
-/**
- * Whether a listing scope must retain team-origin sessions.
- *
- * A routine owns every session produced during its run, including teammates and
- * SDK-launched children. Requiring callers to add `--teams` would make a routine
- * catalog incomplete and can make team-heavy routines appear to have no runs.
- */
-export function shouldShowTeamSessions(filters) {
-    return !!filters.teams || !!filters.routine;
-}
-/**
- * Split `sessions` into visible and hidden (team-origin) groups.
- * When `showTeams` is true every session is visible and `teamOrigin` is
- * populated on team sessions for display. When false, team sessions are
- * excluded and counted in `hiddenCount`.
- */
-export function filterTeamSessions(sessions, showTeams) {
-    let hiddenCount = 0;
-    const visible = [];
-    for (const session of sessions) {
-        const origin = classifyTeamSession(session);
-        if (origin !== null) {
-            if (showTeams) {
-                visible.push({ ...session, teamOrigin: origin });
-            }
-            else {
-                hiddenCount++;
-            }
-        }
-        else {
-            visible.push(session);
-        }
-    }
-    return { visible, hiddenCount };
-}
-/**
- * Whether a team-origin session is a real `agents teams` teammate or a bare SDK
- * spawn with no teammate record. The two share the `sdk-cli` entrypoint that
- * sets `isTeamOrigin`, so they are told apart by whether a `meta.json` teammate
- * record backs the origin ({@link TeamOrigin.source} === `'meta'`).
- *
- * `source` is newer than the rest of {@link TeamOrigin}, so a row that arrived
- * from a pre-`source` peer over the `--device` fan-out carries none. There the
- * meta-only fields settle it: the entrypoint fallback is a bare `{ handle }`, so
- * any `team` / `mode` / `parentSessionId` / `startedAt` means a real teammate
- * record produced it — otherwise a genuine teammate from an unupgraded peer
- * would be misfiled into the no-team bucket, the exact conflation this splits.
- */
-export function teamRowKind(origin) {
-    if (!origin)
-        return 'subagent';
-    if (origin.source === 'meta')
-        return 'teammate';
-    if (origin.source === 'entrypoint')
-        return 'subagent';
-    return origin.team || origin.mode || origin.parentSessionId || origin.startedAt
-        ? 'teammate'
-        : 'subagent';
-}
-/**
- * Key/label for the residual bucket — sessions flagged `isTeamOrigin` (an SDK /
- * `sdk-cli` entrypoint) that carry no teammate `meta.json`. In practice this is
- * headless `agents run` spawns and teammates whose team record aged out; a true
- * `Task` sub-agent's transcript is never indexed, so it cannot land here. Named
- * "(no team)" rather than "(sub-agents)" so the label matches what it holds.
- */
-export const NO_TEAM_GROUP_KEY = '(no team)';
-/** Key/label for teammates whose record carries no team name (`task_name`). */
-export const UNNAMED_TEAM_KEY = '(unnamed team)';
-/** Recency signal for a row: last activity, else the creation timestamp. */
-function rowTs(s) {
-    return s.lastActivity ?? s.timestamp;
-}
-/** Spawn time for a row: the meta `started_at`, else the transcript creation time. */
-function spawnTs(s) {
-    return s.teamOrigin.startedAt ?? s.timestamp;
-}
-/**
- * Group team-origin sessions for the `--teams` view: each named team becomes one
- * group of its teammates, and every bare SDK spawn with no teammate record falls
- * into a single trailing {@link NO_TEAM_GROUP_KEY} bucket, so a real teammate and
- * a bare spawn are never shown as the same thing.
- *
- * Only rows with a resolved {@link TeamOrigin} participate (the caller has
- * already run {@link filterTeamSessions}); any non-team session is ignored.
- * Groups are ordered newest-active first; sub-agents always sort last. Pure —
- * unit-tested.
- */
-export function groupSessionsByTeam(sessions) {
-    const byKey = new Map();
-    for (const s of sessions) {
-        if (!s.teamOrigin)
-            continue;
-        const kind = teamRowKind(s.teamOrigin);
-        const key = kind === 'subagent'
-            ? NO_TEAM_GROUP_KEY
-            : safeTeamText(s.teamOrigin.team) ?? UNNAMED_TEAM_KEY;
-        const ts = s;
-        (byKey.get(key) ?? byKey.set(key, []).get(key)).push(ts);
-    }
-    const groups = [];
-    for (const [key, rows] of byKey) {
-        rows.sort((a, b) => (rowTs(a) < rowTs(b) ? 1 : rowTs(a) > rowTs(b) ? -1 : 0));
-        const kind = key === NO_TEAM_GROUP_KEY ? 'noTeam' : 'team';
-        // A single agreed-on spawner names the orchestrator for the whole team; a
-        // mix (or none) leaves it unset rather than claiming a wrong parent.
-        const parents = new Set(rows.map((r) => r.teamOrigin.parentSessionId).filter((p) => !!p));
-        groups.push({
-            key,
-            kind,
-            team: kind === 'team' && key !== UNNAMED_TEAM_KEY ? key : undefined,
-            spawnerSessionId: parents.size === 1 ? [...parents][0] : undefined,
-            sessions: rows,
-            maxTs: rowTs(rows[0]),
-            firstSpawnTs: rows.map(spawnTs).sort()[0],
-        });
-    }
-    // Newest-active team first; the no-team bucket always sinks to the bottom.
-    groups.sort((a, b) => {
-        if (a.kind !== b.kind)
-            return a.kind === 'noTeam' ? 1 : -1;
-        return a.maxTs < b.maxTs ? 1 : a.maxTs > b.maxTs ? -1 : a.key.localeCompare(b.key);
-    });
-    return groups;
-}

package/dist/lib/session/timeline.d.ts

@@ -1,172 +0,0 @@
-/**
- * The narration-anchored session timeline (PHNX-3939) — a pure, resumable fold.
- *
- * A transcript is a flat event stream: the agent says a line, runs six tools,
- * says the next line. A person reading a sidebar wants the LINES, with the tool
- * calls collapsed underneath them. That is the whole model here: one
- * {@link SessionStep} per narration beat, the calls until the next beat folded
- * into counts, failures and milestones.
- *
- * Two properties this module is built around:
- *
- *   - **Deterministic, no model.** The headline is the harness's OWN narration
- *     (Claude assistant text, Codex `AgentMessage` commentary, Gemini thought
- *     subject) and the per-tool label is the harness's own (`description`,
- *     `state.title`, the parsed command). Nothing is invented; the optional
- *     summarizer polishes ON TOP and is never required.
- *   - **Resumable.** {@link foldTimeline} takes the state from the previous fold
- *     and the events that arrived since, so the daemon reads only the bytes a
- *     transcript grew by. Folding the appended tail onto the prior state is
- *     identical to folding the whole file from zero — every piece of mutable
- *     state lives in the serializable {@link TimelineState}, nothing in a
- *     closure.
- *
- * No I/O: the pass (`timeline-pass.ts`) reads bytes and calls this. Same
- * discipline as `digest.ts` and `trajectory.ts`.
- */
-import type { SessionEvent, SessionFileChange, SessionFiles, SessionRequest, SessionStep, SessionTimeline, SessionVerbClass } from './types.js';
-/**
- * Bumped when the fold's OUTPUT changes, so a cached state computed by an older
- * CLI is recomputed rather than rendered. Same role as
- * `SESSION_SUMMARY_EXTRACTOR_VERSION`.
- */
-export declare const TIMELINE_EXTRACTOR_VERSION = 1;
-/** Steps carried on the row in full; everything older folds into a counter. */
-export declare const TIMELINE_KEEP_STEPS = 8;
-/** One file the session touched, as accumulated during the fold. */
-interface TimelineFileEntry {
-    op: SessionFileChange['op'];
-    edits: number;
-    at: string;
-    /** True when a harness file ledger (not a tool argument) recorded this path. */
-    harness: boolean;
-}
-/**
- * Everything the fold needs to continue from where it stopped. Serialized into
- * `session_timelines.state_json`; every field is plain JSON on purpose (`open`
- * and `pending` are indices, not object references) so a resume is exact.
- */
-export interface TimelineState {
-    version: number;
-    /** Byte offset just past the last COMPLETE record folded. */
-    offset: number;
-    steps: SessionStep[];
-    /** Index of the currently open step in {@link steps}, or -1. */
-    open: number;
-    /** Harness call id → index of the step that owns it, for results that arrive later. */
-    pending: Record<string, number>;
-    firstMs: number | null;
-    lastMs: number | null;
-    /** Genuine user turns seen so far. */
-    turns: number;
-    /** The latest genuine user turn, tidied — the session's operative request. */
-    request?: SessionRequest;
-    /** The FIRST genuine user turn, kept so history still shows where it started. */
-    firstRequest?: SessionRequest;
-    /** Path → accumulated change record. */
-    files: Record<string, TimelineFileEntry>;
-    /** Set when an event cap stopped the fold short: the projection reports `partial`. */
-    truncated?: boolean;
-    /**
-     * Steps rolled out of {@link steps} to keep the persisted state bounded. Their
-     * counts still ride the projection's `earlier` block and totals, so folding a
-     * compacted state and folding the whole file report the same numbers.
-     */
-    dropped?: {
-        steps: number;
-        tools: number;
-        failed: number;
-        blocked: number;
-    };
-    /** Paths rolled out of {@link files} for the same reason; `total` stays exact. */
-    filesDropped?: number;
-}
-/**
- * Roll the oldest steps and file rows out of the state so a session that runs
- * for hours does not grow its cached state without bound. Their tallies survive
- * in {@link TimelineState.dropped} / {@link TimelineState.filesDropped}, which
- * the projection adds back — so this changes the state's SIZE, never its
- * reported numbers.
- */
-export declare function compactTimelineState(state: TimelineState, maxSteps?: number, maxFiles?: number): TimelineState;
-/** A fresh state for a session nothing has been folded for yet. */
-export declare function emptyTimelineState(): TimelineState;
-/**
- * Bucket one Bash command into a verb class, reusing the repo's single command
- * classifier (`classifyBashCommand`) rather than re-deriving a second taxonomy.
- * Its `category` answers most of it; the three things its taxonomy deliberately
- * does not carry — a write redirection, `agents` subcommands, and whether a
- * build tool is running tests — are added on top.
- *
- * Multi-segment commands take the most consequential class present, so
- * `cd x && bun test` is a test, not a `cd`.
- */
-export declare function classifyCommandVerb(command: string | undefined): SessionVerbClass;
-/** The verb class for one tool call: the harness's own if it classified it, else derived. */
-export declare function verbClassForEvent(event: SessionEvent): SessionVerbClass;
-/** Options the fold needs that are not on the events themselves. */
-interface FoldTimelineOptions {
-    /** Row attachments, so an image the prose never named still rides the request. */
-    attachments?: import('./types.js').SessionAttachment[];
-    /** Stop after this many events and mark the state `truncated` (the projection reads `partial`). */
-    maxEvents?: number;
-    /** Byte offset the folded events end at; stored so the next fold resumes there. */
-    offset?: number;
-}
-/**
- * Fold `events` onto `prior` (or a fresh state) and return the new state.
- *
- * Pure: no clock, no filesystem, no database. The rules, in the order they are
- * applied per event, are the plan's fold table — narration opens, thinking opens
- * only when there is nothing open or the open step is already a wall of calls,
- * tools attach, a genuine user turn is its own step, results resolve
- * failed-vs-blocked, and a harness file ledger both marks the step and feeds the
- * files projection.
- */
-export declare function foldTimeline(events: SessionEvent[], prior?: TimelineState, opts?: FoldTimelineOptions): TimelineState;
-/** The activity values that mean the agent is mid-step, so the newest step is live. */
-type TimelineActivity = string | undefined;
-/** How {@link projectTimeline} scrubs the transcript text it is about to ship. */
-interface ProjectTimelineOptions {
-    /** Redact secrets from every projected string. Default true — see below. */
-    redact?: boolean;
-    /** Known credential values to mask verbatim; defaults to {@link knownSecretValuesFromEnv}. */
-    knownSecrets?: readonly string[];
-}
-/**
- * Project the folded state onto the bounded shape that rides a session row.
- *
- * `keep` newest steps travel in full; everything older collapses into
- * `earlier`. The newest step is marked `live` while the session is working —
- * that is what the sidebar renders with the amber now-line, using the `now`
- * label the harness wrote for the call that is running.
- *
- * **This is the single place raw transcript text leaves the fold**, so it is
- * where scrubbing happens — every consumer (the session row, the git-tracked
- * fleet mirror `daemon-state.json`, and `sessions trace --steps`) is covered at
- * the source rather than each remembering to do it. Two passes, and they are
- * not the same thing:
- *
- *   - **Terminal escapes are ALWAYS stripped.** A transcript is untrusted input
- *     and these labels are printed to a terminal; `sanitizeEvents` never runs on
- *     the fold's parse path (only `tail.ts` / `stream-render.ts` call it), so
- *     this is the only place that scrub happens for a timeline.
- *   - **Secrets are redacted unless the caller opts out.** `redact` defaults to
- *     ON; only the local-only `--no-redact` path passes `redact: false`, and it
- *     buys exactly that — not raw control characters.
- */
-export declare function projectTimeline(state: TimelineState, activity: TimelineActivity, keep?: number, options?: ProjectTimelineOptions): SessionTimeline;
-/** The honest empty timeline for a harness that writes no parseable transcript. */
-export declare function unavailableTimeline(reason: string): SessionTimeline;
-/**
- * Project the files the session changed. Bounded to `keep` rows, newest first,
- * with `total` reporting the real count.
- *
- * `source` reports where the OPERATIONS came from: `harness` when at least one
- * entry was written by the harness's own ledger (Codex `FileChange` carries
- * add/update/delete per path, OpenCode `patch` and Claude `file-history-delta`
- * carry the path set), `tools` when everything was derived from Edit/Write
- * arguments because the harness records no ledger at all.
- */
-export declare function projectSessionFiles(state: TimelineState, keep?: number): SessionFiles | undefined;
-export {};