@phnx-labs/agents-cli 1.20.68 → 1.20.70

package/dist/lib/auth-health.d.ts

@@ -0,0 +1,141 @@
+import { type AccountInfo } from './agents.js';
+import type { AgentId } from './types.js';
+import { type ProviderProbe } from './usage.js';
+/**
+ * - `live`        — completed an authenticated request (200).
+ * - `revoked`     — the server rejected the token (401/403).
+ * - `expired`     — locally-detected expiry; not network-verified (no refresh on the read path).
+ * - `rate_limited`— token works but is throttled right now (429).
+ * - `unverified`  — credential present, not locally expired, but this agent has no in-repo probe endpoint (codex/grok).
+ * - `unconfigured`— no usable credential on disk.
+ * - `error`       — network/other failure; verdict indeterminate (keep the last known one).
+ */
+export type AuthVerdict = 'live' | 'revoked' | 'expired' | 'rate_limited' | 'unverified' | 'unconfigured' | 'error';
+export interface AuthHealth {
+    verdict: AuthVerdict;
+    /** epoch ms of the probe. */
+    checkedAt: number;
+    /** optional short human detail (e.g. "HTTP 401", a network error). */
+    detail?: string;
+    /** account label for display (email / id), when known. Never part of the key. */
+    account?: string;
+}
+/** Agents with a live network probe wired up today. The rest are best-effort. */
+export declare const LIVE_PROBE_AGENTS: ReadonlySet<AgentId>;
+/** Map an HTTP status from a live probe to a verdict. */
+export declare function classifyHttpStatus(status: number): AuthVerdict;
+/** Turn a raw provider probe (from usage.ts) into a verdict. */
+export declare function verdictFromProbe(probe: ProviderProbe): AuthVerdict;
+/** A short human detail line for a probe result (rendered under --verbose). */
+export declare function probeDetail(probe: ProviderProbe): string | undefined;
+/** Uncolored glyph for a verdict (color is applied by the caller). */
+export declare function verdictGlyph(verdict: AuthVerdict): string;
+/** One-word label for matrices/verbose output. */
+export declare function verdictLabel(verdict: AuthVerdict): string;
+/** Roll a set of verdicts (one host×agent's installs) into counts for a matrix cell. */
+export interface VerdictSummary {
+    live: number;
+    /** revoked — the server rejected the token (401/403). Genuinely needs re-login. */
+    bad: number;
+    /**
+     * expired / rate_limited / unverified / error — degraded or unknown, but NOT
+     * "re-login now". `expired` is soft for kimi/droid (their CLIs refresh the
+     * token on next launch; we don't refresh on the read path), so it must not be
+     * lumped with revoked or we'd cry wolf on a self-healing token.
+     */
+    warn: number;
+    total: number;
+}
+export declare function summarizeVerdicts(verdicts: AuthVerdict[]): VerdictSummary;
+/** Verdicts that mean "this token was rejected by the server — re-login required". */
+export declare function isDeadVerdict(verdict: AuthVerdict): boolean;
+/**
+ * A host's rolled-up auth state for the `fleet status` Auth column.
+ *
+ * The four display buckets are deliberately finer-grained than
+ * {@link VerdictSummary}'s live/bad/warn: they separate "present but this agent
+ * has no live probe" (`unverified`) and "soft, self-healing expiry"
+ * (`expired`/`rate_limited`) from a genuine server rejection (`revoked`). The
+ * old three-bucket rollup lumped all of those into `warn` and the column painted
+ * them one alarming yellow — so a fleet of perfectly logged-in accounts on
+ * codex/grok/etc (which can NEVER be probed live) read as half-degraded. These
+ * buckets let the renderer show `unverified` as neutral and reserve red for the
+ * only verdict that actually means "re-login now" ({@link isDeadVerdict}).
+ */
+export interface HostAuthSummary {
+    /** Live-verified accounts (a real 2xx). */
+    live: number;
+    /** Signed in but this agent has no live-probe endpoint — benign, neutral. */
+    present: number;
+    /** Soft/degraded: expired (self-healing) / rate_limited / error. Mild warning. */
+    degraded: number;
+    /** Server rejected the token — genuinely needs re-login. */
+    revoked: number;
+    /** Total cached rows for this host (0 → the renderer shows "—"). */
+    total: number;
+    /** Oldest `checkedAt` (epoch ms) among this host's cached rows, or null when none. */
+    oldestCheckedAt: number | null;
+}
+/**
+ * Roll every cached (agent, version) row for one host into a {@link HostAuthSummary}
+ * plus the age of its stalest entry. Pure — reads the map the caller already
+ * loaded via {@link readAuthHealthCache}, so `fleet status` renders the Auth
+ * column without any network probe. A host with no cached rows yields an empty
+ * summary (total 0), which the renderer shows as "—".
+ *
+ * Keys are `host:agent:version` ({@link authCacheKey}); we match on the `host:`
+ * prefix so agent/version segments can never be mistaken for a host.
+ */
+export declare function summarizeHostAuth(cache: Record<string, AuthHealth>, host: string): HostAuthSummary;
+/** Human "3m ago" style age for a checkedAt timestamp. */
+export declare function formatCheckedAge(checkedAt: number, now?: number): string;
+/**
+ * Human account label for display (email, else id). NOT used in the cache key —
+ * two installs on one host can hold the same account with independently valid
+ * tokens, so the key is keyed by version (below), not account.
+ */
+export declare function authAccountLabel(info: Pick<AccountInfo, 'email' | 'accountId' | 'userId'> | null | undefined): string | undefined;
+/** Cache key: one entry per install — (host, agent, version). Unique per token. */
+export declare function authCacheKey(host: string, agent: AgentId | string, version: string): string;
+/** Read the whole cache (best-effort; a corrupt/missing file yields an empty map). */
+export declare function readAuthHealthCache(): Record<string, AuthHealth>;
+/** Read one entry, or null. */
+export declare function readAuthHealth(host: string, agent: AgentId | string, version: string): AuthHealth | null;
+/**
+ * Merge entries into the cache. An incoming `error` verdict (a network blip,
+ * not a server rejection) is indeterminate, so it must NOT clobber a prior
+ * known verdict — otherwise one 8s timeout flips a `live` chip to `error`,
+ * exactly the "cry wolf" the verdict model avoids for `expired`. This is the
+ * behaviour promised by the `error` doc on AuthVerdict ("keep the last known
+ * one"). Pure, so it's unit-tested directly. */
+export declare function mergeAuthHealthEntries(current: Record<string, AuthHealth>, incoming: Record<string, AuthHealth>): Record<string, AuthHealth>;
+/** Merge one or more entries into the cache (best-effort write). */
+export declare function writeAuthHealthEntries(entries: Record<string, AuthHealth>): void;
+/**
+ * Complete a live auth probe for one (agent, home). For claude/kimi/droid this
+ * hits the provider; for everyone else it reports a best-effort local verdict
+ * (`unverified` when a credential is present, `unconfigured` otherwise) — never
+ * masquerading as `live`.
+ */
+export declare function probeAuthHealth(agent: AgentId, home: string | undefined, opts?: {
+    cliVersion?: string | null;
+    info?: AccountInfo | null;
+}): Promise<AuthHealth>;
+/** One probed install on a host. */
+export interface AuthProbeRow {
+    agent: AgentId;
+    version: string;
+    account?: string;
+    health: AuthHealth;
+}
+/**
+ * Enumerate every installed (agent, version) on THIS host, probe each in
+ * parallel, and return the rows (installs with no credential at all are
+ * dropped). Shared by `agents fleet ping --local` and the daemon refresh.
+ */
+export declare function probeLocalFleetAuth(opts?: {
+    cliVersion?: string | null;
+    agents?: readonly AgentId[];
+}): Promise<AuthProbeRow[]>;
+/** Persist a host's probed rows into the cache (keyed by host+agent+version). */
+export declare function writeFleetAuthRows(host: string, rows: AuthProbeRow[]): void;

package/dist/lib/auth-health.js

@@ -0,0 +1,277 @@
+/**
+ * Live auth-health: does an agent account's stored credential actually complete
+ * an authenticated request right now?
+ *
+ * The rest of the CLI reports "signed in" from a local heuristic — a credential
+ * file is present and its email decodes — which cannot distinguish a good token
+ * from a revoked-but-unexpired one. This module completes a real request per
+ * (agent, account) and records the verdict in a small cache that `agents view`
+ * (per-version chip), `agents fleet status` (the per-host Auth column, via
+ * {@link summarizeHostAuth}), and the run rotation all read. The writers are
+ * the daemon (a periodic local refresh) and `agents fleet ping` (which also
+ * fans out to write remote hosts' rows into the local cache); everyone else
+ * reads.
+ *
+ * The network probes themselves live in lib/usage.ts (where the per-provider
+ * token loaders + endpoints already are); this module classifies their result,
+ * covers the best-effort (non-networked) providers, and owns the cache.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { ALL_AGENT_IDS, getAccountInfo } from './agents.js';
+import { getCacheDir } from './state.js';
+import { probeClaudeStatus, probeDroidStatus, probeKimiStatus, } from './usage.js';
+import { getVersionHomePath, listInstalledVersions } from './versions.js';
+/** Agents with a live network probe wired up today. The rest are best-effort. */
+export const LIVE_PROBE_AGENTS = new Set(['claude', 'kimi', 'droid']);
+// ---------------------------------------------------------------------------
+// Pure classifiers / render (unit-tested; no network, no fs)
+// ---------------------------------------------------------------------------
+/** Map an HTTP status from a live probe to a verdict. */
+export function classifyHttpStatus(status) {
+    if (status >= 200 && status < 300)
+        return 'live';
+    if (status === 401 || status === 403)
+        return 'revoked';
+    if (status === 429)
+        return 'rate_limited';
+    return 'error';
+}
+/** Turn a raw provider probe (from usage.ts) into a verdict. */
+export function verdictFromProbe(probe) {
+    if (probe.token === 'missing')
+        return 'unconfigured';
+    if (probe.token === 'expired')
+        return 'expired';
+    if (probe.status == null)
+        return 'error';
+    return classifyHttpStatus(probe.status);
+}
+/** A short human detail line for a probe result (rendered under --verbose). */
+export function probeDetail(probe) {
+    if (probe.status != null && (probe.status < 200 || probe.status >= 300))
+        return `HTTP ${probe.status}`;
+    if (probe.error)
+        return probe.error;
+    return undefined;
+}
+const VERDICT_GLYPHS = {
+    live: '●', // ●
+    revoked: '○', // ○
+    expired: '○', // ○
+    rate_limited: '◐', // ◐
+    unverified: '◐', // ◐
+    unconfigured: '·', // ·
+    error: '·', // ·
+};
+/** Uncolored glyph for a verdict (color is applied by the caller). */
+export function verdictGlyph(verdict) {
+    return VERDICT_GLYPHS[verdict] ?? '·';
+}
+/** One-word label for matrices/verbose output. */
+export function verdictLabel(verdict) {
+    switch (verdict) {
+        case 'live': return 'live';
+        case 'revoked': return 'revoked';
+        case 'expired': return 'expired';
+        case 'rate_limited': return 'limited';
+        case 'unverified': return 'unverified';
+        case 'unconfigured': return '—';
+        case 'error': return '?';
+    }
+}
+export function summarizeVerdicts(verdicts) {
+    let live = 0;
+    let bad = 0;
+    let warn = 0;
+    for (const v of verdicts) {
+        if (v === 'live')
+            live++;
+        else if (v === 'revoked')
+            bad++;
+        else
+            warn++;
+    }
+    return { live, bad, warn, total: verdicts.length };
+}
+/** Verdicts that mean "this token was rejected by the server — re-login required". */
+export function isDeadVerdict(verdict) {
+    return verdict === 'revoked';
+}
+/**
+ * Roll every cached (agent, version) row for one host into a {@link HostAuthSummary}
+ * plus the age of its stalest entry. Pure — reads the map the caller already
+ * loaded via {@link readAuthHealthCache}, so `fleet status` renders the Auth
+ * column without any network probe. A host with no cached rows yields an empty
+ * summary (total 0), which the renderer shows as "—".
+ *
+ * Keys are `host:agent:version` ({@link authCacheKey}); we match on the `host:`
+ * prefix so agent/version segments can never be mistaken for a host.
+ */
+export function summarizeHostAuth(cache, host) {
+    const prefix = `${host}:`;
+    let live = 0, present = 0, degraded = 0, revoked = 0, total = 0;
+    let oldest = null;
+    for (const [key, health] of Object.entries(cache)) {
+        if (!key.startsWith(prefix))
+            continue;
+        // `unconfigured` = no credential at all — not a probed account. Writers
+        // already drop these before they reach the cache; skip here too so a stray
+        // one never counts toward total or the freshness age (belt-and-suspenders).
+        if (health.verdict === 'unconfigured')
+            continue;
+        total++;
+        switch (health.verdict) {
+            case 'live':
+                live++;
+                break;
+            case 'unverified':
+                present++;
+                break; // signed in, no probe — benign
+            case 'revoked':
+                revoked++;
+                break; // server said no — re-login
+            default:
+                degraded++;
+                break; // expired / rate_limited / error — soft
+        }
+        if (oldest === null || health.checkedAt < oldest)
+            oldest = health.checkedAt;
+    }
+    return { live, present, degraded, revoked, total, oldestCheckedAt: oldest };
+}
+/** Human "3m ago" style age for a checkedAt timestamp. */
+export function formatCheckedAge(checkedAt, now = Date.now()) {
+    const secs = Math.max(0, Math.round((now - checkedAt) / 1000));
+    if (secs < 60)
+        return `${secs}s ago`;
+    const mins = Math.round(secs / 60);
+    if (mins < 60)
+        return `${mins}m ago`;
+    const hours = Math.round(mins / 60);
+    if (hours < 24)
+        return `${hours}h ago`;
+    return `${Math.round(hours / 24)}d ago`;
+}
+// ---------------------------------------------------------------------------
+// Cache identity + IO (single source of truth read by view/fleet/rotation)
+// ---------------------------------------------------------------------------
+/**
+ * Human account label for display (email, else id). NOT used in the cache key —
+ * two installs on one host can hold the same account with independently valid
+ * tokens, so the key is keyed by version (below), not account.
+ */
+export function authAccountLabel(info) {
+    return info?.email || info?.accountId || info?.userId || undefined;
+}
+/** Cache key: one entry per install — (host, agent, version). Unique per token. */
+export function authCacheKey(host, agent, version) {
+    return `${host}:${agent}:${version}`;
+}
+function cacheFilePath() {
+    return path.join(getCacheDir(), '.auth-health.json');
+}
+/** Read the whole cache (best-effort; a corrupt/missing file yields an empty map). */
+export function readAuthHealthCache() {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(cacheFilePath(), 'utf-8'));
+        if (parsed && parsed.entries && typeof parsed.entries === 'object')
+            return parsed.entries;
+    }
+    catch {
+        // missing or corrupt — treat as empty
+    }
+    return {};
+}
+/** Read one entry, or null. */
+export function readAuthHealth(host, agent, version) {
+    return readAuthHealthCache()[authCacheKey(host, agent, version)] ?? null;
+}
+/**
+ * Merge entries into the cache. An incoming `error` verdict (a network blip,
+ * not a server rejection) is indeterminate, so it must NOT clobber a prior
+ * known verdict — otherwise one 8s timeout flips a `live` chip to `error`,
+ * exactly the "cry wolf" the verdict model avoids for `expired`. This is the
+ * behaviour promised by the `error` doc on AuthVerdict ("keep the last known
+ * one"). Pure, so it's unit-tested directly. */
+export function mergeAuthHealthEntries(current, incoming) {
+    const merged = { ...current };
+    for (const [key, health] of Object.entries(incoming)) {
+        if (health.verdict === 'error' && merged[key])
+            continue; // keep last known
+        merged[key] = health;
+    }
+    return merged;
+}
+/** Merge one or more entries into the cache (best-effort write). */
+export function writeAuthHealthEntries(entries) {
+    try {
+        const dir = getCacheDir();
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+        const merged = {
+            version: 1,
+            entries: mergeAuthHealthEntries(readAuthHealthCache(), entries),
+        };
+        fs.writeFileSync(cacheFilePath(), JSON.stringify(merged, null, 2));
+    }
+    catch {
+        // best-effort; a failed write just means the next reader falls back to heuristics
+    }
+}
+// ---------------------------------------------------------------------------
+// The probe (writer side)
+// ---------------------------------------------------------------------------
+/**
+ * Complete a live auth probe for one (agent, home). For claude/kimi/droid this
+ * hits the provider; for everyone else it reports a best-effort local verdict
+ * (`unverified` when a credential is present, `unconfigured` otherwise) — never
+ * masquerading as `live`.
+ */
+export async function probeAuthHealth(agent, home, opts) {
+    const checkedAt = Date.now();
+    if (LIVE_PROBE_AGENTS.has(agent)) {
+        let probe;
+        if (agent === 'claude')
+            probe = await probeClaudeStatus(home, opts?.cliVersion);
+        else if (agent === 'kimi')
+            probe = await probeKimiStatus(home);
+        else
+            probe = await probeDroidStatus(home);
+        return { verdict: verdictFromProbe(probe), checkedAt, detail: probeDetail(probe) };
+    }
+    const info = opts?.info !== undefined ? opts.info : await getAccountInfo(agent, home).catch(() => null);
+    return { verdict: info?.signedIn ? 'unverified' : 'unconfigured', checkedAt };
+}
+/**
+ * Enumerate every installed (agent, version) on THIS host, probe each in
+ * parallel, and return the rows (installs with no credential at all are
+ * dropped). Shared by `agents fleet ping --local` and the daemon refresh.
+ */
+export async function probeLocalFleetAuth(opts) {
+    const agentIds = opts?.agents ?? ALL_AGENT_IDS;
+    const tasks = [];
+    for (const agent of agentIds) {
+        for (const version of listInstalledVersions(agent)) {
+            const home = getVersionHomePath(agent, version);
+            tasks.push((async () => {
+                const info = await getAccountInfo(agent, home).catch(() => null);
+                const health = await probeAuthHealth(agent, home, { cliVersion: opts?.cliVersion, info });
+                health.account = authAccountLabel(info);
+                if (health.verdict === 'unconfigured')
+                    return null;
+                return { agent, version, account: health.account, health };
+            })());
+        }
+    }
+    const settled = await Promise.all(tasks);
+    return settled.filter((r) => r !== null);
+}
+/** Persist a host's probed rows into the cache (keyed by host+agent+version). */
+export function writeFleetAuthRows(host, rows) {
+    const entries = {};
+    for (const row of rows) {
+        entries[authCacheKey(host, row.agent, row.version)] = row.health;
+    }
+    writeAuthHealthEntries(entries);
+}

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

@@ -24,6 +24,15 @@ export declare function findFirstInstalledBrowser(platform?: string): {
     browserType: BrowserType;
     binary: string;
 } | null;
+/**
+ * List every installed Chromium-family browser on this machine, in the platform
+ * priority order. Used by `agents setup browser` to offer a pick when more than
+ * one is present. Returns [] if none are installed.
+ */
+export declare function listInstalledBrowsers(platform?: string): {
+    browserType: BrowserType;
+    binary: string;
+}[];
 export interface LaunchResult {
     pid: number;
     port: number;

package/dist/lib/browser/chrome.js

@@ -203,6 +203,28 @@ export function findFirstInstalledBrowser(platform = os.platform()) {
     }
     return null;
 }
+/**
+ * List every installed Chromium-family browser on this machine, in the platform
+ * priority order. Used by `agents setup browser` to offer a pick when more than
+ * one is present. Returns [] if none are installed.
+ */
+export function listInstalledBrowsers(platform = os.platform()) {
+    const priority = DEFAULT_BROWSER_PRIORITY[platform];
+    const platformPaths = BROWSER_PATHS[platform];
+    if (!priority || !platformPaths)
+        return [];
+    const found = [];
+    for (const browserType of priority) {
+        const candidates = platformPaths[browserType] || [];
+        for (const p of candidates) {
+            if (fs.existsSync(p)) {
+                found.push({ browserType, binary: resolveBrowserBinary(p) });
+                break; // one install path per browser type is enough
+            }
+        }
+    }
+    return found;
+}
 export async function launchBrowser(profileName, browserType, port, options = {}, secrets, customBinary, 
 // `electron: true` distinguishes Notion / VS Code-style apps from
 // regular Chrome — purely informational, stored in meta.json so the

package/dist/lib/computer/download.d.ts

@@ -0,0 +1,54 @@
+/**
+ * On-demand download + verification of the macOS `agents computer` helper
+ * ("ComputerHelper.app").
+ *
+ * The helper is a signed + notarized universal `.app` bundle published as a
+ * GitHub release asset per tagged CLI version — the same distribution model as
+ * the Windows helper (see `lib/ssh-tunnel.ts`). A fresh `npm i -g` machine has
+ * no local build, so `agents computer setup` / `agents setup computer` fetch the
+ * asset for the running CLI version, verify its sha256 against the published
+ * `.sha256`, then verify the code signature (Developer ID Team + notarization)
+ * before it is ever copied to /Applications.
+ *
+ * A `.app` is a directory, so the asset is a zip (`ditto -c -k --keepParent`);
+ * we extract it with `ditto -x -k` after the checksum passes.
+ */
+/** GitHub repo whose `v<version>` releases carry the helper asset. */
+export declare const HELPER_RELEASE_REPO = "phnx-labs/agents-cli";
+/** The zipped `.app` release asset name. */
+export declare const MAC_HELPER_ASSET = "ComputerHelper.app.zip";
+/** The bundle directory name once extracted. */
+export declare const MAC_HELPER_APP_NAME = "ComputerHelper.app";
+/** Apple Developer ID Team the helper must be signed by (defense in depth on top
+ * of `spctl` notarization assessment). "Developer ID Application: Muqit Nawaz". */
+export declare const EXPECTED_TEAM_ID = "2HTP252L87";
+/** Cache dir for the downloaded helper, one subdir per release tag. */
+export declare function macHelperCacheDir(version: string): string;
+/** Release-asset URLs for the helper zip + its checksum at one `v<version>` tag. */
+export declare function macHelperAssetUrls(version: string): {
+    zip: string;
+    sha256: string;
+};
+/** Extract `TeamIdentifier=XXXX` from `codesign -dv --verbose=4` output (which is
+ * emitted on stderr). Returns null when absent (ad-hoc / unsigned). */
+export declare function parseTeamId(codesignInfo: string): string | null;
+/**
+ * Verify a helper `.app` bundle is intact, signed by the expected Developer ID
+ * Team, and notarized (Gatekeeper-accepted). Throws with an actionable message
+ * on any failure — a downloaded bundle is never trusted without this.
+ */
+export declare function verifyMacHelper(appPath: string): void;
+/**
+ * Download the helper release asset for `version`, verify sha256, extract the
+ * `.app`, and verify its signature. Returns the path to the extracted
+ * `ComputerHelper.app`. A missing asset is a hard error naming the exact tag —
+ * never a silent fallback to another release.
+ */
+export declare function downloadMacHelperApp(version: string): Promise<string>;
+/**
+ * Resolve the helper `.app` to install from: a local build / bundled copy first
+ * (repo checkout), else the checksum + signature-verified release-asset download
+ * for the running CLI version. Throws with the tag it checked when neither
+ * exists. macOS only.
+ */
+export declare function ensureMacHelperApp(version?: string): Promise<string>;

package/dist/lib/computer/download.js

@@ -0,0 +1,146 @@
+/**
+ * On-demand download + verification of the macOS `agents computer` helper
+ * ("ComputerHelper.app").
+ *
+ * The helper is a signed + notarized universal `.app` bundle published as a
+ * GitHub release asset per tagged CLI version — the same distribution model as
+ * the Windows helper (see `lib/ssh-tunnel.ts`). A fresh `npm i -g` machine has
+ * no local build, so `agents computer setup` / `agents setup computer` fetch the
+ * asset for the running CLI version, verify its sha256 against the published
+ * `.sha256`, then verify the code signature (Developer ID Team + notarization)
+ * before it is ever copied to /Applications.
+ *
+ * A `.app` is a directory, so the asset is a zip (`ditto -c -k --keepParent`);
+ * we extract it with `ditto -x -k` after the checksum passes.
+ */
+import { execFileSync, spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { getCacheDir } from '../state.js';
+import { getCliVersion } from '../version.js';
+import { parseSha256Asset, sha256File } from '../ssh-tunnel.js';
+import { resolveHelperApp } from '../computer-rpc.js';
+/** GitHub repo whose `v<version>` releases carry the helper asset. */
+export const HELPER_RELEASE_REPO = 'phnx-labs/agents-cli';
+/** The zipped `.app` release asset name. */
+export const MAC_HELPER_ASSET = 'ComputerHelper.app.zip';
+/** The bundle directory name once extracted. */
+export const MAC_HELPER_APP_NAME = 'ComputerHelper.app';
+/** Apple Developer ID Team the helper must be signed by (defense in depth on top
+ * of `spctl` notarization assessment). "Developer ID Application: Muqit Nawaz". */
+export const EXPECTED_TEAM_ID = '2HTP252L87';
+/** Cache dir for the downloaded helper, one subdir per release tag. */
+export function macHelperCacheDir(version) {
+    return path.join(getCacheDir(), 'computer', 'mac-helper', `v${version}`);
+}
+/** Release-asset URLs for the helper zip + its checksum at one `v<version>` tag. */
+export function macHelperAssetUrls(version) {
+    const base = `https://github.com/${HELPER_RELEASE_REPO}/releases/download/v${version}`;
+    return { zip: `${base}/${MAC_HELPER_ASSET}`, sha256: `${base}/${MAC_HELPER_ASSET}.sha256` };
+}
+/** Extract `TeamIdentifier=XXXX` from `codesign -dv --verbose=4` output (which is
+ * emitted on stderr). Returns null when absent (ad-hoc / unsigned). */
+export function parseTeamId(codesignInfo) {
+    return codesignInfo.match(/TeamIdentifier=([A-Z0-9]+)/)?.[1] ?? null;
+}
+/**
+ * Verify a helper `.app` bundle is intact, signed by the expected Developer ID
+ * Team, and notarized (Gatekeeper-accepted). Throws with an actionable message
+ * on any failure — a downloaded bundle is never trusted without this.
+ */
+export function verifyMacHelper(appPath) {
+    // 1. Structural + signature integrity.
+    try {
+        execFileSync('/usr/bin/codesign', ['--verify', '--deep', '--strict', appPath], { stdio: 'pipe' });
+    }
+    catch (e) {
+        throw new Error(`code signature invalid for ${appPath}: ${e.message}`);
+    }
+    // 2. Team identity — must be our Developer ID, not some other valid signer.
+    // `codesign -dv` writes its details to STDERR even on success (exit 0), so we
+    // must read stderr, not stdout. spawnSync captures both streams regardless of
+    // exit code; execFileSync would return only (empty) stdout and the Team check
+    // would falsely reject every validly-signed helper.
+    const dv = spawnSync('/usr/bin/codesign', ['-dv', '--verbose=4', appPath], { encoding: 'utf8' });
+    const info = `${dv.stdout ?? ''}${dv.stderr ?? ''}`;
+    const team = parseTeamId(info);
+    if (team !== EXPECTED_TEAM_ID) {
+        throw new Error(`helper signed by unexpected Team (${team ?? 'none'}), expected ${EXPECTED_TEAM_ID}. Refusing to install.`);
+    }
+    // 3. Notarization / Gatekeeper — confirms Apple stapled a notarization ticket.
+    try {
+        execFileSync('/usr/sbin/spctl', ['--assess', '--type', 'execute', '--verbose', appPath], { stdio: 'pipe' });
+    }
+    catch (e) {
+        throw new Error(`helper is not notarized / rejected by Gatekeeper: ${e.message}. Refusing to install.`);
+    }
+}
+/**
+ * Download the helper release asset for `version`, verify sha256, extract the
+ * `.app`, and verify its signature. Returns the path to the extracted
+ * `ComputerHelper.app`. A missing asset is a hard error naming the exact tag —
+ * never a silent fallback to another release.
+ */
+export async function downloadMacHelperApp(version) {
+    const dir = macHelperCacheDir(version);
+    const cachedApp = path.join(dir, MAC_HELPER_APP_NAME);
+    if (fs.existsSync(cachedApp)) {
+        // Re-verify a cached bundle cheaply; a tampered cache must not be trusted.
+        verifyMacHelper(cachedApp);
+        return cachedApp;
+    }
+    const tag = `v${version}`;
+    const { zip: zipUrl, sha256: shaUrl } = macHelperAssetUrls(version);
+    const missing = (status, url) => new Error(`no ${MAC_HELPER_ASSET} release asset for tag ${tag} (HTTP ${status} on ${url}). ` +
+        `The macOS helper ships as a GitHub release asset per tagged CLI version; ` +
+        `from a repo checkout you can build it locally instead: ` +
+        `bash native/computer-mac/scripts/build.sh release`);
+    // Checksum first: it is tiny and 404s fast when the tag has no assets.
+    const shaRes = await fetch(shaUrl, { signal: AbortSignal.timeout(30_000) });
+    if (!shaRes.ok)
+        throw missing(shaRes.status, shaUrl);
+    const expected = parseSha256Asset(await shaRes.text());
+    console.error(`Downloading ${MAC_HELPER_ASSET} ${tag} from GitHub releases...`);
+    const zipRes = await fetch(zipUrl, { signal: AbortSignal.timeout(15 * 60_000) });
+    if (!zipRes.ok || !zipRes.body)
+        throw missing(zipRes.status, zipUrl);
+    fs.mkdirSync(dir, { recursive: true });
+    const partial = path.join(dir, `${MAC_HELPER_ASSET}.download`);
+    try {
+        await pipeline(Readable.fromWeb(zipRes.body), fs.createWriteStream(partial));
+        const actual = await sha256File(partial);
+        if (actual !== expected) {
+            throw new Error(`sha256 mismatch for ${zipUrl}: expected ${expected}, got ${actual}`);
+        }
+        // Extract the zip (created with `ditto -c -k --keepParent`, so it contains
+        // ComputerHelper.app/ at top level) into the version cache dir.
+        fs.rmSync(cachedApp, { recursive: true, force: true });
+        execFileSync('/usr/bin/ditto', ['-x', '-k', partial, dir], { stdio: 'pipe' });
+        if (!fs.existsSync(cachedApp)) {
+            throw new Error(`extracted asset did not contain ${MAC_HELPER_APP_NAME}`);
+        }
+        verifyMacHelper(cachedApp);
+    }
+    finally {
+        fs.rmSync(partial, { force: true });
+    }
+    return cachedApp;
+}
+/**
+ * Resolve the helper `.app` to install from: a local build / bundled copy first
+ * (repo checkout), else the checksum + signature-verified release-asset download
+ * for the running CLI version. Throws with the tag it checked when neither
+ * exists. macOS only.
+ */
+export async function ensureMacHelperApp(version = getCliVersion()) {
+    if (os.platform() !== 'darwin') {
+        throw new Error('The macOS computer helper is only available on macOS.');
+    }
+    const local = resolveHelperApp();
+    if (local)
+        return local;
+    return downloadMacHelperApp(version);
+}