agl 43.8.0 → 43.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (146) hide show
  1. package/changelog.md +28 -0
  2. package/dist_serve/bundle.js +1157 -1122
  3. package/dist_serve/bundle.js.map +2 -2
  4. package/dist_ts/00_commitinfo_data.js +2 -2
  5. package/dist_ts/aglapi/aglapisurface.document.js +826 -8
  6. package/dist_ts/aglapi/interfaces.d.ts +8 -0
  7. package/dist_ts/aglapi/interfaces.js +3 -1
  8. package/dist_ts/classes.accountsactions.d.ts +3 -1
  9. package/dist_ts/classes.accountsactions.js +17 -1
  10. package/dist_ts/classes.controller.d.ts +1 -1
  11. package/dist_ts/classes.controller.js +21 -7
  12. package/dist_ts/classes.inferencegateway.js +7 -5
  13. package/dist_ts/classes.inferenceplacement.d.ts +1 -1
  14. package/dist_ts/classes.inferencerouter.d.ts +20 -3
  15. package/dist_ts/classes.inferencerouter.js +37 -10
  16. package/dist_ts/classes.inferenceservice.js +2 -2
  17. package/dist_ts/classes.mcpclient.js +3 -3
  18. package/dist_ts/classes.mcpcontrollerhost.js +3 -2
  19. package/dist_ts/classes.mcptools.d.ts +1 -1
  20. package/dist_ts/classes.mcptools.js +2 -1
  21. package/dist_ts/classes.ticketnotifier.d.ts +2 -2
  22. package/dist_ts/classes.ticketnotifier.js +6 -4
  23. package/dist_ts/classes.ticketstore.d.ts +36 -8
  24. package/dist_ts/classes.ticketstore.js +131 -29
  25. package/dist_ts/classes.workercallers.d.ts +35 -1
  26. package/dist_ts/classes.workercallers.js +139 -28
  27. package/dist_ts/fleet/classes.boardpump.d.ts +1 -1
  28. package/dist_ts/fleet/classes.boardpump.js +4 -2
  29. package/dist_ts/fleet/classes.ticketeffects.d.ts +11 -0
  30. package/dist_ts/fleet/classes.ticketeffects.js +28 -1
  31. package/dist_ts/fleet/classes.workers.d.ts +18 -1
  32. package/dist_ts/fleet/classes.workers.js +49 -8
  33. package/dist_ts/fleet/functions.workervalidation.js +7 -4
  34. package/dist_ts/functions.deviceapi.js +3 -1
  35. package/dist_ts/functions.fleetworkercli.d.ts +3 -1
  36. package/dist_ts/functions.fleetworkercli.js +6 -2
  37. package/dist_ts/functions.inferencecli.js +4 -1
  38. package/dist_ts/functions.mcpfleetworkertools.js +3 -3
  39. package/dist_ts/functions.mcptickettools.d.ts +60 -0
  40. package/dist_ts/functions.mcptickettools.js +4 -3
  41. package/dist_ts/functions.proxycapacity.d.ts +2 -1
  42. package/dist_ts/functions.proxycapacity.js +6 -3
  43. package/dist_ts/functions.proxycapacitycli.js +2 -2
  44. package/dist_ts/functions.ticketcli.d.ts +4 -2
  45. package/dist_ts/functions.ticketcli.js +70 -4
  46. package/dist_ts/functions.ticketlisting.d.ts +38 -0
  47. package/dist_ts/functions.ticketlisting.js +211 -0
  48. package/dist_ts/functions.ticketvalidation.d.ts +62 -0
  49. package/dist_ts/functions.ticketvalidation.js +41 -3
  50. package/dist_ts/functions.workerprocessproof.d.ts +6 -0
  51. package/dist_ts/functions.workerprocessproof.js +8 -3
  52. package/dist_ts/interfaces.auth.d.ts +1 -1
  53. package/dist_ts/interfaces.auth.js +2 -1
  54. package/dist_ts/interfaces.flexipc.d.ts +3 -1
  55. package/dist_ts/interfaces.flexipc.js +1 -1
  56. package/dist_ts_authswitch/authority-contract.d.ts +25 -0
  57. package/dist_ts_authswitch/authority-contract.js +1 -1
  58. package/dist_ts_authswitch/authority-overview.d.ts +7 -0
  59. package/dist_ts_authswitch/authority-overview.js +10 -6
  60. package/dist_ts_authswitch/authority-placement.d.ts +5 -2
  61. package/dist_ts_authswitch/authority-placement.js +6 -3
  62. package/dist_ts_authswitch/classes.authoritybroker.d.ts +6 -0
  63. package/dist_ts_authswitch/classes.authoritybroker.js +26 -1
  64. package/dist_ts_authswitch/classes.authoritycli.d.ts +1 -0
  65. package/dist_ts_authswitch/classes.authoritycli.js +50 -4
  66. package/dist_ts_authswitch/classes.authorityclient.d.ts +3 -1
  67. package/dist_ts_authswitch/classes.authorityclient.js +9 -4
  68. package/dist_ts_authswitch/classes.authoritydaemon.js +7 -1
  69. package/dist_ts_authswitch/classes.authoritydatabase.js +5 -1
  70. package/dist_ts_authswitch/classes.authoritymodels.d.ts +7 -0
  71. package/dist_ts_authswitch/classes.authoritymodels.js +13 -6
  72. package/dist_ts_interfaces/fleetworkers.d.ts +26 -1
  73. package/dist_ts_interfaces/fleetworkers.js +1 -1
  74. package/dist_ts_interfaces/interfaces.d.ts +4 -2
  75. package/dist_ts_interfaces/interfaces.js +1 -1
  76. package/dist_ts_interfaces/mcprequests.d.ts +1 -1
  77. package/dist_ts_interfaces/proxycapacity.d.ts +1 -1
  78. package/dist_ts_interfaces/requests.accounts.d.ts +19 -0
  79. package/dist_ts_interfaces/requests.accounts.js +1 -1
  80. package/dist_ts_interfaces/requests.d.ts +2 -2
  81. package/dist_ts_interfaces/requests.fleetworkers.d.ts +3 -1
  82. package/dist_ts_interfaces/requests.js +1 -1
  83. package/dist_ts_interfaces/requests.tickets.d.ts +31 -3
  84. package/dist_ts_interfaces/requests.tickets.js +2 -2
  85. package/dist_ts_interfaces/tickets.d.ts +174 -2
  86. package/dist_ts_interfaces/tickets.js +20 -2
  87. package/dist_ts_migration/v41_ticketclosedcolumn.js +7 -3
  88. package/docs/authswitch.md +22 -0
  89. package/package.json +2 -2
  90. package/readme.md +85 -6
  91. package/ts/00_commitinfo_data.ts +1 -1
  92. package/ts/aglapi/aglapisurface.document.ts +825 -7
  93. package/ts/aglapi/interfaces.ts +2 -0
  94. package/ts/classes.accountsactions.ts +25 -0
  95. package/ts/classes.controller.ts +18 -3
  96. package/ts/classes.inferencegateway.ts +6 -4
  97. package/ts/classes.inferenceplacement.ts +1 -1
  98. package/ts/classes.inferencerouter.ts +49 -10
  99. package/ts/classes.inferenceservice.ts +1 -1
  100. package/ts/classes.mcpclient.ts +2 -2
  101. package/ts/classes.mcpcontrollerhost.ts +2 -1
  102. package/ts/classes.mcptools.ts +1 -0
  103. package/ts/classes.ticketnotifier.ts +5 -3
  104. package/ts/classes.ticketstore.ts +124 -27
  105. package/ts/classes.workercallers.ts +165 -28
  106. package/ts/fleet/classes.boardpump.ts +3 -2
  107. package/ts/fleet/classes.ticketeffects.ts +25 -0
  108. package/ts/fleet/classes.workers.ts +47 -7
  109. package/ts/fleet/functions.workervalidation.ts +6 -3
  110. package/ts/functions.deviceapi.ts +2 -0
  111. package/ts/functions.fleetworkercli.ts +5 -1
  112. package/ts/functions.inferencecli.ts +2 -0
  113. package/ts/functions.mcpfleetworkertools.ts +2 -2
  114. package/ts/functions.mcptickettools.ts +3 -2
  115. package/ts/functions.proxycapacity.ts +5 -2
  116. package/ts/functions.proxycapacitycli.ts +1 -1
  117. package/ts/functions.ticketcli.ts +70 -5
  118. package/ts/functions.ticketlisting.ts +214 -0
  119. package/ts/functions.ticketvalidation.ts +41 -2
  120. package/ts/functions.workerprocessproof.ts +10 -2
  121. package/ts/interfaces.auth.ts +1 -0
  122. package/ts/interfaces.flexipc.ts +3 -1
  123. package/ts_authswitch/authority-contract.ts +20 -0
  124. package/ts_authswitch/authority-overview.ts +17 -6
  125. package/ts_authswitch/authority-placement.ts +7 -3
  126. package/ts_authswitch/classes.authoritybroker.ts +24 -0
  127. package/ts_authswitch/classes.authoritycli.ts +58 -4
  128. package/ts_authswitch/classes.authorityclient.ts +11 -4
  129. package/ts_authswitch/classes.authoritydaemon.ts +8 -1
  130. package/ts_authswitch/classes.authoritydatabase.ts +3 -0
  131. package/ts_authswitch/classes.authoritymodels.ts +12 -4
  132. package/ts_interfaces/fleetworkers.ts +26 -1
  133. package/ts_interfaces/interfaces.ts +4 -2
  134. package/ts_interfaces/proxycapacity.ts +1 -1
  135. package/ts_interfaces/requests.accounts.ts +17 -0
  136. package/ts_interfaces/requests.fleetworkers.ts +3 -1
  137. package/ts_interfaces/requests.tickets.ts +32 -2
  138. package/ts_interfaces/requests.ts +2 -0
  139. package/ts_interfaces/tickets.ts +136 -3
  140. package/ts_migration/v41_ticketclosedcolumn.ts +6 -2
  141. package/ts_web/00_commitinfo_data.ts +1 -1
  142. package/ts_web/accounts.templates.ts +12 -2
  143. package/ts_web/classes.accountsreadmodel.ts +42 -6
  144. package/ts_web/elements.accounts.ts +45 -3
  145. package/ts_web/elements.harnesscontrollerapp.ts +6 -1
  146. package/ts_web/elements.inbox.ts +50 -9
@@ -13,8 +13,8 @@ const descriptions: Record<TFleetWorkerAction, string> = {
13
13
  archive: 'Archive a settled worker. Codex archives natively; Claude archives the AGL registry only and retains its transcript/worktree. Returns a job handle.',
14
14
  refresh: 'Start a fresh thread from the settled predecessor\'s self-contained Handoff report. Store the successor before retiring the predecessor. With profile, the successor launches on that configured profile, which must run the predecessor\'s harness (only move changes the harness); without it the successor keeps the predecessor\'s recorded profile. Returns a job handle.',
15
15
  move: 'Move a settled Claude lane to a new shared-daemon Codex thread with its Handoff report. Identify the successor before retiring Claude. Returns a job handle.',
16
- list: 'List this owner\'s fleet workers as summaries, newest first, in pages of limit (1-100, default 50): identity, ticket, state, native id, cwd, the native status, newest turn outcome and native wait last observed, and fence flags (an unresolved dispatch with its action and since, a lost or reconfirmed dispatch, a recorded error). total, fenced and failed (recorded errors and failed turn outcomes) count the whole filtered set, so a page never hides a fence. Continue with nextCursor and the same filter (archived, ticketKey, state, harness); a cursor of another filter or one after a worker no longer held as it was is refused. view full returns every full record unpaged; fleet_worker_get returns one worker whole.',
17
- get: 'Read one of this owner\'s fleet workers, archived ones included, by name or id: its full record (dispatch fence, lost, reconfirmed and re-bind resolutions with their attribution and proof, error) and the native status, turn outcome and start, native wait and excerpt the controller last observed.',
16
+ list: 'List this owner\'s fleet workers as summaries, newest first, in pages of limit (1-100, default 50): identity, ticket, state, native id, cwd, the native status, newest turn outcome and native wait last observed, and fence flags (an unresolved dispatch with its action and since, a lost or reconfirmed dispatch, a recorded error), and identity {unverified, reason, since} while a worker\'s MCP calls are refused its identity. total, fenced and failed (recorded errors and failed turn outcomes) count the whole filtered set, so a page never hides a fence. Continue with nextCursor and the same filter (archived, ticketKey, state, harness); a cursor of another filter or one after a worker no longer held as it was is refused. view full returns every full record unpaged; fleet_worker_get returns one worker whole.',
17
+ get: 'Read one of this owner\'s fleet workers, archived ones included, by name or id: its full record (dispatch fence, lost, reconfirmed and re-bind resolutions with their attribution and proof, error) and the native status, turn outcome and start, native wait and excerpt the controller last observed, and identity {unverified, reason, since} while its MCP calls are refused its identity.',
18
18
  status: 'Read a fleet operation job (the handle a fleet_worker_* action returns), not a host job. Jobs are transient; bindings and unresolved dispatches survive restart. Inspect unknown native outcomes before retrying.',
19
19
  'job-wait': 'Wait until a fleet operation job (the handle a fleet_worker_* action returns, not a host job) succeeds or fails, or timeoutMs (at most 240000) passes; timedOut tells which. Waiting, a timeout or an abandoned wait never cancels the job. A job the controller no longer holds (jobs end with a controller restart or eviction) is JOB_UNAVAILABLE, not failed: read the worker with fleet_worker_get. A failed job\'s errorOutcome is refused when nothing reached a native session, unknown when it may have (a steer may have been delivered): never repeat an unknown one before reading the worker.',
20
20
  'native-message': 'Reach a Claude Code background job that no fleet worker binds with an attributed message, through Claude Code itself, as the browser\'s native session send does: a settled (done, blocked or stopped) job is woken with it (`claude --bg --resume <id> <text>`), a running one takes it in its inbox through Claude Code\'s own SendMessage, accepted and queued there, not yet read. nativeId is the full session id or a unique prefix of at least 8 characters; an ambiguous prefix is refused. A running job without a session name of its own (none, or one another running session shares), a failed or held job, a fleet worker\'s session and a project conversation are refused with their reason. The message arrives behind the same attribution header as session_message, naming the sender label and the local owner capability, never as the job\'s user. It holds no dispatch fence, writes no ticket comment and does not observe the turn that reads it; the receipt (delivery native-wake or native-inbox) names the command that adopts the job as a fleet worker. Returns a job handle; an unknown outcome is never retried.',
@@ -3,7 +3,8 @@ import type { TTicketOperation } from '../ts_interfaces/tickets.js';
3
3
 
4
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, 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.' },
6
+ { name: 'board_overview', operation: 'overview', description: 'Read the whole board at a glance in one bounded answer, without any ticket\'s texts; start here. Counts by column, by priority (open tickets), by AutoLabel, by project and by assignee, each open epic\'s progress over its direct children (children, done, columns), and under attention the tickets that need someone: urgent, needsInput, openQuestions, review, unassignedReady and stale (in_progress, needs_input or review work without a change for staleDays, default 3, oldest first). recent holds the tickets changed last. Every list holds at most limit tickets (default 5, at most 50) as summaries and its total counts all of them; projects, assignees and epics list at most 50 beside projectsTotal, assigneesTotal and epicsTotal. project narrows to one project, mine to your verified session. Continue with tickets_list for a whole list and ticket_get for one ticket.' },
7
+ { name: 'tickets_list', operation: 'page', description: 'List the shared board across all projects in pages of limit tickets (1-200, default 50; a page also ends at 256 KiB). Tickets are summaries: key, revision, project, kind, title, columnId, priority, updatedAt, and where present assignee, parentId, labels, autoLabels, links (a count per kind), releasePlan, deployPlan, maintenanceWindow and openQuestions; view full returns whole tickets with description and source words, ticket_get one ticket with its history. total and columns (a count per column) describe everything the filters match, on every page, so a page never hides how much there is. Filter by mine (your verified session), project, status or statuses (several columns), open (true leaves out released and closed, false keeps only those), kind, priorities, parent (a ticket\'s direct children, such as an epic\'s tasks), assignee (a person id or a session id as a ticket shows it, never a name), unassigned, keys (up to 200 tickets by key in one call), updatedSince (an ISO 8601 instant), label or text (in key, title, description or source words). 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. sort is board (default: by column, then position), updated or created (newest first) or priority (urgent first). Continue with nextCursor and the same filters, sort and view; a cursor of other ones is refused. moved tells that the board changed since the first page: a ticket that changed its place meanwhile may be missing or shown twice, so list again when the reading must be exact.' },
7
8
  { 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
9
  { 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
10
  { 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.' },
@@ -14,4 +15,4 @@ export const ticketToolDefinitions = [
14
15
  { 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.' },
15
16
  ].map((definitionArg) => ({ ...definitionArg, operation: definitionArg.operation as TTicketOperation,
16
17
  description: definitionArg.description + workflow, inputSchema: ticketInputSchemas[definitionArg.operation as TTicketOperation],
17
- readOnly: definitionArg.operation === 'list' || definitionArg.operation === 'get' }));
18
+ readOnly: definitionArg.operation === 'page' || definitionArg.operation === 'overview' || definitionArg.operation === 'get' }));
@@ -145,7 +145,8 @@ const projectMember = (accountArg: IProxyCapacityAccount, planArg: string, nowAr
145
145
  };
146
146
 
147
147
  /**
148
- * A pool's room for new work (AGL-1097). Its members are the pool's subscription sign-ins that have not lapsed and whose
148
+ * A pool's room for new work (AGL-1097). Its members are the pool's subscription sign-ins that have not lapsed, are not
149
+ * paused by their owner and whose
149
150
  * held reading states a plan the pool counts (`proxyCapacityPlans`), stale or not; API keys never count. The room is
150
151
  * the headroom its members add now (see `projectMember`), summed.
151
152
  *
@@ -161,7 +162,9 @@ export const proxyPoolCapacity = (providerArg: TProxyCapacityProvider, accountsA
161
162
  const { now, minHeadroom, observedSince } = optionsArg;
162
163
  const counted = accountsArg.flatMap((accountArg) => {
163
164
  const { status } = accountArg;
164
- if (status.provider !== providerArg || status.credential !== 'subscription' || status.lifecycle === 'lapsed') return [];
165
+ // An account its owner holds paused (AGL-1933) takes no work, so it adds no room and is no member.
166
+ if (status.provider !== providerArg || status.credential !== 'subscription' || status.lifecycle === 'lapsed'
167
+ || status.pausedAt) return [];
165
168
  const plan = proxyCapacityHeldPlan(providerArg, accountArg.usage);
166
169
  return plan !== null && proxyCapacityPlanCounts(providerArg, plan) ? [{ account: accountArg, plan }] : [];
167
170
  }).sort((left, right) => left.account.status.id.localeCompare(right.account.status.id));
@@ -49,7 +49,7 @@ const poolText = (poolArg: IProxyCapacityPool, observedSinceArg: string): string
49
49
  `${poolNames[poolArg.provider]} pool (${poolArg.provider}): ${verdictText}; room ${percent(poolArg.room)}, `
50
50
  + `minimum ${poolArg.minHeadroom}%; last provider 429 on a member: ${poolArg.last429At ?? `none since ${observedSinceArg}`}`,
51
51
  ...poolArg.members.length ? poolArg.members.map(memberText)
52
- : [` no account counts (${countedPlans(poolArg.provider)}, a subscription sign-in that has not lapsed)`],
52
+ : [` no account counts (${countedPlans(poolArg.provider)}, a subscription sign-in that has not lapsed and is not paused)`],
53
53
  ];
54
54
  };
55
55
 
@@ -4,11 +4,27 @@ import { withLocalConfigurationOwner } from './functions.configurationowner.js';
4
4
  import { assertTicketRequest } from './functions.ticketvalidation.js';
5
5
  import { defaultControllerPort } from './classes.config.js';
6
6
  import type {
7
- ITicketChanges, ITicketDeployPlanInput, ITicketMaintenanceWindow, ITicketPerson, TTicketOperation, TTicketRequest, TTicketLink,
7
+ ITicketChanges, ITicketDeployPlanInput, ITicketMaintenanceWindow, ITicketOverview, ITicketPerson, ITicketSummary, TTicketOperation,
8
+ TTicketRequest, TTicketLink,
8
9
  } from '../ts_interfaces/tickets.js';
9
10
 
10
- export const ticketCliHelp = `Usage: agl ticket <list|get|create|update|move|comment|link|unlink|assign|ask|answer> [AGL-<n>] [options]
11
+ export const ticketCliHelp = `Usage: agl ticket <overview|page|list|get|create|update|move|comment|link|unlink|assign|ask|answer> [AGL-<n>] [options]
12
+ overview [--project ID] [--mine] [--limit N] [--stale-days N]
13
+ The board at a glance: counts by column, priority, AutoLabel, project and assignee, each open epic's
14
+ progress, the tickets that need someone (urgent, needs input, open questions, review, ready without an
15
+ assignee, stale after N days without a change, default 3) and the tickets changed last. Lists hold at
16
+ most --limit tickets (default 5, at most 50) and name how many there are in all.
17
+ page [--mine] [--project ID] [--status COLUMN] [--statuses COLUMN,…] [--open|--done] [--kind epic|task|subtask]
18
+ [--priorities PRIORITY,…] [--parent AGL-<n>] [--assignee ID] [--unassigned] [--keys AGL-<n>,…]
19
+ [--since INSTANT] [--label LABEL] [--text TEXT] [--sort board|updated|created|priority] [--full]
20
+ [--limit N] [--cursor CURSOR]
21
+ One page of the board (default 50 tickets, at most 200, within 256 KiB) as summaries without description
22
+ and source words; --full returns whole tickets. total and columns count everything the filters match.
23
+ --open leaves out released and closed tickets, --done keeps only those; --parent lists a ticket's direct
24
+ children; --assignee is a person id or a session id; --since an ISO 8601 instant of the last change.
25
+ nextCursor names the next page: pass it as --cursor with the same filters, sort and view.
11
26
  list [--mine] [--project ID] [--status COLUMN] [--label LABEL] [--text TEXT]
27
+ Every matching ticket whole and unpaged; prefer page on a large board.
12
28
  --label also matches AutoLabels, which AGL computes: openQuestion (an unanswered question),
13
29
  planned (a release plan on a ticket not yet released)
14
30
  get AGL-<n> [--limit N] [--before HISTORY-ID] [--comment COMMENT-ID]
@@ -73,6 +89,9 @@ export interface ITicketCliArguments {
73
89
  const common = ['port', 'json'];
74
90
  const actionOptions: Record<string, string[]> = {
75
91
  list: ['mine', 'project', 'status', 'label', 'text'], get: ['limit', 'before', 'comment'],
92
+ page: ['mine', 'project', 'status', 'statuses', 'open', 'done', 'kind', 'priorities', 'parent', 'assignee', 'unassigned', 'keys',
93
+ 'since', 'label', 'text', 'sort', 'full', 'limit', 'cursor'],
94
+ overview: ['project', 'mine', 'limit', 'stale-days'],
76
95
  create: ['project', 'title', 'description', 'kind', 'parent', 'priority', 'labels', 'source', 'attachments', 'column', 'release-plan',
77
96
  'deploy-plan', 'window', 'window-targets'],
78
97
  update: ['expected-revision', 'changes', 'title', 'description', 'priority', 'project', 'labels', 'parent', 'clear-parent',
@@ -82,7 +101,7 @@ const actionOptions: Record<string, string[]> = {
82
101
  assign: ['expected-revision', 'session-id', 'assignee', 'name', 'kind', 'clear'],
83
102
  ask: ['text', 'options', 'multi', 'no-custom'], answer: ['question', 'choice', 'text'],
84
103
  };
85
- const booleanOptions = new Set(['json', 'mine', 'clear', 'clear-parent', 'clear-release-plan', 'clear-window', 'multi', 'no-custom']);
104
+ const booleanOptions = new Set(['json', 'mine', 'open', 'done', 'unassigned', 'full', 'clear', 'clear-parent', 'clear-release-plan', 'clear-window', 'multi', 'no-custom']);
86
105
 
87
106
  /** `REPO[@VERSION]`: the repository a release plan names and, after the last `@`, the version it should reach. */
88
107
  export const parseReleasePlanOption = (valueArg: string): { repo: string; version?: string } => {
@@ -112,7 +131,7 @@ export const parseTicketCliArguments = (argumentsArg: string[]): ITicketCliArgum
112
131
  const [action, ...argumentsRest] = argumentsArg;
113
132
  if (!action || !Object.hasOwn(actionOptions, action)) throw new Error(ticketCliHelp);
114
133
  const rest = [...argumentsRest];
115
- const ticketId = action === 'list' || action === 'create' ? undefined : rest.shift();
134
+ const ticketId = ['list', 'page', 'overview', 'create'].includes(action) ? undefined : rest.shift();
116
135
  const allowed = new Set([...common, ...actionOptions[action]!]);
117
136
  const options = new Map<string, string>();
118
137
  for (let index = 0; index < rest.length; index++) {
@@ -159,6 +178,19 @@ export const parseTicketCliArguments = (argumentsArg: string[]): ITicketCliArgum
159
178
  };
160
179
  if (action === 'list') request = { ...(options.has('mine') ? { mine: true } : {}), ...optional('project'),
161
180
  ...optional('status'), ...optional('label'), ...optional('text') };
181
+ else if (action === 'page') {
182
+ if (options.has('open') && options.has('done')) throw new Error('--open and --done conflict.');
183
+ const list = (keyArg: string, fieldArg = keyArg) => options.has(keyArg)
184
+ ? { [fieldArg]: options.get(keyArg)!.split(',').map((valueArg) => valueArg.trim()).filter(Boolean) } : {};
185
+ request = { ...(options.has('mine') ? { mine: true } : {}), ...optional('project'), ...optional('status'), ...list('statuses'),
186
+ ...(options.has('open') ? { open: true } : {}), ...(options.has('done') ? { open: false } : {}), ...optional('kind'),
187
+ ...list('priorities'), ...optional('parent'), ...optional('assignee'), ...(options.has('unassigned') ? { unassigned: true } : {}),
188
+ ...list('keys'), ...optional('since', 'updatedSince'), ...optional('label'), ...optional('text'), ...optional('sort'),
189
+ ...(options.has('full') ? { view: 'full' } : {}), ...(options.has('limit') ? { limit: Number(required('limit')) } : {}),
190
+ ...optional('cursor') };
191
+ } else if (action === 'overview') request = { ...optional('project'), ...(options.has('mine') ? { mine: true } : {}),
192
+ ...(options.has('limit') ? { limit: Number(required('limit')) } : {}),
193
+ ...(options.has('stale-days') ? { staleDays: Number(required('stale-days')) } : {}) };
162
194
  else if (action === 'get') request = { ticketId, ...optional('before'), ...optional('comment', 'commentId'),
163
195
  ...(options.has('limit') ? { limit: Number(required('limit')) } : {}) };
164
196
  else if (action === 'create') request = { project: required('project'), title: required('title'), ...optional('description'),
@@ -210,11 +242,44 @@ export const parseTicketCliArguments = (argumentsArg: string[]): ITicketCliArgum
210
242
  return { operation, request: assertTicketRequest(operation, request), port, json: options.has('json') };
211
243
  };
212
244
 
245
+ const counts = (countsArg: Record<string, number>): string => Object.entries(countsArg).filter(([, countArg]) => countArg > 0)
246
+ .map(([nameArg, countArg]) => `${nameArg} ${countArg}`).join(', ') || 'none';
247
+ const summaryLine = (ticketArg: Pick<ITicketSummary, 'key' | 'project' | 'columnId' | 'priority' | 'title' | 'assignee'>): string => (
248
+ `${ticketArg.key}\t${ticketArg.project}\t${ticketArg.columnId}\t${ticketArg.priority}\t${ticketArg.assignee?.name ?? '-'}\t${ticketArg.title}\n`);
249
+ /** The overview as text: the counts, then each list with what it stands for. */
250
+ export const formatTicketOverview = (overviewArg: ITicketOverview): string => {
251
+ const lines = [`Board revision ${overviewArg.revision}: ${overviewArg.total} tickets, ${overviewArg.open} open, ${overviewArg.unassignedOpen} open without an assignee\n`,
252
+ `Columns: ${counts(overviewArg.columns)}\n`, `Open by priority: ${counts(overviewArg.priorities)}\n`, `AutoLabels: ${counts(overviewArg.autoLabels)}\n`,
253
+ `\nProjects (${overviewArg.projects.length} of ${overviewArg.projectsTotal}):\n`,
254
+ ...overviewArg.projects.map((projectArg) => ` ${projectArg.project}\t${projectArg.open} open of ${projectArg.total}\t${counts(projectArg.columns)}\n`),
255
+ `\nAssignees (${overviewArg.assignees.length} of ${overviewArg.assigneesTotal}):\n`,
256
+ ...overviewArg.assignees.map((assigneeArg) => ` ${assigneeArg.name}\t${assigneeArg.open} open\t${counts(assigneeArg.columns)}\t${assigneeArg.sessionId ?? assigneeArg.id}\n`),
257
+ `\nOpen epics (${overviewArg.epics.length} of ${overviewArg.epicsTotal}):\n`,
258
+ ...overviewArg.epics.map((epicArg) => ` ${epicArg.key}\t${epicArg.project}\t${epicArg.done}/${epicArg.children} done\t${epicArg.title}\n`)];
259
+ const groups: [string, ITicketOverview['attention'][keyof ITicketOverview['attention']]][] = [
260
+ ['Urgent', overviewArg.attention.urgent], ['Needs input', overviewArg.attention.needsInput],
261
+ ['Open questions', overviewArg.attention.openQuestions], ['Review', overviewArg.attention.review],
262
+ ['Ready without an assignee', overviewArg.attention.unassignedReady], ['Stale', overviewArg.attention.stale]];
263
+ for (const [titleArg, groupArg] of groups) {
264
+ lines.push(`\n${titleArg} (${groupArg.tickets.length} of ${groupArg.total}):\n`, ...groupArg.tickets.map((ticketArg) => ` ${summaryLine(ticketArg)}`));
265
+ }
266
+ lines.push('\nChanged last:\n', ...overviewArg.recent.map((ticketArg) => ` ${ticketArg.updatedAt}\t${summaryLine(ticketArg)}`));
267
+ return lines.join('');
268
+ };
269
+
213
270
  export const formatTicketCliResult = (resultArg: unknown, jsonArg: boolean): string => {
214
271
  if (jsonArg) return JSON.stringify(resultArg) + '\n';
215
272
  const result = resultArg as { tickets?: { key: string; columnId: string; title: string; project: string }[];
216
- ticket?: { key: string; columnId: string; title: string; project: string } };
273
+ ticket?: { key: string; columnId: string; title: string; project: string };
274
+ view?: string; total?: number; columns?: Record<string, number>; nextCursor?: string; moved?: true; attention?: unknown };
275
+ if (result.attention !== undefined) return formatTicketOverview(resultArg as ITicketOverview);
217
276
  const tickets = result.tickets;
277
+ if (tickets && result.view !== undefined) {
278
+ return (tickets as ITicketSummary[]).map(summaryLine).join('')
279
+ + `${tickets.length} of ${result.total} (${counts(result.columns ?? {})})\n`
280
+ + (result.moved ? 'The board changed since the first page: a ticket that changed its place may be missing or shown twice.\n' : '')
281
+ + (result.nextCursor ? `Next page: --cursor ${result.nextCursor}\n` : '');
282
+ }
218
283
  return tickets ? tickets.map((ticketArg) => `${ticketArg.key}\t${ticketArg.project}\t${ticketArg.columnId}\t${ticketArg.title}\n`).join('')
219
284
  : JSON.stringify(resultArg, null, 2) + '\n';
220
285
  };
@@ -0,0 +1,214 @@
1
+ import * as plugins from './plugins.js';
2
+ import {
3
+ ticketAutoLabels, ticketColumns, ticketDoneColumns, ticketListPage, ticketOverviewDefaults, ticketPriorities,
4
+ type ITicket, type ITicketOverview, type ITicketOverviewGroup, type ITicketOverviewRequest, type ITicketPageRequest,
5
+ type ITicketSummary, type TTicketColumn, type TTicketPage, type TTicketPageSort, type TTicketPriority,
6
+ } from '../ts_interfaces/tickets.js';
7
+
8
+ /**
9
+ * Paged listings and the board overview, as pure functions over the tickets a listing shows (`TicketStore.visible`,
10
+ * already narrowed by `ticketFilter`). Nothing here reads the store: `TicketStore.perform` hands in the tickets, the
11
+ * board revision and the open-question counts one transaction read.
12
+ */
13
+
14
+ /** A cursor the store refuses: `invalid` is no `nextCursor` of a page, `mismatch` pages another filter, sort or view. */
15
+ export class TicketCursorError extends Error {
16
+ constructor(public readonly code: 'ticket_cursor_invalid' | 'ticket_cursor_mismatch') { super(code); }
17
+ }
18
+
19
+ const priorityRank: Record<TTicketPriority, number> = { urgent: 0, high: 1, normal: 2, low: 3, none: 4 };
20
+ const ticketNumber = (ticketArg: Pick<ITicket, 'key'>): number => Number(ticketArg.key.slice(4));
21
+ const isDone = (ticketArg: Pick<ITicket, 'columnId'>): boolean => ticketDoneColumns.includes(ticketArg.columnId);
22
+
23
+ /**
24
+ * Where a ticket stands in a sort, as numbers compared left to right; the ticket's number ends every key, so no two
25
+ * tickets share one. `board` is the board's own order (column, then position), `updated` and `created` newest first,
26
+ * `priority` urgent first and then the board's order.
27
+ */
28
+ export const ticketSortKey = (ticketArg: ITicket, sortArg: TTicketPageSort): number[] => {
29
+ const column = ticketColumns.indexOf(ticketArg.columnId), number = ticketNumber(ticketArg);
30
+ switch (sortArg) {
31
+ case 'board': return [column, ticketArg.order, number];
32
+ case 'updated': return [-Date.parse(ticketArg.updatedAt), number];
33
+ case 'created': return [-number];
34
+ case 'priority': return [priorityRank[ticketArg.priority], column, ticketArg.order, number];
35
+ }
36
+ };
37
+ const compareKeys = (leftArg: readonly number[], rightArg: readonly number[]): number => {
38
+ for (let index = 0; index < Math.max(leftArg.length, rightArg.length); index += 1) {
39
+ const difference = (leftArg[index] ?? 0) - (rightArg[index] ?? 0);
40
+ if (difference !== 0) return difference;
41
+ }
42
+ return 0;
43
+ };
44
+
45
+ /** What a page narrows by beyond `ticketFilter`'s own filters (mine, project, status, label, text). */
46
+ export const ticketPageNarrows = (requestArg: ITicketPageRequest): (ticketArg: ITicket) => boolean => {
47
+ const statuses = requestArg.statuses && new Set<TTicketColumn>(requestArg.statuses);
48
+ const priorities = requestArg.priorities && new Set<TTicketPriority>(requestArg.priorities);
49
+ const keys = requestArg.keys && new Set(requestArg.keys);
50
+ const since = requestArg.updatedSince === undefined ? undefined : Date.parse(requestArg.updatedSince);
51
+ return (ticketArg) => (
52
+ (!statuses || statuses.has(ticketArg.columnId))
53
+ && (requestArg.open === undefined || requestArg.open !== isDone(ticketArg))
54
+ && (!requestArg.kind || ticketArg.kind === requestArg.kind)
55
+ && (!priorities || priorities.has(ticketArg.priority))
56
+ && (!requestArg.parent || ticketArg.parentId === requestArg.parent)
57
+ && (!requestArg.assignee || ticketArg.assignee?.id === requestArg.assignee || ticketArg.assignee?.sessionId === requestArg.assignee)
58
+ && (!requestArg.unassigned || ticketArg.assignee === undefined)
59
+ && (!keys || keys.has(ticketArg.key))
60
+ && (since === undefined || Date.parse(ticketArg.updatedAt) >= since)
61
+ );
62
+ };
63
+
64
+ /** A ticket without its texts: what a listing or the overview shows of it. Empty fields are left out. */
65
+ export const ticketSummary = (ticketArg: ITicket, openQuestionsArg: number): ITicketSummary => {
66
+ const links: NonNullable<ITicketSummary['links']> = {};
67
+ for (const link of ticketArg.links) links[link.kind] = (links[link.kind] ?? 0) + 1;
68
+ return {
69
+ key: ticketArg.key, revision: ticketArg.revision, project: ticketArg.project, kind: ticketArg.kind, title: ticketArg.title,
70
+ columnId: ticketArg.columnId, priority: ticketArg.priority, updatedAt: ticketArg.updatedAt,
71
+ ...(ticketArg.assignee === undefined ? {} : { assignee: { id: ticketArg.assignee.id, name: ticketArg.assignee.name,
72
+ ...(ticketArg.assignee.sessionId === undefined ? {} : { sessionId: ticketArg.assignee.sessionId }) } }),
73
+ ...(ticketArg.parentId === undefined ? {} : { parentId: ticketArg.parentId }),
74
+ ...(ticketArg.labels.length ? { labels: [...ticketArg.labels] } : {}),
75
+ ...(ticketArg.autoLabels?.length ? { autoLabels: [...ticketArg.autoLabels] } : {}),
76
+ ...(ticketArg.links.length ? { links } : {}),
77
+ ...(ticketArg.releasePlan === undefined ? {} : { releasePlan: { ...ticketArg.releasePlan } }),
78
+ ...(ticketArg.deployPlan === undefined ? {} : { deployPlan: { target: ticketArg.deployPlan.target, version: ticketArg.deployPlan.version } }),
79
+ ...(ticketArg.maintenanceWindow === undefined ? {} : { maintenanceWindow: { from: ticketArg.maintenanceWindow.from,
80
+ to: ticketArg.maintenanceWindow.to, targets: [...ticketArg.maintenanceWindow.targets] } }),
81
+ ...(openQuestionsArg > 0 ? { openQuestions: openQuestionsArg } : {}),
82
+ };
83
+ };
84
+
85
+ interface ITicketPageCursor { filter: string; key: number[]; revision: number }
86
+ const cursorSchema = plugins.z.object({ filter: plugins.z.string().regex(/^[A-Za-z0-9_-]{22}$/u),
87
+ key: plugins.z.array(plugins.z.number().finite()).min(1).max(4), revision: plugins.z.number().int().nonnegative() }).strict();
88
+ /** The digest a cursor carries of what it pages: every filter, the sort and the view, never `limit`. */
89
+ const pageDigest = (requestArg: ITicketPageRequest, viewerArg: string | undefined): string => plugins.crypto.createHash('sha256')
90
+ .update(JSON.stringify([requestArg.mine === true ? viewerArg ?? '' : null, requestArg.project ?? null, requestArg.status ?? null,
91
+ requestArg.label ?? null, requestArg.text ?? null, requestArg.statuses ? [...requestArg.statuses].sort() : null, requestArg.open ?? null,
92
+ requestArg.kind ?? null, requestArg.priorities ? [...requestArg.priorities].sort() : null, requestArg.parent ?? null,
93
+ requestArg.assignee ?? null, requestArg.unassigned === true, requestArg.keys ? [...requestArg.keys].sort() : null,
94
+ requestArg.updatedSince ?? null, requestArg.sort ?? 'board', requestArg.view ?? 'summary'])).digest('base64url').slice(0, 22);
95
+ const encodeCursor = (cursorArg: ITicketPageCursor): string => Buffer.from(JSON.stringify(cursorArg)).toString('base64url');
96
+ const decodeCursor = (cursorArg: string): ITicketPageCursor => {
97
+ try { return cursorSchema.parse(JSON.parse(Buffer.from(cursorArg, 'base64url').toString('utf8'))); }
98
+ catch { throw new TicketCursorError('ticket_cursor_invalid'); }
99
+ };
100
+
101
+ /**
102
+ * One page of the tickets `ticketsArg` holds (those `ticketFilter` kept), narrowed by the request's further filters
103
+ * and sorted: at most `limit` tickets (`ticketListPage`) and no more than `ticketListPage.bytes` of them serialized,
104
+ * which wins over `limit`; a page holds at least one ticket. `total` and `columns` count the whole filtered set, so a
105
+ * page never hides how much there is. A cursor is a position in the sort, not a snapshot: the next page holds the
106
+ * tickets that sort after the last one shown, as the board stands now, and `moved` tells that the board changed since
107
+ * the first page, so a ticket that changed its place meanwhile may be missing or shown twice.
108
+ */
109
+ export const ticketPage = (ticketsArg: ITicket[], requestArg: ITicketPageRequest, revisionArg: number,
110
+ openQuestionsArg: (ticketIdArg: string) => number, viewerArg?: string): TTicketPage => {
111
+ const sort = requestArg.sort ?? 'board', view = requestArg.view ?? 'summary';
112
+ const filter = pageDigest(requestArg, viewerArg);
113
+ const keyed = ticketsArg.filter(ticketPageNarrows(requestArg)).map((ticketArg) => ({ ticket: ticketArg, key: ticketSortKey(ticketArg, sort) }))
114
+ .sort((leftArg, rightArg) => compareKeys(leftArg.key, rightArg.key));
115
+ const columns: TTicketPage['columns'] = {};
116
+ for (const { ticket } of keyed) columns[ticket.columnId] = (columns[ticket.columnId] ?? 0) + 1;
117
+ let start = 0, firstRevision = revisionArg;
118
+ if (requestArg.cursor !== undefined) {
119
+ const cursor = decodeCursor(requestArg.cursor);
120
+ if (cursor.filter !== filter) throw new TicketCursorError('ticket_cursor_mismatch');
121
+ firstRevision = cursor.revision;
122
+ start = keyed.findIndex((entryArg) => compareKeys(entryArg.key, cursor.key) > 0);
123
+ if (start < 0) start = keyed.length;
124
+ }
125
+ const limit = requestArg.limit ?? ticketListPage.default;
126
+ const rows: (ITicket | ITicketSummary)[] = [];
127
+ let bytes = 0, end = start;
128
+ while (end < keyed.length && rows.length < limit) {
129
+ const { ticket } = keyed[end]!;
130
+ const row = view === 'full' ? ticket : ticketSummary(ticket, openQuestionsArg(ticket.id));
131
+ const size = Buffer.byteLength(JSON.stringify(row));
132
+ if (rows.length && bytes + size > ticketListPage.bytes) break;
133
+ rows.push(row); bytes += size; end += 1;
134
+ }
135
+ return {
136
+ view, tickets: rows, total: keyed.length, columns, revision: revisionArg,
137
+ ...(end < keyed.length ? { nextCursor: encodeCursor({ filter, key: keyed[end - 1]!.key, revision: firstRevision }) } : {}),
138
+ ...(firstRevision !== revisionArg ? { moved: true } : {}),
139
+ } as TTicketPage;
140
+ };
141
+
142
+ const group = (ticketsArg: ITicket[], limitArg: number, openQuestionsArg: (ticketIdArg: string) => number): ITicketOverviewGroup => ({
143
+ total: ticketsArg.length, tickets: ticketsArg.slice(0, limitArg).map((ticketArg) => ticketSummary(ticketArg, openQuestionsArg(ticketArg.id))),
144
+ });
145
+ const byBoard = (leftArg: ITicket, rightArg: ITicket): number => compareKeys(ticketSortKey(leftArg, 'board'), ticketSortKey(rightArg, 'board'));
146
+ const byPriority = (leftArg: ITicket, rightArg: ITicket): number => compareKeys(ticketSortKey(leftArg, 'priority'), ticketSortKey(rightArg, 'priority'));
147
+ const columnCounts = (ticketsArg: ITicket[]): Partial<Record<TTicketColumn, number>> => {
148
+ const counts: Partial<Record<TTicketColumn, number>> = {};
149
+ for (const column of ticketColumns) {
150
+ const count = ticketsArg.filter((ticketArg) => ticketArg.columnId === column).length;
151
+ if (count) counts[column] = count;
152
+ }
153
+ return counts;
154
+ };
155
+
156
+ /**
157
+ * The board in one bounded answer, without any ticket's texts: counts by column, priority, AutoLabel, project and
158
+ * assignee, each open epic's progress over its direct children, the tickets that need someone (urgent, needs input,
159
+ * open questions, review, ready without an assignee, stale work) and the newest changes. Every list is cut to
160
+ * `limit` tickets (projects, assignees and epics to `ticketOverviewDefaults.groups`) and carries the count of all it
161
+ * stands for. Stale is in_progress, needs_input or review work nobody changed for `staleDays`, oldest first.
162
+ */
163
+ export const ticketOverview = (ticketsArg: ITicket[], requestArg: ITicketOverviewRequest, revisionArg: number, nowArg: string,
164
+ openQuestionsArg: (ticketIdArg: string) => number): ITicketOverview => {
165
+ const limit = requestArg.limit ?? ticketOverviewDefaults.limit;
166
+ const staleBefore = Date.parse(nowArg) - (requestArg.staleDays ?? ticketOverviewDefaults.staleDays) * 86_400_000;
167
+ const open = ticketsArg.filter((ticketArg) => !isDone(ticketArg));
168
+ const count = <TKey extends string>(keysArg: readonly TKey[], ofArg: (keyArg: TKey) => number): Record<TKey, number> => (
169
+ Object.fromEntries(keysArg.map((keyArg) => [keyArg, ofArg(keyArg)])) as Record<TKey, number>);
170
+ const projects = [...new Set(ticketsArg.map((ticketArg) => ticketArg.project))].map((projectArg) => {
171
+ const own = ticketsArg.filter((ticketArg) => ticketArg.project === projectArg);
172
+ return { project: projectArg, total: own.length, open: own.filter((ticketArg) => !isDone(ticketArg)).length, columns: columnCounts(own) };
173
+ }).sort((leftArg, rightArg) => rightArg.open - leftArg.open || rightArg.total - leftArg.total || leftArg.project.localeCompare(rightArg.project));
174
+ const assigned = new Map<string, ITicket[]>();
175
+ for (const ticket of open) {
176
+ if (!ticket.assignee) continue;
177
+ const id = ticket.assignee.sessionId ?? ticket.assignee.id;
178
+ assigned.set(id, [...(assigned.get(id) ?? []), ticket]);
179
+ }
180
+ const assignees = [...assigned.values()].map((ownArg) => {
181
+ const { id, name, sessionId } = ownArg[0]!.assignee!;
182
+ return { id, name, ...(sessionId === undefined ? {} : { sessionId }), open: ownArg.length, columns: columnCounts(ownArg) };
183
+ }).sort((leftArg, rightArg) => rightArg.open - leftArg.open || leftArg.name.localeCompare(rightArg.name));
184
+ const epics = open.filter((ticketArg) => ticketArg.kind === 'epic').sort(byBoard).map((epicArg) => {
185
+ const children = ticketsArg.filter((ticketArg) => ticketArg.parentId === epicArg.key);
186
+ return { key: epicArg.key, title: epicArg.title, project: epicArg.project, columnId: epicArg.columnId, children: children.length,
187
+ done: children.filter(isDone).length, columns: columnCounts(children) };
188
+ });
189
+ const active = new Set<TTicketColumn>(['in_progress', 'needs_input', 'review']);
190
+ const groups = ticketOverviewDefaults.groups;
191
+ return {
192
+ revision: revisionArg, total: ticketsArg.length, open: open.length,
193
+ columns: count(ticketColumns, (columnArg) => ticketsArg.filter((ticketArg) => ticketArg.columnId === columnArg).length),
194
+ priorities: count(ticketPriorities, (priorityArg) => open.filter((ticketArg) => ticketArg.priority === priorityArg).length),
195
+ autoLabels: count(ticketAutoLabels, (labelArg) => ticketsArg.filter((ticketArg) => ticketArg.autoLabels?.includes(labelArg)).length),
196
+ projects: projects.slice(0, groups), projectsTotal: projects.length,
197
+ assignees: assignees.slice(0, groups), assigneesTotal: assignees.length,
198
+ unassignedOpen: open.filter((ticketArg) => ticketArg.assignee === undefined).length,
199
+ epics: epics.slice(0, groups), epicsTotal: epics.length,
200
+ attention: {
201
+ urgent: group(open.filter((ticketArg) => ticketArg.priority === 'urgent').sort(byBoard), limit, openQuestionsArg),
202
+ needsInput: group(open.filter((ticketArg) => ticketArg.columnId === 'needs_input').sort(byPriority), limit, openQuestionsArg),
203
+ openQuestions: group(open.filter((ticketArg) => openQuestionsArg(ticketArg.id) > 0).sort(byPriority), limit, openQuestionsArg),
204
+ review: group(open.filter((ticketArg) => ticketArg.columnId === 'review').sort(byPriority), limit, openQuestionsArg),
205
+ unassignedReady: group(open.filter((ticketArg) => ticketArg.columnId === 'ready' && ticketArg.assignee === undefined).sort(byPriority),
206
+ limit, openQuestionsArg),
207
+ stale: group(open.filter((ticketArg) => active.has(ticketArg.columnId) && Date.parse(ticketArg.updatedAt) < staleBefore)
208
+ .sort((leftArg, rightArg) => Date.parse(leftArg.updatedAt) - Date.parse(rightArg.updatedAt) || ticketNumber(leftArg) - ticketNumber(rightArg)),
209
+ limit, openQuestionsArg),
210
+ },
211
+ recent: [...ticketsArg].sort((leftArg, rightArg) => compareKeys(ticketSortKey(leftArg, 'updated'), ticketSortKey(rightArg, 'updated')))
212
+ .slice(0, limit).map((ticketArg) => ticketSummary(ticketArg, openQuestionsArg(ticketArg.id))),
213
+ };
214
+ };
@@ -1,6 +1,7 @@
1
1
  import * as plugins from './plugins.js';
2
2
  import {
3
- ticketAutoLabels, ticketColumns, ticketHistoryPage, type TTicketFleetEvent, type TTicketLink, type TTicketOperation, type TTicketRequest,
3
+ ticketAutoLabels, ticketColumns, ticketHistoryPage, ticketListPage, ticketOverviewDefaults, ticketPageSorts, ticketPriorities,
4
+ type TTicketFleetEvent, type TTicketLink, type TTicketOperation, type TTicketRequest,
4
5
  } from '../ts_interfaces/tickets.js';
5
6
  import { fleetDeployTargetIdPattern } from '../ts_interfaces/deployments.js';
6
7
 
@@ -82,6 +83,15 @@ const optionId = plugins.z.string().regex(/^[1-9][0-9]*$/u);
82
83
  const questionOption = plugins.z.object({ label: text(200).trim().min(1), description: text(1000).optional() }).strict();
83
84
  const filters = plugins.z.object({ mine: plugins.z.boolean().optional(), project: identifier.optional(),
84
85
  status: plugins.z.enum(ticketColumns).optional(), label: text(100).min(1).optional(), text: text(1024).optional() }).strict();
86
+ const pageRequest = plugins.z.object({ ...filters.shape,
87
+ statuses: plugins.z.array(plugins.z.enum(ticketColumns)).min(1).max(ticketColumns.length).optional(), open: plugins.z.boolean().optional(),
88
+ kind: kind.optional(), priorities: plugins.z.array(priority).min(1).max(ticketPriorities.length).optional(), parent: ticketId.optional(),
89
+ assignee: identifier.optional(), unassigned: plugins.z.boolean().optional(), keys: plugins.z.array(ticketId).min(1).max(200).optional(),
90
+ updatedSince: instantInput.optional(), sort: plugins.z.enum(ticketPageSorts).optional(), view: plugins.z.enum(['summary', 'full']).optional(),
91
+ limit: plugins.z.number().int().min(1).max(ticketListPage.maximum).optional(), cursor: text(2048).min(1).optional() }).strict();
92
+ const overviewRequest = plugins.z.object({ project: identifier.optional(), mine: plugins.z.boolean().optional(),
93
+ limit: plugins.z.number().int().min(1).max(ticketOverviewDefaults.maximumLimit).optional(),
94
+ staleDays: plugins.z.number().int().min(1).max(365).optional() }).strict();
85
95
  const changes = plugins.z.object({
86
96
  title: text(200).trim().min(1).optional(), description: text(64 * 1024).optional(),
87
97
  priority: priority.optional(), assignee: person.nullable().optional(), parentId: ticketId.nullable().optional(),
@@ -89,7 +99,7 @@ const changes = plugins.z.object({
89
99
  maintenanceWindow: maintenanceWindowInput.nullable().optional(), deployPlan: deployPlanInput.optional(),
90
100
  }).strict().refine((valueArg) => Object.keys(valueArg).length > 0, 'At least one change is required.');
91
101
  export const ticketInputSchemas = {
92
- list: filters, board: filters,
102
+ list: filters, board: filters, page: pageRequest, overview: overviewRequest,
93
103
  search: plugins.z.object({ query: text(1024), label: text(100).min(1).optional() }).strict(),
94
104
  get: plugins.z.object({ ticketId, before: identifier.optional(),
95
105
  limit: plugins.z.number().int().min(1).max(ticketHistoryPage.maximum).optional(), commentId: identifier.optional() }).strict()
@@ -177,8 +187,37 @@ export const assertTicketResponse = (methodArg: string, valueArg: unknown): void
177
187
  permissions: plugins.z.object({ edit: plugins.z.boolean(), move: plugins.z.boolean(),
178
188
  comment: plugins.z.boolean(), createChild: plugins.z.boolean(), ask: plugins.z.boolean(), answer: plugins.z.boolean() }).strict(),
179
189
  autoLabels: plugins.z.array(plugins.z.enum(ticketAutoLabels)) });
190
+ const count = plugins.z.number().int().nonnegative();
191
+ const columnCounts = plugins.z.partialRecord(storedColumn, count);
192
+ const summaryPerson = plugins.z.object({ id: identifier, name: text(200).min(1), sessionId: identifier.optional() }).strict();
193
+ const summary = plugins.z.object({ key: ticketId, revision: count, project: identifier, kind, title: text(200).min(1),
194
+ columnId: storedColumn, priority, updatedAt: plugins.z.iso.datetime(), assignee: summaryPerson.optional(), parentId: ticketId.optional(),
195
+ labels: labels.optional(), autoLabels: plugins.z.array(plugins.z.enum(ticketAutoLabels)).optional(),
196
+ links: plugins.z.partialRecord(plugins.z.enum(['branch', 'commit', 'release', 'affects']), count).optional(),
197
+ releasePlan: releasePlan.optional(), deployPlan: plugins.z.object({ target: deployTargetId, version: identifier }).strict().optional(),
198
+ maintenanceWindow: plugins.z.object({ from: plugins.z.iso.datetime(), to: plugins.z.iso.datetime(),
199
+ targets: plugins.z.array(deployTargetId) }).strict().optional(), openQuestions: count.optional() }).strict();
200
+ const pageBase = { total: count, columns: columnCounts, revision: count, nextCursor: text(2048).min(1).optional(),
201
+ moved: plugins.z.literal(true).optional() };
202
+ const group = plugins.z.object({ total: count, tickets: plugins.z.array(summary) }).strict();
180
203
  const schemas = {
181
204
  list: plugins.z.object({ tickets: plugins.z.array(ticket) }).strict(),
205
+ page: plugins.z.discriminatedUnion('view', [
206
+ plugins.z.object({ view: plugins.z.literal('summary'), tickets: plugins.z.array(summary), ...pageBase }).strict(),
207
+ plugins.z.object({ view: plugins.z.literal('full'), tickets: plugins.z.array(ticket), ...pageBase }).strict(),
208
+ ]),
209
+ overview: plugins.z.object({ revision: count, total: count, open: count,
210
+ columns: plugins.z.record(storedColumn, count), priorities: plugins.z.record(priority, count),
211
+ autoLabels: plugins.z.record(plugins.z.enum(ticketAutoLabels), count),
212
+ projects: plugins.z.array(plugins.z.object({ project: identifier, total: count, open: count, columns: columnCounts }).strict()),
213
+ projectsTotal: count,
214
+ assignees: plugins.z.array(summaryPerson.extend({ open: count, columns: columnCounts }).strict()), assigneesTotal: count,
215
+ unassignedOpen: count,
216
+ epics: plugins.z.array(plugins.z.object({ key: ticketId, title: text(200).min(1), project: identifier, columnId: storedColumn,
217
+ children: count, done: count, columns: columnCounts }).strict()), epicsTotal: count,
218
+ attention: plugins.z.object({ urgent: group, needsInput: group, openQuestions: group, review: group, unassignedReady: group,
219
+ stale: group }).strict(),
220
+ recent: plugins.z.array(summary) }).strict(),
182
221
  search: plugins.z.object({ tickets: plugins.z.array(ticket) }).strict(),
183
222
  board: plugins.z.object({ revision: plugins.z.number().int().nonnegative(), columns: plugins.z.array(plugins.z.object({
184
223
  id: storedColumn, title: plugins.z.string(), done: plugins.z.boolean().optional() }).strict()), tickets: plugins.z.array(ticket),
@@ -215,6 +215,15 @@ export const verifyClaudeWorkerProcess = async (
215
215
  return snapshot;
216
216
  };
217
217
 
218
+ /**
219
+ * Whether `executableArg`, a process's executable as the kernel names it, lies in the directory of the Claude Code
220
+ * release `releaseArg`: the directory Claude Code installs every release in. A release file removed since the process
221
+ * started still does (the kernel names it with ` (deleted)` appended); a shell or a terminal does not.
222
+ */
223
+ export const inClaudeReleaseDirectory = (executableArg: string, releaseArg: string): boolean => (
224
+ plugins.path.isAbsolute(executableArg) && plugins.path.dirname(executableArg) === plugins.path.dirname(releaseArg)
225
+ );
226
+
218
227
  /**
219
228
  * The process `processArg` (PID and start), proved to run an installed Claude Code release: its executable is a
220
229
  * regular file of the controller's user in the directory of `releaseArg`, the release `claude` resolves to now, and is
@@ -231,8 +240,7 @@ export const verifyClaudeReleaseProcess = async (
231
240
  throw new WorkerCallerProofError('Invalid Claude launch observation.');
232
241
  }
233
242
  const snapshot = await readWorkerProcessSnapshot(processArg.pid);
234
- if (snapshot.startTicks !== processArg.startTicks || !plugins.path.isAbsolute(snapshot.executable)
235
- || plugins.path.dirname(snapshot.executable) !== plugins.path.dirname(releaseArg)) {
243
+ if (snapshot.startTicks !== processArg.startTicks || !inClaudeReleaseDirectory(snapshot.executable, releaseArg)) {
236
244
  throw new WorkerCallerProofError('The Claude process does not run an installed Claude Code release.');
237
245
  }
238
246
  const [installed, running] = await Promise.all([plugins.fs.promises.lstat(snapshot.executable, { bigint: true }),
@@ -86,6 +86,7 @@ export const controllerAuditEventTypes = [
86
86
  'accounts.claudecode',
87
87
  'accounts.renewal',
88
88
  'accounts.priority',
89
+ 'accounts.pause',
89
90
  'accounts.remove',
90
91
  'accounts.add',
91
92
  'accounts.reauth',
@@ -614,7 +614,9 @@ export type TFlexPublicConnectionState =
614
614
  | 'deleting'
615
615
  | 'reauthRequired'
616
616
  /** This host's Codex runs on the account, which renews its login; Flex cannot use it meanwhile. */
617
- | 'inHostCodex';
617
+ | 'inHostCodex'
618
+ /** The account's owner holds it paused (AGL-1933): AGL places nothing on it until it is resumed. */
619
+ | 'paused';
618
620
 
619
621
  /**
620
622
  * The providers Flex runs models of: OpenAI on the ChatGPT accounts the accounts service holds, Anthropic on the
@@ -288,6 +288,14 @@ export interface IAuthSwitchAccount {
288
288
  * one.
289
289
  */
290
290
  priorityUntil: string | null;
291
+ /**
292
+ * Since when the account is paused by its owner (AGL-1933), ISO 8601 UTC by the authority's clock; `null` while it is
293
+ * not. A paused account takes no new work: placement never chooses it (`authSwitchPlacement` answers `never`), AGL's
294
+ * inference proxy leaves it out of every pool, and a session on it moves to another account. Its sign-in, logins,
295
+ * usage readings, limits and renewal stay as they are and keep being read, so it is ready the moment it is resumed.
296
+ * It has no end: it holds until the owner resumes the account. A paused account holds no priority.
297
+ */
298
+ pausedAt: string | null;
291
299
  /**
292
300
  * An API key account's spend limit per calendar month in UTC, in micro-dollars (`isAuthSwitchSpendLimitMicroUsd`);
293
301
  * `null` for none, and always for an account on a sign-in. The limit counts what AGL's inference proxy relayed on the
@@ -1565,6 +1573,18 @@ export interface IReq_AuthSwitchSetAccountPriority extends ITypedRequest {
1565
1573
  response: { account: IAuthSwitchAccount };
1566
1574
  }
1567
1575
 
1576
+ /**
1577
+ * Pauses an account (`paused: true`) or resumes it (`false`): see `IAuthSwitchAccount.pausedAt`. Pausing ends a priority
1578
+ * the account holds; pausing a paused account, or resuming one that is not, changes nothing but its revision. The moment
1579
+ * is the authority's clock, never the caller's. `expectedRevision` is the revision the caller read, so a change of an
1580
+ * account that changed meanwhile is refused as `account_changed`.
1581
+ */
1582
+ export interface IReq_AuthSwitchSetAccountPause extends ITypedRequest {
1583
+ method: 'authswitch.authority.pause';
1584
+ request: { accountId: string; expectedRevision: number; paused: boolean };
1585
+ response: { account: IAuthSwitchAccount };
1586
+ }
1587
+
1568
1588
  /**
1569
1589
  * One binding by the id `bind` returned, credential-free, or `null` when this authority holds no binding by
1570
1590
  * that id. A backend checks that its binding still stands without reading the whole snapshot.