@xingular/harness 2.0.0 → 2.0.1-unstable

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

@@ -0,0 +1,13 @@
+import type { TodoItem } from "./contracts.js";
+export interface SessionState {
+    /** The name Pi has for this native session, or null while it is unnamed. */
+    name: string | null;
+    /** This run's own todo list. A run starts with an empty list. */
+    todo: readonly TodoItem[];
+    /** A previous run's list, shown as context only. */
+    previousTodo?: readonly TodoItem[];
+    /** Whether this is the first turn in the native session. */
+    firstTurn: boolean;
+}
+/** The latest non-empty session_info name in a native history, or null. */
+export declare function latestSessionName(historyFile: string | null): string | null;

package/dist/sdk/sessions/sessionState.js

@@ -0,0 +1,31 @@
+// The current name and todo state a run sees in its request context. The structured path
+// delivers this as a dynamic prompt section; the terminal appends the same text to the request.
+import { readFileSync } from 'node:fs';
+/** The latest non-empty session_info name in a native history, or null. */
+export function latestSessionName(historyFile) {
+    if (!historyFile)
+        return null;
+    let text;
+    try {
+        text = readFileSync(historyFile, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    let name = null;
+    for (const line of text.split('\n')) {
+        if (!line.includes('"session_info"'))
+            continue;
+        try {
+            const entry = JSON.parse(line);
+            if (entry?.type === 'session_info') {
+                const value = typeof entry.name === 'string' ? entry.name.trim() : '';
+                name = value || null;
+            }
+        }
+        catch {
+            // A malformed line is not a session name.
+        }
+    }
+    return name;
+}

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

@@ -0,0 +1,238 @@
+import type { Accounts } from "../accounts/accounts.js";
+import type { CapabilitySet } from "../capabilities/types.js";
+import type { CallerContext } from "../core/caller.js";
+import type { Plugins } from "../plugins/plugins.js";
+import { type Launch } from "../prompt/compile.js";
+import { type VariantChoice } from "../variant/materialise.js";
+import type { VariantTrust } from "../variant/trust.js";
+import { type GoalLimits } from "./goal.js";
+import type { ToolProvider, ToolSession, ToolSpec } from "../tools/types.js";
+import type { DispatchEnv } from "../tools/dispatch.js";
+import { type RunRecord } from "./contracts.js";
+import { type SubagentInput, type SubagentOptions } from "./subagents.js";
+import type { Subagents } from "./subagentService.js";
+import { type WorkSliceInput } from "./workSlice.js";
+import type { ToolPolicy } from "./policy.js";
+import type { ActiveRun, RunRegistry } from "./registry.js";
+import { type Effort, type SessionCommand, type SessionFactory, type ToolGate } from "./runner.js";
+import { LiveSessions, type LiveSessionStatus } from "./live.js";
+/** The fields of a run record the caller decides; the harness fills in the rest. */
+export type RunFields = Pick<RunRecord, 'id' | 'sessionId'> & Partial<Pick<RunRecord, 'mode' | 'harness' | 'sessionType' | 'projectId' | 'agentId' | 'trigger' | 'goal' | 'attachmentCount' | 'resumedFromRunId' | 'parentRunId' | 'relation' | 'worktreeId' | 'handoffId' | 'profile' | 'title'>>;
+export interface SessionRunInput {
+    run: RunFields;
+    /** The account this session is pinned to. A new session may name a pool, or neither for the default. */
+    accountId?: string | null;
+    poolId?: string | null;
+    model?: string | null;
+    effort?: Effort | null;
+    cwd: string;
+    /** Where this session's native history lives. */
+    sessionDir: string;
+    /** Continue exactly this recorded history; never another one. */
+    resume?: {
+        sessionFile?: string | null;
+        nativeSessionId?: string | null;
+    } | null;
+    text: string;
+    /** Run this user-authored Bash command before prompting the model. */
+    initialBashCommand?: string;
+    /** A prior run's Bash attempt and result, supplied when retrying a ! command. */
+    initialBashContext?: {
+        runId: string;
+        status: 'completed' | 'incomplete' | 'unknown';
+        ok?: boolean;
+        output?: string;
+    };
+    images?: {
+        mediaType: string;
+        data: string;
+    }[];
+    /** Reject a resolved model that cannot inspect image content. */
+    requiresImageInput?: boolean;
+    preamble?: string | null;
+    /** Unattended: no project extensions, no context files, nothing may ask a person. */
+    automatic?: boolean;
+    /** Who the session works as, for history, the Wiki and the prompt. */
+    caller: CallerContext;
+    /**
+     * The variant the session runs: a scope's head (or a version of it), or a variant on disk.
+     * Its version is pinned for the whole run and recorded on it.
+     */
+    variant?: VariantChoice | null;
+    /**
+     * The subagent profile files this session's switched-on packages bring, chosen when it starts.
+     * The harness sets it; children of the run resolve their profiles from the same list.
+     */
+    packageProfiles?: string[];
+    /** What the application adds to the prompt, and which tools it describes. */
+    launch?: Launch;
+    /** The tools switched on, in the order the model sees them, and those that ask before each call. */
+    tools: {
+        allow: string[];
+        gated?: string[];
+    };
+    /** Give the session the connected-apps broker. */
+    connections?: boolean | {
+        readOnly?: boolean;
+    };
+    /** Optional narrower set for a child run; the harness intersects it with current availability. */
+    capabilities?: CapabilitySet;
+    /** Hops from the user to this session (0 when the user started it). */
+    depth?: number;
+    /** Interactive default: native child tools. Null disables; unattended callers must opt in. */
+    subagents?: SubagentOptions | null;
+    /** Ask the application's tool providers for tools (the default). False runs with the harness's own tools only. */
+    providers?: boolean;
+    /** Give the session the harness's own tools: History, the Wiki, skills, and other defaults. */
+    harnessTools?: boolean;
+    /** Set a provisional name when a top-level session starts unnamed. Defaults to true. */
+    autoName?: boolean;
+    /**
+     * Plan mode: an attended run may read, search, recall and ask, and is told to end with a
+     * `<proposed_plan>` block. Other calls are refused at the gate; the system prompt stays stable.
+     */
+    plan?: boolean;
+    /**
+     * A goal (ADR-0072): the run keeps working on this objective, continuing in place after each
+     * reply, until the model's completion claim is checked and holds, a brake stops it, or its
+     * rounds or hours are used. Only a person's own top-level run may carry one. The objective is the
+     * request; `text` is ignored.
+     */
+    goal?: {
+        objective: string;
+    } & Partial<GoalLimits>;
+    /**
+     * Continue a run that stopped before it finished: the earlier run's id. The new run reopens its
+     * native history and pins its account, variant version and capability set, and the model is told
+     * where it stopped. A work-slice policy may also ask for it when a reply reaches its budget.
+     */
+    continueFrom?: string | null;
+    /**
+     * Bound this reply (PROP-0041): a tool-call, minute and token budget, then a checkpoint and a
+     * continuation. Absent uses the foundation defaults; the policy is carried to the next slice.
+     */
+    workSlice?: WorkSliceInput;
+    /**
+     * Run a session command instead of sending `text`: compact the context, navigate the history
+     * with a summary of the branch left behind, or export it to HTML. It pins the account like a turn.
+     */
+    command?: SessionCommand;
+    /**
+     * Keep the Pi session open after this run (ADR-0083), and reuse an open one when this run's pins
+     * equal its own. Steer the running reply with `runs.steer`, queue the next message with
+     * `sessions.followUp`, and close it with `sessions.close`. Never for unattended or child runs.
+     */
+    live?: boolean;
+    /** Start a new native history in `sessionDir` instead of continuing its newest one. */
+    newHistory?: boolean;
+    /**
+     * How a plan run withholds what it may not use. `gate` (the default) keeps every tool in the
+     * request, so the prompt and its cache stay as they were, and refuses the calls at the gate.
+     * `active` sends only the plan's tools, as the terminal does (ADR-0083).
+     */
+    planTools?: 'gate' | 'active';
+    /**
+     * Hidden messages saved in the native history before the request, as the context update is: the
+     * skills a person required with `$name`, or a goal note. The person's own text reaches the model
+     * unchanged. At most 8, of at most 20,000 characters each.
+     */
+    hiddenNotes?: Array<{
+        customType: string;
+        content: string;
+    }>;
+}
+/** The connected-apps broker, as a session sees it. */
+export interface SessionBroker {
+    toolNames: readonly string[];
+    tools(session: ToolSession, options: {
+        readOnly: boolean;
+    }): ToolSpec[];
+}
+export interface SessionsOptions {
+    subagents: Subagents;
+    env: DispatchEnv;
+    accounts: Accounts;
+    runs: RunRegistry;
+    policy: ToolPolicy;
+    broker?: SessionBroker | null;
+    /** Chooses what a session loads. Without it Pi discovers extensions and skills on its own. */
+    plugins?: Plugins;
+    /** Resolves the caller's capability set from the harness's stores. */
+    resolveCapabilities?: (caller: CallerContext, tools: readonly string[], cwd: string) => Promise<CapabilitySet>;
+    /** Whether the run's explicit Full Permission switch is enabled (remembered tool grants do not count). */
+    fullPermission?: (run: RunRecord) => boolean | Promise<boolean>;
+    factory?: SessionFactory;
+    /** Which plugin code in variants a person trusted. */
+    trust?: VariantTrust | null;
+    /** Managed worktrees: a run naming one works in its folder and holds it until the run settles. */
+    worktrees?: {
+        pathOf(id: string): string | null;
+        acquire(id: string, holder: string): Promise<unknown>;
+        release(id: string, holder: string): Promise<void>;
+    } | null;
+    /** How long an idle live session stays open (ADR-0083). */
+    liveIdleMs?: number;
+}
+export declare class Sessions {
+    private readonly options;
+    private readonly providers;
+    private readonly factory;
+    /** Pi sessions kept open between the runs of a conversation (ADR-0083). */
+    readonly live: LiveSessions;
+    /** The last live run's input per session, which a follow-up repeats with its own text. */
+    private readonly liveInputs;
+    constructor(options: SessionsOptions);
+    /** The live sessions open now. */
+    liveSessions(): LiveSessionStatus[];
+    /**
+     * Sends a message as the next run of a live session: now when it is idle, or after its active
+     * run settles. The run repeats the last live run's input with this text.
+     */
+    followUp(sessionId: string, text: string): Promise<{
+        runId: string;
+    } | {
+        queued: number;
+    }>;
+    /** Closes a live session now, or as soon as its active run settles. */
+    closeLive(sessionId: string): {
+        closed: boolean;
+        afterRun: string | null;
+    };
+    /** Closes every live session; the harness calls it when it shuts down. */
+    close(): void;
+    private runFollowUp;
+    private get env();
+    /** Adds tools an application provides. Providers are asked in the order they were added. */
+    provide(provider: ToolProvider): void;
+    diagnostics(context: import("../doctor/types.js").DoctorContext): Promise<import("../doctor/types.js").DoctorCheck[]>;
+    /** The same registered providers used by real runs; no native Pi session is constructed. */
+    diagnosticTools(session: import("../tools/types.js").ToolSession): Promise<import("../tools/types.js").ToolSpec[]>;
+    diagnosticGate(run: ActiveRun, caller: CallerContext): ToolGate;
+    private gate;
+    /** Compatibility alias for the shared native service. */
+    spawnSubagent(request: SubagentInput): Promise<{
+        runId: string;
+        nativeSessionId: string | null;
+    }>;
+    /**
+     * Starts one turn. Returns once the Pi session is open; the reply arrives as run events. A
+     * session that cannot be opened ends its run as failed and returns no native session id.
+     */
+    run(input: SessionRunInput): Promise<{
+        runId: string;
+        nativeSessionId: string | null;
+    }>;
+    /**
+     * A run that names a worktree the harness manages works in that worktree's folder and holds it
+     * until the run settles. An id the harness does not know is kept as the caller's own field.
+     */
+    private enterWorktree;
+    /**
+     * Starts the next slice when a reply stopped at its work-slice boundary (PROP-0041). Never for
+     * unattended, plan, subagent, command or worktree runs, after a blocked or fruitless slice, or
+     * past the policy's slice cap. The earlier record is never reopened; this is a new run with the
+     * same pins, exactly as an application-asked continuation.
+     */
+    private continueSlice;
+    private start;
+}