@peakflo/agent-harness 0.2.22-rc.1 → 0.2.24-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
@@ -18,7 +18,9 @@ Run a Peakflo coding agent on your machine.
18
18
 
19
19
  ## Quick start
20
20
 
21
- Use Node.js 22.19 or newer and install Git. The runner checks the Node.js
21
+ Use a patched Node.js release from the `engines.node` range in this package's
22
+ `package.json` (`npm view @peakflo/agent-harness engines.node`) and install Git.
23
+ The runner checks the Node.js
22
24
  version when it starts and stops with one line if it is older (see
23
25
  "Troubleshooting"). Install the Pi coding agent once:
24
26
 
@@ -54,26 +56,49 @@ Optional flags include `--health-port <port>`, `--runtime <desktop|self-hosted>`
54
56
 
55
57
  ## Connect your own agent in one command
56
58
 
57
- Agents → "Connect your own agent" in Spaces (and the Welcome window during
58
- onboarding) shows one command for Codex, Claude Code, or
59
- Cursor, for example:
59
+ Choose **Connect this computer** in Spaces. Copy its command:
60
60
 
61
61
  ```sh
62
- npx --yes @peakflo/agent-harness@<version> connect claude-code --connection <id>
62
+ npx --yes @peakflo/agent-harness@<version> connect --connection <id>
63
63
  ```
64
64
 
65
- `connect` checks that the vendor CLI is installed and signed in, opens your
66
- browser so you can approve this computer (you must be signed in as the same
67
- user and company), registers the computer as your personal runner for that
68
- vendor only, and installs a background service for it. The command holds no
69
- secret: `--connection` is a public id, and the one-time enrolment token is
70
- fetched only after the approval, with a PKCE verifier that never leaves the
71
- process. If port 7777 or 7780 is in use, `connect` picks free ports.
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.
69
+ Agents allow actions by default. Change permissions in the editor, or add
70
+ `--ask` to the command to start in Ask mode. `--all` remains a compatibility
71
+ alias; it is no longer needed.
72
+
73
+ The terminal lists connected agents and skipped backends, with install or
74
+ sign-in help. Pi and OpenCode have no reliable subscription sign-in check;
75
+ their result means available, not proof of a vendor subscription.
76
+
77
+ The computer has one runner and service per API, company, and local account.
78
+ A saved random computer ID lets a new approved connection reuse that runner.
79
+ Repeating the same command uses its saved connection record and creates no
80
+ new token or runner. The command contains a connection ID, not a secret.
81
+ Enrolment uses browser approval and PKCE. The single-use enrolment token is
82
+ never saved. The runner credential is saved with file mode 0600.
83
+
84
+ While idle, the runner checks again every five minutes. Newly installed or
85
+ signed-in harnesses connect automatically on the same runner. Machines →
86
+ Detected backends shows status and install/sign-in help. No extra action,
87
+ connection token, or runner is needed. Existing agent settings stay unchanged.
88
+
89
+ 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:
92
+
93
+ ```sh
94
+ npx --yes @peakflo/agent-harness@<version> connect claude-code --connection <id>
95
+ ```
72
96
 
73
- Each vendor gets its own service and workspace under
74
- `~/.pf-agent-harness/connect/<vendor>`. Check or remove one with
75
- `service status --vendor <vendor>` or `service uninstall --vendor <vendor>`.
76
- `connect` needs macOS or Linux.
97
+ The legacy vendor path has one service and workspace per vendor under
98
+ `~/.pf-agent-harness/connect/<vendor>`. The computer path uses a separate
99
+ account-scoped service. Existing vendor runners are not silently combined.
100
+ Use **Reconnect** on an old machine to move its agents to the new computer
101
+ connection while keeping their IDs, names, and history.
77
102
 
78
103
  ## Run after you close the terminal
79
104
 
@@ -321,8 +346,9 @@ public registry for this one command:
321
346
  npx --@peakflo:registry=https://registry.npmjs.org @peakflo/agent-harness@latest start
322
347
  ```
323
348
 
324
- **"pf-agent-harness needs Node.js 22.19 or newer".** Switch to a newer
325
- Node.js, for example `nvm install 22 && nvm use 22`, and start again. npm only
349
+ **"pf-agent-harness needs a patched Node.js release (...)".** The message
350
+ lists the supported range; it is the `engines.node` field of `package.json`.
351
+ Switch to a Node.js inside that range, for example `nvm install 22 && nvm use 22`, and start again. npm only
326
352
  prints an `EBADENGINE` warning for an older Node.js and installs anyway; the
327
353
  runner is what stops. The requirement comes from Pi, which the runner starts
328
354
  with the same Node.js. To start on an older Node.js at your own risk, set
@@ -31,6 +31,7 @@ exports.AcpAdapter = exports.ACP_SESSION_START_TIMEOUT_MS = void 0;
31
31
  const child_process_1 = require("child_process");
32
32
  const crypto_1 = require("crypto");
33
33
  const child_stream_guards_1 = require("../runtime/child-stream-guards");
34
+ const permission_mode_1 = require("../runtime/permission-mode");
34
35
  const path_1 = require("path");
35
36
  const util_1 = require("util");
36
37
  const coding_agent_adapter_1 = require("./coding-agent-adapter");
@@ -1275,10 +1276,10 @@ class AcpAdapter {
1275
1276
  // its own config on the runner. A person answering from the control plane
1276
1277
  // is offered the one-time answers only.
1277
1278
  const oneTimeOptions = allApprovalOptions.filter((option) => !isStandingAcpOption(option));
1278
- const approvalOptions = this.agentType === 'cursor' && session.config.permissionMode !== 'allow' && oneTimeOptions.length > 0
1279
+ const approvalOptions = this.agentType === 'cursor' && (0, permission_mode_1.effectivePermissionMode)(session.config) === 'ask' && oneTimeOptions.length > 0
1279
1280
  ? oneTimeOptions
1280
1281
  : allApprovalOptions;
1281
- if (session.config.permissionMode === 'allow') {
1282
+ if ((0, permission_mode_1.effectivePermissionMode)(session.config) === 'allow') {
1282
1283
  // Cursor saves "allow always" as a standing rule (seen: one bypass
1283
1284
  // turn added Shell(echo) and Shell(cat)). That rule could affect later
1284
1285
  // turns. Every request is approved once instead.
@@ -696,10 +696,10 @@ class ClaudeCodeAdapter {
696
696
  * onto — see runtime/permission-mode.ts for the table. Claude Code is the
697
697
  * one backend that takes all four natively, so nothing is lost here.
698
698
  *
699
- * A config with NO permissionMode maps to 'default', NOT to
700
- * 'bypassPermissions'. That is deliberate: the old behaviour must not be
701
- * reachable by omission, or every caller that forgets the field silently
702
- * restores the defect.
699
+ * A config with NO permissionMode gets the new-agent default,
700
+ * 'bypassPermissions' (owner decision: "Allow by default"). The fix for
701
+ * G1 is that an explicit 'ask' is now honoured — the user's choice is
702
+ * read, not hardcoded — so 'default', 'plan' and 'acceptEdits' still ask.
703
703
  */
704
704
  permissionMode: claudePermissionMode,
705
705
  // ONLY for the mode that actually asks for it. The SDK requires this flag
@@ -54,6 +54,7 @@ exports.codexApprovalPolicy = codexApprovalPolicy;
54
54
  const child_process_1 = require("child_process");
55
55
  const fs_1 = require("fs");
56
56
  const child_stream_guards_1 = require("../runtime/child-stream-guards");
57
+ const permission_mode_1 = require("../runtime/permission-mode");
57
58
  const path_1 = require("path");
58
59
  const util_1 = require("util");
59
60
  const coding_agent_adapter_1 = require("./coding-agent-adapter");
@@ -128,11 +129,11 @@ function elicitationFormFields(params) {
128
129
  return [...new Set([...required, ...properties])];
129
130
  }
130
131
  function codexApprovalPolicy(config) {
131
- // `'allow'` is what `mapPermissionMode` makes of the agent's
132
- // `bypassPermissions` ("Don't ask for permission"), and of nothing else.
133
- // Only an explicit "allow" runs without asking. Anything else, including a
134
- // value this build does not know, asks.
135
- return config.permissionMode === 'allow' ? 'never' : 'untrusted';
132
+ // `'ask'` is what `mapPermissionMode` makes of an asking mode (default,
133
+ // plan, acceptEdits, or a value this build does not know); that asks before
134
+ // every command not known to be read-only. `'allow'`, and a config with no
135
+ // mode at all (the new-agent default), runs without asking.
136
+ return (0, permission_mode_1.effectivePermissionMode)(config) === 'ask' ? 'untrusted' : 'never';
136
137
  }
137
138
  const MAX_IPC_TOOL_INPUT_CHARS = 20_000;
138
139
  const MAX_IPC_TOOL_OUTPUT_CHARS = 100_000;
@@ -995,7 +996,7 @@ class CodexAppServerAdapter {
995
996
  this.addEvent(session, notification);
996
997
  }
997
998
  handleApprovalRequest(session, request, params) {
998
- if (session.config.permissionMode === 'allow') {
999
+ if ((0, permission_mode_1.effectivePermissionMode)(session.config) === 'allow') {
999
1000
  const responseKind = this.getApprovalResponseKind(request.method);
1000
1001
  const selected = responseKind === 'execCommand' ? 'approved' : 'accept';
1001
1002
  this.sendRpcResponse(session, request.id, this.buildApprovalResponse(responseKind, selected, true, params.permissions));
@@ -17,6 +17,7 @@ exports.resolveCursorModeValue = resolveCursorModeValue;
17
17
  exports.isCursorPlanLimitReply = isCursorPlanLimitReply;
18
18
  exports.mayBecomeCursorPlanLimitReply = mayBecomeCursorPlanLimitReply;
19
19
  exports.describeAcpRpcError = describeAcpRpcError;
20
+ const permission_mode_1 = require("../runtime/permission-mode");
20
21
  function isRecord(value) {
21
22
  return typeof value === 'object' && value !== null && !Array.isArray(value);
22
23
  }
@@ -126,8 +127,10 @@ function resolveCursorModelValue(model, sessionResult) {
126
127
  * A permission request Cursor does raise is still put to the person.
127
128
  */
128
129
  function cursorModeFor(config) {
129
- // Only an explicit "allow" may act. An unknown value is treated as asking.
130
- if (config.permissionMode === 'allow')
130
+ // Only an explicit "ask" restricts Cursor. A config with no mode gets the
131
+ // new-agent default ("allow"); `mapPermissionMode` already turned an unknown
132
+ // lease value into "ask".
133
+ if ((0, permission_mode_1.effectivePermissionMode)(config) === 'allow')
131
134
  return 'agent';
132
135
  return config.sandboxMode === 'read-only' ? 'plan' : 'ask';
133
136
  }
@@ -25,6 +25,7 @@ const opencode_server_policy_1 = require("./opencode-server-policy");
25
25
  const opencode_config_1 = require("./opencode-config");
26
26
  const model_gateway_1 = require("./model-gateway");
27
27
  const coding_agent_adapter_1 = require("./coding-agent-adapter");
28
+ const permission_mode_1 = require("../runtime/permission-mode");
28
29
  /**
29
30
  * A REAL dynamic ESM import, which `await import(...)` is not in this package.
30
31
  *
@@ -1110,7 +1111,7 @@ class OpencodeAdapter {
1110
1111
  * completion in `ask` mode and NOT ONE raised a prompt, while the file on
1111
1112
  * disk said `"bash": "ask"` the whole time. Do not move this below.
1112
1113
  */
1113
- this.writeSessionPermissionConfig(config.workspaceDir, config.permissionMode || 'ask');
1114
+ this.writeSessionPermissionConfig(config.workspaceDir, (0, permission_mode_1.effectivePermissionMode)(config));
1114
1115
  await this.ensureServerRunning(config.serverUrl || DEFAULT_SERVER_URL, config.environment);
1115
1116
  // Config is pushed once on first server connection (ensureServerRunning).
1116
1117
  // Subsequent config changes (key rotation, settings edit) go through
@@ -1164,7 +1165,7 @@ class OpencodeAdapter {
1164
1165
  this.writeTillDoneSessionConfig(ocSessionId, config.tillDone !== false);
1165
1166
  this.clients.set(ocSessionId, ocClient);
1166
1167
  this.promptClients.set(ocSessionId, promptClient);
1167
- this.sessionPermissionModes.set(ocSessionId, config.permissionMode || 'ask');
1168
+ this.sessionPermissionModes.set(ocSessionId, (0, permission_mode_1.effectivePermissionMode)(config));
1168
1169
  if (config.workspaceDir)
1169
1170
  this.sessionWorkspaceDirs.set(ocSessionId, config.workspaceDir);
1170
1171
  if (config.mcpServers)
@@ -1327,7 +1328,7 @@ class OpencodeAdapter {
1327
1328
  * An `allow` session is the one case where approving is what the user
1328
1329
  * actually chose, and it matches what `handleServerEvent` does live.
1329
1330
  */
1330
- const resumeMode = config.permissionMode || 'ask';
1331
+ const resumeMode = (0, permission_mode_1.effectivePermissionMode)(config);
1331
1332
  const staleReply = resumeMode === 'allow' ? 'always' : 'reject';
1332
1333
  const listResult = await v2.permission.list({});
1333
1334
  if (listResult.data && Array.isArray(listResult.data)) {
@@ -1353,7 +1354,7 @@ class OpencodeAdapter {
1353
1354
  }
1354
1355
  this.clients.set(sessionId, ocClient);
1355
1356
  this.promptClients.set(sessionId, promptClient);
1356
- this.sessionPermissionModes.set(sessionId, config.permissionMode || 'ask');
1357
+ this.sessionPermissionModes.set(sessionId, (0, permission_mode_1.effectivePermissionMode)(config));
1357
1358
  if (config.workspaceDir)
1358
1359
  this.sessionWorkspaceDirs.set(sessionId, config.workspaceDir);
1359
1360
  if (config.mcpServers)
@@ -1361,7 +1362,7 @@ class OpencodeAdapter {
1361
1362
  // WIRE 5, on the resume path too. A workspace is rebuilt per turn, so a
1362
1363
  // resumed session that skipped this would silently run unrestricted — the
1363
1364
  // defect returning on the SECOND message of every conversation.
1364
- this.writeSessionPermissionConfig(config.workspaceDir, config.permissionMode || 'ask');
1365
+ this.writeSessionPermissionConfig(config.workspaceDir, (0, permission_mode_1.effectivePermissionMode)(config));
1365
1366
  this.writeTillDoneSessionConfig(sessionId, config.tillDone !== false);
1366
1367
  // Fetch existing messages
1367
1368
  const messagesResult = await ocClient.session.messages({
@@ -2612,7 +2613,7 @@ class OpencodeAdapter {
2612
2613
  }
2613
2614
  console.log(`[OpencodeAdapter] Permission requested: ${permission} for session ${sessionID} (${permissionId}) patterns=${patterns.join(', ')}`);
2614
2615
  // Auto-approve if the agent's permission mode is 'allow'
2615
- const mode = this.sessionPermissionModes.get(sessionID) || 'ask';
2616
+ const mode = this.sessionPermissionModes.get(sessionID) || 'allow';
2616
2617
  if (mode === 'allow') {
2617
2618
  console.log(`[OpencodeAdapter] Auto-approving permission ${permissionId} (permissionMode=allow)`);
2618
2619
  this.autoApprovePermission(sessionID, permissionId).catch((err) => {
@@ -26,6 +26,7 @@ const vendor_environment_1 = require("./vendor-environment");
26
26
  const browser_takeover_1 = require("../runtime/browser-takeover");
27
27
  const cold_start_steps_1 = require("../runtime/cold-start-steps");
28
28
  const dev_server_guard_1 = require("../runtime/dev-server-guard");
29
+ const permission_mode_1 = require("../runtime/permission-mode");
29
30
  const execFileAsync = (0, util_1.promisify)(child_process_1.execFile);
30
31
  const RPC_TIMEOUT_MS = 15_000;
31
32
  const MAX_BUFFERED_PARTS = 1_000;
@@ -569,7 +570,7 @@ class PiAdapter {
569
570
  ...(config.environment ?? {}),
570
571
  ...(config.secretEnvVars ?? {}),
571
572
  ...(gateway ? { PEAKFLO_AI_GATEWAY_API_KEY: gateway.apiKey } : {}),
572
- [PI_PERMISSION_MODE_ENV]: config.permissionMode ?? 'ask'
573
+ [PI_PERMISSION_MODE_ENV]: (0, permission_mode_1.effectivePermissionMode)(config)
573
574
  };
574
575
  delete env.AI_AGENT;
575
576
  delete env.PI_CODING_AGENT;
@@ -1079,7 +1080,8 @@ class PiAdapter {
1079
1080
  ? event.options.filter((option) => typeof option === 'string')
1080
1081
  : []
1081
1082
  };
1082
- if (method === 'confirm' && session.config.permissionMode === 'allow') {
1083
+ if (method === 'confirm' &&
1084
+ (0, permission_mode_1.effectivePermissionMode)(session.config) === 'allow') {
1083
1085
  this.sendRecord(session, {
1084
1086
  type: 'extension_ui_response',
1085
1087
  id,
package/dist/cli.js CHANGED
@@ -96,7 +96,8 @@ Options:
96
96
  default for desktop/self-hosted; never runs
97
97
  in a sandbox.
98
98
 
99
- Needs Node.js 22.19 or newer; start stops with one line on an older one.
99
+ Needs a Node.js release in the engines.node range of package.json; start stops
100
+ with one line (exit code 1) that names the range on any other release.
100
101
  PF_ALLOW_UNSUPPORTED_NODE=1 starts anyway, at your own risk.
101
102
 
102
103
  In a managed sandbox pf-bootstrap hands the token over a private IPC channel,
@@ -28,14 +28,17 @@ export declare const VENDOR_SETUP: Record<VendorBackend, {
28
28
  install: string;
29
29
  login: string;
30
30
  }>;
31
+ export type ConnectTarget = VendorBackend | 'computer';
31
32
  export interface ConnectArgs {
32
- vendor: VendorBackend;
33
+ vendor: ConnectTarget;
34
+ all?: boolean;
35
+ askFirst?: boolean;
33
36
  connection: string;
34
37
  controlPlane: string;
35
38
  appUrl?: string;
36
39
  openBrowser: boolean;
37
40
  }
38
- export declare const CONNECT_USAGE = "Usage: pf-agent-harness connect <codex|claude-code|cursor> --connection <id> [--control-plane <url>]\n\nCopy this command from Agents \u2192 \"Connect your own agent\" in Spaces (or\n\"Reconnect\" on your machine there). It approves this computer\nin your browser, connects the agent as your personal agent, and keeps it\nrunning in the background.";
41
+ export declare const CONNECT_USAGE = "Usage: pf-agent-harness connect [codex|claude-code|cursor] [--all] [--ask] --connection <id> [--control-plane <url>]\n\nCopy this command from Agents \u2192 \"Connect this computer\" in Spaces (or\n\"Reconnect\" on your machine there). It approves this computer\nin your browser, connects all usable personal agents, and keeps the runner\nrunning in the background.";
39
42
  export declare function parseConnectArgs(argv: string[], env?: NodeJS.ProcessEnv): ConnectArgs;
40
43
  /** The machine name the approval page shows. Must match the API's rule. */
41
44
  export declare function machineName(raw: string): string;
@@ -50,6 +53,14 @@ export interface ServicePorts {
50
53
  healthPort: number;
51
54
  proxyPort: number;
52
55
  }
56
+ interface ComputerHarnessStatus {
57
+ name: string;
58
+ installed: boolean;
59
+ usable: boolean;
60
+ runnable: boolean;
61
+ transient?: boolean;
62
+ reason?: string;
63
+ }
53
64
  export interface ConnectDeps {
54
65
  fetchImpl: typeof fetch;
55
66
  log: (message: string) => void;
@@ -67,30 +78,35 @@ export interface ConnectDeps {
67
78
  register: (input: {
68
79
  controlPlane: string;
69
80
  enrolmentToken: string;
70
- vendor: VendorBackend;
81
+ vendor: ConnectTarget;
82
+ computerId?: string;
71
83
  workspaceRoot: string;
72
84
  }) => Promise<{
73
85
  runnerId: string;
86
+ connectedBackends?: string[];
87
+ report?: ComputerHarnessStatus[];
74
88
  }>;
75
89
  /** Start args of an installed service, or null. `undefined` = default one. */
76
- installedStartArgs: (instance?: VendorBackend) => string[] | null;
90
+ installedStartArgs: (instance?: string) => string[] | null;
91
+ installedInstances?: () => string[];
77
92
  portOccupied: (port: number) => Promise<boolean>;
78
93
  /** A copy of the harness outside the npx cache, so the service survives. */
79
94
  stableInstall: () => {
80
95
  nodePath: string;
81
96
  cliPath: string;
82
97
  };
83
- installService: (instance: VendorBackend, startArgs: string[], paths: {
98
+ installService: (instance: string, startArgs: string[], paths: {
84
99
  nodePath: string;
85
100
  cliPath: string;
86
101
  }) => Promise<void>;
87
102
  waitForHealth: (port: number) => Promise<boolean>;
88
103
  }
89
104
  /** Reuse this vendor's previous ports; otherwise pick free ones. */
90
- export declare function choosePorts(vendor: VendorBackend, deps: Pick<ConnectDeps, 'installedStartArgs' | 'portOccupied'>): Promise<ServicePorts>;
105
+ export declare function choosePorts(vendor: string, deps: Pick<ConnectDeps, 'installedStartArgs' | 'portOccupied' | 'installedInstances'>): Promise<ServicePorts>;
91
106
  export declare function runConnect(args: ConnectArgs, deps: ConnectDeps): Promise<void>;
92
107
  export declare function defaultConnectDeps(context: {
93
108
  nodePath: string;
94
109
  cliPath: string;
95
110
  env: NodeJS.ProcessEnv;
96
111
  }): ConnectDeps;
112
+ export {};