@sweny-ai/core 0.1.97 → 0.1.99

package/dist/cli/cloud-lifecycle.d.ts

@@ -15,7 +15,7 @@
  *
  * All errors are swallowed: cloud reporting MUST NEVER block the workflow.
  */
-import type { NodeResult, Observer, Workflow } from "../types.js";
+import type { NodeResult, Observer, Workflow, WorkflowInputs } from "../types.js";
 export type TriggerSource = "github_action" | "gitlab_ci" | "circleci" | "buildkite" | "other_ci" | "manual" | "cron" | "mcp" | "unknown";
 export interface CloudReportConfig {
     cloudToken: string;
@@ -29,6 +29,17 @@ export interface StartRunInput {
     trigger_metadata?: Record<string, unknown>;
     metadata?: Record<string, unknown>;
     run_uuid?: string;
+    /**
+     * Declared input shape for this run: key name → declared (or observed)
+     * type. Values are intentionally NEVER included; per the workflow spec
+     * (Telemetry shape), cloud renderers may display the input contract a
+     * run was invoked with but must not receive the values themselves. A
+     * workflow that takes a token as input therefore never leaks it.
+     *
+     * Omitted when the caller didn't pass an inputs shape (e.g. legacy
+     * call sites pre-dating the inputs contract).
+     */
+    inputs_shape?: Record<string, string>;
 }
 export interface StartRunResult {
     run_id: string;
@@ -61,10 +72,18 @@ export declare function newRunUuid(): string;
 /**
  * Build a run-start payload from a Workflow + env. Pure function; the caller
  * is responsible for passing it to `startRun()`.
+ *
+ * `inputsShape` (when provided) ships the key-name → declared-type map for
+ * the run. Values are NEVER transmitted; callers compute the shape via
+ * `summarizeInputShape` (or pass the workflow's declared `inputs` block
+ * and resolved input bag and let this helper compute it). See the
+ * Telemetry shape rule in spec/src/content/docs/workflow.mdx.
  */
 export declare function buildStartRunPayload(workflow: Pick<Workflow, "id" | "workflow_type">, options: {
     runUuid: string;
     env?: NodeJS.ProcessEnv;
+    declaredInputs?: WorkflowInputs;
+    resolvedInputs?: Record<string, unknown>;
 }): StartRunInput;
 /**
  * POST /api/runs — start a run, returning the run id (or null on failure).
@@ -120,7 +139,10 @@ export interface CloudLifecycleHandle {
 export declare function beginCloudLifecycle(config: {
     cloudToken?: string;
     repository?: string;
-}, workflow: Pick<Workflow, "id" | "workflow_type">): Promise<CloudLifecycleHandle | null>;
+}, workflow: Pick<Workflow, "id" | "workflow_type">, options?: {
+    declaredInputs?: WorkflowInputs;
+    resolvedInputs?: Record<string, unknown>;
+}): Promise<CloudLifecycleHandle | null>;
 /**
  * Close a cloud lifecycle session opened by `beginCloudLifecycle`.
  *

package/dist/cli/cloud-lifecycle.js

@@ -16,6 +16,7 @@
  * All errors are swallowed: cloud reporting MUST NEVER block the workflow.
  */
 import { randomUUID } from "node:crypto";
+import { summarizeInputShape } from "../inputs.js";
 const CLOUD_URL_DEFAULT = "https://cloud.sweny.ai";
 const TIMEOUT_MS = 10_000;
 // startRun runs on the critical path BEFORE execute(), so a slow cloud
@@ -85,6 +86,12 @@ export function newRunUuid() {
 /**
  * Build a run-start payload from a Workflow + env. Pure function; the caller
  * is responsible for passing it to `startRun()`.
+ *
+ * `inputsShape` (when provided) ships the key-name → declared-type map for
+ * the run. Values are NEVER transmitted; callers compute the shape via
+ * `summarizeInputShape` (or pass the workflow's declared `inputs` block
+ * and resolved input bag and let this helper compute it). See the
+ * Telemetry shape rule in spec/src/content/docs/workflow.mdx.
  */
 export function buildStartRunPayload(workflow, options) {
     const env = options.env ?? process.env;
@@ -97,7 +104,7 @@ export function buildStartRunPayload(workflow, options) {
         metadata.commit_sha = env.GITHUB_SHA;
     if (env.GITHUB_ACTOR)
         metadata.actor = env.GITHUB_ACTOR;
-    return {
+    const payload = {
         workflow_id: workflow.id,
         workflow_type: workflow.workflow_type ?? "generic",
         trigger_source,
@@ -105,6 +112,17 @@ export function buildStartRunPayload(workflow, options) {
         metadata,
         run_uuid: options.runUuid,
     };
+    // Compute the shape when caller provided either a declaration or a
+    // resolved bag. Omit the key entirely when there's nothing to summarize
+    // so old cloud builds that don't model `inputs_shape` aren't surprised
+    // by an empty object.
+    if (options.declaredInputs || options.resolvedInputs) {
+        const shape = summarizeInputShape(options.declaredInputs, options.resolvedInputs);
+        if (Object.keys(shape).length > 0) {
+            payload.inputs_shape = shape;
+        }
+    }
+    return payload;
 }
 /**
  * POST /api/runs — start a run, returning the run id (or null on failure).
@@ -204,11 +222,15 @@ export function deriveGenericMetrics(results, durationMs) {
  * Pair every successful call with `finishCloudLifecycle(handle, …)` once the
  * workflow completes (success or failure).
  */
-export async function beginCloudLifecycle(config, workflow) {
+export async function beginCloudLifecycle(config, workflow, options) {
     if (!config.cloudToken)
         return null;
     const runUuid = newRunUuid();
-    const payload = buildStartRunPayload(workflow, { runUuid });
+    const payload = buildStartRunPayload(workflow, {
+        runUuid,
+        declaredInputs: options?.declaredInputs,
+        resolvedInputs: options?.resolvedInputs,
+    });
     const reportConfig = {
         cloudToken: config.cloudToken,
         repository: config.repository,

package/dist/cli/config.d.ts

@@ -52,6 +52,12 @@ export interface CliConfig {
     repositoryOwner: string;
     json: boolean;
     stream: boolean;
+    /**
+     * When true, print each tool call's input and output inline (human-readable,
+     * truncated). Adds a verbose tool observer alongside the spinner/progress
+     * observer. Use `stream` if you need full untruncated NDJSON instead.
+     */
+    verbose: boolean;
     bell: boolean;
     cacheDir: string;
     cacheTtl: number;

package/dist/cli/config.js

@@ -56,6 +56,7 @@ export function registerTriageCommand(program) {
         .option("--gitlab-base-url <url>", "GitLab base URL (default: https://gitlab.com)")
         .option("--json", "Output results as JSON", false)
         .option("--stream", "Stream NDJSON events to stdout (for Studio / automation)", false)
+        .option("--verbose", "Print each tool call's input and output inline (human-readable, truncated). Use --stream for full untruncated NDJSON.", false)
         .option("--bell", "Ring terminal bell on completion", false)
         .option("--cache-dir <path>", "Step cache directory (default: .sweny/cache)")
         .option("--cache-ttl <seconds>", "Cache TTL in seconds, 0 = infinite (default: 86400)")
@@ -163,6 +164,7 @@ export function parseCliInputs(options, fileConfig = {}) {
         // Per-invocation flags: CLI only
         json: Boolean(options.json),
         stream: Boolean(options.stream),
+        verbose: Boolean(options.verbose),
         bell: Boolean(options.bell),
         cacheDir: options.cacheDir || env.SWENY_CACHE_DIR || f("cache-dir") || ".sweny/cache",
         cacheTtl: parsePositiveInt(options.cacheTtl ?? f("cache-ttl"), 86400),
@@ -638,6 +640,7 @@ export function registerImplementCommand(program) {
         .option("--review-mode <mode>", "PR merge behavior: auto (GitHub auto-merge when CI passes) | review (human approval, default)", "review")
         .option("--additional-instructions <text>", "Extra instructions for the coding agent")
         .option("--stream", "Stream NDJSON events to stdout (for Studio / automation)", false)
+        .option("--verbose", "Print each tool call's input and output inline (human-readable, truncated). Use --stream for full untruncated NDJSON.", false)
         .option("--offline", "Skip URL Sources and fail fast if any are referenced", false);
 }
 /**

package/dist/cli/main.js

@@ -15,6 +15,7 @@ import { configuredSkills, configuredSkillsWithDiagnostics } from "../skills/cus
 import { buildAutoMcpServers, buildSkillMcpServers, buildProviderContext } from "../mcp.js";
 import { loadAdditionalContext } from "../templates.js";
 import { loadAndValidateWorkflow } from "../loader.js";
+import { validateRuntimeInput } from "../inputs.js";
 import { stringify as stringifyYaml } from "yaml";
 import { buildWorkflow, refineWorkflow } from "../workflow-builder.js";
 import { toMermaidBlock } from "../mermaid.js";
@@ -355,11 +356,18 @@ triageCmd.action(async (options) => {
     // node-streaming observer can attach events to the correct runId.
     // Null when the token is unset or startRun fails — cloud reporting
     // must never block the workflow.
-    const cloudHandle = await beginCloudLifecycle(config, triageWorkflow);
+    //
+    // Cloud sees the input *shape* (key names + observed types), never
+    // the values. Per workflow spec Telemetry shape rule, a token in the
+    // bag never leaves the host.
+    const cloudHandle = await beginCloudLifecycle(config, triageWorkflow, {
+        declaredInputs: triageWorkflow.inputs,
+        resolvedInputs: workflowInput,
+    });
     if (cloudHandle?.dashboardUrl) {
         console.log(c.subtle(`  cloud: ${cloudHandle.dashboardUrl}`));
     }
-    const observer = composeObservers(progressObserver, config.stream ? createStreamObserver() : undefined, createCloudStreamObserver(config, cloudHandle));
+    const observer = composeObservers(progressObserver, config.verbose ? createVerboseToolObserver() : undefined, config.stream ? createStreamObserver() : undefined, createCloudStreamObserver(config, cloudHandle));
     try {
         const { results, trace } = await execute(triageWorkflow, workflowInput, {
             skills,
@@ -527,12 +535,15 @@ implementCmd.action(async (issueId, options) => {
     };
     // Open cloud lifecycle session BEFORE composing observers so the
     // node-streaming observer can attach to the correct runId. See
-    // triage path for rationale.
-    const implCloudHandle = await beginCloudLifecycle(config, implementWorkflow);
+    // triage path for rationale. Cloud sees the input *shape* only.
+    const implCloudHandle = await beginCloudLifecycle(config, implementWorkflow, {
+        declaredInputs: implementWorkflow.inputs,
+        resolvedInputs: workflowInput,
+    });
     if (implCloudHandle?.dashboardUrl) {
         console.log(c.subtle(`  cloud: ${implCloudHandle.dashboardUrl}`));
     }
-    const observer = composeObservers(implProgressObserver, Boolean(options.stream) ? createStreamObserver() : undefined, createCloudStreamObserver(config, implCloudHandle));
+    const observer = composeObservers(implProgressObserver, config.verbose ? createVerboseToolObserver() : undefined, Boolean(options.stream) ? createStreamObserver() : undefined, createCloudStreamObserver(config, implCloudHandle));
     try {
         const { results } = await execute(implementWorkflow, workflowInput, {
             skills,
@@ -720,14 +731,39 @@ export async function workflowRunAction(file, options) {
     // Build workflow input — prefer --input JSON if provided, else fall back to config-derived input
     let workflowInput;
     if (options.input && typeof options.input === "string") {
+        let parsed;
         try {
-            workflowInput = JSON.parse(options.input);
+            parsed = JSON.parse(options.input);
         }
         catch {
             console.error(chalk.red("  --input must be valid JSON"));
             process.exit(1);
             return;
         }
+        // Validate against the workflow's declared `inputs` contract (when present).
+        // Workflows without an `inputs` block pass through unchanged.
+        const validated = validateRuntimeInput(workflow.inputs, parsed);
+        if (!validated.ok) {
+            console.error(chalk.red(`\n  --input does not match workflow "${workflow.id}" inputs contract:\n`));
+            for (const err of validated.errors) {
+                console.error(chalk.red(`    ✗ ${err.field}: ${err.message}`));
+            }
+            if (workflow.inputs) {
+                console.error(chalk.dim(`\n  Declared inputs:`));
+                for (const [name, field] of Object.entries(workflow.inputs)) {
+                    const flags = [field.type];
+                    if (field.required)
+                        flags.push("required");
+                    if (field.default !== undefined)
+                        flags.push(`default=${JSON.stringify(field.default)}`);
+                    console.error(chalk.dim(`    - ${name} (${flags.join(", ")})${field.description ? `: ${field.description}` : ""}`));
+                }
+            }
+            console.error("");
+            process.exit(1);
+            return;
+        }
+        workflowInput = validated.value;
     }
     else {
         workflowInput = {
@@ -748,11 +784,33 @@ export async function workflowRunAction(file, options) {
             }),
             context: buildProviderCtx(config, mcpServers),
         };
+        // If the workflow declared `inputs`, apply defaults to the config-derived bag.
+        // This lets a CI caller omit --input entirely and still get the documented
+        // defaults filled in (e.g. since_tag/until_tag pulled from a release-notes
+        // workflow's declaration).
+        if (workflow.inputs) {
+            const validated = validateRuntimeInput(workflow.inputs, workflowInput);
+            if (!validated.ok) {
+                console.error(chalk.red(`\n  Workflow "${workflow.id}" declares required inputs not satisfied by default config:\n`));
+                for (const err of validated.errors) {
+                    console.error(chalk.red(`    ✗ ${err.field}: ${err.message}`));
+                }
+                console.error(chalk.dim(`\n  Pass them via --input '{ ... }'.\n`));
+                process.exit(1);
+                return;
+            }
+            workflowInput = validated.value;
+        }
     }
     // Open cloud lifecycle session BEFORE composing observers so the
     // node-streaming observer can attach to the correct runId. See
-    // triage path for rationale.
-    const wfCloudHandle = await beginCloudLifecycle(config, workflow);
+    // triage path for rationale. Cloud sees the input *shape* only,
+    // never the values. Enforces the workflow spec Telemetry rule
+    // even when the workflow's declared inputs include secrets.
+    const wfCloudHandle = await beginCloudLifecycle(config, workflow, {
+        declaredInputs: workflow.inputs,
+        resolvedInputs: workflowInput,
+    });
     if (wfCloudHandle?.dashboardUrl && !isJson) {
         console.log(c.subtle(`  cloud: ${wfCloudHandle.dashboardUrl}`));
     }

package/dist/index.d.ts

@@ -21,7 +21,8 @@
  * })
  * ```
  */
-export type { Skill, SkillCategory, SkillDefinition, Tool, ToolContext, ConfigField, JSONSchema, Workflow, Node, Edge, NodeResult, ToolCall, ExecutionEvent, Observer, Claude, Logger, TraceStep, TraceEdge, ExecutionTrace, ExecutionResult, Source, ResolvedSource, SourceKind, SourceResolutionMap, } from "./types.js";
+export type { Skill, SkillCategory, SkillDefinition, Tool, ToolContext, ConfigField, JSONSchema, Workflow, Node, Edge, NodeResult, ToolCall, ExecutionEvent, Observer, Claude, Logger, TraceStep, TraceEdge, ExecutionTrace, ExecutionResult, Source, ResolvedSource, SourceKind, SourceResolutionMap, WorkflowInputs, WorkflowInputField, WorkflowInputType, InputValidationError, InputValidationResult, } from "./types.js";
+export { WORKFLOW_INPUT_TYPES } from "./types.js";
 export { consoleLogger } from "./types.js";
 export { execute } from "./executor.js";
 export type { ExecuteOptions } from "./executor.js";
@@ -30,8 +31,9 @@ export type { ClaudeClientOptions } from "./claude.js";
 export { github, linear, slack, sentry, datadog, notification, supabase, builtinSkills, createSkillMap, allSkills, isSkillConfigured, configuredBuiltinSkills, validateWorkflowSkills, } from "./skills/index.js";
 export type { SkillValidationResult } from "./skills/index.js";
 export { loadCustomSkills, discoverSkills, configuredSkills } from "./skills/custom-loader.js";
-export { workflowZ, nodeZ, edgeZ, skillZ, mcpServerConfigZ, skillDefinitionZ, sourceZ, parseWorkflow, validateWorkflow, workflowJsonSchema, } from "./schema.js";
+export { workflowZ, nodeZ, edgeZ, skillZ, mcpServerConfigZ, skillDefinitionZ, sourceZ, workflowInputsZ, parseWorkflow, validateWorkflow, workflowJsonSchema, } from "./schema.js";
 export type { WorkflowError } from "./schema.js";
+export { validateRuntimeInput, summarizeInputShape } from "./inputs.js";
 export { buildAutoMcpServers, buildSkillMcpServers, buildProviderContext } from "./mcp.js";
 export type { ProviderContextOptions, SkillMcpOptions } from "./mcp.js";
 export type { McpServerConfig, McpAutoConfig } from "./types.js";

package/dist/index.js

@@ -21,6 +21,7 @@
  * })
  * ```
  */
+export { WORKFLOW_INPUT_TYPES } from "./types.js";
 export { consoleLogger } from "./types.js";
 // Executor
 export { execute } from "./executor.js";
@@ -31,7 +32,9 @@ export { github, linear, slack, sentry, datadog, notification, supabase, builtin
 // Node-only skill discovery (filesystem-based)
 export { loadCustomSkills, discoverSkills, configuredSkills } from "./skills/custom-loader.js";
 // Schema & validation
-export { workflowZ, nodeZ, edgeZ, skillZ, mcpServerConfigZ, skillDefinitionZ, sourceZ, parseWorkflow, validateWorkflow, workflowJsonSchema, } from "./schema.js";
+export { workflowZ, nodeZ, edgeZ, skillZ, mcpServerConfigZ, skillDefinitionZ, sourceZ, workflowInputsZ, parseWorkflow, validateWorkflow, workflowJsonSchema, } from "./schema.js";
+// Workflow input validation
+export { validateRuntimeInput, summarizeInputShape } from "./inputs.js";
 // MCP auto-injection
 export { buildAutoMcpServers, buildSkillMcpServers, buildProviderContext } from "./mcp.js";
 // Workflow builder

package/dist/inputs.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Workflow inputs — declared per-run parameter contract.
+ *
+ * A workflow YAML may declare a top-level `inputs` block describing the
+ * per-run parameters it accepts. The CLI validates `--input <json>` against
+ * this declaration, applies defaults, and rejects malformed runs at the
+ * boundary so node prompts and conditional routing receive a well-shaped
+ * `input` value.
+ *
+ * Design notes (the contract that matters for downstream consumers):
+ *
+ *   1. The `inputs` block is OPTIONAL. Workflows without one accept any
+ *      JSON object (back-compat with every workflow shipped before this
+ *      change). Author opts in by adding the block.
+ *   2. Types are the JSON-native primitives we can validate without a
+ *      schema engine: `string`, `number`, `boolean`, plus `string[]` for
+ *      multi-value cases (labels, files, etc.). This is intentionally
+ *      narrower than full JSON Schema. Authors who need richer shapes can
+ *      still pass an arbitrary object; declaring it just opts into the
+ *      validator. We can widen later without breaking existing YAML.
+ *   3. `required: true` makes a field mandatory. Missing fields surface a
+ *      single grouped error listing every gap, not one error per call.
+ *   4. `default` fills in the value when the caller omits it. The default
+ *      is type-checked against the field's `type` at parse time, so
+ *      authors can't ship a YAML that injects a string into a number
+ *      field at run time. `required: true` and `default` are mutually
+ *      exclusive: declaring both is incoherent (the default either
+ *      satisfies the required check, making it vestigial, or it doesn't,
+ *      making the default dead code), so the schema rejects the
+ *      combination at parse time.
+ *   5. Telemetry redaction: the executor only ever sees the resolved
+ *      `input` map. Cloud observers see the *shape* (key names + types)
+ *      via `summarizeInputShape`, never the values, so a workflow that
+ *      takes API tokens as input never leaks them.
+ *
+ * Out of scope on purpose:
+ *   - No templating language (`{{input.foo}}` etc.). Workflow instructions
+ *     are natural-language and the LLM already sees `input` in its context
+ *     map; that path is good enough for v1 and avoids inventing a dialect.
+ *   - No nested object schemas. If a single workflow needs deep input,
+ *     pass a JSON blob through and document it; we can layer schemas in
+ *     later. Most production use cases are flat (since_tag, until_tag,
+ *     dry_run, repo, time_range, etc.).
+ */
+import { z } from "zod";
+/**
+ * Supported input field types.
+ *
+ * Kept narrow on purpose. See module docstring for rationale.
+ */
+export declare const WORKFLOW_INPUT_TYPES: readonly ["string", "number", "boolean", "string[]"];
+export type WorkflowInputType = (typeof WORKFLOW_INPUT_TYPES)[number];
+/** A single declared input field. */
+export interface WorkflowInputField {
+    /** JSON-native type. See {@link WORKFLOW_INPUT_TYPES}. */
+    type: WorkflowInputType;
+    /** Human-readable description. Surfaced by CLI help and cloud renderers. */
+    description?: string;
+    /** When true, the caller MUST provide a value. */
+    required?: boolean;
+    /**
+     * Default applied when the caller omits the field. Type-checked against
+     * `type` at YAML parse time (a string default on a number field is a
+     * schema error, not a runtime surprise).
+     */
+    default?: unknown;
+    /** Optional set of allowed values. Validated after type-check. */
+    enum?: unknown[];
+}
+/** Declared input contract for a workflow. Keys are field names. */
+export type WorkflowInputs = Record<string, WorkflowInputField>;
+export declare const workflowInputsZ: z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodObject<{
+    type: z.ZodEnum<["string", "number", "boolean", "string[]"]>;
+    description: z.ZodOptional<z.ZodString>;
+    required: z.ZodOptional<z.ZodBoolean>;
+    default: z.ZodOptional<z.ZodUnknown>;
+    enum: z.ZodOptional<z.ZodArray<z.ZodUnknown, "many">>;
+}, "strict", z.ZodTypeAny, {
+    type: "string" | "number" | "boolean" | "string[]";
+    description?: string | undefined;
+    required?: boolean | undefined;
+    default?: unknown;
+    enum?: unknown[] | undefined;
+}, {
+    type: "string" | "number" | "boolean" | "string[]";
+    description?: string | undefined;
+    required?: boolean | undefined;
+    default?: unknown;
+    enum?: unknown[] | undefined;
+}>, {
+    type: "string" | "number" | "boolean" | "string[]";
+    description?: string | undefined;
+    required?: boolean | undefined;
+    default?: unknown;
+    enum?: unknown[] | undefined;
+}, {
+    type: "string" | "number" | "boolean" | "string[]";
+    description?: string | undefined;
+    required?: boolean | undefined;
+    default?: unknown;
+    enum?: unknown[] | undefined;
+}>>;
+/** A single validation error against the declared input contract. */
+export interface InputValidationError {
+    field: string;
+    message: string;
+}
+/** Tagged result of validating raw runtime input against a declared contract. */
+export type InputValidationResult = {
+    ok: true;
+    value: Record<string, unknown>;
+} | {
+    ok: false;
+    errors: InputValidationError[];
+};
+/**
+ * Validate the caller's raw input object against the workflow's declared
+ * `inputs` block. Applies defaults for omitted optional fields. Surfaces
+ * every problem in a single response so the CLI prints a useful message
+ * instead of failing on the first error.
+ *
+ * When no `inputs` block is declared, returns the caller's object verbatim
+ * (back-compat: every existing workflow passes through unchanged).
+ */
+export declare function validateRuntimeInput(declared: WorkflowInputs | undefined, raw: unknown): InputValidationResult;
+/**
+ * Summary of an input bag suitable for telemetry: keys + observed types,
+ * never values. Cloud renderers use this to display the input contract a
+ * run was invoked with, without leaking the values themselves.
+ *
+ * `declared` shapes the output when present (so the summary stays stable
+ * across runs even when the caller omits optional fields). Falls back to
+ * the resolved values' runtime shape when no declaration exists.
+ */
+export declare function summarizeInputShape(declared: WorkflowInputs | undefined, resolved: Record<string, unknown> | undefined): Record<string, WorkflowInputType | "object" | "null">;

package/dist/inputs.js

@@ -0,0 +1,256 @@
+/**
+ * Workflow inputs — declared per-run parameter contract.
+ *
+ * A workflow YAML may declare a top-level `inputs` block describing the
+ * per-run parameters it accepts. The CLI validates `--input <json>` against
+ * this declaration, applies defaults, and rejects malformed runs at the
+ * boundary so node prompts and conditional routing receive a well-shaped
+ * `input` value.
+ *
+ * Design notes (the contract that matters for downstream consumers):
+ *
+ *   1. The `inputs` block is OPTIONAL. Workflows without one accept any
+ *      JSON object (back-compat with every workflow shipped before this
+ *      change). Author opts in by adding the block.
+ *   2. Types are the JSON-native primitives we can validate without a
+ *      schema engine: `string`, `number`, `boolean`, plus `string[]` for
+ *      multi-value cases (labels, files, etc.). This is intentionally
+ *      narrower than full JSON Schema. Authors who need richer shapes can
+ *      still pass an arbitrary object; declaring it just opts into the
+ *      validator. We can widen later without breaking existing YAML.
+ *   3. `required: true` makes a field mandatory. Missing fields surface a
+ *      single grouped error listing every gap, not one error per call.
+ *   4. `default` fills in the value when the caller omits it. The default
+ *      is type-checked against the field's `type` at parse time, so
+ *      authors can't ship a YAML that injects a string into a number
+ *      field at run time. `required: true` and `default` are mutually
+ *      exclusive: declaring both is incoherent (the default either
+ *      satisfies the required check, making it vestigial, or it doesn't,
+ *      making the default dead code), so the schema rejects the
+ *      combination at parse time.
+ *   5. Telemetry redaction: the executor only ever sees the resolved
+ *      `input` map. Cloud observers see the *shape* (key names + types)
+ *      via `summarizeInputShape`, never the values, so a workflow that
+ *      takes API tokens as input never leaks them.
+ *
+ * Out of scope on purpose:
+ *   - No templating language (`{{input.foo}}` etc.). Workflow instructions
+ *     are natural-language and the LLM already sees `input` in its context
+ *     map; that path is good enough for v1 and avoids inventing a dialect.
+ *   - No nested object schemas. If a single workflow needs deep input,
+ *     pass a JSON blob through and document it; we can layer schemas in
+ *     later. Most production use cases are flat (since_tag, until_tag,
+ *     dry_run, repo, time_range, etc.).
+ */
+import { z } from "zod";
+/**
+ * Supported input field types.
+ *
+ * Kept narrow on purpose. See module docstring for rationale.
+ */
+export const WORKFLOW_INPUT_TYPES = ["string", "number", "boolean", "string[]"];
+// ─── Zod schema ─────────────────────────────────────────────────
+const workflowInputTypeZ = z.enum(WORKFLOW_INPUT_TYPES);
+/**
+ * Per-field validator. Cross-field checks (default matches type, enum
+ * values match type) run in superRefine so all problems on a single field
+ * surface together rather than one-at-a-time.
+ */
+const workflowInputFieldZ = z
+    .object({
+    type: workflowInputTypeZ,
+    description: z.string().optional(),
+    required: z.boolean().optional(),
+    default: z.unknown().optional(),
+    enum: z.array(z.unknown()).min(1).optional(),
+})
+    .strict()
+    .superRefine((field, ctx) => {
+    // `required: true` together with a `default` is incoherent: if the
+    // default substitutes for an omitted value, the field is effectively
+    // optional; if the required check fires, the default is dead code.
+    // Reject the combination at parse time so authors fix the YAML
+    // instead of relying on undocumented runtime tie-breaking.
+    if (field.required === true && field.default !== undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "field cannot declare both `required: true` and `default`; pick one (a default makes the field optional)",
+            path: ["required"],
+        });
+    }
+    if (field.default !== undefined) {
+        const err = checkValueType(field.default, field.type);
+        if (err) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `default ${err}`,
+                path: ["default"],
+            });
+        }
+    }
+    if (field.enum) {
+        for (let i = 0; i < field.enum.length; i++) {
+            const err = checkValueType(field.enum[i], field.type);
+            if (err) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    message: `enum[${i}] ${err}`,
+                    path: ["enum", i],
+                });
+            }
+        }
+    }
+});
+export const workflowInputsZ = z.record(workflowInputFieldZ);
+/**
+ * Validate the caller's raw input object against the workflow's declared
+ * `inputs` block. Applies defaults for omitted optional fields. Surfaces
+ * every problem in a single response so the CLI prints a useful message
+ * instead of failing on the first error.
+ *
+ * When no `inputs` block is declared, returns the caller's object verbatim
+ * (back-compat: every existing workflow passes through unchanged).
+ */
+export function validateRuntimeInput(declared, raw) {
+    // Back-compat: no declaration → accept anything.
+    if (!declared || Object.keys(declared).length === 0) {
+        if (raw == null)
+            return { ok: true, value: {} };
+        if (typeof raw !== "object" || Array.isArray(raw)) {
+            return { ok: false, errors: [{ field: "(root)", message: "input must be a JSON object" }] };
+        }
+        return { ok: true, value: raw };
+    }
+    if (raw != null && (typeof raw !== "object" || Array.isArray(raw))) {
+        return { ok: false, errors: [{ field: "(root)", message: "input must be a JSON object" }] };
+    }
+    const provided = (raw ?? {});
+    const errors = [];
+    const out = {};
+    for (const [name, field] of Object.entries(declared)) {
+        const has = Object.prototype.hasOwnProperty.call(provided, name);
+        let value = has ? provided[name] : undefined;
+        if (!has || value === undefined || value === null) {
+            if (field.default !== undefined) {
+                out[name] = field.default;
+                continue;
+            }
+            if (field.required) {
+                errors.push({ field: name, message: "required but not provided" });
+            }
+            // Optional and no default: leave unset. Downstream `priorNode.input.X`
+            // reads will see `undefined`, which JSON-serializes as absent.
+            continue;
+        }
+        const typeErr = checkValueType(value, field.type);
+        if (typeErr) {
+            errors.push({ field: name, message: typeErr });
+            continue;
+        }
+        if (field.enum && !field.enum.some((v) => deepEqual(v, value))) {
+            errors.push({
+                field: name,
+                message: `must be one of: ${field.enum.map((v) => JSON.stringify(v)).join(", ")}`,
+            });
+            continue;
+        }
+        out[name] = value;
+    }
+    // Pass through caller-provided keys that aren't in the declaration.
+    // This is intentional: existing CLI flags (timeRange, dryRun, etc.)
+    // and the cascade `rules`/`context` mechanism inject extra keys into
+    // the input bag. The declaration narrows the contract for documented
+    // fields without locking down the whole object.
+    for (const [k, v] of Object.entries(provided)) {
+        if (!Object.prototype.hasOwnProperty.call(declared, k)) {
+            out[k] = v;
+        }
+    }
+    if (errors.length > 0)
+        return { ok: false, errors };
+    return { ok: true, value: out };
+}
+/**
+ * Summary of an input bag suitable for telemetry: keys + observed types,
+ * never values. Cloud renderers use this to display the input contract a
+ * run was invoked with, without leaking the values themselves.
+ *
+ * `declared` shapes the output when present (so the summary stays stable
+ * across runs even when the caller omits optional fields). Falls back to
+ * the resolved values' runtime shape when no declaration exists.
+ */
+export function summarizeInputShape(declared, resolved) {
+    const shape = {};
+    if (declared) {
+        for (const [name, field] of Object.entries(declared)) {
+            shape[name] = field.type;
+        }
+        return shape;
+    }
+    if (!resolved)
+        return shape;
+    for (const [name, value] of Object.entries(resolved)) {
+        shape[name] = observedType(value);
+    }
+    return shape;
+}
+// ─── Internals ──────────────────────────────────────────────────
+function checkValueType(value, type) {
+    switch (type) {
+        case "string":
+            return typeof value === "string" ? null : `must be a string (got ${observedType(value)})`;
+        case "number":
+            return typeof value === "number" && Number.isFinite(value)
+                ? null
+                : `must be a finite number (got ${observedType(value)})`;
+        case "boolean":
+            return typeof value === "boolean" ? null : `must be a boolean (got ${observedType(value)})`;
+        case "string[]":
+            if (!Array.isArray(value))
+                return `must be an array of strings (got ${observedType(value)})`;
+            for (let i = 0; i < value.length; i++) {
+                if (typeof value[i] !== "string") {
+                    return `must be an array of strings (element ${i} is ${observedType(value[i])})`;
+                }
+            }
+            return null;
+    }
+}
+function observedType(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value)) {
+        return value.every((v) => typeof v === "string") ? "string[]" : "object";
+    }
+    switch (typeof value) {
+        case "string":
+            return "string";
+        case "number":
+            return "number";
+        case "boolean":
+            return "boolean";
+        default:
+            return "object";
+    }
+}
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== typeof b)
+        return false;
+    if (a == null || b == null)
+        return false;
+    if (Array.isArray(a) && Array.isArray(b)) {
+        if (a.length !== b.length)
+            return false;
+        return a.every((v, i) => deepEqual(v, b[i]));
+    }
+    if (typeof a === "object" && typeof b === "object") {
+        const ak = Object.keys(a);
+        const bk = Object.keys(b);
+        if (ak.length !== bk.length)
+            return false;
+        return ak.every((k) => deepEqual(a[k], b[k]));
+    }
+    return false;
+}

package/dist/schema.d.ts

@@ -9,7 +9,9 @@
 import { z } from "zod";
 import type { Workflow } from "./types.js";
 import { sourceZ } from "./sources.js";
+import { workflowInputsZ } from "./inputs.js";
 export { sourceZ };
+export { workflowInputsZ };
 export declare const jsonSchemaZ: z.ZodRecord<z.ZodString, z.ZodUnknown>;
 export declare const configFieldZ: z.ZodObject<{
     description: z.ZodString;
@@ -34,12 +36,12 @@ export declare const toolZ: z.ZodObject<{
     description: z.ZodString;
     input_schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
 }, "strip", z.ZodTypeAny, {
-    name: string;
     description: string;
+    name: string;
     input_schema: Record<string, unknown>;
 }, {
-    name: string;
     description: string;
+    name: string;
     input_schema: Record<string, unknown>;
 }>;
 export declare const skillCategoryZ: z.ZodEnum<["general", "git", "tasks", "notification", "observability", "data"]>;
@@ -120,8 +122,8 @@ export declare const skillDefinitionZ: z.ZodEffects<z.ZodObject<{
         args?: string[] | undefined;
     }>>;
 }, "strict", z.ZodTypeAny, {
-    name?: string | undefined;
     description?: string | undefined;
+    name?: string | undefined;
     instruction?: string | undefined;
     mcp?: {
         url?: string | undefined;
@@ -132,8 +134,8 @@ export declare const skillDefinitionZ: z.ZodEffects<z.ZodObject<{
         args?: string[] | undefined;
     } | undefined;
 }, {
-    name?: string | undefined;
     description?: string | undefined;
+    name?: string | undefined;
     instruction?: string | undefined;
     mcp?: {
         url?: string | undefined;
@@ -144,8 +146,8 @@ export declare const skillDefinitionZ: z.ZodEffects<z.ZodObject<{
         args?: string[] | undefined;
     } | undefined;
 }>, {
-    name?: string | undefined;
     description?: string | undefined;
+    name?: string | undefined;
     instruction?: string | undefined;
     mcp?: {
         url?: string | undefined;
@@ -156,8 +158,8 @@ export declare const skillDefinitionZ: z.ZodEffects<z.ZodObject<{
         args?: string[] | undefined;
     } | undefined;
 }, {
-    name?: string | undefined;
     description?: string | undefined;
+    name?: string | undefined;
     instruction?: string | undefined;
     mcp?: {
         url?: string | undefined;
@@ -191,12 +193,12 @@ export declare const skillZ: z.ZodEffects<z.ZodObject<{
         description: z.ZodString;
         input_schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     }, "strip", z.ZodTypeAny, {
-        name: string;
         description: string;
+        name: string;
         input_schema: Record<string, unknown>;
     }, {
-        name: string;
         description: string;
+        name: string;
         input_schema: Record<string, unknown>;
     }>, "many">>;
     instruction: z.ZodOptional<z.ZodString>;
@@ -238,9 +240,9 @@ export declare const skillZ: z.ZodEffects<z.ZodObject<{
     }>>;
     mcpAliases: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString, "many">>>;
 }, "strip", z.ZodTypeAny, {
-    id: string;
-    name: string;
     description: string;
+    name: string;
+    id: string;
     category: "general" | "git" | "tasks" | "notification" | "observability" | "data";
     config: Record<string, {
         description: string;
@@ -248,8 +250,8 @@ export declare const skillZ: z.ZodEffects<z.ZodObject<{
         env?: string | undefined;
     }>;
     tools: {
-        name: string;
         description: string;
+        name: string;
         input_schema: Record<string, unknown>;
     }[];
     instruction?: string | undefined;
@@ -263,9 +265,9 @@ export declare const skillZ: z.ZodEffects<z.ZodObject<{
     } | undefined;
     mcpAliases?: Record<string, string[]> | undefined;
 }, {
-    id: string;
-    name: string;
     description: string;
+    name: string;
+    id: string;
     category: "general" | "git" | "tasks" | "notification" | "observability" | "data";
     instruction?: string | undefined;
     mcp?: {
@@ -282,15 +284,15 @@ export declare const skillZ: z.ZodEffects<z.ZodObject<{
         env?: string | undefined;
     }> | undefined;
     tools?: {
-        name: string;
         description: string;
+        name: string;
         input_schema: Record<string, unknown>;
     }[] | undefined;
     mcpAliases?: Record<string, string[]> | undefined;
 }>, {
-    id: string;
-    name: string;
     description: string;
+    name: string;
+    id: string;
     category: "general" | "git" | "tasks" | "notification" | "observability" | "data";
     config: Record<string, {
         description: string;
@@ -298,8 +300,8 @@ export declare const skillZ: z.ZodEffects<z.ZodObject<{
         env?: string | undefined;
     }>;
     tools: {
-        name: string;
         description: string;
+        name: string;
         input_schema: Record<string, unknown>;
     }[];
     instruction?: string | undefined;
@@ -313,9 +315,9 @@ export declare const skillZ: z.ZodEffects<z.ZodObject<{
     } | undefined;
     mcpAliases?: Record<string, string[]> | undefined;
 }, {
-    id: string;
-    name: string;
     description: string;
+    name: string;
+    id: string;
     category: "general" | "git" | "tasks" | "notification" | "observability" | "data";
     instruction?: string | undefined;
     mcp?: {
@@ -332,8 +334,8 @@ export declare const skillZ: z.ZodEffects<z.ZodObject<{
         env?: string | undefined;
     }> | undefined;
     tools?: {
-        name: string;
         description: string;
+        name: string;
         input_schema: Record<string, unknown>;
     }[] | undefined;
     mcpAliases?: Record<string, string[]> | undefined;
@@ -2041,8 +2043,8 @@ export declare const workflowZ: z.ZodObject<{
             args?: string[] | undefined;
         }>>;
     }, "strict", z.ZodTypeAny, {
-        name?: string | undefined;
         description?: string | undefined;
+        name?: string | undefined;
         instruction?: string | undefined;
         mcp?: {
             url?: string | undefined;
@@ -2053,8 +2055,8 @@ export declare const workflowZ: z.ZodObject<{
             args?: string[] | undefined;
         } | undefined;
     }, {
-        name?: string | undefined;
         description?: string | undefined;
+        name?: string | undefined;
         instruction?: string | undefined;
         mcp?: {
             url?: string | undefined;
@@ -2065,8 +2067,8 @@ export declare const workflowZ: z.ZodObject<{
             args?: string[] | undefined;
         } | undefined;
     }>, {
-        name?: string | undefined;
         description?: string | undefined;
+        name?: string | undefined;
         instruction?: string | undefined;
         mcp?: {
             url?: string | undefined;
@@ -2077,8 +2079,8 @@ export declare const workflowZ: z.ZodObject<{
             args?: string[] | undefined;
         } | undefined;
     }, {
-        name?: string | undefined;
         description?: string | undefined;
+        name?: string | undefined;
         instruction?: string | undefined;
         mcp?: {
             url?: string | undefined;
@@ -2135,13 +2137,44 @@ export declare const workflowZ: z.ZodObject<{
     }>]>, "many">>;
     judge_model: z.ZodOptional<z.ZodString>;
     judge_budget: z.ZodOptional<z.ZodNumber>;
+    inputs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodObject<{
+        type: z.ZodEnum<["string", "number", "boolean", "string[]"]>;
+        description: z.ZodOptional<z.ZodString>;
+        required: z.ZodOptional<z.ZodBoolean>;
+        default: z.ZodOptional<z.ZodUnknown>;
+        enum: z.ZodOptional<z.ZodArray<z.ZodUnknown, "many">>;
+    }, "strict", z.ZodTypeAny, {
+        type: "string" | "number" | "boolean" | "string[]";
+        description?: string | undefined;
+        required?: boolean | undefined;
+        default?: unknown;
+        enum?: unknown[] | undefined;
+    }, {
+        type: "string" | "number" | "boolean" | "string[]";
+        description?: string | undefined;
+        required?: boolean | undefined;
+        default?: unknown;
+        enum?: unknown[] | undefined;
+    }>, {
+        type: "string" | "number" | "boolean" | "string[]";
+        description?: string | undefined;
+        required?: boolean | undefined;
+        default?: unknown;
+        enum?: unknown[] | undefined;
+    }, {
+        type: "string" | "number" | "boolean" | "string[]";
+        description?: string | undefined;
+        required?: boolean | undefined;
+        default?: unknown;
+        enum?: unknown[] | undefined;
+    }>>>;
 }, "strip", z.ZodTypeAny, {
-    id: string;
-    name: string;
     description: string;
+    name: string;
+    id: string;
     skills: Record<string, {
-        name?: string | undefined;
         description?: string | undefined;
+        name?: string | undefined;
         instruction?: string | undefined;
         mcp?: {
             url?: string | undefined;
@@ -2267,9 +2300,16 @@ export declare const workflowZ: z.ZodObject<{
     judge_model?: string | undefined;
     workflow_type?: "pr_review" | "e2e_test" | "content_generation" | "monitor" | "data_sync" | "generic" | undefined;
     judge_budget?: number | undefined;
+    inputs?: Record<string, {
+        type: "string" | "number" | "boolean" | "string[]";
+        description?: string | undefined;
+        required?: boolean | undefined;
+        default?: unknown;
+        enum?: unknown[] | undefined;
+    }> | undefined;
 }, {
-    id: string;
     name: string;
+    id: string;
     nodes: Record<string, {
         name: string;
         instruction: string | {
@@ -2368,8 +2408,8 @@ export declare const workflowZ: z.ZodObject<{
     entry: string;
     description?: string | undefined;
     skills?: Record<string, {
-        name?: string | undefined;
         description?: string | undefined;
+        name?: string | undefined;
         instruction?: string | undefined;
         mcp?: {
             url?: string | undefined;
@@ -2399,15 +2439,22 @@ export declare const workflowZ: z.ZodObject<{
     judge_model?: string | undefined;
     workflow_type?: "pr_review" | "e2e_test" | "content_generation" | "monitor" | "data_sync" | "generic" | undefined;
     judge_budget?: number | undefined;
+    inputs?: Record<string, {
+        type: "string" | "number" | "boolean" | "string[]";
+        description?: string | undefined;
+        required?: boolean | undefined;
+        default?: unknown;
+        enum?: unknown[] | undefined;
+    }> | undefined;
 }>;
 /** Parse + validate a raw object as a Workflow. Throws on invalid input. */
 export declare function parseWorkflow(raw: unknown): {
-    id: string;
-    name: string;
     description: string;
+    name: string;
+    id: string;
     skills: Record<string, {
-        name?: string | undefined;
         description?: string | undefined;
+        name?: string | undefined;
         instruction?: string | undefined;
         mcp?: {
             url?: string | undefined;
@@ -2533,6 +2580,13 @@ export declare function parseWorkflow(raw: unknown): {
     judge_model?: string | undefined;
     workflow_type?: "pr_review" | "e2e_test" | "content_generation" | "monitor" | "data_sync" | "generic" | undefined;
     judge_budget?: number | undefined;
+    inputs?: Record<string, {
+        type: "string" | "number" | "boolean" | "string[]";
+        description?: string | undefined;
+        required?: boolean | undefined;
+        default?: unknown;
+        enum?: unknown[] | undefined;
+    }> | undefined;
 };
 export interface WorkflowError {
     code: "MISSING_ENTRY" | "UNKNOWN_EDGE_SOURCE" | "UNKNOWN_EDGE_TARGET" | "UNREACHABLE_NODE" | "UNKNOWN_SKILL" | "SELF_LOOP" | "UNBOUNDED_CYCLE" | "INVALID_INLINE_SKILL";
@@ -2802,6 +2856,39 @@ export declare const workflowJsonSchema: {
             readonly default: 50;
             readonly description: "Soft cap on expected judge calls per workflow run. Executor warns at load time if exceeded; not a hard runtime cap in v1.";
         };
+        readonly inputs: {
+            readonly type: "object";
+            readonly description: "Declared per-run input contract. Each entry names a parameter the caller may supply via --input. The CLI validates against this declaration, applies defaults for omitted optional fields, and rejects unknown types before the executor runs. Optional; workflows without an inputs block accept any JSON object (back-compat).";
+            readonly additionalProperties: {
+                readonly type: "object";
+                readonly required: readonly ["type"];
+                readonly additionalProperties: false;
+                readonly properties: {
+                    readonly type: {
+                        readonly type: "string";
+                        readonly enum: readonly ["string", "number", "boolean", "string[]"];
+                        readonly description: "JSON-native type. Use a flat object if you need richer shapes.";
+                    };
+                    readonly description: {
+                        readonly type: "string";
+                        readonly description: "Human-readable purpose. Shown in CLI help and cloud renderers.";
+                    };
+                    readonly required: {
+                        readonly type: "boolean";
+                        readonly default: false;
+                        readonly description: "When true, the caller must provide a value.";
+                    };
+                    readonly default: {
+                        readonly description: "Value applied when the caller omits the field. Type-checked at parse time against 'type'.";
+                    };
+                    readonly enum: {
+                        readonly type: "array";
+                        readonly minItems: 1;
+                        readonly description: "Optional set of allowed values. Validated after the type check.";
+                    };
+                };
+            };
+        };
         readonly nodes: {
             readonly type: "object";
             readonly additionalProperties: {

package/dist/schema.js

@@ -9,7 +9,9 @@
 import { z } from "zod";
 import { EVALUATOR_KINDS, EVAL_POLICIES, MCP_TRANSPORTS, REQUIRES_ON_FAIL, SKILL_CATEGORIES, SKILL_ID_MAX_LENGTH, SKILL_ID_PATTERN, } from "./types.js";
 import { sourceZ } from "./sources.js";
+import { workflowInputsZ, WORKFLOW_INPUT_TYPES } from "./inputs.js";
 export { sourceZ };
+export { workflowInputsZ };
 // ─── Zod Schemas ─────────────────────────────────────────────────
 export const jsonSchemaZ = z.record(z.unknown());
 export const configFieldZ = z.object({
@@ -241,6 +243,7 @@ export const workflowZ = z.object({
     context: z.array(sourceZ).optional(),
     judge_model: z.string().min(1).optional(),
     judge_budget: z.number().int().min(0).optional(),
+    inputs: workflowInputsZ.optional(),
 });
 const LEGACY_VERIFY_MESSAGE = "uses the legacy 'verify:' field. It was renamed to 'eval:' in @sweny-ai/core v0.2.0 with a different shape (named evaluators with kind: value | function | judge). " +
     "Migration guide: https://spec.sweny.ai/nodes/#eval";
@@ -572,6 +575,39 @@ export const workflowJsonSchema = {
             default: 50,
             description: "Soft cap on expected judge calls per workflow run. Executor warns at load time if exceeded; not a hard runtime cap in v1.",
         },
+        inputs: {
+            type: "object",
+            description: "Declared per-run input contract. Each entry names a parameter the caller may supply via --input. The CLI validates against this declaration, applies defaults for omitted optional fields, and rejects unknown types before the executor runs. Optional; workflows without an inputs block accept any JSON object (back-compat).",
+            additionalProperties: {
+                type: "object",
+                required: ["type"],
+                additionalProperties: false,
+                properties: {
+                    type: {
+                        type: "string",
+                        enum: [...WORKFLOW_INPUT_TYPES],
+                        description: "JSON-native type. Use a flat object if you need richer shapes.",
+                    },
+                    description: {
+                        type: "string",
+                        description: "Human-readable purpose. Shown in CLI help and cloud renderers.",
+                    },
+                    required: {
+                        type: "boolean",
+                        default: false,
+                        description: "When true, the caller must provide a value.",
+                    },
+                    default: {
+                        description: "Value applied when the caller omits the field. Type-checked at parse time against 'type'.",
+                    },
+                    enum: {
+                        type: "array",
+                        minItems: 1,
+                        description: "Optional set of allowed values. Validated after the type check.",
+                    },
+                },
+            },
+        },
         nodes: {
             type: "object",
             additionalProperties: {

package/dist/types.d.ts

@@ -1,4 +1,6 @@
 export type { Source, ResolvedSource, SourceKind, SourceResolutionMap } from "./sources.js";
+export type { WorkflowInputs, WorkflowInputField, WorkflowInputType, InputValidationError, InputValidationResult, } from "./inputs.js";
+export { WORKFLOW_INPUT_TYPES } from "./inputs.js";
 import type { Source as _Source, ResolvedSource as _ResolvedSource } from "./sources.js";
 export type JSONSchema = Record<string, unknown>;
 /** Context passed to tool handlers at execution time */
@@ -311,6 +313,16 @@ export interface Workflow {
     judge_model?: string;
     /** Soft cap on expected judge calls per workflow run. Warning at load time when exceeded. */
     judge_budget?: number;
+    /**
+     * Declared per-run input contract. When present, the CLI validates the
+     * caller-provided `--input` JSON against this declaration, applies defaults
+     * for omitted optional fields, and rejects malformed input before the
+     * executor runs. Workflows without an `inputs` block accept any JSON
+     * object (back-compat).
+     *
+     * See `src/inputs.ts` for the field shape and validation rules.
+     */
+    inputs?: import("./inputs.js").WorkflowInputs;
 }
 /**
  * Inline skill definition in a workflow's `skills` block.

package/dist/types.js

@@ -1,3 +1,4 @@
+export { WORKFLOW_INPUT_TYPES } from "./inputs.js";
 /**
  * Skill categories: used for per-node validation and grouping.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sweny-ai/core",
-  "version": "0.1.97",
+  "version": "0.1.99",
   "type": "module",
   "bin": {
     "sweny": "./dist/cli/main.js"