crewly 1.5.18 → 1.5.19

package/dist/backend/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' | 'proposed' | 'accepted' | 'running' | 'blocked' | 'escalated' | 'done_by_worker' | 'verified' | 'rejected' | 'done' | '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/backend/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":"AAAA;;;;;;;;GAQG;AAQH;;GAEG;AACH,MAAM,MAAM,YAAY,GACpB,UAAU,GACV,cAAc,GACd,OAAO,GACP,QAAQ,GACR,UAAU,GACV,QAAQ,GACR,SAAS,GACT,WAAW,CAAC;AAEhB,qCAAqC;AACrC,eAAO,MAAM,eAAe,EAAE,SAAS,YAAY,EASzC,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,aAAa,GACrB,cAAc,GACd,WAAW,GACX,OAAO,GACP,QAAQ,CAAC;AAEb,sCAAsC;AACtC,eAAO,MAAM,gBAAgB,EAAE,SAAS,aAAa,EAK3C,CAAC;AAEX;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,MAAM,MAAM,cAAc,GACtB,QAAQ,GACR,WAAW,GACX,UAAU,GACV,UAAU,GACV,SAAS,GACT,SAAS,GACT,WAAW,GACX,gBAAgB,GAChB,UAAU,GACV,UAAU,GACV,MAAM,GACN,QAAQ,GACR,WAAW,CAAC;AAEhB,uCAAuC;AACvC,eAAO,MAAM,kBAAkB,EAAE,SAAS,cAAc,EAc9C,CAAC;AAEX,0DAA0D;AAC1D,eAAO,MAAM,2BAA2B,EAAE,WAAW,CAAC,cAAc,CAIlE,CAAC;AAMH;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ;IACvB,cAAc;IACd,EAAE,EAAE,MAAM,CAAC;IACX,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8CAA8C;IAC9C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,uDAAuD;IACvD,IAAI,EAAE,YAAY,CAAC;IACnB,uCAAuC;IACvC,KAAK,EAAE,aAAa,CAAC;IACrB,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2BAA2B;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uBAAuB;IACvB,MAAM,EAAE,cAAc,CAAC;IACvB,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yBAAyB;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4BAA4B;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,8BAA8B;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,UAAU,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qDAAqD;IACrD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAMD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,IAAI,EAAE,YAAY,CAAC;IACnB,KAAK,EAAE,aAAa,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAMD;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,cAAc,EAAE,WAAW,CAAC,cAAc,CAAC,CAcrF,CAAC;AAMF;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,aAAa,CAAC,CAe7E,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,cAAc,EACpB,EAAE,EAAE,cAAc,EAClB,SAAS,EAAE,aAAa,GACvB,OAAO,CAWT;AAMD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,YAAY,CAExE;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,cAAc,CAE5E;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,aAAa,CAE1E;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,cAAc,EAAE,EAAE,EAAE,cAAc,GAAG,OAAO,CAE3F;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAgB5D;AAMD;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,mBAAmB,GAAG,MAAM,EAAE,CAqBhF;AAMD,yCAAyC;AACzC,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,QAAQ,CAyBnE;AAMD;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,iDAAiD;IACjD,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,qCAAqC;IACrC,YAAY,EAAE,MAAM,CAAC;IACrB,uEAAuE;IACvE,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,mDAAmD;IACnD,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,wEAAwE;IACxE,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,yCAAyC;IACzC,cAAc,EAAE,MAAM,CAAC;IACvB,8CAA8C;IAC9C,eAAe,EAAE,MAAM,CAAC;IACxB,kCAAkC;IAClC,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,4CAA4C;IAC5C,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAMD,uCAAuC;AACvC,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG,OAAO,CAAC;AAEpD;;GAEG;AACH,MAAM,MAAM,eAAe,GACvB,cAAc,GACd,mBAAmB,GACnB,qBAAqB,GACrB,oBAAoB,GACpB,WAAW,CAAC;AAEhB;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,0CAA0C;IAC1C,WAAW,EAAE,MAAM,CAAC;IACpB,oCAAoC;IACpC,eAAe,EAAE,MAAM,CAAC;IACxB,mCAAmC;IACnC,MAAM,EAAE,eAAe,CAAC;IACxB,4CAA4C;IAC5C,gBAAgB,EAAE,MAAM,CAAC;IACzB,mDAAmD;IACnD,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,gCAAgC;IAChC,cAAc,EAAE,MAAM,CAAC;IACvB,wCAAwC;IACxC,cAAc,EAAE,MAAM,CAAC;IACvB,oCAAoC;IACpC,MAAM,EAAE,eAAe,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,wCAAwC;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,iCAAiC;IACjC,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,0CAA0C;IAC1C,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,oCAAoC;IACpC,MAAM,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;CACnC"}

package/dist/backend/backend/src/types/v2/work-item.types.js

@@ -0,0 +1,264 @@
+/**
+ * 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
+ */
+import { v4 as uuidv4 } from 'uuid';
+/** All valid WorkItemType values. */
+export const WORK_ITEM_TYPES = [
+    'delegate',
+    'project_task',
+    'check',
+    'notify',
+    'cron_run',
+    'review',
+    'confirm',
+    'reconcile',
+];
+/** All valid WorkItemOwner values. */
+export const WORK_ITEM_OWNERS = [
+    'orchestrator',
+    'team_lead',
+    'agent',
+    'system',
+];
+/** All valid WorkItemStatus values. */
+export const WORK_ITEM_STATUSES = [
+    'queued',
+    'scheduled',
+    'proposed',
+    'accepted',
+    'running',
+    'blocked',
+    'escalated',
+    'done_by_worker',
+    'verified',
+    'rejected',
+    'done',
+    'failed',
+    'cancelled',
+];
+/** Terminal statuses — no further transitions allowed. */
+export const TERMINAL_WORK_ITEM_STATUSES = new Set([
+    'done',
+    'verified',
+    'cancelled',
+]);
+// ---------------------------------------------------------------------------
+// Valid State Transitions
+// ---------------------------------------------------------------------------
+/**
+ * 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 const WORK_ITEM_TRANSITIONS = {
+    queued: new Set(['running', 'proposed', 'scheduled', 'cancelled']),
+    scheduled: new Set(['queued', 'cancelled']),
+    proposed: new Set(['accepted', 'rejected', 'cancelled']),
+    accepted: new Set(['running', 'cancelled']),
+    running: new Set(['done', 'done_by_worker', 'failed', 'blocked', 'escalated', 'cancelled']),
+    blocked: new Set(['queued', 'cancelled']),
+    escalated: new Set(['queued', 'cancelled']),
+    done_by_worker: new Set(['verified', 'rejected']),
+    verified: new Set(),
+    rejected: new Set(['queued']),
+    done: new Set(),
+    failed: new Set(['queued']),
+    cancelled: new Set(),
+};
+// ---------------------------------------------------------------------------
+// Role-Based Transition Permissions
+// ---------------------------------------------------------------------------
+/**
+ * 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 const TRANSITION_PERMISSIONS = {
+    // Only TL or orchestrator can propose tasks
+    'queued→proposed': new Set(['team_lead', 'orchestrator']),
+    // Only the assigned agent can accept or reject a proposal
+    'proposed→accepted': new Set(['agent']),
+    'proposed→rejected': new Set(['agent']),
+    // Only the assigned agent can report completion
+    'running→done_by_worker': new Set(['agent']),
+    // Only the assigned agent can escalate
+    'running→escalated': new Set(['agent']),
+    // Only TL can verify or reject worker output
+    'done_by_worker→verified': new Set(['team_lead']),
+    'done_by_worker→rejected': new Set(['team_lead']),
+    // Simple done — allowed for agents (simple tasks) and system (reconciler)
+    'running→done': new Set(['agent', 'system', 'orchestrator']),
+};
+/**
+ * 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 function isTransitionPermitted(from, to, actorRole) {
+    // System role can always transition
+    if (actorRole === 'system')
+        return true;
+    const key = `${from}→${to}`;
+    const allowed = TRANSITION_PERMISSIONS[key];
+    // If no explicit permission defined, allow any role (backward compatible)
+    if (!allowed)
+        return true;
+    return allowed.has(actorRole);
+}
+// ---------------------------------------------------------------------------
+// Type Guards
+// ---------------------------------------------------------------------------
+/**
+ * Checks whether a string is a valid WorkItemType.
+ *
+ * @param value - The string to check
+ * @returns True if value is a valid WorkItemType
+ */
+export function isValidWorkItemType(value) {
+    return WORK_ITEM_TYPES.includes(value);
+}
+/**
+ * Checks whether a string is a valid WorkItemStatus.
+ *
+ * @param value - The string to check
+ * @returns True if value is a valid WorkItemStatus
+ */
+export function isValidWorkItemStatus(value) {
+    return WORK_ITEM_STATUSES.includes(value);
+}
+/**
+ * Checks whether a string is a valid WorkItemOwner.
+ *
+ * @param value - The string to check
+ * @returns True if value is a valid WorkItemOwner
+ */
+export function isValidWorkItemOwner(value) {
+    return WORK_ITEM_OWNERS.includes(value);
+}
+/**
+ * Checks whether a WorkItem status transition is valid.
+ *
+ * @param from - Current status
+ * @param to - Desired next status
+ * @returns True if transition is allowed
+ */
+export function isValidWorkItemTransition(from, to) {
+    return WORK_ITEM_TRANSITIONS[from].has(to);
+}
+/**
+ * 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 function isWorkItem(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const obj = value;
+    return (typeof obj.id === 'string' &&
+        typeof obj.type === 'string' &&
+        isValidWorkItemType(obj.type) &&
+        typeof obj.owner === 'string' &&
+        isValidWorkItemOwner(obj.owner) &&
+        typeof obj.title === 'string' &&
+        typeof obj.status === 'string' &&
+        isValidWorkItemStatus(obj.status) &&
+        typeof obj.createdAt === 'string' &&
+        typeof obj.retryCount === 'number' &&
+        typeof obj.maxRetries === 'number');
+}
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+/**
+ * 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 function validateCreateWorkItemInput(input) {
+    const errors = [];
+    if (!input.type || !isValidWorkItemType(input.type)) {
+        errors.push(`type must be one of: ${WORK_ITEM_TYPES.join(', ')}`);
+    }
+    if (!input.owner || !isValidWorkItemOwner(input.owner)) {
+        errors.push(`owner must be one of: ${WORK_ITEM_OWNERS.join(', ')}`);
+    }
+    if (!input.title || typeof input.title !== 'string') {
+        errors.push('title is required and must be a non-empty string');
+    }
+    if (input.scheduledAt) {
+        const d = new Date(input.scheduledAt);
+        if (isNaN(d.getTime())) {
+            errors.push('scheduledAt must be a valid ISO8601 date string');
+        }
+    }
+    if (input.maxRetries !== undefined && (input.maxRetries < 0 || !Number.isInteger(input.maxRetries))) {
+        errors.push('maxRetries must be a non-negative integer');
+    }
+    return errors;
+}
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/** Default max retries for WorkItems. */
+export 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 function createWorkItem(input) {
+    const now = new Date().toISOString();
+    const hasSchedule = !!input.scheduledAt;
+    return {
+        id: uuidv4(),
+        requestId: input.requestId,
+        parentWorkItemId: input.parentWorkItemId,
+        type: input.type,
+        owner: input.owner,
+        target: input.target,
+        title: input.title,
+        description: input.description,
+        status: hasSchedule ? 'scheduled' : 'queued',
+        scheduledAt: input.scheduledAt,
+        createdAt: now,
+        retryCount: 0,
+        maxRetries: input.maxRetries ?? DEFAULT_MAX_RETRIES,
+        triggerId: input.triggerId,
+        projectTaskId: input.projectTaskId,
+        missionId: input.missionId,
+        inputTokens: 0,
+        outputTokens: 0,
+        cost: 0,
+        metadata: input.metadata,
+    };
+}
+//# sourceMappingURL=work-item.types.js.map

package/dist/backend/backend/src/types/v2/work-item.types.js.map

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