@camstack/types 1.2.429 → 1.2.430

package/dist/automation/step-runner.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The ONE step runner — shared by an internal Action and by the block an
+ * automation recipe compiles to. It is pure: it knows nothing about `ctx`, the
+ * hub or a clock beyond the functions it is handed.
+ *
+ * Contract (the one the NC runner it mirrors set): steps run in order, the
+ * sequence STOPS at the first failure (continuing past a failed step executes
+ * an intent the operator never expressed), and every step is traced — the ones
+ * after a failure, or after an abort, are `not-run` with the reason.
+ */
+import type { ActionStep } from './recipe.js';
+import type { AutomationStepTrace } from './trace.js';
+/** Static facts about a step, known before it runs. */
+export interface StepMeta {
+    readonly kind: string;
+    readonly cap?: string;
+    readonly method?: string;
+    readonly deviceId?: number;
+}
+/** What a running step can tell the runner (the device a fan-out is on right now). */
+export interface StepScope {
+    setDeviceId(deviceId: number): void;
+}
+/** One step as the runner sees it: its meta and a closure that does the work. */
+export interface RunnableStep {
+    readonly meta: StepMeta;
+    run(scope: StepScope): Promise<void>;
+}
+export interface StepFailure {
+    readonly index: number;
+    readonly path: string;
+    readonly message: string;
+    readonly deviceId: number | undefined;
+}
+export interface RunStepsOptions {
+    /** `actions` for an automation, `steps` for an Action run. */
+    readonly pathPrefix: string;
+    /** True once the run was cut short (a restart, a stop). Checked between steps. */
+    readonly isAborted: () => boolean;
+    readonly abortReason: string;
+    readonly now: () => number;
+    /** Called once, for the step that failed. */
+    readonly onFailure: (failure: StepFailure) => void;
+}
+export interface RunStepsResult {
+    readonly steps: readonly AutomationStepTrace[];
+    readonly failed: boolean;
+    readonly aborted: boolean;
+}
+export declare function runSteps(steps: readonly RunnableStep[], options: RunStepsOptions): Promise<RunStepsResult>;
+/** The bag of values `{ $var }` and `{{vars.x}}` read from. */
+export type StepVars = Readonly<Record<string, unknown>>;
+/**
+ * Substitute a step's args from the run's variables. SUBSTITUTION only, never
+ * evaluation:
+ *  - a value that is exactly `{ $var: 'name' }` becomes the variable's value,
+ *    keeping its type (a number stays a number);
+ *  - `{{vars.name}}` inside a string becomes its text.
+ * A variable that is not set THROWS — a step must not run with a hole where
+ * the operator meant a value. (`{{vars.x}}` keeps the automation behaviour:
+ * the hole is reported through `onMissing` and rendered empty.)
+ */
+export declare function resolveStepArgs(value: unknown, vars: StepVars, onMissing: (name: string) => void): unknown;
+/** A `{ $var }` device target, resolved from the bag BEFORE dispatch. */
+export declare function resolveDeviceTarget(vars: StepVars, name: string): number;
+export interface CapCall {
+    readonly deviceId: number;
+    readonly cap: string;
+    readonly method: string;
+    readonly args: Readonly<Record<string, unknown>>;
+}
+export interface ActionStepDeps {
+    invokeCap(call: CapCall): Promise<void>;
+    sleep(ms: number): Promise<void>;
+    onMissingVar(name: string): void;
+}
+/**
+ * The runnable form of an internal Action's steps, bound to one run's
+ * variables. Variables are substituted per step, at the moment it runs, so a
+ * missing one fails THAT step (traced) and leaves the later ones not-run.
+ */
+export declare function buildActionSteps(steps: readonly ActionStep[], vars: StepVars, deps: ActionStepDeps): RunnableStep[];

package/dist/automation/trace.d.ts

@@ -0,0 +1,325 @@
+/**
+ * Run traces — what an automation (or, later, an Action run) DID, node by node,
+ * so the editor can paint every block green or red with its reason.
+ *
+ * A trace is data, not a log: it covers the WHOLE tree — the trigger stage,
+ * every condition node (containers and leaves, including the ones a
+ * short-circuit never reached), the run-mode verdict and every action step —
+ * each addressed by a stable path (`conditions.0.1`, `actions.2`, or `steps.N`
+ * for an Action run). Skipped
+ * evaluations are traced too, and identical consecutive skips collapse into a
+ * repeat count so a trigger that fails every 5 minutes cannot flush real runs.
+ *
+ * {@link AutomationStepTraceSchema} is deliberately free of automation
+ * vocabulary so an Action run records the same step shape.
+ */
+import { z } from 'zod';
+/** A value a trace may show: JSON primitives and short lists, nothing deeper. */
+export declare const TraceValueSchema: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>]>;
+export type TraceValue = z.infer<typeof TraceValueSchema>;
+export declare const AutomationRunOutcomeSchema: z.ZodEnum<{
+    aborted: "aborted";
+    failed: "failed";
+    ran: "ran";
+    "skipped-conditions": "skipped-conditions";
+    "skipped-cooldown": "skipped-cooldown";
+    "skipped-overlap": "skipped-overlap";
+    "skipped-trigger": "skipped-trigger";
+}>;
+export type AutomationRunOutcome = z.infer<typeof AutomationRunOutcomeSchema>;
+/** `not-evaluated` = a short-circuit never reached the node. */
+export declare const TraceNodeOutcomeSchema: z.ZodEnum<{
+    fail: "fail";
+    "not-evaluated": "not-evaluated";
+    pass: "pass";
+}>;
+export type TraceNodeOutcome = z.infer<typeof TraceNodeOutcomeSchema>;
+export declare const AutomationTriggerTraceSchema: z.ZodObject<{
+    kind: z.ZodString;
+    outcome: z.ZodEnum<{
+        fail: "fail";
+        pass: "pass";
+    }>;
+    reason: z.ZodString;
+    vars: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>]>>;
+}, z.core.$strip>;
+export type AutomationTriggerTrace = z.infer<typeof AutomationTriggerTraceSchema>;
+export declare const AutomationConditionTraceNodeSchema: z.ZodObject<{
+    path: z.ZodString;
+    kind: z.ZodEnum<{
+        all: "all";
+        any: "any";
+        condition: "condition";
+        expression: "expression";
+        not: "not";
+    }>;
+    outcome: z.ZodEnum<{
+        fail: "fail";
+        "not-evaluated": "not-evaluated";
+        pass: "pass";
+    }>;
+    reason: z.ZodString;
+    deviceId: z.ZodOptional<z.ZodNumber>;
+    cap: z.ZodOptional<z.ZodString>;
+    fieldPath: z.ZodOptional<z.ZodString>;
+    operator: z.ZodOptional<z.ZodString>;
+    expected: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>]>>;
+    observed: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>]>>;
+}, z.core.$strip>;
+export type AutomationConditionTraceNode = z.infer<typeof AutomationConditionTraceNodeSchema>;
+export declare const AutomationRunVerdictSchema: z.ZodObject<{
+    mode: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        mode: z.ZodLiteral<"single">;
+    }, z.core.$strip>, z.ZodObject<{
+        mode: z.ZodLiteral<"restart">;
+    }, z.core.$strip>, z.ZodObject<{
+        mode: z.ZodLiteral<"queued">;
+        max: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        mode: z.ZodLiteral<"parallel">;
+        max: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        mode: z.ZodLiteral<"cooldown">;
+        minutes: z.ZodNumber;
+    }, z.core.$strip>], "mode">;
+    decision: z.ZodEnum<{
+        bypass: "bypass";
+        cooldown: "cooldown";
+        drop: "drop";
+        queued: "queued";
+        restart: "restart";
+        run: "run";
+    }>;
+    reason: z.ZodString;
+}, z.core.$strip>;
+export type AutomationRunVerdict = z.infer<typeof AutomationRunVerdictSchema>;
+/** One executed (or not-run) step — shared by automations and Action runs. */
+export declare const AutomationStepTraceSchema: z.ZodObject<{
+    path: z.ZodString;
+    kind: z.ZodString;
+    cap: z.ZodOptional<z.ZodString>;
+    method: z.ZodOptional<z.ZodString>;
+    deviceId: z.ZodOptional<z.ZodNumber>;
+    startedAt: z.ZodOptional<z.ZodNumber>;
+    endedAt: z.ZodOptional<z.ZodNumber>;
+    outcome: z.ZodEnum<{
+        error: "error";
+        "not-run": "not-run";
+        ok: "ok";
+    }>;
+    message: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type AutomationStepTrace = z.infer<typeof AutomationStepTraceSchema>;
+export declare const AutomationRunTraceSchema: z.ZodObject<{
+    runId: z.ZodString;
+    startedAt: z.ZodNumber;
+    endedAt: z.ZodNumber;
+    trigger: z.ZodObject<{
+        kind: z.ZodString;
+        outcome: z.ZodEnum<{
+            fail: "fail";
+            pass: "pass";
+        }>;
+        reason: z.ZodString;
+        vars: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>]>>;
+    }, z.core.$strip>;
+    conditions: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        kind: z.ZodEnum<{
+            all: "all";
+            any: "any";
+            condition: "condition";
+            expression: "expression";
+            not: "not";
+        }>;
+        outcome: z.ZodEnum<{
+            fail: "fail";
+            "not-evaluated": "not-evaluated";
+            pass: "pass";
+        }>;
+        reason: z.ZodString;
+        deviceId: z.ZodOptional<z.ZodNumber>;
+        cap: z.ZodOptional<z.ZodString>;
+        fieldPath: z.ZodOptional<z.ZodString>;
+        operator: z.ZodOptional<z.ZodString>;
+        expected: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>]>>;
+        observed: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>]>>;
+    }, z.core.$strip>>;
+    verdict: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            mode: z.ZodLiteral<"single">;
+        }, z.core.$strip>, z.ZodObject<{
+            mode: z.ZodLiteral<"restart">;
+        }, z.core.$strip>, z.ZodObject<{
+            mode: z.ZodLiteral<"queued">;
+            max: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            mode: z.ZodLiteral<"parallel">;
+            max: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            mode: z.ZodLiteral<"cooldown">;
+            minutes: z.ZodNumber;
+        }, z.core.$strip>], "mode">;
+        decision: z.ZodEnum<{
+            bypass: "bypass";
+            cooldown: "cooldown";
+            drop: "drop";
+            queued: "queued";
+            restart: "restart";
+            run: "run";
+        }>;
+        reason: z.ZodString;
+    }, z.core.$strip>>;
+    steps: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        kind: z.ZodString;
+        cap: z.ZodOptional<z.ZodString>;
+        method: z.ZodOptional<z.ZodString>;
+        deviceId: z.ZodOptional<z.ZodNumber>;
+        startedAt: z.ZodOptional<z.ZodNumber>;
+        endedAt: z.ZodOptional<z.ZodNumber>;
+        outcome: z.ZodEnum<{
+            error: "error";
+            "not-run": "not-run";
+            ok: "ok";
+        }>;
+        message: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    outcome: z.ZodEnum<{
+        aborted: "aborted";
+        failed: "failed";
+        ran: "ran";
+        "skipped-conditions": "skipped-conditions";
+        "skipped-cooldown": "skipped-cooldown";
+        "skipped-overlap": "skipped-overlap";
+        "skipped-trigger": "skipped-trigger";
+    }>;
+    repeat: z.ZodNumber;
+    lastAt: z.ZodNumber;
+}, z.core.$strip>;
+export type AutomationRunTrace = z.infer<typeof AutomationRunTraceSchema>;
+/**
+ * What the hub's `runs` ledger holds for one owner (`automation:<blockId>` or
+ * `action:<actionId>`): the cooldown stamp and the trace ring.
+ */
+export declare const AutomationStateDocSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    lastRunStartedAt: z.ZodNullable<z.ZodNumber>;
+    traces: z.ZodArray<z.ZodObject<{
+        runId: z.ZodString;
+        startedAt: z.ZodNumber;
+        endedAt: z.ZodNumber;
+        trigger: z.ZodObject<{
+            kind: z.ZodString;
+            outcome: z.ZodEnum<{
+                fail: "fail";
+                pass: "pass";
+            }>;
+            reason: z.ZodString;
+            vars: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>]>>;
+        }, z.core.$strip>;
+        conditions: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            kind: z.ZodEnum<{
+                all: "all";
+                any: "any";
+                condition: "condition";
+                expression: "expression";
+                not: "not";
+            }>;
+            outcome: z.ZodEnum<{
+                fail: "fail";
+                "not-evaluated": "not-evaluated";
+                pass: "pass";
+            }>;
+            reason: z.ZodString;
+            deviceId: z.ZodOptional<z.ZodNumber>;
+            cap: z.ZodOptional<z.ZodString>;
+            fieldPath: z.ZodOptional<z.ZodString>;
+            operator: z.ZodOptional<z.ZodString>;
+            expected: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>]>>;
+            observed: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>]>>;
+        }, z.core.$strip>>;
+        verdict: z.ZodOptional<z.ZodObject<{
+            mode: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                mode: z.ZodLiteral<"single">;
+            }, z.core.$strip>, z.ZodObject<{
+                mode: z.ZodLiteral<"restart">;
+            }, z.core.$strip>, z.ZodObject<{
+                mode: z.ZodLiteral<"queued">;
+                max: z.ZodNumber;
+            }, z.core.$strip>, z.ZodObject<{
+                mode: z.ZodLiteral<"parallel">;
+                max: z.ZodNumber;
+            }, z.core.$strip>, z.ZodObject<{
+                mode: z.ZodLiteral<"cooldown">;
+                minutes: z.ZodNumber;
+            }, z.core.$strip>], "mode">;
+            decision: z.ZodEnum<{
+                bypass: "bypass";
+                cooldown: "cooldown";
+                drop: "drop";
+                queued: "queued";
+                restart: "restart";
+                run: "run";
+            }>;
+            reason: z.ZodString;
+        }, z.core.$strip>>;
+        steps: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            kind: z.ZodString;
+            cap: z.ZodOptional<z.ZodString>;
+            method: z.ZodOptional<z.ZodString>;
+            deviceId: z.ZodOptional<z.ZodNumber>;
+            startedAt: z.ZodOptional<z.ZodNumber>;
+            endedAt: z.ZodOptional<z.ZodNumber>;
+            outcome: z.ZodEnum<{
+                error: "error";
+                "not-run": "not-run";
+                ok: "ok";
+            }>;
+            message: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        outcome: z.ZodEnum<{
+            aborted: "aborted";
+            failed: "failed";
+            ran: "ran";
+            "skipped-conditions": "skipped-conditions";
+            "skipped-cooldown": "skipped-cooldown";
+            "skipped-overlap": "skipped-overlap";
+            "skipped-trigger": "skipped-trigger";
+        }>;
+        repeat: z.ZodNumber;
+        lastAt: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type AutomationStateDoc = z.infer<typeof AutomationStateDocSchema>;
+/** The state of an owner that never reported. */
+export declare const EMPTY_AUTOMATION_STATE: AutomationStateDoc;
+export declare function isSkippedTrace(trace: AutomationRunTrace): boolean;
+/** Two skips with the same signature are the same event repeating. */
+export declare function skipSignature(trace: AutomationRunTrace): string;
+/**
+ * `next` folded into `prev` when both are skips of the same signature (the
+ * repeat count and the latest time move on), else null. Used by the block
+ * BEFORE it sends, so a trigger that fails every few seconds costs one RPC per
+ * flush, not one per skip; the ledger applies the same rule through
+ * {@link appendTrace}.
+ */
+export declare function mergeSkipTraces(prev: AutomationRunTrace, next: AutomationRunTrace): AutomationRunTrace | null;
+/**
+ * Append a trace to a ring of at most `keep` entries, without mutating it.
+ *
+ *  - A skip identical to the previous trace is counted on that trace
+ *    (`repeat`, `lastAt`), not appended.
+ *  - When the ring is full, the oldest SKIPPED trace goes first; a real run is
+ *    evicted only when every trace is a run. A noisy skip stream therefore
+ *    cannot push the runs the operator is looking for out of the ring.
+ */
+export declare function appendTrace(ring: readonly AutomationRunTrace[], trace: AutomationRunTrace, keep: number): AutomationRunTrace[];
+/**
+ * The trigger stage of a trace from the bag a trigger handed to `run()`:
+ * primitives only (a device-state `to` that is an object is left out), minus the
+ * bookkeeping keys `kind` and `at`.
+ */
+export declare function buildTriggerTrace(trigger: Readonly<Record<string, unknown>>, outcome: 'pass' | 'fail', reason: string): AutomationTriggerTrace;

package/dist/capabilities/action-source.cap.d.ts

@@ -0,0 +1,74 @@
+import { z } from 'zod';
+import { type InferProvider } from './capability-definition.js';
+/**
+ * action-source — an addon DECLARES runnable actions (a Home Assistant script,
+ * a scene, a vendor routine) as list entries. Never as devices.
+ *
+ * It mirrors `notification-output`: `listActions` returns an array, so the
+ * generated cap mount concat-fans it across every provider; `runAction` and
+ * `stopAction` route to ONE provider by the `addonId` the generated collection
+ * router extracts from the call input.
+ *
+ * Nobody but the `actions` surface (the core-blocks builtin) calls this cap.
+ * The UI and automations talk to `actions`, which fans out here LIVE on every
+ * `list` and keeps no catalog of its own (D3: no shadow registry).
+ *
+ * `listActions` entries carry `source: 'addon'`, `readOnly: true`, an id of
+ * `<addonId>:<localId>` and an idle `status` (the provider may fill what it
+ * knows). `actionId` on `runAction` / `stopAction` is the full entry id.
+ */
+export declare const actionSourceCapability: {
+    readonly name: 'action-source';
+    readonly scope: 'system';
+    readonly mode: 'collection';
+    readonly methods: {
+        readonly listActions: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{}, z.core.$strip>, z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+            addonId: z.ZodString;
+            source: z.ZodEnum<{
+                addon: "addon";
+                internal: "internal";
+            }>;
+            readOnly: z.ZodBoolean;
+            steps: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"wait">;
+                seconds: z.ZodNumber;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"cap">;
+                deviceId: z.ZodUnion<readonly [z.ZodNumber, z.ZodArray<z.ZodNumber>, z.ZodObject<{
+                    $var: z.ZodString;
+                }, z.core.$strip>]>;
+                cap: z.ZodString;
+                method: z.ZodString;
+                args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            }, z.core.$strip>], "kind">>>;
+            variables: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                label: z.ZodOptional<z.ZodString>;
+                type: z.ZodEnum<{
+                    boolean: "boolean";
+                    number: "number";
+                    select: "select";
+                    string: "string";
+                }>;
+                required: z.ZodOptional<z.ZodBoolean>;
+                default: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+                options: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            }, z.core.$strip>>>;
+            status: z.ZodObject<{
+                isRunning: z.ZodBoolean;
+                lastRunAt: z.ZodNullable<z.ZodNumber>;
+                lastError: z.ZodNullable<z.ZodString>;
+            }, z.core.$strip>;
+        }, z.core.$strip>>, import("./capability-definition.js").CapabilityMethodKind>;
+        readonly runAction: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            actionId: z.ZodString;
+            variables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        }, z.core.$strip>, z.ZodVoid, "mutation">;
+        readonly stopAction: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            actionId: z.ZodString;
+        }, z.core.$strip>, z.ZodVoid, "mutation">;
+    };
+};
+export type IActionSourceProvider = InferProvider<typeof actionSourceCapability>;