@peakflo/agent-harness 0.2.13 → 0.2.14-rc.2

package/dist/control-plane.js

@@ -114,15 +114,23 @@ class ControlPlaneClient {
     getRunnerId() {
         return this.runnerId;
     }
-    /** Diagnostics must never delay a turn. The caller handles any failure. */
-    async reportColdStart(line) {
+    /**
+     * All cold-start timing events of one turn in ONE request. Diagnostics
+     * must never delay a turn; the caller handles any failure.
+     *
+     * This replaced one POST per step. The control plane accepts both shapes,
+     * so an older harness on an existing sandbox keeps working.
+     */
+    async reportColdStartBatch(body) {
         if (!this.runnerId || !this.runnerCredential)
             return;
+        if (body.events.length === 0)
+            return;
         await this.send({
             method: 'POST',
             path: contract_1.ROUTES.coldStart(this.runnerId),
             token: this.runnerCredential,
-            body: JSON.parse(line),
+            body,
             timeoutMs: 2_000
         });
     }

package/dist/github-proxy-certificates.d.ts

@@ -3,6 +3,9 @@ export interface GitHubProxyCertificateOptions {
     /** Override only for deterministic tests. Production preserves process.env. */
     environment?: NodeJS.ProcessEnv;
 }
+export declare function ambientCaCertificates(environment: NodeJS.ProcessEnv, outputPath: string): Promise<Buffer[]>;
+/** Node's bundled public roots, PEM, newline-terminated. */
+export declare function publicRootCertificates(): string;
 export interface GitHubProxyCertificates {
     caCertificate: Buffer;
     caCertificatePath: string;

package/dist/github-proxy-certificates.js

@@ -1,5 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ambientCaCertificates = ambientCaCertificates;
+exports.publicRootCertificates = publicRootCertificates;
 exports.createGitHubProxyCertificates = createGitHubProxyCertificates;
 require("reflect-metadata");
 const node_crypto_1 = require("node:crypto");
@@ -54,6 +56,10 @@ async function ambientCaCertificates(environment, outputPath) {
     }
     return certificates;
 }
+/** Node's bundled public roots, PEM, newline-terminated. */
+function publicRootCertificates() {
+    return `${node_tls_1.rootCertificates.join('\n')}\n`;
+}
 function validity() {
     const now = Date.now();
     return {
@@ -103,7 +109,7 @@ async function createGitHubProxyCertificates(stateRoot, options = {}) {
     const caCertificate = Buffer.from(ca.toString('pem'));
     const caCertificatePath = (0, node_path_1.join)(root, CA_CERTIFICATE_FILE);
     const ambientRoots = await ambientCaCertificates(options.environment ?? process.env, caCertificatePath);
-    const publicRoots = `${node_tls_1.rootCertificates.join('\n')}\n`;
+    const publicRoots = publicRootCertificates();
     await (0, promises_1.writeFile)(caCertificatePath, Buffer.concat([...ambientRoots, Buffer.from(publicRoots), caCertificate]), { mode: 0o644 });
     await (0, promises_1.chmod)(caCertificatePath, 0o644);
     const leaves = new Map();

package/dist/github-workspace.d.ts

@@ -11,6 +11,12 @@ export interface GitHubWorkspaceOptions {
     /** Injected in tests: the proxy's peer-uid lookup. See `GitHubTlsProxy`. */
     peerUid?: PeerUidResolver;
 }
+/**
+ * Hostnames of URLs the agent reaches WITHOUT a proxy (control plane, model
+ * gateway, MCP). Shared with the credential proxy's NO_PROXY so both proxies
+ * bypass exactly the same hosts.
+ */
+export declare function directHostnames(urls: string[]): string[];
 /** Bare clone plus one worktree per session, adapted from 20x. */
 export declare class GitHubWorkspaceProvider implements WorkspaceProvider {
     private readonly options;

package/dist/github-workspace.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GitHubWorkspaceProvider = void 0;
+exports.directHostnames = directHostnames;
 const node_child_process_1 = require("node:child_process");
 const node_crypto_1 = require("node:crypto");
 const node_fs_1 = require("node:fs");
@@ -17,6 +18,25 @@ const DEFAULT_PROXY_PORT = 7780;
 const LINK_SECRET_FILE = '.github-proxy-link-secret';
 const WIP_PUSH_FAILED_FILE = '.worktree-wip-push-failed';
 const WIP_COMMIT_MESSAGE = 'chore(agent): wip — uncommitted at turn end';
+/**
+ * Hostnames of URLs the agent reaches WITHOUT a proxy (control plane, model
+ * gateway, MCP). Shared with the credential proxy's NO_PROXY so both proxies
+ * bypass exactly the same hosts.
+ */
+function directHostnames(urls) {
+    const hosts = [];
+    for (const value of urls) {
+        if (!value)
+            continue;
+        try {
+            hosts.push(new URL(value).hostname.toLowerCase());
+        }
+        catch {
+            /* The component that owns an invalid URL reports it. */
+        }
+    }
+    return hosts;
+}
 /** Bare clone plus one worktree per session, adapted from 20x. */
 class GitHubWorkspaceProvider {
     options;
@@ -46,16 +66,8 @@ class GitHubWorkspaceProvider {
         this.rememberDirectUrls(options.directUrls ?? []);
     }
     rememberDirectUrls(urls) {
-        for (const value of urls) {
-            if (!value)
-                continue;
-            try {
-                this.directHosts.add(new URL(value).hostname.toLowerCase());
-            }
-            catch {
-                /* The component that owns an invalid URL reports it. */
-            }
-        }
+        for (const host of directHostnames(urls))
+            this.directHosts.add(host);
     }
     runGit(args, options = {}) {
         const { environment, ...execOptions } = options;

package/dist/harness.d.ts

@@ -249,6 +249,8 @@ export declare class Harness {
     private readonly activeLeaseIds;
     /** Renewal workers that must receive a credential rotation in flight. */
     private readonly activeRenewals;
+    /** Cold-start timing buffered per running turn; sent once at turn end. */
+    private readonly coldStartBatches;
     /** commandIds already applied. `SessionCommand` is idempotent by contract. */
     private readonly appliedCommands;
     /** Prune lease-bound command IDs when their session turn ends. */
@@ -473,6 +475,7 @@ export declare class Harness {
     private observeSandboxToolsPin;
     /** Stop once. A failed install is then the supervisor's terminal decision. */
     private requestUpgrade;
+    private newColdStartBatch;
     /**
      * Run one leased turn.
      *

package/dist/harness.js

@@ -18,6 +18,7 @@ const health_1 = require("./health");
 const model_probe_1 = require("./model-probe");
 const ports_default_1 = require("./ports-default");
 const browser_takeover_1 = require("./runtime/browser-takeover");
+const cold_start_batch_1 = require("./runtime/cold-start-batch");
 const knowledge_tools_1 = require("./runtime/knowledge-tools");
 const lease_renewal_1 = require("./runtime/lease-renewal");
 const mcp_auth_proxy_1 = require("./runtime/mcp-auth-proxy");
@@ -200,7 +201,9 @@ class Harness {
     mcpCheckState = {
         checked: new Map(),
         failed: new Map(),
-        shownNotices: new Set()
+        shownNotices: new Set(),
+        // Item 1(b): per-session MCP tool listings, reused on warm turns.
+        toolsets: new Map()
     };
     startedAt = Date.now();
     status = 'starting';
@@ -265,6 +268,8 @@ class Harness {
     activeLeaseIds = new Map();
     /** Renewal workers that must receive a credential rotation in flight. */
     activeRenewals = new Set();
+    /** Cold-start timing buffered per running turn; sent once at turn end. */
+    coldStartBatches = new Set();
     /** commandIds already applied. `SessionCommand` is idempotent by contract. */
     appliedCommands = new Set();
     /** Prune lease-bound command IDs when their session turn ends. */
@@ -515,6 +520,11 @@ class Harness {
         for (const controller of this.active.values()) {
             controller.abort();
         }
+        // Send buffered turn timing while the credential is still valid.
+        // Deregistration below revokes it. Each send has a 2 s timeout.
+        const coldStarts = Array.from(this.coldStartBatches);
+        this.coldStartBatches.clear();
+        await Promise.all(coldStarts.map((batch) => batch.flush()));
         /*
          * A DURABLE RUNNER DOES NOT DEREGISTER.
          *
@@ -1565,7 +1575,9 @@ class Harness {
                 durationMs: Date.now() - pollStartedAt
             });
             log(leaseReceived);
-            void this.client.reportColdStart(leaseReceived).catch(() => undefined);
+            // Buffered, not sent: the whole turn's timing goes out as ONE request.
+            const coldStart = this.newColdStartBatch(lease);
+            coldStart.add(leaseReceived);
             this.observeHarnessPin(lease.harnessVersion);
             this.observeSandboxToolsPin(lease.sandboxToolsVersion);
             // Protocol 3 uses a short visibility window until the runner confirms
@@ -1593,10 +1605,12 @@ class Harness {
                 }
             }
             if (!leaseAcknowledged) {
+                this.coldStartBatches.delete(coldStart);
+                void coldStart.flush();
                 await sleep(LEASE_ERROR_BACKOFF_MS);
                 continue;
             }
-            void this.runLeasedTurn(lease);
+            void this.runLeasedTurn(lease, coldStart);
         }
         await this.stop();
     }
@@ -1680,6 +1694,11 @@ class Harness {
         this.fatal = new UpgradeRequestedError(harnessVersion);
         await this.stop({ preserveRegistration: true });
     }
+    newColdStartBatch(lease) {
+        const batch = new cold_start_batch_1.ColdStartBatch(lease.session.sessionId, lease.session.turnId, (body) => this.client.reportColdStartBatch(body));
+        this.coldStartBatches.add(batch);
+        return batch;
+    }
     /**
      * Run one leased turn.
      *
@@ -1688,7 +1707,7 @@ class Harness {
      * throws must not end the lease loop, or one bad session would take the whole
      * runner offline.
      */
-    async runLeasedTurn(lease) {
+    async runLeasedTurn(lease, coldStart = this.newColdStartBatch(lease)) {
         const { sessionId } = lease.session;
         // The exact loopback-proxy targets this session will reach. Keyed on these
         // urls, this session's MCP token cannot be overwritten or revoked by a
@@ -1852,9 +1871,9 @@ class Harness {
             secrets: this.secrets,
             events: this.events,
             telemetry: this.telemetry,
-            coldStartLog: (line) => {
-                void this.client.reportColdStart(line).catch(() => undefined);
-            },
+            coldStartLog: (line) => coldStart.add(line),
+            runtime: this.options.runtime,
+            directUrls: [this.options.controlPlaneUrl],
             notifier: this.notifier,
             artifacts: this.artifacts,
             conversation: this.conversation,
@@ -1938,6 +1957,10 @@ class Harness {
         finally {
             renewal.stop();
             this.activeRenewals.delete(renewal);
+            // ONE telemetry request for the whole turn, sent before the git
+            // preservation below so slow pushes do not delay it. Fire-and-forget.
+            this.coldStartBatches.delete(coldStart);
+            void coldStart.flush();
             let workProtected = true;
             if ((this.options.autoCommitDirtyWorktree ??
                 this.options.runtime === 'sandbox') &&

package/dist/index.d.ts

@@ -59,4 +59,4 @@ export * from './adapters';
  * "ephemeral" means. A rule written twice is a rule that drifts.
  */
 export { CONTRACT_ERROR_CODES, DEFAULT_BASE_DELAY_MS, DEFAULT_HEARTBEAT_INTERVAL_MS, DEFAULT_LEASE_TTL_MS, DEFAULT_LEASE_WAIT_SECONDS, DEFAULT_MAX_ATTEMPTS, EPHEMERAL_PART_TYPES, FINAL_HTTP_STATUSES, HARNESS_UPGRADE_EXIT_CODE, MAX_INGEST_PARTS, MAX_INGEST_PART_BYTES, MAX_LEASE_WAIT_SECONDS, MIN_SUPPORTED_PROTOCOL_VERSION, MISSED_HEARTBEATS_BEFORE_OFFLINE, PERSISTED_PART_TYPES, PROTOCOL_VERSION, PROTOCOL_VERSION_HEADER, ROUTES, ingestPartByteLength, isEphemeralPartType, isFinalStatus, isPersistablePart, isProtocolSupported } from './contract';
-export type { BootstrapRequest, BootstrapResponse, ControlPlaneErrorBody, CredentialRotateRequest, CredentialRotateResponse, DeregisterRequest, DeregisterResponse, HarnessOptions, HealthReport, IngestRejection, IngestRejectionReason, IngestRequest, IngestResponse, JsonValue, LeaseRenewRequest, LeaseRenewResponse, LeaseResponse, LeasedAgent, LeasedAttachment, LeasedLimits, LeasedMcpServer, LeasedModel, LeasedSession, LeasedSkill, LeasedTurnInput, LeasedWorkspace, LeasedGitHubCredential, LeasedGitHubRepository, ProtocolEnvelope, RunnerBackend, RunnerCapabilities, RunnerHeartbeatRequest, RunnerHeartbeatResponse, RunnerModel, RunnerRegisterRequest, RunnerRegisterResponse, RunnerRuntime, RunnerStatus, SessionCommand, TranscriptPart, TranscriptPartInput, TurnMetadata } from './types';
+export type { BootstrapRequest, BootstrapResponse, ControlPlaneErrorBody, CredentialRotateRequest, CredentialRotateResponse, DeregisterRequest, DeregisterResponse, HarnessOptions, HealthReport, IngestRejection, IngestRejectionReason, IngestRequest, IngestResponse, JsonValue, LeaseRenewRequest, LeaseRenewResponse, LeaseResponse, LeasedAgent, LeasedAttachment, LeasedCredentialProxy, LeasedLimits, LeasedMcpServer, LeasedModel, LeasedSession, LeasedSkill, LeasedTurnInput, LeasedWorkspace, LeasedGitHubCredential, LeasedGitHubRepository, ProtocolEnvelope, RunnerBackend, RunnerCapabilities, RunnerHeartbeatRequest, RunnerHeartbeatResponse, RunnerModel, RunnerRegisterRequest, RunnerRegisterResponse, RunnerRuntime, RunnerStatus, SessionCommand, TranscriptPart, TranscriptPartInput, TurnMetadata } from './types';

package/dist/runtime/cold-start-batch.d.ts

@@ -0,0 +1,36 @@
+/**
+ * One cold-start telemetry POST per turn instead of one per step.
+ *
+ * `ColdStartSteps` and the Pi adapter emit 13–15 timing lines per turn. Each
+ * used to become its own `POST /runners/:id/cold-start` (auth + turn lookup on
+ * the server every time). This buffer collects the lines for ONE turn and the
+ * harness sends them as a single batch when the turn ends, or when the
+ * harness stops. It is diagnostics only: it never throws, never blocks a turn
+ * and never retries.
+ */
+/** Events the control plane records. Anything else stays in the local log. */
+export declare const COLD_START_EVENTS: ReadonlySet<string>;
+/** Mirrors the server limit in `services/coding-agents/cold-start-telemetry.ts`. */
+export declare const COLD_START_BATCH_MAX_EVENTS = 64;
+export interface ColdStartBatchBody {
+    sessionId: string;
+    turnId: string;
+    events: Array<Record<string, unknown>>;
+}
+export declare class ColdStartBatch {
+    readonly sessionId: string;
+    readonly turnId: string;
+    private readonly send;
+    /** Lines that arrive after the turn-end flush are coalesced this long. */
+    private readonly lateFlushMs;
+    private events;
+    private flushed;
+    private lateTimer;
+    constructor(sessionId: string, turnId: string, send: (body: ColdStartBatchBody) => Promise<void>, 
+    /** Lines that arrive after the turn-end flush are coalesced this long. */
+    lateFlushMs?: number);
+    /** Buffer one JSON line from `ColdStartSteps`. Never throws. */
+    add(line: string): void;
+    /** Send everything buffered as ONE request. Resolves; never rejects. */
+    flush(): Promise<void>;
+}

package/dist/runtime/cold-start-batch.js

@@ -0,0 +1,96 @@
+"use strict";
+/**
+ * One cold-start telemetry POST per turn instead of one per step.
+ *
+ * `ColdStartSteps` and the Pi adapter emit 13–15 timing lines per turn. Each
+ * used to become its own `POST /runners/:id/cold-start` (auth + turn lookup on
+ * the server every time). This buffer collects the lines for ONE turn and the
+ * harness sends them as a single batch when the turn ends, or when the
+ * harness stops. It is diagnostics only: it never throws, never blocks a turn
+ * and never retries.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ColdStartBatch = exports.COLD_START_BATCH_MAX_EVENTS = exports.COLD_START_EVENTS = void 0;
+/** Events the control plane records. Anything else stays in the local log. */
+exports.COLD_START_EVENTS = new Set([
+    'cold_start_step',
+    'cold_start_summary',
+    'model_catalogue_deferred'
+]);
+/** Mirrors the server limit in `services/coding-agents/cold-start-telemetry.ts`. */
+exports.COLD_START_BATCH_MAX_EVENTS = 64;
+class ColdStartBatch {
+    sessionId;
+    turnId;
+    send;
+    lateFlushMs;
+    events = [];
+    flushed = false;
+    lateTimer = null;
+    constructor(sessionId, turnId, send, 
+    /** Lines that arrive after the turn-end flush are coalesced this long. */
+    lateFlushMs = 1_000) {
+        this.sessionId = sessionId;
+        this.turnId = turnId;
+        this.send = send;
+        this.lateFlushMs = lateFlushMs;
+    }
+    /** Buffer one JSON line from `ColdStartSteps`. Never throws. */
+    add(line) {
+        try {
+            const event = JSON.parse(line);
+            if (!event || typeof event !== 'object' || Array.isArray(event))
+                return;
+            const record = event;
+            if (typeof record.event !== 'string' ||
+                !exports.COLD_START_EVENTS.has(record.event) ||
+                record.sessionId !== this.sessionId ||
+                record.turnId !== this.turnId) {
+                return;
+            }
+            // The batch carries the ids once; per-event copies are redundant bytes.
+            const rest = { ...record };
+            delete rest.sessionId;
+            delete rest.turnId;
+            this.events.push(rest);
+            if (this.events.length >= exports.COLD_START_BATCH_MAX_EVENTS) {
+                void this.flush();
+            }
+            else if (this.flushed && !this.lateTimer) {
+                // A step that ends after the turn-end flush (rare) is still sent,
+                // coalesced with any others that follow it.
+                this.lateTimer = setTimeout(() => {
+                    this.lateTimer = null;
+                    void this.flush();
+                }, this.lateFlushMs);
+                this.lateTimer.unref?.();
+            }
+        }
+        catch {
+            // A diagnostic sink must never stop an agent turn.
+        }
+    }
+    /** Send everything buffered as ONE request. Resolves; never rejects. */
+    flush() {
+        this.flushed = true;
+        if (this.lateTimer) {
+            clearTimeout(this.lateTimer);
+            this.lateTimer = null;
+        }
+        if (this.events.length === 0)
+            return Promise.resolve();
+        const events = this.events;
+        this.events = [];
+        try {
+            return this.send({
+                sessionId: this.sessionId,
+                turnId: this.turnId,
+                events
+            }).catch(() => undefined);
+        }
+        catch {
+            return Promise.resolve();
+        }
+    }
+}
+exports.ColdStartBatch = ColdStartBatch;

package/dist/runtime/credential-proxy.d.ts

@@ -0,0 +1,44 @@
+import type { LeasedCredentialProxy, RunnerRuntime } from '../types';
+export declare const CREDENTIAL_PROXY_CA_BUNDLE_FILE = ".pf-credential-proxy-ca.pem";
+export declare const CREDENTIAL_PROXY_HEALTH_TIMEOUT_MS = 1000;
+export declare const CREDENTIAL_PROXY_TOKEN_REDACTION = "[credential-proxy-token]";
+/** Every key this module may add or replace. Nothing else is ever touched. */
+export declare const CREDENTIAL_PROXY_ENV_KEYS: readonly ["HTTPS_PROXY", "https_proxy", "HTTP_PROXY", "http_proxy", "NO_PROXY", "no_proxy", "SSL_CERT_FILE", "CURL_CA_BUNDLE", "NODE_EXTRA_CA_CERTS", "GIT_SSL_CAINFO", "REQUESTS_CA_BUNDLE", "PF_CREDENTIAL_PROXY"];
+export type CredentialProxyUnavailableReason = 'not_offered' | 'runtime_not_sandbox' | 'vendor_backend' | 'invalid_descriptor' | 'health_check_failed' | 'ca_unreadable' | 'bundle_write_failed';
+export interface CredentialProxyEnvironmentInput {
+    /** The HARNESS's own runtime (its CLI/env option), not the lease's claim. */
+    harnessRuntime: RunnerRuntime | undefined;
+    /** The lease's session runtime. Both must say `sandbox`. */
+    sessionRuntime: RunnerRuntime | string | undefined;
+    backend: string;
+    sessionId: string;
+    /** Session directory; the merged CA bundle is written here, 0644. */
+    sessionDir: string;
+    descriptor: LeasedCredentialProxy | undefined | null;
+    /** The environment the turn would get today (GitHub's, or undefined). */
+    environment: Record<string, string> | undefined;
+    /** Hosts the agent reaches directly (gateway, MCP, control plane...). */
+    directUrls: string[];
+    logger: Pick<Console, 'log' | 'warn'>;
+    /** Tests only. Production reads process.env, like the GitHub bundle. */
+    ambientEnvironment?: NodeJS.ProcessEnv;
+}
+export interface CredentialProxyEnvironmentResult {
+    environment: Record<string, string> | undefined;
+    /** Non-null exactly when the proxy variables were applied. */
+    token: string | null;
+    reason: CredentialProxyUnavailableReason | null;
+}
+/** TCP connect to 127.0.0.1:port; true when it connects within the timeout. */
+export declare function probeLoopbackPort(port: number, timeoutMs?: number): Promise<boolean>;
+/** The GitHub proxy's loopback port, read off the env GitHub already built. */
+export declare function githubProxyPort(environment: Record<string, string> | undefined): number | null;
+export declare function credentialProxyEnvironment(input: CredentialProxyEnvironmentInput): Promise<CredentialProxyEnvironmentResult>;
+/** Replace every occurrence of `token` in a string. No-op without a token. */
+export declare function redactCredentialProxyToken(text: string, token: string | null): string;
+/**
+ * Same, for a JSON-shaped value (transcript parts, turn metadata). The token
+ * alphabet needs no JSON escaping, so a string split over the serialised form
+ * finds every occurrence in every nested string.
+ */
+export declare function redactCredentialProxyTokenDeep<T>(value: T, token: string | null): T;