@peakflo/agent-harness 0.2.30-rc.2 → 0.2.31-rc.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -63,9 +63,12 @@ npx --yes @peakflo/agent-harness@<version> connect --connection <id>
63
63
  ```
64
64
 
65
65
  Approve the computer in the browser, using the account and company that made
66
- the command. The runner checks Claude Code, Codex, Cursor, Pi, and OpenCode.
67
- All usable supported harnesses connect automatically. There is no harness
68
- selection during setup. Choose which harness an agent uses in the agent editor.
66
+ the command. The runner finds Claude Code, Codex, Cursor and Pi and connects
67
+ the ones that are ready. It also detects OpenCode, which it cannot run on a
68
+ computer yet, and lists it as unavailable.
69
+ All usable supported harnesses connect automatically. Spaces then lists what
70
+ it found ("Found on this computer"), with the ready ones checked; unchecking one
71
+ turns its agent off. Choose which harness an agent uses in the agent editor.
69
72
  Agents allow actions by default. Change permissions in the editor, or add
70
73
  `--ask` to the command to start in Ask mode. `--all` remains a compatibility
71
74
  alias; it is no longer needed.
@@ -87,8 +90,25 @@ Detected backends shows status and install/sign-in help. No extra action,
87
90
  connection token, or runner is needed. Existing agent settings stay unchanged.
88
91
 
89
92
  The computer flow needs harness 0.2.23 or later on macOS or Linux. An older
90
- pin keeps the vendor-specific fallback. The legacy per-vendor path also
91
- keeps that path available:
93
+ pin keeps the vendor-specific fallback.
94
+
95
+ From 0.2.31 the Connect picker offers it for a new connection ("Auto — find
96
+ the agents on this computer"). That release checks Pi's MCP extension: every
97
+ turn passes `--mcp-config`, which only `pi-mcp-adapter` understands. A Pi
98
+ without it is reported as "needs setup" with the fix
99
+ `pi install npm:pi-mcp-adapter` and is not routed work. On a computer or VM, a
100
+ turn that reaches it anyway is refused with that fix instead of failing as
101
+ "Pi process exited". The cloud sandbox installs the adapter in its image and
102
+ skips this check.
103
+
104
+ Only Pi's agent directory counts (`PI_CODING_AGENT_DIR`, else `~/.pi/agent`).
105
+ The runner serves many workspaces, so an adapter listed only in a project's
106
+ `.pi/settings.json` is "needs setup". The 20x desktop installer already runs
107
+ `pi install npm:pi-mcp-adapter`, so a machine set up by 20x is Ready.
108
+ Reconnect of an existing computer still works from 0.2.23; a pin from 0.2.23
109
+ to 0.2.30 keeps the old Pi behaviour there.
110
+
111
+ The legacy per-vendor path also stays available:
92
112
 
93
113
  ```sh
94
114
  npx --yes @peakflo/agent-harness@<version> connect claude-code --connection <id>
@@ -308,7 +308,11 @@ stateDir, options = {}) {
308
308
  if (backend === 'pi') {
309
309
  // The adapter reads the per-turn gateway holder directly. If the lease
310
310
  // has no model token SessionRunner refuses before this is reached.
311
- return new adapters_1.PiAdapter(ports.modelGateway);
311
+ // The sandbox image installs pi-mcp-adapter and checks it at build
312
+ // time; the preflight is for personal computers and VMs.
313
+ return new adapters_1.PiAdapter(ports.modelGateway, {
314
+ checkMcpAdapter: runtime !== 'sandbox'
315
+ });
312
316
  }
313
317
  if ((0, vendor_backends_1.isVendorBackend)(backend)) {
314
318
  const blocker = (0, vendor_backends_1.vendorBackendBlocker)(backend, runtime);
@@ -56,6 +56,12 @@ export declare function buildPiMcpConfigDocument(servers: NonNullable<SessionCon
56
56
  export declare const PI_PERMISSION_EXTENSION_SOURCE: string;
57
57
  export declare class PiAdapter implements CodingAgentAdapter {
58
58
  private modelGateway;
59
+ /**
60
+ * Refuse a turn with MCP servers before Pi starts when pi-mcp-adapter is
61
+ * not listed (I-4). Off in the cloud sandbox, whose image installs the
62
+ * adapter, so a check there can never block a working sandbox.
63
+ */
64
+ private readonly options;
59
65
  private sessions;
60
66
  private piExecutablePath;
61
67
  onDataAvailable?: (sessionId: string) => void;
@@ -66,7 +72,15 @@ export declare class PiAdapter implements CodingAgentAdapter {
66
72
  * its parts are already buffered. See `CodingAgentAdapter.idleIsTerminal`.
67
73
  */
68
74
  readonly idleIsTerminal = true;
69
- constructor(modelGateway: ModelGatewayConfigSource);
75
+ constructor(modelGateway: ModelGatewayConfigSource,
76
+ /**
77
+ * Refuse a turn with MCP servers before Pi starts when pi-mcp-adapter is
78
+ * not listed (I-4). Off in the cloud sandbox, whose image installs the
79
+ * adapter, so a check there can never block a working sandbox.
80
+ */
81
+ options?: {
82
+ checkMcpAdapter?: boolean;
83
+ });
70
84
  private agentDirectory;
71
85
  /** Identity of the Pi session store that can honour native session files. */
72
86
  backendInstanceId(): string;
@@ -78,6 +92,11 @@ export declare class PiAdapter implements CodingAgentAdapter {
78
92
  * value only to the child process.
79
93
  */
80
94
  private installPeakfloGateway;
95
+ /**
96
+ * The shared rule (`checkPiMcpAdapter`): false only when the agent
97
+ * directory's settings exist and do not list pi-mcp-adapter.
98
+ */
99
+ protected piMcpAdapterAvailable(): boolean;
81
100
  /** Replaceable in tests; the real loader needs the installed adapter. */
82
101
  protected loadMcpCacheApi: (agentDir: string) => PiMetadataCacheApi | null;
83
102
  /**
@@ -21,6 +21,7 @@ const string_decoder_1 = require("string_decoder");
21
21
  const util_1 = require("util");
22
22
  const coding_agent_adapter_1 = require("./coding-agent-adapter");
23
23
  const model_gateway_1 = require("./model-gateway");
24
+ const pi_mcp_adapter_check_1 = require("./pi-mcp-adapter-check");
24
25
  const pi_mcp_cache_seed_1 = require("./pi-mcp-cache-seed");
25
26
  const vendor_environment_1 = require("./vendor-environment");
26
27
  const browser_takeover_1 = require("../runtime/browser-takeover");
@@ -74,6 +75,8 @@ const piInstanceIdCache = new Map();
74
75
  */
75
76
  exports.MAX_PI_NAME_LENGTH = 64;
76
77
  exports.MAX_PI_MCP_SERVER_SLUG_LENGTH = 24;
78
+ /** Enough to hold "Unknown option: --mcp-config" split at any point. */
79
+ const STDERR_TAIL_CHARS = 64;
77
80
  /**
78
81
  * Electron's main macOS executable belongs to the foreground application
79
82
  * bundle. Reusing it as Node makes LaunchServices register every Pi process as
@@ -305,6 +308,7 @@ function resultText(result) {
305
308
  }
306
309
  class PiAdapter {
307
310
  modelGateway;
311
+ options;
308
312
  sessions = new Map();
309
313
  piExecutablePath = null;
310
314
  onDataAvailable;
@@ -315,8 +319,15 @@ class PiAdapter {
315
319
  * its parts are already buffered. See `CodingAgentAdapter.idleIsTerminal`.
316
320
  */
317
321
  idleIsTerminal = true;
318
- constructor(modelGateway) {
322
+ constructor(modelGateway,
323
+ /**
324
+ * Refuse a turn with MCP servers before Pi starts when pi-mcp-adapter is
325
+ * not listed (I-4). Off in the cloud sandbox, whose image installs the
326
+ * adapter, so a check there can never block a working sandbox.
327
+ */
328
+ options = {}) {
319
329
  this.modelGateway = modelGateway;
330
+ this.options = options;
320
331
  }
321
332
  agentDirectory() {
322
333
  return process.env.PI_CODING_AGENT_DIR || (0, path_1.join)((0, os_1.homedir)(), '.pi', 'agent');
@@ -429,6 +440,25 @@ class PiAdapter {
429
440
  (0, fs_1.chmodSync)(modelsPath, 0o600);
430
441
  return { apiKey: gateway.apiKey, providerModels: gateway.models ?? [] };
431
442
  }
443
+ /**
444
+ * The shared rule (`checkPiMcpAdapter`): false only when the agent
445
+ * directory's settings exist and do not list pi-mcp-adapter.
446
+ */
447
+ piMcpAdapterAvailable() {
448
+ return ((0, pi_mcp_adapter_check_1.checkPiMcpAdapter)({
449
+ env: process.env,
450
+ home: (0, os_1.homedir)(),
451
+ exists: fs_1.existsSync,
452
+ readFile: (path) => {
453
+ try {
454
+ return (0, fs_1.readFileSync)(path, 'utf8');
455
+ }
456
+ catch {
457
+ return null;
458
+ }
459
+ }
460
+ }) !== 'missing');
461
+ }
432
462
  /** Replaceable in tests; the real loader needs the installed adapter. */
433
463
  loadMcpCacheApi = pi_mcp_cache_seed_1.loadPiMetadataCacheApi;
434
464
  /**
@@ -723,6 +753,16 @@ class PiAdapter {
723
753
  : null;
724
754
  const executable = await this.findPiExecutable();
725
755
  const gateway = this.installPeakfloGateway();
756
+ // I-4: refuse BEFORE Pi starts when the turn needs `--mcp-config` and
757
+ // the agent directory's settings do not list pi-mcp-adapter. Pi would only
758
+ // exit with "Unknown option". Same rule as discovery (`checkPiMcpAdapter`),
759
+ // so a Pi that discovery reports Ready is never refused here.
760
+ if (this.options.checkMcpAdapter !== false &&
761
+ config.mcpServers &&
762
+ Object.keys(config.mcpServers).length > 0 &&
763
+ !this.piMcpAdapterAvailable()) {
764
+ throw new Error(pi_mcp_adapter_check_1.PI_MCP_ADAPTER_MISSING_ERROR);
765
+ }
726
766
  const endMcpConfig = steps?.begin('mcp_config_write');
727
767
  const mcpConfigPath = this.buildMcpConfig(config, seedOwner);
728
768
  endMcpConfig?.();
@@ -822,7 +862,17 @@ class PiAdapter {
822
862
  this.consumeStdout(session, session.stdoutDecoder.end(), true);
823
863
  });
824
864
  session.process.stderr.on('data', (chunk) => {
825
- const length = chunk.toString().trim().length;
865
+ const text = chunk.toString();
866
+ const length = text.trim().length;
867
+ // I-4: Pi without pi-mcp-adapter refuses `--mcp-config` and exits.
868
+ // Pi's text is never reported; a known pattern becomes a fixed
869
+ // sentence that names the fix, instead of "Pi process exited". A short
870
+ // tail of the previous chunk is kept in memory only, so the pattern is
871
+ // still found when Pi's message is split across two `data` events.
872
+ const window = `${session.stderrTail ?? ''}${text}`;
873
+ session.stderrTail = window.slice(-STDERR_TAIL_CHARS);
874
+ if (pi_mcp_adapter_check_1.PI_UNKNOWN_MCP_CONFIG_OPTION.test(window))
875
+ session.lastError = pi_mcp_adapter_check_1.PI_MCP_ADAPTER_MISSING_ERROR;
826
876
  if (length > 0)
827
877
  console.warn(`[PiAdapter/${session.id}] Pi wrote ${length} character(s) to stderr`);
828
878
  });
@@ -840,7 +890,8 @@ class PiAdapter {
840
890
  }
841
891
  if (!session.closing && session.status === 'busy') {
842
892
  session.status = 'error';
843
- session.lastError = `Pi exited before the turn completed (${signal || `code ${code}`})`;
893
+ if (session.lastError !== pi_mcp_adapter_check_1.PI_MCP_ADAPTER_MISSING_ERROR)
894
+ session.lastError = `Pi exited before the turn completed (${signal || `code ${code}`})`;
844
895
  }
845
896
  this.rejectPending(session, new Error(session.lastError ||
846
897
  (session.closing ? 'Pi process closed' : 'Pi process exited')));
@@ -0,0 +1,44 @@
1
+ /** The one-line fix, shown in the terminal and in the UI. */
2
+ export declare const PI_MCP_ADAPTER_INSTALL_COMMAND = "pi install npm:pi-mcp-adapter";
3
+ /**
4
+ * The structured reason code for "Pi needs pi-mcp-adapter". Sent on the wire
5
+ * as `harnesses[].reasonCode`; the control plane maps it to the fix it shows
6
+ * (`RUNNER_HARNESS_SETUP_FIXES` in `@pf-workflo/core`). The workflow-api
7
+ * contract test keeps the two packages in agreement.
8
+ */
9
+ export declare const PI_MCP_ADAPTER_REASON_CODE: "pi-mcp-adapter-missing";
10
+ /**
11
+ * Pi's agent directory: `PI_CODING_AGENT_DIR`, else `~/.pi/agent`. Resolved
12
+ * exactly like the harness's PiAdapter (`agentDirectory()`), which is the
13
+ * directory the harness hands to Pi, so this check reads the same settings
14
+ * file the turn uses. A `~` or relative value is not expanded, as there.
15
+ */
16
+ export declare function piAgentDirectory(env: NodeJS.ProcessEnv, home: string): string;
17
+ /**
18
+ * - `configured`: the settings list the adapter.
19
+ * - `missing`: no settings file, or settings that do not list it.
20
+ * - `unknown`: the settings file is not valid JSON, or `packages` /
21
+ * `extensions` are not lists (a format this check does not know). The
22
+ * check then claims nothing; Pi's own error is still mapped at run time.
23
+ */
24
+ export type PiMcpAdapterState = 'configured' | 'missing' | 'unknown';
25
+ export declare function isPiMcpAdapterSource(source: string): boolean;
26
+ export declare function piMcpAdapterState(agentDir: string, readFile: (path: string) => string | null, options?: {
27
+ exists?: (path: string) => boolean;
28
+ home?: string;
29
+ }): PiMcpAdapterState;
30
+ /**
31
+ * THE shared check: discovery, the routing drop (via discovery's reason
32
+ * code) and the turn preflight all use this one function.
33
+ */
34
+ export declare function checkPiMcpAdapter(deps: {
35
+ env: NodeJS.ProcessEnv;
36
+ home: string;
37
+ readFile: (path: string) => string | null;
38
+ /** Checks that a local-path source still exists. */
39
+ exists?: (path: string) => boolean;
40
+ }): PiMcpAdapterState;
41
+ /** Pi's own words when the adapter is absent and `--mcp-config` is passed. */
42
+ export declare const PI_UNKNOWN_MCP_CONFIG_OPTION: RegExp;
43
+ /** The turn error for that case: the cause and the fix, no Pi output. */
44
+ export declare const PI_MCP_ADAPTER_MISSING_ERROR = "Pi cannot load MCP tools: pi-mcp-adapter is not installed. Run `pi install npm:pi-mcp-adapter` on this machine, then try again.";
@@ -0,0 +1,143 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.PI_MCP_ADAPTER_MISSING_ERROR = exports.PI_UNKNOWN_MCP_CONFIG_OPTION = exports.PI_MCP_ADAPTER_REASON_CODE = exports.PI_MCP_ADAPTER_INSTALL_COMMAND = void 0;
4
+ exports.piAgentDirectory = piAgentDirectory;
5
+ exports.isPiMcpAdapterSource = isPiMcpAdapterSource;
6
+ exports.piMcpAdapterState = piMcpAdapterState;
7
+ exports.checkPiMcpAdapter = checkPiMcpAdapter;
8
+ /**
9
+ * IS pi-mcp-adapter SET UP FOR PI ON THIS MACHINE? — the ONE rule.
10
+ *
11
+ * Every Peakflo turn gives Pi its MCP servers with `--mcp-config <file>`.
12
+ * That flag is not Pi's: the pi-mcp-adapter extension adds it. Without the
13
+ * extension Pi stops at once with `Error: Unknown option: --mcp-config`, and
14
+ * the turn used to fail as "Pi process exited" (I-4).
15
+ *
16
+ * Pi loads a package only when its settings list it. `pi install
17
+ * npm:pi-mcp-adapter` (also what the 20x desktop installer runs) adds
18
+ * `npm:pi-mcp-adapter` to `<agent dir>/settings.json` (`packages`), and Pi
19
+ * installs a listed package that is missing on its next start. So "listed in
20
+ * the agent directory's settings" is the check.
21
+ *
22
+ * ONLY THE AGENT DIRECTORY COUNTS. A runner serves many workspaces, so
23
+ * discovery (which decides whether Pi is routed work at all) cannot see a
24
+ * project's `.pi/settings.json`. Discovery, the runner's routing drop and the
25
+ * turn preflight all call `checkPiMcpAdapter` below, so they cannot disagree:
26
+ * an adapter listed only in one project is "needs setup" everywhere.
27
+ *
28
+ * File reads only: this runs inside discovery, which must never start Pi twice.
29
+ */
30
+ const node_path_1 = require("node:path");
31
+ /** The one-line fix, shown in the terminal and in the UI. */
32
+ exports.PI_MCP_ADAPTER_INSTALL_COMMAND = 'pi install npm:pi-mcp-adapter';
33
+ /**
34
+ * The structured reason code for "Pi needs pi-mcp-adapter". Sent on the wire
35
+ * as `harnesses[].reasonCode`; the control plane maps it to the fix it shows
36
+ * (`RUNNER_HARNESS_SETUP_FIXES` in `@pf-workflo/core`). The workflow-api
37
+ * contract test keeps the two packages in agreement.
38
+ */
39
+ exports.PI_MCP_ADAPTER_REASON_CODE = 'pi-mcp-adapter-missing';
40
+ /**
41
+ * Pi's agent directory: `PI_CODING_AGENT_DIR`, else `~/.pi/agent`. Resolved
42
+ * exactly like the harness's PiAdapter (`agentDirectory()`), which is the
43
+ * directory the harness hands to Pi, so this check reads the same settings
44
+ * file the turn uses. A `~` or relative value is not expanded, as there.
45
+ */
46
+ function piAgentDirectory(env, home) {
47
+ return env.PI_CODING_AGENT_DIR || (0, node_path_1.join)(home, '.pi', 'agent');
48
+ }
49
+ /**
50
+ * The package source forms that ARE the adapter, anchored so a fork or an
51
+ * unrelated name that merely contains the text does not count:
52
+ * - `npm:pi-mcp-adapter` and `npm:pi-mcp-adapter@<version>`
53
+ * - a git or URL source whose last path segment is the package
54
+ * (`git:github.com/x/pi-mcp-adapter`, `https://…/pi-mcp-adapter.git@v2`)
55
+ * - a local path to the package directory or its entry file
56
+ * (`/opt/pi-mcp-adapter`, `./pi-mcp-adapter/index.ts`)
57
+ */
58
+ const NPM_SOURCE = /^npm:pi-mcp-adapter(?:@[\w.+^~*-]+)?$/;
59
+ /*
60
+ * Any host is accepted for a git/URL source on purpose: this reads the
61
+ * person's own Pi settings to tell whether Pi will load the adapter. It is a
62
+ * setup check, not a trust decision about where the package came from.
63
+ */
64
+ const PATH_OR_GIT_SOURCE = /(?:^|[/:])pi-mcp-adapter(?:\.git)?(?:\/(?:index\.(?:ts|js|mjs))?)?(?:@[\w.-]+)?$/;
65
+ function isPiMcpAdapterSource(source) {
66
+ const value = source.trim();
67
+ if (value.startsWith('npm:'))
68
+ return NPM_SOURCE.test(value);
69
+ return PATH_OR_GIT_SOURCE.test(value);
70
+ }
71
+ /** A local path source (not npm, git or a URL). */
72
+ function localPath(source) {
73
+ return /^(?:\/|\.\.?\/|~\/)/.test(source);
74
+ }
75
+ function sourceOf(value) {
76
+ const source = typeof value === 'string'
77
+ ? value
78
+ : value && typeof value === 'object'
79
+ ? value.source
80
+ : undefined;
81
+ return typeof source === 'string' ? source.trim() : undefined;
82
+ }
83
+ /**
84
+ * Names the adapter, and — for a local path, which Pi cannot reinstall the
85
+ * way it reinstalls a missing npm package — the path still exists.
86
+ */
87
+ function namesAdapter(value, agentDir, home, exists) {
88
+ const source = sourceOf(value);
89
+ if (!source || !isPiMcpAdapterSource(source))
90
+ return false;
91
+ if (!exists || !localPath(source))
92
+ return true;
93
+ const path = source.startsWith('~/')
94
+ ? home
95
+ ? (0, node_path_1.join)(home, source.slice(2))
96
+ : source
97
+ : source.startsWith('/')
98
+ ? source
99
+ : (0, node_path_1.join)(agentDir, source);
100
+ return exists(path);
101
+ }
102
+ function piMcpAdapterState(agentDir, readFile, options = {}) {
103
+ const text = readFile((0, node_path_1.join)(agentDir, 'settings.json'));
104
+ if (text === null)
105
+ return 'missing';
106
+ let settings;
107
+ try {
108
+ settings = JSON.parse(text);
109
+ }
110
+ catch {
111
+ return 'unknown';
112
+ }
113
+ if (!settings || typeof settings !== 'object')
114
+ return 'unknown';
115
+ const { packages, extensions } = settings;
116
+ // A shape this check does not know (a future Pi format): claim nothing,
117
+ // rather than block a Pi that may work. Absent keys are Pi's own way of
118
+ // saying "nothing installed", so they still mean `missing`.
119
+ if ((packages !== undefined && !Array.isArray(packages)) ||
120
+ (extensions !== undefined && !Array.isArray(extensions)))
121
+ return 'unknown';
122
+ const listed = [
123
+ ...(Array.isArray(packages) ? packages : []),
124
+ ...(Array.isArray(extensions) ? extensions : [])
125
+ ];
126
+ return listed.some((value) => namesAdapter(value, agentDir, options.home, options.exists))
127
+ ? 'configured'
128
+ : 'missing';
129
+ }
130
+ /**
131
+ * THE shared check: discovery, the routing drop (via discovery's reason
132
+ * code) and the turn preflight all use this one function.
133
+ */
134
+ function checkPiMcpAdapter(deps) {
135
+ return piMcpAdapterState(piAgentDirectory(deps.env, deps.home), deps.readFile, {
136
+ exists: deps.exists,
137
+ home: deps.home
138
+ });
139
+ }
140
+ /** Pi's own words when the adapter is absent and `--mcp-config` is passed. */
141
+ exports.PI_UNKNOWN_MCP_CONFIG_OPTION = /Unknown option:\s*--mcp-config/;
142
+ /** The turn error for that case: the cause and the fix, no Pi output. */
143
+ exports.PI_MCP_ADAPTER_MISSING_ERROR = `Pi cannot load MCP tools: pi-mcp-adapter is not installed. Run \`${exports.PI_MCP_ADAPTER_INSTALL_COMMAND}\` on this machine, then try again.`;
@@ -60,6 +60,7 @@ interface ComputerHarnessStatus {
60
60
  runnable: boolean;
61
61
  transient?: boolean;
62
62
  reason?: string;
63
+ reasonCode?: string;
63
64
  }
64
65
  export interface ConnectDeps {
65
66
  fetchImpl: typeof fetch;
@@ -36,6 +36,7 @@ const capabilities_1 = require("../capabilities");
36
36
  const control_plane_1 = require("../control-plane");
37
37
  const credential_store_1 = require("../credential-store");
38
38
  const browser_enrol_1 = require("../enrol/browser-enrol");
39
+ const pi_mcp_adapter_check_1 = require("../adapters/pi-mcp-adapter-check");
39
40
  const harness_discovery_1 = require("../harness-discovery");
40
41
  const service_1 = require("../service");
41
42
  const vendor_backends_1 = require("../vendor-backends");
@@ -230,7 +231,7 @@ function logComputerResult(deps, added, report) {
230
231
  ? exports.VENDOR_SETUP[item.name]
231
232
  : {
232
233
  install: item.name === 'pi'
233
- ? 'npm install -g @mariozechner/pi-coding-agent'
234
+ ? 'npm install -g @earendil-works/pi-coding-agent'
234
235
  : 'npm install -g opencode-ai',
235
236
  login: item.name === 'pi'
236
237
  ? 'Open pi and choose a model provider.'
@@ -241,7 +242,9 @@ function logComputerResult(deps, added, report) {
241
242
  : !item.installed
242
243
  ? `not installed. ${help.install}`
243
244
  : !item.usable
244
- ? `${item.reason ? printable(item.reason) : 'not signed in.'} ${help.login}`
245
+ ? item.reasonCode === pi_mcp_adapter_check_1.PI_MCP_ADAPTER_REASON_CODE
246
+ ? `needs setup. Run \`${pi_mcp_adapter_check_1.PI_MCP_ADAPTER_INSTALL_COMMAND}\` on this machine.`
247
+ : `${item.reason ? printable(item.reason) : 'not signed in.'} ${help.login}`
245
248
  : !item.runnable
246
249
  ? 'runner support is unavailable. Reinstall the runner.'
247
250
  : 'not ready. Check Machines for the next discovery result.';
@@ -269,6 +272,8 @@ async function runConnectInner(args, deps) {
269
272
  ['installed', 'usable', 'runnable'].every((key) => typeof item[key] ===
270
273
  'boolean') &&
271
274
  (item.reason === undefined || typeof item.reason === 'string') &&
275
+ (item.reasonCode === undefined ||
276
+ typeof item.reasonCode === 'string') &&
272
277
  (item.transient === undefined ||
273
278
  typeof item.transient === 'boolean')) ||
274
279
  (prior.startArgs !== undefined &&
@@ -554,6 +559,10 @@ function defaultConnectDeps(context) {
554
559
  report = await (0, harness_discovery_1.discoverHarnesses)({
555
560
  runnableBackends: COMPUTER_BACKENDS
556
561
  });
562
+ // A Pi without pi-mcp-adapter cannot run a turn: not routable.
563
+ // Always applied here: `connect` registers a personal computer,
564
+ // never a sandbox (which installs the adapter in its image).
565
+ capabilities.backends = (0, harness_discovery_1.dropPiWithoutMcpAdapter)(capabilities.backends, report);
557
566
  for (const h of report) {
558
567
  if (h.installed &&
559
568
  h.usable &&
@@ -591,13 +600,14 @@ function defaultConnectDeps(context) {
591
600
  return {
592
601
  runnerId,
593
602
  connectedBackends: response.connectedBackends,
594
- report: report.map(({ name, installed, usable, runnable, transient, reason }) => ({
603
+ report: report.map(({ name, installed, usable, runnable, transient, reason, reasonCode }) => ({
595
604
  name,
596
605
  installed,
597
606
  usable,
598
607
  runnable,
599
608
  transient,
600
- reason
609
+ reason,
610
+ reasonCode
601
611
  }))
602
612
  };
603
613
  },
@@ -72,6 +72,7 @@ export declare const REASONS: {
72
72
  readonly codexSignIn: "Not signed in. Run `codex login` on this machine.";
73
73
  readonly claudeSignIn: "Not signed in. Run `claude auth login` on this machine.";
74
74
  readonly cursorSignIn: "Not signed in. Run `cursor-agent login` on this machine.";
75
+ readonly piMcpAdapter: "Needs setup. Run `pi install npm:pi-mcp-adapter` on this machine.";
75
76
  };
76
77
  /** 20x `CLAUDE_MODELS`. Claude Code has no command that lists models. */
77
78
  export declare const CLAUDE_STATIC_MODELS: ReadonlyArray<RunnerHarnessModel>;
@@ -174,3 +175,18 @@ export declare const KNOWN_HARNESSES: ReadonlyArray<{
174
175
  * returned.
175
176
  */
176
177
  export declare function discoverHarnesses(options?: DiscoverHarnessesOptions): Promise<RunnerHarness[]>;
178
+ /**
179
+ * `backends` without Pi while discovery says Pi's pi-mcp-adapter is missing
180
+ * (reason code `pi-mcp-adapter-missing`, from `checkPiMcpAdapter`). A Pi turn
181
+ * there cannot start (I-4), so it must not be routed here: the person sees
182
+ * "needs setup" and the fix instead of a failed turn. Returns a NEW list; the
183
+ * input is not changed. Once the adapter is installed, the next discovery
184
+ * pass clears the code and Pi is routed again.
185
+ *
186
+ * Callers decide where it applies: the desktop runner (`harness.ts`, not the
187
+ * sandbox, whose image installs and checks the adapter at build time) and the
188
+ * computer `connect` registration (always a desktop machine).
189
+ */
190
+ export declare function dropPiWithoutMcpAdapter<T extends {
191
+ name: string;
192
+ }>(backends: readonly T[], report: readonly RunnerHarness[] | null | undefined): T[];
@@ -40,10 +40,12 @@ exports.parseCodexDefaultModel = parseCodexDefaultModel;
40
40
  exports.parseCursorModels = parseCursorModels;
41
41
  exports.parseOpencodeModels = parseOpencodeModels;
42
42
  exports.discoverHarnesses = discoverHarnesses;
43
+ exports.dropPiWithoutMcpAdapter = dropPiWithoutMcpAdapter;
43
44
  const node_child_process_1 = require("node:child_process");
44
45
  const node_fs_1 = require("node:fs");
45
46
  const node_os_1 = require("node:os");
46
47
  const node_path_1 = require("node:path");
48
+ const pi_mcp_adapter_check_1 = require("./adapters/pi-mcp-adapter-check");
47
49
  const harness_path_1 = require("./harness-path");
48
50
  /**
49
51
  * One command: `--version`, a status check, or a model listing.
@@ -93,7 +95,12 @@ exports.REASONS = {
93
95
  signInUnknown: 'Sign-in could not be confirmed.',
94
96
  codexSignIn: 'Not signed in. Run `codex login` on this machine.',
95
97
  claudeSignIn: 'Not signed in. Run `claude auth login` on this machine.',
96
- cursorSignIn: 'Not signed in. Run `cursor-agent login` on this machine.'
98
+ cursorSignIn: 'Not signed in. Run `cursor-agent login` on this machine.',
99
+ /*
100
+ * Starts with "Needs setup." on purpose: the control plane maps exactly
101
+ * this sentence to the one-line fix it shows in the UI.
102
+ */
103
+ piMcpAdapter: `Needs setup. Run \`${pi_mcp_adapter_check_1.PI_MCP_ADAPTER_INSTALL_COMMAND}\` on this machine.`
97
104
  };
98
105
  /* -------------------------------------------------------------------------- */
99
106
  /* Static model lists — copied from 20x `src/renderer/src/types/index.ts` */
@@ -551,9 +558,24 @@ const PI = {
551
558
  label: 'Pi',
552
559
  commands: ['pi'],
553
560
  // Pi needs no login of its own here: each turn brings the Peakflo model
554
- // gateway and a key for it.
555
- async checkAuth() {
556
- return { usable: true };
561
+ // gateway and a key for it. It DOES need pi-mcp-adapter: every turn passes
562
+ // `--mcp-config`, which only that extension understands, and without it Pi
563
+ // exits before the turn starts (I-4). So a Pi without the adapter is "needs
564
+ // setup", never usable, and the runner does not route Pi turns to it.
565
+ async checkAuth({ deps }) {
566
+ const state = (0, pi_mcp_adapter_check_1.checkPiMcpAdapter)({
567
+ env: deps.env,
568
+ home: deps.home,
569
+ readFile: (path) => deps.readFile(path),
570
+ exists: (path) => deps.exists(path)
571
+ });
572
+ return state === 'missing'
573
+ ? {
574
+ usable: false,
575
+ reason: exports.REASONS.piMcpAdapter,
576
+ reasonCode: pi_mcp_adapter_check_1.PI_MCP_ADAPTER_REASON_CODE
577
+ }
578
+ : { usable: true };
557
579
  },
558
580
  // The runner already probes Pi's models for `backends[].models`
559
581
  // (model-probe.ts). The caller copies that list in, so Pi is not started
@@ -645,6 +667,8 @@ async function probeHarness(spec, entry, deps, commandTimeoutMs, isExpired, prog
645
667
  entry.usable = auth.usable;
646
668
  if (!auth.usable && auth.reason)
647
669
  entry.reason = auth.reason;
670
+ if (!auth.usable && auth.reasonCode)
671
+ entry.reasonCode = auth.reasonCode;
648
672
  if (!auth.usable && auth.transient)
649
673
  entry.transient = true;
650
674
  /*
@@ -753,6 +777,7 @@ async function discoverHarnesses(options = {}) {
753
777
  // Found, and the checks did not finish in time: "will be tried again".
754
778
  report.usable = false;
755
779
  report.reason = exports.REASONS.discoveryTimedOut;
780
+ delete report.reasonCode;
756
781
  if (report.installed)
757
782
  report.transient = true;
758
783
  delete report.models;
@@ -761,6 +786,7 @@ async function discoverHarnesses(options = {}) {
761
786
  else if (outcome === 'failed' && !progress.stateKnown) {
762
787
  report.usable = false;
763
788
  report.reason = exports.REASONS.discoveryFailed;
789
+ delete report.reasonCode;
764
790
  delete report.transient;
765
791
  delete report.models;
766
792
  delete report.modelSource;
@@ -770,3 +796,21 @@ async function discoverHarnesses(options = {}) {
770
796
  return report;
771
797
  });
772
798
  }
799
+ /**
800
+ * `backends` without Pi while discovery says Pi's pi-mcp-adapter is missing
801
+ * (reason code `pi-mcp-adapter-missing`, from `checkPiMcpAdapter`). A Pi turn
802
+ * there cannot start (I-4), so it must not be routed here: the person sees
803
+ * "needs setup" and the fix instead of a failed turn. Returns a NEW list; the
804
+ * input is not changed. Once the adapter is installed, the next discovery
805
+ * pass clears the code and Pi is routed again.
806
+ *
807
+ * Callers decide where it applies: the desktop runner (`harness.ts`, not the
808
+ * sandbox, whose image installs and checks the adapter at build time) and the
809
+ * computer `connect` registration (always a desktop machine).
810
+ */
811
+ function dropPiWithoutMcpAdapter(backends, report) {
812
+ const pi = report?.find((harness) => harness.name === 'pi');
813
+ if (pi?.reasonCode !== pi_mcp_adapter_check_1.PI_MCP_ADAPTER_REASON_CODE)
814
+ return [...backends];
815
+ return backends.filter((backend) => backend.name !== 'pi');
816
+ }
package/dist/harness.js CHANGED
@@ -1075,6 +1075,11 @@ class Harness {
1075
1075
  return;
1076
1076
  }
1077
1077
  capabilities.vendorHarnesses = this.options.vendorHarnesses ?? [];
1078
+ // Desktop/VM only: a sandbox image installs pi-mcp-adapter and checks it
1079
+ // at build time, and its backend probe stays the authority there.
1080
+ if (this.options.runtime !== 'sandbox') {
1081
+ capabilities.backends = (0, harness_discovery_1.dropPiWithoutMcpAdapter)(capabilities.backends, this.harnessReport);
1082
+ }
1078
1083
  const blocked = this.addVendorBackends(capabilities);
1079
1084
  const harnesses = this.harnessReport.map((harness) => {
1080
1085
  const backend = capabilities.backends.find((candidate) => candidate.name === harness.name);
@@ -1103,6 +1108,7 @@ class Harness {
1103
1108
  version: backend.version ?? harness.version ?? null
1104
1109
  };
1105
1110
  delete entry.reason;
1111
+ delete entry.reasonCode;
1106
1112
  delete entry.transient;
1107
1113
  if (!entry.models && backend.models && backend.models.length > 0) {
1108
1114
  entry.models = backend.models.map(({ id, name }) => ({ id, name }));
package/dist/types.d.ts CHANGED
@@ -293,6 +293,13 @@ export interface RunnerHarness {
293
293
  * account name or a token.
294
294
  */
295
295
  reason?: string;
296
+ /**
297
+ * A machine-readable code for `reason`, from a closed set, when the control
298
+ * plane can offer a fixed one-line fix for it. Today only
299
+ * `'pi-mcp-adapter-missing'` (Pi needs `pi install npm:pi-mcp-adapter`).
300
+ * Optional: an older control plane ignores it and shows `reason`.
301
+ */
302
+ reasonCode?: 'pi-mcp-adapter-missing';
296
303
  /**
297
304
  * The check of this harness DID NOT FINISH (it timed out), so `usable:
298
305
  * false` here is not a statement about the harness. The runner checks again
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@peakflo/agent-harness",
3
- "version": "0.2.30-rc.2",
3
+ "version": "0.2.31-rc.1",
4
4
  "description": "Headless Peakflo coding-agent harness. One codebase, three hosting modes: a Daytona cloud sandbox, a customer VM, and the 20x desktop.",
5
5
  "license": "MIT",
6
6
  "type": "commonjs",