@xingular/harness 2.0.0 → 2.0.1-unstable

package/dist/sdk/sessions/control.js

@@ -0,0 +1,158 @@
+// Session commands that need no model: read the branch tree, move to another branch, fork, clone,
+// name, copy the last reply, and export to JSONL. They act on the saved native history directly,
+// so a host that opens one Pi session per turn offers the same commands as the terminal.
+// Compacting, navigating with a summary and exporting to HTML need a live session: they run as a
+// session command through `sessions.run` (see `SessionCommand`).
+import { existsSync, mkdirSync, realpathSync, writeFileSync } from 'node:fs';
+import { isAbsolute, relative } from 'node:path';
+import { SessionManager } from '@earendil-works/pi-coding-agent';
+import { invalid, notFound } from "../core/errors.js";
+import { sessionFile as newestSessionFile } from "../prompt/compile.js";
+/** A move without a summary is saved as this entry, so the next turn opens on the chosen branch. */
+export const NAVIGATION_ENTRY = 'xingular-navigation';
+function within(dir, file) {
+    const path = relative(realpathSync(dir), realpathSync(file));
+    return !path.startsWith('..') && !isAbsolute(path);
+}
+function resolveFile(ref) {
+    if (!ref.sessionDir || !existsSync(ref.sessionDir))
+        throw notFound('This conversation has no saved history yet.');
+    const file = ref.sessionFile ?? newestSessionFile(ref.sessionDir);
+    if (!file || !existsSync(file))
+        throw notFound('This conversation has no saved history yet.');
+    if (!file.endsWith('.jsonl') || !within(ref.sessionDir, file))
+        throw invalid('The history must be a .jsonl file in the session folder.');
+    return realpathSync(file);
+}
+function open(ref, targetDir) {
+    const file = resolveFile(ref);
+    return { manager: SessionManager.open(file, targetDir ?? ref.sessionDir, ref.cwd ?? undefined), file };
+}
+function contentText(content) {
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return '';
+    return content.map((part) => part && typeof part === 'object' && part.type === 'text' ? String(part.text ?? '') : '').join(' ');
+}
+function entryText(entry) {
+    const record = entry;
+    if (entry.type === 'message') {
+        const message = record.message;
+        return { role: message?.role, text: contentText(message?.content) };
+    }
+    if (entry.type === 'branch_summary' || entry.type === 'compaction')
+        return { text: String(record.summary ?? '') };
+    if (entry.type === 'session_info')
+        return { text: String(record.name ?? '') };
+    if (entry.type === 'model_change')
+        return { text: `${record.provider ?? ''}/${record.modelId ?? ''}` };
+    return { text: '' };
+}
+const oneLine = (text) => text.replace(/\s+/g, ' ').trim().slice(0, 160);
+function flatten(nodes, depth, out) {
+    for (const node of nodes) {
+        const entry = node.entry;
+        const { role, text } = entryText(entry);
+        if (entry.type === 'custom' || entry.type === 'label') {
+            flatten(node.children, depth, out);
+            continue;
+        }
+        out.push({
+            id: entry.id,
+            parentId: entry.parentId ?? null,
+            type: entry.type,
+            ...(role ? { role } : {}),
+            text: oneLine(text),
+            ...(node.label ? { label: node.label } : {}),
+            timestamp: entry.timestamp,
+            depth
+        });
+        flatten(node.children, node.children.length > 1 ? depth + 1 : depth, out);
+    }
+}
+export function tree(ref) {
+    const { manager, file } = open(ref);
+    const entries = [];
+    flatten(manager.getTree(), 0, entries);
+    const forkPoints = manager.getBranch()
+        .filter((entry) => entry.type === 'message' && entryText(entry).role === 'user')
+        .map((entry) => ({ entryId: entry.id, text: oneLine(entryText(entry).text) }));
+    return { sessionFile: file, leafId: manager.getLeafId(), entries, forkPoints };
+}
+/**
+ * Moves the conversation to another entry without a summary. Choosing one of the person's
+ * messages goes to just before it and gives its text back to edit, as the terminal does.
+ */
+export function navigate(ref) {
+    const { manager } = open(ref);
+    const entry = manager.getEntry(ref.entryId);
+    if (!entry)
+        throw notFound(`No entry ${ref.entryId} in this conversation.`);
+    const { role, text } = entryText(entry);
+    const userMessage = entry.type === 'message' && role === 'user';
+    const target = userMessage ? entry.parentId ?? null : entry.id;
+    if (target)
+        manager.branch(target);
+    else
+        manager.resetLeaf();
+    manager.appendCustomEntry(NAVIGATION_ENTRY, { to: target });
+    return { leafId: target, ...(userMessage ? { editorText: text } : {}) };
+}
+/** A new history in `targetDir` that ends just before one of the person's messages. */
+export function fork(ref) {
+    const { manager } = open(ref, ensureDir(ref.targetDir));
+    const entry = manager.getEntry(ref.entryId);
+    const { role, text } = entry ? entryText(entry) : { text: '' };
+    if (!entry || entry.type !== 'message' || role !== 'user')
+        throw invalid('Fork from one of your messages.');
+    const sessionFile = entry.parentId
+        ? manager.createBranchedSession(entry.parentId)
+        : SessionManager.create(manager.getCwd(), ref.targetDir).getSessionFile();
+    if (!sessionFile)
+        throw invalid('The fork could not be saved.');
+    return { sessionFile, editorText: text };
+}
+/** A new history in `targetDir` with the whole current branch. */
+export function clone(ref) {
+    const { manager } = open(ref, ensureDir(ref.targetDir));
+    const leaf = manager.getLeafId();
+    if (!leaf)
+        throw invalid('Nothing to clone yet.');
+    const sessionFile = manager.createBranchedSession(leaf);
+    if (!sessionFile)
+        throw invalid('The clone could not be saved.');
+    return { sessionFile };
+}
+export function rename(ref) {
+    const name = ref.name.trim();
+    if (!name)
+        throw invalid('A session name cannot be empty.');
+    open(ref).manager.appendSessionInfo(name);
+    return { name };
+}
+/** The text of the last reply on the current branch, or null before the first. */
+export function lastReply(ref) {
+    const branch = open(ref).manager.getBranch();
+    for (let index = branch.length - 1; index >= 0; index -= 1) {
+        const { role, text } = entryText(branch[index]);
+        if (branch[index].type === 'message' && role === 'assistant' && text.trim())
+            return { text: text.trim() };
+    }
+    return { text: null };
+}
+/** Writes the current branch as JSONL. HTML needs a live session: see `SessionCommand`. */
+export function exportJsonl(ref) {
+    if (!isAbsolute(ref.path) || !ref.path.endsWith('.jsonl'))
+        throw invalid('Export to an absolute .jsonl path.');
+    const { manager } = open(ref);
+    const lines = [manager.getHeader(), ...manager.getBranch()].filter(Boolean).map((entry) => JSON.stringify(entry));
+    writeFileSync(ref.path, `${lines.join('\n')}\n`, 'utf8');
+    return { path: ref.path };
+}
+function ensureDir(dir) {
+    if (!isAbsolute(dir))
+        throw invalid('The new history folder must be an absolute path.');
+    mkdirSync(dir, { recursive: true });
+    return dir;
+}

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

@@ -0,0 +1,19 @@
+import type { ExtensionUIContext } from '@earendil-works/pi-coding-agent';
+import type { QuestionAnswer, QuestionInput } from "./registry.js";
+/** A status line, a notification, or an error from an extension. */
+export interface ExtensionNotice {
+    kind: 'notify' | 'status' | 'widget' | 'title' | 'error';
+    /** `notify` only. */
+    level?: 'info' | 'warning' | 'error';
+    /** The extension's own name for a status entry or a widget, so a later one replaces it. */
+    key?: string;
+    /** The text. Empty clears a status entry or a widget. */
+    text: string;
+    /** The file of the extension, for an error. */
+    extension?: string;
+}
+export interface ExtensionHost {
+    ask(input: QuestionInput): Promise<QuestionAnswer>;
+    notice(notice: ExtensionNotice): void;
+}
+export declare function extensionUi(host: ExtensionHost): ExtensionUIContext;

package/dist/sdk/sessions/extensionUi.js

@@ -0,0 +1,64 @@
+const MAX_TEXT = 4_000;
+const clip = (text) => (text.length > MAX_TEXT ? `${text.slice(0, MAX_TEXT)}…` : text);
+/** A dialog that Pi can dismiss on its own: by a signal, or after a time. */
+function dismissable(answer, fallback, options) {
+    if (!options?.signal && !options?.timeout)
+        return answer;
+    return new Promise((resolve) => {
+        let timer;
+        const done = (value) => {
+            if (timer)
+                clearTimeout(timer);
+            resolve(value);
+        };
+        if (options.signal?.aborted)
+            return done(fallback);
+        options.signal?.addEventListener('abort', () => done(fallback), { once: true });
+        if (options.timeout)
+            timer = setTimeout(() => done(fallback), options.timeout);
+        void answer.then(done, () => done(fallback));
+    });
+}
+// Text styling has no meaning without a terminal: every style returns the text it was given.
+const plainTheme = new Proxy({}, { get: () => (...args) => String(args[args.length - 1] ?? '') });
+export function extensionUi(host) {
+    const context = {
+        select: (title, options, opts) => dismissable(options.length
+            ? host.ask({ question: clip(title), options: options.map((label, index) => ({ label, ...(index === 0 ? { recommended: true } : {}) })), multiSelect: false, allowText: false, dialog: { kind: 'select', title: clip(title), options: options.map(clip) } }).then((answer) => answer.selected[0])
+            : Promise.resolve(undefined), undefined, opts),
+        confirm: (title, message, opts) => dismissable(host.ask({ question: clip(message ? `${title}\n\n${message}` : title), options: [{ label: 'Yes' }, { label: 'No', recommended: true }], multiSelect: false, allowText: false, dialog: { kind: 'confirm', title: clip(title), ...(message ? { message: clip(message) } : {}) } }).then((answer) => answer.selected[0] === 'Yes'), false, opts),
+        input: (title, placeholder, opts) => dismissable(host.ask({ question: clip(placeholder ? `${title} (${placeholder})` : title), options: [{ label: 'Type your response', recommended: true }], multiSelect: false, allowText: true, dialog: { kind: 'input', title: clip(title), ...(placeholder ? { placeholder: clip(placeholder) } : {}) } }).then((answer) => answer.text || undefined), undefined, opts),
+        editor: (title, prefill) => host.ask({ question: clip(prefill ? `${title}\n\n${prefill}` : title), options: [{ label: 'Type your response', recommended: true }], multiSelect: false, allowText: true, dialog: { kind: 'editor', title: clip(title), ...(prefill ? { prefill: prefill.slice(0, 100_000) } : {}) } }).then((answer) => answer.text || undefined),
+        notify: (message, level) => host.notice({ kind: 'notify', level: level ?? 'info', text: clip(message) }),
+        setStatus: (key, text) => host.notice({ kind: 'status', key, text: clip(text ?? '') }),
+        setWidget: (key, content) => {
+            // Only lines of text can be shown; a component needs a terminal.
+            if (content === undefined || Array.isArray(content))
+                host.notice({ kind: 'widget', key, text: clip((content ?? []).join('\n')) });
+        },
+        setTitle: (title) => host.notice({ kind: 'title', text: clip(title) }),
+        onTerminalInput: () => () => { },
+        setWorkingMessage: () => { },
+        setWorkingVisible: () => { },
+        setWorkingIndicator: () => { },
+        setHiddenThinkingLabel: () => { },
+        setFooter: () => { },
+        setHeader: () => { },
+        custom: async () => undefined,
+        pasteToEditor: () => { },
+        setEditorText: () => { },
+        getEditorText: () => '',
+        addAutocompleteProvider: () => { },
+        setEditorComponent: () => { },
+        getEditorComponent: () => undefined,
+        get theme() {
+            return plainTheme;
+        },
+        getAllThemes: () => [],
+        getTheme: () => undefined,
+        setTheme: () => ({ success: false, error: 'There is no terminal to theme in this session.' }),
+        getToolsExpanded: () => false,
+        setToolsExpanded: () => { }
+    };
+    return context;
+}

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

@@ -0,0 +1,145 @@
+import type { ToolSpec } from "../tools/types.js";
+export declare const GET_GOAL = "get_goal";
+export declare const UPDATE_GOAL = "update_goal";
+export declare const GOAL_TOOLS: readonly ["get_goal", "update_goal"];
+export declare const GOAL_CUSTOM_TYPE = "xingular-goal";
+export declare const GOAL_STATE_ENTRY = "xingular-goal-state";
+/** Codex limits a goal objective to this many characters. */
+export declare const MAX_GOAL_OBJECTIVE = 4000;
+export declare const DEFAULT_GOAL_ROUNDS = 30;
+export declare const DEFAULT_GOAL_HOURS = 8;
+/** Consecutive automatic rounds without activity, or with only failed commands, before a goal is blocked. */
+export declare const GOAL_STRIKES = 3;
+export type GoalStatus = 'active' | 'paused' | 'blocked' | 'usage_limited' | 'budget_limited' | 'complete';
+export interface GoalLimits {
+    rounds: number;
+    hours: number;
+}
+export interface GoalState {
+    /** Changes when a goal is replaced, kept when its objective is edited. */
+    goalId: string;
+    objective: string;
+    status: GoalStatus;
+    limits: GoalLimits;
+    /** Automatic continuations started so far. */
+    rounds: number;
+    timeUsedSeconds: number;
+    createdAt: number;
+    updatedAt: number;
+    /** The model called update_goal(complete) and the harness has not checked the claim yet. */
+    claimed: boolean;
+    /** The latest verdict on a completion claim, while it matters. */
+    lastReason: string;
+}
+/** Thrown for a call the model may not make; the message goes back to the model as the tool result. */
+export declare class GoalError extends Error {
+}
+export declare const withLimits: (limits?: Partial<GoalLimits>) => GoalLimits;
+/** `59s`, `1m`, `1h 30m`, `2d 23h 42m`: Codex's elapsed-time format. */
+export declare function formatElapsed(seconds: number): string;
+export declare const continuationPrompt: (goal: GoalState) => string;
+export declare const budgetLimitPrompt: (goal: GoalState) => string;
+export declare const objectiveUpdatedPrompt: (goal: GoalState) => string;
+/** The goal as the model's tools report it. */
+export declare function goalReport(goal: GoalState | null): Record<string, unknown>;
+/** The text a goal-aware session shows after it ends in `complete`. */
+export declare const completionReport: (goal: GoalState) => string;
+/** What one finished round did, as the loop saw it. */
+export interface RoundOutcome {
+    /** The round produced text, reasoning, or a tool call. */
+    activity: boolean;
+    /** A command failed and no tool succeeded in the round. */
+    failedCommands: boolean;
+    /** The round ended with a provider error (not a usage limit). */
+    error?: boolean;
+    /** The round ended with a usage-limit error. */
+    usageLimit?: boolean;
+}
+export interface GoalControllerOptions {
+    now?: () => number;
+    /** Called after every change with the new state (null once cleared), to persist and show it. */
+    onChange?: (state: GoalState | null) => void;
+}
+/**
+ * One session's goal. All changes go through it, so the status rules live in one place:
+ * the model may only claim `complete`, report `blocked` or, on the person's word, `paused`;
+ * the person sets, edits, pauses, resumes and clears; the system alone limits.
+ */
+export declare class GoalController {
+    private readonly options;
+    private state;
+    private idleStrikes;
+    private failureStrikes;
+    private startedAt;
+    private readonly now;
+    private readonly listeners;
+    constructor(options?: GoalControllerOptions);
+    get(): GoalState | null;
+    active(): boolean;
+    /** Restores a persisted goal; the in-memory strike counters start fresh. */
+    restore(state: GoalState | null): void;
+    /** Hears every change (a persisted copy, the footer, the model's tools). Returns the way to stop. */
+    subscribe(listener: (state: GoalState | null) => void): () => void;
+    private changed;
+    private touch;
+    /** The person sets a goal. Replaces a finished one; the caller confirms replacing an unfinished one. */
+    set(objective: string, limits?: Partial<GoalLimits>): GoalState;
+    /** The person edits the objective: the same goal, its usage kept. A finished goal becomes active again. */
+    edit(objective: string): GoalState;
+    pause(): GoalState | null;
+    resume(): GoalState;
+    clear(): boolean;
+    /** A round (a turn charged to the goal) begins. */
+    beginRound(): void;
+    /** Charges the round's wall time to the goal. Called at every stop, so an idle gap is not billed. */
+    endRound(): void;
+    /** The model's `update_goal`. Returns the tool result. */
+    update(status: string): {
+        text: string;
+        goal: GoalState;
+    };
+    /** The claim was checked and holds. */
+    accept(reason?: string): GoalState;
+    /** The claim was checked and does not hold: the goal stays active with the reason. */
+    reject(reason: string): GoalState;
+    /** The system limits the goal. */
+    limit(status: 'budget_limited' | 'usage_limited' | 'blocked', reason?: string): GoalState;
+    /** Counts one automatic round; returns the status the system moved the goal to, if any. */
+    settleRound(outcome: RoundOutcome): GoalStatus | null;
+    /** True once the goal has used its rounds or hours. */
+    overLimit(): boolean;
+    /** Starts the next automatic round. */
+    nextRound(): GoalState;
+}
+export declare function goalTools(goal: () => GoalController | null): ToolSpec[];
+export type GoalCommand = {
+    kind: 'show';
+} | {
+    kind: 'set';
+    objective: string;
+    limits: Partial<GoalLimits>;
+} | {
+    kind: 'edit';
+    objective: string | null;
+} | {
+    kind: 'pause';
+} | {
+    kind: 'resume';
+} | {
+    kind: 'clear';
+} | {
+    kind: 'error';
+    message: string;
+};
+export declare const GOAL_USAGE = "Usage: /goal [<objective>|edit|pause|resume|clear]";
+/**
+ * Parses the argument of `/goal`. Subcommands match only as the whole text, so "pause now" is
+ * an objective. `--rounds N` and `--hours H` before the objective set this goal's caps.
+ */
+export declare function parseGoalCommand(argument: string): GoalCommand;
+/** The text of a bare `/goal`. */
+export declare function goalSummary(goal: GoalState | null): string;
+/** The footer label (Codex's wording, with rounds in place of tokens). */
+export declare function goalFooter(goal: GoalState | null): string | null;
+/** The hidden message that records who changed the goal, so a pause can be checked as the person's. */
+export declare function provenanceText(action: 'set' | 'paused' | 'cleared' | 'resumed' | 'edited', goal: GoalState | null): string;