@xingular/harness 0.1.7 → 1.0.0

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/continuation.d.ts

@@ -0,0 +1,48 @@
+import type { CapabilitySet } from "../capabilities/types.js";
+import type { HostSection } from "../prompt/compile.js";
+import { type ChecklistItem } 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;
+    checklist: ChecklistItem[];
+    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,85 @@
+// 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 { checklistOf, describeChecklist } from "../tools/checklist.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, checklist: [], 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: checklistOf(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.checklist.length)
+        lines.push('', 'Its checklist when it stopped:', describeChecklist(continuation.checklist));
+    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(', ')}. Start them again if their work is still needed.`);
+    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;
+}