@hyperdrive.bot/paseo-protocol 0.3.35 → 0.3.37

package/dist/agent-labels.d.ts

@@ -1,9 +1,26 @@
 export declare const PARENT_AGENT_ID_LABEL = "paseo.parent-agent-id";
 export declare const WORKFLOW_ID_LABEL = "paseo.workflow-id";
 export declare const WORKFLOW_TASK_ID_LABEL = "paseo.workflow-task-id";
+export declare const LOOP_NAME_LABEL = "loop";
+export declare const LOOP_RUN_LABEL = "run";
 export interface AgentLabelSource {
     labels?: Record<string, unknown> | null;
 }
 export declare function getParentAgentIdFromLabels(labels: Record<string, unknown> | null | undefined): string | null;
 export declare function isDelegatedAgent(agent: AgentLabelSource): boolean;
+export declare const LOOP_ADOPTED_AT_LABEL = "loop.adopted-at";
+export declare function getLoopNameFromLabels(labels: Record<string, unknown> | null | undefined): string | null;
+export declare function getLoopRunFromLabels(labels: Record<string, unknown> | null | undefined): string | null;
+export declare function getLoopAdoptedAtFromLabels(labels: Record<string, unknown> | null | undefined): string | null;
+/** Any agent a loop spawned, adopted or not. Use for provenance ("from loop X"). */
+export declare function isLoopAgent(agent: AgentLabelSource): boolean;
+/**
+ * A loop execution still in loop custody, the set the general session surfaces hide.
+ * Adopted sessions return `false`: they are the user's now and belong back in the lists.
+ *
+ * Hiding is a LIST concern only. Attention surfaces (favicon, background activity, push)
+ * must keep counting these, otherwise a loop that needs a permission goes silent and the
+ * whole HITL story dies. See docs/loops.md.
+ */
+export declare function isLoopExecutionAgent(agent: AgentLabelSource): boolean;
 //# sourceMappingURL=agent-labels.d.ts.map

package/dist/agent-labels.js

@@ -11,6 +11,12 @@ export const WORKFLOW_ID_LABEL = "paseo.workflow-id";
 // Children must already be scoped to a single workflow (via WORKFLOW_ID_LABEL) before
 // being mapped — task ids are only unique within one workflow's graph.
 export const WORKFLOW_TASK_ID_LABEL = "paseo.workflow-task-id";
+// Loop fleet (super-repo automation loops surfaced in the UI as "Loops"). A loop
+// execution agent carries loop=<loop-name> for per-loop attribution + the Executions
+// view, and run=<timestamp> for the specific tick. Producer: the paseo engine in
+// tooling/loops/lib/run-agent.sh (`paseo agent run --label loop=<name> --label run=<ts>`).
+export const LOOP_NAME_LABEL = "loop";
+export const LOOP_RUN_LABEL = "run";
 export function getParentAgentIdFromLabels(labels) {
     const parentAgentId = labels?.[PARENT_AGENT_ID_LABEL];
     return typeof parentAgentId === "string" && parentAgentId.trim().length > 0
@@ -20,4 +26,40 @@ export function getParentAgentIdFromLabels(labels) {
 export function isDelegatedAgent(agent) {
     return getParentAgentIdFromLabels(agent.labels) !== null;
 }
+// Adoption (loop custody hand-off). A loop execution agent is hidden from the general
+// session surfaces (Sessions, kanban, sidebar, command center) and appears only inside
+// the Loops feature. Adoption is the escape hatch: once a human takes the session over,
+// it leaves loop custody and behaves like any other session, keeping the `loop=<name>`
+// label purely as lineage so the "from loop" provenance chip still renders.
+//
+// The rule, in one line: a loop session is invisible until you touch it. Reading or
+// interrogating it does NOT count as touching; taking it over does.
+export const LOOP_ADOPTED_AT_LABEL = "loop.adopted-at";
+export function getLoopNameFromLabels(labels) {
+    const loopName = labels?.[LOOP_NAME_LABEL];
+    return typeof loopName === "string" && loopName.trim().length > 0 ? loopName.trim() : null;
+}
+export function getLoopRunFromLabels(labels) {
+    const run = labels?.[LOOP_RUN_LABEL];
+    return typeof run === "string" && run.trim().length > 0 ? run.trim() : null;
+}
+export function getLoopAdoptedAtFromLabels(labels) {
+    const adoptedAt = labels?.[LOOP_ADOPTED_AT_LABEL];
+    return typeof adoptedAt === "string" && adoptedAt.trim().length > 0 ? adoptedAt.trim() : null;
+}
+/** Any agent a loop spawned, adopted or not. Use for provenance ("from loop X"). */
+export function isLoopAgent(agent) {
+    return getLoopNameFromLabels(agent.labels) !== null;
+}
+/**
+ * A loop execution still in loop custody, the set the general session surfaces hide.
+ * Adopted sessions return `false`: they are the user's now and belong back in the lists.
+ *
+ * Hiding is a LIST concern only. Attention surfaces (favicon, background activity, push)
+ * must keep counting these, otherwise a loop that needs a permission goes silent and the
+ * whole HITL story dies. See docs/loops.md.
+ */
+export function isLoopExecutionAgent(agent) {
+    return isLoopAgent(agent) && getLoopAdoptedAtFromLabels(agent.labels) === null;
+}
 //# sourceMappingURL=agent-labels.js.map

package/dist/fleet/decisions.d.ts

@@ -0,0 +1,178 @@
+import { z } from "zod";
+/**
+ * Loop decisions: the typed question a loop asks a human, and the record of how it
+ * was answered.
+ *
+ * A loop that needs a person does NOT emit a string and hope. It emits options with
+ * effects, so the UI can render buttons, a phone notification can carry the actual
+ * choices, and the resolution is attributable afterwards.
+ */
+/**
+ * What silence means. This is the field the UI must surface FIRST on every decision,
+ * because with a per-decision posture the same empty inbox can mean three different
+ * things: nothing is happening, work is frozen waiting for you, or work already
+ * happened while you were away.
+ *
+ * - `blocking`   the item freezes until answered (the loop keeps ticking other items)
+ * - `deferring`  the item is skipped this tick and re-offered on the next one
+ * - `advisory`   the option runs now, you are told, and you can revoke it in the window
+ */
+export declare const LoopDecisionPostureSchema: z.ZodEnum<{
+    blocking: "blocking";
+    deferring: "deferring";
+    advisory: "advisory";
+}>;
+export type LoopDecisionPosture = z.infer<typeof LoopDecisionPostureSchema>;
+/**
+ * How undoable an option's effect is. Posture is BOUNDED by this: you cannot repent of
+ * a sacrament, so an irreversible effect may never be `advisory` (see
+ * `assertDecisionIsSound`). Advisory on an irreversible act would mean the loop acts
+ * unsupervised with an undo button that cannot actually undo.
+ */
+export declare const LoopEffectReversibilitySchema: z.ZodEnum<{
+    reversible: "reversible";
+    compensable: "compensable";
+    irreversible: "irreversible";
+}>;
+export type LoopEffectReversibility = z.infer<typeof LoopEffectReversibilitySchema>;
+export declare const LoopDecisionEffectSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        act: "act";
+        rehearse: "rehearse";
+        defer: "defer";
+        suppress: "suppress";
+    }>;
+    reversibility: z.ZodEnum<{
+        reversible: "reversible";
+        compensable: "compensable";
+        irreversible: "irreversible";
+    }>;
+    compensatingAction: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type LoopDecisionEffect = z.infer<typeof LoopDecisionEffectSchema>;
+export declare const LoopDecisionOptionSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    effect: z.ZodObject<{
+        kind: z.ZodEnum<{
+            act: "act";
+            rehearse: "rehearse";
+            defer: "defer";
+            suppress: "suppress";
+        }>;
+        reversibility: z.ZodEnum<{
+            reversible: "reversible";
+            compensable: "compensable";
+            irreversible: "irreversible";
+        }>;
+        compensatingAction: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type LoopDecisionOption = z.infer<typeof LoopDecisionOptionSchema>;
+export declare const LoopDecisionKindSchema: z.ZodEnum<{
+    "gate-approval": "gate-approval";
+    "action-approval": "action-approval";
+    "outcome-review": "outcome-review";
+}>;
+export type LoopDecisionKind = z.infer<typeof LoopDecisionKindSchema>;
+export declare const LoopDecisionResolverSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"human">;
+    userId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"expiry">;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"policy">;
+    rule: z.ZodString;
+}, z.core.$strip>], "kind">;
+export type LoopDecisionResolver = z.infer<typeof LoopDecisionResolverSchema>;
+export declare const LoopDecisionSchema: z.ZodObject<{
+    id: z.ZodString;
+    loopName: z.ZodString;
+    runId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    itemKey: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    kind: z.ZodEnum<{
+        "gate-approval": "gate-approval";
+        "action-approval": "action-approval";
+        "outcome-review": "outcome-review";
+    }>;
+    question: z.ZodString;
+    evidence: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    posture: z.ZodEnum<{
+        blocking: "blocking";
+        deferring: "deferring";
+        advisory: "advisory";
+    }>;
+    options: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        effect: z.ZodObject<{
+            kind: z.ZodEnum<{
+                act: "act";
+                rehearse: "rehearse";
+                defer: "defer";
+                suppress: "suppress";
+            }>;
+            reversibility: z.ZodEnum<{
+                reversible: "reversible";
+                compensable: "compensable";
+                irreversible: "irreversible";
+            }>;
+            compensatingAction: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+    onExpiry: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    expiresAt: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    createdAt: z.ZodString;
+    resolvedAt: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    resolvedOptionId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    resolvedBy: z.ZodDefault<z.ZodNullable<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"human">;
+        userId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"expiry">;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"policy">;
+        rule: z.ZodString;
+    }, z.core.$strip>], "kind">>>;
+}, z.core.$strip>;
+export type LoopDecision = z.infer<typeof LoopDecisionSchema>;
+export interface CreateLoopDecisionInput {
+    loopName: string;
+    kind: LoopDecisionKind;
+    question: string;
+    posture: LoopDecisionPosture;
+    options: LoopDecisionOption[];
+    runId?: string | null;
+    itemKey?: string | null;
+    evidence?: string | null;
+    onExpiry?: string | null;
+    /** Relative lifetime; the service stamps `expiresAt` from it. */
+    expiresInMs?: number | null;
+}
+/**
+ * Reject decisions that are unsound rather than letting them reach a human.
+ *
+ * Two rules, both load-bearing:
+ *  1. advisory + irreversible is refused outright. Not warned about: refused.
+ *  2. anything that can expire must say what expiring does, and that option must exist.
+ */
+export declare function assertDecisionIsSound(input: {
+    posture: LoopDecisionPosture;
+    options: readonly LoopDecisionOption[];
+    onExpiry?: string | null;
+    expiresAt?: string | null;
+    expiresInMs?: number | null;
+}): void;
+/** Decisions still awaiting an answer. */
+export declare function isDecisionPending(decision: LoopDecision): boolean;
+/**
+ * Sort key for the decision inbox: ascending time-to-consequence.
+ *
+ * Decisions that never expire sort LAST, which is deliberately counterintuitive. They
+ * feel the most urgent, yet they are the only ones where nothing happens if you look
+ * tomorrow. The ticking ones are where inaction is a decision you did not know you
+ * were making.
+ */
+export declare function decisionUrgency(decision: LoopDecision, now: number): number;
+export declare function sortDecisionsByUrgency(decisions: readonly LoopDecision[], now: number): LoopDecision[];
+//# sourceMappingURL=decisions.d.ts.map

package/dist/fleet/decisions.js

@@ -0,0 +1,149 @@
+import { z } from "zod";
+/**
+ * Loop decisions: the typed question a loop asks a human, and the record of how it
+ * was answered.
+ *
+ * A loop that needs a person does NOT emit a string and hope. It emits options with
+ * effects, so the UI can render buttons, a phone notification can carry the actual
+ * choices, and the resolution is attributable afterwards.
+ */
+/**
+ * What silence means. This is the field the UI must surface FIRST on every decision,
+ * because with a per-decision posture the same empty inbox can mean three different
+ * things: nothing is happening, work is frozen waiting for you, or work already
+ * happened while you were away.
+ *
+ * - `blocking`   the item freezes until answered (the loop keeps ticking other items)
+ * - `deferring`  the item is skipped this tick and re-offered on the next one
+ * - `advisory`   the option runs now, you are told, and you can revoke it in the window
+ */
+export const LoopDecisionPostureSchema = z.enum(["blocking", "deferring", "advisory"]);
+/**
+ * How undoable an option's effect is. Posture is BOUNDED by this: you cannot repent of
+ * a sacrament, so an irreversible effect may never be `advisory` (see
+ * `assertDecisionIsSound`). Advisory on an irreversible act would mean the loop acts
+ * unsupervised with an undo button that cannot actually undo.
+ */
+export const LoopEffectReversibilitySchema = z.enum([
+    /** A clean inverse exists and the loop owns it (close the MR, delete the branch). */
+    "reversible",
+    /** No inverse, but a visible correction is possible (post a retraction). */
+    "compensable",
+    /** It left your control: message delivered, money moved, prod touched. */
+    "irreversible",
+]);
+export const LoopDecisionEffectSchema = z.object({
+    kind: z.enum(["act", "rehearse", "defer", "suppress"]),
+    reversibility: LoopEffectReversibilitySchema,
+    /**
+     * Required for a `compensable` effect offered under an `advisory` posture: the UI
+     * must name the correction ("post a retraction"), never a generic "undo".
+     */
+    compensatingAction: z.string().trim().min(1).optional(),
+});
+export const LoopDecisionOptionSchema = z.object({
+    id: z.string().trim().min(1),
+    label: z.string().trim().min(1),
+    effect: LoopDecisionEffectSchema,
+});
+export const LoopDecisionKindSchema = z.enum([
+    /** Before any action: "the gate found 6, act on these?" */
+    "gate-approval",
+    /** Mid-run, for one item. */
+    "action-approval",
+    /** After the fact: "it says it opened MR !412, did it?" */
+    "outcome-review",
+]);
+export const LoopDecisionResolverSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("human"), userId: z.string().optional() }),
+    /** Resolved by the clock running out, applying `onExpiry`. Never silent. */
+    z.object({ kind: z.literal("expiry") }),
+    z.object({ kind: z.literal("policy"), rule: z.string() }),
+]);
+export const LoopDecisionSchema = z.object({
+    id: z.string(),
+    loopName: z.string().trim().min(1),
+    runId: z.string().nullable().default(null),
+    itemKey: z.string().nullable().default(null),
+    kind: LoopDecisionKindSchema,
+    question: z.string().trim().min(1),
+    /** What the gate saw, rendered next to the question so the answer is informed. */
+    evidence: z.string().nullable().default(null),
+    posture: LoopDecisionPostureSchema,
+    options: z.array(LoopDecisionOptionSchema).min(1),
+    /**
+     * Which option fires when the clock runs out. REQUIRED unless the decision is
+     * `blocking` with no expiry, i.e. the only shape where waiting forever is the
+     * declared behaviour. An author who will not say what happens when nobody answers
+     * has not finished thinking about the decision.
+     */
+    onExpiry: z.string().nullable().default(null),
+    expiresAt: z.string().nullable().default(null),
+    createdAt: z.string(),
+    resolvedAt: z.string().nullable().default(null),
+    resolvedOptionId: z.string().nullable().default(null),
+    resolvedBy: LoopDecisionResolverSchema.nullable().default(null),
+});
+/**
+ * Reject decisions that are unsound rather than letting them reach a human.
+ *
+ * Two rules, both load-bearing:
+ *  1. advisory + irreversible is refused outright. Not warned about: refused.
+ *  2. anything that can expire must say what expiring does, and that option must exist.
+ */
+export function assertDecisionIsSound(input) {
+    const ids = new Set();
+    for (const option of input.options) {
+        if (ids.has(option.id)) {
+            throw new Error(`Duplicate decision option id: ${option.id}`);
+        }
+        ids.add(option.id);
+        if (input.posture === "advisory" && option.effect.reversibility === "irreversible") {
+            throw new Error(`Option "${option.id}" is irreversible and cannot be offered under an advisory posture: ` +
+                "it would act unsupervised with an undo that cannot undo.");
+        }
+        if (input.posture === "advisory" &&
+            option.effect.reversibility === "compensable" &&
+            !option.effect.compensatingAction) {
+            throw new Error(`Option "${option.id}" is compensable under an advisory posture and must name its ` +
+                "compensating action, so the UI can offer it by name instead of a generic undo.");
+        }
+    }
+    const canExpire = input.expiresAt != null || (input.expiresInMs != null && input.expiresInMs > 0);
+    const waitsForever = input.posture === "blocking" && !canExpire;
+    if (!waitsForever && !input.onExpiry) {
+        throw new Error("onExpiry is required: a decision that can time out must declare what timing out does.");
+    }
+    if (input.onExpiry && !ids.has(input.onExpiry)) {
+        throw new Error(`onExpiry "${input.onExpiry}" is not one of the decision's options.`);
+    }
+}
+/** Decisions still awaiting an answer. */
+export function isDecisionPending(decision) {
+    return decision.resolvedAt === null;
+}
+/**
+ * Sort key for the decision inbox: ascending time-to-consequence.
+ *
+ * Decisions that never expire sort LAST, which is deliberately counterintuitive. They
+ * feel the most urgent, yet they are the only ones where nothing happens if you look
+ * tomorrow. The ticking ones are where inaction is a decision you did not know you
+ * were making.
+ */
+export function decisionUrgency(decision, now) {
+    if (decision.expiresAt === null) {
+        return Number.POSITIVE_INFINITY;
+    }
+    return new Date(decision.expiresAt).getTime() - now;
+}
+export function sortDecisionsByUrgency(decisions, now) {
+    return [...decisions].sort((left, right) => {
+        const delta = decisionUrgency(left, now) - decisionUrgency(right, now);
+        if (Number.isNaN(delta) || delta === 0) {
+            // Stable tiebreak so the inbox does not reshuffle between renders.
+            return left.createdAt.localeCompare(right.createdAt);
+        }
+        return delta;
+    });
+}
+//# sourceMappingURL=decisions.js.map

package/dist/fleet/params.d.ts

@@ -0,0 +1,84 @@
+import { z } from "zod";
+/**
+ * Loop parameters: a loop declares the knobs it takes, and the client renders the
+ * config form from that declaration instead of hard-coding one form per loop.
+ *
+ * This is deliberately NOT full JSON Schema. A loop's knobs are a flat list of scalar
+ * fields, and a small closed vocabulary is renderable, validatable, and reviewable;
+ * full JSON Schema would let a loop declare shapes the form could not draw, which
+ * turns "schema-driven" into "sometimes-driven".
+ *
+ * On disk, inside the loop's own directory:
+ *   params.schema.json   the declaration (committed with the loop)
+ *   params.json          the current values (written by the app)
+ */
+export declare const LoopParamTypeSchema: z.ZodEnum<{
+    string: "string";
+    number: "number";
+    boolean: "boolean";
+    enum: "enum";
+    "string-list": "string-list";
+}>;
+export type LoopParamType = z.infer<typeof LoopParamTypeSchema>;
+export declare const LoopParamFieldSchema: z.ZodObject<{
+    key: z.ZodString;
+    label: z.ZodString;
+    type: z.ZodEnum<{
+        string: "string";
+        number: "number";
+        boolean: "boolean";
+        enum: "enum";
+        "string-list": "string-list";
+    }>;
+    description: z.ZodOptional<z.ZodString>;
+    required: z.ZodDefault<z.ZodBoolean>;
+    options: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    min: z.ZodOptional<z.ZodNumber>;
+    max: z.ZodOptional<z.ZodNumber>;
+    default: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+export type LoopParamField = z.infer<typeof LoopParamFieldSchema>;
+export declare const LoopParamsSchemaSchema: z.ZodObject<{
+    fields: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        label: z.ZodString;
+        type: z.ZodEnum<{
+            string: "string";
+            number: "number";
+            boolean: "boolean";
+            enum: "enum";
+            "string-list": "string-list";
+        }>;
+        description: z.ZodOptional<z.ZodString>;
+        required: z.ZodDefault<z.ZodBoolean>;
+        options: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        min: z.ZodOptional<z.ZodNumber>;
+        max: z.ZodOptional<z.ZodNumber>;
+        default: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type LoopParamsSchema = z.infer<typeof LoopParamsSchemaSchema>;
+export declare const LoopParamValueSchema: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>;
+export type LoopParamValue = z.infer<typeof LoopParamValueSchema>;
+export type LoopParamValues = Record<string, LoopParamValue>;
+export interface LoopParamIssue {
+    key: string;
+    message: string;
+}
+/**
+ * Validate values against a loop's declared fields.
+ *
+ * Returns every issue rather than throwing on the first, so the form can mark all the
+ * bad fields at once instead of making the user resubmit to find the next one. Unknown
+ * keys are reported too: silently dropping one would let a user "save" a value the loop
+ * never receives.
+ */
+export declare function validateLoopParams(schema: LoopParamsSchema, values: LoopParamValues): LoopParamIssue[];
+/** Values a loop starts with: every field's declared default, where it has one. */
+export declare function defaultLoopParams(schema: LoopParamsSchema): LoopParamValues;
+/**
+ * Render values as env vars for the loop's runner. Lists join on commas and booleans
+ * become 1/0, which is what a bash runner can consume without a JSON parser.
+ */
+export declare function loopParamsToEnv(values: LoopParamValues): Record<string, string>;
+//# sourceMappingURL=params.d.ts.map

package/dist/fleet/params.js

@@ -0,0 +1,142 @@
+import { z } from "zod";
+/**
+ * Loop parameters: a loop declares the knobs it takes, and the client renders the
+ * config form from that declaration instead of hard-coding one form per loop.
+ *
+ * This is deliberately NOT full JSON Schema. A loop's knobs are a flat list of scalar
+ * fields, and a small closed vocabulary is renderable, validatable, and reviewable;
+ * full JSON Schema would let a loop declare shapes the form could not draw, which
+ * turns "schema-driven" into "sometimes-driven".
+ *
+ * On disk, inside the loop's own directory:
+ *   params.schema.json   the declaration (committed with the loop)
+ *   params.json          the current values (written by the app)
+ */
+export const LoopParamTypeSchema = z.enum(["string", "number", "boolean", "enum", "string-list"]);
+export const LoopParamFieldSchema = z.object({
+    key: z
+        .string()
+        .trim()
+        .min(1)
+        // Values are handed to a shell runner as env vars, so the key has to be a safe
+        // identifier rather than arbitrary text.
+        .regex(/^[A-Za-z_][A-Za-z0-9_]*$/, "param key must be a valid identifier"),
+    label: z.string().trim().min(1),
+    type: LoopParamTypeSchema,
+    description: z.string().optional(),
+    required: z.boolean().default(false),
+    /** Allowed values, required when `type` is `enum`. */
+    options: z.array(z.string()).optional(),
+    min: z.number().optional(),
+    max: z.number().optional(),
+    default: z.unknown().optional(),
+});
+export const LoopParamsSchemaSchema = z.object({
+    fields: z.array(LoopParamFieldSchema),
+});
+export const LoopParamValueSchema = z.union([
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.array(z.string()),
+]);
+/**
+ * Validate values against a loop's declared fields.
+ *
+ * Returns every issue rather than throwing on the first, so the form can mark all the
+ * bad fields at once instead of making the user resubmit to find the next one. Unknown
+ * keys are reported too: silently dropping one would let a user "save" a value the loop
+ * never receives.
+ */
+export function validateLoopParams(schema, values) {
+    const issues = [];
+    const declared = new Set(schema.fields.map((field) => field.key));
+    for (const key of Object.keys(values)) {
+        if (!declared.has(key)) {
+            issues.push({ key, message: `"${key}" is not a parameter this loop declares` });
+        }
+    }
+    for (const field of schema.fields) {
+        const value = values[field.key];
+        if (value === undefined || value === null || value === "") {
+            if (field.required) {
+                issues.push({ key: field.key, message: `${field.label} is required` });
+            }
+            continue;
+        }
+        issues.push(...validateField(field, value));
+    }
+    return issues;
+}
+/** Type-specific checks for one field, split out to keep each rule readable. */
+function validateField(field, value) {
+    switch (field.type) {
+        case "string":
+            return typeof value === "string"
+                ? []
+                : [{ key: field.key, message: `${field.label} must be text` }];
+        case "number":
+            return validateNumberField(field, value);
+        case "boolean":
+            return typeof value === "boolean"
+                ? []
+                : [{ key: field.key, message: `${field.label} must be true or false` }];
+        case "enum":
+            return typeof value === "string" && (field.options ?? []).includes(value)
+                ? []
+                : [
+                    {
+                        key: field.key,
+                        message: `${field.label} must be one of: ${(field.options ?? []).join(", ")}`,
+                    },
+                ];
+        case "string-list":
+            return Array.isArray(value) && value.every((entry) => typeof entry === "string")
+                ? []
+                : [{ key: field.key, message: `${field.label} must be a list of text values` }];
+    }
+}
+function validateNumberField(field, value) {
+    if (typeof value !== "number" || Number.isNaN(value)) {
+        return [{ key: field.key, message: `${field.label} must be a number` }];
+    }
+    const issues = [];
+    if (field.min !== undefined && value < field.min) {
+        issues.push({ key: field.key, message: `${field.label} must be at least ${field.min}` });
+    }
+    if (field.max !== undefined && value > field.max) {
+        issues.push({ key: field.key, message: `${field.label} must be at most ${field.max}` });
+    }
+    return issues;
+}
+/** Values a loop starts with: every field's declared default, where it has one. */
+export function defaultLoopParams(schema) {
+    const values = {};
+    for (const field of schema.fields) {
+        const parsed = LoopParamValueSchema.safeParse(field.default);
+        if (parsed.success) {
+            values[field.key] = parsed.data;
+        }
+    }
+    return values;
+}
+/**
+ * Render values as env vars for the loop's runner. Lists join on commas and booleans
+ * become 1/0, which is what a bash runner can consume without a JSON parser.
+ */
+export function loopParamsToEnv(values) {
+    const env = {};
+    for (const [key, value] of Object.entries(values)) {
+        if (Array.isArray(value)) {
+            env[key] = value.join(",");
+        }
+        else if (typeof value === "boolean") {
+            env[key] = value ? "1" : "0";
+        }
+        else {
+            env[key] = String(value);
+        }
+    }
+    return env;
+}
+//# sourceMappingURL=params.js.map