@xingular/harness 1.6.0-unstable → 2.0.1-unstable

package/dist/sdk/sessions/live.js

@@ -0,0 +1,265 @@
+// Live sessions (ADR-0083): a Pi session the harness keeps open between the runs of one
+// conversation, so a later run reuses it instead of opening and loading a new one. A live session
+// serves only a run whose pins equal the ones it was opened with (INV-RUN-1); anything else closes it
+// at the turn boundary, and the next run opens a fresh session on the same native history.
+import { createHash } from 'node:crypto';
+import { realpathSync } from 'node:fs';
+import { HarnessError } from "../core/errors.js";
+/** How long an idle live session stays open, unless the caller sets another time. */
+export const LIVE_IDLE_MS = 30 * 60_000;
+/** Follow-up messages one live session may hold. */
+export const MAX_FOLLOW_UPS = 20;
+const MAX_FOLLOW_UP_CHARS = 100_000;
+/** The run fields a live session must share with a run before it may serve it. */
+export function livePin(fields) {
+    return createHash('sha256').update(JSON.stringify(fields)).digest('hex');
+}
+function samePath(a, b) {
+    if (a === b)
+        return true;
+    try {
+        return realpathSync(a) === realpathSync(b);
+    }
+    catch {
+        return false;
+    }
+}
+const now = () => new Date().toISOString();
+export class LiveSessions {
+    options;
+    entries = new Map();
+    /** Watchers of each session's native Pi events; they outlive a session replaced at a pin change. */
+    watchers = new Map();
+    unsubscribers = new Map();
+    /** Follow-ups of a session closed at a pin change, handed to the session that replaces it. */
+    parked = new Map();
+    idleMs;
+    constructor(options) {
+        this.options = options;
+        this.idleMs = options.idleMs ?? LIVE_IDLE_MS;
+    }
+    /** Whether a run of this session is using its live session now. */
+    busy(sessionId) {
+        return Boolean(this.entries.get(sessionId)?.activeRunId);
+    }
+    /**
+     * The live session for this run, now marked in use, or null when there is none to reuse. An idle
+     * session whose pins, history or native id differ is closed here, at the turn boundary.
+     */
+    claim(sessionId, pin, runId, historyFile, nativeSessionId) {
+        const entry = this.entries.get(sessionId);
+        if (!entry)
+            return null;
+        if (entry.activeRunId)
+            throw new HarnessError('session_busy', 'This session is already replying. Steer it with runs.steer, or queue the message with sessions.followUp.');
+        const historyMatches = !historyFile || !entry.pi.sessionFile || samePath(historyFile, entry.pi.sessionFile);
+        const nativeMatches = !nativeSessionId || nativeSessionId === entry.pi.sessionId;
+        if (entry.pin !== pin || !historyMatches || !nativeMatches || !entry.pi.rebind) {
+            if (entry.followUps.length)
+                this.parked.set(sessionId, entry.followUps.splice(0));
+            this.dispose(entry);
+            return null;
+        }
+        this.stopTimer(entry);
+        entry.activeRunId = runId;
+        entry.idleSince = null;
+        return entry.pi;
+    }
+    /** Records the session a run just opened, so the next run of the conversation can reuse it. */
+    hold(sessionId, pin, pi, runId, sessionDir) {
+        const previous = this.entries.get(sessionId);
+        if (previous && previous.pi !== pi)
+            this.dispose(previous);
+        this.entries.set(sessionId, {
+            sessionId, sessionDir, pin, pi, activeRunId: runId, lastRunId: runId, runs: 0, openedAt: now(), idleSince: null,
+            followUps: previous?.followUps ?? this.parked.get(sessionId) ?? [], closeWhenIdle: false, timer: null
+        });
+        this.parked.delete(sessionId);
+        const entry = this.entries.get(sessionId);
+        // Every native event of the session reaches its watchers, whichever run is current.
+        this.unsubscribers.set(entry, pi.subscribe((event) => {
+            for (const watcher of this.watchers.get(sessionId) ?? []) {
+                try {
+                    watcher(event);
+                }
+                catch (error) {
+                    this.options.log?.(`a live session watcher failed: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+        }));
+    }
+    /** The run has started on the session: count it. */
+    started(sessionId, runId) {
+        const entry = this.entries.get(sessionId);
+        if (!entry || entry.activeRunId !== runId)
+            return;
+        entry.runs += 1;
+        entry.lastRunId = runId;
+    }
+    /**
+     * The run settled. The session stays open for the next run. A queued follow-up is sent after a
+     * reply that completed or that the person stopped; after a failure, or an interruption the person
+     * did not ask for, it stays parked (page 02, queued-message dispatch). `close` ends the session
+     * instead of keeping it, with its queue parked.
+     */
+    release(sessionId, runId, close = false) {
+        const entry = this.entries.get(sessionId);
+        if (!entry || entry.activeRunId !== runId)
+            return;
+        entry.activeRunId = null;
+        entry.idleSince = now();
+        if (close) {
+            // A session the run could not trust (a stalled turn) is not reused; its queue waits for the next session.
+            if (entry.followUps.length)
+                this.parked.set(sessionId, entry.followUps.splice(0));
+            this.dispose(entry);
+            return;
+        }
+        if (entry.closeWhenIdle) {
+            this.dispose(entry);
+            return;
+        }
+        this.startTimer(entry);
+        if (!entry.followUps.length)
+            return;
+        const record = this.options.record(runId);
+        // A work-slice continuation is the next run already; the queue waits for it.
+        const dispatch = record && record.terminalReason !== 'slice_complete'
+            && (record.status === 'completed' || (record.status === 'interrupted' && record.terminalCode === 'user_abort'));
+        if (!dispatch)
+            return;
+        const text = entry.followUps.shift();
+        void this.options.followUp(sessionId, runId, text).catch((error) => {
+            // The message is not lost: it goes back to the front of the queue.
+            entry.followUps.unshift(text);
+            this.options.log?.(`a follow-up did not start: ${error instanceof Error ? error.message : String(error)}`);
+        });
+    }
+    /**
+     * Something other than the live session is about to change this history: a separate command
+     * run or a saved-history edit. An idle live session closes, so its next run reads the file again;
+     * one that is replying refuses the change.
+     */
+    yieldHistory(match) {
+        for (const entry of [...this.entries.values()]) {
+            const hit = (match.sessionId !== undefined && entry.sessionId === match.sessionId)
+                || (match.sessionDir !== undefined && samePath(entry.sessionDir, match.sessionDir));
+            if (!hit)
+                continue;
+            if (entry.activeRunId)
+                throw new HarnessError('session_busy', 'This conversation is replying in a live session. Wait for it to settle, or interrupt it, before changing its history.');
+            this.dispose(entry);
+        }
+    }
+    /** The session could not serve the run after all: forget it and close it. */
+    discard(sessionId, pi) {
+        const entry = this.entries.get(sessionId);
+        if (entry?.pi === pi)
+            this.dispose(entry);
+        else
+            pi.dispose();
+    }
+    /**
+     * Queues a message for after the active run, or reports that the session is idle so the caller
+     * starts it now.
+     */
+    queue(sessionId, text) {
+        const entry = this.entries.get(sessionId);
+        if (!entry)
+            throw new HarnessError('not_found', 'This session has no live session. Start a run with live: true first.');
+        if (!text.trim() || text.length > MAX_FOLLOW_UP_CHARS)
+            throw new HarnessError('invalid_request', `A follow-up needs text of at most ${MAX_FOLLOW_UP_CHARS} characters.`);
+        if (!entry.activeRunId)
+            return { idle: true, lastRunId: entry.lastRunId };
+        if (entry.followUps.length >= MAX_FOLLOW_UPS)
+            throw new HarnessError('invalid_request', `A session holds at most ${MAX_FOLLOW_UPS} follow-up messages.`);
+        entry.followUps.push(text);
+        return { queued: entry.followUps.length };
+    }
+    /** Drops the queued follow-ups and returns them, oldest first. */
+    clearQueue(sessionId) {
+        const entry = this.entries.get(sessionId);
+        return entry ? entry.followUps.splice(0) : [];
+    }
+    /**
+     * Receives the native Pi events of this conversation's live session, and of the one that replaces
+     * it, until the returned function is called (ADR-0083: a client renders from them).
+     */
+    watch(sessionId, watcher) {
+        const set = this.watchers.get(sessionId) ?? new Set();
+        set.add(watcher);
+        this.watchers.set(sessionId, set);
+        return () => {
+            set.delete(watcher);
+            if (!set.size && this.watchers.get(sessionId) === set)
+                this.watchers.delete(sessionId);
+        };
+    }
+    /** The open Pi session of a conversation, for a read of its current state. */
+    session(sessionId) {
+        return this.entries.get(sessionId)?.pi ?? null;
+    }
+    status(sessionId) {
+        const entry = this.entries.get(sessionId);
+        return entry ? this.statusOf(entry) : null;
+    }
+    list() {
+        return [...this.entries.values()].map((entry) => this.statusOf(entry));
+    }
+    /** Closes a live session now, or when its active run settles. */
+    close(sessionId) {
+        const entry = this.entries.get(sessionId);
+        if (!entry)
+            return { closed: false, afterRun: null };
+        if (entry.activeRunId) {
+            entry.closeWhenIdle = true;
+            return { closed: true, afterRun: entry.activeRunId };
+        }
+        this.dispose(entry);
+        return { closed: true, afterRun: null };
+    }
+    closeAll() {
+        this.parked.clear();
+        for (const entry of [...this.entries.values()])
+            this.dispose(entry);
+    }
+    statusOf(entry) {
+        return {
+            sessionId: entry.sessionId,
+            nativeSessionId: entry.pi.sessionId,
+            sessionFile: entry.pi.sessionFile ?? null,
+            activeRunId: entry.activeRunId,
+            lastRunId: entry.lastRunId,
+            runs: entry.runs,
+            openedAt: entry.openedAt,
+            idleSince: entry.idleSince,
+            followUps: [...entry.followUps]
+        };
+    }
+    startTimer(entry) {
+        this.stopTimer(entry);
+        entry.timer = setTimeout(() => {
+            if (!entry.activeRunId && this.entries.get(entry.sessionId) === entry)
+                this.dispose(entry);
+        }, this.idleMs);
+        entry.timer.unref?.();
+    }
+    stopTimer(entry) {
+        if (entry.timer)
+            clearTimeout(entry.timer);
+        entry.timer = null;
+    }
+    dispose(entry) {
+        this.stopTimer(entry);
+        this.unsubscribers.get(entry)?.();
+        this.unsubscribers.delete(entry);
+        if (this.entries.get(entry.sessionId) === entry)
+            this.entries.delete(entry.sessionId);
+        try {
+            entry.pi.dispose();
+        }
+        catch (error) {
+            this.options.log?.(`a live session did not close cleanly: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+}

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

@@ -17,9 +17,19 @@ export interface ApprovalInput {
     /** How long to wait for a decision before the request counts as denied. */
     timeoutMs?: number;
 }
+/** The Pi extension dialog a question stands for, so a terminal can show the dialog itself (ADR-0083). */
+export interface QuestionDialog {
+    kind: 'select' | 'confirm' | 'input' | 'editor';
+    title: string;
+    message?: string;
+    placeholder?: string;
+    prefill?: string;
+    options?: string[];
+}
 export interface QuestionInput {
     requestId?: string;
     userOnly?: boolean;
+    dialog?: QuestionDialog;
     summary?: string;
     question: string;
     uiSketch?: true;
@@ -55,6 +65,8 @@ export interface ActiveRun {
         message: string;
     }, reason?: string, code?: RunStopCode): void;
     readonly finished: boolean;
+    /** Whether the run is waiting for a person's approval or answer, which no stall guard may cut short. */
+    readonly waiting?: boolean;
 }
 /** Called with every persisted event, and the run's record as it is after that event. */
 export type RunListener = (event: RunEvent, run: RunRecord | null) => void;

package/dist/sdk/sessions/registry.js

@@ -211,6 +211,9 @@ export class RunRegistry {
             get finished() {
                 return finished;
             },
+            get waiting() {
+                return waitingStatus() !== 'running';
+            },
             interrupt: async (stop) => {
                 // Release approvals/questions before SDK abort waits for their blocked tools.
                 run.finish('interrupted', undefined, stop?.reason, stop?.code ?? 'user_abort');

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

@@ -18,6 +18,12 @@ export interface TurnParams {
     /** 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;
@@ -26,8 +32,10 @@ export interface TurnParams {
     /** 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 start a fresh one. */
+    /** 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;
@@ -78,6 +86,11 @@ export interface TurnParams {
     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. */
@@ -230,6 +243,14 @@ export interface PiSessionLike {
         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. */
@@ -242,7 +263,7 @@ export interface ToolGate {
     /** 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: {
+export interface SessionFactoryInput {
     params: TurnParams;
     /** Pi's own tools and the custom tools switched on for this turn, in order. */
     allow: string[];
@@ -252,7 +273,8 @@ export type SessionFactory = (input: {
     runtime: () => Promise<ModelRuntime>;
     /** Where a loaded extension's dialogs and notices go. Without it extensions have no interface. */
     extensions?: ExtensionHost;
-}) => Promise<PiSessionLike>;
+}
+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. */