@kbediako/codex-orchestrator 0.1.38 → 0.2.1

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

@@ -0,0 +1,284 @@
+import { isoTimestamp } from '../utils/time.js';
+import { serializeProviderIntakeSummary } from './observabilityReadModel.js';
+import { findCompatibilityProjectionIssueRecord } from './compatibilityIssuePresenter.js';
+import { buildCompatibilityIssueRecordLookups, resolveRetryIssueRecord, resolveRunningIssueRecord } from './operatorDashboardPresenter.js';
+const READ_ONLY_COMPAT_ACTION = 'refresh';
+const COMPATIBILITY_MUTATING_ACTIONS = new Set(['pause', 'resume', 'cancel', 'fail', 'rerun']);
+const JSON_HEADERS = { 'Content-Type': 'application/json' };
+export function buildCompatibilityErrorResponse(input) {
+    return {
+        status: input.status,
+        headers: JSON_HEADERS,
+        body: {
+            error: {
+                code: input.code,
+                message: input.message,
+                ...(input.details ? { details: input.details } : {})
+            },
+            ...(input.traceability ? { traceability: input.traceability } : {})
+        }
+    };
+}
+export function buildCompatibilityMethodNotAllowedResponse(context, allowedMethod, issueIdentifier) {
+    return buildCompatibilityErrorResponse({
+        status: 405,
+        code: 'method_not_allowed',
+        message: 'Method not allowed',
+        details: {
+            surface: 'api_v1',
+            allowed_method: allowedMethod,
+            ...(issueIdentifier ? { issue_identifier: issueIdentifier } : {})
+        },
+        traceability: buildCompatibilityTraceability(context, {
+            decision: 'rejected',
+            reason: 'method_not_allowed',
+            ...(issueIdentifier ? { issueIdentifier } : {})
+        })
+    });
+}
+export function buildCompatibilityIssueNotFoundResponse(context, issueIdentifier) {
+    return buildCompatibilityErrorResponse({
+        status: 404,
+        code: 'issue_not_found',
+        message: 'Issue not found',
+        details: {
+            surface: 'api_v1',
+            issue_identifier: issueIdentifier
+        },
+        traceability: buildCompatibilityTraceability(context, {
+            decision: 'rejected',
+            reason: 'issue_not_found',
+            issueIdentifier
+        })
+    });
+}
+export function buildCompatibilityNotFoundResponse(context) {
+    return buildCompatibilityErrorResponse({
+        status: 404,
+        code: 'not_found',
+        message: 'Route not found',
+        details: {
+            surface: 'api_v1'
+        },
+        traceability: buildCompatibilityTraceability(context, {
+            decision: 'rejected',
+            reason: 'route_not_found'
+        })
+    });
+}
+export function buildCompatibilityRefreshRejectedResponse(context, rejection) {
+    return buildCompatibilityErrorResponse({
+        status: resolveCompatibilityRefreshRejectionStatus(rejection.reason),
+        code: 'read_only_action_rejected',
+        message: 'Compatibility surface is read-only; only refresh acknowledgements are supported.',
+        details: {
+            surface: 'api_v1',
+            mode: 'read_only',
+            reason: rejection.reason,
+            allowed_actions: ['refresh'],
+            allowed_tools: [],
+            requested_action: rejection.requestAction,
+            requested_tool: rejection.requestTool
+        },
+        traceability: buildCompatibilityTraceability(context, {
+            decision: 'rejected',
+            reason: rejection.reason,
+            requestAction: rejection.requestAction,
+            requestTool: rejection.requestTool
+        })
+    });
+}
+// `/api/v1/dispatch` is a CO-specific extension over the Symphony-aligned
+// compatibility surface, so keep the dispatch payload seam explicit.
+export async function readDispatchExtension(context) {
+    const { issueIdentifier, evaluation } = await context.readDispatchEvaluation();
+    if (evaluation.failure) {
+        return {
+            kind: 'fail_closed',
+            issueIdentifier,
+            evaluation,
+            failure: evaluation.failure,
+            details: {
+                surface: 'api_v1',
+                mode: 'read_only',
+                advisory_only: true,
+                reason: evaluation.failure.reason,
+                dispatch_pilot: evaluation.summary
+            }
+        };
+    }
+    return {
+        kind: 'ok',
+        issueIdentifier,
+        evaluation,
+        payload: {
+            generated_at: isoTimestamp(),
+            mode: 'read_only',
+            advisory_only: true,
+            dispatch_pilot: evaluation.summary,
+            recommendation: evaluation.recommendation
+        }
+    };
+}
+export async function readCompatibilityRefresh(context, body = {}) {
+    const rejection = resolveCompatibilityActionEnvelopeRejection(body);
+    if (rejection) {
+        return {
+            kind: 'rejected',
+            reason: rejection.reason,
+            requestAction: rejection.requestAction,
+            requestTool: rejection.requestTool
+        };
+    }
+    const refreshAcknowledgement = normalizeRefreshAcknowledgement(await context.requestRefresh());
+    const requestBody = isRecordLike(body) ? body : {};
+    const requestedAction = readStringValue(requestBody, 'action');
+    return {
+        kind: 'accepted',
+        payload: {
+            ...refreshAcknowledgement,
+            traceability: buildCompatibilityTraceability(context, {
+                decision: 'acknowledged',
+                reason: 'refresh_requested',
+                requestAction: requestedAction ? requestedAction.toLowerCase() : READ_ONLY_COMPAT_ACTION
+            })
+        }
+    };
+}
+function normalizeRefreshAcknowledgement(value) {
+    return {
+        queued: value?.queued ?? true,
+        coalesced: value?.coalesced ?? false,
+        requested_at: value?.requested_at ?? isoTimestamp(),
+        operations: value?.operations ?? ['poll', 'reconcile'],
+        stuck: value?.stuck ?? false,
+        restart_required: value?.restart_required ?? false,
+        reason: value?.reason ?? null
+    };
+}
+export function buildCompatibilityTraceability(context, input) {
+    const snapshot = context.controlStore.snapshot();
+    return {
+        task_id: resolveTaskIdFromManifestPath(context.paths.manifestPath),
+        run_id: snapshot.run_id,
+        manifest_path: context.paths.manifestPath,
+        surface: 'api_v1',
+        issue_identifier: input.issueIdentifier ?? null,
+        requested_action: input.requestAction ?? null,
+        requested_tool: input.requestTool ?? null,
+        decision: input.decision,
+        reason: input.reason,
+        timestamp: isoTimestamp()
+    };
+}
+export async function readCompatibilityState(context) {
+    const projection = await context.readCompatibilityProjection();
+    const generatedAt = isoTimestamp();
+    const issueRecordLookups = buildCompatibilityIssueRecordLookups(projection.issues);
+    return {
+        generated_at: generatedAt,
+        counts: { running: projection.running.length, retrying: projection.retrying.length },
+        running_ids: projection.running.map((entry) => resolveRunningIssueRecord(entry, issueRecordLookups)?.issueIdentifier ?? entry.issue_identifier),
+        retrying_ids: projection.retrying.map((entry) => resolveRetryIssueRecord(entry, issueRecordLookups)?.issueIdentifier ?? entry.issue_identifier),
+        running: projection.running,
+        retrying: projection.retrying,
+        codex_totals: projection.codexTotals,
+        rate_limits: projection.rateLimits,
+        selected: projection.selected,
+        ...(projection.providerIntake
+            ? { provider_intake: serializeProviderIntakeSummary(projection.providerIntake) }
+            : {}),
+        ...(projection.providerWorkflow ? { provider_workflow: projection.providerWorkflow } : {}),
+        ...(projection.polling ? { polling: projection.polling } : {}),
+        ...(projection.dispatchPilot ? { dispatch_pilot: projection.dispatchPilot } : {}),
+        ...(projection.tracked ? { tracked: projection.tracked } : {})
+    };
+}
+export async function readCompatibilityIssue(context, issueIdentifier) {
+    const projection = await context.readCompatibilityProjection();
+    const issue = findCompatibilityProjectionIssueRecord(projection, issueIdentifier);
+    if (!issue) {
+        return { kind: 'issue_not_found' };
+    }
+    return {
+        kind: 'ok',
+        payload: issue.payload
+    };
+}
+function resolveCompatibilityActionEnvelopeRejection(body) {
+    if (!isRecordLike(body)) {
+        return {
+            reason: 'malformed_action_request',
+            requestAction: null,
+            requestTool: null
+        };
+    }
+    const hasAction = Object.prototype.hasOwnProperty.call(body, 'action');
+    const hasTool = Object.prototype.hasOwnProperty.call(body, 'tool');
+    if (!hasAction && !hasTool) {
+        return null;
+    }
+    const actionValue = readStringValue(body, 'action');
+    const normalizedAction = actionValue ? actionValue.toLowerCase() : null;
+    const toolValue = readStringValue(body, 'tool');
+    const normalizedTool = toolValue ? toolValue.toLowerCase() : null;
+    if (hasAction && !normalizedAction) {
+        return {
+            reason: 'malformed_action_request',
+            requestAction: null,
+            requestTool: normalizedTool
+        };
+    }
+    if (normalizedAction && COMPATIBILITY_MUTATING_ACTIONS.has(normalizedAction)) {
+        return {
+            reason: 'forbidden_mutating_action',
+            requestAction: normalizedAction,
+            requestTool: normalizedTool
+        };
+    }
+    if (normalizedAction && normalizedAction !== READ_ONLY_COMPAT_ACTION) {
+        return {
+            reason: 'unsupported_action',
+            requestAction: normalizedAction,
+            requestTool: normalizedTool
+        };
+    }
+    if (hasTool) {
+        return {
+            reason: 'unsupported_tool',
+            requestAction: normalizedAction,
+            requestTool: normalizedTool
+        };
+    }
+    return null;
+}
+function resolveCompatibilityRefreshRejectionStatus(reason) {
+    switch (reason) {
+        case 'forbidden_mutating_action':
+        case 'unsupported_tool':
+            return 403;
+        case 'malformed_action_request':
+        case 'unsupported_action':
+            return 400;
+    }
+}
+function isRecordLike(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function resolveTaskIdFromManifestPath(manifestPath) {
+    const normalizedPath = manifestPath.replace(/\\/g, '/');
+    const match = normalizedPath.match(/\.runs\/([^/]+)\/cli\//);
+    return match?.[1] ?? null;
+}
+function readStringValue(record, ...keys) {
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value === 'string') {
+            const trimmed = value.trim();
+            if (trimmed.length > 0) {
+                return trimmed;
+            }
+        }
+    }
+    return undefined;
+}

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

@@ -0,0 +1,22 @@
+import { logger } from '../../logger.js';
+export function createObservabilityUpdateNotifier() {
+    const listeners = new Set();
+    return {
+        publish(input) {
+            const snapshot = Array.from(listeners);
+            for (const listener of snapshot) {
+                Promise.resolve()
+                    .then(() => listener(input))
+                    .catch((error) => {
+                    logger.warn(`Failed to handle observability update: ${error?.message ?? String(error)}`);
+                });
+            }
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        }
+    };
+}

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

@@ -0,0 +1,252 @@
+import { hostname } from 'node:os';
+import { resolveProviderWorkerHost } from './observabilityReadModel.js';
+import { isoTimestamp } from '../utils/time.js';
+const LOCAL_HOSTNAME = hostname();
+export function buildUiDataset(input) {
+    const generatedAt = input.generatedAt ?? isoTimestamp();
+    const selectedIssueIdentifier = input.projection.selected?.issue_identifier ?? null;
+    const issueRecords = input.projection.issues;
+    const issuePayloads = issueRecords.map((record) => record.payload);
+    const issueRecordLookups = buildCompatibilityIssueRecordLookups(issueRecords);
+    return {
+        generated_at: generatedAt,
+        mode: 'operator_dashboard',
+        read_only: true,
+        host: LOCAL_HOSTNAME,
+        counts: {
+            running: input.projection.running.length,
+            retrying: input.projection.retrying.length,
+            issues: issuePayloads.length,
+            max_allowed: input.projection.maxConcurrentAgents ?? null
+        },
+        totals: input.projection.codexTotals,
+        rate_limits: input.projection.rateLimits,
+        polling: input.projection.polling ?? null,
+        selected_issue_identifier: selectedIssueIdentifier,
+        selected: input.projection.selected,
+        running: input.projection.running.map((entry) => buildRunningSessionPayload(entry, resolveRunningIssueRecord(entry, issueRecordLookups))),
+        retrying: input.projection.retrying.map((entry) => buildRetryQueuePayload(entry, resolveRetryIssueRecord(entry, issueRecordLookups))),
+        issues: issuePayloads.map((issue) => buildIssuePayload(issue, issue.issue_identifier === selectedIssueIdentifier)),
+        ...(input.projection.providerWorkflow ? { provider_workflow: input.projection.providerWorkflow } : {}),
+        ...(input.projection.providerIntake ? { provider_intake: input.projection.providerIntake } : {}),
+        ...(input.projection.dispatchPilot ? { dispatch_pilot: input.projection.dispatchPilot } : {}),
+        ...(input.projection.tracked ? { tracked: input.projection.tracked } : {})
+    };
+}
+export function buildCompatibilityIssueRecordLookups(issueRecords) {
+    const records = issueRecords ?? [];
+    return {
+        byId: new Map(records.flatMap((issue) => issue.payload.issue_id === null ? [] : [[issue.payload.issue_id, issue]])),
+        byRunId: new Map(records.flatMap((issue) => issue.payload.run_id === null ? [] : [[issue.payload.run_id, issue]])),
+        byIdentifier: new Map(records.map((issue) => [issue.payload.issue_identifier, issue]))
+    };
+}
+export async function readUiDataset(context) {
+    const projection = await context.readCompatibilityProjection();
+    return buildUiDataset({
+        projection
+    });
+}
+function buildIssuePayload(issue, isSelected) {
+    const proof = issue.provider_linear_worker_proof ?? null;
+    const trackedLinear = issue.tracked && 'linear' in issue.tracked ? issue.tracked.linear : null;
+    const running = issue.running ?? null;
+    const stageStartedAt = running?.started_at ??
+        issue.retry?.started_at ??
+        issue.provider_debug_snapshot?.claim?.launch_started_at ??
+        null;
+    const workerHost = issue.worker_host ??
+        resolveProviderWorkerHost({
+            providerLinearWorkerProof: proof,
+            providerDebugSnapshot: issue.provider_debug_snapshot ?? null,
+            stageStartedAt
+        });
+    return {
+        issue_identifier: issue.issue_identifier,
+        issue_id: issue.issue_id,
+        task_id: issue.task_id,
+        run_id: issue.run_id,
+        status: issue.status,
+        raw_status: issue.raw_status,
+        display_status: issue.display_status,
+        status_reason: issue.status_reason,
+        title: trackedLinear?.title ?? null,
+        url: trackedLinear?.url ?? null,
+        workspace: {
+            path: issue.workspace.path ?? proof?.workspace_path ?? null,
+            host: LOCAL_HOSTNAME
+        },
+        ...(workerHost !== null ? { worker_host: workerHost } : {}),
+        session: {
+            session_id: proof?.latest_session_id ?? running?.session_id ?? issue.retry?.session_id ?? null,
+            thread_id: proof?.thread_id ?? null,
+            turn_count: proof?.turn_count ?? running?.turn_count ?? null
+        },
+        owner: {
+            phase: proof?.owner_phase ?? null,
+            status: proof?.owner_status ?? null
+        },
+        tokens: proof?.tokens ?? running?.tokens ?? null,
+        rate_limits: proof?.rate_limits ?? null,
+        summary: issue.summary,
+        last_error: issue.last_error,
+        latest_event: issue.latest_event,
+        recent_agent_activity: normalizeRecentAgentActivity(issue, proof),
+        linear_activity: normalizeLinearActivity(trackedLinear?.recent_activity),
+        running: issue.running,
+        retry: issue.retry,
+        attempts: issue.attempts,
+        tracked: issue.tracked,
+        provider_linear_worker_proof: proof,
+        provider_debug_snapshot: issue.provider_debug_snapshot ?? null,
+        is_selected: isSelected
+    };
+}
+function buildRunningSessionPayload(entry, issueRecord) {
+    const issue = issueRecord?.payload ?? null;
+    const proof = issue?.provider_linear_worker_proof ?? null;
+    const workerHost = entry.worker_host ??
+        issue?.worker_host ??
+        resolveProviderWorkerHost({
+            providerLinearWorkerProof: proof,
+            providerDebugSnapshot: issue?.provider_debug_snapshot ?? null,
+            stageStartedAt: entry.started_at ??
+                issue?.running?.started_at ??
+                issue?.provider_debug_snapshot?.claim?.launch_started_at ??
+                null
+        });
+    return {
+        issue_identifier: entry.issue_identifier,
+        issue_id: entry.issue_id,
+        id: issueRecord?.issueIdentifier ?? entry.issue_identifier,
+        bucket: 'running',
+        state: entry.state,
+        reason: entry.status_reason,
+        aliases: resolveCompatibilityAliases({
+            issueRecord,
+            issueIdentifier: entry.issue_identifier,
+            issueId: entry.issue_id,
+            taskId: issue?.task_id ?? null,
+            runId: issue?.run_id ?? null
+        }),
+        task_id: issue?.task_id ?? null,
+        run_id: issue?.run_id ?? null,
+        summary: issue?.summary ?? null,
+        display_state: entry.display_state,
+        status_reason: entry.status_reason,
+        pid: proof === null ? (entry.pid ?? null) : (proof.pid ?? null),
+        session_id: proof?.latest_session_id ?? entry.session_id,
+        thread_id: proof?.thread_id ?? null,
+        turn_count: proof?.turn_count ?? entry.turn_count,
+        workspace_path: issue?.workspace.path ?? proof?.workspace_path ?? null,
+        host: LOCAL_HOSTNAME,
+        ...(workerHost !== null ? { worker_host: workerHost } : {}),
+        last_event: entry.last_event,
+        last_message: entry.last_message,
+        display_event: entry.display_event ?? null,
+        started_at: entry.started_at,
+        last_event_at: entry.last_event_at,
+        tokens: proof?.tokens ?? entry.tokens
+    };
+}
+function buildRetryQueuePayload(entry, issueRecord) {
+    const issue = issueRecord?.payload ?? null;
+    const proof = issue?.provider_linear_worker_proof ?? null;
+    const workerHost = entry.worker_host ??
+        issue?.worker_host ??
+        resolveProviderWorkerHost({
+            providerLinearWorkerProof: proof,
+            providerDebugSnapshot: issue?.provider_debug_snapshot ?? null,
+            stageStartedAt: entry.started_at ??
+                issue?.retry?.started_at ??
+                issue?.provider_debug_snapshot?.claim?.launch_started_at ??
+                null
+        });
+    return {
+        issue_identifier: entry.issue_identifier,
+        issue_id: entry.issue_id,
+        id: issueRecord?.issueIdentifier ?? entry.issue_identifier,
+        bucket: 'retrying',
+        state: entry.state,
+        reason: entry.status_reason,
+        aliases: resolveCompatibilityAliases({
+            issueRecord,
+            issueIdentifier: entry.issue_identifier,
+            issueId: entry.issue_id,
+            taskId: entry.task_id ?? issue?.task_id ?? null,
+            runId: entry.run_id ?? issue?.run_id ?? null
+        }),
+        task_id: entry.task_id ?? issue?.task_id ?? null,
+        run_id: entry.run_id ?? issue?.run_id ?? null,
+        summary: issue?.summary ?? null,
+        display_state: entry.display_state,
+        status_reason: entry.status_reason,
+        session_id: entry.session_id,
+        thread_id: entry.thread_id ?? null,
+        turn_count: entry.turn_count ?? null,
+        workspace_path: entry.workspace_path ?? null,
+        host: LOCAL_HOSTNAME,
+        ...(workerHost !== null ? { worker_host: workerHost } : {}),
+        attempt: entry.attempt,
+        due_at: entry.due_at,
+        error: entry.error,
+        last_event: entry.last_event,
+        last_message: entry.last_message,
+        started_at: entry.started_at,
+        last_event_at: entry.last_event_at
+    };
+}
+export function resolveRunningIssueRecord(entry, issueRecordLookups) {
+    if (entry.issue_id !== null) {
+        const issueById = issueRecordLookups.byId.get(entry.issue_id);
+        if (issueById) {
+            return issueById;
+        }
+    }
+    return issueRecordLookups.byIdentifier.get(entry.issue_identifier) ?? null;
+}
+export function resolveRetryIssueRecord(entry, issueRecordLookups) {
+    if (entry.run_id) {
+        const issueByRunId = issueRecordLookups.byRunId.get(entry.run_id);
+        if (issueByRunId) {
+            return issueByRunId;
+        }
+    }
+    if (entry.issue_id !== null) {
+        const issueById = issueRecordLookups.byId.get(entry.issue_id);
+        if (issueById) {
+            return issueById;
+        }
+    }
+    return issueRecordLookups.byIdentifier.get(entry.issue_identifier) ?? null;
+}
+function resolveCompatibilityAliases(input) {
+    const aliases = [
+        ...(input.issueRecord?.aliases ?? []),
+        input.issueIdentifier,
+        input.issueId,
+        input.taskId,
+        input.runId
+    ];
+    return Array.from(new Set(aliases.filter((alias) => typeof alias === 'string' && alias.length > 0)));
+}
+function normalizeRecentAgentActivity(issue, proof) {
+    if (issue.recent_events.length > 0) {
+        return issue.recent_events;
+    }
+    const event = issue.latest_event?.event ?? proof?.last_event ?? null;
+    const message = issue.latest_event?.message ?? proof?.last_message ?? null;
+    if (!event && !message) {
+        return [];
+    }
+    return [
+        {
+            at: issue.latest_event?.at ?? proof?.last_event_at ?? null,
+            event,
+            message
+        }
+    ];
+}
+function normalizeLinearActivity(recentActivity) {
+    return Array.isArray(recentActivity) ? recentActivity : [];
+}

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

@@ -0,0 +1,70 @@
+import { normalizeProviderLinearWorkflowState } from './providerLinearWorkflowStates.js';
+export const DEFAULT_PROVIDER_MAX_CONCURRENT_AGENTS = 10;
+export const DEFAULT_LOCAL_PROVIDER_MAX_CONCURRENT_AGENTS = 3;
+export function resolveProviderPollDispatchLimits(featureToggles, options = {}) {
+    const agentConfig = readProviderPollAgentConfig(featureToggles);
+    const explicitMaxConcurrentAgents = readPositiveIntegerValue(agentConfig, 'max_concurrent_agents', 'maxConcurrentAgents');
+    const maxConcurrentAgentsByState = readPositiveIntegerMap(agentConfig, 'max_concurrent_agents_by_state', 'maxConcurrentAgentsByState');
+    return {
+        maxConcurrentAgents: explicitMaxConcurrentAgents ??
+            (options.localWorkerOnly === true
+                ? DEFAULT_LOCAL_PROVIDER_MAX_CONCURRENT_AGENTS
+                : DEFAULT_PROVIDER_MAX_CONCURRENT_AGENTS),
+        maxConcurrentAgentsByState
+    };
+}
+function readProviderPollAgentConfig(featureToggles) {
+    const direct = readRecordValue(featureToggles, 'agent');
+    const nested = readRecordValue(readRecordValue(featureToggles, 'coordinator'), 'agent');
+    if (!direct && !nested) {
+        return null;
+    }
+    return {
+        ...(nested ?? {}),
+        ...(direct ?? {})
+    };
+}
+function readPositiveIntegerMap(record, ...keys) {
+    const value = readRecordValue(record, ...keys);
+    if (!value) {
+        return new Map();
+    }
+    const entries = new Map();
+    for (const [rawKey, rawValue] of Object.entries(value)) {
+        const normalizedKey = normalizeProviderLinearWorkflowState(rawKey);
+        const parsedValue = readPositiveIntegerValue({ value: rawValue }, 'value');
+        if (!normalizedKey || parsedValue === null) {
+            continue;
+        }
+        entries.set(normalizedKey, parsedValue);
+    }
+    return entries;
+}
+function readPositiveIntegerValue(record, ...keys) {
+    for (const key of keys) {
+        const value = record?.[key];
+        if (typeof value === 'number' && Number.isInteger(value) && value > 0) {
+            return value;
+        }
+        if (typeof value === 'string') {
+            const trimmed = value.trim();
+            if (!trimmed || !/^\d+$/.test(trimmed)) {
+                continue;
+            }
+            const parsed = Number.parseInt(trimmed, 10);
+            if (Number.isInteger(parsed) && parsed > 0) {
+                return parsed;
+            }
+        }
+    }
+    return null;
+}
+function readRecordValue(record, ...keys) {
+    for (const key of keys) {
+        const value = record?.[key];
+        if (value && typeof value === 'object' && !Array.isArray(value)) {
+            return value;
+        }
+    }
+    return null;
+}