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

package/dist/adapters/coding-agent-adapter.d.ts

@@ -0,0 +1,289 @@
+/**
+ * Adapter interface for coding agent backends.
+ * Defines common operations that all coding agent implementations must support.
+ */
+/**
+ * Extracted verbatim from 20x `src/main/adapters/coding-agent-adapter.ts`.
+ * CHANGED: imports only — `../../shared/reasoning-effort` ->
+ * `../shared/reasoning-effort`. Source formatting (no semicolons) preserved.
+ */
+import type { ReasoningEffort } from '../shared/reasoning-effort';
+export declare enum SessionStatusType {
+    IDLE = "idle",
+    BUSY = "busy",
+    RETRY = "retry",
+    ERROR = "error",
+    WAITING_APPROVAL = "waiting_approval"
+}
+export declare enum MessageRole {
+    USER = "user",
+    ASSISTANT = "assistant",
+    SYSTEM = "system"
+}
+export declare enum MessagePartType {
+    TEXT = "text",
+    REASONING = "reasoning",
+    TOOL = "tool",
+    QUESTION = "question",
+    IMAGE = "image",
+    ERROR = "error",
+    TASK_PROGRESS = "task_progress"
+}
+export interface McpServerConfig {
+    name?: string;
+    type: 'stdio' | 'http' | 'sse';
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    url?: string;
+    headers?: Record<string, string>;
+}
+export interface SessionConfig {
+    agentId: string;
+    taskId: string;
+    workspaceDir: string;
+    serverUrl?: string;
+    model?: string;
+    reasoningEffort?: ReasoningEffort;
+    systemPrompt?: string;
+    tools?: Record<string, boolean>;
+    promptAbort?: AbortController;
+    mcpServers?: Record<string, McpServerConfig>;
+    /** Claude Code auth method: 'subscription' (OAuth/Pro/Max) or 'api_key' (pay-per-use). Defaults to 'subscription'. */
+    authMethod?: 'subscription' | 'api_key';
+    permissionMode?: 'ask' | 'allow';
+    sandboxMode?: 'read-only' | 'workspace-write' | 'danger-full-access';
+    apiKeys?: {
+        openai?: string;
+        anthropic?: string;
+        cursor?: string;
+    };
+    /** Port of the local secret broker HTTP server */
+    secretBrokerPort?: number;
+    /** Per-session token for authenticating with the secret broker */
+    secretSessionToken?: string;
+    /** Absolute path to the secret-shell.sh wrapper script */
+    secretShellPath?: string;
+    /** Decrypted secret env vars to inject directly into the agent process env.
+     *  Used when the agent runtime doesn't respect $SHELL (e.g. Claude Code). */
+    secretEnvVars?: Record<string, string>;
+    /** Non-secret values exported into the backend process for this turn. */
+    environment?: Record<string, string>;
+    /** Published skills made available to this session. */
+    skills?: Array<{
+        name: string;
+        content: string;
+    }>;
+    /** Whether the OpenCode tillDone runtime plugin should enforce todo completion for this session. */
+    tillDone?: boolean;
+}
+export interface SessionStatus {
+    type: SessionStatusType;
+    message?: string;
+}
+export interface SessionMessage {
+    id: string;
+    role: MessageRole;
+    parts: MessagePart[];
+}
+export interface MessagePart {
+    id?: string;
+    type: MessagePartType;
+    text?: string;
+    content?: string;
+    role?: 'user' | 'assistant' | 'system';
+    tool?: {
+        name: string;
+        status?: string;
+        title?: string;
+        description?: string;
+        input?: unknown;
+        output?: unknown;
+        error?: string;
+        requestId?: string;
+        questions?: unknown;
+        todos?: unknown;
+    };
+    state?: {
+        status?: string;
+        title?: string;
+        input?: unknown;
+        output?: unknown;
+        error?: string;
+    };
+    update?: boolean;
+    realSessionId?: string;
+    receivedAt?: number;
+    taskProgress?: {
+        taskId: string;
+        status: 'started' | 'running' | 'completed' | 'failed' | 'stopped';
+        description: string;
+        lastToolName?: string;
+        summary?: string;
+        usage?: {
+            total_tokens: number;
+            tool_uses: number;
+            duration_ms: number;
+        };
+    };
+}
+export interface MessagePayload {
+    content: string;
+    partType: string;
+    tool?: {
+        name: string;
+        status?: string;
+        title?: string;
+        description?: string;
+        input?: unknown;
+        output?: unknown;
+        error?: string;
+    };
+}
+/**
+ * Common interface for all coding agent backends (OpenCode, Claude Code, etc.)
+ */
+export interface CodingAgentAdapter {
+    /**
+     * Initialize the adapter (e.g., load SDK, validate config)
+     */
+    initialize(): Promise<void>;
+    /**
+     * Create a new coding session
+     * @returns OpenCode/Claude session ID
+     */
+    createSession(config: SessionConfig): Promise<string>;
+    /**
+     * Resume an existing session from a persisted session ID
+     * @returns Session messages for replay
+     */
+    resumeSession(sessionId: string, config: SessionConfig): Promise<SessionMessage[]>;
+    /**
+     * Send a prompt/message to the session
+     */
+    sendPrompt(sessionId: string, parts: MessagePart[], config: SessionConfig): Promise<void>;
+    /**
+     * Deliver a message to a turn that is ALREADY RUNNING, without starting a
+     * new one — used for the soft "you have N minutes left" warning near the
+     * LONG TURNS hard ceiling.
+     *
+     * OPTIONAL AND BEST-EFFORT. Not every backend can safely take a second
+     * message while one is in flight — a backend whose `sendPrompt` is a single
+     * long-lived call per session (OpenCode) would collide with itself. Return
+     * `true` when the message reached the running turn, `false` when it could
+     * not (the caller still has the transcript note either way).
+     */
+    steerTurn?(sessionId: string, text: string, config: SessionConfig): Promise<boolean>;
+    /**
+     * Get current session status
+     */
+    getStatus(sessionId: string, config: SessionConfig): Promise<SessionStatus>;
+    /**
+     * Get new messages since last poll
+     * @param seenMessageIds Set of message IDs already processed
+     * @param seenPartIds Set of part IDs already processed
+     * @returns New message parts
+     */
+    pollMessages(sessionId: string, seenMessageIds: Set<string>, seenPartIds: Set<string>, partContentLengths: Map<string, string>, config: SessionConfig): Promise<MessagePart[]>;
+    /**
+     * Get all session messages in a standardized format
+     * Used for extracting output fields and other post-processing
+     * @returns All messages from the session
+     */
+    getAllMessages?(sessionId: string, config: SessionConfig): Promise<SessionMessage[]>;
+    /**
+     * Read the session's PERSISTED history from durable storage (e.g. the CLI's
+     * on-disk session file) WITHOUT requiring a live/in-memory session or spawning
+     * the agent. Used to backfill the durable transcript projection once for
+     * sessions that predate write-through. Parts should carry `receivedAt` (real
+     * event time) so the projection stores true timestamps.
+     * @returns Persisted messages, or [] when unavailable.
+     */
+    getPersistedMessages?(sessionId: string, config: SessionConfig): Promise<SessionMessage[]>;
+    /**
+     * Abort ongoing prompt
+     */
+    abortPrompt(sessionId: string, config: SessionConfig): Promise<void>;
+    /**
+     * Get tools currently in "running" state.
+     * Used by the stuck-tool detector to abort tools that hang without producing
+     * data (e.g. cross-workspace file reads that the server silently blocks).
+     * Optional — returns empty array if the adapter doesn't support it.
+     */
+    getRunningTools?(sessionId: string, config: SessionConfig): Promise<Array<{
+        partId: string;
+        toolName: string;
+        startTime?: number;
+        input?: Record<string, unknown>;
+    }>>;
+    /**
+     * Destroy/cleanup session
+     */
+    destroySession(sessionId: string, config: SessionConfig): Promise<void>;
+    /**
+     * Register an MCP server with the adapter
+     */
+    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>;
+    /**
+     * Respond to a pending question (AskUserQuestion tool call).
+     * Agent-manager passes structured answers; each adapter delivers them
+     * in whatever format its backend expects.
+     *
+     * @param answers Map of question header/label → selected answer text
+     */
+    respondToQuestion?(sessionId: string, answers: Record<string, string>, config: SessionConfig, requestId?: string): Promise<boolean | void | {
+        handled: boolean;
+        resolutionPart?: MessagePart;
+    }>;
+    /**
+     * List available providers and their models from the backend.
+     * Returns null if the backend doesn't support provider listing.
+     */
+    getProviders?(serverUrl?: string, directory?: string): Promise<{
+        providers: {
+            id: string;
+            name: string;
+            models: unknown;
+            [key: string]: unknown;
+        }[];
+        default: Record<string, string>;
+    } | null>;
+    /**
+     * Notify the adapter that provider/auth config has changed (e.g. user edited
+     * agent settings, AI gateway key was rotated).  Adapters that manage a shared
+     * backend server (like OpenCode) should push the updated config.
+     *
+     * Only call this on actual config changes — NOT on every session creation,
+     * as some backends (OpenCode) tear down all running sessions on config update.
+     */
+    notifyConfigChanged?(): Promise<void>;
+    /**
+     * Check if this adapter's backend is available and healthy
+     */
+    checkHealth(): Promise<{
+        available: boolean;
+        reason?: string;
+    }>;
+    /**
+     * Optional callback invoked by the adapter when new data is buffered and
+     * ready for consumption.  The polling coordinator uses this to trigger an
+     * immediate poll cycle instead of waiting for the next 2-second heartbeat,
+     * which dramatically reduces perceived latency during active streaming.
+     *
+     * Set by agent-manager when the session is registered for polling.
+     *
+     * Lifecycle contract: an IDLE status ends only the current turn. It must not
+     * close the adapter session or disable this callback. Push transports and
+     * subscriptions must stay open until destroySession() or an explicit abort
+     * closes them. This lets late harness events wake an idle session without a
+     * continuous polling loop.
+     */
+    onDataAvailable?: (sessionId: string) => void;
+}

package/dist/adapters/coding-agent-adapter.js

@@ -0,0 +1,31 @@
+"use strict";
+/**
+ * Adapter interface for coding agent backends.
+ * Defines common operations that all coding agent implementations must support.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MessagePartType = exports.MessageRole = exports.SessionStatusType = void 0;
+var SessionStatusType;
+(function (SessionStatusType) {
+    SessionStatusType["IDLE"] = "idle";
+    SessionStatusType["BUSY"] = "busy";
+    SessionStatusType["RETRY"] = "retry";
+    SessionStatusType["ERROR"] = "error";
+    SessionStatusType["WAITING_APPROVAL"] = "waiting_approval";
+})(SessionStatusType || (exports.SessionStatusType = SessionStatusType = {}));
+var MessageRole;
+(function (MessageRole) {
+    MessageRole["USER"] = "user";
+    MessageRole["ASSISTANT"] = "assistant";
+    MessageRole["SYSTEM"] = "system";
+})(MessageRole || (exports.MessageRole = MessageRole = {}));
+var MessagePartType;
+(function (MessagePartType) {
+    MessagePartType["TEXT"] = "text";
+    MessagePartType["REASONING"] = "reasoning";
+    MessagePartType["TOOL"] = "tool";
+    MessagePartType["QUESTION"] = "question";
+    MessagePartType["IMAGE"] = "image";
+    MessagePartType["ERROR"] = "error";
+    MessagePartType["TASK_PROGRESS"] = "task_progress";
+})(MessagePartType || (exports.MessagePartType = MessagePartType = {}));

package/dist/adapters/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Public surface of the coding-agent adapters extracted from the 20x Electron
+ * app (`src/main/adapters/`). This barrel is new — it does not exist in 20x,
+ * where each adapter is imported by path.
+ */
+export { SessionStatusType, MessageRole, MessagePartType } from './coding-agent-adapter';
+export type { CodingAgentAdapter, McpServerConfig, SessionConfig, SessionStatus, SessionMessage, MessagePart, MessagePayload } from './coding-agent-adapter';
+export { OpencodeAdapter } from './opencode-adapter';
+export { PiAdapter } from './pi-adapter';
+export { createOpencodeServerPolicy, backendInstanceId, ephemeralLoopbackPort, SHARED_SERVER_URL, type OpencodeServerPolicy } from './opencode-server-policy';
+export { ClaudeCodeAdapter } from './claude-code-adapter';
+export { CodexAdapter, DEFAULT_CODEX_MODEL } from './codex-adapter';
+export { CodexAppServerAdapter } from './codex-app-server-adapter';
+export { AcpAdapter } from './acp-adapter';
+export type { AcpAgentType } from './acp-adapter';
+export { ENTERPRISE_AI_GATEWAY_PROVIDER_ID, ENTERPRISE_AI_GATEWAY_PROVIDER_NAME, buildEnterpriseAiGatewayProviderConfig, buildPiAiGatewayProviderConfig } from './model-gateway';
+export type { ModelGatewayConfig, ModelGatewayConfigSource, ModelGatewayModel } from './model-gateway';

package/dist/adapters/index.js

@@ -0,0 +1,35 @@
+"use strict";
+/**
+ * Public surface of the coding-agent adapters extracted from the 20x Electron
+ * app (`src/main/adapters/`). This barrel is new — it does not exist in 20x,
+ * where each adapter is imported by path.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildPiAiGatewayProviderConfig = exports.buildEnterpriseAiGatewayProviderConfig = exports.ENTERPRISE_AI_GATEWAY_PROVIDER_NAME = exports.ENTERPRISE_AI_GATEWAY_PROVIDER_ID = exports.AcpAdapter = exports.CodexAppServerAdapter = exports.DEFAULT_CODEX_MODEL = exports.CodexAdapter = exports.ClaudeCodeAdapter = exports.SHARED_SERVER_URL = exports.ephemeralLoopbackPort = exports.backendInstanceId = exports.createOpencodeServerPolicy = exports.PiAdapter = exports.OpencodeAdapter = exports.MessagePartType = exports.MessageRole = exports.SessionStatusType = void 0;
+var coding_agent_adapter_1 = require("./coding-agent-adapter");
+Object.defineProperty(exports, "SessionStatusType", { enumerable: true, get: function () { return coding_agent_adapter_1.SessionStatusType; } });
+Object.defineProperty(exports, "MessageRole", { enumerable: true, get: function () { return coding_agent_adapter_1.MessageRole; } });
+Object.defineProperty(exports, "MessagePartType", { enumerable: true, get: function () { return coding_agent_adapter_1.MessagePartType; } });
+var opencode_adapter_1 = require("./opencode-adapter");
+Object.defineProperty(exports, "OpencodeAdapter", { enumerable: true, get: function () { return opencode_adapter_1.OpencodeAdapter; } });
+var pi_adapter_1 = require("./pi-adapter");
+Object.defineProperty(exports, "PiAdapter", { enumerable: true, get: function () { return pi_adapter_1.PiAdapter; } });
+var opencode_server_policy_1 = require("./opencode-server-policy");
+Object.defineProperty(exports, "createOpencodeServerPolicy", { enumerable: true, get: function () { return opencode_server_policy_1.createOpencodeServerPolicy; } });
+Object.defineProperty(exports, "backendInstanceId", { enumerable: true, get: function () { return opencode_server_policy_1.backendInstanceId; } });
+Object.defineProperty(exports, "ephemeralLoopbackPort", { enumerable: true, get: function () { return opencode_server_policy_1.ephemeralLoopbackPort; } });
+Object.defineProperty(exports, "SHARED_SERVER_URL", { enumerable: true, get: function () { return opencode_server_policy_1.SHARED_SERVER_URL; } });
+var claude_code_adapter_1 = require("./claude-code-adapter");
+Object.defineProperty(exports, "ClaudeCodeAdapter", { enumerable: true, get: function () { return claude_code_adapter_1.ClaudeCodeAdapter; } });
+var codex_adapter_1 = require("./codex-adapter");
+Object.defineProperty(exports, "CodexAdapter", { enumerable: true, get: function () { return codex_adapter_1.CodexAdapter; } });
+Object.defineProperty(exports, "DEFAULT_CODEX_MODEL", { enumerable: true, get: function () { return codex_adapter_1.DEFAULT_CODEX_MODEL; } });
+var codex_app_server_adapter_1 = require("./codex-app-server-adapter");
+Object.defineProperty(exports, "CodexAppServerAdapter", { enumerable: true, get: function () { return codex_app_server_adapter_1.CodexAppServerAdapter; } });
+var acp_adapter_1 = require("./acp-adapter");
+Object.defineProperty(exports, "AcpAdapter", { enumerable: true, get: function () { return acp_adapter_1.AcpAdapter; } });
+var model_gateway_1 = require("./model-gateway");
+Object.defineProperty(exports, "ENTERPRISE_AI_GATEWAY_PROVIDER_ID", { enumerable: true, get: function () { return model_gateway_1.ENTERPRISE_AI_GATEWAY_PROVIDER_ID; } });
+Object.defineProperty(exports, "ENTERPRISE_AI_GATEWAY_PROVIDER_NAME", { enumerable: true, get: function () { return model_gateway_1.ENTERPRISE_AI_GATEWAY_PROVIDER_NAME; } });
+Object.defineProperty(exports, "buildEnterpriseAiGatewayProviderConfig", { enumerable: true, get: function () { return model_gateway_1.buildEnterpriseAiGatewayProviderConfig; } });
+Object.defineProperty(exports, "buildPiAiGatewayProviderConfig", { enumerable: true, get: function () { return model_gateway_1.buildPiAiGatewayProviderConfig; } });

package/dist/adapters/model-gateway.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Model-gateway seam for the extracted coding-agent adapters.
+ *
+ * In the 20x Electron app the adapters read the enterprise AI gateway
+ * credentials directly from SQLite via `src/main/enterprise-ai-gateway.ts`.
+ * That module cannot be extracted because it depends on Electron's
+ * `safeStorage` for encrypt/decrypt. The harness therefore takes the already
+ * decrypted config through an injected `ModelGatewayConfigSource` instead.
+ *
+ * `ENTERPRISE_AI_GATEWAY_PROVIDER_ID`, `ENTERPRISE_AI_GATEWAY_PROVIDER_NAME`
+ * and `buildEnterpriseAiGatewayProviderConfig` are copied verbatim (behaviour
+ * identical) from 20x `src/main/enterprise-ai-gateway.ts`; only the formatting
+ * follows this package's Prettier config.
+ */
+export declare const ENTERPRISE_AI_GATEWAY_PROVIDER_ID = "peakflo";
+export declare const ENTERPRISE_AI_GATEWAY_PROVIDER_NAME = "Peakflo";
+/** Real per-model limits from the gateway. Absent when it did not report them. */
+export interface ModelGatewayLimit {
+    context: number;
+    output: number;
+}
+export interface ModelGatewayModel {
+    id: string;
+    name: string;
+    limit?: ModelGatewayLimit;
+}
+/**
+ * The decrypted enterprise AI gateway config. Structurally identical to
+ * `StoredEnterpriseAiGatewayConfig` in 20x.
+ */
+export interface ModelGatewayConfig {
+    apiKey: string;
+    baseUrl: string;
+    keyName?: string | null;
+    expiresAt?: string | null;
+    models?: ModelGatewayModel[];
+}
+/**
+ * Injected replacement for `readEnterpriseAiGatewayConfig(db)`.
+ * Returns `null` when no gateway is configured, exactly like the original.
+ */
+export interface ModelGatewayConfigSource {
+    readModelGatewayConfig(): ModelGatewayConfig | null;
+}
+export declare function buildEnterpriseAiGatewayProviderConfig(stored: ModelGatewayConfig): Record<string, unknown>;
+/** Build the provider entry Pi stores under `providers.peakflo`. */
+export declare function buildPiAiGatewayProviderConfig(stored: ModelGatewayConfig): Record<string, unknown>;
+/**
+ * The gateway config for the turn that is running right now.
+ *
+ * Created ONCE and re-pointed per turn, exactly like `SessionTokenInjector`
+ * and for the same reason: the adapter is constructed once and holds this
+ * reference for the whole process life, so swapping the object would leave it
+ * reading a credential from a session that has already ended.
+ *
+ * `readModelGatewayConfig()` returns `null` when no turn is live, which is the
+ * same answer `readEnterpriseAiGatewayConfig(db)` gives in 20x when no gateway
+ * is configured. Null means "no gateway provider" — it does NOT mean "fall
+ * back to whatever credentials happen to be on this machine".
+ */
+export declare class SessionModelGateway implements ModelGatewayConfigSource {
+    private config;
+    readModelGatewayConfig(): ModelGatewayConfig | null;
+    /** Install the gateway for the turn about to run. */
+    set(config: ModelGatewayConfig | null): void;
+    /**
+     * Swap in a re-minted credential without disturbing `baseUrl`/`models` — the
+     * LONG TURNS fix's answer to a fixed per-turn LiteLLM key TTL. A no-op when
+     * no turn is live (the config was already revoked or never set), which is
+     * the correct outcome for a refresh that raced the turn's own end.
+     */
+    updateApiKey(apiKey: string): void;
+    /** Drop the credential the moment the turn ends. */
+    revoke(): void;
+}
+/** Exported for tests, which must not inherit another test's catalogue. */
+export declare function __clearGatewayModelCacheForTest(): void;
+export declare function fetchGatewayModels(params: {
+    baseUrl: string;
+    apiKey: string;
+    timeoutMs?: number;
+    /** Bypass the cache. Used by a deliberate refresh, never by a turn. */
+    force?: boolean;
+}): Promise<ModelGatewayModel[]>;