@atolis-hq/wake 0.4.62 → 0.4.63

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 (34) hide show
  1. package/dist/src/bootstrap/config/root-schema.d.ts +2 -2
  2. package/dist/src/bootstrap/surface-api-applications.js +2 -0
  3. package/dist/src/bootstrap/surface-api-trigger-applications.d.ts +3 -0
  4. package/dist/src/bootstrap/surface-api-trigger-applications.js +79 -0
  5. package/dist/src/bootstrap/surface-api-work-applications.js +8 -0
  6. package/dist/src/bootstrap/version.js +1 -1
  7. package/dist/src/control-plane/application/trigger-diagnostics.d.ts +33 -0
  8. package/dist/src/control-plane/application/trigger-diagnostics.js +38 -0
  9. package/dist/src/control-plane/application/trigger-service-ports.d.ts +21 -0
  10. package/dist/src/control-plane/application/trigger-service-ports.js +1 -0
  11. package/dist/src/control-plane/application/trigger-service.d.ts +10 -22
  12. package/dist/src/control-plane/application/trigger-service.js +21 -14
  13. package/dist/src/control-plane/contracts/trigger-diagnostics.d.ts +53 -0
  14. package/dist/src/control-plane/contracts/trigger-diagnostics.js +23 -0
  15. package/dist/src/control-plane/domain/cron-trigger-policy.d.ts +1 -0
  16. package/dist/src/control-plane/domain/cron-trigger-policy.js +11 -0
  17. package/dist/src/control-plane/index.d.ts +1 -0
  18. package/dist/src/control-plane/index.js +1 -0
  19. package/dist/src/orchestration/contracts/config.d.ts +2 -2
  20. package/dist/src/surfaces/api/contracts/index.d.ts +1 -0
  21. package/dist/src/surfaces/api/contracts/index.js +1 -0
  22. package/dist/src/surfaces/api/contracts/transport-values.d.ts +8 -0
  23. package/dist/src/surfaces/api/contracts/transport-values.js +23 -0
  24. package/dist/src/surfaces/api/contracts/triggers.d.ts +22 -0
  25. package/dist/src/surfaces/api/contracts/triggers.js +8 -0
  26. package/dist/src/surfaces/api/contracts/work.d.ts +1 -0
  27. package/dist/src/surfaces/api/contracts/workflow-diagram.d.ts +4 -4
  28. package/dist/src/surfaces/api/routes/applications.d.ts +7 -1
  29. package/dist/src/surfaces/api/routes/commands.js +10 -0
  30. package/dist/src/surfaces/api/routes/read.js +16 -0
  31. package/dist/src/surfaces/web-assets/assets/index-9IfrHvBo.js +1192 -0
  32. package/dist/src/surfaces/web-assets/index.html +1 -1
  33. package/package.json +1 -1
  34. package/dist/src/surfaces/web-assets/assets/index-CCvwzTeC.js +0 -1131
@@ -15,8 +15,8 @@ declare const orchestrationConfigSchema: z.ZodDefault<z.ZodObject<{
15
15
  with: z.ZodOptional<z.ZodUnknown>;
16
16
  allowedActors: z.ZodReadonly<z.ZodArray<z.ZodEnum<{
17
17
  human: "human";
18
- watch: "watch";
19
18
  auto: "auto";
19
+ watch: "watch";
20
20
  }>>>;
21
21
  }, z.core.$strict>>>;
22
22
  watches: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodObject<{
@@ -162,8 +162,8 @@ export declare const rootConfigSchema: z.ZodObject<{
162
162
  with: z.ZodOptional<z.ZodUnknown>;
163
163
  allowedActors: z.ZodReadonly<z.ZodArray<z.ZodEnum<{
164
164
  human: "human";
165
- watch: "watch";
166
165
  auto: "auto";
166
+ watch: "watch";
167
167
  }>>>;
168
168
  }, z.core.$strict>>>;
169
169
  watches: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodObject<{
@@ -8,6 +8,7 @@ import { createSelfUpdateFailureLog, describeSelfUpdateFailure, } from './self-u
8
8
  import { createExecutionApplications } from './surface-api-execution-applications.js';
9
9
  import { projectionMeta, sampledMeta } from './surface-api-metadata.js';
10
10
  import { projectionPage } from './surface-api-projection-pages.js';
11
+ import { createTriggerApplications } from './surface-api-trigger-applications.js';
11
12
  import { createSurfaceWorkApplications } from './surface-api-work-applications.js';
12
13
  import { createWorkflowDiagramApplications } from './surface-api-workflow-diagrams.js';
13
14
  import { UpdateMaintenancePhase } from './update-maintenance-lease.js';
@@ -18,6 +19,7 @@ export function createSurfaceApiApplications(root, now) {
18
19
  board: createBoardApplications(root, now),
19
20
  status: createStatusApplications(root, now),
20
21
  controlPlane: createControlPlaneApplications(root, now),
22
+ triggers: createTriggerApplications(root, now),
21
23
  work: createSurfaceWorkApplications(root, now),
22
24
  resources: createResourceApplications(root, now),
23
25
  orchestration: createOrchestrationApplications(root, now),
@@ -0,0 +1,3 @@
1
+ import { type ApiApplications } from '../surfaces/index.js';
2
+ import type { CompositionRoot } from './composition-root.js';
3
+ export declare function createTriggerApplications(root: CompositionRoot, now: () => string): NonNullable<ApiApplications['triggers']>;
@@ -0,0 +1,79 @@
1
+ import { correlationId, EventActorKind } from '@atolis-hq/eventing';
2
+ import { CronTriggerPolicy } from '../control-plane/index.js';
3
+ import { ApiCommandStatus, toWorkItemKey, TriggerStatus, } from '../surfaces/index.js';
4
+ export function createTriggerApplications(root, now) {
5
+ async function list() {
6
+ const view = await root.triggers.get();
7
+ const ids = new Set([
8
+ ...root.config.controlPlane.triggers.map((config) => config.id),
9
+ ...Object.keys(view.pauses),
10
+ ...view.requests.map((request) => request.triggerId),
11
+ ...view.invocations.map((entry) => entry.claim.triggerId),
12
+ ...(view.diagnostics ?? []).map((entry) => entry.triggerId),
13
+ ]);
14
+ const asOf = now();
15
+ return { data: [...ids].sort().map((id) => present(id, view, asOf)), meta: { asOf } };
16
+ }
17
+ function present(id, view, asOf) {
18
+ const definition = root.config.controlPlane.triggers.find((config) => config.id === id) ?? null;
19
+ const invocations = view.invocations
20
+ .filter((entry) => entry.claim.triggerId === id)
21
+ .sort((a, b) => b.claimedAt.localeCompare(a.claimedAt))
22
+ .map((entry) => ({ ...entry, workItemKey: toWorkItemKey(entry.claim.workItemId) }));
23
+ const pauseReason = view.pauses[id] ?? null;
24
+ const running = invocations.some((entry) => entry.result === undefined);
25
+ return {
26
+ triggerId: id,
27
+ definition,
28
+ paused: pauseReason !== null,
29
+ pauseReason,
30
+ status: definition === null
31
+ ? TriggerStatus.Removed
32
+ : pauseReason !== null
33
+ ? TriggerStatus.Paused
34
+ : running
35
+ ? TriggerStatus.Running
36
+ : TriggerStatus.Enabled,
37
+ nextOccurrence: definition?.on.cron === undefined
38
+ ? null
39
+ : new CronTriggerPolicy().nextOccurrence(definition.on.cron, asOf),
40
+ pending: Object.values(view.coalesced).filter((entry) => entry.triggerId === id),
41
+ latestSkip: view.diagnostics?.find((entry) => entry.triggerId === id) ?? null,
42
+ invocations,
43
+ };
44
+ }
45
+ async function command(id, request, pause) {
46
+ if (!(await list()).data.some((entry) => entry.triggerId === id))
47
+ return {
48
+ conflict: true,
49
+ code: 'trigger-not-found',
50
+ detail: 'Trigger definition and history are unavailable',
51
+ };
52
+ const context = {
53
+ commandId: 'trigger:' + request.idempotencyKey,
54
+ correlationId: correlationId('trigger:' + request.idempotencyKey),
55
+ occurredAt: now(),
56
+ actor: { kind: EventActorKind.Operator, id: 'web' },
57
+ };
58
+ if (pause)
59
+ await root.triggers.pause(id, 'Operator pause', context);
60
+ else
61
+ await root.triggers.resume(id, context);
62
+ return {
63
+ commandId: context.commandId,
64
+ idempotencyKey: request.idempotencyKey,
65
+ acceptedAt: now(),
66
+ status: ApiCommandStatus.Completed,
67
+ };
68
+ }
69
+ return {
70
+ list,
71
+ async detail(id) {
72
+ const result = await list();
73
+ const data = result.data.find((entry) => entry.triggerId === id);
74
+ return data === undefined ? undefined : { data, meta: result.meta };
75
+ },
76
+ pause: (id, request) => command(id, request, true),
77
+ resume: (id, request) => command(id, request, false),
78
+ };
79
+ }
@@ -1,5 +1,6 @@
1
1
  import { correlationId, EventActorKind } from '@atolis-hq/eventing';
2
2
  import { pullRequestProjection } from '../activities/index.js';
3
+ import { triggerInvocationProjection } from '../control-plane/index.js';
3
4
  import { conversationIdForWorkItem, ConversationOriginKind, } from '../conversations/index.js';
4
5
  import { executionProjection, runsByWorkflowInstanceProjection, } from '../execution/index.js';
5
6
  import { ApprovalAuthorityKind, ConversationSurfaceCapability, GroupBudgetExtensionIneligibleError, isGroupBudgetExtensionEligible, OperatorRetryIneligibleError, orchestrationProjection, selectOperatorRetryTarget, workflowsByWorkItemProjection, } from '../orchestration/index.js';
@@ -198,6 +199,7 @@ async function workDetail(root, key, now) {
198
199
  // the production root always composes Conversations.
199
200
  const conversation = await conversationForWorkItem(root, id);
200
201
  const data = {
202
+ ...(await triggerOriginForWork(root, id)),
201
203
  work: presentDetailWork(work, externalRef, runs),
202
204
  resources: resources.map(presentResource(root.resolveResourceLink)),
203
205
  orchestration: {
@@ -320,6 +322,7 @@ function presentPullRequest(value) {
320
322
  async function contributingProjections(root, id, resources, workflows, runs) {
321
323
  const records = await Promise.all([
322
324
  root.projections.read('work', id),
325
+ root.projections.read(triggerInvocationProjection.name, id),
323
326
  ...resources.map((value) => root.projections.read('resources', value.resourceId)),
324
327
  ...workflows.map((value) => root.projections.read(orchestrationProjection.name, value.workflowInstanceId)),
325
328
  ...runs.map((value) => root.projections.read(executionProjection.name, value.runId)),
@@ -352,3 +355,8 @@ function retryIneligible(detail) {
352
355
  function extendIneligible(detail) {
353
356
  return { conflict: true, code: 'extend-ineligible', detail };
354
357
  }
358
+ async function triggerOriginForWork(root, id) {
359
+ await root.projectionSubscriptions?.catchUp(triggerInvocationProjection);
360
+ const origin = await root.projections.read(triggerInvocationProjection.name, id);
361
+ return origin?.value == null ? {} : { triggerOrigin: origin.value.claim.triggerId };
362
+ }
@@ -124,6 +124,6 @@ export function resolveWakeVersion(options = {}) {
124
124
  return `g${headHash.slice(0, 7)}`;
125
125
  return '0.1.0-dev';
126
126
  }
127
- export const wakeVersion = "v0.4.62";
127
+ export const wakeVersion = "v0.4.63";
128
128
  /** The registry-installable version used by packaged sandbox images. */
129
129
  export const wakePackageVersion = packageVersion(defaultRepoRoot) ?? wakeVersion;
@@ -0,0 +1,33 @@
1
+ import type { ProcessorStateStore } from '@atolis-hq/eventing';
2
+ import type { TriggerConfig } from '../contracts/config.js';
3
+ import type { TriggerSource } from '../contracts/events.js';
4
+ import { type TriggerSkipReason as SkipReason } from '../contracts/trigger-diagnostics.js';
5
+ import type { TriggerView } from './trigger-projection.js';
6
+ interface Dependencies {
7
+ readonly state: ProcessorStateStore;
8
+ readonly now: () => string;
9
+ readonly isDispatchPaused: () => Promise<boolean>;
10
+ readonly capacityAvailable: (config: TriggerConfig) => Promise<boolean>;
11
+ }
12
+ /** Diagnostic writes never emit trigger sources or retain an unbounded occurrence history. */
13
+ export declare class TriggerDiagnostics {
14
+ private readonly dependencies;
15
+ private readonly consumer;
16
+ constructor(dependencies: Dependencies, consumer: string);
17
+ get(): Promise<{
18
+ triggerId: string;
19
+ source: {
20
+ kind: "event";
21
+ eventId: string;
22
+ eventType: string;
23
+ } | {
24
+ kind: "cron";
25
+ slot: string;
26
+ };
27
+ occurredAt: string;
28
+ reason: "paused" | "own-scope" | "removed" | "dispatch-paused" | "capacity-unavailable" | "pending-source-limit";
29
+ }[]>;
30
+ record(triggerId: string, source: TriggerSource, reason: SkipReason): Promise<void>;
31
+ ineligibleReason(view: TriggerView, id: string, config: TriggerConfig | undefined, configured: boolean, active?: boolean): Promise<SkipReason | undefined>;
32
+ }
33
+ export {};
@@ -0,0 +1,38 @@
1
+ import { TriggerSkipReason, maximumTriggerDiagnostics, triggerDiagnosticsSchema, } from '../contracts/trigger-diagnostics.js';
2
+ /** Diagnostic writes never emit trigger sources or retain an unbounded occurrence history. */
3
+ export class TriggerDiagnostics {
4
+ dependencies;
5
+ consumer;
6
+ constructor(dependencies, consumer) {
7
+ this.dependencies = dependencies;
8
+ this.consumer = consumer;
9
+ }
10
+ async get() {
11
+ const stored = await this.dependencies.state.read(this.consumer, 'skip-diagnostics');
12
+ return stored === null ? [] : triggerDiagnosticsSchema.parse(stored.value);
13
+ }
14
+ async record(triggerId, source, reason) {
15
+ const previous = await this.get();
16
+ await this.dependencies.state.write({
17
+ consumer: this.consumer,
18
+ key: 'skip-diagnostics',
19
+ value: [
20
+ ...previous.filter((entry) => entry.triggerId !== triggerId),
21
+ { triggerId, source, reason, occurredAt: this.dependencies.now() },
22
+ ].slice(-maximumTriggerDiagnostics),
23
+ });
24
+ }
25
+ async ineligibleReason(view, id, config, configured, active = false) {
26
+ if (view.pauses[id] !== undefined)
27
+ return TriggerSkipReason.Paused;
28
+ if (config === undefined || !configured)
29
+ return TriggerSkipReason.Removed;
30
+ if (await this.dependencies.isDispatchPaused())
31
+ return TriggerSkipReason.DispatchPaused;
32
+ if (!active &&
33
+ config.when?.capacityAvailable === true &&
34
+ !(await this.dependencies.capacityAvailable(config)))
35
+ return TriggerSkipReason.Capacity;
36
+ return undefined;
37
+ }
38
+ }
@@ -0,0 +1,21 @@
1
+ import type { EventEnvelope, EventJournal, ProcessorRunSerialiser, ProcessorStateStore } from '@atolis-hq/eventing';
2
+ import type { IdGenerator } from '../../kernel/index.js';
3
+ import type { TriggerConfig } from '../contracts/config.js';
4
+ import type { TriggerInvocationView } from './trigger-projection.js';
5
+ import type { TriggerCheckpointStore } from './trigger-source-cursor.js';
6
+ import type { TriggerWorkflowPorts } from './trigger-workflow.js';
7
+ export interface TriggerServiceDependencies extends TriggerWorkflowPorts {
8
+ readonly checkpoint: TriggerCheckpointStore;
9
+ readonly journal: EventJournal;
10
+ readonly state: ProcessorStateStore;
11
+ readonly history: () => Promise<readonly TriggerInvocationView[]>;
12
+ readonly invocationScope: (workItemId: string) => Promise<string | null>;
13
+ readonly serialise: ProcessorRunSerialiser;
14
+ readonly ids: IdGenerator;
15
+ readonly configurations: () => readonly TriggerConfig[];
16
+ readonly coordinationKey?: (config: TriggerConfig) => string;
17
+ readonly sourceWorkItem: (event: EventEnvelope) => Promise<string | null>;
18
+ readonly isDispatchPaused: () => Promise<boolean>;
19
+ readonly capacityAvailable: (config: TriggerConfig) => Promise<boolean>;
20
+ readonly now: () => string;
21
+ }
@@ -1,35 +1,24 @@
1
- import { type CommandContext, type EventEnvelope, type EventJournal, type ProcessorRunSerialiser, type ProcessorStateStore } from '@atolis-hq/eventing';
2
- import type { IdGenerator } from '../../kernel/index.js';
1
+ import type { CommandContext, EventEnvelope } from '@atolis-hq/eventing';
3
2
  import type { TriggerConfig } from '../contracts/config.js';
4
3
  import { type TriggerSource } from '../contracts/events.js';
5
- import { type TriggerInvocationView, type TriggerView } from './trigger-projection.js';
6
- import { type TriggerCheckpointStore } from './trigger-source-cursor.js';
7
- import type { TriggerWorkflowPorts } from './trigger-workflow.js';
4
+ import { type TriggerSkipDiagnostic } from '../contracts/trigger-diagnostics.js';
5
+ import { type TriggerView } from './trigger-projection.js';
6
+ import type { TriggerServiceDependencies } from './trigger-service-ports.js';
7
+ export type { TriggerServiceDependencies } from './trigger-service-ports.js';
8
8
  export type { TriggerCheckpointStore } from './trigger-source-cursor.js';
9
+ export type TriggerInspectionView = TriggerView & {
10
+ readonly diagnostics: readonly TriggerSkipDiagnostic[];
11
+ };
9
12
  export declare const triggerCriticalSectionConsumer = "control-plane:trigger-coordination";
10
- export interface TriggerServiceDependencies extends TriggerWorkflowPorts {
11
- readonly checkpoint: TriggerCheckpointStore;
12
- readonly journal: EventJournal;
13
- readonly state: ProcessorStateStore;
14
- readonly history: () => Promise<readonly TriggerInvocationView[]>;
15
- readonly invocationScope: (workItemId: string) => Promise<string | null>;
16
- readonly serialise: ProcessorRunSerialiser;
17
- readonly ids: IdGenerator;
18
- readonly configurations: () => readonly TriggerConfig[];
19
- readonly coordinationKey?: (config: TriggerConfig) => string;
20
- readonly sourceWorkItem: (event: EventEnvelope) => Promise<string | null>;
21
- readonly isDispatchPaused: () => Promise<boolean>;
22
- readonly capacityAvailable: (config: TriggerConfig) => Promise<boolean>;
23
- readonly now: () => string;
24
- }
25
13
  /** Requests and claims are journal facts; the cron cursor is processor recovery state. */
26
14
  export declare class TriggerService {
27
15
  private readonly dependencies;
28
16
  private readonly policy;
29
17
  private readonly reader;
30
18
  private readonly sourceCursor;
19
+ private readonly diagnostics;
31
20
  constructor(dependencies: TriggerServiceDependencies);
32
- get(): Promise<TriggerView>;
21
+ get(): Promise<TriggerInspectionView>;
33
22
  reconcile(context: CommandContext): Promise<void>;
34
23
  pause(triggerId: string, reason: string, context: CommandContext): Promise<void>;
35
24
  resume(triggerId: string, context: CommandContext): Promise<void>;
@@ -43,7 +32,6 @@ export declare class TriggerService {
43
32
  private emit;
44
33
  private request;
45
34
  private suppressed;
46
- private eligible;
47
35
  private advanceCoalesced;
48
36
  private recover;
49
37
  }
@@ -1,7 +1,9 @@
1
1
  import { ControlEventType, TriggerRequestDisposition, TriggerSourceKind, } from '../contracts/events.js';
2
+ import { TriggerSkipReason } from '../contracts/trigger-diagnostics.js';
2
3
  import { CronTriggerPolicy } from '../domain/cron-trigger-policy.js';
4
+ import { TriggerDiagnostics } from './trigger-diagnostics.js';
3
5
  import { appendTriggerFact, sourceIdentity } from './trigger-facts.js';
4
- import { maximumTriggerSources, } from './trigger-projection.js';
6
+ import { maximumTriggerSources } from './trigger-projection.js';
5
7
  import { recoverTriggerInvocation } from './trigger-recovery.js';
6
8
  import { hasActiveInvocation, isOwnScopeSource } from './trigger-rules.js';
7
9
  import { TriggerSourceCursor } from './trigger-source-cursor.js';
@@ -13,8 +15,10 @@ export class TriggerService {
13
15
  policy = new CronTriggerPolicy();
14
16
  reader;
15
17
  sourceCursor;
18
+ diagnostics;
16
19
  constructor(dependencies) {
17
20
  this.dependencies = dependencies;
21
+ this.diagnostics = new TriggerDiagnostics(dependencies, triggerCriticalSectionConsumer);
18
22
  this.reader = new TriggerStateReader(dependencies.journal);
19
23
  this.sourceCursor = new TriggerSourceCursor(dependencies);
20
24
  }
@@ -22,6 +26,7 @@ export class TriggerService {
22
26
  return this.serialise(async () => ({
23
27
  ...(await this.view()),
24
28
  invocations: await this.dependencies.history(),
29
+ diagnostics: await this.diagnostics.get(),
25
30
  }));
26
31
  }
27
32
  async reconcile(context) {
@@ -112,14 +117,21 @@ export class TriggerService {
112
117
  const coordinationKey = this.key(config);
113
118
  // The reactor checkpoint consumes suppressed sources. Emitting another trigger request
114
119
  // here could itself become a source when subscribed to Control Plane events.
115
- if (duplicate || (await this.suppressed(view, config, coordinationKey, event))) {
120
+ if (duplicate) {
116
121
  await this.sourceCursor.consume(config.id, source, event);
117
122
  return false;
118
123
  }
119
- const eligible = view.pauses[config.id] === undefined &&
120
- this.configured(config.id) !== undefined &&
121
- !(await this.dependencies.isDispatchPaused()) &&
122
- (hasActiveInvocation(view, coordinationKey) || (await this.eligible(config)));
124
+ if (await this.suppressed(view, config, coordinationKey, event)) {
125
+ await this.diagnostics.record(config.id, source, TriggerSkipReason.OwnScope);
126
+ await this.sourceCursor.consume(config.id, source, event);
127
+ return false;
128
+ }
129
+ const reason = await this.diagnostics.ineligibleReason(view, config.id, config, this.configured(config.id) !== undefined, hasActiveInvocation(view, coordinationKey));
130
+ const eligible = reason === undefined;
131
+ if (reason !== undefined)
132
+ await this.diagnostics.record(config.id, source, reason);
133
+ else if ((view.coalesced[coordinationKey]?.sources.length ?? 0) >= maximumTriggerSources)
134
+ await this.diagnostics.record(config.id, source, TriggerSkipReason.PendingLimit);
123
135
  if (eligible && (view.coalesced[coordinationKey]?.sources.length ?? 0) < maximumTriggerSources)
124
136
  await this.emit({
125
137
  eventType: ControlEventType.TriggerRequestRecorded,
@@ -143,11 +155,6 @@ export class TriggerService {
143
155
  invocationScope: this.dependencies.invocationScope,
144
156
  });
145
157
  }
146
- async eligible(config) {
147
- return (!(await this.dependencies.isDispatchPaused()) &&
148
- (config.when?.capacityAvailable !== true ||
149
- (await this.dependencies.capacityAvailable(config))));
150
- }
151
158
  async advanceCoalesced(context) {
152
159
  const view = await this.view();
153
160
  for (const request of Object.values(view.coalesced)) {
@@ -155,9 +162,9 @@ export class TriggerService {
155
162
  continue;
156
163
  const config = this.configured(request.triggerId);
157
164
  const identity = `trigger:${request.triggerId}:${sourceIdentity(request.source)}`;
158
- if (config === undefined ||
159
- view.pauses[request.triggerId] !== undefined ||
160
- !(await this.eligible(config))) {
165
+ const reason = await this.diagnostics.ineligibleReason(view, request.triggerId, config, config !== undefined);
166
+ if (reason !== undefined || config === undefined) {
167
+ await this.diagnostics.record(request.triggerId, request.source, reason ?? TriggerSkipReason.Removed);
161
168
  // This recorded request was reconsidered and consumed; later eligibility is not a source.
162
169
  await this.emit({
163
170
  eventType: ControlEventType.TriggerRequestRecorded,
@@ -0,0 +1,53 @@
1
+ import { z } from 'zod';
2
+ import type { ValueOf } from '../../kernel/index.js';
3
+ export declare const TriggerSkipReason: {
4
+ readonly OwnScope: "own-scope";
5
+ readonly Paused: "paused";
6
+ readonly Removed: "removed";
7
+ readonly DispatchPaused: "dispatch-paused";
8
+ readonly Capacity: "capacity-unavailable";
9
+ readonly PendingLimit: "pending-source-limit";
10
+ };
11
+ export type TriggerSkipReason = ValueOf<typeof TriggerSkipReason>;
12
+ export declare const triggerSkipDiagnosticSchema: z.ZodObject<{
13
+ triggerId: z.ZodString;
14
+ source: z.ZodDiscriminatedUnion<[z.ZodObject<{
15
+ kind: z.ZodLiteral<"event">;
16
+ eventId: z.ZodString;
17
+ eventType: z.ZodString;
18
+ }, z.core.$strict>, z.ZodObject<{
19
+ kind: z.ZodLiteral<"cron">;
20
+ slot: z.ZodString;
21
+ }, z.core.$strict>], "kind">;
22
+ occurredAt: z.ZodString;
23
+ reason: z.ZodEnum<{
24
+ readonly OwnScope: "own-scope";
25
+ readonly Paused: "paused";
26
+ readonly Removed: "removed";
27
+ readonly DispatchPaused: "dispatch-paused";
28
+ readonly Capacity: "capacity-unavailable";
29
+ readonly PendingLimit: "pending-source-limit";
30
+ }>;
31
+ }, z.core.$strict>;
32
+ export type TriggerSkipDiagnostic = z.infer<typeof triggerSkipDiagnosticSchema>;
33
+ export declare const maximumTriggerDiagnostics = 256;
34
+ export declare const triggerDiagnosticsSchema: z.ZodArray<z.ZodObject<{
35
+ triggerId: z.ZodString;
36
+ source: z.ZodDiscriminatedUnion<[z.ZodObject<{
37
+ kind: z.ZodLiteral<"event">;
38
+ eventId: z.ZodString;
39
+ eventType: z.ZodString;
40
+ }, z.core.$strict>, z.ZodObject<{
41
+ kind: z.ZodLiteral<"cron">;
42
+ slot: z.ZodString;
43
+ }, z.core.$strict>], "kind">;
44
+ occurredAt: z.ZodString;
45
+ reason: z.ZodEnum<{
46
+ readonly OwnScope: "own-scope";
47
+ readonly Paused: "paused";
48
+ readonly Removed: "removed";
49
+ readonly DispatchPaused: "dispatch-paused";
50
+ readonly Capacity: "capacity-unavailable";
51
+ readonly PendingLimit: "pending-source-limit";
52
+ }>;
53
+ }, z.core.$strict>>;
@@ -0,0 +1,23 @@
1
+ import { z } from 'zod';
2
+ import { triggerSourceSchema } from './events.js';
3
+ export const TriggerSkipReason = {
4
+ OwnScope: 'own-scope',
5
+ Paused: 'paused',
6
+ Removed: 'removed',
7
+ DispatchPaused: 'dispatch-paused',
8
+ Capacity: 'capacity-unavailable',
9
+ PendingLimit: 'pending-source-limit',
10
+ };
11
+ export const triggerSkipDiagnosticSchema = z
12
+ .object({
13
+ triggerId: z.string().min(1),
14
+ source: triggerSourceSchema,
15
+ occurredAt: z.string().datetime({ offset: true }),
16
+ reason: z.enum(TriggerSkipReason),
17
+ })
18
+ .strict();
19
+ // Operational diagnostics are bounded processor state, not occurrence history.
20
+ export const maximumTriggerDiagnostics = 256;
21
+ export const triggerDiagnosticsSchema = z
22
+ .array(triggerSkipDiagnosticSchema)
23
+ .max(maximumTriggerDiagnostics);
@@ -3,6 +3,7 @@ export interface CronTriggerSlot {
3
3
  readonly at: string;
4
4
  }
5
5
  export declare class CronTriggerPolicy {
6
+ nextOccurrence(cron: string, now: string): string;
6
7
  elapsedSlots(config: {
7
8
  readonly id: string;
8
9
  readonly cron: string;
@@ -1,5 +1,16 @@
1
1
  import { CronExpressionParser } from 'cron-parser';
2
2
  export class CronTriggerPolicy {
3
+ nextOccurrence(cron, now) {
4
+ const fields = cron.trim().split(/\s+/);
5
+ const expression = CronExpressionParser.parse(cron, { currentDate: now, tz: 'UTC' });
6
+ const dayOfMonth = fieldExpression(fields, 2, 4);
7
+ const dayOfWeek = fieldExpression(fields, 4, 2);
8
+ while (true) {
9
+ const date = expression.next().toDate();
10
+ if (matchesDays(date, dayOfMonth, dayOfWeek))
11
+ return date.toISOString();
12
+ }
13
+ }
3
14
  elapsedSlots(config, now, checkpoint, maximumSlots = Number.POSITIVE_INFINITY) {
4
15
  const end = minute(new Date(now));
5
16
  const start = checkpoint === null ? end : minute(new Date(new Date(checkpoint).getTime() + 60_000));
@@ -10,6 +10,7 @@ export * from './application/trigger-service.js';
10
10
  export * from './application/intake-pipeline.js';
11
11
  export * from './application/runner-pipeline.js';
12
12
  export * from './application/work-cancellation-policy.js';
13
+ export * from './contracts/trigger-diagnostics.js';
13
14
  export * from './contracts/commands.js';
14
15
  export * from './contracts/config.js';
15
16
  export * from './contracts/events.js';
@@ -9,6 +9,7 @@ export * from './application/trigger-service.js';
9
9
  export * from './application/intake-pipeline.js';
10
10
  export * from './application/runner-pipeline.js';
11
11
  export * from './application/work-cancellation-policy.js';
12
+ export * from './contracts/trigger-diagnostics.js';
12
13
  export * from './contracts/commands.js';
13
14
  export * from './contracts/config.js';
14
15
  export * from './contracts/events.js';
@@ -173,8 +173,8 @@ export declare const supplementalCommandConfigSchema: z.ZodObject<{
173
173
  with: z.ZodOptional<z.ZodUnknown>;
174
174
  allowedActors: z.ZodReadonly<z.ZodArray<z.ZodEnum<{
175
175
  human: "human";
176
- watch: "watch";
177
176
  auto: "auto";
177
+ watch: "watch";
178
178
  }>>>;
179
179
  }, z.core.$strict>;
180
180
  export declare const workflowDefinitionConfigSchema: z.ZodObject<{
@@ -184,8 +184,8 @@ export declare const workflowDefinitionConfigSchema: z.ZodObject<{
184
184
  with: z.ZodOptional<z.ZodUnknown>;
185
185
  allowedActors: z.ZodReadonly<z.ZodArray<z.ZodEnum<{
186
186
  human: "human";
187
- watch: "watch";
188
187
  auto: "auto";
188
+ watch: "watch";
189
189
  }>>>;
190
190
  }, z.core.$strict>>>;
191
191
  watches: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodObject<{
@@ -10,5 +10,6 @@ export * from './resources.js';
10
10
  export * from './system.js';
11
11
  export * from './status.js';
12
12
  export * from './transport-values.js';
13
+ export * from './triggers.js';
13
14
  export * from './work.js';
14
15
  export * from './workflow-diagram.js';
@@ -10,5 +10,6 @@ export * from './resources.js';
10
10
  export * from './system.js';
11
11
  export * from './status.js';
12
12
  export * from './transport-values.js';
13
+ export * from './triggers.js';
13
14
  export * from './work.js';
14
15
  export * from './workflow-diagram.js';
@@ -1,4 +1,5 @@
1
1
  import type { ActivityOutcomeKind } from '../../../activities/index.js';
2
+ import type { TriggerRequestDisposition, TriggerSkipReason, TriggerSourceKind } from '../../../control-plane/index.js';
2
3
  import type { RunStatus } from '../../../execution/index.js';
3
4
  import type { ApiCommandStatus } from './control-plane.js';
4
5
  export declare const AcceptedCommandStatusValue: {
@@ -42,4 +43,11 @@ export declare const TranscriptGroupKindValue: {
42
43
  readonly Session: string;
43
44
  readonly Run: string;
44
45
  };
46
+ export declare const TriggerSourceKindValue: typeof TriggerSourceKind;
47
+ export declare const TriggerRequestDispositionValue: typeof TriggerRequestDisposition;
48
+ export declare const TriggerSkipReasonValue: typeof TriggerSkipReason;
49
+ export declare const TriggerFinishedStatusValue: {
50
+ readonly Completed: "completed" | "superseded";
51
+ readonly Superseded: "completed" | "superseded";
52
+ };
45
53
  export {};
@@ -58,3 +58,26 @@ export const TranscriptGroupKindValue = {
58
58
  Session: transcriptGroupKinds[0],
59
59
  Run: transcriptGroupKinds[1],
60
60
  };
61
+ // Trigger transport vocabulary avoids importing the server implementation into the browser.
62
+ export const TriggerSourceKindValue = {
63
+ Event: 'event',
64
+ Cron: 'cron',
65
+ };
66
+ export const TriggerRequestDispositionValue = {
67
+ Coalesced: 'coalesced',
68
+ Skipped: 'skipped',
69
+ };
70
+ export const TriggerSkipReasonValue = {
71
+ OwnScope: 'own-scope',
72
+ Paused: 'paused',
73
+ Removed: 'removed',
74
+ DispatchPaused: 'dispatch-paused',
75
+ Capacity: 'capacity-unavailable',
76
+ PendingLimit: 'pending-source-limit',
77
+ };
78
+ const triggerFinishedStatusShape = { completed: true, superseded: true };
79
+ const triggerFinishedStatuses = Object.keys(triggerFinishedStatusShape);
80
+ export const TriggerFinishedStatusValue = {
81
+ Completed: triggerFinishedStatuses[0],
82
+ Superseded: triggerFinishedStatuses[1],
83
+ };
@@ -0,0 +1,22 @@
1
+ import type { TriggerConfig, TriggerInvocationView, TriggerSkipDiagnostic, TriggerView } from '../../../control-plane/index.js';
2
+ import type { ValueOf } from '../../../kernel/index.js';
3
+ export declare const TriggerStatus: {
4
+ readonly Enabled: "running" | "paused" | "removed" | "enabled";
5
+ readonly Paused: "running" | "paused" | "removed" | "enabled";
6
+ readonly Running: "running" | "paused" | "removed" | "enabled";
7
+ readonly Removed: "running" | "paused" | "removed" | "enabled";
8
+ };
9
+ export type TriggerStatus = ValueOf<typeof TriggerStatus>;
10
+ export interface TriggerResponse {
11
+ readonly triggerId: string;
12
+ readonly status: TriggerStatus;
13
+ readonly definition: TriggerConfig | null;
14
+ readonly paused: boolean;
15
+ readonly pauseReason: string | null;
16
+ readonly nextOccurrence: string | null;
17
+ readonly pending: readonly TriggerView['coalesced'][string][];
18
+ readonly latestSkip: TriggerSkipDiagnostic | null;
19
+ readonly invocations: readonly (TriggerInvocationView & {
20
+ readonly workItemKey: string;
21
+ })[];
22
+ }
@@ -0,0 +1,8 @@
1
+ const triggerStatusShape = { enabled: true, paused: true, running: true, removed: true };
2
+ const triggerStatuses = Object.keys(triggerStatusShape);
3
+ export const TriggerStatus = {
4
+ Enabled: triggerStatuses[0],
5
+ Paused: triggerStatuses[1],
6
+ Running: triggerStatuses[2],
7
+ Removed: triggerStatuses[3],
8
+ };
@@ -19,6 +19,7 @@ export interface WorkItemResponse {
19
19
  readonly lastRunOutcome?: string;
20
20
  }
21
21
  export interface WorkDetailResponse {
22
+ readonly triggerOrigin?: string;
22
23
  readonly work: WorkItemResponse;
23
24
  readonly resources: readonly ResourceItemResponse[];
24
25
  readonly orchestration: {