@phnx-labs/agents-cli 1.22.75 → 1.22.77

package/dist/lib/summarizer/summarize.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The one model call behind the session summarizer (PHNX-3939).
+ *
+ * A pure boundary: given the session's first user turn (the goal source) and its
+ * live progress (todos / plan / phase off the state engine), it asks a local
+ * Anthropic-wire endpoint (Ollama / vLLM / LiteLLM — the same configurable base
+ * URL `computer/model.ts` speaks) for a strict JSON `{goal, checkpoints, checklist}`
+ * and validates the shape. On ANY failure — network, non-2xx, non-JSON, wrong
+ * shape — it returns `undefined`, and the caller records `summaryState: 'skipped'`.
+ *
+ * NEVER called on the request path: only the background SessionSummarizerService
+ * invokes it, debounced and reader-gated.
+ */
+import type { TodoProgress } from '../session/types.js';
+/** Live progress fed to the model alongside the goal-bearing prompt. */
+export interface SummarizeProgress {
+    /** Latest checklist write (TodoWrite / update_plan), when the session has one. */
+    todos?: TodoProgress;
+    /** Plan markdown from the last ExitPlanMode, when present. */
+    plan?: string;
+    /** Coarse lifecycle phase (running / waiting / idle / …), when known. */
+    phase?: string;
+}
+/** The validated model output. `at` timestamps are stamped by the caller. */
+export interface SummarizeResult {
+    goal: string;
+    /** Progress checkpoints, newest last (short lines). */
+    checkpoints: string[];
+    /** Detailed checklist. */
+    checklist: {
+        text: string;
+        done: boolean;
+    }[];
+}
+export interface SummarizeOptions {
+    baseUrl: string;
+    model: string;
+    maxTokens?: number;
+    /**
+     * API key for the endpoint. Deliberately NOT resolved from `ANTHROPIC_API_KEY`:
+     * the summarizer targets an operator-configured local/remote endpoint
+     * (Ollama/vLLM/LiteLLM) that typically ignores the key, so forwarding the real
+     * Anthropic credential there would leak it. Only an explicit
+     * `AGENTS_SUMMARIZER_API_KEY` (or this option) is ever sent; otherwise the
+     * header is empty.
+     */
+    apiKey?: string;
+    /** Injectable for tests; defaults to the global fetch. */
+    fetchImpl?: typeof fetch;
+    /** Abort the request when the daemon tick's deadline elapses. */
+    signal?: AbortSignal;
+}
+/** Compose the user message from the goal-bearing prompt and the live progress. */
+export declare function buildSummarizeUserMessage(prompt: string, progress: SummarizeProgress): string;
+/**
+ * Coerce an untrusted parsed object into a {@link SummarizeResult}, or undefined
+ * when the shape is wrong. Extra/missing optional arrays degrade to `[]` rather
+ * than failing, but a non-string goal is a hard reject — a summary with no goal
+ * is not a summary.
+ */
+export declare function validateSummarizeResult(parsed: unknown): SummarizeResult | undefined;
+/** Strip ``` fences and pull the first {...} block so a chatty model still parses. */
+export declare function extractJsonObject(text: string): string | undefined;
+/**
+ * Run one summarization. Returns the validated result, or `undefined` on any
+ * failure (the caller then marks the session `summaryState: 'skipped'`).
+ */
+export declare function summarize(prompt: string, progress: SummarizeProgress, opts: SummarizeOptions): Promise<SummarizeResult | undefined>;

package/dist/lib/summarizer/summarize.js

@@ -0,0 +1,120 @@
+/**
+ * The one model call behind the session summarizer (PHNX-3939).
+ *
+ * A pure boundary: given the session's first user turn (the goal source) and its
+ * live progress (todos / plan / phase off the state engine), it asks a local
+ * Anthropic-wire endpoint (Ollama / vLLM / LiteLLM — the same configurable base
+ * URL `computer/model.ts` speaks) for a strict JSON `{goal, checkpoints, checklist}`
+ * and validates the shape. On ANY failure — network, non-2xx, non-JSON, wrong
+ * shape — it returns `undefined`, and the caller records `summaryState: 'skipped'`.
+ *
+ * NEVER called on the request path: only the background SessionSummarizerService
+ * invokes it, debounced and reader-gated.
+ */
+import { ANTHROPIC_VERSION } from '../computer/model.js';
+const SYSTEM_PROMPT = [
+    'You summarize a coding-agent session for an operator dashboard.',
+    'Reply with ONLY a single JSON object, no prose and no code fences, of exactly this shape:',
+    '{"goal": string, "checkpoints": string[], "checklist": [{"text": string, "done": boolean}]}',
+    '- goal: 1-2 lines capturing what the user actually asked for, in plain language.',
+    '- checkpoints: short lines of concrete progress so far, newest last; [] if none yet.',
+    '- checklist: the detailed steps to finish the goal, each with a done flag; [] if unknown.',
+    'Do not invent progress that is not evidenced by the provided context.',
+].join('\n');
+/** Compose the user message from the goal-bearing prompt and the live progress. */
+export function buildSummarizeUserMessage(prompt, progress) {
+    const parts = [`USER REQUEST:\n${prompt.trim()}`];
+    if (progress.phase)
+        parts.push(`PHASE: ${progress.phase}`);
+    if (progress.todos && progress.todos.items.length > 0) {
+        const lines = progress.todos.items.map((t) => `- [${t.status === 'completed' ? 'x' : ' '}] ${t.content}`);
+        parts.push(`CURRENT CHECKLIST (${progress.todos.done}/${progress.todos.total} done):\n${lines.join('\n')}`);
+    }
+    if (progress.plan)
+        parts.push(`PLAN:\n${progress.plan.trim().slice(0, 4000)}`);
+    return parts.join('\n\n');
+}
+/**
+ * Coerce an untrusted parsed object into a {@link SummarizeResult}, or undefined
+ * when the shape is wrong. Extra/missing optional arrays degrade to `[]` rather
+ * than failing, but a non-string goal is a hard reject — a summary with no goal
+ * is not a summary.
+ */
+export function validateSummarizeResult(parsed) {
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        return undefined;
+    const obj = parsed;
+    if (typeof obj.goal !== 'string' || obj.goal.trim().length === 0)
+        return undefined;
+    const checkpoints = Array.isArray(obj.checkpoints)
+        ? obj.checkpoints.filter((c) => typeof c === 'string' && c.trim().length > 0).map((c) => c.trim())
+        : [];
+    const checklist = Array.isArray(obj.checklist)
+        ? obj.checklist
+            .filter((c) => Boolean(c) && typeof c === 'object' && !Array.isArray(c))
+            .map((c) => ({ text: typeof c.text === 'string' ? c.text.trim() : '', done: Boolean(c.done) }))
+            .filter((c) => c.text.length > 0)
+        : [];
+    return { goal: obj.goal.trim(), checkpoints, checklist };
+}
+/** Extract the assistant text from an Anthropic Messages response body. */
+function textFromBody(body) {
+    const content = body.content;
+    if (!Array.isArray(content))
+        return '';
+    return content
+        .filter((b) => Boolean(b) && typeof b === 'object')
+        .filter((b) => b.type === 'text' && typeof b.text === 'string')
+        .map((b) => b.text)
+        .join('');
+}
+/** Strip ``` fences and pull the first {...} block so a chatty model still parses. */
+export function extractJsonObject(text) {
+    const unfenced = text.replace(/```(?:json)?/gi, '').trim();
+    const start = unfenced.indexOf('{');
+    const end = unfenced.lastIndexOf('}');
+    if (start === -1 || end === -1 || end < start)
+        return undefined;
+    return unfenced.slice(start, end + 1);
+}
+/**
+ * Run one summarization. Returns the validated result, or `undefined` on any
+ * failure (the caller then marks the session `summaryState: 'skipped'`).
+ */
+export async function summarize(prompt, progress, opts) {
+    if (!prompt.trim())
+        return undefined;
+    const baseUrl = opts.baseUrl.replace(/\/+$/, '');
+    const doFetch = opts.fetchImpl ?? fetch;
+    // Only an explicit summarizer key is ever forwarded — never the ambient
+    // ANTHROPIC_API_KEY, which would leak to the operator's local endpoint.
+    const apiKey = opts.apiKey ?? process.env.AGENTS_SUMMARIZER_API_KEY ?? '';
+    try {
+        const res = await doFetch(`${baseUrl}/v1/messages`, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                'x-api-key': apiKey,
+                'anthropic-version': ANTHROPIC_VERSION,
+            },
+            body: JSON.stringify({
+                model: opts.model,
+                max_tokens: opts.maxTokens ?? 512,
+                system: SYSTEM_PROMPT,
+                messages: [{ role: 'user', content: buildSummarizeUserMessage(prompt, progress) }],
+            }),
+            ...(opts.signal ? { signal: opts.signal } : {}),
+        });
+        if (!res.ok)
+            return undefined;
+        const body = await res.json();
+        const text = textFromBody(body);
+        const json = extractJsonObject(text);
+        if (!json)
+            return undefined;
+        return validateSummarizeResult(JSON.parse(json));
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/lib/teams/agents.d.ts

@@ -569,9 +569,10 @@ export declare class AgentManager {
     private resolveScheduledPlacement;
     /**
      * Place an UNPINNED, non-cloud teammate onto the team pool via the cascade
-     * (least-loaded), if the team declares one. A no-op for a pinned teammate
-     * (hostName already set from `--device`), a cloud teammate, or a poolless team —
-     * leaving hostName null so the local spawn runs unchanged. Shared by spawn()
+     * (least-loaded). A poolless team consumes the active worker allowlist and
+     * fails loud when none exists; it never silently lands on the orchestrator.
+     * A no-op only for a pinned teammate (hostName already set from `--device`) or
+     * a cloud teammate. Shared by spawn()
      * (immediate add-launch) and startReady() (staged launch) so an unpinned pool
      * teammate schedules identically no matter how it was fired.
      */

package/dist/lib/teams/agents.js

@@ -38,6 +38,7 @@ import { atomicWriteJsonSync } from '../fs-atomic.js';
 import { resolvePlacement, classifyExclusions, isTransientPlacementBlock, NoViableDeviceError, } from './scheduler.js';
 import { probePoolSignals } from './placement-probe.js';
 import { readMaxConcurrentCaps } from '../device-config.js';
+import { filterAutoPool, listWorkerDevices } from '../devices/pool.js';
 import { redactSecrets, sanitizeForTerminal } from '../redact.js';
 import chalk from 'chalk';
 let lastMemoryWarnAt = 0;
@@ -2328,9 +2329,10 @@ export class AgentManager {
     }
     /**
      * Place an UNPINNED, non-cloud teammate onto the team pool via the cascade
-     * (least-loaded), if the team declares one. A no-op for a pinned teammate
-     * (hostName already set from `--device`), a cloud teammate, or a poolless team —
-     * leaving hostName null so the local spawn runs unchanged. Shared by spawn()
+     * (least-loaded). A poolless team consumes the active worker allowlist and
+     * fails loud when none exists; it never silently lands on the orchestrator.
+     * A no-op only for a pinned teammate (hostName already set from `--device`) or
+     * a cloud teammate. Shared by spawn()
      * (immediate add-launch) and startReady() (staged launch) so an unpinned pool
      * teammate schedules identically no matter how it was fired.
      */
@@ -2341,7 +2343,12 @@ export class AgentManager {
         if (!teamMeta)
             return;
         const roster = await this.listByTask(taskName);
-        const pool = teamMeta.devices ?? [];
+        // A poolless team is still an automatic placement request: use the same
+        // explicit worker allowlist as `--device auto`. Never silently run it on a
+        // personal/desktop orchestrator merely because `devices` was omitted.
+        const pool = teamMeta.devices?.length
+            ? teamMeta.devices
+            : filterAutoPool(listWorkerDevices());
         const maxConcurrent = pool.length > 1 ? readMaxConcurrentCaps(pool) : undefined;
         // On the start path (opts.probe), gather live signals so the pick is health-,
         // harness-, and load-aware (RUSH-2002); the add path stays the cap-only
@@ -2353,6 +2360,7 @@ export class AgentManager {
         const placeOpts = {
             maxConcurrent,
             signals,
+            defaultDevices: pool,
             agentLabel: this.placementAgentLabel(agent),
         };
         if (signals) {

package/dist/lib/teams/scheduler.d.ts

@@ -45,6 +45,8 @@ export interface PlacementTeam {
  * is never second-guessed.
  */
 export interface PlacementOptions {
+    /** Worker pool used when the team does not declare an explicit device pool. */
+    defaultDevices?: string[];
     maxConcurrent?: Record<string, number>;
     /**
      * Live per-device signals (RUSH-2002). When present, the many-device pick
@@ -144,8 +146,8 @@ export declare function classifyExclusions(devices: string[], roster: RosterEntr
  */
 export declare function pickBestDevice(devices: string[], roster: RosterEntry[], opts?: PlacementOptions): string;
 /**
- * Resolve where a teammate runs. Returns `{ device: null }` for a local run
- * (no pin, no pool, or the chosen device is the local machine) and
+ * Resolve where a teammate runs. Returns `{ device: null }` only when the
+ * explicitly/default-selected device is the local machine, and
  * `{ device: <name> }` for a remote placement. See the cascade in the module
  * header. Throws {@link NoViableDeviceError} when a required pool has no viable
  * host — the caller surfaces it at `teams start` rather than falling back local.

package/dist/lib/teams/scheduler.js

@@ -9,7 +9,7 @@
  *   1. teammate has an explicit `--device` pin      → that device
  *   2. else the team pool has exactly one device     → that device (whole team)
  *   3. else the team pool has many devices           → best-viable pick
- *   4. else (no pin, no pool)                         → null == run local
+ *   4. else (no pin, no pool)                         → active worker pool
  *
  * Step 3 is cap-, health-, and harness-aware (RUSH-2002). When the caller
  * supplies live {@link DevicePlacementSignal}s (probed reachability, headroom,
@@ -294,8 +294,8 @@ export function pickBestDevice(devices, roster, opts) {
     })[0];
 }
 /**
- * Resolve where a teammate runs. Returns `{ device: null }` for a local run
- * (no pin, no pool, or the chosen device is the local machine) and
+ * Resolve where a teammate runs. Returns `{ device: null }` only when the
+ * explicitly/default-selected device is the local machine, and
  * `{ device: <name> }` for a remote placement. See the cascade in the module
  * header. Throws {@link NoViableDeviceError} when a required pool has no viable
  * host — the caller surfaces it at `teams start` rather than falling back local.
@@ -306,10 +306,10 @@ export function resolvePlacement(team, explicitDevice, roster, opts) {
     if (explicitDevice) {
         return { device: isLocalDevice(explicitDevice) ? null : explicitDevice };
     }
-    const pool = team.devices ?? [];
-    // 4. No pool → local, exactly like today.
+    const pool = team.devices?.length ? team.devices : (opts?.defaultDevices ?? []);
+    // An omitted pool means automatic worker placement, never implicit local.
     if (pool.length === 0)
-        return { device: null };
+        throw new NoViableDeviceError([], opts?.agentLabel);
     // 2. Pool of one → the whole team runs there. Respect the choice for
     //    load/cap/reachability, but still fail loud when the agent is provably
     //    NOT installed there — running it would be futile.

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

@@ -25,6 +25,8 @@ export declare const AGENTS_TMUX_HISTORY_LIMIT = 20000;
  * these defaults, silently. Same shape as AGENT_HOOK_SCHEMA below.
  */
 export declare const AGENTS_TMUX_CONFIG_SCHEMA = 1;
+/** Source one user config without tmux's quiet flag, preserving path bytes. */
+export declare function userConfigSourceLine(value: string): string;
 /** Provenance written alongside each live tmux session. */
 export interface SessionMeta {
     name: string;

package/dist/lib/tmux/session.js

@@ -55,6 +55,10 @@ let startupConfigSequence = 0;
 function tmuxConfigArgument(value) {
     return `"${value.replace(/([\\"$])/g, '\\$1')}"`;
 }
+/** Source one user config without tmux's quiet flag, preserving path bytes. */
+export function userConfigSourceLine(value) {
+    return `source-file ${tmuxConfigArgument(value)}`;
+}
 /**
  * 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
@@ -90,7 +94,9 @@ function writeStartupConfig(env) {
         '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)}`);
+        // Do not suppress parse/read failures: a broken user config must fail the
+        // launch visibly instead of producing a silently half-configured server.
+        lines.push(userConfigSourceLine(userConfig));
     }
     fs.writeFileSync(startupConfig, `${lines.join('\n')}\n`, { mode: 0o600 });
     return startupConfig;

package/dist/lib/types.d.ts

@@ -1204,6 +1204,26 @@ export interface BrowserProfileConfig {
     }>;
     /** Preset name to use when `--endpoint` is not passed to `start`. */
     defaultEndpoint?: string;
+    /**
+     * How `agents browser` obtains a live browser for this profile (PHNX-3967):
+     *   - `launch` (default when absent): agents-cli spawns the browser itself
+     *     under a managed `--user-data-dir` when nothing is serving CDP on the port.
+     *   - `attach-only`: agents-cli NEVER spawns a rival window. It attaches to a
+     *     browser the user (or a one-time command) already started with remote
+     *     debugging, and fails loud with a relaunch hint when none is there. This
+     *     is how "enforce one window" is expressed — Arc is inherently attach-only,
+     *     and a canonical signed-in Comet uses it so agents can't spawn a second,
+     *     logged-out instance. Pairs with a durable {@link userDataDir}.
+     */
+    launchPolicy?: 'attach-only' | 'launch';
+    /**
+     * Absolute durable `--user-data-dir` for this profile's browser (PHNX-3967).
+     * When absent, an attach-only profile resolves a default durable dir outside
+     * `~/.agents/.cache` (`getBrowserDurableDir()`), so a one-time sign-in survives
+     * quit+relaunch and `profiles remove`'s cache sweep. Also the value the
+     * ownership guard compares a running instance against to reject a port-squatter.
+     */
+    userDataDir?: string;
     chrome?: {
         headless?: boolean;
         args?: string[];

package/dist/lib/verbs.d.ts

@@ -0,0 +1,23 @@
+import type { Command } from 'commander';
+/**
+ * The ONE place that defines the CLI's standard short-form verb aliases.
+ *
+ * These are the canonical short forms an agent or user reaches for on a
+ * command group's CRUD verbs — `ls` for `list`, `rm` for `remove`, and so on.
+ * They are NOT cross-verb synonyms (`info`/`install`/`create`); those are
+ * per-command back-compat aliases owned by the individual commands.
+ *
+ * Apply them with {@link withAliases} so every group stays in lockstep instead
+ * of each command hand-rolling its own `.alias('rm')`.
+ */
+export declare const CANONICAL_ALIASES: {
+    readonly list: readonly ["ls"];
+    readonly view: readonly ["show"];
+    readonly add: readonly [];
+    readonly remove: readonly ["rm"];
+    readonly rename: readonly ["mv"];
+    readonly edit: readonly [];
+};
+export type CanonicalVerb = keyof typeof CANONICAL_ALIASES;
+/** Apply the standard aliases for `verb` to an already-created subcommand, returning it. */
+export declare function withAliases(cmd: Command, verb: CanonicalVerb): Command;

package/dist/lib/verbs.js

@@ -0,0 +1,24 @@
+/**
+ * The ONE place that defines the CLI's standard short-form verb aliases.
+ *
+ * These are the canonical short forms an agent or user reaches for on a
+ * command group's CRUD verbs — `ls` for `list`, `rm` for `remove`, and so on.
+ * They are NOT cross-verb synonyms (`info`/`install`/`create`); those are
+ * per-command back-compat aliases owned by the individual commands.
+ *
+ * Apply them with {@link withAliases} so every group stays in lockstep instead
+ * of each command hand-rolling its own `.alias('rm')`.
+ */
+export const CANONICAL_ALIASES = {
+    list: ['ls'],
+    view: ['show'],
+    add: [],
+    remove: ['rm'],
+    rename: ['mv'],
+    edit: [],
+};
+/** Apply the standard aliases for `verb` to an already-created subcommand, returning it. */
+export function withAliases(cmd, verb) {
+    const aliases = CANONICAL_ALIASES[verb];
+    return aliases.length ? cmd.aliases([...aliases]) : cmd;
+}

package/dist/lib/view-types.d.ts

@@ -23,12 +23,16 @@ export interface ViewJsonVersion {
     launchable: boolean;
     /** Live cached authentication verdict for this installed version. */
     authVerdict: AuthVerdict | null;
+    /** Epoch milliseconds when authVerdict was last checked, or null if absent. */
+    authCheckedAt: number | null;
     email: string | null;
     accountId?: string | null;
     organizationType?: string | null;
     organizationName?: string | null;
     plan: string | null;
     usageStatus: 'available' | 'rate_limited' | 'out_of_credits' | null;
+    /** ISO timestamp of the usage snapshot behind usageStatus, or null if absent. */
+    usageCapturedAt: string | null;
     overageCredits?: {
         amount: number;
         currency: string;

package/dist/lib/watchdog/rotate.d.ts

@@ -166,7 +166,7 @@ export declare function isWatchdogRotateEnabled(): boolean;
  * Persist `watchdog.rotate: on|off`. Called by the `agents watchdog rotate
  * on|off` subcommand (commands/watchdog.ts) — the rotate-only switch the
  * Factory migration uses so a user who opted out of autoRotate keeps nudging
- * (rather than `agents watchdog off`, which disables the whole watchdog here).
+ * (rather than `agents watchdog disable`, which disables the whole watchdog here).
  */
 export declare function setWatchdogRotateEnabled(on: boolean): void;
 export interface RotateGateResult {

package/dist/lib/watchdog/rotate.js

@@ -291,7 +291,7 @@ export function isWatchdogRotateEnabled() {
  * Persist `watchdog.rotate: on|off`. Called by the `agents watchdog rotate
  * on|off` subcommand (commands/watchdog.ts) — the rotate-only switch the
  * Factory migration uses so a user who opted out of autoRotate keeps nudging
- * (rather than `agents watchdog off`, which disables the whole watchdog here).
+ * (rather than `agents watchdog disable`, which disables the whole watchdog here).
  */
 export function setWatchdogRotateEnabled(on) {
     const meta = readMeta();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.22.75",
+  "version": "1.22.77",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",