@illuminis/comprism 0.1.3 → 0.1.5

package/out/agent/session.d.ts

@@ -1,3 +1,4 @@
+import { type ProjectFacts } from "../lib/project";
 import * as ui from "./render";
 export interface SessionOptions {
     /** Where the workspace lives, and the URL of the server that owns it. */
@@ -5,6 +6,9 @@ export interface SessionOptions {
     /** The workspace credential the device flow minted. Never a decodable token. */
     credential: string;
     root: string;
+    /** The project, start folder, branch and added folders (manual 2.1 to 2.3).
+     *  `root` is the project root when this is present. */
+    project?: ProjectFacts;
     /** read_only, approve_writes, auto_edit or full_auto. Named, not numbered. */
     permissionMode?: string;
     /** Investigate and propose, change nothing. */
@@ -23,6 +27,25 @@ export interface SessionOptions {
      *  corpus study, which has to measure each model as itself. */
     pinModel?: boolean;
     maxSpendUsd?: number;
+    /** Stop after this many steps (manual 4.13). */
+    maxSteps?: number;
+    /** Reasoning effort asked for: low, medium or high (manual 4.18). */
+    effort?: string;
+    /** Commands run in the operating system's sandbox (manual 4.12). */
+    sandbox?: boolean;
+    /** Seconds each command may run (manual 5.12); the service applies it. */
+    commandTimeoutS?: number;
+    /** Background processes outlive the job; the session stops them (5.13). */
+    keepProcesses?: boolean;
+    /** Start from this GitHub issue (manual 5.20). */
+    issue?: number;
+    /** Lead this team (manual 5.27). */
+    team?: string;
+    /** A review job (manual 5.19). */
+    review?: {
+        pr?: number;
+        post?: boolean;
+    };
     /** Commands the person has approved in advance, matched exactly.
      *
      *  The one thing a run with nobody watching cannot otherwise do is verify its
@@ -35,6 +58,8 @@ export interface SessionOptions {
      *  Ids only: the server holds the text for half an hour and nothing here has
      *  ever seen the contents. */
     attachmentIds?: string[];
+    /** Files named that could not be attached. Names only (manual 3.10). */
+    leftOut?: string[];
     /** Nobody is at the keyboard. Approvals cannot be asked for, so the
      *  permission mode has to have settled them in advance. */
     headless?: boolean;
@@ -47,6 +72,10 @@ export interface SessionOptions {
      *  process owns the keyboard and lends it here. Absent, this class opens its
      *  own reader as before, which is the standalone command's case. */
     confirm?: (question: string) => Promise<boolean>;
+    /** Ask the person for a line of text on the same lent keyboard: the plan
+     *  question and the agent's questions (manual 4.2, 4.3). Resolves null when
+     *  the person pressed Ctrl+C, which stops the job. */
+    prompt?: (question: string) => Promise<string | null>;
     /** Continue a job that already exists, rather than starting one. */
     resumeJobId?: string;
     /** The job this question follows on from. The server loads that job's
@@ -55,6 +84,27 @@ export interface SessionOptions {
     continuesJob?: string;
     /** Go without the code map for this job. See `command.ts`. */
     withoutMap?: boolean;
+    /**
+     * Which conversation this job belongs to.
+     *
+     * Sent because the server cannot work it out. With no conversation id it
+     * files the work under a person's DAY on one client, so three separate
+     * sessions in one afternoon were stored as one row called "cli, 2026-09-21"
+     * and the terminal's own session list disagreed with the Sessions screen.
+     * The terminal has always known which session it was in; it simply never
+     * said.
+     */
+    conversationId?: string;
+    /** `--max-minutes` (manual 10.7), held by the service. */
+    maxMinutes?: number;
+    /** `--schema`, `--config`, `--no-personal` (manual 10.5, 10.8), sent as read. */
+    answerSchema?: Record<string, unknown>;
+    settingsConfig?: Record<string, unknown>;
+    noPersonal?: boolean;
+    /** A queued job this run carries out (manual 10.17 to 10.19). */
+    queuedJob?: string;
+    /** `--output stream`: handed the service's stream lines as they arrive. */
+    onStream?: (items: Array<Record<string, unknown>>) => void;
 }
 export interface JobResult {
     outcome: string;
@@ -72,15 +122,44 @@ export interface JobResult {
      *  model and the arithmetic are all on the server, so a client that wrote its
      *  own wording would be a second answer to the same question. */
     receipt: string;
+    /** The receipt card, worded by the server. Drawn as sent. */
+    card?: ui.ReceiptCard | null;
     /** Which models did the work, and each one's share, as the server reported
      *  it. Taken as sent, never recalculated here. */
     models: ui.ModelShare[];
     text: string;
     testsPassed?: boolean;
+    /** How the job ended, in the service's words (manual 5.15): the first line,
+     *  the proof lines and the exit status. Absent from an older service. */
+    ending?: {
+        line: string | null;
+        proof: string[];
+        exit: number | null;
+        reason?: string;
+    };
+    /** The result object a script reads (manual 10.3), exactly as the service
+     *  built it. Printed with --output json; never assembled here. */
+    result?: Record<string, unknown>;
+    /** Reason word to exit number, as the service sent it (Appendix B). */
+    exitStatus?: Record<string, number>;
+    /** Why the job was refused before it started, as a reason word: the
+     *  service's own, or what the reply showed (no sign in, no connection). */
+    refusalReason?: string;
     /** Share of everything the job sent that the provider served from cache. */
     reusedPct?: number | null;
+    /** The agent's checklist as it ended (manual 4.4). */
+    todos: Array<{
+        content: string;
+        status: string;
+    }>;
+    /** The full reason for the last step's model, for `why` (manual 4.16). */
+    why?: string[];
+    /** Notes typed after the last step, to be sent as new requests (6.8). */
+    lateNotes: string[];
 }
 export declare class TerminalSession {
+    /** The VS Code window this terminal is inside, when there is one (VS Code manual 9.12). */
+    private editor;
     private socket;
     private readonly executor;
     private readonly opts;
@@ -92,6 +171,15 @@ export declare class TerminalSession {
      *  with nothing between the copies. */
     private lastSaid;
     private canceled;
+    /** The live "thinking 12s" line while the model works on a step. Drawn in
+     *  place and erased before anything else prints, so it never lands in the
+     *  answer. Without it a step is a blank screen for as long as the model takes,
+     *  and "thinking" and "hung" look identical. */
+    private working;
+    /** When the current wait began, kept across the line being redrawn. Cleared
+     *  when a step finishes, so the next step counts from its own start. */
+    private workFrom;
+    private readonly write;
     constructor(opts: SessionOptions, write?: (s: string) => void);
     /** Where the socket lives, derived from the workspace URL.
      *
@@ -122,8 +210,13 @@ export declare class TerminalSession {
      *  the run frame already sends as the workspace. One expression, so the map
      *  and the job record can never be about two different projects. */
     private project;
+    /** Connections lost during this job, so reconnecting gives up in the end. */
+    private drops;
     /** Why the one service would not start this job, in its own words. */
     private refusal;
+    private refusalReason;
+    private refusalResult;
+    private refusalTable;
     /** The workspace does not carry the permission question yet, so fall back. */
     private olderWorkspace;
     /** Set while one is actually running, so two never overlap. */
@@ -152,11 +245,68 @@ export declare class TerminalSession {
     private remap;
     /** Run one request to its end. Resolves with how it went. */
     run(request: string): Promise<JobResult>;
-    /** Stop the running job. Takes effect mid action, not at the end of the run. */
+    /**
+     * A pass to rejoin this job after a dropped connection, trying for about
+     * half a minute, inside the service's window (manual 8.9). Null when the
+     * service could not be reached again, or refused.
+     */
+    private reconnect;
+    /** Stop the running job. Takes effect mid action, not at the end of the run:
+     *  a command already running on this machine is stopped too (manual 6.7). */
     cancel(): void;
-    /** Something typed while it works. Joins the conversation at the next step. */
+    /** Something typed while it works. Joins the conversation at the next step;
+     *  the service says so in the `note` event it sends back (6.8). */
     steer(text: string): void;
+    /** Esc: finish the current action, then wait (manual 6.7). */
+    pause(): void;
+    /** Carry on after Esc, with a correction or without one. */
+    carryOn(text: string): void;
+    /** This job's id, once the service has issued it (`transcript`, 6.9). */
+    jobId: string | undefined;
+    /** Set from Esc until the job carries on or stops. */
+    paused: boolean;
+    /** Helpers running now, from the service's own events (manual 5.25). */
+    readonly helpers: Map<string, {
+        id: string;
+        question: string;
+        agent?: string | null;
+    }>;
+    /** `stop h2` (5.25): the service stops that one helper. */
+    stopHelper(id: string): void;
+    /** `queue` and `queue clear` (6.8): the service answers with the notes. */
+    queue(clear: boolean): void;
+    /** Ctrl+O: each action's full input and output, or the short line (6.9). */
+    full: boolean;
     private announce;
+    /** The allowance and plan notes, printed under the first line so it stays first. */
+    private allowanceLine;
+    /** A running command's output on screen (manual 5.12): the first lines as
+     *  they arrive, then held, and at the end either the rest or the last lines
+     *  with a count of what was left out. How many is the service's number. */
+    private screen;
+    private stream;
+    private flushScreen;
+    /** Changes already put in front of the person to approve, so they are not
+     *  shown twice. Every other change is shown as it is made (5.6 to 5.8). */
+    private asked;
+    /** The sandbox this machine offers, worked out once (manual 4.12). */
+    private sandboxChecked;
+    private sandboxSystem;
+    /** The full reason for the last step, as the service wrote it (4.16). */
+    lastWhy: string[];
+    /** An unattended run refused an action that needed approval (Appendix B, 4). */
+    refusedUnattended: boolean;
+    /** Approved actions by call, and what exactly was approved (manual 4.8). */
+    private approvedCalls;
+    /** Approvals waiting here that the browser may answer first (web manual 6.15). */
+    private answeredElsewhere;
+    /** An action as approved: its name, its arguments and the real folder it
+     *  runs in, so a changed argument or a moved folder is caught. */
+    private fingerprint;
+    /** Starts the working line with the service's own words. Only on a real
+     *  terminal: a piped or unattended run gets the answer and nothing else. */
+    private startWorking;
+    private stopWorking;
     private narrate;
     private targetOf;
     /** Put a change in front of the person and wait.
@@ -171,5 +321,9 @@ export declare class TerminalSession {
      *  a script that needs to change files says so by choosing a mode that allows
      *  it, up front. */
     private ask;
+    /** The plan question or one of the agent's questions (manual 4.2, 4.3).
+     *  Returns what the person typed, or null for Ctrl+C. The meaning of the
+     *  answer (y, n, a number, words) is decided by the service. */
+    private question;
     private report;
 }