@xingular/harness 0.1.6 → 1.0.0

package/dist/sdk/sessions/registry.js

@@ -0,0 +1,383 @@
+// Live runs. Assigns per-run sequence numbers, validates every event against the contract,
+// persists it, hands it to listeners, and tracks interrupt, approval, and question handlers.
+import { randomUUID } from 'node:crypto';
+import { log } from "../core/bus.js";
+import { HarnessError } from "../core/errors.js";
+import { isActiveStatus, runEventSchema } from "./contracts.js";
+import { findRun, persistEvent, readEvents, runFamily } from "./runStore.js";
+function validateQuestionRecommendations(input) {
+    if (!Array.isArray(input.options) || input.options.length === 0) {
+        throw new HarnessError('invalid_request', 'Every question needs at least one choice.');
+    }
+    const recommendations = input.options.filter((option) => option.recommended).length;
+    if (recommendations === 0) {
+        throw new HarnessError('invalid_request', 'Every question needs at least one recommended choice.');
+    }
+    if (!input.multiSelect && recommendations > 1) {
+        throw new HarnessError('invalid_request', 'A single-choice question can recommend at most one option.');
+    }
+}
+export class RunRegistry {
+    options;
+    runs = new Map();
+    approvals = new Map();
+    questions = new Map();
+    nativeCleared = new Map();
+    waiters = new Map();
+    stopping = new Set();
+    listeners = [];
+    constructor(options) {
+        this.options = options;
+    }
+    /** Observers see events after they are persisted, in order. */
+    listen(listener) {
+        this.listeners.push(listener);
+        return () => {
+            const at = this.listeners.indexOf(listener);
+            if (at >= 0)
+                this.listeners.splice(at, 1);
+        };
+    }
+    deliver(event) {
+        const root = this.options.root();
+        try {
+            this.options.redact?.(event);
+            if (!persistEvent(root, event))
+                return false;
+        }
+        catch (error) {
+            log(`could not persist event for ${event.runId}: ${error instanceof Error ? error.message : String(error)}`);
+            return false;
+        }
+        const run = findRun(root, event.runId);
+        for (const listener of this.listeners) {
+            try {
+                listener(event, run);
+            }
+            catch (error) {
+                log('a run listener failed', error instanceof Error ? error.message : String(error));
+            }
+        }
+        return true;
+    }
+    /** Starts tracking a run whose record is already saved. */
+    start(sessionId, runId = randomUUID()) {
+        let sequence = 0;
+        try {
+            sequence = readEvents(this.options.root(), runId).reduce((highest, event) => Math.max(highest, event.sequence + 1), 0);
+        }
+        catch {
+            sequence = 0;
+        }
+        let finished = false;
+        let finishing = false;
+        const interruptHandlers = [];
+        let steerHandler = null;
+        const waitingStatus = () => [...this.approvals.values()].some((request) => request.runId === runId) ? 'waiting_for_approval' : [...this.questions.values()].some((request) => request.runId === runId) ? 'waiting_for_input' : 'running';
+        const requestQuestion = (input, batch, statusEvent = true) => {
+            const { requestId, ...payload } = input;
+            const questionId = requestId ?? randomUUID();
+            if (finished || finishing || this.nativeCleared.delete(questionId))
+                return Promise.resolve({ selected: [] });
+            validateQuestionRecommendations(input);
+            if (this.questions.has(questionId))
+                throw new HarnessError('invalid_request', 'This question id is already pending.');
+            return new Promise((resolve) => {
+                this.questions.set(questionId, {
+                    runId,
+                    input,
+                    ...(batch ? { batch } : {}),
+                    resolve: (answer) => {
+                        this.questions.delete(questionId);
+                        emit('question.answered', { questionId, ...answer, ...(batch ?? {}) });
+                        emit('status.changed', { status: waitingStatus() });
+                        resolve(answer);
+                    }
+                });
+                emit('question.requested', { questionId, ...payload, ...(batch ?? {}) });
+                if (statusEvent)
+                    emit('status.changed', { status: 'waiting_for_input' });
+            });
+        };
+        const emit = (type, payload, native) => {
+            if (finished)
+                return;
+            const parsed = runEventSchema.safeParse({ id: randomUUID(), runId, sessionId, sequence, timestamp: new Date().toISOString(), type, payload, ...(native === undefined ? {} : { native }) });
+            if (!parsed.success) {
+                log(`dropped invalid ${type} event for run ${runId}`);
+                return;
+            }
+            sequence += 1;
+            this.deliver(parsed.data);
+        };
+        const run = {
+            runId,
+            sessionId,
+            emit,
+            onInterrupt: (handler) => void interruptHandlers.push(handler),
+            onSteer: (handler) => {
+                steerHandler = handler;
+            },
+            steer: async (text) => {
+                if (finished || !steerHandler)
+                    throw new HarnessError('run_not_active', 'This run is not accepting messages.');
+                await steerHandler(text);
+            },
+            requestApproval: async (input) => {
+                const { requestId, standing = 'full', timeoutMs, ...payload } = input;
+                const approvalId = requestId ?? randomUUID();
+                // What the user already allowed is known here; if it cannot be read, ask as usual.
+                const record = findRun(this.options.root(), runId);
+                const automatic = record && this.options.automatic && standing !== 'none' ? await this.options.automatic(record, input.target, input.operation, standing).catch(() => null) : null;
+                if (finished || finishing)
+                    return 'denied';
+                if (this.nativeCleared.delete(approvalId))
+                    return 'native';
+                if (automatic) {
+                    // Marked on the request too, so nothing treats it as waiting on someone.
+                    emit('approval.requested', { approvalId, ...payload, automatic });
+                    emit('approval.resolved', { approvalId, decision: 'approved', automatic });
+                    return 'approved';
+                }
+                emit('approval.requested', { approvalId, ...payload });
+                emit('status.changed', { status: 'waiting_for_approval' });
+                return new Promise((resolve) => {
+                    const timer = timeoutMs ? setTimeout(() => this.approvals.get(approvalId)?.resolve('denied'), timeoutMs) : null;
+                    this.approvals.set(approvalId, {
+                        runId,
+                        resolve: (decision) => {
+                            if (timer)
+                                clearTimeout(timer);
+                            this.approvals.delete(approvalId);
+                            emit('approval.resolved', { approvalId, decision });
+                            emit('status.changed', { status: waitingStatus() });
+                            resolve(decision);
+                        }
+                    });
+                });
+            },
+            requestAnswer: (input) => requestQuestion(input),
+            requestAnswers: (inputs) => {
+                if (!Array.isArray(inputs) || inputs.length < 1 || inputs.length > 5) {
+                    throw new HarnessError('invalid_request', 'A question batch must contain between one and five questions.');
+                }
+                inputs.forEach(validateQuestionRecommendations);
+                const requestedIds = inputs.flatMap((input) => input.requestId ? [input.requestId] : []);
+                if (new Set(requestedIds).size !== requestedIds.length || requestedIds.some((id) => this.questions.has(id))) {
+                    throw new HarnessError('invalid_request', 'Question ids in a batch must be unique and not already pending.');
+                }
+                if (finished || finishing)
+                    return Promise.resolve(inputs.map(() => ({ selected: [] })));
+                const batchId = randomUUID();
+                const answers = inputs.map((input, index) => requestQuestion(input, { batchId, batchIndex: index + 1, batchCount: inputs.length }, false));
+                emit('status.changed', { status: 'waiting_for_input' });
+                return Promise.all(answers);
+            },
+            finish: (outcome, failure) => {
+                if (finished || finishing)
+                    return;
+                finishing = true;
+                // Persist cancellation receipts while emit is still open, so every interface clears them.
+                for (const [, approval] of [...this.approvals])
+                    if (approval.runId === runId)
+                        approval.resolve('denied');
+                for (const [, question] of [...this.questions])
+                    if (question.runId === runId)
+                        question.resolve({ selected: [] });
+                if (outcome === 'failed')
+                    emit('failed', failure ?? { code: 'failed', message: 'The run failed.' });
+                else if (outcome === 'interrupted')
+                    emit('status.changed', { status: 'interrupted' });
+                else
+                    emit('completed', {});
+                finished = true;
+                this.runs.delete(runId);
+                for (const resolve of [...(this.waiters.get(runId) ?? [])])
+                    resolve();
+                this.waiters.delete(runId);
+                for (const [id, owner] of this.nativeCleared)
+                    if (owner === runId)
+                        this.nativeCleared.delete(id);
+                try {
+                    this.options.ended?.(runId, sessionId);
+                }
+                catch (error) {
+                    log('a run could not be closed cleanly', error instanceof Error ? error.message : String(error));
+                }
+            },
+            get finished() {
+                return finished;
+            },
+            interrupt: async () => {
+                // Release approvals/questions before SDK abort waits for their blocked tools.
+                run.finish('interrupted');
+                for (const handler of interruptHandlers) {
+                    try {
+                        await handler();
+                    }
+                    catch (error) {
+                        log(`an interrupt handler failed for run ${runId}`, error instanceof Error ? error.message : String(error));
+                    }
+                }
+            }
+        };
+        this.runs.set(runId, run);
+        emit('started', {});
+        emit('status.changed', { status: 'running' });
+        const record = findRun(this.options.root(), runId);
+        if (record?.parentRunId && this.hasStoppedAncestor(record.parentRunId))
+            run.finish('interrupted');
+        return run;
+    }
+    hasStoppedAncestor(runId) {
+        const visited = new Set();
+        let currentId = runId;
+        while (currentId && !visited.has(currentId)) {
+            if (this.stopping.has(currentId))
+                return true;
+            visited.add(currentId);
+            const record = findRun(this.options.root(), currentId);
+            if (!record)
+                return false;
+            if (!isActiveStatus(record.status))
+                return true;
+            currentId = record.parentRunId;
+        }
+        return false;
+    }
+    /** Wait for a recorded run to settle without polling storage or retaining an event listener. */
+    wait(runId, signal) {
+        const record = findRun(this.options.root(), runId);
+        if (!record)
+            throw new HarnessError('not_found', 'Run was not found.');
+        if (!isActiveStatus(record.status))
+            return Promise.resolve();
+        if (!this.runs.has(runId))
+            throw new HarnessError('run_not_active', 'This run is not active in this process.');
+        if (signal?.aborted)
+            return Promise.reject(new HarnessError('run_not_active', 'The wait was interrupted.'));
+        return new Promise((resolve, reject) => {
+            const cleanup = () => {
+                signal?.removeEventListener('abort', abort);
+                const pending = this.waiters.get(runId);
+                const index = pending?.indexOf(done) ?? -1;
+                if (index >= 0)
+                    pending.splice(index, 1);
+                if (!pending?.length)
+                    this.waiters.delete(runId);
+            };
+            const done = () => { cleanup(); resolve(); };
+            const abort = () => { cleanup(); reject(new HarnessError('run_not_active', 'The wait was interrupted.')); };
+            const pending = this.waiters.get(runId) ?? [];
+            pending.push(done);
+            this.waiters.set(runId, pending);
+            signal?.addEventListener('abort', abort, { once: true });
+        });
+    }
+    /** The live run with this id, for a tool or broker that reports into it. */
+    active(runId) {
+        return this.runs.get(runId) ?? null;
+    }
+    /** The live run of a session, when it has one. */
+    activeForSession(sessionId) {
+        for (const run of this.runs.values())
+            if (run.sessionId === sessionId)
+                return run;
+        return null;
+    }
+    /** Hands a message to a live run's model after its current step. Throws `run_not_active` when the run cannot take it. */
+    async steer(runId, text) {
+        const run = this.runs.get(runId);
+        if (!run)
+            throw new HarnessError('run_not_active', 'This run is not active.');
+        await run.steer(text);
+    }
+    async interrupt(runId) {
+        const run = this.runs.get(runId);
+        if (!run)
+            throw new HarnessError('run_not_active', 'This run is not active.');
+        if (this.stopping.has(runId))
+            return;
+        const family = runFamily(this.options.root(), runId);
+        const active = family.runs.map(({ run: member }) => member.id).filter((id) => this.runs.has(id));
+        for (const id of active)
+            this.stopping.add(id);
+        try {
+            await Promise.allSettled(active.map((id) => this.runs.get(id)?.interrupt()));
+        }
+        finally {
+            for (const id of active)
+                this.stopping.delete(id);
+        }
+    }
+    /** Interrupts every live run, giving each a moment to stop cleanly. */
+    async interruptAll(timeoutMs = 3000) {
+        await Promise.race([Promise.allSettled(this.activeRunIds().map((id) => this.interrupt(id))), new Promise((resolve) => setTimeout(resolve, timeoutMs))]);
+    }
+    resolveApproval(runId, approvalId, decision) {
+        if (decision !== 'approved' && decision !== 'denied' && decision !== 'native')
+            throw new HarnessError('invalid_request', 'Unknown decision.');
+        const approval = this.approvals.get(approvalId);
+        if (!approval || approval.runId !== runId)
+            throw new HarnessError('approval_not_pending', 'This approval is not pending for this run.');
+        approval.resolve(decision);
+    }
+    answerQuestion(runId, questionId, answer) {
+        const question = this.questions.get(questionId);
+        if (!question || question.runId !== runId)
+            throw new HarnessError('question_not_pending', 'This question is not waiting for an answer.');
+        if (question.batch)
+            throw new HarnessError('question_batch_required', 'Answer every question in this batch together.');
+        question.resolve(this.validateAnswer(question.input, answer));
+    }
+    answerQuestions(runId, batchId, answers) {
+        const questions = [...this.questions.entries()].filter(([, pending]) => pending.runId === runId && pending.batch?.batchId === batchId);
+        if (!questions.length || answers.length !== questions.length || new Set(answers.map(({ questionId }) => questionId)).size !== answers.length) {
+            throw new HarnessError('question_not_pending', 'This question batch is not waiting for an answer.');
+        }
+        const pendingById = new Map(questions);
+        const validated = answers.map(({ questionId, answer }) => {
+            const pending = pendingById.get(questionId);
+            if (!pending)
+                throw new HarnessError('question_not_pending', 'Every question in the batch must be answered together.');
+            return { pending, answer: this.validateAnswer(pending.input, answer) };
+        });
+        for (const { pending, answer } of validated)
+            pending.resolve(answer);
+    }
+    validateAnswer(input, answer) {
+        const selected = answer.selected;
+        const selectedLabels = new Set(selected);
+        const notes = {};
+        for (const [label, note] of Object.entries(answer.notes ?? {})) {
+            const normalized = typeof note === 'string' ? note.trim() : '';
+            if (normalized)
+                notes[label] = normalized;
+        }
+        const text = answer.text?.trim();
+        if ((!input.multiSelect && selected.length > 1) ||
+            selectedLabels.size !== selected.length ||
+            selected.some((label) => !input.options.some((option) => option.label === label)) ||
+            (text && !input.allowText) ||
+            Object.keys(notes).some((label) => !selectedLabels.has(label)) ||
+            Object.values(notes).some((note) => note.length > 10_000)) {
+            throw new HarnessError('invalid_answer', 'Choose the offered options or an allowed text answer, and attach notes only to selected choices.');
+        }
+        return { selected, ...(text ? { text } : {}), ...(Object.keys(notes).length ? { notes } : {}) };
+    }
+    activeRunIds() {
+        return [...this.runs.keys()];
+    }
+    /** A request the session's own interface already settled: nothing here is waiting on it any more. */
+    nativeResolved(runId, requestId) {
+        if (!this.runs.has(runId))
+            return;
+        const approval = this.approvals.get(requestId);
+        if (approval?.runId === runId)
+            return approval.resolve('native');
+        const question = this.questions.get(requestId);
+        if (question?.runId === runId)
+            return question.resolve({ selected: [] });
+        this.nativeCleared.set(requestId, runId);
+    }
+}

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

@@ -0,0 +1,21 @@
+import type { DatabaseSync } from 'node:sqlite';
+import { type RunRecord } from "./contracts.js";
+export declare function upsertRun(database: DatabaseSync, record: RunRecord): void;
+/** Index failures never block a run. */
+export declare function recordRun(root: string, record: RunRecord): void;
+/** Every readable run record under `<data root>/runs`. */
+export declare function readAllRuns(root: string): RunRecord[];
+/**
+ * Adds the runs the table is missing, and those whose status changed, from the run files. A run
+ * recorded while the index was unavailable would otherwise be absent from session history.
+ */
+export declare function syncRuns(root: string): number;
+export declare function runsForSession(root: string, sessionId: string, limit: number): string[];
+/** Which runs to read: one session's, one agent's wherever it replied, one account's, or all. */
+export interface RunFilter {
+    session?: string | null;
+    agent?: string | null;
+    account?: string | null;
+}
+/** Runs matching `filter` started at or after `since` (an RFC 3339 instant), oldest first. */
+export declare function runsSince(root: string, filter: RunFilter, since: string | null): string[];

package/dist/sdk/sessions/runIndex.js

@@ -0,0 +1,65 @@
+import { join } from 'node:path';
+import { readJson } from "../core/fs.js";
+import { all, run as execute, runFolders, transaction, withIndex } from "../core/index.js";
+import { runRecordSchema, upgradeRunRecord } from "./contracts.js";
+export function upsertRun(database, record) {
+    execute(database, `INSERT OR REPLACE INTO runs (id, project_id, mode, harness, session_type, session_id, status, started_at, ended_at, account_id, agent_id)
+     VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11)`, record.id, record.projectId, record.mode, record.harness, record.sessionType, record.sessionId, record.status, record.startedAt, record.endedAt, record.accountId, record.agentId);
+}
+/** Index failures never block a run. */
+export function recordRun(root, record) {
+    try {
+        withIndex(root, (database) => upsertRun(database, record));
+    }
+    catch {
+        // The index is rebuilt from run files when it is next repaired.
+    }
+}
+/** Every readable run record under `<data root>/runs`. */
+export function readAllRuns(root) {
+    const records = [];
+    for (const name of runFolders(root)) {
+        try {
+            const parsed = runRecordSchema.safeParse(upgradeRunRecord(readJson(join(root, 'runs', name, 'run.json'))));
+            if (parsed.success)
+                records.push(parsed.data);
+        }
+        catch {
+            // Not a run folder.
+        }
+    }
+    return records;
+}
+/**
+ * Adds the runs the table is missing, and those whose status changed, from the run files. A run
+ * recorded while the index was unavailable would otherwise be absent from session history.
+ */
+export function syncRuns(root) {
+    const known = new Map();
+    withIndex(root, (database) => {
+        for (const row of all(database, 'SELECT id, status, agent_id FROM runs'))
+            known.set(row.id, { status: row.status, agentId: row.agent_id });
+    });
+    // A row is rewritten when its status changed, or when it predates the agent column.
+    const pending = readAllRuns(root).filter((record) => {
+        const row = known.get(record.id);
+        return !row || row.status !== record.status || (row.agentId === null && record.agentId !== null);
+    });
+    if (!pending.length)
+        return 0;
+    withIndex(root, (database) => transaction(database, () => pending.forEach((record) => upsertRun(database, record))));
+    return pending.length;
+}
+export function runsForSession(root, sessionId, limit) {
+    return withIndex(root, (database) => all(database, 'SELECT id FROM runs WHERE session_id = ?1 ORDER BY started_at DESC LIMIT ?2', sessionId, limit).map((row) => row.id));
+}
+/** Runs matching `filter` started at or after `since` (an RFC 3339 instant), oldest first. */
+export function runsSince(root, filter, since) {
+    return withIndex(root, (database) => 
+    // A chat run recorded before the agent column belongs to the agent whose own session it ran in.
+    all(database, `SELECT id FROM runs WHERE started_at >= ?1
+          AND (?2 IS NULL OR session_id = ?2)
+          AND (?3 IS NULL OR agent_id = ?3 OR (agent_id IS NULL AND mode = 'chat' AND session_id = ?3))
+          AND (?4 IS NULL OR account_id = ?4)
+       ORDER BY started_at`, since ?? '', filter.session ?? null, filter.agent ?? null, filter.account ?? null).map((row) => row.id));
+}

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

@@ -0,0 +1,66 @@
+import { type RunEvent, type RunRecord, type UsagePayload } from "./contracts.js";
+export declare function runDir(root: string, runId: string): string;
+export declare function saveRun(root: string, record: RunRecord): void;
+export declare function loadRun(root: string, runId: string): RunRecord;
+export declare function findRun(root: string, runId: string): RunRecord | null;
+/** A parent's reserved child IDs survive a crash before the spawn tool returns. */
+export declare function recordSubagent(root: string, parentRunId: string, childRunId: string): void;
+export declare function recordedSubagents(root: string, parentRunId: string): string[];
+/** Changes a run's record. A settled run keeps its outcome whatever the change says. */
+export declare function updateRun(root: string, runId: string, update: (record: RunRecord) => void): void;
+export declare function terminalStatus(event: Pick<RunEvent, 'type' | 'payload'>): 'completed' | 'failed' | 'interrupted' | null;
+export declare function appendEvent(root: string, event: RunEvent): void;
+/** A torn final line (a crash mid-write) is skipped rather than failing the whole log. */
+export declare function readEvents(root: string, runId: string): RunEvent[];
+/** An incoming event that passes the contract, or `null`. */
+export declare function parseEvent(value: unknown): RunEvent | null;
+/** The events that affected execution; what arrived after the outcome stays in the raw log as evidence. */
+export declare function executionEvents(events: readonly RunEvent[]): RunEvent[];
+/**
+ * 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 declare function persistEvent(root: string, event: RunEvent): boolean;
+/** Startup reconciliation for every run that did not settle before the process stopped. */
+export declare function markInterruptedRuns(root: string, reason?: string): string[];
+/** An approval or question a run asked for that nothing has answered yet. */
+export interface PendingDecision {
+    kind: 'approval' | 'question';
+    id: string;
+    eventId: string;
+    payload: unknown;
+}
+/** The run's unanswered approvals and questions, oldest first. */
+export declare function pendingDecisions(events: readonly RunEvent[]): PendingDecision[];
+export interface RunSnapshot {
+    run: RunRecord;
+    events: RunEvent[];
+    lastSequence: number;
+}
+export interface RunFamilySnapshot {
+    rootRunId: string;
+    runs: {
+        run: RunRecord;
+        usage: UsagePayload | null;
+    }[];
+    usage: {
+        inputTokens: number | null;
+        outputTokens: number | null;
+        cacheReadTokens: number | null;
+        cacheWriteTokens: number | null;
+        reasoningTokens: number | null;
+        costUsd: number | null;
+        requests: number | null;
+    };
+    settled: boolean;
+}
+/** A root run and all descendants linked through opaque parent-run metadata. */
+export declare function runFamily(root: string, runId: string): RunFamilySnapshot;
+export declare function snapshot(root: string, runId: string): RunSnapshot;
+export interface RunListFilter {
+    projectId?: string | null;
+    sessionId?: string | null;
+    activeOnly?: boolean;
+}
+/** A session's history comes from the index; other filters scan run records. At most 200, newest first. */
+export declare function listRuns(root: string, filter: RunListFilter): RunRecord[];