@oxygen-agent/cli 1.377.3 → 1.591.1

package/node_modules/@oxygen/workflows/dist/event-dispatch.d.ts

@@ -0,0 +1,126 @@
+import type { JsonSchema, JsonSchemaValidationIssue, WorkflowEventFilter } from "./index.js";
+/**
+ * Read a dot-delimited path out of an event payload.
+ *
+ * Returns `found` separately from `value` so `exists` / `not_exists` filters can
+ * distinguish "the key is absent" from "the key is present and holds
+ * undefined/null" — collapsing those two would make `not_exists` fire on an
+ * explicit null, which is a real value the producer chose to send.
+ *
+ * Uses Object.hasOwn so inherited/prototype keys never satisfy a filter.
+ */
+export declare function readWorkflowEventJsonPath(value: Record<string, unknown>, path: string): {
+    found: boolean;
+    value: unknown;
+};
+/**
+ * Structural equality for filter comparisons. JSON-serialization equality is
+ * deliberate: filter values arrive as JSON from a stored trigger manifest, so
+ * two values are equal exactly when they round-trip identically.
+ */
+export declare function workflowEventJsonEqual(left: unknown, right: unknown): boolean;
+/**
+ * Does this payload satisfy every filter declared on the trigger?
+ *
+ * No filters (absent, not an array, or empty) means "match everything" — a
+ * trigger that declares no narrowing wants every event of its source+type.
+ *
+ * A malformed filter entry returns false (the whole trigger does not match)
+ * rather than being skipped. Ignoring an unparseable filter would silently
+ * WIDEN the trigger to fire on events the author meant to exclude; failing
+ * closed keeps a broken filter from becoming an unintended fan-out.
+ */
+export declare function matchesWorkflowEventFilters(payload: Record<string, unknown>, filters: unknown): boolean;
+/**
+ * The run idempotency key for one (event, trigger) delivery.
+ *
+ * Precedence, most to least specific:
+ *   1. the trigger's declared `idempotency_key_path` resolved against the payload
+ *      — lets a producer dedupe on its own domain id (e.g. the provider's
+ *      contact id) across redeliveries that carry different envelope ids;
+ *   2. an explicit caller-supplied key;
+ *   3. the provider's external event id (the redelivery guard webhooks carry);
+ *   4. the recorded event's own id, which is unique by construction.
+ *
+ * The `event:<source>:<type>:` prefix scopes the key so two different event
+ * types carrying the same domain id can never collide into one run.
+ *
+ * Takes scalars rather than db rows so both the web and worker callers — whose
+ * row types come from different drizzle schemas — can share one implementation.
+ */
+export declare function workflowEventRunIdempotencyKey(input: {
+    eventId: string;
+    eventSource: string;
+    eventType: string;
+    triggerMetadata: Record<string, unknown> | null | undefined;
+    payload: Record<string, unknown>;
+    explicitKey?: string | null;
+    externalEventId?: string | null;
+}): string;
+/**
+ * The verdict for one candidate delivery, before any state is written.
+ *
+ * `skipped` is a normal outcome (the trigger asked not to see this payload);
+ * `failed` means the payload reached a trigger that wanted it but could not be
+ * run. Callers record the distinction on the delivery row, so an operator can
+ * tell "my filter excluded it" from "my workflow's input schema rejected it".
+ */
+export type WorkflowEventDeliveryPlan = {
+    status: "deliverable";
+} | {
+    status: "skipped";
+    reason: "filters_not_matched";
+} | {
+    status: "failed";
+    error: {
+        ok: false;
+        error: {
+            code: "invalid_input";
+            message: string;
+            details: {
+                issues: JsonSchemaValidationIssue[];
+            };
+        };
+    };
+};
+/**
+ * Decide whether one event payload should produce a run for one trigger.
+ *
+ * Order matters: filters run BEFORE schema validation. A trigger that filtered
+ * an event out never wanted it, so validating that payload against the
+ * workflow's input schema would manufacture a spurious `failed` delivery (and a
+ * misleading "your workflow rejected this input" error) for an event the author
+ * deliberately excluded.
+ *
+ * `validateSchema` is injected rather than imported to keep this module free of
+ * a runtime dependency on index.ts (see the note at the top of the file).
+ */
+export declare function planWorkflowEventDelivery(input: {
+    payload: Record<string, unknown>;
+    filters: unknown;
+    inputSchema: JsonSchema | undefined;
+    validateSchema: (value: unknown, schema: JsonSchema | undefined) => JsonSchemaValidationIssue[];
+}): WorkflowEventDeliveryPlan;
+/**
+ * Per-run credit estimate for the standing `workflow_trigger` budget check.
+ *
+ * A triggered live run's projected spend is the per-run ceiling it carries — the
+ * call-time max_credits (run metadata), else the trigger's declared
+ * trigger_max_credits, else the manifest's declared max_credits, else 0.
+ *
+ * A 0 estimate makes daily/monthly caps reactive (they block the first run after
+ * the window crosses the cap) and per_run-window caps inert; a declared cap
+ * makes the gate preventive. That is the same trade-off the cron monitor
+ * carries, and both paths must price a run identically or the same workflow
+ * would be gated differently depending on which process fired it.
+ *
+ * Numeric strings are coerced: a cap that round-tripped through JSON as "500"
+ * must still price the run, or the projection counts a ceiling the run does not
+ * actually carry.
+ */
+export declare function estimateWorkflowTriggerRunCredits(runMetadata: Record<string, unknown> | null | undefined, triggerMetadata: Record<string, unknown> | null | undefined, manifest: unknown): number;
+/**
+ * Filters declared on a stored trigger's metadata, coerced to the manifest type.
+ * Stored metadata is untyped jsonb; this keeps the cast in one place.
+ */
+export declare function readWorkflowEventTriggerFilters(triggerMetadata: Record<string, unknown> | null | undefined): WorkflowEventFilter[] | undefined;

package/node_modules/@oxygen/workflows/dist/event-dispatch.js

@@ -0,0 +1,173 @@
+/**
+ * Read a dot-delimited path out of an event payload.
+ *
+ * Returns `found` separately from `value` so `exists` / `not_exists` filters can
+ * distinguish "the key is absent" from "the key is present and holds
+ * undefined/null" — collapsing those two would make `not_exists` fire on an
+ * explicit null, which is a real value the producer chose to send.
+ *
+ * Uses Object.hasOwn so inherited/prototype keys never satisfy a filter.
+ */
+export function readWorkflowEventJsonPath(value, path) {
+    let current = value;
+    for (const part of path.split(".")) {
+        if (!part)
+            return { found: false, value: undefined };
+        if (!current || typeof current !== "object" || Array.isArray(current)) {
+            return { found: false, value: undefined };
+        }
+        const record = current;
+        if (!Object.hasOwn(record, part))
+            return { found: false, value: undefined };
+        current = record[part];
+    }
+    return { found: true, value: current };
+}
+/**
+ * Structural equality for filter comparisons. JSON-serialization equality is
+ * deliberate: filter values arrive as JSON from a stored trigger manifest, so
+ * two values are equal exactly when they round-trip identically.
+ */
+export function workflowEventJsonEqual(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+/**
+ * Does this payload satisfy every filter declared on the trigger?
+ *
+ * No filters (absent, not an array, or empty) means "match everything" — a
+ * trigger that declares no narrowing wants every event of its source+type.
+ *
+ * A malformed filter entry returns false (the whole trigger does not match)
+ * rather than being skipped. Ignoring an unparseable filter would silently
+ * WIDEN the trigger to fire on events the author meant to exclude; failing
+ * closed keeps a broken filter from becoming an unintended fan-out.
+ */
+export function matchesWorkflowEventFilters(payload, filters) {
+    if (!Array.isArray(filters) || filters.length === 0)
+        return true;
+    return filters.every((filter) => {
+        if (!filter || typeof filter !== "object" || Array.isArray(filter))
+            return false;
+        const path = typeof filter.path === "string"
+            ? filter.path.trim()
+            : "";
+        const op = filter.op;
+        if (!path)
+            return false;
+        const current = readWorkflowEventJsonPath(payload, path);
+        if (op === "exists")
+            return current.found;
+        if (op === "not_exists")
+            return !current.found;
+        if (op === "eq") {
+            return current.found && workflowEventJsonEqual(current.value, filter.value);
+        }
+        if (op === "neq") {
+            return !current.found || !workflowEventJsonEqual(current.value, filter.value);
+        }
+        return false;
+    });
+}
+/**
+ * The run idempotency key for one (event, trigger) delivery.
+ *
+ * Precedence, most to least specific:
+ *   1. the trigger's declared `idempotency_key_path` resolved against the payload
+ *      — lets a producer dedupe on its own domain id (e.g. the provider's
+ *      contact id) across redeliveries that carry different envelope ids;
+ *   2. an explicit caller-supplied key;
+ *   3. the provider's external event id (the redelivery guard webhooks carry);
+ *   4. the recorded event's own id, which is unique by construction.
+ *
+ * The `event:<source>:<type>:` prefix scopes the key so two different event
+ * types carrying the same domain id can never collide into one run.
+ *
+ * Takes scalars rather than db rows so both the web and worker callers — whose
+ * row types come from different drizzle schemas — can share one implementation.
+ */
+export function workflowEventRunIdempotencyKey(input) {
+    const idempotencyPath = typeof input.triggerMetadata?.idempotency_key_path === "string"
+        ? input.triggerMetadata.idempotency_key_path
+        : null;
+    const pathValue = idempotencyPath
+        ? readWorkflowEventJsonPath(input.payload, idempotencyPath)
+        : null;
+    const key = pathValue?.found && typeof pathValue.value === "string" && pathValue.value.trim()
+        ? pathValue.value.trim()
+        : input.explicitKey?.trim() || input.externalEventId?.trim() || input.eventId;
+    return `event:${input.eventSource}:${input.eventType}:${key}`;
+}
+/**
+ * Decide whether one event payload should produce a run for one trigger.
+ *
+ * Order matters: filters run BEFORE schema validation. A trigger that filtered
+ * an event out never wanted it, so validating that payload against the
+ * workflow's input schema would manufacture a spurious `failed` delivery (and a
+ * misleading "your workflow rejected this input" error) for an event the author
+ * deliberately excluded.
+ *
+ * `validateSchema` is injected rather than imported to keep this module free of
+ * a runtime dependency on index.ts (see the note at the top of the file).
+ */
+export function planWorkflowEventDelivery(input) {
+    if (!matchesWorkflowEventFilters(input.payload, input.filters)) {
+        return { status: "skipped", reason: "filters_not_matched" };
+    }
+    if (input.inputSchema) {
+        const issues = input.validateSchema(input.payload, input.inputSchema);
+        if (issues.length > 0) {
+            return {
+                status: "failed",
+                error: {
+                    ok: false,
+                    error: {
+                        code: "invalid_input",
+                        message: "Workflow event payload does not match the workflow input schema.",
+                        details: { issues },
+                    },
+                },
+            };
+        }
+    }
+    return { status: "deliverable" };
+}
+/**
+ * Per-run credit estimate for the standing `workflow_trigger` budget check.
+ *
+ * A triggered live run's projected spend is the per-run ceiling it carries — the
+ * call-time max_credits (run metadata), else the trigger's declared
+ * trigger_max_credits, else the manifest's declared max_credits, else 0.
+ *
+ * A 0 estimate makes daily/monthly caps reactive (they block the first run after
+ * the window crosses the cap) and per_run-window caps inert; a declared cap
+ * makes the gate preventive. That is the same trade-off the cron monitor
+ * carries, and both paths must price a run identically or the same workflow
+ * would be gated differently depending on which process fired it.
+ *
+ * Numeric strings are coerced: a cap that round-tripped through JSON as "500"
+ * must still price the run, or the projection counts a ceiling the run does not
+ * actually carry.
+ */
+export function estimateWorkflowTriggerRunCredits(runMetadata, triggerMetadata, manifest) {
+    const manifestCap = manifest?.max_credits;
+    const candidates = [
+        runMetadata?.max_credits,
+        runMetadata?.maxCredits,
+        triggerMetadata?.trigger_max_credits,
+        manifestCap,
+    ];
+    for (const raw of candidates) {
+        const value = typeof raw === "number" ? raw : Number(raw);
+        if (Number.isFinite(value) && value > 0)
+            return value;
+    }
+    return 0;
+}
+/**
+ * Filters declared on a stored trigger's metadata, coerced to the manifest type.
+ * Stored metadata is untyped jsonb; this keeps the cast in one place.
+ */
+export function readWorkflowEventTriggerFilters(triggerMetadata) {
+    const filters = triggerMetadata?.filters;
+    return Array.isArray(filters) ? filters : undefined;
+}

package/node_modules/@oxygen/workflows/dist/graph/expression.d.ts

@@ -0,0 +1,78 @@
+import type { WorkflowCompareOp, WorkflowCondition, WorkflowValueRef } from "./types.js";
+/**
+ * The data a v2 run exposes to its value refs.
+ *
+ * `steps` is keyed by node id and always present (an empty object before the
+ * first node completes); `trigger` and `loop` are absent until a run supplies
+ * them. `contextProfile` / `contextAssets` carry the Knowledge-layer values the
+ * `context_profile` / `context_asset` refs read.
+ */
+export type WorkflowRunScope = {
+    trigger?: {
+        input?: unknown;
+        payload?: unknown;
+    };
+    steps: Record<string, {
+        output?: unknown;
+    }>;
+    loop?: Record<string, {
+        item?: unknown;
+        index?: number;
+    }>;
+    contextProfile?: unknown;
+    contextAssets?: Record<string, unknown>;
+};
+/** The roots a `ref` path may start from. Anything else is not a scope path. */
+export declare const SCOPE_PATH_ROOTS: ReadonlySet<string>;
+export declare const WORKFLOW_COMPARE_OPS: ReadonlySet<WorkflowCompareOp>;
+/** Operators that take no right operand. */
+export declare const UNARY_COMPARE_OPS: ReadonlySet<WorkflowCompareOp>;
+/**
+ * Split a path expression into its segments, or return null when the expression
+ * is malformed or reaches a blocked segment.
+ *
+ * Grammar: dotted keys with optional index suffixes —
+ *   steps.find_person.output.emails[0].address
+ *   trigger.input["odd.key"]
+ *
+ * Returning null (rather than throwing) is what lets `resolvePath` stay total;
+ * the linter uses the same parser to reject the path at authoring time, so a
+ * typo surfaces in lint rather than as a silently empty value at run time.
+ */
+export declare function parseScopePath(path: string): string[] | null;
+/** Resolve a dotted (+ `[n]`) scope path. Missing or malformed → undefined. */
+export declare function resolvePath(path: string, scope: WorkflowRunScope): unknown;
+/**
+ * Substitute every `{{ path }}` placeholder. The result is always a string:
+ * blanks render as "", scalars as their text, objects/arrays as compact JSON.
+ * `{{}}` (no path) is literal text, not a binding.
+ */
+export declare function renderTemplate(template: string, scope: WorkflowRunScope): string;
+export declare function resolveValueRef(ref: WorkflowValueRef, scope: WorkflowRunScope): unknown;
+export declare function evaluateCondition(condition: WorkflowCondition, scope: WorkflowRunScope): boolean;
+/**
+ * Compile a `matches` pattern, or return null when it is unsafe or invalid.
+ *
+ * Choice: conservative STATIC REJECTION rather than a linear (Thompson NFA)
+ * matcher. A linear engine would be several hundred lines of new, security-load-
+ * bearing code in a module the browser also bundles, whereas the patterns real
+ * GTM authors write (domain suffixes, job-title keywords, ID formats) never need
+ * the constructs rejected here. Rejected: sources over 200 characters,
+ * lookaround, backreferences, and a quantified group whose body itself contains
+ * an unbounded quantifier — the `(a+)+` family that drives catastrophic
+ * backtracking. Everything else compiles as a normal RegExp.
+ *
+ * The linter calls this at authoring time and reports `invalid_condition`, so a
+ * rejected pattern is a lint error the author sees, not a silent run-time false.
+ */
+export declare function compileConditionPattern(pattern: string): RegExp | null;
+/**
+ * Node ids a ref or condition reads, in first-seen order.
+ *
+ * `steps.<id>...` and `loop.<id>...` paths name a node exactly. Formula refs are
+ * a superset: the tokenizer's bare identifiers may name a node, a workflow
+ * input, or a loop, and nothing in the expression distinguishes them — callers
+ * that need certainty (edge inference, dependency ordering) intersect the result
+ * with the manifest's declared node ids.
+ */
+export declare function referencedNodeIds(ref: WorkflowValueRef | WorkflowCondition): string[];