@peakflo/agent-harness 0.0.0-stage → 0.2.1-rc.3

package/dist/types.js

@@ -0,0 +1,55 @@
+"use strict";
+/**
+ * THE RUNNER WIRE CONTRACT — the single meeting point between the control
+ * plane (Track A, workflow-builder) and the harness (Track B, extracted from
+ * 20x).
+ *
+ * This file is the contract. `packages/agentSandbox/test/control-plane-stub.mjs`
+ * is the SAME contract in executable form. The two are kept in lockstep on
+ * purpose: prose drifts, a running stub does not.
+ *
+ * FOUR PROPERTIES THAT ARE NOT NEGOTIABLE
+ *
+ * 1. VERSIONED. Every request carries `protocolVersion`. A harness below the
+ *    control plane's floor is refused, and the refusal is FINAL — the harness
+ *    exits so the host is recycled onto a supported version. See
+ *    `./contract.ts`.
+ *
+ * 2. OUTBOUND ONLY. Nothing here requires the harness to accept an inbound
+ *    connection. Work is delivered by a bounded long-poll (`GET .../lease`),
+ *    never by the control plane dialling in. That single property is what lets
+ *    a customer VM behind NAT work with no tunnel and no listening port.
+ *    Anything that needs to reach a running harness — abort, an answer to a
+ *    question — travels back on the NEXT poll, which is why
+ *    `RunnerHeartbeatResponse.sessionCommands` exists.
+ *
+ * 3. RUNTIME NEUTRAL. A Daytona sandbox, a customer VM and the 20x desktop are
+ *    the same client. There is no route, field or token that only one of them
+ *    can use. `POST /api/coding-agents/sessions/:id/ingest` in particular is
+ *    identical for all three; that is the whole payoff of the extraction.
+ *
+ * 4. TOKENS TRAVEL IN THE ENVIRONMENT OR IN HEADERS, NEVER IN ARGV.
+ *    `/proc/<pid>/cmdline` is world-readable; `/proc/<pid>/environ` is readable
+ *    only by the process owner. Every credential below is either an
+ *    `Authorization: Bearer` header or an environment variable handed to a
+ *    child process. Do not "improve" this by adding a `--token` flag.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+/* -------------------------------------------------------------------------- */
+/* Phase 0 bootstrap shapes — REMOVED                                          */
+/* -------------------------------------------------------------------------- */
+/*
+ * `RegisterRequest`, `RegisterResponse`, `HeartbeatRequest` and
+ * `HeartbeatResponse` described the Phase 0 routes
+ * `/api/coding-agents/harness/{register,heartbeat}`. Both routes and all four
+ * shapes are gone.
+ *
+ * They were never aliases of the runner protocol: they carried no
+ * `protocolVersion`, so that path could not be protocol-version gated, and it
+ * was the only registration route running in production. Deleting them removes
+ * the last route exempt from the versioning guarantee.
+ *
+ * The replacements are `RunnerRegisterRequest`/`RunnerRegisterResponse` and
+ * `RunnerHeartbeatRequest`/`RunnerHeartbeatResponse` above. `sandboxToken` and
+ * `sandboxId` became `runnerCredential` and `runnerId`.
+ */

package/dist/version.d.ts

@@ -0,0 +1,32 @@
+/** The version of THIS package, as installed. */
+export declare function getHarnessVersion(): string;
+/**
+ * The version of the SANDBOX TOOLS layer (gh, @peculiar/x509, ...) currently
+ * installed, or null when nothing was ever synced — a self-hosted runner or
+ * desktop, or a sandbox that booted before this layer existed.
+ *
+ * Set by pf-bootstrap on the child environment it hands to the harness,
+ * `PF_INSTALLED_TOOLS_VERSION`, AFTER it resolved (fetched, reused, or fell
+ * back to) a tools install — never guessed by the harness itself, the same
+ * way `PF_HARNESS_DEGRADED` is reported rather than inferred.
+ */
+export declare function getInstalledSandboxToolsVersion(): string | null;
+/**
+ * The tools pin pf-bootstrap most recently TRIED to install and could not
+ * make stick this boot (a bad hash, a registry outage, a malformed pin —
+ * anything that made it fall back or keep the prior install instead). Set
+ * on the harness's own environment, alongside `PF_INSTALLED_TOOLS_VERSION`.
+ *
+ * Read by `observeSandboxToolsPin()` to avoid re-arming a drain for the
+ * EXACT SAME pin the current boot cycle already gave up on — without this,
+ * a standing bad pin in a control-plane secret spins every affected sandbox
+ * in an unbounded drain -> exit-75 -> reboot -> fallback -> still-mismatched
+ * loop that takes zero leases the entire time.
+ */
+export declare function getAttemptedSandboxToolsVersion(): string | null;
+/**
+ * The `pi` version baked into the snapshot, or null when the binary is
+ * absent. Reported at registration so the control plane can see the runtime
+ * matrix of its fleet without shelling into a sandbox.
+ */
+export declare function getPiVersion(): string | null;

package/dist/version.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getHarnessVersion = getHarnessVersion;
+exports.getInstalledSandboxToolsVersion = getInstalledSandboxToolsVersion;
+exports.getAttemptedSandboxToolsVersion = getAttemptedSandboxToolsVersion;
+exports.getPiVersion = getPiVersion;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+let cachedHarnessVersion = null;
+let cachedPiVersion;
+/** The version of THIS package, as installed. */
+function getHarnessVersion() {
+    if (cachedHarnessVersion) {
+        return cachedHarnessVersion;
+    }
+    try {
+        const pkg = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(__dirname, '..', 'package.json'), 'utf8'));
+        cachedHarnessVersion = pkg.version ?? '0.0.0';
+    }
+    catch {
+        cachedHarnessVersion = '0.0.0';
+    }
+    return cachedHarnessVersion;
+}
+/**
+ * The version of the SANDBOX TOOLS layer (gh, @peculiar/x509, ...) currently
+ * installed, or null when nothing was ever synced — a self-hosted runner or
+ * desktop, or a sandbox that booted before this layer existed.
+ *
+ * Set by pf-bootstrap on the child environment it hands to the harness,
+ * `PF_INSTALLED_TOOLS_VERSION`, AFTER it resolved (fetched, reused, or fell
+ * back to) a tools install — never guessed by the harness itself, the same
+ * way `PF_HARNESS_DEGRADED` is reported rather than inferred.
+ */
+function getInstalledSandboxToolsVersion() {
+    const value = process.env.PF_INSTALLED_TOOLS_VERSION;
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+/**
+ * The tools pin pf-bootstrap most recently TRIED to install and could not
+ * make stick this boot (a bad hash, a registry outage, a malformed pin —
+ * anything that made it fall back or keep the prior install instead). Set
+ * on the harness's own environment, alongside `PF_INSTALLED_TOOLS_VERSION`.
+ *
+ * Read by `observeSandboxToolsPin()` to avoid re-arming a drain for the
+ * EXACT SAME pin the current boot cycle already gave up on — without this,
+ * a standing bad pin in a control-plane secret spins every affected sandbox
+ * in an unbounded drain -> exit-75 -> reboot -> fallback -> still-mismatched
+ * loop that takes zero leases the entire time.
+ */
+function getAttemptedSandboxToolsVersion() {
+    const value = process.env.PF_ATTEMPTED_TOOLS_VERSION;
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+/**
+ * The `pi` version baked into the snapshot, or null when the binary is
+ * absent. Reported at registration so the control plane can see the runtime
+ * matrix of its fleet without shelling into a sandbox.
+ */
+function getPiVersion() {
+    if (cachedPiVersion !== undefined) {
+        return cachedPiVersion;
+    }
+    try {
+        const out = (0, node_child_process_1.execFileSync)('pi', ['--version'], {
+            encoding: 'utf8',
+            timeout: 10_000,
+            stdio: ['ignore', 'pipe', 'ignore']
+        });
+        cachedPiVersion = out.trim() || null;
+    }
+    catch {
+        cachedPiVersion = null;
+    }
+    return cachedPiVersion;
+}

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@peakflo/agent-harness",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.1-rc.3",
+  "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",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "pf-agent-harness": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.19"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json && node scripts/make-executable.mjs",
+    "dev": "tsc -p tsconfig.json --watch --preserveWatchOutput",
+    "start": "tsx src/cli.ts start",
+    "clean": "rm -rf dist",
+    "test": "jest"
+  },
+  "devDependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.3.195",
+    "@opencode-ai/sdk": "^1.15.13",
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.3",
+    "typescript": "^5.7.2",
+    "undici": "^7.21.0"
+  },
+  "dependencies": {
+    "@peculiar/x509": "^2.1.0",
+    "reflect-metadata": "^0.2.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/peakflo/workflow-builder.git",
+    "directory": "packages/agent-harness"
+  },
+  "homepage": "https://github.com/peakflo/workflow-builder/tree/main/packages/agent-harness",
+  "keywords": [
+    "peakflo",
+    "agent",
+    "runner",
+    "harness"
+  ]
+}