@vercel/factory 0.0.12 → 0.0.14

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 (57) hide show
  1. package/README.md +1 -1
  2. package/dist/api.d.mts +225 -0
  3. package/dist/api.mjs +312 -0
  4. package/dist/api.mjs.map +1 -0
  5. package/dist/{approval-DdvEKLiE.mjs → approval-JX2Px9IC.mjs} +2 -2
  6. package/dist/{approval-DdvEKLiE.mjs.map → approval-JX2Px9IC.mjs.map} +1 -1
  7. package/dist/blob/index.d.mts +4 -3
  8. package/dist/blob/index.mjs +21 -15
  9. package/dist/blob/index.mjs.map +1 -1
  10. package/dist/budget-DzSiIA4t.mjs +42 -0
  11. package/dist/budget-DzSiIA4t.mjs.map +1 -0
  12. package/dist/build-factory.d.mts +1 -1
  13. package/dist/build-factory.mjs +1 -1
  14. package/dist/change-D2U6v7Ek.mjs +554 -0
  15. package/dist/change-D2U6v7Ek.mjs.map +1 -0
  16. package/dist/communication-Kd9nU5RP.mjs +30 -0
  17. package/dist/communication-Kd9nU5RP.mjs.map +1 -0
  18. package/dist/connectors/index.d.mts +3 -2
  19. package/dist/connectors/index.mjs +53 -26
  20. package/dist/connectors/index.mjs.map +1 -1
  21. package/dist/connectors/slack.d.mts +17 -6
  22. package/dist/connectors/slack.mjs +99 -32
  23. package/dist/connectors/slack.mjs.map +1 -1
  24. package/dist/coordination-Cq08hb1l.mjs +76 -0
  25. package/dist/coordination-Cq08hb1l.mjs.map +1 -0
  26. package/dist/dispatch-BaZS3PT8.d.mts +76 -0
  27. package/dist/{driver-CrZsy7sm.d.mts → driver-BC0Mt5KG.d.mts} +2 -2
  28. package/dist/driver-Bbd25rNM.mjs.map +1 -1
  29. package/dist/engine-DFHU2Pe-.d.mts +781 -0
  30. package/dist/engine-WaUM2cGA.mjs +1068 -0
  31. package/dist/engine-WaUM2cGA.mjs.map +1 -0
  32. package/dist/eve/index.d.mts +289 -153
  33. package/dist/eve/index.mjs +378 -89
  34. package/dist/eve/index.mjs.map +1 -1
  35. package/dist/{factory-config-ifd3JxiU.mjs → factory-config-BoRXOw43.mjs} +23 -22
  36. package/dist/factory-config-BoRXOw43.mjs.map +1 -0
  37. package/dist/{factory-config-Bu4mklm9.d.mts → factory-config-D2yU3G0c.d.mts} +21 -2
  38. package/dist/{github-wThBfbm-.d.mts → github-C5HNBN6p.d.mts} +34 -3
  39. package/dist/github.d.mts +2 -2
  40. package/dist/github.mjs +61 -1
  41. package/dist/github.mjs.map +1 -1
  42. package/dist/{id-DwCihQr4.mjs → id-BLIkCVue.mjs} +4 -2
  43. package/dist/{id-DwCihQr4.mjs.map → id-BLIkCVue.mjs.map} +1 -1
  44. package/dist/index-Bw6hggoH.d.mts +40 -0
  45. package/dist/index.d.mts +291 -61
  46. package/dist/index.mjs +140 -783
  47. package/dist/index.mjs.map +1 -1
  48. package/dist/postgres/index.d.mts +1 -1
  49. package/dist/task-CcOyOJ3k.mjs +154 -0
  50. package/dist/task-CcOyOJ3k.mjs.map +1 -0
  51. package/package.json +5 -1
  52. package/dist/approval-CIXB8IF8.d.mts +0 -522
  53. package/dist/change-CFNGXVqD.mjs +0 -230
  54. package/dist/change-CFNGXVqD.mjs.map +0 -1
  55. package/dist/factory-config-ifd3JxiU.mjs.map +0 -1
  56. package/dist/index-Cy4jfXh5.d.mts +0 -67
  57. package/dist/signal-CHVEmzvI.d.mts +0 -59
package/dist/index.d.mts CHANGED
@@ -1,8 +1,173 @@
1
- import { a as StoredEntry, i as StoreDriver, n as RecordExistsError, o as StoredRecord, r as RecordNotFoundError, s as VersionConflictError, t as CollectionName } from "./driver-CrZsy7sm.mjs";
2
- import { a as factoryConfigSchema, i as factoryConfigRepositorySchema, n as FactoryConfigInput, r as defineFactory, t as FactoryConfig } from "./factory-config-Bu4mklm9.mjs";
3
- import { a as signalSchema, c as ReplyTo, d as replyToSchema, f as schemaVersionSchema, i as signalOutcomeSchema, l as SCHEMA_VERSION, m as vocabularySchema, n as SignalOutcome, o as signalSourceSchema, p as usdSchema, r as SignalSource, s as standardSignalSources, t as Signal, u as isoDateTimeSchema } from "./signal-CHVEmzvI.mjs";
4
- import { $ as Cost, A as FactoryStores, At as repositoryIdsSchema, B as standardTaskKinds, C as ChangePatch, Ct as RepositoryId, D as CreateStoresOptions, Dt as factoryIdSchema, E as CreateSignalInput, Et as changeIdSchema, F as TaskApproval, G as taskOriginSchema, H as taskDevboxSchema, I as TaskKind, J as taskStateSchema, K as taskQuestionSchema, L as TaskState, M as TaskTransitionOptions, Mt as taskIdSchema, N as createStores, O as CreateTaskInput, Ot as receiptIdSchema, P as Task, Q as repositorySlugSchema, R as coordinationRepositoryIdsSchema, S as ChangeAssociationError, St as ReceiptId, T as CreateChangeInput, Tt as TaskId, U as taskExecutionRepositoryIdsSchema, V as taskApprovalSchema, W as taskKindSchema, X as RepositorySlug, Y as Repository, Z as repositorySchema, _ as findingVerificationMethodSchema, _t as changeSchema, a as approvalRuleSchema, at as receiptKindSchema, b as ApprovalDecision, bt as ChangeId, c as Finding, ct as receiptStateSchema, d as FindingVerification, dt as standardReceiptStates, et as Receipt, f as findingCategorySchema, ft as Change, g as findingVerificationLevelSchema, gt as changeEvidenceSchema, h as findingSchema, ht as Level, i as approvalPolicySchema, it as costSchema, j as TaskPatch, jt as signalIdSchema, k as DecideSignalOptions, kt as repositoryIdSchema, l as FindingCategory, lt as standardReceiptKinds, m as findingPrioritySchema, mt as ChangeState, n as ApprovalRule, nt as ReceiptPhase, o as defaultApprovalPolicy, ot as receiptPhaseSchema, p as findingFingerprint, pt as ChangeEvidence, q as taskSchema, r as ApprovalSubject, rt as ReceiptState, s as requiresApproval, st as receiptSchema, t as ApprovalPolicy, tt as ReceiptKind, u as FindingPriority, ut as standardReceiptPhases, v as findingVerificationSchema, vt as changeStateSchema, w as ChangeTransitionOptions, wt as SignalId, x as ApprovalError, xt as FactoryId, y as AppendReceiptInput, yt as levelSchema, z as harnessSchema } from "./approval-CIXB8IF8.mjs";
1
+ import { a as DispatchRefusedError, c as AgentRouteInput, d as defineAgentRoutes, i as DispatchOptions, l as AgentRouteRegistry, n as DEFAULT_MAX_LAUNCH_ATTEMPTS, o as dispatchTask, r as DispatchBudget, s as AgentRoute, t as BudgetExhaustedError, u as agentRouteSchema } from "./dispatch-BaZS3PT8.mjs";
2
+ import { $ as Change, $t as outboxIdSchema, A as standardSignalSources, At as coordinationRepositoryIdsSchema, B as costSchema, Bt as taskStateSchema, C as createStores, Ct as answerEventSchema, D as signalOutcomeSchema, Dt as TaskKind, E as SignalSource, Et as TaskApproval, F as Cost, Ft as taskExecutionRepositoryIdsSchema, G as standardReceiptKinds, Gt as OutboxId, H as receiptPhaseSchema, Ht as AnswerId, I as Receipt, It as taskKindSchema, J as OutboxMessage, Jt as SignalId, K as standardReceiptPhases, Kt as ReceiptId, L as ReceiptKind, Lt as taskOriginSchema, M as RepositorySlug, Mt as harnessSchema, N as repositorySchema, Nt as standardTaskKinds, O as signalSchema, Ot as TaskState, P as repositorySlugSchema, Pt as taskApprovalSchema, Q as outboxStateSchema, Qt as factoryIdSchema, R as ReceiptPhase, Rt as taskQuestionSchema, S as TaskTransitionOptions, St as AnswerEvent, T as SignalOutcome, Tt as Task, U as receiptSchema, Ut as ChangeId, V as receiptKindSchema, Vt as taskUsageSchema, W as receiptStateSchema, Wt as FactoryId, X as outboxMessageSchema, Xt as answerIdSchema, Y as OutboxQueue, Yt as TaskId, Z as outboxQueueSchema, Zt as changeIdSchema, _ as SessionConflictError, _t as usdSchema, a as ApprovalError, an as Budget, at as changeStateSchema, b as StepUsage, bt as agentSessionIdSchema, c as ChangeTransitionOptions, cn as budgetMonthSchema, ct as CommunicationOutcome, d as CreateStoresOptions, dt as communicationOutcomes, en as receiptIdSchema, et as ChangeEvidence, f as CreateTaskInput, ft as ReplyTo, g as OutboxEventConflictError, gt as schemaVersionSchema, h as FactoryStores, ht as replyToSchema, i as ApprovalDecision, in as taskIdSchema, it as changeSchema, j as Repository, jt as executionReferenceSchema, k as signalSourceSchema, kt as TaskUsage, l as CreateChangeInput, ln as budgetSchema, lt as communicationEventSchema, m as EnsureBudgetInput, mt as isoDateTimeSchema, n as AnswerQuestionInput, nn as repositoryIdsSchema, nt as Level, o as ChangeAssociationError, on as BudgetLimits, ot as levelSchema, p as DecideSignalOptions, pt as SCHEMA_VERSION, q as standardReceiptStates, qt as RepositoryId, r as AppendReceiptInput, rn as signalIdSchema, rt as changeEvidenceSchema, s as ChangePatch, sn as budgetLimitsSchema, st as CommunicationEvent, t as AnswerEventConflictError, tn as repositoryIdSchema, tt as ChangeState, u as CreateSignalInput, ut as communicationOutcomeSchema, v as SettleTaskOptions, vt as vocabularySchema, w as Signal, wt as ExecutionReference, x as TaskPatch, xt as agentSessionSchema, y as SettlementError, yt as AgentSession, z as ReceiptState, zt as taskSchema } from "./engine-DFHU2Pe-.mjs";
3
+ import { a as StoredEntry, i as StoreDriver, n as RecordExistsError, o as StoredRecord, r as RecordNotFoundError, s as VersionConflictError, t as CollectionName } from "./driver-BC0Mt5KG.mjs";
4
+ import { a as defineFactory, c as factoryConfigSchema, i as defaultExecutionPolicy, n as FactoryConfig, o as executionPolicySchema, r as FactoryConfigInput, s as factoryConfigRepositorySchema, t as ExecutionPolicy } from "./factory-config-D2yU3G0c.mjs";
5
5
  import { z } from "zod";
6
+ //#region src/schema/finding.d.ts
7
+ declare const findingPrioritySchema: z.ZodEnum<{
8
+ P0: "P0";
9
+ P1: "P1";
10
+ P2: "P2";
11
+ P3: "P3";
12
+ }>;
13
+ declare const findingCategorySchema: z.ZodEnum<{
14
+ security: "security";
15
+ correctness: "correctness";
16
+ reliability: "reliability";
17
+ performance: "performance";
18
+ compatibility: "compatibility";
19
+ accessibility: "accessibility";
20
+ documentation: "documentation";
21
+ maintainability: "maintainability";
22
+ testing: "testing";
23
+ usability: "usability";
24
+ }>;
25
+ declare const findingVerificationLevelSchema: z.ZodEnum<{
26
+ unverified: "unverified";
27
+ supported: "supported";
28
+ confirmed: "confirmed";
29
+ }>;
30
+ declare const findingVerificationMethodSchema: z.ZodEnum<{
31
+ documentation: "documentation";
32
+ code_inspection: "code_inspection";
33
+ static_analysis: "static_analysis";
34
+ manual_reproduction: "manual_reproduction";
35
+ unit_test: "unit_test";
36
+ integration_test: "integration_test";
37
+ e2e_test: "e2e_test";
38
+ runtime_observation: "runtime_observation";
39
+ }>;
40
+ /**
41
+ * What was done to check the finding. Forces a reporter to distinguish "I
42
+ * think this is a problem" from "I demonstrated it", which is the axis a human
43
+ * approving fixes cares about most.
44
+ */
45
+ declare const findingVerificationSchema: z.ZodObject<{
46
+ level: z.ZodEnum<{
47
+ unverified: "unverified";
48
+ supported: "supported";
49
+ confirmed: "confirmed";
50
+ }>;
51
+ method: z.ZodEnum<{
52
+ documentation: "documentation";
53
+ code_inspection: "code_inspection";
54
+ static_analysis: "static_analysis";
55
+ manual_reproduction: "manual_reproduction";
56
+ unit_test: "unit_test";
57
+ integration_test: "integration_test";
58
+ e2e_test: "e2e_test";
59
+ runtime_observation: "runtime_observation";
60
+ }>;
61
+ summary: z.ZodString;
62
+ limitations: z.ZodOptional<z.ZodString>;
63
+ }, z.core.$strict>;
64
+ /** A single problem found in a repository, as a scanner or agent reports it. */
65
+ declare const findingSchema: z.ZodObject<{
66
+ title: z.ZodString;
67
+ body: z.ZodString;
68
+ path: z.ZodOptional<z.ZodString>;
69
+ line: z.ZodOptional<z.ZodNumber>;
70
+ endLine: z.ZodOptional<z.ZodNumber>;
71
+ priority: z.ZodEnum<{
72
+ P0: "P0";
73
+ P1: "P1";
74
+ P2: "P2";
75
+ P3: "P3";
76
+ }>;
77
+ category: z.ZodEnum<{
78
+ security: "security";
79
+ correctness: "correctness";
80
+ reliability: "reliability";
81
+ performance: "performance";
82
+ compatibility: "compatibility";
83
+ accessibility: "accessibility";
84
+ documentation: "documentation";
85
+ maintainability: "maintainability";
86
+ testing: "testing";
87
+ usability: "usability";
88
+ }>;
89
+ verification: z.ZodObject<{
90
+ level: z.ZodEnum<{
91
+ unverified: "unverified";
92
+ supported: "supported";
93
+ confirmed: "confirmed";
94
+ }>;
95
+ method: z.ZodEnum<{
96
+ documentation: "documentation";
97
+ code_inspection: "code_inspection";
98
+ static_analysis: "static_analysis";
99
+ manual_reproduction: "manual_reproduction";
100
+ unit_test: "unit_test";
101
+ integration_test: "integration_test";
102
+ e2e_test: "e2e_test";
103
+ runtime_observation: "runtime_observation";
104
+ }>;
105
+ summary: z.ZodString;
106
+ limitations: z.ZodOptional<z.ZodString>;
107
+ }, z.core.$strict>;
108
+ tool: z.ZodOptional<z.ZodString>;
109
+ ruleId: z.ZodOptional<z.ZodString>;
110
+ }, z.core.$strict>;
111
+ type FindingPriority = z.infer<typeof findingPrioritySchema>;
112
+ type FindingCategory = z.infer<typeof findingCategorySchema>;
113
+ type FindingVerification = z.infer<typeof findingVerificationSchema>;
114
+ type Finding = z.infer<typeof findingSchema>;
115
+ /**
116
+ * Stable identity of a finding across scans, used as the signal's delivery id
117
+ * so re-reporting is a no-op instead of a second task. A scanner finding is
118
+ * the same problem when the same tool reports the same rule on the same file;
119
+ * its title is model-written prose and changes between runs, so it is left
120
+ * out. Without a rule id the title is all there is, normalised.
121
+ */
122
+ declare function findingFingerprint(repositoryId: string, finding: Finding): string;
123
+ //#endregion
124
+ //#region src/approval.d.ts
125
+ /**
126
+ * One approval rule. Every listed field must match for the rule to apply;
127
+ * absent fields match anything. Rules are evaluated first-match.
128
+ */
129
+ declare const approvalRuleSchema: z.ZodObject<{
130
+ source: z.ZodOptional<z.ZodString>;
131
+ kind: z.ZodOptional<z.ZodString>;
132
+ priority: z.ZodOptional<z.ZodArray<z.ZodEnum<{
133
+ P0: "P0";
134
+ P1: "P1";
135
+ P2: "P2";
136
+ P3: "P3";
137
+ }>>>;
138
+ require: z.ZodBoolean;
139
+ }, z.core.$strict>;
140
+ declare const approvalPolicySchema: z.ZodArray<z.ZodObject<{
141
+ source: z.ZodOptional<z.ZodString>;
142
+ kind: z.ZodOptional<z.ZodString>;
143
+ priority: z.ZodOptional<z.ZodArray<z.ZodEnum<{
144
+ P0: "P0";
145
+ P1: "P1";
146
+ P2: "P2";
147
+ P3: "P3";
148
+ }>>>;
149
+ require: z.ZodBoolean;
150
+ }, z.core.$strict>>;
151
+ type ApprovalRule = z.infer<typeof approvalRuleSchema>;
152
+ type ApprovalPolicy = z.infer<typeof approvalPolicySchema>;
153
+ /**
154
+ * The default: fixes for security findings wait for a human; everything else
155
+ * runs as it always has. Handoffs between agents (verification) never wait,
156
+ * because a human already approved the work they continue.
157
+ */
158
+ declare const defaultApprovalPolicy: ApprovalPolicy;
159
+ interface ApprovalSubject {
160
+ source?: string;
161
+ kind: string;
162
+ priority?: FindingPriority;
163
+ }
164
+ /**
165
+ * Decide at task-creation time whether a task needs approval. Pure: the answer
166
+ * is stamped on the task and never re-evaluated, so a later policy change
167
+ * cannot silently release work a human was expecting to see.
168
+ */
169
+ declare function requiresApproval(policy: ApprovalPolicy, subject: ApprovalSubject): boolean;
170
+ //#endregion
6
171
  //#region src/briefs.d.ts
7
172
  /** The finding behind a task, when its signal carries one. */
8
173
  declare function findingForTask(stores: FactoryStores, task: Task): Promise<Finding | null>;
@@ -16,6 +181,79 @@ declare function scanBrief(task: Task, repository: Repository): string;
16
181
  /** The verifier's starting message for a recorded pull request. */
17
182
  declare function verificationBrief(task: Task, repository: Repository, change: Change): string;
18
183
  //#endregion
184
+ //#region src/budget.d.ts
185
+ /**
186
+ * Stable factory identity for budget rows. Nothing mints factory ids yet, so
187
+ * the app derives one from a deployment-stable seed such as the Vercel
188
+ * project id.
189
+ */
190
+ declare function deriveFactoryId(seed: string): FactoryId;
191
+ /** The budget month ("YYYY-MM", UTC) a timestamp falls into. */
192
+ declare function budgetMonthOf(isoDateTime: string): string;
193
+ /**
194
+ * Monthly spend is derived from task rows, never stored: each task counts its
195
+ * settled cost once that exists, otherwise its held reservation. A task
196
+ * settles once, so a settled row never also counts its reservation.
197
+ * Attribution uses the reservation time so tasks that wait across a month
198
+ * boundary charge the month they actually ran in.
199
+ */
200
+ declare function computeMonthSpendUsd(tasks: readonly Task[], month: string): number;
201
+ type BudgetStatus = "ok" | "warning" | "exhausted";
202
+ /**
203
+ * True when one more per-task slice fits under the monthly total. Dispatch
204
+ * refuses on this exact predicate and budgetStatus reports "exhausted" on its
205
+ * negation, so refusing and reporting can never disagree.
206
+ */
207
+ declare function canReserve(spendUsd: number, limits: Pick<BudgetLimits, "totalUsd" | "perTaskReservationUsd">): boolean;
208
+ declare function budgetStatus(spendUsd: number, limits: Pick<BudgetLimits, "totalUsd" | "perTaskReservationUsd" | "warningPercent">): BudgetStatus;
209
+ interface SettleSweepOptions {
210
+ /** How long a terminal task waits for late usage before the sweep settles it. */
211
+ graceMinutes?: number;
212
+ now?: () => Date;
213
+ }
214
+ interface SettleSweepResult {
215
+ settled: {
216
+ taskId: TaskId;
217
+ totalUsd: number;
218
+ }[];
219
+ }
220
+ /**
221
+ * Settle reserved terminal tasks the session hook did not: a task that ended
222
+ * after its session (a change verified later) or whose session died. Settles
223
+ * at the recorded usage, or at zero with a warning reason when none was
224
+ * recorded within the grace window.
225
+ */
226
+ declare function sweepSettlements(stores: FactoryStores, options?: SettleSweepOptions): Promise<SettleSweepResult>;
227
+ interface BudgetNotice {
228
+ outcome: "budget_warning" | "budget_exhausted";
229
+ month: string;
230
+ spendUsd: number;
231
+ limits: BudgetLimits;
232
+ }
233
+ interface BudgetSweepOptions {
234
+ factoryId: FactoryId;
235
+ limits: BudgetLimits;
236
+ /** Defaults to the current UTC month. */
237
+ month?: string;
238
+ now?: () => Date;
239
+ /** Owner-only delivery; invoked at most once per month per outcome. */
240
+ notify?: (notice: BudgetNotice) => Promise<void>;
241
+ }
242
+ interface BudgetSweepResult {
243
+ month: string;
244
+ spendUsd: number;
245
+ status: BudgetStatus;
246
+ warned: boolean;
247
+ exhausted: boolean;
248
+ }
249
+ /**
250
+ * Ensure the month's budget row, derive spend, and record threshold crossings
251
+ * write-once. Delivery comes first and the stamp only lands after it, so a
252
+ * failed notification retries on the next sweep instead of being lost; the
253
+ * write-once stamp still keeps each threshold to one message per month.
254
+ */
255
+ declare function sweepBudget(stores: FactoryStores, options: BudgetSweepOptions): Promise<BudgetSweepResult>;
256
+ //#endregion
19
257
  //#region src/changes.d.ts
20
258
  interface AdoptPullRequestInput {
21
259
  repositoryId: RepositoryId;
@@ -26,11 +264,19 @@ interface AdoptPullRequestInput {
26
264
  declare function adoptPullRequest(stores: Pick<FactoryStores, "changes">, input: AdoptPullRequestInput): Promise<Change>;
27
265
  //#endregion
28
266
  //#region src/coordination.d.ts
29
- interface CreateCoordinationInput {
267
+ interface CreateCoordinationInputBase {
30
268
  repositoryIds: readonly [RepositoryId, RepositoryId, ...RepositoryId[]];
31
- signalId: SignalId;
32
269
  replyTo: ReplyTo;
270
+ /** Same key recreates neither the parent nor its repository-scoped children. */
271
+ dedupeKey?: string;
33
272
  }
273
+ type CreateCoordinationInput = CreateCoordinationInputBase & ({
274
+ signalId: SignalId;
275
+ operator?: never;
276
+ } | {
277
+ operator: string;
278
+ signalId?: never;
279
+ });
34
280
  interface CoordinationPlan {
35
281
  parent: Task;
36
282
  children: readonly Task[];
@@ -57,33 +303,6 @@ declare function createCoordination(stores: FactoryStores, input: CreateCoordina
57
303
  /** Reconcile a coordination parent from its direct children without ever dispatching the parent. */
58
304
  declare function reconcileCoordination(stores: FactoryStores, parentTaskId: TaskId, options: ReconcileCoordinationOptions): Promise<CoordinationReconciliation>;
59
305
  //#endregion
60
- //#region src/dispatch.d.ts
61
- declare class DispatchRefusedError extends Error {
62
- readonly taskId: TaskId;
63
- readonly reason: string;
64
- constructor(taskId: TaskId, reason: string);
65
- }
66
- interface DispatchOptions {
67
- /**
68
- * Starts the durable execution for the task (an Eve agent run). Runs after
69
- * the task has won the queued -> running transition. The execution owns its
70
- * own provisioning: it creates its Devbox as its first step and patches the
71
- * task record with the result.
72
- */
73
- launch: (task: Task) => Promise<void>;
74
- /** How many launches to try before the task fails for good; a failure re-queues for the next sweep. */
75
- maxLaunchAttempts?: number;
76
- }
77
- declare const DEFAULT_MAX_LAUNCH_ATTEMPTS = 45;
78
- /**
79
- * The handshake between recorded work and execution: win the store-gated
80
- * transition (at most one dispatcher can succeed), then start the run. A
81
- * launch failure re-queues the task (bumping its attempt) until the attempt
82
- * limit, then fails it; a crash between the transition and the launch leaves
83
- * a running task with no execution, which the sweep reaps.
84
- */
85
- declare function dispatchTask(stores: FactoryStores, taskId: TaskId, options: DispatchOptions): Promise<Task>;
86
- //#endregion
87
306
  //#region src/metrics.d.ts
88
307
  /**
89
308
  * The derived review bucket from the default risk x confidence table. Derived
@@ -140,6 +359,8 @@ interface HealthOptions {
140
359
  now?: Date;
141
360
  /** Open-change cap from factory configuration; omitted disables that check. */
142
361
  maxOpenChanges?: number;
362
+ /** Minutes an eligible executable task may remain queued before health turns yellow. Default 5. */
363
+ maxQueuedMinutes?: number;
143
364
  }
144
365
  interface RepositoryHealth {
145
366
  color: HealthColor;
@@ -147,32 +368,13 @@ interface RepositoryHealth {
147
368
  reasons: string[];
148
369
  }
149
370
  /**
150
- * Green, yellow, or red from rows, never from a model. Budget and onboarding
151
- * signals are not evaluated yet: budgets do not settle and onboarding
152
- * investigations are not recorded, so those spec rules have no rows to read.
371
+ * Green, yellow, or red from rows, never from a model. Budget threshold and
372
+ * onboarding rules are not evaluated here yet: budget notices live on the
373
+ * budgets collection (not in these rows), and onboarding investigations are
374
+ * not recorded.
153
375
  */
154
376
  declare function computeRepositoryHealth(rows: LedgerRows, options?: HealthOptions): RepositoryHealth;
155
377
  //#endregion
156
- //#region src/schema/budget.d.ts
157
- declare const budgetMonthSchema: z.ZodString;
158
- declare const budgetSchema: z.ZodObject<{
159
- schemaVersion: z.ZodLiteral<1>;
160
- factoryId: z.ZodString;
161
- month: z.ZodString;
162
- limits: z.ZodObject<{
163
- totalUsd: z.ZodNumber;
164
- investigationUsd: z.ZodNumber;
165
- perTaskReservationUsd: z.ZodNumber;
166
- warningPercent: z.ZodNumber;
167
- perRepositoryUsd: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
168
- }, z.core.$strict>;
169
- notices: z.ZodObject<{
170
- warningAt: z.ZodOptional<z.ZodISODateTime>;
171
- exhaustedAt: z.ZodOptional<z.ZodISODateTime>;
172
- }, z.core.$strict>;
173
- }, z.core.$strict>;
174
- type Budget = z.infer<typeof budgetSchema>;
175
- //#endregion
176
378
  //#region src/schema/transitions.d.ts
177
379
  type TransitionActor = "system" | "reconciler" | "foreman" | "operator" | "webhook" | "human";
178
380
  interface Transition<State extends string> {
@@ -209,24 +411,52 @@ interface SignalCreator {
209
411
  */
210
412
  declare function createSignalCreator(stores: Pick<FactoryStores, "signals">): SignalCreator;
211
413
  //#endregion
414
+ //#region src/stall.d.ts
415
+ interface StallSweepOptions {
416
+ policy: ExecutionPolicy;
417
+ now?: () => Date;
418
+ }
419
+ interface StallSweepResult {
420
+ stalled: TaskId[];
421
+ requeued: TaskId[];
422
+ failed: TaskId[];
423
+ }
424
+ declare function stallWindowMinutes(policy: ExecutionPolicy, kind: Task["kind"]): number;
425
+ /**
426
+ * The reconciler's stall pass. A running task whose execution has not
427
+ * progressed within its stall window is marked stalled; a stalled task is
428
+ * re-queued for a replacement attempt while attempts remain, and failed once
429
+ * they are exhausted. Only `running` tasks can stall: a task whose result has
430
+ * already been recorded (verifying, or terminal) is never retried by this
431
+ * pass. Coordination parents run only through their children and are skipped.
432
+ */
433
+ declare function sweepStalled(stores: FactoryStores, options: StallSweepOptions): Promise<StallSweepResult>;
434
+ //#endregion
212
435
  //#region src/store/memory.d.ts
213
436
  declare function createInMemoryDriver(): StoreDriver;
214
437
  //#endregion
215
438
  //#region src/sweep.d.ts
216
- /** Starts the agent for one task kind. Supplied by the app, which knows its agents' addresses. */
217
- type TaskLauncher = (task: Task, repository: Repository) => Promise<void>;
439
+ /**
440
+ * Starts the agent for one task kind. Supplied by the app, which knows its
441
+ * agents' addresses. Returns the provider's execution reference when it has one.
442
+ */
443
+ type TaskLauncher = (task: Task, repository: Repository) => Promise<ExecutionReference | void>;
218
444
  interface SweepOptions {
219
445
  /** Launcher per task kind, e.g. code_change -> foreman, security_scan -> security-scanner. */
220
446
  launchers: Readonly<Record<string, TaskLauncher>>;
447
+ /** Reserve-before-execution limits, passed through to every dispatch. */
448
+ budget?: DispatchBudget;
449
+ /** Maximum task launches attempted in one pass; omitted means no limit. */
450
+ maxDispatches?: number;
221
451
  }
222
452
  interface SweepResult {
223
453
  dispatched: string[];
224
- /** Tasks left in the queue and why: awaiting approval, no launcher, missing repository. */
454
+ /** Tasks left in the queue because a declared gate may become eligible later. */
225
455
  skipped: {
226
456
  taskId: string;
227
457
  reason: string;
228
458
  }[];
229
- /** Tasks whose launch threw; dispatchTask has already recorded them as failed. */
459
+ /** Tasks whose routing is invalid or whose launch threw. */
230
460
  failed: {
231
461
  taskId: string;
232
462
  reason: string;
@@ -250,5 +480,5 @@ interface VerificationTaskSweep {
250
480
  /** Ensure every recorded code change has exactly one durable verification task. */
251
481
  declare function ensureVerificationTasks(stores: FactoryStores): Promise<VerificationTaskSweep>;
252
482
  //#endregion
253
- export { AdoptPullRequestInput, AppendReceiptInput, ApprovalDecision, ApprovalError, ApprovalPolicy, ApprovalRule, ApprovalSubject, Budget, Change, ChangeAssociationError, ChangeEvidence, ChangeId, ChangePatch, ChangeState, ChangeTransitionOptions, CollectionName, CoordinationPlan, CoordinationReconciliation, Cost, CreateChangeInput, CreateCoordinationInput, CreateSignalInput, CreateStoresOptions, CreateTaskInput, DEFAULT_MAX_LAUNCH_ATTEMPTS, DecideSignalOptions, DispatchOptions, DispatchRefusedError, FactoryConfig, FactoryConfigInput, FactoryId, FactoryStores, Finding, FindingCategory, FindingPriority, FindingVerification, HealthColor, HealthOptions, InvalidTransitionError, LedgerMetrics, LedgerRows, Level, MetricsOptions, Receipt, ReceiptId, ReceiptKind, ReceiptPhase, ReceiptState, ReconcileCoordinationOptions, RecordExistsError, RecordNotFoundError, ReplyTo, Repository, RepositoryHealth, RepositoryId, RepositorySlug, ReviewBucket, SCHEMA_VERSION, Signal, SignalCreator, SignalId, SignalOutcome, SignalSource, StoreDriver, StoredEntry, StoredRecord, SweepOptions, SweepResult, Task, TaskApproval, TaskId, TaskKind, TaskLauncher, TaskPatch, TaskState, TaskTransitionOptions, Transition, TransitionActor, VerificationTaskSweep, VersionConflictError, adoptPullRequest, approvalPolicySchema, approvalRuleSchema, assertTransition, budgetMonthSchema, budgetSchema, changeEvidenceSchema, changeIdSchema, changeInitialState, changeSchema, changeStateSchema, changeTransitions, computeLedgerMetrics, computeRepositoryHealth, coordinationRepositoryIdsSchema, costSchema, createCoordination, createInMemoryDriver, createSignalCreator, createStores, defaultApprovalPolicy, defineFactory, dispatchTask, ensureVerificationTasks, factoryConfigRepositorySchema, factoryConfigSchema, factoryIdSchema, findingCategorySchema, findingFingerprint, findingForTask, findingPrioritySchema, findingSchema, findingVerificationLevelSchema, findingVerificationMethodSchema, findingVerificationSchema, fixBrief, harnessSchema, isTransitionAllowed, isoDateTimeSchema, legalNextStates, levelSchema, receiptIdSchema, receiptKindSchema, receiptPhaseSchema, receiptSchema, receiptStateSchema, reconcileCoordination, replyToSchema, repositoryIdSchema, repositoryIdsSchema, repositorySchema, repositorySlugSchema, requiresApproval, reviewBucket, scanBrief, schemaVersionSchema, signalIdSchema, signalInitialOutcome, signalOutcomeSchema, signalOutcomeTransitions, signalSchema, signalSourceSchema, standardReceiptKinds, standardReceiptPhases, standardReceiptStates, standardSignalSources, standardTaskKinds, sweepQueued, taskApprovalSchema, taskDevboxSchema, taskExecutionRepositoryIdsSchema, taskIdSchema, taskInitialState, taskKindSchema, taskOriginSchema, taskQuestionSchema, taskSchema, taskStateSchema, taskTransitions, terminalStates, usdSchema, verificationBrief, vocabularySchema };
483
+ export { AdoptPullRequestInput, AgentRoute, AgentRouteInput, AgentRouteRegistry, AgentSession, AnswerEvent, AnswerEventConflictError, AnswerId, AnswerQuestionInput, AppendReceiptInput, ApprovalDecision, ApprovalError, ApprovalPolicy, ApprovalRule, ApprovalSubject, Budget, BudgetExhaustedError, BudgetLimits, BudgetNotice, BudgetStatus, BudgetSweepOptions, BudgetSweepResult, Change, ChangeAssociationError, ChangeEvidence, ChangeId, ChangePatch, ChangeState, ChangeTransitionOptions, CollectionName, CommunicationEvent, CommunicationOutcome, CoordinationPlan, CoordinationReconciliation, Cost, CreateChangeInput, CreateCoordinationInput, CreateSignalInput, CreateStoresOptions, CreateTaskInput, DEFAULT_MAX_LAUNCH_ATTEMPTS, DecideSignalOptions, DispatchBudget, DispatchOptions, DispatchRefusedError, EnsureBudgetInput, ExecutionPolicy, ExecutionReference, FactoryConfig, FactoryConfigInput, FactoryId, FactoryStores, Finding, FindingCategory, FindingPriority, FindingVerification, HealthColor, HealthOptions, InvalidTransitionError, LedgerMetrics, LedgerRows, Level, MetricsOptions, OutboxEventConflictError, OutboxId, OutboxMessage, OutboxQueue, Receipt, ReceiptId, ReceiptKind, ReceiptPhase, ReceiptState, ReconcileCoordinationOptions, RecordExistsError, RecordNotFoundError, ReplyTo, Repository, RepositoryHealth, RepositoryId, RepositorySlug, ReviewBucket, SCHEMA_VERSION, SessionConflictError, SettleSweepOptions, SettleSweepResult, SettleTaskOptions, SettlementError, Signal, SignalCreator, SignalId, SignalOutcome, SignalSource, StallSweepOptions, StallSweepResult, StepUsage, StoreDriver, StoredEntry, StoredRecord, SweepOptions, SweepResult, Task, TaskApproval, TaskId, TaskKind, TaskLauncher, TaskPatch, TaskState, TaskTransitionOptions, TaskUsage, Transition, TransitionActor, VerificationTaskSweep, VersionConflictError, adoptPullRequest, agentRouteSchema, agentSessionIdSchema, agentSessionSchema, answerEventSchema, answerIdSchema, approvalPolicySchema, approvalRuleSchema, assertTransition, budgetLimitsSchema, budgetMonthOf, budgetMonthSchema, budgetSchema, budgetStatus, canReserve, changeEvidenceSchema, changeIdSchema, changeInitialState, changeSchema, changeStateSchema, changeTransitions, communicationEventSchema, communicationOutcomeSchema, communicationOutcomes, computeLedgerMetrics, computeMonthSpendUsd, computeRepositoryHealth, coordinationRepositoryIdsSchema, costSchema, createCoordination, createInMemoryDriver, createSignalCreator, createStores, defaultApprovalPolicy, defaultExecutionPolicy, defineAgentRoutes, defineFactory, deriveFactoryId, dispatchTask, ensureVerificationTasks, executionPolicySchema, executionReferenceSchema, factoryConfigRepositorySchema, factoryConfigSchema, factoryIdSchema, findingCategorySchema, findingFingerprint, findingForTask, findingPrioritySchema, findingSchema, findingVerificationLevelSchema, findingVerificationMethodSchema, findingVerificationSchema, fixBrief, harnessSchema, isTransitionAllowed, isoDateTimeSchema, legalNextStates, levelSchema, outboxIdSchema, outboxMessageSchema, outboxQueueSchema, outboxStateSchema, receiptIdSchema, receiptKindSchema, receiptPhaseSchema, receiptSchema, receiptStateSchema, reconcileCoordination, replyToSchema, repositoryIdSchema, repositoryIdsSchema, repositorySchema, repositorySlugSchema, requiresApproval, reviewBucket, scanBrief, schemaVersionSchema, signalIdSchema, signalInitialOutcome, signalOutcomeSchema, signalOutcomeTransitions, signalSchema, signalSourceSchema, stallWindowMinutes, standardReceiptKinds, standardReceiptPhases, standardReceiptStates, standardSignalSources, standardTaskKinds, sweepBudget, sweepQueued, sweepSettlements, sweepStalled, taskApprovalSchema, taskExecutionRepositoryIdsSchema, taskIdSchema, taskInitialState, taskKindSchema, taskOriginSchema, taskQuestionSchema, taskSchema, taskStateSchema, taskTransitions, taskUsageSchema, terminalStates, usdSchema, verificationBrief, vocabularySchema };
254
484
  //# sourceMappingURL=index.d.mts.map