crewly 1.5.18 → 1.5.20

package/dist/cli/backend/src/types/v2/claim.types.d.ts

@@ -0,0 +1,143 @@
+/**
+ * V2 Task Claim Type Definitions
+ *
+ * Claims represent an agent's active hold on a WorkItem from the Task Pool.
+ * The claim system uses lease + heartbeat to ensure liveness:
+ * - Lease: 10 minutes default, agent must renew before expiry
+ * - Heartbeat: 2 minutes, agent signals it's still working
+ * - Grace period: 3 minutes after lease expiry before forced release
+ *
+ * @module types/v2/claim.types
+ */
+/**
+ * Lifecycle statuses for a TaskClaim.
+ */
+export type ClaimStatus = 'active' | 'expiring' | 'released' | 'revoked';
+/** All valid ClaimStatus values. */
+export declare const CLAIM_STATUSES: readonly ClaimStatus[];
+/**
+ * Represents an agent's claim on a WorkItem from the Task Pool.
+ *
+ * The claim lifecycle:
+ *   1. Agent calls claimFromPool() → TaskClaim created (status: 'active')
+ *   2. Agent sends heartbeats every 2 minutes → lastHeartbeatAt updated
+ *   3a. Agent finishes → releases claim (status: 'released')
+ *   3b. Lease expires → Reconciler sets 'expiring', starts grace period
+ *   4. Grace period exceeded → Reconciler revokes (status: 'revoked'), WorkItem back to pool
+ */
+export interface TaskClaim {
+    /** UUID v4 */
+    id: string;
+    /** WorkItem ID being claimed */
+    workItemId: string;
+    /** Agent session name that holds the claim */
+    agentId: string;
+    /** Current claim status */
+    status: ClaimStatus;
+    /** ISO8601 — when the claim was created */
+    claimedAt: string;
+    /** ISO8601 — when the lease expires (claimedAt + leaseDurationMs) */
+    leaseExpiresAt: string;
+    /** ISO8601 — last heartbeat received from the agent */
+    lastHeartbeatAt: string;
+    /** Number of lease extensions granted */
+    extensionCount: number;
+    /** Maximum allowed extensions (default: 3) */
+    maxExtensions: number;
+    /** Lease duration in ms (default: 600000 = 10 min) */
+    leaseDurationMs: number;
+    /** ISO8601 — when the claim ended (release or revoke) */
+    endedAt?: string;
+    /** Reason for release or revocation */
+    endReason?: string;
+}
+/**
+ * Input for creating a new claim.
+ */
+export interface CreateClaimInput {
+    workItemId: string;
+    agentId: string;
+    leaseDurationMs?: number;
+    maxExtensions?: number;
+}
+/** Default lease duration: 1 hour (increased from 10m to prevent bottlenecks). */
+export declare const DEFAULT_LEASE_DURATION_MS = 3600000;
+/** Extended lease duration for project_task WorkItems: 2 hours.
+ * Complex project tasks need longer execution time to avoid premature revocation. */
+export declare const PROJECT_TASK_LEASE_DURATION_MS = 7200000;
+/** Default heartbeat interval: 2 minutes. */
+export declare const DEFAULT_HEARTBEAT_INTERVAL_MS = 120000;
+/** Default grace period after lease expiry: 3 minutes. */
+export declare const DEFAULT_GRACE_PERIOD_MS = 180000;
+/** Default maximum lease extensions. */
+export declare const DEFAULT_MAX_EXTENSIONS = 3;
+/**
+ * Checks whether a string is a valid ClaimStatus.
+ *
+ * @param value - The string to check
+ * @returns True if value is a valid ClaimStatus
+ */
+export declare function isValidClaimStatus(value: string): value is ClaimStatus;
+/**
+ * Validates that an unknown value is structurally a valid TaskClaim.
+ *
+ * @param value - Unknown value to validate
+ * @returns True if value conforms to the TaskClaim interface
+ */
+export declare function isTaskClaim(value: unknown): value is TaskClaim;
+/**
+ * Checks whether a claim's lease has expired (not counting grace period).
+ *
+ * @param claim - The claim to check
+ * @param now - Current time (defaults to Date.now())
+ * @returns True if the lease has expired
+ */
+export declare function isLeaseExpired(claim: TaskClaim, now?: number): boolean;
+/**
+ * Checks whether a claim is past its grace period and should be revoked.
+ *
+ * @param claim - The claim to check
+ * @param gracePeriodMs - Grace period duration in ms
+ * @param now - Current time (defaults to Date.now())
+ * @returns True if grace period has exceeded
+ */
+export declare function isGracePeriodExceeded(claim: TaskClaim, gracePeriodMs?: number, now?: number): boolean;
+/**
+ * Checks whether a claim can be extended (has not exhausted max extensions).
+ *
+ * @param claim - The claim to check
+ * @returns True if another extension is allowed
+ */
+export declare function canExtendLease(claim: TaskClaim): boolean;
+/**
+ * Validates CreateClaimInput and returns an array of error messages.
+ *
+ * @param input - The creation input to validate
+ * @returns Array of validation error strings (empty = valid)
+ */
+export declare function validateCreateClaimInput(input: CreateClaimInput): string[];
+/**
+ * Creates a new TaskClaim with sensible defaults.
+ *
+ * @param input - Required and optional creation fields
+ * @returns A fully populated TaskClaim object
+ *
+ * @example
+ * ```typescript
+ * const claim = createTaskClaim({
+ *   workItemId: 'wi-abc-123',
+ *   agentId: 'crewly-product-leo-member-n',
+ * });
+ * // claim.leaseExpiresAt will be 10 minutes from now
+ * ```
+ */
+export declare function createTaskClaim(input: CreateClaimInput): TaskClaim;
+/**
+ * Extends a claim's lease by the original lease duration.
+ * Returns a new claim object (immutable pattern).
+ *
+ * @param claim - The claim to extend
+ * @returns New TaskClaim with extended lease, or null if extension not allowed
+ */
+export declare function extendClaim(claim: TaskClaim): TaskClaim | null;
+//# sourceMappingURL=claim.types.d.ts.map

package/dist/cli/backend/src/types/v2/claim.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claim.types.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/types/v2/claim.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAQH;;GAEG;AACH,MAAM,MAAM,WAAW,GACnB,QAAQ,GACR,UAAU,GACV,UAAU,GACV,SAAS,CAAC;AAEd,oCAAoC;AACpC,eAAO,MAAM,cAAc,EAAE,SAAS,WAAW,EAKvC,CAAC;AAMX;;;;;;;;;GASG;AACH,MAAM,WAAW,SAAS;IACxB,cAAc;IACd,EAAE,EAAE,MAAM,CAAC;IACX,gCAAgC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,2BAA2B;IAC3B,MAAM,EAAE,WAAW,CAAC;IACpB,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,cAAc,EAAE,MAAM,CAAC;IACvB,uDAAuD;IACvD,eAAe,EAAE,MAAM,CAAC;IACxB,yCAAyC;IACzC,cAAc,EAAE,MAAM,CAAC;IACvB,8CAA8C;IAC9C,aAAa,EAAE,MAAM,CAAC;IACtB,sDAAsD;IACtD,eAAe,EAAE,MAAM,CAAC;IACxB,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uCAAuC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAMD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAMD,kFAAkF;AAClF,eAAO,MAAM,yBAAyB,UAAY,CAAC;AAEnD;qFACqF;AACrF,eAAO,MAAM,8BAA8B,UAAY,CAAC;AAExD,6CAA6C;AAC7C,eAAO,MAAM,6BAA6B,SAAU,CAAC;AAErD,0DAA0D;AAC1D,eAAO,MAAM,uBAAuB,SAAU,CAAC;AAE/C,wCAAwC;AACxC,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAMxC;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,WAAW,CAEtE;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAgB9D;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,GAAE,MAAmB,GAAG,OAAO,CAElF;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,SAAS,EAChB,aAAa,GAAE,MAAgC,EAC/C,GAAG,GAAE,MAAmB,GACvB,OAAO,CAGT;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAExD;AAMD;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,EAAE,CAoB1E;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,gBAAgB,GAAG,SAAS,CAiBlE;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,GAAG,IAAI,CAW9D"}

package/dist/cli/backend/src/types/v2/claim.types.js

@@ -0,0 +1,183 @@
+/**
+ * V2 Task Claim Type Definitions
+ *
+ * Claims represent an agent's active hold on a WorkItem from the Task Pool.
+ * The claim system uses lease + heartbeat to ensure liveness:
+ * - Lease: 10 minutes default, agent must renew before expiry
+ * - Heartbeat: 2 minutes, agent signals it's still working
+ * - Grace period: 3 minutes after lease expiry before forced release
+ *
+ * @module types/v2/claim.types
+ */
+import { v4 as uuidv4 } from 'uuid';
+/** All valid ClaimStatus values. */
+export const CLAIM_STATUSES = [
+    'active',
+    'expiring',
+    'released',
+    'revoked',
+];
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Default lease duration: 1 hour (increased from 10m to prevent bottlenecks). */
+export const DEFAULT_LEASE_DURATION_MS = 3_600_000;
+/** Extended lease duration for project_task WorkItems: 2 hours.
+ * Complex project tasks need longer execution time to avoid premature revocation. */
+export const PROJECT_TASK_LEASE_DURATION_MS = 7_200_000;
+/** Default heartbeat interval: 2 minutes. */
+export const DEFAULT_HEARTBEAT_INTERVAL_MS = 120_000;
+/** Default grace period after lease expiry: 3 minutes. */
+export const DEFAULT_GRACE_PERIOD_MS = 180_000;
+/** Default maximum lease extensions. */
+export const DEFAULT_MAX_EXTENSIONS = 3;
+// ---------------------------------------------------------------------------
+// Type Guards
+// ---------------------------------------------------------------------------
+/**
+ * Checks whether a string is a valid ClaimStatus.
+ *
+ * @param value - The string to check
+ * @returns True if value is a valid ClaimStatus
+ */
+export function isValidClaimStatus(value) {
+    return CLAIM_STATUSES.includes(value);
+}
+/**
+ * Validates that an unknown value is structurally a valid TaskClaim.
+ *
+ * @param value - Unknown value to validate
+ * @returns True if value conforms to the TaskClaim interface
+ */
+export function isTaskClaim(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const obj = value;
+    return (typeof obj.id === 'string' &&
+        typeof obj.workItemId === 'string' &&
+        typeof obj.agentId === 'string' &&
+        typeof obj.status === 'string' &&
+        isValidClaimStatus(obj.status) &&
+        typeof obj.claimedAt === 'string' &&
+        typeof obj.leaseExpiresAt === 'string' &&
+        typeof obj.lastHeartbeatAt === 'string' &&
+        typeof obj.extensionCount === 'number' &&
+        typeof obj.maxExtensions === 'number' &&
+        typeof obj.leaseDurationMs === 'number');
+}
+/**
+ * Checks whether a claim's lease has expired (not counting grace period).
+ *
+ * @param claim - The claim to check
+ * @param now - Current time (defaults to Date.now())
+ * @returns True if the lease has expired
+ */
+export function isLeaseExpired(claim, now = Date.now()) {
+    return now > new Date(claim.leaseExpiresAt).getTime();
+}
+/**
+ * Checks whether a claim is past its grace period and should be revoked.
+ *
+ * @param claim - The claim to check
+ * @param gracePeriodMs - Grace period duration in ms
+ * @param now - Current time (defaults to Date.now())
+ * @returns True if grace period has exceeded
+ */
+export function isGracePeriodExceeded(claim, gracePeriodMs = DEFAULT_GRACE_PERIOD_MS, now = Date.now()) {
+    const leaseExpiry = new Date(claim.leaseExpiresAt).getTime();
+    return now > leaseExpiry + gracePeriodMs;
+}
+/**
+ * Checks whether a claim can be extended (has not exhausted max extensions).
+ *
+ * @param claim - The claim to check
+ * @returns True if another extension is allowed
+ */
+export function canExtendLease(claim) {
+    return claim.status === 'active' && claim.extensionCount < claim.maxExtensions;
+}
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+/**
+ * Validates CreateClaimInput and returns an array of error messages.
+ *
+ * @param input - The creation input to validate
+ * @returns Array of validation error strings (empty = valid)
+ */
+export function validateCreateClaimInput(input) {
+    const errors = [];
+    if (!input.workItemId || typeof input.workItemId !== 'string') {
+        errors.push('workItemId is required and must be a string');
+    }
+    if (!input.agentId || typeof input.agentId !== 'string') {
+        errors.push('agentId is required and must be a string');
+    }
+    if (input.leaseDurationMs !== undefined) {
+        if (input.leaseDurationMs < 60_000) {
+            errors.push('leaseDurationMs must be at least 60000 (1 minute)');
+        }
+        if (input.leaseDurationMs > 3_600_000) {
+            errors.push('leaseDurationMs must not exceed 3600000 (1 hour)');
+        }
+    }
+    if (input.maxExtensions !== undefined && (input.maxExtensions < 0 || !Number.isInteger(input.maxExtensions))) {
+        errors.push('maxExtensions must be a non-negative integer');
+    }
+    return errors;
+}
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Creates a new TaskClaim with sensible defaults.
+ *
+ * @param input - Required and optional creation fields
+ * @returns A fully populated TaskClaim object
+ *
+ * @example
+ * ```typescript
+ * const claim = createTaskClaim({
+ *   workItemId: 'wi-abc-123',
+ *   agentId: 'crewly-product-leo-member-n',
+ * });
+ * // claim.leaseExpiresAt will be 10 minutes from now
+ * ```
+ */
+export function createTaskClaim(input) {
+    const now = new Date();
+    const leaseDuration = input.leaseDurationMs ?? DEFAULT_LEASE_DURATION_MS;
+    const leaseExpiry = new Date(now.getTime() + leaseDuration);
+    return {
+        id: uuidv4(),
+        workItemId: input.workItemId,
+        agentId: input.agentId,
+        status: 'active',
+        claimedAt: now.toISOString(),
+        leaseExpiresAt: leaseExpiry.toISOString(),
+        lastHeartbeatAt: now.toISOString(),
+        extensionCount: 0,
+        maxExtensions: input.maxExtensions ?? DEFAULT_MAX_EXTENSIONS,
+        leaseDurationMs: leaseDuration,
+    };
+}
+/**
+ * Extends a claim's lease by the original lease duration.
+ * Returns a new claim object (immutable pattern).
+ *
+ * @param claim - The claim to extend
+ * @returns New TaskClaim with extended lease, or null if extension not allowed
+ */
+export function extendClaim(claim) {
+    if (!canExtendLease(claim))
+        return null;
+    const now = new Date();
+    const newExpiry = new Date(now.getTime() + claim.leaseDurationMs);
+    return {
+        ...claim,
+        leaseExpiresAt: newExpiry.toISOString(),
+        lastHeartbeatAt: now.toISOString(),
+        extensionCount: claim.extensionCount + 1,
+    };
+}
+//# sourceMappingURL=claim.types.js.map

package/dist/cli/backend/src/types/v2/claim.types.js.map

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

package/dist/cli/backend/src/types/v2/trigger.types.d.ts

@@ -0,0 +1,201 @@
+/**
+ * V2 Trigger Type Definitions
+ *
+ * Triggers unify v1's ScheduledMessage, CronTask, and EventSubscription
+ * into a single time/signal/compound mechanism that creates or wakes WorkItems.
+ *
+ * @module types/v2/trigger.types
+ */
+import type { WorkItem } from './work-item.types.js';
+/**
+ * What kind of trigger.
+ * - time: Cron expression or one-shot delay (replaces ScheduledMessage + CronTask)
+ * - signal: Agent event, webhook, or status change (replaces EventSubscription)
+ * - compound: Multiple conditions combined with AND/OR
+ */
+export type TriggerType = 'time' | 'signal' | 'compound';
+/** All valid TriggerType values. */
+export declare const TRIGGER_TYPES: readonly TriggerType[];
+/**
+ * Trigger lifecycle statuses.
+ */
+export type TriggerStatus = 'active' | 'paused' | 'exhausted' | 'cancelled';
+/** All valid TriggerStatus values. */
+export declare const TRIGGER_STATUSES: readonly TriggerStatus[];
+/**
+ * Time trigger: fires on schedule or after delay.
+ * Replaces v1 ScheduledMessage + CronTask.
+ */
+export interface TimeTriggerConfig {
+    type: 'time';
+    /** Cron expression for recurring (e.g., "0 9 * * 1") */
+    cronExpression?: string;
+    /** IANA timezone (e.g., "America/New_York") */
+    timezone?: string;
+    /** One-shot delay in ms from creation */
+    delayMs?: number;
+    /** Fixed ISO8601 datetime for one-shot */
+    fireAt?: string;
+}
+/**
+ * Signal trigger: fires when an event matches.
+ * Replaces v1 EventSubscription.
+ */
+export interface SignalTriggerConfig {
+    type: 'signal';
+    /** Event type to watch for (e.g., "agent:idle", "task:completed") */
+    eventType: string;
+    /** Optional filter — only fire if event payload matches */
+    filter?: Record<string, unknown>;
+}
+/**
+ * Compound trigger: combines sub-conditions with AND/OR.
+ */
+export interface CompoundTriggerConfig {
+    type: 'compound';
+    /** How sub-conditions combine */
+    operator: 'and' | 'or';
+    /** Sub-trigger configs */
+    conditions: (TimeTriggerConfig | SignalTriggerConfig)[];
+}
+/**
+ * Discriminated union of all trigger configuration types.
+ */
+export type TriggerConfig = TimeTriggerConfig | SignalTriggerConfig | CompoundTriggerConfig;
+/**
+ * What happens when a trigger fires. At least one field should be set.
+ */
+export interface TriggerAction {
+    /** Create a new WorkItem from this template */
+    createWorkItem?: Partial<WorkItem>;
+    /** Wake (re-queue) an existing WorkItem by ID */
+    wakeWorkItemId?: string;
+    /** Send a message to a session */
+    sendMessage?: {
+        target: string;
+        message: string;
+    };
+    /** Run the Reconciler */
+    runReconciler?: boolean;
+}
+/**
+ * A Trigger monitors time or signals and produces actions (WorkItems, messages, reconciliation).
+ *
+ * Triggers are the unified replacement for v1's ScheduledMessage, CronTask,
+ * and EventSubscription patterns.
+ */
+export interface Trigger {
+    /** UUID v4 */
+    id: string;
+    /** What kind of trigger */
+    type: TriggerType;
+    /** Trigger-specific configuration */
+    config: TriggerConfig;
+    /** What action to take when the trigger fires */
+    action: TriggerAction;
+    /** Lifecycle status */
+    status: TriggerStatus;
+    /** Who created this trigger */
+    createdBy: 'user' | 'orchestrator' | 'system' | 'mission';
+    /** ISO8601 timestamps */
+    createdAt: string;
+    lastFiredAt?: string;
+    nextFireAt?: string;
+    /** Number of times this trigger has fired */
+    fireCount: number;
+    /** Maximum fires before auto-disable (undefined = unlimited) */
+    maxFires?: number;
+    /** Auto-cancel after N consecutive idle fires (v1 lesson from issue #131) */
+    maxIdleFires: number;
+    /** Current count of consecutive idle fires */
+    consecutiveIdleFires: number;
+    /**
+     * Owning team, if this trigger was provisioned from a Team's `triggers` spec.
+     * Used by {@link TeamTriggerReconciler} to look up and cancel team-scoped
+     * triggers without touching user/mission/system triggers.
+     */
+    teamId?: string;
+    /**
+     * Stable name set by the provisioner (e.g. `"youtube-monthly-kickoff"`).
+     * The reconciler uses (teamId, name) as the identity key so editing
+     * `Team.triggers[].cronExpression` replaces instead of duplicating.
+     */
+    name?: string;
+}
+/**
+ * Input for creating a new Trigger.
+ */
+export interface CreateTriggerInput {
+    type: TriggerType;
+    config: TriggerConfig;
+    action: TriggerAction;
+    createdBy: 'user' | 'orchestrator' | 'system' | 'mission';
+    maxFires?: number;
+    maxIdleFires?: number;
+    /** Optional owning team (team-scoped triggers) */
+    teamId?: string;
+    /** Optional stable name for reconciliation-by-identity */
+    name?: string;
+}
+/** Default max idle fires before auto-cancel. From v1 issue #131 lesson. */
+export declare const DEFAULT_MAX_IDLE_FIRES = 3;
+/**
+ * Checks whether a string is a valid TriggerType.
+ *
+ * @param value - The string to check
+ * @returns True if value is a valid TriggerType
+ */
+export declare function isValidTriggerType(value: string): value is TriggerType;
+/**
+ * Checks whether a string is a valid TriggerStatus.
+ *
+ * @param value - The string to check
+ * @returns True if value is a valid TriggerStatus
+ */
+export declare function isValidTriggerStatus(value: string): value is TriggerStatus;
+/**
+ * Validates that a trigger config's type field matches its parent type.
+ *
+ * @param config - The config to validate
+ * @returns True if the config is internally consistent
+ */
+export declare function isValidTriggerConfig(config: TriggerConfig): boolean;
+/**
+ * Validates that an unknown value is structurally a valid Trigger.
+ *
+ * @param value - Unknown value to validate
+ * @returns True if value conforms to the Trigger interface
+ */
+export declare function isTrigger(value: unknown): value is Trigger;
+/**
+ * Checks whether a TriggerAction has at least one action defined.
+ *
+ * @param action - The action to validate
+ * @returns True if at least one action field is set
+ */
+export declare function isValidTriggerAction(action: TriggerAction): boolean;
+/**
+ * Validates CreateTriggerInput and returns an array of error messages.
+ *
+ * @param input - The creation input to validate
+ * @returns Array of validation error strings (empty = valid)
+ */
+export declare function validateCreateTriggerInput(input: CreateTriggerInput): string[];
+/**
+ * Creates a new Trigger with sensible defaults.
+ *
+ * @param input - Required and optional creation fields
+ * @returns A fully populated Trigger object
+ *
+ * @example
+ * ```typescript
+ * const trigger = createTrigger({
+ *   type: 'time',
+ *   config: { type: 'time', cronExpression: '0 9 * * 1' },
+ *   action: { runReconciler: true },
+ *   createdBy: 'system',
+ * });
+ * ```
+ */
+export declare function createTrigger(input: CreateTriggerInput): Trigger;
+//# sourceMappingURL=trigger.types.d.ts.map

package/dist/cli/backend/src/types/v2/trigger.types.d.ts.map

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