@phnx-labs/agents-cli 1.20.55 → 1.20.57

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

@@ -301,6 +301,22 @@ 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, hostName?: string | null, hostTarget?: string | null, repoPath?: string | null): Promise<AgentProcess>;
+    /**
+     * Resume a STOPPED teammate (completed / failed / stopped) by re-entering its
+     * own session with `message` as the next user turn. Re-launches through the
+     * SAME backend the teammate first used (local process or remote host), reusing
+     * its stored cwd / worktree / host / version / model / effort, and flips it
+     * back to RUNNING so the team tracks it live again.
+     *
+     * The resume target is the teammate's underlying agent session id: for Claude
+     * that IS its agent_id (unified identity, pinned via --session-id at first
+     * launch); other harnesses only expose their session/thread id after their
+     * first stream event, captured as `remoteSessionId`.
+     *
+     * Callers branch on status first — a RUNNING teammate is steered via its
+     * mailbox, never re-launched — so this method assumes a non-running teammate.
+     */
+    resumeTeammate(agentId: string, message: string): Promise<AgentProcess>;
     /**
      * Actually spawn the OS process for a teammate. Extracted from spawn() so
      * staged teammates can be launched later by startReady().

package/dist/lib/teams/agents.js

@@ -8,6 +8,7 @@
  * multiple permission modes (plan, edit, full).
  */
 import { spawn, execSync, execFileSync } from 'child_process';
+import { getAgentsInvocation } from '../daemon.js';
 import * as fs from 'fs/promises';
 import * as fsSync from 'fs';
 import * as path from 'path';
@@ -1356,11 +1357,69 @@ export class AgentManager {
         await this.cleanupOldAgents();
         return agent;
     }
+    /**
+     * Resume a STOPPED teammate (completed / failed / stopped) by re-entering its
+     * own session with `message` as the next user turn. Re-launches through the
+     * SAME backend the teammate first used (local process or remote host), reusing
+     * its stored cwd / worktree / host / version / model / effort, and flips it
+     * back to RUNNING so the team tracks it live again.
+     *
+     * The resume target is the teammate's underlying agent session id: for Claude
+     * that IS its agent_id (unified identity, pinned via --session-id at first
+     * launch); other harnesses only expose their session/thread id after their
+     * first stream event, captured as `remoteSessionId`.
+     *
+     * Callers branch on status first — a RUNNING teammate is steered via its
+     * mailbox, never re-launched — so this method assumes a non-running teammate.
+     */
+    async resumeTeammate(agentId, message) {
+        await this.initialize();
+        const agent = await this.get(agentId);
+        if (!agent)
+            throw new Error(`No teammate with id ${agentId}`);
+        const who = agent.name ?? agent.agentId.slice(0, 8);
+        // The message rides as `agents run`'s prompt positional. A leading '-' makes
+        // commander parse it as an (unknown) flag, exiting the child non-zero — the
+        // teammate would silently land FAILED. `--` can't rescue it: `agents run`
+        // treats post-`--` tokens as native passthrough and unsets the prompt. Fail
+        // loud and early instead. (Steer/mailbox delivery has no such limit.)
+        if (message.startsWith('-')) {
+            throw new Error(`Resume message can't start with '-' — \`agents run\` would parse it as a flag. ` +
+                `Rephrase so it leads with a word (e.g. "Please ${message}").`);
+        }
+        // Cloud-backed teammates run on remote provider infrastructure with no local
+        // or host process to re-launch; continuing them goes through the provider.
+        if (agent.cloudProvider) {
+            throw new Error(`Teammate '${who}' is a ${agent.cloudProvider} cloud task — resume it with ` +
+                `\`agents message ${agent.cloudSessionId ?? agent.agentId} "<message>"\` instead.`);
+        }
+        // For non-Claude teammates the agent_id is NOT the harness session id — that
+        // is only known once the agent emitted its first stream event. If it never
+        // did (e.g. it failed before its first turn), there is no resumable handle.
+        if (agent.agentType !== 'claude' && !agent.remoteSessionId) {
+            throw new Error(`No resumable session id was captured for ${agent.agentType} teammate '${who}' — ` +
+                `its session id is discovered from the agent's own output, which never arrived ` +
+                `(it may have failed before its first turn). Start a fresh teammate instead.`);
+        }
+        const resume = { id: agent.remoteSessionId ?? agent.agentId, message };
+        // Flip to RUNNING up front so a concurrent status poll can't reap the
+        // teammate between the exit-sentinel clear and the new PID landing; the
+        // launch re-persists with the fresh pid/startTime.
+        agent.status = AgentStatus.RUNNING;
+        agent.completedAt = null;
+        if (agent.hostName) {
+            await this.launchRemoteProcess(agent, resume);
+        }
+        else {
+            await this.launchProcess(agent, resume);
+        }
+        return agent;
+    }
     /**
      * Actually spawn the OS process for a teammate. Extracted from spawn() so
      * staged teammates can be launched later by startReady().
      */
-    async launchProcess(agent) {
+    async launchProcess(agent, resume) {
         const running = await this.listRunning();
         warnIfMemoryLow(running.length);
         const effort = agent.effort ?? 'medium';
@@ -1368,10 +1427,20 @@ export class AgentManager {
         // forwarded). Effort is a separate knob wired into buildReasoningFlags
         // inside buildCommand.
         const resolvedModel = agent.model ?? null;
-        const cmd = this.buildCommand(agent.agentType, agent.prompt, agent.mode, resolvedModel, agent.cwd, agent.agentId, effort, agent.version, agent.profileName);
-        debug(`Launching ${agent.agentType} agent ${agent.agentId} [${agent.mode}]: ${cmd.slice(0, 3).join(' ')}...`);
+        const cmd = this.buildCommand(agent.agentType, agent.prompt, agent.mode, resolvedModel, agent.cwd, agent.agentId, effort, agent.version, agent.profileName, resume);
+        debug(`Launching ${agent.agentType} agent ${agent.agentId} [${agent.mode}]${resume ? ' (resume)' : ''}: ${cmd.slice(0, 3).join(' ')}...`);
         try {
             const stdoutPath = await agent.getStdoutPath();
+            // Always TRUNCATE — including on resume. The status reader re-reads the
+            // whole log from byte 0 every poll (lastReadPos is in-memory, not
+            // persisted) and marks terminal status from the last `result` event it
+            // sees, with no liveness guard. If the resumed turn's stream were appended
+            // after the prior turn's `result:success`, that stale event would win for
+            // the entire duration of the new (still-running) turn — reporting the
+            // teammate COMPLETED while it works, and steering a second follow-up into
+            // a forked session. Truncating keeps exactly one turn in the log, so the
+            // re-read is always correct. The authoritative transcript lives in the
+            // agent's own session (resumed via --resume), not this stdout mirror.
             const stdoutFile = await fs.open(stdoutPath, 'w');
             const stdoutFd = stdoutFile.fd;
             // Wrap the teammate command in a shell that records the underlying CLI's
@@ -1423,7 +1492,7 @@ export class AgentManager {
      * created ON THE HOST off the freshly-fetched default branch; the teammate runs
      * there. Otherwise it runs in the host repo path directly.
      */
-    async launchRemoteProcess(agent) {
+    async launchRemoteProcess(agent, resume) {
         if (!agent.hostName || !agent.hostTarget || !agent.repoPath) {
             throw new Error(`Remote teammate ${agent.agentId} is missing host placement (host/target/repo).`);
         }
@@ -1447,17 +1516,25 @@ export class AgentManager {
         }
         // Worktree isolation on the host, if the team enables it. createRemoteWorktree
         // fetches origin and branches off origin/<default>, returning the host path.
+        // On RESUME the worktree already exists from the original launch — reuse it
+        // (its path is persisted) instead of re-creating (which would fail on the
+        // existing branch and would also discard the teammate's in-progress work).
         let remoteCwd = agent.repoPath;
         if (agent.worktreeName) {
-            const worktreePath = createRemoteWorktree(agent.hostTarget, agent.repoPath, agent.worktreeName);
-            agent.worktreePath = worktreePath;
-            remoteCwd = worktreePath;
+            if (resume && agent.worktreePath) {
+                remoteCwd = agent.worktreePath;
+            }
+            else {
+                const worktreePath = createRemoteWorktree(agent.hostTarget, agent.repoPath, agent.worktreeName);
+                agent.worktreePath = worktreePath;
+                remoteCwd = worktreePath;
+            }
         }
         // Same run argv the local path builds (shared buildRunArgv keeps the prompt
         // scaffolding + flags from drifting); dispatched non-blocking (follow:false)
         // — the supervisor polls the host, we don't block here.
         const effort = agent.effort ?? 'medium';
-        const forwardedArgs = this.buildRunArgv(agent.agentType, agent.prompt, agent.mode, agent.model ?? null, effort, agent.version, agent.profileName);
+        const forwardedArgs = this.buildRunArgv(agent.agentType, agent.prompt, agent.mode, agent.model ?? null, effort, agent.version, agent.profileName, resume);
         try {
             const { task } = await dispatchAgentsCommand(host, {
                 forwardedArgs,
@@ -1468,6 +1545,13 @@ export class AgentManager {
             agent.remoteLog = task.remoteLog ?? null;
             agent.remoteExit = task.remoteExit ?? null;
             agent.remoteLogOffset = 0;
+            // On resume the offset resets to 0 against a FRESH remote log, and
+            // syncRemoteMirror appends the delta onto the local mirror. Truncate that
+            // mirror first so the prior turn's terminal event can't linger and get
+            // re-read as the current status (same hazard the local path truncates for).
+            if (resume) {
+                await fs.writeFile(await agent.getStdoutPath(), '').catch(() => { });
+            }
             agent.status = AgentStatus.RUNNING;
             agent.startedAt = new Date();
             await agent.saveMeta();
@@ -1669,47 +1753,56 @@ export class AgentManager {
      * before invoking `agents`. `sessionId` is likewise local-only (the remote run
      * mints its own session on the host).
      */
-    buildRunArgv(agentType, prompt, mode, model, effort, version, profileName) {
-        // Compose the prompt: a plan-mode prefix for Claude (clarifying headless
-        // plan-mode restrictions) and a universal summary suffix. These are
-        // team-specific prompt scaffolding — `agents run` does not apply them.
-        let fullPrompt = prompt + PROMPT_SUFFIX;
-        if (agentType === 'claude' && mode === 'plan') {
-            fullPrompt = CLAUDE_PLAN_MODE_PREFIX + fullPrompt;
+    buildRunArgv(agentType, prompt, mode, model, effort, version, profileName, resume) {
+        // Compose the prompt. On RESUME the message is the teammate's next user turn,
+        // not a fresh brief — so skip the original brief and the plan-mode prefix, but
+        // keep PROMPT_SUFFIX so the resumed run still emits a final summary the team
+        // parser reads. On a fresh launch, add the plan-mode prefix for Claude and the
+        // universal summary suffix. These are team-specific prompt scaffolding —
+        // `agents run` does not apply them.
+        let fullPrompt;
+        if (resume) {
+            fullPrompt = resume.message + PROMPT_SUFFIX;
+        }
+        else {
+            fullPrompt = prompt + PROMPT_SUFFIX;
+            if (agentType === 'claude' && mode === 'plan') {
+                fullPrompt = CLAUDE_PLAN_MODE_PREFIX + fullPrompt;
+            }
         }
         // Profile target takes precedence — `agents run <profile>` resolves the
         // host harness, version pin, and env injection in one place. Plain
         // version pins only apply when no profile is selected.
         const target = profileName ?? (version ? `${agentType}@${version}` : agentType);
-        const args = [
-            'run',
-            target,
-            fullPrompt,
-            '--mode', mode,
-            '--effort', effort,
-            '--json',
-            '--headless',
-            '--quiet',
-        ];
+        // Keep the prompt as the first positional (right after target), matching the
+        // fresh-launch shape, and add `--resume <id>` among the flags. `agents run`
+        // continues the teammate's own session natively (claude `--resume`, codex
+        // `resume`) or via the universal `/continue` replay for other harnesses.
+        const args = ['run', target, fullPrompt];
+        if (resume) {
+            args.push('--resume', resume.id);
+        }
+        args.push('--mode', mode, '--effort', effort, '--json', '--headless', '--quiet');
         if (model)
             args.push('--model', model);
         args.push('--env', 'AGENTS_RUNTIME=teams');
         return args;
     }
-    buildCommand(agentType, prompt, mode, model, cwd = null, sessionId = null, effort = 'medium', version = null, profileName = null) {
-        const agentsCli = process.argv[1];
-        const cmd = [
-            process.execPath,
-            agentsCli,
-            ...this.buildRunArgv(agentType, prompt, mode, model, effort, version, profileName),
-        ];
+    buildCommand(agentType, prompt, mode, model, cwd = null, sessionId = null, effort = 'medium', version = null, profileName = null, resume) {
+        // Route through getAgentsInvocation so a teammate launched by the compiled
+        // standalone binary (#315) doesn't relaunch as `agents /$bunfs/root/agents …`
+        // (process.argv[1] is the bun virtual entry there) → "unknown command".
+        const inv = getAgentsInvocation(this.buildRunArgv(agentType, prompt, mode, model, effort, version, profileName, resume));
+        const cmd = [inv.command, ...inv.args];
         if (cwd)
             cmd.push('--cwd', cwd);
         // Pin the session UUID to our agent_id so buildExecEnv keys
         // AGENTS_MAILBOX_DIR by the same id mailboxIdForActiveSession returns.
         // Claude also forwards --session-id to its CLI (unified identity);
         // other agents ignore the flag but still get the correct mailbox dir.
-        if (sessionId) {
+        // On RESUME we continue an existing session — `--session-id` CREATES one and
+        // `agents run` rejects it alongside `--resume`, so it must be omitted.
+        if (sessionId && !resume) {
             cmd.push('--session-id', sessionId);
         }
         // Claude: grant access to the teammate's working directory.

package/package.json

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