@phnx-labs/agents-cli 1.20.65 → 1.20.67

package/dist/lib/share/config.js

@@ -0,0 +1,100 @@
+// Config + credential glue for `agents share`.
+//
+// - The endpoint config (base URL, account, worker/bucket names) lives in
+//   `agents.yaml` under `share:` (Meta.share) so it syncs fleet-wide via
+//   `agents repo push/pull`.
+// - The raw write token lives in the `share` secrets bundle (keychain-backed,
+//   fleet-injectable) — never on disk in plaintext.
+// - The Cloudflare API token (for provisioning) is read from the user's existing
+//   `cloudflare.com` bundle.
+import { randomBytes } from 'node:crypto';
+import { readMeta, updateMeta } from '../state.js';
+import { bundleItemStore, bundlePolicy, isHeadlessSecretsContext, keychainRef, readAndResolveBundleEnv, readBundle, writeBundle, } from '../secrets/bundles.js';
+import { secretsKeychainItem } from '../secrets/index.js';
+export const SHARE_BUNDLE = 'share';
+export const SHARE_TOKEN_KEY = 'SHARE_WRITE_TOKEN';
+export const DEFAULT_CF_BUNDLE = 'cloudflare.com';
+export const DEFAULT_WORKER_NAME = 'agents-share';
+export const DEFAULT_BUCKET_NAME = 'agents-share';
+/** Read the persisted endpoint config, or null if `agents share setup`/`join` never ran. */
+export function readShareConfig() {
+    const s = readMeta().share;
+    if (!s?.baseUrl || !s.accountId || !s.workerName || !s.bucketName)
+        return null;
+    return {
+        baseUrl: s.baseUrl.replace(/\/+$/, ''),
+        accountId: s.accountId,
+        workerName: s.workerName,
+        bucketName: s.bucketName,
+        domain: s.domain,
+    };
+}
+/** Persist the endpoint config to `agents.yaml` (syncs across the fleet). */
+export function writeShareConfig(cfg) {
+    updateMeta((meta) => ({ ...meta, share: { ...meta.share, ...cfg } }));
+}
+/** A fresh 32-byte hex write token. */
+export function generateWriteToken() {
+    return randomBytes(32).toString('hex');
+}
+/** Persist the raw write token into the `share` secrets bundle (keychain-backed,
+ * fleet-injectable). Mirrors the add-key sequence in `commands/secrets.ts`. */
+export function storeWriteToken(token) {
+    let bundle;
+    try {
+        bundle = readBundle(SHARE_BUNDLE);
+    }
+    catch {
+        bundle = {
+            name: SHARE_BUNDLE,
+            description: 'agents share — write token for the R2 share endpoint',
+            vars: {},
+        };
+    }
+    const store = bundleItemStore(bundle.backend, { noAcl: bundlePolicy(bundle) === 'never' });
+    store.set(secretsKeychainItem(bundle.name, SHARE_TOKEN_KEY), token);
+    bundle.vars[SHARE_TOKEN_KEY] = keychainRef(SHARE_TOKEN_KEY);
+    writeBundle(bundle);
+}
+/** Read the raw write token from the `share` secrets bundle. Throws with an
+ * actionable message if absent (run setup/join first). */
+export function readWriteToken() {
+    const { env } = readAndResolveBundleEnv(SHARE_BUNDLE, {
+        caller: 'share',
+        agentOnly: isHeadlessSecretsContext(),
+    });
+    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).`);
+    }
+    return token;
+}
+/** Cloudflare API credentials for provisioning, read from `cloudflare.com` (or a
+ * user-named bundle). Fuzzy-matches key names so it works across bundle layouts. */
+export function readCloudflareCreds(bundle = DEFAULT_CF_BUNDLE, override) {
+    // Explicit --token/--account bypass the bundle entirely (robust escape hatch).
+    if (override?.apiToken) {
+        return { apiToken: override.apiToken, accountId: override.accountId ?? '' };
+    }
+    const { env } = readAndResolveBundleEnv(bundle, {
+        caller: 'share',
+        agentOnly: isHeadlessSecretsContext(),
+    });
+    const find = (re) => {
+        for (const [k, v] of Object.entries(env))
+            if (re.test(k) && v)
+                return v;
+        return '';
+    };
+    const apiToken = env.CLOUDFLARE_API_TOKEN || env.CF_API_TOKEN || find(/API[_-]?TOKEN|(?:^|_)TOKEN$/i);
+    const accountId = override?.accountId || env.CLOUDFLARE_ACCOUNT_ID || env.CF_ACCOUNT_ID || find(/ACCOUNT[_-]?ID/i);
+    if (!apiToken) {
+        const keys = Object.keys(env);
+        throw new Error(`No Cloudflare API token in the '${bundle}' bundle ` +
+            `(keys present: ${keys.length ? keys.join(', ') : 'none'}). ` +
+            `Pass it directly with --token <t> [--account <id>], or add it: ` +
+            `agents secrets add ${bundle} CLOUDFLARE_API_TOKEN`);
+    }
+    return { apiToken, accountId };
+}

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

@@ -0,0 +1,25 @@
+/**
+ * Open Graph / Twitter card meta for a shared HTML page.
+ *
+ * `deriveMeta` pulls a title + description out of the document (its `<title>`/`<h1>`
+ * and first real paragraph or existing `<meta name=description>`); `injectOgMeta`
+ * splices the social tags into `<head>` (idempotent — it strips any tags we
+ * previously added before re-inserting). Pure string work so it's unit-testable
+ * without a browser or network.
+ */
+export interface OgFields {
+    title: string;
+    description: string;
+    imageUrl: string;
+    pageUrl: string;
+    /** Actual pixel dimensions of the served image (defaults to the 1200×630 OG card). */
+    imageWidth?: number;
+    imageHeight?: number;
+}
+/** Pull a sensible title + description out of a plan/document's HTML. */
+export declare function deriveMeta(html: string, fallbackTitle?: string): {
+    title: string;
+    description: string;
+};
+/** Splice OG + Twitter tags into `<head>` (or prepend if there's no head). Idempotent. */
+export declare function injectOgMeta(html: string, f: OgFields): string;

package/dist/lib/share/og.js

@@ -0,0 +1,84 @@
+/**
+ * Open Graph / Twitter card meta for a shared HTML page.
+ *
+ * `deriveMeta` pulls a title + description out of the document (its `<title>`/`<h1>`
+ * and first real paragraph or existing `<meta name=description>`); `injectOgMeta`
+ * splices the social tags into `<head>` (idempotent — it strips any tags we
+ * previously added before re-inserting). Pure string work so it's unit-testable
+ * without a browser or network.
+ */
+const OG_MARK_OPEN = '<!-- agents-share:og -->';
+const OG_MARK_CLOSE = '<!-- /agents-share:og -->';
+function escapeAttr(s) {
+    return s
+        .replace(/&/g, '&amp;')
+        .replace(/"/g, '&quot;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+}
+function stripTags(s) {
+    return s
+        .replace(/<[^>]+>/g, ' ')
+        .replace(/&nbsp;/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+/** Pull a sensible title + description out of a plan/document's HTML. */
+export function deriveMeta(html, fallbackTitle = 'agents-cli') {
+    const titleMatch = /<title[^>]*>([\s\S]*?)<\/title>/i.exec(html);
+    const h1Match = /<h1[^>]*>([\s\S]*?)<\/h1>/i.exec(html);
+    const title = stripTags(titleMatch?.[1] ?? h1Match?.[1] ?? '') || fallbackTitle;
+    let description = '';
+    const metaDesc = /<meta[^>]+name=["']description["'][^>]+content=["']([^"']*)["']/i.exec(html);
+    if (metaDesc) {
+        description = metaDesc[1].trim();
+    }
+    else {
+        for (const m of html.matchAll(/<p[^>]*>([\s\S]*?)<\/p>/gi)) {
+            const t = stripTags(m[1]);
+            if (t.length > 40) {
+                description = t;
+                break;
+            }
+        }
+    }
+    if (description.length > 198)
+        description = description.slice(0, 197).trimEnd() + '…';
+    return { title, description };
+}
+/** Remove a previously-injected block so re-publishing doesn't stack duplicate tags. */
+function stripPrevious(html) {
+    const re = new RegExp(`${OG_MARK_OPEN}[\\s\\S]*?${OG_MARK_CLOSE}\\n?`, 'g');
+    return html.replace(re, '');
+}
+/** Splice OG + Twitter tags into `<head>` (or prepend if there's no head). Idempotent. */
+export function injectOgMeta(html, f) {
+    const cleaned = stripPrevious(html);
+    const t = escapeAttr(f.title);
+    const d = escapeAttr(f.description);
+    const w = f.imageWidth ?? 1200;
+    const h = f.imageHeight ?? 630;
+    const block = `${OG_MARK_OPEN}\n` +
+        `<meta property="og:type" content="website">\n` +
+        `<meta property="og:site_name" content="agents-cli">\n` +
+        `<meta property="og:title" content="${t}">\n` +
+        `<meta property="og:description" content="${d}">\n` +
+        `<meta property="og:url" content="${escapeAttr(f.pageUrl)}">\n` +
+        `<meta property="og:image" content="${escapeAttr(f.imageUrl)}">\n` +
+        `<meta property="og:image:width" content="${w}">\n` +
+        `<meta property="og:image:height" content="${h}">\n` +
+        `<meta name="twitter:card" content="summary_large_image">\n` +
+        `<meta name="twitter:title" content="${t}">\n` +
+        `<meta name="twitter:description" content="${d}">\n` +
+        `<meta name="twitter:image" content="${escapeAttr(f.imageUrl)}">\n` +
+        `${OG_MARK_CLOSE}\n`;
+    const headClose = cleaned.search(/<\/head>/i);
+    if (headClose !== -1)
+        return cleaned.slice(0, headClose) + block + cleaned.slice(headClose);
+    const headOpen = /<head[^>]*>/i.exec(cleaned);
+    if (headOpen) {
+        const at = headOpen.index + headOpen[0].length;
+        return cleaned.slice(0, at) + '\n' + block + cleaned.slice(at);
+    }
+    return block + cleaned;
+}

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

@@ -0,0 +1,10 @@
+/** Create the R2 bucket (idempotent). */
+export declare function createBucket(apiToken: string, accountId: string, name: string): Promise<void>;
+/** Upload the module Worker with an R2 binding (`BUCKET`) + inline `WRITE_TOKEN` secret. */
+export declare function deployWorker(apiToken: string, accountId: string, workerName: string, script: string, bucketName: string, writeToken: string): Promise<void>;
+/** Enable the free `*.workers.dev` route for the script, and return the account subdomain. */
+export declare function enableWorkersDev(apiToken: string, accountId: string, workerName: string): Promise<string>;
+/** Resolve a zone id for a domain the token can see, or null if not owned/visible. */
+export declare function findZoneId(apiToken: string, domain: string): Promise<string | null>;
+/** Map a custom hostname (e.g. `share.agents-cli.sh`) to the Worker via Workers Custom Domains. */
+export declare function addCustomDomain(apiToken: string, accountId: string, workerName: string, zoneId: string, hostname: string): Promise<void>;

package/dist/lib/share/provision.js

@@ -0,0 +1,91 @@
+// Cloudflare provisioning for `agents share setup` — plain `fetch` against the CF
+// REST API (the repo has no CF wrapper). Creates the R2 bucket, uploads the Worker
+// (with an R2 binding + the WRITE_TOKEN as an inline secret), enables the free
+// `*.workers.dev` subdomain, and — when the token owns the zone — maps a custom domain.
+const CF_API = 'https://api.cloudflare.com/client/v4';
+async function cf(apiToken, method, pathname, body, form) {
+    const headers = { authorization: `Bearer ${apiToken}` };
+    let payload;
+    if (form) {
+        payload = form; // fetch sets multipart boundary
+    }
+    else if (body !== undefined) {
+        headers['content-type'] = 'application/json';
+        payload = JSON.stringify(body);
+    }
+    const res = await fetch(`${CF_API}${pathname}`, { method, headers, body: payload });
+    const json = (await res.json().catch(() => ({})));
+    if (!res.ok || json.success === false) {
+        const msg = (json.errors ?? []).map((e) => `${e.code ?? ''} ${e.message ?? ''}`.trim()).join('; ') ||
+            res.statusText;
+        throw new Error(`Cloudflare ${method} ${pathname} failed (${res.status}): ${msg}`);
+    }
+    return json.result;
+}
+/** True if the CF error looks like "the thing already exists" (idempotent create). */
+function isAlreadyExists(e) {
+    return /already exists|duplicate|10004|10014/i.test(String(e));
+}
+/** Create the R2 bucket (idempotent). */
+export async function createBucket(apiToken, accountId, name) {
+    try {
+        await cf(apiToken, 'POST', `/accounts/${accountId}/r2/buckets`, { name });
+    }
+    catch (e) {
+        if (!isAlreadyExists(e))
+            throw e;
+    }
+}
+/** Upload the module Worker with an R2 binding (`BUCKET`) + inline `WRITE_TOKEN` secret. */
+export async function deployWorker(apiToken, accountId, workerName, script, bucketName, writeToken) {
+    const metadata = {
+        main_module: 'worker.js',
+        compatibility_date: '2024-11-06',
+        bindings: [
+            { type: 'r2_bucket', name: 'BUCKET', bucket_name: bucketName },
+            { type: 'secret_text', name: 'WRITE_TOKEN', text: writeToken },
+        ],
+    };
+    const form = new FormData();
+    form.set('metadata', new Blob([JSON.stringify(metadata)], { type: 'application/json' }));
+    form.set('worker.js', new Blob([script], { type: 'application/javascript+module' }), 'worker.js');
+    await cf(apiToken, 'PUT', `/accounts/${accountId}/workers/scripts/${workerName}`, undefined, form);
+}
+/** Enable the free `*.workers.dev` route for the script, and return the account subdomain. */
+export async function enableWorkersDev(apiToken, accountId, workerName) {
+    await cf(apiToken, 'POST', `/accounts/${accountId}/workers/scripts/${workerName}/subdomain`, {
+        enabled: true,
+        previews_enabled: false,
+    });
+    const sub = await cf(apiToken, 'GET', `/accounts/${accountId}/workers/subdomain`);
+    if (!sub?.subdomain) {
+        throw new Error('No workers.dev subdomain on this account yet — register one at dash.cloudflare.com → Workers → Subdomain, then re-run.');
+    }
+    return sub.subdomain;
+}
+/** Resolve a zone id for a domain the token can see, or null if not owned/visible. */
+export async function findZoneId(apiToken, domain) {
+    // Try the exact name, then the registrable parent (share.agents-cli.sh -> agents-cli.sh).
+    const candidates = [domain, domain.split('.').slice(-2).join('.')];
+    for (const name of candidates) {
+        const zones = await cf(apiToken, 'GET', `/zones?name=${encodeURIComponent(name)}`).catch(() => []);
+        if (zones?.length)
+            return zones[0].id;
+    }
+    return null;
+}
+/** Map a custom hostname (e.g. `share.agents-cli.sh`) to the Worker via Workers Custom Domains. */
+export async function addCustomDomain(apiToken, accountId, workerName, zoneId, hostname) {
+    try {
+        await cf(apiToken, 'PUT', `/accounts/${accountId}/workers/domains`, {
+            zone_id: zoneId,
+            hostname,
+            service: workerName,
+            environment: 'production',
+        });
+    }
+    catch (e) {
+        if (!isAlreadyExists(e))
+            throw e;
+    }
+}

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

@@ -0,0 +1,57 @@
+type PutFn = (url: string, body: Buffer, headers: Record<string, string>) => Promise<{
+    ok: boolean;
+    status: number;
+    url?: string;
+}>;
+export interface PublishOptions {
+    slug?: string;
+    /** e.g. `30d`, `12h`, or an absolute date like `2026-08-01`. */
+    expire?: string;
+    contentType?: string;
+    /** Generate + attach an OG cover for HTML pages (default true). */
+    cover?: boolean;
+    /** DI seam for tests — override the real HTTP PUT. */
+    uploader?: (url: string, body: Buffer, headers: Record<string, string>) => Promise<{
+        ok: boolean;
+        status: number;
+        url?: string;
+    }>;
+    /** DI seam for tests — override cover capture (returns a PNG buffer or null). */
+    capturer?: (htmlPath: string) => Promise<Buffer | null>;
+}
+/** `30d` / `12h` / `2026-08-01` → an absolute ISO timestamp (or undefined). */
+export declare function parseExpire(spec: string | undefined): string | undefined;
+/** Derive a URL-safe slug from a filename (or pass one through). */
+export declare function slugify(name: string): string;
+/** The project the file belongs to — git repo name, else the cwd's basename. */
+export declare function detectProject(dir?: string): string;
+/**
+ * Notion-style default slug: `<project>-<feature>-<6hex>`. Project scopes the link
+ * to the repo the agent is in; the random tail keeps it unguessable + collision-free.
+ * A leading `plan-` on the filename is dropped (it's redundant under the project).
+ */
+export declare function defaultSlug(filePath: string, dir?: string): string;
+/**
+ * Best-effort OG cover: capture a screenshot, upload it as `<slug>.png`, and return
+ * the page body with og:image meta injected (+ the cover URL). All IO is injected
+ * (`put`, `capturer`), so this whole path is unit-testable without config/keychain.
+ * Any miss — no capturer output, a failed upload — returns the original body and no
+ * coverUrl, so publishing never fails because a cover couldn't be made.
+ */
+export declare function attachOgCover(filePath: string, body: Buffer, ctx: {
+    /** Absolute URL to PUT the cover to, `${pageUrl}.png`. Doubles as the cover URL. */
+    pngUrl: string;
+    pageUrl: string;
+    put: PutFn;
+    pngHeaders: Record<string, string>;
+    capturer: (p: string) => Promise<Buffer | null>;
+}): Promise<{
+    body: Buffer;
+    coverUrl?: string;
+}>;
+export declare function publishFile(filePath: string, opts?: PublishOptions): Promise<{
+    url: string;
+    expiresAt?: string;
+    coverUrl?: string;
+}>;
+export {};

package/dist/lib/share/publish.js

@@ -0,0 +1,145 @@
+// The publish path for `agents share <file>` — an authed PUT to the Worker.
+// Pure logic (slug, expiry) is exported for tests; the network call is behind a DI seam.
+//
+// For HTML publishes it also captures a 1200×630 cover (the page's own hero) and
+// injects og:image / twitter:card meta, so the link unfurls into a preview card in
+// Slack / iMessage / Twitter / Discord. The cover is best-effort: if no headless
+// browser is available it's skipped and the plain link still publishes.
+import { readFileSync } from 'node:fs';
+import { basename } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { readShareConfig, readWriteToken } from './config.js';
+import { captureCover, OG_WIDTH, OG_HEIGHT, OG_SCALE } from './capture.js';
+import { deriveMeta, injectOgMeta } from './og.js';
+const UNIT_MS = { s: 1e3, m: 6e4, h: 36e5, d: 864e5, w: 6048e5 };
+/** `30d` / `12h` / `2026-08-01` → an absolute ISO timestamp (or undefined). */
+export function parseExpire(spec) {
+    if (!spec)
+        return undefined;
+    const rel = /^(\d+)\s*([smhdw])$/i.exec(spec.trim());
+    if (rel) {
+        return new Date(Date.now() + parseInt(rel[1], 10) * UNIT_MS[rel[2].toLowerCase()]).toISOString();
+    }
+    const d = new Date(spec);
+    if (!Number.isNaN(d.getTime()))
+        return d.toISOString();
+    throw new Error(`Bad --expire '${spec}'. Use e.g. 30d, 12h, or an absolute date like 2026-08-01.`);
+}
+/** Derive a URL-safe slug from a filename (or pass one through). */
+export function slugify(name) {
+    return (basename(name)
+        .replace(/\.[^.]+$/, '')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 60) || 'page');
+}
+function sanitizeSlugPart(s) {
+    return s.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+}
+/** The project the file belongs to — git repo name, else the cwd's basename. */
+export function detectProject(dir = process.cwd()) {
+    try {
+        const top = execFileSync('git', ['-C', dir, 'rev-parse', '--show-toplevel'], {
+            stdio: ['ignore', 'pipe', 'ignore'],
+        })
+            .toString()
+            .trim();
+        if (top)
+            return sanitizeSlugPart(basename(top)) || 'share';
+    }
+    catch {
+        // not a git repo — fall through to cwd basename
+    }
+    return sanitizeSlugPart(basename(dir)) || 'share';
+}
+/**
+ * Notion-style default slug: `<project>-<feature>-<6hex>`. Project scopes the link
+ * to the repo the agent is in; the random tail keeps it unguessable + collision-free.
+ * A leading `plan-` on the filename is dropped (it's redundant under the project).
+ */
+export function defaultSlug(filePath, dir) {
+    const feature = slugify(filePath).replace(/^plan-/, '') || 'page';
+    return `${detectProject(dir)}-${feature}-${randomBytes(3).toString('hex')}`;
+}
+function guessContentType(filePath) {
+    if (/\.html?$/i.test(filePath))
+        return 'text/html; charset=utf-8';
+    if (/\.css$/i.test(filePath))
+        return 'text/css; charset=utf-8';
+    if (/\.js$/i.test(filePath))
+        return 'text/javascript; charset=utf-8';
+    if (/\.json$/i.test(filePath))
+        return 'application/json';
+    if (/\.svg$/i.test(filePath))
+        return 'image/svg+xml';
+    if (/\.txt$|\.md$/i.test(filePath))
+        return 'text/plain; charset=utf-8';
+    return 'application/octet-stream';
+}
+/**
+ * Best-effort OG cover: capture a screenshot, upload it as `<slug>.png`, and return
+ * the page body with og:image meta injected (+ the cover URL). All IO is injected
+ * (`put`, `capturer`), so this whole path is unit-testable without config/keychain.
+ * Any miss — no capturer output, a failed upload — returns the original body and no
+ * coverUrl, so publishing never fails because a cover couldn't be made.
+ */
+export async function attachOgCover(filePath, body, ctx) {
+    const png = await ctx.capturer(filePath).catch(() => null);
+    if (!png)
+        return { body };
+    const cr = await ctx.put(ctx.pngUrl, png, ctx.pngHeaders);
+    if (!cr.ok)
+        return { body };
+    const { title, description } = deriveMeta(body.toString('utf8'));
+    const injected = injectOgMeta(body.toString('utf8'), {
+        title,
+        description,
+        imageUrl: ctx.pngUrl,
+        pageUrl: ctx.pageUrl,
+        imageWidth: OG_WIDTH * OG_SCALE,
+        imageHeight: OG_HEIGHT * OG_SCALE,
+    });
+    return { body: Buffer.from(injected, 'utf8'), coverUrl: ctx.pngUrl };
+}
+export async function publishFile(filePath, opts = {}) {
+    const cfg = 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).");
+    }
+    const token = readWriteToken();
+    const slug = (opts.slug ?? defaultSlug(filePath)).replace(/^\/+/, '');
+    const expiresAt = parseExpire(opts.expire);
+    const pageUrl = `${cfg.baseUrl}/${slug}`;
+    const put = opts.uploader ??
+        (async (u, b, h) => {
+            const res = await fetch(u, { method: 'PUT', headers: h, body: new Uint8Array(b) });
+            return { ok: res.ok, status: res.status, url: u };
+        });
+    const authHeaders = (contentType) => {
+        const h = { authorization: `Bearer ${token}`, 'content-type': contentType };
+        if (expiresAt)
+            h['x-share-expires-at'] = expiresAt;
+        return h;
+    };
+    let body = readFileSync(filePath);
+    let coverUrl;
+    // Cover: screenshot the page's hero → upload <slug>.png → inject og:image meta.
+    if (/\.html?$/i.test(filePath) && opts.cover !== false) {
+        const res = await attachOgCover(filePath, body, {
+            pngUrl: `${pageUrl}.png`,
+            pageUrl,
+            put,
+            pngHeaders: authHeaders('image/png'),
+            capturer: opts.capturer ?? captureCover,
+        });
+        body = res.body;
+        coverUrl = res.coverUrl;
+    }
+    const r = await put(pageUrl, body, authHeaders(opts.contentType ?? guessContentType(filePath)));
+    if (!r.ok) {
+        throw new Error(`Publish failed (${r.status}) for ${pageUrl}. Check the write token, or that 'agents share setup' completed.`);
+    }
+    return { url: r.url ?? pageUrl, expiresAt, coverUrl };
+}

package/dist/lib/share/worker-template.d.ts

@@ -0,0 +1,2 @@
+/** Render the Worker source. Pure — the R2 binding + token are wired at deploy time. */
+export declare function renderWorkerScript(): string;

package/dist/lib/share/worker-template.js

@@ -0,0 +1,82 @@
+// The Cloudflare Worker that fronts the R2 share bucket.
+//
+// One tiny Worker does both sides:
+//   - PUT  /<slug>  — bearer-gated (WRITE_TOKEN secret); writes the body to R2 via
+//                     the BUCKET binding, storing an optional expiry in object metadata.
+//   - GET  /<slug>  — public; streams the object from R2, 410s (and lazily deletes)
+//                     once its expiry has passed. A bucket lifecycle rule is the
+//                     durable sweeper; this is the immediate gate.
+//
+// Emitted as a string (mirrors src/lib/serve/page.ts `renderPage()`), so it compiles
+// into `dist/**` and ships with no package.json#files change. `provision.ts` uploads
+// this verbatim as an ES-module Worker with a BUCKET (R2) binding + a WRITE_TOKEN secret.
+/** Render the Worker source. Pure — the R2 binding + token are wired at deploy time. */
+export function renderWorkerScript() {
+    return `// GENERATED by agents-cli \`agents share setup\` — do not edit here; edit
+// src/lib/share/worker-template.ts and re-run setup.
+export default {
+  async fetch(request, env) {
+    const url = new URL(request.url);
+    const key = decodeURIComponent(url.pathname.replace(/^\\/+/, ''));
+
+    if (!key) {
+      return new Response('agents share — POST is not it; PUT /<slug> to publish, GET /<slug> to view.', {
+        status: 200, headers: { 'content-type': 'text/plain; charset=utf-8' },
+      });
+    }
+
+    if (request.method === 'PUT') {
+      const presented = (request.headers.get('authorization') || '').replace(/^Bearer\\s+/i, '');
+      if (!env.WRITE_TOKEN || !safeEqual(presented, env.WRITE_TOKEN)) {
+        return json({ error: 'unauthorized' }, 401);
+      }
+      const expiresAt = request.headers.get('x-share-expires-at') || '';
+      const contentType = request.headers.get('content-type') || 'text/html; charset=utf-8';
+      await env.BUCKET.put(key, request.body, {
+        httpMetadata: { contentType },
+        customMetadata: expiresAt ? { expiresAt } : {},
+      });
+      return json({ ok: true, url: url.origin + '/' + key, expiresAt: expiresAt || null }, 200);
+    }
+
+    if (request.method === 'GET' || request.method === 'HEAD') {
+      const obj = await env.BUCKET.get(key);
+      if (!obj) return new Response('not found', { status: 404, headers: { 'content-type': 'text/plain' } });
+      const expiresAt = obj.customMetadata && obj.customMetadata.expiresAt;
+      if (expiresAt && Date.now() > Date.parse(expiresAt)) {
+        await env.BUCKET.delete(key);
+        return new Response('gone — this link has expired', { status: 410, headers: { 'content-type': 'text/plain' } });
+      }
+      const headers = new Headers();
+      obj.writeHttpMetadata(headers);
+      headers.set('etag', obj.httpEtag);
+      if (!headers.has('content-type')) headers.set('content-type', 'text/html; charset=utf-8');
+      headers.set('cache-control', 'public, max-age=60');
+      return new Response(request.method === 'HEAD' ? null : obj.body, { status: 200, headers });
+    }
+
+    if (request.method === 'DELETE') {
+      const presented = (request.headers.get('authorization') || '').replace(/^Bearer\\s+/i, '');
+      if (!env.WRITE_TOKEN || !safeEqual(presented, env.WRITE_TOKEN)) return json({ error: 'unauthorized' }, 401);
+      await env.BUCKET.delete(key);
+      return json({ ok: true, deleted: key }, 200);
+    }
+
+    return new Response('method not allowed', { status: 405 });
+  },
+};
+
+function json(body, status) {
+  return new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json' } });
+}
+
+// Length-independent constant-time-ish compare (Workers has no timingSafeEqual).
+function safeEqual(a, b) {
+  if (typeof a !== 'string' || typeof b !== 'string') return false;
+  const la = a.length, lb = b.length;
+  let out = la ^ lb;
+  for (let i = 0; i < la; i++) out |= a.charCodeAt(i) ^ b.charCodeAt(i % lb || 0);
+  return out === 0 && la === lb;
+}
+`;
+}

package/dist/lib/shims.d.ts

@@ -247,6 +247,19 @@ export declare function readCodexConfiguredModel(): string | undefined;
  * preserved so the "freshest" comparison stays stable and switches don't
  * ping-pong. Best-effort: a failed copy just means the user re-logs in.
  */
+/**
+ * Best-effort account identity for the credential *directory* of a file-auth
+ * agent (droid / kimi / antigravity), or null when the directory holds no
+ * decodable account claim. Delegates to readAuthAccountIdentity, which decrypts
+ * / decodes each agent's REAL on-disk format (droid AES-256-GCM + WorkOS JWT,
+ * kimi access-token JWT, antigravity refresh-token) — the earlier plaintext
+ * top-level-key scan matched NO real credential file, so the guard below never
+ * engaged. Two dirs for the SAME account compare equal; DIFFERENT accounts
+ * compare distinct. Used by carryForwardAuthFiles to refuse overwriting one
+ * account's login with a credential that belongs to a DIFFERENT account
+ * (RUSH-1764).
+ */
+export declare function readAuthFileIdentity(agent: AgentId, configDir: string): string | null;
 export declare function carryForwardAuthFiles(agent: AgentId, toConfigDir: string): void;
 export declare function switchConfigSymlink(agent: AgentId, version: string): Promise<{
     success: boolean;