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

package/dist/ports-default.js

@@ -0,0 +1,333 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DirectoryWorkspaceProvider = exports.CompositeEventSink = exports.NullEventSink = exports.SessionTokenInjector = exports.StaticTaskMcpProvider = exports.NoArtifactInspector = exports.NoSecretProvider = exports.ServerNotifier = exports.NoopTelemetry = void 0;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+/* -------------------------------------------------------------------------- */
+/* Telemetry                                                                   */
+/* -------------------------------------------------------------------------- */
+/**
+ * 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.
+ */
+class NoopTelemetry {
+    record() {
+        // Deliberately empty.
+    }
+}
+exports.NoopTelemetry = NoopTelemetry;
+/* -------------------------------------------------------------------------- */
+/* Notifier                                                                    */
+/* -------------------------------------------------------------------------- */
+/** No human at this machine, and nothing that sleeps. */
+class ServerNotifier {
+    notify() {
+        // Deliberately empty.
+    }
+    keepAwake() {
+        return () => {
+            // Deliberately empty.
+        };
+    }
+}
+exports.ServerNotifier = ServerNotifier;
+/* -------------------------------------------------------------------------- */
+/* Secrets                                                                     */
+/* -------------------------------------------------------------------------- */
+/**
+ * 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.
+ */
+class NoSecretProvider {
+    getBrokerPort() {
+        return null;
+    }
+    registerSession() {
+        // Nothing to authorise.
+    }
+    unregisterSession() {
+        // Nothing to revoke.
+    }
+    writeShellWrapper() {
+        return null;
+    }
+    getSecretEnv() {
+        return {};
+    }
+}
+exports.NoSecretProvider = NoSecretProvider;
+/* -------------------------------------------------------------------------- */
+/* Artifacts                                                                   */
+/* -------------------------------------------------------------------------- */
+/**
+ * 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.
+ */
+class NoArtifactInspector {
+    async inspect() {
+        return null;
+    }
+}
+exports.NoArtifactInspector = NoArtifactInspector;
+/* -------------------------------------------------------------------------- */
+/* Task MCP                                                                    */
+/* -------------------------------------------------------------------------- */
+/**
+ * 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).
+ */
+class StaticTaskMcpProvider {
+    url;
+    constructor(url) {
+        this.url = url;
+    }
+    async getUrl() {
+        return this.url;
+    }
+}
+exports.StaticTaskMcpProvider = StaticTaskMcpProvider;
+/* -------------------------------------------------------------------------- */
+/* Tokens                                                                      */
+/* -------------------------------------------------------------------------- */
+/**
+ * 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.
+ */
+class SessionTokenInjector {
+    /** targetUrl -> the session token to attach for that url. */
+    byTarget = new Map();
+    fallback;
+    constructor(token) {
+        this.fallback = token;
+    }
+    async getToken(targetUrl) {
+        return this.byTarget.has(targetUrl)
+            ? (this.byTarget.get(targetUrl) ?? null)
+            : this.fallback;
+    }
+    /**
+     * 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, token) {
+        for (const url of targetUrls) {
+            this.byTarget.set(url, token);
+        }
+    }
+    /**
+     * 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) {
+        for (const url of targetUrls) {
+            this.byTarget.delete(url);
+        }
+    }
+    /**
+     * Set the process-wide FALLBACK token. Retained for the desktop single-token
+     * path and for tests; the concurrent runner path uses `registerTargets`.
+     */
+    setToken(token) {
+        this.fallback = token;
+    }
+    /** Clear the fallback AND every per-target token. Used on full teardown. */
+    revoke() {
+        this.fallback = null;
+        this.byTarget.clear();
+    }
+}
+exports.SessionTokenInjector = SessionTokenInjector;
+/* -------------------------------------------------------------------------- */
+/* Events                                                                      */
+/* -------------------------------------------------------------------------- */
+/**
+ * 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.
+ */
+class NullEventSink {
+    transcriptChanged() {
+        // Deliberately empty.
+    }
+    emit() {
+        // Deliberately empty.
+    }
+}
+exports.NullEventSink = NullEventSink;
+/**
+ * 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.
+ */
+class CompositeEventSink {
+    sinks;
+    constructor(sinks) {
+        this.sinks = sinks;
+    }
+    transcriptChanged(sessionId, maxRev) {
+        for (const sink of this.sinks) {
+            try {
+                sink.transcriptChanged(sessionId, maxRev);
+            }
+            catch {
+                // Isolated on purpose. See the class comment.
+            }
+        }
+    }
+    emit(channel, payload) {
+        for (const sink of this.sinks) {
+            try {
+                sink.emit(channel, payload);
+            }
+            catch {
+                // Isolated on purpose.
+            }
+        }
+    }
+}
+exports.CompositeEventSink = CompositeEventSink;
+/**
+ * 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.
+ */
+class DirectoryWorkspaceProvider {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async prepare(request) {
+        if (request.mode === 'repository') {
+            throw new Error('Repository workspaces are not available on this runner. ' +
+                'Repository access is an explicit per-agent opt-in on a self-hosted runner.');
+        }
+        const dir = this.pathFor(request.sessionId);
+        // 0700, and recursive so a fresh host with no root directory still works.
+        await (0, promises_1.mkdir)(dir, { recursive: true, mode: 0o700 });
+        return dir;
+    }
+    async release(sessionId) {
+        // `force` so releasing a session that never got a directory — an abort
+        // before the first turn — is not an error on a shutdown path.
+        await (0, promises_1.rm)(this.pathFor(sessionId), { recursive: true, force: true });
+    }
+    /**
+     * 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.
+     */
+    pathFor(sessionId) {
+        if (!/^[a-zA-Z0-9._-]+$/.test(sessionId)) {
+            throw new Error(`Unusable session id for a workspace path: ${JSON.stringify(sessionId)}. Expected only [A-Za-z0-9._-].`);
+        }
+        if (sessionId === '.' || sessionId === '..') {
+            throw new Error(`Unusable session id for a workspace path: ${sessionId}`);
+        }
+        const root = (0, node_path_1.resolve)(this.options.root);
+        const dir = (0, node_path_1.resolve)((0, node_path_1.join)(root, sessionId));
+        // Belt and braces. The check above already excludes a separator, but a
+        // path that escaped here would let one session read another's workspace,
+        // and that is not a thing to protect with a single regular expression.
+        if (dir !== root && !dir.startsWith(root + '/')) {
+            throw new Error(`Workspace path escaped the root: ${sessionId}`);
+        }
+        return dir;
+    }
+}
+exports.DirectoryWorkspaceProvider = DirectoryWorkspaceProvider;