@peakflo/agent-harness 0.2.10-rc.3 → 0.2.11-rc.1

package/README.md

@@ -52,6 +52,28 @@ Optional flags include `--health-port <port>`, `--runtime <desktop|self-hosted>`
 `--workspace-root <path>`, and `--github-proxy-port <port>`. Run
 `npx @peakflo/agent-harness@rc --help` for the full list.
 
+## Connect your own agent in one command
+
+The Welcome window in Spaces shows one command for Codex, Claude Code, or
+Cursor, for example:
+
+```sh
+npx --yes @peakflo/agent-harness@<version> connect claude-code --connection <id>
+```
+
+`connect` checks that the vendor CLI is installed and signed in, opens your
+browser so you can approve this computer (you must be signed in as the same
+user and company), registers the computer as your personal runner for that
+vendor only, and installs a background service for it. The command holds no
+secret: `--connection` is a public id, and the one-time enrolment token is
+fetched only after the approval, with a PKCE verifier that never leaves the
+process. If port 7777 or 7780 is in use, `connect` picks free ports.
+
+Each vendor gets its own service and workspace under
+`~/.pf-agent-harness/connect/<vendor>`. Check or remove one with
+`service status --vendor <vendor>` or `service uninstall --vendor <vendor>`.
+`connect` needs macOS or Linux.
+
 ## Run after you close the terminal
 
 The background service supports macOS launchd user agents and Linux systemd

package/dist/cli.js

@@ -45,12 +45,16 @@ const version_1 = require("./version");
 const USAGE = `pf-agent-harness — headless Peakflo coding-agent harness
 
 Usage:
+  pf-agent-harness connect <codex|claude-code|cursor> --connection <id> [--control-plane <url>]
+                                one command from the Welcome window: approve
+                                this computer in the browser, connect the agent
+                                as your personal agent, run it in the background
   pf-agent-harness start [options]
   pf-agent-harness version
   pf-agent-harness service install [start options]
-  pf-agent-harness service status
-  pf-agent-harness service repair
-  pf-agent-harness service uninstall
+  pf-agent-harness service status [--vendor <name>]
+  pf-agent-harness service repair [--vendor <name>]
+  pf-agent-harness service uninstall [--vendor <name>]
 
 Options:
   --control-plane <url>         workflow-api base url (env PF_CONTROL_PLANE_URL)
@@ -150,6 +154,33 @@ async function main() {
         });
         return;
     }
+    if (command === 'connect') {
+        const floor = (0, node_floor_1.checkNodeFloor)({
+            current: process.versions.node,
+            floor: (0, version_1.getNodeFloor)(),
+            runtime: 'desktop',
+            env: process.env
+        });
+        if (floor.action === 'refuse') {
+            process.stderr.write(`${floor.message}\n`);
+            process.exit(1);
+        }
+        const { defaultConnectDeps, parseConnectArgs, runConnect } = await Promise.resolve().then(() => __importStar(require('./connect/connect')));
+        try {
+            await runConnect(parseConnectArgs(argv.slice(1), process.env), defaultConnectDeps({
+                nodePath: process.execPath,
+                cliPath: __filename,
+                env: process.env
+            }));
+        }
+        catch (error) {
+            // A message for a person, not a stack. Never includes the token.
+            process.stderr.write(`\n✗ ${error instanceof Error ? error.message : String(error)}\n`);
+            process.exit(1);
+        }
+        // Loopback servers and timers are closed; exit promptly anyway.
+        process.exit(0);
+    }
     if (command !== 'start') {
         process.stderr.write(`Unknown command: ${command}\n\n${USAGE}`);
         process.exitCode = 2;

package/dist/connect/approval-callback.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The 127.0.0.1 receiver for the `connect` approval.
+ *
+ * After the user approves in the browser, the approval page sends
+ * `?state=<nonce>&code=<one-time code>` here. The code is useless alone: the
+ * exchange also needs the PKCE verifier, which never leaves this process. The
+ * `state` nonce is compared in constant time, so another page in the browser
+ * cannot feed this process a different approval. No CORS headers are sent.
+ */
+export declare const CALLBACK_PORT_START = 48690;
+export declare const CALLBACK_PORT_END = 48710;
+export declare const APPROVAL_TIMEOUT_MS: number;
+export declare class ApprovalCallback {
+    readonly state: string;
+    port: number;
+    private server;
+    private resolve;
+    private timer;
+    private used;
+    start(): Promise<number>;
+    private listen;
+    wait(timeoutMs?: number): Promise<string>;
+    private clearTimer;
+    stop(): void;
+}

package/dist/connect/approval-callback.js

@@ -0,0 +1,122 @@
+"use strict";
+/**
+ * The 127.0.0.1 receiver for the `connect` approval.
+ *
+ * After the user approves in the browser, the approval page sends
+ * `?state=<nonce>&code=<one-time code>` here. The code is useless alone: the
+ * exchange also needs the PKCE verifier, which never leaves this process. The
+ * `state` nonce is compared in constant time, so another page in the browser
+ * cannot feed this process a different approval. No CORS headers are sent.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApprovalCallback = exports.APPROVAL_TIMEOUT_MS = exports.CALLBACK_PORT_END = exports.CALLBACK_PORT_START = void 0;
+const node_crypto_1 = require("node:crypto");
+const node_http_1 = require("node:http");
+exports.CALLBACK_PORT_START = 48690;
+exports.CALLBACK_PORT_END = 48710;
+exports.APPROVAL_TIMEOUT_MS = 10 * 60 * 1000;
+const CODE = /^[A-Za-z0-9_-]{43}$/;
+function page(title, detail) {
+    return `<!doctype html><html><head><meta charset="utf-8"><title>${title}</title>
+<style>body{font:15px -apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;display:flex;align-items:center;justify-content:center;height:100vh;margin:0}
+.c{text-align:center;max-width:28rem;padding:2rem}h1{font-size:1.2rem;margin:0 0 .5rem}p{color:#666;margin:0}</style>
+</head><body><div class="c"><h1>${title}</h1><p>${detail}</p></div></body></html>`;
+}
+function matches(expected, actual) {
+    if (actual === null)
+        return false;
+    const a = Buffer.from(expected);
+    const b = Buffer.from(actual);
+    return a.length === b.length && (0, node_crypto_1.timingSafeEqual)(a, b);
+}
+class ApprovalCallback {
+    state = (0, node_crypto_1.randomBytes)(24).toString('base64url');
+    port = 0;
+    server = null;
+    resolve = null;
+    timer = null;
+    used = false;
+    async start() {
+        for (let port = exports.CALLBACK_PORT_START; port <= exports.CALLBACK_PORT_END; port += 1) {
+            try {
+                await this.listen(port);
+                this.port = port;
+                return port;
+            }
+            catch {
+                continue;
+            }
+        }
+        throw new Error(`No free local port for the approval in ${exports.CALLBACK_PORT_START}-${exports.CALLBACK_PORT_END}.`);
+    }
+    listen(port) {
+        return new Promise((resolve, reject) => {
+            const server = (0, node_http_1.createServer)((req, res) => {
+                const url = new URL(req.url ?? '/', `http://127.0.0.1:${port}`);
+                // DNS-rebinding guard: only a request addressed to this loopback port.
+                const host = req.headers.host ?? '';
+                if (host !== `127.0.0.1:${port}` && host !== `localhost:${port}`) {
+                    res.writeHead(421);
+                    res.end();
+                    return;
+                }
+                if (req.method !== 'GET' || url.pathname !== '/connect/callback') {
+                    res.writeHead(404);
+                    res.end();
+                    return;
+                }
+                if (this.used) {
+                    res.writeHead(410, { 'Content-Type': 'text/html; charset=utf-8' });
+                    res.end(page('Already approved', 'You can close this tab.'));
+                    return;
+                }
+                const code = url.searchParams.get('code');
+                if (!matches(this.state, url.searchParams.get('state'))) {
+                    res.writeHead(403, { 'Content-Type': 'text/html; charset=utf-8' });
+                    res.end(page('Approval refused', 'Run the connect command again.'));
+                    return;
+                }
+                if (!code || !CODE.test(code)) {
+                    res.writeHead(400, { 'Content-Type': 'text/html; charset=utf-8' });
+                    res.end(page('Approval incomplete', 'Run the connect command again.'));
+                    return;
+                }
+                res.writeHead(200, {
+                    'Content-Type': 'text/html; charset=utf-8',
+                    'Cache-Control': 'no-store',
+                    'Referrer-Policy': 'no-referrer'
+                });
+                res.end(page('Approved', 'Finishing setup in your terminal. You can close this tab.'));
+                this.used = true;
+                this.clearTimer();
+                this.resolve?.(code);
+                this.resolve = null;
+            });
+            server.on('error', reject);
+            // 127.0.0.1 only: never reachable from another machine.
+            server.listen(port, '127.0.0.1', () => {
+                this.server = server;
+                resolve();
+            });
+        });
+    }
+    wait(timeoutMs = exports.APPROVAL_TIMEOUT_MS) {
+        return new Promise((resolve, reject) => {
+            this.resolve = resolve;
+            this.timer = setTimeout(() => reject(new Error('Timed out waiting for approval in the browser. Run the command again.')), timeoutMs);
+            this.timer.unref?.();
+        });
+    }
+    clearTimer() {
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = null;
+    }
+    stop() {
+        this.clearTimer();
+        this.server?.close();
+        this.server = null;
+        this.resolve = null;
+    }
+}
+exports.ApprovalCallback = ApprovalCallback;

package/dist/connect/connect.d.ts

@@ -0,0 +1,95 @@
+/**
+ * `pf-agent-harness connect <vendor> --connection <id> [--control-plane <url>]`
+ *
+ * ONE COMMAND, copied from the Welcome window, that:
+ *   1. checks the vendor CLI is installed and signed in;
+ *   2. asks the signed-in user to approve this computer in the browser
+ *      (loopback + PKCE + `state`; see workflow-api `byo-connect.ts`);
+ *   3. enrols this computer as the user's PERSONAL runner for that vendor only;
+ *   4. installs and starts a background service for it, choosing free local
+ *      ports when 7777/7780 are taken;
+ *   5. prints one clear success line.
+ *
+ * The command carries no secret. The enrolment token exists only in memory
+ * here, between the exchange and the registration call, and is never printed,
+ * written to disk, or placed in argv. The service starts from the saved
+ * runner credential, exactly like `service install` after `start`.
+ */
+import { type VendorBackend } from '../vendor-backends';
+export declare const DEFAULT_CONTROL_PLANE = "https://api.peakflo.ai";
+/** Network text shown in a terminal: no control characters, bounded. */
+export declare function printable(text: string): string;
+/** A failure with a message written for the person at the terminal. */
+export declare class ConnectError extends Error {
+}
+export declare const VENDOR_SETUP: Record<VendorBackend, {
+    label: string;
+    install: string;
+    login: string;
+}>;
+export interface ConnectArgs {
+    vendor: VendorBackend;
+    connection: string;
+    controlPlane: string;
+    appUrl?: string;
+    openBrowser: boolean;
+}
+export declare const CONNECT_USAGE = "Usage: pf-agent-harness connect <codex|claude-code|cursor> --connection <id> [--control-plane <url>]\n\nCopy this command from the Welcome window in Spaces. It approves this computer\nin your browser, connects the agent as your personal agent, and keeps it\nrunning in the background.";
+export declare function parseConnectArgs(argv: string[], env?: NodeJS.ProcessEnv): ConnectArgs;
+/** The machine name the approval page shows. Must match the API's rule. */
+export declare function machineName(raw: string): string;
+export interface VendorCheck {
+    installed: boolean;
+    usable: boolean;
+    /** A check that timed out; the runner keeps checking in the background. */
+    transient: boolean;
+    reason?: string;
+}
+export interface ServicePorts {
+    healthPort: number;
+    proxyPort: number;
+}
+export interface ConnectDeps {
+    fetchImpl: typeof fetch;
+    log: (message: string) => void;
+    openBrowser: (url: string) => void;
+    hostname: () => string;
+    home: string;
+    platform: NodeJS.Platform;
+    checkVendor: (vendor: VendorBackend) => Promise<VendorCheck>;
+    createCallback: () => {
+        state: string;
+        start(): Promise<number>;
+        wait(): Promise<string>;
+        stop(): void;
+    };
+    register: (input: {
+        controlPlane: string;
+        enrolmentToken: string;
+        vendor: VendorBackend;
+        workspaceRoot: string;
+    }) => Promise<{
+        runnerId: string;
+    }>;
+    /** Start args of an installed service, or null. `undefined` = default one. */
+    installedStartArgs: (instance?: VendorBackend) => string[] | null;
+    portOccupied: (port: number) => Promise<boolean>;
+    /** A copy of the harness outside the npx cache, so the service survives. */
+    stableInstall: () => {
+        nodePath: string;
+        cliPath: string;
+    };
+    installService: (instance: VendorBackend, startArgs: string[], paths: {
+        nodePath: string;
+        cliPath: string;
+    }) => Promise<void>;
+    waitForHealth: (port: number) => Promise<boolean>;
+}
+/** Reuse this vendor's previous ports; otherwise pick free ones. */
+export declare function choosePorts(vendor: VendorBackend, deps: Pick<ConnectDeps, 'installedStartArgs' | 'portOccupied'>): Promise<ServicePorts>;
+export declare function runConnect(args: ConnectArgs, deps: ConnectDeps): Promise<void>;
+export declare function defaultConnectDeps(context: {
+    nodePath: string;
+    cliPath: string;
+    env: NodeJS.ProcessEnv;
+}): ConnectDeps;

package/dist/connect/connect.js

@@ -0,0 +1,427 @@
+"use strict";
+/**
+ * `pf-agent-harness connect <vendor> --connection <id> [--control-plane <url>]`
+ *
+ * ONE COMMAND, copied from the Welcome window, that:
+ *   1. checks the vendor CLI is installed and signed in;
+ *   2. asks the signed-in user to approve this computer in the browser
+ *      (loopback + PKCE + `state`; see workflow-api `byo-connect.ts`);
+ *   3. enrols this computer as the user's PERSONAL runner for that vendor only;
+ *   4. installs and starts a background service for it, choosing free local
+ *      ports when 7777/7780 are taken;
+ *   5. prints one clear success line.
+ *
+ * The command carries no secret. The enrolment token exists only in memory
+ * here, between the exchange and the registration call, and is never printed,
+ * written to disk, or placed in argv. The service starts from the saved
+ * runner credential, exactly like `service install` after `start`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONNECT_USAGE = exports.VENDOR_SETUP = exports.ConnectError = exports.DEFAULT_CONTROL_PLANE = void 0;
+exports.printable = printable;
+exports.parseConnectArgs = parseConnectArgs;
+exports.machineName = machineName;
+exports.choosePorts = choosePorts;
+exports.runConnect = runConnect;
+exports.defaultConnectDeps = defaultConnectDeps;
+const node_child_process_1 = require("node:child_process");
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_net_1 = require("node:net");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const approval_callback_1 = require("./approval-callback");
+const capabilities_1 = require("../capabilities");
+const control_plane_1 = require("../control-plane");
+const credential_store_1 = require("../credential-store");
+const browser_enrol_1 = require("../enrol/browser-enrol");
+const harness_discovery_1 = require("../harness-discovery");
+const service_1 = require("../service");
+const vendor_backends_1 = require("../vendor-backends");
+const version_1 = require("../version");
+exports.DEFAULT_CONTROL_PLANE = 'https://api.peakflo.ai';
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const HEALTH_PORTS = [7777, 7778, 7779, ...range(7790, 7799)];
+const PROXY_PORTS = range(7780, 7789);
+function range(from, to) {
+    return Array.from({ length: to - from + 1 }, (_, index) => from + index);
+}
+/** Network text shown in a terminal: no control characters, bounded. */
+function printable(text) {
+    // eslint-disable-next-line no-control-regex
+    return text.replace(/[\u0000-\u001f\u007f-\u009f]/g, ' ').slice(0, 300);
+}
+/** A failure with a message written for the person at the terminal. */
+class ConnectError extends Error {
+}
+exports.ConnectError = ConnectError;
+exports.VENDOR_SETUP = {
+    'claude-code': {
+        label: 'Claude Code',
+        install: 'npm install -g @anthropic-ai/claude-code',
+        login: 'claude auth login'
+    },
+    codex: {
+        label: 'Codex',
+        install: 'npm install -g @openai/codex',
+        login: 'codex login'
+    },
+    cursor: {
+        label: 'Cursor',
+        install: 'curl https://cursor.com/install -fsS | bash',
+        login: 'cursor-agent login'
+    }
+};
+exports.CONNECT_USAGE = `Usage: pf-agent-harness connect <codex|claude-code|cursor> --connection <id> [--control-plane <url>]
+
+Copy this command from the Welcome window in Spaces. It approves this computer
+in your browser, connects the agent as your personal agent, and keeps it
+running in the background.`;
+function flag(argv, name) {
+    const inline = argv.find((arg) => arg.startsWith(`--${name}=`));
+    if (inline)
+        return inline.slice(name.length + 3);
+    const at = argv.indexOf(`--${name}`);
+    if (at < 0)
+        return undefined;
+    const value = argv[at + 1];
+    return value && !value.startsWith('--') ? value : undefined;
+}
+function checkUrl(value, name) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new ConnectError(`The ${name} URL is invalid.`);
+    }
+    const loopback = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
+    if (url.username ||
+        url.password ||
+        url.search ||
+        url.hash ||
+        !(url.protocol === 'https:' || (url.protocol === 'http:' && loopback)))
+        throw new ConnectError(`The ${name} URL must use HTTPS (or HTTP on this computer).`);
+    return url.origin + url.pathname.replace(/\/+$/, '');
+}
+function parseConnectArgs(argv, env = {}) {
+    const known = new Set([
+        '--connection',
+        '--control-plane',
+        '--app-url',
+        '--no-browser'
+    ]);
+    for (let index = 1; index < argv.length; index += 1) {
+        const name = argv[index].split('=')[0];
+        if (!known.has(name))
+            throw new ConnectError(`Unknown option: ${name}\n\n${exports.CONNECT_USAGE}`);
+        if (name !== '--no-browser' && !argv[index].includes('='))
+            index += 1;
+    }
+    const vendor = argv[0];
+    if (!vendor || !(0, vendor_backends_1.isVendorBackend)(vendor))
+        throw new ConnectError(`Choose codex, claude-code, or cursor.\n\n${exports.CONNECT_USAGE}`);
+    // `--token` is refused on purpose: this command never takes a secret.
+    const connection = flag(argv, 'connection');
+    if (!connection || !UUID.test(connection))
+        throw new ConnectError(`Copy the command from the Welcome window: it includes --connection <id>.\n\n${exports.CONNECT_USAGE}`);
+    const appUrl = flag(argv, 'app-url') ?? env.PF_APP_URL;
+    return {
+        vendor,
+        connection,
+        controlPlane: checkUrl(flag(argv, 'control-plane') ??
+            env.PF_CONTROL_PLANE_URL ??
+            exports.DEFAULT_CONTROL_PLANE, 'control plane'),
+        ...(appUrl ? { appUrl: checkUrl(appUrl, 'app') } : {}),
+        openBrowser: !argv.includes('--no-browser')
+    };
+}
+/** The machine name the approval page shows. Must match the API's rule. */
+function machineName(raw) {
+    const cleaned = raw
+        .replace(/[^A-Za-z0-9._ '-]/g, '-')
+        .replace(/^[^A-Za-z0-9]+/, '')
+        .slice(0, 64);
+    return cleaned || 'computer';
+}
+function argNumber(args, name) {
+    if (!args)
+        return null;
+    const at = args.indexOf(name);
+    const value = at >= 0 ? Number(args[at + 1]) : NaN;
+    return Number.isInteger(value) ? value : null;
+}
+/** Reuse this vendor's previous ports; otherwise pick free ones. */
+async function choosePorts(vendor, deps) {
+    const prior = deps.installedStartArgs(vendor);
+    const priorHealth = argNumber(prior, '--health-port');
+    const priorProxy = argNumber(prior, '--github-proxy-port');
+    if (prior && priorHealth && priorProxy)
+        return { healthPort: priorHealth, proxyPort: priorProxy };
+    // Ports other services of ours were given, even if they are stopped now.
+    const reserved = new Set();
+    for (const other of [undefined, 'codex', 'claude-code', 'cursor']) {
+        if (other === vendor)
+            continue;
+        const args = deps.installedStartArgs(other);
+        if (!args)
+            continue;
+        reserved.add(argNumber(args, '--health-port') ?? 7777);
+        reserved.add(argNumber(args, '--github-proxy-port') ?? 7780);
+    }
+    const pick = async (candidates, what) => {
+        for (const port of candidates) {
+            if (reserved.has(port))
+                continue;
+            if (!(await deps.portOccupied(port))) {
+                reserved.add(port);
+                return port;
+            }
+        }
+        throw new ConnectError(`No free local ${what} port (${candidates[0]}-${candidates.at(-1)}). Close other runners and try again.`);
+    };
+    return {
+        healthPort: priorHealth ?? (await pick(HEALTH_PORTS, 'health')),
+        proxyPort: priorProxy ?? (await pick(PROXY_PORTS, 'proxy'))
+    };
+}
+async function postJson(fetchImpl, url, body) {
+    let response;
+    try {
+        response = await fetchImpl(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body)
+        });
+    }
+    catch {
+        throw new ConnectError(`Could not reach ${new URL(url).origin}. Check your internet connection and try again.`);
+    }
+    const json = (await response.json().catch(() => ({})));
+    return { status: response.status, json };
+}
+async function runConnect(args, deps) {
+    const { vendor, connection, controlPlane } = args;
+    const setup = exports.VENDOR_SETUP[vendor];
+    const log = deps.log;
+    if (deps.platform !== 'darwin' && deps.platform !== 'linux')
+        throw new ConnectError('connect needs macOS or Linux. On Windows, use "Ask my agent to do it" in the Welcome window.');
+    const machine = machineName(deps.hostname());
+    log(`Connecting ${setup.label} on ${machine}…`);
+    /* 1. The vendor CLI must be installed and signed in. */
+    const check = await deps.checkVendor(vendor);
+    if (!check.installed)
+        throw new ConnectError(`${setup.label} is not installed on this computer.\n` +
+            `  Install it:  ${setup.install}\n` +
+            `  Sign in:     ${setup.login}\n` +
+            'Then run this command again.');
+    if (!check.usable && !check.transient)
+        throw new ConnectError(`${setup.label} is installed but not signed in.\n` +
+            `  Sign in:  ${setup.login}\n` +
+            'Then run this command again.');
+    log(check.usable
+        ? `✓ ${setup.label} is installed and signed in.`
+        : `! ${setup.label} is installed; its sign-in check is slow and will be retried in the background.`);
+    /* 2. Browser approval, bound to this process by `state` and PKCE. */
+    const verifier = (0, node_crypto_1.randomBytes)(32).toString('base64url');
+    const challenge = (0, node_crypto_1.createHash)('sha256')
+        .update(verifier, 'utf8')
+        .digest('base64url');
+    const callback = deps.createCallback();
+    let code;
+    try {
+        const port = await callback.start();
+        const appOrigin = args.appUrl
+            ? new URL(args.appUrl).origin
+            : (0, browser_enrol_1.deriveAppOrigin)(controlPlane);
+        const query = new URLSearchParams({
+            connection,
+            vendor,
+            machine,
+            port: String(port),
+            state: callback.state,
+            challenge
+        });
+        const approvalUrl = `${appOrigin}/connect-computer?${query.toString()}`;
+        log('');
+        log('Approve this computer in your browser:');
+        log(`    ${approvalUrl}`);
+        log('Waiting for approval… (Ctrl-C to cancel)');
+        const waiting = callback.wait();
+        // Never leave the timeout rejection unhandled if opening the browser throws.
+        waiting.catch(() => undefined);
+        if (args.openBrowser)
+            deps.openBrowser(approvalUrl);
+        code = await waiting;
+    }
+    finally {
+        callback.stop();
+    }
+    /* 3. Exchange the approval for a one-time enrolment token. */
+    const exchange = await postJson(deps.fetchImpl, `${controlPlane}/api/onboarding/byo/connect/${connection}/exchange`, { code, codeVerifier: verifier });
+    const enrolmentToken = exchange.json.enrolmentToken;
+    if (exchange.status !== 200 ||
+        typeof enrolmentToken !== 'string' ||
+        exchange.json.vendor !== vendor)
+        throw new ConnectError(typeof exchange.json.error === 'string'
+            ? printable(exchange.json.error)
+            : `The approval could not be used (${exchange.status}). Get a new command from the Welcome window.`);
+    const company = typeof exchange.json.companyName === 'string'
+        ? exchange.json.companyName
+        : 'your company';
+    log(`✓ Approved for ${company}.`);
+    /* 4. Enrol: a personal runner for this vendor only. */
+    const workspaceRoot = (0, node_path_1.join)(deps.home, '.pf-agent-harness', 'connect', vendor, 'workspaces');
+    const ports = await choosePorts(vendor, deps);
+    await deps.register({ controlPlane, enrolmentToken, vendor, workspaceRoot });
+    log('✓ This computer is registered as your personal runner.');
+    /* 5. Background service, started from the saved credential. */
+    log('Setting up the background service…');
+    const paths = deps.stableInstall();
+    if (paths.cliPath.includes('/_npx/'))
+        log("! The service runs from npm's npx cache. If it stops after a cache cleanup, run this command again.");
+    const startArgs = [
+        '--control-plane',
+        controlPlane,
+        ...(args.appUrl ? ['--app-url', args.appUrl] : []),
+        '--runtime',
+        'desktop',
+        '--vendor-harnesses',
+        vendor,
+        '--workspace-root',
+        workspaceRoot,
+        '--health-port',
+        String(ports.healthPort),
+        '--github-proxy-port',
+        String(ports.proxyPort)
+    ];
+    await deps.installService(vendor, startArgs, paths);
+    log('✓ Background service installed. It starts when you log in.');
+    const healthy = await deps.waitForHealth(ports.healthPort);
+    if (!healthy)
+        log(`! The service has not answered yet (it may still be starting, or a local port was taken). Check it with: npx @peakflo/agent-harness service status --vendor ${vendor}`);
+    log('');
+    log(`✓ ${setup.label} is connected to ${company} on ${machine}. Return to the Welcome window.`);
+}
+/* -------------------------------------------------------------------------- */
+/* Real dependencies                                                           */
+/* -------------------------------------------------------------------------- */
+function openInBrowser(url) {
+    const command = process.platform === 'darwin' ? 'open' : 'xdg-open';
+    try {
+        const child = (0, node_child_process_1.spawn)(command, [url], { stdio: 'ignore', detached: true });
+        child.on('error', () => undefined);
+        child.unref();
+    }
+    catch {
+        /* the printed url is the fallback */
+    }
+}
+function portInUse(port) {
+    return new Promise((resolve) => {
+        const server = (0, node_net_1.createServer)();
+        server.once('error', () => resolve(true));
+        server.listen(port, '127.0.0.1', () => server.close(() => resolve(false)));
+    });
+}
+function defaultConnectDeps(context) {
+    const home = (0, node_os_1.homedir)();
+    const manager = (instance) => new service_1.ServiceManager({ ...context, instance });
+    return {
+        fetchImpl: fetch,
+        log: (message) => process.stdout.write(`${message}\n`),
+        openBrowser: openInBrowser,
+        hostname: node_os_1.hostname,
+        home,
+        platform: process.platform,
+        checkVendor: async (vendor) => {
+            const [entry] = await (0, harness_discovery_1.discoverHarnesses)({ only: [vendor] });
+            return {
+                installed: Boolean(entry?.installed),
+                usable: Boolean(entry?.usable),
+                transient: Boolean(entry?.transient),
+                reason: entry?.reason
+            };
+        },
+        createCallback: () => new approval_callback_1.ApprovalCallback(),
+        register: async ({ controlPlane, enrolmentToken, vendor, workspaceRoot }) => {
+            const capabilities = await (0, capabilities_1.probeCapabilities)({
+                maxConcurrentSessions: 10
+            });
+            capabilities.vendorHarnesses = [vendor];
+            const client = new control_plane_1.ControlPlaneClient(controlPlane);
+            const response = await client.register({
+                enrolmentToken,
+                capabilities,
+                runtime: 'desktop',
+                degraded: false
+            });
+            const runnerId = client.getRunnerId();
+            if (!client.isRegistered() || !runnerId || !response.runnerCredential)
+                throw new ConnectError(`The control plane did not accept this computer: ${response.reason ?? 'no runner credential'}.`);
+            new credential_store_1.FileCredentialStore(workspaceRoot).save({
+                runnerId,
+                tenantId: response.tenantId ?? null,
+                credential: response.runnerCredential,
+                credentialExpiresAt: response.credentialExpiresAt ?? null,
+                savedAt: new Date().toISOString()
+            });
+            return { runnerId };
+        },
+        installedStartArgs: (instance) => manager(instance).installedStartArgs(),
+        portOccupied: portInUse,
+        stableInstall: () => {
+            const inNpxCache = context.cliPath.includes('/_npx/') ||
+                context.cliPath.includes('/.npm/_npx/');
+            if (!inNpxCache)
+                return { nodePath: context.nodePath, cliPath: context.cliPath };
+            // npx may delete its cache at any time; the service must not depend on it.
+            const prefix = (0, node_path_1.join)(home, '.pf-agent-harness', 'app');
+            const cliPath = (0, node_path_1.join)(prefix, 'node_modules', '@peakflo', 'agent-harness', 'dist', 'cli.js');
+            try {
+                (0, node_child_process_1.execFileSync)('npm', [
+                    'install',
+                    '--prefix',
+                    prefix,
+                    '--no-audit',
+                    '--no-fund',
+                    '--omit=dev',
+                    `@peakflo/agent-harness@${(0, version_1.getHarnessVersion)()}`
+                ], 
+                // A slow network must not look like a hang for ever.
+                { stdio: ['ignore', 'ignore', 'pipe'], timeout: 180_000 });
+                if ((0, node_fs_1.existsSync)(cliPath))
+                    return { nodePath: context.nodePath, cliPath };
+            }
+            catch {
+                /* fall back to the npx copy, with service install's warning */
+            }
+            return { nodePath: context.nodePath, cliPath: context.cliPath };
+        },
+        installService: async (instance, startArgs, paths) => {
+            await new service_1.ServiceManager({
+                ...context,
+                ...paths,
+                instance,
+                // service install prints its own lines; connect prints its own summary.
+                output: () => undefined
+            }).install(startArgs);
+        },
+        waitForHealth: async (port) => {
+            for (let attempt = 0; attempt < 45; attempt += 1) {
+                try {
+                    const response = await fetch(`http://127.0.0.1:${port}/health`, {
+                        signal: AbortSignal.timeout(2000)
+                    });
+                    if (response.ok)
+                        return true;
+                }
+                catch {
+                    /* not up yet */
+                }
+                await new Promise((resolve) => setTimeout(resolve, 1000));
+            }
+            return false;
+        }
+    };
+}

package/dist/service.d.ts

@@ -17,7 +17,20 @@ export interface ServiceContext {
     output?: (message: string) => void;
     sleep?: (ms: number) => void;
     portOccupied?: (port: number) => Promise<boolean>;
+    /**
+     * A per-vendor service from `connect` (`ai.peakflo.agent-harness.<vendor>`),
+     * so Claude Code, Codex and Cursor can each run as their own personal
+     * runner on one machine. Unset means the original single service.
+     */
+    instance?: string;
 }
+/** Service names for an instance. Only vendor names are accepted. */
+export declare function serviceNames(instance?: string): {
+    label: string;
+    unit: string;
+    stateFile: string;
+    logDir: string;
+};
 export declare function permanentServiceExitCode(platform: Platform, linuxCode: 2 | 78): number;
 /** Only failures that a restart cannot repair belong in this list. */
 export declare function permanentStartupFailure(error: unknown): string | null;
@@ -25,7 +38,7 @@ export declare function permanentStartupFailure(error: unknown): string | null;
 export declare function isServiceStart(argv: string[]): boolean;
 /** Parse only documented start options. A token can never enter service state. */
 export declare function serviceStartArgs(input: string[], env: NodeJS.ProcessEnv, home: string): string[];
-export declare function renderLaunchAgent(config: ServiceConfig, logDir: string): string;
+export declare function renderLaunchAgent(config: ServiceConfig, logDir: string, label?: string): string;
 export declare function renderSystemdUnit(config: ServiceConfig): string;
 export declare function recordServiceFailure(reason: string, home?: string): void;
 export declare function clearServiceFailure(home?: string): void;
@@ -38,12 +51,17 @@ export declare class ServiceManager {
     private readonly stateFile;
     private readonly serviceFile;
     private readonly logDir;
+    private readonly label;
+    private readonly unit;
     constructor(context: ServiceContext);
+    /** Settings of the installed service, or null when there is none. */
+    installedStartArgs(): string[] | null;
     private supported;
     private readConfig;
     private checkCredential;
     private writeAndStart;
     install(input: string[]): Promise<void>;
+    private vendorFlag;
     private checkNodeVersion;
     repair(): void;
     assertNoDuplicateRunner(options: {
@@ -53,5 +71,5 @@ export declare class ServiceManager {
     status(): void;
     uninstall(): void;
 }
-export declare function runServiceCommand(args: string[], context: ServiceContext): Promise<void>;
+export declare function runServiceCommand(input: string[], context: ServiceContext): Promise<void>;
 export {};

package/dist/service.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ServiceManager = void 0;
+exports.serviceNames = serviceNames;
 exports.permanentServiceExitCode = permanentServiceExitCode;
 exports.permanentStartupFailure = permanentStartupFailure;
 exports.isServiceStart = isServiceStart;
@@ -37,6 +38,24 @@ const VALUE_FLAGS = new Set([
     '--vendor-harnesses'
 ]);
 const SWITCH_FLAGS = new Set(['--no-harness-discovery']);
+/** Service names for an instance. Only vendor names are accepted. */
+function serviceNames(instance) {
+    if (instance === undefined)
+        return {
+            label: LABEL,
+            unit: UNIT,
+            stateFile: 'service.json',
+            logDir: 'logs'
+        };
+    if (!(0, vendor_backends_1.isVendorBackend)(instance))
+        throw new Error('Use codex, claude-code, or cursor as the service name.');
+    return {
+        label: `${LABEL}.${instance}`,
+        unit: `pf-agent-harness-${instance}.service`,
+        stateFile: `service-${instance}.json`,
+        logDir: (0, node_path_1.join)('logs', instance)
+    };
+}
 const LAST_ERROR_FILE = 'service-last-error';
 function permanentServiceExitCode(platform, linuxCode) {
     return platform === 'darwin' ? 0 : linuxCode;
@@ -176,12 +195,12 @@ function serviceStartArgs(input, env, home) {
             result.push(flag);
     return result;
 }
-function renderLaunchAgent(config, logDir) {
+function renderLaunchAgent(config, logDir, label = LABEL) {
     const args = [config.nodePath, config.cliPath, 'start', ...config.startArgs];
     const array = args
         .map((arg) => `    <string>${xml(arg)}</string>`)
         .join('\n');
-    return `<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<plist version="1.0">\n<dict>\n  <key>Label</key><string>${LABEL}</string>\n  <key>ProgramArguments</key><array>\n${array}\n  </array>\n  <key>RunAtLoad</key><true/>\n  <key>KeepAlive</key><dict><key>SuccessfulExit</key><false/></dict>\n  <key>ThrottleInterval</key><integer>30</integer>\n  <key>EnvironmentVariables</key><dict><key>PATH</key><string>${xml(config.path)}</string></dict>\n  <key>StandardOutPath</key><string>${xml((0, node_path_1.join)(logDir, 'stdout.log'))}</string>\n  <key>StandardErrorPath</key><string>${xml((0, node_path_1.join)(logDir, 'stderr.log'))}</string>\n</dict>\n</plist>\n`;
+    return `<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<plist version="1.0">\n<dict>\n  <key>Label</key><string>${xml(label)}</string>\n  <key>ProgramArguments</key><array>\n${array}\n  </array>\n  <key>RunAtLoad</key><true/>\n  <key>KeepAlive</key><dict><key>SuccessfulExit</key><false/></dict>\n  <key>ThrottleInterval</key><integer>30</integer>\n  <key>EnvironmentVariables</key><dict><key>PATH</key><string>${xml(config.path)}</string></dict>\n  <key>StandardOutPath</key><string>${xml((0, node_path_1.join)(logDir, 'stdout.log'))}</string>\n  <key>StandardErrorPath</key><string>${xml((0, node_path_1.join)(logDir, 'stderr.log'))}</string>\n</dict>\n</plist>\n`;
 }
 function renderSystemdUnit(config) {
     const command = [
@@ -230,6 +249,8 @@ class ServiceManager {
     stateFile;
     serviceFile;
     logDir;
+    label;
+    unit;
     constructor(context) {
         this.context = context;
         this.home = context.home ?? (0, node_os_1.homedir)();
@@ -237,12 +258,26 @@ class ServiceManager {
         this.run = context.run ?? defaultRun;
         this.output =
             context.output ?? ((message) => process.stdout.write(`${message}\n`));
-        this.stateFile = (0, node_path_1.join)(this.home, '.pf-agent-harness', 'service.json');
-        this.logDir = (0, node_path_1.join)(this.home, '.pf-agent-harness', 'logs');
+        const names = serviceNames(context.instance);
+        this.label = names.label;
+        this.unit = names.unit;
+        this.stateFile = (0, node_path_1.join)(this.home, '.pf-agent-harness', names.stateFile);
+        this.logDir = (0, node_path_1.join)(this.home, '.pf-agent-harness', names.logDir);
         this.serviceFile =
             this.platform === 'darwin'
-                ? (0, node_path_1.join)(this.home, 'Library', 'LaunchAgents', `${LABEL}.plist`)
-                : (0, node_path_1.join)(this.home, '.config', 'systemd', 'user', UNIT);
+                ? (0, node_path_1.join)(this.home, 'Library', 'LaunchAgents', `${this.label}.plist`)
+                : (0, node_path_1.join)(this.home, '.config', 'systemd', 'user', this.unit);
+    }
+    /** Settings of the installed service, or null when there is none. */
+    installedStartArgs() {
+        if (!(0, node_fs_1.existsSync)(this.stateFile))
+            return null;
+        try {
+            return this.readConfig().startArgs;
+        }
+        catch {
+            return null;
+        }
     }
     supported() {
         if (this.platform !== 'darwin' && this.platform !== 'linux') {
@@ -280,10 +315,10 @@ class ServiceManager {
         (0, node_fs_1.mkdirSync)(this.logDir, { recursive: true, mode: 0o700 });
         writePrivate(this.stateFile, `${JSON.stringify(config, null, 2)}\n`);
         if (this.platform === 'darwin') {
-            writePrivate(this.serviceFile, renderLaunchAgent(config, this.logDir));
+            writePrivate(this.serviceFile, renderLaunchAgent(config, this.logDir, this.label));
             const domain = `gui/${this.context.uid ?? process.getuid?.() ?? (0, node_os_1.userInfo)().uid}`;
             try {
-                this.run('launchctl', ['bootout', `${domain}/${LABEL}`]);
+                this.run('launchctl', ['bootout', `${domain}/${this.label}`]);
             }
             catch {
                 /* absent */
@@ -306,15 +341,15 @@ class ServiceManager {
         else {
             writePrivate(this.serviceFile, renderSystemdUnit(config));
             this.run('systemctl', ['--user', 'daemon-reload']);
-            this.run('systemctl', ['--user', 'enable', UNIT]);
+            this.run('systemctl', ['--user', 'enable', this.unit]);
             try {
-                this.run('systemctl', ['--user', 'reset-failed', UNIT]);
+                this.run('systemctl', ['--user', 'reset-failed', this.unit]);
             }
             catch {
                 // A new unit may have no failed state to clear. Restart gives the
                 // operator the actionable error if systemd cannot start it.
             }
-            this.run('systemctl', ['--user', 'restart', UNIT]);
+            this.run('systemctl', ['--user', 'restart', this.unit]);
         }
     }
     async install(input) {
@@ -339,12 +374,12 @@ class ServiceManager {
                     const info = this.platform === 'darwin'
                         ? this.run('launchctl', [
                             'print',
-                            `gui/${this.context.uid ?? process.getuid?.() ?? (0, node_os_1.userInfo)().uid}/${LABEL}`
+                            `gui/${this.context.uid ?? process.getuid?.() ?? (0, node_os_1.userInfo)().uid}/${this.label}`
                         ])
                         : this.run('systemctl', [
                             '--user',
                             'show',
-                            UNIT,
+                            this.unit,
                             '--property=ActiveState',
                             '--property=MainPID'
                         ]);
@@ -378,10 +413,13 @@ class ServiceManager {
         if (this.context.nodePath.includes('/.nvm/versions/node/')) {
             this.output('Warning: this Node.js path can change after an nvm upgrade. Run service repair after upgrades.');
         }
-        this.output('After a Node.js or harness upgrade, run: pf-agent-harness service repair');
+        this.output(`After a Node.js or harness upgrade, run: pf-agent-harness service repair${this.vendorFlag()}`);
         if (this.platform === 'linux')
             this.output('To run after logout, ask your system administrator to run: loginctl enable-linger $USER');
     }
+    vendorFlag() {
+        return this.context.instance ? ` --vendor ${this.context.instance}` : '';
+    }
     checkNodeVersion() {
         const floor = (0, node_floor_1.checkNodeFloor)({
             current: process.versions.node,
@@ -416,12 +454,12 @@ class ServiceManager {
                 this.platform === 'darwin'
                     ? this.run('launchctl', [
                         'print',
-                        `gui/${this.context.uid ?? process.getuid?.() ?? (0, node_os_1.userInfo)().uid}/${LABEL}`
+                        `gui/${this.context.uid ?? process.getuid?.() ?? (0, node_os_1.userInfo)().uid}/${this.label}`
                     ])
                     : this.run('systemctl', [
                         '--user',
                         'show',
-                        UNIT,
+                        this.unit,
                         '--property=ActiveState',
                         '--property=MainPID'
                     ]);
@@ -463,7 +501,10 @@ class ServiceManager {
         try {
             if (this.platform === 'darwin') {
                 const domain = `gui/${this.context.uid ?? process.getuid?.() ?? (0, node_os_1.userInfo)().uid}`;
-                const info = this.run('launchctl', ['print', `${domain}/${LABEL}`]);
+                const info = this.run('launchctl', [
+                    'print',
+                    `${domain}/${this.label}`
+                ]);
                 const running = /\bstate = running\b/.test(info);
                 const exit = info.match(/last exit code = (\d+)/)?.[1];
                 this.output(`Status: ${running ? 'running' : 'stopped'}. Last error: ${!running && savedError ? savedError : exit && exit !== '0' ? `exit ${exit}` : 'none'}.`);
@@ -472,7 +513,7 @@ class ServiceManager {
                 const info = this.run('systemctl', [
                     '--user',
                     'show',
-                    UNIT,
+                    this.unit,
                     '--property=ActiveState',
                     '--property=Result',
                     '--property=ExecMainStatus'
@@ -492,14 +533,14 @@ class ServiceManager {
         if (this.platform === 'darwin') {
             const domain = `gui/${this.context.uid ?? process.getuid?.() ?? (0, node_os_1.userInfo)().uid}`;
             try {
-                this.run('launchctl', ['bootout', `${domain}/${LABEL}`]);
+                this.run('launchctl', ['bootout', `${domain}/${this.label}`]);
             }
             catch {
                 /* absent */
             }
         }
         else if ((0, node_fs_1.existsSync)(this.serviceFile)) {
-            this.run('systemctl', ['--user', 'disable', '--now', UNIT]);
+            this.run('systemctl', ['--user', 'disable', '--now', this.unit]);
         }
         (0, node_fs_1.rmSync)(this.serviceFile, { force: true });
         (0, node_fs_1.rmSync)(this.stateFile, { force: true });
@@ -510,12 +551,23 @@ class ServiceManager {
     }
 }
 exports.ServiceManager = ServiceManager;
-async function runServiceCommand(args, context) {
-    const manager = new ServiceManager(context);
+async function runServiceCommand(input, context) {
+    // `--vendor <name>` selects a per-vendor service installed by `connect`.
+    const args = [...input];
+    const at = args.findIndex((arg) => arg === '--vendor' || arg.startsWith('--vendor='));
+    let instance = context.instance;
+    if (at > 0 && args[0] !== 'install') {
+        const raw = args[at];
+        instance = raw.includes('=')
+            ? raw.slice(raw.indexOf('=') + 1)
+            : args[at + 1];
+        args.splice(at, raw.includes('=') ? 1 : 2);
+    }
+    const manager = new ServiceManager({ ...context, instance });
     switch (args[0]) {
         case 'help':
         case '--help':
-            (context.output ?? ((message) => process.stdout.write(`${message}\n`)))('Use service install [start options], service status, service repair, or service uninstall.');
+            (context.output ?? ((message) => process.stdout.write(`${message}\n`)))('Use service install [start options], service status, service repair, or service uninstall. Add --vendor <name> for a service made by connect.');
             break;
         case 'install':
             await manager.install(args.slice(1));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peakflo/agent-harness",
-  "version": "0.2.10-rc.3",
+  "version": "0.2.11-rc.1",
   "description": "Headless Peakflo coding-agent harness. One codebase, three hosting modes: a Daytona cloud sandbox, a customer VM, and the 20x desktop.",
   "license": "MIT",
   "type": "commonjs",