zcode-acp-server 0.60.0 → 0.62.0

package/dist/workflow/quota-resume.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Quota auto-resume watchdog for dynamic-workflow runs.
+ *
+ * Why: when a workflow subagent hits a usage cap (GLM 1308 …), upstream stops
+ * the WHOLE run as `stopped(provider)` with a `ProviderStopDetails{kind:
+ * "quota"}` and its notification instructs the agent to call
+ * ResumeWorkflowRun AFTER the reset (workflow-notification-copy.ts:55-64).
+ * Nothing schedules that "after" — the run sits stopped until a human acts.
+ * The bridge owns the process that can wait, so it does: a small persisted
+ * registry of pending resumes, a periodic scan over the project's run journal,
+ * and a timer per entry.
+ *
+ * Detection is deliberately journal-first: the v4 session summary carries the
+ * failure message (with the provider's business code in brackets) but NOT the
+ * structured providerStop/resetAt, and the workflow progress poller gives up
+ * after 10 minutes — long runs would never be seen there. The scan reads
+ * `workflows/runs` (one session-less RPC), keeps rows that are
+ * `stopped(provider)`, and only then resolves the few parent sessions through
+ * `v4/conversation/workflowRuns` to read their failure messages.
+ *
+ * Firing is defensive at every step: quota card first (a known future reset
+ * defers without burning an attempt), then a live state read (a run that is
+ * running again / finished / no longer resumable drops the entry), then the
+ * same `resumeWorkflowRun` command the App's Resume button uses. An accepted
+ * resume is re-verified after {@link VERIFY_AFTER_MS}; only a stopped-again run
+ * with no known reset burns an attempt and backs off.
+ *
+ * Store: `~/.zcode/v2/acp-quota-resumes.json`, shared by every bridge process
+ * and written only via temp+rename with merge-at-write (the dismissals-store
+ * discipline — a torn write would lose every pending resume).
+ */
+import type { QuotaResult } from "../quota/types.js";
+import type { ZcodeAcpServer } from "../server.js";
+/** Scan cadence for newly quota-stopped runs. */
+export declare const QUOTA_RESUME_SCAN_INTERVAL_MS: number;
+/** One pending auto-resume. `attempts` counts resume attempts that did not stick. */
+export interface QuotaResumeEntry {
+    runId: string;
+    /** Parent backend session (the run's journal parentSessionId). */
+    zcodeSid: string;
+    /** Workspace the run belongs to — bridges re-arm only their own project's entries. */
+    cwd: string;
+    /** ACP alias when known at schedule time (re-resolved at fire time anyway). */
+    acpSid?: string;
+    name?: string;
+    /** Epoch ms of the next fire. */
+    resumeAt: number;
+    /** Failed-attempt counter (drives the backoff ladder). */
+    attempts: number;
+    /** True while the previous resume attempt is inside its verify window. */
+    awaitingVerify?: boolean;
+    /**
+     * Terminal give-up reason. The journal row stays `stopped(provider)+quota`
+     * forever, so without this marker the scan would re-schedule the same run
+     * every cycle — a retry/give-up loop. A gave-up entry is skipped by scans,
+     * re-arms, and the idle-exit predicate; it expires via the TTL, by which
+     * time the row is out of the backfill window anyway.
+     */
+    gaveUp?: string;
+    /**
+     * In-flight fire claim (cross-process single-flight). Written under the
+     * settings file lock by {@link claimFire}; every normal mutation (updateEntry
+     * / reschedule / markGaveUp) clears it. Without it, two bridges of the same
+     * workspace (editor + serve/TUI) could both resume one run — a money-level
+     * double execution.
+     */
+    firing?: {
+        pid: number;
+        at: number;
+    };
+    scheduledAt: number;
+    updatedAt: number;
+}
+export interface QuotaResumeInput {
+    runId: string;
+    zcodeSid: string;
+    cwd: string;
+    name?: string;
+    acpSid?: string;
+    /** Provider-reported reset (Retry-After). Absent → the first fire re-derives. */
+    resetAt?: number;
+}
+/**
+ * Register (or merge) a pending auto-resume. Idempotent per runId; an earlier
+ * resumeAt wins so a duplicate detection never delays an armed timer.
+ *
+ * The whole read-decide-write runs under the store file lock: the merge must
+ * see the CURRENT record (a sibling's in-flight fire claim included — which it
+ * must never stomp) rather than a snapshot read before the lock was taken.
+ */
+export declare function scheduleQuotaResume(server: ZcodeAcpServer, input: QuotaResumeInput): Promise<void>;
+/**
+ * One scan over the project's journal for quota-stopped runs. Best-effort and
+ * side-effect free when nothing matches; never spawns a backend (the scan is
+ * discovery — only a fire may act).
+ */
+export declare function scanQuotaStoppedRuns(server: ZcodeAcpServer): Promise<void>;
+export interface QuotaResumeDeps {
+    /** Injectable for tests; defaults to the real quota card. */
+    queryQuota?: () => Promise<QuotaResult>;
+}
+/**
+ * Fire one pending entry. Everything is re-checked here because the state may
+ * have moved since scheduling (user resumed/stopped/dismissed the run, quota
+ * already recovered, bridge slept past the reset).
+ *
+ * Cross-process single-flight: the side-effecting tail runs only under a
+ * locked fire claim (see {@link claimFire}); a sibling bridge that loses the
+ * claim re-arms its local timer and lets the winner's store write (reschedule
+ * / retire) become the truth.
+ */
+export declare function fire(server: ZcodeAcpServer, runId: string, deps?: QuotaResumeDeps): Promise<void>;
+/**
+ * Arm the watchdog for one bridge: re-arm its project's persisted entries and
+ * start the periodic scan. Idempotent per server. Scans never spawn a backend
+ * and never throw; a bridge that never sees a backend stays silent.
+ */
+export declare function armQuotaResumeWatchdog(server: ZcodeAcpServer): void;
+/** Is a resume armed for this run? (test/observability hook) */
+export declare function quotaResumePending(runId: string): boolean;
+/**
+ * Is any resume pending for a workspace? The headless serve bridge consults
+ * this in its idle decision: exiting would kill the backend the pending
+ * resume must act on, breaking "the bridge owns the wait" exactly when the
+ * app is asleep (the case the watchdog exists for). Retired (gave-up) entries
+ * do not hold a serve bridge alive.
+ */
+export declare function hasQuotaResumePendingForCwd(cwd: string): boolean;
+/** Read one entry (test hook). */
+export declare function quotaResumeEntryForTest(runId: string): QuotaResumeEntry | undefined;
+/** Patch an entry and drop its timer (test hook; patches may include `firing`). */
+export declare function updateQuotaResumeEntryForTest(runId: string, patch: Partial<QuotaResumeEntry>): void;
+/** Drop every timer and the store file (test hook). */
+export declare function resetQuotaResumeForTest(): void;
+//# sourceMappingURL=quota-resume.d.ts.map

package/dist/workflow/quota-resume.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quota-resume.d.ts","sourceRoot":"","sources":["../../src/workflow/quota-resume.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAyBH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAMnD,iDAAiD;AACjD,eAAO,MAAM,6BAA6B,QAAa,CAAC;AA8CxD,qFAAqF;AACrF,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;IACjB,sFAAsF;IACtF,GAAG,EAAE,MAAM,CAAC;IACZ,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iCAAiC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AA8QD,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,cAAc,EACtB,KAAK,EAAE,gBAAgB,GACtB,OAAO,CAAC,IAAI,CAAC,CAyDf;AA0CD;;;;GAIG;AACH,wBAAsB,oBAAoB,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CA6EhF;AAED,MAAM,WAAW,eAAe;IAC9B,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,WAAW,CAAC,CAAC;CACzC;AAED;;;;;;;;;GASG;AACH,wBAAsB,IAAI,CACxB,MAAM,EAAE,cAAc,EACtB,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,eAAoB,GACzB,OAAO,CAAC,IAAI,CAAC,CAqIf;AAmED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CA2BnE;AAED,gEAAgE;AAChE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAIzD;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAKhE;AAED,kCAAkC;AAClC,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAEnF;AAED,mFAAmF;AACnF,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,OAAO,CAAC,gBAAgB,CAAC,GAC/B,IAAI,CAQN;AAED,uDAAuD;AACvD,wBAAgB,uBAAuB,IAAI,IAAI,CAQ9C"}