@phnx-labs/agents-cli 1.20.49 → 1.20.51

package/dist/lib/ssh-tunnel.d.ts

@@ -50,10 +50,41 @@ export declare const REMOTE_TASK_NAME = "AgentsComputerHelper";
 /** Basename of the cross-published exe under native/computer-win/dist. */
 export declare const WIN_HELPER_EXE = "computer-helper-win.exe";
 /**
- * Locate the cross-published Windows daemon exe. Only the local build output is
- * a candidate — `scripts/build-win.sh` writes it to packages/.../dist/.
+ * Locate a locally built Windows daemon exe — a repo-checkout build output from
+ * `scripts/build-win.sh`, or one bundled next to the package. Local paths are
+ * only the first candidate; npm-installed CLIs have neither and fall through to
+ * the release-asset download (`ensureWinHelperExe`).
  */
 export declare function resolveWinHelperExe(): string | null;
+/** GitHub repo whose `v<version>` releases carry the exe as an asset. */
+export declare const WIN_HELPER_RELEASE_REPO = "phnx-labs/agents-cli";
+/** Cache dir for downloaded helper exes, one subdir per release tag. */
+export declare function winHelperCacheDir(version: string): string;
+/** Release-asset URLs for the exe + its checksum at one exact `v<version>` tag. */
+export declare function winHelperAssetUrls(version: string): {
+    exe: string;
+    sha256: string;
+};
+/**
+ * Parse the published `.sha256` asset — `sha256sum` format (`<hex>  <name>`) or
+ * a bare hex digest. Throws on anything that does not lead with 64 hex chars.
+ */
+export declare function parseSha256Asset(text: string): string;
+/** Stream a file through sha256 — the exe is ~157MB, never read it whole. */
+export declare function sha256File(file: string): Promise<string>;
+/**
+ * Download the exe release asset for this CLI version, verify its sha256
+ * against the published `.sha256` asset, and cache it under the agents cache
+ * dir. Only the exact `v<version>` tag is consulted — a missing asset is a
+ * hard error naming that tag, never a silent fallback to another release.
+ */
+export declare function downloadWinHelperExe(version: string): Promise<string>;
+/**
+ * Resolve the helper exe for `setup --host`: local build outputs first (repo
+ * checkout / bundled), then the checksum-verified release-asset download for
+ * the running CLI version. Throws with the tag it checked when neither exists.
+ */
+export declare function ensureWinHelperExe(version?: string): Promise<string>;
 /** Persisted per-device tunnel state so verbs can reconnect after `start --host`. */
 export interface RemoteTunnelState {
     device: string;

package/dist/lib/ssh-tunnel.js

@@ -21,7 +21,9 @@ import * as net from 'net';
 import * as fs from 'fs';
 import * as path from 'path';
 import { fileURLToPath } from 'url';
-import { randomBytes } from 'crypto';
+import { randomBytes, createHash } from 'crypto';
+import { Readable } from 'stream';
+import { pipeline } from 'stream/promises';
 import { sshExec, SSH_OPTS } from './ssh-exec.js';
 import { backgroundSpawnOptions } from './platform/process.js';
 import { encodePowerShell } from './browser/drivers/ssh.js';
@@ -29,6 +31,7 @@ import { getDevice } from './devices/registry.js';
 import { sshTargetFor } from './devices/connect.js';
 import { hostNameFor } from './devices/ssh-config.js';
 import { getCacheDir } from './state.js';
+import { getCliVersion } from './version.js';
 import { openComputerClient, resolveTcpEndpoint } from './computer-rpc.js';
 /** Build the ssh argv (after the `ssh` program name) for an `-L` tunnel. Pure.
  *
@@ -89,8 +92,10 @@ export const REMOTE_TASK_NAME = 'AgentsComputerHelper';
 /** Basename of the cross-published exe under native/computer-win/dist. */
 export const WIN_HELPER_EXE = 'computer-helper-win.exe';
 /**
- * Locate the cross-published Windows daemon exe. Only the local build output is
- * a candidate — `scripts/build-win.sh` writes it to packages/.../dist/.
+ * Locate a locally built Windows daemon exe — a repo-checkout build output from
+ * `scripts/build-win.sh`, or one bundled next to the package. Local paths are
+ * only the first candidate; npm-installed CLIs have neither and fall through to
+ * the release-asset download (`ensureWinHelperExe`).
  */
 export function resolveWinHelperExe() {
     const here = path.dirname(fileURLToPath(import.meta.url));
@@ -106,6 +111,89 @@ export function resolveWinHelperExe() {
     }
     return null;
 }
+/** GitHub repo whose `v<version>` releases carry the exe as an asset. */
+export const WIN_HELPER_RELEASE_REPO = 'phnx-labs/agents-cli';
+/** Cache dir for downloaded helper exes, one subdir per release tag. */
+export function winHelperCacheDir(version) {
+    return path.join(getCacheDir(), 'computer', 'win-helper', `v${version}`);
+}
+/** Release-asset URLs for the exe + its checksum at one exact `v<version>` tag. */
+export function winHelperAssetUrls(version) {
+    const base = `https://github.com/${WIN_HELPER_RELEASE_REPO}/releases/download/v${version}`;
+    return { exe: `${base}/${WIN_HELPER_EXE}`, sha256: `${base}/${WIN_HELPER_EXE}.sha256` };
+}
+/**
+ * Parse the published `.sha256` asset — `sha256sum` format (`<hex>  <name>`) or
+ * a bare hex digest. Throws on anything that does not lead with 64 hex chars.
+ */
+export function parseSha256Asset(text) {
+    const m = text.trim().match(/^([A-Fa-f0-9]{64})(\s|$)/);
+    if (!m)
+        throw new Error(`malformed .sha256 release asset: ${JSON.stringify(text.slice(0, 80))}`);
+    return m[1].toLowerCase();
+}
+/** Stream a file through sha256 — the exe is ~157MB, never read it whole. */
+export function sha256File(file) {
+    return new Promise((resolve, reject) => {
+        const hash = createHash('sha256');
+        fs.createReadStream(file)
+            .on('error', reject)
+            .on('data', (d) => hash.update(d))
+            .on('end', () => resolve(hash.digest('hex')));
+    });
+}
+/**
+ * Download the exe release asset for this CLI version, verify its sha256
+ * against the published `.sha256` asset, and cache it under the agents cache
+ * dir. Only the exact `v<version>` tag is consulted — a missing asset is a
+ * hard error naming that tag, never a silent fallback to another release.
+ */
+export async function downloadWinHelperExe(version) {
+    const cached = path.join(winHelperCacheDir(version), WIN_HELPER_EXE);
+    if (fs.existsSync(cached))
+        return cached;
+    const tag = `v${version}`;
+    const { exe: exeUrl, sha256: shaUrl } = winHelperAssetUrls(version);
+    const missing = (status, url) => new Error(`no ${WIN_HELPER_EXE} release asset for tag ${tag} (HTTP ${status} on ${url}). ` +
+        `The Windows helper ships as a GitHub release asset per tagged CLI version; ` +
+        `from a repo checkout you can build it locally instead: bash scripts/build-win.sh`);
+    // 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 ${WIN_HELPER_EXE} ${tag} from GitHub releases (~160 MB)...`);
+    const exeRes = await fetch(exeUrl, { signal: AbortSignal.timeout(15 * 60_000) });
+    if (!exeRes.ok || !exeRes.body)
+        throw missing(exeRes.status, exeUrl);
+    fs.mkdirSync(path.dirname(cached), { recursive: true });
+    // Stream to a partial file and rename only after the checksum passes, so an
+    // interrupted download can never be picked up as a valid cache hit.
+    const partial = `${cached}.download`;
+    try {
+        await pipeline(Readable.fromWeb(exeRes.body), fs.createWriteStream(partial));
+        const actual = await sha256File(partial);
+        if (actual !== expected) {
+            throw new Error(`sha256 mismatch for ${exeUrl}: expected ${expected}, got ${actual}`);
+        }
+        fs.renameSync(partial, cached);
+    }
+    finally {
+        fs.rmSync(partial, { force: true });
+    }
+    return cached;
+}
+/**
+ * Resolve the helper exe for `setup --host`: local build outputs first (repo
+ * checkout / bundled), then the checksum-verified release-asset download for
+ * the running CLI version. Throws with the tag it checked when neither exists.
+ */
+export async function ensureWinHelperExe(version = getCliVersion()) {
+    const local = resolveWinHelperExe();
+    if (local)
+        return local;
+    return downloadWinHelperExe(version);
+}
 function remoteStateDir() {
     return path.join(getCacheDir(), 'computer', 'remote');
 }
@@ -249,10 +337,9 @@ function copyFileOverScp(target, remotePath, filePath, timeoutMs = 600_000) {
  */
 export async function setupRemoteHelper(name) {
     const { target } = await resolveRemoteDevice(name);
-    const exe = resolveWinHelperExe();
-    if (!exe) {
-        throw new Error(`Windows helper exe not built. Run: bash scripts/build-win.sh`);
-    }
+    // Local build output, else the checksum-verified GitHub release asset for
+    // this CLI version. Throws naming the tag it checked when neither exists.
+    const exe = await ensureWinHelperExe();
     const prep = sshExec(target, encodePowerShell(buildPushScript()), { timeoutMs: 60_000 });
     if (prep.code !== 0) {
         throw new Error(`preparing helper exe path on '${name}' failed (exit ${prep.code ?? 'null'}): ${prep.stderr.trim() || prep.stdout.trim()}`);

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

@@ -53,4 +53,3 @@ export interface SyncManifest {
     workflows?: Record<string, DirEntry>;
     plugins?: Record<string, PluginEntry>;
 }
-export type ResourceType = 'commands' | 'skills' | 'hooks' | 'mcp' | 'rules' | 'subagents' | 'workflows' | 'plugins' | 'permissions';

package/dist/lib/teams/agents.d.ts

@@ -92,6 +92,21 @@ export interface SignInAdvisory {
  * probe). Never flips the authoritative installed/ready column.
  */
 export declare function resolveSignInAdvisory(installed: boolean, running: boolean, probeSignedIn: boolean): SignInAdvisory;
+/** One row of `agents teams doctor --json` output. */
+export interface TeamsDoctorEntry {
+    installed: boolean;
+    path: string | null;
+    error: string | null;
+    signedIn: boolean | null;
+    running: boolean;
+}
+/**
+ * Collect the same data `agents teams doctor` prints: per-agent install status,
+ * launch health, and advisory sign-in state. Kept in one place so `agents doctor
+ * --devices` can run it locally or compare it against remote JSON without
+ * duplicating the probe logic.
+ */
+export declare function collectTeamsDoctorData(): Promise<Record<string, TeamsDoctorEntry>>;
 /** Resolve and cache the base directory where teammate process data is stored. */
 export declare function getAgentsDir(): Promise<string>;
 /**
@@ -131,6 +146,17 @@ export declare class AgentProcess {
     cloudBranch: string | null;
     worktreeName: string | null;
     worktreePath: string | null;
+    hostName: string | null;
+    hostTarget: string | null;
+    repoPath: string | null;
+    remotePid: number | null;
+    remoteLog: string | null;
+    remoteExit: string | null;
+    remoteLogOffset: number;
+    remotePollSnapshot: {
+        alive: boolean;
+        exit: string | null;
+    } | null;
     private eventsCache;
     private lastReadPos;
     private baseDir;
@@ -175,7 +201,35 @@ export declare class AgentProcess {
      * Falls back to null when none are available.
      */
     private getLatestEventTime;
+    /**
+     * For a distributed (remote-host) teammate, pull NEW bytes of the host's log
+     * into the LOCAL mirror the parser consumes, advance the remote offset, and
+     * resolve terminal status from the remote `.exit` sentinel. Runs BEFORE the
+     * local read in readNewEvents(), so the existing stream-json parse path then
+     * runs unchanged over the freshly-mirrored bytes.
+     *
+     * Uses a per-wave batched snapshot (remotePollSnapshot) when the supervisor's
+     * one-ssh-per-host pre-pass populated it; otherwise falls back to its own
+     * round-trips so a bare `teams status`/`teams logs` is still correct.
+     */
+    private syncRemoteMirror;
     readNewEvents(): Promise<void>;
+    /**
+     * Truncate the local mirror to its trailing REMOTE_MIRROR_MAX_BYTES and reset
+     * lastReadPos to the new (smaller) size so the parser doesn't re-read the kept
+     * tail. Only trims when over the cap — a normal-length log is untouched.
+     */
+    private capMirrorToTail;
+    /** Cap on the in-memory event backlog kept per remote teammate. */
+    private static readonly REMOTE_EVENTS_MAX;
+    /**
+     * Drop the oldest cached events for a remote teammate once past the cap. The
+     * status path only needs recent events (last N messages, recentToolCalls,
+     * terminal status) and the getDelta cursor filters by timestamp, so a bounded
+     * recent window preserves the digest while bounding the heap. Terminal status
+     * is already latched onto `this.status`, so trimming can't lose it.
+     */
+    private capEventsCache;
     saveMeta(): Promise<void>;
     static loadFromDisk(agentId: string, baseDir?: string | null): Promise<AgentProcess | null>;
     isProcessAlive(): boolean;
@@ -246,12 +300,51 @@ export declare class AgentManager {
      */
     rescanFromDisk(): Promise<number>;
     private loadExistingAgents;
-    spawn(taskName: string, agentType: AgentType, prompt: string, cwd?: string | null, mode?: Mode | null, effort?: EffortLevel, parentSessionId?: string | null, workspaceDir?: string | null, version?: string | null, name?: string | null, after?: string[], model?: string | null, envOverrides?: Record<string, string> | null, taskType?: TaskType | null, cloudProvider?: string | null, cloudSessionId?: string | null, cloudRepo?: string | null, cloudBranch?: string | null, worktreeName?: string | null, worktreePath?: string | null, profileName?: string | null): Promise<AgentProcess>;
+    spawn(taskName: string, agentType: AgentType, prompt: string, cwd?: string | null, mode?: Mode | null, effort?: EffortLevel, parentSessionId?: string | null, workspaceDir?: string | null, version?: string | null, name?: string | null, after?: string[], model?: string | null, envOverrides?: Record<string, string> | null, taskType?: TaskType | null, cloudProvider?: string | null, cloudSessionId?: string | null, cloudRepo?: string | null, cloudBranch?: string | null, worktreeName?: string | null, worktreePath?: string | null, profileName?: string | null, hostName?: string | null, hostTarget?: string | null, repoPath?: string | null): Promise<AgentProcess>;
     /**
      * Actually spawn the OS process for a teammate. Extracted from spawn() so
      * staged teammates can be launched later by startReady().
      */
     private launchProcess;
+    /**
+     * Dispatch a distributed teammate onto its host over SSH — the remote-host
+     * analog of launchProcess(). Symmetric to the cloud path: no local process; the
+     * lifecycle lives on the host and is polled (isProcessAlive/readNewEvents over
+     * SSH via the remote `.exit` sentinel + offset-tailed log).
+     *
+     * When the team uses worktrees (agent.worktreeName set), a git worktree is first
+     * created ON THE HOST off the freshly-fetched default branch; the teammate runs
+     * there. Otherwise it runs in the host repo path directly.
+     */
+    private launchRemoteProcess;
+    /**
+     * Resolve a scheduler-picked device to host placement fields on an unpinned
+     * teammate at LAUNCH time (the same resolution `teams add --device` runs, minus
+     * the fatal `die()` — a scheduling failure here is per-teammate, not per-add).
+     * Sets hostName/hostTarget/repoPath + persists, so the subsequent
+     * launchRemoteProcess dispatches over SSH. Mirrors the `add`-time pin path:
+     * resolve device → reject Windows (POSIX-only) → ssh target → ensure the repo
+     * is present on the host from the team's --repo (ensureRemoteRepo).
+     */
+    private resolveScheduledPlacement;
+    /**
+     * Place an UNPINNED, non-cloud teammate onto the team pool via the cascade
+     * (least-loaded), if the team declares one. A no-op for a pinned teammate
+     * (hostName already set from `--device`), a cloud teammate, or a poolless team —
+     * leaving hostName null so the local spawn runs unchanged. Shared by spawn()
+     * (immediate add-launch) and startReady() (staged launch) so an unpinned pool
+     * teammate schedules identically no matter how it was fired.
+     */
+    private maybeSchedulePlacement;
+    /**
+     * One-ssh-per-host batched liveness/exit pre-pass for a team's remote teammates.
+     * The supervisor calls this each wave BEFORE listByTask() so the per-teammate
+     * isProcessAlive()/readNewEvents() consume a cached snapshot instead of each
+     * issuing its own SSH handshake — avoiding N round-trips per wave at 10+ remote
+     * teammates. Groups by hostTarget and, for each host, checks every teammate's
+     * `.exit` + `kill -0` in a single ssh call over the shared ControlMaster socket.
+     */
+    prefetchRemoteStatus(taskName: string): Promise<void>;
     /**
      * Fire any pending teammates in the given team whose `after` deps have all
      * completed. Returns the list of teammates just launched. Repeatable:
@@ -266,6 +359,20 @@ export declare class AgentManager {
      * exec path (src/lib/exec.ts). The team runner just supplies prompt + mode
      * and reads stream-json events off stdout.
      */
+    /**
+     * Build the `agents run …` argv AFTER the `agents` binary — the flags + prompt
+     * scaffolding shared by the LOCAL launch (buildCommand, which prefixes
+     * process.execPath + the agents CLI path) and the REMOTE launch
+     * (launchRemoteProcess, which prefixes `agents` on the host via dispatch). Kept
+     * in one place so the PROMPT_SUFFIX / CLAUDE_PLAN_MODE_PREFIX scaffolding and the
+     * flag set can never drift between the two backends.
+     *
+     * `cwd` is intentionally NOT emitted here: the local path passes it as
+     * `--cwd`/`--add-dir` (below), while the remote path `cd`s into the host cwd
+     * before invoking `agents`. `sessionId` is likewise local-only (the remote run
+     * mints its own session on the host).
+     */
+    private buildRunArgv;
     private buildCommand;
     get(agentId: string): Promise<AgentProcess | null>;
     /**