@phnx-labs/agents-cli 1.22.35 → 1.22.38

package/dist/lib/session/types.js

@@ -13,6 +13,21 @@ export const SESSION_AGENTS = ['claude', 'codex', 'gemini', 'antigravity', 'open
  * of {@link SESSION_AGENTS}). The single predicate every session-index writer
  * gates on, so "is this a trackable agent?" is decided in exactly one place.
  */
+/**
+ * The tmux session name the CLI mints for an agent run: `ag-<agent>-<shortid>`.
+ *
+ * ONE definition. This shape was independently re-written as a regex literal in
+ * five places (focus's selector test, sessions-resume's direct-selector test,
+ * active's name parsers, actor-sidecar, and the deeplink parser); they drifted —
+ * focus accepted a 6+ hex suffix while the others required exactly 8 — which is
+ * how the same alias could be an "identity" to one code path and a keyword query
+ * to the next.
+ */
+export const AG_TMUX_NAME_RE = /^ag-([a-z][a-z0-9-]*?)-([0-9a-f]{8})$/i;
+/** Whether `name` is an `ag-<agent>-<shortid>` tmux session name. */
+export function isAgentTmuxAlias(name) {
+    return AG_TMUX_NAME_RE.test(name);
+}
 export function isSessionTrackedAgent(agent) {
     return SESSION_AGENTS.includes(agent);
 }

package/dist/lib/session/viewing-in.d.ts

@@ -41,7 +41,7 @@ export interface ViewingIn {
  * BOTH "no client attached" and "could not locate the pane", so the pane's resolved
  * `tmuxTarget` is what separates them: without it there is no evidence of absence,
  * only absence of evidence. Claiming `'detached'` there would invent an orphaned
- * session — and a consumer acts on that claim (Factory's picker pre-ticks every
+ * session — and a consumer acts on that claim (the ext's picker pre-ticks every
  * detached row for rescue), so the wrong answer resumes a session nobody asked for.
  *
  * Shared by the `--active` row renderer and the `--json` serializer so a machine

package/dist/lib/session/viewing-in.js

@@ -40,7 +40,7 @@ const execFileAsync = promisify(execFile);
  * BOTH "no client attached" and "could not locate the pane", so the pane's resolved
  * `tmuxTarget` is what separates them: without it there is no evidence of absence,
  * only absence of evidence. Claiming `'detached'` there would invent an orphaned
- * session — and a consumer acts on that claim (Factory's picker pre-ticks every
+ * session — and a consumer acts on that claim (the ext's picker pre-ticks every
  * detached row for rescue), so the wrong answer resumes a session nobody asked for.
  *
  * Shared by the `--active` row renderer and the `--json` serializer so a machine

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

@@ -0,0 +1,101 @@
+import type { ActiveSession } from './active.js';
+import { readActiveSessionsCache } from './session-cache.js';
+export declare const SESSION_WATCH_VERSION: 1;
+export declare const SESSION_WATCH_HEARTBEAT_MS = 15000;
+export type SessionWatchScopeStatus = 'available' | 'unavailable';
+export type SessionWatchEnvelope = {
+    version: 1;
+    type: 'reset';
+    streamId: string;
+    sequence: number;
+    capturedAt: number;
+    scope: string;
+    rows: SessionWatchRow[];
+} | {
+    version: 1;
+    type: 'upsert';
+    streamId: string;
+    sequence: number;
+    capturedAt: number;
+    scope: string;
+    rowKey: string;
+    row: SessionWatchRow;
+} | {
+    version: 1;
+    type: 'remove';
+    streamId: string;
+    sequence: number;
+    capturedAt: number;
+    scope: string;
+    rowKey: string;
+} | {
+    version: 1;
+    type: 'scope';
+    streamId: string;
+    sequence: number;
+    capturedAt: number;
+    scope: string;
+    status: SessionWatchScopeStatus;
+    reason?: string;
+} | {
+    version: 1;
+    type: 'heartbeat';
+    streamId: string;
+    sequence: number;
+    scope: string;
+    capturedAt: number;
+};
+export interface SessionWatchRow extends Omit<ActiveSession, 'viewingIn'> {
+    rowKey: string;
+    sourceDevice: string;
+    resumable: boolean;
+    unwatched: boolean;
+    viewingIn: string | null;
+    recovery: {
+        command: 'agents';
+        args: string[];
+        cwd?: string;
+    } | null;
+}
+/** Stable, opaque identity for one row within one device scope. */
+export declare function sessionWatchRowKey(scope: string, row: ActiveSession): string;
+export declare function toSessionWatchRow(scope: string, row: ActiveSession): SessionWatchRow;
+/** Stream-local sequencer and convergent row diff. */
+export declare class SessionWatchState {
+    readonly streamId: string;
+    private sequence;
+    private readonly rows;
+    constructor(streamId?: string);
+    private base;
+    reset(scope: string, sourceRows: ActiveSession[]): SessionWatchEnvelope;
+    update(scope: string, sourceRows: ActiveSession[]): SessionWatchEnvelope[];
+    patch(scope: string, upserts: ActiveSession[], removes: string[]): SessionWatchEnvelope[];
+    scope(scope: string, status: SessionWatchScopeStatus, reason?: string): SessionWatchEnvelope;
+    heartbeat(scope: string, capturedAt?: number): SessionWatchEnvelope;
+}
+export interface WatchLocalOptions {
+    scope: string;
+    signal: AbortSignal;
+    emit: (event: SessionWatchEnvelope) => void;
+    refreshMs?: number;
+    heartbeatMs?: number;
+    readCache?: typeof readActiveSessionsCache;
+    journalPath?: string;
+    journalPollMs?: number;
+}
+/**
+ * Keep one local subscription alive. Startup reads one canonical reset snapshot;
+ * steady state tails the canonical writer journal and never invokes a gather.
+ */
+export declare function watchLocalSessions(options: WatchLocalOptions): Promise<void>;
+export interface WatchFleetOptions {
+    signal: AbortSignal;
+    emit: (event: SessionWatchEnvelope) => void;
+    reconnectMs?: number;
+}
+/**
+ * Subscribe to every dialable compute device with one persistent SSH process.
+ * A peer disconnect emits `scope: unavailable` but no removes; reconnecting
+ * peer resets only its own scope. There is no recurring fleet list command.
+ */
+export declare function watchFleetSessions(options: WatchFleetOptions): Promise<void>;

package/dist/lib/session/watch.js

@@ -0,0 +1,242 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { loadDevices, isControlDevice, isDialableDevice } from '../devices/registry.js';
+import { deviceIdentityArgs, sshTargetFor } from '../devices/connect.js';
+import { machineId, normalizeHost } from '../machine-id.js';
+import { SSH_OPTS, controlOpts, shellQuote } from '../ssh-exec.js';
+import { buildWindowsAgentsCommand, remoteShellFor } from '../hosts/remote-cmd.js';
+import { activeSessionsJournalPath, activeSessionJournalIdentity, readActiveSessionsCache, } from './session-cache.js';
+export const SESSION_WATCH_VERSION = 1;
+export const SESSION_WATCH_HEARTBEAT_MS = 15_000;
+/** Stable, opaque identity for one row within one device scope. */
+export function sessionWatchRowKey(scope, row) {
+    const identity = activeSessionJournalIdentity(row);
+    return createHash('sha256').update(`${scope}\0${identity}`).digest('base64url').slice(0, 22);
+}
+export function toSessionWatchRow(scope, row) {
+    const rowKey = sessionWatchRowKey(scope, row);
+    const resumable = Boolean(row.sessionId);
+    const viewingIn = row.viewingIn
+        ? [row.viewingIn.app, row.viewingIn.tab ? `tab ${row.viewingIn.tab}` : undefined].filter(Boolean).join(' ')
+        : null;
+    return {
+        ...row,
+        rowKey,
+        sourceDevice: scope,
+        resumable,
+        unwatched: !viewingIn,
+        viewingIn,
+        recovery: resumable
+            ? { command: 'agents', args: ['sessions', 'resume', row.sessionId, '--device', scope], ...(row.cwd ? { cwd: row.cwd } : {}) }
+            : null,
+    };
+}
+function sameRow(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+/** Stream-local sequencer and convergent row diff. */
+export class SessionWatchState {
+    streamId;
+    sequence = 0;
+    rows = new Map();
+    constructor(streamId = randomUUID()) { this.streamId = streamId; }
+    base(type) {
+        return { version: SESSION_WATCH_VERSION, type, streamId: this.streamId, sequence: ++this.sequence, capturedAt: Date.now() };
+    }
+    reset(scope, sourceRows) {
+        const rows = sourceRows.map((row) => toSessionWatchRow(scope, row));
+        this.rows.set(scope, new Map(rows.map((row) => [row.rowKey, row])));
+        return { ...this.base('reset'), scope, rows };
+    }
+    update(scope, sourceRows) {
+        const previous = this.rows.get(scope) ?? new Map();
+        const nextRows = sourceRows.map((row) => toSessionWatchRow(scope, row));
+        const next = new Map(nextRows.map((row) => [row.rowKey, row]));
+        const events = [];
+        for (const [rowKey, row] of next) {
+            if (!previous.has(rowKey) || !sameRow(previous.get(rowKey), row)) {
+                events.push({ ...this.base('upsert'), scope, rowKey, row });
+            }
+        }
+        for (const rowKey of previous.keys()) {
+            if (!next.has(rowKey))
+                events.push({ ...this.base('remove'), scope, rowKey });
+        }
+        this.rows.set(scope, next);
+        return events;
+    }
+    patch(scope, upserts, removes) {
+        const current = new Map(this.rows.get(scope) ?? []);
+        const events = [];
+        for (const source of upserts) {
+            const row = toSessionWatchRow(scope, source);
+            if (!current.has(row.rowKey) || !sameRow(current.get(row.rowKey), row)) {
+                current.set(row.rowKey, row);
+                events.push({ ...this.base('upsert'), scope, rowKey: row.rowKey, row });
+            }
+        }
+        for (const identity of removes) {
+            const rowKey = createHash('sha256').update(`${scope}\0${identity}`).digest('base64url').slice(0, 22);
+            if (current.delete(rowKey))
+                events.push({ ...this.base('remove'), scope, rowKey });
+        }
+        this.rows.set(scope, current);
+        return events;
+    }
+    scope(scope, status, reason) {
+        // Deliberately retain rows while unavailable. A reconnecting scope replaces
+        // them with a reset; transient fleet loss must not look like session death.
+        return { ...this.base('scope'), scope, status, ...(reason ? { reason } : {}) };
+    }
+    heartbeat(scope, capturedAt = Date.now()) {
+        return { ...this.base('heartbeat'), scope, capturedAt };
+    }
+}
+/**
+ * Keep one local subscription alive. Startup reads one canonical reset snapshot;
+ * steady state tails the canonical writer journal and never invokes a gather.
+ */
+export async function watchLocalSessions(options) {
+    const state = new SessionWatchState();
+    const readCache = options.readCache ?? readActiveSessionsCache;
+    const journal = options.journalPath ?? activeSessionsJournalPath();
+    const heartbeatMs = options.heartbeatMs ?? SESSION_WATCH_HEARTBEAT_MS;
+    let offset = 0;
+    try {
+        offset = fs.statSync(journal).size;
+    }
+    catch { /* first publication */ }
+    const initial = readCache('local');
+    options.emit(state.reset(options.scope, initial?.sessions ?? []));
+    options.emit(state.scope(options.scope, initial ? 'available' : 'unavailable', initial ? undefined : 'awaiting publisher'));
+    if (options.signal.aborted)
+        return;
+    await new Promise((resolve) => {
+        let partial = '';
+        let reading = false;
+        const readAppended = () => {
+            if (reading || options.signal.aborted)
+                return;
+            reading = true;
+            try {
+                const size = fs.statSync(journal).size;
+                if (size < offset) {
+                    offset = 0;
+                    partial = '';
+                }
+                if (size === offset)
+                    return;
+                const fd = fs.openSync(journal, 'r');
+                try {
+                    const buffer = Buffer.alloc(size - offset);
+                    fs.readSync(fd, buffer, 0, buffer.length, offset);
+                    offset = size;
+                    const lines = (partial + buffer.toString('utf8')).split('\n');
+                    partial = lines.pop() ?? '';
+                    for (const line of lines) {
+                        if (!line)
+                            continue;
+                        try {
+                            const record = JSON.parse(line);
+                            if (record.version !== 1 || record.scope !== 'local' || !Array.isArray(record.upserts) || !Array.isArray(record.removes))
+                                continue;
+                            for (const event of state.patch(options.scope, record.upserts, record.removes))
+                                options.emit(event);
+                            options.emit(state.scope(options.scope, 'available'));
+                        }
+                        catch { /* partial/corrupt journal lines are not state */ }
+                    }
+                }
+                finally {
+                    fs.closeSync(fd);
+                }
+            }
+            catch { /* journal may not exist until the first publisher write */ }
+            finally {
+                reading = false;
+            }
+        };
+        fs.mkdirSync(path.dirname(journal), { recursive: true });
+        const journalListener = () => readAppended();
+        fs.watchFile(journal, { interval: options.journalPollMs ?? 250 }, journalListener);
+        const heartbeatTimer = setInterval(() => options.emit(state.heartbeat(options.scope)), heartbeatMs);
+        const stop = () => { fs.unwatchFile(journal, journalListener); clearInterval(heartbeatTimer); resolve(); };
+        options.signal.addEventListener('abort', stop, { once: true });
+        // Close the offset/read/watch handoff: a publisher may append after the
+        // startup offset is captured but before watchFile is registered.
+        readAppended();
+    });
+}
+function remoteWatchCommand(os) {
+    const args = ['sessions', 'watch', '--json', '--local'];
+    return remoteShellFor(os) === 'powershell'
+        ? buildWindowsAgentsCommand({ args })
+        : `bash -lc ${shellQuote(`agents ${args.map(shellQuote).join(' ')}`)}`;
+}
+/**
+ * Subscribe to every dialable compute device with one persistent SSH process.
+ * A peer disconnect emits `scope: unavailable` but no removes; reconnecting
+ * peer resets only its own scope. There is no recurring fleet list command.
+ */
+export async function watchFleetSessions(options) {
+    const local = watchLocalSessions({ scope: machineId(), signal: options.signal, emit: options.emit });
+    let devices;
+    try {
+        devices = await loadDevices();
+    }
+    catch {
+        await local;
+        return;
+    }
+    const self = machineId();
+    const peers = Object.values(devices).filter((device) => isDialableDevice(device)
+        && !isControlDevice(device)
+        && normalizeHost(device.name) !== self
+        && ['windows', 'linux', 'macos'].includes(device.platform));
+    const reconnectMs = options.reconnectMs ?? 2_000;
+    const peerTasks = peers.map(async (device) => {
+        const scope = normalizeHost(device.name);
+        const state = new SessionWatchState();
+        while (!options.signal.aborted) {
+            let target;
+            try {
+                target = sshTargetFor(device);
+            }
+            catch (error) {
+                options.emit(state.scope(scope, 'unavailable', error instanceof Error ? error.message : String(error)));
+                break;
+            }
+            const child = spawn('ssh', [
+                ...SSH_OPTS, ...controlOpts(), ...deviceIdentityArgs(device), target, remoteWatchCommand(device.platform),
+            ], { stdio: ['ignore', 'pipe', 'ignore'] });
+            const stop = () => child.kill('SIGTERM');
+            options.signal.addEventListener('abort', stop, { once: true });
+            const reader = createInterface({ input: child.stdout });
+            reader.on('line', (line) => {
+                try {
+                    const event = JSON.parse(line);
+                    if (event.version === SESSION_WATCH_VERSION && typeof event.sequence === 'number')
+                        options.emit(event);
+                }
+                catch { /* incomplete/non-protocol peer output is not state */ }
+            });
+            const code = await new Promise((resolve) => {
+                child.once('error', () => resolve(null));
+                child.once('close', resolve);
+            });
+            reader.close();
+            options.signal.removeEventListener('abort', stop);
+            if (options.signal.aborted)
+                break;
+            options.emit(state.scope(scope, 'unavailable', code === null ? 'ssh failed' : `ssh exited ${code}`));
+            await new Promise((resolve) => {
+                const timer = setTimeout(resolve, reconnectMs);
+                options.signal.addEventListener('abort', () => { clearTimeout(timer); resolve(); }, { once: true });
+            });
+        }
+    });
+    await Promise.all([local, ...peerTasks]);
+}

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

@@ -8,6 +8,10 @@ export interface ShareConfig {
     domain?: string;
     /** Cloudflare Web Analytics token injected into published HTML pages. */
     analyticsToken?: string;
+    /** sha256 of the Worker script deployed at the last provision/update. Absent
+     * on any config written before this field existed — treat that as "unknown",
+     * never as "outdated" (there is nothing to compare against). */
+    templateHash?: string;
 }
 export declare const SHARE_BUNDLE = "share";
 export declare const SHARE_TOKEN_KEY = "WRITE_TOKEN";
@@ -18,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;
@@ -42,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)
@@ -35,6 +35,7 @@ export function readShareConfig() {
         bucketName: s.bucketName,
         domain: s.domain,
         analyticsToken: s.analyticsToken,
+        templateHash: s.templateHash,
     };
 }
 /** Persist the endpoint config to `agents.yaml` (syncs across the fleet). */
@@ -55,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
@@ -82,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;
 }
@@ -101,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 });

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

@@ -51,6 +51,44 @@ export declare function mergeShareLifecycleRule(existing?: R2LifecycleRule[], ru
 export declare function configureBucketLifecycle(apiToken: string, accountId: string, bucketName: string, opts?: ProvisionOptions): Promise<void>;
 /** Upload the module Worker with an R2 binding (`BUCKET`). Secrets are set via the Workers Secrets API. */
 export declare function deployWorker(apiToken: string, accountId: string, workerName: string, script: string, bucketName: string, opts?: ProvisionOptions): Promise<void>;
+/** sha256 of the rendered Worker script, so a deployed endpoint can be compared
+ * against the current `worker-template.ts` without redeploying to find out. */
+export declare function hashWorkerScript(script: string): string;
+export interface UpdateWorkerResult {
+    /** sha256 of `script` (the hash the endpoint now matches, whether or not this
+     * call actually redeployed). */
+    templateHash: string;
+    /** True when the upload was skipped because `previousHash` already matched. */
+    skipped: boolean;
+}
+/**
+ * Re-deploy the Worker script against an ALREADY-provisioned endpoint (same
+ * account/worker/bucket `deployWorker` was first called with) and idempotently
+ * no-op when the template hasn't changed.
+ *
+ * Cloudflare's script-upload endpoint (`deployWorker`, above) replaces the
+ * Worker's bindings/secrets wholesale on every call — there is no documented,
+ * reliable way to tell it "keep the existing secret" (the `keep_bindings`
+ * metadata field some third-party guides mention is absent from Cloudflare's
+ * current Multipart upload metadata reference, and the community has reported
+ * it not preventing binding loss even when present:
+ * https://developers.cloudflare.com/workers/configuration/multipart-upload-metadata/,
+ * https://community.cloudflare.com/t/upload-worker-module-endpoint-removes-existing-bindings-despite-keep-bindings/766447).
+ * So instead this immediately re-applies WRITE_TOKEN via the documented Secrets
+ * API right after the upload — the same two-call sequence first-time
+ * provisioning already uses (`deployWorker` then `setWorkerSecret`), except
+ * `writeToken` here is the caller's EXISTING token, never a freshly generated
+ * one. Cloudflare's own docs describe exactly this "secrets survive a
+ * subsequent write" contract for the sibling `wrangler versions upload
+ * --secrets-file` flow ("Secrets not included in the file are preserved from
+ * the previous version" —
+ * https://developers.cloudflare.com/workers/configuration/secrets/#upload-secrets-alongside-code);
+ * re-setting the secret to its own value after every deploy gets the same
+ * outcome without depending on an unverified upload-time flag.
+ */
+export declare function updateWorker(apiToken: string, accountId: string, workerName: string, bucketName: string, script: string, writeToken: string, previousHash: string | undefined, opts?: ProvisionOptions & {
+    force?: boolean;
+}): Promise<UpdateWorkerResult>;
 /** Add/update the WRITE_TOKEN binding using Cloudflare's Workers Secrets API. */
 export declare function setWorkerSecret(apiToken: string, accountId: string, workerName: string, writeToken: string, opts?: ProvisionOptions): Promise<void>;
 /** Enable the free `*.workers.dev` route for the script, and return the account subdomain. */

package/dist/lib/share/provision.js

@@ -1,8 +1,9 @@
-// Cloudflare provisioning for `agents share setup` — plain `fetch` against the CF
+// Cloudflare provisioning for `agents artifacts setup` — plain `fetch` against the CF
 // REST API (the repo has no CF wrapper). Creates the R2 bucket, configures its
 // lifecycle, uploads the Worker (with an R2 binding), sets the WRITE_TOKEN secret,
 // enables the free `*.workers.dev` subdomain, and — when the token owns the zone —
 // maps a custom domain.
+import { createHash } from 'node:crypto';
 const CF_API = 'https://api.cloudflare.com/client/v4';
 export const SHARE_LIFECYCLE_RULE_ID = 'agents-share-expire-objects';
 export const SHARE_LIFECYCLE_RETENTION_DAYS = 366;
@@ -95,6 +96,55 @@ export async function deployWorker(apiToken, accountId, workerName, script, buck
         form,
     });
 }
+/** sha256 of the rendered Worker script, so a deployed endpoint can be compared
+ * against the current `worker-template.ts` without redeploying to find out. */
+export function hashWorkerScript(script) {
+    return createHash('sha256').update(script, 'utf8').digest('hex');
+}
+/**
+ * Re-deploy the Worker script against an ALREADY-provisioned endpoint (same
+ * account/worker/bucket `deployWorker` was first called with) and idempotently
+ * no-op when the template hasn't changed.
+ *
+ * Cloudflare's script-upload endpoint (`deployWorker`, above) replaces the
+ * Worker's bindings/secrets wholesale on every call — there is no documented,
+ * reliable way to tell it "keep the existing secret" (the `keep_bindings`
+ * metadata field some third-party guides mention is absent from Cloudflare's
+ * current Multipart upload metadata reference, and the community has reported
+ * it not preventing binding loss even when present:
+ * https://developers.cloudflare.com/workers/configuration/multipart-upload-metadata/,
+ * https://community.cloudflare.com/t/upload-worker-module-endpoint-removes-existing-bindings-despite-keep-bindings/766447).
+ * So instead this immediately re-applies WRITE_TOKEN via the documented Secrets
+ * API right after the upload — the same two-call sequence first-time
+ * provisioning already uses (`deployWorker` then `setWorkerSecret`), except
+ * `writeToken` here is the caller's EXISTING token, never a freshly generated
+ * one. Cloudflare's own docs describe exactly this "secrets survive a
+ * subsequent write" contract for the sibling `wrangler versions upload
+ * --secrets-file` flow ("Secrets not included in the file are preserved from
+ * the previous version" —
+ * https://developers.cloudflare.com/workers/configuration/secrets/#upload-secrets-alongside-code);
+ * re-setting the secret to its own value after every deploy gets the same
+ * outcome without depending on an unverified upload-time flag.
+ */
+export async function updateWorker(apiToken, accountId, workerName, bucketName, script, writeToken, previousHash, opts = {}) {
+    const templateHash = hashWorkerScript(script);
+    if (!opts.force && previousHash === templateHash) {
+        return { templateHash, skipped: true };
+    }
+    await deployWorker(apiToken, accountId, workerName, script, bucketName, opts);
+    // Script upload clears bindings/secrets (see JSDoc above). If re-applying
+    // WRITE_TOKEN fails here, the live Worker has no write token — every
+    // `agents artifacts share` publish/delete 401s until a re-run of `agents artifacts share update`
+    // completes both steps. Surface that explicitly instead of the raw CF error.
+    try {
+        await setWorkerSecret(apiToken, accountId, workerName, writeToken, opts);
+    }
+    catch (e) {
+        const detail = e instanceof Error ? e.message : String(e);
+        throw new Error(`Worker deployed but the write token failed to re-apply — re-run \`agents artifacts share update\` to fix this before publishing/deleting anything. (${detail})`);
+    }
+    return { templateHash, skipped: false };
+}
 /** Add/update the WRITE_TOKEN binding using Cloudflare's Workers Secrets API. */
 export async function setWorkerSecret(apiToken, accountId, workerName, writeToken, opts = {}) {
     const request = opts.request ?? defaultCloudflareRequester;