@scarn/sdk 0.8.1 → 0.8.3

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 (66) hide show
  1. package/dist/automations/define-automation.d.ts +20 -0
  2. package/dist/automations/index.d.ts +8 -0
  3. package/dist/automations/index.js +21 -0
  4. package/dist/automations/targets.d.ts +36 -0
  5. package/dist/automations/types.d.ts +116 -0
  6. package/dist/{chunk-dp86pa6m.js → chunk-01nfqm18.js} +5 -1
  7. package/dist/chunk-0vzq22dj.js +73 -0
  8. package/dist/chunk-11hbmexe.js +250 -0
  9. package/dist/{chunk-700xe701.js → chunk-3gy0cb5f.js} +5 -1
  10. package/dist/{chunk-102vfpw4.js → chunk-43y7tfn4.js} +33 -414
  11. package/dist/chunk-61jf8b6s.js +53 -0
  12. package/dist/chunk-76d1bwwz.js +119 -0
  13. package/dist/chunk-8z1wa3kd.js +109 -0
  14. package/dist/{chunk-p7yrcmqm.js → chunk-cnxaagfj.js} +2 -52
  15. package/dist/{chunk-cdanncng.js → chunk-ejzfdm1z.js} +21 -5
  16. package/dist/{chunk-gds7w7zh.js → chunk-fgfhvsee.js} +1 -4
  17. package/dist/{chunk-3ctaaseb.js → chunk-fyfvp6jx.js} +48 -21
  18. package/dist/{chunk-mz53r914.js → chunk-jj9pezwb.js} +22 -119
  19. package/dist/{chunk-vfeytkqx.js → chunk-wnfj3wyx.js} +106 -33
  20. package/dist/chunk-x0hjhqrf.js +416 -0
  21. package/dist/chunk-y11p1q7r.js +159 -0
  22. package/dist/client.js +6 -4
  23. package/dist/contracts/automation-document/index.d.ts +5 -0
  24. package/dist/contracts/automation-document/index.js +34 -0
  25. package/dist/contracts/automation-document/schema.d.ts +363 -0
  26. package/dist/contracts/pipeline-document/built-ins.d.ts +1 -1
  27. package/dist/contracts/pipeline-document/index.js +9 -7
  28. package/dist/contracts/pipeline-document/schema.d.ts +3 -3
  29. package/dist/contracts/work-item-changes.d.ts +51 -0
  30. package/dist/contracts/work-item-changes.js +68 -0
  31. package/dist/defaults/index.js +2 -2
  32. package/dist/definitions/automations/automations-client.d.ts +178 -0
  33. package/dist/definitions/automations/index.d.ts +1 -0
  34. package/dist/definitions/automations/index.js +12 -0
  35. package/dist/definitions/pipelines/index.d.ts +0 -1
  36. package/dist/definitions/pipelines/index.js +4 -12
  37. package/dist/definitions/pipelines/work-item-fields.d.ts +11 -22
  38. package/dist/definitions/steps/define-code-step.d.ts +3 -1
  39. package/dist/definitions/steps/define-step.d.ts +29 -1
  40. package/dist/definitions/steps/index.js +12 -7
  41. package/dist/definitions/steps/repo.d.ts +11 -3
  42. package/dist/definitions/steps/runtime.d.ts +11 -12
  43. package/dist/definitions/steps/step-definitions-client.d.ts +18 -0
  44. package/dist/definitions/steps/step-features.d.ts +2 -2
  45. package/dist/definitions/steps/step-handle.d.ts +8 -1
  46. package/dist/definitions/validation/index.js +2 -2
  47. package/dist/generated/index.d.ts +2 -2
  48. package/dist/generated/sdk.gen.d.ts +66 -11
  49. package/dist/generated/types.gen.d.ts +5513 -3488
  50. package/dist/index.d.ts +1 -0
  51. package/dist/index.js +61 -49
  52. package/dist/pipelines/define-pipeline.d.ts +7 -7
  53. package/dist/pipelines/handles.d.ts +0 -5
  54. package/dist/pipelines/index.js +7 -4
  55. package/dist/pipelines/types.d.ts +13 -1
  56. package/dist/push/collect-definitions.d.ts +3 -8
  57. package/dist/push/collect-pipeline-documents.d.ts +13 -3
  58. package/dist/push/index.d.ts +2 -2
  59. package/dist/push/index.js +90 -127
  60. package/dist/push/push-from-directory.d.ts +10 -6
  61. package/dist/repo-config.d.ts +14 -4
  62. package/dist/repo-config.js +5 -1
  63. package/dist/task-plane-client.d.ts +42 -0
  64. package/package.json +17 -1
  65. package/dist/chunk-zm72ksz0.js +0 -256
  66. package/dist/definitions/pipelines/define-default-pipeline-assignment.d.ts +0 -263
@@ -311,9 +311,9 @@ export declare const waitNodeSchema: z.ZodObject<{
311
311
  kind: z.ZodLiteral<"wait">;
312
312
  title: z.ZodOptional<z.ZodString>;
313
313
  for: z.ZodEnum<{
314
- event: "event";
315
314
  decision: "decision";
316
315
  reply: "reply";
316
+ event: "event";
317
317
  timer: "timer";
318
318
  }>;
319
319
  actions: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -478,9 +478,9 @@ export declare const nodeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
478
478
  kind: z.ZodLiteral<"wait">;
479
479
  title: z.ZodOptional<z.ZodString>;
480
480
  for: z.ZodEnum<{
481
- event: "event";
482
481
  decision: "decision";
483
482
  reply: "reply";
483
+ event: "event";
484
484
  timer: "timer";
485
485
  }>;
486
486
  actions: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -671,9 +671,9 @@ export declare const pipelineDocumentSchema: z.ZodObject<{
671
671
  kind: z.ZodLiteral<"wait">;
672
672
  title: z.ZodOptional<z.ZodString>;
673
673
  for: z.ZodEnum<{
674
- event: "event";
675
674
  decision: "decision";
676
675
  reply: "reply";
676
+ event: "event";
677
677
  timer: "timer";
678
678
  }>;
679
679
  actions: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -0,0 +1,51 @@
1
+ export declare const WORK_ITEM_CHANGES_RELATIVE_PATH = ".scarn/work-item-changes.json";
2
+ /** At most this many items created in one run; the server checks it too. */
3
+ export declare const MAX_WORK_ITEMS_CREATED_PER_RUN = 10;
4
+ export declare const WORK_ITEM_CLOSE_REASONS: readonly ["completed", "out_of_scope", "superseded"];
5
+ export type WorkItemCloseReason = (typeof WORK_ITEM_CLOSE_REASONS)[number];
6
+ export type WorkItemChange = {
7
+ kind: "create";
8
+ workItemId: string;
9
+ title: string;
10
+ description: string;
11
+ fields?: Record<string, unknown>;
12
+ labels?: string[];
13
+ blockedBy?: string[];
14
+ } | {
15
+ kind: "label";
16
+ workItemId: string;
17
+ add?: string[];
18
+ remove?: string[];
19
+ } | {
20
+ kind: "block";
21
+ blockedWorkItemId: string;
22
+ blockingWorkItemId: string;
23
+ remove?: boolean;
24
+ } | {
25
+ kind: "describe";
26
+ workItemId: string;
27
+ description: string;
28
+ descriptionVersion: number;
29
+ } | {
30
+ kind: "comment";
31
+ workItemId: string;
32
+ body: string;
33
+ } | {
34
+ kind: "close";
35
+ workItemId: string;
36
+ reason: WorkItemCloseReason;
37
+ resolution?: string | null;
38
+ } | {
39
+ kind: "startTask";
40
+ workItemId: string;
41
+ stepKey: string;
42
+ };
43
+ export declare function buildWorkItemChangesPath(workspacePath: string): string;
44
+ /** The changes recorded so far; a missing file means none. */
45
+ export declare function readWorkItemChanges(workspacePath: string): Promise<WorkItemChange[]>;
46
+ export declare function appendWorkItemChange(workspacePath: string, change: WorkItemChange): Promise<WorkItemChange[]>;
47
+ /**
48
+ * Deletes the file. Called when a run's workspace is set up, so changes
49
+ * committed on an earlier step's branch are never sent again.
50
+ */
51
+ export declare function removeWorkItemChanges(workspacePath: string): Promise<void>;
@@ -0,0 +1,68 @@
1
+ // @bun
2
+ import {
3
+ exports_external
4
+ } from "../chunk-skzxcba3.js";
5
+ import"../chunk-y64skrwp.js";
6
+
7
+ // src/contracts/work-item-changes.ts
8
+ import { mkdir, readFile, rm, writeFile } from "fs/promises";
9
+ import path from "path";
10
+ var WORK_ITEM_CHANGES_RELATIVE_PATH = ".scarn/work-item-changes.json";
11
+ var MAX_WORK_ITEMS_CREATED_PER_RUN = 10;
12
+ var WORK_ITEM_CLOSE_REASONS = [
13
+ "completed",
14
+ "out_of_scope",
15
+ "superseded"
16
+ ];
17
+ var workItemChangesFileSchema = exports_external.object({
18
+ changes: exports_external.array(exports_external.looseObject({
19
+ kind: exports_external.enum([
20
+ "create",
21
+ "label",
22
+ "block",
23
+ "describe",
24
+ "comment",
25
+ "close",
26
+ "startTask"
27
+ ])
28
+ }))
29
+ });
30
+ function buildWorkItemChangesPath(workspacePath) {
31
+ return path.join(workspacePath, WORK_ITEM_CHANGES_RELATIVE_PATH);
32
+ }
33
+ async function readWorkItemChanges(workspacePath) {
34
+ let raw;
35
+ try {
36
+ raw = await readFile(buildWorkItemChangesPath(workspacePath), "utf8");
37
+ } catch (error) {
38
+ if (error.code === "ENOENT") {
39
+ return [];
40
+ }
41
+ throw error;
42
+ }
43
+ const parsed = workItemChangesFileSchema.safeParse(JSON.parse(raw));
44
+ if (!parsed.success) {
45
+ throw new Error(`${WORK_ITEM_CHANGES_RELATIVE_PATH} is malformed: ${parsed.error.message}`);
46
+ }
47
+ return parsed.data.changes;
48
+ }
49
+ async function appendWorkItemChange(workspacePath, change) {
50
+ const changes = [...await readWorkItemChanges(workspacePath), change];
51
+ const filePath = buildWorkItemChangesPath(workspacePath);
52
+ await mkdir(path.dirname(filePath), { recursive: true });
53
+ await writeFile(filePath, `${JSON.stringify({ changes }, null, 2)}
54
+ `, "utf8");
55
+ return changes;
56
+ }
57
+ async function removeWorkItemChanges(workspacePath) {
58
+ await rm(buildWorkItemChangesPath(workspacePath), { force: true });
59
+ }
60
+ export {
61
+ MAX_WORK_ITEMS_CREATED_PER_RUN,
62
+ WORK_ITEM_CHANGES_RELATIVE_PATH,
63
+ WORK_ITEM_CLOSE_REASONS,
64
+ appendWorkItemChange,
65
+ buildWorkItemChangesPath,
66
+ readWorkItemChanges,
67
+ removeWorkItemChanges
68
+ };
@@ -4,8 +4,8 @@ import {
4
4
  } from "../chunk-rt9tq4j6.js";
5
5
  import {
6
6
  createScarnClient
7
- } from "../chunk-700xe701.js";
8
- import"../chunk-vfeytkqx.js";
7
+ } from "../chunk-3gy0cb5f.js";
8
+ import"../chunk-wnfj3wyx.js";
9
9
  import"../chunk-y64skrwp.js";
10
10
 
11
11
  // src/defaults/auth-file.ts
@@ -0,0 +1,178 @@
1
+ import { z } from "zod";
2
+ import { Automations } from "../../generated/sdk.gen";
3
+ import type { PutApiProjectsByProjectIdAutomationsByKeyResponses } from "../../generated/types.gen";
4
+ type RequestOptions = {
5
+ headers?: Record<string, unknown> | undefined;
6
+ };
7
+ export type PublishAutomationResult = PutApiProjectsByProjectIdAutomationsByKeyResponses[200];
8
+ export type Automation = PublishAutomationResult["automation"];
9
+ declare const automationDocumentIssueSchema: z.ZodObject<{
10
+ code: z.ZodString;
11
+ path: z.ZodString;
12
+ message: z.ZodString;
13
+ hint: z.ZodOptional<z.ZodString>;
14
+ }, z.core.$strip>;
15
+ /** One validation error the server reports for a rejected automation document. */
16
+ export type AutomationDocumentIssue = z.infer<typeof automationDocumentIssueSchema>;
17
+ type ApiError = {
18
+ title?: string;
19
+ detail?: string;
20
+ code?: string;
21
+ meta?: {
22
+ [key: string]: unknown;
23
+ };
24
+ };
25
+ /**
26
+ * Thrown when the API rejects a request. `issues` carries the per-path
27
+ * validation errors of an `AUTOMATION_DOCUMENT_INVALID` rejection.
28
+ */
29
+ export declare class AutomationsApiError extends Error {
30
+ readonly code: string | undefined;
31
+ readonly issues: readonly AutomationDocumentIssue[];
32
+ constructor(error: ApiError);
33
+ }
34
+ export declare function createAutomationsClient(baseUrl: string): ReturnType<typeof buildAutomationsClient>;
35
+ declare const buildAutomationsClient: (automations: Automations) => {
36
+ listByProjectId: (projectId: string, options?: RequestOptions) => Promise<{
37
+ id: string;
38
+ projectId: string;
39
+ key: string;
40
+ title: string | unknown;
41
+ scope: "workItem" | "project";
42
+ enabled: boolean;
43
+ latestVersion: {
44
+ id: string;
45
+ version: number;
46
+ schemaVersion: number;
47
+ contentHash: string;
48
+ document: {
49
+ [key: string]: unknown;
50
+ };
51
+ publishedAt: string;
52
+ } | unknown;
53
+ createdAt: string;
54
+ updatedAt: string;
55
+ }[]>;
56
+ /**
57
+ * Publishes `document` as the automation's next version, creating the
58
+ * automation (disabled) when its key is new. `published` is false when it
59
+ * matched the latest version.
60
+ */
61
+ publish: (projectId: string, key: string, document: Record<string, unknown>, options?: RequestOptions) => Promise<{
62
+ published: boolean;
63
+ automation: {
64
+ id: string;
65
+ projectId: string;
66
+ key: string;
67
+ title: string | unknown;
68
+ scope: "workItem" | "project";
69
+ enabled: boolean;
70
+ latestVersion: {
71
+ id: string;
72
+ version: number;
73
+ schemaVersion: number;
74
+ contentHash: string;
75
+ document: {
76
+ [key: string]: unknown;
77
+ };
78
+ publishedAt: string;
79
+ } | unknown;
80
+ createdAt: string;
81
+ updatedAt: string;
82
+ };
83
+ }>;
84
+ enable: (projectId: string, key: string, options?: RequestOptions) => Promise<{
85
+ id: string;
86
+ projectId: string;
87
+ key: string;
88
+ title: string | unknown;
89
+ scope: "workItem" | "project";
90
+ enabled: boolean;
91
+ latestVersion: {
92
+ id: string;
93
+ version: number;
94
+ schemaVersion: number;
95
+ contentHash: string;
96
+ document: {
97
+ [key: string]: unknown;
98
+ };
99
+ publishedAt: string;
100
+ } | unknown;
101
+ createdAt: string;
102
+ updatedAt: string;
103
+ }>;
104
+ disable: (projectId: string, key: string, options?: RequestOptions) => Promise<{
105
+ id: string;
106
+ projectId: string;
107
+ key: string;
108
+ title: string | unknown;
109
+ scope: "workItem" | "project";
110
+ enabled: boolean;
111
+ latestVersion: {
112
+ id: string;
113
+ version: number;
114
+ schemaVersion: number;
115
+ contentHash: string;
116
+ document: {
117
+ [key: string]: unknown;
118
+ };
119
+ publishedAt: string;
120
+ } | unknown;
121
+ createdAt: string;
122
+ updatedAt: string;
123
+ }>;
124
+ listForWorkItem: (workItemId: string, options?: RequestOptions) => Promise<{
125
+ workItemId: string;
126
+ automation: {
127
+ id: string;
128
+ projectId: string;
129
+ key: string;
130
+ title: string | unknown;
131
+ scope: "workItem" | "project";
132
+ enabled: boolean;
133
+ latestVersion: {
134
+ id: string;
135
+ version: number;
136
+ schemaVersion: number;
137
+ contentHash: string;
138
+ document: {
139
+ [key: string]: unknown;
140
+ };
141
+ publishedAt: string;
142
+ } | unknown;
143
+ createdAt: string;
144
+ updatedAt: string;
145
+ };
146
+ attachedByUserId: string;
147
+ attachedAt: string;
148
+ }[]>;
149
+ attach: (workItemId: string, key: string, options?: RequestOptions) => Promise<{
150
+ workItemId: string;
151
+ automation: {
152
+ id: string;
153
+ projectId: string;
154
+ key: string;
155
+ title: string | unknown;
156
+ scope: "workItem" | "project";
157
+ enabled: boolean;
158
+ latestVersion: {
159
+ id: string;
160
+ version: number;
161
+ schemaVersion: number;
162
+ contentHash: string;
163
+ document: {
164
+ [key: string]: unknown;
165
+ };
166
+ publishedAt: string;
167
+ } | unknown;
168
+ createdAt: string;
169
+ updatedAt: string;
170
+ };
171
+ attachedByUserId: string;
172
+ attachedAt: string;
173
+ }>;
174
+ detach: (workItemId: string, key: string, options?: RequestOptions) => Promise<{
175
+ detached: boolean;
176
+ }>;
177
+ };
178
+ export {};
@@ -0,0 +1 @@
1
+ export * from "./automations-client";
@@ -0,0 +1,12 @@
1
+ // @bun
2
+ import {
3
+ AutomationsApiError,
4
+ createAutomationsClient
5
+ } from "../../chunk-0vzq22dj.js";
6
+ import"../../chunk-wnfj3wyx.js";
7
+ import"../../chunk-skzxcba3.js";
8
+ import"../../chunk-y64skrwp.js";
9
+ export {
10
+ AutomationsApiError,
11
+ createAutomationsClient
12
+ };
@@ -1,3 +1,2 @@
1
1
  export * from "./pipeline-definitions-client";
2
- export * from "./define-default-pipeline-assignment";
3
2
  export * from "./work-item-fields";
@@ -1,26 +1,18 @@
1
1
  // @bun
2
2
  import {
3
- DEFAULT_PIPELINE_ASSIGNMENT_FILENAME,
4
3
  PipelineDefinitionsApiError,
5
4
  WORK_ITEM_FIELDS_PATH_PREFIX,
6
5
  WORK_ITEM_TOP_LEVEL_FIELDS,
7
6
  createPipelineDefinitionsClient,
8
- defaultPipelineAssignment,
9
- isDefaultPipelineAssignmentSpec,
10
- resolveWorkItemFieldPath,
11
- serializeDefaultPipelineAssignment
12
- } from "../../chunk-zm72ksz0.js";
13
- import"../../chunk-vfeytkqx.js";
7
+ resolveWorkItemFieldPath
8
+ } from "../../chunk-8z1wa3kd.js";
9
+ import"../../chunk-wnfj3wyx.js";
14
10
  import"../../chunk-skzxcba3.js";
15
11
  import"../../chunk-y64skrwp.js";
16
12
  export {
17
- DEFAULT_PIPELINE_ASSIGNMENT_FILENAME,
18
13
  PipelineDefinitionsApiError,
19
14
  WORK_ITEM_FIELDS_PATH_PREFIX,
20
15
  WORK_ITEM_TOP_LEVEL_FIELDS,
21
16
  createPipelineDefinitionsClient,
22
- defaultPipelineAssignment,
23
- isDefaultPipelineAssignmentSpec,
24
- resolveWorkItemFieldPath,
25
- serializeDefaultPipelineAssignment
17
+ resolveWorkItemFieldPath
26
18
  };
@@ -1,17 +1,12 @@
1
1
  import type { GetApiWorkItemsByWorkItemIdResponses } from "../../generated/types.gen";
2
2
  /**
3
- * Top-level work-item properties addressable by the default-pipeline-assignment
4
- * DSL's `workItem.<field>` accessor (`define-default-pipeline-assignment.ts`)
5
- * and, reversed, its `scarn pipelines pull` file generator
6
- * (`default-pipeline-assignment-file-generator.ts`). `fields` is deliberately excluded from this
7
- * list: it's reached via `.field(name)` on every one of those accessors, not
8
- * as a top-level property.
3
+ * Top-level work-item properties a server-side resolver publishes. `fields`
4
+ * is deliberately excluded from this list: it's reached via
5
+ * `fields.<name>` paths, not as a top-level property.
9
6
  *
10
7
  * This is the single source of truth for the list — it must stay in sync
11
- * with the `workItem` fact/context shape every corresponding server-side
12
- * resolver publishes (`buildFacts` in
13
- * `evaluate-default-pipeline-assignment.ts`; `buildResolvedWorkItemContext`
14
- * in `resolve-node-input.ts`).
8
+ * with the `workItem` context shape the server-side resolver publishes
9
+ * (`buildResolvedWorkItemContext` in `resolve-node-input.ts`).
15
10
  */
16
11
  export declare const WORK_ITEM_TOP_LEVEL_FIELDS: readonly ["id", "projectId", "platform", "platformId", "platformKey", "url", "title", "description", "sourceCreatedAt", "sourceUpdatedAt", "createdByUserId", "parentWorkItemId", "createdAt", "updatedAt"];
17
12
  export type WorkItemTopLevelField = (typeof WORK_ITEM_TOP_LEVEL_FIELDS)[number];
@@ -25,9 +20,8 @@ export type WorkItemTopLevelField = (typeof WORK_ITEM_TOP_LEVEL_FIELDS)[number];
25
20
  type WorkItemPlatformLiteral = GetApiWorkItemsByWorkItemIdResponses[200]["platform"];
26
21
  /**
27
22
  * Per-field value types for every member of `WORK_ITEM_TOP_LEVEL_FIELDS`,
28
- * mirroring exactly what the server-side resolvers publish at evaluation/
29
- * resolution time (`buildFacts` for default-pipeline-assignment;
30
- * `buildResolvedWorkItemContext` for regular pipeline/step input bindings).
23
+ * mirroring exactly what the server-side resolver publishes at resolution
24
+ * time (`buildResolvedWorkItemContext` for pipeline/step input bindings).
31
25
  * Notably, `sourceCreatedAt`/`sourceUpdatedAt`/`createdAt`/`updatedAt` are
32
26
  * serialized as ISO date strings (or `null`), never `Date` objects.
33
27
  */
@@ -50,11 +44,8 @@ export type WorkItemTopLevelFieldTypeMap = {
50
44
  /**
51
45
  * The path prefix marking a reference into a work item's platform-specific
52
46
  * `fields` bag (a Jira custom field, a GitHub label, etc.), as opposed to a
53
- * `WorkItemTopLevelField`. Shared by every accessor that authors these paths
54
- * (`workItem.field(name)` in the default-pipeline-assignment DSL) and every resolver that
55
- * reads them back (`resolveWorkItemFieldPath` below; the JSONPath-rooted
56
- * variant in `evaluate-default-pipeline-assignment.ts`, which layers a `$.`
57
- * prefix on top of this same convention).
47
+ * `WorkItemTopLevelField`. Shared by every resolver that reads these paths
48
+ * (`resolveWorkItemFieldPath` below).
58
49
  */
59
50
  export declare const WORK_ITEM_FIELDS_PATH_PREFIX = "fields.";
60
51
  /**
@@ -75,10 +66,8 @@ export declare const WORK_ITEM_FIELDS_PATH_PREFIX = "fields.";
75
66
  * This resolver sidesteps that hazard entirely: everything after `fields.`
76
67
  * is treated as one atomic, unsplit key. Every work-item path resolver in
77
68
  * the codebase must use this same convention for a field name to round-trip
78
- * correctly — see `evaluate-default-pipeline-assignment.ts`'s
79
- * `resolveWorkItemAssignmentPath` (which layers `$.` path-rooting on top of
80
- * this function) and `resolve-node-input.ts`'s `work_item` binding
81
- * resolution (which calls this function directly, replacing what used to be
69
+ * correctly — see `resolve-node-input.ts`'s `work_item` binding resolution
70
+ * (which calls this function directly, replacing what used to be
82
71
  * a dot-splitting walker shared with unrelated binding sources and
83
72
  * susceptible to the exact hazard described above).
84
73
  *
@@ -1,5 +1,5 @@
1
1
  import type { ZodType } from "zod";
2
- import type { EffectiveResult, StepRetryEntry } from "./define-step";
2
+ import type { EffectiveResult, StepConcurrency, StepRetryEntry } from "./define-step";
3
3
  import type { BuiltInError } from "../../pipelines/types";
4
4
  import { type StepHandle } from "./step-handle";
5
5
  import { type CodeStepEnvironment } from "./runtime";
@@ -67,6 +67,8 @@ export type DefineCodeStepInput<TInput extends ZodType = ZodType, TResult extend
67
67
  errors?: readonly string[];
68
68
  /** As `defineStep()`'s `retry`: how a standalone Task of this step retries. */
69
69
  retry?: readonly StepRetryEntry[];
70
+ /** As `defineStep()`'s `concurrency`: the per-work-item concurrency limit. */
71
+ concurrency?: StepConcurrency;
70
72
  };
71
73
  /**
72
74
  * Defines a `kind: "code"` step: a plain function instead of an LLM
@@ -9,6 +9,7 @@ import type { EnvRecord, PromptEnvContext } from "./env";
9
9
  import { type StepEnvironment } from "./runtime";
10
10
  import type { McpHandle } from "./define-mcp";
11
11
  import type { BuiltInError, ConversationResult } from "../../pipelines/types";
12
+ import type { PutApiStepDefinitionsData } from "../../generated/types.gen";
12
13
  import { type StepHandle } from "./step-handle";
13
14
  type Prettify<T> = {
14
15
  [K in keyof T]: T[K];
@@ -26,7 +27,7 @@ export type DefineStepInput<TInput extends ZodType = ZodType, TResult extends Zo
26
27
  */
27
28
  environment?: StepEnvironment<TInput["_output"], TEnv, TResult["_output"]>;
28
29
  agentPrompt: string | ((context: PromptTemplateContext<TInput["_output"], PromptEnvContext<TEnv>>) => string);
29
- additionalInput?: TInput;
30
+ input?: TInput;
30
31
  result?: TResult;
31
32
  features?: AnyStepFeature[];
32
33
  /**
@@ -53,7 +54,28 @@ export type DefineStepInput<TInput extends ZodType = ZodType, TResult extends Zo
53
54
  * step uses its node's `.retry(...)` instead.
54
55
  */
55
56
  retry?: readonly StepRetryEntry[];
57
+ /**
58
+ * How many times a standalone Task of this step may hand over. Omitted
59
+ * means the server default. A pipeline step uses its node's
60
+ * `.settings({ maxTurns })` instead.
61
+ */
62
+ maxTurns?: number;
63
+ /**
64
+ * How many live Tasks of this step may run on one work item (`max`), and
65
+ * how many more may wait for a slot (`waiting`). Anything past that is
66
+ * dropped. Omitted means no limit. Pipeline nodes can't override it.
67
+ */
68
+ concurrency?: StepConcurrency;
69
+ /** Work item permissions the step's Tasks get on top of `self`. */
70
+ workItemPermissions?: readonly WorkItemPermission[];
71
+ };
72
+ /** A step's per-work-item concurrency limit. */
73
+ export type StepConcurrency = {
74
+ max: number;
75
+ waiting: number;
56
76
  };
77
+ /** A work item permission a step's Tasks may be granted. */
78
+ export type WorkItemPermission = NonNullable<PutApiStepDefinitionsData["body"]["workItemPermissions"]>[number];
57
79
  /** One `retry` entry: the same shape as a pipeline node's `retry`. */
58
80
  export type StepRetryEntry = {
59
81
  on: readonly string[];
@@ -104,6 +126,12 @@ export type StepDefinitionSpec = {
104
126
  * the handle's pipeline chain method.
105
127
  */
106
128
  retryJson?: StepRetryEntry[];
129
+ /** How many times a standalone Task of this step may hand over; omitted means the server default. */
130
+ maxTurns?: number;
131
+ /** The step's per-work-item concurrency limit; omitted means no limit. */
132
+ concurrency?: StepConcurrency;
133
+ /** Work item permissions the step's Tasks get on top of `self`. */
134
+ workItemPermissions?: readonly WorkItemPermission[];
107
135
  /**
108
136
  * `kind === "code"` only: the live function of a spec produced by
109
137
  * `codeStep()`. Code-step discovery (`findCodeStepInModule`) reads it to
@@ -13,7 +13,9 @@ import {
13
13
  compileEnvironment,
14
14
  compileMcps,
15
15
  compileRepo,
16
+ compileStepConcurrency,
16
17
  compileStepErrors,
18
+ compileStepMaxTurns,
17
19
  compileStepRetry,
18
20
  createPromptInputProxy,
19
21
  createPromptTemplateContext,
@@ -29,18 +31,19 @@ import {
29
31
  resolveMcpChecks,
30
32
  toStepHandle,
31
33
  toStepSpec
32
- } from "../../chunk-3ctaaseb.js";
33
- import"../../chunk-mz53r914.js";
34
+ } from "../../chunk-fyfvp6jx.js";
35
+ import"../../chunk-e1h021kq.js";
36
+ import"../../chunk-63f90zky.js";
37
+ import"../../chunk-jj9pezwb.js";
38
+ import"../../chunk-y11p1q7r.js";
34
39
  import"../../chunk-5zsavw98.js";
35
40
  import"../../chunk-4ggr8af6.js";
36
41
  import"../../chunk-k4y5qt4y.js";
37
- import"../../chunk-cdanncng.js";
38
- import"../../chunk-e1h021kq.js";
39
- import"../../chunk-63f90zky.js";
42
+ import"../../chunk-ejzfdm1z.js";
43
+ import"../../chunk-wnfj3wyx.js";
40
44
  import"../../chunk-ngy1fdcx.js";
41
45
  import"../../chunk-y2pv8d6a.js";
42
- import"../../chunk-dp86pa6m.js";
43
- import"../../chunk-vfeytkqx.js";
46
+ import"../../chunk-01nfqm18.js";
44
47
  import"../../chunk-skzxcba3.js";
45
48
  import"../../chunk-y64skrwp.js";
46
49
  export {
@@ -57,7 +60,9 @@ export {
57
60
  compileEnvironment,
58
61
  compileMcps,
59
62
  compileRepo,
63
+ compileStepConcurrency,
60
64
  compileStepErrors,
65
+ compileStepMaxTurns,
61
66
  compileStepRetry,
62
67
  createPromptInputProxy,
63
68
  createPromptTemplateContext,
@@ -17,22 +17,30 @@ export type ReadOnlyRepoSpec = {
17
17
  export type ReadWriteRepoSpec = {
18
18
  readonly mode: "readWrite";
19
19
  /**
20
- * Commit message template; `{{input.…}}` and `{{result.…}}` tokens only, one
21
- * line, at most 500 characters. Defaults to `scarn: task <taskId>`.
20
+ * Commit message template; `{{input.…}}`, `{{result.…}}`,
21
+ * `{{workItem.title}}` and `{{workItem.platformKey}}` tokens only, one line,
22
+ * at most 500 characters. Defaults to `scarn: task <taskId>`.
22
23
  */
23
24
  readonly message?: string;
24
25
  /** Defaults to `"fail"`: a failed push fails the step. */
25
26
  readonly onPushFailure?: "fail" | "warn";
26
27
  };
27
28
  export type RepoSpec = NoneRepoSpec | ReadOnlyRepoSpec | ReadWriteRepoSpec;
28
- /** What `Runtime.devcontainer()` accepts. */
29
+ /** What `Runtime.devcontainer()` and `Runtime.managed.<id>()` accept. */
29
30
  export type DevcontainerRepoSpec = ReadOnlyRepoSpec | ReadWriteRepoSpec;
30
31
  /** What `Runtime.host()` accepts. */
31
32
  export type HostRepoSpec = NoneRepoSpec;
32
33
  /** Runs once at definition time, against the same proxies `agentPrompt` and `vars` use. */
34
+ /** The work item values a commit message may name, read live at commit time. */
35
+ export type CommitMessageWorkItem = {
36
+ title: string;
37
+ platformKey: string;
38
+ };
33
39
  export type RepoFn<TInput, TResult, TSpec extends RepoSpec> = (context: {
34
40
  input: PromptInputProxy<TInput>;
35
41
  result: PromptInputProxy<TResult>;
42
+ /** The Task's work item: `{{workItem.title}}` and `{{workItem.platformKey}}`. */
43
+ workItem: PromptInputProxy<CommitMessageWorkItem>;
36
44
  }) => TSpec;
37
45
  export type RepoField<TInput, TResult, TSpec extends RepoSpec> = TSpec | RepoFn<TInput, TResult, TSpec>;
38
46
  export type ReadWriteRepoOpts = Omit<ReadWriteRepoSpec, "mode">;
@@ -17,8 +17,8 @@ export type HostRuntimeSpec = {
17
17
  readonly kind: "host";
18
18
  };
19
19
  /**
20
- * A worker-supplied container (image, config and dependency install owned by
21
- * the worker). Build one with `Runtime.managed.<id>()`. `codeStep` only.
20
+ * A worker-supplied container (image and config owned by the worker). Build one
21
+ * with `Runtime.managed.<id>()`. Works with `codeStep` and `defineStep`.
22
22
  */
23
23
  export type ManagedRuntimeSpec<TId extends ManagedRuntimeId = ManagedRuntimeId> = {
24
24
  readonly kind: "managed";
@@ -28,15 +28,15 @@ export type RuntimeSpec = DevcontainerRuntimeSpec | HostRuntimeSpec | ManagedRun
28
28
  /**
29
29
  * How a step runs: its `runtime`, its environment `vars` and its `repo` access.
30
30
  * A union on the runtime kind, so a `repo` the runtime cannot honor is a type
31
- * error: a host step takes only `Repo.none()`, a devcontainer step takes
32
- * `Repo.readOnly()` or `Repo.readWrite()`.
31
+ * error: a host step takes only `Repo.none()`, a devcontainer or managed step
32
+ * takes `Repo.readOnly()` or `Repo.readWrite()`.
33
33
  *
34
34
  * Declare `vars` before `agentPrompt` so `TEnv` is inferred into the prompt's
35
35
  * `env`, which is then strict: only declared, non-secret keys.
36
36
  */
37
37
  export type StepEnvironment<TInput, TEnv extends EnvRecord = EnvRecord, TResult = unknown> = {
38
38
  /** Defaults to `Runtime.devcontainer()`. */
39
- runtime?: DevcontainerRuntimeSpec;
39
+ runtime?: DevcontainerRuntimeSpec | ManagedRuntimeSpec;
40
40
  vars?: EnvFn<TInput, TEnv>;
41
41
  /** Defaults to `Repo.readWrite()`. */
42
42
  repo?: RepoField<TInput, TResult, DevcontainerRepoSpec>;
@@ -47,9 +47,8 @@ export type StepEnvironment<TInput, TEnv extends EnvRecord = EnvRecord, TResult
47
47
  repo?: RepoField<TInput, TResult, HostRepoSpec>;
48
48
  };
49
49
  /**
50
- * `codeStep`'s environment: `StepEnvironment`'s devcontainer variant plus
51
- * managed runtimes. A code step runs repo code, which needs a clone, and the
52
- * host runtime has none.
50
+ * `codeStep`'s environment: `StepEnvironment`'s workspace variant. A code step
51
+ * runs repo code, which needs a clone, and the host runtime has none.
53
52
  */
54
53
  export type CodeStepEnvironment<TInput, TResult = unknown> = {
55
54
  /**
@@ -75,10 +74,10 @@ export type ManagedRuntimeFactories = {
75
74
  };
76
75
  export declare const Runtime: {
77
76
  /**
78
- * Worker-supplied containers for `codeStep`, one factory per identifier, for
79
- * example `Runtime.managed.bun1()`. The worker owns the image and installs the
80
- * pipeline-builder dependencies; the repo holds nothing. An unknown identifier
81
- * is a type error. Not supported for `defineStep`.
77
+ * Worker-supplied containers, one factory per identifier, for example
78
+ * `Runtime.managed.bun1()`. The worker owns the image and clones the repo
79
+ * into it; the repo holds nothing. For a `codeStep` it also installs the
80
+ * pipeline-builder dependencies. An unknown identifier is a type error.
82
81
  */
83
82
  readonly managed: ManagedRuntimeFactories;
84
83
  /**