@phnx-labs/agents-cli 1.20.34 → 1.20.35

package/dist/lib/terminal/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Terminal launch engine — open an interactive command as a tab or split pane
+ * in iTerm / Ghostty / tmux, on this machine or a remote host.
+ *
+ * Public entry point. Callers typically use `openSurfaces` (a batch with a
+ * layout policy) or `openSurface` (a single request), and `availableBackends` /
+ * `detectCurrentBackend` to pick a target. See docs/terminal-engine.md.
+ */
+export type { Backend, SplitDirection, Layout, EngineContext, LaunchSpec, LaunchRequest, LaunchResult, TerminalBackend, } from './types.js';
+export { currentContext } from './types.js';
+export { BACKENDS, detectCurrentBackend, availableBackends, itermBackend, ghosttyBackend, tmuxBackend } from './backends/index.js';
+export { planLayouts, type Packing } from './policy.js';
+export { specForRequest, buildRequests, openSurface, openSurfaces, type OpenOptions, type OpenManyOptions, type BuildRequestsOptions, type SurfaceItem, } from './engine.js';
+export { runLocal, runRemote, runSpec, remoteCommand, type HostResolver, type RunResult } from './transport.js';

package/dist/lib/terminal/index.js

@@ -0,0 +1,5 @@
+export { currentContext } from './types.js';
+export { BACKENDS, detectCurrentBackend, availableBackends, itermBackend, ghosttyBackend, tmuxBackend } from './backends/index.js';
+export { planLayouts } from './policy.js';
+export { specForRequest, buildRequests, openSurface, openSurfaces, } from './engine.js';
+export { runLocal, runRemote, runSpec, remoteCommand } from './transport.js';

package/dist/lib/terminal/policy.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Layout policy — how a batch of surfaces is arranged.
+ *
+ * `two-per-tab` (default) packs sessions two-up: session 1 opens a new tab,
+ * session 2 splits it (right), session 3 opens a new tab, and so on — so each
+ * tab holds a left+right pair. `tabs` gives every session its own tab.
+ */
+import type { Layout } from './types.js';
+export type Packing = 'two-per-tab' | 'tabs';
+/** Assign a layout to each index in a batch of `count` surfaces. */
+export declare function planLayouts(count: number, packing?: Packing): Layout[];

package/dist/lib/terminal/policy.js

@@ -0,0 +1,11 @@
+/** Assign a layout to each index in a batch of `count` surfaces. */
+export function planLayouts(count, packing = 'two-per-tab') {
+    const out = [];
+    for (let i = 0; i < count; i++) {
+        if (packing === 'tabs')
+            out.push('tab');
+        else
+            out.push(i % 2 === 0 ? 'tab' : 'split-right');
+    }
+    return out;
+}

package/dist/lib/terminal/quote.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Quoting helpers for building launch commands.
+ *
+ * `shellQuote` is the single canonical POSIX single-quoter, re-exported from the
+ * SSH transport so the local and remote legs quote identically. `appleScriptStr`
+ * is the AppleScript string-literal escaper used by the iTerm/Ghostty backends.
+ */
+import { shellQuote } from '../ssh-exec.js';
+export { shellQuote };
+/** AppleScript double-quoted string literal (escape backslash, then quote). */
+export declare function appleScriptStr(s: string): string;

package/dist/lib/terminal/quote.js

@@ -0,0 +1,13 @@
+/**
+ * Quoting helpers for building launch commands.
+ *
+ * `shellQuote` is the single canonical POSIX single-quoter, re-exported from the
+ * SSH transport so the local and remote legs quote identically. `appleScriptStr`
+ * is the AppleScript string-literal escaper used by the iTerm/Ghostty backends.
+ */
+import { shellQuote } from '../ssh-exec.js';
+export { shellQuote };
+/** AppleScript double-quoted string literal (escape backslash, then quote). */
+export function appleScriptStr(s) {
+    return `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}

package/dist/lib/terminal/shell.d.ts

@@ -0,0 +1,6 @@
+/** `cd <cwd> && exec <command>` — for backends that don't set cwd natively. */
+export declare function loginExec(cwd: string, command: string[]): string;
+/** `exec <command>` — for backends that set the working directory natively. */
+export declare function execOnly(command: string[]): string;
+/** Wrap an inner shell script in an interactive login zsh: `zsh -ilc '<inner>'`. */
+export declare function iLoginShell(inner: string): string;

package/dist/lib/terminal/shell.js

@@ -0,0 +1,23 @@
+/**
+ * Interactive-login-shell wrappers shared by every backend.
+ *
+ * `-i` is load-bearing, not cosmetic: the version-pinned shims (e.g.
+ * `claude@2.1.187`) live in `~/.agents/.cache/shims`, which `.zshrc` puts on
+ * PATH for *interactive* shells only. A plain `zsh -lc` (login, non-interactive)
+ * skips `.zshrc`, so the shim isn't found and the surface dies with "command not
+ * found". Every backend wraps its command in `zsh -ilc` for this reason — do not
+ * drop the `-i`.
+ */
+import { shellQuote } from './quote.js';
+/** `cd <cwd> && exec <command>` — for backends that don't set cwd natively. */
+export function loginExec(cwd, command) {
+    return `cd ${shellQuote(cwd)} && exec ${command.join(' ')}`;
+}
+/** `exec <command>` — for backends that set the working directory natively. */
+export function execOnly(command) {
+    return `exec ${command.join(' ')}`;
+}
+/** Wrap an inner shell script in an interactive login zsh: `zsh -ilc '<inner>'`. */
+export function iLoginShell(inner) {
+    return `zsh -ilc ${shellQuote(inner)}`;
+}

package/dist/lib/terminal/transport.d.ts

@@ -0,0 +1,15 @@
+import type { LaunchSpec } from './types.js';
+/** Resolve a host alias to an ssh target. Default: identity (ssh_config resolves it). */
+export type HostResolver = (alias: string) => string;
+export interface RunResult {
+    ok: boolean;
+    error?: string;
+}
+/** Run the spec on this machine: spawn the launcher, resolve when it exits. */
+export declare function runLocal(spec: LaunchSpec): Promise<RunResult>;
+/** Serialize a launch argv into a single POSIX-quoted shell command string. */
+export declare function remoteCommand(spec: LaunchSpec): string;
+/** Run the spec on a remote host over SSH. */
+export declare function runRemote(spec: LaunchSpec, target: string): RunResult;
+/** Run a spec locally (no host / 'local') or on a resolved remote host. */
+export declare function runSpec(spec: LaunchSpec, host?: string, resolveHost?: HostResolver): Promise<RunResult>;

package/dist/lib/terminal/transport.js

@@ -0,0 +1,40 @@
+/**
+ * Transport — runs a LaunchSpec locally or on a remote host.
+ *
+ * Local: spawn the launcher (osascript / tmux) and wait for it to exit — these
+ * are short-lived commands that create the surface and return, so waiting gives
+ * a real success/failure. Remote: serialize the argv into one shell string and
+ * hand it to `sshExec` — the same hardened SSH primitive `agents sessions
+ * --host` and the browser driver use (target-injection guard, POSIX quoting,
+ * connection multiplexing).
+ */
+import { spawn } from 'child_process';
+import { sshExec } from '../ssh-exec.js';
+import { shellQuote } from './quote.js';
+/** Run the spec on this machine: spawn the launcher, resolve when it exits. */
+export function runLocal(spec) {
+    return new Promise((resolve) => {
+        const child = spawn(spec.argv[0], spec.argv.slice(1), { stdio: 'ignore' });
+        child.on('error', (err) => resolve({ ok: false, error: err.message }));
+        child.on('close', (code) => resolve(code === 0 ? { ok: true } : { ok: false, error: `${spec.argv[0]} exited with code ${code}` }));
+    });
+}
+/** Serialize a launch argv into a single POSIX-quoted shell command string. */
+export function remoteCommand(spec) {
+    return spec.argv.map(shellQuote).join(' ');
+}
+/** Run the spec on a remote host over SSH. */
+export function runRemote(spec, target) {
+    const res = sshExec(target, remoteCommand(spec), { multiplex: true });
+    if (res.code === 0)
+        return { ok: true };
+    const err = (res.stderr || '').trim();
+    return { ok: false, error: err || `ssh exited with code ${res.code}` };
+}
+/** Run a spec locally (no host / 'local') or on a resolved remote host. */
+export async function runSpec(spec, host, resolveHost) {
+    if (!host || host === 'local')
+        return runLocal(spec);
+    const target = resolveHost ? resolveHost(host) : host;
+    return runRemote(spec, target);
+}

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

@@ -0,0 +1,59 @@
+/**
+ * Core types for the terminal launch engine.
+ *
+ * The engine opens an *interactive* surface — a tab or a split pane — running a
+ * command, in a chosen terminal backend (iTerm / Ghostty / tmux), on this
+ * machine or a remote host. This is distinct from cloud providers
+ * (src/lib/cloud), which dispatch autonomous headless tasks; a terminal surface
+ * is attended and live. See docs/terminal-engine.md.
+ */
+/** An interactive terminal backend the engine can drive. */
+export type Backend = 'iterm' | 'ghostty' | 'tmux';
+/** Which way a split pane grows. `right` = side-by-side; `down` = stacked. */
+export type SplitDirection = 'right' | 'down';
+/** Where a surface lands: a new tab, or a split of the current pane. */
+export type Layout = 'tab' | 'split-right' | 'split-down';
+/** Ambient facts a backend needs to decide availability and detection. */
+export interface EngineContext {
+    platform: NodeJS.Platform;
+    env: NodeJS.ProcessEnv;
+}
+/** Snapshot the live process context. */
+export declare function currentContext(): EngineContext;
+/** The concrete OS command that opens a surface — the pure output of a backend. */
+export interface LaunchSpec {
+    /** argv to run (e.g. `['osascript','-e',script]` or `['tmux','split-window',…]`). */
+    argv: string[];
+}
+/** A single "open this command as this surface" instruction. */
+export interface LaunchRequest {
+    backend: Backend;
+    layout: Layout;
+    /** Working directory the command runs in. */
+    cwd: string;
+    /** argv to exec in the surface (e.g. a resume command). */
+    command: string[];
+    /** undefined / 'local' = this machine; otherwise a resolvable host alias. */
+    host?: string;
+}
+/** Outcome of opening one surface. Never throws for launch failures — reports them. */
+export interface LaunchResult {
+    ok: boolean;
+    request: LaunchRequest;
+    error?: string;
+}
+/**
+ * A terminal backend: pure builders + an availability check. No side effects —
+ * building a spec never opens anything, so every backend is unit-testable
+ * without a display. The engine's transport is what actually runs the spec.
+ */
+export interface TerminalBackend {
+    readonly id: Backend;
+    readonly label: string;
+    /** Can this backend be driven here? (platform + app installed / inside tmux). */
+    isAvailable(ctx: EngineContext): boolean;
+    /** Command that opens a new tab running `command` in `cwd`. */
+    buildTab(cwd: string, command: string[]): LaunchSpec;
+    /** Command that splits the current surface, running `command` in `cwd`. */
+    buildSplit(cwd: string, command: string[], direction: SplitDirection): LaunchSpec;
+}

package/dist/lib/terminal/types.js

@@ -0,0 +1,13 @@
+/**
+ * Core types for the terminal launch engine.
+ *
+ * The engine opens an *interactive* surface — a tab or a split pane — running a
+ * command, in a chosen terminal backend (iTerm / Ghostty / tmux), on this
+ * machine or a remote host. This is distinct from cloud providers
+ * (src/lib/cloud), which dispatch autonomous headless tasks; a terminal surface
+ * is attended and live. See docs/terminal-engine.md.
+ */
+/** Snapshot the live process context. */
+export function currentContext() {
+    return { platform: process.platform, env: process.env };
+}

package/dist/lib/types.d.ts

@@ -86,6 +86,13 @@ export interface AgentConfig {
      */
     nativeCommandRuntime?: boolean;
     hooksDir: string;
+    /**
+     * Directory (relative to a plugin's install dir) the agent reads its plugin
+     * manifest from, when it differs from the canonical `.claude-plugin/`. Codex
+     * uses `.codex-plugin`, Droid `.factory-plugin`. Set to `.` when the agent
+     * reads the manifest from the plugin ROOT (Copilot). syncPluginToVersion
+     * mirrors `.claude-plugin/plugin.json` into this dir.
+     */
     pluginManifestDir?: string;
     instructionsFile: string;
     format: 'markdown' | 'toml';

package/dist/lib/versions.d.ts

@@ -337,9 +337,13 @@ export declare function listRepoNames(): string[];
  * sync path uses. Passing the result as an explicit `selection` means the sync
  * touches only that repo's resources — no orphan-sweep of the other layers.
  *
- * `memory` is set to `[]` (not omitted): that empty-array sentinel is what
- * `syncResourcesToVersion`'s `skipMemory` gate keys on to leave the memory
- * file untouched — it's a merge of all layers, not a per-repo artifact.
+ * `memory` is set to `'all'`, NOT `[]`: the composed rules-memory file is a
+ * merge of ALL layers, so scoping the sync to a single repo must still
+ * recompile it in the same pass (RUSH-1354). Leaving it out — or using the
+ * `[]` skip-sentinel — silently strands the memory file at its old content
+ * whenever a repo-scoped sync runs after a rules change. `'all'` makes
+ * `syncResourcesToVersion` recompose from every layer via the active preset,
+ * exactly as an unscoped full reconcile does.
  */
 export declare function buildRepoScopedSelection(repo: string, cwd?: string): ResourceSelection;
 /**

package/dist/lib/versions.js

@@ -1692,9 +1692,13 @@ function resourceSourceMap(kind, cwd, available) {
  * sync path uses. Passing the result as an explicit `selection` means the sync
  * touches only that repo's resources — no orphan-sweep of the other layers.
  *
- * `memory` is set to `[]` (not omitted): that empty-array sentinel is what
- * `syncResourcesToVersion`'s `skipMemory` gate keys on to leave the memory
- * file untouched — it's a merge of all layers, not a per-repo artifact.
+ * `memory` is set to `'all'`, NOT `[]`: the composed rules-memory file is a
+ * merge of ALL layers, so scoping the sync to a single repo must still
+ * recompile it in the same pass (RUSH-1354). Leaving it out — or using the
+ * `[]` skip-sentinel — silently strands the memory file at its old content
+ * whenever a repo-scoped sync runs after a rules change. `'all'` makes
+ * `syncResourcesToVersion` recompose from every layer via the active preset,
+ * exactly as an unscoped full reconcile does.
  */
 export function buildRepoScopedSelection(repo, cwd = process.cwd()) {
     const patterns = [`${repo}:*`];
@@ -1706,8 +1710,9 @@ export function buildRepoScopedSelection(repo, cwd = process.cwd()) {
         if (names.length > 0)
             selection[kind] = names;
     }
-    // Empty-array sentinel → skip the memory writer (see skipMemory below).
-    selection.memory = [];
+    // Recompile the memory file from all layers even under a repo scope — it is
+    // composed, not a per-repo artifact (see skipMemory below and RUSH-1354).
+    selection.memory = 'all';
     return selection;
 }
 /**

package/dist/lib/whats-new.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Render a compact "What's new" summary from a CHANGELOG.md body: one bullet
+ * per feature/fix heading (the `**...**` lines) for each version in the range
+ * the user actually moved through, `(fromVersion, toVersion]`. The verbose
+ * sub-bullets are intentionally dropped — the full notes live in the changelog.
+ *
+ * Returns colored lines ready to print, empty when nothing is in range.
+ */
+export declare function renderWhatsNew(changelog: string, fromVersion: string, toVersion: string): string[];

package/dist/lib/whats-new.js

@@ -0,0 +1,35 @@
+import chalk from 'chalk';
+import { compareVersions } from './agent-spec/primitives.js';
+/**
+ * Render a compact "What's new" summary from a CHANGELOG.md body: one bullet
+ * per feature/fix heading (the `**...**` lines) for each version in the range
+ * the user actually moved through, `(fromVersion, toVersion]`. The verbose
+ * sub-bullets are intentionally dropped — the full notes live in the changelog.
+ *
+ * Returns colored lines ready to print, empty when nothing is in range.
+ */
+export function renderWhatsNew(changelog, fromVersion, toVersion) {
+    const out = [];
+    let inRelevantSection = false;
+    for (const line of changelog.split('\n')) {
+        const versionMatch = line.match(/^## (\d+\.\d+\.\d+)/);
+        if (versionMatch) {
+            const currentVersion = versionMatch[1];
+            // Bounding the top end matters when upgrading to a specific older
+            // version, and guards against a changelog that lists unreleased entries.
+            inRelevantSection =
+                compareVersions(currentVersion, fromVersion) > 0 &&
+                    compareVersions(currentVersion, toVersion) <= 0;
+            if (inRelevantSection) {
+                out.push('');
+                out.push(chalk.bold(`v${currentVersion}`));
+            }
+            continue;
+        }
+        // Only the bold headings — one bullet per feature/fix.
+        if (inRelevantSection && line.startsWith('**') && line.endsWith('**')) {
+            out.push(`  ${chalk.cyan('•')} ${line.replace(/\*\*/g, '')}`);
+        }
+    }
+    return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.20.34",
+  "version": "1.20.35",
   "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",