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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Peakflo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,69 @@
-# Temporary Holding Version
+# @peakflo/agent-harness
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Run a Peakflo coding agent on your machine.
+
+## Quick start
+
+Use Node.js 22.19 or newer and install Git. Install the Pi coding agent once:
+
+```sh
+npm install -g --ignore-scripts @earendil-works/pi-coding-agent
+```
+
+Start a runner for staging or production:
+
+```sh
+npx @peakflo/agent-harness@rc start --control-plane https://stage-api.peakflo.ai
+npx @peakflo/agent-harness@latest start --control-plane https://api.peakflo.ai
+```
+
+The runner opens a browser sign-in page. Sign in and select your organisation.
+The runner then receives an enrolment token and starts its health service.
+Check it in another terminal:
+
+```sh
+curl http://127.0.0.1:7777/health
+```
+
+To start without a browser, get an enrolment token from your Peakflo
+administrator and pass it through the environment:
+
+```sh
+PF_ENROLMENT_TOKEN='<token>' npx @peakflo/agent-harness@rc start --control-plane https://stage-api.peakflo.ai
+```
+
+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.
+
+## Releasing
+
+`.github/scripts/agent-harness-release.mjs` publishes this package
+automatically: an rc from `main` on every push, a final from `production`.
+**`version` in this package's `package.json` is a FLOOR, not the release** —
+the lowest version the pipeline may produce, not the version it will produce.
+The pipeline reads the registry and computes the actual version on every run:
+
+1. `latestFinal` = the highest already-published **final** (non-prerelease)
+   version that is `>= floor`.
+2. If this tree's content is byte-identical to `latestFinal`'s (ignoring only
+   the `version` field), there is nothing to publish on **either** channel —
+   `latestFinal` is reused as the version to pin. This is the common case:
+   most deploys do not touch the harness at all.
+3. Otherwise `next = max(floor, patch(latestFinal) + 1)` — or just `floor`
+   when there is no `latestFinal` at or above it (a floor a human just
+   raised). The rc channel publishes `${next}-rc.N` (reusing an identical
+   existing rc rather than republishing); the final channel publishes `next`,
+   after confirming an rc of `next` has this exact content.
+
+**A routine patch release needs no PR at all** — pushing a harness change to
+`main` and then to `production` is enough; the version above `floor` is
+computed, not hand-written. **A minor or major bump is still a human
+decision**: raise `version` in `packages/agent-harness/package.json` (e.g.
+`0.2.1` -> `0.3.0`) and the next computed release starts from there.
+
+See the comments above `contentDigest()`, `planRelease()` and `release()` in
+`agent-harness-release.mjs` for the full reasoning, including how two
+concurrent runs are kept from publishing the same version.
+
+Licensed under the MIT License. See [LICENSE](./LICENSE).

package/dist/adapters/acp-adapter.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Unified ACP (Agent Client Protocol) adapter for all ACP-compatible coding agents.
+ * Supports: codex-acp and other ACP-compliant agent processes.
+ *
+ * Protocol: JSON-RPC 2.0 over stdio (newline-delimited JSON)
+ * Spec: https://github.com/agentclientprotocol/typescript-sdk
+ */
+import type { CodingAgentAdapter, SessionConfig, SessionMessage, SessionStatus, MessagePart } from './coding-agent-adapter';
+export type AcpAgentType = 'codex' | 'cursor';
+interface AcpPermissionRequest {
+    requestId: string | number;
+    toolCallId: string;
+    question: string;
+    options: Array<{
+        optionId: string;
+        name: string;
+        kind: string;
+    }>;
+}
+/**
+ * Unified ACP adapter for all ACP-compatible agents
+ */
+export declare class AcpAdapter implements CodingAgentAdapter {
+    private agentType;
+    private agentConfig;
+    private sessions;
+    private debugRpcLogs;
+    /**
+     * Maximum number of raw JSON-RPC messages to keep in permanent history.
+     * This is used for replaying transcripts upon session resume.
+     * 1,000 events is enough for ~50-100 turns.  Lowered from 2,000 to reduce
+     * memory footprint — each event can be multi-KB (tool outputs).
+     */
+    private static readonly MAX_PERMANENT_MESSAGES;
+    /**
+     * Maximum number of entries in toolCallMetadata before pruning.
+     * This map caches tool_call metadata for in-progress tool calls and should
+     * be pruned if it grows beyond what's reasonable (e.g. due to un-cleaned
+     * entries from tool calls that never completed).
+     */
+    private static readonly MAX_TOOL_CALL_METADATA;
+    /** Callback set by agent-manager to trigger an immediate poll cycle */
+    onDataAvailable?: (sessionId: string) => void;
+    constructor(agentType: AcpAgentType);
+    private static isDebugLogLevel;
+    /**
+     * Resolve the path to the codex-acp native binary for the current platform.
+     *
+     * codex-acp ships as a native binary per platform (e.g. codex-acp-darwin-arm64).
+     * The JS wrapper (codex-acp.js) uses import.meta.resolve() which returns an ASAR
+     * path — but the OS can't execute a native binary from inside an ASAR archive.
+     * We bypass the wrapper and resolve the native binary directly, replacing the
+     * ASAR path with the unpacked path (electron-builder auto-unpacks native binaries).
+     *
+     * pnpm note: the platform-specific package (e.g. codex-acp-darwin-arm64) is an
+     * optionalDependency of codex-acp, so under pnpm it is NOT hoisted to the root
+     * node_modules. We must resolve it from codex-acp's own directory using the
+     * `{ paths }` option of require.resolve. In a packaged app (ASAR), electron-builder
+     * flattens the structure so a plain require.resolve would also work.
+     */
+    private resolveCodexBinary;
+    private getAgentConfig;
+    /**
+     * Decide how Codex authenticates for this session and mutate `env` accordingly.
+     * Returns true when API-key auth is used, false when the ChatGPT subscription /
+     * Codex CLI login is used.
+     *
+     * The user's explicit choice in the agent configuration (config.authMethod) is
+     * the source of truth:
+     *   - 'subscription' -> use the Codex CLI login (~/.codex), exactly like running
+     *     `codex` in a terminal. Any ambient OPENAI_API_KEY/CODEX_API_KEY inherited
+     *     from the user's shell is STRIPPED so it cannot hijack auth into API-key
+     *     mode (which bills a separate, often-exhausted quota and made 20x show
+     *     "out of rate limits" even though the terminal subscription worked fine).
+     *   - 'api_key' -> use an API key (the per-agent config key if set, otherwise the
+     *     ambient one) in an isolated temp CODEX_HOME so keys can differ per session.
+     *
+     * When authMethod is unset (legacy agents), fall back to the historical rule but
+     * WITHOUT the ambient-key hijack: only an explicitly-configured per-agent API
+     * key implies API-key mode; otherwise default to the subscription/login path.
+     */
+    private configureCodexAuthEnv;
+    private configureCursorAuthEnv;
+    initialize(): Promise<void>;
+    /**
+     * Authenticate the session if required
+     */
+    private authenticateSession;
+    createSession(config: SessionConfig): Promise<string>;
+    resumeSession(sessionId: string, config: SessionConfig): Promise<SessionMessage[]>;
+    sendPrompt(sessionId: string, parts: MessagePart[], _config: SessionConfig): Promise<void>;
+    getStatus(sessionId: string, _config: SessionConfig): Promise<SessionStatus>;
+    pollMessages(sessionId: string, seenMessageIds: Set<string>, seenPartIds: Set<string>, partContentLengths: Map<string, string>, _config: SessionConfig): Promise<MessagePart[]>;
+    abortPrompt(sessionId: string, _config: SessionConfig): Promise<void>;
+    destroySession(sessionId: string, _config: SessionConfig): Promise<void>;
+    getAllMessages(sessionId: string, _config: SessionConfig): Promise<SessionMessage[]>;
+    registerMcpServer(_serverName: string, _mcpConfig: {
+        type: 'local' | 'remote';
+        command?: string[];
+        args?: string[];
+        url?: string;
+        headers?: Record<string, string>;
+        environment?: Record<string, string>;
+    }, _workspaceDir?: string): Promise<void>;
+    checkHealth(): Promise<{
+        available: boolean;
+        reason?: string;
+    }>;
+    /**
+     * Get pending approval request for a session
+     */
+    getPendingApproval(sessionId: string): AcpPermissionRequest | null;
+    /**
+     * Respond to a pending approval request
+     */
+    respondToApproval(sessionId: string, approved: boolean, optionId?: string): Promise<void>;
+    private setupStdoutParser;
+    private handleRpcMessage;
+    /**
+     * Extract codex-specific error info from an RPC error response.
+     * Returns a user-friendly error message if this is a known codex error type,
+     * or null if it's a generic error that should be handled normally.
+     */
+    private extractCodexErrorInfo;
+    /**
+     * Handle a quota/usage limit error by setting session state and surfacing
+     * a clear, actionable error message to the user.
+     */
+    private handleQuotaError;
+    private updateSessionStatus;
+    /**
+     * Adds a notification or event to the permanent message history, with
+     * consolidation and size-based pruning to prevent OOM.
+     *
+     * IMPORTANT: events are stored as deep clones. The incoming `event` object is
+     * the SAME object that handleRpcMessage() pushed into session.messageBuffer
+     * for live polling. This method mutates stored events in two ways:
+     *   1. chunk consolidation rewrites content.text on the last stored event
+     *   2. tool outputs are truncated to 100KB for history
+     * Without cloning, those mutations corrupted the un-polled live buffer:
+     * when several agent_message_chunk deltas arrived between polls (always the
+     * case at the START of a response — the first token burst lands before the
+     * first poll cycle), consolidation silently rewrote the FIRST buffered chunk
+     * into the full accumulated text while the later buffered chunks stayed raw
+     * deltas. pollMessages() then appended those deltas again after the already
+     * complete text, scrambling the beginning of the message
+     * ("Hello world, how are you? world, how are you?").
+     */
+    private addToPermanentMessages;
+    private sendRpcRequest;
+    private sendRpcRequestNoWait;
+    private sendRpcResponse;
+    private sendRpcNotification;
+    private handlePermissionRequest;
+    private extractAcpSessionId;
+    /**
+     * Convert internal McpServerConfig map to ACP-spec McpServer array.
+     * ACP spec: https://agentclientprotocol.com/protocol/schema
+     *
+     * - mcpServers is Vec<McpServer> (array, not map)
+     * - stdio variant: { name, command, args: string[], env: EnvVariable[] }
+     * - http variant:  { type: "http", name, url, headers: HttpHeader[] }
+     * - EnvVariable / HttpHeader = { name: string, value: string }
+     */
+    private convertMcpServers;
+    private extractTextFromUpdateContent;
+    private mergeStreamingText;
+    private isUserUpdateType;
+    private isAssistantChunkUpdateType;
+    private isToolingUpdateType;
+    private getAssistantTurnId;
+    private getUserTurnId;
+    private normalizeToolName;
+    private buildToolTitle;
+    private convertAcpEventToMessageParts;
+}
+export {};