crewly 1.5.18 → 1.5.19

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":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,EAAE,IAAI,MAAM,EAAE,MAAM,MAAM,CAAC;AAepC,oCAAoC;AACpC,MAAM,CAAC,MAAM,cAAc,GAA2B;IACpD,QAAQ;IACR,UAAU;IACV,UAAU;IACV,SAAS;CACD,CAAC;AAyDX,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E,kFAAkF;AAClF,MAAM,CAAC,MAAM,yBAAyB,GAAG,SAAS,CAAC;AAEnD;qFACqF;AACrF,MAAM,CAAC,MAAM,8BAA8B,GAAG,SAAS,CAAC;AAExD,6CAA6C;AAC7C,MAAM,CAAC,MAAM,6BAA6B,GAAG,OAAO,CAAC;AAErD,0DAA0D;AAC1D,MAAM,CAAC,MAAM,uBAAuB,GAAG,OAAO,CAAC;AAE/C,wCAAwC;AACxC,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC;AAExC,8EAA8E;AAC9E,cAAc;AACd,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAa;IAC9C,OAAQ,cAAoC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC/D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,GAAG,GAAG,KAAgC,CAAC;IAC7C,OAAO,CACL,OAAO,GAAG,CAAC,EAAE,KAAK,QAAQ;QAC1B,OAAO,GAAG,CAAC,UAAU,KAAK,QAAQ;QAClC,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ;QAC/B,OAAO,GAAG,CAAC,MAAM,KAAK,QAAQ;QAC9B,kBAAkB,CAAC,GAAG,CAAC,MAAM,CAAC;QAC9B,OAAO,GAAG,CAAC,SAAS,KAAK,QAAQ;QACjC,OAAO,GAAG,CAAC,cAAc,KAAK,QAAQ;QACtC,OAAO,GAAG,CAAC,eAAe,KAAK,QAAQ;QACvC,OAAO,GAAG,CAAC,cAAc,KAAK,QAAQ;QACtC,OAAO,GAAG,CAAC,aAAa,KAAK,QAAQ;QACrC,OAAO,GAAG,CAAC,eAAe,KAAK,QAAQ,CACxC,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,KAAgB,EAAE,MAAc,IAAI,CAAC,GAAG,EAAE;IACvE,OAAO,GAAG,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,OAAO,EAAE,CAAC;AACxD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CACnC,KAAgB,EAChB,gBAAwB,uBAAuB,EAC/C,MAAc,IAAI,CAAC,GAAG,EAAE;IAExB,MAAM,WAAW,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,OAAO,EAAE,CAAC;IAC7D,OAAO,GAAG,GAAG,WAAW,GAAG,aAAa,CAAC;AAC3C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,KAAgB;IAC7C,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,cAAc,GAAG,KAAK,CAAC,aAAa,CAAC;AACjF,CAAC;AAED,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,UAAU,wBAAwB,CAAC,KAAuB;IAC9D,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,IAAI,CAAC,KAAK,CAAC,UAAU,IAAI,OAAO,KAAK,CAAC,UAAU,KAAK,QAAQ,EAAE,CAAC;QAC9D,MAAM,CAAC,IAAI,CAAC,6CAA6C,CAAC,CAAC;IAC7D,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,IAAI,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;QACxD,MAAM,CAAC,IAAI,CAAC,0CAA0C,CAAC,CAAC;IAC1D,CAAC;IACD,IAAI,KAAK,CAAC,eAAe,KAAK,SAAS,EAAE,CAAC;QACxC,IAAI,KAAK,CAAC,eAAe,GAAG,MAAM,EAAE,CAAC;YACnC,MAAM,CAAC,IAAI,CAAC,mDAAmD,CAAC,CAAC;QACnE,CAAC;QACD,IAAI,KAAK,CAAC,eAAe,GAAG,SAAS,EAAE,CAAC;YACtC,MAAM,CAAC,IAAI,CAAC,kDAAkD,CAAC,CAAC;QAClE,CAAC;IACH,CAAC;IACD,IAAI,KAAK,CAAC,aAAa,KAAK,SAAS,IAAI,CAAC,KAAK,CAAC,aAAa,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,EAAE,CAAC;QAC7G,MAAM,CAAC,IAAI,CAAC,8CAA8C,CAAC,CAAC;IAC9D,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,eAAe,CAAC,KAAuB;IACrD,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;IACvB,MAAM,aAAa,GAAG,KAAK,CAAC,eAAe,IAAI,yBAAyB,CAAC;IACzE,MAAM,WAAW,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,aAAa,CAAC,CAAC;IAE5D,OAAO;QACL,EAAE,EAAE,MAAM,EAAE;QACZ,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,MAAM,EAAE,QAAQ;QAChB,SAAS,EAAE,GAAG,CAAC,WAAW,EAAE;QAC5B,cAAc,EAAE,WAAW,CAAC,WAAW,EAAE;QACzC,eAAe,EAAE,GAAG,CAAC,WAAW,EAAE;QAClC,cAAc,EAAE,CAAC;QACjB,aAAa,EAAE,KAAK,CAAC,aAAa,IAAI,sBAAsB;QAC5D,eAAe,EAAE,aAAa;KAC/B,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,KAAgB;IAC1C,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACxC,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;IACvB,MAAM,SAAS,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,KAAK,CAAC,eAAe,CAAC,CAAC;IAElE,OAAO;QACL,GAAG,KAAK;QACR,cAAc,EAAE,SAAS,CAAC,WAAW,EAAE;QACvC,eAAe,EAAE,GAAG,CAAC,WAAW,EAAE;QAClC,cAAc,EAAE,KAAK,CAAC,cAAc,GAAG,CAAC;KACzC,CAAC;AACJ,CAAC"}

package/dist/cli/backend/src/types/v2/work-item.types.d.ts

@@ -0,0 +1,323 @@
+/**
+ * V2 WorkItem Type Definitions
+ *
+ * A WorkItem is the unified execution primitive. Every action the system
+ * takes to fulfill a Request or advance a Mission materializes as a WorkItem.
+ * This replaces v1's separate delegation, scheduled-message, and event-subscription concepts.
+ *
+ * @module types/v2/work-item.types
+ */
+/**
+ * Execution type — determines handler and behavior.
+ */
+export type WorkItemType = 'delegate' | 'project_task' | 'check' | 'notify' | 'cron_run' | 'review' | 'confirm' | 'reconcile';
+/** All valid WorkItemType values. */
+export declare const WORK_ITEM_TYPES: readonly WorkItemType[];
+/**
+ * Who is responsible for execution.
+ */
+export type WorkItemOwner = 'orchestrator' | 'team_lead' | 'agent' | 'system';
+/** All valid WorkItemOwner values. */
+export declare const WORK_ITEM_OWNERS: readonly WorkItemOwner[];
+/**
+ * Lifecycle statuses for a WorkItem.
+ *
+ * State machine (extended with acceptance/verification flow):
+ *
+ *   --- Creation & Scheduling ---
+ *   queued → running          (executor picks up item — simple tasks)
+ *   queued → proposed         (TL sends task contract to worker)
+ *   queued → scheduled        (has future scheduledAt)
+ *   queued → cancelled        (parent cancelled)
+ *   scheduled → queued        (scheduledAt reached, trigger fires)
+ *
+ *   --- Acceptance Handshake ---
+ *   proposed → accepted       (worker confirms understanding)
+ *   proposed → rejected       (worker cannot accept — wrong fit, unclear, etc.)
+ *   proposed → cancelled      (parent cancelled before acceptance)
+ *   accepted → running        (worker begins execution)
+ *   rejected → queued         (TL reassigns or re-scopes)
+ *
+ *   --- Execution ---
+ *   running → done_by_worker  (worker reports completion, pending TL verification)
+ *   running → failed          (execution failed, retries exhausted)
+ *   running → blocked         (waiting on dependency)
+ *   running → escalated       (worker escalates — scope/risk/ambiguity)
+ *   running → cancelled       (parent cancelled during execution)
+ *
+ *   --- Verification ---
+ *   done_by_worker → verified (TL verifies and accepts)
+ *   done_by_worker → rejected (TL rejects — needs rework)
+ *   rejected → queued         (re-queue for retry/reassignment)
+ *   escalated → queued        (TL/human resolves and re-queues)
+ *   escalated → cancelled     (escalation results in cancellation)
+ *
+ *   --- Recovery ---
+ *   blocked → queued          (dependency resolved, re-queue)
+ *   failed → queued           (manual retry or reconciler recovery)
+ *
+ *   --- Legacy Compatibility ---
+ *   running → done            (simple tasks without TL verification)
+ *   done is terminal (backward compatible with existing pool operations)
+ */
+export type WorkItemStatus = 'queued' | 'scheduled' | 'ready' | 'proposed' | 'accepted' | 'running' | 'waiting_confirmation' | 'blocked' | 'escalated' | 'done_by_worker' | 'verified' | 'rejected' | 'done' | 'completed' | 'failed' | 'cancelled';
+/** All valid WorkItemStatus values. */
+export declare const WORK_ITEM_STATUSES: readonly WorkItemStatus[];
+/** Terminal statuses — no further transitions allowed. */
+export declare const TERMINAL_WORK_ITEM_STATUSES: ReadonlySet<WorkItemStatus>;
+/**
+ * A single unit of system execution.
+ *
+ * WorkItems are the internal execution primitive — users rarely see them directly.
+ * They unify what v1 had as separate concepts: delegations, scheduled messages,
+ * event subscriptions, cron runs, and checks.
+ */
+export interface WorkItem {
+    /** UUID v4 */
+    id: string;
+    /** Parent Request (undefined for Mission-generated items) */
+    requestId?: string;
+    /** Parent WorkItem for sub-tasks / retries */
+    parentWorkItemId?: string;
+    /** Execution type — determines handler and behavior */
+    type: WorkItemType;
+    /** Who is responsible for execution */
+    owner: WorkItemOwner;
+    /** Target agent session, team, or system component */
+    target?: string;
+    /** Human-readable title */
+    title: string;
+    /** Detailed instructions or description */
+    description?: string;
+    /** Lifecycle status */
+    status: WorkItemStatus;
+    /** When this item should execute (null = immediately) */
+    scheduledAt?: string;
+    /** ISO8601 timestamps */
+    createdAt: string;
+    startedAt?: string;
+    completedAt?: string;
+    /** Execution result data */
+    result?: Record<string, unknown>;
+    /** Error details if failed */
+    error?: string;
+    /** Number of retry attempts so far */
+    retryCount: number;
+    /** Maximum retries before permanent failure */
+    maxRetries: number;
+    /** Trigger ID that created or will wake this WorkItem */
+    triggerId?: string;
+    /** Link to ProjectTask (for durable project work) */
+    projectTaskId?: string;
+    /** Link to Mission (for autonomy-generated work) */
+    missionId?: string;
+    /** Token usage for this specific WorkItem */
+    inputTokens: number;
+    outputTokens: number;
+    /** Cost in USD for this WorkItem */
+    cost: number;
+    /** Extensible metadata (dependency tracking, skill requirements, etc.) */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Input for creating a new WorkItem.
+ */
+export interface CreateWorkItemInput {
+    requestId?: string;
+    parentWorkItemId?: string;
+    type: WorkItemType;
+    owner: WorkItemOwner;
+    target?: string;
+    title: string;
+    description?: string;
+    scheduledAt?: string;
+    maxRetries?: number;
+    triggerId?: string;
+    projectTaskId?: string;
+    missionId?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Input for updating an existing WorkItem.
+ */
+export interface UpdateWorkItemInput {
+    status?: WorkItemStatus;
+    target?: string;
+    result?: Record<string, unknown>;
+    error?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    cost?: number;
+}
+/**
+ * Map of valid status transitions for WorkItems.
+ *
+ * Includes both the original simple flow (queued→running→done) and
+ * the extended acceptance/verification flow (proposed→accepted→running→done_by_worker→verified).
+ */
+export declare const WORK_ITEM_TRANSITIONS: Record<WorkItemStatus, ReadonlySet<WorkItemStatus>>;
+/**
+ * Defines which roles are allowed to trigger specific status transitions.
+ *
+ * Format: `from→to` key maps to a set of allowed WorkItemOwner roles.
+ * If a transition is not listed here, any role may trigger it (backward compatible).
+ * The 'system' role (reconciler) can always trigger any valid transition.
+ */
+export declare const TRANSITION_PERMISSIONS: Record<string, ReadonlySet<WorkItemOwner>>;
+/**
+ * Checks whether a role is permitted to trigger a specific status transition.
+ *
+ * If no explicit permission is defined for a transition, it is considered
+ * open to all roles (backward compatible). The 'system' role always has
+ * permission for any valid transition.
+ *
+ * @param from - Current status
+ * @param to - Desired next status
+ * @param actorRole - Role of the agent/system attempting the transition
+ * @returns True if the role is permitted to trigger this transition
+ */
+export declare function isTransitionPermitted(from: WorkItemStatus, to: WorkItemStatus, actorRole: WorkItemOwner): boolean;
+/**
+ * Checks whether a string is a valid WorkItemType.
+ *
+ * @param value - The string to check
+ * @returns True if value is a valid WorkItemType
+ */
+export declare function isValidWorkItemType(value: string): value is WorkItemType;
+/**
+ * Checks whether a string is a valid WorkItemStatus.
+ *
+ * @param value - The string to check
+ * @returns True if value is a valid WorkItemStatus
+ */
+export declare function isValidWorkItemStatus(value: string): value is WorkItemStatus;
+/**
+ * Checks whether a string is a valid WorkItemOwner.
+ *
+ * @param value - The string to check
+ * @returns True if value is a valid WorkItemOwner
+ */
+export declare function isValidWorkItemOwner(value: string): value is WorkItemOwner;
+/**
+ * Checks whether a WorkItem status transition is valid.
+ *
+ * @param from - Current status
+ * @param to - Desired next status
+ * @returns True if transition is allowed
+ */
+export declare function isValidWorkItemTransition(from: WorkItemStatus, to: WorkItemStatus): boolean;
+/**
+ * Validates that an unknown value is structurally a valid WorkItem.
+ *
+ * @param value - Unknown value to validate
+ * @returns True if value conforms to the WorkItem interface
+ */
+export declare function isWorkItem(value: unknown): value is WorkItem;
+/**
+ * Validates CreateWorkItemInput 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 validateCreateWorkItemInput(input: CreateWorkItemInput): string[];
+/** Default max retries for WorkItems. */
+export declare const DEFAULT_MAX_RETRIES = 3;
+/**
+ * Creates a new WorkItem with sensible defaults.
+ *
+ * @param input - Required and optional creation fields
+ * @returns A fully populated WorkItem object
+ *
+ * @example
+ * ```typescript
+ * const workItem = createWorkItem({
+ *   type: 'delegate',
+ *   owner: 'agent',
+ *   target: 'crewly-product-leo-member-n',
+ *   title: 'Implement TaskPoolService',
+ * });
+ * ```
+ */
+export declare function createWorkItem(input: CreateWorkItemInput): WorkItem;
+/**
+ * Structured contract that a Team Lead sends when delegating a task.
+ *
+ * The worker must confirm understanding before execution begins.
+ * This prevents misaligned expectations and reduces costly late-stage rework.
+ */
+export interface TaskContract {
+    /** What the worker must achieve */
+    goal: string;
+    /** What is explicitly out of scope */
+    nonGoals: string[];
+    /** Specific, verifiable conditions for "done" */
+    acceptanceCriteria: string[];
+    /** Expected deliverable structure */
+    outputFormat: string;
+    /** When to stop and report back (time, complexity, risk thresholds) */
+    cutoffConditions: string[];
+    /** Situations that require immediate escalation */
+    escalationTriggers: string[];
+    /** If true, worker may skip classification gate and proceed directly */
+    preClassified?: boolean;
+}
+/**
+ * Worker's structured confirmation of a received Task Contract.
+ *
+ * TL reviews this before allowing the task to enter 'running' status.
+ */
+export interface TaskAcceptance {
+    /** Worker's understanding of the goal */
+    understoodGoal: string;
+    /** How the worker intends to accomplish it */
+    plannedApproach: string;
+    /** What the worker will NOT do */
+    outOfScope: string[];
+    /** Risks or blockers the worker foresees */
+    identifiedRisks: string[];
+}
+/** Target for an alignment request. */
+export type AlignmentTarget = 'team_lead' | 'human';
+/**
+ * Reason categories for why a worker cannot proceed with direct execution.
+ */
+export type AlignmentReason = 'scope_change' | 'priority_resource' | 'ownership_authority' | 'ambiguity_tradeoff' | 'high_risk';
+/**
+ * A structured escalation from a worker who determines that direct execution
+ * is inappropriate for the current task.
+ *
+ * This replaces unstructured "I'm blocked" messages with actionable information
+ * that enables fast decision-making by TLs or humans.
+ */
+export interface AlignmentRequest {
+    /** The task the worker was asked to do */
+    currentTask: string;
+    /** What triggered the escalation */
+    discoveredIssue: string;
+    /** Category of alignment needed */
+    reason: AlignmentReason;
+    /** Why direct execution is inappropriate */
+    whyCannotExecute: string;
+    /** 2-3 possible approaches with impact analysis */
+    options: AlignmentOption[];
+    /** Worker's recommended path */
+    recommendation: string;
+    /** What the TL/human needs to decide */
+    decisionNeeded: string;
+    /** Who should make this decision */
+    target: AlignmentTarget;
+}
+/**
+ * A single option in an Alignment Request.
+ */
+export interface AlignmentOption {
+    /** Brief description of the approach */
+    description: string;
+    /** Expected positive outcomes */
+    pros: string[];
+    /** Expected negative outcomes or risks */
+    cons: string[];
+    /** Estimated effort/impact level */
+    impact: 'low' | 'medium' | 'high';
+}
+//# sourceMappingURL=work-item.types.d.ts.map

package/dist/cli/backend/src/types/v2/work-item.types.d.ts.map

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