agent-nuvira 3.1.3 → 3.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (164) hide show
  1. package/dist/agents/agents/reasoner.d.ts +8 -0
  2. package/dist/agents/agents/reasoner.d.ts.map +1 -1
  3. package/dist/agents/agents/reasoner.js +53 -2
  4. package/dist/agents/agents/reasoner.js.map +1 -1
  5. package/dist/agents/agents/writer.d.ts +24 -0
  6. package/dist/agents/agents/writer.d.ts.map +1 -1
  7. package/dist/agents/agents/writer.js +200 -0
  8. package/dist/agents/agents/writer.js.map +1 -1
  9. package/dist/agents/composite-plan.d.ts +143 -0
  10. package/dist/agents/composite-plan.d.ts.map +1 -0
  11. package/dist/agents/composite-plan.js +399 -0
  12. package/dist/agents/composite-plan.js.map +1 -0
  13. package/dist/agents/long-form-plan.d.ts +156 -0
  14. package/dist/agents/long-form-plan.d.ts.map +1 -0
  15. package/dist/agents/long-form-plan.js +274 -0
  16. package/dist/agents/long-form-plan.js.map +1 -0
  17. package/dist/agents/orchestrator.d.ts +107 -0
  18. package/dist/agents/orchestrator.d.ts.map +1 -1
  19. package/dist/agents/orchestrator.js +501 -35
  20. package/dist/agents/orchestrator.js.map +1 -1
  21. package/dist/agents/prompt-assembly.d.ts +8 -0
  22. package/dist/agents/prompt-assembly.d.ts.map +1 -1
  23. package/dist/agents/prompt-assembly.js +17 -0
  24. package/dist/agents/prompt-assembly.js.map +1 -1
  25. package/dist/cli/chat.d.ts +33 -0
  26. package/dist/cli/chat.d.ts.map +1 -1
  27. package/dist/cli/chat.js +161 -7
  28. package/dist/cli/chat.js.map +1 -1
  29. package/dist/cli/execute.d.ts +12 -0
  30. package/dist/cli/execute.d.ts.map +1 -1
  31. package/dist/cli/execute.js +150 -2
  32. package/dist/cli/execute.js.map +1 -1
  33. package/dist/cli/loop-executor.d.ts +17 -0
  34. package/dist/cli/loop-executor.d.ts.map +1 -1
  35. package/dist/cli/loop-executor.js +160 -1
  36. package/dist/cli/loop-executor.js.map +1 -1
  37. package/dist/cli/models.d.ts.map +1 -1
  38. package/dist/cli/models.js +10 -0
  39. package/dist/cli/models.js.map +1 -1
  40. package/dist/cli/trace.d.ts +19 -0
  41. package/dist/cli/trace.d.ts.map +1 -1
  42. package/dist/cli/trace.js +109 -2
  43. package/dist/cli/trace.js.map +1 -1
  44. package/dist/gateway/registry.d.ts +31 -0
  45. package/dist/gateway/registry.d.ts.map +1 -1
  46. package/dist/gateway/registry.js +162 -13
  47. package/dist/gateway/registry.js.map +1 -1
  48. package/dist/inference/model-entitlement.d.ts +46 -0
  49. package/dist/inference/model-entitlement.d.ts.map +1 -0
  50. package/dist/inference/model-entitlement.js +98 -0
  51. package/dist/inference/model-entitlement.js.map +1 -0
  52. package/dist/inference/tool-call-utils.d.ts +10 -0
  53. package/dist/inference/tool-call-utils.d.ts.map +1 -1
  54. package/dist/inference/tool-call-utils.js +90 -0
  55. package/dist/inference/tool-call-utils.js.map +1 -1
  56. package/dist/learning/autonomy-policy.d.ts +370 -0
  57. package/dist/learning/autonomy-policy.d.ts.map +1 -0
  58. package/dist/learning/autonomy-policy.js +544 -0
  59. package/dist/learning/autonomy-policy.js.map +1 -0
  60. package/dist/learning/cost-tracker.d.ts +14 -0
  61. package/dist/learning/cost-tracker.d.ts.map +1 -1
  62. package/dist/learning/cost-tracker.js +22 -0
  63. package/dist/learning/cost-tracker.js.map +1 -1
  64. package/dist/learning/credential-fingerprint.d.ts +58 -0
  65. package/dist/learning/credential-fingerprint.d.ts.map +1 -0
  66. package/dist/learning/credential-fingerprint.js +126 -0
  67. package/dist/learning/credential-fingerprint.js.map +1 -0
  68. package/dist/learning/deliverable-class.d.ts +178 -0
  69. package/dist/learning/deliverable-class.d.ts.map +1 -0
  70. package/dist/learning/deliverable-class.js +504 -0
  71. package/dist/learning/deliverable-class.js.map +1 -0
  72. package/dist/learning/engine-router.d.ts +12 -1
  73. package/dist/learning/engine-router.d.ts.map +1 -1
  74. package/dist/learning/engine-router.js +28 -0
  75. package/dist/learning/engine-router.js.map +1 -1
  76. package/dist/learning/long-form.d.ts +252 -0
  77. package/dist/learning/long-form.d.ts.map +1 -0
  78. package/dist/learning/long-form.js +521 -0
  79. package/dist/learning/long-form.js.map +1 -0
  80. package/dist/learning/model-first-router.d.ts +17 -0
  81. package/dist/learning/model-first-router.d.ts.map +1 -1
  82. package/dist/learning/model-first-router.js +27 -0
  83. package/dist/learning/model-first-router.js.map +1 -1
  84. package/dist/learning/model-registry.d.ts +66 -4
  85. package/dist/learning/model-registry.d.ts.map +1 -1
  86. package/dist/learning/model-registry.js +67 -6
  87. package/dist/learning/model-registry.js.map +1 -1
  88. package/dist/learning/model-warmup.d.ts +97 -2
  89. package/dist/learning/model-warmup.d.ts.map +1 -1
  90. package/dist/learning/model-warmup.js +165 -60
  91. package/dist/learning/model-warmup.js.map +1 -1
  92. package/dist/learning/prompt-layers.d.ts +61 -0
  93. package/dist/learning/prompt-layers.d.ts.map +1 -0
  94. package/dist/learning/prompt-layers.js +140 -0
  95. package/dist/learning/prompt-layers.js.map +1 -0
  96. package/dist/learning/provider-limits.d.ts +66 -0
  97. package/dist/learning/provider-limits.d.ts.map +1 -0
  98. package/dist/learning/provider-limits.js +184 -0
  99. package/dist/learning/provider-limits.js.map +1 -0
  100. package/dist/learning/reasoning-trace.d.ts +125 -1
  101. package/dist/learning/reasoning-trace.d.ts.map +1 -1
  102. package/dist/learning/reasoning-trace.js +85 -2
  103. package/dist/learning/reasoning-trace.js.map +1 -1
  104. package/dist/learning/resilient-call.d.ts +36 -1
  105. package/dist/learning/resilient-call.d.ts.map +1 -1
  106. package/dist/learning/resilient-call.js +80 -5
  107. package/dist/learning/resilient-call.js.map +1 -1
  108. package/dist/learning/unattended-job.d.ts +350 -0
  109. package/dist/learning/unattended-job.d.ts.map +1 -0
  110. package/dist/learning/unattended-job.js +636 -0
  111. package/dist/learning/unattended-job.js.map +1 -0
  112. package/dist/learning/unattended-progress.d.ts +95 -0
  113. package/dist/learning/unattended-progress.d.ts.map +1 -0
  114. package/dist/learning/unattended-progress.js +147 -0
  115. package/dist/learning/unattended-progress.js.map +1 -0
  116. package/dist/learning/working-state.d.ts +109 -0
  117. package/dist/learning/working-state.d.ts.map +1 -0
  118. package/dist/learning/working-state.js +244 -0
  119. package/dist/learning/working-state.js.map +1 -0
  120. package/dist/nlu/conversation-gate.d.ts +33 -0
  121. package/dist/nlu/conversation-gate.d.ts.map +1 -1
  122. package/dist/nlu/conversation-gate.js +68 -3
  123. package/dist/nlu/conversation-gate.js.map +1 -1
  124. package/dist/tools/coding-tools.d.ts.map +1 -1
  125. package/dist/tools/coding-tools.js +95 -19
  126. package/dist/tools/coding-tools.js.map +1 -1
  127. package/dist/tools/edit-verification.d.ts +142 -0
  128. package/dist/tools/edit-verification.d.ts.map +1 -0
  129. package/dist/tools/edit-verification.js +262 -0
  130. package/dist/tools/edit-verification.js.map +1 -0
  131. package/dist/tools/git-tool.d.ts.map +1 -1
  132. package/dist/tools/git-tool.js +37 -4
  133. package/dist/tools/git-tool.js.map +1 -1
  134. package/dist/tools/registry.d.ts +30 -2
  135. package/dist/tools/registry.d.ts.map +1 -1
  136. package/dist/tools/registry.js +40 -11
  137. package/dist/tools/registry.js.map +1 -1
  138. package/dist/tools/run-cli.d.ts.map +1 -1
  139. package/dist/tools/run-cli.js +40 -13
  140. package/dist/tools/run-cli.js.map +1 -1
  141. package/dist/tools/run-terminal.d.ts +6 -1
  142. package/dist/tools/run-terminal.d.ts.map +1 -1
  143. package/dist/tools/run-terminal.js +158 -18
  144. package/dist/tools/run-terminal.js.map +1 -1
  145. package/dist/tools/tool-loop.d.ts +109 -0
  146. package/dist/tools/tool-loop.d.ts.map +1 -1
  147. package/dist/tools/tool-loop.js +362 -2
  148. package/dist/tools/tool-loop.js.map +1 -1
  149. package/dist/web-dashboard/chat-console.d.ts +8 -0
  150. package/dist/web-dashboard/chat-console.d.ts.map +1 -1
  151. package/dist/web-dashboard/chat-console.js +9 -0
  152. package/dist/web-dashboard/chat-console.js.map +1 -1
  153. package/dist/web-dashboard/chat-retry.d.ts.map +1 -1
  154. package/dist/web-dashboard/chat-retry.js +10 -2
  155. package/dist/web-dashboard/chat-retry.js.map +1 -1
  156. package/dist/web-dashboard/server.d.ts.map +1 -1
  157. package/dist/web-dashboard/server.js +80 -8
  158. package/dist/web-dashboard/server.js.map +1 -1
  159. package/dist/web-dashboard/src/types.d.ts +81 -4
  160. package/dist/web-dashboard/src/types.d.ts.map +1 -1
  161. package/package.json +1 -1
  162. package/src/web-dashboard/public/assets/{index-Co7Hk2FT.js → index-kCUkORm7.js} +2 -2
  163. package/src/web-dashboard/public/assets/{index-Co7Hk2FT.js.map → index-kCUkORm7.js.map} +1 -1
  164. package/src/web-dashboard/public/index.html +1 -1
@@ -0,0 +1,350 @@
1
+ /**
2
+ * Unattended jobs — the engine that finishes long work WITHOUT the user having
3
+ * to say "continue" (enterprise-grade hardening, G11).
4
+ *
5
+ * THE BUG THIS CLOSES. The long-form ledger (G8) made a 100-page book
6
+ * *possible*: it split the ask into bounded units and recorded progress. But it
7
+ * left the CADENCE manual. Every batch ended with
8
+ *
9
+ * "Reply \"continue\" and I will write the next batch"
10
+ *
11
+ * so a 39-unit book needed ~10 human turns. The user asked for a book and got a
12
+ * job they had to keep pressing. That is a shortcut, not a delivery: "write me
13
+ * a 100-page book" is itself the authorization to spend the time, and an
14
+ * assistant that stops after 4 of 39 units to ask whether to continue has
15
+ * substituted a protocol for the work.
16
+ *
17
+ * WHAT THIS MODULE IS. A persisted queue of IN-PROGRESS WORK, plus a runner
18
+ * that keeps executing it until it is done, blocked on a genuine question, or
19
+ * out of its own time budget. It is deliberately NOT the retry queue
20
+ * (`deferred-task.ts`):
21
+ *
22
+ * | | deferred-task | unattended-job |
23
+ * |---|---|---|
24
+ * | triggered by | a FAILURE | unfinished WORK |
25
+ * | authorization | the user replying "yes" | the original ask |
26
+ * | wait shape | backoff between attempts | run continuously |
27
+ * | budget | ~6h of retries | hours of actual work (default 10h) |
28
+ * | stops on | attempts/TTL | completion, a real question, or no progress |
29
+ *
30
+ * Merging the two would make "keep retrying the model" and "keep writing the
31
+ * book" the same switch, and the consent semantics of each are opposites.
32
+ *
33
+ * THREE GUARANTEES THE RUNNER ENFORCES
34
+ * 1. PROGRESS IS MEASURED, NOT CLAIMED. A batch that did not move the ledger
35
+ * is a stall even if every step reported success. Three stalls in a row
36
+ * stop the run and ask, because an agent looping without progress is the
37
+ * exact "goes in a loop and never delivers" behaviour this exists to end.
38
+ * 2. IT STOPS FOR QUESTIONS, NOT FOR PERMISSION. The only thing that pauses
39
+ * work is a decision the user genuinely owns (see `autonomy-policy.ts`).
40
+ * 3. IT NEVER RUNS UNBOUNDED. A deadline (default 10 hours), a stall cap, a
41
+ * failure cap and a per-drain batch cap.
42
+ *
43
+ * Storage: `<memory>/unattended-jobs.json`. Best-effort writes — bookkeeping
44
+ * must never break the turn that scheduled the work.
45
+ */
46
+ /**
47
+ * How long a job may keep working before it gives up and reports.
48
+ *
49
+ * Ten hours because the ask this module exists for is "a 100/200-page book" or
50
+ * "a phased build", and the user's requirement is explicit: those must run to
51
+ * completion unattended rather than in 4-turn increments. It is a CEILING, not
52
+ * a target — a job that finishes in ten minutes leaves the queue immediately.
53
+ */
54
+ export declare const DEFAULT_DEADLINE_MS: number;
55
+ /** Consecutive no-progress batches before the run stops and asks. */
56
+ export declare const MAX_STALLED_BATCHES = 3;
57
+ /** Consecutive hard failures (provider errors, verification failures). */
58
+ export declare const MAX_CONSECUTIVE_FAILURES = 6;
59
+ /** Batches one drain may run before yielding (keeps a tick responsive). */
60
+ export declare const MAX_BATCHES_PER_DRAIN = 6;
61
+ /**
62
+ * How long a job may sit in `running` before it is treated as abandoned.
63
+ *
64
+ * A batch is claimed before it runs; if the process dies mid-batch — a restart,
65
+ * a reboot, a crash, all normal over a ten-hour job — nothing resets it and a
66
+ * `running` job is invisible to every query. The work would be stranded
67
+ * silently, which is the failure mode the whole ledger exists to prevent. The
68
+ * ceiling is generous (well past a single batch) so a live batch is never
69
+ * stolen.
70
+ */
71
+ export declare const STALE_RUNNING_MS: number;
72
+ /** What kind of ongoing work this is. */
73
+ export type UnattendedKind = 'long-form' | 'phased';
74
+ export type UnattendedStatus = 'pending' | 'running' | 'done' | 'blocked' | 'failed' | 'cancelled';
75
+ /** Where a job's progress must be reported. */
76
+ export interface UnattendedSurface {
77
+ /** `dashboard`, `cli`, `whatsapp`, … — the drain is ownership-filtered on this. */
78
+ platform: string;
79
+ /** Session id / channel id the report goes to. */
80
+ channelId: string;
81
+ }
82
+ /** One unit of ongoing work, as much as the runner needs to keep it going. */
83
+ export interface UnattendedJob {
84
+ id: string;
85
+ kind: UnattendedKind;
86
+ /** The ORIGINAL ask, verbatim — a batch re-states it so intent survives hours. */
87
+ goal: string;
88
+ /** Absolute project root the work happens in. */
89
+ projectPath: string;
90
+ /** Where to report. */
91
+ surface: UnattendedSurface;
92
+ /**
93
+ * What to send the engine to make it do the next batch.
94
+ *
95
+ * Usually "continue", which the long-form planner resolves against the ledger
96
+ * (so a batch never restarts the book). Kept as data rather than hard-coded
97
+ * so a phased build can carry a richer brief.
98
+ */
99
+ continuationPrompt: string;
100
+ createdAt: number;
101
+ updatedAt: number;
102
+ lastRunAt: number;
103
+ /** Absolute epoch ms after which the job stops and reports. */
104
+ deadline: number;
105
+ /** Batches executed. */
106
+ batches: number;
107
+ /** Consecutive batches that produced no measurable progress. */
108
+ stalledBatches: number;
109
+ /** Consecutive hard failures. */
110
+ failures: number;
111
+ status: UnattendedStatus;
112
+ /** Last MEASURED completion, 0–100 (from the ledgers, not from a claim). */
113
+ progress: number;
114
+ /** Human-readable progress, e.g. "chapter 12/39 · 10,800 words". */
115
+ progressLine?: string;
116
+ /** Why it stopped, when it did not finish. */
117
+ stopReason?: string;
118
+ /** The one question blocking the run, when status is `blocked`. */
119
+ pendingQuestion?: string;
120
+ /** Report progress to the user as the job runs (off for silent builds). */
121
+ notify: boolean;
122
+ /**
123
+ * Total spend across the job's batches (USD), summed from MEASURED windows.
124
+ * Undefined until a surface reports economy data — never defaulted to 0, so
125
+ * "free" and "not measured" stay distinguishable in a report.
126
+ */
127
+ costUsd?: number;
128
+ /** Total tokens across the job's batches (measured windows). */
129
+ tokens?: number;
130
+ /** Per-batch economy and duration, oldest first (bounded to MAX_BATCH_STATS). */
131
+ batchStats?: BatchStat[];
132
+ /**
133
+ * Files that must ALL exist for the deliverable to count as finished.
134
+ *
135
+ * Set by a composite plan (site + chapters + optional tools). The progress
136
+ * measurement treats their presence as part of completion, so "the prose
137
+ * phase finished" is never reported as "the deliverable is done" when the
138
+ * experience layer is still missing.
139
+ */
140
+ expectedArtifacts?: string[];
141
+ }
142
+ /**
143
+ * One batch's measured economy and duration, kept for the run report (G27).
144
+ *
145
+ * Recorded for EVERY batch, including failures: a failed batch still spent
146
+ * tokens, and hiding its cost is exactly the accounting gap that makes a long
147
+ * unattended run's bill a surprise.
148
+ */
149
+ export interface BatchStat {
150
+ /** 1-based batch number within the job. */
151
+ index: number;
152
+ /** Measured completion 0–100 after the batch. */
153
+ progress: number;
154
+ /** Human-readable progress line after the batch. */
155
+ progressLine?: string;
156
+ /** Measured spend for this batch's window (USD). */
157
+ costUsd?: number;
158
+ /** Measured tokens for this batch's window. */
159
+ tokens?: number;
160
+ /** Wall-clock duration of the batch. */
161
+ durationMs?: number;
162
+ /** Short failure reason, when the batch failed. */
163
+ error?: string;
164
+ }
165
+ /** What a surface tells the store after running one batch. */
166
+ export interface BatchOutcome {
167
+ /**
168
+ * Measured completion 0–100, read from the ledgers/artifacts.
169
+ *
170
+ * MUST be measured: this is what separates a slow-but-working job from a
171
+ * loop, and an agent-reported number would defeat the whole check.
172
+ */
173
+ progress?: number;
174
+ /** Human-readable progress line, e.g. "chapter 12/39 complete". */
175
+ progressLine?: string;
176
+ /** The work is finished — the deliverable exists. */
177
+ finished?: boolean;
178
+ /** A genuine decision the run cannot make for the user (from the policy). */
179
+ question?: string;
180
+ /** The batch failed (provider error, verification failure). */
181
+ error?: string;
182
+ /** Wall-clock duration of the batch in ms (measured by the surface). */
183
+ durationMs?: number;
184
+ /** Spend during the batch window (USD), measured from the cost ledger. */
185
+ costUsd?: number;
186
+ /** Tokens during the batch window, measured from the cost ledger. */
187
+ tokens?: number;
188
+ }
189
+ /** Everything needed to schedule ongoing work. */
190
+ export interface StartUnattendedInput {
191
+ kind: UnattendedKind;
192
+ goal: string;
193
+ projectPath: string;
194
+ surface: UnattendedSurface;
195
+ continuationPrompt?: string;
196
+ /** Override the time budget (tests use a short one). */
197
+ deadlineMs?: number;
198
+ notify?: boolean;
199
+ /** Files that must all exist for the job to count as finished. */
200
+ expectedArtifacts?: string[];
201
+ }
202
+ /** Read the queue. Best-effort: a corrupt file is an empty queue, never a throw. */
203
+ export declare function loadUnattendedJobs(now?: number): UnattendedJob[];
204
+ /**
205
+ * Schedule ongoing work — or return the job already carrying it.
206
+ *
207
+ * Idempotent per (kind, project, surface) on purpose: every batch of a book
208
+ * re-enters this function, and treating each re-entry as a new job would spawn
209
+ * a duplicate worker per batch and have them race on the same chapters.
210
+ */
211
+ export declare function startUnattendedJob(input: StartUnattendedInput): {
212
+ job: UnattendedJob;
213
+ created: boolean;
214
+ };
215
+ export declare function getUnattendedJob(id: string): UnattendedJob | undefined;
216
+ /** The live job for a surface (newest first), if any. */
217
+ export declare function findUnattendedJob(surface: UnattendedSurface): UnattendedJob | undefined;
218
+ /** Every job still waiting for a turn (for status surfaces, newest first). */
219
+ export declare function listUnattendedJobs(): UnattendedJob[];
220
+ /**
221
+ * One drain OWNS a subset of the queue.
222
+ *
223
+ * The store is shared by every process that can run a turn, so each drain
224
+ * declares what it owns — without this the gateway would claim a dashboard
225
+ * session and try to deliver a book chapter to a messaging platform.
226
+ */
227
+ export type JobOwnership = (job: UnattendedJob) => boolean;
228
+ /**
229
+ * Jobs ready to run now: pending, inside their deadline, and not out of road.
230
+ *
231
+ * `blocked` jobs are deliberately excluded — they are waiting on the user, not
232
+ * on the scheduler.
233
+ */
234
+ export declare function dueUnattendedJobs(now?: number, owns?: JobOwnership): UnattendedJob[];
235
+ /** Jobs whose time budget ran out — the user must be told, not ghosted. */
236
+ export declare function expiredUnattendedJobs(now?: number, owns?: JobOwnership): UnattendedJob[];
237
+ /**
238
+ * Stop a job with a reason, without touching its counters.
239
+ *
240
+ * Used by the runner to expire jobs whose time budget ran out — the reason
241
+ * must be RECORDED (the user is told why the promised work stopped), and doing
242
+ * it here keeps the runner free of ledger-write logic.
243
+ */
244
+ export declare function stopUnattendedJob(id: string, status: Extract<UnattendedStatus, 'failed' | 'cancelled' | 'done'>, reason: string, now?: number): UnattendedJob | undefined;
245
+ /** Stop a job (the user said stop, or the work is being replaced). */
246
+ export declare function cancelUnattendedJob(id: string, reason?: string): void;
247
+ /** Drop every job for a surface (`stop`, `cancel`, a fresh unrelated ask). */
248
+ export declare function cancelUnattendedJobsFor(surface: UnattendedSurface, reason?: string): number;
249
+ /** Claim a job for one batch. Returns the claimed job, or undefined. */
250
+ export declare function claimUnattendedJob(id: string, now?: number): UnattendedJob | undefined;
251
+ /**
252
+ * Record what one batch actually did, and decide what happens next.
253
+ *
254
+ * This is where "no manual cadence" is enforced: the batch's own outcome
255
+ * determines whether the job keeps running, stops because it is DONE, or stops
256
+ * because it needs the user — nobody has to say "continue".
257
+ *
258
+ * @returns the updated job (undefined when the id is unknown).
259
+ */
260
+ export declare function recordBatchOutcome(id: string, outcome: BatchOutcome, now?: number): UnattendedJob | undefined;
261
+ /** Resume a blocked job after the user answered. */
262
+ export declare function resumeUnattendedJob(id: string, extraDeadlineMs?: number, now?: number): UnattendedJob | undefined;
263
+ /** Percentage complete, clamped. */
264
+ export declare function jobPercent(job: UnattendedJob): number;
265
+ /** A compact human duration (`850ms`, `12.4s`, `3m 07s`, `1h 12m`). */
266
+ export declare function formatDuration(ms: number): string;
267
+ /**
268
+ * Per-batch cost and latency report for an unattended run (G27).
269
+ *
270
+ * WHY. The run reported a batch COUNT and a percentage, which answers neither
271
+ * of the two questions a long unattended job actually raises: what did it
272
+ * cost, and is it slowing down. Those had to be reconstructed by hand from the
273
+ * cost ledger afterwards.
274
+ *
275
+ * HONESTY. A dash means the surface did not measure that column — never a
276
+ * fabricated 0, which would read as "free" for a batch that simply was not
277
+ * metered. Token/cost columns come from the persisted cost ledger's timestamps
278
+ * (see `costSince`), so a resumed job in a new process reports accurately.
279
+ *
280
+ * @returns a printable block, or '' when no batch measured anything.
281
+ */
282
+ export declare function formatBatchReport(job: UnattendedJob): string;
283
+ /**
284
+ * The honest status line for a job.
285
+ *
286
+ * Deliberately quotes MEASURED progress and says explicitly that no reply is
287
+ * needed — the user's complaint was having to reply at all, so a progress
288
+ * report that ends by asking for one would repeat the mistake in miniature.
289
+ */
290
+ export declare function unattendedStatusLine(job: UnattendedJob): string;
291
+ /** How long the job may still run, in ms (0 when the budget is spent). */
292
+ export declare function remainingBudgetMs(job: UnattendedJob, now?: number): number;
293
+ /** Test/reset hook. */
294
+ export declare function clearUnattendedJobs(): void;
295
+ /** What a surface must supply to have its work continued. */
296
+ export interface UnattendedRunnerDeps {
297
+ /**
298
+ * Run ONE batch of the job, and report what it did.
299
+ *
300
+ * The surface owns the turn (it knows how to reach its engine); the runner
301
+ * owns the bookkeeping. The returned outcome MUST be measured from the
302
+ * artifacts, not from what the agent claimed.
303
+ */
304
+ runBatch: (job: UnattendedJob) => Promise<BatchOutcome>;
305
+ /** A user-facing line about the job (progress, completion, a question). */
306
+ notify?: (job: UnattendedJob, line: string) => void | Promise<void>;
307
+ /**
308
+ * Is the surface busy for this job? A batch waits rather than colliding with
309
+ * a live turn (which the surface would reject), losing nothing.
310
+ */
311
+ isBusy?: (job: UnattendedJob) => boolean;
312
+ /** Which jobs this drain owns (default: all). */
313
+ owns?: JobOwnership;
314
+ now?: () => number;
315
+ /** Batches per drain — higher means a tick finishes more of a long job. */
316
+ maxBatchesPerDrain?: number;
317
+ }
318
+ /**
319
+ * The unattended continuation loop.
320
+ *
321
+ * One instance per surface process. `drain()` is the periodic tick: it expires
322
+ * anything out of time, reports it, then runs whatever is due — looping so a
323
+ * single tick advances a long job as far as its budget allows instead of one
324
+ * chapter per tick. Drains are serialized through an internal chain, because
325
+ * two overlapping drains would run the same job twice and race on the same
326
+ * files (exactly how the first end-to-end run produced four copies of the last
327
+ * chapter).
328
+ */
329
+ export declare class UnattendedRunner {
330
+ private readonly deps;
331
+ private chain;
332
+ private active;
333
+ constructor(deps: UnattendedRunnerDeps);
334
+ private now;
335
+ /** Is a drain currently running? Status surfaces use this to show activity. */
336
+ get isRunning(): boolean;
337
+ /** The jobs this runner would pick up right now. */
338
+ due(): UnattendedJob[];
339
+ /**
340
+ * Advance every due job as far as one tick may.
341
+ *
342
+ * @returns how many batches were run.
343
+ */
344
+ drain(): Promise<number>;
345
+ private lastBatches;
346
+ private runOnce;
347
+ /** A notification must never break the run that produced it. */
348
+ private safeNotify;
349
+ }
350
+ //# sourceMappingURL=unattended-job.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"unattended-job.d.ts","sourceRoot":"","sources":["../../src/learning/unattended-job.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAQH;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,QAAiB,CAAC;AAElD,qEAAqE;AACrE,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC,0EAA0E;AAC1E,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAE1C,2EAA2E;AAC3E,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,QAAc,CAAC;AAkB5C,yCAAyC;AACzC,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG,QAAQ,CAAC;AAEpD,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,WAAW,CAAC;AAEnG,+CAA+C;AAC/C,MAAM,WAAW,iBAAiB;IAChC,mFAAmF;IACnF,QAAQ,EAAE,MAAM,CAAC;IACjB,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,8EAA8E;AAC9E,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,cAAc,CAAC;IACrB,kFAAkF;IAClF,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB,uBAAuB;IACvB,OAAO,EAAE,iBAAiB,CAAC;IAC3B;;;;;;OAMG;IACH,kBAAkB,EAAE,MAAM,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAC;IACjB,wBAAwB;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,cAAc,EAAE,MAAM,CAAC;IACvB,iCAAiC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,gBAAgB,CAAC;IACzB,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,8CAA8C;IAC9C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,2EAA2E;IAC3E,MAAM,EAAE,OAAO,CAAC;IAChB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,UAAU,CAAC,EAAE,SAAS,EAAE,CAAC;IACzB;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC9B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,SAAS;IACxB,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,oDAAoD;IACpD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+CAA+C;IAC/C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,8DAA8D;AAC9D,MAAM,WAAW,YAAY;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,kDAAkD;AAClD,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,cAAc,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,iBAAiB,CAAC;IAC3B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,wDAAwD;IACxD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,kEAAkE;IAClE,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC9B;AAmED,oFAAoF;AACpF,wBAAgB,kBAAkB,CAAC,GAAG,GAAE,MAAmB,GAAG,aAAa,EAAE,CAU5E;AAkCD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,oBAAoB,GAAG;IAAE,GAAG,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAuCxG;AAED,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAEtE;AAED,yDAAyD;AACzD,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,iBAAiB,GAAG,aAAa,GAAG,SAAS,CAOvF;AAED,8EAA8E;AAC9E,wBAAgB,kBAAkB,IAAI,aAAa,EAAE,CAEpD;AAED;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC;AAE3D;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,MAAmB,EAAE,IAAI,GAAE,YAAyB,GAAG,aAAa,EAAE,CAS5G;AAED,2EAA2E;AAC3E,wBAAgB,qBAAqB,CAAC,GAAG,GAAE,MAAmB,EAAE,IAAI,GAAE,YAAyB,GAAG,aAAa,EAAE,CAEhH;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,OAAO,CAAC,gBAAgB,EAAE,QAAQ,GAAG,WAAW,GAAG,MAAM,CAAC,EAClE,MAAM,EAAE,MAAM,EACd,GAAG,GAAE,MAAmB,GACvB,aAAa,GAAG,SAAS,CAU3B;AAED,sEAAsE;AACtE,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,SAA0B,GAAG,IAAI,CAQtF;AAED,8EAA8E;AAC9E,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,iBAAiB,EAAE,MAAM,SAA0B,GAAG,MAAM,CAa5G;AAED,wEAAwE;AACxE,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,GAAE,MAAmB,GAAG,aAAa,GAAG,SAAS,CASlG;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,YAAY,EACrB,GAAG,GAAE,MAAmB,GACvB,aAAa,GAAG,SAAS,CAiG3B;AAED,oDAAoD;AACpD,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,MAAM,EAAE,eAAe,SAAI,EAAE,GAAG,GAAE,MAAmB,GAAG,aAAa,GAAG,SAAS,CAexH;AAID,oCAAoC;AACpC,wBAAgB,UAAU,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAErD;AAOD,uEAAuE;AACvE,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CASjD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAmC5D;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAkB/D;AAED,0EAA0E;AAC1E,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,aAAa,EAAE,GAAG,GAAE,MAAmB,GAAG,MAAM,CAEtF;AAED,uBAAuB;AACvB,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAID,6DAA6D;AAC7D,MAAM,WAAW,oBAAoB;IACnC;;;;;;OAMG;IACH,QAAQ,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;IACxD,2EAA2E;IAC3E,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE;;;OAGG;IACH,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC;IACzC,iDAAiD;IACjD,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,2EAA2E;IAC3E,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;;;GAUG;AACH,qBAAa,gBAAgB;IAIf,OAAO,CAAC,QAAQ,CAAC,IAAI;IAHjC,OAAO,CAAC,KAAK,CAAoC;IACjD,OAAO,CAAC,MAAM,CAAS;gBAEM,IAAI,EAAE,oBAAoB;IAEvD,OAAO,CAAC,GAAG;IAIX,+EAA+E;IAC/E,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,oDAAoD;IACpD,GAAG,IAAI,aAAa,EAAE;IAItB;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;IAM9B,OAAO,CAAC,WAAW,CAAK;YAEV,OAAO;IAwCrB,gEAAgE;YAClD,UAAU;CAQzB"}