@phnx-labs/agents-cli 1.22.37 → 1.22.38

package/dist/lib/browser/service.d.ts

@@ -1,5 +1,6 @@
 import { type ResolvedDomainSkill } from './domain-skills.js';
-import { type TabInfo, type ProfileStatus, type HistoricalTask } from './types.js';
+import { type Task, type TabInfo, type ProfileStatus, type HistoricalTask, type ReapResult } from './types.js';
+import { type ReapOptions } from './hygiene.js';
 import { type RefOpts, type RefNode } from './refs.js';
 import type { TargetFilter } from './types.js';
 export type UploadMode = 'auto' | 'input' | 'drop' | 'chooser';
@@ -77,11 +78,17 @@ export declare class BrowserService {
     private networkRequests;
     private pendingDownloads;
     private enabledSessions;
+    /** Profile -> when a `touchTask` last persisted tasks.json for it. */
+    private lastTouchPersist;
+    /** Coalescing window for the `touchTask` write. See {@link touchTask}. */
+    private static readonly TOUCH_PERSIST_INTERVAL_MS;
     start(profileName: string, opts?: {
         taskName?: string;
         url?: string;
         endpointName?: string;
         skipDomainSkill?: boolean;
+        /** Always open a new tab, skipping the abandoned-task reclaim. */
+        fresh?: boolean;
         /** Caller identity, forwarded from the CLI (see IPCRequest.actor/launchId). */
         actor?: string;
         launchId?: string;
@@ -95,6 +102,54 @@ export declare class BrowserService {
         profile: string;
         skill?: ResolvedDomainSkill;
     }>;
+    /**
+     * Reclaim a live page already showing `url` from an ABANDONED task, instead
+     * of opening a second copy of the same page (RUSH-2622). Returns its CDP
+     * targetId, or undefined when there is nothing safe to reclaim.
+     *
+     * "Safe" is narrow on purpose, because both of the wider readings close a tab
+     * somebody is using:
+     *
+     *   - An UNOWNED matching page is NOT taken. No task claims it, which most
+     *     often means the user opened it themselves — and adopting it would make
+     *     this task's `done` close the user's tab.
+     *   - A page owned by a LIVE task is NOT taken. Stealing it would leave that
+     *     agent's `screenshot`/`click` throwing "No tabs open for this task", its
+     *     `navigate` silently opening the duplicate this feature exists to
+     *     prevent, and any in-flight recording truncated when the new owner calls
+     *     `done`.
+     *
+     * What is left is exactly the pile-up case: a page held by a task whose owner
+     * is provably gone. Liveness uses the reaper's own predicate
+     * (`taskOwnerIsGone`), so "dead" has one definition in this codebase rather
+     * than two that can drift. A task the reaper cannot prove dead keeps its tab
+     * and is closed later by the idle rule instead.
+     *
+     * Reclaiming transfers rather than shares: two tasks holding one targetId
+     * means the first `done` closes the other's tab. `start --fresh` skips this
+     * path entirely.
+     *
+     * URLs are compared canonically (`new URL(...).href`), so a requested
+     * `https://example.com` matches the `https://example.com/` Chrome reports. A
+     * page that has since redirected elsewhere simply does not match, and the
+     * caller opens a tab as before.
+     */
+    private adoptTabShowing;
+    /**
+     * Every live task across every connected profile — the reaper's input
+     * (`hygiene.ts`). A read-only view: mutating a returned `Task` mutates the
+     * daemon's live state, so callers only read it and act through `stop`.
+     */
+    listTasks(): Array<{
+        profile: string;
+        task: Task;
+    }>;
+    /**
+     * Close tasks whose owning agent session is gone, or that have sat untouched
+     * past the idle window. The entry point the daemon's periodic tick and
+     * `agents browser gc` both call; the policy lives in `hygiene.ts`.
+     */
+    reapAbandoned(opts?: ReapOptions): Promise<ReapResult>;
     stop(taskName: string): Promise<{
         ok: boolean;
         profile?: string;
@@ -281,6 +336,25 @@ export declare class BrowserService {
     private getOrCreateWindow;
     private hasTaskNamed;
     private generateUniqueTaskName;
+    /**
+     * Mark a task as active, so the reaper's idle window measures time since the
+     * last real use rather than time since `start` (RUSH-2622).
+     *
+     * Called from `findTask` — the single funnel every task-scoped operation
+     * resolves through — rather than from each of the ~26 call sites, so a new
+     * action added later cannot forget to stamp it.
+     *
+     * The in-memory stamp is what the reaper reads: it runs inside the same
+     * daemon that owns these `Task` objects. The write to tasks.json exists only
+     * so a daemon RESTART does not inherit a stale stamp and reap a task an agent
+     * has been clicking through for the last half hour — `click`, `type`,
+     * `evaluate`, and `screenshot` never call `saveTaskState` on their own, so
+     * without this the on-disk stamp would sit at the last navigation. It is
+     * coalesced to at most one write per profile per minute so a screenshot loop
+     * does not become a write loop; the resulting on-disk stamp trails by at most
+     * a minute, well inside the 30-minute idle window.
+     */
+    private touchTask;
     private findTask;
     private getTabsForTask;
     private getProfileStatus;

package/dist/lib/browser/service.js

@@ -9,6 +9,7 @@ import { connectSSH, shellQuote } from './drivers/ssh.js';
 import { clearProfileRuntime, listProfileCacheDirs, readProfileRuntimeMeta, isProcessAlive } from './runtime-state.js';
 import { resolveDomainSkill } from './domain-skills.js';
 import { generateTaskId, generateShortId, generateTaskName, } from './types.js';
+import { reapAbandonedTasks, resolveLiveIdentities, taskOwnerIsGone, } from './hygiene.js';
 import { getRefs, resolveRefToCoords, describeRefs, healRef } from './refs.js';
 import { clickAtCoords, hoverAtCoords, scrollAtCoords, typeText, pressKey, focusNode } from './input.js';
 import { typeEditorText } from './editor.js';
@@ -17,6 +18,20 @@ import { emit } from '../events.js';
 import { resolveActor } from '../actor.js';
 import { recordBrowserSession } from '../session/db.js';
 import { sshExecAsync } from '../ssh-exec.js';
+/**
+ * Canonical form for comparing a requested URL against what CDP reports for a
+ * live target. `new URL('https://example.com').href` is `https://example.com/`,
+ * which is exactly what Chrome reports — comparing the raw strings would miss
+ * every bare-origin match. Unparseable input compares as itself.
+ */
+function canonicalTabUrl(raw) {
+    try {
+        return new URL(raw).href;
+    }
+    catch {
+        return raw;
+    }
+}
 function isPathInside(candidate, dir) {
     const rel = path.relative(dir, candidate);
     return rel === '' || (!!rel && !rel.startsWith('..') && !path.isAbsolute(rel));
@@ -252,6 +267,10 @@ export class BrowserService {
     networkRequests = new Map();
     pendingDownloads = new Map();
     enabledSessions = new Map(); // sessionId -> enabled domains
+    /** Profile -> when a `touchTask` last persisted tasks.json for it. */
+    lastTouchPersist = new Map();
+    /** Coalescing window for the `touchTask` write. See {@link touchTask}. */
+    static TOUCH_PERSIST_INTERVAL_MS = 60_000;
     async start(profileName, opts = {}) {
         const profile = await getProfile(profileName);
         if (!profile) {
@@ -331,23 +350,37 @@ export class BrowserService {
         // Browsers launch with --no-startup-window (session-cookie persistence,
         // see launchBrowser), so a bare `start` with no --url would otherwise
         // leave the user staring at a process with zero windows. Recreate the
-        // old startup-window affordance: if no page target exists, open a blank
-        // one. Deliberately NOT registered on the task — the startup window
-        // never was either, and tasks track only tabs they created.
+        // old startup-window affordance: if no page target exists, open a blank one.
+        //
+        // This tab IS registered on the task below. It used to be deliberately
+        // unregistered ("tasks track only tabs they created") — but this daemon did
+        // create it, and an unregistered tab is one `done`/`stop` can never close:
+        // `stop` closes exactly the entries in `task.tabs`. So every bare `start`
+        // left a blank globe tab behind forever, which is a large share of the
+        // pile-up in RUSH-2622. Tabs the daemon did NOT open are still left alone —
+        // the branch only fires when the profile has no page target at all.
+        let startupBlankTargetId;
         if (!opts.url && !conn.electron) {
             const { targetInfos } = (await conn.cdp.send('Target.getTargets'));
             if (!targetInfos.some((t) => t.type === 'page')) {
-                await conn.cdp.send('Target.createTarget', { url: 'about:blank' });
+                const created = (await conn.cdp.send('Target.createTarget', {
+                    url: 'about:blank',
+                }));
+                startupBlankTargetId = created.targetId;
                 this.invalidateTargetCache(conn);
             }
         }
+        const now = Date.now();
         const task = {
             id: taskId,
             name: taskName,
             profile: effectiveProfileName,
             tabs: {},
             currentTabId: undefined,
-            createdAt: Date.now(),
+            createdAt: now,
+            // A brand-new task has done exactly one thing — start — so its last
+            // action is its creation. The reaper's idle window runs from here.
+            lastActionAt: now,
             pid: conn.pid,
             // Identity is forwarded from the caller (see resolveTaskIdentity): WHO
             // (owner), WHICH run (launchId), and WHICH agent session (sessionId).
@@ -355,6 +388,11 @@ export class BrowserService {
             // actor (the RUSH-2020 bug).
             ...resolveTaskIdentity({ actor: opts.actor, launchId: opts.launchId, sessionId: opts.sessionId }, () => resolveActor().id),
         };
+        if (startupBlankTargetId) {
+            const shortId = generateShortId();
+            task.tabs[shortId] = startupBlankTargetId;
+            task.currentTabId = shortId;
+        }
         // For Electron, get the existing window as the tab
         if (conn.electron) {
             const windowId = await this.getOrCreateWindow(conn);
@@ -400,14 +438,17 @@ export class BrowserService {
                 meta: { task: taskName },
             });
         }).catch(() => { });
-        // If URL provided, create tab directly (no about:blank)
+        // If URL provided, reclaim a tab an abandoned task is holding on it, else
+        // create one directly (no about:blank).
         let tabId;
         if (opts.url && !conn.electron) {
-            const result = (await conn.cdp.send('Target.createTarget', {
-                url: opts.url,
-            }));
+            const adopted = opts.fresh ? undefined : await this.adoptTabShowing(conn, opts.url);
+            const targetId = adopted ??
+                (await conn.cdp.send('Target.createTarget', {
+                    url: opts.url,
+                })).targetId;
             const shortId = generateShortId();
-            task.tabs[shortId] = result.targetId;
+            task.tabs[shortId] = targetId;
             task.currentTabId = shortId;
             this.invalidateTargetCache(conn);
             await this.saveTaskState(effectiveProfileName, conn.tasks);
@@ -428,6 +469,110 @@ export class BrowserService {
         }
         return { task: taskId, name: taskName, tabId, profile: effectiveProfileName, skill };
     }
+    /**
+     * Reclaim a live page already showing `url` from an ABANDONED task, instead
+     * of opening a second copy of the same page (RUSH-2622). Returns its CDP
+     * targetId, or undefined when there is nothing safe to reclaim.
+     *
+     * "Safe" is narrow on purpose, because both of the wider readings close a tab
+     * somebody is using:
+     *
+     *   - An UNOWNED matching page is NOT taken. No task claims it, which most
+     *     often means the user opened it themselves — and adopting it would make
+     *     this task's `done` close the user's tab.
+     *   - A page owned by a LIVE task is NOT taken. Stealing it would leave that
+     *     agent's `screenshot`/`click` throwing "No tabs open for this task", its
+     *     `navigate` silently opening the duplicate this feature exists to
+     *     prevent, and any in-flight recording truncated when the new owner calls
+     *     `done`.
+     *
+     * What is left is exactly the pile-up case: a page held by a task whose owner
+     * is provably gone. Liveness uses the reaper's own predicate
+     * (`taskOwnerIsGone`), so "dead" has one definition in this codebase rather
+     * than two that can drift. A task the reaper cannot prove dead keeps its tab
+     * and is closed later by the idle rule instead.
+     *
+     * Reclaiming transfers rather than shares: two tasks holding one targetId
+     * means the first `done` closes the other's tab. `start --fresh` skips this
+     * path entirely.
+     *
+     * URLs are compared canonically (`new URL(...).href`), so a requested
+     * `https://example.com` matches the `https://example.com/` Chrome reports. A
+     * page that has since redirected elsewhere simply does not match, and the
+     * caller opens a tab as before.
+     */
+    async adoptTabShowing(conn, url) {
+        const { targetInfos } = (await conn.cdp.send('Target.getTargets'));
+        const wanted = canonicalTabUrl(url);
+        const matching = new Set(targetInfos
+            .filter((t) => t.type === 'page' && canonicalTabUrl(t.url) === wanted)
+            .map((t) => t.targetId));
+        if (matching.size === 0)
+            return undefined;
+        const candidates = [];
+        for (const task of conn.tasks.values()) {
+            for (const [shortId, cdpId] of Object.entries(task.tabs)) {
+                if (matching.has(cdpId))
+                    candidates.push({ task, shortId, targetId: cdpId });
+            }
+        }
+        if (candidates.length === 0)
+            return undefined;
+        const live = resolveLiveIdentities();
+        for (const { task, shortId, targetId } of candidates) {
+            // An in-flight capture means the task is in use whatever its owner looks
+            // like — same guard the reaper applies before stopping anything.
+            if (this.recordings.has(task.name))
+                continue;
+            if (!(await taskOwnerIsGone(task, live)))
+                continue;
+            // Re-check the claim after the await. Nothing serializes IPC requests —
+            // `BrowserIPCServer` registers a per-connection `socket.on('data', async …)`
+            // that Node never awaits — so two concurrent `start`s can both pass the
+            // liveness check on one candidate and both return the same targetId,
+            // putting two live tasks on one tab and re-opening the double-owner bug
+            // this reclaim is careful to avoid. Whoever deletes it first owns it.
+            if (task.tabs[shortId] !== targetId)
+                continue;
+            delete task.tabs[shortId];
+            delete task.refDescriptors?.[shortId];
+            if (task.currentTabId === shortId) {
+                const remaining = Object.keys(task.tabs);
+                task.currentTabId = remaining.length > 0 ? remaining[remaining.length - 1] : undefined;
+            }
+            try {
+                await conn.cdp.send('Target.activateTarget', { targetId });
+            }
+            catch {
+                // Bringing the tab to the front is cosmetic and not every endpoint
+                // implements activateTarget; the tab is reclaimed either way.
+            }
+            return targetId;
+        }
+        return undefined;
+    }
+    /**
+     * Every live task across every connected profile — the reaper's input
+     * (`hygiene.ts`). A read-only view: mutating a returned `Task` mutates the
+     * daemon's live state, so callers only read it and act through `stop`.
+     */
+    listTasks() {
+        const out = [];
+        for (const [key, conn] of this.connections) {
+            for (const task of conn.tasks.values()) {
+                out.push({ profile: conn.profileName ?? key, task });
+            }
+        }
+        return out;
+    }
+    /**
+     * Close tasks whose owning agent session is gone, or that have sat untouched
+     * past the idle window. The entry point the daemon's periodic tick and
+     * `agents browser gc` both call; the policy lives in `hygiene.ts`.
+     */
+    async reapAbandoned(opts = {}) {
+        return reapAbandonedTasks(this, opts);
+    }
     async stop(taskName) {
         for (const [profileName, conn] of this.connections) {
             const task = conn.tasks.get(taskName);
@@ -1877,6 +2022,41 @@ export class BrowserService {
         }
         throw new Error('Could not generate unique task name after 8 attempts');
     }
+    /**
+     * Mark a task as active, so the reaper's idle window measures time since the
+     * last real use rather than time since `start` (RUSH-2622).
+     *
+     * Called from `findTask` — the single funnel every task-scoped operation
+     * resolves through — rather than from each of the ~26 call sites, so a new
+     * action added later cannot forget to stamp it.
+     *
+     * The in-memory stamp is what the reaper reads: it runs inside the same
+     * daemon that owns these `Task` objects. The write to tasks.json exists only
+     * so a daemon RESTART does not inherit a stale stamp and reap a task an agent
+     * has been clicking through for the last half hour — `click`, `type`,
+     * `evaluate`, and `screenshot` never call `saveTaskState` on their own, so
+     * without this the on-disk stamp would sit at the last navigation. It is
+     * coalesced to at most one write per profile per minute so a screenshot loop
+     * does not become a write loop; the resulting on-disk stamp trails by at most
+     * a minute, well inside the 30-minute idle window.
+     */
+    async touchTask(conn, task) {
+        const now = Date.now();
+        task.lastActionAt = now;
+        const last = this.lastTouchPersist.get(task.profile) ?? 0;
+        if (now - last < BrowserService.TOUCH_PERSIST_INTERVAL_MS)
+            return;
+        this.lastTouchPersist.set(task.profile, now);
+        try {
+            await this.saveTaskState(task.profile, conn.tasks);
+        }
+        catch {
+            // Durability here is best-effort — the in-memory stamp above is
+            // authoritative for the running daemon — and an unwritable runtime dir
+            // must not turn a working browser action into a failure. Same guard the
+            // `recordBrowserSession` call in `start` uses for the same reason.
+        }
+    }
     async findTask(taskId, profileName) {
         if (profileName) {
             const conn = this.connections.get(profileName);
@@ -1887,11 +2067,13 @@ export class BrowserService {
             if (!task) {
                 throw new Error(`Task "${taskId}" not found on profile "${profileName}"`);
             }
+            await this.touchTask(conn, task);
             return { conn, task, profileName };
         }
         for (const [key, conn] of this.connections) {
             const task = conn.tasks.get(taskId);
             if (task) {
+                await this.touchTask(conn, task);
                 return { conn, task, profileName: conn.profileName ?? key };
             }
         }
@@ -2055,11 +2237,19 @@ export class BrowserService {
                     tabs,
                     currentTabId: tabIds.length > 0 ? tabIds[tabIds.length - 1] : undefined,
                     createdAt: task.createdAt,
+                    lastActionAt: task.lastActionAt ?? task.createdAt,
                     pid: task.pid,
                 });
             }
             else {
-                tasks.set(key, task);
+                const loaded = task;
+                // Tasks persisted before RUSH-2622 carry no lastActionAt. Normalize on
+                // read so every in-memory task has one: its own createdAt is the last
+                // moment we can prove the task did anything.
+                if (typeof loaded.lastActionAt !== 'number') {
+                    loaded.lastActionAt = loaded.createdAt;
+                }
+                tasks.set(key, loaded);
             }
         }
         // Save migrated data back to disk

package/dist/lib/browser/types.d.ts

@@ -77,6 +77,20 @@ export interface Task {
     tabs: Record<string, string>;
     currentTabId?: string;
     createdAt: number;
+    /**
+     * When this task last did anything. Stamped at creation (equal to
+     * `createdAt`) and refreshed by every task-scoped action, because every one
+     * of them resolves the task through `BrowserService.findTask`.
+     *
+     * Read by the idle half of the abandoned-task reaper (`hygiene.ts`): a task
+     * nobody has driven for `idleMs` is stopped so its tabs stop piling up in the
+     * profile window (RUSH-2622).
+     *
+     * Persisted in tasks.json. Tasks written before RUSH-2622 carry none;
+     * `loadTaskState` normalizes those to `createdAt` on read, so every task in
+     * memory has one and the reaper never has to guess.
+     */
+    lastActionAt: number;
     pid: number;
     /**
      * Resolved actor id (`resolveActor().id`) stamped at task start — WHO launched
@@ -151,7 +165,24 @@ export interface HistoricalTask {
     /** Actor id who launched the task (RUSH-2020); absent for pre-RUSH-2020 history. */
     owner?: string;
 }
-export type IPCAction = 'start' | 'record-start' | 'record-stop' | 'done' | 'stop' | 'status' | 'history' | 'navigate' | 'tab-add' | 'tab-focus' | 'tab-close' | 'tab-list' | 'evaluate' | 'screenshot' | 'pdf' | 'refs' | 'click' | 'type' | 'press' | 'hover' | 'scroll' | 'set-viewport' | 'set-device' | 'console' | 'errors' | 'requests' | 'response-body' | 'wait' | 'set-download-path' | 'wait-download' | 'upload' | 'getAppLogs' | 'version';
+/**
+ * Why the reaper stopped a task. `session-dead` — the agent session (or run)
+ * that started it is provably gone; `idle` — nothing has driven it for the
+ * idle window. See `hygiene.ts`.
+ */
+export type ReapReason = 'session-dead' | 'idle';
+/** One task the reaper stopped (or, under `dryRun`, would have stopped). */
+export interface ReapedTask {
+    task: string;
+    profile: string;
+    reason: ReapReason;
+}
+export interface ReapResult {
+    closed: ReapedTask[];
+    /** Tasks left alone this pass: still live, still inside the idle window, or recording. */
+    skipped: number;
+}
+export type IPCAction = 'start' | 'gc' | 'record-start' | 'record-stop' | 'done' | 'stop' | 'status' | 'history' | 'navigate' | 'tab-add' | 'tab-focus' | 'tab-close' | 'tab-list' | 'evaluate' | 'screenshot' | 'pdf' | 'refs' | 'click' | 'type' | 'press' | 'hover' | 'scroll' | 'set-viewport' | 'set-device' | 'console' | 'errors' | 'requests' | 'response-body' | 'wait' | 'set-download-path' | 'wait-download' | 'upload' | 'getAppLogs' | 'version';
 export interface IPCRequest {
     action: IPCAction;
     task?: string;
@@ -201,6 +232,16 @@ export interface IPCRequest {
     until?: string;
     appLevel?: string;
     skipDomainSkill?: boolean;
+    /**
+     * Browser start: always open a new tab. Without it, `start --url` reclaims a
+     * tab that an ABANDONED task is still holding on this exact URL rather than
+     * opening a duplicate (RUSH-2622). A tab held by a live task, or one nobody's
+     * task owns (the user's own), is never taken either way — set this when the
+     * caller wants its own tab regardless.
+     */
+    fresh?: boolean;
+    idleMinutes?: number;
+    dryRun?: boolean;
     actor?: string;
     launchId?: string;
     /**
@@ -236,6 +277,8 @@ export interface IPCResponse {
     tabs?: TabInfo[];
     profiles?: ProfileStatus[];
     history?: HistoricalTask[];
+    /** `gc`: what the abandoned-task reaper closed (or would close under dryRun). */
+    reaped?: ReapResult;
     result?: unknown;
     path?: string;
     bytes?: number;

package/dist/lib/git.d.ts

@@ -123,7 +123,7 @@ export declare function _resetSnapshotShaCacheForTest(): void;
  */
 export declare function getGitHubUsername(): Promise<string | null>;
 /**
- * Resolve the GitHub username synchronously for `agents share`. Order:
+ * Resolve the GitHub username synchronously for `agents artifacts share`. Order:
  *   1. `AGENTS_SHARE_GITHUB_USER` env override
  *   2. `git config --global github.user`
  * Falls back to null so callers can decide whether to require auth or proceed

package/dist/lib/git.js

@@ -437,7 +437,7 @@ function readGitConfigUser() {
     }
 }
 /**
- * Resolve the GitHub username synchronously for `agents share`. Order:
+ * Resolve the GitHub username synchronously for `agents artifacts share`. Order:
  *   1. `AGENTS_SHARE_GITHUB_USER` env override
  *   2. `git config --global github.user`
  * Falls back to null so callers can decide whether to require auth or proceed

package/dist/lib/routines.d.ts

@@ -79,7 +79,9 @@ export interface LinearJobTrigger {
     teamKey?: string;
     /** Required issue label name. */
     label?: string;
-    /** Current Linear state name that must match (e.g. `Plan`). */
+    /** Fire on a transition INTO this Linear state (e.g. `Plan`): the current state
+     *  must match AND the delivery's `updatedFrom` must record a state change, so a
+     *  later edit that leaves the issue in this state does not re-fire (RUSH-2539). */
     stateTo?: string;
     /** Previous Linear state name that must match (e.g. `Triage`). */
     stateFrom?: string;

package/dist/lib/share/analytics.js

@@ -1,4 +1,4 @@
-// Cloudflare Web Analytics injection for `agents share`.
+// Cloudflare Web Analytics injection for `agents artifacts share`.
 //
 // The beacon is cookieless and privacy-first, which matters because a lot of shared
 // content (games, kid-facing pages) should avoid GA4-style tracking. The token is

package/dist/lib/share/capture.d.ts

@@ -1,7 +1,7 @@
 /**
  * Render an HTML file to a 1200×630 PNG — the Open Graph cover for a shared plan.
  *
- * When `agents share plan.html` runs, we screenshot the plan's own hero and use it
+ * When `agents artifacts share plan.html` runs, we screenshot the plan's own hero and use it
  * as the `og:image`, so the link unfurls into a card in Slack / iMessage / Twitter /
  * Discord. No AI, no central render service: it's a headless screenshot on the
  * publisher's machine, so it works identically for us and for any user, and costs

package/dist/lib/share/capture.js

@@ -1,7 +1,7 @@
 /**
  * Render an HTML file to a 1200×630 PNG — the Open Graph cover for a shared plan.
  *
- * When `agents share plan.html` runs, we screenshot the plan's own hero and use it
+ * When `agents artifacts share plan.html` runs, we screenshot the plan's own hero and use it
  * as the `og:image`, so the link unfurls into a card in Slack / iMessage / Twitter /
  * Discord. No AI, no central render service: it's a headless screenshot on the
  * publisher's machine, so it works identically for us and for any user, and costs
@@ -112,7 +112,7 @@ export async function captureCover(htmlPath, timeoutMs = 15_000) {
         // A silently-dropped cover reads as "the CLI decided this page needs none",
         // when in fact no headless browser was found. Say so and point at the escape
         // hatch instead of leaving the publish coverless with no explanation.
-        process.stderr.write('[agents share] no headless browser found for the OG cover — install Chrome/Chromium ' +
+        process.stderr.write('[agents artifacts share] no headless browser found for the OG cover — install Chrome/Chromium ' +
             'or set AGENTS_SHARE_BROWSER=/path/to/chrome. Publishing without a preview image.\n');
         return null;
     }
@@ -159,7 +159,7 @@ export async function captureCover(htmlPath, timeoutMs = 15_000) {
     }
     // Every candidate ran but none yielded a cover — surface the last reason so a
     // missing preview card is diagnosable (timeout, crash, bad binary) rather than silent.
-    process.stderr.write(`[agents share] OG cover capture failed (${lastFailure || 'unknown error'}) — ` +
+    process.stderr.write(`[agents artifacts share] OG cover capture failed (${lastFailure || 'unknown error'}) — ` +
         'publishing without a preview image. Set AGENTS_SHARE_BROWSER to override.\n');
     return null;
 }

package/dist/lib/share/config.d.ts

@@ -22,7 +22,7 @@ export declare const DEFAULT_BUCKET_NAME = "agents-share";
 export declare const DEFAULT_SHARE_DOMAIN = "share.agents-cli.sh";
 /** The write token may be injected ephemerally into fleet/cloud agents. */
 export declare function readWriteTokenEnv(env?: NodeJS.ProcessEnv): string | null;
-/** Read the persisted endpoint config, or null if `agents share setup`/`join` never ran. */
+/** Read the persisted endpoint config, or null if `agents artifacts setup` / `agents artifacts share join` never ran. */
 export declare function readShareConfig(): ShareConfig | null;
 /** Persist the endpoint config to `agents.yaml` (syncs across the fleet). */
 export declare function writeShareConfig(cfg: ShareConfig): void;
@@ -46,7 +46,7 @@ export declare function readWriteToken(): string;
  * launch. The read is now always `agentOnly` — it resolves the token only from the
  * injected env or an already-held / no-ACL bundle, and silently returns undefined
  * otherwise (the caller runs without auto-share; the agent can still publish via
- * its own `agents share`). To get zero-friction auto-share with no prompt: unlock
+ * its own `agents artifacts share`). To get zero-friction auto-share with no prompt: unlock
  * once (`agents secrets unlock share`) or make it no-ACL (`agents secrets policy
  * share never`). */
 export declare function shareRuntimeEnv(): Record<string, string> | undefined;

package/dist/lib/share/config.js

@@ -1,4 +1,4 @@
-// Config + credential glue for `agents share`.
+// Config + credential glue for `agents artifacts share`.
 //
 // - The endpoint config (base URL, account, worker/bucket names) lives in
 //   `agents.yaml` under `share:` (Meta.share) so it syncs fleet-wide via
@@ -23,7 +23,7 @@ export function readWriteTokenEnv(env = process.env) {
     const token = env[SHARE_TOKEN_ENV_KEY]?.trim();
     return token ? token : null;
 }
-/** Read the persisted endpoint config, or null if `agents share setup`/`join` never ran. */
+/** Read the persisted endpoint config, or null if `agents artifacts setup` / `agents artifacts share join` never ran. */
 export function readShareConfig() {
     const s = readMeta().share;
     if (!s?.baseUrl || !s.accountId || !s.workerName || !s.bucketName)
@@ -56,7 +56,7 @@ export function storeWriteToken(token) {
     catch {
         bundle = {
             name: SHARE_BUNDLE,
-            description: 'agents share — write token for the R2 share endpoint',
+            description: 'agents artifacts share — write token for the R2 share endpoint',
             // A NEW share bundle defaults to the `never` tier (no biometry ACL). The R2
             // write token is low-sensitivity automation infra that is auto-read on EVERY
             // `agents run` (shareRuntimeEnv) — a biometry ACL there is what produced the
@@ -83,7 +83,7 @@ export function readWriteTokenFromBundle() {
     const token = env[SHARE_TOKEN_KEY];
     if (!token) {
         throw new Error(`No ${SHARE_TOKEN_KEY} in the '${SHARE_BUNDLE}' secrets bundle. ` +
-            `Run 'agents share setup' (to provision your own endpoint) or 'agents share join' (to use an existing one).`);
+            `Run 'agents artifacts setup' (to provision your own endpoint) or 'agents artifacts share join' (to use an existing one).`);
     }
     return token;
 }
@@ -102,7 +102,7 @@ export function readWriteToken() {
  * launch. The read is now always `agentOnly` — it resolves the token only from the
  * injected env or an already-held / no-ACL bundle, and silently returns undefined
  * otherwise (the caller runs without auto-share; the agent can still publish via
- * its own `agents share`). To get zero-friction auto-share with no prompt: unlock
+ * its own `agents artifacts share`). To get zero-friction auto-share with no prompt: unlock
  * once (`agents secrets unlock share`) or make it no-ACL (`agents secrets policy
  * share never`). */
 export function shareRuntimeEnv() {

package/dist/lib/share/delete.js

@@ -1,4 +1,4 @@
-// The delete path for `agents share delete` / `agents unshare` — an authed DELETE
+// The delete path for `agents artifacts share delete` / `agents unshare` — an authed DELETE
 // to the Worker, which already implements it (worker-template.ts). Mirrors
 // publish.ts: pure target-resolution logic is exported for tests, the network
 // calls (a status check + a delete) sit behind an injectable DI seam.
@@ -76,7 +76,7 @@ export async function deleteObject(endpoint, key, opts = {}) {
     const existedBefore = before.status !== 404;
     const r = await del(url, { authorization: `Bearer ${endpoint.token}` });
     if (!r.ok) {
-        throw new Error(`Delete failed (${r.status}) for ${url}. Check the write token, or that 'agents share setup' completed.`);
+        throw new Error(`Delete failed (${r.status}) for ${url}. Check the write token, or that 'agents artifacts setup' completed.`);
     }
     const after = await check(url);
     const verified404 = after.status === 404;
@@ -88,7 +88,7 @@ export async function deleteObject(endpoint, key, opts = {}) {
 export async function deleteShare(target, opts = {}) {
     const cfg = opts.config ?? readShareConfig();
     if (!cfg) {
-        throw new Error("Not set up yet. Run 'agents share setup' (provision your own endpoint) or 'agents share join' (use an existing one).");
+        throw new Error("Not set up yet. Run 'agents artifacts setup' (provision your own endpoint) or 'agents artifacts share join' (use an existing one).");
     }
     const token = opts.writeToken ?? readWriteToken();
     const resolved = await resolveDeleteTarget(target, { githubUser: opts.githubUser });