@relayflows/sdk 2.0.0

package/dist/protocol.d.ts

@@ -0,0 +1,359 @@
+import type { KernelRunSpec, StepType } from './spec.js';
+/** Stamped per segment; readers read every past version, writers write newest. */
+export declare const PROTOCOL_VERSION: 0;
+/** A journal append that fails fails the step (AGENTS.md rule 4). */
+export declare const JOURNAL_WRITE_FAILED: "journal_write_failed";
+export type ProtocolError = {
+    code: string;
+    message: string;
+};
+/** Client -> server. */
+export interface Request<P = unknown> {
+    id: string;
+    verb: string;
+    params: P;
+}
+/** Server -> client response, correlated by `id`. */
+export type Response<R = unknown> = {
+    id: string;
+    ok: true;
+    result: R;
+} | {
+    id: string;
+    ok: false;
+    error: ProtocolError;
+};
+/** Server -> client push (no `id`). */
+export interface ServerEvent {
+    event: string;
+    data: unknown;
+}
+export type Verb = 'hello' | 'run.start' | 'run.resume' | 'run.cancel' | 'run.get' | 'run.watch' | 'worker.attach' | 'step.heartbeat' | 'effect.record' | 'effect.confirm' | 'step.complete' | 'event.emit' | 'event.submit' | 'stream.append' | 'stream.read' | 'journal.read';
+export interface HelloParams {
+    protocol: 0;
+    client: string;
+}
+export interface HelloResult {
+    protocol: 0;
+    server: string;
+}
+export interface RunStartParams {
+    /**
+     * The kernel spec dialect — the ONE boundary shape `RunSpec::parse`
+     * accepts (snake_case, flat v0 verification, defaults materialized).
+     * The authoring `FlowSpec` never crosses the wire; `JournalClient.runStart`
+     * converts via `toKernelSpec`.
+     */
+    spec: KernelRunSpec;
+}
+export type RunStatus = 'running' | 'completed' | 'failed' | 'interrupted' | 'parked';
+export type RunCompletionReason = 'success' | 'step_failed' | 'canceled' | 'budget_exceeded';
+export interface RunOutcome {
+    run_id: string;
+    status: RunStatus;
+    completion_reason: RunCompletionReason | null;
+    completed_steps: number;
+}
+export type RunStartResult = RunOutcome;
+export interface RunResumeParams {
+    run_id: string;
+}
+export type RunResumeResult = RunOutcome;
+export interface RunCancelParams {
+    run_id: string;
+}
+export type RunCancelResult = RunOutcome;
+export interface RunGetParams {
+    run_id: string;
+}
+export type StepStatus = 'pending' | 'runnable' | 'running' | 'backoff' | 'waiting' | 'needs_human' | 'done';
+export interface StepSnapshot {
+    type: StepType;
+    state: StepStatus;
+    lease_deadline_ms?: number;
+}
+export interface RunGetResult {
+    run_id: string;
+    status: RunStatus;
+    steps: Record<string, StepSnapshot>;
+    budget: {
+        tokens_in: number;
+        tokens_out: number;
+        dollars: string;
+    };
+}
+export interface RunWatchParams {
+    run_id: string;
+}
+export interface RunWatchResult {
+    watching: string;
+}
+/** `run.watch` opens a push stream of `{event: "entry", data: Entry}`. */
+export interface WorkerAttachParams {
+    worker_id: string;
+    step_types: StepType[];
+    /** Maximum concurrent assignments. Omitted means the conservative default 1. */
+    capacity?: number;
+    /**
+     * The surfaces this worker holds, as opaque revisions/offsets. Required when
+     * `step_types` includes `agent` — an agent attempt's start pins come from
+     * here (Appendix A rule 2), so an agent worker with no pins is refused at
+     * attach rather than failing in the middle of a run.
+     */
+    pins?: Pins;
+}
+export interface WorkerAttachResult {
+    worker_id: string;
+}
+/**
+ * Wake-context payload assembled kernel-side at `subscription.matched`.
+ * The two fields typed below are the ones every current consumer keys
+ * against; additional kernel-side fields flow through as extra
+ * properties without breaking this type.
+ */
+export interface WakeContext {
+    triggering_event?: {
+        type: string;
+        payload?: unknown;
+    };
+    epoch_summary?: {
+        open_steps?: string[];
+    };
+    [additionalKernelFields: string]: unknown;
+}
+/** Server then pushes `step.dispatch` events to the attached worker. */
+export interface StepDispatchEvent {
+    run_id: string;
+    step_id: string;
+    attempt: number;
+    step_type: StepType;
+    spec: unknown;
+    lease_id: string;
+    idempotency_key: string;
+    pins: Pins;
+    /**
+     * The `wake_context` payload from the run's `subscription.matched`
+     * journal entry — carries the triggering event and any epoch summary
+     * the flow needs to know why this step is running. Present when the
+     * run was spawned by an event; `undefined` for runs started directly
+     * (no trigger fired). A real agent needs this to see the event
+     * payload (e.g. the HN story ID).
+     *
+     * Shape is assembled kernel-side in
+     * `kernel/relayflowd/src/engine/wake.rs` (grep for
+     * `wake_context` — the Rust field is written with quoted
+     * JSON keys so `"wake_context":` hits the assembly site
+     * directly). The narrow type below pins the two fields
+     * every consumer currently reads —
+     * `triggering_event.type`/`payload` and `epoch_summary` — while
+     * keeping the container `unknown`-permissive so a kernel-side
+     * addition (a new nested field) does not break the SDK type. A
+     * kernel-side RENAME of these two fields does break every
+     * consumer; that is deliberate and preferable to silent drift.
+     */
+    wake_context?: WakeContext;
+    recovery?: {
+        mode: 'reset' | 'inspect' | 'manual';
+        restore_pins?: Pins;
+        previous_completion_reason?: CompletionReason;
+        trajectory_tail?: unknown;
+    };
+    lease_deadline_ms: number;
+}
+export interface StepHeartbeatParams {
+    run_id: string;
+    step_id: string;
+    attempt: number;
+    lease_id: string;
+}
+export interface StepHeartbeatResult {
+    lease_deadline_ms: number;
+}
+/** completionReason mirrors kernel DESIGN.md §1.3. */
+export type CompletionReason = 'success' | 'verification_failed' | 'retries_exhausted' | 'lease_expired' | 'crashed' | 'timeout' | 'worker_error' | 'budget_exceeded' | 'canceled';
+export interface Pins {
+    workspace?: {
+        surface: string;
+        revision_id: string;
+    }[];
+    streams?: {
+        stream: string;
+        read_offset: number;
+    }[];
+}
+export interface EffectRef {
+    surface_path: string;
+    idempotency_key: string;
+}
+export interface EffectRecordParams {
+    run_id: string;
+    step_id: string;
+    attempt: number;
+    idempotency_key: string;
+    surface_path: string;
+    revision_before: string;
+    revision_after: string;
+}
+export interface EffectRecordResult {
+    /**
+     * True only when a *confirmed* election already covers this
+     * `(step_id, idempotency_key, surface_path)`: the writeback provably
+     * happened, so this attempt must not call the provider. An election that was
+     * never confirmed does not dedupe — this attempt reclaims it and owes the
+     * call, which is what keeps an effect from being lost to a worker that died
+     * between recording and performing.
+     */
+    deduped: boolean;
+}
+/** Phase two: the elected attempt performed the writeback. */
+export interface EffectConfirmParams {
+    run_id: string;
+    step_id: string;
+    attempt: number;
+    idempotency_key: string;
+    surface_path: string;
+}
+export interface EffectConfirmResult {
+    confirmed: string;
+}
+export interface StepCompleteParams {
+    run_id: string;
+    step_id: string;
+    attempt: number;
+    idempotency_key: string;
+    completionReason: CompletionReason;
+    output?: unknown;
+    usage?: {
+        tokens_in: number;
+        tokens_out: number;
+        dollars: string;
+    };
+    started_pins?: Pins;
+    end_pins?: Pins;
+    effects?: EffectRef[];
+    /** `inspect` evidence for the next attempt. Rejected over 16 KiB of JSON. */
+    trajectory_tail?: unknown;
+}
+export type StepCompleteResult = RunOutcome;
+export interface EventEmitParams {
+    run_id: string;
+    event_key: string;
+    payload: unknown;
+}
+export interface EventEmitResult {
+    matched: number;
+}
+/**
+ * Submit an external event to a flow that declares an event trigger. The
+ * kernel matches it against the spec's subscriptions and, on a first match,
+ * spawns a run; a repeat of the same (flow, subscription, key) is deduped.
+ */
+export interface EventSubmitParams {
+    spec: unknown;
+    event: {
+        type: string;
+        payload?: unknown;
+        /** Overrides the subscription's dedupeKeyTemplate when supplied. */
+        key?: string;
+    };
+}
+export interface EventSubmitResult {
+    matched: boolean;
+    deduped: boolean;
+    subscription_id?: string | null;
+    run?: unknown;
+}
+export interface StreamAppendParams {
+    run_id: string;
+    stream: string;
+    message: unknown;
+}
+export interface StreamAppendResult {
+    offset: number;
+}
+export interface StreamReadParams {
+    run_id: string;
+    stream: string;
+    from_offset: number;
+    limit?: number;
+}
+export interface StreamReadResult {
+    messages: unknown[];
+    next_offset: number;
+}
+export interface JournalReadParams {
+    run_id: string;
+    from_seq: number;
+    limit?: number;
+}
+export interface JournalReadResult {
+    entries: unknown[];
+}
+/** Typed map of verb -> { params, result }. Used by the client for type-safety. */
+export interface VerbContract {
+    hello: {
+        params: HelloParams;
+        result: HelloResult;
+    };
+    'run.start': {
+        params: RunStartParams;
+        result: RunStartResult;
+    };
+    'run.resume': {
+        params: RunResumeParams;
+        result: RunResumeResult;
+    };
+    'run.cancel': {
+        params: RunCancelParams;
+        result: RunCancelResult;
+    };
+    'run.get': {
+        params: RunGetParams;
+        result: RunGetResult;
+    };
+    'run.watch': {
+        params: RunWatchParams;
+        result: RunWatchResult;
+    };
+    'worker.attach': {
+        params: WorkerAttachParams;
+        result: WorkerAttachResult;
+    };
+    'step.heartbeat': {
+        params: StepHeartbeatParams;
+        result: StepHeartbeatResult;
+    };
+    'effect.record': {
+        params: EffectRecordParams;
+        result: EffectRecordResult;
+    };
+    'effect.confirm': {
+        params: EffectConfirmParams;
+        result: EffectConfirmResult;
+    };
+    'step.complete': {
+        params: StepCompleteParams;
+        result: StepCompleteResult;
+    };
+    'event.emit': {
+        params: EventEmitParams;
+        result: EventEmitResult;
+    };
+    'event.submit': {
+        params: EventSubmitParams;
+        result: EventSubmitResult;
+    };
+    'stream.append': {
+        params: StreamAppendParams;
+        result: StreamAppendResult;
+    };
+    'stream.read': {
+        params: StreamReadParams;
+        result: StreamReadResult;
+    };
+    'journal.read': {
+        params: JournalReadParams;
+        result: JournalReadResult;
+    };
+}
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"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"}

package/dist/protocol.js

@@ -0,0 +1,15 @@
+// Journal protocol v0 — the SDK boundary (kernel DESIGN.md §5).
+//
+// Transport: newline-delimited JSON over a unix socket at
+// `<data-dir>/relayflowd.sock`. Requests `{id, verb, params}`; responses
+// `{id, ok: true, result}` or `{id, ok: false, error: {code, message}}`;
+// server-pushed events `{event, data}` (no `id`). Any verb whose journal
+// append fails returns `error{code: "journal_write_failed"}` and the affected
+// step fails — the protocol is fail-closed like everything behind it.
+//
+// This module is the typed wire surface; `journal-client.ts` implements it.
+/** Stamped per segment; readers read every past version, writers write newest. */
+export const PROTOCOL_VERSION = 0;
+/** A journal append that fails fails the step (AGENTS.md rule 4). */
+export const JOURNAL_WRITE_FAILED = 'journal_write_failed';
+//# sourceMappingURL=protocol.js.map

package/dist/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,EAAE;AACF,0DAA0D;AAC1D,yEAAyE;AACzE,yEAAyE;AACzE,yEAAyE;AACzE,8EAA8E;AAC9E,sEAAsE;AACtE,EAAE;AACF,4EAA4E;AAI5E,kFAAkF;AAClF,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAU,CAAC;AAE3C,qEAAqE;AACrE,MAAM,CAAC,MAAM,oBAAoB,GAAG,sBAA+B,CAAC"}

package/dist/spec.d.ts

@@ -0,0 +1,294 @@
+import type { JsonOutputSchema } from './output-schema.js';
+export type { JsonOutputSchema } from './output-schema.js';
+/** The three rungs of the ladder (RFC §1; AGENTS.md rule 7). */
+export type StepType = 'deterministic' | 'llm' | 'agent';
+/**
+ * Verification is control flow, not decoration (kernel DESIGN.md §3).
+ * v0 gates are deterministic so verification is kernel-side and replayable.
+ */
+export type VerificationGateType = 'exit_code' | 'output_contains' | 'json_schema';
+/**
+ * `exit_code == 0` — the implicit gate for deterministic steps. v0 judges
+ * exactly zero (kernel DESIGN.md §4); it is not configurable, so this gate
+ * carries no parameters. Writing it explicitly is allowed and compiles to the
+ * same kernel spec as omitting it.
+ */
+export interface ExitCodeGate {
+    type: 'exit_code';
+}
+/** Step output (stdout_tail / llm value, stringified) contains `value`. */
+export interface OutputContainsGate {
+    type: 'output_contains';
+    value: string;
+}
+/** Step output validates against a JSON Schema. Used for `llm` structured output. */
+export interface JsonSchemaGate {
+    type: 'json_schema';
+    schema: boolean | Record<string, unknown>;
+}
+export type VerificationSpec = ExitCodeGate | OutputContainsGate | JsonSchemaGate;
+export type OutputVerificationSpec = OutputContainsGate | JsonSchemaGate;
+/**
+ * Agent-step recovery modes (RFC Appendix A rule 4). Default is `reset`.
+ * `deterministic` / `llm` steps have no workspace, so these do not apply.
+ */
+export type RecoveryMode = 'reset' | 'inspect' | 'manual';
+/**
+ * Declared mutable surfaces for an agent step (RFC Appendix A rule 1).
+ * Anything undeclared is outside the contract and outside the step's
+ * permissions (gate 8 makes this enforceable, not advisory).
+ */
+export interface WorkspaceSurface {
+    /** Relayfile mount path, or a named worktree. */
+    surface: string;
+}
+export interface StreamSurface {
+    /** Durable channel the agent may write (kernel DESIGN.md §1.8). */
+    stream: string;
+}
+export interface AgentSurfaces {
+    workspace?: WorkspaceSurface[];
+    streams?: StreamSurface[];
+    /** Integration writeback paths — mount writes per gate 6. */
+    external?: string[];
+}
+/** Permission model for an agent step (gate 8). `readonly` provably cannot write. */
+export interface PermissionsSpec {
+    fileGlobs?: string[];
+    networkAllowlist?: string[];
+    accessPreset?: 'readonly' | 'readwrite';
+}
+/**
+ * Budget envelope. Per decision #10 every token has exactly one owner: an
+ * injected context pack spends the consuming step's budget. Money is a decimal
+ * string at the boundary (kernel DESIGN.md §1: no floats for money); tokens
+ * are integers.
+ */
+export interface BudgetSpec {
+    maxTokensIn?: number;
+    maxTokensOut?: number;
+    /** Decimal string, e.g. "1.50". */
+    maxDollars?: string;
+}
+/** Fields shared by every step on the ladder. */
+export interface BaseStepSpec {
+    /** Stable step identity; journaled as `step_id` and hashed into the idempotency key. */
+    id: string;
+    type: StepType;
+    /** Step dependencies — a step runs only after these complete. */
+    dependsOn?: string[];
+    /** Semantic retry bound (kernel DESIGN.md §1.2 `max_iterations`). Default 1. */
+    maxIterations?: number;
+}
+/**
+ * Rung 1 — a pure script. Executed by the `relayflowd` binary: spawn command,
+ * capture stdout/exit code. Output = `{exit_code, stdout_tail}`. Gate-1
+ * deterministic steps are pure (no pins).
+ */
+export interface DeterministicStepSpec extends BaseStepSpec {
+    type: 'deterministic';
+    command: string;
+    /** Wall-clock command timeout; worker-backed verbs own their dispatch timeout. */
+    timeoutMs?: number;
+    /** Omit to get the implicit `exit_code` gate. */
+    verification?: VerificationSpec;
+}
+/**
+ * Rung 2 — a bare model call. No workspace, output is a value. The kernel
+ * never calls a model: it dispatches to an attached SDK worker (§5) which
+ * returns `{output, usage}`; the kernel then runs the verification gate.
+ */
+export interface LlmStepSpec extends BaseStepSpec {
+    type: 'llm';
+    prompt: string;
+    verification?: OutputVerificationSpec;
+    model?: string;
+    /** Inert preflight declaration; overrides the flow/project CLI default. */
+    cli?: string;
+    /**
+     * Structured-output authoring sugar. Compiles to the existing `json_schema`
+     * verification primitive and is removed before the kernel boundary.
+     */
+    output?: JsonOutputSchema;
+}
+/**
+ * Rung 3 — a harnessed agent in a workspace. Dispatched like `llm`, plus
+ * Appendix A in full: pins declared workspace revisions and stream offsets;
+ * every writeback is a journaled `effect.recorded` deduped by
+ * `(step_id, idempotency_key, surface_path)`.
+ */
+export interface AgentStepSpec extends BaseStepSpec {
+    type: 'agent';
+    instruction: string;
+    verification?: OutputVerificationSpec;
+    /** Named authoring declaration selected from `FlowSpec.agents`. Compiled away. */
+    agent?: string;
+    /** Inert preflight declaration; overrides the flow/project CLI default. */
+    cli?: string;
+    /**
+     * Model the declared CLI must use. Raw Claude/Codex adapters receive their
+     * real model flag; an identified Relayflows wrapper receives it in its
+     * same-process execution request. Declared here so the choice is journaled with the step
+     * instead of being ambient host state.
+     */
+    model?: string;
+    surfaces?: AgentSurfaces;
+    recoveryMode?: RecoveryMode;
+    permissions?: PermissionsSpec;
+    /**
+     * Structured-output authoring sugar. A successful CLI JSON object is the parsed
+     * value; the kernel persists it only after `json_schema` verification.
+     */
+    output?: JsonOutputSchema;
+}
+export type StepSpec = DeterministicStepSpec | LlmStepSpec | AgentStepSpec;
+/**
+ * Reusable authoring declaration for an agent CLI/model pair. Both fields are
+ * required so selecting a named agent can never inherit a host model. The
+ * compiler lowers these values into the selected kernel agent step at the
+ * journal boundary; the kernel never receives this map or a new step field.
+ */
+export interface NamedAgentSpec {
+    cli: string;
+    model: string;
+}
+/**
+ * A trigger is an entry condition, not a scheduler (RFC-0001 gate 2). It names
+ * the event type that wakes the flow, the payload subset that must match, the
+ * template that derives the dedupe key, and the silence budget after which the
+ * kernel's liveness sweep declares the subscription dead.
+ *
+ * The event-subscription fields were shipped in `testdata/` long before this
+ * interface described them: `hn-monitor.flow.yaml`, `dir-watcher.flow.yaml`
+ * and `event-triggered-flow.yaml` all carry `eventType`, `pattern` and
+ * `dedupeKeyTemplate`, and `validate.ts` has always accepted them. The type
+ * still said "inert gate-1 declaration" with only `id` and `executor`, so the
+ * authoring dialect disagreed with both the shipped specs and the kernel.
+ */
+export interface TriggerSpec {
+    id: string;
+    /** Executor registration required before this trigger may start a run. */
+    executor: string;
+    /** Event type this trigger subscribes to. Lowers to `event_type`. */
+    eventType?: string;
+    /** Recursive-subset match against the event payload. Lowers to `pattern`. */
+    pattern?: Record<string, unknown>;
+    /** Derives the dedupe key. Lowers to `dedupe_key_template`. */
+    dedupeKeyTemplate?: string;
+    /**
+     * Silence budget in milliseconds. When no matching event arrives inside it,
+     * the kernel's liveness sweep journals `subscription.stale` and emits a
+     * `relayflowd: subscription.stale ...` line
+     * (`kernel/relayflowd/src/server/liveness.rs`). Omitted means the engine
+     * default (`DEFAULT_STALE_AFTER_MS`, 5 minutes) applies — which is a
+     * decision the author did not make, not the absence of a budget.
+     *
+     * A flow that is never triggered is silently zero (RFC-0001 §"Trigger
+     * liveness"), so declaring this is how a schedule stops being able to die
+     * quietly. Lowers to `stale_after_ms`.
+     */
+    staleAfterMs?: number;
+}
+/**
+ * A Relayflow spec in the authoring shape — the composable unit (RFC settled
+ * decision #5). Schema-validated, diffable, signable (gate 8), and emittable
+ * by a step (gate 9 self-authoring). What the kernel inlines in `run.spawned`
+ * is this spec mapped to the kernel dialect (`toKernelSpec`).
+ */
+export interface FlowSpec {
+    /** Spec schema semver (RFC §7). Compilers always emit latest. */
+    version: string;
+    name?: string;
+    description?: string;
+    /** Inert preflight default for llm/agent steps that do not declare a CLI. */
+    cli?: string;
+    /** Named authoring declarations. Compiled into agent steps, never journaled as a new primitive. */
+    agents?: Record<string, NamedAgentSpec>;
+    /** Declarations checked by preflight; gate 1 never dispatches them. */
+    triggers?: TriggerSpec[];
+    steps: StepSpec[];
+    budget?: BudgetSpec;
+}
+/** Current spec schema version emitted by this SDK. */
+export declare const SPEC_SCHEMA_VERSION = "0.1.0";
+export interface KernelRetryPolicy {
+    initial_backoff_ms: number;
+    max_backoff_ms: number;
+    multiplier: number;
+    jitter_percent: number;
+}
+/**
+ * Flat v0 gates (kernel DESIGN.md §4): `exit_code == 0` is implicit for
+ * deterministic steps; these two are optional and combinable. An empty object
+ * means "implicit gates only".
+ */
+export interface KernelVerificationSpec {
+    output_contains?: string;
+    json_schema?: boolean | Record<string, unknown>;
+}
+export interface KernelStepCommon {
+    id: string;
+    depends_on: string[];
+    max_iterations: number;
+    retry: KernelRetryPolicy;
+    verification: KernelVerificationSpec;
+}
+export interface KernelDeterministicStep extends KernelStepCommon {
+    type: 'deterministic';
+    command: string;
+    timeout_ms?: number;
+}
+export interface KernelLlmStep extends KernelStepCommon {
+    type: 'llm';
+    prompt: string;
+    model?: string;
+    cli?: string;
+}
+export interface KernelAgentSurfaces {
+    workspace?: {
+        surface: string;
+    }[];
+    streams?: {
+        stream: string;
+    }[];
+    external?: string[];
+}
+export interface KernelPermissionsSpec {
+    file_globs?: string[];
+    network_allowlist?: string[];
+    access_preset?: 'readonly' | 'readwrite';
+}
+export interface KernelAgentStep extends KernelStepCommon {
+    type: 'agent';
+    instruction: string;
+    cli?: string;
+    model?: string;
+    recovery_mode: RecoveryMode;
+    surfaces?: KernelAgentSurfaces;
+    permissions?: KernelPermissionsSpec;
+}
+export type KernelStepSpec = KernelDeterministicStep | KernelLlmStep | KernelAgentStep;
+export interface KernelBudgetSpec {
+    max_tokens_in?: number;
+    max_tokens_out?: number;
+    max_dollars?: string;
+}
+export interface KernelTriggerSpec {
+    id: string;
+    executor: string;
+    event_type?: string;
+    pattern?: Record<string, unknown>;
+    dedupe_key_template?: string;
+    stale_after_ms?: number;
+}
+/** The compiled spec as the kernel parses, journals, and hashes it. */
+export interface KernelRunSpec {
+    version: string;
+    name?: string;
+    description?: string;
+    cli?: string;
+    triggers?: KernelTriggerSpec[];
+    steps: KernelStepSpec[];
+    budget?: KernelBudgetSpec;
+}
+//# sourceMappingURL=spec.d.ts.map