@kbediako/codex-orchestrator 0.1.38 → 0.2.0

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

@@ -0,0 +1,516 @@
+import { execFile } from 'node:child_process';
+import { access } from 'node:fs/promises';
+import process from 'node:process';
+import { promisify } from 'node:util';
+import { getProviderLinearIssueContext } from './providerLinearWorkflowFacade.js';
+import { isoTimestamp } from '../utils/time.js';
+const execFileAsync = promisify(execFile);
+export const DEFAULT_PROVIDER_TERMINAL_CLEANUP_COMMENT_TEMPLATE = 'Closing because the Linear issue for branch {{branch}} entered a terminal state without merge.';
+const PROVIDER_TERMINAL_CLEANUP_COMMAND_TIMEOUT_MS = 5_000;
+const PROVIDER_TERMINAL_CLEANUP_TOTAL_BUDGET_MS = 15_000;
+const PROVIDER_TERMINAL_CLEANUP_MAX_ATTACHED_PRS = 20;
+export function resolveProviderTerminalCleanupConfig(value) {
+    const record = asRecord(value);
+    const terminalCleanup = asRecord(record?.terminal_cleanup ?? record?.terminalCleanup);
+    const enabled = readBoolean(terminalCleanup, 'enabled') ?? false;
+    const closeAttachedPr = asRecord(terminalCleanup?.close_attached_pr ?? terminalCleanup?.closeAttachedPr);
+    return {
+        enabled,
+        closeAttachedPr: {
+            enabled: readBoolean(closeAttachedPr, 'enabled') ?? enabled,
+            commentTemplate: readNonEmptyString(closeAttachedPr, 'comment_template', 'commentTemplate') ??
+                DEFAULT_PROVIDER_TERMINAL_CLEANUP_COMMENT_TEMPLATE
+        }
+    };
+}
+export async function runProviderTerminalCleanup(input, deps = {}) {
+    const attemptedAt = deps.now?.() ?? isoTimestamp();
+    const env = input.env ?? process.env;
+    const readIssueContext = deps.readIssueContext ?? getProviderLinearIssueContext;
+    const runCommand = deps.runCommand ?? runProviderTerminalCleanupCommand;
+    const issueIdentifier = normalizeOptionalString(input.issueIdentifier);
+    const nowMs = deps.nowMs ?? Date.now;
+    if (!input.config.enabled) {
+        return buildResult({
+            attemptedAt,
+            issueId: input.issueId,
+            issueIdentifier,
+            workspacePath: input.workspacePath,
+            status: 'disabled',
+            summary: 'Terminal cleanup hook is disabled.',
+            branch: null
+        });
+    }
+    if (!input.config.closeAttachedPr.enabled) {
+        return buildResult({
+            attemptedAt,
+            issueId: input.issueId,
+            issueIdentifier,
+            workspacePath: input.workspacePath,
+            status: 'disabled',
+            summary: 'Attached PR auto-close is disabled for terminal cleanup.',
+            branch: null
+        });
+    }
+    if (!(await workspaceExists(input.workspacePath))) {
+        return buildResult({
+            attemptedAt,
+            issueId: input.issueId,
+            issueIdentifier,
+            workspacePath: input.workspacePath,
+            status: 'noop',
+            summary: 'Workspace was already absent before terminal cleanup.',
+            branch: null
+        });
+    }
+    const branchResult = await runCommand({
+        command: 'git',
+        args: ['-C', input.workspacePath, 'branch', '--show-current'],
+        cwd: input.workspacePath
+    });
+    if (!branchResult.ok) {
+        return buildResult({
+            attemptedAt,
+            issueId: input.issueId,
+            issueIdentifier,
+            workspacePath: input.workspacePath,
+            status: 'failed',
+            summary: 'Terminal cleanup could not determine the workspace branch.',
+            error: formatCommandFailure('git', branchResult),
+            branch: null
+        });
+    }
+    const branch = normalizeOptionalString(branchResult.stdout);
+    const headResult = await runCommand({
+        command: 'git',
+        args: ['-C', input.workspacePath, 'rev-parse', 'HEAD'],
+        cwd: input.workspacePath
+    });
+    if (!headResult.ok) {
+        return buildResult({
+            attemptedAt,
+            issueId: input.issueId,
+            issueIdentifier,
+            workspacePath: input.workspacePath,
+            status: 'failed',
+            summary: branch === null
+                ? 'Terminal cleanup could not determine the detached workspace HEAD.'
+                : 'Terminal cleanup could not determine the workspace HEAD.',
+            error: formatCommandFailure('git', headResult),
+            branch
+        });
+    }
+    const workspaceHeadOid = normalizeOptionalString(headResult.stdout);
+    if (!workspaceHeadOid) {
+        if (!branch) {
+            return buildResult({
+                attemptedAt,
+                issueId: input.issueId,
+                issueIdentifier,
+                workspacePath: input.workspacePath,
+                status: 'noop',
+                summary: 'Workspace is detached or has no current branch; skipping attached PR cleanup.',
+                branch: null
+            });
+        }
+        return buildResult({
+            attemptedAt,
+            issueId: input.issueId,
+            issueIdentifier,
+            workspacePath: input.workspacePath,
+            status: 'failed',
+            summary: 'Terminal cleanup could not determine the workspace HEAD.',
+            branch
+        });
+    }
+    const workspaceTargetLabel = formatWorkspaceTargetLabel(branch, workspaceHeadOid);
+    const originUrlResult = await runCommand({
+        command: 'git',
+        args: ['-C', input.workspacePath, 'remote', 'get-url', 'origin'],
+        cwd: input.workspacePath
+    });
+    if (!originUrlResult.ok) {
+        return buildResult({
+            attemptedAt,
+            issueId: input.issueId,
+            issueIdentifier,
+            workspacePath: input.workspacePath,
+            status: 'failed',
+            summary: 'Terminal cleanup could not determine the workspace origin remote.',
+            error: formatCommandFailure('git', originUrlResult),
+            branch
+        });
+    }
+    const workspaceRepoKey = parseGitHubRepositoryUrl(originUrlResult.stdout);
+    if (!workspaceRepoKey) {
+        return buildResult({
+            attemptedAt,
+            issueId: input.issueId,
+            issueIdentifier,
+            workspacePath: input.workspacePath,
+            status: 'failed',
+            summary: 'Terminal cleanup could not determine the workspace GitHub repository.',
+            error: JSON.stringify(originUrlResult.stdout.trim()),
+            branch
+        });
+    }
+    const issueContext = await readIssueContext({
+        issueId: input.issueId,
+        env
+    });
+    if (!issueContext.ok) {
+        return buildResult({
+            attemptedAt,
+            issueId: input.issueId,
+            issueIdentifier,
+            workspacePath: input.workspacePath,
+            status: 'failed',
+            summary: `Terminal cleanup could not load Linear issue context for ${input.issueId}.`,
+            error: `${issueContext.error.code}: ${issueContext.error.message}`,
+            branch
+        });
+    }
+    const attachedPrUrls = collectAttachedGitHubPrUrls(issueContext.issue.attachments);
+    if (attachedPrUrls.length === 0) {
+        return buildResult({
+            attemptedAt,
+            issueId: input.issueId,
+            issueIdentifier,
+            workspacePath: input.workspacePath,
+            status: 'noop',
+            summary: `No attached GitHub PRs were present for ${workspaceTargetLabel}.`,
+            branch
+        });
+    }
+    const matchingOpenPrUrls = [];
+    const closedPrUrls = [];
+    const errors = [];
+    let resolvedBranch = branch;
+    const cleanupDeadlineMs = nowMs() + PROVIDER_TERMINAL_CLEANUP_TOTAL_BUDGET_MS;
+    const sameRepoAttachedPrUrls = attachedPrUrls.filter((attachedPrUrl) => parseGitHubPullRequestUrl(attachedPrUrl)?.repoKey === workspaceRepoKey);
+    const attachedPrUrlsToProcess = sameRepoAttachedPrUrls.slice(0, PROVIDER_TERMINAL_CLEANUP_MAX_ATTACHED_PRS);
+    if (sameRepoAttachedPrUrls.length > attachedPrUrlsToProcess.length) {
+        errors.push(`skipped ${sameRepoAttachedPrUrls.length - attachedPrUrlsToProcess.length} attached PR(s) beyond cleanup cap of ${PROVIDER_TERMINAL_CLEANUP_MAX_ATTACHED_PRS}`);
+    }
+    let processedAttachedPrCount = 0;
+    for (const attachedPrUrl of attachedPrUrlsToProcess) {
+        if (nowMs() >= cleanupDeadlineMs) {
+            errors.push(`cleanup budget exceeded after processing ${processedAttachedPrCount} attached PR(s)`);
+            break;
+        }
+        processedAttachedPrCount += 1;
+        const prView = await runCommand({
+            command: 'gh',
+            args: [
+                'pr',
+                'view',
+                attachedPrUrl,
+                '--json',
+                'state,headRefName,headRefOid,url,headRepository,headRepositoryOwner,isCrossRepository'
+            ],
+            cwd: input.workspacePath
+        });
+        if (!prView.ok) {
+            errors.push(`gh pr view ${attachedPrUrl}: ${formatCommandFailure('gh', prView)}`);
+            continue;
+        }
+        const prDetails = parsePrViewResponse(prView.stdout);
+        if (!prDetails) {
+            errors.push(`gh pr view ${attachedPrUrl}: invalid JSON response`);
+            continue;
+        }
+        const sameBaseRepository = prDetails.repoKey === workspaceRepoKey;
+        const sameHeadRepository = prDetails.headRepoKey === workspaceRepoKey;
+        const matchesBranch = branch !== null &&
+            prDetails.headRefName === branch &&
+            prDetails.headRefOid === workspaceHeadOid;
+        const matchesHead = branch === null &&
+            workspaceHeadOid !== null &&
+            prDetails.headRefOid !== null &&
+            prDetails.headRefOid === workspaceHeadOid;
+        if (prDetails.state !== 'OPEN' ||
+            !sameBaseRepository ||
+            !sameHeadRepository ||
+            (!matchesBranch && !matchesHead)) {
+            continue;
+        }
+        const closingBranch = prDetails.headRefName ??
+            branch ??
+            resolvedBranch ??
+            `HEAD ${shortOid(workspaceHeadOid)}`;
+        resolvedBranch ??= prDetails.headRefName;
+        matchingOpenPrUrls.push(prDetails.url ?? attachedPrUrl);
+        if (nowMs() >= cleanupDeadlineMs) {
+            errors.push(`cleanup budget exceeded before closing ${attachedPrUrl}`);
+            break;
+        }
+        const prClose = await runCommand({
+            command: 'gh',
+            args: [
+                'pr',
+                'close',
+                attachedPrUrl,
+                '--comment',
+                renderClosingComment(input.config.closeAttachedPr.commentTemplate, closingBranch)
+            ],
+            cwd: input.workspacePath
+        });
+        if (!prClose.ok) {
+            errors.push(`gh pr close ${attachedPrUrl}: ${formatCommandFailure('gh', prClose)}`);
+            continue;
+        }
+        closedPrUrls.push(prDetails.url ?? attachedPrUrl);
+    }
+    if (errors.length > 0) {
+        return buildResult({
+            attemptedAt,
+            issueId: input.issueId,
+            issueIdentifier,
+            workspacePath: input.workspacePath,
+            status: 'failed',
+            summary: matchingOpenPrUrls.length === 0
+                ? `Terminal cleanup encountered ${errors.length} attached PR error(s) for ${workspaceTargetLabel}.`
+                : `Terminal cleanup closed ${closedPrUrls.length} of ${matchingOpenPrUrls.length} matching attached PR(s) for ${formatWorkspaceTargetLabel(resolvedBranch, workspaceHeadOid)} and encountered ${errors.length} error(s).`,
+            error: errors.join(' | '),
+            branch: resolvedBranch,
+            attachedPrUrls,
+            matchingOpenPrUrls,
+            closedPrUrls
+        });
+    }
+    if (matchingOpenPrUrls.length === 0) {
+        return buildResult({
+            attemptedAt,
+            issueId: input.issueId,
+            issueIdentifier,
+            workspacePath: input.workspacePath,
+            status: 'noop',
+            summary: `No attached open PR matched ${workspaceTargetLabel}.`,
+            branch: resolvedBranch,
+            attachedPrUrls
+        });
+    }
+    return buildResult({
+        attemptedAt,
+        issueId: input.issueId,
+        issueIdentifier,
+        workspacePath: input.workspacePath,
+        status: 'succeeded',
+        summary: `Closed ${closedPrUrls.length} attached PR(s) for ${formatWorkspaceTargetLabel(resolvedBranch, workspaceHeadOid)}.`,
+        branch: resolvedBranch,
+        attachedPrUrls,
+        matchingOpenPrUrls,
+        closedPrUrls
+    });
+}
+async function runProviderTerminalCleanupCommand(input) {
+    try {
+        const { stdout, stderr } = await execFileAsync(input.command, input.args, {
+            cwd: input.cwd,
+            timeout: PROVIDER_TERMINAL_CLEANUP_COMMAND_TIMEOUT_MS
+        });
+        return {
+            ok: true,
+            exitCode: 0,
+            stdout,
+            stderr
+        };
+    }
+    catch (error) {
+        const execError = error;
+        const timedOut = execError.killed === true && execError.signal === 'SIGTERM';
+        return {
+            ok: false,
+            exitCode: typeof execError.code === 'number' && Number.isInteger(execError.code)
+                ? execError.code
+                : null,
+            stdout: typeof execError.stdout === 'string' ? execError.stdout : '',
+            stderr: typeof execError.stderr === 'string' && execError.stderr.length > 0
+                ? execError.stderr
+                : timedOut
+                    ? `command timed out after ${PROVIDER_TERMINAL_CLEANUP_COMMAND_TIMEOUT_MS}ms`
+                    : (execError.message ?? ''),
+        };
+    }
+}
+function buildResult(input) {
+    return {
+        attemptedAt: input.attemptedAt,
+        status: input.status,
+        summary: input.summary,
+        error: input.error ?? null,
+        issueId: input.issueId,
+        issueIdentifier: input.issueIdentifier,
+        workspacePath: input.workspacePath,
+        branch: input.branch,
+        attachedPrUrls: [...(input.attachedPrUrls ?? [])],
+        matchingOpenPrUrls: [...(input.matchingOpenPrUrls ?? [])],
+        closedPrUrls: [...(input.closedPrUrls ?? [])]
+    };
+}
+function collectAttachedGitHubPrUrls(attachments) {
+    const seen = new Set();
+    const urls = [];
+    for (const attachment of attachments) {
+        const parsed = parseGitHubPullRequestUrl(attachment.url);
+        if (!parsed || seen.has(parsed.canonicalUrl)) {
+            continue;
+        }
+        seen.add(parsed.canonicalUrl);
+        urls.push(parsed.canonicalUrl);
+    }
+    return urls;
+}
+function parsePrViewResponse(value) {
+    try {
+        const parsed = JSON.parse(value);
+        const parsedUrl = parseGitHubPullRequestUrl(typeof parsed.url === 'string' ? parsed.url : null);
+        const headRepository = asRecord(parsed.headRepository);
+        const headRepositoryOwner = asRecord(parsed.headRepositoryOwner);
+        const headRepositoryName = normalizeOptionalString(headRepository?.name);
+        const headRepositoryOwnerLogin = normalizeOptionalString(headRepositoryOwner?.login);
+        const isCrossRepository = typeof parsed.isCrossRepository === 'boolean' ? parsed.isCrossRepository : null;
+        const headRepoKey = headRepositoryName && headRepositoryOwnerLogin
+            ? `${headRepositoryOwnerLogin.toLowerCase()}/${headRepositoryName.toLowerCase()}`
+            : isCrossRepository === false
+                ? parsedUrl?.repoKey ?? null
+                : null;
+        return {
+            state: normalizeOptionalString(typeof parsed.state === 'string' ? parsed.state : null)?.toUpperCase() ?? null,
+            headRefName: normalizeOptionalString(typeof parsed.headRefName === 'string' ? parsed.headRefName : null),
+            headRefOid: normalizeOptionalString(typeof parsed.headRefOid === 'string' ? parsed.headRefOid : null),
+            url: parsedUrl?.canonicalUrl ?? null,
+            repoKey: parsedUrl?.repoKey ?? null,
+            headRepoKey
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function renderClosingComment(template, branch) {
+    return template.replaceAll('{{branch}}', branch);
+}
+function formatCommandFailure(command, result) {
+    const parts = [`${command} exited ${result.exitCode ?? 'unknown'}`];
+    const stderr = result.stderr.trim();
+    const stdout = result.stdout.trim();
+    if (stderr) {
+        parts.push(`stderr=${JSON.stringify(stderr)}`);
+    }
+    else if (stdout) {
+        parts.push(`stdout=${JSON.stringify(stdout)}`);
+    }
+    return parts.join(' ');
+}
+async function workspaceExists(workspacePath) {
+    try {
+        await access(workspacePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function formatWorkspaceTargetLabel(branch, headOid) {
+    if (branch) {
+        return `branch ${branch}`;
+    }
+    if (headOid) {
+        return `detached HEAD ${shortOid(headOid)}`;
+    }
+    return 'the workspace target';
+}
+function shortOid(value) {
+    const normalized = normalizeOptionalString(value);
+    return normalized ? normalized.slice(0, 12) : 'unknown';
+}
+function parseGitHubPullRequestUrl(value) {
+    const normalized = normalizeOptionalString(value);
+    if (!normalized) {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = new URL(normalized);
+    }
+    catch {
+        return null;
+    }
+    const hostname = parsed.hostname.toLowerCase();
+    if (hostname !== 'github.com' && hostname !== 'www.github.com') {
+        return null;
+    }
+    const segments = parsed.pathname.split('/').filter(Boolean);
+    const owner = normalizeOptionalString(segments[0] ?? null);
+    const repo = normalizeOptionalString(segments[1] ?? null);
+    const resource = normalizeOptionalString(segments[2] ?? null)?.toLowerCase() ?? null;
+    const pullNumber = normalizePullRequestNumber(segments[3] ?? null);
+    if (!owner || !repo || resource !== 'pull' || !pullNumber) {
+        return null;
+    }
+    return {
+        canonicalUrl: `https://github.com/${owner}/${repo}/pull/${pullNumber}`,
+        repoKey: `${owner.toLowerCase()}/${repo.toLowerCase()}`
+    };
+}
+function parseGitHubRepositoryUrl(value) {
+    const normalized = normalizeOptionalString(value);
+    if (!normalized) {
+        return null;
+    }
+    const scpMatch = normalized.match(/^git@github\.com:([^/]+)\/([^/]+?)(?:\.git)?$/);
+    if (scpMatch) {
+        return `${scpMatch[1].toLowerCase()}/${scpMatch[2].toLowerCase()}`;
+    }
+    let parsed;
+    try {
+        parsed = new URL(normalized);
+    }
+    catch {
+        return null;
+    }
+    const hostname = parsed.hostname.toLowerCase();
+    if (hostname !== 'github.com' && hostname !== 'www.github.com') {
+        return null;
+    }
+    const segments = parsed.pathname.split('/').filter(Boolean);
+    const owner = normalizeOptionalString(segments[0] ?? null);
+    const repo = normalizeOptionalString((segments[1] ?? '').replace(/\.git$/iu, ''));
+    if (!owner || !repo || segments.length !== 2) {
+        return null;
+    }
+    return `${owner.toLowerCase()}/${repo.toLowerCase()}`;
+}
+function normalizePullRequestNumber(value) {
+    const normalized = normalizeOptionalString(value);
+    if (!normalized || !/^\d+$/u.test(normalized)) {
+        return null;
+    }
+    return String(Number.parseInt(normalized, 10));
+}
+function asRecord(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return null;
+    }
+    return value;
+}
+function readBoolean(record, key) {
+    const value = record?.[key];
+    if (typeof value === 'boolean') {
+        return value;
+    }
+    return null;
+}
+function readNonEmptyString(record, ...keys) {
+    for (const key of keys) {
+        const value = normalizeOptionalString(record?.[key]);
+        if (value) {
+            return value;
+        }
+    }
+    return null;
+}
+function normalizeOptionalString(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;
+}

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

@@ -0,0 +1,191 @@
+export const PROVIDER_WORKER_HOST_ENV_KEY = 'CODEX_ORCHESTRATOR_PROVIDER_WORKER_HOST';
+const DEFAULT_PROVIDER_WORKER_HOST_MAX_CONCURRENT_AGENTS = 1;
+const ACTIVE_PROVIDER_WORKER_HOST_CLAIM_STATES = new Set(['starting', 'running', 'resuming']);
+export function resolveProviderWorkerHostConfig(metadata) {
+    const record = asRecord(metadata);
+    const workerHostsRecord = asRecord(record?.worker_hosts ?? record?.workerHosts);
+    if (workerHostsRecord && workerHostsRecord.hosts !== undefined && !Array.isArray(workerHostsRecord.hosts)) {
+        throw new Error('provider worker hosts metadata "hosts" must be an array.');
+    }
+    const hostEntries = Array.isArray(workerHostsRecord?.hosts)
+        ? workerHostsRecord.hosts
+        : Array.isArray(record?.worker_hosts)
+            ? record.worker_hosts
+            : Array.isArray(record?.workerHosts)
+                ? record.workerHosts
+                : [];
+    if (hostEntries.length === 0) {
+        return [];
+    }
+    const names = new Set();
+    return hostEntries.map((entry, index) => {
+        const host = asRecord(entry);
+        if (!host) {
+            throw new Error(`provider worker host entry #${index + 1} must be an object.`);
+        }
+        const name = readRequiredString(host, 'name', `provider worker host entry #${index + 1}`);
+        if (names.has(name)) {
+            throw new Error(`provider worker host "${name}" is duplicated.`);
+        }
+        names.add(name);
+        const transport = readOptionalString(host, 'transport') ?? 'ssh';
+        if (transport !== 'ssh') {
+            throw new Error(`provider worker host "${name}" transport must be "ssh" for the current distributed worker-host lane.`);
+        }
+        const sshDestination = readRequiredString(host, 'ssh_destination', `provider worker host "${name}"`);
+        return {
+            name,
+            transport: 'ssh',
+            ssh_destination: sshDestination,
+            ssh_options: readStringArray(host, 'ssh_options'),
+            max_concurrent_agents: readOptionalPositiveInteger(host, 'max_concurrent_agents', `provider worker host "${name}"`) ??
+                DEFAULT_PROVIDER_WORKER_HOST_MAX_CONCURRENT_AGENTS,
+            node_path: readOptionalString(host, 'node_path')
+        };
+    });
+}
+export function cloneProviderWorkerHostConfigs(hosts) {
+    return Array.isArray(hosts)
+        ? hosts.map((host) => ({
+            ...host,
+            ssh_options: [...host.ssh_options]
+        }))
+        : [];
+}
+export function normalizeProviderWorkerHostName(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;
+}
+export function findProviderWorkerHost(hosts, name) {
+    const normalizedName = normalizeProviderWorkerHostName(name);
+    if (!normalizedName || !Array.isArray(hosts)) {
+        return null;
+    }
+    return hosts.find((host) => host.name === normalizedName) ?? null;
+}
+export function selectProviderWorkerHost(input) {
+    const hosts = cloneProviderWorkerHostConfigs(input.hosts);
+    const occupancy = buildProviderWorkerHostOccupancy({
+        claims: input.claims,
+        currentProviderKey: input.currentProviderKey
+    });
+    if (hosts.length === 0) {
+        return {
+            kind: 'local',
+            host: null,
+            occupancy
+        };
+    }
+    const preferred = findProviderWorkerHost(hosts, input.preferredHost);
+    if (preferred && hasProviderWorkerHostCapacity(preferred, occupancy)) {
+        return {
+            kind: 'remote',
+            host: preferred,
+            occupancy
+        };
+    }
+    const selected = [...hosts]
+        .map((host, index) => ({
+        host,
+        index,
+        used: occupancy.get(host.name) ?? 0,
+        remaining: host.max_concurrent_agents - (occupancy.get(host.name) ?? 0)
+    }))
+        .filter((entry) => entry.remaining > 0)
+        .sort((left, right) => {
+        if (right.remaining !== left.remaining) {
+            return right.remaining - left.remaining;
+        }
+        if (left.used !== right.used) {
+            return left.used - right.used;
+        }
+        return left.index - right.index;
+    })[0]?.host ?? null;
+    if (!selected) {
+        return {
+            kind: 'exhausted',
+            host: null,
+            occupancy
+        };
+    }
+    return {
+        kind: 'remote',
+        host: selected,
+        occupancy
+    };
+}
+function buildProviderWorkerHostOccupancy(input) {
+    const occupancy = new Map();
+    if (!Array.isArray(input.claims)) {
+        return occupancy;
+    }
+    for (const claim of input.claims) {
+        if (claim.provider_key && input.currentProviderKey && claim.provider_key === input.currentProviderKey) {
+            continue;
+        }
+        if (!ACTIVE_PROVIDER_WORKER_HOST_CLAIM_STATES.has(normalizeClaimState(claim.state))) {
+            continue;
+        }
+        const workerHost = normalizeProviderWorkerHostName(claim.worker_host);
+        if (!workerHost) {
+            continue;
+        }
+        occupancy.set(workerHost, (occupancy.get(workerHost) ?? 0) + 1);
+    }
+    return occupancy;
+}
+function hasProviderWorkerHostCapacity(host, occupancy) {
+    return (occupancy.get(host.name) ?? 0) < host.max_concurrent_agents;
+}
+function normalizeClaimState(value) {
+    return typeof value === 'string' ? value : '';
+}
+function asRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+function readOptionalString(record, key) {
+    const value = record[key];
+    return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;
+}
+function readRequiredString(record, key, source) {
+    const value = readOptionalString(record, key);
+    if (!value) {
+        throw new Error(`${source} requires a non-empty ${key}.`);
+    }
+    return value;
+}
+function readStringArray(record, key) {
+    const value = record[key];
+    if (value === undefined || value === null) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new Error(`${key} must be an array of strings.`);
+    }
+    return value.map((entry, index) => {
+        if (typeof entry !== 'string' || entry.trim().length === 0) {
+            throw new Error(`${key}[${index}] must be a non-empty string.`);
+        }
+        return entry;
+    });
+}
+function readPositiveInteger(record, key, source) {
+    const value = record[key];
+    if (typeof value === 'number' && Number.isInteger(value) && value > 0) {
+        return value;
+    }
+    if (typeof value === 'string' && /^\d+$/u.test(value.trim())) {
+        const parsed = Number.parseInt(value.trim(), 10);
+        if (parsed > 0) {
+            return parsed;
+        }
+    }
+    throw new Error(`${source} requires ${key} to be a positive integer.`);
+}
+function readOptionalPositiveInteger(record, key, source) {
+    if (record[key] === undefined || record[key] === null) {
+        return null;
+    }
+    return readPositiveInteger(record, key, source);
+}