@scarn/sdk 0.8.17 → 0.8.19

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 (62) hide show
  1. package/dist/{chunk-g2mzg278.js → chunk-0c60x3v8.js} +51 -59
  2. package/dist/{chunk-dhqeg0wf.js → chunk-2tmrw253.js} +1 -1
  3. package/dist/{chunk-r03knh9j.js → chunk-3zp2qtf8.js} +80 -1
  4. package/dist/{chunk-ar6hcj1r.js → chunk-6tra3gw8.js} +7 -1
  5. package/dist/{chunk-a04phj60.js → chunk-833ef6dg.js} +121 -260
  6. package/dist/{chunk-2ekz6tr5.js → chunk-aemxz9r7.js} +18 -2
  7. package/dist/chunk-e0pt5x0e.js +167 -0
  8. package/dist/chunk-mmy80pec.js +64 -0
  9. package/dist/chunk-mzj1j0p5.js +116 -0
  10. package/dist/{chunk-cdj0yqgs.js → chunk-pqtd0hr7.js} +12 -2
  11. package/dist/chunk-qgkx89eg.js +210 -0
  12. package/dist/chunk-rphfy0fj.js +167 -0
  13. package/dist/chunk-t1dq2c2s.js +224 -0
  14. package/dist/{chunk-qs7p11rp.js → chunk-tvjcfh6s.js} +5 -1
  15. package/dist/{chunk-1wnv6rb2.js → chunk-ymywp5ht.js} +1 -1
  16. package/dist/client.js +8 -2
  17. package/dist/connectors/catalog.d.ts +49 -0
  18. package/dist/connectors/index.d.ts +45 -0
  19. package/dist/connectors/index.js +41 -0
  20. package/dist/defaults/index.js +2 -2
  21. package/dist/definitions/automations/index.js +2 -2
  22. package/dist/definitions/environments/define-environment.d.ts +39 -0
  23. package/dist/definitions/environments/environments-client.d.ts +50 -0
  24. package/dist/definitions/environments/index.d.ts +6 -0
  25. package/dist/definitions/environments/index.js +97 -0
  26. package/dist/definitions/pipelines/index.js +2 -2
  27. package/dist/definitions/steps/compile-mcps.d.ts +8 -12
  28. package/dist/definitions/steps/define-code-step.d.ts +18 -11
  29. package/dist/definitions/steps/define-step.d.ts +14 -25
  30. package/dist/definitions/steps/env.d.ts +30 -8
  31. package/dist/definitions/steps/index.js +30 -13
  32. package/dist/definitions/steps/mcp-server-config.d.ts +19 -9
  33. package/dist/definitions/steps/repo.d.ts +56 -28
  34. package/dist/definitions/steps/runtime.d.ts +54 -39
  35. package/dist/definitions/steps/step-definitions-client.d.ts +222 -63
  36. package/dist/definitions/steps/step-handle.d.ts +8 -1
  37. package/dist/definitions/validation/index.js +6 -3
  38. package/dist/definitions/validation/validate-repo.d.ts +3 -7
  39. package/dist/definitions/validation/validate-runtime.d.ts +2 -7
  40. package/dist/env-vars.d.ts +57 -1
  41. package/dist/env-vars.js +7 -1
  42. package/dist/environment.d.ts +564 -0
  43. package/dist/environment.js +46 -0
  44. package/dist/generated/index.d.ts +2 -2
  45. package/dist/generated/sdk.gen.d.ts +27 -2
  46. package/dist/generated/types.gen.d.ts +2141 -187
  47. package/dist/index.d.ts +2 -0
  48. package/dist/index.js +94 -28
  49. package/dist/opencode-mcp.d.ts +75 -4
  50. package/dist/opencode-mcp.js +2 -1
  51. package/dist/push/code-step-lookup.d.ts +6 -0
  52. package/dist/push/code-step-lookup.js +3 -1
  53. package/dist/push/collect-definitions.d.ts +13 -0
  54. package/dist/push/index.js +127 -15
  55. package/dist/push/push-from-directory.d.ts +11 -2
  56. package/dist/repo-config.d.ts +88 -30
  57. package/dist/repo-config.js +21 -5
  58. package/dist/resolve-environment.d.ts +19 -0
  59. package/dist/resolve-environment.js +19 -0
  60. package/dist/task-plane-client.d.ts +132 -22
  61. package/package.json +17 -1
  62. package/dist/chunk-2sk92cnd.js +0 -103
@@ -0,0 +1,50 @@
1
+ import { z } from "zod";
2
+ import { Environments } from "../../generated/sdk.gen";
3
+ import type { GetApiProjectsByProjectIdEnvironmentsByNameResponses, GetApiProjectsByProjectIdEnvironmentsResponses, PutApiProjectsByProjectIdEnvironmentsByNameData, PutApiProjectsByProjectIdEnvironmentsByNameResponses } from "../../generated/types.gen";
4
+ type RequestOptions = {
5
+ headers?: Record<string, unknown> | undefined;
6
+ };
7
+ export type EnvironmentSummary = GetApiProjectsByProjectIdEnvironmentsResponses[200][number];
8
+ export type EnvironmentDetail = GetApiProjectsByProjectIdEnvironmentsByNameResponses[200];
9
+ export type PublishEnvironmentContent = PutApiProjectsByProjectIdEnvironmentsByNameData["body"]["content"];
10
+ export type PublishEnvironmentResult = PutApiProjectsByProjectIdEnvironmentsByNameResponses[200];
11
+ declare const environmentContentIssueSchema: z.ZodObject<{
12
+ path: z.ZodString;
13
+ message: z.ZodString;
14
+ }, z.core.$strip>;
15
+ /** One validation error the server reports for rejected environment content. */
16
+ export type EnvironmentContentIssue = z.infer<typeof environmentContentIssueSchema>;
17
+ type ApiError = {
18
+ title?: string;
19
+ detail?: string;
20
+ code?: string;
21
+ status?: number;
22
+ errors?: unknown;
23
+ };
24
+ /**
25
+ * Thrown when the API rejects a request. `issues` carries the per-path
26
+ * validation errors of a `VALIDATION` rejection.
27
+ */
28
+ export declare class EnvironmentsApiError extends Error {
29
+ readonly code: string | undefined;
30
+ readonly status: number | undefined;
31
+ readonly issues: readonly EnvironmentContentIssue[];
32
+ constructor(error: ApiError);
33
+ }
34
+ export type EnvironmentsClient = ReturnType<typeof buildEnvironmentsClient>;
35
+ export declare function createEnvironmentsClient(baseUrl: string): EnvironmentsClient;
36
+ declare const buildEnvironmentsClient: (environments: Environments) => {
37
+ listByProjectId: (projectId: string, options?: RequestOptions) => Promise<EnvironmentSummary[]>;
38
+ /** The latest version's content, or version `options.version` when given. */
39
+ get: (projectId: string, name: string, options?: RequestOptions & {
40
+ version?: number;
41
+ }) => Promise<EnvironmentDetail>;
42
+ /**
43
+ * Publishes `content` as the environment's next version, creating the
44
+ * environment when the name is new or deleted. `published` is false when it
45
+ * matched the latest version.
46
+ */
47
+ publish: (projectId: string, name: string, content: PublishEnvironmentContent, options?: RequestOptions) => Promise<PublishEnvironmentResult>;
48
+ delete: (projectId: string, name: string, options?: RequestOptions) => Promise<void>;
49
+ };
50
+ export {};
@@ -0,0 +1,6 @@
1
+ export * from "./define-environment";
2
+ export * from "./environments-client";
3
+ export { Env, type EnvEntry, type EnvInherit, type EnvRecord, type EnvSecret, type EnvValue, } from "../steps/env";
4
+ export { Runtime, type DevcontainerRuntimeSpec, type HostRuntimeSpec, type ManagedRuntimeSpec, type RuntimeSpec, } from "../steps/runtime";
5
+ export { environmentContentSchema, type EnvironmentContentInput, } from "../../environment";
6
+ export { isEnvironmentHandle } from "../../push/code-step-lookup";
@@ -0,0 +1,97 @@
1
+ // @bun
2
+ import {
3
+ EnvironmentsApiError,
4
+ createEnvironmentsClient
5
+ } from "../../chunk-mmy80pec.js";
6
+ import {
7
+ Env,
8
+ Runtime,
9
+ assertNoSetupVarsOnHost,
10
+ compileConnectors,
11
+ normalizeEnv
12
+ } from "../../chunk-t1dq2c2s.js";
13
+ import {
14
+ isEnvironmentHandle
15
+ } from "../../chunk-6tra3gw8.js";
16
+ import {
17
+ environmentContentSchema,
18
+ environmentNameSchema
19
+ } from "../../chunk-e0pt5x0e.js";
20
+ import"../../chunk-098740f7.js";
21
+ import"../../chunk-46wmsgv7.js";
22
+ import {
23
+ findMissingConnectorVars
24
+ } from "../../chunk-qgkx89eg.js";
25
+ import"../../chunk-pqtd0hr7.js";
26
+ import {
27
+ containsInputToken
28
+ } from "../../chunk-aemxz9r7.js";
29
+ import"../../chunk-3zp2qtf8.js";
30
+ import"../../chunk-yf15kdte.js";
31
+ import"../../chunk-y64skrwp.js";
32
+
33
+ // src/definitions/environments/define-environment.ts
34
+ function compileContent(owner, config) {
35
+ if (typeof config.vars === "function") {
36
+ throw new Error(`${owner}: vars must be a record; an environment is shared across steps with different inputs, so it has no function form.`);
37
+ }
38
+ const vars = normalizeEnv(config.vars);
39
+ const tokenVar = (vars ?? []).find((entry) => [
40
+ entry.source === "value" ? entry.value : undefined,
41
+ entry.source === "inherit" ? entry.default : undefined
42
+ ].some((value) => value !== undefined && containsInputToken(value)));
43
+ if (tokenVar !== undefined) {
44
+ throw new Error(`${owner} env "${tokenVar.name}": an environment is shared across steps with different inputs, so it cannot use {{input.\u2026}} tokens. Put input-dependent vars on the step's inline environment.`);
45
+ }
46
+ assertNoSetupVarsOnHost(vars, config.runtime, owner);
47
+ const connectors = compileConnectors(config.connectors, owner);
48
+ assertConnectorVars(owner, connectors ?? [], vars ?? []);
49
+ const parsed = environmentContentSchema.safeParse({
50
+ ...config.description === undefined ? {} : { description: config.description },
51
+ ...config.runtime === undefined ? {} : { runtime: config.runtime },
52
+ ...vars === null ? {} : { vars },
53
+ ...connectors === undefined ? {} : { connectors }
54
+ });
55
+ if (parsed.success)
56
+ return parsed.data;
57
+ throw new Error(`${owner}: ${parsed.error.issues.map((issue) => issue.path.length > 0 ? `${issue.path.map(String).join(".")}: ${issue.message}` : issue.message).join("; ")}`);
58
+ }
59
+ function assertConnectorVars(owner, connectors, vars) {
60
+ const missing = findMissingConnectorVars(connectors, vars);
61
+ if (missing.length === 0)
62
+ return;
63
+ throw new Error(`${owner} is missing variables its connectors need: ${missing.map(({ connector, vars: vars2 }) => `${connector} needs ${vars2.join(", ")}`).join("; ")}. Add them to the environment's vars.`);
64
+ }
65
+ function defineEnvironment(config) {
66
+ const owner = `Environment "${config.name}"`;
67
+ const name = environmentNameSchema.safeParse(config.name);
68
+ if (!name.success) {
69
+ throw new Error(`${owner}: name ${name.error.issues.map((issue) => issue.message).join("; ")}`);
70
+ }
71
+ if ("branch" in config) {
72
+ throw new Error(`${owner}: environments have no branch; use the step's repo baseBranch.`);
73
+ }
74
+ let content;
75
+ try {
76
+ content = compileContent(owner, config);
77
+ } catch (error) {
78
+ if (error instanceof Error && !error.message.startsWith(owner)) {
79
+ throw new Error(`${owner}: ${error.message}`, { cause: error });
80
+ }
81
+ throw error;
82
+ }
83
+ return Object.freeze({
84
+ kind: "environment",
85
+ name: name.data,
86
+ content
87
+ });
88
+ }
89
+ export {
90
+ Env,
91
+ EnvironmentsApiError,
92
+ Runtime,
93
+ createEnvironmentsClient,
94
+ defineEnvironment,
95
+ environmentContentSchema,
96
+ isEnvironmentHandle
97
+ };
@@ -5,8 +5,8 @@ import {
5
5
  WORK_ITEM_TOP_LEVEL_FIELDS,
6
6
  createPipelineDefinitionsClient,
7
7
  resolveWorkItemFieldPath
8
- } from "../../chunk-1wnv6rb2.js";
9
- import"../../chunk-r03knh9j.js";
8
+ } from "../../chunk-ymywp5ht.js";
9
+ import"../../chunk-3zp2qtf8.js";
10
10
  import"../../chunk-yf15kdte.js";
11
11
  import"../../chunk-y64skrwp.js";
12
12
  export {
@@ -1,19 +1,10 @@
1
- import type { EnvVarSpec, EnvVarsInput } from "../../env-vars";
1
+ import type { EnvVarsInput } from "../../env-vars";
2
2
  import type { HealthChecksInput } from "../../health-checks";
3
3
  import type { OpenCodeMcpServers } from "../../opencode-mcp";
4
4
  import { type McpHandle } from "./define-mcp";
5
- /**
6
- * Compiles a step's `mcps` (`defineMcp` handles keyed by the step's server
7
- * key) into the wire fields, and merges them with the step's own
8
- * `healthChecks` and `environment.vars`.
9
- */
10
- type InheritEnvVarSpec = Extract<EnvVarSpec, {
11
- source: "inherit";
12
- }>;
13
5
  export type CompiledMcps = {
14
6
  opencodeMcpJson: OpenCodeMcpServers;
15
7
  healthChecks: HealthChecksInput;
16
- envEntries: InheritEnvVarSpec[];
17
8
  };
18
9
  export type StepMcpFields = {
19
10
  opencodeMcpJson: OpenCodeMcpServers | null;
@@ -22,13 +13,18 @@ export type StepMcpFields = {
22
13
  };
23
14
  /** Throws when a value under `mcps` is not a `defineMcp` handle. */
24
15
  export declare function compileMcps(mcps: Readonly<Record<string, McpHandle>>, stepKey: string): CompiledMcps;
16
+ /**
17
+ * Throws when a step `mcps` key reuses a connector id of the step's
18
+ * environment handle. A name-only environment is checked at publish and
19
+ * startup instead.
20
+ */
21
+ export declare function assertNoConnectorMcpCollisions(stepKey: string, environment: unknown, mcps: Readonly<Record<string, McpHandle>> | undefined): void;
25
22
  /**
26
23
  * Merges compiled `mcps` into the step's own fields: MCP checks run before the
27
- * step's own, and a step var replaces an MCP var of the same name.
24
+ * step's own. Variable declarations stay on each server until worker resolution.
28
25
  */
29
26
  export declare function mergeStepMcps(stepKey: string, input: {
30
27
  mcps: Readonly<Record<string, McpHandle>> | undefined;
31
28
  healthChecks: HealthChecksInput | null | undefined;
32
29
  envJson: EnvVarsInput | null;
33
30
  }): StepMcpFields;
34
- export {};
@@ -2,8 +2,10 @@ import type { ZodType } from "zod";
2
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
- import { type CodeStepEnvironment } from "./runtime";
5
+ import { type InlineCodeStepEnvironment, type NamedStepEnvironment } from "./runtime";
6
+ import type { EnvRecord, PromptEnvContext } from "./env";
6
7
  import type { CodeStepFeature } from "./step-features";
8
+ import { type RepoField, type RepoSpec } from "./repo";
7
9
  /** What the worker passes a code step besides its input. */
8
10
  export type CodeStepContext = {
9
11
  /**
@@ -14,7 +16,7 @@ export type CodeStepContext = {
14
16
  artifactsDir: string;
15
17
  };
16
18
  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<CodeStepFeature> = never[]> = {
19
+ export type DefineCodeStepInput<TInput extends ZodType = ZodType, TResult extends ZodType = ZodType, TFeatures extends ReadonlyArray<CodeStepFeature> = never[], TEnv extends EnvRecord = EnvRecord, TNamed extends NamedStepEnvironment | undefined = NamedStepEnvironment | undefined> = {
18
20
  key: string;
19
21
  name: string;
20
22
  description?: string | null;
@@ -43,23 +45,28 @@ export type DefineCodeStepInput<TInput extends ZodType = ZodType, TResult extend
43
45
  */
44
46
  features?: TFeatures;
45
47
  /**
46
- * Where the step's runner executes (`runtime`) and the environment variables
47
- * it receives (`vars`). The function reads the variables back through
48
- * `process.env`; unlike `defineStep()`, there is no typed `env` argument to
49
- * `fn`.
48
+ * A named environment (its name or `defineEnvironment` handle), or inline
49
+ * runtime and environment variables (`vars`).
50
+ * The function reads the variables back through `process.env`; unlike
51
+ * `defineStep()`, there is no typed `env` argument to `fn`.
50
52
  *
51
- * Omitting `runtime` compiles to `Runtime.managed.bun1()`, a worker-supplied
52
- * container. `Runtime.devcontainer()` opts into the project's own container,
53
- * which must then provide a JS runtime for the runner script.
53
+ * For an inline environment, omitting `runtime` compiles to
54
+ * `Runtime.managed.bun1()`, a worker-supplied container.
55
+ * `Runtime.devcontainer()` opts into the project's own container, which must
56
+ * then provide a JS runtime for the runner script.
54
57
  *
55
58
  * `Runtime.host()` is not supported: a code step runs repo code, so it needs
56
59
  * a workspace, and the host runtime has none. It is a type error here and
57
60
  * `validateDefinitionSpecs` rejects it for hand-built specs.
61
+ * A handle whose runtime is host throws here; a name's runtime is checked by
62
+ * the worker after resolution.
58
63
  *
59
64
  * `repo` follows the same rules as for `defineStep()`; `result` is typed from
60
65
  * `resultSchema`.
61
66
  */
62
- environment?: CodeStepEnvironment<TInput["_output"], TResult["_output"]>;
67
+ environment?: InlineCodeStepEnvironment<TInput["_output"], TEnv> | TNamed;
68
+ /** `env` is typed from the environment as `defineStep()`'s prompt `env` is. */
69
+ repo?: RepoField<TInput["_output"], TResult["_output"], RepoSpec, PromptEnvContext<TEnv, TNamed>>;
63
70
  status?: "draft" | "active";
64
71
  /**
65
72
  * Error names this step can fail with, beyond the built-in ones. A
@@ -78,7 +85,7 @@ export type DefineCodeStepInput<TInput extends ZodType = ZodType, TResult extend
78
85
  * `entrypoint.fn` reference attached instead — see `StepDefinitionSpec`'s
79
86
  * own doc comment for what happens to it during collection.
80
87
  */
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"> & {
88
+ export declare function codeStep<TInput extends ZodType = ZodType, TResult extends ZodType = ZodType, const TFeatures extends ReadonlyArray<CodeStepFeature> = never[], const TErrors extends string = never, TEnv extends EnvRecord = EnvRecord, TNamed extends NamedStepEnvironment | undefined = undefined>(config: Omit<DefineCodeStepInput<TInput, TResult, TFeatures, TEnv, TNamed>, "errors" | "retry"> & {
82
89
  errors?: readonly TErrors[];
83
90
  retry?: readonly {
84
91
  on: readonly (BuiltInError | TErrors)[];
@@ -3,29 +3,30 @@ import type { AnyStepFeature, FeatureResultExtensions, Grant } from "./step-feat
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";
6
- import type { EnvVarsInput } from "../../env-vars";
7
6
  import type { RepoConfigInput } from "../../repo-config";
8
7
  import type { EnvRecord, PromptEnvContext } from "./env";
9
- import { type StepEnvironment } from "./runtime";
8
+ import { type CompiledEnvironment, type InlineStepEnvironment, type NamedStepEnvironment } from "./runtime";
9
+ import { type RepoField, type RepoSpec } from "./repo";
10
10
  import type { McpHandle } from "./define-mcp";
11
11
  import type { BuiltInError, ConversationResult } from "../../pipelines/types";
12
12
  import { type StepHandle } from "./step-handle";
13
13
  type Prettify<T> = {
14
14
  [K in keyof T]: T[K];
15
15
  } & {};
16
- export type DefineStepInput<TInput extends ZodType = ZodType, TResult extends ZodType = ZodType, TEnv extends EnvRecord = EnvRecord> = {
16
+ export type DefineStepInput<TInput extends ZodType = ZodType, TResult extends ZodType = ZodType, TEnv extends EnvRecord = EnvRecord, TNamed extends NamedStepEnvironment | undefined = NamedStepEnvironment | undefined> = {
17
17
  key: string;
18
18
  name: string;
19
19
  description?: string | null;
20
20
  version?: number;
21
21
  /**
22
- * Where the step runs (`runtime`), its environment variables (`vars`) and what
23
- * it may do to the repository (`repo`). Declare it before `agentPrompt` so
24
- * `TEnv` is inferred from `vars` into the prompt's `env`, which is then
25
- * strict: only declared, non-secret keys.
22
+ * A named environment, by name or by `defineEnvironment` handle, or an
23
+ * inline runtime, checkout branch and variables (`vars`). Declare it before
24
+ * `agentPrompt` and a `repo` function so their `env` is typed from the
25
+ * handle's or the inline `vars`: only declared, non-secret keys.
26
26
  */
27
- environment?: StepEnvironment<TInput["_output"], TEnv, TResult["_output"]>;
28
- agentPrompt: string | ((context: PromptTemplateContext<TInput["_output"], PromptEnvContext<TEnv>>) => string);
27
+ environment?: InlineStepEnvironment<TInput["_output"], TEnv> | TNamed;
28
+ repo?: RepoField<TInput["_output"], TResult["_output"], RepoSpec, PromptEnvContext<TEnv, TNamed>>;
29
+ agentPrompt: string | ((context: PromptTemplateContext<TInput["_output"], PromptEnvContext<TEnv, TNamed>>) => string);
29
30
  input?: TInput;
30
31
  result?: TResult;
31
32
  features?: AnyStepFeature[];
@@ -91,21 +92,10 @@ export type StepDefinitionSpec = {
91
92
  version: number;
92
93
  kind: "user_defined" | "code";
93
94
  status: "draft" | "active" | "archived";
94
- executionMode?: "workspace" | "no_workspace";
95
+ environment: CompiledEnvironment;
95
96
  /**
96
- * Repo-relative path of the devcontainer config to launch; `null` or omitted
97
- * means auto-detect. Only valid with `executionMode: "workspace"`.
98
- */
99
- devcontainerConfigPath?: string | null;
100
- /**
101
- * Identifier of the worker-supplied managed runtime (`Runtime.managed.<id>()`);
102
- * `null` or omitted means not managed. Only valid on a `code` step with
103
- * `executionMode: "workspace"` and no `devcontainerConfigPath`.
104
- */
105
- managedRuntime?: string | null;
106
- /**
107
- * Repository access. Omitted means the runtime's default (`readWrite` for
108
- * `workspace`, `none` for `no_workspace`), which the server resolves.
97
+ * Repository access. Omitted means the server resolves the default; shared
98
+ * repo resolution defaults to `readWrite` for every runtime.
109
99
  */
110
100
  repo?: RepoConfigInput;
111
101
  prompt: string | null;
@@ -113,7 +103,6 @@ export type StepDefinitionSpec = {
113
103
  resultSchemaJson: Record<string, unknown> | null;
114
104
  opencodeMcpJson: OpenCodeMcpServers | null;
115
105
  healthChecksJson: HealthChecksInput | null;
116
- envJson?: EnvVarsInput | null;
117
106
  /** Error names the step declares besides the built-in ones. */
118
107
  errors?: readonly string[];
119
108
  /**
@@ -152,7 +141,7 @@ export type EffectiveResult<TResult, TFeatures extends ReadonlyArray<AnyStepFeat
152
141
  * its effective result.
153
142
  */
154
143
  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>;
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"> & {
144
+ 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, TNamed extends NamedStepEnvironment | undefined = undefined>(config: Omit<DefineStepInput<TInput, TResult, TEnv, TNamed>, "features" | "errors" | "retry"> & {
156
145
  features?: TFeatures;
157
146
  errors?: readonly TErrors[];
158
147
  retry?: readonly {
@@ -58,7 +58,13 @@ export type EnvInherit<TSecret extends boolean = boolean, TOptional extends bool
58
58
  readonly default: TDefault;
59
59
  readonly applies: EnvVarApplies;
60
60
  };
61
- export type EnvEntry = string | EnvValue | EnvInherit;
61
+ /** A project secret saved in Scarn, referenced by name. Always masked. */
62
+ export type EnvSecret = {
63
+ readonly kind: "secret";
64
+ readonly secretName: string;
65
+ readonly applies: EnvVarApplies;
66
+ };
67
+ export type EnvEntry = string | EnvValue | EnvInherit | EnvSecret;
62
68
  export type EnvRecord = Record<string, EnvEntry>;
63
69
  /** Runs once at definition time, against the same input proxy `agentPrompt` uses. */
64
70
  export type EnvFn<TInput, TEnv extends EnvRecord = EnvRecord> = (context: {
@@ -91,12 +97,19 @@ export type PromptEnv<TEnv extends EnvRecord> = {
91
97
  } ? K : never]: PromptEntryValue<TEnv[K]>;
92
98
  };
93
99
  /**
94
- * The prompt `env` type for a step: strict (`PromptEnv`) once
95
- * `environment.vars` is declared, today's loose record otherwise. Undeclared
96
- * `vars` leaves `TEnv` at its `EnvRecord` default, whose index signature is the
97
- * marker.
100
+ * The prompt `env` type for a step: a string record for an environment given
101
+ * by name, strict (`PromptEnv`) for an environment handle or once inline
102
+ * `environment.vars` is declared, and an optional string record otherwise.
103
+ * Undeclared `vars` leaves `TEnv` at its `EnvRecord` default, whose index
104
+ * signature is the marker; a handle typed as plain `EnvironmentHandle` (vars
105
+ * unknown) gets the string record. `TNamed` is the step's named environment,
106
+ * if any.
98
107
  */
99
- export type PromptEnvContext<TEnv extends EnvRecord> = string extends keyof TEnv ? PromptInputProxy<Record<string, string | undefined>> : PromptEnv<TEnv>;
108
+ export type PromptEnvContext<TEnv extends EnvRecord, TNamed extends string | {
109
+ readonly __env: EnvRecord;
110
+ } | undefined = undefined> = [TNamed] extends [string] ? Record<string, string> : [TNamed] extends [{
111
+ readonly __env: infer THandleEnv extends EnvRecord;
112
+ }] ? string extends keyof THandleEnv ? Record<string, string> : PromptEnv<THandleEnv> : string extends keyof TEnv ? PromptInputProxy<Record<string, string | undefined>> : PromptEnv<TEnv>;
100
113
  export declare const Env: {
101
114
  /**
102
115
  * A literal or `{{input.…}}` template value. Same as writing a bare string,
@@ -126,11 +139,20 @@ export declare const Env: {
126
139
  * example to steer the repo's `initializeCommand`.
127
140
  */
128
141
  readonly inherit: <const O extends InheritOpts = Record<never, never>>(opts?: O) => EnvInherit<SecretOf<O>, OptionalOf<O>, DefaultOf<O>>;
142
+ /**
143
+ * Reads a project secret saved in Scarn, looked up by `secretName` at run
144
+ * time (the worker's `.scarn/.env` first, then Scarn; never `process.env`).
145
+ * The variable name comes from the key and may differ from the secret name.
146
+ *
147
+ * - Stored: only the secret's name.
148
+ * - Masked: always. A secret variable has no default.
149
+ */
150
+ readonly secret: (secretName: string, opts?: EnvAppliesOpt) => EnvSecret;
129
151
  };
130
152
  /**
131
- * Runs the authored `environment.vars` function once and returns the wire
153
+ * Evaluates the authored `environment.vars` record or function once and returns the wire
132
154
  * shape, or `null` when the step declares no `vars` (or an empty record).
133
155
  * Throws on a static secret, or a static literal on a secret-looking name.
134
156
  */
135
- export declare function normalizeEnv<TInput>(fn: EnvFn<TInput> | undefined): EnvVarsInput | null;
157
+ export declare function normalizeEnv<TInput>(fn: EnvFn<TInput> | EnvRecord | undefined): EnvVarsInput | null;
136
158
  export {};
@@ -3,22 +3,19 @@ import {
3
3
  ARTIFACT_BRAND,
4
4
  Artifact,
5
5
  ArtifactTypes,
6
- Env,
7
6
  Features,
8
7
  Notify,
9
8
  Repo,
10
- Runtime,
9
+ WorkBranch,
11
10
  artifact,
11
+ assertBaseBranchFitsEnvironment,
12
12
  codeStep,
13
- compileEnvironment,
14
13
  compileMcps,
15
14
  compileRepo,
16
15
  compileStepConcurrency,
17
16
  compileStepErrors,
18
17
  compileStepMaxTurns,
19
18
  compileStepRetry,
20
- createPromptInputProxy,
21
- createPromptTemplateContext,
22
19
  createStepDefinitionsClient,
23
20
  defineMcp,
24
21
  defineStep,
@@ -26,23 +23,37 @@ import {
26
23
  grantActionValues,
27
24
  grantScopeValues,
28
25
  isMcpHandle,
29
- isSecretLookingEnvName,
30
26
  normalizeArtifactAccept,
31
- normalizeEnv,
32
- renderPromptTemplate,
33
27
  resolveMcpChecks,
28
+ stepEnvironmentHandle,
34
29
  toStepHandle,
35
30
  toStepSpec
36
- } from "../../chunk-a04phj60.js";
37
- import"../../chunk-cdj0yqgs.js";
31
+ } from "../../chunk-833ef6dg.js";
38
32
  import"../../chunk-y34zsgsw.js";
33
+ import {
34
+ Env,
35
+ Runtime,
36
+ assertNoSetupVarsOnHost,
37
+ compileConnectors,
38
+ compileEnvironment,
39
+ createPromptInputProxy,
40
+ createPromptTemplateContext,
41
+ isSecretLookingEnvName,
42
+ knownEnvironmentVars,
43
+ normalizeEnv,
44
+ renderPromptTemplate
45
+ } from "../../chunk-t1dq2c2s.js";
46
+ import"../../chunk-6tra3gw8.js";
39
47
  import"../../chunk-jj9pezwb.js";
40
48
  import"../../chunk-y11p1q7r.js";
41
- import"../../chunk-2ekz6tr5.js";
49
+ import"../../chunk-rphfy0fj.js";
50
+ import"../../chunk-e0pt5x0e.js";
42
51
  import"../../chunk-098740f7.js";
43
52
  import"../../chunk-46wmsgv7.js";
44
- import"../../chunk-2sk92cnd.js";
45
- import"../../chunk-r03knh9j.js";
53
+ import"../../chunk-qgkx89eg.js";
54
+ import"../../chunk-pqtd0hr7.js";
55
+ import"../../chunk-aemxz9r7.js";
56
+ import"../../chunk-3zp2qtf8.js";
46
57
  import"../../chunk-ngy1fdcx.js";
47
58
  import"../../chunk-19brnwkp.js";
48
59
  import"../../chunk-01nfqm18.js";
@@ -57,8 +68,12 @@ export {
57
68
  Notify,
58
69
  Repo,
59
70
  Runtime,
71
+ WorkBranch,
60
72
  artifact,
73
+ assertBaseBranchFitsEnvironment,
74
+ assertNoSetupVarsOnHost,
61
75
  codeStep,
76
+ compileConnectors,
62
77
  compileEnvironment,
63
78
  compileMcps,
64
79
  compileRepo,
@@ -75,10 +90,12 @@ export {
75
90
  grantScopeValues,
76
91
  isMcpHandle,
77
92
  isSecretLookingEnvName,
93
+ knownEnvironmentVars,
78
94
  normalizeArtifactAccept,
79
95
  normalizeEnv,
80
96
  renderPromptTemplate,
81
97
  resolveMcpChecks,
98
+ stepEnvironmentHandle,
82
99
  toStepHandle,
83
100
  toStepSpec,
84
101
  exports_z as z
@@ -5,12 +5,22 @@ declare const refFieldsSchema: z.ZodObject<{
5
5
  catalog: z.ZodOptional<z.ZodInt>;
6
6
  execution: z.ZodOptional<z.ZodInt>;
7
7
  }, z.core.$strict>>;
8
+ workerVars: z.ZodOptional<z.ZodArray<z.ZodObject<{
9
+ name: z.ZodString;
10
+ source: z.ZodLiteral<"inherit">;
11
+ from: z.ZodString;
12
+ secret: z.ZodBoolean;
13
+ optional: z.ZodBoolean;
14
+ default: z.ZodOptional<z.ZodString>;
15
+ mcp: z.ZodOptional<z.ZodString>;
16
+ applies: z.ZodLiteral<"agent">;
17
+ }, z.core.$strict>>>;
18
+ codemode: z.ZodOptional<z.ZodBoolean>;
8
19
  protocol: z.ZodOptional<z.ZodEnum<{
9
20
  auto: "auto";
10
21
  legacy: "legacy";
11
22
  "2026-07-28": "2026-07-28";
12
23
  }>>;
13
- codemode: z.ZodOptional<z.ZodBoolean>;
14
24
  }, z.core.$strict>;
15
25
  declare const localFieldsSchema: z.ZodObject<{
16
26
  timeout: z.ZodOptional<z.ZodObject<{
@@ -19,14 +29,14 @@ declare const localFieldsSchema: z.ZodObject<{
19
29
  execution: z.ZodOptional<z.ZodInt>;
20
30
  }, z.core.$strict>>;
21
31
  command: z.ZodArray<z.ZodString>;
32
+ cwd: z.ZodOptional<z.ZodString>;
33
+ environment: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
34
+ codemode: z.ZodOptional<z.ZodBoolean>;
22
35
  protocol: z.ZodOptional<z.ZodEnum<{
23
36
  auto: "auto";
24
37
  legacy: "legacy";
25
38
  "2026-07-28": "2026-07-28";
26
39
  }>>;
27
- cwd: z.ZodOptional<z.ZodString>;
28
- environment: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
29
- codemode: z.ZodOptional<z.ZodBoolean>;
30
40
  }, z.core.$strict>;
31
41
  declare const remoteFieldsSchema: z.ZodObject<{
32
42
  headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
@@ -36,11 +46,6 @@ declare const remoteFieldsSchema: z.ZodObject<{
36
46
  catalog: z.ZodOptional<z.ZodInt>;
37
47
  execution: z.ZodOptional<z.ZodInt>;
38
48
  }, z.core.$strict>>;
39
- protocol: z.ZodOptional<z.ZodEnum<{
40
- auto: "auto";
41
- legacy: "legacy";
42
- "2026-07-28": "2026-07-28";
43
- }>>;
44
49
  oauth: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
45
50
  client_id: z.ZodOptional<z.ZodString>;
46
51
  client_secret: z.ZodOptional<z.ZodString>;
@@ -50,6 +55,11 @@ declare const remoteFieldsSchema: z.ZodObject<{
50
55
  auth_server_metadata_url: z.ZodOptional<z.ZodString>;
51
56
  }, z.core.$strict>, z.ZodLiteral<false>]>>;
52
57
  codemode: z.ZodOptional<z.ZodBoolean>;
58
+ protocol: z.ZodOptional<z.ZodEnum<{
59
+ auto: "auto";
60
+ legacy: "legacy";
61
+ "2026-07-28": "2026-07-28";
62
+ }>>;
53
63
  }, z.core.$strict>;
54
64
  /** The shared OpenCode fields a `ref` applies on top of the repo's definition. */
55
65
  export type McpRefServerFields = z.output<typeof refFieldsSchema>;