The best way to control Claude Code, Codex and more from any computer or phone

main
ts 538 lines 17.2 KB
Raw
1 import type { Input } from "alchemy/Input";
2 import * as Output from "alchemy/Output";
3 import { toSeconds as toWholeSeconds } from "alchemy/Util/Duration";
4 /**
5 * The Step Functions program compiler: `SfnEffect` AST → a plain JSONata-mode
6 * ASL `definition` object (with embedded `Output`s the engine resolves) plus
7 * the IAM `policyStatements` its Task states require.
8 *
9 * The output is deliberately deterministic — state names and variable names
10 * are per-compile ordinals, no timestamps — so `StateMachine`'s
11 * `normalizeDefinition` drift comparison stays quiet across deploys of an
12 * unchanged program.
13 */
14 import * as Data from "effect/Data";
15 import type * as Duration from "effect/Duration";
16 import type { PolicyStatement } from "../../IAM/Policy.ts";
17 import {
18 inputExpr,
19 isExpr,
20 nodeOf,
21 renderExprString,
22 renderNode,
23 variableExpr,
24 } from "./Jsonata.ts";
25 import type { AslNode, RetryOptions } from "./Node.ts";
26 import { isSfnEffect, type SfnEffect } from "./Program.ts";
27
28 /**
29 * A program failed to compile to ASL — e.g. yielding a non-`Sfn` value
30 * inside `Sfn.gen`, or unreachable steps after an unconditional `Sfn.fail`.
31 */
32 export class SfnCompileError extends Data.TaggedError("SfnCompileError")<{
33 readonly message: string;
34 }> {}
35
36 /** The result of {@link compileProgram}. */
37 export interface CompiledProgram {
38 /**
39 * The ASL definition (JSONata query language). A plain object with
40 * embedded `Output`s — exactly what `StateMachineProps.definition`
41 * accepts.
42 */
43 readonly definition: Record<string, unknown>;
44 /**
45 * IAM policy statements collected from `Sfn.invoke` / `Sfn.integrate`
46 * task states, for the state machine's execution role.
47 */
48 readonly policyStatements: Input<PolicyStatement>[];
49 }
50
51 interface Ctx {
52 readonly nameCounters: Record<string, number>;
53 varCounter: number;
54 readonly policyStatements: Input<PolicyStatement>[];
55 readonly invokedFunctions: Set<string>;
56 }
57
58 type State = Record<string, any>;
59
60 /**
61 * A partially-built subgraph: its entry state, its states, and the names of
62 * states whose `Next`/`End` is still open (patched when the fragment is
63 * chained to a successor or sealed).
64 */
65 interface Fragment {
66 readonly startAt: string;
67 readonly states: Record<string, State>;
68 readonly terminals: readonly string[];
69 }
70
71 const allocName = (ctx: Ctx, prefix: string): string => {
72 const n = ctx.nameCounters[prefix] ?? 0;
73 ctx.nameCounters[prefix] = n + 1;
74 return `${prefix}${n}`;
75 };
76
77 const allocVar = (ctx: Ctx): string => `v${ctx.varCounter++}`;
78
79 /** Chain `next` after `self`, patching `self`'s open terminals. */
80 const chain = (self: Fragment, next: Fragment): Fragment => {
81 const states = { ...self.states, ...next.states };
82 for (const terminal of self.terminals) {
83 states[terminal] = { ...states[terminal], Next: next.startAt };
84 }
85 return { startAt: self.startAt, states, terminals: next.terminals };
86 };
87
88 /** Seal a fragment into a `{ StartAt, States }` machine (`End: true`). */
89 const seal = (fragment: Fragment): { StartAt: string; States: Record<string, State> } => {
90 const states = { ...fragment.states };
91 for (const terminal of fragment.terminals) {
92 states[terminal] = { ...states[terminal], End: true };
93 }
94 return { StartAt: fragment.startAt, States: states };
95 };
96
97 /**
98 * Render a payload/assign value: `Expr` references become `{% ... %}`
99 * JSONata strings, embedded `Output`s pass through untouched (the engine
100 * resolves them before serialization), containers recurse, `undefined`
101 * becomes `null`.
102 */
103 const renderValue = (value: unknown): unknown => {
104 if (value === undefined) return null;
105 if (isExpr(value)) return renderExprString(value);
106 if (Output.isOutput(value)) return value;
107 if (Array.isArray(value)) return value.map(renderValue);
108 if (typeof value === "object" && value !== null) {
109 return Object.fromEntries(
110 Object.entries(value).map(([key, entry]) => [key, renderValue(entry)]),
111 );
112 }
113 return value;
114 };
115
116 /**
117 * Convert a `Duration.Input` to ASL whole seconds (normalizing any
118 * persisted-state `Duration` JSON via the central util). ASL second fields
119 * (`TimeoutSeconds`, `IntervalSeconds`, `Seconds`) must be positive
120 * integers, so sub-second durations round up to 1.
121 */
122 export const aslSeconds = (input: Duration.Input): number => Math.max(1, toWholeSeconds(input)!);
123
124 const retryPolicy = (options: RetryOptions): Record<string, unknown> => ({
125 ErrorEquals:
126 options.while === undefined
127 ? ["States.ALL"]
128 : typeof options.while === "string"
129 ? [options.while]
130 : [...options.while],
131 IntervalSeconds: aslSeconds(options.initial ?? "1 second"),
132 BackoffRate: options.backoff ?? 2,
133 MaxAttempts: options.maxAttempts ?? 3,
134 ...(options.maxDelay !== undefined ? { MaxDelaySeconds: aslSeconds(options.maxDelay) } : {}),
135 ...(options.jitter ? { JitterStrategy: "FULL" } : {}),
136 });
137
138 /**
139 * Does this node compile to exactly one catchable/retryable state
140 * (`Task`/`Parallel`/`Map`)? When true, `retry`/`catch` attach their
141 * `Retry`/`Catch` directly instead of wrapping in a single-branch
142 * `Parallel`.
143 */
144 const isSingleCatchableState = (node: AslNode): boolean =>
145 node.kind === "invoke" ||
146 node.kind === "integrate" ||
147 node.kind === "all" ||
148 node.kind === "forEach" ||
149 (node.kind === "retry" && isSingleCatchableState(node.inner.node));
150
151 export const compileNode = (ctx: Ctx, node: AslNode, v: string): Fragment => {
152 switch (node.kind) {
153 case "invoke": {
154 const name = allocName(ctx, "Invoke");
155 if (!ctx.invokedFunctions.has(node.fn.LogicalId)) {
156 ctx.invokedFunctions.add(node.fn.LogicalId);
157 ctx.policyStatements.push({
158 Effect: "Allow",
159 Action: ["lambda:InvokeFunction"],
160 Resource: [
161 node.fn.functionArn,
162 // cover qualified invocations (versions/aliases)
163 Output.interpolate`${node.fn.functionArn}:*`,
164 ],
165 } as Input<PolicyStatement>);
166 }
167 return {
168 startAt: name,
169 states: {
170 [name]: {
171 Type: "Task",
172 Resource: "arn:aws:states:::lambda:invoke",
173 Arguments: {
174 FunctionName: node.fn.functionArn,
175 Payload: renderValue(node.payload),
176 },
177 Assign: { [v]: "{% $states.result.Payload %}" },
178 },
179 },
180 terminals: [name],
181 };
182 }
183
184 case "integrate": {
185 const name = allocName(ctx, "Task");
186 ctx.policyStatements.push(
187 ...((node.options.policyStatements ?? []) as Input<PolicyStatement>[]),
188 );
189 return {
190 startAt: name,
191 states: {
192 [name]: {
193 Type: "Task",
194 Resource: node.waitForTaskToken
195 ? `${node.options.resource}.waitForTaskToken`
196 : node.options.resource,
197 ...(node.options.arguments !== undefined
198 ? { Arguments: renderValue(node.options.arguments) }
199 : {}),
200 ...(node.options.timeout !== undefined
201 ? { TimeoutSeconds: aslSeconds(node.options.timeout) }
202 : {}),
203 Assign: { [v]: "{% $states.result %}" },
204 },
205 },
206 terminals: [name],
207 };
208 }
209
210 case "all": {
211 const name = allocName(ctx, "Parallel");
212 return {
213 startAt: name,
214 states: {
215 [name]: {
216 Type: "Parallel",
217 Branches: node.branches.map((branch) => compileBranch(ctx, branch)),
218 Assign: { [v]: "{% $states.result %}" },
219 },
220 },
221 terminals: [name],
222 };
223 }
224
225 case "forEach": {
226 const name = allocName(ctx, "Map");
227 // the item arrives as the ItemProcessor's state input — bind it to a
228 // variable in a prologue Pass so the body can reference it anywhere
229 // ($states.context.Map.Item.Value only exists inside ItemSelector)
230 const itemVar = allocVar(ctx);
231 const body = node.body(variableExpr(itemVar));
232 if (!isSfnEffect(body)) {
233 throw new SfnCompileError({
234 message: "Sfn.forEach body must return an Sfn effect",
235 });
236 }
237 const itemName = allocName(ctx, "Item");
238 const intro: Fragment = {
239 startAt: itemName,
240 states: {
241 [itemName]: {
242 Type: "Pass",
243 Assign: { [itemVar]: "{% $states.input %}" },
244 },
245 },
246 terminals: [itemName],
247 };
248 return {
249 startAt: name,
250 states: {
251 [name]: {
252 Type: "Map",
253 Items: renderExprString(node.items),
254 ...(node.options.concurrency !== undefined
255 ? { MaxConcurrency: node.options.concurrency }
256 : {}),
257 ItemProcessor: {
258 ProcessorConfig: { Mode: "INLINE" },
259 ...compileBranch(ctx, body, intro),
260 },
261 Assign: { [v]: "{% $states.result %}" },
262 },
263 },
264 terminals: [name],
265 };
266 }
267
268 case "sleep": {
269 const name = allocName(ctx, "Wait");
270 return {
271 startAt: name,
272 states: {
273 [name]: {
274 Type: "Wait",
275 Seconds: node.seconds,
276 Assign: { [v]: null },
277 },
278 },
279 terminals: [name],
280 };
281 }
282
283 case "when": {
284 const name = allocName(ctx, "Choice");
285 const onTrue = compileNode(ctx, node.onTrue.node, v);
286 const onFalse = compileNode(ctx, node.onFalse?.node ?? { kind: "succeed", value: null }, v);
287 return {
288 startAt: name,
289 states: {
290 [name]: {
291 Type: "Choice",
292 Choices: [
293 {
294 Condition: renderExprString(node.condition),
295 Next: onTrue.startAt,
296 },
297 ],
298 Default: onFalse.startAt,
299 },
300 ...onTrue.states,
301 ...onFalse.states,
302 },
303 terminals: [...onTrue.terminals, ...onFalse.terminals],
304 };
305 }
306
307 case "match": {
308 const name = allocName(ctx, "Choice");
309 const states: Record<string, State> = {};
310 const terminals: string[] = [];
311 const rules: Record<string, unknown>[] = [];
312 const value = renderNode(nodeOf(node.value));
313 for (const [caseValue, program] of Object.entries(node.cases)) {
314 const fragment = compileNode(ctx, program.node, v);
315 Object.assign(states, fragment.states);
316 terminals.push(...fragment.terminals);
317 rules.push({
318 // string-coerced comparison so numeric/boolean case keys behave
319 Condition: `{% ($string(${value}) = ${JSON.stringify(caseValue)}) %}`,
320 Next: fragment.startAt,
321 });
322 }
323 let defaultTarget: string | undefined;
324 if (node.otherwise !== undefined) {
325 const fragment = compileNode(ctx, node.otherwise.node, v);
326 Object.assign(states, fragment.states);
327 terminals.push(...fragment.terminals);
328 defaultTarget = fragment.startAt;
329 }
330 return {
331 startAt: name,
332 states: {
333 [name]: {
334 Type: "Choice",
335 Choices: rules,
336 ...(defaultTarget !== undefined ? { Default: defaultTarget } : {}),
337 },
338 ...states,
339 },
340 terminals,
341 };
342 }
343
344 case "succeed": {
345 const name = allocName(ctx, "Pass");
346 return {
347 startAt: name,
348 states: {
349 [name]: { Type: "Pass", Assign: { [v]: renderValue(node.value) } },
350 },
351 terminals: [name],
352 };
353 }
354
355 case "fail": {
356 const name = allocName(ctx, "Fail");
357 return {
358 startAt: name,
359 states: {
360 [name]: { Type: "Fail", Error: node.error, Cause: node.cause },
361 },
362 terminals: [],
363 };
364 }
365
366 case "retry": {
367 if (isSingleCatchableState(node.inner.node)) {
368 const fragment = compileNode(ctx, node.inner.node, v);
369 const state = fragment.states[fragment.startAt];
370 state.Retry = [...(state.Retry ?? []), retryPolicy(node.options)];
371 return fragment;
372 }
373 // multi-state program: wrap in a single-branch Parallel so the whole
374 // program re-runs on retry (Effect.retry semantics)
375 const name = allocName(ctx, "Try");
376 return {
377 startAt: name,
378 states: {
379 [name]: {
380 Type: "Parallel",
381 Branches: [compileBranch(ctx, node.inner)],
382 Retry: [retryPolicy(node.options)],
383 Assign: { [v]: "{% $states.result[0] %}" },
384 },
385 },
386 terminals: [name],
387 };
388 }
389
390 case "catch": {
391 const errorVar = allocVar(ctx);
392 let guarded: Fragment;
393 if (isSingleCatchableState(node.inner.node)) {
394 guarded = compileNode(ctx, node.inner.node, v);
395 } else {
396 const name = allocName(ctx, "Try");
397 guarded = {
398 startAt: name,
399 states: {
400 [name]: {
401 Type: "Parallel",
402 Branches: [compileBranch(ctx, node.inner)],
403 Assign: { [v]: "{% $states.result[0] %}" },
404 },
405 },
406 terminals: [name],
407 };
408 }
409 const handlerProgram = node.handler(variableExpr(errorVar));
410 if (!isSfnEffect(handlerProgram)) {
411 throw new SfnCompileError({
412 message: "Sfn.catchTag/catchAll handler must return an Sfn effect",
413 });
414 }
415 const handler = compileNode(ctx, handlerProgram.node, v);
416 const target = guarded.states[guarded.startAt];
417 target.Catch = [
418 ...(target.Catch ?? []),
419 {
420 ErrorEquals: [...node.tags],
421 Assign: { [errorVar]: "{% $states.errorOutput %}" },
422 Next: handler.startAt,
423 },
424 ];
425 return {
426 startAt: guarded.startAt,
427 states: { ...guarded.states, ...handler.states },
428 terminals: [...guarded.terminals, ...handler.terminals],
429 };
430 }
431
432 case "gen": {
433 const iterator = node.body(inputExpr());
434 const fragments: Fragment[] = [];
435 let step = iterator.next();
436 while (!step.done) {
437 const program: unknown = step.value;
438 if (!isSfnEffect(program)) {
439 throw new SfnCompileError({
440 message:
441 "Sfn.gen may only yield Sfn effects (Sfn.invoke, Sfn.when, ...) — real Effects cannot compile to ASL",
442 });
443 }
444 const stepVar = allocVar(ctx);
445 fragments.push(compileNode(ctx, program.node, stepVar));
446 step = iterator.next(variableExpr(stepVar));
447 }
448 const diverged =
449 fragments.length > 0 && fragments[fragments.length - 1].terminals.length === 0;
450 if (!diverged) {
451 // final Pass assigning the generator's return value
452 const name = allocName(ctx, "Pass");
453 fragments.push({
454 startAt: name,
455 states: {
456 [name]: { Type: "Pass", Assign: { [v]: renderValue(step.value) } },
457 },
458 terminals: [name],
459 });
460 }
461 return fragments.reduce((chained, fragment) => {
462 if (chained.terminals.length === 0) {
463 throw new SfnCompileError({
464 message:
465 "unreachable steps after an unconditional Sfn.fail — move the failure into a branch or make it the final step",
466 });
467 }
468 return chain(chained, fragment);
469 });
470 }
471 }
472 };
473
474 /**
475 * Compile a program into a sealed `{ StartAt, States }` branch machine
476 * (Parallel branch / Map ItemProcessor). The branch's own result variable is
477 * exposed as the branch output via a terminal Pass state.
478 */
479 const compileBranch = (
480 ctx: Ctx,
481 program: SfnEffect<any, any>,
482 intro?: Fragment,
483 ): { StartAt: string; States: Record<string, State> } => {
484 const branchVar = allocVar(ctx);
485 let fragment = compileNode(ctx, program.node, branchVar);
486 if (intro !== undefined) fragment = chain(intro, fragment);
487 if (fragment.terminals.length === 0) {
488 // the branch always fails — no output state needed
489 return seal(fragment);
490 }
491 const name = allocName(ctx, "Result");
492 return seal(
493 chain(fragment, {
494 startAt: name,
495 states: { [name]: { Type: "Pass", Output: `{% $${branchVar} %}` } },
496 terminals: [name],
497 }),
498 );
499 };
500
501 /**
502 * Compile a typed Step Functions program to a plain ASL definition object
503 * (JSONata query language, embedded `Output`s intact) plus the IAM policy
504 * statements its task states require. Pure and deterministic; throws
505 * {@link SfnCompileError} on structurally invalid programs.
506 *
507 * This is sugar over the raw path: feed the result straight into the
508 * existing `StateMachine` resource (`StateMachine.fromProgram` does exactly
509 * that), or inspect/extend the definition first — the raw
510 * `definition: Record<string, unknown>` escape hatch stays first-class.
511 */
512 export const compileProgram = (program: SfnEffect<any, any>): CompiledProgram => {
513 const ctx: Ctx = {
514 nameCounters: {},
515 varCounter: 0,
516 policyStatements: [],
517 invokedFunctions: new Set(),
518 };
519 const v = allocVar(ctx);
520 const fragment = compileNode(ctx, program.node, v);
521 const full =
522 fragment.terminals.length === 0
523 ? fragment
524 : chain(fragment, {
525 startAt: "Return",
526 states: { Return: { Type: "Pass", Output: `{% $${v} %}` } },
527 terminals: ["Return"],
528 });
529 const machine = seal(full);
530 return {
531 definition: {
532 QueryLanguage: "JSONata",
533 StartAt: machine.StartAt,
534 States: machine.States,
535 },
536 policyStatements: ctx.policyStatements,
537 };
538 };