@xingular/harness 0.1.7 → 1.1.1

package/dist/sdk/sessions/runStore.js

@@ -0,0 +1,337 @@
+// 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, 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,
+        id: record.id,
+        projectId: record.projectId,
+        mode: record.mode,
+        harness: record.harness,
+        sessionType: record.sessionType,
+        sessionId: record.sessionId,
+        nativeSessionId: record.nativeSessionId,
+        workingDirectory: record.workingDirectory,
+        worktreeId: record.worktreeId,
+        goal: record.goal,
+        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 } : {})
+    };
+}
+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 } = record;
+    update(record);
+    if (!isActiveStatus(status))
+        Object.assign(record, { status, endedAt, terminalReason });
+    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;
+}
+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);
+        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);
+            if (record.status !== status || record.endedAt !== settled.timestamp || record.terminalReason !== settledReason) {
+                const backup = `${path}.before-outcome-repair`;
+                if (!existsSync(backup))
+                    copyFileSync(path, backup);
+                Object.assign(record, { status, endedAt: settled.timestamp, terminalReason: settledReason });
+                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.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 } });
+        write(root, record);
+        interrupted.push(record.id);
+    }
+    return interrupted;
+}
+/** 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,213 @@
+import type { 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 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>;
+    cwd: string;
+    sessionDir: string;
+    /** The native history to open, or `null` to start a fresh one. */
+    historyFile: string | null;
+    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;
+    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;
+    };
+    /** 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;
+}
+/** 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;
+    }>;
+    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;
+    }): 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;
+}
+export interface ToolGate {
+    /** Resolves to a block reason, or null to let the call run. */
+    check(toolName: string, input: unknown): Promise<string | null>;
+    /** 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 type SessionFactory = (input: {
+    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;
+}) => 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;
+/** Streams one request through a Pi session, translating events for the run. */
+export declare function runTurn(run: ActiveRun, session: PiSessionLike, params: TurnParams): Promise<void>;
+/**
+ * Loads what a session may use besides its tools: Pi's context files, the registry's skills and
+ * prompts, and what the harness found for it. `gate` is loaded after every extension on disk.
+ */
+export declare function loadResources(pi: typeof import('@earendil-works/pi-coding-agent'), params: Pick<TurnParams, 'cwd' | 'account' | 'automatic' | 'resources' | 'variantExtensions' | 'plugins' | 'system' | 'inline'>, 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;