@phnx-labs/agents-cli 1.20.72 → 1.20.74

package/dist/lib/agents.js

@@ -313,7 +313,9 @@ export const AGENTS = {
         skillsDir: path.join(HOME, '.opencode', 'skills'),
         // Plugins: TS/JS modules auto-loaded from ~/.config/opencode/plugins/ (global)
         // and .opencode/plugins/ (project). Not Claude marketplace format — see
-        // installOpenCodePlugin in plugins.ts. No native shell hooks (plugins only).
+        // installOpenCodePlugin in plugins.ts. OpenCode v1.18.4 exposes lifecycle
+        // hooks through plugin modules (event/tool/etc. functions), not a native
+        // opencode.json shell-command hooks block.
         hooksDir: 'hooks',
         instructionsFile: 'AGENTS.md',
         format: 'markdown',
@@ -341,7 +343,9 @@ export const AGENTS = {
         // tools.alsoAllow (allow) / tools.deny (deny). OpenClaw gates at tool
         // granularity only, so sub-command/path/domain patterns are skipped.
         // OpenClaw is self-updating (no pinned since), so `true` is correct.
-        capabilities: { hooks: true, mcp: true, mcpHttp: false, mcpHeaders: false, allowlist: true, skills: true, commands: false, plugins: true, subagents: true, rules: { file: 'workspace/AGENTS.md' }, workflows: false, memory: true, modes: ['plan', 'edit', 'skip'] },
+        // Workflows sync as Lobster `.lobster` files under `.openclaw/workflows/`;
+        // the Lobster tool runs them by receiving the file path as `pipeline`.
+        capabilities: { hooks: true, mcp: true, mcpHttp: false, mcpHeaders: false, allowlist: true, skills: true, commands: false, plugins: true, subagents: true, rules: { file: 'workspace/AGENTS.md' }, workflows: true, memory: true, modes: ['plan', 'edit', 'skip'] },
     },
     copilot: {
         id: 'copilot',
@@ -366,7 +370,7 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: true,
-        capabilities: { hooks: true, mcp: true, mcpHttp: false, mcpHeaders: false, allowlist: false, skills: true, commands: true, plugins: true, subagents: { since: '0.0.353' }, rules: { file: 'AGENTS.md' }, workflows: false, memory: false, modes: ['plan', 'edit', 'auto', 'skip'] },
+        capabilities: { hooks: true, mcp: true, mcpHttp: false, mcpHeaders: false, allowlist: true, skills: true, commands: true, plugins: true, subagents: { since: '0.0.353' }, rules: { file: 'AGENTS.md' }, workflows: false, memory: false, modes: ['plan', 'edit', 'auto', 'skip'] },
     },
     amp: {
         id: 'amp',
@@ -650,7 +654,11 @@ export const AGENTS = {
             mcp: true,
             mcpHttp: true,
             mcpHeaders: false,
-            allowlist: false,
+            // Permissions: ~/.hermes/config.yaml carries `command_allowlist` for
+            // always-approved command globs and `approvals.deny` for unconditional
+            // command blocks. It is command-glob only; session `/tools` toggles are
+            // intentionally not persisted by agents-cli.
+            allowlist: true,
             skills: true,
             commands: false,
             plugins: true,
@@ -691,7 +699,10 @@ export const AGENTS = {
             mcp: true,
             mcpHttp: true,
             mcpHeaders: false,
-            allowlist: false,
+            // Permissions: ~/.forge/permissions.yaml (or $FORGE_CONFIG/permissions.yaml)
+            // carries ordered operation-family glob policies. It is active only when
+            // `.forge.toml` sets `restricted = true`; MCP tools bypass this file.
+            allowlist: true,
             skills: true,
             commands: true,
             plugins: false,
@@ -849,7 +860,20 @@ export async function getCliState(agentId) {
             }
         }
     }
-    // Non-version-managed: single PATH lookup + cached version read
+    return getUnmanagedCliState(agentId);
+}
+/**
+ * Resolve the agent's OWN install — the one agents-cli does not manage — by plain
+ * PATH lookup, ignoring the version dirs entirely.
+ *
+ * Callers that specifically mean "the user's own globally-installed CLI" must use
+ * this rather than `getCliState`, whose managed fast path reports an installed
+ * version (any version dir, in readdir order) and would therefore hand back an
+ * isolated copy — a copy that is deliberately unreachable from PATH — labelled as
+ * the global install.
+ */
+export async function getUnmanagedCliState(agentId) {
+    const agent = AGENTS[agentId];
     // Special case for grok: it manages its own binaries in ~/.grok/downloads/
     if (agentId === 'grok') {
         const grokBin = resolveGrokBinary();
@@ -1311,6 +1335,48 @@ function isValidOpenCodeCredential(value) {
         default: return false;
     }
 }
+/**
+ * Whether a Claude version home's credential file is present but carries no
+ * token — the "must have a real credential" floor (see
+ * `isValidOpenCodeCredential`) applied to claude.
+ *
+ * A FAILED OAuth refresh leaves exactly this state behind: Claude Code rewrites
+ * `.claude/.credentials.json` with `accessToken: ""`, `refreshToken: ""` and
+ * `expiresAt: 0`, keeping only the descriptive fields (`subscriptionType`,
+ * `rateLimitTier`, `refreshTokenExpiresAt`). Everything we derive from
+ * `.claude.json` — email, plan — still looks healthy, so the install reported
+ * `signedIn: true`, `agents view` drew usage bars for it, and balanced rotation
+ * (whose `authValid` is just "email present") kept picking it — every pick dying
+ * at spawn on "OAuth session expired and could not be refreshed".
+ *
+ * Only decidable off macOS: there the login Keychain is the canonical store and
+ * this file is not authoritative, and probing the Keychain would raise an
+ * authorization sheet per installed version on every `agents run` — the reason
+ * rotation stopped calling `isClaudeAuthValid` at all. Off macOS the file IS the
+ * only store, so a token-less file is proof of signed-out. `platform` is a
+ * parameter so both branches are testable on any host.
+ *
+ * Sync, no Keychain, no network — safe on the `agents run` hot path.
+ */
+export function isClaudeCredentialFileBlank(base, platform = process.platform) {
+    if (platform === 'darwin')
+        return false;
+    try {
+        const raw = fs.readFileSync(path.join(base, '.claude', '.credentials.json'), 'utf-8');
+        const oauth = JSON.parse(raw).claudeAiOauth;
+        if (!oauth)
+            return false;
+        const nonEmpty = (v) => typeof v === 'string' && v.trim().length > 0;
+        return !nonEmpty(oauth.accessToken) && !nonEmpty(oauth.refreshToken);
+    }
+    catch {
+        // No file (a Keychain-backed home, or never logged in here) or an
+        // unreadable/corrupt one: not positive evidence of a blank credential, so
+        // leave the existing signal alone rather than declaring a working install
+        // signed out.
+        return false;
+    }
+}
 export async function getAccountInfo(agentId, home) {
     const base = home || os.homedir();
     const empty = {
@@ -1347,6 +1413,13 @@ export async function getAccountInfo(agentId, home) {
                 const accountId = normalizeIdentityPart(oa?.accountUuid);
                 const organizationId = normalizeIdentityPart(oa?.organizationUuid);
                 const email = oa?.emailAddress || null;
+                // Credential floor: a blanked credential file means this home cannot
+                // authenticate, whatever `.claude.json` still says. Report it signed out
+                // so `agents view` prompts a re-login and rotation routes around it,
+                // instead of handing runs to an install that dies at spawn.
+                if (email && isClaudeCredentialFileBlank(base)) {
+                    return { ...empty, lastActive };
+                }
                 const accountKey = buildIdentityKey(agentId, [
                     ['account', accountId],
                     ['org', organizationId],

package/dist/lib/artifact-actions.d.ts

@@ -1,6 +1,6 @@
 /**
  * Artifact action types and validation.
- * Ported from agents/halo/cli/pkg/config.
+ * Ported from the legacy agent CLI config helpers.
  *
  * Artifact actions map tool invocations to artifact labels, allowing agents to
  * trigger tools automatically when specific artifacts are produced.

package/dist/lib/artifact-actions.js

@@ -1,6 +1,6 @@
 /**
  * Artifact action types and validation.
- * Ported from agents/halo/cli/pkg/config.
+ * Ported from the legacy agent CLI config helpers.
  *
  * Artifact actions map tool invocations to artifact labels, allowing agents to
  * trigger tools automatically when specific artifacts are produced.

package/dist/lib/ask-classifier.d.ts

@@ -50,7 +50,7 @@ export interface SuppressResult {
  * Auto-answer + remove a suppressible block so it never renders as a card.
  * Logs the stall as answered by policy:stall-suppression.
  */
-export declare function suppressStallBlock(block: OpenBlock, root?: string): SuppressResult;
+export declare function suppressStallBlock(block: OpenBlock, root?: string, mailboxRoot?: string): SuppressResult;
 export interface FeedFilterResult {
     /** Blocks that should render as cards. */
     surfaced: OpenBlock[];
@@ -66,6 +66,7 @@ export interface FeedFilterResult {
 export declare function filterBlocksForFeed(blocks: OpenBlock[], opts?: {
     apply?: boolean;
     root?: string;
+    mailboxRoot?: string;
 }): FeedFilterResult;
 /** Human digest: "31 stalls auto-resolved by policy". */
 export declare function suppressionDigest(result: FeedFilterResult): string;

package/dist/lib/ask-classifier.js

@@ -108,7 +108,7 @@ export function classifyBlock(block) {
  * Auto-answer + remove a suppressible block so it never renders as a card.
  * Logs the stall as answered by policy:stall-suppression.
  */
-export function suppressStallBlock(block, root) {
+export function suppressStallBlock(block, root, mailboxRoot) {
     const c = classifyBlock(block);
     if (!c.suppress || !c.autoAnswer) {
         return { blockId: block.blockId, class: c.class, rule: c.rule, autoAnswer: '', suppressed: false };
@@ -124,7 +124,7 @@ export function suppressStallBlock(block, root) {
     }
     try {
         // Mailbox lives under the global mailbox root (not the feed dir).
-        const msgId = enqueue(mailboxDir(block.mailboxId), {
+        const msgId = enqueue(mailboxDir(block.mailboxId, mailboxRoot), {
             to: block.mailboxId,
             text: c.autoAnswer,
             from: 'stall-suppression',
@@ -164,7 +164,7 @@ export function filterBlocksForFeed(blocks, opts) {
         counts[c.class] += 1;
         if (c.suppress) {
             if (apply) {
-                const r = suppressStallBlock(block, opts?.root);
+                const r = suppressStallBlock(block, opts?.root, opts?.mailboxRoot);
                 suppressed.push(r);
                 if (!r.suppressed)
                     surfaced.push(block);

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

@@ -35,18 +35,46 @@ 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;
+    /**
+     * unverified — signed in, but this agent has no in-repo live-probe endpoint
+     * (codex/grok). A benign, neutral state: the account is present and usable, we
+     * just can't complete a 2xx to prove it. It must NOT be lumped with the soft
+     * `warn` bucket, or a fully-logged-in codex/grok fleet reads as half-degraded
+     * (the exact "cry wolf" the ping matrix used to produce).
+     */
+    present: 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.
+     * expired / rate_limited / 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;
+/** A resolved display color; the caller maps it to chalk. Pure, so it's unit-tested. */
+export type AuthCellColor = 'green' | 'yellow' | 'red' | 'gray' | 'dim';
+/**
+ * Color for a single verdict in the per-account (`--verbose`) breakdown. This is
+ * the one source of truth shared with {@link authCellColor} so the matrix and the
+ * account list can never drift — they did: the matrix painted `expired` yellow
+ * while the verbose list painted it *red* (lumped with revoked), directly against
+ * the {@link VerdictSummary} contract. Red is reserved for `revoked` (the only
+ * "re-login now"); `unverified` is a neutral signed-in state (gray);
+ * `expired`/`rate_limited`/`error` are soft (yellow).
+ */
+export declare function verdictColor(verdict: AuthVerdict): AuthCellColor;
+/**
+ * Color for a matrix cell that rolls up several accounts. Red only when a token
+ * was genuinely rejected (`revoked`); yellow for soft/expired; green when at least
+ * one account is live-verified and none are soft/revoked; gray when accounts are
+ * present but unverifiable (codex/grok) — never the alarming yellow the old
+ * renderer used, which made a fully-logged-in fleet read as half-broken.
+ */
+export declare function authCellColor(summary: VerdictSummary): AuthCellColor;
 /** Verdicts that mean "this token was rejected by the server — re-login required". */
 export declare function isDeadVerdict(verdict: AuthVerdict): boolean;
 /**

package/dist/lib/auth-health.js

@@ -82,17 +82,56 @@ export function verdictLabel(verdict) {
 }
 export function summarizeVerdicts(verdicts) {
     let live = 0;
+    let present = 0;
     let bad = 0;
     let warn = 0;
     for (const v of verdicts) {
         if (v === 'live')
             live++;
+        else if (v === 'unverified')
+            present++;
         else if (v === 'revoked')
             bad++;
         else
             warn++;
     }
-    return { live, bad, warn, total: verdicts.length };
+    return { live, present, bad, warn, total: verdicts.length };
+}
+/**
+ * Color for a single verdict in the per-account (`--verbose`) breakdown. This is
+ * the one source of truth shared with {@link authCellColor} so the matrix and the
+ * account list can never drift — they did: the matrix painted `expired` yellow
+ * while the verbose list painted it *red* (lumped with revoked), directly against
+ * the {@link VerdictSummary} contract. Red is reserved for `revoked` (the only
+ * "re-login now"); `unverified` is a neutral signed-in state (gray);
+ * `expired`/`rate_limited`/`error` are soft (yellow).
+ */
+export function verdictColor(verdict) {
+    switch (verdict) {
+        case 'live': return 'green';
+        case 'revoked': return 'red';
+        case 'unverified': return 'gray';
+        case 'unconfigured': return 'dim';
+        default: return 'yellow'; // expired / rate_limited / error — soft, self-healing/indeterminate
+    }
+}
+/**
+ * Color for a matrix cell that rolls up several accounts. Red only when a token
+ * was genuinely rejected (`revoked`); yellow for soft/expired; green when at least
+ * one account is live-verified and none are soft/revoked; gray when accounts are
+ * present but unverifiable (codex/grok) — never the alarming yellow the old
+ * renderer used, which made a fully-logged-in fleet read as half-broken.
+ */
+export function authCellColor(summary) {
+    if (summary.total === 0)
+        return 'dim';
+    if (summary.bad > 0)
+        return 'red';
+    if (summary.warn > 0)
+        return 'yellow';
+    if (summary.live > 0)
+        return 'green';
+    return 'gray'; // all present/unverifiable — signed in, neutral
 }
 /** Verdicts that mean "this token was rejected by the server — re-login required". */
 export function isDeadVerdict(verdict) {

package/dist/lib/auto-pull.js

@@ -38,10 +38,17 @@ export function spawnDetachedSync() {
     if (!fs.existsSync(workerPath))
         return;
     try {
+        // Scrub AGENTS_BRAND so the background sync always reconciles the FULL
+        // resource set into the shared agent homes. Otherwise a branded foreground
+        // invocation (e.g. `jack …`) would leak its curated/reduced profile into the
+        // detached sync and silently strip skills/plugins for the plain `agents`
+        // user (last-writer-wins on shared homes). Brand curation must stay a
+        // foreground, in-process view — never a background mutation of shared state.
+        const { AGENTS_BRAND: _brand, ...unbrandedEnv } = process.env;
         const child = spawn(process.execPath, [workerPath], {
             ...backgroundSpawnOptions(),
             stdio: 'ignore',
-            env: process.env,
+            env: unbrandedEnv,
         });
         child.unref();
     }

package/dist/lib/brand.d.ts

@@ -0,0 +1,40 @@
+import type { BrandConfig } from './types.js';
+/** The default (unbranded) program name. */
+export declare const DEFAULT_CLI_NAME = "agents";
+/**
+ * Resolve the name this invocation runs under. The brand shim exports
+ * `AGENTS_BRAND`; when unset (a normal `agents`/`ag` call) we are unbranded and
+ * everything is byte-identical to before.
+ */
+export declare function resolveBrandName(): string;
+/** The active brand name, or null when unbranded. */
+export declare function activeBrandName(): string | null;
+/** True when this process is running under a brand (not the plain `agents` CLI). */
+export declare function isBranded(): boolean;
+/** Names that would clobber an agent CLI shim or the `agents`/`ag` binary. */
+export declare function reservedBrandNames(): Set<string>;
+/** Validate a proposed brand name; returns an error string or null when ok. */
+export declare function validateBrandName(name: string): string | null;
+/** All configured brands, keyed by name. */
+export declare function listBrands(): Record<string, BrandConfig>;
+/** One brand's config, or undefined. */
+export declare function getBrandConfig(name: string): BrandConfig | undefined;
+/**
+ * The active brand's config (from AGENTS_BRAND), or null when unbranded or when
+ * the brand is explicitly disabled (`enabled: false`) — a disabled brand's shim
+ * still works as a plain pass-through but applies no command/resource curation.
+ */
+export declare function getActiveBrandConfig(): BrandConfig | null;
+/**
+ * The resource-profile preset name a brand pins, or null. Read on the hot path
+ * by resource-profiles.ts to make the active profile brand-scoped.
+ */
+export declare function brandProfileName(): string | null;
+/** Built-in top-level commands the active brand has turned off. */
+export declare function disabledCommandsForActiveBrand(): Set<string>;
+/** The preset name a brand owns (one resource profile per brand). */
+export declare function brandPresetName(name: string): string;
+/** Create or replace a brand's config in agents.yaml. */
+export declare function upsertBrand(cfg: BrandConfig): void;
+/** Remove a brand's config (leaves its resource preset unless `purgePreset`). */
+export declare function removeBrand(name: string, purgePreset?: boolean): void;

package/dist/lib/brand.js

@@ -0,0 +1,122 @@
+/**
+ * Brand ("white-label") support — let a user run agents-cli under their own
+ * personally-named binary (e.g. `jack` instead of `agents`), skinned with their
+ * name and pinned to the exact feature set they enable.
+ *
+ * A brand is minted by `agents setup mine` / `agents mine init <name>`, which
+ * writes a pure pass-through shim (`~/.agents/.cache/shims/<name>`) that sets
+ * `AGENTS_BRAND=<name>` then execs the real agents-cli entrypoint. The entrypoint
+ * reads `AGENTS_BRAND` to (a) present its own name/help/errors as the brand, and
+ * (b) apply the brand's config: a list of disabled built-in commands plus an
+ * optional resource-profile preset that curates skills/plugins/mcp/etc.
+ *
+ * Brand config lives in `meta.brands[<name>]` (agents.yaml), so it rides
+ * `agents repo push/pull` across the fleet like every other user config. The
+ * curated resource set reuses the existing resource-profile engine — a brand
+ * pins a preset name (`meta.profiles.presets[...]`); see resource-profiles.ts,
+ * where the active profile is resolved brand-first.
+ */
+import { readMeta, updateMeta } from './state.js';
+import { ALL_AGENT_IDS, AGENTS } from './agents.js';
+/** The default (unbranded) program name. */
+export const DEFAULT_CLI_NAME = 'agents';
+/** Valid brand names: a letter, then letters/digits/_/- (matches alias rules). */
+const BRAND_NAME_PATTERN = /^[a-zA-Z][a-zA-Z0-9_-]*$/;
+/**
+ * Resolve the name this invocation runs under. The brand shim exports
+ * `AGENTS_BRAND`; when unset (a normal `agents`/`ag` call) we are unbranded and
+ * everything is byte-identical to before.
+ */
+export function resolveBrandName() {
+    const raw = process.env.AGENTS_BRAND?.trim();
+    if (raw && BRAND_NAME_PATTERN.test(raw))
+        return raw;
+    return DEFAULT_CLI_NAME;
+}
+/** The active brand name, or null when unbranded. */
+export function activeBrandName() {
+    const name = resolveBrandName();
+    return name === DEFAULT_CLI_NAME ? null : name;
+}
+/** True when this process is running under a brand (not the plain `agents` CLI). */
+export function isBranded() {
+    return activeBrandName() !== null;
+}
+/** Names that would clobber an agent CLI shim or the `agents`/`ag` binary. */
+export function reservedBrandNames() {
+    const reserved = new Set([DEFAULT_CLI_NAME, 'ag']);
+    for (const id of ALL_AGENT_IDS)
+        reserved.add(AGENTS[id].cliCommand);
+    return reserved;
+}
+/** Validate a proposed brand name; returns an error string or null when ok. */
+export function validateBrandName(name) {
+    if (!BRAND_NAME_PATTERN.test(name)) {
+        return `Invalid name "${name}". Use a letter, then letters, digits, _ or -.`;
+    }
+    if (reservedBrandNames().has(name)) {
+        return `"${name}" is reserved (collides with an agent CLI or the agents binary).`;
+    }
+    return null;
+}
+/** All configured brands, keyed by name. */
+export function listBrands() {
+    return readMeta().brands ?? {};
+}
+/** One brand's config, or undefined. */
+export function getBrandConfig(name) {
+    return listBrands()[name];
+}
+/**
+ * The active brand's config (from AGENTS_BRAND), or null when unbranded or when
+ * the brand is explicitly disabled (`enabled: false`) — a disabled brand's shim
+ * still works as a plain pass-through but applies no command/resource curation.
+ */
+export function getActiveBrandConfig() {
+    const name = activeBrandName();
+    if (!name)
+        return null;
+    const cfg = getBrandConfig(name);
+    if (!cfg || cfg.enabled === false)
+        return null;
+    return cfg;
+}
+/**
+ * The resource-profile preset name a brand pins, or null. Read on the hot path
+ * by resource-profiles.ts to make the active profile brand-scoped.
+ */
+export function brandProfileName() {
+    const cfg = getActiveBrandConfig();
+    return cfg?.profile ?? null;
+}
+/** Built-in top-level commands the active brand has turned off. */
+export function disabledCommandsForActiveBrand() {
+    const cfg = getActiveBrandConfig();
+    return new Set(cfg?.disabledCommands ?? []);
+}
+/** The preset name a brand owns (one resource profile per brand). */
+export function brandPresetName(name) {
+    return `mine-${name}`;
+}
+/** Create or replace a brand's config in agents.yaml. */
+export function upsertBrand(cfg) {
+    updateMeta((meta) => {
+        const brands = { ...(meta.brands ?? {}) };
+        brands[cfg.name] = cfg;
+        return { ...meta, brands };
+    });
+}
+/** Remove a brand's config (leaves its resource preset unless `purgePreset`). */
+export function removeBrand(name, purgePreset = false) {
+    updateMeta((meta) => {
+        const brands = { ...(meta.brands ?? {}) };
+        delete brands[name];
+        let profiles = meta.profiles;
+        if (purgePreset && profiles?.presets) {
+            const presets = { ...profiles.presets };
+            delete presets[brandPresetName(name)];
+            profiles = { ...profiles, presets };
+        }
+        return { ...meta, brands, ...(profiles ? { profiles } : {}) };
+    });
+}

package/dist/lib/browser/drivers/ssh.js

@@ -5,11 +5,8 @@ import { getPortOccupant } from '../chrome.js';
 import { parseEndpointUrl } from '../profiles.js';
 import { writeProfileRuntime, clearProfileRuntime } from '../runtime-state.js';
 // shellQuote lives in the shared ssh-exec helper (single choke point); re-export
-// so existing importers of `shellQuote` from this module keep working. SSH_OPTS
-// is the shared hardened baseline (BatchMode + ConnectTimeout + keepalive) —
-// reuse it so the raw-ssh spawns below fail fast on an unreachable host instead
-// of hanging on the default ~127s TCP timeout, rather than re-listing options.
-import { shellQuote, SSH_OPTS, assertValidSshTarget } from '../../ssh-exec.js';
+// so existing importers of `shellQuote` from this module keep working.
+import { shellQuote, assertValidSshTarget, controlOpts, sshConnectOpts } from '../../ssh-exec.js';
 export { shellQuote };
 // The `ssh -L` tunnel spawn is shared with `agents computer --host`; it lives in
 // the single ssh-tunnel helper. Calling it with no options preserves this
@@ -309,7 +306,7 @@ export async function ensureRemoteBrowser(user, host, browserType, port, remoteO
         // macOS stops at the first non-option, so any `-o` after `user@host` would
         // be swallowed into the remote command instead of applied.
         const child = spawn('ssh', [
-            ...SSH_OPTS,
+            ...sshConnectOpts(controlOpts()),
             `${user}@${host}`,
             remoteCmd,
         ], { stdio: ['ignore', 'ignore', 'pipe'], windowsHide: true });
@@ -384,7 +381,7 @@ function runSSHCommand(user, host, cmd) {
         // host is bounded by ConnectTimeout (the local 3s kill below only bounds a
         // connected-but-slow command, not the connect itself). Options precede the
         // target — see ensureRemoteBrowser.
-        const child = spawn('ssh', [...SSH_OPTS, `${user}@${host}`, cmd], {
+        const child = spawn('ssh', [...sshConnectOpts(controlOpts()), `${user}@${host}`, cmd], {
             stdio: 'ignore',
             windowsHide: true,
         });

package/dist/lib/browser/service.js

@@ -1,8 +1,6 @@
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import { execFile } from 'child_process';
-import { promisify } from 'util';
 import { BrowserCdpConnectionError, CDPClient, discoverBrowserWsUrl, verifyBrowserIdentity, } from './cdp.js';
 import { getProfile, getProfileRuntimeDir, getProfileDownloadsDir, getProfileSessionsDir, getBrowserRuntimeDir, listProfiles, extractConfiguredPort, resolveEndpoint, } from './profiles.js';
 import { killChrome, getRunningChromeInfo, launchBrowser, allocatePort } from './chrome.js';
@@ -16,6 +14,7 @@ import { clickAtCoords, hoverAtCoords, scrollAtCoords, typeText, pressKey, focus
 import { typeEditorText } from './editor.js';
 import { detectUploadPattern, stageUploadFile, uploadToDropTarget, uploadToFileInput, uploadViaFileChooser, } from './upload.js';
 import { emit } from '../events.js';
+import { sshExecAsync } from '../ssh-exec.js';
 function isPathInside(candidate, dir) {
     const rel = path.relative(dir, candidate);
     return rel === '' || (!!rel && !rel.startsWith('..') && !path.isAbsolute(rel));
@@ -149,7 +148,6 @@ export function pickWindowTarget(targets, filter) {
         return visible;
     return pages[0];
 }
-const execFileP = promisify(execFile);
 /**
  * Parse a `--since`/`--until` value. Accepts ISO-8601 absolute timestamps
  * or relative offsets like `30s`, `5m`, `2h`, `1d`.
@@ -166,11 +164,11 @@ export function parseSinceUntil(s) {
     return new Date(Date.now() - n * unitMs[m[2]]);
 }
 async function execSSH(host, cmd) {
-    const { stdout } = await execFileP('ssh', [host, cmd], {
-        timeout: 10_000,
-        maxBuffer: 10_000_000,
-    });
-    return stdout;
+    const res = await sshExecAsync(host, cmd, { timeoutMs: 10_000 });
+    if (res.code !== 0) {
+        throw new Error(`ssh ${host} failed${res.stderr.trim() ? `: ${res.stderr.trim()}` : ''}`);
+    }
+    return res.stdout;
 }
 export function readNewestMatchingRemoteFileCommand(dir, prefix, tailLines) {
     const glob = `${shellQuote(dir)}/${prefix}*.jsonl`;

package/dist/lib/channels/providers/index.d.ts

@@ -0,0 +1,2 @@
+/** Register all built-in providers once (idempotent). */
+export declare function registerBuiltinProviders(): void;

package/dist/lib/channels/providers/index.js

@@ -0,0 +1,20 @@
+/**
+ * Provider barrel — importing this registers every built-in channel provider.
+ * "App" providers register themselves the same way (registerChannelProvider),
+ * so nothing here is privileged over an extension.
+ */
+import { registerChannelProvider } from '../registry.js';
+import { mailboxProvider } from './mailbox.js';
+import { rushProviders } from './rush.js';
+import { openclawTelegramProvider } from './openclaw-telegram.js';
+let registered = false;
+/** Register all built-in providers once (idempotent). */
+export function registerBuiltinProviders() {
+    if (registered)
+        return;
+    registered = true;
+    registerChannelProvider(mailboxProvider);
+    for (const p of rushProviders)
+        registerChannelProvider(p);
+    registerChannelProvider(openclawTelegramProvider);
+}

package/dist/lib/channels/providers/mailbox.d.ts

@@ -0,0 +1,2 @@
+import type { ChannelProvider } from '../registry.js';
+export declare const mailboxProvider: ChannelProvider;

package/dist/lib/channels/providers/mailbox.js

@@ -0,0 +1,26 @@
+/**
+ * Mailbox channel provider — delivers to an agent's file-based mailbox.
+ *
+ * The mailbox is one channel among many. This provider is a thin wrapper over
+ * the same `enqueue` seam that `agents message` uses (commands/message.ts), so
+ * both callers share one spool at ~/.agents/.history/mailbox/<id>/.
+ */
+import { mailboxDir, enqueue, isValidMailboxId } from '../../mailbox.js';
+export const mailboxProvider = {
+    name: 'mailbox',
+    async send(text, opts) {
+        if (!isValidMailboxId(opts.target)) {
+            return { ok: false, channel: 'mailbox', id: opts.target, error: `invalid mailbox id '${opts.target}'` };
+        }
+        if (opts.dryRun) {
+            return { ok: true, channel: 'mailbox', id: opts.target };
+        }
+        try {
+            const msgId = enqueue(mailboxDir(opts.target), { to: opts.target, text, from: opts.from });
+            return { ok: true, channel: 'mailbox', id: opts.target, msgId };
+        }
+        catch (err) {
+            return { ok: false, channel: 'mailbox', id: opts.target, error: err.message };
+        }
+    },
+};

package/dist/lib/channels/providers/openclaw-telegram.d.ts

@@ -0,0 +1,2 @@
+import type { ChannelProvider } from '../registry.js';
+export declare const openclawTelegramProvider: ChannelProvider;