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

package/dist/shared/reasoning-effort.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Extracted verbatim from 20x `src/shared/reasoning-effort.ts`.
+ * Nothing changed — the file has no imports. Source formatting (no
+ * semicolons) is preserved deliberately so the diff stays reviewable.
+ */
+export declare const CODEX_REASONING_EFFORT_VALUES: readonly ["minimal", "low", "medium", "high", "xhigh"];
+export declare const CLAUDE_REASONING_EFFORT_VALUES: readonly ["low", "medium", "high", "xhigh", "max"];
+export declare const REASONING_EFFORT_VALUES: readonly ["minimal", "low", "medium", "high", "xhigh", "max"];
+export type ReasoningEffort = typeof REASONING_EFFORT_VALUES[number];
+export declare function isReasoningEffort(value: unknown): value is ReasoningEffort;
+export declare function normalizeReasoningEffort(value: unknown): ReasoningEffort | undefined;

package/dist/shared/reasoning-effort.js

@@ -0,0 +1,20 @@
+"use strict";
+/**
+ * Extracted verbatim from 20x `src/shared/reasoning-effort.ts`.
+ * Nothing changed — the file has no imports. Source formatting (no
+ * semicolons) is preserved deliberately so the diff stays reviewable.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REASONING_EFFORT_VALUES = exports.CLAUDE_REASONING_EFFORT_VALUES = exports.CODEX_REASONING_EFFORT_VALUES = void 0;
+exports.isReasoningEffort = isReasoningEffort;
+exports.normalizeReasoningEffort = normalizeReasoningEffort;
+exports.CODEX_REASONING_EFFORT_VALUES = ['minimal', 'low', 'medium', 'high', 'xhigh'];
+exports.CLAUDE_REASONING_EFFORT_VALUES = ['low', 'medium', 'high', 'xhigh', 'max'];
+exports.REASONING_EFFORT_VALUES = ['minimal', 'low', 'medium', 'high', 'xhigh', 'max'];
+const REASONING_EFFORT_SET = new Set(exports.REASONING_EFFORT_VALUES);
+function isReasoningEffort(value) {
+    return typeof value === 'string' && REASONING_EFFORT_SET.has(value);
+}
+function normalizeReasoningEffort(value) {
+    return isReasoningEffort(value) ? value : undefined;
+}

package/dist/store/conversation-store.d.ts

@@ -0,0 +1,100 @@
+/**
+ * WHERE THE HARNESS REMEMBERS A CONVERSATION BETWEEN TURNS.
+ *
+ * Two things live here, and they are two things rather than one on purpose:
+ *
+ *   BACKEND SESSION ID — an OPAQUE CHECKPOINT. It means "the backend still
+ *   holds this conversation's context; ask it, do not rebuild it". The harness
+ *   never interprets it; only the adapter that minted it knows what it is.
+ *
+ *   MODEL MESSAGES — the FALLBACK. What the model was actually given and
+ *   actually said, in order, so a fresh session on a fresh machine can be told
+ *   what happened. See `runtime/conversation.ts` for why this is not the
+ *   transcript projection.
+ *
+ * WHY BOTH. The checkpoint is better whenever it works, and it stops working
+ * for entirely ordinary reasons: the sandbox was swept for being idle, the
+ * runner was redeployed, the turn was leased to a different machine. The log is
+ * what turns those from "the user lost the thread" into "the user repeats
+ * nothing".
+ *
+ * THIS STORE IS A CACHE, NOT THE RECORD. The control plane owns the durable
+ * copy, because a runner is disposable and a new one starts with an empty disk.
+ * This exists so the common case — same runner, next turn — costs no network
+ * call at all.
+ */
+import type { ConversationStore, ModelMessageRecord, SessionCheckpoint } from '../ports';
+import type { ModelMessage } from '../runtime/conversation';
+interface SqliteStatement {
+    run(...params: unknown[]): unknown;
+    all(...params: unknown[]): unknown[];
+    get(...params: unknown[]): unknown;
+}
+interface SqliteDatabase {
+    exec(sql: string): void;
+    prepare(sql: string): SqliteStatement;
+}
+export declare class SqliteConversationStore implements ConversationStore {
+    private readonly db;
+    constructor(db: SqliteDatabase);
+    getCheckpoint(sessionId: string): SessionCheckpoint | null;
+    setCheckpoint(sessionId: string, backendSessionId: string | null, backend: string, extra?: {
+        backendOwnerId?: string | null;
+        permissionDecision?: string;
+    }): void;
+    getModelMessages(sessionId: string): ModelMessageRecord[];
+    /**
+     * Append, with the sequence allocated HERE rather than by the caller.
+     *
+     * `INSERT OR IGNORE` plus a computed `MAX(seq)+1` makes a re-append after a
+     * crash idempotent in the only way that matters: a turn that ingested its
+     * messages and then died before recording that it had cannot produce a
+     * duplicate at a NEW seq, because the seq is derived from what is already
+     * stored, not from a counter the caller holds.
+     */
+    appendModelMessages(sessionId: string, messages: ModelMessage[]): void;
+    /**
+     * Replace the whole log with what the control plane holds.
+     *
+     * Used when the control plane knows about messages this runner has never
+     * seen — a cold runner. REPLACE rather than merge, because the control plane
+     * is the record and a local cache that disagrees with it is worse than no
+     * cache at all.
+     */
+    replaceModelMessages(sessionId: string, messages: ModelMessageRecord[]): void;
+    forget(sessionId: string): void;
+}
+/**
+ * The same behaviour without durability.
+ *
+ * A REAL implementation, not a stub — if the two disagreed, every test using
+ * this would be testing something the product does not do.
+ */
+export declare class MemoryConversationStore implements ConversationStore {
+    private readonly checkpoints;
+    private readonly messages;
+    getCheckpoint(sessionId: string): SessionCheckpoint | null;
+    setCheckpoint(sessionId: string, backendSessionId: string | null, backend: string, extra?: {
+        backendOwnerId?: string | null;
+        permissionDecision?: string;
+    }): void;
+    getModelMessages(sessionId: string): ModelMessageRecord[];
+    appendModelMessages(sessionId: string, messages: ModelMessage[]): void;
+    replaceModelMessages(sessionId: string, messages: ModelMessageRecord[]): void;
+    forget(sessionId: string): void;
+}
+export interface OpenConversationStoreResult {
+    store: ConversationStore;
+    durable: boolean;
+    reason?: string;
+}
+/**
+ * Open the durable conversation store, or say plainly why it could not be.
+ *
+ * NEVER THROWS, for the same reason `openTranscriptStore` does not: the control
+ * plane is the record, so a harness that cannot open a local database is
+ * degraded rather than broken. It will fetch history over the network every
+ * turn instead of caching it, which is slower and still correct.
+ */
+export declare function openConversationStore(path: string): OpenConversationStoreResult;
+export {};

package/dist/store/conversation-store.js

@@ -0,0 +1,305 @@
+"use strict";
+/**
+ * WHERE THE HARNESS REMEMBERS A CONVERSATION BETWEEN TURNS.
+ *
+ * Two things live here, and they are two things rather than one on purpose:
+ *
+ *   BACKEND SESSION ID — an OPAQUE CHECKPOINT. It means "the backend still
+ *   holds this conversation's context; ask it, do not rebuild it". The harness
+ *   never interprets it; only the adapter that minted it knows what it is.
+ *
+ *   MODEL MESSAGES — the FALLBACK. What the model was actually given and
+ *   actually said, in order, so a fresh session on a fresh machine can be told
+ *   what happened. See `runtime/conversation.ts` for why this is not the
+ *   transcript projection.
+ *
+ * WHY BOTH. The checkpoint is better whenever it works, and it stops working
+ * for entirely ordinary reasons: the sandbox was swept for being idle, the
+ * runner was redeployed, the turn was leased to a different machine. The log is
+ * what turns those from "the user lost the thread" into "the user repeats
+ * nothing".
+ *
+ * THIS STORE IS A CACHE, NOT THE RECORD. The control plane owns the durable
+ * copy, because a runner is disposable and a new one starts with an empty disk.
+ * This exists so the common case — same runner, next turn — costs no network
+ * call at all.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryConversationStore = exports.SqliteConversationStore = void 0;
+exports.openConversationStore = openConversationStore;
+const SCHEMA = `
+  CREATE TABLE IF NOT EXISTS model_messages (
+    session_id TEXT NOT NULL,
+    seq        INTEGER NOT NULL,
+    role       TEXT NOT NULL,
+    content    TEXT NOT NULL,
+    created_at INTEGER NOT NULL,
+    PRIMARY KEY (session_id, seq)
+  );
+  CREATE TABLE IF NOT EXISTS session_checkpoints (
+    session_id          TEXT PRIMARY KEY,
+    backend_session_id  TEXT,
+    backend             TEXT,
+    -- WHICH INSTANCE minted the handle. Without it a checkpoint is handed to
+    -- whichever runner takes the next turn and resolves nowhere.
+    backend_owner       TEXT,
+    -- The permission decision the backend session was CREATED under. See
+    -- ConversationStore#getCheckpoint for why this is the only place it can
+    -- live. Nullable: rows written before this column existed have no value,
+    -- and an unknown decision must NOT force a rebuild.
+    permission_decision TEXT,
+    updated_at          INTEGER NOT NULL
+  );
+`;
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/* -------------------------------------------------------------------------- */
+/* SQLite                                                                      */
+/* -------------------------------------------------------------------------- */
+class SqliteConversationStore {
+    db;
+    constructor(db) {
+        this.db = db;
+        this.db.exec(SCHEMA);
+        /*
+         * ADD THE COLUMNS TO A DATABASE THAT PREDATES THEM.
+         *
+         * `CREATE TABLE IF NOT EXISTS` is a no-op on an existing table, so a store
+         * written before these columns existed keeps its old shape and every read
+         * would throw. Any runner that has run a turn before this change has
+         * exactly that file on disk.
+         *
+         * MERGE NOTE (#1591 × #1602): both changes added a column here. #1602 used
+         * a bare `catch {}`; this keeps #1591's stricter guard and applies it to
+         * BOTH columns, because the failure it protects against is the same for
+         * each — see the comment inside.
+         */
+        for (const column of ['backend_owner', 'permission_decision']) {
+            try {
+                this.db.exec(`ALTER TABLE session_checkpoints ADD COLUMN ${column} TEXT`);
+            }
+            catch (error) {
+                /*
+                 * SQLite has no ADD COLUMN IF NOT EXISTS, so the ordinary outcome on an
+                 * already-migrated store is a duplicate-column error. That one is
+                 * expected and silent.
+                 *
+                 * ANYTHING ELSE IS NOT. A bare `catch {}` here would swallow a locked
+                 * database, a corrupt file or a read-only disk, and the store would
+                 * then run on without the column — every checkpoint would read as
+                 * "owner unknown", every turn would replay, and the symptom would be
+                 * indistinguishable from the defect the column was added to fix.
+                 */
+                const message = errorMessage(error).toLowerCase();
+                if (!message.includes('duplicate column')) {
+                    console.warn(`[ConversationStore] could not add session_checkpoints.${column}: ` +
+                        errorMessage(error));
+                }
+            }
+        }
+    }
+    getCheckpoint(sessionId) {
+        const row = this.db
+            .prepare('SELECT backend_session_id, backend, backend_owner, permission_decision FROM session_checkpoints WHERE session_id = ?')
+            .get(sessionId);
+        if (!row?.backend_session_id)
+            return null;
+        return {
+            backendSessionId: row.backend_session_id,
+            backend: row.backend ?? '',
+            backendOwnerId: row.backend_owner ?? null,
+            ...(row.permission_decision
+                ? { permissionDecision: row.permission_decision }
+                : {})
+        };
+    }
+    setCheckpoint(sessionId, backendSessionId, backend, extra) {
+        const backendOwnerId = extra?.backendOwnerId ?? null;
+        const permissionDecision = extra?.permissionDecision;
+        this.db
+            .prepare(`INSERT INTO session_checkpoints (session_id, backend_session_id, backend, backend_owner, permission_decision, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?)
+         ON CONFLICT(session_id) DO UPDATE SET
+           backend_session_id  = excluded.backend_session_id,
+           backend             = excluded.backend,
+           backend_owner       = excluded.backend_owner,
+           permission_decision = excluded.permission_decision,
+           updated_at          = excluded.updated_at`)
+            .run(sessionId, backendSessionId, backend, backendOwnerId, permissionDecision ?? null, Date.now());
+    }
+    getModelMessages(sessionId) {
+        const rows = this.db
+            .prepare('SELECT seq, role, content FROM model_messages WHERE session_id = ? ORDER BY seq ASC')
+            .all(sessionId);
+        return rows.map((row) => ({
+            seq: row.seq,
+            role: row.role === 'user' ? 'user' : 'assistant',
+            content: row.content
+        }));
+    }
+    /**
+     * Append, with the sequence allocated HERE rather than by the caller.
+     *
+     * `INSERT OR IGNORE` plus a computed `MAX(seq)+1` makes a re-append after a
+     * crash idempotent in the only way that matters: a turn that ingested its
+     * messages and then died before recording that it had cannot produce a
+     * duplicate at a NEW seq, because the seq is derived from what is already
+     * stored, not from a counter the caller holds.
+     */
+    appendModelMessages(sessionId, messages) {
+        if (messages.length === 0)
+            return;
+        const row = this.db
+            .prepare('SELECT COALESCE(MAX(seq), 0) AS max_seq FROM model_messages WHERE session_id = ?')
+            .get(sessionId);
+        let seq = Number(row?.max_seq ?? 0);
+        const insert = this.db.prepare(`INSERT INTO model_messages (session_id, seq, role, content, created_at)
+       VALUES (?, ?, ?, ?, ?)
+       ON CONFLICT(session_id, seq) DO NOTHING`);
+        this.db.exec('BEGIN');
+        try {
+            for (const message of messages) {
+                seq += 1;
+                insert.run(sessionId, seq, message.role, message.content, Date.now());
+            }
+            this.db.exec('COMMIT');
+        }
+        catch (error) {
+            try {
+                this.db.exec('ROLLBACK');
+            }
+            catch {
+                /* the original error is the one worth reporting */
+            }
+            throw error;
+        }
+    }
+    /**
+     * Replace the whole log with what the control plane holds.
+     *
+     * Used when the control plane knows about messages this runner has never
+     * seen — a cold runner. REPLACE rather than merge, because the control plane
+     * is the record and a local cache that disagrees with it is worse than no
+     * cache at all.
+     */
+    replaceModelMessages(sessionId, messages) {
+        this.db.exec('BEGIN');
+        try {
+            this.db
+                .prepare('DELETE FROM model_messages WHERE session_id = ?')
+                .run(sessionId);
+            const insert = this.db.prepare(`INSERT INTO model_messages (session_id, seq, role, content, created_at)
+         VALUES (?, ?, ?, ?, ?)`);
+            for (const message of messages) {
+                insert.run(sessionId, message.seq, message.role, message.content, Date.now());
+            }
+            this.db.exec('COMMIT');
+        }
+        catch (error) {
+            try {
+                this.db.exec('ROLLBACK');
+            }
+            catch {
+                /* same */
+            }
+            throw error;
+        }
+    }
+    forget(sessionId) {
+        this.db
+            .prepare('DELETE FROM model_messages WHERE session_id = ?')
+            .run(sessionId);
+        this.db
+            .prepare('DELETE FROM session_checkpoints WHERE session_id = ?')
+            .run(sessionId);
+    }
+}
+exports.SqliteConversationStore = SqliteConversationStore;
+/* -------------------------------------------------------------------------- */
+/* In-memory                                                                   */
+/* -------------------------------------------------------------------------- */
+/**
+ * The same behaviour without durability.
+ *
+ * A REAL implementation, not a stub — if the two disagreed, every test using
+ * this would be testing something the product does not do.
+ */
+class MemoryConversationStore {
+    checkpoints = new Map();
+    messages = new Map();
+    getCheckpoint(sessionId) {
+        return this.checkpoints.get(sessionId) ?? null;
+    }
+    setCheckpoint(sessionId, backendSessionId, backend, extra) {
+        const backendOwnerId = extra?.backendOwnerId ?? null;
+        const permissionDecision = extra?.permissionDecision;
+        if (!backendSessionId) {
+            this.checkpoints.delete(sessionId);
+            return;
+        }
+        this.checkpoints.set(sessionId, {
+            backendSessionId,
+            backend,
+            backendOwnerId,
+            ...(permissionDecision ? { permissionDecision } : {})
+        });
+    }
+    getModelMessages(sessionId) {
+        return (this.messages.get(sessionId) ?? []).map((message) => ({
+            ...message
+        }));
+    }
+    appendModelMessages(sessionId, messages) {
+        if (messages.length === 0)
+            return;
+        const existing = this.messages.get(sessionId) ?? [];
+        let seq = existing.length ? existing[existing.length - 1].seq : 0;
+        for (const message of messages) {
+            seq += 1;
+            existing.push({ seq, role: message.role, content: message.content });
+        }
+        this.messages.set(sessionId, existing);
+    }
+    replaceModelMessages(sessionId, messages) {
+        this.messages.set(sessionId, messages.map((message) => ({ ...message })));
+    }
+    forget(sessionId) {
+        this.messages.delete(sessionId);
+        this.checkpoints.delete(sessionId);
+    }
+}
+exports.MemoryConversationStore = MemoryConversationStore;
+/**
+ * Open the durable conversation store, or say plainly why it could not be.
+ *
+ * NEVER THROWS, for the same reason `openTranscriptStore` does not: the control
+ * plane is the record, so a harness that cannot open a local database is
+ * degraded rather than broken. It will fetch history over the network every
+ * turn instead of caching it, which is slower and still correct.
+ */
+function openConversationStore(path) {
+    let sqlite;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        sqlite = require('node:sqlite');
+    }
+    catch (error) {
+        return {
+            store: new MemoryConversationStore(),
+            durable: false,
+            reason: `node:sqlite unavailable (needs Node >= 22.13): ${errorMessage(error)}`
+        };
+    }
+    try {
+        const db = new sqlite.DatabaseSync(path);
+        return { store: new SqliteConversationStore(db), durable: true };
+    }
+    catch (error) {
+        return {
+            store: new MemoryConversationStore(),
+            durable: false,
+            reason: `could not open ${path}: ${errorMessage(error)}`
+        };
+    }
+}

package/dist/store/sqlite-store.d.ts

@@ -0,0 +1,120 @@
+/**
+ * THE HARNESS TRANSCRIPT STORE.
+ *
+ * Decision: KEEP THE SQLITE STORE. A runner that holds its working state only
+ * in memory loses a turn to its own crash, and the crash is exactly when the
+ * transcript matters. The control plane stays the source of truth via
+ * `POST /ingest`; this table is WORKING STATE — what has been produced, and
+ * what has been acknowledged — so a restarted harness can resume a lease
+ * instead of replaying a turn the user already paid for.
+ *
+ * WHY `node:sqlite` AND NOT `better-sqlite3`, which 20x uses:
+ *
+ * `pf-bootstrap` installs the harness with `--ignore-scripts` (a Phase 0
+ * hardening decision: an npm install script runs arbitrary code as the harness
+ * user before any of our code is reached). `better-sqlite3` is a NATIVE module
+ * whose binary is fetched or built by `prebuild-install` — an install script.
+ * Depending on it would therefore break the one boot path Phase 0 actually
+ * proved, and it would break it silently, at runtime, on a customer VM.
+ *
+ * `node:sqlite` ships INSIDE Node 22 (unflagged from 22.13). It costs no
+ * dependency, no native build, no install script and no prebuild matrix, and
+ * the sandbox image is already `node:22-bookworm-slim`. On an older Node the
+ * module is simply absent and `openTranscriptStore` falls back to memory, which
+ * costs crash-resumption and nothing else.
+ *
+ * THE SEVEN INVARIANTS are ported from 20x `src/main/database.ts` (schema at
+ * :1225, upsert at :2118, delta at :2179, snapshot at :2209) and each is
+ * asserted individually in the tests. They are NOT approximated: the control
+ * plane implements the same seven, and a transcript written by a runner must be
+ * byte-for-byte the transcript the desktop would have written.
+ */
+import { StoredPart, StoredPartInput, TranscriptStore } from '../ports';
+/**
+ * Structurally typed rather than imported.
+ *
+ * `node:sqlite` has no bundled type declarations on every supported Node, and a
+ * hard `import { DatabaseSync } from 'node:sqlite'` would make the package fail
+ * to COMPILE wherever those types are missing — turning a graceful runtime
+ * fallback into a build error. The surface used is five methods wide, so
+ * describing it here is cheaper and safer than a dependency.
+ */
+interface SqliteStatement {
+    run(...params: unknown[]): unknown;
+    get(...params: unknown[]): unknown;
+    all(...params: unknown[]): unknown[];
+}
+interface SqliteDatabase {
+    exec(sql: string): void;
+    prepare(sql: string): SqliteStatement;
+    close(): void;
+}
+export declare class SqliteTranscriptStore implements TranscriptStore {
+    private readonly db;
+    constructor(db: SqliteDatabase);
+    /**
+     * INVARIANTS 1-5, in one transaction.
+     *
+     * The transaction is explicit BEGIN/COMMIT because `node:sqlite` has no
+     * `db.transaction()` wrapper of the kind better-sqlite3 provides. The
+     * rollback on failure is what makes invariant 1 true: a batch that fails
+     * half-way must leave no parts behind, or a retry would see a transcript that
+     * never existed.
+     */
+    upsertParts(sessionId: string, parts: StoredPartInput[]): {
+        maxRev: number;
+        changedPartIds: string[];
+    };
+    /** INVARIANTS 6 and 7. */
+    getDelta(sessionId: string, sinceRev: number): {
+        parts: StoredPart[];
+        maxRev: number;
+    };
+    getParts(sessionId: string): StoredPart[];
+    getMaxRev(sessionId: string): number;
+    deleteParts(sessionId: string): void;
+    close(): void;
+}
+/**
+ * The same seven invariants, without durability.
+ *
+ * Used when `node:sqlite` is absent, and in tests. It is a REAL implementation
+ * rather than a stub: if the two disagreed, every test that used this would be
+ * testing something the product does not do. The tests run the same invariant
+ * suite against both.
+ */
+export declare class MemoryTranscriptStore implements TranscriptStore {
+    private readonly bySession;
+    private globalRev;
+    upsertParts(sessionId: string, parts: StoredPartInput[]): {
+        maxRev: number;
+        changedPartIds: string[];
+    };
+    getDelta(sessionId: string, sinceRev: number): {
+        parts: StoredPart[];
+        maxRev: number;
+    };
+    getParts(sessionId: string): StoredPart[];
+    getMaxRev(sessionId: string): number;
+    deleteParts(sessionId: string): void;
+    private ordered;
+}
+export interface OpenStoreResult {
+    store: TranscriptStore;
+    /** True when the store survives a restart. False means the fallback is in use. */
+    durable: boolean;
+    /** Why durability was unavailable. Reported so a degraded fleet is visible. */
+    reason?: string;
+}
+/**
+ * Open the durable store, or say plainly why it could not be opened.
+ *
+ * NEVER THROWS. A harness that cannot open a database is still able to run a
+ * turn and push it to the control plane, which is the source of truth; refusing
+ * to boot would trade a recoverable degradation for an outage. The caller
+ * reports `durable: false` in its health snapshot so the degradation is VISIBLE
+ * rather than silent — a fallback nobody can see is how an outage becomes a
+ * mystery.
+ */
+export declare function openTranscriptStore(path: string): OpenStoreResult;
+export {};