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

package/dist/ports.d.ts

@@ -0,0 +1,436 @@
+/**
+ * THE PORTS — the seams the extraction cuts along.
+ *
+ * The 20x coding-agent runtime reached for seven process-wide singletons and
+ * three Electron symbols. None of them exist on a Linux VM, and none of them
+ * were ever load-bearing: each is a small, nameable capability that the HOST
+ * supplies and the runtime merely uses.
+ *
+ * Every interface below is therefore written from the RUNTIME's point of view —
+ * what it needs — never from the host's. That is what lets 20x pass an
+ * Electron-backed implementation, the harness pass a server-backed one, and a
+ * test pass nothing at all.
+ *
+ * TWO RULES THAT KEEP THIS HONEST
+ *
+ * 1. NO PORT MAY BE REQUIRED. Every one has a working no-op or in-memory
+ *    default (see ./ports-default). A port that a host must implement before
+ *    anything runs is not a seam, it is a second constructor — and it would
+ *    make the package untestable and un-adoptable in one step.
+ *
+ * 2. A PORT DESCRIBES A CAPABILITY, NOT A HOST. There is no `isDesktop()`,
+ *    no `isSandbox()` and no runtime discriminator anywhere in this file. The
+ *    moment a port lets the runtime ask WHO is hosting it, the three hosting
+ *    modes stop being the same program and the extraction has bought nothing.
+ */
+import type { JsonValue } from './types';
+/**
+ * Access to the user's stored secrets, and to the local broker that hands them
+ * to an agent process WITHOUT putting them in that process's environment.
+ *
+ * WHY A BROKER AT ALL, rather than just setting env vars: an agent runs shell
+ * commands on the user's behalf, and anything it runs inherits its environment.
+ * A secret in `process.env` is therefore readable by every command the model
+ * decides to run, and by anything that reads `/proc/<pid>/environ`. The broker
+ * keeps the values on the other side of a loopback HTTP call authenticated by a
+ * per-session token, so a leaked transcript does not leak the secrets.
+ *
+ * A host with no secret store returns null from `getBrokerPort()` and the
+ * runtime simply runs without secrets — it does not fail.
+ */
+export interface SecretProvider {
+    /**
+     * The loopback port of the running secret broker, or null when the host has
+     * no broker. NEVER bound to anything but 127.0.0.1.
+     */
+    getBrokerPort(): number | null;
+    /**
+     * Authorise one session to fetch exactly `secretIds` and nothing else.
+     * The token is generated by the CALLER and is per session, so revoking one
+     * session cannot affect another.
+     */
+    registerSession(token: string, agentId: string, secretIds: string[]): void;
+    /** Revoke a session's access. Called on every session teardown path. */
+    unregisterSession(token: string): void;
+    /**
+     * Absolute path to the shell wrapper that resolves `$SECRET_*` through the
+     * broker, or null when the host has none. Handed to the agent as its $SHELL.
+     */
+    writeShellWrapper(): string | null;
+    /**
+     * Decrypted values, for the backends that ignore $SHELL (Claude Code does).
+     * Returns {} when the host has no secret store.
+     *
+     * This is the one method that puts plaintext in the agent's environment, and
+     * it exists only because a backend forced it. Prefer the wrapper.
+     */
+    getSecretEnv(secretIds: string[]): Record<string, string>;
+}
+/**
+ * Where transcript changes and other UI-facing events go.
+ *
+ * On the desktop this is `mainWindow.webContents.send(...)` — an IPC hop to a
+ * renderer in the same machine. On a runner it is `POST /ingest` — an HTTPS hop
+ * to the control plane. THE RUNTIME CANNOT TELL THE DIFFERENCE, and that is the
+ * entire point: the transcript projection is identical in both, which is why a
+ * cloud session can later be mirrored into the desktop's local table with no UI
+ * change at all.
+ *
+ * Delivery is FIRE AND FORGET by design. An event sink that could reject would
+ * put transport failure in the middle of the agent loop; durability is the
+ * store's job (see TranscriptStore), not the sink's.
+ */
+export interface EventSink {
+    /**
+     * The transcript for `sessionId` changed. `maxRev` is the client cursor —
+     * a reader that already holds this rev has nothing to fetch.
+     */
+    transcriptChanged(sessionId: string, maxRev: number): void;
+    /** Any other host-specific channel. Unknown channels must be ignored, not throw. */
+    emit(channel: string, payload: JsonValue): void;
+}
+/**
+ * Telling a HUMAN AT THIS MACHINE something, and keeping the machine awake.
+ *
+ * Both are no-ops on a server, and deliberately so — a headless runner has no
+ * one to notify and never sleeps. Keeping them as a port rather than deleting
+ * them is what lets the desktop keep its behaviour unchanged while the same
+ * code runs on a VM.
+ */
+export interface Notifier {
+    /** Show a desktop notification. `onClick` focuses the host window, if any. */
+    notify(input: {
+        title: string;
+        body: string;
+        onClick?: () => void;
+    }): void;
+    /**
+     * Prevent the machine sleeping mid-turn. Returns a release function.
+     *
+     * A LAPTOP THAT SUSPENDS MID-TURN IS A DEFECT: the agent's child processes
+     * are frozen, the model connection times out, and the user returns to a
+     * half-written transcript. On a server this is a no-op returning a no-op.
+     */
+    keepAwake(): () => void;
+}
+/**
+ * The task-management MCP server the agent is given.
+ *
+ * IN PROCESS ON THE DESKTOP, A REMOTE GATEWAY ON A RUNNER. This is the port
+ * whose two implementations differ most, and the difference is entirely inside
+ * `getUrl()` — the runtime only ever needs a URL to hand the backend.
+ *
+ * Returns null when the host offers no task MCP. The runtime must then simply
+ * not configure that server, NOT fail: a free-standing session with no human
+ * task behind it is explicitly allowed (decision 6).
+ */
+export interface TaskMcpProvider {
+    /**
+     * The MCP endpoint for this scope, or null when unavailable.
+     *
+     * `await`ed because the desktop implementation may still be starting its
+     * in-process server when the first session begins.
+     */
+    getUrl(scope: TaskMcpScope): Promise<string | null>;
+}
+export interface TaskMcpScope {
+    taskId?: string | null;
+    parentTaskId?: string | null;
+    artifactTaskId?: string | null;
+}
+/**
+ * Product analytics. A NO-OP ON A SERVER.
+ *
+ * Every 20x call site was already written as `analytics()?.record(...)`, so the
+ * singleton was ALWAYS allowed to be absent. That is why this port is safe to
+ * default to a no-op: the runtime has never been able to depend on it.
+ */
+export interface Telemetry {
+    record(event: string, properties?: Record<string, unknown>): void;
+}
+/**
+ * Supplies the bearer token for an outbound MCP call, FRESHLY, ON EVERY CALL.
+ *
+ * THIS PORT IS NEEDED IN EVERY MODE, which is why the measurement called it out
+ * separately. ACP, OpenCode and Claude Code all bake MCP headers at session
+ * start and none of them refresh mid-session, so a one-hour token expires
+ * during a long run and every subsequent tool call 401s with no recovery path.
+ * The loopback proxy in ./runtime/mcp-auth-proxy decouples token lifetime from
+ * session lifetime by asking this port per request.
+ *
+ * Desktop: the enterprise JWT. Runner: the session-scoped MCP token from the
+ * lease — which carries NO tool list, so the gateway's allowlist stays
+ * authoritative and revocation is immediate.
+ */
+export interface TokenInjector {
+    /**
+     * A currently-valid bearer token for `targetUrl`.
+     *
+     * Throwing is a legitimate answer and means "this integration cannot be
+     * authenticated right now"; the proxy answers the agent 502 rather than
+     * forwarding an unauthenticated request. Returning null means "send no
+     * Authorization header at all", which is different and is how an already
+     * public endpoint is expressed.
+     */
+    getToken(targetUrl: string): Promise<string | null>;
+}
+/**
+ * Turns a path the agent wrote into a described artifact (kind, size, preview).
+ *
+ * Returns null for anything it cannot or should not describe. A host with no
+ * artifact concept returns null always, and the runtime carries on.
+ */
+export interface ArtifactInspector {
+    inspect(workspaceDir: string, artifactPath: string): Promise<InspectedArtifact | null>;
+}
+export interface InspectedArtifact {
+    path: string;
+    name: string;
+    mimeType?: string;
+    sizeBytes?: number;
+    /** Host-defined extras. Kept JSON-shaped so it can cross the wire unchanged. */
+    meta?: JsonValue;
+}
+/**
+ * The durable transcript projection.
+ *
+ * A NARROW SLICE OF `DatabaseManager` ON PURPOSE. The measurement recorded
+ * DatabaseManager as "already at an interface boundary" because 20x imports it
+ * with `import type`, and that is true syntactically — but the SURFACE the
+ * runtime actually touches is 20 methods spanning tasks, skills, secrets, MCP
+ * servers and settings, i.e. most of the desktop's database. Lifting that whole
+ * surface into the package would drag the 20x task model along with it and the
+ * "harness" would just be 20x with the window removed.
+ *
+ * So the port is cut where the DATA is genuinely shared rather than where the
+ * import happened to be: the transcript projection, and nothing else. Its
+ * invariants (below) are the ones the control plane also implements, so all
+ * three writers agree.
+ *
+ * THE SEVEN INVARIANTS, which an implementation MUST honour:
+ *   1. Upsert keyed on (sessionId, partId), in ONE transaction.
+ *   2. A NEW part takes MAX(seq)+1. An EXISTING part KEEPS its seq and only
+ *      replaces content — this is exactly how token streaming works, and
+ *      re-seq'ing would make a growing part jump to the end on every delta.
+ *   3. partType/tool/payload COALESCE against the stored value, so a partial
+ *      update never erases metadata a fuller earlier update established.
+ *   4. createdAt is NEVER overwritten on conflict; the first write wins.
+ *   5. rev is monotonic and is bumped on UPDATES as well as inserts.
+ *   6. `maxRev` is PER SESSION — it is the client's cursor.
+ *   7. Reads are ORDER BY createdAt ASC, seq ASC. Insertion order is not
+ *      chronological once older history is backfilled.
+ */
+export interface TranscriptStore {
+    /**
+     * Write a batch. Returns the session's new maxRev and which parts changed.
+     *
+     * SYNCHRONOUS on purpose. The desktop implementation is better-sqlite3, which
+     * is synchronous, and the agent loop calls this on every streaming delta;
+     * making it a promise would add a microtask per token for no gain and would
+     * open a window in which two batches interleave.
+     */
+    upsertParts(sessionId: string, parts: StoredPartInput[]): {
+        maxRev: number;
+        changedPartIds: string[];
+    };
+    /** Everything with rev > sinceRev, plus the new cursor. */
+    getDelta(sessionId: string, sinceRev: number): {
+        parts: StoredPart[];
+        maxRev: number;
+    };
+    /** The whole ordered transcript. */
+    getParts(sessionId: string): StoredPart[];
+    /** The session's current cursor. 0 when empty. */
+    getMaxRev(sessionId: string): number;
+    /** Drop a session's transcript. */
+    deleteParts(sessionId: string): void;
+}
+/**
+ * What goes IN. `seq` and `rev` are absent by construction, exactly as in the
+ * wire contract's `TranscriptPartInput` — a caller must not be able to
+ * fabricate an ordering or replay an old rev over a newer one.
+ */
+export interface StoredPartInput {
+    partId: string;
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+    partType: string;
+    tool?: string | null;
+    payload?: JsonValue | null;
+    /** Unix ms. The part's ORIGINAL time when known, not the write time. */
+    createdAt?: number;
+}
+/** What comes OUT. */
+export interface StoredPart extends StoredPartInput {
+    seq: number;
+    rev: number;
+    createdAt: number;
+    updatedAt: number;
+}
+/**
+ * Where a session's files live.
+ *
+ * COLLAPSED FROM THREE MANAGERS TO ONE PORT. The measurement listed
+ * WorktreeManager, GitHubManager and GitLabManager as three separate
+ * already-injected dependencies, but between them the runtime calls exactly
+ * three methods at exactly three call sites. Injecting three whole managers to
+ * reach three methods would import the desktop's entire git and forge stack
+ * into a package whose default workspace mode is a bare scratch directory.
+ *
+ * The default implementation makes a plain directory and refuses
+ * 'repository' mode, which is correct for a cloud sandbox: repository access is
+ * an explicit per-agent opt-in on a runner the customer chose.
+ */
+/**
+ * A record in the model-facing conversation log, with its allocated order.
+ *
+ * `seq` is allocated by whoever stores it and is never sent by a caller — the
+ * same rule the transcript contract applies to `seq` and `rev`, and for the
+ * same reason: a runner that could choose its own ordering could rewrite
+ * history.
+ */
+export interface ModelMessageRecord {
+    seq: number;
+    role: 'user' | 'assistant';
+    content: string;
+}
+/**
+ * WHERE THE HARNESS REMEMBERS A CONVERSATION BETWEEN TURNS.
+ *
+ * This port is the fix for the defect that mattered most in this project: the
+ * runner created and destroyed a backend session on every turn and sent only
+ * the new user message, so the model began every turn with no idea what had
+ * just been discussed, while the UI transcript looked perfect.
+ *
+ * See `store/conversation-store.ts` for why a checkpoint and a message log are
+ * both needed, and `runtime/conversation.ts` for why the message log is not the
+ * transcript projection.
+ */
+export interface SessionCheckpoint {
+    /** The backend's own handle for the conversation. Opaque here. */
+    backendSessionId: string;
+    /** Which KIND of backend minted it — 'opencode', 'claude-code', ... */
+    backend: string;
+    /**
+     * Which INSTANCE of that backend minted it.
+     *
+     * Null on a checkpoint written before ownership was recorded, which is read
+     * as "unknown, therefore not mine" — replay once rather than resume a handle
+     * that may belong to another machine.
+     */
+    backendOwnerId: string | null;
+    /**
+     * The permission decision ('ask' | 'allow') the backend session was CREATED
+     * under, when it is known.
+     *
+     * NOT DECORATION. OpenCode binds a session's permission policy at creation
+     * and nothing reaches it afterwards — not the workspace config file, not a
+     * directory-scoped `config.update`; both were tried and MEASURED to do
+     * nothing. So a session created under `allow` keeps running unprompted
+     * however the agent is later edited, which is defect G1 reopening on
+     * message two, in the direction that hurts.
+     *
+     * This is the only durable record of that. The workspace is deleted and
+     * rebuilt every turn, and the adapter is constructed fresh per turn, so
+     * neither can carry it.
+     */
+    permissionDecision?: string;
+}
+export interface ConversationStore {
+    /**
+     * The backend's own handle for this conversation, when one is still held.
+     *
+     * MERGE NOTE (#1591 × #1602): both changes added a field to this checkpoint —
+     * `backendOwnerId`, so a handle is only resumed on the instance that minted
+     * it, and `permissionDecision`, so a session's creation-time permission
+     * policy survives the turn. They are independent and both are kept. The
+     * inline shape #1602 introduced is folded back into the named
+     * `SessionCheckpoint` so there is ONE declaration to add the next field to.
+     */
+    getCheckpoint(sessionId: string): SessionCheckpoint | null;
+    /**
+     * Record it, or clear it by passing null when the backend has lost it.
+     *
+     * THE LAST ARGUMENT IS A NAMED OBJECT, NOT TWO POSITIONAL STRINGS, AND THAT
+     * IS DELIBERATE. #1591 and #1602 each added an optional string here, in
+     * parallel. Merging them produced `setCheckpoint(id, ses, 'opencode',
+     * 'allow')` writing "allow" into the OWNER slot — silently, because both are
+     * `string | undefined` and the compiler cannot tell them apart. Only a test
+     * caught it. Two adjacent optional strings of the same type is a
+     * transposition waiting to happen; naming them removes the class.
+     */
+    setCheckpoint(sessionId: string, backendSessionId: string | null, backend: string, extra?: {
+        backendOwnerId?: string | null;
+        permissionDecision?: string;
+    }): void;
+    /** The whole log, in order. */
+    getModelMessages(sessionId: string): ModelMessageRecord[];
+    /** Append this turn's messages, allocating `seq` at the store. */
+    appendModelMessages(sessionId: string, messages: {
+        role: 'user' | 'assistant';
+        content: string;
+    }[]): void;
+    /** Replace the local cache with the control plane's copy. */
+    replaceModelMessages(sessionId: string, messages: ModelMessageRecord[]): void;
+    /** Drop everything for a session. */
+    forget(sessionId: string): void;
+}
+export interface WorkspaceProvider {
+    /**
+     * Prepare and return the absolute working directory for a session.
+     *
+     * MUST be unique per session. Decision 2 dropped the unix-user-per-session
+     * design, so inside a tenant this directory IS the isolation boundary as far
+     * as the filesystem is concerned — the rest is enforced by the harness and
+     * the MCP gateway rather than by the kernel. Create it 0700.
+     */
+    prepare(input: WorkspaceRequest): Promise<string>;
+    /** Environment values that describe the workspace prepared for this turn. */
+    getEnvironment?(sessionId: string, directUrls?: string[]): Record<string, string>;
+    /** One-use host note to prepend to the next model turn, when present. */
+    takeTurnNote?(sessionId: string): string | null;
+    /**
+     * Save dirty repository work before a turn gives up its credential.
+     * A false result means a remote backup failed and cleanup must keep the tree.
+     */
+    preserveAtTurnEnd?(sessionId: string): Promise<boolean>;
+    /**
+     * Release a session workspace. A non-forced release must keep a dirty Git
+     * worktree. Force is reserved for an explicit session-end or wipe command.
+     */
+    release(sessionId: string, options?: {
+        force?: boolean;
+    }): Promise<boolean | void>;
+}
+export interface WorkspaceRequest {
+    sessionId: string;
+    mode: 'scratch' | 'repository';
+    repositoryUrl?: string;
+    ref?: string;
+    repositories?: import('./types').LeasedGitHubRepository[];
+    requestedRepositories?: string[];
+    onRepositoryStatus?: (status: {
+        fullName: string;
+        status: 'checkedOut';
+    }) => void;
+    refusalReason?: string;
+}
+/**
+ * Every port, all optional.
+ *
+ * One options object rather than positional constructor arguments, because the
+ * 20x `AgentManager` is constructed in 20-odd tests as `new AgentManager(db)`
+ * and a widened arity would break every one of them. An options bag with
+ * defaults is additive: existing callers keep working untouched.
+ */
+export interface HarnessPorts {
+    secrets?: SecretProvider;
+    events?: EventSink;
+    notifier?: Notifier;
+    taskMcp?: TaskMcpProvider;
+    telemetry?: Telemetry;
+    tokens?: TokenInjector;
+    artifacts?: ArtifactInspector;
+    store?: TranscriptStore;
+    workspace?: WorkspaceProvider;
+}

package/dist/ports.js

@@ -0,0 +1,27 @@
+"use strict";
+/**
+ * THE PORTS — the seams the extraction cuts along.
+ *
+ * The 20x coding-agent runtime reached for seven process-wide singletons and
+ * three Electron symbols. None of them exist on a Linux VM, and none of them
+ * were ever load-bearing: each is a small, nameable capability that the HOST
+ * supplies and the runtime merely uses.
+ *
+ * Every interface below is therefore written from the RUNTIME's point of view —
+ * what it needs — never from the host's. That is what lets 20x pass an
+ * Electron-backed implementation, the harness pass a server-backed one, and a
+ * test pass nothing at all.
+ *
+ * TWO RULES THAT KEEP THIS HONEST
+ *
+ * 1. NO PORT MAY BE REQUIRED. Every one has a working no-op or in-memory
+ *    default (see ./ports-default). A port that a host must implement before
+ *    anything runs is not a seam, it is a second constructor — and it would
+ *    make the package untestable and un-adoptable in one step.
+ *
+ * 2. A PORT DESCRIBES A CAPABILITY, NOT A HOST. There is no `isDesktop()`,
+ *    no `isSandbox()` and no runtime discriminator anywhere in this file. The
+ *    moment a port lets the runtime ask WHO is hosting it, the three hosting
+ *    modes stop being the same program and the extraction has bought nothing.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/runtime/attachments.d.ts

@@ -0,0 +1,92 @@
+import type { LeasedAttachment } from '../types';
+/** The directory, relative to the workspace, that attachments land in. */
+export declare const ATTACHMENTS_DIR = "attachments";
+/**
+ * Per-file ceiling. MIRRORS `CHAT_ATTACHMENT_MAX_BYTES` in
+ * `packages/core/src/services/coding-agents/chat-attachments.ts` — this
+ * package does not depend on core, so the number is repeated, not imported.
+ */
+export declare const MAX_ATTACHMENT_BYTES: number;
+/** Per-download wall clock. */
+export declare const ATTACHMENT_DOWNLOAD_TIMEOUT_MS = 120000;
+export interface SyncedAttachment {
+    /** The file's name inside `attachments/`. May differ from the lease's. */
+    name: string;
+    /** `attachments/<name>` — relative to the workspace, as the agent sees it. */
+    relativePath: string;
+    mimeType: string;
+    sizeBytes: number;
+}
+export interface FailedAttachment {
+    name: string;
+    reason: string;
+}
+export interface AttachmentSyncResult {
+    synced: SyncedAttachment[];
+    failed: FailedAttachment[];
+}
+/**
+ * One safe path segment: the basename, without control characters, reserved
+ * characters or leading dots. `..`, `a/b`, `C:\x\y.pdf` and `` all come out as
+ * something that cannot leave the directory.
+ */
+export declare function sanitizeAttachmentName(raw: unknown): string;
+/**
+ * A MIME type safe to interpolate into the model's prompt.
+ *
+ * `attachmentPromptNote` puts every synced file's type straight into text the
+ * model reads. Like the name (`sanitizeAttachmentName` above), the lease's
+ * `mimeType` is UNTRUSTED as far as this package is concerned — it may also
+ * simply be whatever a browser's `File.type` reported for the original
+ * upload, carried through unchanged. Anything that is not a plain
+ * `type/subtype` token — in particular anything containing whitespace,
+ * a newline, or a control character — becomes `application/octet-stream`
+ * rather than reaching the prompt.
+ *
+ * A NARROWER PURPOSE than core's `sanitizeAttachmentMimeType`: that function
+ * additionally allow-lists WHICH types are safe to serve as a browser
+ * `Content-Type` (closing a stored-XSS path). This one only needs to keep the
+ * PROMPT safe, so a shape check is enough — a real, unusual-but-legitimate
+ * type like `application/vnd.ms-excel` must still reach the model.
+ */
+export declare function sanitizeAttachmentMimeType(raw: unknown): string;
+/**
+ * A short, filesystem-safe, deterministic token for a turn id — used to
+ * namespace one turn's files from another's (see `turnId` below). Hashed
+ * rather than sliced from the id verbatim: turn ids are not guaranteed to be
+ * short, URL-safe or free of characters `sanitizeAttachmentName` would
+ * mangle, and a re-lease of the SAME turn must produce the SAME token for
+ * this function to stay idempotent, which a hash guarantees regardless of
+ * the id's own shape.
+ */
+export declare function turnToken(turnId: string): string;
+/**
+ * Download every attachment into `<workspaceDir>/attachments/`.
+ *
+ * Returns what landed and what did not; never throws for a single file.
+ */
+export declare function syncAttachmentsToWorkspace(attachments: LeasedAttachment[] | undefined, workspaceDir: string, options?: {
+    fetchImpl?: typeof fetch;
+    logger?: Pick<Console, 'warn'>;
+    maxBytes?: number;
+    timeoutMs?: number;
+    /**
+     * A stable identifier for the turn these attachments belong to (the
+     * lease's `turnId`). When given, every synced filename is prefixed with
+     * a short token derived from it — see `turnToken` — so a LATER turn that
+     * happens to attach a same-named file never silently overwrites an
+     * EARLIER turn's file still referenced from an earlier point in the
+     * conversation log. A RE-LEASE of the SAME turn reuses the same token
+     * (same `turnId` in, same token out), which is what keeps this function
+     * idempotent under a retried lease. Omitted by callers — mostly tests —
+     * that don't need cross-turn isolation.
+     */
+    turnId?: string;
+}): Promise<AttachmentSyncResult>;
+/**
+ * The note appended to the user's message. Empty when nothing was attached.
+ *
+ * Paths are given relative to the working directory (`./attachments/...`),
+ * which is what every backend's file tools resolve against.
+ */
+export declare function attachmentPromptNote(result: AttachmentSyncResult): string;