agl 42.2.2 → 43.0.1

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 (179) hide show
  1. package/changelog.md +24 -0
  2. package/dist_serve/bundle.js +6697 -5287
  3. package/dist_serve/bundle.js.map +2 -2
  4. package/dist_serve/bundle.js.third-party-notices.json +29 -29
  5. package/dist_serve/bundle.js.third-party-notices.txt +29 -29
  6. package/dist_serve/third-party-notices.md +597 -8
  7. package/dist_ts/00_commitinfo_data.js +1 -1
  8. package/dist_ts/aglapi/aglapisurface.document.js +114 -16
  9. package/dist_ts/aglapi/interfaces.d.ts +30 -0
  10. package/dist_ts/aglapi/interfaces.js +7 -1
  11. package/dist_ts/classes.authstore.d.ts +7 -0
  12. package/dist_ts/classes.authstore.js +12 -1
  13. package/dist_ts/classes.browserpainttransport.d.ts +2 -2
  14. package/dist_ts/classes.browserpainttransport.js +9 -8
  15. package/dist_ts/classes.browserresourcehost.js +30 -20
  16. package/dist_ts/classes.cli.js +10 -1
  17. package/dist_ts/classes.controller.d.ts +41 -11
  18. package/dist_ts/classes.controller.js +232 -52
  19. package/dist_ts/classes.harnessoperationmanager.d.ts +44 -0
  20. package/dist_ts/classes.harnessoperationmanager.js +15 -10
  21. package/dist_ts/classes.mcpclient.d.ts +5 -0
  22. package/dist_ts/classes.mcpclient.js +15 -3
  23. package/dist_ts/classes.mcpcontrollerhost.d.ts +3 -0
  24. package/dist_ts/classes.mcpcontrollerhost.js +17 -3
  25. package/dist_ts/classes.mcptools.d.ts +4 -3
  26. package/dist_ts/classes.mcptools.js +20 -1
  27. package/dist_ts/classes.mcpvalidation.js +4 -1
  28. package/dist_ts/classes.ticketstore.d.ts +71 -3
  29. package/dist_ts/classes.ticketstore.js +299 -12
  30. package/dist_ts/classes.validation.d.ts +2 -0
  31. package/dist_ts/classes.validation.js +27 -5
  32. package/dist_ts/driver/classes.directreports.d.ts +23 -3
  33. package/dist_ts/driver/classes.directreports.js +59 -2
  34. package/dist_ts/driver/classes.drivereventrelay.js +3 -2
  35. package/dist_ts/driver/functions.driverinstructions.d.ts +1 -1
  36. package/dist_ts/driver/functions.driverinstructions.js +12 -3
  37. package/dist_ts/driver/functions.drivertools.d.ts +4 -0
  38. package/dist_ts/driver/functions.drivertools.js +8 -2
  39. package/dist_ts/fleet/classes.boardpump.d.ts +53 -3
  40. package/dist_ts/fleet/classes.boardpump.js +237 -32
  41. package/dist_ts/fleet/classes.claudeworkers.d.ts +10 -3
  42. package/dist_ts/fleet/classes.claudeworkers.js +43 -19
  43. package/dist_ts/fleet/classes.codexworkers.d.ts +5 -3
  44. package/dist_ts/fleet/classes.codexworkers.js +26 -9
  45. package/dist_ts/fleet/classes.deploymonitor.d.ts +253 -0
  46. package/dist_ts/fleet/classes.deploymonitor.js +821 -0
  47. package/dist_ts/fleet/classes.gitfacts.d.ts +61 -0
  48. package/dist_ts/fleet/classes.gitfacts.js +125 -0
  49. package/dist_ts/fleet/classes.releasereconciler.d.ts +51 -0
  50. package/dist_ts/fleet/classes.releasereconciler.js +101 -0
  51. package/dist_ts/fleet/classes.service.d.ts +13 -1
  52. package/dist_ts/fleet/classes.service.js +76 -7
  53. package/dist_ts/fleet/classes.ticketeffects.d.ts +13 -0
  54. package/dist_ts/fleet/classes.ticketeffects.js +42 -8
  55. package/dist_ts/fleet/classes.workers.d.ts +10 -3
  56. package/dist_ts/fleet/classes.workers.js +18 -3
  57. package/dist_ts/fleet/functions.controllerbuild.d.ts +23 -0
  58. package/dist_ts/fleet/functions.controllerbuild.js +75 -0
  59. package/dist_ts/fleet/functions.deployprobes.d.ts +39 -0
  60. package/dist_ts/fleet/functions.deployprobes.js +82 -0
  61. package/dist_ts/fleet/functions.deployvalidation.d.ts +27 -0
  62. package/dist_ts/fleet/functions.deployvalidation.js +43 -0
  63. package/dist_ts/fleet/functions.release.d.ts +2 -1
  64. package/dist_ts/fleet/functions.release.js +32 -5
  65. package/dist_ts/fleet/functions.releasefacts.d.ts +42 -0
  66. package/dist_ts/fleet/functions.releasefacts.js +46 -0
  67. package/dist_ts/fleet/functions.validation.d.ts +3 -3
  68. package/dist_ts/fleet/functions.validation.js +4 -7
  69. package/dist_ts/fleet/functions.watchprobes.js +7 -9
  70. package/dist_ts/fleet/functions.workervalidation.js +4 -3
  71. package/dist_ts/fleet/interfaces.workers.d.ts +30 -3
  72. package/dist_ts/fleet/interfaces.workers.js +14 -1
  73. package/dist_ts/functions.deploycli.d.ts +36 -0
  74. package/dist_ts/functions.deploycli.js +157 -0
  75. package/dist_ts/functions.mcpdeploytools.d.ts +13 -0
  76. package/dist_ts/functions.mcpdeploytools.js +16 -0
  77. package/dist_ts/functions.mcptickettools.d.ts +54 -0
  78. package/dist_ts/functions.mcptickettools.js +8 -7
  79. package/dist_ts/functions.ticketautolabels.d.ts +2 -0
  80. package/dist_ts/functions.ticketautolabels.js +9 -3
  81. package/dist_ts/functions.ticketcli.d.ts +16 -2
  82. package/dist_ts/functions.ticketcli.js +105 -27
  83. package/dist_ts/functions.ticketvalidation.d.ts +55 -0
  84. package/dist_ts/functions.ticketvalidation.js +26 -8
  85. package/dist_ts_interfaces/deployments.d.ts +241 -0
  86. package/dist_ts_interfaces/deployments.js +5 -6
  87. package/dist_ts_interfaces/fleet.d.ts +12 -0
  88. package/dist_ts_interfaces/fleetworkers.d.ts +21 -1
  89. package/dist_ts_interfaces/functions.fleetversion.d.ts +4 -0
  90. package/dist_ts_interfaces/functions.fleetversion.js +25 -0
  91. package/dist_ts_interfaces/interfaces.d.ts +4 -2
  92. package/dist_ts_interfaces/interfaces.js +4 -2
  93. package/dist_ts_interfaces/mcprequests.d.ts +3 -2
  94. package/dist_ts_interfaces/mcprequests.js +3 -1
  95. package/dist_ts_interfaces/requests.d.ts +3 -2
  96. package/dist_ts_interfaces/requests.directreports.d.ts +58 -6
  97. package/dist_ts_interfaces/requests.js +1 -1
  98. package/dist_ts_interfaces/requests.tickets.d.ts +25 -5
  99. package/dist_ts_interfaces/requests.tickets.js +2 -2
  100. package/dist_ts_interfaces/tickets.d.ts +71 -6
  101. package/dist_ts_interfaces/tickets.js +34 -6
  102. package/dist_ts_migration/classes.documentmigrationrunner.d.ts +7 -0
  103. package/dist_ts_migration/classes.documentmigrationrunner.js +14 -1
  104. package/dist_ts_migration/index.d.ts +2 -0
  105. package/dist_ts_migration/index.js +3 -1
  106. package/dist_ts_migration/v41_ticketclosedcolumn.d.ts +20 -0
  107. package/dist_ts_migration/v41_ticketclosedcolumn.js +118 -0
  108. package/dist_ts_migration/v41_ticketlinkrepos.d.ts +24 -0
  109. package/dist_ts_migration/v41_ticketlinkrepos.js +101 -0
  110. package/package.json +6 -2
  111. package/readme.md +308 -36
  112. package/third-party-notices.md +597 -8
  113. package/ts/00_commitinfo_data.ts +1 -1
  114. package/ts/aglapi/aglapisurface.document.ts +113 -15
  115. package/ts/aglapi/interfaces.ts +6 -0
  116. package/ts/classes.authstore.ts +13 -0
  117. package/ts/classes.browserpainttransport.ts +8 -7
  118. package/ts/classes.browserresourcehost.ts +38 -14
  119. package/ts/classes.cli.ts +9 -0
  120. package/ts/classes.controller.ts +244 -61
  121. package/ts/classes.harnessoperationmanager.ts +20 -14
  122. package/ts/classes.mcpclient.ts +17 -2
  123. package/ts/classes.mcpcontrollerhost.ts +18 -2
  124. package/ts/classes.mcptools.ts +21 -2
  125. package/ts/classes.mcpvalidation.ts +2 -0
  126. package/ts/classes.ticketstore.ts +312 -13
  127. package/ts/classes.validation.ts +28 -4
  128. package/ts/driver/classes.directreports.ts +58 -3
  129. package/ts/driver/classes.drivereventrelay.ts +2 -1
  130. package/ts/driver/functions.driverinstructions.ts +11 -2
  131. package/ts/driver/functions.drivertools.ts +10 -2
  132. package/ts/fleet/classes.boardpump.ts +235 -28
  133. package/ts/fleet/classes.claudeworkers.ts +36 -15
  134. package/ts/fleet/classes.codexworkers.ts +24 -7
  135. package/ts/fleet/classes.deploymonitor.ts +854 -0
  136. package/ts/fleet/classes.gitfacts.ts +135 -0
  137. package/ts/fleet/classes.releasereconciler.ts +103 -0
  138. package/ts/fleet/classes.service.ts +81 -8
  139. package/ts/fleet/classes.ticketeffects.ts +38 -6
  140. package/ts/fleet/classes.workers.ts +19 -5
  141. package/ts/fleet/functions.controllerbuild.ts +84 -0
  142. package/ts/fleet/functions.deployprobes.ts +84 -0
  143. package/ts/fleet/functions.deployvalidation.ts +50 -0
  144. package/ts/fleet/functions.release.ts +32 -3
  145. package/ts/fleet/functions.releasefacts.ts +74 -0
  146. package/ts/fleet/functions.validation.ts +3 -6
  147. package/ts/fleet/functions.watchprobes.ts +6 -8
  148. package/ts/fleet/functions.workervalidation.ts +3 -2
  149. package/ts/fleet/interfaces.workers.ts +23 -3
  150. package/ts/functions.deploycli.ts +156 -0
  151. package/ts/functions.mcpdeploytools.ts +18 -0
  152. package/ts/functions.mcptickettools.ts +7 -6
  153. package/ts/functions.ticketautolabels.ts +10 -2
  154. package/ts/functions.ticketcli.ts +100 -24
  155. package/ts/functions.ticketvalidation.ts +26 -7
  156. package/ts_interfaces/deployments.ts +194 -0
  157. package/ts_interfaces/fleet.ts +17 -2
  158. package/ts_interfaces/fleetworkers.ts +20 -0
  159. package/ts_interfaces/functions.fleetversion.ts +20 -0
  160. package/ts_interfaces/interfaces.ts +3 -1
  161. package/ts_interfaces/mcprequests.ts +3 -0
  162. package/ts_interfaces/requests.directreports.ts +52 -8
  163. package/ts_interfaces/requests.tickets.ts +20 -4
  164. package/ts_interfaces/requests.ts +6 -1
  165. package/ts_interfaces/tickets.ts +53 -6
  166. package/ts_migration/classes.documentmigrationrunner.ts +15 -0
  167. package/ts_migration/index.ts +2 -0
  168. package/ts_migration/v41_ticketclosedcolumn.ts +106 -0
  169. package/ts_migration/v41_ticketlinkrepos.ts +91 -0
  170. package/ts_web/00_commitinfo_data.ts +1 -1
  171. package/ts_web/elements.deployments.ts +1066 -0
  172. package/ts_web/elements.directreport.ts +2 -2
  173. package/ts_web/elements.directreportsession.ts +5 -5
  174. package/ts_web/elements.harnesscontrollerapp.ts +179 -13
  175. package/ts_web/elements.makedirectreport.ts +444 -0
  176. package/ts_web/elements.nativesession.ts +29 -1
  177. package/ts_web/elements.ticketboard.ts +74 -18
  178. package/ts_web/functions.deployments.ts +231 -0
  179. package/ts_web/functions.sessionchat.ts +2 -0
@@ -1,15 +1,16 @@
1
1
  import { ticketInputSchemas } from './functions.ticketvalidation.js';
2
2
  import type { TTicketOperation } from '../ts_interfaces/tickets.js';
3
3
 
4
- const workflow = ' Caller identity comes from AGL, never a supplied name. Unidentified callers may list/get tickets with empty mine; every mutation requires a verified caller. Workers create in backlog and may update/move only their assigned tickets within ready, in_progress, needs_input and review. Link a branch with a full sha before Review. Only the driver or owner assigns, lands or releases tickets.';
4
+ const workflow = ' Caller identity comes from AGL, never a supplied name. Unidentified callers may list/get tickets with empty mine; every mutation requires a verified caller. Workers create in backlog and may update/move only their assigned tickets within ready, in_progress, needs_input and review. Link a branch with a full sha before Review. Only the driver or owner assigns, lands, releases or closes tickets.';
5
5
  export const ticketToolDefinitions = [
6
- { name: 'tickets_list', operation: 'list', description: 'Read the shared board across all projects. Filter by mine, project, status, label or text. mine uses your verified session. label also matches AutoLabels, which AGL computes and nobody sets: openQuestion marks a ticket with an unanswered question.' },
6
+ { name: 'tickets_list', operation: 'list', description: 'Read the shared board across all projects. Filter by mine, project, status, label or text. mine uses your verified session. label also matches AutoLabels, which AGL computes and nobody sets: openQuestion marks a ticket with an unanswered question, planned a ticket that is not done and plans a release, a deploy or a maintenance window, undeployed a ticket released in a version some deploy target of its repository does not run yet.' },
7
7
  { name: 'ticket_get', operation: 'get', description: 'Read a ticket by its AGL-<n> key: source, links, all its questions and their answers, and the newest page of its history, oldest first: up to limit entries (default 50, at most 500), fewer when the entries and their comments would pass 256 KiB. activity is the page; comments are the markdown comments it names, and a commented entry names its comment by id. historyBefore is present while older history exists: pass it as before for the next older page. commentId instead reads the one comment an activity entry or fleet event names (without before or limit).' },
8
- { name: 'ticket_create', operation: 'create', description: 'Capture discussed work as a ticket. Include project, title, description and sourceText (the original words); optional attachments are named URLs. Worker-created tickets start in backlog for driver triage.' },
9
- { name: 'ticket_update', operation: 'update', description: 'Update the title, markdown description, priority, labels, project or parent of your assigned ticket. Supply expectedRevision from the ticket you read; stale edits return TICKET_REVISION_CONFLICT with currentRevision. Reload before editing again. Status is changed only with ticket_move; assignment is driver/owner-only.' },
10
- { name: 'ticket_move', operation: 'move', description: 'Atomically move/reorder your assigned ticket. Omit beforeTicketId to append. Returns every record whose column or order changed. Review requires a linked branch and sha. Use needs_input to report a blocker.' },
8
+ { name: 'ticket_create', operation: 'create', description: 'Capture discussed work as a ticket. Include project, title, description and sourceText (the original words); optional attachments are named URLs. Worker-created tickets start in backlog for driver triage. The driver or owner may give it a releasePlan (repo as org/name of a fleet repository, optional version such as 41.0.0; without a version it means the next release), a deployPlan (a deploy target and the release version it should run: AGL asks the owner on the ticket whether to deploy it now, in the next maintenance window, or to hold) or a maintenanceWindow (from and to as ISO 8601 instants, at most 7 days, and the deploy targets it is for); one the driver plans asks the owner and counts once the owner approves it, the owner\'s own counts at once.' },
9
+ { name: 'ticket_update', operation: 'update', description: 'Update the title, markdown description, priority, labels, project or parent of your assigned ticket. Supply expectedRevision from the ticket you read; stale edits return TICKET_REVISION_CONFLICT with currentRevision. Reload before editing again. Status is changed only with ticket_move; assignment is driver/owner-only. releasePlan (driver/owner only) plans a release: repo as org/name of a fleet repository and an optional version; null clears it. A hotfix is a release plan on an urgent ticket, without a version. fleet_release for the ticket refuses another repository and stops when gitzone plans another version. deployPlan (driver/owner only) plans a deploy and asks the owner its question; once asked it keeps its target and version (setting the same plan again asks anew once the owner answered; closing the ticket drops it; a deploy ticket holds no code or release: a ticket that does, or that is done, plans none, and one with a plan takes no branch, commit or release link), and AGL closes the ticket once the target runs the release. maintenanceWindow (driver/owner only) plans or moves a window; null removes it, and closing the ticket cancels it. A window the driver plans or moves asks the owner and counts once approved; while that question is open it does not change.' },
10
+ { name: 'ticket_move', operation: 'move', description: 'Atomically move/reorder your assigned ticket. Omit beforeTicketId to append. Returns every record whose column or order changed. Review requires a linked branch and sha, landed a branch or commit, released a release link; closed holds work that ships no code (driver/owner only); a landed ticket is released by its tag, never closed. Use needs_input to report a blocker.' },
11
11
  { name: 'ticket_comment', operation: 'comment', description: 'Comment on any ticket, including another worker’s. body is markdown text or an array of text/reference parts. Actor and time are recorded by AGL.' },
12
- { name: 'ticket_link', operation: 'link', description: 'Attach a branch (repo, branch, full sha), commit (repo, sha), or release (package, version) to your assigned ticket. Link the review branch before moving to review.' },
12
+ { name: 'ticket_link', operation: 'link', description: 'Attach a branch (repo, branch, full sha), commit (repo, sha), or the version a bug was found in (affects: repo as org/name of a fleet repository, version such as 0.5.0) to your assigned ticket. Link the review branch before moving to review. Fleet links landings itself, and releases from the tags on the remote; only the owner links a release (package, version) by hand.' },
13
+ { name: 'ticket_unlink', operation: 'unlink', description: 'Remove one link from a ticket, exactly as ticket_get shows it (an affects link may name its repository as ticket_link does). The driver removes affects links only; code and release links only the owner, and workers none. The evidence a column requires (a review branch, a landed branch or commit, a release link on a released ticket) cannot be removed while the ticket is there.' },
13
14
  { name: 'ticket_question_ask', operation: 'ask', description: 'Ask the owner a question on your assigned ticket. question is markdown; options are up to 20 choices (label, optional description), multiSelect allows several, allowCustom (default true) allows a free-text answer. The ticket shows the openQuestion AutoLabel until the owner or driver answers; the answer arrives in your session as a ticket notice. Keep working on what the question does not block.' },
14
15
  ].map((definitionArg) => ({ ...definitionArg, operation: definitionArg.operation as TTicketOperation,
15
16
  description: definitionArg.description + workflow, inputSchema: ticketInputSchemas[definitionArg.operation as TTicketOperation],
@@ -1,13 +1,21 @@
1
- import { ticketAutoLabels, type TTicketAutoLabel, type TTicketData } from '../ts_interfaces/tickets.js';
1
+ import { ticketAutoLabels, ticketDoneColumns, type TTicketAutoLabel, type TTicketData } from '../ts_interfaces/tickets.js';
2
2
 
3
3
  /** What the AutoLabel rules read besides the ticket itself; the ticket transaction loads it. */
4
4
  export interface ITicketAutoLabelFacts {
5
5
  openQuestions: number;
6
+ /** Whether the deploy monitor's last pass found the ticket released in a version no target of its repository runs. */
7
+ undeployed: boolean;
6
8
  }
7
9
 
8
10
  /** One rule per AutoLabel. A new AutoLabel adds its name to `ticketAutoLabels` and its rule here. */
9
11
  export const ticketAutoLabelRules: Record<TTicketAutoLabel, (ticketArg: TTicketData, factsArg: ITicketAutoLabelFacts) => boolean> = {
10
- openQuestion: (_ticketArg, factsArg) => factsArg.openQuestions > 0,
12
+ // A done ticket asks nobody: a question left open on it (a fulfilled deploy plan's, say) is not shown as waiting.
13
+ openQuestion: (ticketArg, factsArg) => factsArg.openQuestions > 0 && !ticketDoneColumns.includes(ticketArg.columnId),
14
+ // From the ticket alone: a plan (a release, a deploy or a maintenance window) holds until the ticket is done.
15
+ planned: (ticketArg) => (ticketArg.releasePlan !== undefined || ticketArg.deployPlan !== undefined || ticketArg.maintenanceWindow !== undefined)
16
+ && !ticketDoneColumns.includes(ticketArg.columnId),
17
+ // Read from the map the deploy monitor keeps; never git or a probe inside the ticket transaction.
18
+ undeployed: (_ticketArg, factsArg) => factsArg.undeployed,
11
19
  };
12
20
 
13
21
  export const ticketAutoLabelsFor = (ticketArg: TTicketData, factsArg: ITicketAutoLabelFacts): TTicketAutoLabel[] => (
@@ -3,24 +3,47 @@ import { withCliDiagnostics } from './functions.clidiagnostics.js';
3
3
  import { withLocalConfigurationOwner } from './functions.configurationowner.js';
4
4
  import { assertTicketRequest } from './functions.ticketvalidation.js';
5
5
  import { defaultControllerPort } from './classes.config.js';
6
- import type { ITicketChanges, ITicketPerson, TTicketOperation, TTicketRequest, TTicketLink } from '../ts_interfaces/tickets.js';
6
+ import type {
7
+ ITicketChanges, ITicketDeployPlanInput, ITicketMaintenanceWindow, ITicketPerson, TTicketOperation, TTicketRequest, TTicketLink,
8
+ } from '../ts_interfaces/tickets.js';
7
9
 
8
- export const ticketCliHelp = `Usage: agl ticket <list|get|create|update|move|comment|link|assign|ask|answer> [AGL-<n>] [options]
10
+ export const ticketCliHelp = `Usage: agl ticket <list|get|create|update|move|comment|link|unlink|assign|ask|answer> [AGL-<n>] [options]
9
11
  list [--mine] [--project ID] [--status COLUMN] [--label LABEL] [--text TEXT]
10
- --label also matches AutoLabels, which AGL computes: openQuestion (an unanswered question)
12
+ --label also matches AutoLabels, which AGL computes: openQuestion (an unanswered question),
13
+ planned (a release plan on a ticket not yet released)
11
14
  get AGL-<n> [--limit N] [--before HISTORY-ID] [--comment COMMENT-ID]
12
15
  The ticket, its questions and the newest N history entries (default 50, at most 500, within 256 KiB);
13
16
  historyBefore names the next older page: pass it as --before.
14
17
  --comment reads the one comment an activity entry names instead (not with --limit or --before)
15
18
  create --project ID --title TEXT [--description MARKDOWN] [--kind epic|task|subtask]
16
19
  [--parent AGL-<n>] [--priority none|low|normal|high|urgent] [--labels a,b]
17
- [--source TEXT] [--attachments JSON] [--column COLUMN]
18
- update AGL-<n> --expected-revision NUMBER --changes JSON (title, description, priority, assignee, parentId, project, labels)
19
- Or use --title, --description, --priority, --project, --labels, --parent, --clear-parent
20
+ [--source TEXT] [--attachments JSON] [--column COLUMN] [--release-plan REPO[@VERSION]]
21
+ [--deploy-plan TARGET@VERSION] [--window FROM/TO --window-targets TARGET,…]
22
+ update AGL-<n> --expected-revision NUMBER --changes JSON (title, description, priority, assignee, parentId, project, labels,
23
+ releasePlan, deployPlan, maintenanceWindow)
24
+ Or use --title, --description, --priority, --project, --labels, --parent, --clear-parent,
25
+ --release-plan REPO[@VERSION], --clear-release-plan, --deploy-plan TARGET@VERSION,
26
+ --window FROM/TO --window-targets TARGET,…, --clear-window
27
+ A release plan names a fleet repository (org/name, as fleet discovery knows it) and optionally the version
28
+ it should reach; without one it means the next release. fleet release --ticket checks it.
29
+ A deploy plan names a deploy target and the release it should run, and asks the owner whether to deploy
30
+ it now, in the next maintenance window (the AGL controller: when no session is busy) or to hold. Once
31
+ asked it keeps its target and version: the same plan again asks anew once the owner answered, and closing
32
+ the ticket drops it. A deploy ticket holds no code or release: a ticket that does, or that is done,
33
+ plans none, and one with a plan takes no branch, commit or release link. AGL closes it once the target
34
+ runs the release.
35
+ A maintenance window runs FROM/TO (ISO 8601 instants, at most 7 days) for the targets it names; a target
36
+ whose deploys need a window is deployed only inside one. One the driver plans asks the owner and counts
37
+ once approved, and does not change while that question is open; the owner's counts at once. Close the
38
+ ticket to cancel it.
20
39
  move AGL-<n> --column COLUMN [--before AGL-<n>]
21
40
  comment AGL-<n> --body MARKDOWN
22
41
  link AGL-<n> --repo REPO --branch BRANCH --sha SHA
23
- Or --repo REPO --sha SHA (commit), or --package PACKAGE --version VERSION (release)
42
+ Or --repo REPO --sha SHA (commit), or --affects REPO@VERSION (the version of a fleet repository
43
+ a bug was found in), or --package PACKAGE --version VERSION (a release: the owner only, since fleet
44
+ links each release from the remote's tag)
45
+ unlink AGL-<n> with the flags of the link to remove, exactly as the ticket holds it; a fleet release link
46
+ also names --repo REPO --sha SHA. Driver and owner only; a column's required evidence stays.
24
47
  assign AGL-<n> --expected-revision NUMBER --session-id codex:<native-id>|claude:<session-id> --name NAME [--kind codex|claude|worker]
25
48
  Or --assignee PERSON-ID --name NAME, or --clear
26
49
  ask AGL-<n> --text MARKDOWN [--options JSON] [--multi] [--no-custom]
@@ -29,9 +52,17 @@ export const ticketCliHelp = `Usage: agl ticket <list|get|create|update|move|com
29
52
  A question takes one answer; repeating it is accepted, a different one is refused.
30
53
  All commands accept --port PORT and --json. The running controller is required.
31
54
  The CLI uses a short-lived local-owner capability, as agl config does. It never dispatches workers.
32
- Review requires a linked branch with a full sha; only the driver/owner may land or release.
55
+ Review requires a linked branch with a full sha; landed a branch or commit; released a release link.
56
+ Only the driver/owner may land, release or close; closed holds work that ships no code.
33
57
  Update/assign require the revision you read; a stale edit is refused with the current revision.
34
- Columns: backlog, ready, in_progress, needs_input, review, landed, released.\n`;
58
+ Columns: backlog, ready, in_progress, needs_input, review, landed, released, closed.\n`;
59
+
60
+ /** `REPO@VERSION`: the repository and the version a bug was found in. */
61
+ export const parseAffectsOption = (valueArg: string): { repo: string; version: string } => {
62
+ const separator = valueArg.lastIndexOf('@');
63
+ if (separator < 1 || separator === valueArg.length - 1) throw new Error(`--affects requires REPO@VERSION, such as bellini.io/app@0.5.0: ${valueArg}`);
64
+ return { repo: valueArg.slice(0, separator), version: valueArg.slice(separator + 1) };
65
+ };
35
66
 
36
67
  export interface ITicketCliArguments {
37
68
  operation: TTicketOperation;
@@ -42,13 +73,40 @@ export interface ITicketCliArguments {
42
73
  const common = ['port', 'json'];
43
74
  const actionOptions: Record<string, string[]> = {
44
75
  list: ['mine', 'project', 'status', 'label', 'text'], get: ['limit', 'before', 'comment'],
45
- create: ['project', 'title', 'description', 'kind', 'parent', 'priority', 'labels', 'source', 'attachments', 'column'],
46
- update: ['expected-revision', 'changes', 'title', 'description', 'priority', 'project', 'labels', 'parent', 'clear-parent'],
47
- move: ['column', 'before'], comment: ['body'], link: ['repo', 'branch', 'sha', 'package', 'version'],
76
+ create: ['project', 'title', 'description', 'kind', 'parent', 'priority', 'labels', 'source', 'attachments', 'column', 'release-plan',
77
+ 'deploy-plan', 'window', 'window-targets'],
78
+ update: ['expected-revision', 'changes', 'title', 'description', 'priority', 'project', 'labels', 'parent', 'clear-parent',
79
+ 'release-plan', 'clear-release-plan', 'deploy-plan', 'window', 'window-targets', 'clear-window'],
80
+ move: ['column', 'before'], comment: ['body'], link: ['repo', 'branch', 'sha', 'package', 'version', 'affects'],
81
+ unlink: ['repo', 'branch', 'sha', 'package', 'version', 'affects'],
48
82
  assign: ['expected-revision', 'session-id', 'assignee', 'name', 'kind', 'clear'],
49
83
  ask: ['text', 'options', 'multi', 'no-custom'], answer: ['question', 'choice', 'text'],
50
84
  };
51
- const booleanOptions = new Set(['json', 'mine', 'clear', 'clear-parent', 'multi', 'no-custom']);
85
+ const booleanOptions = new Set(['json', 'mine', 'clear', 'clear-parent', 'clear-release-plan', 'clear-window', 'multi', 'no-custom']);
86
+
87
+ /** `REPO[@VERSION]`: the repository a release plan names and, after the last `@`, the version it should reach. */
88
+ export const parseReleasePlanOption = (valueArg: string): { repo: string; version?: string } => {
89
+ const separator = valueArg.lastIndexOf('@');
90
+ const repo = separator < 0 ? valueArg : valueArg.slice(0, separator), version = separator < 0 ? undefined : valueArg.slice(separator + 1);
91
+ if (!repo || version === '') throw new Error(`--release-plan requires REPO[@VERSION], such as modelprofile.com/agl@41.0.0: ${valueArg}`);
92
+ return { repo, ...(version === undefined ? {} : { version }) };
93
+ };
94
+
95
+ /** `TARGET@VERSION`: the deploy target a deploy plan names and the release it should run. */
96
+ export const parseDeployPlanOption = (valueArg: string): ITicketDeployPlanInput => {
97
+ const separator = valueArg.lastIndexOf('@');
98
+ if (separator <= 0 || separator === valueArg.length - 1) throw new Error(`--deploy-plan requires TARGET@VERSION, such as publicdata@3.1.0: ${valueArg}`);
99
+ return { target: valueArg.slice(0, separator), version: valueArg.slice(separator + 1) };
100
+ };
101
+
102
+ /** `FROM/TO` and `TARGET,…`: a maintenance window's instants (ISO 8601) and the deploy targets it names. */
103
+ export const parseWindowOption = (valueArg: string, targetsArg: string | undefined): ITicketMaintenanceWindow => {
104
+ const [from, to, extra] = valueArg.split('/');
105
+ if (!from || !to || extra !== undefined) throw new Error(`--window requires FROM/TO, such as 2026-10-27T02:00Z/2026-10-27T03:00Z: ${valueArg}`);
106
+ const targets = (targetsArg ?? '').split(',').map((targetArg) => targetArg.trim()).filter(Boolean);
107
+ if (!targets.length) throw new Error('--window requires --window-targets TARGET,….');
108
+ return { from, to, targets };
109
+ };
52
110
 
53
111
  export const parseTicketCliArguments = (argumentsArg: string[]): ITicketCliArguments => {
54
112
  const [action, ...argumentsRest] = argumentsArg;
@@ -77,35 +135,53 @@ export const parseTicketCliArguments = (argumentsArg: string[]): ITicketCliArgum
77
135
  };
78
136
  const optional = (keyArg: string, fieldArg = keyArg) => options.has(keyArg) ? { [fieldArg]: options.get(keyArg) } : {};
79
137
  const labels = () => options.has('labels') ? { labels: options.get('labels')!.split(',').filter(Boolean) } : {};
138
+ const releasePlan = () => options.has('release-plan') ? { releasePlan: parseReleasePlanOption(options.get('release-plan')!) } : {};
139
+ const deployPlan = () => options.has('deploy-plan') ? { deployPlan: parseDeployPlanOption(options.get('deploy-plan')!) } : {};
140
+ if (options.has('window-targets') && !options.has('window')) throw new Error('--window-targets goes with --window FROM/TO.');
141
+ const maintenanceWindow = () => options.has('window') ? { maintenanceWindow: parseWindowOption(options.get('window')!, options.get('window-targets')) } : {};
80
142
  let request: unknown;
81
143
  const operation = action === 'assign' ? 'update' : action as TTicketOperation;
144
+ /** The link `link` adds or `unlink` removes; only a removed fleet release link names its repository and commit. */
145
+ const linkFromOptions = (): TTicketLink => {
146
+ if (options.has('affects')) {
147
+ if (['repo', 'branch', 'sha', 'package', 'version'].some((keyArg) => options.has(keyArg))) throw new Error('--affects stands alone.');
148
+ return { kind: 'affects', ...parseAffectsOption(options.get('affects')!) };
149
+ }
150
+ if (options.has('package') || options.has('version')) {
151
+ if (options.has('branch') || (action === 'link' && (options.has('repo') || options.has('sha')))) throw new Error('A release link cannot carry branch/commit fields.');
152
+ if (options.has('repo') !== options.has('sha')) throw new Error('A fleet release link names both --repo and --sha.');
153
+ // A release the reconciler linked from a tag may name no package; it is removed by its repository and commit.
154
+ return { kind: 'release', version: required('version'), ...(action === 'unlink' && !options.has('package') ? {} : { package: required('package') }),
155
+ ...(options.has('repo') ? { repo: required('repo'), sha: required('sha') } : {}) };
156
+ }
157
+ return options.has('branch') ? { kind: 'branch', repo: required('repo'), branch: required('branch'), sha: required('sha') }
158
+ : { kind: 'commit', repo: required('repo'), sha: required('sha') };
159
+ };
82
160
  if (action === 'list') request = { ...(options.has('mine') ? { mine: true } : {}), ...optional('project'),
83
161
  ...optional('status'), ...optional('label'), ...optional('text') };
84
162
  else if (action === 'get') request = { ticketId, ...optional('before'), ...optional('comment', 'commentId'),
85
163
  ...(options.has('limit') ? { limit: Number(required('limit')) } : {}) };
86
164
  else if (action === 'create') request = { project: required('project'), title: required('title'), ...optional('description'),
87
165
  ...optional('kind'), ...optional('parent', 'parentId'), ...optional('priority'), ...labels(), ...optional('source', 'sourceText'),
88
- ...optional('column', 'columnId'), ...(options.has('attachments') ? { attachments: JSON.parse(required('attachments')) } : {}) };
166
+ ...optional('column', 'columnId'), ...releasePlan(), ...deployPlan(), ...maintenanceWindow(),
167
+ ...(options.has('attachments') ? { attachments: JSON.parse(required('attachments')) } : {}) };
89
168
  else if (action === 'update') {
90
169
  if (options.has('changes') && [...options.keys()].some((keyArg) => !['changes', 'expected-revision', ...common].includes(keyArg))) {
91
170
  throw new Error('--changes cannot be combined with individual change flags.');
92
171
  }
93
172
  if (options.has('parent') && options.has('clear-parent')) throw new Error('--parent and --clear-parent conflict.');
173
+ if (options.has('release-plan') && options.has('clear-release-plan')) throw new Error('--release-plan and --clear-release-plan conflict.');
174
+ if (options.has('window') && options.has('clear-window')) throw new Error('--window and --clear-window conflict.');
94
175
  const changes = options.has('changes') ? JSON.parse(required('changes')) : { ...optional('title'), ...optional('description'),
95
176
  ...optional('priority'), ...optional('project'), ...labels(), ...optional('parent', 'parentId'),
96
- ...(options.has('clear-parent') ? { parentId: null } : {}) };
177
+ ...(options.has('clear-parent') ? { parentId: null } : {}), ...releasePlan(),
178
+ ...(options.has('clear-release-plan') ? { releasePlan: null } : {}), ...deployPlan(),
179
+ ...maintenanceWindow(), ...(options.has('clear-window') ? { maintenanceWindow: null } : {}) };
97
180
  request = { ticketId, expectedRevision: Number(required('expected-revision')), changes };
98
181
  } else if (action === 'move') request = { ticketId, columnId: required('column'), ...optional('before', 'beforeTicketId') };
99
182
  else if (action === 'comment') request = { ticketId, body: required('body') };
100
- else if (action === 'link') {
101
- let link: TTicketLink;
102
- if (options.has('package') || options.has('version')) {
103
- if (options.has('repo') || options.has('branch') || options.has('sha')) throw new Error('A release link cannot carry branch/commit fields.');
104
- link = { kind: 'release', package: required('package'), version: required('version') };
105
- } else link = options.has('branch') ? { kind: 'branch', repo: required('repo'), branch: required('branch'), sha: required('sha') }
106
- : { kind: 'commit', repo: required('repo'), sha: required('sha') };
107
- request = { ticketId, link };
108
- } else if (action === 'ask') {
183
+ else if (action === 'link' || action === 'unlink') request = { ticketId, link: linkFromOptions() };
184
+ else if (action === 'ask') {
109
185
  const choices: unknown = options.has('options') ? JSON.parse(required('options')) : [];
110
186
  if (!Array.isArray(choices)) throw new Error('--options must be a JSON array.');
111
187
  request = { ticketId, question: required('text'),
@@ -16,9 +16,12 @@ const person = plugins.z.object({
16
16
  const actor = person.extend({ role: plugins.z.enum(['owner', 'driver', 'worker']) }).strict();
17
17
  const branchLink = plugins.z.object({ kind: plugins.z.literal('branch'), repo: identifier, branch: identifier, sha }).strict();
18
18
  const commitLink = plugins.z.object({ kind: plugins.z.literal('commit'), repo: identifier, sha }).strict();
19
+ /** A version a bug was found in, as a release names it. */
20
+ const foundVersion = plugins.z.string().regex(/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/u, 'A found-in version looks like 0.5.0.');
19
21
  const link = plugins.z.discriminatedUnion('kind', [
20
22
  branchLink, commitLink,
21
23
  plugins.z.object({ kind: plugins.z.literal('release'), package: identifier, version: identifier }).strict(),
24
+ plugins.z.object({ kind: plugins.z.literal('affects'), repo: identifier.refine((valueArg) => !/[\s@]/u.test(valueArg)), version: foundVersion }).strict(),
22
25
  ]);
23
26
  /**
24
27
  * Every link a stored ticket may hold: what callers link, plus the repository and commit a fleet release adds to its
@@ -33,8 +36,6 @@ const storedLink = plugins.z.discriminatedUnion('kind', [
33
36
  'A release link names its repository or its package.');
34
37
  /** The columns a stored ticket may name. */
35
38
  const storedColumn = plugins.z.enum(ticketColumns);
36
- /** The columns a request may move a ticket to; `closed` is read one release before anything moves a ticket there. */
37
- const requestColumn = plugins.z.enum(ticketColumns).exclude(['closed']);
38
39
  const releasePlan = plugins.z.object({ repo: identifier, version: identifier.optional() }).strict();
39
40
  const deployTargetId = plugins.z.string().regex(fleetDeployTargetIdPattern);
40
41
  const questionId = plugins.z.string().regex(/^Q[1-9][0-9]*$/u);
@@ -45,6 +46,19 @@ const maintenanceWindow = plugins.z.object({ from: plugins.z.iso.datetime(), to:
45
46
  .refine((valueArg) => Date.parse(valueArg.to) > Date.parse(valueArg.from), 'A maintenance window ends after it starts.');
46
47
  /** A stored deploy plan; read one release before anything writes one. */
47
48
  const deployPlan = plugins.z.object({ target: deployTargetId, version: identifier, questionId }).strict();
49
+ /** What a caller plans: a repository name (resolved against fleet discovery before it is stored) and a release version. */
50
+ const releasePlanInput = plugins.z.object({ repo: text(1024).trim().min(1).regex(/^[^\s@]+$/u, 'A repository name holds no spaces or @.'),
51
+ version: plugins.z.string().regex(/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/u, 'A planned version looks like 41.0.0.').optional() }).strict();
52
+ /** What a caller plans as a maintenance window: ISO 8601 instants (an offset is allowed; AGL stores UTC), at most 7 days. */
53
+ const instantInput = plugins.z.string().regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,9})?)?(?:Z|[+-]\d{2}:\d{2})$/u,
54
+ 'An instant is ISO 8601 with a time zone, such as 2026-10-27T02:00Z.').refine((valueArg) => Number.isFinite(Date.parse(valueArg)), 'An instant is a real time.');
55
+ const maintenanceWindowInput = plugins.z.object({ from: instantInput, to: instantInput,
56
+ targets: plugins.z.array(deployTargetId).min(1).max(64).refine((valueArg) => new Set(valueArg).size === valueArg.length, 'A window names each target once.') }).strict()
57
+ .refine((valueArg) => Date.parse(valueArg.to) > Date.parse(valueArg.from), 'A maintenance window ends after it starts.')
58
+ .refine((valueArg) => Date.parse(valueArg.to) - Date.parse(valueArg.from) <= 7 * 24 * 3_600_000, 'A maintenance window lasts at most 7 days.');
59
+ /** What a caller plans as a deploy: the target and the release it should run. */
60
+ const deployPlanInput = plugins.z.object({ target: deployTargetId,
61
+ version: plugins.z.string().regex(/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/u, 'A deploy plan names a release version such as 3.1.0.') }).strict();
48
62
  const attachment = plugins.z.object({ name: text(200).min(1),
49
63
  url: plugins.z.url().max(4096).refine((valueArg) => /^https?:\/\//iu.test(valueArg), 'Attachments require HTTP or HTTPS URLs.') }).strict();
50
64
  const labels = plugins.z.array(text(100).min(1)).max(100).refine((valueArg) => new Set(valueArg).size === valueArg.length);
@@ -61,7 +75,8 @@ const filters = plugins.z.object({ mine: plugins.z.boolean().optional(), project
61
75
  const changes = plugins.z.object({
62
76
  title: text(200).trim().min(1).optional(), description: text(64 * 1024).optional(),
63
77
  priority: priority.optional(), assignee: person.nullable().optional(), parentId: ticketId.nullable().optional(),
64
- project: identifier.optional(), labels: labels.optional(),
78
+ project: identifier.optional(), labels: labels.optional(), releasePlan: releasePlanInput.nullable().optional(),
79
+ maintenanceWindow: maintenanceWindowInput.nullable().optional(), deployPlan: deployPlanInput.optional(),
65
80
  }).strict().refine((valueArg) => Object.keys(valueArg).length > 0, 'At least one change is required.');
66
81
  export const ticketInputSchemas = {
67
82
  list: filters, board: filters,
@@ -72,13 +87,16 @@ export const ticketInputSchemas = {
72
87
  'commentId reads one comment and excludes before and limit.'),
73
88
  comments: plugins.z.object({ ticketId }).strict(),
74
89
  create: plugins.z.object({ project: identifier, kind: kind.optional(), title: text(200).trim().min(1),
75
- description: text(64 * 1024).optional(), columnId: requestColumn.optional(), parentId: ticketId.optional(),
76
- priority: priority.optional(), assignee: person.optional(), labels: labels.optional(), sourceText: text(64 * 1024).optional(),
90
+ description: text(64 * 1024).optional(), columnId: plugins.z.enum(ticketColumns).optional(), parentId: ticketId.optional(),
91
+ priority: priority.optional(), assignee: person.optional(), labels: labels.optional(), releasePlan: releasePlanInput.optional(),
92
+ maintenanceWindow: maintenanceWindowInput.optional(), deployPlan: deployPlanInput.optional(), sourceText: text(64 * 1024).optional(),
77
93
  attachments: plugins.z.array(attachment).max(100).optional() }).strict(),
78
94
  update: plugins.z.object({ ticketId, expectedRevision: plugins.z.number().int().nonnegative(), changes }).strict(),
79
- move: plugins.z.object({ ticketId, columnId: requestColumn, beforeTicketId: ticketId.optional() }).strict(),
95
+ move: plugins.z.object({ ticketId, columnId: plugins.z.enum(ticketColumns), beforeTicketId: ticketId.optional() }).strict(),
80
96
  comment: plugins.z.object({ ticketId, body: plugins.z.union([text(64 * 1024).min(1), referenceContent]) }).strict(),
81
97
  link: plugins.z.object({ ticketId, link }).strict(),
98
+ // A link is removed exactly as it is held, fleet release links (repo, sha) included.
99
+ unlink: plugins.z.object({ ticketId, link: storedLink }).strict(),
82
100
  ask: plugins.z.object({ ticketId, question: text(16 * 1024).trim().min(1),
83
101
  options: plugins.z.array(questionOption).max(20).refine((valueArg) => new Set(valueArg.map((optionArg) => optionArg.label)).size === valueArg.length,
84
102
  'Option labels must be unique.').optional(),
@@ -159,7 +177,8 @@ export const assertTicketResponse = (methodArg: string, valueArg: unknown): void
159
177
  questions: plugins.z.array(ticketQuestionSchema), historyBefore: identifier.optional() }).strict(),
160
178
  comments: plugins.z.object({ comments: plugins.z.array(ticketCommentSchema) }).strict(),
161
179
  create: plugins.z.object({ ticket }).strict(), update: plugins.z.object({ ticket }).strict(),
162
- link: plugins.z.object({ ticket }).strict(), move: plugins.z.object({ tickets: plugins.z.array(ticket) }).strict(),
180
+ link: plugins.z.object({ ticket }).strict(), unlink: plugins.z.object({ ticket }).strict(),
181
+ move: plugins.z.object({ tickets: plugins.z.array(ticket) }).strict(),
163
182
  comment: plugins.z.object({ comment: ticketCommentSchema }).strict(),
164
183
  ask: plugins.z.object({ question: ticketQuestionSchema, ticket }).strict(),
165
184
  answer: plugins.z.object({ question: ticketQuestionSchema, ticket }).strict(),
@@ -1,3 +1,6 @@
1
+ import type * as plugins from './plugins.js';
2
+ import type { ITicketReleasePlan, TTicketColumn, TTicketPriority } from './tickets.js';
3
+
1
4
  /**
2
5
  * Deployments (AGL-909): what runs where, observed rather than claimed. A release is the repository's tag `v<version>`;
3
6
  * what a target runs is what its probe answers, recorded as an observation whenever it changes. Everything else (what a
@@ -96,3 +99,194 @@ export interface IFleetDeployObservation {
96
99
  */
97
100
  artifacts: IFleetDeployArtifact[];
98
101
  }
102
+
103
+ /** What the last probe of a target found; held by the controller, never stored. */
104
+ export interface IFleetDeployProbeState {
105
+ state: 'up' | 'down' | 'unknown';
106
+ checkedAt?: string;
107
+ /** The first failed probe of the failure that still lasts. */
108
+ downSince?: string;
109
+ error?: string;
110
+ }
111
+
112
+ /** A release: the tag `v<version>` and the commit it names. */
113
+ export interface IFleetDeployRelease {
114
+ version: string;
115
+ sha: string;
116
+ taggedAt?: string;
117
+ }
118
+
119
+ /** A ticket as the deploy views name it. */
120
+ export interface IFleetDeployTicket {
121
+ key: string;
122
+ title: string;
123
+ priority: TTicketPriority;
124
+ columnId: TTicketColumn;
125
+ /** The release that shipped it, for a ticket that does not run yet. */
126
+ version?: string;
127
+ }
128
+
129
+ /** A ticket planning a release of the repository and not released yet; a hotfix is an urgent one. */
130
+ export interface IFleetReleasePlanTicket extends IFleetDeployTicket {
131
+ /** The version the plan names; absent means the next release. */
132
+ plannedVersion?: string;
133
+ }
134
+
135
+ /** When a target's deploys may run now: any time, inside a maintenance window, or (the AGL controller) when no session is busy. */
136
+ export type TFleetDeployCondition = TFleetDeployWhen | 'idle';
137
+
138
+ /** Where a maintenance window stands now: before it, in it, or after it. */
139
+ export type TFleetMaintenanceWindowState = 'scheduled' | 'active' | 'done';
140
+
141
+ /**
142
+ * The owner's go on a maintenance window: `given` for the owner's own window or one the owner approved, `waiting` while
143
+ * the question of one the driver proposed is open, `declined`. Only a given window counts.
144
+ */
145
+ export type TFleetDeployWindowGo = 'given' | 'waiting' | 'declined';
146
+
147
+ /** A maintenance window as the deploy views show it: its ticket, its schedule, where it stands now and the owner's go. */
148
+ export interface IFleetDeployWindow extends IFleetDeployTicket {
149
+ from: string;
150
+ to: string;
151
+ targets: string[];
152
+ state: TFleetMaintenanceWindowState;
153
+ go: TFleetDeployWindowGo;
154
+ /** The owner's question on the ticket, for a window the driver proposed. */
155
+ questionId?: string;
156
+ }
157
+
158
+ /**
159
+ * The owner's go on a deploy plan, from the answer to its question: `waiting` while it is open, `now`, `window` (the next
160
+ * maintenance window), `idle` (the AGL controller: when no session is busy) or `hold`.
161
+ */
162
+ export type TFleetDeployGo = 'waiting' | 'now' | 'window' | 'idle' | 'hold';
163
+
164
+ /** A ticket planning a deploy of a target, not done yet: the release it should run and the owner's go. */
165
+ export interface IFleetDeployPlan extends IFleetDeployTicket {
166
+ target: string;
167
+ /** The target should run this release or a newer one. */
168
+ version: string;
169
+ questionId: string;
170
+ go: TFleetDeployGo;
171
+ /** When the owner answered. */
172
+ answeredAt?: string;
173
+ /** For `window`: the window the deploy is queued into, the next one the owner gave for the target; absent while none is. */
174
+ window?: IFleetDeployWindow;
175
+ /** Who deploys it: the session the plan ticket is assigned to, a direct report; absent is the driver. */
176
+ assignee?: string;
177
+ }
178
+
179
+ /** An open bug found in the version a target runs (its `affects` link), whose fix does not run there. */
180
+ export interface IFleetDeployBug extends IFleetDeployTicket {
181
+ foundIn: string;
182
+ /** The commit its fix landed as on main, when it landed. */
183
+ fixLandedSha?: string;
184
+ /** The first release holding that commit. */
185
+ fixedIn?: string;
186
+ }
187
+
188
+ /** One target as `agl deploy status` and the Deployments view show it, computed when it is read. */
189
+ export interface IFleetDeployTargetStatus {
190
+ target: IFleetDeployTarget & { builtIn?: true };
191
+ /** The repository's `org/name` as fleet discovery found its checkout; absent when no checkout holds it. */
192
+ repository?: string;
193
+ /**
194
+ * What the target runs, from its newest observation. `untagged` marks a build whose commit is not the one its
195
+ * version's tag on the remote names, such as a development checkout's.
196
+ */
197
+ running?: { version: string; sha?: string; since: string; previousVersion?: string; rolledBack?: true; untagged?: true };
198
+ probe: IFleetDeployProbeState;
199
+ /** The newest release tag of the repository. */
200
+ latest?: IFleetDeployRelease;
201
+ /** Releases newer than the running version, newest first, and the tickets they shipped. */
202
+ notRunning: { releases: IFleetDeployRelease[]; tickets: IFleetDeployTicket[] };
203
+ /** Landed tickets of the repository that the newest release does not hold: what the next release ships. */
204
+ landedAfterLatest: IFleetDeployTicket[];
205
+ openBugs: IFleetDeployBug[];
206
+ plans: IFleetReleasePlanTicket[];
207
+ /** When its deploys may run: any time, in a maintenance window, or (the AGL controller) when no session is busy. */
208
+ deployWhen: TFleetDeployCondition;
209
+ /** For `idle`: the sessions busy now. */
210
+ busySessions?: number;
211
+ /** Whether a deploy may run now: always for `anytime`, inside an active window the owner gave for `window`, with no session busy for `idle`. */
212
+ deployOpen: boolean;
213
+ /** The maintenance windows planned for the target that have not ended, the earliest first. */
214
+ windows: IFleetDeployWindow[];
215
+ /** Its deploy plans whose ticket is not done. */
216
+ deployPlans: IFleetDeployPlan[];
217
+ }
218
+
219
+ export interface IFleetDeployStatus {
220
+ checkedAt: string;
221
+ targets: IFleetDeployTargetStatus[];
222
+ /** Every maintenance window on a ticket that is not done, scheduled, active or done, the earliest first. */
223
+ windows: IFleetDeployWindow[];
224
+ }
225
+
226
+ /** A repository's release state, as `agl release status` shows it. */
227
+ export interface IFleetRepositoryReleaseStatus {
228
+ /** `org/name`. */
229
+ repo: string;
230
+ /** The fleet id. */
231
+ id: string;
232
+ latest?: IFleetDeployRelease;
233
+ plans: IFleetReleasePlanTicket[];
234
+ landedAfterLatest: IFleetDeployTicket[];
235
+ /** The ids of the deploy targets that run it. */
236
+ targets: string[];
237
+ }
238
+
239
+ export interface IFleetReleaseStatus {
240
+ checkedAt: string;
241
+ repositories: IFleetRepositoryReleaseStatus[];
242
+ }
243
+
244
+ /** Where a ticket's work runs, for the ticket detail ("Where it runs"), computed when it is read. */
245
+ export interface IFleetDeployTicketPlacement {
246
+ ticketKey: string;
247
+ /** Per repository: the commit it landed as, its branch, and the first release holding it ("fixed in"). */
248
+ landed: { repo: string; sha: string; branch?: string; fixedIn?: IFleetDeployRelease }[];
249
+ /** Per deploy target of those repositories: what it runs and whether that holds the ticket's release. */
250
+ runs: { targetId: string; name: string; environment?: string; repo: string; version?: string;
251
+ probe: IFleetDeployProbeState['state']; runs: boolean; shippedIn?: string }[];
252
+ /** The versions it was found in (its `affects` links). */
253
+ foundIn: { repo: string; version: string }[];
254
+ releasePlan?: ITicketReleasePlan;
255
+ /** Its maintenance window and where it stands, while the ticket is not done. */
256
+ maintenanceWindow?: IFleetDeployWindow;
257
+ /** Its deploy plan with the owner's go, while the ticket is not done, and the target as the views name it. */
258
+ deployPlan?: { plan: IFleetDeployPlan; targetName: string; environment?: string; deployWhen: TFleetDeployCondition };
259
+ }
260
+
261
+ /** Every request of the deploy views; the browser sends the `controller.deploy.*` ones, `agl deploy` the `agl.mcp.deploy.*` ones. */
262
+ export interface IFleetDeployOperations {
263
+ status: { request: { targetId?: string }; response: IFleetDeployStatus };
264
+ history: { request: { targetId: string; limit?: number }; response: { targetId: string; observations: IFleetDeployObservation[] } };
265
+ probe: { request: { targetId: string }; response: IFleetDeployTargetStatus };
266
+ release: { request: { repo?: string }; response: IFleetReleaseStatus };
267
+ ticket: { request: { ticketKey: string }; response: IFleetDeployTicketPlacement };
268
+ }
269
+ export type TFleetDeployOperation = keyof IFleetDeployOperations;
270
+ export const fleetDeployOperations = ['status', 'history', 'probe', 'release', 'ticket'] as const satisfies readonly TFleetDeployOperation[];
271
+
272
+ /**
273
+ * The deploy views in the browser. `status` and `history` read; `probe` asks for a probe of one target now and claims
274
+ * nothing (a deploy path calls it after a deploy); `release` reads a repository's release state.
275
+ */
276
+ export type TControllerDeployRequest<TOperation extends TFleetDeployOperation> = {
277
+ method: `controller.deploy.${TOperation}`;
278
+ request: IFleetDeployOperations[TOperation]['request'];
279
+ response: IFleetDeployOperations[TOperation]['response'];
280
+ } & plugins.typedrequestInterfaces.ITypedRequest;
281
+ export type TControllerDeployTypedRequest = { [TOperation in TFleetDeployOperation]: TControllerDeployRequest<TOperation> }[TFleetDeployOperation];
282
+
283
+ /** The same through the controller's private channel, for `agl deploy` and `agl release status`: the local owner capability. */
284
+ export const controllerMcpDeployMethods = ['agl.mcp.deploy.status', 'agl.mcp.deploy.history', 'agl.mcp.deploy.probe', 'agl.mcp.deploy.release',
285
+ 'agl.mcp.deploy.ticket'] as const;
286
+ export type TControllerMcpDeployMethod = (typeof controllerMcpDeployMethods)[number];
287
+ export type TControllerMcpDeployRequest<TOperation extends TFleetDeployOperation> = {
288
+ method: `agl.mcp.deploy.${TOperation}`;
289
+ request: IFleetDeployOperations[TOperation]['request'] & { ownerToken: string };
290
+ response: IFleetDeployOperations[TOperation]['response'];
291
+ } & plugins.typedrequestInterfaces.ITypedRequest;
292
+ export type TControllerMcpDeployTypedRequest = { [TOperation in TFleetDeployOperation]: TControllerMcpDeployRequest<TOperation> }[TFleetDeployOperation];
@@ -94,14 +94,29 @@ export interface IFleetTicketSync { state: IFleetTicketEffect['state']; effects:
94
94
  export interface IFleetReconcileResult { operation: 'reconcile'; ticketSync: IFleetTicketSync }
95
95
  export interface IFleetCheck { name: string; passed: number; total: number }
96
96
  export interface IFleetLandResult {
97
- operation: 'land'; repo: string; branch: string; sha: string; checks: IFleetCheck[];
97
+ operation: 'land'; repo: string;
98
+ /** The repository as `org/name`, the name every link fleet writes carries. */
99
+ repository: string;
100
+ branch: string; sha: string; checks: IFleetCheck[];
98
101
  /** Where the worktree's evidence was archived; absent when fleet landed from its own temporary worktree. */
99
102
  archive?: string; resolutions: string[];
100
103
  ticketSync?: IFleetTicketSync;
101
104
  }
102
105
  export interface IFleetReleaseResult {
103
- operation: 'release'; repo: string; sha: string; version: string; toolingCommit?: string;
106
+ operation: 'release'; repo: string;
107
+ /** The repository as `org/name`, the name every link fleet writes carries. */
108
+ repository: string;
109
+ /** The release commit, which the tag `v<version>` names. */
110
+ sha: string; version: string;
111
+ /**
112
+ * Whether the remote holds the tag `v<version>` at `sha` once the release finished. A release is the remote's tag: only
113
+ * then does fleet release the operation's own ticket.
114
+ */
115
+ tagged: boolean;
116
+ toolingCommit?: string;
104
117
  checks: IFleetCheck[]; packages: string[]; registries: string[];
118
+ /** The other landed tickets whose landed commit in this repository the release contains: fleet links and releases each. */
119
+ contained?: string[];
105
120
  ticketSync?: IFleetTicketSync;
106
121
  }
107
122
  export interface IFleetToolingResult {
@@ -22,6 +22,18 @@ export interface IFleetWorkerProfile {
22
22
  approvalPolicy?: string;
23
23
  sandbox?: string;
24
24
  }
25
+ /**
26
+ * Why the fleet would refuse to relaunch a Claude Code session now: `invalidId`, not its full session id;
27
+ * `unsupported`, Claude cannot start there (its version, or a checkout it does not trust); `notInInventory`, the
28
+ * profile's Claude home does not list it, so AGL cannot prove it is not running; `running`, a process runs it (`pid`);
29
+ * `working`, its turn is under way; `noAgentId`, a background session without agent id; `noTranscript`, no readable
30
+ * saved conversation in that directory.
31
+ */
32
+ export interface IFleetRelaunchBlocker {
33
+ code: 'invalidId' | 'unsupported' | 'notInInventory' | 'running' | 'working' | 'noAgentId' | 'noTranscript';
34
+ message: string;
35
+ pid?: number;
36
+ }
25
37
  export interface IFleetWorkerAbsenceProof {
26
38
  kind: 'start-absent' | 'session-gone';
27
39
  home: string;
@@ -215,6 +227,12 @@ export type TFleetEventKind = 'worker.changed' | 'worker.turn.ended' | 'worker.r
215
227
  * runs on it, what stays refused and where the compatibility check is listed. Published to every owner.
216
228
  */
217
229
  | 'harness.release.discovered'
230
+ /** A deploy target (`target`) answered another version, commit or artifact set than it ran (`version`); `text` says what changed. */
231
+ | 'deploy.observed'
232
+ /** A deploy target's probe stopped answering on two probes in a row; once per failure, `error` says why. */
233
+ | 'deploy.probe.failed'
234
+ /** A deploy target whose probe had failed answers again; `text` says since when it was down. */
235
+ | 'deploy.probe.recovered'
218
236
  | 'host.load';
219
237
  export interface IFleetEventCursor { epoch: string; after: number }
220
238
  export interface IFleetEvent {
@@ -242,6 +260,8 @@ export interface IFleetEvent {
242
260
  repo?: string;
243
261
  operationId?: string;
244
262
  version?: string;
263
+ /** The deploy target a `deploy.*` event is about. */
264
+ target?: string;
245
265
  metrics?: IControllerSystemMetrics;
246
266
  }
247
267
  export interface IFleetWatchResult { cursor: IFleetEventCursor; reset: boolean; events: IFleetEvent[] }
@@ -0,0 +1,20 @@
1
+ const versionPattern = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/u;
2
+ /** A release version as a tag or probe gives it, without a leading `v`; undefined when it is no semantic version. */
3
+ export const fleetVersion = (valueArg: string): string | undefined => {
4
+ const match = versionPattern.exec(valueArg.trim());
5
+ return match ? valueArg.trim().replace(/^v/u, '') : undefined;
6
+ };
7
+ /** Semantic version order; a prerelease sorts before its release. */
8
+ export const compareFleetVersions = (leftArg: string, rightArg: string): number => {
9
+ const left = versionPattern.exec(leftArg), right = versionPattern.exec(rightArg);
10
+ if (!left || !right) return leftArg.localeCompare(rightArg);
11
+ for (const index of [1, 2, 3]) {
12
+ const difference = Number(left[index]) - Number(right[index]);
13
+ if (difference) return difference;
14
+ }
15
+ if (left[4] === right[4]) return 0;
16
+ if (left[4] === undefined) return 1;
17
+ if (right[4] === undefined) return -1;
18
+ return left[4].localeCompare(right[4], 'en', { numeric: true });
19
+ };
20
+