@zgeoff/atc 2.27.0 → 2.29.0

package/src/client/spawn-picker.ts

@@ -19,9 +19,19 @@ import { KEY, planTextEdit } from './keys';
 import { pickRefusalStep } from './pick-refusal-step';
 import { resolvePathInput } from './resolve-path-input';
 import { resolveWorkspaceRoot } from './resolve-workspace-root';
-import { ansi, cols, drawPicker } from './ui';
-
-type PickerStep = 'agent' | 'dir' | 'source' | 'ref' | 'target' | 'confirm' | 'name' | 'prompt';
+import { splitToWidth } from './split-to-width';
+import { ansi, cols, drawPicker, getPickerWidth } from './ui';
+
+type PickerStep =
+  | 'agent'
+  | 'dir'
+  | 'source'
+  | 'ref'
+  | 'target'
+  | 'confirm'
+  | 'name'
+  | 'prompt'
+  | 'spawned';
 
 // What the flow borrows from the client that owns the screen, the daemon
 // connection and the fleet mirror.
@@ -114,10 +124,14 @@ type SourceStepAction =
  * optional first prompt. The sources are the ones the daemon offers, in
  * its order, and Tab cycles them; a daemon that offers none gets the local
  * directory flow alone. A source of directories is followed by the
- * execution target when the daemon has more than one. A source of git
+ * execution target when more than one target can run it. A source of git
  * repositories opens the target first, then its candidates, the ref, and a
  * confirm screen with the destination the checkout lands in, so every
  * request about the repository is made for the target the spawn runs on.
+ * A choice of agent or target with one row the source can use is no
+ * choice: the flow takes that row and goes on, and Esc from the step after
+ * it goes back past it. A daemon that lists targets none of which can run
+ * the source shows the target step with the reason.
  * Typed input a source does not match against its candidates is read by
  * the source, then by the others in order. Every path out of the flow
  * either attaches the new session or returns the client to the screen it
@@ -145,6 +159,10 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
   // edit or a fresh install lands without a client restart.
   private picks: AgentPick[] = [];
 
+  // Whether the agent step waits on the daemon's targets and sources once
+  // an agent is chosen.
+  private sourcesPending = false;
+
   // The directories the directory step lists, and the label each shows.
   private dirs: string[] = [];
 
@@ -170,6 +188,10 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
 
   private target: TargetPick | null = null;
 
+  // Why the flow offers no target although the daemon lists some, or null
+  // when it offers some or the daemon lists none.
+  private targetGap: string | null = null;
+
   // The git source's candidates and the scope they were listed under, or
   // the notice that stands in for a list the daemon could not give, with
   // the source and target they were listed for. A listing runs behind the
@@ -226,6 +248,12 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
 
   private pending: PendingRequest | null = null;
 
+  // A session the daemon started with warnings, and those warnings, shown
+  // before the flow attaches it.
+  private spawned: TMirror | null = null;
+
+  private spawnWarnings: readonly string[] = [];
+
   private requestSeq = 0;
 
   // The flow's generation. Opening the flow and every way out of it moves
@@ -249,7 +277,9 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
     this.input = '';
     this.sources = null;
     this.sourceIndex = -1;
+    this.sourcesPending = false;
     this.target = null;
+    this.targetGap = null;
     this.repo = null;
     this.ref = null;
     this.sourceDraft = '';
@@ -275,12 +305,26 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
     this.pending = null;
 
     process.stdout.write(ansi.clear);
+
+    // One installed agent is no choice to make, so the flow goes on with it.
+    if (this.picks.length === 1) {
+      void this.openFirstSource();
+
+      return;
+    }
+
     this.render();
   }
 
   applyKey(buf: Buffer) {
     this.refusal = null;
 
+    if (this.step === 'spawned') {
+      this.applySpawnedKey(buf);
+
+      return;
+    }
+
     const edit = planTextEdit(buf, this.input, {
       isLeaderKey: this.deps.isLeaderKey,
       moves:
@@ -303,6 +347,17 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
       return;
     }
 
+    // The agent step waiting on the daemon's targets and sources takes Esc
+    // and the leader, and every other key waits for the answer.
+    if (
+      this.step === 'agent' &&
+      this.sourcesPending &&
+      edit.kind !== 'cancel' &&
+      edit.kind !== 'leader'
+    ) {
+      return;
+    }
+
     const tab = buf.length === 1 && buf[0] === KEY.tab;
 
     // A tab to a source of directories waits for its listing on the step it
@@ -365,10 +420,14 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
 
       // An empty menu means every configured binary is missing, so the hint
       // carries the fix instead of the movement keys.
-      const hint =
-        this.picks.length === 0
-          ? 'no agent CLI found — set claudeBin, grokBin, or codexBin in config.json · esc cancel'
-          : '↑↓ move · ⏎ select · esc cancel';
+      let hint = '↑↓ move · ⏎ select · esc cancel';
+
+      if (this.picks.length === 0) {
+        hint =
+          'no agent CLI found — set claudeBin, grokBin, or codexBin in config.json · esc cancel';
+      } else if (this.sourcesPending) {
+        hint = 'reading targets and sources… · esc cancel';
+      }
 
       drawPicker({
         title: `${verb}: agent`,
@@ -387,6 +446,14 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
       this.renderTargetStep(verb);
     } else if (this.step === 'confirm') {
       this.renderConfirmStep();
+    } else if (this.step === 'spawned') {
+      drawPicker({
+        title: `${verb}: started`,
+        items: this.spawnWarnings.flatMap((w) => splitToWidth(w, getPickerWidth() - 4)),
+        selected: -1,
+        input: '',
+        hint: '⏎ attach · esc back',
+      });
     } else if (this.step === 'name') {
       const where = this.isGitFlow() ? this.formatDestination() : formatDir(this.dir);
 
@@ -458,13 +525,21 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
 
     const git = this.isGitFlow();
     const what = git ? 'the repository' : formatDir(this.dir);
+    let hint = `where ${what} runs · ↑↓ move · ⏎ select · esc back`;
+
+    // A step with no target the source can run on says what is missing.
+    if (this.collectEligibleTargets().length === 0) {
+      const gap = this.targetGap ?? `none of these targets can run ${what}`;
+
+      hint = `${gap} · set targets in config.json · esc back`;
+    }
 
     drawPicker({
       title: `${verb}: target`,
       items: this.targets.map((t) => formatTargetPick(t)),
       selected: this.selected,
       input: '',
-      hint: this.refusal ?? `where ${what} runs · ↑↓ move · ⏎ select · esc back`,
+      hint: this.refusal ?? hint,
       dimmed: new Set(
         this.targets.flatMap((t, i) =>
           t.takesWorkspace || (!git && t.available && t.inPlace) ? [] : [i],
@@ -636,11 +711,19 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
 
     if (this.step === 'dir') {
       this.openAgentStep();
-    } else if (this.step === 'source') {
+
+      return;
+    }
+
+    if (this.step === 'source') {
       this.sourceDraft = typed;
 
       this.applySourceCancel();
-    } else if (this.step === 'ref') {
+
+      return;
+    }
+
+    if (this.step === 'ref') {
       this.input = this.repo?.label ?? '';
       this.repo = null;
       this.step = 'source';
@@ -654,10 +737,8 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
       if (this.isGitFlow()) {
         this.input = this.buildDestination();
         this.step = 'confirm';
-      } else {
-        this.openTargetStep(() => {
-          this.step = 'dir';
-        });
+      } else if (!this.openTargetStep()) {
+        this.step = 'dir';
       }
     } else {
       this.input = this.name;
@@ -668,20 +749,33 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
     this.render();
   }
 
+  // Goes back to the agent step, or leaves the flow when one installed
+  // agent left no agent step to go back to.
   private openAgentStep() {
+    if (this.picks.length === 1) {
+      this.quitFlow();
+
+      return;
+    }
+
     this.selected = Math.max(
       0,
       this.picks.findIndex((p) => p.agent === this.agent),
     );
 
+    this.sourcesPending = false;
     this.step = 'agent';
+
+    process.stdout.write(ansi.clear);
+    this.render();
   }
 
-  // Leaves a git source step backwards: to the target step when the daemon
-  // has more than one target, else to the agent.
+  // Leaves a git source step backwards: to the target step when the spawn
+  // has one, else to the agent.
   private applySourceCancel() {
-    if (this.targets.length >= 2) {
-      this.openTargetStep(() => {});
+    if (this.openTargetStep()) {
+      process.stdout.write(ansi.clear);
+      this.render();
 
       return;
     }
@@ -707,8 +801,6 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
 
     if (index === -1) {
       this.openAgentStep();
-      process.stdout.write(ansi.clear);
-      this.render();
 
       return;
     }
@@ -811,9 +903,9 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
     this.dir = dir;
     this.input = '';
 
-    this.openTargetStep(() => {
+    if (!this.openTargetStep()) {
       this.step = 'name';
-    });
+    }
 
     process.stdout.write(ansi.clear);
     this.render();
@@ -998,8 +1090,8 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
   }
 
   // Moves the flow to a source of git repositories, carrying the typed text
-  // across: the target step first when the daemon has more than one target
-  // and the flow had no repository target yet, then the source step, which
+  // across: the target step first when the spawn has one and the flow had
+  // no repository target yet, then the source step, which
   // acts as asked once it opens.
   private openGitSource(index: number, draft: string, action: SourceStepAction) {
     const fromGit = this.isGitFlow();
@@ -1015,16 +1107,13 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
       return;
     }
 
-    if (this.targets.length >= 2) {
-      this.openTargetStep(() => {});
+    if (this.openTargetStep()) {
       process.stdout.write(ansi.clear);
       this.render();
 
       return;
     }
 
-    this.target = this.targets[0] ?? null;
-
     this.openSourceStep();
   }
 
@@ -1569,19 +1658,22 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
     return this.target ?? this.targets.find((t) => t.isDefault) ?? null;
   }
 
-  // Opens the target step when the daemon has more than one target, and
-  // the fallback step otherwise. The chosen target is selected, else for a
-  // repository the default when it takes a workspace and the first target
-  // that does when it does not, else the default.
-  private openTargetStep(fallback: () => void) {
-    if (this.targets.length < 2) {
-      // The one target is the spawn's, default or not, so the spawn names it
-      // and its provider decides whether a directory runs in place.
-      this.target = this.targets[0] ?? null;
+  // Opens the target step when more than one target can run the flow's
+  // source, or none can although the daemon lists targets, and answers
+  // whether it did. The chosen target is selected, else for a repository
+  // the default when it takes a workspace and the first target that does
+  // when it does not, else the default.
+  private openTargetStep(): boolean {
+    const eligible = this.collectEligibleTargets();
 
-      fallback();
+    if (eligible.length === 1 || (this.targets.length === 0 && this.targetGap === null)) {
+      // The one target that can run the source is the spawn's, default or
+      // not, so the spawn names it and its provider decides whether a
+      // directory runs in place. A daemon that lists no targets runs the
+      // spawn on its default.
+      this.target = eligible[0] ?? null;
 
-      return;
+      return false;
     }
 
     const preferred =
@@ -1599,6 +1691,15 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
 
     this.input = '';
     this.step = 'target';
+
+    return true;
+  }
+
+  // The targets the flow's source can run on.
+  private collectEligibleTargets(): TargetPick[] {
+    const git = this.isGitFlow();
+
+    return this.targets.filter((t) => findTargetRefusal(t, git) === null);
   }
 
   // Reads the daemon's targets and sources once the agent is chosen, and
@@ -1608,6 +1709,10 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
     const generation = this.generation;
     let listed: Readonly<Record<string, unknown>> = {};
 
+    this.sourcesPending = true;
+
+    this.render();
+
     try {
       listed = await this.deps.sendRequest('agents.list');
     } catch {}
@@ -1619,12 +1724,20 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
     // An agent that takes its credential from impd's broker runs only on a
     // target that reaches the broker.
     const brokered = isBrokerAgent(listed['agents'], this.agent);
-    const picks = collectTargetPicks(listed).filter((t) => !brokered || t.brokerAuth);
+    const listedTargets = collectTargetPicks(listed);
+    const picks = listedTargets.filter((t) => !brokered || t.brokerAuth);
 
     // An adopt resumes a session from its history on this host, which a
     // fresh checkout elsewhere does not hold, so it is offered only the
     // targets that run here.
     this.targets = this.resume ? picks.filter((t) => t.available && t.inPlace) : picks;
+    this.targetGap = null;
+
+    if (listedTargets.length > 0 && picks.length === 0) {
+      this.targetGap = `no target reaches the credential broker ${this.agent} needs`;
+    } else if (listedTargets.length > 0 && this.targets.length === 0) {
+      this.targetGap = 'no target on this host can adopt a session';
+    }
 
     const announced = parseAnnouncedSources(listed['sources']);
     const index = this.resume ? announced.findIndex((source) => source.kind === 'path') : 0;
@@ -1714,9 +1827,49 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
     this.stopFlow();
     this.deps.upsertMirror(session);
 
+    const warnings = spawned.answer['warnings'];
+
+    // A workspace that left changes behind says so before the session's
+    // screen takes over.
+    if (Array.isArray(warnings) && warnings.length > 0) {
+      this.spawned = session;
+      this.spawnWarnings = warnings.filter((w): w is string => typeof w === 'string');
+      this.step = 'spawned';
+
+      process.stdout.write(ansi.clear);
+      this.render();
+
+      return;
+    }
+
     await this.deps.attach(session.id);
   }
 
+  // The started step takes Enter to attach the session and Esc or the
+  // leader to return to the screen the flow came from; the session runs
+  // either way.
+  private applySpawnedKey(buf: Buffer) {
+    const edit = planTextEdit(buf, '', { isLeaderKey: this.deps.isLeaderKey, moves: false });
+
+    if (edit.kind !== 'submit' && edit.kind !== 'cancel' && edit.kind !== 'leader') {
+      return;
+    }
+
+    const session = this.spawned;
+
+    this.spawned = null;
+    this.spawnWarnings = [];
+    this.step = 'agent';
+
+    if (edit.kind === 'submit' && session !== null) {
+      void this.deps.attach(session.id);
+
+      return;
+    }
+
+    this.deps.toBase();
+  }
+
   // A refused git workspace spawn returns to the step that can fix it. Any
   // other refusal keeps the picker on the step that sent it, with the
   // entered text back in the input, so the user can fix the cause and retry

package/src/client/split-to-width.ts

@@ -0,0 +1,47 @@
+/**
+ * Splits text into rows of at most `width` characters, breaking at spaces
+ * and counting a grapheme cluster as one character. A word wider than a
+ * row breaks at the row's edge, never inside a character.
+ */
+export function splitToWidth(text: string, width: number): string[] {
+  if (width <= 0) {
+    return [text];
+  }
+
+  const segmenter = new Intl.Segmenter();
+
+  const rows: string[] = [];
+  let row: string[] = [];
+
+  for (const word of text.split(' ')) {
+    let rest = Array.from(segmenter.segment(word), (part) => part.segment);
+
+    while (rest.length > width) {
+      if (row.length > 0) {
+        rows.push(row.join(''));
+
+        row = [];
+      }
+
+      rows.push(rest.slice(0, width).join(''));
+
+      rest = rest.slice(width);
+    }
+
+    if (row.length === 0) {
+      row = rest;
+    } else if (row.length + 1 + rest.length <= width) {
+      row = [...row, ' ', ...rest];
+    } else {
+      rows.push(row.join(''));
+
+      row = rest;
+    }
+  }
+
+  if (row.length > 0) {
+    rows.push(row.join(''));
+  }
+
+  return rows;
+}

package/src/client/to-mirror-session.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import type { SessionState } from '../protocol/session-state';
 import type { AgentID } from '../shared/agent-id';
+import { isRecord } from '../shared/report';
 import { toAgentID } from '../shared/to-agent-id';
 
 export interface MirrorSession {
@@ -20,8 +21,24 @@ export interface MirrorSession {
   canEject: boolean;
   agent: AgentID;
   parent: string | null;
+
+  // The execution target the session runs on, from the descriptor's
+  // locator; 'local' when the descriptor carries none.
+  target: string;
+
+  // The model the session was spawned with, as the daemon stores it: null
+  // when it runs the agent's default. An alias a gateway's models map
+  // resolves is resolved at draw time, where the map is at hand.
+  model: string | null;
+
+  // Where the session's harness stands: running, suspended inside a
+  // sleeping host, or exited. Distinct from `state`, which carries the
+  // attention a live harness last reported.
+  harness: HarnessLifecycle;
 }
 
+export type HarnessLifecycle = 'running' | 'suspended' | 'exited';
+
 // Only the fields a mirror can't function without; an unparseable descriptor
 // is skipped rather than thrown into the event loop. Unknown keys pass
 // through so the lenient fallbacks below can still read them.
@@ -63,5 +80,32 @@ export function toMirrorSession(value: unknown): MirrorSession | null {
     canEject: record['canEject'] === true,
     agent: toAgentID(record['agent']),
     parent: typeof record['parent'] === 'string' ? record['parent'] : null,
+    target: readTargetID(record['locator']),
+    model: typeof record['model'] === 'string' ? record['model'] : null,
+    harness: readHarnessLifecycle(record['lifecycle'], record.alive),
   };
 }
+
+// The locator's target id, with 'local' for a descriptor that carries no
+// locator at all.
+function readTargetID(locator: unknown): string {
+  if (isRecord(locator) && typeof locator['targetID'] === 'string') {
+    return locator['targetID'];
+  }
+
+  return 'local';
+}
+
+// The harness layer of a descriptor's lifecycle, falling back to what the
+// alive flag says when the lifecycle is missing.
+function readHarnessLifecycle(lifecycle: unknown, alive: boolean): HarnessLifecycle {
+  if (isRecord(lifecycle)) {
+    const harness = lifecycle['harness'];
+
+    if (harness === 'running' || harness === 'suspended' || harness === 'exited') {
+      return harness;
+    }
+  }
+
+  return alive ? 'running' : 'exited';
+}