@xingular/harness 2.0.0 → 2.0.1-unstable

package/dist/sdk/sessions/runStore.js

@@ -0,0 +1,393 @@
+// Canonical run records and their event logs.
+//
+// `<data root>/runs/<run id>/run.json` holds the run's fields; `events.jsonl` is the
+// append-only, validated event log. The harness is the only writer of both.
+import { appendFileSync, copyFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { notFound } from "../core/errors.js";
+import { newId, now, readJson, readJsonOr, safeId, writeJson } from "../core/fs.js";
+import { compareText, lines } from "../core/text.js";
+import { isActiveStatus, runEventSchema, runRecordSchema, stopCodeOf, upgradeRunRecord, usagePayloadSchema } from "./contracts.js";
+import { readAllRuns, recordRun, runsForSession } from "./runIndex.js";
+export function runDir(root, runId) {
+    return join(root, 'runs', safeId(runId));
+}
+const recordPath = (root, runId) => join(runDir(root, runId), 'run.json');
+// Field order of the file, so a record written here reads the same as one written before.
+function ordered(record) {
+    return {
+        resumedFromRunId: record.resumedFromRunId,
+        parentRunId: record.parentRunId,
+        relation: record.relation,
+        terminalReason: record.terminalReason,
+        ...(record.terminalCode !== undefined ? { terminalCode: record.terminalCode } : {}),
+        id: record.id,
+        projectId: record.projectId,
+        mode: record.mode,
+        ...(record.effectiveMode !== undefined ? { effectiveMode: record.effectiveMode } : {}),
+        harness: record.harness,
+        sessionType: record.sessionType,
+        sessionId: record.sessionId,
+        nativeSessionId: record.nativeSessionId,
+        workingDirectory: record.workingDirectory,
+        ...(record.workspaceRoot !== undefined ? { workspaceRoot: record.workspaceRoot } : {}),
+        worktreeId: record.worktreeId,
+        goal: record.goal,
+        ...(record.goalMode ? { goalMode: record.goalMode } : {}),
+        attachmentCount: record.attachmentCount,
+        startedAt: record.startedAt,
+        endedAt: record.endedAt,
+        status: record.status,
+        exitCode: record.exitCode,
+        handoffId: record.handoffId,
+        accountId: record.accountId,
+        agentId: record.agentId,
+        trigger: record.trigger,
+        ...(record.variantScope ? { variantScope: record.variantScope } : {}),
+        ...(record.variantVersion ? { variantVersion: record.variantVersion } : {}),
+        ...(record.profile ? { profile: record.profile } : {}),
+        ...(record.title ? { title: record.title } : {}),
+        ...(record.model ? { model: record.model } : {}),
+        ...(record.effort ? { effort: record.effort } : {}),
+        ...(record.loadedSkills !== undefined ? { loadedSkills: record.loadedSkills } : {}),
+        ...(record.activatedPlugins !== undefined ? { activatedPlugins: record.activatedPlugins } : {}),
+        ...(record.workspaceSnapshot ? { workspaceSnapshot: record.workspaceSnapshot } : {})
+    };
+}
+function write(root, record) {
+    writeJson(recordPath(root, record.id), ordered(record));
+    if (isActiveStatus(record.status))
+        claimOwner(root, record.id);
+    recordRun(root, record);
+}
+// The process that is driving an active run. Startup recovery leaves such a run alone while that process lives.
+const ownerPath = (root, runId) => join(runDir(root, runId), 'owner.json');
+function claimOwner(root, runId) {
+    const path = ownerPath(root, runId);
+    if (readJsonOr(path, null)?.pid === process.pid)
+        return;
+    writeJson(path, { pid: process.pid });
+}
+/** True only when a different live process owns the run. No marker, or a dead owner, means nothing holds it. */
+function ownedElsewhere(root, runId) {
+    const pid = readJsonOr(ownerPath(root, runId), null)?.pid;
+    if (typeof pid !== 'number' || pid <= 0 || pid === process.pid)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+export function saveRun(root, record) {
+    write(root, record);
+}
+function readRecord(path) {
+    const parsed = runRecordSchema.safeParse(upgradeRunRecord(readJson(path)));
+    return parsed.success ? parsed.data : null;
+}
+export function loadRun(root, runId) {
+    const record = readRecord(recordPath(root, runId));
+    if (!record)
+        throw notFound('Run');
+    return record;
+}
+export function findRun(root, runId) {
+    try {
+        return loadRun(root, runId);
+    }
+    catch {
+        return null;
+    }
+}
+/** A parent's reserved child IDs survive a crash before the spawn tool returns. */
+export function recordSubagent(root, parentRunId, childRunId) {
+    loadRun(root, parentRunId);
+    const ids = recordedSubagents(root, parentRunId);
+    if (!ids.includes(childRunId))
+        writeJson(join(runDir(root, parentRunId), 'subagents.json'), [...ids, childRunId]);
+}
+export function recordedSubagents(root, parentRunId) {
+    const value = readJson(join(runDir(root, parentRunId), 'subagents.json'));
+    if (value === null)
+        return [];
+    if (!Array.isArray(value) || value.some(id => typeof id !== 'string'))
+        throw new Error('Recorded subagent ownership is unreadable.');
+    return value;
+}
+/** Changes a run's record. A settled run keeps its outcome whatever the change says. */
+export function updateRun(root, runId, update) {
+    const record = readRecord(recordPath(root, runId));
+    if (!record)
+        return;
+    const { status, endedAt, terminalReason, terminalCode } = record;
+    update(record);
+    if (!isActiveStatus(status))
+        Object.assign(record, { status, endedAt, terminalReason, terminalCode });
+    write(root, record);
+}
+export function terminalStatus(event) {
+    if (event.type === 'completed')
+        return 'completed';
+    if (event.type === 'failed')
+        return 'failed';
+    if (event.type !== 'status.changed')
+        return null;
+    const status = event.payload?.status;
+    return status === 'interrupted' || status === 'failed' || status === 'completed' ? status : null;
+}
+function reasonOf(event) {
+    const payload = event.payload;
+    const reason = payload?.reason ?? payload?.message;
+    return typeof reason === 'string' ? reason : null;
+}
+/** The stop code a terminal event carries; null for an interruption written without one. */
+export function stopCodeOfEvent(event) {
+    const payload = event.payload;
+    if (event.type === 'completed')
+        return 'completed';
+    if (event.type === 'failed')
+        return stopCodeOf(typeof payload?.code === 'string' ? payload.code : 'failed');
+    return typeof payload?.code === 'string' ? stopCodeOf(payload.code) : null;
+}
+export function appendEvent(root, event) {
+    const directory = runDir(root, event.runId);
+    mkdirSync(directory, { recursive: true });
+    // O_APPEND with a single write keeps each line intact.
+    appendFileSync(join(directory, 'events.jsonl'), `${JSON.stringify(event)}\n`);
+}
+/** A stored event as it was written: structurally an event, whatever its payload. */
+function storedEvent(line) {
+    try {
+        const value = JSON.parse(line);
+        const valid = value && typeof value.id === 'string' && typeof value.runId === 'string' && typeof value.sessionId === 'string' && Number.isInteger(value.sequence) && value.sequence >= 0 && typeof value.timestamp === 'string' && typeof value.type === 'string' && value.payload !== undefined;
+        return valid ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** A torn final line (a crash mid-write) is skipped rather than failing the whole log. */
+export function readEvents(root, runId) {
+    let text;
+    try {
+        text = readFileSync(join(runDir(root, runId), 'events.jsonl'), 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    return lines(text).flatMap((line) => storedEvent(line) ?? []);
+}
+/** An incoming event that passes the contract, or `null`. */
+export function parseEvent(value) {
+    const parsed = runEventSchema.safeParse(value);
+    if (!parsed.success)
+        return null;
+    try {
+        safeId(parsed.data.runId);
+    }
+    catch {
+        return null;
+    }
+    return parsed.data;
+}
+/** The events that affected execution; what arrived after the outcome stays in the raw log as evidence. */
+export function executionEvents(events) {
+    const end = events.findIndex((event) => terminalStatus(event) !== null);
+    return events.slice(0, end < 0 ? events.length : end + 1).filter((event) => event.native?.hostIgnored === undefined);
+}
+/**
+ * Appends an event and applies it to the run record. An event that arrives after the run
+ * settled is kept as evidence and returns `false`: it is never applied or relayed.
+ */
+export function persistEvent(root, event) {
+    const record = loadRun(root, event.runId);
+    if (!isActiveStatus(record.status)) {
+        event.native = { hostIgnored: 'run_already_ended', event: event.native ?? null };
+        appendEvent(root, event);
+        return false;
+    }
+    appendEvent(root, event);
+    // Most events (text deltas above all) leave the record as it is; it is rewritten only when it changes.
+    let changed = false;
+    const outcome = terminalStatus(event);
+    if (outcome) {
+        record.status = outcome;
+        record.endedAt = event.timestamp;
+        record.terminalReason = reasonOf(event);
+        record.terminalCode = stopCodeOfEvent(event);
+        changed = true;
+    }
+    else if (event.type === 'status.changed') {
+        const status = event.payload.status;
+        if (typeof status === 'string' && status !== record.status) {
+            record.status = status;
+            changed = true;
+        }
+    }
+    const payload = event.payload;
+    if (event.type === 'message.completed' && payload.role === 'user' && record.mode === 'code' && !record.goal) {
+        record.goal = typeof payload.text === 'string' ? payload.text : null;
+        changed = true;
+    }
+    if (changed)
+        write(root, record);
+    return true;
+}
+const STOPPED = 'The harness stopped before the run settled.';
+/** Startup reconciliation for every run that did not settle before the process stopped. */
+export function markInterruptedRuns(root, reason = STOPPED) {
+    const interrupted = [];
+    for (const record of readAllRuns(root)) {
+        const path = recordPath(root, record.id);
+        const events = readEvents(root, record.id);
+        const settled = events.find((event) => terminalStatus(event) !== null);
+        if (settled) {
+            const status = terminalStatus(settled);
+            const settledReason = reasonOf(settled);
+            const settledCode = stopCodeOfEvent(settled);
+            if (record.status !== status || record.endedAt !== settled.timestamp || record.terminalReason !== settledReason || (settledCode !== null && record.terminalCode !== settledCode)) {
+                const backup = `${path}.before-outcome-repair`;
+                if (!existsSync(backup))
+                    copyFileSync(path, backup);
+                Object.assign(record, { status, endedAt: settled.timestamp, terminalReason: settledReason, ...(settledCode ? { terminalCode: settledCode } : {}) });
+                write(root, record);
+            }
+        }
+        if (!isActiveStatus(record.status))
+            continue;
+        // Another live Harness on the same data folder is still running this; it is not an orphan.
+        if (ownedElsewhere(root, record.id))
+            continue;
+        record.status = 'interrupted';
+        record.terminalReason = reason;
+        record.terminalCode = 'harness_restart';
+        record.endedAt ??= now();
+        const last = events.reduce((highest, event) => Math.max(highest, event.sequence), -1);
+        appendEvent(root, { id: newId(), runId: record.id, sessionId: record.sessionId, sequence: last + 1, timestamp: now(), type: 'status.changed', payload: { status: 'interrupted', reason, code: 'harness_restart' } });
+        write(root, record);
+        interrupted.push(record.id);
+    }
+    return interrupted;
+}
+/** How long a live run may go without a heartbeat before it counts as wedged. */
+export const STALE_HEARTBEAT_MS = 5 * 60_000;
+/** How long a run from before heartbeats existed may be silent before it counts as abandoned. */
+export const STALE_SILENT_MS = 30 * 60_000;
+/**
+ * Settles runs this process still owns but is no longer driving. A reply that emitted `heartbeat`
+ * and stopped is wedged; one that never emitted any and has been silent since before heartbeats
+ * existed is abandoned. A live command keeps emitting heartbeats, so a long build is not mistaken
+ * for a hang. Model work is never restarted (INV-RUN-4).
+ */
+export function reconcileStaleRuns(root, at = Date.now(), options = {}) {
+    const heartbeatMs = options.heartbeatMs ?? STALE_HEARTBEAT_MS;
+    const silentMs = options.silentMs ?? STALE_SILENT_MS;
+    const stalled = [];
+    for (const record of readAllRuns(root)) {
+        if (!isActiveStatus(record.status) || ownedElsewhere(root, record.id))
+            continue;
+        const events = readEvents(root, record.id);
+        const lastHeartbeat = events.filter((event) => event.type === 'heartbeat').at(-1);
+        const last = events.at(-1);
+        const stamp = Date.parse(lastHeartbeat?.timestamp ?? last?.timestamp ?? '');
+        if (!Number.isFinite(stamp) || at - stamp <= (lastHeartbeat ? heartbeatMs : silentMs))
+            continue;
+        const reason = lastHeartbeat ? 'stalled' : 'owner_gone';
+        record.status = 'interrupted';
+        record.terminalReason = reason;
+        record.terminalCode = reason;
+        record.endedAt = now();
+        const sequence = events.reduce((highest, event) => Math.max(highest, event.sequence), -1) + 1;
+        appendEvent(root, { id: newId(), runId: record.id, sessionId: record.sessionId, sequence, timestamp: now(), type: 'status.changed', payload: { status: 'interrupted', reason, code: reason } });
+        write(root, record);
+        stalled.push(record.id);
+    }
+    return stalled;
+}
+/** The run's unanswered approvals and questions, oldest first. */
+export function pendingDecisions(events) {
+    const pending = [];
+    for (const requested of events) {
+        const shape = requested.type === 'approval.requested' ? ['approval', 'approvalId', 'approval.resolved'] : requested.type === 'question.requested' ? ['question', 'questionId', 'question.answered'] : null;
+        if (!shape)
+            continue;
+        const [kind, key, answered] = shape;
+        const id = requested.payload[key];
+        if (typeof id !== 'string')
+            continue;
+        if (events.some((entry) => entry.type === answered && entry.payload[key] === id))
+            continue;
+        pending.push({ kind, id, eventId: requested.id, payload: requested.payload });
+    }
+    return pending;
+}
+function belongsToRoot(record, rootRunId, records) {
+    const visited = new Set();
+    let current = record;
+    while (current && !visited.has(current.id)) {
+        if (current.id === rootRunId)
+            return true;
+        visited.add(current.id);
+        current = current.parentRunId ? records.get(current.parentRunId) : undefined;
+    }
+    return false;
+}
+/** A root run and all descendants linked through opaque parent-run metadata. */
+export function runFamily(root, runId) {
+    const all = readAllRuns(root);
+    const byId = new Map(all.map((record) => [record.id, record]));
+    const target = byId.get(runId);
+    if (!target)
+        throw notFound('Run');
+    let familyRoot = target;
+    const ancestors = new Set([target.id]);
+    while (familyRoot.parentRunId) {
+        const parent = byId.get(familyRoot.parentRunId);
+        if (!parent || ancestors.has(parent.id))
+            break;
+        ancestors.add(parent.id);
+        familyRoot = parent;
+    }
+    const members = all.filter((record) => belongsToRoot(record, familyRoot.id, byId))
+        .sort((left, right) => compareText(left.startedAt, right.startedAt));
+    const runs = members.map((run) => {
+        const events = executionEvents(readEvents(root, run.id));
+        const lastUsage = events.filter((event) => event.type === 'usage.updated').at(-1)?.payload;
+        const parsed = usagePayloadSchema.safeParse(lastUsage);
+        return { run, usage: parsed.success ? parsed.data : null };
+    });
+    const counters = ['inputTokens', 'outputTokens', 'cacheReadTokens', 'cacheWriteTokens', 'reasoningTokens', 'costUsd', 'requests'];
+    const usage = Object.fromEntries(counters.map((counter) => {
+        const values = runs.map(({ usage: current }) => current?.[counter]);
+        return [counter, values.every((value) => typeof value === 'number') ? values.reduce((total, value) => total + value, 0) : null];
+    }));
+    return { rootRunId: familyRoot.id, runs, usage, settled: runs.every(({ run }) => !isActiveStatus(run.status)) };
+}
+export function snapshot(root, runId) {
+    const run = loadRun(root, runId);
+    const events = executionEvents(readEvents(root, runId));
+    return { run, events, lastSequence: events.reduce((highest, event) => Math.max(highest, event.sequence), -1) };
+}
+/** A session's history comes from the index; other filters scan run records. At most 200, newest first. */
+export function listRuns(root, filter) {
+    if (filter.sessionId) {
+        try {
+            const records = runsForSession(root, filter.sessionId, 200).flatMap((id) => findRun(root, id) ?? []);
+            return filter.activeOnly ? records.filter((record) => isActiveStatus(record.status)) : records;
+        }
+        catch {
+            // Fall through to the files.
+        }
+    }
+    return readAllRuns(root)
+        .filter((record) => !filter.projectId || record.projectId === filter.projectId)
+        .filter((record) => !filter.sessionId || record.sessionId === filter.sessionId)
+        .filter((record) => !filter.activeOnly || isActiveStatus(record.status))
+        .sort((left, right) => compareText(right.startedAt, left.startedAt))
+        .slice(0, 200);
+}

package/dist/sdk/sessions/runner.d.ts

@@ -0,0 +1,291 @@
+import type { Refusal } from "./contracts.js";
+import type { BashOperations, ModelRuntime, SettingsManager } from '@earendil-works/pi-coding-agent';
+import { EFFORTS, type Effort } from "../core/effort.js";
+import type { AccountContext } from "../accounts/env.js";
+import type { InlineExtension } from "../plugins/firstParty.js";
+import type { Loading, Registered } from "../plugins/plugins.js";
+import { type ContextUpdate } from "../prompt/compile.js";
+import type { ToolSpec } from "../tools/types.js";
+import { type SliceState } from "./workSlice.js";
+import type { GoalController } from "./goal.js";
+import { type ExtensionHost } from "./extensionUi.js";
+import type { ActiveRun } from "./registry.js";
+export { EFFORTS };
+export type { Effort };
+/** What one turn needs once its prompt is compiled and its tools are chosen. */
+export interface TurnParams {
+    runId: string;
+    /** Child runs may not gain tools registered by extensions outside their snapshot. */
+    restrictTools?: boolean;
+    settle?: () => Promise<void>;
+    /**
+     * A live session (ADR-0083): called instead of disposing the Pi session when the run settles, so
+     * the next run of the conversation can use it again. `close` asks to end the session instead,
+     * because the turn stalled and the session cannot be trusted.
+     */
+    release?: (close?: boolean) => void;
+    cwd: string;
+    /** Canonical project root pinned to this run. */
+    workspaceRoot: string;
+    /** A plan run: model-issued Bash runs only in the read-only sandbox scope. */
+    plan?: boolean;
+    /** A top-level attended plan run: one hidden repair turn if the reply lacks its plan block. */
+    repairPlan?: boolean;
+    sessionDir: string;
+    /** The native history to open, or `null` to continue the folder's newest one or start one. */
+    historyFile: string | null;
+    /** Start a new history even when the folder has one (a new conversation). */
+    newHistory?: boolean;
+    model: string | null;
+    effort?: Effort | null;
+    text: string;
+    /** A user-requested shell command to run before the model sees the request. */
+    initialBashCommand?: string;
+    /** A prior run's Bash attempt and result, supplied when retrying a ! command. */
+    initialBashContext?: {
+        runId: string;
+        status: 'completed' | 'incomplete' | 'unknown';
+        ok?: boolean;
+        output?: string;
+    };
+    /** Whether Bash is present in this run's frozen capability snapshot. */
+    initialBashAvailable?: boolean;
+    /** The same gate used for model-issued tools. */
+    gate?: ToolGate;
+    onRefusal?: (toolCallId: string, name: string, refusal: Refusal) => void;
+    images?: {
+        mediaType: string;
+        data: string;
+    }[];
+    requiresImageInput?: boolean;
+    /** App-origin notes placed before the text of the request. */
+    preamble?: string | null;
+    /** Unattended: no project extensions, no context files, settings held in memory. */
+    automatic?: boolean;
+    account: AccountContext;
+    /** Skills and prompt templates to load natively: the variant's skills folder. */
+    resources?: {
+        ids: string[];
+        skillPaths: string[];
+        promptPaths: string[];
+    };
+    /** Pi extensions from the variant (c8) that may load: trusted code, or a probe the person allowed. */
+    variantExtensions?: string[];
+    /**
+     * What the harness found for this session to load, and where it reports what loaded. Pi's own
+     * discovery is off whenever this is set, so only these paths and the registry's reach the session.
+     */
+    plugins?: {
+        loading(): Promise<Loading>;
+        loaded(extensions: Registered[]): void;
+    };
+    activatedPlugins?: (ids: string[]) => void;
+    /** The harness's own switched-on extensions. They are code in this process, so they load in every kind of run. */
+    inline?: InlineExtension[];
+    /** The stable part of the compiled prompt: the only text added to Pi's own. */
+    system: string;
+    /** Changed state, saved as a hidden message in native history before the request. */
+    update: ContextUpdate | null;
+    /** Other hidden messages saved before the request (`SessionRunInput.hiddenNotes`). */
+    hiddenNotes?: Array<{
+        customType: string;
+        content: string;
+    }>;
+    /** Run a session command instead of a prompt: compact, navigate with a summary, or export. */
+    command?: SessionCommand;
+    /** The work slice this reply is bounded by (PROP-0041); the guard updates it as the reply runs. */
+    slice?: {
+        state: SliceState;
+        maxToolCalls: number;
+    };
+    /** The run's /goal (ADR-0072); the runner counts a claim check's model request with the run's usage. */
+    goal?: {
+        controller: GoalController;
+        recordUsage?: (message: unknown) => void;
+    };
+}
+/** The session commands that need a model or a live Pi session, run as their own run. */
+export type SessionCommand = {
+    name: 'compact';
+    instructions?: string;
+} | {
+    name: 'navigate';
+    entryId: string;
+    summarize: boolean;
+    instructions?: string;
+} | {
+    name: 'export';
+    path: string;
+};
+/** Structural view of the Pi events the harness consumes. */
+export type PiEvent = {
+    type: 'message_start';
+    message: {
+        role: string;
+    };
+} | {
+    type: 'message_update';
+    message: {
+        role: string;
+    };
+    assistantMessageEvent: {
+        type: string;
+        delta?: string;
+    };
+} | {
+    type: 'message_end';
+    message: {
+        role: string;
+        content?: Array<{
+            type: string;
+            text?: string;
+            thinkingSignature?: string;
+        }>;
+        api?: string;
+        usage?: {
+            input?: number;
+            output?: number;
+            cacheRead?: number;
+            cacheWrite?: number;
+            reasoning?: number;
+            cost?: {
+                total?: number;
+            };
+        };
+        model?: string;
+        provider?: string;
+        responseId?: string;
+        stopReason?: string;
+        errorMessage?: string;
+    };
+} | {
+    type: 'tool_execution_start';
+    toolCallId: string;
+    toolName: string;
+    args: unknown;
+} | {
+    type: 'tool_execution_end';
+    toolCallId: string;
+    toolName: string;
+    isError: boolean;
+    result?: unknown;
+} | {
+    type: string;
+};
+export interface PiSessionLike {
+    sessionId: string;
+    readonly sessionName?: string;
+    setSessionName?(name: string): void;
+    sessionManager?: {
+        getBranch(): unknown[];
+    };
+    thinkingLevel?: Effort;
+    systemPrompt?: string;
+    extensionCommands?: readonly string[];
+    model?: {
+        input: string[];
+        contextWindow?: number;
+        id?: string;
+        provider?: string;
+    };
+    getActiveToolNames?(): string[];
+    getAllTools?(): Array<{
+        name: string;
+        description?: string;
+        parameters?: unknown;
+    }>;
+    /** Pi's compaction settings, so the run records the headroom it was held to. */
+    settingsManager?: {
+        getCompactionSettings(model?: {
+            provider: string;
+            id: string;
+        }): {
+            enabled: boolean;
+            reserveTokens: number;
+        };
+    };
+    subscribe(listener: (event: PiEvent) => void): () => void;
+    prompt(text: string, options?: {
+        images?: unknown[];
+    }): Promise<void>;
+    executeBash?(command: string, onChunk?: (chunk: string) => void, options?: {
+        id?: string;
+        excludeFromContext?: boolean;
+        operations?: BashOperations;
+    }): Promise<{
+        output: string;
+        exitCode: number | undefined;
+        cancelled: boolean;
+        truncated: boolean;
+        fullOutputPath?: string;
+    }>;
+    abortBash?(): void;
+    /** Queues a message for the model after the current step. Resolves `handled` when Pi takes it without queueing. */
+    steer?(text: string): Promise<'handled' | 'queued'>;
+    /** Drops queued messages Pi has not delivered. */
+    clearQueue?(): unknown;
+    sendCustomMessage?(message: {
+        customType: string;
+        content: string;
+        display: boolean;
+        details: unknown;
+    }, options: {
+        triggerTurn: boolean;
+    }): Promise<void>;
+    abort(): Promise<void>;
+    dispose(): void;
+    compact?(instructions?: string): Promise<unknown>;
+    navigateTree?(targetId: string, options?: {
+        summarize?: boolean;
+        customInstructions?: string;
+    }): Promise<{
+        editorText?: string;
+        cancelled: boolean;
+    }>;
+    exportToHtml?(outputPath?: string): Promise<string>;
+    /** The native history file the session writes, once it has one. */
+    readonly sessionFile?: string;
+    /**
+     * Points an open session at the next run of its conversation (ADR-0083): that run's gate, tools,
+     * extension host and run-scoped extensions replace the previous run's. Only a session the factory
+     * built for reuse has it; the caller checks that the run's pins equal the session's first.
+     */
+    rebind?(input: SessionFactoryInput): Promise<void>;
+}
+export interface ToolGate {
+    /** Resolves to a block reason, or null to let the call run. */
+    check(toolName: string, input: unknown): Promise<string | null>;
+    checkDetailed?(toolName: string, input: unknown): Promise<Refusal | null>;
+    /** Requests one human-only approval before an explicit outside-workspace Bash call runs. */
+    requestWorkspaceWriteScope?(toolName: string, input: unknown, reason: string): Promise<boolean>;
+    /** Whether the explicit Full Permission switch bypasses the boundary for this Bash command. */
+    workspaceBoundaryBypass?(toolName: string, input: unknown): Promise<boolean>;
+    /** Makes these tools ask before each call. Used for tools an extension brought, which no one switched on by name. */
+    ask?(toolNames: readonly string[]): void;
+}
+export interface SessionFactoryInput {
+    params: TurnParams;
+    /** Pi's own tools and the custom tools switched on for this turn, in order. */
+    allow: string[];
+    gate: ToolGate;
+    /** Custom tools already bound to this run. */
+    tools: ToolSpec[];
+    runtime: () => Promise<ModelRuntime>;
+    /** Where a loaded extension's dialogs and notices go. Without it extensions have no interface. */
+    extensions?: ExtensionHost;
+}
+export type SessionFactory = (input: SessionFactoryInput) => Promise<PiSessionLike>;
+/** A one-line description of a tool call, for an approval request or the activity list. */
+export declare function summarize(input: unknown, toolName?: string): string;
+/** How much text a tool handed back to the model: what its result adds to every later request. */
+export declare function resultSize(result: unknown): number | null;
+export declare function runTurn(run: ActiveRun, session: PiSessionLike, params: TurnParams): Promise<void>;
+export declare function loadResources(pi: typeof import('@earendil-works/pi-coding-agent'), params: Pick<TurnParams, 'cwd' | 'account' | 'automatic' | 'resources' | 'variantExtensions' | 'plugins' | 'system' | 'inline' | 'activatedPlugins'>, gate: unknown, automaticSettings?: SettingsManager): Promise<import("@earendil-works/pi-coding-agent").DefaultResourceLoader>;
+/** What each extension on disk registered when it was loaded. The harness's own gate is not one of them. */
+export declare function registeredBy(loader: {
+    getExtensions(): {
+        extensions: readonly unknown[];
+    };
+}): Registered[];
+/** Opens a Pi session for one turn: the account's runtime, the compiled prompt, and the gated tools. */
+export declare const piSessionFactory: SessionFactory;