import { type Choices } from "./reporting.js"; export type ProgressState = "working" | "blocked" | "waiting_human" | "done"; export declare const PROGRESS_STATES: ProgressState[]; export interface JobProgress { state: ProgressState; message: string; percent?: number; step?: string; updated_at: string; } export interface JobQuestion { id: string; text: string; options?: string[]; /** The option the agent suggests (one of `options`). */ recommended?: string; /** The person may pick several options; the answer then lists them one per line. */ multiple?: boolean; /** What the person needs to know to answer (a diff, a URL, the alternatives). */ context?: string; asked_at: string; /** Until when the agent said it would wait for a live answer. */ wait_until?: string; answered_at?: string; } export interface JobAnswer { /** The question answered; absent when a person answered a job that finished with outcome `needs_human` without asking anything. */ question_id?: string; text: string; /** One of the question's options, when the person picked one. */ option?: string; /** For a multiple-choice question: the options the person picked (the lines of `text` that are options). */ options?: string[]; by?: string; at: string; } export type ProgressEntry = { at: string; } & ({ type: "progress"; state: "working" | "blocked"; message: string; percent?: number; step?: string; title?: string; } | { type: "note"; message: string; } | { type: "question"; id: string; text: string; options?: string[]; recommended?: string; multiple?: boolean; context?: string; wait_until?: string; } | { type: "answer"; question_id?: string; text: string; option?: string; options?: string[]; by?: string; } | { type: "outcome"; outcome: string; summary: string; title?: string; headline?: string; }); export declare const PROGRESS_LOG = "progress.jsonl"; export declare const PROGRESS_FILE = "progress.json"; export declare const QUESTION_FILE = "question.json"; export declare const ANSWER_FILE = "answer.json"; /** How long `ask` waits for a live answer when neither the call nor the skill says. */ export declare const DEFAULT_HUMAN_WAIT_SECONDS = 300; export declare const MAX_HUMAN_WAIT_SECONDS = 86400; export declare function progressPaths(jobDir: string): { log: string; current: string; question: string; answer: string; }; /** * `working` or `blocked` with a message: what the agent is doing right now. `title` names the whole job ("Fix the 500 * on /api/sync") and stays until another report changes it; it becomes `job.title`. */ export declare function reportProgress(jobDir: string, input: { message: string; state?: "working" | "blocked"; percent?: number; step?: string; title?: string; }): JobProgress; /** A timeline note that does not change the state. */ export declare function addNote(jobDir: string, message: string): ProgressEntry; /** Records that the agent reported an outcome (the `response.json` it wrote), for the timeline; its headline, when it has one, is the last progress message. */ export declare function recordOutcome(jobDir: string, outcome: string, summary: string, extra?: { title?: string; headline?: string; }): ProgressEntry; export declare function readQuestion(jobDir: string): JobQuestion | undefined; export declare function readAnswer(jobDir: string): JobAnswer | undefined; export declare function readCurrent(jobDir: string): JobProgress | undefined; /** * Asks a person something: the question is written, the state becomes `waiting_human`, and any earlier answer is * discarded. `options` become buttons on Skillhook Cloud's inbox; `recommended` marks the one the agent suggests and * `multiple` lets the person pick several. */ export declare function askQuestion(jobDir: string, input: { text: string; options?: string[]; recommended?: string; multiple?: boolean; context?: string; waitSeconds?: number; }): JobQuestion; export declare class NoQuestionError extends Error { constructor(jobDir: string); } /** * A person answers the pending question (or, with `questionId`, a specific one). With `requireQuestion` an unanswered * question must exist (the live path: a waiting `ask` call picks the answer up); otherwise the answer may stand alone, * for a job that finished with outcome `needs_human` without asking anything (`choices` are then the ones that outcome * offered). For a multiple-choice question the lines of the answer that are options become `options`. The state goes * back to `working`. */ export declare function answerQuestion(jobDir: string, input: { text: string; option?: string; by?: string; questionId?: string; requireQuestion?: boolean; choices?: Choices; }): JobAnswer; /** Polls `answer.json` until an answer to `questionId` appears, the timeout passes or `signal` aborts. */ export declare function waitForAnswer(jobDir: string, questionId: string, options: { timeoutMs: number; pollMs?: number; signal?: AbortSignal; }): Promise; /** New complete lines of `progress.jsonl` after byte `offset` (what the queue tails); `offset` advances past them. */ export declare function readTimeline(jobDir: string, offset?: number): { entries: ProgressEntry[]; offset: number; }; export interface ProgressReport { progress?: JobProgress; question?: JobQuestion; answer?: JobAnswer; timeline: ProgressEntry[]; } /** Everything the files say about a job: current state, pending question, answer and the whole timeline. */ export declare function readProgress(jobDir: string, options?: { timelineLimit?: number; }): ProgressReport;