@peakflo/agent-harness 0.0.0-stage → 0.2.2-rc.1

package/dist/options.js

@@ -0,0 +1,212 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OptionsError = void 0;
+exports.parseOptions = parseOptions;
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const DEFAULT_HEALTH_PORT = 7777;
+const DEFAULT_GITHUB_PROXY_PORT = 7780;
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 30_000;
+class OptionsError extends Error {
+}
+exports.OptionsError = OptionsError;
+/** Keep in step with `LOOPBACK_HOSTS` in `agentSandbox/bin/pf-bootstrap`. */
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '[::1]']);
+function readFlag(argv, name) {
+    const withEquals = argv.find((arg) => arg.startsWith(`--${name}=`));
+    if (withEquals) {
+        return withEquals.slice(name.length + 3);
+    }
+    const index = argv.indexOf(`--${name}`);
+    if (index !== -1 && argv[index + 1] && !argv[index + 1].startsWith('--')) {
+        return argv[index + 1];
+    }
+    return undefined;
+}
+function readBoolFlag(argv, name) {
+    return argv.includes(`--${name}`);
+}
+/**
+ * A bad interval must fail fast, not quietly.
+ *
+ * `Number.parseInt('abc')` is NaN, and `setTimeout(fn, NaN)` is clamped to
+ * about 1 ms — so a typo in the environment turned the heartbeat into a tight
+ * loop hammering /harness/heartbeat rather than an obvious start-up error.
+ * The floor also stops a well-meaning `--heartbeat-interval-ms 10`.
+ */
+const MIN_HEARTBEAT_INTERVAL_MS = 1_000;
+const MAX_HEARTBEAT_INTERVAL_MS = 3_600_000;
+function parseInterval(raw, fallback) {
+    if (raw === undefined || raw === '') {
+        return fallback;
+    }
+    const value = Number.parseInt(raw, 10);
+    if (!Number.isInteger(value) ||
+        value < MIN_HEARTBEAT_INTERVAL_MS ||
+        value > MAX_HEARTBEAT_INTERVAL_MS) {
+        throw new OptionsError(`Invalid heartbeat interval: '${raw}'. Expected an integer between ` +
+            `${MIN_HEARTBEAT_INTERVAL_MS} and ${MAX_HEARTBEAT_INTERVAL_MS} ms.`);
+    }
+    return value;
+}
+function parsePort(raw, fallback) {
+    if (!raw) {
+        return fallback;
+    }
+    const value = Number.parseInt(raw, 10);
+    if (!Number.isInteger(value) || value < 1 || value > 65535) {
+        throw new OptionsError(`Invalid port: ${raw}`);
+    }
+    return value;
+}
+/**
+ * WHERE SESSION WORKSPACES LIVE — ONE ANSWER, NOT ONE PER RUNTIME.
+ *
+ * Under the user's own home, always. This is the shape 20x has always had:
+ * `join(app.getPath('userData'), 'workspaces', taskId)` in `database.ts` —
+ * a directory the process owns by definition, with no per-runtime branch,
+ * because a path the program GUESSES is a path it can guess wrong.
+ *
+ * IT USED TO BRANCH, and returned `/var/pf/workspaces` for `runtime=sandbox`.
+ * That is the managed image's path, created there as pfharness:0700 at build
+ * time — and it is not writable anywhere else. Running a sandbox-runtime
+ * harness on a laptop therefore died with
+ * `EACCES: permission denied, mkdir '/var/pf'` AFTER registering and burning
+ * its single-use enrolment token, so retrying meant enrolling again.
+ *
+ * THE SANDBOX DOES NOT NEED THE GUESS. It is TOLD: the control plane passes
+ * `PF_WORKSPACE_ROOT` in the Daytona sandbox's `envVars` at creation, and the
+ * image sets the same variable as a backstop. An explicit `--workspace-root`
+ * or `PF_WORKSPACE_ROOT` still wins over this default, which is exactly how
+ * that value arrives. So the sandbox path is now a PARAMETER the control plane
+ * owns rather than a constant duplicated in the harness and the Dockerfile with
+ * nothing keeping the two in step.
+ */
+function defaultWorkspaceRoot() {
+    return (0, node_path_1.join)((0, node_os_1.homedir)(), '.pf-agent-harness', 'workspaces');
+}
+const RUNTIMES = new Set(['sandbox', 'self-hosted', 'desktop']);
+/**
+ * Defaults to 'desktop'.
+ *
+ * Somebody who runs `pf-agent-harness start` by hand is, essentially always,
+ * sitting at the machine — that is what the browser sign-in assumes too. The
+ * previous default of `self-hosted` was chosen to fail towards caution, but it
+ * failed towards CONFUSION instead: a laptop runner announced itself as
+ * self-hosted, the gateway became the only permitted model route, and a turn
+ * naming one of the machine's own opencode providers was refused with a
+ * message about credential borrowing on a host we do not own — the host being
+ * the user's own laptop.
+ *
+ * A missing value must still never be read as "managed sandbox": that is the
+ * trusted mode, provisioned by us, and defaulting into it would be a
+ * permission granted by an absent environment variable. pf-bootstrap always
+ * sets PF_RUNNER_RUNTIME=sandbox explicitly, so nothing relies on the default.
+ */
+function parseRuntime(raw) {
+    if (!raw) {
+        return 'desktop';
+    }
+    if (!RUNTIMES.has(raw)) {
+        throw new OptionsError(`Invalid runtime: '${raw}'. Expected sandbox, self-hosted or desktop.`);
+    }
+    return raw;
+}
+const LOCAL_RUNNER_DEFAULT_CONCURRENCY = 10;
+/**
+ * Desktop and self-hosted runners should use the machine as a pool rather than
+ * serialising every session. The conservative end of the supported 10–20 range
+ * is the default; operators can still size it explicitly for their host.
+ *
+ * Managed sandboxes receive their measured limit explicitly from the control
+ * plane, so one remains the safe fallback if that configuration is absent.
+ */
+function parseConcurrency(raw, runtime) {
+    if (!raw) {
+        return runtime === 'sandbox' ? 1 : LOCAL_RUNNER_DEFAULT_CONCURRENCY;
+    }
+    const value = Number.parseInt(raw, 10);
+    if (!Number.isInteger(value) || value < 1 || value > 64) {
+        throw new OptionsError(`Invalid max concurrent sessions: '${raw}'. Expected an integer 1-64.`);
+    }
+    return value;
+}
+function parseLabels(raw) {
+    if (!raw) {
+        return undefined;
+    }
+    const labels = raw
+        .split(',')
+        .map((label) => label.trim())
+        .filter(Boolean);
+    return labels.length > 0 ? labels : undefined;
+}
+function parseBoolean(raw, fallback, name) {
+    if (raw === undefined || raw === '')
+        return fallback;
+    if (raw === 'true')
+        return true;
+    if (raw === 'false')
+        return false;
+    throw new OptionsError(`Invalid ${name}: '${raw}'. Expected true or false.`);
+}
+/**
+ * Flags win over environment variables, so a local developer can override a
+ * value that pf-bootstrap injected.
+ *
+ * NOTE ON THE ENROLMENT TOKEN: it is accepted on the command line for local
+ * development and self-hosted installs, which is what the design calls for.
+ * In a managed sandbox pf-bootstrap passes it through PF_ENROLMENT_TOKEN
+ * instead, so it never appears in the process arguments — /proc/<pid>/cmdline
+ * is world-readable, while /proc/<pid>/environ is readable only by the
+ * process owner.
+ */
+function parseOptions(argv, env) {
+    const controlPlaneUrl = readFlag(argv, 'control-plane') ?? env.PF_CONTROL_PLANE_URL;
+    if (!controlPlaneUrl) {
+        throw new OptionsError('Missing control plane url. Pass --control-plane <url> or set PF_CONTROL_PLANE_URL.');
+    }
+    const enrolmentToken = readFlag(argv, 'token') ?? env.PF_ENROLMENT_TOKEN;
+    if (!enrolmentToken) {
+        throw new OptionsError('Missing enrolment token. Pass --token <token> or set PF_ENROLMENT_TOKEN.');
+    }
+    let parsed;
+    try {
+        parsed = new URL(controlPlaneUrl);
+    }
+    catch {
+        throw new OptionsError(`Invalid control plane url: ${controlPlaneUrl}`);
+    }
+    // Transport rule, and it MUST match `agentSandbox/bin/pf-bootstrap`.
+    //
+    // https everywhere, except LOOPBACK, which is allowed for local
+    // development — the form this package's README documents.
+    // PF_ALLOW_INSECURE_CONTROL_PLANE exists ONLY for the containerised exit
+    // test, where the stub is reached by a CONTAINER HOSTNAME rather than by
+    // loopback. It must never be set on a managed sandbox.
+    const isLoopback = LOOPBACK_HOSTS.has(parsed.hostname);
+    const insecureAllowed = env.PF_ALLOW_INSECURE_CONTROL_PLANE === 'true';
+    if (parsed.protocol !== 'https:' && !isLoopback && !insecureAllowed) {
+        throw new OptionsError(`Control plane url must use https (loopback is allowed for development): ${controlPlaneUrl}`);
+    }
+    // Resolved before the object literal, because the workspace-root DEFAULT
+    // depends on it.
+    const runtime = parseRuntime(readFlag(argv, 'runtime') ?? env.PF_RUNNER_RUNTIME);
+    return {
+        controlPlaneUrl,
+        enrolmentToken,
+        healthPort: parsePort(readFlag(argv, 'health-port') ?? env.PF_HARNESS_HEALTH_PORT, DEFAULT_HEALTH_PORT),
+        githubProxyPort: parsePort(readFlag(argv, 'github-proxy-port') ?? env.PF_GITHUB_PROXY_PORT, DEFAULT_GITHUB_PROXY_PORT),
+        autoCommitDirtyWorktree: parseBoolean(readFlag(argv, 'worktree-wip-commit') ?? env.PF_WORKTREE_WIP_COMMIT, runtime === 'sandbox', 'worktree WIP commit flag'),
+        heartbeatIntervalMs: parseInterval(readFlag(argv, 'heartbeat-interval-ms') ??
+            env.PF_HARNESS_HEARTBEAT_INTERVAL_MS, DEFAULT_HEARTBEAT_INTERVAL_MS),
+        degraded: readBoolFlag(argv, 'degraded') || env.PF_HARNESS_DEGRADED === 'true',
+        degradedReason: readFlag(argv, 'degraded-reason') ?? env.PF_HARNESS_DEGRADED_REASON,
+        workspaceRoot: readFlag(argv, 'workspace-root') ??
+            env.PF_WORKSPACE_ROOT ??
+            defaultWorkspaceRoot(),
+        runtime,
+        maxConcurrentSessions: parseConcurrency(readFlag(argv, 'max-sessions') ?? env.PF_MAX_CONCURRENT_SESSIONS, runtime),
+        labels: parseLabels(readFlag(argv, 'labels') ?? env.PF_RUNNER_LABELS)
+    };
+}

package/dist/ports-default.d.ts

@@ -0,0 +1,212 @@
+/**
+ * THE SERVER-SIDE PORT IMPLEMENTATIONS — what a headless runner uses when the
+ * desktop is not there to supply anything.
+ *
+ * Every one of these is a REAL implementation of a capability a server genuinely
+ * has, or an HONEST NO-OP for one it genuinely lacks. None of them pretends: a
+ * server has no user to notify and never sleeps, so `ServerNotifier` does
+ * nothing and says so. That is why `Notifier` stayed a port instead of being
+ * deleted — the desktop's behaviour is preserved without the runtime having to
+ * ask which host it is running on.
+ */
+import { ArtifactInspector, EventSink, InspectedArtifact, Notifier, SecretProvider, TaskMcpProvider, Telemetry, TokenInjector, WorkspaceProvider, WorkspaceRequest } from './ports';
+import { JsonValue } from './types';
+/**
+ * A no-op, per the brief: product analytics on a server is the CONTROL PLANE's
+ * business, and it already sees every register, heartbeat, lease and ingest.
+ * Shipping a second telemetry pipe out of a customer VM would be a data-flow the
+ * customer never agreed to.
+ */
+export declare class NoopTelemetry implements Telemetry {
+    record(): void;
+}
+/** No human at this machine, and nothing that sleeps. */
+export declare class ServerNotifier implements Notifier {
+    notify(): void;
+    keepAwake(): () => void;
+}
+/**
+ * No local secret store.
+ *
+ * THIS IS A SECURITY POSITION, NOT A GAP. A customer VM is outside our security
+ * perimeter, so the harness deliberately holds no vendor credential to hand an
+ * agent: everything the agent can reach, it reaches through the MCP gateway,
+ * which injects the real credentials SERVER-SIDE. A runner with a secret store
+ * would recreate exactly the exposure the gateway exists to remove.
+ *
+ * `getBrokerPort()` returning null makes the runtime skip secret wiring
+ * entirely, which is why this is a working implementation and not a stub.
+ */
+export declare class NoSecretProvider implements SecretProvider {
+    getBrokerPort(): number | null;
+    registerSession(): void;
+    unregisterSession(): void;
+    writeShellWrapper(): string | null;
+    getSecretEnv(): Record<string, string>;
+}
+/**
+ * Describes nothing.
+ *
+ * Artifact inspection on the desktop reads the file to build a preview. On a
+ * runner the file is on the runner, and the reader is a browser somewhere else,
+ * so the useful implementation is an upload — which belongs to the control
+ * plane's ingest path, not here.
+ */
+export declare class NoArtifactInspector implements ArtifactInspector {
+    inspect(): Promise<InspectedArtifact | null>;
+}
+/**
+ * The task-management MCP server, when the control plane supplies one.
+ *
+ * ON THE DESKTOP this port is backed by an IN-PROCESS server. On a runner there
+ * is no such server and there must not be one — a task MCP endpoint on the
+ * runner would be a second, unauthenticated door into the tenant's data. The
+ * runner is handed a REMOTE gateway URL in the lease instead, already scoped and
+ * already authenticated, and this class simply carries it.
+ *
+ * Constructed with null when the lease carried no task MCP, which is the
+ * ordinary case for a free-standing session (decision 6).
+ */
+export declare class StaticTaskMcpProvider implements TaskMcpProvider {
+    private readonly url;
+    constructor(url: string | null);
+    getUrl(): Promise<string | null>;
+}
+/**
+ * Hands out the session-scoped MCP token from the lease, KEYED BY TARGET URL.
+ *
+ * The token is held in memory and never written anywhere. It is short-lived,
+ * bound to this runner AND this session, and carries no tool list — so the
+ * gateway re-reads the allowlist on every call and a revocation takes effect
+ * immediately rather than at the next session.
+ *
+ * WHY THE MAP, AND NOT A SINGLE FIELD — this is a concurrency correctness bug,
+ * not a refinement. The loopback proxy holds ONE reference to this injector for
+ * the whole process life, and `runLeasedTurn` runs several turns at once when
+ * `maxConcurrentSessions > 1`. A single shared `token` field therefore had the
+ * exact failure the per-turn model gateway holder was already fixed to avoid:
+ *
+ *   - turn B's `setToken(tokenB)` OVERWROTE turn A's token, so A's forwarded
+ *     MCP calls carried B's session token. The gateway's session-id gate
+ *     (`mcpSessionAuthMiddleware`, gate 3) then answered 401 for A — a valid
+ *     token for the wrong session — and OpenCode mis-reported that 401 as an
+ *     OAuth challenge, so `create_artifact` failed mid-session with two agents
+ *     running;
+ *   - whichever turn finished FIRST called `revoke()` and blanked the token for
+ *     every still-running turn, 401ing the survivor for the rest of its run.
+ *
+ * Each target url embeds its own session id (`/api/mcp/agent/:sessionId/...`),
+ * so keying the token by target url gives every concurrent session an
+ * independent slot. `getToken(targetUrl)` receives that url from the proxy on
+ * every request, so the per-request contract the proxy already relies on is
+ * unchanged — only the storage is now per-session instead of process-global.
+ *
+ * The constructor argument is a FALLBACK, used only for a target that was never
+ * explicitly registered (the desktop single-token case). It is deliberately NOT
+ * mutated by the per-session methods, so a fallback can never leak a session
+ * token to an unrelated target.
+ */
+export declare class SessionTokenInjector implements TokenInjector {
+    /** targetUrl -> the session token to attach for that url. */
+    private readonly byTarget;
+    private fallback;
+    constructor(token: string | null);
+    getToken(targetUrl: string): Promise<string | null>;
+    /**
+     * Install one session's token for exactly the target urls that session will
+     * reach, for the turn that is about to run.
+     *
+     * The injector is re-pointed per turn rather than recreated, because the
+     * loopback proxy holds a reference to it for the whole process life. Two
+     * concurrent turns register DISJOINT url sets (their session ids differ), so
+     * neither can overwrite the other's slot.
+     */
+    registerTargets(targetUrls: readonly string[], token: string | null): void;
+    /**
+     * Revoke exactly one session's tokens when its turn ends.
+     *
+     * Scoped to the urls that turn owned, so a sibling turn still in flight keeps
+     * its own credential — the process-global `revoke()` blanked everyone's.
+     */
+    revokeTargets(targetUrls: readonly string[]): void;
+    /**
+     * Set the process-wide FALLBACK token. Retained for the desktop single-token
+     * path and for tests; the concurrent runner path uses `registerTargets`.
+     */
+    setToken(token: string | null): void;
+    /** Clear the fallback AND every per-target token. Used on full teardown. */
+    revoke(): void;
+}
+/**
+ * Drops everything.
+ *
+ * The runner's real event path is `POST /ingest`, driven by the session runner
+ * on the transcript it has already stored. This exists so a caller that supplies
+ * no sink does not have to null-check on the hot path of the agent loop.
+ */
+export declare class NullEventSink implements EventSink {
+    transcriptChanged(): void;
+    emit(): void;
+}
+/**
+ * Fans out to several sinks, and NEVER lets one failure hide another.
+ *
+ * The desktop needs exactly this once it can also run cloud sessions: the same
+ * transcript change goes to the renderer AND to the control plane. A sink that
+ * throws must not stop the sinks after it — the agent loop is the caller, and a
+ * broken IPC channel silently ending transcript delivery is precisely the class
+ * of bug this package exists to make impossible.
+ */
+export declare class CompositeEventSink implements EventSink {
+    private readonly sinks;
+    constructor(sinks: EventSink[]);
+    transcriptChanged(sessionId: string, maxRev: number): void;
+    emit(channel: string, payload: JsonValue): void;
+}
+export interface DirectoryWorkspaceOptions {
+    /**
+     * The root under which every session directory is created.
+     *
+     * `/var/pf/workspaces` in the sandbox image, and it is owned `pfharness:0700`
+     * — Phase 0 found it as `root:0755`, which would have stopped the harness
+     * creating session directories at all.
+     */
+    root: string;
+}
+/**
+ * One directory per session, mode 0700.
+ *
+ * DECISION 2 REMOVED THE UNIX USER PER SESSION, and `useradd` is deliberately
+ * absent from the sandbox image. The consequence is stated plainly rather than
+ * left implicit: INSIDE A TENANT, this directory is the only filesystem
+ * separation there is, and it is separation by path, not by kernel. Everything
+ * stronger is enforced by the harness and by the phase-3 MCP gateway, which is
+ * what makes that gateway load-bearing rather than merely useful.
+ *
+ * 'repository' mode is REFUSED here. Cloning a customer repository is an
+ * explicit per-agent opt-in on a runner the customer chose, so the capability
+ * belongs to a workspace provider that a self-hosted runner installs — not to
+ * the default that a shared cloud sandbox gets.
+ */
+export declare class DirectoryWorkspaceProvider implements WorkspaceProvider {
+    private readonly options;
+    constructor(options: DirectoryWorkspaceOptions);
+    prepare(request: WorkspaceRequest): Promise<string>;
+    release(sessionId: string): Promise<void>;
+    /**
+     * Session ids come from the control plane, but a PATH is built from them, so
+     * they are treated as UNTRUSTED INPUT regardless.
+     *
+     * IT REJECTS RATHER THAN SANITISES, and that distinction is the whole point.
+     * An earlier version mapped every unsafe character to `_`, which is not
+     * injective: `a/b` and `a_b` both became `<root>/a_b`. Two distinct sessions
+     * would then SHARE one workspace — and `release()` on either would delete the
+     * other's files. Decision 2 removed the unix user per session, so this
+     * directory is the only filesystem separation two sessions of one tenant have;
+     * a sanitiser that can collide quietly removes even that.
+     *
+     * The id is a control-plane identifier, so refusing an unrepresentable one
+     * costs nothing real and fails loudly instead of silently sharing state.
+     */
+    private pathFor;
+}