import type { RunnerName } from "./config.js"; import type { Trigger, WebhookEvent } from "./payload.js"; import type { RunOverrides } from "./run.js"; import type { JobAnswer, JobProgress, JobQuestion } from "./progress.js"; import type { FailureKind, JobFailure } from "./runners/failure.js"; import { type JobOutcome, type JobResponse } from "./response.js"; export type JobStatus = "queued" | "running" | "succeeded" | "failed" | "timed_out" | "cancelled" | "interrupted"; export declare const TERMINAL_STATUSES: JobStatus[]; export declare const JOB_STATUSES: JobStatus[]; export interface JobSource { ip: string; method: string; path: string; content_type: string | null; user_agent?: string; } export interface JobRecord { id: string; skill: string; /** What the job is about, in a few words, as the agent named it (`job_progress` / `job_set_outcome` `title`); a resume job inherits it. */ title?: string; status: JobStatus; trigger: Trigger; runner: RunnerName; model?: string; effort?: string; created_at: string; started_at?: string; finished_at?: string; duration_ms?: number; cwd?: string; command?: string[]; pid?: number; exit_code?: number | null; signal?: string | null; session_id?: string; /** Command a human can run to continue the agent session. */ resume_command?: string; cost_usd?: number; usage?: unknown; num_turns?: number; /** Final agent message (truncated in job.json; complete in result.md). */ result?: string; error?: string; /** Whether the task was done, set when the job ends: `completed`, `partial`, `needs_human`, `nothing_to_do`, `failed` or `unknown` (see response.ts). */ outcome?: JobOutcome; /** What the agent reported (structured output or `response.json`): outcome, summary, links, data. */ response?: JobResponse; /** For `trigger: replay`: the delivery-log record and/or job this run repeats. */ replay_of?: { delivery?: string; job?: string; }; /** The SKILL.md came with the request (`POST /skills/test`, `skillhook run --file`) and lives in `jobs//skill//`. */ adhoc?: true; /** The `SKILL.md` (or `skillhook.yaml`) the job ran from. */ skill_file?: string; /** Linked project directory identified at admission. */ project_dir?: string; /** Starting revision checked immediately before invoking a runner. */ project_commit?: string; /** Original webhook admission policy digest. */ webhook_policy?: string; /** Explicit runner/model/cwd overrides, so a project refresh can resolve new defaults. */ run_overrides?: RunOverrides; /** For a cloud-managed skill: the content hash of the definition the run used (src/definitions.ts). */ definition_sha256?: string; /** For a cloud-managed skill: whether Skillhook Cloud confirmed that definition right before the run (false: it ran the copy on disk because the cloud could not be asked). */ definition_fresh?: boolean; /** What the agent last reported while running (`skillhook job progress`, the `job_progress` tool). */ progress?: JobProgress; /** The question the agent asked a person, pending until `answered_at` is set. */ question?: JobQuestion; /** The answer a person gave. */ answer?: JobAnswer; /** For `trigger: resume`: the job whose question was answered and whose session this run continues. */ resume_of?: string; /** For `trigger: resume`: the session this run continues (absent when the original had none: the skill then ran afresh with the answer). */ resume?: { session_id: string; runner: RunnerName; }; /** Set on the original job when its answer started a resume job. */ resolved_by?: string; /** Set when a person closed the job without answering it (the question went stale, the finding cleared by itself): it no longer waits for anyone. */ closed?: JobClosure; /** Why the runner or the way of running differs from what was asked (a resume without a session, a fallback). */ runner_reason?: string; /** The runner the skill asked for, when `runner` is a fallback that took over. */ runner_requested?: RunnerName; /** The account the run used (`skillhook accounts`), when it used a named one; set once the job starts. */ account?: string; /** The account asked for explicitly (`skillhook run --account`, a replay with `--account`); otherwise the skill's pool decides. */ account_requested?: string; /** Why a job that did not succeed failed, classified from the runner's output (see docs/runners.md#failure-kinds). Set for `failed` and `timed_out` jobs. */ failure?: JobFailure; /** Earlier attempts of this job (a retry, or a fallback after a failed run); the record itself is the last one. */ attempts?: JobAttempt[]; delivery_id?: string; /** Hash of payload + query for in-flight de-duplication of deliveries and recovery (see `deliveryFingerprint`). */ fingerprint?: string; source: JobSource; } export interface JobPaths { dir: string; job: string; payload: string; event: string; prompt: string; stdout: string; stderr: string; result: string; lastMessage: string; body: string; response: string; responseSchema: string; /** `skill/`: where an ad-hoc SKILL.md is kept (`skill//SKILL.md`). */ skillDir: string; /** The agent's progress timeline and current state (see progress.ts). */ progressLog: string; progress: string; question: string; answer: string; } export interface CreateJobInput { id?: string; skill: string; title?: string; trigger: Trigger; runner: RunnerName; model?: string; effort?: string; cwd?: string; source: JobSource; delivery_id?: string; fingerprint?: string; replay_of?: { delivery?: string; job?: string; }; adhoc?: true; skill_file?: string; project_dir?: string; webhook_policy?: string; run_overrides?: RunOverrides; resume_of?: string; resume?: { session_id: string; runner: RunnerName; }; question?: JobQuestion; answer?: JobAnswer; runner_reason?: string; account_requested?: string; event: WebhookEvent; rawBody?: Buffer; } /** The files of one job directory (also what `JobStore.pathsFor` returns; usable without a store). */ export declare function jobPathsFor(jobsDir: string, id: string): JobPaths; export interface JobAttempt { runner: RunnerName; account?: string; started_at: string; finished_at: string; status: JobStatus; error?: string; failure?: JobFailure; } export interface JobFilter { skill?: string; /** Only jobs that ran with this account (`skillhook accounts`). */ account?: string; status?: JobStatus | JobStatus[]; trigger?: Trigger | Trigger[]; /** Failure kind of jobs that did not succeed. */ failure?: FailureKind | FailureKind[]; /** Task outcome (derived for records written before outcomes existed); queued and running jobs never match. */ outcome?: JobOutcome | JobOutcome[]; /** Only jobs waiting for a person: a pending question, or a finished job with outcome `needs_human` that no resume answered yet. */ waiting?: boolean; /** Only jobs created at or after this instant (ISO-8601); the store stops reading once it is past it. */ since?: string; /** Only jobs created at or before this instant. */ until?: string; /** Only jobs older than the one with this id (the `next_after` of the previous page). */ after?: string; limit?: number; } export interface JobPage { jobs: JobRecord[]; /** Pass as `after` to get the next page; null when this page was not full. */ next_after: string | null; } export type JobArtifact = "stdout" | "stderr" | "prompt" | "result" | "payload" | "event" | "response"; export declare const JOB_ARTIFACTS: JobArtifact[]; /** Every job is a directory under `jobs/`; `job.json` is the record, siblings are the artifacts. */ export declare class JobStore { readonly jobsDir: string; private options; private readonly deliveriesFile; private deliveries; constructor(jobsDir: string, options: { maxJobs: number; dedupeWindowSeconds: number; }); /** New retention and dedupe settings (a config reload). */ configure(options: { maxJobs: number; dedupeWindowSeconds: number; }): void; pathsFor(id: string): JobPaths; create(input: CreateJobInput): JobRecord; get(id: string): JobRecord | undefined; require(id: string): JobRecord; update(id: string, patch: Partial): JobRecord; readEvent(id: string): WebhookEvent; readArtifact(id: string, artifact: JobArtifact, maxBytes?: number): string | undefined; ids(): string[]; list(filter?: JobFilter): JobRecord[]; /** Newest first, with a cursor. Ids encode their creation time, so `since`/`until`/`after` are decided before a `job.json` is read. */ listPage(filter?: JobFilter): JobPage; /** Checkpoint dispatch order at a graceful exit; records and payloads stay in their original directories. */ preserveQueueOrder(ids: string[]): void; /** Called once at server start: running jobs from a previous process are lost; queued ones are re-run. */ recoverOnStartup(): { interrupted: JobRecord[]; queued: JobRecord[]; }; private loadDeliveries; private saveDeliveries; /** Returns the job that already handled this delivery id (within the de-dupe window), if any. */ seenDelivery(skill: string, deliveryId: string, now?: number): string | undefined; rememberDelivery(skill: string, deliveryId: string, jobId: string, now?: number, retentionSeconds?: number): void; /** Deletes the oldest finished jobs beyond `max_jobs`. Returns how many were removed. */ prune(keep?: number): number; remove(id: string): boolean; } export declare function isTerminal(status: JobStatus): boolean; /** A waiting job a person closed without an answer: when, who and why. */ export interface JobClosure { at: string; by?: string; reason?: string; } /** A person's turn: the agent asked something nobody answered yet, or it finished saying a person must act and nobody answered or resumed it since. */ export declare function isWaitingForHuman(job: Pick): boolean;