@xingular/harness 2.0.0 → 2.0.1-unstable

package/dist/sdk/sessions/completionCheck.js

@@ -0,0 +1,161 @@
+/** What the check sends; kept small so a check costs a fraction of a round. */
+export const MAX_CHECK_TRANSCRIPT = 24_000;
+const MAX_TOOL_RESULT = 600;
+const MAX_TOOL_ARGS = 300;
+const MAX_TEXT = 2_000;
+export const CHECK_TIMEOUT_MS = 60_000;
+/** The fixed instructions of the check. Answering is all it does: it has no tools. */
+export 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:
+
+{"verdict":"done"|"continue","reason":"one or two sentences","next":"the next concrete step, for continue"}
+
+Treat 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.
+
+Answer "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".
+
+Judge only from the objective and the transcript. Keep "reason" and "next" short and specific.`;
+const clip = (text, limit) => (text.length <= limit ? text : `${text.slice(0, limit - 1)}…`);
+const textOf = (content) => {
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return '';
+    return content.filter((part) => part?.type === 'text' && typeof part.text === 'string').map((part) => part.text).join('\n');
+};
+/** One message as the check reads it: visible text, tool calls and clipped tool results. Thinking is left out. */
+function renderMessage(message) {
+    if (message.role === 'user') {
+        const text = textOf(message.content);
+        // The goal's own continuation prompts repeat the same long audit text; the check needs only the objective.
+        if (text.startsWith('Continue working toward the active thread goal.'))
+            return '';
+        return `[User or harness]: ${clip(text, MAX_TEXT)}`;
+    }
+    if (message.role === 'toolResult')
+        return `[Tool result${message.toolName ? ` ${message.toolName}` : ''}${message.isError ? ', error' : ''}]: ${clip(textOf(message.content), MAX_TOOL_RESULT)}`;
+    if (message.role === 'assistant') {
+        const parts = Array.isArray(message.content) ? message.content : [];
+        const lines = [];
+        for (const part of parts) {
+            if (part?.type === 'text' && part.text)
+                lines.push(`[Agent]: ${clip(part.text, MAX_TEXT)}`);
+            else if (part?.type === 'toolCall')
+                lines.push(`[Agent tool call] ${part.name ?? 'tool'}(${clip(JSON.stringify(part.arguments ?? {}), MAX_TOOL_ARGS)})`);
+        }
+        return lines.join('\n');
+    }
+    return '';
+}
+/**
+ * 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 function replyTranscript(messages, request, limit = MAX_CHECK_TRANSCRIPT) {
+    const list = messages;
+    const probe = request.trim().slice(0, 80);
+    let start = 0;
+    if (probe) {
+        for (let index = list.length - 1; index >= 0; index -= 1) {
+            if (list[index]?.role === 'user' && textOf(list[index].content).includes(probe)) {
+                start = index;
+                break;
+            }
+        }
+    }
+    const rendered = list.slice(start).map(renderMessage).filter(Boolean);
+    const kept = [];
+    let size = 0;
+    for (let index = rendered.length - 1; index >= 0; index -= 1) {
+        const line = rendered[index];
+        if (size + line.length + 1 > limit) {
+            kept.unshift('[…earlier messages of this reply omitted…]');
+            break;
+        }
+        kept.unshift(line);
+        size += line.length + 1;
+    }
+    return kept.join('\n');
+}
+/** The check's user message. */
+export function checkPrompt(objective, transcript) {
+    return [
+        `## The goal's objective\n${clip(objective.trim() || '(not recorded)', 4_000)}`,
+        `## What the agent did\n${transcript || '(nothing recorded)'}`,
+        '## Your answer\nOne JSON object: verdict, reason, next.'
+    ].join('\n\n');
+}
+/** The verdict in the check's text, or `null` when there is none: the first JSON object that parses. */
+export function parseVerdict(text) {
+    const starts = [];
+    for (let index = text.indexOf('{'); index >= 0; index = text.indexOf('{', index + 1))
+        starts.push(index);
+    for (const start of starts) {
+        for (let end = text.indexOf('}', start); end >= 0; end = text.indexOf('}', end + 1)) {
+            try {
+                const value = JSON.parse(text.slice(start, end + 1));
+                const verdict = value.verdict;
+                if (verdict !== 'done' && verdict !== 'continue')
+                    continue;
+                return {
+                    verdict,
+                    reason: clip(typeof value.reason === 'string' ? value.reason.trim() : '', 500),
+                    next: clip(typeof value.next === 'string' ? value.next.trim() : '', 500)
+                };
+            }
+            catch {
+                // Not a complete object yet; try a longer span.
+            }
+        }
+    }
+    return null;
+}
+/**
+ * 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 async function runCompletionCheck(ask, input, options = {}) {
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    options.signal?.addEventListener('abort', abort, { once: true });
+    const timer = setTimeout(abort, options.timeoutMs ?? CHECK_TIMEOUT_MS);
+    try {
+        const user = checkPrompt(input.objective, replyTranscript(input.messages, ''));
+        const answer = await ask(CHECK_SYSTEM_PROMPT, user, controller.signal);
+        return { verdict: parseVerdict(answer.text), answer };
+    }
+    catch (error) {
+        return { verdict: null, answer: null, error: controller.signal.aborted ? 'the completion check timed out' : error instanceof Error ? error.message : String(error) };
+    }
+    finally {
+        clearTimeout(timer);
+        options.signal?.removeEventListener('abort', abort);
+    }
+}
+/** The text of a model's answer message. */
+export function answerText(message) {
+    return textOf(message?.content);
+}
+/** The model a goal-claim check asks: the session's own model, at low effort, through Pi's registry. */
+export function sessionCheckModel(ctx) {
+    const session = (ctx ?? {});
+    const model = session.model;
+    const registry = session.modelRegistry;
+    if (!model || !registry)
+        return null;
+    // Some providers (opencode-go) reject a request without a session id.
+    const sessionId = session.sessionManager?.getSessionId?.();
+    return async (system, user, signal) => {
+        const context = { systemPrompt: system, messages: [{ role: 'user', content: user, timestamp: Date.now() }] };
+        const message = await registry.streamSimple(model, context, { ...(model.reasoning ? { reasoning: 'low' } : {}), ...(sessionId ? { sessionId } : {}), maxTokens: 4_000, signal }).result();
+        const failed = message.stopReason;
+        if (failed === 'error' || failed === 'aborted')
+            throw new Error(message.errorMessage || `the check request ended: ${failed}`);
+        return { text: answerText(message), message };
+    };
+}
+/** `XINGULAR_COMPLETION_CHECK=off` at launch accepts every goal claim unchecked, for experiments. */
+export function launchSwitchOff(name) {
+    const value = process.env[name]?.trim().toLowerCase();
+    return value === 'off' || value === '0' || value === 'false';
+}

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

@@ -0,0 +1,53 @@
+import type { CapabilitySet } from "../capabilities/types.js";
+import type { HostSection } from "../prompt/compile.js";
+import type { Checkpoint } from "./contracts.js";
+import { type TodoItem } from "./contracts.js";
+import { type PendingDecision } from "./runStore.js";
+export declare const CONTINUATION_SECTION_ID = "continuation";
+/** Right after the plan section, before the variant's own sections. */
+export declare const CONTINUATION_SECTION_ORDER = 26;
+/** Why a run cannot be continued. */
+export type ContinuationBlock = 'not_found' | 'active' | 'completed' | 'no_history' | 'history_missing';
+export interface Continuation {
+    runId: string;
+    sessionId: string;
+    status: string;
+    resumable: boolean;
+    reason: ContinuationBlock | null;
+    /** The exact native history to reopen; set when it was found in the session folder. */
+    resume: {
+        sessionFile: string;
+        nativeSessionId: string;
+    } | null;
+    accountId: string | null;
+    /** The variant the run pinned; a continuation pins the same version. */
+    variant: {
+        scope: string;
+        version: string | null;
+    } | null;
+    capabilities: CapabilitySet | null;
+    stoppedAt: string | null;
+    terminalReason: string | null;
+    todo: TodoItem[];
+    /** @deprecated Use `todo`; kept for one release so hosts can migrate. */
+    checklist: TodoItem[];
+    /** The last work-slice handoff, when the run wrote one (PROP-0041). */
+    checkpoint: Checkpoint | null;
+    pending: PendingDecision[];
+    /** The last tool the run started, and whether it finished. */
+    lastTool: {
+        name: string;
+        finished: boolean;
+    } | null;
+    /** Child runs that did not finish. */
+    unfinishedSubagents: string[];
+}
+/**
+ * What a new run needs to continue `runId`. With `sessionDir` the native history is looked up in
+ * it; without, `resume` stays null and the run reads as not resumable only when it has no history.
+ */
+export declare function continuationOf(root: string, runId: string, sessionDir?: string | null): Continuation;
+/** The text that tells the model where the earlier run stopped. */
+export declare function continuationBody(continuation: Continuation): string;
+/** The dynamic section for a continuation; on a later run, the empty slot withdraws it. */
+export declare function continuationSection(continuation: Continuation | null, delivered: boolean): HostSection | null;

package/dist/sdk/sessions/continuation.js

@@ -0,0 +1,90 @@
+// Continuing a run that stopped before it finished. The harness never restarts model work on its
+// own (INV-RUN-4); it says whether a run can be continued and, when the application starts a new
+// run with `continueFrom`, tells the model where the earlier one stopped.
+import { loadRun as loadCapabilities } from "../capabilities/runSnapshot.js";
+import { todoOf, describeTodo } from "../tools/todo.js";
+import { checkpointOf, describeCheckpoint } from "./checkpoint.js";
+import { isActiveStatus } from "./contracts.js";
+import { findHistory } from "./history.js";
+import { findRun, pendingDecisions, readEvents, recordedSubagents } from "./runStore.js";
+export const CONTINUATION_SECTION_ID = 'continuation';
+/** Right after the plan section, before the variant's own sections. */
+export const CONTINUATION_SECTION_ORDER = 26;
+const CONTINUATION_BUDGET = 2000;
+/**
+ * What a new run needs to continue `runId`. With `sessionDir` the native history is looked up in
+ * it; without, `resume` stays null and the run reads as not resumable only when it has no history.
+ */
+export function continuationOf(root, runId, sessionDir) {
+    const record = findRun(root, runId);
+    if (!record) {
+        return { runId, sessionId: '', status: 'missing', resumable: false, reason: 'not_found', resume: null, accountId: null, variant: null, capabilities: null, stoppedAt: null, terminalReason: null, todo: [], checklist: [], checkpoint: null, pending: [], lastTool: null, unfinishedSubagents: [] };
+    }
+    const events = readEvents(root, runId);
+    const started = events.filter((event) => event.type === 'tool.started').at(-1);
+    const startedPayload = started?.payload;
+    const lastTool = startedPayload?.name
+        ? { name: startedPayload.name, finished: events.some((event) => event.type === 'tool.completed' && event.payload.toolCallId === startedPayload.toolCallId) }
+        : null;
+    const snapshot = loadCapabilities(root, runId);
+    const capabilities = snapshot ? { version: 1, tools: snapshot.tools, connectors: snapshot.connectors, contributions: snapshot.contributions } : null;
+    const sessionFile = sessionDir && record.nativeSessionId ? findHistory(sessionDir, record.nativeSessionId) : null;
+    const reason = isActiveStatus(record.status) ? 'active'
+        : record.status === 'completed' ? 'completed'
+            : !record.nativeSessionId ? 'no_history'
+                : sessionDir && !sessionFile ? 'history_missing'
+                    : null;
+    return {
+        runId,
+        sessionId: record.sessionId,
+        status: record.status,
+        resumable: reason === null,
+        reason,
+        resume: sessionFile && record.nativeSessionId ? { sessionFile, nativeSessionId: record.nativeSessionId } : null,
+        accountId: record.accountId,
+        variant: record.variantScope ? { scope: record.variantScope, version: record.variantVersion ?? null } : null,
+        capabilities,
+        stoppedAt: record.endedAt,
+        terminalReason: record.terminalReason,
+        checklist: todoOf(events),
+        todo: todoOf(events),
+        checkpoint: checkpointOf(events),
+        pending: pendingDecisions(events),
+        lastTool,
+        unfinishedSubagents: recordedSubagents(root, runId).filter((id) => {
+            const child = findRun(root, id);
+            return !child || child.status !== 'completed';
+        })
+    };
+}
+const describePending = (decision) => {
+    const payload = decision.payload;
+    if (decision.kind === 'approval')
+        return `- An approval for ${typeof payload.target === 'string' ? payload.target : 'a tool call'}${typeof payload.action === 'string' && payload.action ? ` (${payload.action})` : ''} was never answered.`;
+    const question = typeof payload.question === 'string' ? payload.question : Array.isArray(payload.questions) && typeof payload.questions[0]?.question === 'string' ? payload.questions[0].question : 'a question';
+    return `- A question to the user was never answered: ${question}`;
+};
+/** The text that tells the model where the earlier run stopped. */
+export function continuationBody(continuation) {
+    const lines = [
+        `The previous run (${continuation.runId}) stopped before it finished${continuation.stoppedAt ? ` at ${continuation.stoppedAt}` : ''}${continuation.terminalReason ? `: ${continuation.terminalReason}` : '.'}`,
+        'Its conversation above is intact up to that point. Check the current state before you repeat any step: work may be partly done.'
+    ];
+    if (continuation.lastTool)
+        lines.push(continuation.lastTool.finished ? `Its last tool call, ${continuation.lastTool.name}, finished.` : `Its last tool call, ${continuation.lastTool.name}, did not finish; its effect is unknown.`);
+    if (continuation.checkpoint)
+        lines.push('', 'The handoff it wrote when it stopped:', describeCheckpoint(continuation.checkpoint));
+    if (continuation.todo.length)
+        lines.push('', 'Its todo list when it stopped:', describeTodo(continuation.todo));
+    if (continuation.pending.length)
+        lines.push('', 'Unanswered when it stopped (ask again if still needed; never assume an answer):', ...continuation.pending.map(describePending));
+    if (continuation.unfinishedSubagents.length)
+        lines.push('', `Subagents that did not finish: ${continuation.unfinishedSubagents.join(', ')}. Their conversations are saved: continue one with spawn_subagent { "continue": "<run ID>" } if its work is still needed, instead of starting it again from scratch.`);
+    return lines.join('\n');
+}
+/** The dynamic section for a continuation; on a later run, the empty slot withdraws it. */
+export function continuationSection(continuation, delivered) {
+    if (continuation)
+        return { id: CONTINUATION_SECTION_ID, title: 'Continuing', body: continuationBody(continuation), budget: CONTINUATION_BUDGET, order: CONTINUATION_SECTION_ORDER, dynamic: true };
+    return delivered ? { id: CONTINUATION_SECTION_ID, title: 'Continuing', body: null, budget: CONTINUATION_BUDGET, order: CONTINUATION_SECTION_ORDER, dynamic: true } : null;
+}