@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/commands/run-cloud.js

@@ -1,32 +1,14 @@
-/**
- * `agents run <agent> [prompt] --cloud` — the vendor-cloud placement for a run.
- *
- * One of three run placements: local (default), machine (--device,
- * --lease), cloud (--cloud). Routing goes through the cloud provider registry
- * exactly like `agents cloud run --agent <agent>`: the agent's native
- * `cloudProvider` wins, `--provider` overrides. The dispatch itself is the
- * shared core in lib/cloud/dispatch.ts — this module only validates the run
- * surface and translates run flags into a DispatchOptions.
- */
 import chalk from 'chalk';
 import { AGENTS, resolveAgentName, isAgentHardDeprecated, hardDeprecationError } from '../lib/agents.js';
 import { RUN_AUTO_KEYWORD } from '../lib/types.js';
 import { resolveProvider, nativeProviderForAgent } from '../lib/cloud/registry.js';
 import { resolveCloudPrompt, executeCloudDispatch } from '../lib/cloud/dispatch.js';
-/** Error type for run --cloud validation failures (exit 1, red message). */
 export class RunCloudError extends Error {
     constructor(message) {
         super(message);
         this.name = 'RunCloudError';
     }
 }
-/**
- * Run flags that are meaningless on a cloud placement. Each entry maps the
- * option field to the flag the user typed. Cloud tasks run in the provider's
- * workspace on the provider's accounts, so local-run knobs (account strategy,
- * secrets injection, loop guards, resume, terminal handoff, cwd) have nothing
- * to act on — passing one is an error, never a silent ignore.
- */
 const RUN_CLOUD_CONFLICTS = [
     { field: 'terminal', flag: '--terminal', set: (v) => v !== undefined && v !== false },
     { field: 'interactive', flag: '--interactive', set: (v) => v === true },
@@ -53,39 +35,27 @@ const RUN_CLOUD_CONFLICTS = [
     { field: 'remoteCwd', flag: '--remote-cwd', set: (v) => v !== undefined },
     { field: 'env', flag: '--env', set: (v) => Array.isArray(v) && v.length > 0 },
     { field: 'notify', flag: '--notify', set: (v) => v === true },
-    // effort defaults to 'auto' on run; only an explicit non-default value is a
-    // conflict (no provider consumes an effort option — it would be dropped).
     { field: 'effort', flag: '--effort', set: (v) => v !== undefined && v !== 'auto' },
-    // --name seeds the LOCAL session label; a cloud task has no local session.
     { field: 'name', flag: '--name', set: (v) => v !== undefined },
 ];
-/** Flags that refine a cloud dispatch; meaningless without the placement. */
 const CLOUD_ONLY_FLAGS = [
     { field: 'provider', flag: '--provider', set: (v) => v !== undefined },
     { field: 'repo', flag: '--repo', set: (v) => Array.isArray(v) && v.length > 0 },
     { field: 'branch', flag: '--branch', set: (v) => v !== undefined },
     { field: 'cloudEnv', flag: '--cloud-env', set: (v) => v !== undefined },
 ];
-/** Flags the user passed that cannot ride a cloud placement. */
 export function runCloudConflicts(options) {
     return RUN_CLOUD_CONFLICTS.filter((c) => c.set(options[c.field])).map((c) => c.flag);
 }
-/** Cloud-only flags passed without the --cloud placement. */
 export function cloudFlagsWithoutCloud(options) {
     return CLOUD_ONLY_FLAGS.filter((c) => c.set(options[c.field])).map((c) => c.flag);
 }
-/** Agents that route to a native cloud provider (the registry's truth). */
 export function cloudCapableAgentIds() {
     return Object.values(AGENTS)
         .filter((a) => a.cloudProvider)
         .map((a) => a.id)
         .sort();
 }
-/**
- * Resolve the cloud provider for a run: explicit --provider wins, else the
- * agent's native cloud. An agent with no native cloud fails loud with the
- * capable list — never a silent ride onto the configured default.
- */
 export function resolveRunCloudProvider(agentId, explicitProvider) {
     if (explicitProvider)
         return resolveProvider(explicitProvider);
@@ -95,7 +65,6 @@ export function resolveRunCloudProvider(agentId, explicitProvider) {
     }
     return resolveProvider(undefined, agentId);
 }
-/** Validate the agent half of `agents run <agent> --cloud` and return the registry id. */
 export function resolveRunCloudAgent(agentSpec) {
     if (agentSpec === RUN_AUTO_KEYWORD || agentSpec.startsWith(`${RUN_AUTO_KEYWORD}@`)) {
         throw new RunCloudError(`agents run auto --cloud: auto harness-pick is a local-run feature. ` +
@@ -114,11 +83,6 @@ export function resolveRunCloudAgent(agentSpec) {
     }
     return agentId;
 }
-/**
- * Handle `agents run <agent> [prompt] --cloud`. Validation lives in the
- * exported helpers above (unit-tested); this wires them to the shared
- * dispatch core and dies on any validation failure.
- */
 export async function handleRunCloud(agentSpec, prompt, options, command) {
     const json = options.json === true;
     try {
@@ -141,7 +105,6 @@ export async function handleRunCloud(agentSpec, prompt, options, command) {
         };
         if (options.cloudEnv)
             dispatchOptions.providerOptions.env = options.cloudEnv;
-        // --mode defaults to 'plan' on run; forward it only when the user set it.
         if (command.getOptionValueSource('mode') === 'cli') {
             dispatchOptions.providerOptions.mode = options.mode;
         }

package/dist/commands/run-device-picker.d.ts

@@ -1,6 +1,5 @@
 import type { AgentId } from '../lib/types.js';
 import { type Headroom } from '../lib/devices/health.js';
-/** One row of the menu, already resolved from disk. Pure data so ordering is testable. */
 export interface RunDeviceRow {
     name: string;
     platform?: string;
@@ -20,22 +19,7 @@ interface RunDeviceChoice {
     value: string;
     disabled?: boolean | string;
 }
-/**
- * Pure. Ordering: this machine first; then online rows by headroom (idle,
- * light, busy, loaded, unknown) then loadPercent ascending then name; then
- * unknown-state rows; then offline rows, disabled with the last-seen time.
- *
- * `accountLabel` renders the ✓/– account mark on rows whose `hasAccount` the
- * catalog answered; without it the mark is omitted (hasAccount stays on the
- * row for the caller either way).
- */
 export declare function buildRunDeviceChoices(rows: RunDeviceRow[], accountLabel?: string): RunDeviceChoice[];
-/**
- * Reads devices.yaml + the cached fleet stats + configured roles + (optionally)
- * whether `accountLabel` exists on each box. ZERO SSH, zero network, never
- * re-probes. Returns the rows and the age of the newest stats row (undefined
- * when no cache).
- */
 export declare function readRunDeviceRows(opts: {
     agent: AgentId;
     accountLabel?: string;
@@ -43,15 +27,6 @@ export declare function readRunDeviceRows(opts: {
     rows: RunDeviceRow[];
     snapshotAgeMs?: number;
 };
-/**
- * Interactive menu. Off a TTY: fail loud with the non-interactive forms,
- * exactly like the account picker. Prompt message: `Select a device for this
- * run (fleet state as of <age>):` where <age> is e.g. '2 min ago', or
- * `Select a device for this run (no cached fleet state):`. Returns the device
- * name, or null when the user cancels (Esc/Ctrl-C) — a cancel launches
- * nothing. Throws when the registry has no devices at all (the message names
- * `agents devices add`).
- */
 export declare function pickRunDevice(opts: {
     agent: AgentId;
     accountLabel?: string;

package/dist/commands/run-device-picker.js

@@ -1,19 +1,3 @@
-/**
- * Device picker for `agents run <agent>@` (PHNX-4083).
- *
- * The menu behind the trailing-`@` form: every registered fleet device,
- * rendered from files the daemon already keeps on disk — the SSH device
- * registry, the cached fleet stats (`.fleet-stats.json`), the fleet-synced
- * device docs (roles + descriptions), and the fleet-synced account catalog.
- *
- * This module NEVER probes: no SSH, no network, no re-fetch of stale rows.
- * `loadFleetStats` re-probes rows older than 3 minutes over SSH, which is the
- * multi-second hang a mid-run menu cannot afford; the whole point here is that
- * the picker renders the last cached fleet state, honestly aged ("fleet state
- * as of 2 min ago"), instead of re-deriving it live.
- *
- * PR 2 wires this into `agents run`; this module ships the data + menu only.
- */
 import { select } from '@inquirer/prompts';
 import { headroom } from '../lib/devices/health.js';
 import { loadDevicesSync } from '../lib/devices/registry.js';
@@ -37,7 +21,6 @@ const HEADROOM_ORDER = {
 function formatPercentCell(value, suffix) {
     return value === undefined ? '—' : `${Math.round(value)}% ${suffix}`;
 }
-/** 'HH:MM' (local) from an ISO timestamp; the raw string when it does not parse. */
 function formatHourMinute(iso) {
     const d = new Date(iso);
     if (Number.isNaN(d.getTime()))
@@ -46,15 +29,6 @@ function formatHourMinute(iso) {
     const mm = String(d.getMinutes()).padStart(2, '0');
     return `${hh}:${mm}`;
 }
-/**
- * Pure. Ordering: this machine first; then online rows by headroom (idle,
- * light, busy, loaded, unknown) then loadPercent ascending then name; then
- * unknown-state rows; then offline rows, disabled with the last-seen time.
- *
- * `accountLabel` renders the ✓/– account mark on rows whose `hasAccount` the
- * catalog answered; without it the mark is omitted (hasAccount stays on the
- * row for the caller either way).
- */
 export function buildRunDeviceChoices(rows, accountLabel) {
     const byHeadroomLoadName = (a, b) => HEADROOM_ORDER[a.headroom] - HEADROOM_ORDER[b.headroom]
         || (a.loadPercent ?? Number.POSITIVE_INFINITY) - (b.loadPercent ?? Number.POSITIVE_INFINITY)
@@ -95,18 +69,10 @@ export function buildRunDeviceChoices(rows, accountLabel) {
         };
     });
 }
-/**
- * The catalog's per-device answer for one account label, straight off the
- * fleet-synced shared state (the same rows `agents view` renders): the daemon
- * on each box publishes an auth verdict per registered account, and absence of
- * a verdict row on a publishing box means the account is not provisioned
- * there. A box that publishes no account rows at all (an older release) cannot
- * be answered for — its devices stay `undefined`, never guessed.
- */
 function resolveAccountDevices(agent, accountLabel) {
     const account = listNativeAccounts(readMeta()).find((row) => row.agent === agent && (row.name === accountLabel || row.id === accountLabel));
     if (!account)
-        return undefined; // the catalog has no such account — it cannot answer for any device
+        return undefined;
     const shared = readSharedAccountVerdicts();
     const publishing = new Set();
     for (const rows of shared.values()) {
@@ -119,12 +85,6 @@ function resolveAccountDevices(agent, accountLabel) {
     }
     return { byDevice, publishing };
 }
-/**
- * Reads devices.yaml + the cached fleet stats + configured roles + (optionally)
- * whether `accountLabel` exists on each box. ZERO SSH, zero network, never
- * re-probes. Returns the rows and the age of the newest stats row (undefined
- * when no cache).
- */
 export function readRunDeviceRows(opts) {
     const registry = loadDevicesSync();
     const statsCache = readStatsCache();
@@ -170,7 +130,6 @@ export function readRunDeviceRows(opts) {
     });
     return { rows, snapshotAgeMs };
 }
-/** Human age for the prompt's "fleet state as of …" note: 'just now', '2 min ago', '3 h ago', … */
 function formatSnapshotAge(ageMs) {
     if (ageMs < 45_000)
         return 'just now';
@@ -182,18 +141,7 @@ function formatSnapshotAge(ageMs) {
         return `${Math.round(ageMs / 3_600_000)} h ago`;
     return `${Math.round(ageMs / 86_400_000)} d ago`;
 }
-/**
- * Interactive menu. Off a TTY: fail loud with the non-interactive forms,
- * exactly like the account picker. Prompt message: `Select a device for this
- * run (fleet state as of <age>):` where <age> is e.g. '2 min ago', or
- * `Select a device for this run (no cached fleet state):`. Returns the device
- * name, or null when the user cancels (Esc/Ctrl-C) — a cancel launches
- * nothing. Throws when the registry has no devices at all (the message names
- * `agents devices add`).
- */
 export async function pickRunDevice(opts) {
-    // An empty registry is wrong on every terminal, so it is judged before the
-    // TTY gate: "register a device" is the useful answer, not "need a TTY".
     const { rows, snapshotAgeMs } = readRunDeviceRows(opts);
     if (rows.length === 0) {
         throw new Error('No devices are registered. Add one with: agents devices add <name>');

package/dist/commands/secrets-passthrough.d.ts

@@ -1,34 +1,3 @@
-/**
- * `agents secrets` — thin passthrough to the standalone `secrets` CLI
- * (PHNX-3989, DIST-1). Every bundle/keychain/vault operation now lives in
- * `@phnx-labs/secrets-cli`, not in this repo; this command re-declares no
- * subcommand or flag of its own. `agents secrets <anything>` execs the
- * installed executable with the same argv, `SECRETS_HOME` defaulted to this
- * box's existing store (`buildServeEnv`, matching the process client's own
- * default so an interactive `secrets list` and an injected `readBundle` see
- * the same store), and `SECRETS_SCOPE`/`SECRETS_CONTEXT` passed through
- * unmodified from the ambient environment — this is the operator's own
- * terminal, not an injected agent exec, so there is no separate scope to
- * compute here (that stays in `lib/exec.ts` for the run/inject path).
- *
- * A missing executable fails loud with install guidance — no fallback to the
- * retired in-repo engine (`commands/secrets.ts` and its siblings), which stays
- * in the tree, unregistered, until every consumer has moved off it (tasks.md
- * item 7).
- *
- * `secrets` is listed in {@link import('../lib/hosts/passthrough.js').OWN_HOST_COMMANDS}
- * so `--device` never routes through the generic SSH passthrough — the engine
- * has no fleet registry of its own (PHNX-4090), so a `--device <name>` here is
- * rewritten to `--host ssh://user@host` before exec, exactly like
- * `agents computer`'s equivalent rewrite. An explicit `--host` on the command
- * line is left untouched.
- */
 import type { Command } from 'commander';
-/**
- * Rewrite a `--device <name>` (or `-D`) on the forwarded argv to
- * `--host ssh://user@host`, the address grammar `secrets` speaks (PHNX-4090).
- * A `--host` the caller already typed wins — `--device` is left in place so
- * the standalone binary reports the same "both given" ambiguity it always has.
- */
 export declare function rewriteDeviceToHost(argv: string[]): Promise<string[]>;
 export declare function registerSecretsCommands(program: Command): void;

package/dist/commands/secrets-passthrough.js

@@ -5,12 +5,6 @@ import { flagValue } from '../lib/hosts/routing-flag.js';
 import { stripRoutingFlags } from '../lib/hosts/remote-cmd.js';
 import { resolveRemoteDevice } from '../lib/ssh-tunnel.js';
 import { SECRETS_CLI_INSTALL_HINT } from '../lib/secrets-cli.js';
-/**
- * Rewrite a `--device <name>` (or `-D`) on the forwarded argv to
- * `--host ssh://user@host`, the address grammar `secrets` speaks (PHNX-4090).
- * A `--host` the caller already typed wins — `--device` is left in place so
- * the standalone binary reports the same "both given" ambiguity it always has.
- */
 export async function rewriteDeviceToHost(argv) {
     if (flagValue(argv, 'host', 'H') !== undefined)
         return argv;
@@ -27,8 +21,6 @@ export function registerSecretsCommands(program) {
         .description('Named bundles of env variables — passthrough to the standalone `secrets` CLI. Run `agents secrets --help` (or `agents setup secrets`) for the full subcommand list.')
         .allowUnknownOption()
         .allowExcessArguments()
-        // Hand `-h`/`--help` through too — the real subcommand help lives in the
-        // installed `secrets` binary, not in this passthrough.
         .helpOption(false)
         .action(async () => {
         let bin;
@@ -44,8 +36,6 @@ export function registerSecretsCommands(program) {
             }
             throw err;
         }
-        // Everything after the literal `secrets` token on the real argv — the
-        // subcommand + its own flags, verbatim, never re-parsed by commander.
         const secretsIndex = process.argv.indexOf('secrets');
         const forwarded = await rewriteDeviceToHost(secretsIndex >= 0 ? process.argv.slice(secretsIndex + 1) : []);
         const { command, prefix } = invocation(bin);

package/dist/commands/send.d.ts

@@ -1,22 +1,2 @@
-/**
- * `agents send` — deliver a message over any registered channel provider.
- *
- * Envelope (flag-first, industry-shaped):
- *   agents send --to <dest> --text "…" [--channel <name>] [--attach …] [--url …]
- *
- * Destination:
- *   --to owner          expands to notify.owner.{channel,to} in agents.yaml
- *   --to <id>           channel-specific recipient (requires --channel)
- *
- * Compat: positional text still works (`agents send "hi" --channel … --to …`).
- *
- * `send --to owner` is the owner-delivery path; `agents feed post --level
- * important` records a milestone and broadcasts it through the same sink.
- * Not a second stack. Not agent control — use `agents message` /
- * `agents sessions inject` for running agents.
- *
- * Feed / activity are a different plane (record + read); feed.broadcast may
- * call this command as a forward sink.
- */
 import type { Command } from 'commander';
 export declare function registerSendCommand(program: Command): void;

package/dist/commands/send.js

@@ -25,29 +25,15 @@ function toInput(positionalText, opts) {
 async function runSend(positionalText, opts) {
     const meta = readMeta();
     let input = toInput(positionalText, opts);
-    // An owner-bound ping (`agents send --to owner`) goes through
-    // the SAME composer as an important `feed post` (PHNX-3698): short-shaped body,
-    // TEAM-N keys linkified, session crumb as a tappable console URL — instead of a
-    // raw dump. A non-owner send (explicit --channel/--to) is delivered verbatim.
     let ownerCompose;
     if (isOwnerAlias(opts.to)) {
         const flagged = opts.text?.trim() ?? '';
         const positional = (positionalText ?? '').trim();
         const raw = flagged || positional;
-        // When both forms are given and disagree, leave it to sendMessage to fail
-        // loud with the "pass the message once" error rather than composing a guess.
         const bothDiffer = flagged !== '' && positional !== '' && flagged !== positional;
         if (raw && !bothDiffer) {
-            // Resolve the context once, then let each owner destination render its own
-            // format: the envelope carries the plain default (for --json and dry-run
-            // display), while ownerCompose hands sendToOwner the mrkdwn variant for a
-            // Slack owner destination and plain for iMessage (PHNX-3698).
             ownerCompose = ownerMessageComposer(raw);
             input = { ...input, text: ownerCompose('plain'), positionalText: undefined };
-            // The console URL in the composed body only resolves once this session's
-            // trace shard is uploaded; fire that now so the tapped link isn't a 404.
-            // A --dry-run resolves + composes but MUST NOT act (its documented contract),
-            // so it never spawns the sync — it just shows what would be sent.
             fireTraceSyncInBackground({ disabled: Boolean(opts.dryRun) });
         }
     }
@@ -80,16 +66,22 @@ const SHARED_NOTES = `
     send              - DELIVER a message to a recipient (this command)
     feed post         - RECORD progress / milestones (optional broadcast may call send)
     activity          - READ the activity stream (not a send path)
-    message / inject  - CONTROL a running agent (mailbox answer or terminal keystroke)
+    message           - CONTROL a running agent through its mailbox
+    send --channel session - type text + Enter into a running agent's terminal
 
   --to owner is an address alias for notify.owner in agents.yaml, not a
-  special control path. Agent resume / PTY inject stay on message and
-  sessions inject.
+  special control path.
+
+  --channel session resolves --to (a session id or unique prefix, the
+  <shortid> of an ag-<agent>-<shortid> tmux name, or a %pane id) among the
+  live sessions on this machine; add --device <name> for a session on
+  another box. --attach, --thread and --from are refused on this channel.
+  --device runs the whole send on that box, for every channel, not just session.
 `;
 export function registerSendCommand(program) {
     const sendCmd = program
         .command('send [text]')
-        .description('Deliver a message through a channel provider (imessage, slack, desktop, mailbox, …). Prefer --text/--to flags.')
+        .description('Deliver a message through a channel provider (imessage, slack, desktop, mailbox, session, …). Prefer --text/--to flags.')
         .option('--text <text>', 'message body (preferred over positional text)')
         .option('--to <target>', 'recipient id, or "owner" for notify.owner in agents.yaml')
         .option('--channel <name>', 'channel / provider (required unless --to owner)')
@@ -108,6 +100,10 @@ export function registerSendCommand(program) {
       agents send --channel desktop --to local --text "deploy finished" --url https://example.com/pr/1
       agents send --channel mailbox --to <session-id> --text "peer note" --from orchestrator
 
+      # Type into a running agent's terminal (find ids with: agents ps)
+      agents send --channel session --to 4b2f1a9c --text "continue"
+      agents send --channel session --to 4b2f1a9c --text "continue" --device yosemite-s0
+
       # Attach a local file
       agents send --to owner --text "screenshot" --attach ./out/cover.png
 

package/dist/commands/sessions-backfill.d.ts

@@ -34,7 +34,6 @@ interface TitleBackfillOptions {
     limit?: string;
     refresh?: boolean;
     json?: boolean;
-    /** The injectable model call (`SessionTitleRunner`); not a CLI flag — tests pass it. */
     run?: SessionTitleRunner;
 }
 export interface TitleBackfillEnvelope {
@@ -51,12 +50,6 @@ export interface TitleBackfillEnvelope {
         title: string;
     }>;
 }
-/**
- * Generate session headlines NOW instead of waiting for the daemon's sweep — the
- * explicit-refresh half of PHNX-3797. Same code path the `session-title` service
- * ticks, so there is one generator: this only changes when it runs, how many it
- * does, and (with `--refresh`) whether an already-current title is regenerated.
- */
 export declare function runTitlesBackfill(options: TitleBackfillOptions): Promise<TitleBackfillEnvelope>;
 export declare function registerSessionsBackfillCommand(sessionsCmd: Command): void;
 export {};

package/dist/commands/sessions-backfill.js

@@ -3,7 +3,7 @@ import { setHelpSections } from '../lib/help.js';
 import { gatherRemoteAgentsJson } from '../lib/remote-agents-json.js';
 import { discoverSessions, parseTimeFilter } from '../lib/session/discover.js';
 import { machineId } from '../lib/session/sync/config.js';
-import { SESSION_AGENTS } from '../lib/session/types.js';
+import { SESSION_AGENTS } from '@phnx-labs/sessions-cli/reader';
 import { ensureToolIndex, readToolIndexCoverage } from '../lib/session/tool-index.js';
 import { NO_FANOUT_ENV } from '../lib/session/remote-active.js';
 import { backfillResourceUsage } from '../lib/session/db.js';
@@ -140,17 +140,8 @@ export async function runToolsBackfill(options) {
         machines,
     };
 }
-/**
- * Populate session_resource_usage for historical sessions on THIS machine.
- * Local-only by design: the resource signal is derived from each machine's own
- * transcripts, and the index is machine-local, so there is no cross-machine
- * merge to do — run it on each box (or over `agents ssh`). Ensures the session
- * index is complete first (discoverSessions), then re-derives usage gated by the
- * resource_scan_ledger so reruns skip completed transcripts.
- */
 async function runResourceBackfill(options) {
     const { agent, version } = parseAgent(options.agent);
-    // Make sure every matching transcript is indexed before we re-derive usage.
     await discoverSessions({
         agent,
         version,
@@ -182,12 +173,6 @@ async function runResourceBackfill(options) {
         ...result,
     };
 }
-/**
- * Generate session headlines NOW instead of waiting for the daemon's sweep — the
- * explicit-refresh half of PHNX-3797. Same code path the `session-title` service
- * ticks, so there is one generator: this only changes when it runs, how many it
- * does, and (with `--refresh`) whether an already-current title is regenerated.
- */
 export async function runTitlesBackfill(options) {
     const parsedLimit = options.limit ? Number.parseInt(options.limit, 10) : undefined;
     if (options.limit !== undefined && (!Number.isFinite(parsedLimit) || parsedLimit < 1)) {

package/dist/commands/sessions-backup-setup.js

@@ -1,14 +1,3 @@
-// `agents sessions backup-setup` — the OPERATOR command that provisions the
-// managed session-backup endpoint (`sessions.agents-cli.sh`): the Cloudflare
-// Worker + R2 bucket a signed-in user's `sessions export --to-r2` talks to with
-// NO `r2.backups` bucket of their own. It is the deploy producer for that
-// endpoint — first-party infrastructure, not a per-user step. The zero-knowledge
-// `--byo` backup path uses the user's own R2 bucket directly and never touches
-// this Worker, so there is nothing here for an ordinary user to run.
-//
-// Mirrors `agents traces setup`: the same `readCloudflareCreds` bundle plumbing,
-// the same idempotent `deployWorker`/`createBucket` primitives. Provisioning is
-// idempotent — re-running redeploys the current Worker template in place.
 import chalk from 'chalk';
 import { DEFAULT_CF_BUNDLE, readCloudflareCreds } from '../lib/cloudflare/creds.js';
 import { PHOENIX_ID_BASE } from '../lib/identity/client.js';

package/dist/commands/sessions-bookmark.d.ts

@@ -1,10 +1,2 @@
-/**
- * `agents sessions bookmark` — the non-TTY half of the bookmark hotkey.
- *
- * The `*` hotkey in the interactive browser is how a human bookmarks a session;
- * this is how a script, an agent, or a machine without a TTY does the same thing,
- * and it is what makes the feature testable end to end without driving a terminal
- * UI. Both write the one store in `lib/session/bookmarks.ts`.
- */
 import type { Command } from 'commander';
 export declare function registerSessionsBookmarkCommand(sessionsCmd: Command): void;

package/dist/commands/sessions-bookmark.js

@@ -1,27 +1,10 @@
-/**
- * `agents sessions bookmark` — the non-TTY half of the bookmark hotkey.
- *
- * The `*` hotkey in the interactive browser is how a human bookmarks a session;
- * this is how a script, an agent, or a machine without a TTY does the same thing,
- * and it is what makes the feature testable end to end without driving a terminal
- * UI. Both write the one store in `lib/session/bookmarks.ts`.
- */
 import chalk from 'chalk';
 import { setHelpSections } from '../lib/help.js';
 import { findSessionsById } from '../lib/session/db.js';
 import { isCompleteSessionId } from '../lib/session/discover.js';
 import { isBookmarked, listBookmarks, setBookmark } from '../lib/session/bookmarks.js';
-/**
- * Resolve one user-typed id (usually the 8-char short id the listing prints) to
- * a full session id. Ambiguity is an ERROR, not a silent first-match: bookmarking
- * the wrong session is invisible until the user wonders where their bookmark went.
- */
 function resolveBookmarkTarget(idQuery) {
     const matches = findSessionsById(idQuery);
-    // A COMPLETE id needs no index entry: the id is the key the store is built on,
-    // and requiring a transcript row would refuse exactly the newest sessions — a
-    // live one that has not been indexed yet. The browser's `*` bookmarks those
-    // from the live row, so demanding a DB hit here would make the two disagree.
     if (matches.length === 0) {
         return isCompleteSessionId(idQuery.trim())
             ? { id: idQuery.trim() }
@@ -65,13 +48,6 @@ export function registerSessionsBookmarkCommand(sessionsCmd) {
     `,
     });
     cmd.action((ids, options, self) => {
-        // `--json` has to come from the merged view, not `options`. The parent
-        // `sessions` command declares `--json` AND takes a positional `[query]`, so
-        // commander keeps parsing parent-known options past the subcommand name and
-        // binds `--json` to the PARENT — `options.json` is silently undefined here
-        // while `--remove`/`--list` (unknown to the parent) arrive fine.
-        // `optsWithGlobals` is commander's own answer for reading an option a parent
-        // owns; it is still declared on this command so `--help` documents it.
         const json = self.optsWithGlobals().json === true;
         if (options.list || ids.length === 0) {
             const bookmarked = [...listBookmarks()].sort();
@@ -96,8 +72,6 @@ export function registerSessionsBookmarkCommand(sessionsCmd) {
                 results.push({ query: idQuery, error: resolved.error });
                 continue;
             }
-            // Removing a bookmark that does not exist, or bookmarking it twice,
-            // is a no-op the store already short-circuits — report the resulting state.
             setBookmark(resolved.id, on);
             results.push({ query: idQuery, id: resolved.id, bookmark: isBookmarked(resolved.id) });
         }
@@ -112,8 +86,6 @@ export function registerSessionsBookmarkCommand(sessionsCmd) {
                     console.log(`${r.bookmark ? chalk.yellow('★ bookmarked') : chalk.gray('☆ unbookmarked')} ${r.id}`);
             }
         }
-        // A failed lookup is a failed command — a script must not read "bookmarked"
-        // from a zero exit when nothing was bookmarked.
         if (results.some((r) => r.error))
             process.exitCode = 1;
     });