@scarn/sdk 0.8.3 → 0.8.4

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.
@@ -1218,10 +1218,29 @@ function assertStepMcpInput(config2) {
1218
1218
  const issues = parsed.error.issues.map((issue) => issue.path.length > 0 ? `${issue.path.map(String).join(".")}: ${issue.message}` : issue.message).join("; ");
1219
1219
  throw new Error(`Step "${config2.key}" healthChecks: ${issues}. MCP health checks are declared on the server with defineMcp({ healthChecks }).`);
1220
1220
  }
1221
+ function collectGrants(stepKey, features) {
1222
+ const grants = [];
1223
+ const seen = new Set;
1224
+ for (const feature of features) {
1225
+ const grant = feature._grant;
1226
+ if (!grant)
1227
+ continue;
1228
+ const key = `${grant.resource}:${grant.action}:${grant.scope}`;
1229
+ if (seen.has(key)) {
1230
+ throw new Error(`Step "${stepKey}": more than one Features.${grant.resource}s.${grant.action}({ scope: "${grant.scope}" }). Attach each work item grant once.`);
1231
+ }
1232
+ seen.add(key);
1233
+ grants.push("labels" in grant ? { ...grant, labels: [...grant.labels] } : { ...grant });
1234
+ }
1235
+ return grants;
1236
+ }
1221
1237
  function defineStep(config2) {
1222
1238
  const features = config2.features ?? [];
1239
+ const grants = collectGrants(config2.key, features);
1223
1240
  let effectiveResult = config2.result;
1224
1241
  for (const feature of features) {
1242
+ if (!feature._resultExtension)
1243
+ continue;
1225
1244
  effectiveResult = effectiveResult ? effectiveResult.extend(feature._resultExtension.shape) : feature._resultExtension;
1226
1245
  }
1227
1246
  const basePrompt = typeof config2.agentPrompt === "function" ? config2.agentPrompt(createPromptTemplateContext()) : config2.agentPrompt;
@@ -1270,7 +1289,7 @@ ${feature._promptAddition}` : feature._promptAddition;
1270
1289
  ...config2.concurrency !== undefined ? {
1271
1290
  concurrency: compileStepConcurrency(config2.key, config2.concurrency)
1272
1291
  } : {},
1273
- ...config2.workItemPermissions !== undefined ? { workItemPermissions: [...config2.workItemPermissions] } : {}
1292
+ ...grants.length > 0 ? { grants } : {}
1274
1293
  };
1275
1294
  return toStepHandle(spec);
1276
1295
  }
@@ -1279,6 +1298,8 @@ function codeStep(config2) {
1279
1298
  const features = config2.features ?? [];
1280
1299
  let effectiveResult = config2.resultSchema;
1281
1300
  for (const feature of features) {
1301
+ if (!feature._resultExtension)
1302
+ continue;
1282
1303
  effectiveResult = effectiveResult ? effectiveResult.extend(feature._resultExtension.shape) : feature._resultExtension;
1283
1304
  }
1284
1305
  const {
@@ -1369,7 +1390,7 @@ var buildStepDefinitionsClient = (stepDefinitions) => {
1369
1390
  })),
1370
1391
  maxTurns: spec.maxTurns ?? null,
1371
1392
  concurrency: spec.concurrency ?? null,
1372
- workItemPermissions: [...spec.workItemPermissions ?? []],
1393
+ grants: (spec.grants ?? []).map((grant) => ({ ...grant })),
1373
1394
  status: spec.status,
1374
1395
  projectId
1375
1396
  };
@@ -1384,6 +1405,16 @@ var buildStepDefinitionsClient = (stepDefinitions) => {
1384
1405
  };
1385
1406
  };
1386
1407
  // src/definitions/steps/step-features.ts
1408
+ var grantActionValues = [
1409
+ "read",
1410
+ "update",
1411
+ "comment",
1412
+ "label",
1413
+ "block",
1414
+ "close",
1415
+ "create"
1416
+ ];
1417
+ var grantScopeValues = ["self", "children"];
1387
1418
  var notificationKindSchema = exports_external.enum([
1388
1419
  "feedback_request",
1389
1420
  "status_update",
@@ -1453,9 +1484,90 @@ var feedbackRequestsFeature = {
1453
1484
  ].join(`
1454
1485
  `)
1455
1486
  };
1487
+ var WORK_ITEM_TOOLS = {
1488
+ read: "scarn-get-work-item",
1489
+ update: "scarn-set-work-item-description",
1490
+ comment: "scarn-comment-on-work-item",
1491
+ label: "scarn-label-work-item",
1492
+ block: "scarn-block-work-item",
1493
+ close: "scarn-close-work-item",
1494
+ create: "scarn-create-work-item"
1495
+ };
1496
+ var WORK_ITEM_ACTION_TEXT = {
1497
+ read: "read",
1498
+ update: "replace the description of",
1499
+ comment: "comment on",
1500
+ label: "add or remove labels on",
1501
+ block: "mark as blocked",
1502
+ close: "close",
1503
+ create: "create"
1504
+ };
1505
+ var scopeText = (action, scope) => {
1506
+ if (action === "create")
1507
+ return "child work items of your work item";
1508
+ return scope === "self" ? "your work item" : "its child work items";
1509
+ };
1510
+ var scopeHeading = {
1511
+ self: "Your Work Item",
1512
+ children: "Child Work Items"
1513
+ };
1514
+ var actionHeading = {
1515
+ read: "Read",
1516
+ update: "Update",
1517
+ comment: "Comment on",
1518
+ label: "Label",
1519
+ block: "Block",
1520
+ close: "Close",
1521
+ create: "Create"
1522
+ };
1523
+ function workItemPrompt(grant) {
1524
+ const heading = grant.action === "create" ? "## Work Items: Create Child Work Items" : `## Work Items: ${actionHeading[grant.action]} ${scopeHeading[grant.scope]}`;
1525
+ const lines = [
1526
+ heading,
1527
+ "",
1528
+ `You may ${WORK_ITEM_ACTION_TEXT[grant.action]} ${scopeText(grant.action, grant.scope)}. Use the \`${WORK_ITEM_TOOLS[grant.action]}\` tool.`
1529
+ ];
1530
+ if (grant.action === "label" || grant.action === "create") {
1531
+ lines.push("", "Allowed labels:", ...grant.labels.map((label) => `- \`${label}\``), "", "Any other label is rejected.");
1532
+ }
1533
+ return lines.join(`
1534
+ `);
1535
+ }
1536
+ function workItemFeature(grant) {
1537
+ return { _grant: grant, _promptAddition: workItemPrompt(grant) };
1538
+ }
1539
+ var workItems = {
1540
+ read: ({ scope }) => workItemFeature({ resource: "workItem", action: "read", scope }),
1541
+ update: ({ scope }) => workItemFeature({ resource: "workItem", action: "update", scope }),
1542
+ comment: ({ scope }) => workItemFeature({
1543
+ resource: "workItem",
1544
+ action: "comment",
1545
+ scope
1546
+ }),
1547
+ block: ({ scope }) => workItemFeature({ resource: "workItem", action: "block", scope }),
1548
+ close: ({ scope }) => workItemFeature({ resource: "workItem", action: "close", scope }),
1549
+ label: ({
1550
+ scope,
1551
+ labels
1552
+ }) => workItemFeature({
1553
+ resource: "workItem",
1554
+ action: "label",
1555
+ scope,
1556
+ labels: [...labels]
1557
+ }),
1558
+ create: ({
1559
+ labels
1560
+ }) => workItemFeature({
1561
+ resource: "workItem",
1562
+ action: "create",
1563
+ scope: "children",
1564
+ labels: [...labels]
1565
+ })
1566
+ };
1456
1567
  var Features = {
1457
1568
  notifications: () => notificationsFeature,
1458
- feedbackRequests: () => feedbackRequestsFeature
1569
+ feedbackRequests: () => feedbackRequestsFeature,
1570
+ workItems
1459
1571
  };
1460
1572
  var Notify = {
1461
1573
  create: (item) => ({
@@ -1480,4 +1592,4 @@ var Notify = {
1480
1592
  [NOTIFICATION_RESULT_KEY]: fragments.flatMap((fragment) => fragment[NOTIFICATION_RESULT_KEY])
1481
1593
  })
1482
1594
  };
1483
- export { ARTIFACT_BRAND, ArtifactTypes, normalizeArtifactAccept, artifact, Artifact, exports_z, createPromptInputProxy, createPromptTemplateContext, renderPromptTemplate, isSecretLookingEnvName, Env, normalizeEnv, Repo, compileRepo, Runtime, compileEnvironment, isMcpHandle, defineMcp, resolveMcpChecks, compileMcps, compileStepErrors, compileStepRetry, compileStepMaxTurns, compileStepConcurrency, toStepHandle, toStepSpec, defineStep, codeStep, createStepDefinitionsClient, Features, Notify };
1595
+ export { ARTIFACT_BRAND, ArtifactTypes, normalizeArtifactAccept, artifact, Artifact, exports_z, createPromptInputProxy, createPromptTemplateContext, renderPromptTemplate, isSecretLookingEnvName, Env, normalizeEnv, Repo, compileRepo, Runtime, compileEnvironment, isMcpHandle, defineMcp, resolveMcpChecks, compileMcps, compileStepErrors, compileStepRetry, compileStepMaxTurns, compileStepConcurrency, toStepHandle, toStepSpec, defineStep, codeStep, createStepDefinitionsClient, grantActionValues, grantScopeValues, Features, Notify };
@@ -35,10 +35,6 @@ export type WorkItemChange = {
35
35
  workItemId: string;
36
36
  reason: WorkItemCloseReason;
37
37
  resolution?: string | null;
38
- } | {
39
- kind: "startTask";
40
- workItemId: string;
41
- stepKey: string;
42
38
  };
43
39
  export declare function buildWorkItemChangesPath(workspacePath: string): string;
44
40
  /** The changes recorded so far; a missing file means none. */
@@ -22,8 +22,7 @@ var workItemChangesFileSchema = exports_external.object({
22
22
  "block",
23
23
  "describe",
24
24
  "comment",
25
- "close",
26
- "startTask"
25
+ "close"
27
26
  ])
28
27
  }))
29
28
  });
@@ -3,7 +3,7 @@ import type { EffectiveResult, StepConcurrency, StepRetryEntry } from "./define-
3
3
  import type { BuiltInError } from "../../pipelines/types";
4
4
  import { type StepHandle } from "./step-handle";
5
5
  import { type CodeStepEnvironment } from "./runtime";
6
- import type { AnyStepFeature } from "./step-features";
6
+ import type { CodeStepFeature } from "./step-features";
7
7
  /** What the worker passes a code step besides its input. */
8
8
  export type CodeStepContext = {
9
9
  /**
@@ -14,7 +14,7 @@ export type CodeStepContext = {
14
14
  artifactsDir: string;
15
15
  };
16
16
  export type CodeStepFn<TInput, TResult> = (input: TInput, context: CodeStepContext) => TResult | Promise<TResult>;
17
- export type DefineCodeStepInput<TInput extends ZodType = ZodType, TResult extends ZodType = ZodType, TFeatures extends ReadonlyArray<AnyStepFeature> = never[]> = {
17
+ export type DefineCodeStepInput<TInput extends ZodType = ZodType, TResult extends ZodType = ZodType, TFeatures extends ReadonlyArray<CodeStepFeature> = never[]> = {
18
18
  key: string;
19
19
  name: string;
20
20
  description?: string | null;
@@ -38,7 +38,8 @@ export type DefineCodeStepInput<TInput extends ZodType = ZodType, TResult extend
38
38
  /**
39
39
  * Step features to attach — unlike `defineStep()`, only each feature's
40
40
  * `_resultExtension` applies here (there is no prompt to append
41
- * to on a `kind: "code"` step).
41
+ * to on a `kind: "code"` step). `Features.workItems.*` is rejected: a code
42
+ * step has no agent tools to use a grant with.
42
43
  */
43
44
  features?: TFeatures;
44
45
  /**
@@ -77,7 +78,7 @@ export type DefineCodeStepInput<TInput extends ZodType = ZodType, TResult extend
77
78
  * `entrypoint.fn` reference attached instead — see `StepDefinitionSpec`'s
78
79
  * own doc comment for what happens to it during collection.
79
80
  */
80
- export declare function codeStep<TInput extends ZodType = ZodType, TResult extends ZodType = ZodType, const TFeatures extends ReadonlyArray<AnyStepFeature> = never[], const TErrors extends string = never>(config: Omit<DefineCodeStepInput<TInput, TResult, TFeatures>, "errors" | "retry"> & {
81
+ export declare function codeStep<TInput extends ZodType = ZodType, TResult extends ZodType = ZodType, const TFeatures extends ReadonlyArray<CodeStepFeature> = never[], const TErrors extends string = never>(config: Omit<DefineCodeStepInput<TInput, TResult, TFeatures>, "errors" | "retry"> & {
81
82
  errors?: readonly TErrors[];
82
83
  retry?: readonly {
83
84
  on: readonly (BuiltInError | TErrors)[];
@@ -1,5 +1,5 @@
1
1
  import type { ZodType } from "zod";
2
- import type { AnyStepFeature, FeatureResultExtensions } from "./step-features";
2
+ import type { AnyStepFeature, FeatureResultExtensions, Grant } from "./step-features";
3
3
  import { type PromptTemplateContext } from "./prompt-template";
4
4
  import { type HealthChecksInput, type StepHealthChecksInput } from "../../health-checks";
5
5
  import type { OpenCodeMcpServers } from "../../opencode-mcp";
@@ -9,7 +9,6 @@ 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";
13
12
  import { type StepHandle } from "./step-handle";
14
13
  type Prettify<T> = {
15
14
  [K in keyof T]: T[K];
@@ -66,16 +65,12 @@ export type DefineStepInput<TInput extends ZodType = ZodType, TResult extends Zo
66
65
  * dropped. Omitted means no limit. Pipeline nodes can't override it.
67
66
  */
68
67
  concurrency?: StepConcurrency;
69
- /** Work item permissions the step's Tasks get on top of `self`. */
70
- workItemPermissions?: readonly WorkItemPermission[];
71
68
  };
72
69
  /** A step's per-work-item concurrency limit. */
73
70
  export type StepConcurrency = {
74
71
  max: number;
75
72
  waiting: number;
76
73
  };
77
- /** A work item permission a step's Tasks may be granted. */
78
- export type WorkItemPermission = NonNullable<PutApiStepDefinitionsData["body"]["workItemPermissions"]>[number];
79
74
  /** One `retry` entry: the same shape as a pipeline node's `retry`. */
80
75
  export type StepRetryEntry = {
81
76
  on: readonly string[];
@@ -130,8 +125,11 @@ export type StepDefinitionSpec = {
130
125
  maxTurns?: number;
131
126
  /** The step's per-work-item concurrency limit; omitted means no limit. */
132
127
  concurrency?: StepConcurrency;
133
- /** Work item permissions the step's Tasks get on top of `self`. */
134
- workItemPermissions?: readonly WorkItemPermission[];
128
+ /**
129
+ * What the step's Tasks may do to work items, from its
130
+ * `Features.workItems.*` features. Every Task may also read its own.
131
+ */
132
+ grants?: readonly Grant[];
135
133
  /**
136
134
  * `kind === "code"` only: the live function of a spec produced by
137
135
  * `codeStep()`. Code-step discovery (`findCodeStepInModule`) reads it to
@@ -150,10 +148,10 @@ export type StepDefinitionSpec = {
150
148
  export type EffectiveResult<TResult, TFeatures extends ReadonlyArray<AnyStepFeature>> = Prettify<TResult & FeatureResultExtensions<TFeatures>>;
151
149
  /**
152
150
  * A `defineStep` handle's result type: `ConversationResult` when the step has
153
- * no `result` and no features (a conversation step), else its effective
154
- * result.
151
+ * no `result` and no feature adds result fields (a conversation step), else
152
+ * its effective result.
155
153
  */
156
- export type DefineStepResult<TResult extends ZodType, TFeatures extends ReadonlyArray<AnyStepFeature>> = ZodType extends TResult ? [TFeatures[number]] extends [never] ? ConversationResult : EffectiveResult<TResult["_output"], TFeatures> : EffectiveResult<TResult["_output"], TFeatures>;
154
+ export type DefineStepResult<TResult extends ZodType, TFeatures extends ReadonlyArray<AnyStepFeature>> = ZodType extends TResult ? [keyof FeatureResultExtensions<TFeatures>] extends [never] ? ConversationResult : EffectiveResult<TResult["_output"], TFeatures> : EffectiveResult<TResult["_output"], TFeatures>;
157
155
  export declare function defineStep<TInput extends ZodType = ZodType, TResult extends ZodType = ZodType, const TFeatures extends ReadonlyArray<AnyStepFeature> = never[], TEnv extends EnvRecord = EnvRecord, const TErrors extends string = never>(config: Omit<DefineStepInput<TInput, TResult, TEnv>, "features" | "errors" | "retry"> & {
158
156
  features?: TFeatures;
159
157
  errors?: readonly TErrors[];
@@ -23,6 +23,8 @@ import {
23
23
  defineMcp,
24
24
  defineStep,
25
25
  exports_z,
26
+ grantActionValues,
27
+ grantScopeValues,
26
28
  isMcpHandle,
27
29
  isSecretLookingEnvName,
28
30
  normalizeArtifactAccept,
@@ -31,7 +33,7 @@ import {
31
33
  resolveMcpChecks,
32
34
  toStepHandle,
33
35
  toStepSpec
34
- } from "../../chunk-fyfvp6jx.js";
36
+ } from "../../chunk-hyaez4ee.js";
35
37
  import"../../chunk-e1h021kq.js";
36
38
  import"../../chunk-63f90zky.js";
37
39
  import"../../chunk-jj9pezwb.js";
@@ -69,6 +71,8 @@ export {
69
71
  createStepDefinitionsClient,
70
72
  defineMcp,
71
73
  defineStep,
74
+ grantActionValues,
75
+ grantScopeValues,
72
76
  isMcpHandle,
73
77
  isSecretLookingEnvName,
74
78
  normalizeArtifactAccept,
@@ -32,7 +32,37 @@ declare const buildStepDefinitionsClient: (stepDefinitions: StepDefinitions) =>
32
32
  on: Array<string>;
33
33
  maxAttempts: number;
34
34
  }>;
35
- workItemPermissions: Array<"self" | "children">;
35
+ grants: Array<{
36
+ resource: string;
37
+ action: string;
38
+ scope: "self" | "children";
39
+ } | {
40
+ resource: string;
41
+ action: string;
42
+ scope: "self" | "children";
43
+ } | {
44
+ resource: string;
45
+ action: string;
46
+ scope: "self" | "children";
47
+ } | {
48
+ resource: string;
49
+ action: string;
50
+ scope: "self" | "children";
51
+ labels: Array<string>;
52
+ } | {
53
+ resource: string;
54
+ action: string;
55
+ scope: "self" | "children";
56
+ } | {
57
+ resource: string;
58
+ action: string;
59
+ scope: "self" | "children";
60
+ } | {
61
+ resource: string;
62
+ action: string;
63
+ scope: string;
64
+ labels: Array<string>;
65
+ }>;
36
66
  maxTurns: number | unknown;
37
67
  concurrency: {
38
68
  max: number;
@@ -164,7 +194,37 @@ declare const buildStepDefinitionsClient: (stepDefinitions: StepDefinitions) =>
164
194
  on: Array<string>;
165
195
  maxAttempts: number;
166
196
  }>;
167
- workItemPermissions: Array<"self" | "children">;
197
+ grants: Array<{
198
+ resource: string;
199
+ action: string;
200
+ scope: "self" | "children";
201
+ } | {
202
+ resource: string;
203
+ action: string;
204
+ scope: "self" | "children";
205
+ } | {
206
+ resource: string;
207
+ action: string;
208
+ scope: "self" | "children";
209
+ } | {
210
+ resource: string;
211
+ action: string;
212
+ scope: "self" | "children";
213
+ labels: Array<string>;
214
+ } | {
215
+ resource: string;
216
+ action: string;
217
+ scope: "self" | "children";
218
+ } | {
219
+ resource: string;
220
+ action: string;
221
+ scope: "self" | "children";
222
+ } | {
223
+ resource: string;
224
+ action: string;
225
+ scope: string;
226
+ labels: Array<string>;
227
+ }>;
168
228
  maxTurns: number | unknown;
169
229
  concurrency: {
170
230
  max: number;
@@ -306,7 +366,37 @@ declare const buildStepDefinitionsClient: (stepDefinitions: StepDefinitions) =>
306
366
  on: Array<string>;
307
367
  maxAttempts: number;
308
368
  }>;
309
- workItemPermissions: Array<"self" | "children">;
369
+ grants: Array<{
370
+ resource: string;
371
+ action: string;
372
+ scope: "self" | "children";
373
+ } | {
374
+ resource: string;
375
+ action: string;
376
+ scope: "self" | "children";
377
+ } | {
378
+ resource: string;
379
+ action: string;
380
+ scope: "self" | "children";
381
+ } | {
382
+ resource: string;
383
+ action: string;
384
+ scope: "self" | "children";
385
+ labels: Array<string>;
386
+ } | {
387
+ resource: string;
388
+ action: string;
389
+ scope: "self" | "children";
390
+ } | {
391
+ resource: string;
392
+ action: string;
393
+ scope: "self" | "children";
394
+ } | {
395
+ resource: string;
396
+ action: string;
397
+ scope: string;
398
+ labels: Array<string>;
399
+ }>;
310
400
  maxTurns: number | unknown;
311
401
  concurrency: {
312
402
  max: number;
@@ -1,13 +1,47 @@
1
1
  import { z } from "zod";
2
2
  import type { ZodObject, ZodRawShape } from "zod";
3
- export type StepFeature<TResultExtension extends Record<string, unknown> = Record<string, unknown>> = {
4
- readonly _resultExtension: ZodObject<ZodRawShape>;
3
+ export declare const grantActionValues: readonly ["read", "update", "comment", "label", "block", "close", "create"];
4
+ export declare const grantScopeValues: readonly ["self", "children"];
5
+ /** What a grant lets the agent do to a work item. */
6
+ export type GrantAction = (typeof grantActionValues)[number];
7
+ /** `self`: the Task's own work item. `children`: its child work items. */
8
+ export type GrantScope = (typeof grantScopeValues)[number];
9
+ /**
10
+ * One thing a step's Tasks may do to a work item. `label` and `create` name
11
+ * the labels they may set; `create` only covers `children`.
12
+ */
13
+ export type Grant = {
14
+ resource: "workItem";
15
+ action: "read" | "update" | "comment" | "block" | "close";
16
+ scope: GrantScope;
17
+ } | {
18
+ resource: "workItem";
19
+ action: "label";
20
+ scope: GrantScope;
21
+ labels: string[];
22
+ } | {
23
+ resource: "workItem";
24
+ action: "create";
25
+ scope: "children";
26
+ labels: string[];
27
+ };
28
+ export type StepFeature<TResultExtension extends Record<string, unknown> = Record<string, unknown>, TGrant extends Grant | undefined = undefined> = {
29
+ /** Fields the feature adds to the step's result; omitted when it adds none. */
30
+ readonly _resultExtension?: ZodObject<ZodRawShape>;
5
31
  readonly _promptAddition: string;
32
+ /** The grant the feature gives the step's Tasks, if any. */
33
+ readonly _grant?: TGrant;
6
34
  readonly __resultExtension?: TResultExtension;
7
35
  };
8
- export type AnyStepFeature = StepFeature;
36
+ export type AnyStepFeature = StepFeature<Record<string, unknown>, Grant | undefined>;
37
+ /** A feature that grants a work item action. Adds nothing to the result. */
38
+ export type WorkItemFeature<TGrant extends Grant = Grant> = StepFeature<Record<never, never>, TGrant> & {
39
+ readonly _grant: TGrant;
40
+ };
41
+ /** A feature a code step may attach: no grant, since it has no agent tools. */
42
+ export type CodeStepFeature = StepFeature;
9
43
  type UnionToIntersection<U> = (U extends unknown ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
10
- export type FeatureResultExtensions<TFeatures extends readonly AnyStepFeature[]> = [TFeatures[number]] extends [never] ? Record<never, never> : UnionToIntersection<TFeatures[number] extends StepFeature<infer R> ? R : never>;
44
+ export type FeatureResultExtensions<TFeatures extends readonly AnyStepFeature[]> = [TFeatures[number]] extends [never] ? Record<never, never> : UnionToIntersection<TFeatures[number] extends StepFeature<infer R, Grant | undefined> ? R : never>;
11
45
  declare const notificationKindSchema: z.ZodEnum<{
12
46
  blocked: "blocked";
13
47
  feedback_request: "feedback_request";
@@ -78,6 +112,13 @@ export type FeedbackRequestItem = {
78
112
  category: string;
79
113
  urgency: FeedbackRequestUrgency;
80
114
  };
115
+ type ScopeOptions = {
116
+ scope: GrantScope;
117
+ };
118
+ type LabelsOptions<TLabels extends readonly string[]> = {
119
+ scope: GrantScope;
120
+ labels: TLabels;
121
+ };
81
122
  export declare const Features: {
82
123
  readonly notifications: () => NotificationsFeature;
83
124
  /**
@@ -87,6 +128,48 @@ export declare const Features: {
87
128
  * `$scarn_notifications_v1` result field.
88
129
  */
89
130
  readonly feedbackRequests: () => NotificationsFeature;
131
+ readonly workItems: {
132
+ readonly read: ({ scope }: ScopeOptions) => WorkItemFeature<{
133
+ readonly resource: "workItem";
134
+ readonly action: "read";
135
+ readonly scope: "self" | "children";
136
+ }>;
137
+ readonly update: ({ scope }: ScopeOptions) => WorkItemFeature<{
138
+ readonly resource: "workItem";
139
+ readonly action: "update";
140
+ readonly scope: "self" | "children";
141
+ }>;
142
+ readonly comment: ({ scope }: ScopeOptions) => WorkItemFeature<{
143
+ readonly resource: "workItem";
144
+ readonly action: "comment";
145
+ readonly scope: "self" | "children";
146
+ }>;
147
+ readonly block: ({ scope }: ScopeOptions) => WorkItemFeature<{
148
+ readonly resource: "workItem";
149
+ readonly action: "block";
150
+ readonly scope: "self" | "children";
151
+ }>;
152
+ readonly close: ({ scope }: ScopeOptions) => WorkItemFeature<{
153
+ readonly resource: "workItem";
154
+ readonly action: "close";
155
+ readonly scope: "self" | "children";
156
+ }>;
157
+ /** Add or remove the given labels; the agent may not touch any other. */
158
+ readonly label: <const TLabels extends readonly [string, ...string[]]>({ scope, labels, }: LabelsOptions<TLabels>) => WorkItemFeature<Extract<Grant, {
159
+ action: "label";
160
+ }> & {
161
+ labels: [...TLabels];
162
+ }>;
163
+ /** Create child work items, each with labels from `labels` only. */
164
+ readonly create: <const TLabels extends readonly [string, ...string[]]>({ labels, }: {
165
+ scope: "children";
166
+ labels: TLabels;
167
+ }) => WorkItemFeature<Extract<Grant, {
168
+ action: "create";
169
+ }> & {
170
+ labels: [...TLabels];
171
+ }>;
172
+ };
90
173
  };
91
174
  export declare const Notify: {
92
175
  /** The one generic constructor. Field names match `NotificationItem`
@@ -84,7 +84,7 @@ export declare class TaskRuns extends HeyApiClient {
84
84
  getTaskRunWorkerContext<ThrowOnError extends boolean = false>(options: Options<PostApiTaskRunsByTaskRunIdWorkerContextData, ThrowOnError>): import("./client").RequestResult<PostApiTaskRunsByTaskRunIdWorkerContextResponses, PostApiTaskRunsByTaskRunIdWorkerContextErrors, ThrowOnError, "fields">;
85
85
  completeTaskRun<ThrowOnError extends boolean = false>(options: Options<PostApiTaskRunsByTaskRunIdCompletionsData, ThrowOnError>): import("./client").RequestResult<PostApiTaskRunsByTaskRunIdCompletionsResponses, PostApiTaskRunsByTaskRunIdCompletionsErrors, ThrowOnError, "fields">;
86
86
  /**
87
- * Records that the task run's agent ended its turn with a yield; the task run ends `yielded`. A `hand_over` (the default) hands the conversation to a person: when it belongs to a pipeline run, the run posts `message` to the step visit's conversation and waits for a reply. A `wait_for_work` applies `workItemChanges`, leaves the task `waiting_for_work`, and queues its continuation once its work item has no open blockers (at once if it has none). Requires the claim token and `executions:write`.
87
+ * Records that the task run's agent ended its turn with a yield; the task run ends `yielded`. It hands the conversation to a person: when it belongs to a pipeline run, the run posts `message` to the step visit's conversation and waits for a reply. Requires the claim token and `executions:write`.
88
88
  */
89
89
  yieldTaskRun<ThrowOnError extends boolean = false>(options: Options<PostApiTaskRunsByTaskRunIdYieldsData, ThrowOnError>): import("./client").RequestResult<PostApiTaskRunsByTaskRunIdYieldsResponses, PostApiTaskRunsByTaskRunIdYieldsErrors, ThrowOnError, "fields">;
90
90
  markTaskRunRunning<ThrowOnError extends boolean = false>(options: Options<PutApiTaskRunsByTaskRunIdRunningData, ThrowOnError>): import("./client").RequestResult<PutApiTaskRunsByTaskRunIdRunningResponses, PutApiTaskRunsByTaskRunIdRunningErrors, ThrowOnError, "fields">;
@@ -1498,7 +1498,37 @@ export type GetApiStepDefinitionsResponses = {
1498
1498
  on: Array<string>;
1499
1499
  maxAttempts: number;
1500
1500
  }>;
1501
- workItemPermissions: Array<'self' | 'children'>;
1501
+ grants: Array<{
1502
+ resource: string;
1503
+ action: string;
1504
+ scope: 'self' | 'children';
1505
+ } | {
1506
+ resource: string;
1507
+ action: string;
1508
+ scope: 'self' | 'children';
1509
+ } | {
1510
+ resource: string;
1511
+ action: string;
1512
+ scope: 'self' | 'children';
1513
+ } | {
1514
+ resource: string;
1515
+ action: string;
1516
+ scope: 'self' | 'children';
1517
+ labels: Array<string>;
1518
+ } | {
1519
+ resource: string;
1520
+ action: string;
1521
+ scope: 'self' | 'children';
1522
+ } | {
1523
+ resource: string;
1524
+ action: string;
1525
+ scope: 'self' | 'children';
1526
+ } | {
1527
+ resource: string;
1528
+ action: string;
1529
+ scope: string;
1530
+ labels: Array<string>;
1531
+ }>;
1502
1532
  maxTurns: number | unknown;
1503
1533
  concurrency: {
1504
1534
  max: number;
@@ -1632,7 +1662,37 @@ export type PostApiStepDefinitionsData = {
1632
1662
  on: Array<string>;
1633
1663
  maxAttempts: number;
1634
1664
  }>;
1635
- workItemPermissions?: Array<'self' | 'children'>;
1665
+ grants?: Array<{
1666
+ resource: string;
1667
+ action: string;
1668
+ scope: 'self' | 'children';
1669
+ } | {
1670
+ resource: string;
1671
+ action: string;
1672
+ scope: 'self' | 'children';
1673
+ } | {
1674
+ resource: string;
1675
+ action: string;
1676
+ scope: 'self' | 'children';
1677
+ } | {
1678
+ resource: string;
1679
+ action: string;
1680
+ scope: 'self' | 'children';
1681
+ labels: Array<string>;
1682
+ } | {
1683
+ resource: string;
1684
+ action: string;
1685
+ scope: 'self' | 'children';
1686
+ } | {
1687
+ resource: string;
1688
+ action: string;
1689
+ scope: 'self' | 'children';
1690
+ } | {
1691
+ resource: string;
1692
+ action: string;
1693
+ scope: string;
1694
+ labels: Array<string>;
1695
+ }>;
1636
1696
  maxTurns?: number | unknown;
1637
1697
  concurrency?: {
1638
1698
  max: number;
@@ -1906,7 +1966,37 @@ export type PostApiStepDefinitionsResponses = {
1906
1966
  on: Array<string>;
1907
1967
  maxAttempts: number;
1908
1968
  }>;
1909
- workItemPermissions: Array<'self' | 'children'>;
1969
+ grants: Array<{
1970
+ resource: string;
1971
+ action: string;
1972
+ scope: 'self' | 'children';
1973
+ } | {
1974
+ resource: string;
1975
+ action: string;
1976
+ scope: 'self' | 'children';
1977
+ } | {
1978
+ resource: string;
1979
+ action: string;
1980
+ scope: 'self' | 'children';
1981
+ } | {
1982
+ resource: string;
1983
+ action: string;
1984
+ scope: 'self' | 'children';
1985
+ labels: Array<string>;
1986
+ } | {
1987
+ resource: string;
1988
+ action: string;
1989
+ scope: 'self' | 'children';
1990
+ } | {
1991
+ resource: string;
1992
+ action: string;
1993
+ scope: 'self' | 'children';
1994
+ } | {
1995
+ resource: string;
1996
+ action: string;
1997
+ scope: string;
1998
+ labels: Array<string>;
1999
+ }>;
1910
2000
  maxTurns: number | unknown;
1911
2001
  concurrency: {
1912
2002
  max: number;
@@ -2040,7 +2130,37 @@ export type PutApiStepDefinitionsData = {
2040
2130
  on: Array<string>;
2041
2131
  maxAttempts: number;
2042
2132
  }>;
2043
- workItemPermissions?: Array<'self' | 'children'>;
2133
+ grants?: Array<{
2134
+ resource: string;
2135
+ action: string;
2136
+ scope: 'self' | 'children';
2137
+ } | {
2138
+ resource: string;
2139
+ action: string;
2140
+ scope: 'self' | 'children';
2141
+ } | {
2142
+ resource: string;
2143
+ action: string;
2144
+ scope: 'self' | 'children';
2145
+ } | {
2146
+ resource: string;
2147
+ action: string;
2148
+ scope: 'self' | 'children';
2149
+ labels: Array<string>;
2150
+ } | {
2151
+ resource: string;
2152
+ action: string;
2153
+ scope: 'self' | 'children';
2154
+ } | {
2155
+ resource: string;
2156
+ action: string;
2157
+ scope: 'self' | 'children';
2158
+ } | {
2159
+ resource: string;
2160
+ action: string;
2161
+ scope: string;
2162
+ labels: Array<string>;
2163
+ }>;
2044
2164
  maxTurns?: number | unknown;
2045
2165
  concurrency?: {
2046
2166
  max: number;
@@ -2276,7 +2396,37 @@ export type PutApiStepDefinitionsResponses = {
2276
2396
  on: Array<string>;
2277
2397
  maxAttempts: number;
2278
2398
  }>;
2279
- workItemPermissions: Array<'self' | 'children'>;
2399
+ grants: Array<{
2400
+ resource: string;
2401
+ action: string;
2402
+ scope: 'self' | 'children';
2403
+ } | {
2404
+ resource: string;
2405
+ action: string;
2406
+ scope: 'self' | 'children';
2407
+ } | {
2408
+ resource: string;
2409
+ action: string;
2410
+ scope: 'self' | 'children';
2411
+ } | {
2412
+ resource: string;
2413
+ action: string;
2414
+ scope: 'self' | 'children';
2415
+ labels: Array<string>;
2416
+ } | {
2417
+ resource: string;
2418
+ action: string;
2419
+ scope: 'self' | 'children';
2420
+ } | {
2421
+ resource: string;
2422
+ action: string;
2423
+ scope: 'self' | 'children';
2424
+ } | {
2425
+ resource: string;
2426
+ action: string;
2427
+ scope: string;
2428
+ labels: Array<string>;
2429
+ }>;
2280
2430
  maxTurns: number | unknown;
2281
2431
  concurrency: {
2282
2432
  max: number;
@@ -2520,7 +2670,37 @@ export type GetApiStepDefinitionsByStepDefinitionIdResponses = {
2520
2670
  on: Array<string>;
2521
2671
  maxAttempts: number;
2522
2672
  }>;
2523
- workItemPermissions: Array<'self' | 'children'>;
2673
+ grants: Array<{
2674
+ resource: string;
2675
+ action: string;
2676
+ scope: 'self' | 'children';
2677
+ } | {
2678
+ resource: string;
2679
+ action: string;
2680
+ scope: 'self' | 'children';
2681
+ } | {
2682
+ resource: string;
2683
+ action: string;
2684
+ scope: 'self' | 'children';
2685
+ } | {
2686
+ resource: string;
2687
+ action: string;
2688
+ scope: 'self' | 'children';
2689
+ labels: Array<string>;
2690
+ } | {
2691
+ resource: string;
2692
+ action: string;
2693
+ scope: 'self' | 'children';
2694
+ } | {
2695
+ resource: string;
2696
+ action: string;
2697
+ scope: 'self' | 'children';
2698
+ } | {
2699
+ resource: string;
2700
+ action: string;
2701
+ scope: string;
2702
+ labels: Array<string>;
2703
+ }>;
2524
2704
  maxTurns: number | unknown;
2525
2705
  concurrency: {
2526
2706
  max: number;
@@ -2764,7 +2944,37 @@ export type PutApiStepDefinitionsByStepDefinitionIdArchiveResponses = {
2764
2944
  on: Array<string>;
2765
2945
  maxAttempts: number;
2766
2946
  }>;
2767
- workItemPermissions: Array<'self' | 'children'>;
2947
+ grants: Array<{
2948
+ resource: string;
2949
+ action: string;
2950
+ scope: 'self' | 'children';
2951
+ } | {
2952
+ resource: string;
2953
+ action: string;
2954
+ scope: 'self' | 'children';
2955
+ } | {
2956
+ resource: string;
2957
+ action: string;
2958
+ scope: 'self' | 'children';
2959
+ } | {
2960
+ resource: string;
2961
+ action: string;
2962
+ scope: 'self' | 'children';
2963
+ labels: Array<string>;
2964
+ } | {
2965
+ resource: string;
2966
+ action: string;
2967
+ scope: 'self' | 'children';
2968
+ } | {
2969
+ resource: string;
2970
+ action: string;
2971
+ scope: 'self' | 'children';
2972
+ } | {
2973
+ resource: string;
2974
+ action: string;
2975
+ scope: string;
2976
+ labels: Array<string>;
2977
+ }>;
2768
2978
  maxTurns: number | unknown;
2769
2979
  concurrency: {
2770
2980
  max: number;
@@ -3044,7 +3254,37 @@ export type PostApiTasksResponses = {
3044
3254
  taskExecutionConfigId: string | unknown;
3045
3255
  inputJson: unknown;
3046
3256
  retryJson: unknown;
3047
- workItemPermissions: Array<'self' | 'children'>;
3257
+ grants: Array<{
3258
+ resource: string;
3259
+ action: string;
3260
+ scope: 'self' | 'children';
3261
+ } | {
3262
+ resource: string;
3263
+ action: string;
3264
+ scope: 'self' | 'children';
3265
+ } | {
3266
+ resource: string;
3267
+ action: string;
3268
+ scope: 'self' | 'children';
3269
+ } | {
3270
+ resource: string;
3271
+ action: string;
3272
+ scope: 'self' | 'children';
3273
+ labels: Array<string>;
3274
+ } | {
3275
+ resource: string;
3276
+ action: string;
3277
+ scope: 'self' | 'children';
3278
+ } | {
3279
+ resource: string;
3280
+ action: string;
3281
+ scope: 'self' | 'children';
3282
+ } | {
3283
+ resource: string;
3284
+ action: string;
3285
+ scope: string;
3286
+ labels: Array<string>;
3287
+ }>;
3048
3288
  maxTurns: number | unknown;
3049
3289
  heartbeatSeconds: number | unknown;
3050
3290
  executionTimeoutSeconds: number | unknown;
@@ -3325,7 +3565,37 @@ export type GetApiTasksByTaskIdResponses = {
3325
3565
  taskExecutionConfigId: string | unknown;
3326
3566
  inputJson: unknown;
3327
3567
  retryJson: unknown;
3328
- workItemPermissions: Array<'self' | 'children'>;
3568
+ grants: Array<{
3569
+ resource: string;
3570
+ action: string;
3571
+ scope: 'self' | 'children';
3572
+ } | {
3573
+ resource: string;
3574
+ action: string;
3575
+ scope: 'self' | 'children';
3576
+ } | {
3577
+ resource: string;
3578
+ action: string;
3579
+ scope: 'self' | 'children';
3580
+ } | {
3581
+ resource: string;
3582
+ action: string;
3583
+ scope: 'self' | 'children';
3584
+ labels: Array<string>;
3585
+ } | {
3586
+ resource: string;
3587
+ action: string;
3588
+ scope: 'self' | 'children';
3589
+ } | {
3590
+ resource: string;
3591
+ action: string;
3592
+ scope: 'self' | 'children';
3593
+ } | {
3594
+ resource: string;
3595
+ action: string;
3596
+ scope: string;
3597
+ labels: Array<string>;
3598
+ }>;
3329
3599
  maxTurns: number | unknown;
3330
3600
  heartbeatSeconds: number | unknown;
3331
3601
  executionTimeoutSeconds: number | unknown;
@@ -4179,7 +4449,37 @@ export type PostApiTaskRunsByTaskRunIdWorkerContextResponses = {
4179
4449
  } | unknown;
4180
4450
  turnsRemaining: number | unknown;
4181
4451
  workItemId: string;
4182
- workItemPermissions: Array<'self' | 'children'>;
4452
+ grants: Array<{
4453
+ resource: string;
4454
+ action: string;
4455
+ scope: 'self' | 'children';
4456
+ } | {
4457
+ resource: string;
4458
+ action: string;
4459
+ scope: 'self' | 'children';
4460
+ } | {
4461
+ resource: string;
4462
+ action: string;
4463
+ scope: 'self' | 'children';
4464
+ } | {
4465
+ resource: string;
4466
+ action: string;
4467
+ scope: 'self' | 'children';
4468
+ labels: Array<string>;
4469
+ } | {
4470
+ resource: string;
4471
+ action: string;
4472
+ scope: 'self' | 'children';
4473
+ } | {
4474
+ resource: string;
4475
+ action: string;
4476
+ scope: 'self' | 'children';
4477
+ } | {
4478
+ resource: string;
4479
+ action: string;
4480
+ scope: string;
4481
+ labels: Array<string>;
4482
+ }>;
4183
4483
  };
4184
4484
  runtime: {
4185
4485
  executionMode: 'workspace' | 'no_workspace';
@@ -4344,10 +4644,6 @@ export type PostApiTaskRunsByTaskRunIdCompletionsData = {
4344
4644
  workItemId: string;
4345
4645
  reason: 'completed' | 'out_of_scope' | 'superseded';
4346
4646
  resolution?: string | unknown;
4347
- } | {
4348
- kind: string;
4349
- workItemId: string;
4350
- stepKey: string;
4351
4647
  }>;
4352
4648
  };
4353
4649
  path: {
@@ -4513,51 +4809,11 @@ export type PostApiTaskRunsByTaskRunIdCompletionsResponse = PostApiTaskRunsByTas
4513
4809
  export type PostApiTaskRunsByTaskRunIdYieldsData = {
4514
4810
  body: {
4515
4811
  claimToken: string;
4516
- kind?: 'hand_over' | 'wait_for_work';
4517
- message?: string;
4812
+ message: string;
4518
4813
  workBranch?: string | unknown;
4519
4814
  createdFromBranch?: string | unknown;
4520
4815
  sessionObjectKey?: string | unknown;
4521
4816
  sessionRestored?: boolean | unknown;
4522
- workItemChanges?: Array<{
4523
- kind: string;
4524
- workItemId: string;
4525
- title: string;
4526
- description: string;
4527
- fields?: {
4528
- [key: string]: unknown;
4529
- };
4530
- labels?: Array<string>;
4531
- blockedBy?: Array<string>;
4532
- } | {
4533
- kind: string;
4534
- workItemId: string;
4535
- add?: Array<string>;
4536
- remove?: Array<string>;
4537
- } | {
4538
- kind: string;
4539
- blockedWorkItemId: string;
4540
- blockingWorkItemId: string;
4541
- remove?: boolean;
4542
- } | {
4543
- kind: string;
4544
- workItemId: string;
4545
- description: string;
4546
- descriptionVersion: number;
4547
- } | {
4548
- kind: string;
4549
- workItemId: string;
4550
- body: string;
4551
- } | {
4552
- kind: string;
4553
- workItemId: string;
4554
- reason: 'completed' | 'out_of_scope' | 'superseded';
4555
- resolution?: string | unknown;
4556
- } | {
4557
- kind: string;
4558
- workItemId: string;
4559
- stepKey: string;
4560
- }>;
4561
4817
  };
4562
4818
  path: {
4563
4819
  taskRunId: string;
package/dist/index.js CHANGED
@@ -89,6 +89,8 @@ import {
89
89
  defineMcp,
90
90
  defineStep,
91
91
  exports_z,
92
+ grantActionValues,
93
+ grantScopeValues,
92
94
  isMcpHandle,
93
95
  isSecretLookingEnvName,
94
96
  normalizeArtifactAccept,
@@ -97,7 +99,7 @@ import {
97
99
  resolveMcpChecks,
98
100
  toStepHandle,
99
101
  toStepSpec
100
- } from "./chunk-fyfvp6jx.js";
102
+ } from "./chunk-hyaez4ee.js";
101
103
  import {
102
104
  collectEnvPlaceholderNames,
103
105
  isEnvPlaceholderValue,
@@ -255,6 +257,8 @@ export {
255
257
  findArtifactMarkers,
256
258
  formatArtifactMarkerRef,
257
259
  formatIssue,
260
+ grantActionValues,
261
+ grantScopeValues,
258
262
  greaterThan,
259
263
  greaterThanInclusive,
260
264
  isEmbeddableArtifactExtension,
@@ -17,7 +17,7 @@ import {
17
17
  import {
18
18
  createStepDefinitionsClient,
19
19
  toStepSpec
20
- } from "../chunk-fyfvp6jx.js";
20
+ } from "../chunk-hyaez4ee.js";
21
21
  import"../chunk-e1h021kq.js";
22
22
  import"../chunk-63f90zky.js";
23
23
  import"../chunk-jj9pezwb.js";
@@ -329,7 +329,37 @@ declare const buildTaskPlaneClient: (taskRuns: TaskRuns) => {
329
329
  } | unknown;
330
330
  turnsRemaining: number | unknown;
331
331
  workItemId: string;
332
- workItemPermissions: Array<"self" | "children">;
332
+ grants: Array<{
333
+ resource: string;
334
+ action: string;
335
+ scope: "self" | "children";
336
+ } | {
337
+ resource: string;
338
+ action: string;
339
+ scope: "self" | "children";
340
+ } | {
341
+ resource: string;
342
+ action: string;
343
+ scope: "self" | "children";
344
+ } | {
345
+ resource: string;
346
+ action: string;
347
+ scope: "self" | "children";
348
+ labels: Array<string>;
349
+ } | {
350
+ resource: string;
351
+ action: string;
352
+ scope: "self" | "children";
353
+ } | {
354
+ resource: string;
355
+ action: string;
356
+ scope: "self" | "children";
357
+ } | {
358
+ resource: string;
359
+ action: string;
360
+ scope: string;
361
+ labels: Array<string>;
362
+ }>;
333
363
  };
334
364
  runtime: {
335
365
  executionMode: "workspace" | "no_workspace";
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://json.schemastore.org/package.json",
3
3
  "name": "@scarn/sdk",
4
- "version": "0.8.3",
4
+ "version": "0.8.4",
5
5
  "type": "module",
6
6
  "exports": {
7
7
  ".": {