@xingular/harness 2.0.0 → 2.0.1-unstable

package/dist/sdk/server/serve.d.ts

@@ -0,0 +1,13 @@
+import type { Harness } from "../harness.js";
+import { RpcPeer, type Transport } from "./rpc.js";
+export interface Served {
+    peer: RpcPeer;
+    /** Stops live work and releases what the harness holds. */
+    shutdown(): Promise<void>;
+}
+/**
+ * Registers the method table on `peer` and forwards events and notices to it. Returns what stops the
+ * forwarding, for a peer that goes away before the harness does (a socket connection).
+ */
+export declare function attach(harness: Harness, peer: RpcPeer): () => void;
+export declare function serve(harness: Harness, transport: Transport): Served;

package/dist/sdk/server/serve.js

@@ -0,0 +1,25 @@
+import { methods } from "./methods.js";
+import { RpcPeer } from "./rpc.js";
+/**
+ * Registers the method table on `peer` and forwards events and notices to it. Returns what stops the
+ * forwarding, for a peer that goes away before the harness does (a socket connection).
+ */
+export function attach(harness, peer) {
+    for (const [name, handler] of Object.entries(methods(harness)))
+        peer.handle(name, handler);
+    peer.handle('harness.methods', () => peer.methods());
+    const stopEvents = harness.runs.listen((event) => peer.send({ event }));
+    const stopNotices = harness.bus.on((notice) => peer.send({ notice }));
+    return () => {
+        stopEvents();
+        stopNotices();
+    };
+}
+export function serve(harness, transport) {
+    const peer = new RpcPeer(transport);
+    attach(harness, peer);
+    let closing = null;
+    const shutdown = () => (closing ??= harness.close());
+    peer.handle('harness.shutdown', () => shutdown());
+    return { peer, shutdown };
+}

package/dist/sdk/server/socket.d.ts

@@ -0,0 +1,28 @@
+import { type Socket } from 'node:net';
+import type { Harness } from "../harness.js";
+import { type Transport } from "./rpc.js";
+/** Protocol lines over one socket. */
+export declare function socketTransport(socket: Socket): Transport;
+export interface SocketServer {
+    path: string;
+    close(): Promise<void>;
+    /** Connections open now. */
+    connections(): number;
+}
+/**
+ * Serves `harness` on a socket at `path`, readable and writable by this user only. Each connection
+ * gets the whole method table and the run events and notices while it is open.
+ */
+export declare function serveSocket(harness: Harness, path: string, extra?: Record<string, (params: Record<string, unknown>) => unknown>): Promise<SocketServer>;
+export interface HarnessClient {
+    call<T = unknown>(method: string, params?: Record<string, unknown>, timeoutMs?: number): Promise<T>;
+    /** Run events and notices the harness sends while connected. */
+    onMessage(listener: (message: {
+        event?: unknown;
+        notice?: unknown;
+    }) => void): () => void;
+    close(): void;
+    readonly closed: Promise<void>;
+}
+/** Connects to a harness serving on `path`. */
+export declare function connectHarness(path: string): Promise<HarnessClient>;

package/dist/sdk/server/socket.js

@@ -0,0 +1,122 @@
+// The server protocol (page 10) on a local Unix socket, one peer per connection, so more than one
+// client can reach the same long-lived harness (ADR-0083, phase 3). The framing is the stdio
+// protocol's: one JSON message per line.
+import { chmodSync, existsSync, rmSync } from 'node:fs';
+import { createConnection, createServer } from 'node:net';
+import { createInterface } from 'node:readline';
+import { HarnessError } from "../core/errors.js";
+import { PROTOCOL_VERSION, RpcPeer } from "./rpc.js";
+import { attach } from "./serve.js";
+/** Protocol lines over one socket. */
+export function socketTransport(socket) {
+    const reader = createInterface({ input: socket, crlfDelay: Infinity });
+    return {
+        write: (line) => { if (!socket.destroyed)
+            socket.write(`${line}\n`); },
+        onLine: (listener) => void reader.on('line', listener)
+    };
+}
+/**
+ * Serves `harness` on a socket at `path`, readable and writable by this user only. Each connection
+ * gets the whole method table and the run events and notices while it is open.
+ */
+export async function serveSocket(harness, path, extra = {}) {
+    if (existsSync(path))
+        rmSync(path, { force: true });
+    const open = new Set();
+    const server = createServer((socket) => {
+        open.add(socket);
+        const peer = new RpcPeer(socketTransport(socket));
+        const stop = attach(harness, peer);
+        for (const [name, handler] of Object.entries(extra))
+            peer.handle(name, handler);
+        const gone = () => {
+            open.delete(socket);
+            stop();
+        };
+        socket.once('close', gone);
+        socket.on('error', () => socket.destroy());
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(path, () => {
+            server.off('error', reject);
+            resolve();
+        });
+    });
+    chmodSync(path, 0o600);
+    return {
+        path,
+        connections: () => open.size,
+        close: async () => {
+            for (const socket of open)
+                socket.destroy();
+            await new Promise((resolve) => server.close(() => resolve()));
+            rmSync(path, { force: true });
+        }
+    };
+}
+/** Connects to a harness serving on `path`. */
+export async function connectHarness(path) {
+    const socket = createConnection(path);
+    await new Promise((resolve, reject) => {
+        socket.once('connect', resolve);
+        socket.once('error', reject);
+    });
+    const reader = createInterface({ input: socket, crlfDelay: Infinity });
+    const pending = new Map();
+    const listeners = new Set();
+    let next = 0;
+    const closed = new Promise((resolve) => socket.once('close', () => {
+        for (const [, call] of pending) {
+            clearTimeout(call.timer);
+            call.reject(new HarnessError('harness_unavailable', 'The harness closed the connection.'));
+        }
+        pending.clear();
+        resolve();
+    }));
+    socket.on('error', () => undefined);
+    reader.on('line', (line) => {
+        let message;
+        try {
+            message = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        if (message.v !== PROTOCOL_VERSION)
+            return;
+        if (typeof message.id === 'string' && pending.has(message.id)) {
+            const call = pending.get(message.id);
+            pending.delete(message.id);
+            clearTimeout(call.timer);
+            if (message.error) {
+                const shape = message.error;
+                call.reject(new HarnessError(shape.code, shape.message, shape.retryHint ?? null));
+            }
+            else
+                call.resolve(message.result);
+            return;
+        }
+        if ('event' in message || 'notice' in message)
+            for (const listener of listeners)
+                listener(message);
+    });
+    return {
+        call: (method, params = {}, timeoutMs = 60_000) => new Promise((resolve, reject) => {
+            const id = `c${++next}`;
+            const timer = setTimeout(() => {
+                pending.delete(id);
+                reject(new HarnessError('harness_timeout', `The harness did not answer ${method}.`));
+            }, timeoutMs);
+            pending.set(id, { resolve: resolve, reject, timer });
+            socket.write(`${JSON.stringify({ v: PROTOCOL_VERSION, id, method, params })}\n`);
+        }),
+        onMessage: (listener) => {
+            listeners.add(listener);
+            return () => { listeners.delete(listener); };
+        },
+        close: () => socket.end(),
+        closed
+    };
+}

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

@@ -0,0 +1,47 @@
+import type { Bus } from "../core/bus.js";
+import type { RunRecord } from "./contracts.js";
+/** Kinds of session with a switch: an agent's own conversations, and sessions in a project. */
+export declare const APPROVAL_KEYS: readonly ["chat", "pi"];
+export interface ApprovalPolicy {
+    /** Switch key → every approval is granted without asking. */
+    auto: Record<string, boolean>;
+    /** Approval key → tools allowed across sessions that share this local state directory. */
+    globalTools: Record<string, string[]>;
+    /** Session id → approval targets always allowed there. */
+    remembered: Record<string, string[]>;
+}
+/** Why a request is granted without asking. */
+export type AutomaticReason = 'always' | 'remembered' | 'scope';
+/** What only the embedding application knows about a pending approval. */
+export interface ApprovalFacts {
+    /** Unattended work keeps to its saved scope whatever the switches say. */
+    unattended?: boolean;
+    /** The session may not change anything; the switch must not approve its way out of that. */
+    readOnly?: boolean;
+    /** The application's own scope already covers this exact operation. */
+    inScope?: boolean;
+}
+/** Why the standing choices grant this request, if they do. */
+export declare function decide(policy: ApprovalPolicy, key: string, sessionId: string, target: string): AutomaticReason | null;
+export declare function grant(policy: ApprovalPolicy, key: string, sessionId: string, target: string, facts?: ApprovalFacts): AutomaticReason | null;
+/** A conversation's runs share one switch whatever model they use; other runs follow their own. */
+export declare const approvalKey: (run: Pick<RunRecord, "mode" | "harness">) => string;
+export declare class Approvals {
+    private readonly bus;
+    private readonly path;
+    constructor(stateDir: string, bus: Bus);
+    read(): ApprovalPolicy;
+    private change;
+    isAuto(key: string): boolean;
+    /** Why this run's approval for `target` can be granted without asking, if it can. */
+    automatic(run: RunRecord, target: string, facts?: ApprovalFacts): AutomaticReason | null;
+    setAuto(key: string, on: boolean): ApprovalPolicy;
+    /** Always allow `target` for every session in this approval profile and state directory. */
+    allowTool(key: string, target: string): ApprovalPolicy;
+    revokeTool(key: string, target: string): ApprovalPolicy;
+    /** Always allow `target` in this session. */
+    remember(sessionId: string, target: string): ApprovalPolicy;
+    forget(sessionId: string, target: string): ApprovalPolicy;
+    /** Forgets what was remembered for a session that no longer exists. */
+    forgetSession(sessionId: string): void;
+}

package/dist/sdk/sessions/approvals.js

@@ -0,0 +1,119 @@
+// What the user has chosen to stop being asked about: an "always approve" switch, tools allowed
+// across a harness state directory, and tools remembered for one session.
+import { chmodSync } from 'node:fs';
+import { join } from 'node:path';
+import { invalid } from "../core/errors.js";
+import { readJson, writeJson } from "../core/fs.js";
+/** Kinds of session with a switch: an agent's own conversations, and sessions in a project. */
+export const APPROVAL_KEYS = ['chat', 'pi'];
+/** Why the standing choices grant this request, if they do. */
+export function decide(policy, key, sessionId, target) {
+    if (policy.auto[key])
+        return 'always';
+    if (policy.globalTools[key]?.includes(target))
+        return 'remembered';
+    return policy.remembered[sessionId]?.includes(target) ? 'remembered' : null;
+}
+export function grant(policy, key, sessionId, target, facts = {}) {
+    if (facts.unattended)
+        return null;
+    // "Always approve" must not let a read-only session approve its way out of read-only mode.
+    return decide(facts.readOnly ? { auto: {}, globalTools: {}, remembered: policy.remembered } : policy, key, sessionId, target);
+}
+/** A conversation's runs share one switch whatever model they use; other runs follow their own. */
+export const approvalKey = (run) => (run.mode === 'chat' ? 'chat' : run.harness);
+export class Approvals {
+    bus;
+    path;
+    constructor(stateDir, bus) {
+        this.bus = bus;
+        this.path = join(stateDir, 'approvals.json');
+    }
+    read() {
+        const stored = readJson(this.path) ?? {};
+        return { auto: stored.auto ?? {}, globalTools: stored.globalTools ?? {}, remembered: stored.remembered ?? {} };
+    }
+    change(update) {
+        const policy = this.read();
+        update(policy);
+        writeJson(this.path, policy);
+        try {
+            chmodSync(this.path, 0o600);
+        }
+        catch {
+            // The file was written; a mode that cannot be set is not worth failing the change.
+        }
+        this.bus.emit({ type: 'approvals.changed' });
+        return policy;
+    }
+    isAuto(key) {
+        try {
+            return Boolean(this.read().auto[key]);
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Why this run's approval for `target` can be granted without asking, if it can. */
+    automatic(run, target, facts = {}) {
+        // What the application's own scope already covers needs neither the switch nor the user.
+        return grant(this.read(), approvalKey(run), run.sessionId, target, facts) ?? (!facts.unattended && facts.inScope ? 'scope' : null);
+    }
+    setAuto(key, on) {
+        if (!APPROVAL_KEYS.includes(key))
+            throw invalid('Unknown harness.');
+        return this.change((policy) => void (policy.auto[key] = on));
+    }
+    /** Always allow `target` for every session in this approval profile and state directory. */
+    allowTool(key, target) {
+        if (!APPROVAL_KEYS.includes(key))
+            throw invalid('Unknown harness.');
+        if (!target.trim())
+            throw invalid('A tool is required.');
+        return this.change((policy) => {
+            const targets = (policy.globalTools[key] ??= []);
+            if (!targets.includes(target))
+                targets.push(target);
+        });
+    }
+    revokeTool(key, target) {
+        if (!APPROVAL_KEYS.includes(key))
+            throw invalid('Unknown harness.');
+        return this.change((policy) => {
+            const targets = policy.globalTools[key]?.filter((item) => item !== target) ?? [];
+            if (targets.length)
+                policy.globalTools[key] = targets;
+            else
+                delete policy.globalTools[key];
+        });
+    }
+    /** Always allow `target` in this session. */
+    remember(sessionId, target) {
+        if (!target.trim())
+            throw invalid('A tool is required.');
+        return this.change((policy) => {
+            const targets = (policy.remembered[sessionId] ??= []);
+            if (!targets.includes(target))
+                targets.push(target);
+        });
+    }
+    forget(sessionId, target) {
+        return this.change((policy) => {
+            const targets = policy.remembered[sessionId]?.filter((item) => item !== target) ?? [];
+            if (targets.length)
+                policy.remembered[sessionId] = targets;
+            else
+                delete policy.remembered[sessionId];
+        });
+    }
+    /** Forgets what was remembered for a session that no longer exists. */
+    forgetSession(sessionId) {
+        try {
+            if (sessionId in this.read().remembered)
+                this.change((policy) => void delete policy.remembered[sessionId]);
+        }
+        catch {
+            // Nothing recorded.
+        }
+    }
+}

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

@@ -0,0 +1,7 @@
+import { type Checkpoint, type RunEvent } from "./contracts.js";
+/** The removed model tool. Pinned capability sets from before ADR-0069 may still name it. */
+export declare const LEGACY_CHECKPOINT_WRITE = "checkpoint_write";
+/** The latest checkpoint a run recorded, if any. */
+export declare function checkpointOf(events: readonly RunEvent[]): Checkpoint | null;
+/** The checkpoint as the next slice reads it. Bounded by its parts; the caller clips the whole. */
+export declare function describeCheckpoint(checkpoint: Checkpoint): string;

package/dist/sdk/sessions/checkpoint.js

@@ -0,0 +1,41 @@
+// A run's handoff record: where a reply stopped and what the next one must know. The harness writes
+// it from the run's own evidence (files, checks, todo, the completion check's verdict) when a reply stops
+// with work left; the model no longer writes it (ADR-0069 removed `checkpoint_write`). Older runs'
+// model-written checkpoints stay readable.
+import { runEventPayloadSchemas } from "./contracts.js";
+/** The removed model tool. Pinned capability sets from before ADR-0069 may still name it. */
+export const LEGACY_CHECKPOINT_WRITE = 'checkpoint_write';
+/** The latest checkpoint a run recorded, if any. */
+export function checkpointOf(events) {
+    const last = events.filter((event) => event.type === 'checkpoint').at(-1);
+    if (!last)
+        return null;
+    const parsed = runEventPayloadSchemas.checkpoint.safeParse(last.payload);
+    return parsed.success ? parsed.data : null;
+}
+const line = (value) => value.replace(/\s+/gu, ' ').trim();
+/** The checkpoint as the next slice reads it. Bounded by its parts; the caller clips the whole. */
+export function describeCheckpoint(checkpoint) {
+    const parts = [];
+    if (checkpoint.summary)
+        parts.push(`Where the last slice stopped: ${line(checkpoint.summary)}`);
+    if (checkpoint.done.length)
+        parts.push(`Done:\n${checkpoint.done.map((entry) => `- ${line(entry.item)}${entry.evidence.length ? ` (${entry.evidence.map(line).join('; ')})` : ''}`).join('\n')}`);
+    if (checkpoint.files.length)
+        parts.push(`Files touched:\n${checkpoint.files.map((entry) => `- ${line(entry.path)}${entry.why ? `: ${line(entry.why)}` : ''}`).join('\n')}`);
+    if (checkpoint.checks.length) {
+        const failing = checkpoint.checks.filter((entry) => !entry.ok);
+        const passing = checkpoint.checks.filter((entry) => entry.ok);
+        if (passing.length)
+            parts.push(`Checks that passed: ${passing.map((entry) => line(entry.command)).join('; ')}`);
+        if (failing.length)
+            parts.push(`Checks that failed:\n${failing.map((entry) => `- ${line(entry.command)}${entry.detail ? `: ${line(entry.detail)}` : ''}`).join('\n')}`);
+    }
+    if (checkpoint.decisions.length)
+        parts.push(`Decisions:\n${checkpoint.decisions.map((entry) => `- ${line(entry.what)}${entry.why ? `: ${line(entry.why)}` : ''}`).join('\n')}`);
+    if (checkpoint.blocked)
+        parts.push(`Blocked: ${line(checkpoint.blocked)}`);
+    if (checkpoint.next)
+        parts.push(`Next step: ${line(checkpoint.next)}`);
+    return parts.join('\n\n');
+}

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

@@ -0,0 +1,18 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { type TodoItem } from "./contracts.js";
+export declare const COMPACTION_CHECKPOINT_EXTENSION = "compaction-checkpoint";
+export interface CompactionCheckpointOptions {
+    /** A stopped run's persisted todo, when the active run is a continuation. */
+    initialTodo?: readonly TodoItem[];
+    /** The current dynamic plan instructions, if this request is in plan mode. */
+    planInstructions?: () => string | null;
+}
+/** A todo list as `todo_write` received it, validated; `null` when any item is unusable. */
+export declare function validatedTodo(value: unknown): TodoItem[] | null;
+/**
+ * Restores the active run's explicit state after a compaction that happened during that run. A run
+ * that starts from already-compacted history keeps its request, todo and plan in live history, so it
+ * gets nothing. The checkpoint is built once per compaction and sits right after the summary, so each
+ * request stays the previous one plus new items; a moving checkpoint defeats provider caching.
+ */
+export declare function compactionCheckpoint(options?: CompactionCheckpointOptions): (pi: ExtensionAPI) => void;

package/dist/sdk/sessions/compactionCheckpoint.js

@@ -0,0 +1,79 @@
+import { renderCompactionCheckpoint } from "../prompt/compile.js";
+import { TODO_WRITE } from "../tools/todo.js";
+import { todoItemSchema, MAX_TODO_ITEMS } from "./contracts.js";
+export const COMPACTION_CHECKPOINT_EXTENSION = 'compaction-checkpoint';
+/** A todo list as `todo_write` received it, validated; `null` when any item is unusable. */
+export function validatedTodo(value) {
+    if (!Array.isArray(value) || value.length > MAX_TODO_ITEMS)
+        return null;
+    const items = [];
+    for (const valueItem of value) {
+        const item = valueItem;
+        const parsed = todoItemSchema.safeParse({
+            text: typeof item?.text === 'string' ? item.text.trim() : item?.text,
+            status: item?.status
+        });
+        if (!parsed.success)
+            return null;
+        items.push(parsed.data);
+    }
+    return items;
+}
+/**
+ * Restores the active run's explicit state after a compaction that happened during that run. A run
+ * that starts from already-compacted history keeps its request, todo and plan in live history, so it
+ * gets nothing. The checkpoint is built once per compaction and sits right after the summary, so each
+ * request stays the previous one plus new items; a moving checkpoint defeats provider caching.
+ */
+export function compactionCheckpoint(options = {}) {
+    return (pi) => {
+        let goal = '';
+        let todo = validatedTodo(options.initialTodo ?? []) ?? [];
+        // The summary already in context at the run's first request; undefined until that request.
+        let baseline;
+        let checkpoint;
+        const reset = (prompt = '') => {
+            goal = prompt;
+            todo = validatedTodo(options.initialTodo ?? []) ?? [];
+            baseline = undefined;
+            checkpoint = undefined;
+        };
+        pi.on('before_agent_start', (event) => {
+            if (event.messageType !== 'user')
+                return;
+            reset(event.prompt);
+        });
+        pi.on('tool_result', (event) => {
+            if (event.toolName !== TODO_WRITE || event.isError)
+                return;
+            const items = validatedTodo(event.input.items);
+            if (items)
+                todo = items;
+        });
+        pi.on('context', (event) => {
+            const index = event.messages.findLastIndex((message) => message.role === 'compactionSummary');
+            const summary = index >= 0 ? event.messages[index] : undefined;
+            const key = summary ? `${summary.timestamp}:${summary.tokensBefore}` : null;
+            if (!baseline) {
+                baseline = { key };
+                return;
+            }
+            if (!key || key === baseline.key)
+                return;
+            if (checkpoint?.key !== key) {
+                const content = renderCompactionCheckpoint({ goal, todo, planInstructions: options.planInstructions?.() ?? null });
+                checkpoint = {
+                    key,
+                    message: content
+                        ? { role: 'custom', customType: COMPACTION_CHECKPOINT_EXTENSION, content, display: false, timestamp: Date.now() }
+                        : null
+                };
+            }
+            if (!checkpoint.message)
+                return;
+            return { messages: [...event.messages.slice(0, index + 1), checkpoint.message, ...event.messages.slice(index + 1)] };
+        });
+        pi.on('agent_settled', () => reset());
+        pi.on('session_tree', () => reset());
+    };
+}

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

@@ -0,0 +1,51 @@
+export type CheckVerdictKind = 'done' | 'continue';
+export interface CheckVerdict {
+    verdict: CheckVerdictKind;
+    reason: string;
+    /** The next concrete step, for `continue`. */
+    next: string;
+}
+/** What the check sends; kept small so a check costs a fraction of a round. */
+export declare const MAX_CHECK_TRANSCRIPT = 24000;
+export declare const CHECK_TIMEOUT_MS = 60000;
+/** The fixed instructions of the check. Answering is all it does: it has no tools. */
+export declare const CHECK_SYSTEM_PROMPT = "You verify whether an AI coding agent has achieved a goal a person gave it. You do not do the work and you have no tools. You read the goal objective and a transcript of what the agent did and said, and you answer with one JSON object and nothing else:\n\n{\"verdict\":\"done\"|\"continue\",\"reason\":\"one or two sentences\",\"next\":\"the next concrete step, for continue\"}\n\nTreat completion as unproven. Derive the concrete requirements from the objective and from any file, plan or spec it points to that the transcript shows. For every explicit requirement, numbered item, named artifact, command, test, gate and deliverable, look in the transcript for evidence that it was achieved and checked: command output, test results, file contents the agent read or wrote. Evidence that is weak, indirect or missing counts as not achieved. The agent saying the goal is complete is not evidence. Match the scope of the check to the scope of the requirement: a narrow check does not support a broad claim.\n\nAnswer \"done\" only when every requirement has evidence in the transcript. Quote the key evidence in \"reason\". Answer \"continue\" when any requirement is unmet, unchecked or unclear; name the unmet requirements in \"reason\" and the next step in \"next\". If the transcript does not contain clear evidence that the objective is met, answer \"continue\" with the reason \"insufficient evidence in transcript\".\n\nJudge only from the objective and the transcript. Keep \"reason\" and \"next\" short and specific.";
+/**
+ * The reply's transcript: from the person's request onward, clipped to `limit` with the newest
+ * messages kept. The request is found as the last user message that contains its opening text;
+ * without it, the tail of the conversation stands in.
+ */
+export declare function replyTranscript(messages: readonly unknown[], request: string, limit?: number): string;
+/** The check's user message. */
+export declare function checkPrompt(objective: string, transcript: string): string;
+/** The verdict in the check's text, or `null` when there is none: the first JSON object that parses. */
+export declare function parseVerdict(text: string): CheckVerdict | null;
+/** A model answer as the check needs it: its text, and what it cost for the run's usage. */
+export interface CheckAnswer {
+    text: string;
+    /** The provider's message, passed to the usage recorder unchanged. */
+    message?: unknown;
+}
+/** Asks a model once. Implemented over Pi's model registry by the caller. */
+export type CheckModel = (system: string, user: string, signal: AbortSignal) => Promise<CheckAnswer>;
+/**
+ * Runs one check. Never throws: a timeout, an error or an answer without a verdict returns
+ * `{ verdict: null }`, and the claim is accepted as it stands.
+ */
+export declare function runCompletionCheck(ask: CheckModel, input: {
+    objective: string;
+    messages: readonly unknown[];
+}, options?: {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}): Promise<{
+    verdict: CheckVerdict | null;
+    answer: CheckAnswer | null;
+    error?: string;
+}>;
+/** The text of a model's answer message. */
+export declare function answerText(message: unknown): string;
+/** The model a goal-claim check asks: the session's own model, at low effort, through Pi's registry. */
+export declare function sessionCheckModel(ctx: unknown): CheckModel | null;
+/** `XINGULAR_COMPLETION_CHECK=off` at launch accepts every goal claim unchecked, for experiments. */
+export declare function launchSwitchOff(name: 'XINGULAR_COMPLETION_CHECK'): boolean;