@kbediako/codex-orchestrator 0.1.37 → 0.2.0

package/dist/orchestrator/src/cli/control/providerIntakeState.js

@@ -0,0 +1,473 @@
+import { slugify } from '../utils/strings.js';
+import { isoTimestamp } from '../utils/time.js';
+import { deriveProviderIntakeClaimFreshness } from './providerIssueObservability.js';
+import { normalizeProviderWorkerHostName } from './providerWorkerHosts.js';
+const PROVIDER_INTAKE_CLAIM_LIMIT = 128;
+export function normalizeProviderIntakeState(input) {
+    const state = input ?? {
+        schema_version: 1,
+        updated_at: new Date(0).toISOString(),
+        rehydrated_at: null,
+        latest_provider_key: null,
+        latest_reason: null,
+        polling: null,
+        claims: []
+    };
+    return {
+        schema_version: 1,
+        updated_at: typeof state.updated_at === 'string' && state.updated_at.trim().length > 0
+            ? state.updated_at
+            : new Date(0).toISOString(),
+        rehydrated_at: typeof state.rehydrated_at === 'string' ? state.rehydrated_at : null,
+        latest_provider_key: typeof state.latest_provider_key === 'string' ? state.latest_provider_key : null,
+        latest_reason: typeof state.latest_reason === 'string' ? state.latest_reason : null,
+        polling: isRecordLike(state.polling) ? { ...state.polling } : null,
+        claims: Array.isArray(state.claims)
+            ? state.claims
+                .map(normalizeProviderIntakeClaim)
+                .filter((claim) => claim !== null)
+                .slice(-PROVIDER_INTAKE_CLAIM_LIMIT)
+            : []
+    };
+}
+export function buildProviderIssueKey(provider, issueId) {
+    return `${provider}:${issueId}`;
+}
+export function buildProviderFallbackTaskId(trackedIssue) {
+    const slug = slugify(trackedIssue.id, 'issue').toLowerCase();
+    return `linear-${slug}`;
+}
+export function readProviderIntakeClaim(state, providerKey) {
+    return state.claims.find((claim) => claim.provider_key === providerKey) ?? null;
+}
+export function upsertProviderIntakeClaim(state, input) {
+    const now = input.updated_at ?? isoTimestamp();
+    const existingIndex = state.claims.findIndex((claim) => claim.provider_key === input.provider_key);
+    const existing = existingIndex >= 0 ? state.claims[existingIndex] : null;
+    const nextRunId = input.run_id ?? null;
+    const nextRunManifestPath = input.run_manifest_path ?? null;
+    const runIdentityChanged = hasProviderRunIdentityChanged(existing, {
+        task_id: input.task_id,
+        run_id: nextRunId,
+        run_manifest_path: nextRunManifestPath
+    });
+    const existingLaunchStartedAt = existing?.launch_started_at ??
+        (existing?.launch_source === 'control-host' &&
+            (existing.state === 'starting' ||
+                existing.state === 'resuming')
+            ? existing.updated_at
+            : null);
+    const nextLaunchStartedAt = input.launch_started_at === undefined
+        ? runIdentityChanged
+            ? null
+            : existingLaunchStartedAt ??
+                (input.launch_source === 'control-host' &&
+                    (input.state === 'starting' ||
+                        input.state === 'resuming' ||
+                        input.state === 'handoff_failed')
+                    ? now
+                    : null)
+        : input.launch_started_at;
+    const retryStateDefaults = input.state === 'starting' || input.state === 'resuming' || input.state === 'running'
+        ? {
+            retryQueued: false,
+            retryDueAt: null,
+            retryError: existing?.retry_error ?? null
+        }
+        : existing?.retry_attempt !== null && existing?.retry_attempt !== undefined
+            ? input.state === 'resumable' || input.state === 'handoff_failed'
+                ? {
+                    retryQueued: existing?.retry_queued ?? null,
+                    retryDueAt: existing?.retry_due_at ?? null,
+                    retryError: existing?.retry_error ?? null
+                }
+                : {
+                    retryQueued: false,
+                    retryDueAt: null,
+                    retryError: null
+                }
+            : {
+                retryQueued: existing?.retry_queued ?? null,
+                retryDueAt: existing?.retry_due_at ?? null,
+                retryError: existing?.retry_error ?? null
+            };
+    const next = {
+        provider: 'linear',
+        provider_key: input.provider_key,
+        issue_id: input.issue_id,
+        issue_identifier: input.issue_identifier,
+        issue_title: input.issue_title,
+        issue_state: input.issue_state ?? null,
+        issue_state_type: input.issue_state_type ?? null,
+        issue_updated_at: input.issue_updated_at ?? null,
+        issue_archived_at: input.issue_archived_at === undefined
+            ? existing?.issue_archived_at ?? null
+            : input.issue_archived_at ?? null,
+        issue_trashed: input.issue_trashed === undefined
+            ? existing?.issue_trashed ?? null
+            : normalizeOptionalBoolean(input.issue_trashed),
+        issue_viewer_id: input.issue_viewer_id === undefined
+            ? existing?.issue_viewer_id ?? null
+            : input.issue_viewer_id ?? null,
+        issue_viewer_auth_fingerprint: input.issue_viewer_auth_fingerprint === undefined
+            ? existing?.issue_viewer_auth_fingerprint ?? null
+            : input.issue_viewer_auth_fingerprint ?? null,
+        issue_assignee_id: input.issue_assignee_id ?? null,
+        issue_assignee_name: input.issue_assignee_name ?? null,
+        issue_blocked_by: input.issue_blocked_by === undefined
+            ? normalizeProviderIssueBlockedBy(existing?.issue_blocked_by)
+            : normalizeProviderIssueBlockedBy(input.issue_blocked_by),
+        task_id: input.task_id,
+        mapping_source: input.mapping_source,
+        state: input.state,
+        reason: input.reason ?? null,
+        accepted_at: input.accepted_at ?? existing?.accepted_at ?? now,
+        updated_at: now,
+        last_delivery_id: input.last_delivery_id ?? null,
+        last_event: input.last_event ?? null,
+        last_action: input.last_action ?? null,
+        last_webhook_timestamp: input.last_webhook_timestamp ?? null,
+        run_id: nextRunId,
+        run_manifest_path: nextRunManifestPath,
+        worker_host: input.worker_host === undefined
+            ? runIdentityChanged
+                ? null
+                : existing?.worker_host ?? null
+            : normalizeProviderWorkerHostName(input.worker_host),
+        launch_source: input.launch_source === undefined
+            ? runIdentityChanged
+                ? null
+                : existing?.launch_source ?? null
+            : input.launch_source,
+        launch_token: input.launch_token === undefined
+            ? runIdentityChanged
+                ? null
+                : existing?.launch_token ?? null
+            : input.launch_token,
+        launch_started_at: nextLaunchStartedAt,
+        retry_queued: input.retry_queued === undefined
+            ? retryStateDefaults.retryQueued
+            : normalizeRetryQueued(input.retry_queued),
+        retry_attempt: input.retry_attempt === undefined
+            ? existing?.retry_attempt ?? null
+            : normalizeRetryAttempt(input.retry_attempt),
+        retry_due_at: input.retry_due_at === undefined
+            ? retryStateDefaults.retryDueAt
+            : normalizeRetryTimestamp(input.retry_due_at),
+        retry_error: input.retry_error === undefined
+            ? retryStateDefaults.retryError
+            : normalizeRetryError(input.retry_error),
+        review_promotion: input.review_promotion === undefined
+            ? cloneProviderReviewHandoffPromotionRecord(existing?.review_promotion)
+            : cloneProviderReviewHandoffPromotionRecord(input.review_promotion),
+        merge_closeout: input.merge_closeout === undefined
+            ? cloneProviderMergeCloseoutRecord(existing?.merge_closeout)
+            : cloneProviderMergeCloseoutRecord(input.merge_closeout)
+    };
+    if (existingIndex >= 0) {
+        state.claims.splice(existingIndex, 1, next);
+    }
+    else {
+        state.claims.push(next);
+    }
+    state.updated_at = now;
+    state.latest_provider_key = next.provider_key;
+    state.latest_reason = next.reason;
+    state.claims = state.claims.slice(-PROVIDER_INTAKE_CLAIM_LIMIT);
+    return next;
+}
+function hasProviderRunIdentityChanged(existing, next) {
+    if (!existing) {
+        return false;
+    }
+    if (existing.task_id !== next.task_id) {
+        return true;
+    }
+    const existingRunId = existing.run_id ?? null;
+    const nextRunId = next.run_id ?? null;
+    if (existingRunId || nextRunId) {
+        if (!existingRunId && nextRunId) {
+            return false;
+        }
+        return existingRunId !== nextRunId;
+    }
+    return (existing.run_manifest_path ?? null) !== (next.run_manifest_path ?? null);
+}
+export function markProviderIntakeRehydrated(state, at = isoTimestamp()) {
+    state.rehydrated_at = at;
+    state.updated_at = at;
+}
+export function selectProviderIntakeClaim(state) {
+    if (!state || state.claims.length === 0) {
+        return null;
+    }
+    const claims = [...state.claims].sort(compareProviderClaims);
+    const activeClaims = claims.filter(isActiveProviderIntakeClaim);
+    return activeClaims[0] ?? claims[0] ?? null;
+}
+export function buildProviderIntakeSummary(state) {
+    const normalizedState = normalizeProviderIntakeState(state);
+    const claims = [...normalizedState.claims].sort(compareProviderClaims);
+    const activeClaims = claims.filter(isActiveProviderIntakeClaim);
+    const runningClaims = claims.filter((candidate) => candidate.state === 'running');
+    const claim = selectProviderIntakeClaim(normalizedState);
+    if (!claim) {
+        return null;
+    }
+    const selectedClaim = buildProviderIntakeClaimSummary({
+        claim,
+        rehydratedAt: normalizedState.rehydrated_at
+    });
+    return {
+        provider: claim.provider,
+        summary_scope: activeClaims.length > 1 ? 'selected_claim' : 'single_claim',
+        selection_strategy: activeClaims.length > 1 ? 'state_rank_updated_at' : null,
+        claim_count: claims.length,
+        active_claim_count: activeClaims.length,
+        running_claim_count: runningClaims.length,
+        active_issue_identifiers: activeClaims.map((candidate) => candidate.issue_identifier),
+        running_issue_identifiers: runningClaims.map((candidate) => candidate.issue_identifier),
+        selected_claim: selectedClaim,
+        rehydrated_at: normalizedState.rehydrated_at,
+        is_rehydrated: selectedClaim.freshness === 'rehydrated',
+        updated_at: selectedClaim.updated_at
+    };
+}
+function buildProviderIntakeClaimSummary(input) {
+    const freshness = deriveProviderIntakeClaimFreshness({
+        claim: input.claim,
+        rehydrated_at: input.rehydratedAt
+    });
+    return {
+        provider: input.claim.provider,
+        issue_id: input.claim.issue_id,
+        issue_identifier: input.claim.issue_identifier,
+        issue_title: input.claim.issue_title,
+        issue_state: input.claim.issue_state,
+        issue_state_type: input.claim.issue_state_type,
+        issue_updated_at: input.claim.issue_updated_at,
+        issue_archived_at: input.claim.issue_archived_at ?? null,
+        issue_trashed: input.claim.issue_trashed ?? null,
+        issue_viewer_id: input.claim.issue_viewer_id ?? null,
+        issue_assignee_id: input.claim.issue_assignee_id ?? null,
+        issue_assignee_name: input.claim.issue_assignee_name ?? null,
+        task_id: input.claim.task_id,
+        mapping_source: input.claim.mapping_source,
+        state: deriveProviderIntakeSummaryState(input.claim),
+        reason: input.claim.reason,
+        run_id: input.claim.run_id,
+        worker_host: input.claim.worker_host ?? null,
+        freshness,
+        retry: buildProviderIntakeRetrySummary(input.claim),
+        updated_at: input.claim.updated_at
+    };
+}
+export function hasQueuedProviderIntakeRetry(claim) {
+    return claim?.retry_queued === true;
+}
+function buildProviderIntakeRetrySummary(claim) {
+    if (!claim) {
+        return null;
+    }
+    const active = claim.retry_queued === true;
+    const attempt = claim.retry_attempt ?? null;
+    const dueAt = claim.retry_due_at ?? null;
+    const error = claim.retry_error ?? null;
+    if (!active && attempt === null && dueAt === null && error === null) {
+        return null;
+    }
+    return {
+        active,
+        attempt,
+        due_at: dueAt,
+        error
+    };
+}
+function normalizeProviderIntakeClaim(input) {
+    if (!input || input.provider !== 'linear') {
+        return null;
+    }
+    if (!input.provider_key ||
+        !input.issue_id ||
+        !input.issue_identifier ||
+        !input.issue_title ||
+        !input.task_id) {
+        return null;
+    }
+    const state = normalizeClaimState(input.state);
+    const updatedAt = typeof input.updated_at === 'string' && input.updated_at.trim().length > 0
+        ? input.updated_at
+        : new Date(0).toISOString();
+    const launchSource = input.launch_source === 'control-host' ? 'control-host' : null;
+    const launchStartedAt = typeof input.launch_started_at === 'string' && input.launch_started_at.trim().length > 0
+        ? input.launch_started_at
+        : launchSource === 'control-host' &&
+            (state === 'starting' || state === 'resuming')
+            ? updatedAt
+            : null;
+    return {
+        provider: 'linear',
+        provider_key: input.provider_key,
+        issue_id: input.issue_id,
+        issue_identifier: input.issue_identifier,
+        issue_title: input.issue_title,
+        issue_state: typeof input.issue_state === 'string' ? input.issue_state : null,
+        issue_state_type: typeof input.issue_state_type === 'string' ? input.issue_state_type : null,
+        issue_updated_at: typeof input.issue_updated_at === 'string' ? input.issue_updated_at : null,
+        issue_archived_at: typeof input.issue_archived_at === 'string' ? input.issue_archived_at : null,
+        issue_trashed: normalizeOptionalBoolean(input.issue_trashed),
+        issue_viewer_id: typeof input.issue_viewer_id === 'string' ? input.issue_viewer_id : null,
+        issue_viewer_auth_fingerprint: typeof input.issue_viewer_auth_fingerprint === 'string'
+            ? input.issue_viewer_auth_fingerprint
+            : null,
+        issue_assignee_id: typeof input.issue_assignee_id === 'string' ? input.issue_assignee_id : null,
+        issue_assignee_name: typeof input.issue_assignee_name === 'string' ? input.issue_assignee_name : null,
+        issue_blocked_by: normalizeProviderIssueBlockedBy(input.issue_blocked_by),
+        task_id: input.task_id,
+        mapping_source: 'provider_id_fallback',
+        state,
+        reason: typeof input.reason === 'string' ? input.reason : null,
+        accepted_at: typeof input.accepted_at === 'string' && input.accepted_at.trim().length > 0
+            ? input.accepted_at
+            : new Date(0).toISOString(),
+        updated_at: updatedAt,
+        last_delivery_id: typeof input.last_delivery_id === 'string' ? input.last_delivery_id : null,
+        last_event: typeof input.last_event === 'string' ? input.last_event : null,
+        last_action: typeof input.last_action === 'string' ? input.last_action : null,
+        last_webhook_timestamp: typeof input.last_webhook_timestamp === 'number' &&
+            Number.isFinite(input.last_webhook_timestamp)
+            ? input.last_webhook_timestamp
+            : null,
+        run_id: typeof input.run_id === 'string' ? input.run_id : null,
+        run_manifest_path: typeof input.run_manifest_path === 'string' ? input.run_manifest_path : null,
+        worker_host: normalizeProviderWorkerHostName(input.worker_host),
+        launch_source: launchSource,
+        launch_token: typeof input.launch_token === 'string' ? input.launch_token : null,
+        launch_started_at: launchStartedAt,
+        retry_queued: normalizeRetryQueued(input.retry_queued),
+        retry_attempt: normalizeRetryAttempt(input.retry_attempt),
+        retry_due_at: normalizeRetryTimestamp(input.retry_due_at),
+        retry_error: normalizeRetryError(input.retry_error),
+        review_promotion: cloneProviderReviewHandoffPromotionRecord(input.review_promotion),
+        merge_closeout: cloneProviderMergeCloseoutRecord(input.merge_closeout)
+    };
+}
+export function isRecordLike(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function normalizeRetryQueued(value) {
+    return typeof value === 'boolean' ? value : null;
+}
+function normalizeOptionalBoolean(value) {
+    return normalizeRetryQueued(value);
+}
+function normalizeProviderIssueBlockedBy(value) {
+    if (!Array.isArray(value)) {
+        return null;
+    }
+    return value.map((blocker) => ({
+        id: typeof blocker?.id === 'string' ? blocker.id : null,
+        identifier: typeof blocker?.identifier === 'string' ? blocker.identifier : null,
+        state: typeof blocker?.state === 'string' ? blocker.state : null,
+        state_type: typeof blocker?.state_type === 'string' ? blocker.state_type : null
+    }));
+}
+function normalizeRetryAttempt(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value > 0 ? value : null;
+}
+function normalizeRetryTimestamp(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value : null;
+}
+function normalizeRetryError(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value : null;
+}
+function cloneProviderMergeCloseoutRecord(value) {
+    return isRecordLike(value)
+        ? JSON.parse(JSON.stringify(value))
+        : null;
+}
+function cloneProviderReviewHandoffPromotionRecord(value) {
+    return isRecordLike(value)
+        ? JSON.parse(JSON.stringify(value))
+        : null;
+}
+function normalizeClaimState(value) {
+    switch (value) {
+        case 'ignored':
+        case 'accepted':
+        case 'starting':
+        case 'running':
+        case 'resuming':
+        case 'resumable':
+        case 'released':
+        case 'completed':
+        case 'stale':
+        case 'duplicate':
+        case 'handoff_failed':
+            return value;
+        default:
+            return 'ignored';
+    }
+}
+function deriveProviderIntakeSummaryState(claim) {
+    if (claim.state === 'handoff_failed' &&
+        claim.reason === 'provider_issue_handoff_owned') {
+        return 'handoff_owned';
+    }
+    return claim.state;
+}
+function isActiveProviderIntakeClaim(claim) {
+    if (claim.retry_queued === true) {
+        return true;
+    }
+    switch (claim.state) {
+        case 'accepted':
+        case 'starting':
+        case 'running':
+        case 'resuming':
+        case 'resumable':
+        case 'handoff_failed':
+            return true;
+        case 'released':
+        case 'completed':
+        case 'stale':
+        case 'duplicate':
+        case 'ignored':
+        default:
+            return false;
+    }
+}
+function compareProviderClaims(left, right) {
+    const rankDelta = rankClaimState(right.state) - rankClaimState(left.state);
+    if (rankDelta !== 0) {
+        return rankDelta;
+    }
+    return Date.parse(right.updated_at) - Date.parse(left.updated_at);
+}
+function rankClaimState(state) {
+    switch (state) {
+        case 'running':
+            return 9;
+        case 'resuming':
+            return 8;
+        case 'starting':
+            return 7;
+        case 'resumable':
+            return 6;
+        case 'accepted':
+            return 5;
+        case 'released':
+            return 4;
+        case 'handoff_failed':
+            return 3;
+        case 'completed':
+            return 2;
+        case 'duplicate':
+            return 1;
+        case 'stale':
+            return 0;
+        case 'ignored':
+        default:
+            return -1;
+    }
+}