@xingular/harness 0.1.7 → 1.0.0

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

@@ -0,0 +1,43 @@
+import type { CallerContext } from "../core/caller.js";
+import type { ApprovalFacts } from "./approvals.js";
+import type { RunRecord } from "./contracts.js";
+export interface ToolCall {
+    run: RunRecord;
+    caller: CallerContext;
+    tool: string;
+    args: unknown;
+}
+export interface ScopeDecision {
+    /** The run is unattended: nothing may ask a person, so what is not allowed is refused. */
+    automatic?: boolean;
+    allowed: boolean;
+    /** Not allowed as it stands, but a person may approve this one call. */
+    requiresApproval?: boolean;
+    /** Per-tool remembered approvals never answer this call. */
+    humanOnly?: boolean;
+    /** Whether the global always-approve switch may answer a human-only call. Defaults to false. */
+    allowGlobalApproval?: boolean;
+    reason?: string | null;
+}
+export interface ToolPolicy {
+    /** Whether the call is inside what this run may do. Asked before every tool call. */
+    scope?(call: ToolCall): Promise<ScopeDecision>;
+    /** Whether the tool is still switched on. Asked before a call and again after an approval; throws to block. */
+    authorize?(call: ToolCall): Promise<void>;
+    /** Facts about a pending approval that only the application knows. */
+    approval?(input: {
+        run: RunRecord;
+        target: string;
+        operation?: {
+            tool: string;
+            args: unknown;
+        };
+    }): Promise<ApprovalFacts>;
+    /** The connected apps this session may reach, out of those its scope already allows. */
+    connections?(input: {
+        sessionId: string;
+        runId: string | null;
+        caller: CallerContext;
+        connectionIds: string[];
+    }): Promise<string[]>;
+}

package/dist/sdk/sessions/policy.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,34 @@
+/** Dollars per million tokens. */
+export interface PriceRates {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    /** The highest tier whose threshold the request's whole input exceeds replaces the base rates. */
+    tiers?: Array<{
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+        inputTokensAbove: number;
+    }>;
+}
+export interface PricedTokens {
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+}
+/** The cost of one request at `rates`. Same arithmetic as Pi's own `calculateCost`. */
+export declare function costAt(rates: PriceRates, usage: PricedTokens): number;
+type Catalogue = {
+    getModel(provider: string, model: string): {
+        cost?: PriceRates;
+    } | undefined;
+};
+/**
+ * The list rates Pi's catalogue has for a model, or null when it has none. A dated model id
+ * (`…-20250929`) also matches its undated entry. Rates of zero are "unknown", not "free".
+ */
+export declare function modelRates(provider: string | undefined, model: string | undefined, lookup?: Promise<Catalogue>): Promise<PriceRates | null>;
+export {};

package/dist/sdk/sessions/pricing.js

@@ -0,0 +1,40 @@
+import { loadPi } from "../pi/runtime.js";
+/** The cost of one request at `rates`. Same arithmetic as Pi's own `calculateCost`. */
+export function costAt(rates, usage) {
+    const input = usage.inputTokens ?? 0;
+    const cacheRead = usage.cacheReadTokens ?? 0;
+    const cacheWrite = usage.cacheWriteTokens ?? 0;
+    const whole = input + cacheRead + cacheWrite;
+    let applied = rates;
+    let threshold = -1;
+    for (const tier of rates.tiers ?? []) {
+        if (whole > tier.inputTokensAbove && tier.inputTokensAbove > threshold) {
+            applied = tier;
+            threshold = tier.inputTokensAbove;
+        }
+    }
+    return (applied.input * input + applied.output * (usage.outputTokens ?? 0) + applied.cacheRead * cacheRead + applied.cacheWrite * cacheWrite) / 1_000_000;
+}
+let catalogue = null;
+async function loadCatalogue() {
+    const { ModelRuntime } = await loadPi();
+    const none = { read: async () => undefined, list: async () => [], modify: async () => undefined, delete: async () => undefined };
+    return (await ModelRuntime.create({ credentials: none, modelsPath: null, refreshOnCreate: false }));
+}
+/**
+ * The list rates Pi's catalogue has for a model, or null when it has none. A dated model id
+ * (`…-20250929`) also matches its undated entry. Rates of zero are "unknown", not "free".
+ */
+export async function modelRates(provider, model, lookup = (catalogue ??= loadCatalogue())) {
+    if (!provider || !model)
+        return null;
+    const models = await lookup.catch(() => null);
+    if (!models)
+        return null;
+    for (const id of new Set([model, model.replace(/-\d{8}$/, '')])) {
+        const cost = models.getModel(provider, id)?.cost;
+        if (cost && (cost.input > 0 || cost.output > 0))
+            return cost;
+    }
+    return null;
+}

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

@@ -0,0 +1,11 @@
+export declare const MAX_REASONING_SUMMARY_CHARS = 4000;
+export declare const REASONING_SUMMARY_APIS: Set<string>;
+/** Add the Responses API summary request while preserving the provider-selected effort. */
+export declare function requestConciseReasoningSummary(payload: unknown): {
+    payload: unknown;
+    requested: boolean;
+};
+/** Pi preserves the provider reasoning item for both WebSocket and SSE replay.
+ * Read only its explicit summary: Pi's generic thinking field can also contain raw reasoning.
+ */
+export declare function completedReasoningSummary(message: unknown): string | undefined;

package/dist/sdk/sessions/reasoningSummaries.js

@@ -0,0 +1,61 @@
+export const MAX_REASONING_SUMMARY_CHARS = 4_000;
+export const REASONING_SUMMARY_APIS = new Set([
+    'openai-responses',
+    'azure-openai-responses',
+    'openai-codex-responses'
+]);
+function isRecord(value) {
+    return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+function cleanSummary(value) {
+    let text = '';
+    for (const character of value.trim()) {
+        if (text.length + character.length > MAX_REASONING_SUMMARY_CHARS)
+            break;
+        text += character;
+    }
+    return text.trim() || undefined;
+}
+/** Add the Responses API summary request while preserving the provider-selected effort. */
+export function requestConciseReasoningSummary(payload) {
+    if (!isRecord(payload) || !isRecord(payload.reasoning))
+        return { payload, requested: false };
+    const effort = payload.reasoning.effort;
+    if (typeof effort !== 'string' || ['none', 'off'].includes(effort.toLowerCase()))
+        return { payload, requested: false };
+    return {
+        payload: { ...payload, reasoning: { ...payload.reasoning, summary: 'concise' } },
+        requested: true
+    };
+}
+/** Pi preserves the provider reasoning item for both WebSocket and SSE replay.
+ * Read only its explicit summary: Pi's generic thinking field can also contain raw reasoning.
+ */
+export function completedReasoningSummary(message) {
+    if (!isRecord(message) || message.role !== 'assistant' || typeof message.api !== 'string' || !REASONING_SUMMARY_APIS.has(message.api) || !Array.isArray(message.content))
+        return undefined;
+    const parts = [];
+    const seen = new Set();
+    for (const block of message.content) {
+        if (!isRecord(block) || block.type !== 'thinking' || typeof block.thinkingSignature !== 'string')
+            continue;
+        try {
+            const item = JSON.parse(block.thinkingSignature);
+            if (!isRecord(item) || item.type !== 'reasoning' || !Array.isArray(item.summary))
+                continue;
+            if (typeof item.id === 'string') {
+                if (seen.has(item.id))
+                    continue;
+                seen.add(item.id);
+            }
+            for (const part of item.summary) {
+                if (isRecord(part) && part.type === 'summary_text' && typeof part.text === 'string')
+                    parts.push(part.text);
+            }
+        }
+        catch {
+            // Signatures of other formats, or incomplete items, are not summary evidence.
+        }
+    }
+    return cleanSummary(parts.join('\n\n'));
+}

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

@@ -0,0 +1,102 @@
+import type { AutomaticReason } from "./approvals.js";
+import { type QuestionOption, type RunEvent, type RunEventType, type RunRecord } from "./contracts.js";
+export type ApprovalDecision = 'approved' | 'denied' | 'native';
+export interface ApprovalInput {
+    requestId?: string;
+    operation?: {
+        tool: string;
+        args: Record<string, unknown>;
+    };
+    target: string;
+    action: string;
+    screenshotRef?: string;
+    /** A tool the user may choose to always allow for this session. */
+    rememberable?: boolean;
+    /** `switch`: only the "always approve" switch may grant it. `none`: a person always decides. */
+    standing?: 'full' | 'switch' | 'none';
+    /** How long to wait for a decision before the request counts as denied. */
+    timeoutMs?: number;
+}
+export interface QuestionInput {
+    requestId?: string;
+    userOnly?: boolean;
+    summary?: string;
+    question: string;
+    options: QuestionOption[];
+    multiSelect: boolean;
+    allowText: boolean;
+}
+export interface QuestionAnswer {
+    selected: string[];
+    text?: string;
+    /** Optional notes keyed by the selected choice label. */
+    notes?: Record<string, string>;
+}
+export interface ActiveRun {
+    runId: string;
+    sessionId: string;
+    emit(type: RunEventType, payload: unknown, native?: unknown): void;
+    onInterrupt(handler: () => Promise<void> | void): void;
+    /** Hands a message to the model after its current step; the session registers how. */
+    onSteer(handler: (text: string) => Promise<void> | void): void;
+    /** Resolves when the user decides; only the approval with this exact id can be resolved by it. */
+    requestApproval(input: ApprovalInput): Promise<ApprovalDecision>;
+    /** Asks the user a question and resolves with their answer. */
+    requestAnswer(input: QuestionInput): Promise<QuestionAnswer>;
+    /** Asks one to five related questions and resolves only after the whole batch is answered. */
+    requestAnswers(inputs: QuestionInput[]): Promise<QuestionAnswer[]>;
+    finish(outcome: 'completed' | 'failed' | 'interrupted', failure?: {
+        code: string;
+        message: string;
+    }): void;
+    readonly finished: 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;
+export interface RegistryOptions {
+    root: () => string;
+    /** Why this approval can be granted without asking, if it can. */
+    automatic?: (run: RunRecord, target: string, operation: ApprovalInput['operation'], standing: 'full' | 'switch') => Promise<AutomaticReason | null>;
+    /** Called when a run stops being live, whatever its outcome. */
+    ended?: (runId: string, sessionId: string) => void;
+    /** Removes secrets from an event before it is stored or shown. */
+    redact?: (event: RunEvent) => void;
+}
+export declare class RunRegistry {
+    private readonly options;
+    private readonly runs;
+    private readonly approvals;
+    private readonly questions;
+    private readonly nativeCleared;
+    private readonly waiters;
+    private readonly stopping;
+    private readonly listeners;
+    constructor(options: RegistryOptions);
+    /** Observers see events after they are persisted, in order. */
+    listen(listener: RunListener): () => void;
+    private deliver;
+    /** Starts tracking a run whose record is already saved. */
+    start(sessionId: string, runId?: string): ActiveRun;
+    private hasStoppedAncestor;
+    /** Wait for a recorded run to settle without polling storage or retaining an event listener. */
+    wait(runId: string, signal?: AbortSignal): Promise<void>;
+    /** The live run with this id, for a tool or broker that reports into it. */
+    active(runId: string): ActiveRun | null;
+    /** The live run of a session, when it has one. */
+    activeForSession(sessionId: string): ActiveRun | null;
+    /** Hands a message to a live run's model after its current step. Throws `run_not_active` when the run cannot take it. */
+    steer(runId: string, text: string): Promise<void>;
+    interrupt(runId: string): Promise<void>;
+    /** Interrupts every live run, giving each a moment to stop cleanly. */
+    interruptAll(timeoutMs?: number): Promise<void>;
+    resolveApproval(runId: string, approvalId: string, decision: ApprovalDecision): void;
+    answerQuestion(runId: string, questionId: string, answer: QuestionAnswer): void;
+    answerQuestions(runId: string, batchId: string, answers: Array<{
+        questionId: string;
+        answer: QuestionAnswer;
+    }>): void;
+    private validateAnswer;
+    activeRunIds(): string[];
+    /** A request the session's own interface already settled: nothing here is waiting on it any more. */
+    nativeResolved(runId: string, requestId: string): void;
+}