@phnx-labs/agents-cli 1.22.40 → 1.22.42

package/dist/lib/triggers/handlers.js

@@ -208,6 +208,17 @@ export function handlerMatchesWebhook(handler, webhook) {
         return false;
     if (!handlerRunsOnThisDevice(handler))
         return false;
+    // Slack has no GitHub/Linear action/label/branch vocabulary; it matches on the
+    // slash command and (optionally) the channel. `event` already pinned the
+    // subtype (`app_mention`) or the slash command name above.
+    if (webhook.source === 'slack') {
+        const slack = webhook.payload;
+        if (handler.command && slack.command !== handler.command)
+            return false;
+        if (handler.channel && slack.channel !== handler.channel)
+            return false;
+        return true;
+    }
     if (handler.action) {
         const action = webhook.source === 'github' ? githubAction(webhook.payload) : linearAction(webhook.payload);
         if (action !== handler.action)
@@ -262,12 +273,47 @@ export function handlerMatchesWebhook(handler, webhook) {
     }
     return true;
 }
+const asString = (v) => (typeof v === 'string' ? v : '');
+/**
+ * Split a Slack message into a `{{slack.*}}` context. Strips a leading bot
+ * mention (`<@U0BOT> …`), then reads an optional `PROJECT:` prefix — a single
+ * bare token followed by a colon and a space — as the project, with the
+ * remainder the prompt. `AGI: rebase my PR` → project `AGI`, prompt
+ * `rebase my PR`; a message with no such prefix leaves `project` empty and the
+ * whole text as the prompt. The token pattern forbids slashes, so a project
+ * value can never carry a path into a `cwd`/`project` substitution.
+ */
+export function parseSlackMessage(payload) {
+    const cleaned = asString(payload.text).replace(/^\s*<@[^>]+>\s*/, '').trim();
+    const m = /^([A-Za-z0-9][\w.-]*)\s*:\s+([\s\S]+)$/.exec(cleaned);
+    return {
+        text: cleaned,
+        project: m ? m[1] : '',
+        prompt: m ? m[2].trim() : cleaned,
+        channel: asString(payload.channel),
+        thread_ts: asString(payload.thread_ts),
+        user: asString(payload.user),
+        command: asString(payload.command),
+    };
+}
 /**
  * Build the variable-substitution context for a webhook. Linear events expose
  * `issue` and `updatedFrom`; GitHub events expose `repository`, `pull_request`,
- * and `issue`.
+ * and `issue`; Slack events expose the `{{slack.*}}` namespace above.
  */
 export function buildWebhookContext(webhook) {
+    if (webhook.source === 'slack') {
+        // The `{{slack.*}}` namespace rides an intersection over WebhookContext (a
+        // subtype of it) rather than a field on the shared type, so a Slack-only
+        // addition never touches the scheduling hub every routine test depends on.
+        // `substituteWebhookPrompt`/`getPath` read it dynamically at runtime.
+        const ctx = {
+            source: webhook.source,
+            event: webhook.event,
+            slack: parseSlackMessage(webhook.payload),
+        };
+        return ctx;
+    }
     const action = webhook.source === 'github'
         ? githubAction(webhook.payload) ?? undefined
         : linearAction(webhook.payload) ?? undefined;
@@ -306,7 +352,7 @@ function dispatchDefault(config) {
     // Import lazily so the runner module (heavy) is only loaded when a handler
     // actually needs to spawn. Tests inject dispatch functions, so this path is
     // not exercised in unit tests.
-    return import('../runner.js').then((m) => m.executeJobDetached(config));
+    return import('../daemon/runner.js').then((m) => m.executeJobDetached(config));
 }
 /**
  * Execute a handler's action. Runs the configured agent/workflow/command or
@@ -346,6 +392,11 @@ export async function executeHandler(handler, webhook, opts = {}) {
 }
 async function executeHandlerAction(handler, webhook, context, opts) {
     const substitutedPrompt = handler.run?.prompt ? substituteWebhookPrompt(handler.run.prompt, context) : '';
+    // Slack routes the project per-message (`AGI: …`), so a handler may template
+    // its project/cwd — e.g. `project: "{{slack.project}}"`. Substitute + trim; an
+    // empty result omits the field (falls back to the run's default cwd / $HOME).
+    const substitutedProject = handler.project ? substituteWebhookPrompt(handler.project, context).trim() : '';
+    const substitutedCwd = handler.cwd ? substituteWebhookPrompt(handler.cwd, context).trim() : '';
     // Resolved once so a fleet pick can't differ between the two dispatch paths.
     const hostFields = resolveHandlerHost(handler.host);
     if (handler.run?.agent || handler.run?.workflow) {
@@ -359,8 +410,8 @@ async function executeHandlerAction(handler, webhook, context, opts) {
             ...(handler.run.agent ? { agent: handler.run.agent } : { workflow: handler.run.workflow }),
             ...(handler.devices ? { devices: handler.devices } : {}),
             ...(handler.run.env ? { env: handler.run.env } : {}),
-            ...(handler.project ? { project: handler.project } : {}),
-            ...(handler.cwd ? { cwd: handler.cwd } : {}),
+            ...(substitutedProject ? { project: substitutedProject } : {}),
+            ...(substitutedCwd ? { cwd: substitutedCwd } : {}),
             ...(hostFields.host ? { host: hostFields.host } : {}),
             ...(hostFields.hostStrategy ? { hostStrategy: hostFields.hostStrategy } : {}),
         };
@@ -385,8 +436,8 @@ async function executeHandlerAction(handler, webhook, context, opts) {
             ...routine,
             prompt: substituteWebhookPrompt(routine.prompt, context),
             ...(handler.devices ? { devices: handler.devices } : {}),
-            ...(handler.project ? { project: handler.project } : {}),
-            ...(handler.cwd ? { cwd: handler.cwd } : {}),
+            ...(substitutedProject ? { project: substitutedProject } : {}),
+            ...(substitutedCwd ? { cwd: substitutedCwd } : {}),
             ...(handler.mode ? { mode: handler.mode } : {}),
             ...(hostFields.host ? { host: hostFields.host } : {}),
             ...(hostFields.hostStrategy ? { hostStrategy: hostFields.hostStrategy } : {}),

package/dist/lib/triggers/webhook.d.ts

@@ -15,13 +15,15 @@ import * as http from 'http';
 import type { IncomingHttpHeaders } from 'http';
 import type { JobConfig, RunMeta, WebhookContext } from '../scheduling/routines.js';
 import { type FiredHandler } from './handlers.js';
-export type WebhookSource = 'github' | 'linear';
+export type WebhookSource = 'github' | 'linear' | 'slack';
 export interface IncomingWebhook {
     /** Delivery source, derived from `/hooks/<source>` or one-shot command flags. */
     source: WebhookSource;
-    /** Source event name: GitHub header event or Linear payload `type`. */
+    /** Source event name: GitHub header event, Linear payload `type`, or the Slack
+     *  event subtype (`app_mention`) / slash command (`/agents`). */
     event: string;
-    /** Decoded JSON request body. */
+    /** Decoded request body (JSON for GitHub/Linear/Slack-events; the normalized
+     *  {@link SlackPayload} for a Slack slash command's form body). */
     payload: Record<string, unknown>;
 }
 export type GithubWebhook = IncomingWebhook & {
@@ -30,6 +32,9 @@ export type GithubWebhook = IncomingWebhook & {
 export type LinearWebhook = IncomingWebhook & {
     source: 'linear';
 };
+export type SlackWebhook = IncomingWebhook & {
+    source: 'slack';
+};
 /** Read `repository.full_name` (`owner/name`) from a webhook payload, if present. */
 export declare function webhookRepo(payload: Record<string, unknown>): string | null;
 /**
@@ -96,9 +101,59 @@ export declare function fireWebhookJobs(webhook: IncomingWebhook, options?: Fire
 export declare function verifyGithubSignature(headers: IncomingHttpHeaders, rawBody: Buffer, secret: string): boolean;
 export declare function verifyLinearSignature(headers: IncomingHttpHeaders, rawBody: Buffer, secret: string): boolean;
 export declare function verifyLinearTimestamp(payload: Record<string, unknown>, now?: number, toleranceMs?: number): boolean;
+/**
+ * Verify a Slack request signature (the `v0` scheme). Slack signs the base
+ * string `v0:${timestamp}:${rawBody}` with the app's signing secret and sends
+ * the hex digest as `X-Slack-Signature: v0=<hex>`, alongside the unix
+ * `X-Slack-Request-Timestamp`. The timestamp is BOTH part of the signed base
+ * string AND checked for freshness here — a request older than `toleranceSec`
+ * (default 5 min) is rejected, so a captured, correctly-signed body cannot be
+ * replayed later. Fails closed on any missing/malformed header.
+ */
+export declare function verifySlackSignature(headers: IncomingHttpHeaders, rawBody: Buffer, secret: string, now?: number, toleranceSec?: number): boolean;
+/**
+ * Normalized fields extracted from a Slack slash-command or Events API delivery.
+ * This is the `payload` of a Slack {@link IncomingWebhook}: transport-level
+ * parsing lives here, message *semantics* (splitting the mention text into an
+ * agent / project / prompt) live in `handlers.ts` `buildWebhookContext`.
+ */
+export interface SlackPayload extends Record<string, unknown> {
+    /** `url_verification` | `event_callback` | `slash_command`. */
+    type: string;
+    /** Echoed back for the one-time Events API URL-verification handshake. */
+    challenge?: string;
+    /** Slack event id (Events API) — the dedup key when present. */
+    event_id?: string;
+    /** Event subtype, e.g. `app_mention` (Events API). */
+    event_type?: string;
+    /** Raw message text (the mention body, or the slash-command text). */
+    text?: string;
+    /** Channel id (`C0…`) the message arrived in. */
+    channel?: string;
+    /** Thread to reply into: an existing thread's parent ts, else the message ts. */
+    thread_ts?: string;
+    /** Invoking user id (`U0…`). */
+    user?: string;
+    /** Slash command name, e.g. `/agents`. */
+    command?: string;
+    /** Slash-command `response_url` (valid ~30 min, 5 uses). */
+    response_url?: string;
+    /** Slack team / workspace id. */
+    team?: string;
+}
+/**
+ * Parse a Slack delivery body into a normalized {@link SlackPayload}. Slack
+ * sends slash commands as `application/x-www-form-urlencoded` and Events API
+ * deliveries (including the `url_verification` handshake) as
+ * `application/json` — this is the one place that content-type branch lives.
+ */
+export declare function parseSlackBody(contentType: string | undefined, rawBody: Buffer): SlackPayload;
+/** The `event` name a Slack delivery fires under: the slash command, or the event subtype. */
+export declare function slackEventName(payload: SlackPayload): string;
 export interface WebhookSecrets {
     github?: string;
     linear?: string;
+    slack?: string;
 }
 export interface DeliveryStore {
     seen(id: string): boolean;
@@ -140,11 +195,25 @@ export interface WebhookServerOptions {
     secrets: WebhookSecrets;
     /** Override the fire options (mainly for tests). */
     fire?: FireWebhookOptions;
+    /**
+     * Called the moment a delivery's matches are known — BEFORE any routine or
+     * handler is dispatched. Matching is a pure, synchronous lookup (no I/O), so
+     * this fires immediately after the ack, regardless of how long the matched
+     * work then takes to run. This is the right hook for a "webhook X fired Y"
+     * log line: a `run.command` handler that shells out a long agent session
+     * (`exec()`, which only resolves on process exit) used to hold that log back
+     * for as long as the session ran — `ps` would show the agent already running
+     * while the log still implied nothing had matched (RUSH-2722). Names only
+     * (no runId/exitCode yet — those aren't known until dispatch settles).
+     */
+    onMatch?: (webhook: IncomingWebhook, matchedJobNames: string[], matchedHandlerNames: string[]) => void;
     /**
      * Called after a delivery has fully settled — every matched routine and
-     * handler dispatched. Because the receiver acks the HTTP response BEFORE
-     * dispatch (see `startWebhookServer`), this fires strictly after the response
-     * has been written, and is the only way a caller observes the outcome.
+     * handler dispatched (and, for `run.command` handlers, exited). Because the
+     * receiver acks the HTTP response BEFORE dispatch (see `startWebhookServer`),
+     * this fires strictly after the response has been written, and is the only
+     * way a caller observes the dispatch outcome (runId/exitCode/output). It is
+     * NOT the right hook for "did this webhook match" logging — use `onMatch`.
      */
     onDelivery?: (webhook: IncomingWebhook, fired: FiredJob[], handlers: FiredHandler[]) => void;
     /**
@@ -183,6 +252,11 @@ export interface WebhookServerOptions {
  * duplicate from an in-flight set, since `deliveryStore.seen` only reports
  * completed deliveries and would otherwise let a mid-flight retry double-fire.
  *
+ * `onMatch` fires as soon as matching is known, before any dispatch; `onDelivery`
+ * fires only once every matched routine/handler has settled — see their docs on
+ * `WebhookServerOptions`. A caller that wants a prompt "this fired" log uses
+ * `onMatch`, not `onDelivery` (RUSH-2722).
+ *
  * Returns the underlying server so callers can `close()` it.
  */
 export declare function startWebhookServer(options: WebhookServerOptions): http.Server;

package/dist/lib/triggers/webhook.js

@@ -16,7 +16,7 @@ import * as fs from 'fs';
 import * as http from 'http';
 import * as path from 'path';
 import { jobRunsOnThisDevice, listJobs, substituteWebhookPrompt } from '../scheduling/routines.js';
-import { executeJobDetached } from '../runner.js';
+import { executeJobDetached } from '../daemon/runner.js';
 import { emit } from '../feed/events.js';
 import { listHandlers, handlerMatchesWebhook, executeHandler, buildWebhookContext, } from './handlers.js';
 /** Read `repository.full_name` (`owner/name`) from a webhook payload, if present. */
@@ -264,6 +264,76 @@ export function verifyLinearTimestamp(payload, now = Date.now(), toleranceMs = 6
     const ts = payload.webhookTimestamp;
     return typeof ts === 'number' && Math.abs(now - ts) <= toleranceMs;
 }
+/**
+ * Verify a Slack request signature (the `v0` scheme). Slack signs the base
+ * string `v0:${timestamp}:${rawBody}` with the app's signing secret and sends
+ * the hex digest as `X-Slack-Signature: v0=<hex>`, alongside the unix
+ * `X-Slack-Request-Timestamp`. The timestamp is BOTH part of the signed base
+ * string AND checked for freshness here — a request older than `toleranceSec`
+ * (default 5 min) is rejected, so a captured, correctly-signed body cannot be
+ * replayed later. Fails closed on any missing/malformed header.
+ */
+export function verifySlackSignature(headers, rawBody, secret, now = Date.now(), toleranceSec = 300) {
+    const ts = header(headers, 'x-slack-request-timestamp');
+    if (!ts || !/^\d+$/.test(ts))
+        return false;
+    if (Math.abs(Math.floor(now / 1000) - Number(ts)) > toleranceSec)
+        return false;
+    const received = header(headers, 'x-slack-signature');
+    const signature = received?.startsWith('v0=') ? received.slice('v0='.length) : undefined;
+    // Concatenate the base-string prefix with the raw body bytes so a non-ASCII
+    // payload hashes identically to Slack's own `v0:${ts}:${body}` string.
+    const base = Buffer.concat([Buffer.from(`v0:${ts}:`, 'utf-8'), rawBody]);
+    const expected = crypto.createHmac('sha256', secret).update(base).digest('hex');
+    return timingSafeHexEqual(signature, expected);
+}
+/**
+ * Parse a Slack delivery body into a normalized {@link SlackPayload}. Slack
+ * sends slash commands as `application/x-www-form-urlencoded` and Events API
+ * deliveries (including the `url_verification` handshake) as
+ * `application/json` — this is the one place that content-type branch lives.
+ */
+export function parseSlackBody(contentType, rawBody) {
+    if ((contentType ?? '').includes('application/x-www-form-urlencoded')) {
+        const form = new URLSearchParams(rawBody.toString('utf-8'));
+        // A slash command carries no thread; its reply posts to the channel.
+        return {
+            type: 'slash_command',
+            command: form.get('command') ?? undefined,
+            text: form.get('text') ?? undefined,
+            channel: form.get('channel_id') ?? undefined,
+            user: form.get('user_id') ?? undefined,
+            response_url: form.get('response_url') ?? undefined,
+            team: form.get('team_id') ?? undefined,
+        };
+    }
+    const json = rawBody.length > 0 ? JSON.parse(rawBody.toString('utf-8')) : {};
+    const type = String(json.type ?? '');
+    if (type === 'url_verification') {
+        return { type, challenge: typeof json.challenge === 'string' ? json.challenge : '' };
+    }
+    const event = (json.event ?? {});
+    return {
+        type: type || 'event_callback',
+        event_id: typeof json.event_id === 'string' ? json.event_id : undefined,
+        event_type: typeof event.type === 'string' ? event.type : undefined,
+        text: typeof event.text === 'string' ? event.text : undefined,
+        channel: typeof event.channel === 'string' ? event.channel : undefined,
+        thread_ts: typeof event.thread_ts === 'string'
+            ? event.thread_ts
+            : typeof event.ts === 'string'
+                ? event.ts
+                : undefined,
+        user: typeof event.user === 'string' ? event.user : undefined,
+        team: typeof json.team_id === 'string' ? json.team_id : undefined,
+    };
+}
+/** The `event` name a Slack delivery fires under: the slash command, or the event subtype. */
+export function slackEventName(payload) {
+    if (payload.type === 'slash_command')
+        return payload.command ?? 'slash_command';
+    return payload.event_type ?? payload.type;
+}
 export function createMemoryDeliveryStore(maxEntries = 1000) {
     const seen = new Map();
     const touch = (id) => {
@@ -405,7 +475,7 @@ function deliveryId(source, headers, rawBody) {
     return `${source}:${named ?? crypto.createHash('sha256').update(rawBody).digest('hex')}`;
 }
 function sourceFromPath(pathname) {
-    const match = /^\/hooks\/(github|linear)\/?$/.exec(pathname ?? '');
+    const match = /^\/hooks\/(github|linear|slack)\/?$/.exec(pathname ?? '');
     return match ? match[1] : null;
 }
 async function readRawBody(req, maxBytes) {
@@ -461,6 +531,11 @@ export function waitForListening(server) {
  * duplicate from an in-flight set, since `deliveryStore.seen` only reports
  * completed deliveries and would otherwise let a mid-flight retry double-fire.
  *
+ * `onMatch` fires as soon as matching is known, before any dispatch; `onDelivery`
+ * fires only once every matched routine/handler has settled — see their docs on
+ * `WebhookServerOptions`. A caller that wants a prompt "this fired" log uses
+ * `onMatch`, not `onDelivery` (RUSH-2722).
+ *
  * Returns the underlying server so callers can `close()` it.
  */
 export function startWebhookServer(options) {
@@ -482,8 +557,17 @@ export function startWebhookServer(options) {
         try {
             const context = buildWebhookContext(webhook);
             const fireOptions = options.fire ?? {};
+            // Match FIRST, before any dispatch — matching is a pure in-memory lookup,
+            // so this is the earliest point the receiver knows what fired, and the
+            // right time to log it (RUSH-2722). Dispatching a `run.command` handler
+            // can then block on the shelled-out process for minutes; that must never
+            // hold the "fired" log back with it.
+            const matchedJobs = matchJobsToWebhook(fireOptions.jobs ?? listJobs(), webhook);
+            const matchedHandlers = listHandlers().filter((handler) => handlerMatchesWebhook(handler, webhook));
+            options.onMatch?.(webhook, matchedJobs.map((job) => job.name), matchedHandlers.map((handler) => handler.name));
             const firedJobs = await fireWebhookJobs(webhook, {
                 ...fireOptions,
+                jobs: matchedJobs,
                 context,
                 skipJobNames: deliveryStore.completedJobs(id),
                 onJobFired: (job, firedJob) => {
@@ -492,7 +576,6 @@ export function startWebhookServer(options) {
                     fireOptions.onJobFired?.(job, firedJob);
                 },
             });
-            const matchedHandlers = listHandlers().filter((handler) => handlerMatchesWebhook(handler, webhook));
             const firedHandlers = [];
             const handlerErrors = [];
             await Promise.allSettled(matchedHandlers.map(async (handler) => {
@@ -563,13 +646,54 @@ export function startWebhookServer(options) {
                 const rawBody = await readRawBody(req, maxBodyBytes);
                 const valid = source === 'github'
                     ? verifyGithubSignature(req.headers, rawBody, secret)
-                    : verifyLinearSignature(req.headers, rawBody, secret);
+                    : source === 'linear'
+                        ? verifyLinearSignature(req.headers, rawBody, secret)
+                        : verifySlackSignature(req.headers, rawBody, secret);
                 if (!valid) {
                     emit('webhook.rejected', { source, reason: 'invalid signature' });
                     res.writeHead(401, { 'content-type': 'application/json' });
                     res.end(JSON.stringify({ ok: false, error: 'invalid signature' }));
                     return;
                 }
+                // Slack diverges from the GitHub/Linear JSON path: two content-types
+                // (slash = form, events = JSON), a one-time url_verification handshake,
+                // a body-carried event id, and a 200 ack Slack shows to the caller.
+                if (source === 'slack') {
+                    const slack = parseSlackBody(header(req.headers, 'content-type'), rawBody);
+                    // One-time Events API URL handshake: echo the challenge, dispatch nothing.
+                    if (slack.type === 'url_verification') {
+                        res.writeHead(200, { 'content-type': 'application/json' });
+                        res.end(JSON.stringify({ challenge: slack.challenge ?? '' }));
+                        return;
+                    }
+                    const slackEvent = slackEventName(slack);
+                    // Slash commands carry no event_id, so fall back to a body hash for dedup.
+                    const slackId = `slack:${slack.event_id ?? crypto.createHash('sha256').update(rawBody).digest('hex')}`;
+                    emit('webhook.received', { source, event: slackEvent, deliveryId: slackId });
+                    if (deliveryStore.seen(slackId) || inFlight.has(slackId)) {
+                        res.writeHead(200, { 'content-type': 'application/json' });
+                        res.end(JSON.stringify({ ok: true, duplicate: true }));
+                        return;
+                    }
+                    if (!rateLimiter.take(source)) {
+                        emit('webhook.rejected', { source, event: slackEvent, deliveryId: slackId, reason: 'rate limit exceeded' });
+                        res.writeHead(429, { 'content-type': 'application/json' });
+                        res.end(JSON.stringify({ ok: false, error: 'rate limit exceeded' }));
+                        return;
+                    }
+                    const slackWebhook = { source, event: slackEvent, payload: slack };
+                    emit('webhook.authorized', { source, event: slackEvent, deliveryId: slackId });
+                    // ACK FIRST (RUSH-2548): a 200 inside Slack's 3s window. A slash
+                    // command renders the ack text to the caller; an event delivery
+                    // ignores the body. Dispatch outlives the ack, same as GitHub/Linear.
+                    inFlight.add(slackId);
+                    res.writeHead(200, { 'content-type': 'application/json' });
+                    res.end(slack.type === 'slash_command'
+                        ? JSON.stringify({ response_type: 'ephemeral', text: 'On it — replying in this thread.' })
+                        : '');
+                    void settleDelivery(slackWebhook, slackId).finally(() => inFlight.delete(slackId));
+                    return;
+                }
                 const id = deliveryId(source, req.headers, rawBody);
                 const event = source === 'github' ? (header(req.headers, 'x-github-event') ?? '') : '';
                 emit('webhook.received', { source, event, deliveryId: id });

package/dist/lib/types.d.ts

@@ -1110,7 +1110,7 @@ export interface HostEntry {
 /** Browser profile definition stored in agents.yaml. */
 export interface BrowserProfileConfig {
     description?: string;
-    browser: 'chrome' | 'comet' | 'chromium' | 'brave' | 'edge' | 'custom';
+    browser: 'chrome' | 'comet' | 'chromium' | 'brave' | 'edge' | 'arc' | 'custom';
     binary?: string;
     electron?: boolean;
     /**

package/dist/lib/uninstall.js

@@ -19,7 +19,7 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { AGENTS, ALL_AGENT_IDS } from './agents.js';
-import { getAgentConfigPath, getConfigSymlinkVersion, stripShimPathLines, releaseAdoptedLauncher, } from './shims.js';
+import { getAgentConfigPath, getConfigSymlinkVersion, stripShimPathLines, releaseAdoptedLauncher, } from './installations/shims.js';
 import { moveDirCrossDevice, copyDirStrippingAgentsSymlinks } from './config-transfer.js';
 import { getUserAgentsDir, getBackupsDir, getHistoryDir, getShimsDir, getLegacySystemAgentsDir, } from './state.js';
 /** Home dir honoring the AGENTS_REAL_HOME test/override, mirroring shims.ts. */

package/dist/lib/version.d.ts

@@ -43,8 +43,15 @@ export declare function resolveInstalledLayout(): InstallLayout | null;
  * binary can't read its own bundled package.json), fall back to the on-disk
  * install found via the launcher symlink so callers like the menu bar don't see
  * a bogus `unknown`.
+ *
+ * `pkgJsonPath` is an optional override of the shipping package.json path,
+ * accepted by both this function and {@link getCliVersionFresh}. Every
+ * production call site uses the zero-argument form and gets the real on-disk
+ * path below; the parameter exists only so a unit test can point both
+ * functions at a fixture package.json instead of the real one shared by every
+ * parallel test fork.
  */
-export declare function getCliVersion(): string;
+export declare function getCliVersion(pkgJsonPath?: string): string;
 /**
  * Read the version from package.json on disk every call, bypassing the cache.
  *
@@ -55,4 +62,4 @@ export declare function getCliVersion(): string;
  * is now stale and should reload onto the new code (self-healing). Returns
  * 'unknown' on any error.
  */
-export declare function getCliVersionFresh(): string;
+export declare function getCliVersionFresh(pkgJsonPath?: string): string;

package/dist/lib/version.js

@@ -91,14 +91,18 @@ export function resolveInstalledLayout() {
  * binary can't read its own bundled package.json), fall back to the on-disk
  * install found via the launcher symlink so callers like the menu bar don't see
  * a bogus `unknown`.
+ *
+ * `pkgJsonPath` is an optional override of the shipping package.json path,
+ * accepted by both this function and {@link getCliVersionFresh}. Every
+ * production call site uses the zero-argument form and gets the real on-disk
+ * path below; the parameter exists only so a unit test can point both
+ * functions at a fixture package.json instead of the real one shared by every
+ * parallel test fork.
  */
-export function getCliVersion() {
+export function getCliVersion(pkgJsonPath = path.join(__dirname, '..', '..', 'package.json')) {
     if (cached)
         return cached;
-    cached =
-        readVersionAt(path.join(__dirname, '..', '..', 'package.json')) ??
-            readInstalledPackageVersion() ??
-            'unknown';
+    cached = readVersionAt(pkgJsonPath) ?? readInstalledPackageVersion() ?? 'unknown';
     return cached;
 }
 /** Version from the on-disk install (Bun-binary fallback). */
@@ -116,8 +120,6 @@ function readInstalledPackageVersion() {
  * is now stale and should reload onto the new code (self-healing). Returns
  * 'unknown' on any error.
  */
-export function getCliVersionFresh() {
-    return (readVersionAt(path.join(__dirname, '..', '..', 'package.json')) ??
-        readInstalledPackageVersion() ??
-        'unknown');
+export function getCliVersionFresh(pkgJsonPath = path.join(__dirname, '..', '..', 'package.json')) {
+    return readVersionAt(pkgJsonPath) ?? readInstalledPackageVersion() ?? 'unknown';
 }

package/dist/lib/wrap.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Terminal word-wrap — one shared helper for the whole CLI.
+ *
+ * Multi-line word wrapping is the gap the single-line helpers in
+ * `session/width.ts` (`truncateToWidth`, `padToWidth`) do not fill. Anywhere that
+ * renders variable-length text into a fixed-width terminal wraps through THIS,
+ * never a per-field slice.
+ *
+ * Width is measured with `stringWidth` (from the canonical `session/width.ts`),
+ * NOT `String.length`: the text this wraps is routinely ANSI-coloured (chalk /
+ * marked-terminal output) and may carry OSC-8 hyperlinks, where `.length`
+ * over-counts the invisible escape bytes. Words are split on whitespace, so a
+ * wrap boundary always falls between escape sequences, never inside one.
+ */
+/**
+ * Hard-wrap `text` to `cols` visible columns.
+ *
+ * - Splits on existing newlines first (each paragraph wraps independently).
+ * - Wraps on whitespace; a single word wider than the available width is emitted
+ *   on its own line rather than split mid-word (and never mid-escape).
+ * - Width is the visible display width via `stringWidth`, so ANSI colour and
+ *   OSC-8 hyperlink escapes do not inflate the count.
+ * - `hangingIndent` pads every line AFTER the first with that many spaces, so a
+ *   labelled value ("Latest  <text>") keeps its continuation lines aligned under
+ *   the value. The wrapping width is `cols - indent`.
+ * - Floor: when `hangingIndent` is set, the width is floored at 8 so a
+ *   pathologically large indent still makes forward progress. With no indent the
+ *   floor is 1, so a legitimately small `cols` is respected, never overridden. A
+ *   non-finite `cols` degrades to the floor rather than silently disabling wrap.
+ *
+ * Returns the wrapped lines (never mutates input). An empty string yields [''].
+ */
+export declare function wrapToWidth(text: string, cols: number, hangingIndent?: number): string[];

package/dist/lib/wrap.js

@@ -0,0 +1,70 @@
+/**
+ * Terminal word-wrap — one shared helper for the whole CLI.
+ *
+ * Multi-line word wrapping is the gap the single-line helpers in
+ * `session/width.ts` (`truncateToWidth`, `padToWidth`) do not fill. Anywhere that
+ * renders variable-length text into a fixed-width terminal wraps through THIS,
+ * never a per-field slice.
+ *
+ * Width is measured with `stringWidth` (from the canonical `session/width.ts`),
+ * NOT `String.length`: the text this wraps is routinely ANSI-coloured (chalk /
+ * marked-terminal output) and may carry OSC-8 hyperlinks, where `.length`
+ * over-counts the invisible escape bytes. Words are split on whitespace, so a
+ * wrap boundary always falls between escape sequences, never inside one.
+ */
+import { stringWidth } from './session/width.js';
+/**
+ * Hard-wrap `text` to `cols` visible columns.
+ *
+ * - Splits on existing newlines first (each paragraph wraps independently).
+ * - Wraps on whitespace; a single word wider than the available width is emitted
+ *   on its own line rather than split mid-word (and never mid-escape).
+ * - Width is the visible display width via `stringWidth`, so ANSI colour and
+ *   OSC-8 hyperlink escapes do not inflate the count.
+ * - `hangingIndent` pads every line AFTER the first with that many spaces, so a
+ *   labelled value ("Latest  <text>") keeps its continuation lines aligned under
+ *   the value. The wrapping width is `cols - indent`.
+ * - Floor: when `hangingIndent` is set, the width is floored at 8 so a
+ *   pathologically large indent still makes forward progress. With no indent the
+ *   floor is 1, so a legitimately small `cols` is respected, never overridden. A
+ *   non-finite `cols` degrades to the floor rather than silently disabling wrap.
+ *
+ * Returns the wrapped lines (never mutates input). An empty string yields [''].
+ */
+export function wrapToWidth(text, cols, hangingIndent = 0) {
+    const indent = Math.max(0, Math.trunc(hangingIndent));
+    const floor = indent > 0 ? 8 : 1;
+    const width = Number.isFinite(cols) ? Math.max(floor, cols - indent) : floor;
+    const pad = ' '.repeat(indent);
+    const out = [];
+    for (const para of String(text).split('\n')) {
+        const words = para.split(/\s+/).filter(w => w.length > 0);
+        if (words.length === 0) {
+            out.push('');
+            continue;
+        }
+        let line = '';
+        let lineWidth = 0;
+        for (const word of words) {
+            const wordWidth = stringWidth(word);
+            if (line === '') {
+                line = word;
+                lineWidth = wordWidth;
+            }
+            else if (lineWidth + 1 + wordWidth > width) {
+                out.push(line);
+                line = word;
+                lineWidth = wordWidth;
+            }
+            else {
+                line = `${line} ${word}`;
+                lineWidth += 1 + wordWidth;
+            }
+        }
+        if (line !== '')
+            out.push(line);
+    }
+    if (out.length === 0)
+        out.push('');
+    return out.map((l, i) => (i === 0 ? l : pad + l));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.22.40",
+  "version": "1.22.42",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",