agent-nuvira 3.1.3 → 3.2.0

package/dist/learning/unattended-job.d.ts

@@ -0,0 +1,293 @@
+/**
+ * Unattended jobs — the engine that finishes long work WITHOUT the user having
+ * to say "continue" (enterprise-grade hardening, G11).
+ *
+ * THE BUG THIS CLOSES. The long-form ledger (G8) made a 100-page book
+ * *possible*: it split the ask into bounded units and recorded progress. But it
+ * left the CADENCE manual. Every batch ended with
+ *
+ *   "Reply \"continue\" and I will write the next batch"
+ *
+ * so a 39-unit book needed ~10 human turns. The user asked for a book and got a
+ * job they had to keep pressing. That is a shortcut, not a delivery: "write me
+ * a 100-page book" is itself the authorization to spend the time, and an
+ * assistant that stops after 4 of 39 units to ask whether to continue has
+ * substituted a protocol for the work.
+ *
+ * WHAT THIS MODULE IS. A persisted queue of IN-PROGRESS WORK, plus a runner
+ * that keeps executing it until it is done, blocked on a genuine question, or
+ * out of its own time budget. It is deliberately NOT the retry queue
+ * (`deferred-task.ts`):
+ *
+ *   | | deferred-task | unattended-job |
+ *   |---|---|---|
+ *   | triggered by | a FAILURE | unfinished WORK |
+ *   | authorization | the user replying "yes" | the original ask |
+ *   | wait shape | backoff between attempts | run continuously |
+ *   | budget | ~6h of retries | hours of actual work (default 10h) |
+ *   | stops on | attempts/TTL | completion, a real question, or no progress |
+ *
+ * Merging the two would make "keep retrying the model" and "keep writing the
+ * book" the same switch, and the consent semantics of each are opposites.
+ *
+ * THREE GUARANTEES THE RUNNER ENFORCES
+ *  1. PROGRESS IS MEASURED, NOT CLAIMED. A batch that did not move the ledger
+ *     is a stall even if every step reported success. Three stalls in a row
+ *     stop the run and ask, because an agent looping without progress is the
+ *     exact "goes in a loop and never delivers" behaviour this exists to end.
+ *  2. IT STOPS FOR QUESTIONS, NOT FOR PERMISSION. The only thing that pauses
+ *     work is a decision the user genuinely owns (see `autonomy-policy.ts`).
+ *  3. IT NEVER RUNS UNBOUNDED. A deadline (default 10 hours), a stall cap, a
+ *     failure cap and a per-drain batch cap.
+ *
+ * Storage: `<memory>/unattended-jobs.json`. Best-effort writes — bookkeeping
+ * must never break the turn that scheduled the work.
+ */
+/**
+ * How long a job may keep working before it gives up and reports.
+ *
+ * Ten hours because the ask this module exists for is "a 100/200-page book" or
+ * "a phased build", and the user's requirement is explicit: those must run to
+ * completion unattended rather than in 4-turn increments. It is a CEILING, not
+ * a target — a job that finishes in ten minutes leaves the queue immediately.
+ */
+export declare const DEFAULT_DEADLINE_MS: number;
+/** Consecutive no-progress batches before the run stops and asks. */
+export declare const MAX_STALLED_BATCHES = 3;
+/** Consecutive hard failures (provider errors, verification failures). */
+export declare const MAX_CONSECUTIVE_FAILURES = 6;
+/** Batches one drain may run before yielding (keeps a tick responsive). */
+export declare const MAX_BATCHES_PER_DRAIN = 6;
+/**
+ * How long a job may sit in `running` before it is treated as abandoned.
+ *
+ * A batch is claimed before it runs; if the process dies mid-batch — a restart,
+ * a reboot, a crash, all normal over a ten-hour job — nothing resets it and a
+ * `running` job is invisible to every query. The work would be stranded
+ * silently, which is the failure mode the whole ledger exists to prevent. The
+ * ceiling is generous (well past a single batch) so a live batch is never
+ * stolen.
+ */
+export declare const STALE_RUNNING_MS: number;
+/** What kind of ongoing work this is. */
+export type UnattendedKind = 'long-form' | 'phased';
+export type UnattendedStatus = 'pending' | 'running' | 'done' | 'blocked' | 'failed' | 'cancelled';
+/** Where a job's progress must be reported. */
+export interface UnattendedSurface {
+    /** `dashboard`, `cli`, `whatsapp`, … — the drain is ownership-filtered on this. */
+    platform: string;
+    /** Session id / channel id the report goes to. */
+    channelId: string;
+}
+/** One unit of ongoing work, as much as the runner needs to keep it going. */
+export interface UnattendedJob {
+    id: string;
+    kind: UnattendedKind;
+    /** The ORIGINAL ask, verbatim — a batch re-states it so intent survives hours. */
+    goal: string;
+    /** Absolute project root the work happens in. */
+    projectPath: string;
+    /** Where to report. */
+    surface: UnattendedSurface;
+    /**
+     * What to send the engine to make it do the next batch.
+     *
+     * Usually "continue", which the long-form planner resolves against the ledger
+     * (so a batch never restarts the book). Kept as data rather than hard-coded
+     * so a phased build can carry a richer brief.
+     */
+    continuationPrompt: string;
+    createdAt: number;
+    updatedAt: number;
+    lastRunAt: number;
+    /** Absolute epoch ms after which the job stops and reports. */
+    deadline: number;
+    /** Batches executed. */
+    batches: number;
+    /** Consecutive batches that produced no measurable progress. */
+    stalledBatches: number;
+    /** Consecutive hard failures. */
+    failures: number;
+    status: UnattendedStatus;
+    /** Last MEASURED completion, 0–100 (from the ledgers, not from a claim). */
+    progress: number;
+    /** Human-readable progress, e.g. "chapter 12/39 · 10,800 words". */
+    progressLine?: string;
+    /** Why it stopped, when it did not finish. */
+    stopReason?: string;
+    /** The one question blocking the run, when status is `blocked`. */
+    pendingQuestion?: string;
+    /** Report progress to the user as the job runs (off for silent builds). */
+    notify: boolean;
+    /**
+     * Files that must ALL exist for the deliverable to count as finished.
+     *
+     * Set by a composite plan (site + chapters + optional tools). The progress
+     * measurement treats their presence as part of completion, so "the prose
+     * phase finished" is never reported as "the deliverable is done" when the
+     * experience layer is still missing.
+     */
+    expectedArtifacts?: string[];
+}
+/** What a surface tells the store after running one batch. */
+export interface BatchOutcome {
+    /**
+     * Measured completion 0–100, read from the ledgers/artifacts.
+     *
+     * MUST be measured: this is what separates a slow-but-working job from a
+     * loop, and an agent-reported number would defeat the whole check.
+     */
+    progress?: number;
+    /** Human-readable progress line, e.g. "chapter 12/39 complete". */
+    progressLine?: string;
+    /** The work is finished — the deliverable exists. */
+    finished?: boolean;
+    /** A genuine decision the run cannot make for the user (from the policy). */
+    question?: string;
+    /** The batch failed (provider error, verification failure). */
+    error?: string;
+}
+/** Everything needed to schedule ongoing work. */
+export interface StartUnattendedInput {
+    kind: UnattendedKind;
+    goal: string;
+    projectPath: string;
+    surface: UnattendedSurface;
+    continuationPrompt?: string;
+    /** Override the time budget (tests use a short one). */
+    deadlineMs?: number;
+    notify?: boolean;
+    /** Files that must all exist for the job to count as finished. */
+    expectedArtifacts?: string[];
+}
+/** Read the queue. Best-effort: a corrupt file is an empty queue, never a throw. */
+export declare function loadUnattendedJobs(now?: number): UnattendedJob[];
+/**
+ * Schedule ongoing work — or return the job already carrying it.
+ *
+ * Idempotent per (kind, project, surface) on purpose: every batch of a book
+ * re-enters this function, and treating each re-entry as a new job would spawn
+ * a duplicate worker per batch and have them race on the same chapters.
+ */
+export declare function startUnattendedJob(input: StartUnattendedInput): {
+    job: UnattendedJob;
+    created: boolean;
+};
+export declare function getUnattendedJob(id: string): UnattendedJob | undefined;
+/** The live job for a surface (newest first), if any. */
+export declare function findUnattendedJob(surface: UnattendedSurface): UnattendedJob | undefined;
+/** Every job still waiting for a turn (for status surfaces, newest first). */
+export declare function listUnattendedJobs(): UnattendedJob[];
+/**
+ * One drain OWNS a subset of the queue.
+ *
+ * The store is shared by every process that can run a turn, so each drain
+ * declares what it owns — without this the gateway would claim a dashboard
+ * session and try to deliver a book chapter to a messaging platform.
+ */
+export type JobOwnership = (job: UnattendedJob) => boolean;
+/**
+ * Jobs ready to run now: pending, inside their deadline, and not out of road.
+ *
+ * `blocked` jobs are deliberately excluded — they are waiting on the user, not
+ * on the scheduler.
+ */
+export declare function dueUnattendedJobs(now?: number, owns?: JobOwnership): UnattendedJob[];
+/** Jobs whose time budget ran out — the user must be told, not ghosted. */
+export declare function expiredUnattendedJobs(now?: number, owns?: JobOwnership): UnattendedJob[];
+/**
+ * Stop a job with a reason, without touching its counters.
+ *
+ * Used by the runner to expire jobs whose time budget ran out — the reason
+ * must be RECORDED (the user is told why the promised work stopped), and doing
+ * it here keeps the runner free of ledger-write logic.
+ */
+export declare function stopUnattendedJob(id: string, status: Extract<UnattendedStatus, 'failed' | 'cancelled' | 'done'>, reason: string, now?: number): UnattendedJob | undefined;
+/** Stop a job (the user said stop, or the work is being replaced). */
+export declare function cancelUnattendedJob(id: string, reason?: string): void;
+/** Drop every job for a surface (`stop`, `cancel`, a fresh unrelated ask). */
+export declare function cancelUnattendedJobsFor(surface: UnattendedSurface, reason?: string): number;
+/** Claim a job for one batch. Returns the claimed job, or undefined. */
+export declare function claimUnattendedJob(id: string, now?: number): UnattendedJob | undefined;
+/**
+ * Record what one batch actually did, and decide what happens next.
+ *
+ * This is where "no manual cadence" is enforced: the batch's own outcome
+ * determines whether the job keeps running, stops because it is DONE, or stops
+ * because it needs the user — nobody has to say "continue".
+ *
+ * @returns the updated job (undefined when the id is unknown).
+ */
+export declare function recordBatchOutcome(id: string, outcome: BatchOutcome, now?: number): UnattendedJob | undefined;
+/** Resume a blocked job after the user answered. */
+export declare function resumeUnattendedJob(id: string, extraDeadlineMs?: number, now?: number): UnattendedJob | undefined;
+/** Percentage complete, clamped. */
+export declare function jobPercent(job: UnattendedJob): number;
+/**
+ * The honest status line for a job.
+ *
+ * Deliberately quotes MEASURED progress and says explicitly that no reply is
+ * needed — the user's complaint was having to reply at all, so a progress
+ * report that ends by asking for one would repeat the mistake in miniature.
+ */
+export declare function unattendedStatusLine(job: UnattendedJob): string;
+/** How long the job may still run, in ms (0 when the budget is spent). */
+export declare function remainingBudgetMs(job: UnattendedJob, now?: number): number;
+/** Test/reset hook. */
+export declare function clearUnattendedJobs(): void;
+/** What a surface must supply to have its work continued. */
+export interface UnattendedRunnerDeps {
+    /**
+     * Run ONE batch of the job, and report what it did.
+     *
+     * The surface owns the turn (it knows how to reach its engine); the runner
+     * owns the bookkeeping. The returned outcome MUST be measured from the
+     * artifacts, not from what the agent claimed.
+     */
+    runBatch: (job: UnattendedJob) => Promise<BatchOutcome>;
+    /** A user-facing line about the job (progress, completion, a question). */
+    notify?: (job: UnattendedJob, line: string) => void | Promise<void>;
+    /**
+     * Is the surface busy for this job? A batch waits rather than colliding with
+     * a live turn (which the surface would reject), losing nothing.
+     */
+    isBusy?: (job: UnattendedJob) => boolean;
+    /** Which jobs this drain owns (default: all). */
+    owns?: JobOwnership;
+    now?: () => number;
+    /** Batches per drain — higher means a tick finishes more of a long job. */
+    maxBatchesPerDrain?: number;
+}
+/**
+ * The unattended continuation loop.
+ *
+ * One instance per surface process. `drain()` is the periodic tick: it expires
+ * anything out of time, reports it, then runs whatever is due — looping so a
+ * single tick advances a long job as far as its budget allows instead of one
+ * chapter per tick. Drains are serialized through an internal chain, because
+ * two overlapping drains would run the same job twice and race on the same
+ * files (exactly how the first end-to-end run produced four copies of the last
+ * chapter).
+ */
+export declare class UnattendedRunner {
+    private readonly deps;
+    private chain;
+    private active;
+    constructor(deps: UnattendedRunnerDeps);
+    private now;
+    /** Is a drain currently running? Status surfaces use this to show activity. */
+    get isRunning(): boolean;
+    /** The jobs this runner would pick up right now. */
+    due(): UnattendedJob[];
+    /**
+     * Advance every due job as far as one tick may.
+     *
+     * @returns how many batches were run.
+     */
+    drain(): Promise<number>;
+    private lastBatches;
+    private runOnce;
+    /** A notification must never break the run that produced it. */
+    private safeNotify;
+}
+//# sourceMappingURL=unattended-job.d.ts.map

package/dist/learning/unattended-job.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unattended-job.d.ts","sourceRoot":"","sources":["../../src/learning/unattended-job.ts"],"names":[],"mappings":"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"}