@atolis-hq/wake 0.4.66 → 0.4.68

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 (86) hide show
  1. package/dist/src/artifacts/application/artifact-context-service.js +1 -0
  2. package/dist/src/artifacts/application/artifact-service.js +9 -4
  3. package/dist/src/artifacts/application/operator-instructions-projection.d.ts +4 -0
  4. package/dist/src/artifacts/application/operator-instructions-projection.js +19 -0
  5. package/dist/src/artifacts/application/operator-instructions-service.d.ts +25 -0
  6. package/dist/src/artifacts/application/operator-instructions-service.js +110 -0
  7. package/dist/src/artifacts/contracts/context-event-factory.js +2 -0
  8. package/dist/src/artifacts/contracts/context-events.d.ts +5 -1
  9. package/dist/src/artifacts/contracts/context-events.js +17 -2
  10. package/dist/src/artifacts/contracts/context.d.ts +17 -0
  11. package/dist/src/artifacts/contracts/context.js +11 -0
  12. package/dist/src/artifacts/contracts/paths.d.ts +3 -0
  13. package/dist/src/artifacts/contracts/paths.js +10 -0
  14. package/dist/src/artifacts/index.d.ts +2 -0
  15. package/dist/src/artifacts/index.js +2 -0
  16. package/dist/src/artifacts/infrastructure/file-artifact-store.d.ts +6 -0
  17. package/dist/src/artifacts/infrastructure/file-artifact-store.js +12 -5
  18. package/dist/src/artifacts/infrastructure/mcp-server.d.ts +2 -1
  19. package/dist/src/artifacts/infrastructure/mcp-server.js +22 -0
  20. package/dist/src/artifacts/infrastructure/mcp-session-store.d.ts +2 -1
  21. package/dist/src/artifacts/infrastructure/mcp-session-store.js +5 -1
  22. package/dist/src/bootstrap/artifact-mcp.d.ts +4 -2
  23. package/dist/src/bootstrap/artifact-mcp.js +53 -3
  24. package/dist/src/bootstrap/composition-root.d.ts +2 -1
  25. package/dist/src/bootstrap/composition-root.js +5 -1
  26. package/dist/src/bootstrap/initialise.js +63 -0
  27. package/dist/src/bootstrap/integration-runtime.js +17 -2
  28. package/dist/src/bootstrap/persistence-composition.js +4 -1
  29. package/dist/src/bootstrap/projection-runtime.js +2 -1
  30. package/dist/src/bootstrap/surface-api-execution-applications.js +16 -1
  31. package/dist/src/bootstrap/surface-api-trigger-applications.js +77 -4
  32. package/dist/src/bootstrap/surface-api-work-applications.js +38 -3
  33. package/dist/src/bootstrap/surface-cli-applications.js +1 -0
  34. package/dist/src/bootstrap/version.js +1 -1
  35. package/dist/src/conversations/contracts/events.js +2 -0
  36. package/dist/src/conversations/contracts/views.d.ts +5 -1
  37. package/dist/src/execution/application/execution-activity.d.ts +4 -0
  38. package/dist/src/execution/application/execution-activity.js +19 -0
  39. package/dist/src/execution/contracts/event-factory.js +2 -0
  40. package/dist/src/execution/contracts/events.d.ts +5 -0
  41. package/dist/src/execution/contracts/events.js +7 -0
  42. package/dist/src/execution/contracts/views.d.ts +4 -0
  43. package/dist/src/execution/domain/run.js +3 -0
  44. package/dist/src/integrations/application/conversation-command-feedback.d.ts +11 -0
  45. package/dist/src/integrations/application/conversation-command-feedback.js +36 -0
  46. package/dist/src/integrations/delivery/application/delivery-intent-lookup.d.ts +4 -0
  47. package/dist/src/integrations/delivery/application/delivery-intent-lookup.js +23 -0
  48. package/dist/src/integrations/delivery/application/delivery-outcome-reactor.js +4 -11
  49. package/dist/src/integrations/delivery/application/delivery-projector.js +7 -1
  50. package/dist/src/integrations/delivery/contracts/intents.d.ts +3 -1
  51. package/dist/src/integrations/delivery/contracts/intents.js +1 -1
  52. package/dist/src/integrations/delivery/contracts/views.d.ts +1 -0
  53. package/dist/src/integrations/github/application/agent-run-comment.js +7 -9
  54. package/dist/src/integrations/github/application/inbound-translator.js +13 -1
  55. package/dist/src/integrations/github/application/work-control-authorization.d.ts +6 -0
  56. package/dist/src/integrations/github/application/work-control-authorization.js +10 -0
  57. package/dist/src/integrations/index.d.ts +1 -0
  58. package/dist/src/integrations/index.js +1 -0
  59. package/dist/src/node_modules/@atolis-hq/eventing/dist/store/event-journal.d.ts +5 -1
  60. package/dist/src/node_modules/@atolis-hq/eventing/dist/store/event-journal.d.ts.map +1 -1
  61. package/dist/src/node_modules/@atolis-hq/eventing-filesystem/dist/file-event-journal.d.ts +2 -2
  62. package/dist/src/node_modules/@atolis-hq/eventing-filesystem/dist/file-event-journal.d.ts.map +1 -1
  63. package/dist/src/node_modules/@atolis-hq/eventing-filesystem/dist/file-event-journal.js +3 -1
  64. package/dist/src/orchestration/application/conversation-command-reactor.d.ts +16 -1
  65. package/dist/src/orchestration/application/conversation-command-reactor.js +34 -5
  66. package/dist/src/orchestration/application/conversation-command.d.ts +27 -4
  67. package/dist/src/orchestration/application/conversation-command.js +60 -22
  68. package/dist/src/orchestration/application/orchestration-service.d.ts +5 -8
  69. package/dist/src/orchestration/application/orchestration-service.js +93 -34
  70. package/dist/src/orchestration/domain/interpreter.d.ts +1 -1
  71. package/dist/src/orchestration/domain/interpreter.js +1 -1
  72. package/dist/src/orchestration/domain/operator-retry-policy.d.ts +2 -0
  73. package/dist/src/orchestration/domain/operator-retry-policy.js +24 -1
  74. package/dist/src/surfaces/api/contracts/execution.d.ts +7 -0
  75. package/dist/src/surfaces/api/contracts/triggers.d.ts +14 -0
  76. package/dist/src/surfaces/api/contracts/work.d.ts +3 -0
  77. package/dist/src/surfaces/api/http-server.d.ts +1 -0
  78. package/dist/src/surfaces/api/http-server.js +6 -2
  79. package/dist/src/surfaces/api/presenters/execution.js +3 -0
  80. package/dist/src/surfaces/api/routes/applications.d.ts +8 -2
  81. package/dist/src/surfaces/api/routes/commands.js +55 -12
  82. package/dist/src/surfaces/web-assets/assets/index-DVapiQjj.js +1192 -0
  83. package/dist/src/surfaces/web-assets/index.html +1 -1
  84. package/package.json +1 -1
  85. package/prompts/triage-assign.md +4 -0
  86. package/dist/src/surfaces/web-assets/assets/index-9IfrHvBo.js +0 -1192
@@ -1,15 +1,15 @@
1
1
  import { recoverPolicyBlockedMerges } from './policy-blocked-merge-recovery.js';
2
- import { WorkStatus } from '../../work/index.js';
2
+ import { WorkStatus, } from '../../work/index.js';
3
3
  import { selectOrchestrationEvent } from '../contracts/event-decoder.js';
4
4
  import { OrchestrationEventType } from '../contracts/events.js';
5
5
  import { commandName, workflowInstanceId as toWorkflowInstanceId, } from '../contracts/identifiers.js';
6
6
  import { childOrchestrationGroupStream, workflowInstanceStream } from '../contracts/streams.js';
7
- import { ApprovalAuthorityKind } from '../contracts/vocabulary.js';
8
- import { isGroupBudgetExtensionEligible } from '../domain/operator-retry-policy.js';
7
+ import { ApprovalAuthorityKind, ConversationBuiltInCommand } from '../contracts/vocabulary.js';
8
+ import { isGroupBudgetExtensionEligible, isNeedsClarificationResumeEligible, isPlainReplyResumeEligible, selectChangesResumeTargets, } from '../domain/operator-retry-policy.js';
9
9
  import { AcceptActivityOutcome } from './accept-activity-outcome.js';
10
10
  import { AcceptSignal } from './accept-signal.js';
11
11
  import { AdvanceWorkflow } from './advance-workflow.js';
12
- import { applyBuiltInConversationCommand, conversationCommand, } from './conversation-command.js';
12
+ import { applyBuiltInConversationCommand, continuationCommandRejection, conversationCommand, } from './conversation-command.js';
13
13
  import { CoordinationClaims } from './coordination-claims.js';
14
14
  import { GroupBudgetRecorder } from './group-budget-recorder.js';
15
15
  import { workflowsByWorkItemProjection } from './orchestration-projection.js';
@@ -72,48 +72,77 @@ export class OrchestrationService {
72
72
  return this.advanceWorkflow.requestSupplementalActivity(workflowInstanceId, request, context);
73
73
  }
74
74
  async applyConversationCommand(workItemId, input, context) {
75
+ return (await this.applyConversationCommandWithFeedback(workItemId, input, context)).applied;
76
+ }
77
+ async applyConversationCommandWithFeedback(workItemId, input, context) {
75
78
  const command = conversationCommand(input.body);
76
79
  if (command === null)
77
- return false;
78
- if (!input.authorized)
79
- return false;
80
- const work = await this.work.get(workItemId);
81
- if (work === null || work.deleted || work.frozen || work.state !== WorkStatus.Open)
82
- return false;
80
+ return { applied: false, reason: 'Message contains no command.' };
81
+ const continuationRejection = continuationCommandRejection(input, command);
82
+ if (continuationRejection !== null)
83
+ return { applied: false, reason: continuationRejection };
84
+ const reviewAuthorized = input.reviewAuthorized === true;
85
+ if (!input.authorized && !reviewAuthorized)
86
+ return {
87
+ applied: false,
88
+ reason: 'Verified repository write, maintain, or admin permission is required for work control; independent-review authority is required for approval.',
89
+ };
83
90
  // A command is causally adjacent to its conversation entry; projections may lag
84
91
  // the journal, so command application must read the authoritative workflow state.
85
92
  const workflows = (await this.advanceWorkflow.listAll()).filter((workflow) => workflow.workItemId === workItemId);
86
- // Configured commands deliberately win over built-ins, even when their spelling collides.
87
- let supplemental = false;
88
- for (const workflow of workflows) {
89
- const definition = await this.definitions.resolve(workflow);
90
- if (definition.commands[command] === undefined)
91
- continue;
92
- supplemental = true;
93
- await this.requestSupplementalActivity(workflow.workflowInstanceId, { command: commandName(command) }, context);
94
- }
95
- if (supplemental)
96
- return true;
93
+ if (conversationCommandAlreadyApplied(workflows, context.commandId))
94
+ return { applied: true };
95
+ const work = await this.work.get(workItemId);
96
+ if (!isWorkControllable(work))
97
+ return { applied: false, reason: 'Work item must be open, unfrozen, and not deleted.' };
98
+ if (!input.authorized && !isReviewConversationCommand(command))
99
+ return { applied: false, reason: 'Verified repository work-control authority is required.' };
100
+ // Explicit continuation invokes the owning recovery command; ordinary commands keep configured precedence.
101
+ if (!input.continuation &&
102
+ (await this.applyConfiguredConversationCommands(command, workflows, context)))
103
+ return { applied: true };
97
104
  return applyBuiltInConversationCommand({
98
105
  command,
99
106
  capabilities: input.capabilities,
107
+ reviewAuthorized,
108
+ workAuthorized: input.authorized,
109
+ continuation: input.continuation === true,
100
110
  workflows,
101
111
  context,
102
- acceptSignal: (id, outcome) => this.acceptSignal(id, {
103
- kind: (workflows.find((workflow) => workflow.workflowInstanceId === id)?.waitingFor
104
- ?.signalKind ?? 'approved'),
105
- outcome,
106
- actorId: input.actorId,
107
- actorDecision: { authorized: true, evidenceId: context.commandId },
108
- providerEventId: context.commandId,
109
- authority: { kind: ApprovalAuthorityKind.Human },
110
- }, context),
112
+ acceptSignal: async (id, outcome) => {
113
+ const updated = await this.acceptSignal(id, {
114
+ kind: (workflows.find((workflow) => workflow.workflowInstanceId === id)?.waitingFor
115
+ ?.signalKind ?? 'approved'),
116
+ outcome,
117
+ actorId: input.actorId,
118
+ actorDecision: { authorized: true, evidenceId: context.commandId },
119
+ providerEventId: context.commandId,
120
+ authority: { kind: ApprovalAuthorityKind.Human },
121
+ }, context);
122
+ return updated.acceptedSignalIds.includes(context.commandId);
123
+ },
111
124
  retry: (id) => this.retryBlockedFailedStage(id, context),
112
125
  restart: (id) => this.restartBlockedFailedStage(id, context),
113
126
  extend: (id) => this.extendBlockedGroupBudget(id, { kind: ApprovalAuthorityKind.Human }, context),
114
- resumeChanges: (id) => this.resumeBlockedStageForChanges(id, context),
127
+ resumeChanges: async (id) => {
128
+ if (!input.authorized)
129
+ return false;
130
+ const updated = await this.resumeBlockedStageForChanges(id, context);
131
+ return updated?.operatorRetryCommandIds.includes(context.commandId) === true;
132
+ },
115
133
  });
116
134
  }
135
+ async applyConfiguredConversationCommands(command, workflows, context) {
136
+ let supplemental = false;
137
+ for (const workflow of workflows) {
138
+ const definition = await this.definitions.resolve(workflow);
139
+ if (definition.commands[command] === undefined)
140
+ continue;
141
+ supplemental = true;
142
+ await this.requestSupplementalActivity(workflow.workflowInstanceId, { command: commandName(command) }, context);
143
+ }
144
+ return supplemental;
145
+ }
117
146
  markActivationStarted(workflowInstanceId, activationId, context) {
118
147
  return this.advanceWorkflow.markActivationStarted(workflowInstanceId, activationId, context);
119
148
  }
@@ -135,11 +164,29 @@ export class OrchestrationService {
135
164
  restartBlockedFailedStage(workflowInstanceId, context) {
136
165
  return this.transitionWatchChildren(context, () => this.advanceWorkflow.restartBlockedFailedStage(workflowInstanceId, context));
137
166
  }
138
- resumeBlockedStageForChanges(workflowInstanceId, context) {
167
+ async resumeBlockedStageForChanges(workflowInstanceId, context) {
168
+ const current = await this.advanceWorkflow.get(workflowInstanceId);
169
+ if (current === null)
170
+ return null;
171
+ const work = await this.work.get(current.workItemId);
172
+ if (work === null || work.deleted || work.frozen || work.state !== WorkStatus.Open)
173
+ return current;
174
+ if (!current.operatorRetryCommandIds.includes(context.commandId) &&
175
+ !selectChangesResumeTargets((await this.advanceWorkflow.listAll()).filter((workflow) => workflow.workItemId === current.workItemId)).some((workflow) => workflow.workflowInstanceId === workflowInstanceId))
176
+ return current;
139
177
  return this.transitionWatchChildren(context, () => this.advanceWorkflow.resumeBlockedStageForChanges(workflowInstanceId, context));
140
178
  }
141
- resumeNeedsClarificationStage(workflowInstanceId, context) {
142
- return this.transitionWatchChildren(context, () => this.advanceWorkflow.resumeNeedsClarificationStage(workflowInstanceId, context));
179
+ async resumeBlockedStageForReply(workflowInstanceId, context) {
180
+ const current = await this.advanceWorkflow.get(workflowInstanceId);
181
+ if (current === null || !isPlainReplyResumeEligible(current))
182
+ return current;
183
+ return this.resumeBlockedStageForChanges(workflowInstanceId, context);
184
+ }
185
+ async resumeNeedsClarificationStage(workflowInstanceId, context) {
186
+ const current = await this.advanceWorkflow.get(workflowInstanceId);
187
+ if (current === null || !isNeedsClarificationResumeEligible(current))
188
+ return current;
189
+ return this.resumeBlockedStageForChanges(workflowInstanceId, context);
143
190
  }
144
191
  async extendBlockedGroupBudget(workflowInstanceId, authority, context) {
145
192
  if (authority.kind !== ApprovalAuthorityKind.Human)
@@ -254,3 +301,15 @@ async function journalGroupBudgetExhaustion(journal, workflowInstanceId) {
254
301
  });
255
302
  }
256
303
  export const createOrchestrationService = (journal, work, definitions, projections) => new OrchestrationService(journal, work, definitions, projections);
304
+ function isWorkControllable(work) {
305
+ return work !== null && !work.deleted && !work.frozen && work.state === WorkStatus.Open;
306
+ }
307
+ function conversationCommandAlreadyApplied(workflows, commandId) {
308
+ return workflows.some((workflow) => workflow.operatorRetryCommandIds.includes(commandId) ||
309
+ workflow.acceptedSignalIds.includes(commandId));
310
+ }
311
+ function isReviewConversationCommand(command) {
312
+ return (command === ConversationBuiltInCommand.Approved ||
313
+ command === ConversationBuiltInCommand.Accepted ||
314
+ command === ConversationBuiltInCommand.Changes);
315
+ }
@@ -7,7 +7,7 @@ export { acceptSignal, AwaitTimeoutBlockReason, expireTimedOutAwait, hasTimedOut
7
7
  export type { AcceptSignal } from './signal-policy.js';
8
8
  export { requestSupplementalActivity } from './supplemental-policy.js';
9
9
  export type { SupplementalActivityRequest } from './supplemental-policy.js';
10
- export { isChangesResumeEligible, isGroupBudgetExtensionEligible, isNeedsClarificationResumeEligible, isOperatorRetryEligible, requestChangesResume, requestFreshOperatorRetry, requestOperatorRetry, selectOperatorRetryTarget, } from './operator-retry-policy.js';
10
+ export { isChangesResumeEligible, isGroupBudgetExtensionEligible, isNeedsClarificationResumeEligible, isOperatorRetryEligible, isPlainReplyResumeEligible, requestChangesResume, requestFreshOperatorRetry, requestOperatorRetry, selectChangesResumeTargets, selectOperatorRetryTarget, } from './operator-retry-policy.js';
11
11
  export type { OperatorRetryRequest } from './operator-retry-policy.js';
12
12
  export { isRunnerQuotaRetryEligible, requestRunnerQuotaRetry, } from './runner-quota-retry-policy.js';
13
13
  export type { RunnerQuotaRetryRequest } from './runner-quota-retry-policy.js';
@@ -10,7 +10,7 @@ import { finishRoute } from './transition.js';
10
10
  export { startInstance } from './activation-policy.js';
11
11
  export { acceptSignal, AwaitTimeoutBlockReason, expireTimedOutAwait, hasTimedOutAwait, waitForSignal, } from './signal-policy.js';
12
12
  export { requestSupplementalActivity } from './supplemental-policy.js';
13
- export { isChangesResumeEligible, isGroupBudgetExtensionEligible, isNeedsClarificationResumeEligible, isOperatorRetryEligible, requestChangesResume, requestFreshOperatorRetry, requestOperatorRetry, selectOperatorRetryTarget, } from './operator-retry-policy.js';
13
+ export { isChangesResumeEligible, isGroupBudgetExtensionEligible, isNeedsClarificationResumeEligible, isOperatorRetryEligible, isPlainReplyResumeEligible, requestChangesResume, requestFreshOperatorRetry, requestOperatorRetry, selectChangesResumeTargets, selectOperatorRetryTarget, } from './operator-retry-policy.js';
14
14
  export { isRunnerQuotaRetryEligible, requestRunnerQuotaRetry, } from './runner-quota-retry-policy.js';
15
15
  export function acceptActivityOutcome(definition, state, input) {
16
16
  if (!isPendingOutcome(state, input))
@@ -6,7 +6,9 @@ export interface OperatorRetryRequest extends DecisionContext {
6
6
  }
7
7
  export declare function isOperatorRetryEligible(view: WorkflowInstanceView): boolean;
8
8
  export declare function selectOperatorRetryTarget(workflows: readonly WorkflowInstanceView[]): WorkflowInstanceView | undefined;
9
+ export declare function selectChangesResumeTargets(workflows: readonly WorkflowInstanceView[]): readonly WorkflowInstanceView[];
9
10
  export declare function isChangesResumeEligible(view: WorkflowInstanceView): boolean;
11
+ export declare function isPlainReplyResumeEligible(view: WorkflowInstanceView): boolean;
10
12
  /** A clarification reply may be supplied by any conversation participant. */
11
13
  export declare function isNeedsClarificationResumeEligible(view: WorkflowInstanceView): boolean;
12
14
  export declare function isGroupBudgetExtensionEligible(view: WorkflowInstanceView): boolean;
@@ -50,13 +50,36 @@ export function selectOperatorRetryTarget(workflows) {
50
50
  watched.has(watchId(workflow.watchId)) &&
51
51
  isOperatorRetryEligible(workflow));
52
52
  }
53
+ export function selectChangesResumeTargets(workflows) {
54
+ const primary = workflows.find((workflow) => workflow.parentWorkflowInstanceId === undefined);
55
+ if (primary === undefined)
56
+ return [];
57
+ if (isChangesResumeEligible(primary))
58
+ return [primary];
59
+ if (primary.status !== WorkflowStatus.Waiting ||
60
+ primary.waitingFor?.signalKind !== WatchGateVerdictSignal)
61
+ return [];
62
+ const watches = new Set((primary.waitingFor.from ?? []).flatMap((authority) => authority.kind === ApprovalAuthorityKind.Watch ? [authority.watch] : []));
63
+ return workflows.filter((workflow) => workflow.parentWorkflowInstanceId === primary.workflowInstanceId &&
64
+ workflow.workItemId === primary.workItemId &&
65
+ workflow.orchestrationGroupId === primary.orchestrationGroupId &&
66
+ workflow.watchId !== undefined &&
67
+ watches.has(watchId(workflow.watchId)) &&
68
+ isChangesResumeEligible(workflow));
69
+ }
53
70
  export function isChangesResumeEligible(view) {
54
71
  if (!isCompletedAgentStage(view))
55
72
  return false;
56
73
  return ((view.status === WorkflowStatus.Blocked &&
57
74
  view.blockReason === 'unconfigured outcome blocked' &&
58
75
  view.lastOutcome?.kind === ActivityOutcomeKind.Blocked) ||
59
- (view.status === WorkflowStatus.Waiting && view.waitingFor !== undefined));
76
+ (view.status === WorkflowStatus.Waiting &&
77
+ view.waitingFor !== undefined &&
78
+ view.lastOutcome?.kind !== ActivityOutcomeKind.Failed &&
79
+ !(view.waitingFor.from ?? []).some((authority) => authority.kind === ApprovalAuthorityKind.Watch)));
80
+ }
81
+ export function isPlainReplyResumeEligible(view) {
82
+ return isChangesResumeEligible(view) && view.lastOutcome?.kind === ActivityOutcomeKind.Blocked;
60
83
  }
61
84
  /** A clarification reply may be supplied by any conversation participant. */
62
85
  export function isNeedsClarificationResumeEligible(view) {
@@ -1,4 +1,11 @@
1
1
  export interface RunResponse {
2
+ readonly operatorInstructions?: {
3
+ readonly contextScope: string;
4
+ readonly revisionId: string | null;
5
+ readonly content?: string;
6
+ readonly author?: string;
7
+ readonly occurredAt?: string;
8
+ };
2
9
  readonly runId: string;
3
10
  readonly activationId: string;
4
11
  readonly activity: string;
@@ -8,6 +8,13 @@ export declare const TriggerStatus: {
8
8
  };
9
9
  export type TriggerStatus = ValueOf<typeof TriggerStatus>;
10
10
  export interface TriggerResponse {
11
+ readonly operatorInstructions?: {
12
+ readonly contextScope: string;
13
+ readonly revisionId: string;
14
+ readonly content: string;
15
+ readonly author: string;
16
+ readonly occurredAt: string;
17
+ } | null;
11
18
  readonly triggerId: string;
12
19
  readonly status: TriggerStatus;
13
20
  readonly definition: TriggerConfig | null;
@@ -20,3 +27,10 @@ export interface TriggerResponse {
20
27
  readonly workItemKey: string;
21
28
  })[];
22
29
  }
30
+ export interface OrphanedInstructionsResponse {
31
+ readonly contextScope: string;
32
+ readonly revisionId: string;
33
+ readonly content: string | null;
34
+ readonly author: string;
35
+ readonly occurredAt: string;
36
+ }
@@ -49,6 +49,8 @@ export interface WorkDetailResponse {
49
49
  readonly conversation: {
50
50
  /** Whether this authenticated surface may create control-plane entries. */
51
51
  readonly canCreateEntries: boolean;
52
+ /** Owning orchestration policy permits continuation with instructions. */
53
+ readonly canContinue?: boolean;
52
54
  readonly entries: readonly {
53
55
  readonly entryId: string;
54
56
  readonly body: string;
@@ -71,6 +73,7 @@ export interface WorkDetailResponse {
71
73
  export interface ConversationMessageRequest {
72
74
  readonly idempotencyKey: string;
73
75
  readonly body: string;
76
+ readonly continuation?: boolean;
74
77
  }
75
78
  export interface PullRequestResponse {
76
79
  readonly resourceId: string;
@@ -18,6 +18,7 @@ export interface ApiDispatcher {
18
18
  }
19
19
  export interface SurfaceHttpServerOptions {
20
20
  readonly dispatcher: ApiDispatcher;
21
+ readonly operatorInstructionsMaxWriteBytes?: number;
21
22
  readonly credentials: SurfaceCredentials;
22
23
  readonly assets?: AssetSource;
23
24
  readonly auth?: {
@@ -80,7 +80,7 @@ export function createSurfaceHttpServer(options) {
80
80
  if (!authDisabled && request.session.get(SurfaceSessionAttribute.Operator) !== true)
81
81
  return reply.code(401).send({ status: 401, title: 'Unauthorized' });
82
82
  });
83
- protectedApi.all('/*', async (request, reply) => {
83
+ const dispatchProtected = async (request, reply) => {
84
84
  const controller = new AbortController();
85
85
  const abort = () => controller.abort();
86
86
  const close = () => {
@@ -111,7 +111,11 @@ export function createSurfaceHttpServer(options) {
111
111
  contentType: 'application/problem+json',
112
112
  }, request.method === 'HEAD');
113
113
  return sendFastifyJson(reply, result, request.method === 'HEAD');
114
- });
114
+ };
115
+ protectedApi.post('/triggers/:triggerId/commands/instructions', {
116
+ bodyLimit: 6 * (options.operatorInstructionsMaxWriteBytes ?? 25 * 1024 * 1024) + 4096,
117
+ }, dispatchProtected);
118
+ protectedApi.all('/*', dispatchProtected);
115
119
  done();
116
120
  }, { prefix: '/api/v1' });
117
121
  app.route({
@@ -18,6 +18,9 @@ export function presentRun(value) {
18
18
  ? outcomeSentinels[value.outcome.kind]
19
19
  : value.status.toUpperCase()));
20
20
  return {
21
+ ...(value.operatorInstructions === undefined
22
+ ? {}
23
+ : { operatorInstructions: value.operatorInstructions }),
21
24
  runId: value.runId,
22
25
  activationId: value.activationId,
23
26
  activity: value.activity,
@@ -1,6 +1,6 @@
1
1
  import type { RunStatus } from '../../../execution/index.js';
2
2
  import type { AnalyticsReport, ReportDescriptor, ReportWindowId } from '../../../kernel/index.js';
3
- import type { ApiCommandResult, AuditEventResponse, BoardCardResponse, BoardResponse, CommandsResponse, ConfigurationResponse, ControlPlaneStatusResponse, ConversationMessageRequest, HealthResponse, MetricsResponse, ResourceItemResponse, ResourceResponse, ResponseMeta, RunnerResponse, RunResponse, RunTranscriptResponse, StatusResponse, TriggerResponse, WebhookSetupResponse, WorkDetailResponse, WorkflowDiagramsResponse, WorkflowInstanceResponse, WorkItemResponse, WorkItemTranscriptResponse } from '../contracts/index.js';
3
+ import type { ApiCommandResult, AuditEventResponse, BoardCardResponse, BoardResponse, CommandsResponse, ConfigurationResponse, ControlPlaneStatusResponse, ConversationMessageRequest, HealthResponse, MetricsResponse, OrphanedInstructionsResponse, ResourceItemResponse, ResourceResponse, ResponseMeta, RunnerResponse, RunResponse, RunTranscriptResponse, StatusResponse, TriggerResponse, WebhookSetupResponse, WorkDetailResponse, WorkflowDiagramsResponse, WorkflowInstanceResponse, WorkItemResponse, WorkItemTranscriptResponse } from '../contracts/index.js';
4
4
  import type { AnalyticsSummaryResponse } from '../contracts/observability.js';
5
5
  export interface CollectionQuery {
6
6
  readonly cursor?: {
@@ -55,8 +55,14 @@ export interface ApiApplications {
55
55
  clearMaintenance?(command: ApiClearMaintenanceRequest): Promise<ApiCommandResult>;
56
56
  };
57
57
  readonly triggers?: {
58
- list(): Promise<ApiResourceResult<readonly TriggerResponse[]>>;
58
+ list(): Promise<ApiResourceResult<readonly TriggerResponse[]> & {
59
+ readonly orphanedInstructions?: readonly OrphanedInstructionsResponse[];
60
+ }>;
59
61
  detail(id: string): Promise<ApiResourceResult<TriggerResponse> | undefined>;
62
+ saveInstructions?(id: string, command: ApiCommandRequest & {
63
+ readonly content: string;
64
+ readonly expectedRevisionId: string | null;
65
+ }): Promise<ApiCommandResult>;
60
66
  pause(id: string, command: ApiCommandRequest): Promise<ApiCommandResult>;
61
67
  resume(id: string, command: ApiCommandRequest): Promise<ApiCommandResult>;
62
68
  };
@@ -13,19 +13,15 @@ export async function dispatchCommand(applications, url, body) {
13
13
  const maintenance = await dispatchMaintenanceClear(applications, url.pathname, body);
14
14
  if (maintenance !== undefined)
15
15
  return maintenance;
16
+ const instructions = await dispatchInstructions(applications, url.pathname, body);
17
+ if (instructions !== undefined)
18
+ return instructions;
16
19
  const request = commandRequest(body);
17
20
  if (isHttpResponse(request))
18
21
  return request;
19
- const trigger = /^\/api\/v1\/triggers\/([^/]+)\/commands\/(pause|resume)$/.exec(url.pathname);
20
- if (trigger !== null) {
21
- const id = decodePathSegment(trigger[1]);
22
- if (id instanceof ApiPathError)
23
- return invalidPath(id.message);
24
- if (applications.triggers === undefined)
25
- return unavailable('triggers');
26
- const operation = trigger[2] === 'pause' ? applications.triggers.pause : applications.triggers.resume;
27
- return accepted(await operation(id, request), applications.now(), 200);
28
- }
22
+ const trigger = await dispatchTriggerCommand(applications, url.pathname, request);
23
+ if (trigger !== undefined)
24
+ return trigger;
29
25
  const control = await dispatchControlCommand(applications, url.pathname, request);
30
26
  if (control !== undefined)
31
27
  return control;
@@ -76,7 +72,7 @@ async function dispatchWorkCommand(applications, pathname, body) {
76
72
  function conversationMessageRequest(body) {
77
73
  if (!isObject(body))
78
74
  return invalidRequest('', 'A JSON object is required');
79
- if (Object.keys(body).some((key) => key !== 'idempotencyKey' && key !== 'body'))
75
+ if (Object.keys(body).some((key) => key !== 'idempotencyKey' && key !== 'body' && key !== 'continuation'))
80
76
  return invalidRequest('', 'The command body contains unknown fields');
81
77
  const command = commandRequest({ idempotencyKey: body.idempotencyKey });
82
78
  if (isHttpResponse(command))
@@ -85,7 +81,13 @@ function conversationMessageRequest(body) {
85
81
  return invalidRequest('body', 'Must be a non-empty string');
86
82
  if (body.body.length > 20_000)
87
83
  return invalidRequest('body', 'Must be at most 20000 characters');
88
- return { ...command, body: body.body };
84
+ if (body.continuation !== undefined && typeof body.continuation !== 'boolean')
85
+ return invalidRequest('continuation', 'Must be a boolean');
86
+ return {
87
+ ...command,
88
+ body: body.body,
89
+ ...(body.continuation === undefined ? {} : { continuation: body.continuation }),
90
+ };
89
91
  }
90
92
  async function dispatchControlCommand(applications, pathname, request) {
91
93
  const name = controlCommandName(pathname);
@@ -205,3 +207,44 @@ function isHttpResponse(value) {
205
207
  'status' in value &&
206
208
  typeof value.status === 'number');
207
209
  }
210
+ async function dispatchInstructions(applications, pathname, body) {
211
+ const instructions = /^\/api\/v1\/triggers\/([^/]+)\/commands\/instructions$/.exec(pathname);
212
+ if (instructions !== null) {
213
+ const id = decodePathSegment(instructions[1]);
214
+ if (id instanceof ApiPathError)
215
+ return invalidPath(id.message);
216
+ if (!isObject(body) ||
217
+ Object.keys(body).some((key) => !['idempotencyKey', 'content', 'expectedRevisionId'].includes(key)))
218
+ return invalidRequest('', 'Expected idempotencyKey, content and expectedRevisionId');
219
+ const request = commandRequest({ idempotencyKey: body.idempotencyKey });
220
+ if (isHttpResponse(request))
221
+ return request;
222
+ if (typeof body.content !== 'string')
223
+ return invalidRequest('content', 'Must be a string');
224
+ if (body.expectedRevisionId !== null &&
225
+ (typeof body.expectedRevisionId !== 'string' || body.expectedRevisionId.length === 0))
226
+ return invalidRequest('expectedRevisionId', 'Must be a revision ID or null');
227
+ const save = applications.triggers?.saveInstructions;
228
+ if (save === undefined)
229
+ return unavailable('operator-instructions');
230
+ return accepted(await save(id, {
231
+ ...request,
232
+ content: body.content,
233
+ expectedRevisionId: body.expectedRevisionId,
234
+ }), applications.now(), 200);
235
+ }
236
+ return undefined;
237
+ }
238
+ async function dispatchTriggerCommand(applications, pathname, request) {
239
+ const trigger = /^\/api\/v1\/triggers\/([^/]+)\/commands\/(pause|resume)$/.exec(pathname);
240
+ if (trigger !== null) {
241
+ const id = decodePathSegment(trigger[1]);
242
+ if (id instanceof ApiPathError)
243
+ return invalidPath(id.message);
244
+ if (applications.triggers === undefined)
245
+ return unavailable('triggers');
246
+ const operation = trigger[2] === 'pause' ? applications.triggers.pause : applications.triggers.resume;
247
+ return accepted(await operation(id, request), applications.now(), 200);
248
+ }
249
+ return undefined;
250
+ }