@elizaos/agent 0.25.8 → 2.0.0-alpha.144

package/packages/typescript/src/features/orchestrator/services/task-agent-frameworks.js

@@ -0,0 +1,738 @@
+/**
+ * Task-agent framework discovery and preference resolution.
+ *
+ * Detects installed CLIs, available auth, and Eliza subscription preferences so
+ * the orchestrator can choose the best framework when the caller does not
+ * specify one explicitly.
+ *
+ * @module services/task-agent-frameworks
+ */
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { readConfigCloudKey, readConfigEnvKey } from "./config-env.js";
+const RESEARCH_SIGNAL_RE = /\b(research|investigate|analy[sz]e|analysis|compare|evaluate|review|study|summari[sz]e|deep research|look into|explore)\b/i;
+const PLANNING_SIGNAL_RE = /\b(plan|planning|roadmap|strategy|spec|architecture|design|scope|milestone|sequence|timeline)\b/i;
+const OPS_SIGNAL_RE = /\b(deploy|release|ship|rollback|monitor|incident|infra|infrastructure|configure|setup|docker|kubernetes|ci|cd|runbook)\b/i;
+const IMPLEMENTATION_SIGNAL_RE = /\b(code|coding|implement|fix|debug|refactor|write|build|patch|feature|server|api|component|function|typescrip?t|javascript|react)\b/i;
+const VERIFICATION_SIGNAL_RE = /\b(test|tests|verify|validation|prove|acceptance|check|regression|benchmark|lint|typecheck|qa)\b/i;
+const COORDINATION_SIGNAL_RE = /\b(parallel|delegate|subagent|sub-agent|swarm|coordinate|coordination|handoff|mailbox|scheduler|orchestrate)\b/i;
+const REPO_SIGNAL_RE = /\b(repo|repository|branch|commit|pull request|pr|diff|workspace|file|directory|codebase)\b/i;
+const FAST_ITERATION_SIGNAL_RE = /\b(fix|debug|patch|flaky|quick|fast|iterate|loop|unblock|repair)\b/i;
+const FRAMEWORK_CAPABILITY_PROFILES = {
+    claude: {
+        implementation: 0.95,
+        research: 0.95,
+        planning: 1,
+        ops: 0.8,
+        verification: 0.85,
+        coordination: 1,
+        repoWork: 0.9,
+        fastIteration: 0.75,
+    },
+    codex: {
+        implementation: 1,
+        research: 0.8,
+        planning: 0.75,
+        ops: 0.85,
+        verification: 1,
+        coordination: 0.9,
+        repoWork: 1,
+        fastIteration: 0.95,
+    },
+    gemini: {
+        implementation: 0.7,
+        research: 1,
+        planning: 0.95,
+        ops: 0.7,
+        verification: 0.6,
+        coordination: 0.7,
+        repoWork: 0.65,
+        fastIteration: 0.7,
+    },
+    aider: {
+        implementation: 0.9,
+        research: 0.45,
+        planning: 0.45,
+        ops: 0.75,
+        verification: 0.85,
+        coordination: 0.35,
+        repoWork: 0.95,
+        fastIteration: 1,
+    },
+    pi: {
+        implementation: 0.55,
+        research: 0.5,
+        planning: 0.55,
+        ops: 0.5,
+        verification: 0.5,
+        coordination: 0.35,
+        repoWork: 0.5,
+        fastIteration: 0.5,
+    },
+};
+const FRAMEWORK_LABELS = {
+    claude: "Claude Code",
+    codex: "Codex",
+    gemini: "Gemini CLI",
+    aider: "Aider",
+    pi: "Pi",
+};
+const STANDARD_FRAMEWORKS = [
+    "claude",
+    "codex",
+    "gemini",
+    "aider",
+];
+const TASK_AGENT_COMPLEXITY_RE = /\b(repo|repository|code|coding|debug|fix|implement|investigate|research|analyze|analysis|summarize|summary|write|draft|document|plan|workflow|automation|parallel|delegate|subtask|agent|orchestrate|coordinate|compare|test|tests|pull request|pr\b|branch|commit)\b/i;
+let frameworkStateCache;
+const frameworkCooldowns = new Map();
+const TASK_AGENT_USAGE_EXHAUSTED_RE = /\b(insufficient(?:[_\s]+(?:credits?|quota))|insufficient_quota|out of credits|credit balance|usage (?:has )?(?:reached|exceeded)|(?:you(?:'ve| have)? hit your usage limits?)|usage[-\s]?limits?|quota exceeded|payment required|status(?:code)?[:\s]*402)\b/i;
+function normalizePreflightAdapterId(value) {
+    const normalized = value?.trim().toLowerCase();
+    switch (normalized) {
+        case "claude":
+        case "claude code":
+            return "claude";
+        case "codex":
+        case "openai codex":
+            return "codex";
+        case "gemini":
+        case "gemini cli":
+            return "gemini";
+        case "aider":
+            return "aider";
+        default:
+            return null;
+    }
+}
+function safeGetSetting(runtime, key) {
+    // Check the config file first (UI writes here, takes effect without restart),
+    // then fall back to runtime/character settings.
+    try {
+        const fromConfig = readConfigEnvKey(key);
+        if (fromConfig?.trim())
+            return fromConfig.trim();
+    }
+    catch {
+        // ignore — fall through to runtime
+    }
+    if (!runtime)
+        return undefined;
+    try {
+        const value = runtime.getSetting(key);
+        return typeof value === "string" && value.trim() ? value.trim() : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function getPreflightAuthStatus(result) {
+    const auth = result && typeof result === "object"
+        ? result.auth
+        : undefined;
+    const status = typeof auth?.status === "string" ? auth.status : "";
+    if (status === "authenticated" || status === "unauthenticated") {
+        return status;
+    }
+    return "unknown";
+}
+function getUserHomeDir() {
+    return (process.env.HOME?.trim() || process.env.USERPROFILE?.trim() || os.homedir());
+}
+function readJsonFile(filePath) {
+    try {
+        return JSON.parse(fs.readFileSync(filePath, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function extractOauthAccessToken(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return;
+    const record = value;
+    const direct = record.accessToken ?? record.access_token;
+    if (typeof direct === "string" && direct.trim()) {
+        return direct.trim();
+    }
+    for (const nested of Object.values(record)) {
+        const token = extractOauthAccessToken(nested);
+        if (token)
+            return token;
+    }
+    return;
+}
+function resolveElizaConfigPath() {
+    const explicit = process.env.ELIZA_CONFIG_PATH?.trim() ||
+        process.env.ELIZA_CONFIG_PATH?.trim();
+    if (explicit)
+        return explicit;
+    const stateDir = process.env.ELIZA_STATE_DIR?.trim() ||
+        process.env.ELIZA_STATE_DIR?.trim() ||
+        path.join(getUserHomeDir(), ".eliza");
+    const namespace = process.env.ELIZA_NAMESPACE?.trim();
+    const filename = !namespace || namespace === "eliza" ? "eliza.json" : `${namespace}.json`;
+    return path.join(stateDir, filename);
+}
+function readConfiguredSubscriptionProvider() {
+    const config = readJsonFile(resolveElizaConfigPath());
+    if (!config || typeof config !== "object" || Array.isArray(config))
+        return;
+    const agents = config.agents;
+    if (!agents || typeof agents !== "object" || Array.isArray(agents))
+        return;
+    const defaults = agents.defaults;
+    if (!defaults || typeof defaults !== "object" || Array.isArray(defaults))
+        return;
+    const provider = defaults.subscriptionProvider;
+    return typeof provider === "string" && provider.trim()
+        ? provider.trim()
+        : undefined;
+}
+function hasClaudeSubscriptionAuth() {
+    const credentialsPath = path.join(getUserHomeDir(), ".claude", ".credentials.json");
+    const fileToken = extractOauthAccessToken(readJsonFile(credentialsPath));
+    if (fileToken)
+        return true;
+    if (process.platform !== "darwin")
+        return false;
+    try {
+        const raw = execFileSync("security", ["find-generic-password", "-s", "Claude Code-credentials", "-w"], { encoding: "utf8", timeout: 3000, stdio: ["ignore", "pipe", "ignore"] }).trim();
+        if (!raw)
+            return false;
+        return Boolean(extractOauthAccessToken(JSON.parse(raw)));
+    }
+    catch {
+        return false;
+    }
+}
+function hasClaudeApiKey(runtime) {
+    return Boolean(process.env.ANTHROPIC_API_KEY?.trim() ||
+        safeGetSetting(runtime, "ANTHROPIC_API_KEY"));
+}
+function hasCodexSubscriptionAuth() {
+    const authPath = path.join(getUserHomeDir(), ".codex", "auth.json");
+    const auth = readJsonFile(authPath);
+    if (!auth || typeof auth !== "object" || Array.isArray(auth))
+        return false;
+    const key = auth.OPENAI_API_KEY;
+    return typeof key === "string" && key.trim().length > 0;
+}
+function hasCodexApiKey(runtime) {
+    return Boolean(process.env.OPENAI_API_KEY?.trim() ||
+        safeGetSetting(runtime, "OPENAI_API_KEY"));
+}
+function hasGeminiCredential(runtime) {
+    return Boolean(process.env.GOOGLE_GENERATIVE_AI_API_KEY?.trim() ||
+        process.env.GOOGLE_API_KEY?.trim() ||
+        safeGetSetting(runtime, "GOOGLE_GENERATIVE_AI_API_KEY") ||
+        safeGetSetting(runtime, "GOOGLE_API_KEY"));
+}
+/**
+ * Check whether eliza has a paired Eliza Cloud API key. Used to mark
+ * Anthropic/OpenAI-backed task agents as auth-ready when LLM provider is
+ * "cloud" — they'll route through the cloud proxy at spawn time.
+ */
+function hasElizaCloudApiKey() {
+    return Boolean(readConfigCloudKey("apiKey"));
+}
+function hasPiBinary() {
+    return hasBinaryOnPath("pi");
+}
+function hasBinaryOnPath(binaryName) {
+    const command = process.platform === "win32" ? "where" : "which";
+    const args = [binaryName];
+    try {
+        execFileSync(command, args, {
+            encoding: "utf8",
+            timeout: 1500,
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function hasFrameworkBinary(id) {
+    switch (id) {
+        case "claude":
+            return hasBinaryOnPath("claude");
+        case "codex":
+            return hasBinaryOnPath("codex");
+        case "gemini":
+            return hasBinaryOnPath("gemini");
+        case "aider":
+            return hasBinaryOnPath("aider");
+    }
+}
+function getFrameworkCooldown(id) {
+    const cooldown = frameworkCooldowns.get(id);
+    if (!cooldown)
+        return undefined;
+    if (cooldown.until <= Date.now()) {
+        frameworkCooldowns.delete(id);
+        return undefined;
+    }
+    return cooldown;
+}
+async function computeTaskAgentFrameworkState(runtime, probe, profileInput) {
+    const configuredSubscriptionProvider = readConfiguredSubscriptionProvider();
+    const preflightByAdapter = new Map();
+    if (probe?.checkAvailableAgents) {
+        try {
+            const results = await probe.checkAvailableAgents(STANDARD_FRAMEWORKS);
+            // checkAdapters returns `adapter` as the human-readable display name
+            // (e.g. "Claude Code", "OpenAI Codex"), not the lowercase ID. Map back
+            // to the canonical framework ID via case-insensitive substring match.
+            for (const result of results) {
+                const adapterId = normalizePreflightAdapterId(result.adapter);
+                if (adapterId) {
+                    preflightByAdapter.set(adapterId, result);
+                }
+            }
+        }
+        catch {
+            // Keep status surfaces alive even if preflight fails transiently.
+        }
+    }
+    // When the user has selected Eliza Cloud as the LLM provider and has a
+    // paired cloud.apiKey, treat Claude/Codex/Aider as fully auth-ready —
+    // they'll route through the cloud proxy at spawn time.
+    const llmProvider = readConfigEnvKey("PARALLAX_LLM_PROVIDER") || "subscription";
+    const cloudReady = llmProvider === "cloud" && hasElizaCloudApiKey();
+    const claudePreflightAuth = getPreflightAuthStatus(preflightByAdapter.get("claude"));
+    const codexPreflightAuth = getPreflightAuthStatus(preflightByAdapter.get("codex"));
+    const geminiPreflightAuth = getPreflightAuthStatus(preflightByAdapter.get("gemini"));
+    const aiderPreflightAuth = getPreflightAuthStatus(preflightByAdapter.get("aider"));
+    const claudeSubscriptionReady = claudePreflightAuth === "authenticated" || hasClaudeSubscriptionAuth();
+    const claudeAuthReady = cloudReady || claudeSubscriptionReady || hasClaudeApiKey(runtime);
+    const codexSubscriptionReady = codexPreflightAuth === "authenticated" || hasCodexSubscriptionAuth();
+    const codexAuthReady = cloudReady || codexSubscriptionReady || hasCodexApiKey(runtime);
+    // Eliza Cloud doesn't proxy Gemini, so cloud mode does NOT make Gemini auth-ready
+    const geminiAuthReady = geminiPreflightAuth === "authenticated" || hasGeminiCredential(runtime);
+    const aiderAuthReady = cloudReady ||
+        aiderPreflightAuth === "authenticated" ||
+        claudeAuthReady ||
+        codexAuthReady ||
+        geminiAuthReady;
+    const piReady = hasPiBinary();
+    const providerPrefersClaude = configuredSubscriptionProvider === "anthropic-subscription";
+    const providerPrefersCodex = configuredSubscriptionProvider === "openai-codex" ||
+        configuredSubscriptionProvider === "openai-subscription";
+    const inventory = STANDARD_FRAMEWORKS.map((id) => {
+        const preflight = preflightByAdapter.get(id);
+        const cooldown = getFrameworkCooldown(id);
+        const installed = preflight?.installed === true || hasFrameworkBinary(id);
+        const subscriptionReady = id === "claude"
+            ? claudeSubscriptionReady
+            : id === "codex"
+                ? codexSubscriptionReady
+                : false;
+        const authReady = id === "claude"
+            ? claudeAuthReady
+            : id === "codex"
+                ? codexAuthReady
+                : id === "gemini"
+                    ? geminiAuthReady
+                    : aiderAuthReady;
+        const reason = id === "claude" && subscriptionReady
+            ? "ready to use the user's Claude subscription"
+            : id === "codex" && subscriptionReady
+                ? "ready to use the user's OpenAI subscription"
+                : installed
+                    ? authReady
+                        ? "installed with credentials available"
+                        : "installed but credentials were not detected"
+                    : "CLI not detected";
+        return {
+            id,
+            label: FRAMEWORK_LABELS[id],
+            installed,
+            authReady,
+            subscriptionReady,
+            temporarilyDisabled: Boolean(cooldown),
+            temporarilyDisabledUntil: cooldown?.until,
+            temporarilyDisabledReason: cooldown?.reason,
+            recommended: false,
+            reason: cooldown
+                ? `${reason}; temporarily disabled after a provider failure: ${cooldown.reason}`
+                : reason,
+            installCommand: preflight?.installCommand,
+            docsUrl: preflight?.docsUrl,
+        };
+    });
+    inventory.push({
+        id: "pi",
+        label: FRAMEWORK_LABELS.pi,
+        installed: piReady,
+        authReady: piReady,
+        subscriptionReady: false,
+        temporarilyDisabled: false,
+        recommended: false,
+        reason: piReady ? "CLI detected" : "CLI not detected",
+    });
+    const frameworks = inventory.map((framework) => ({
+        ...framework,
+        recommended: false,
+    }));
+    const metrics = probe?.getAgentMetrics?.() ?? {};
+    const profile = buildTaskAgentTaskProfile(profileInput);
+    const explicitDefault = safeGetSetting(runtime, "PARALLAX_DEFAULT_AGENT_TYPE")
+        ?.toLowerCase()
+        .trim();
+    const selectable = frameworks.filter((framework) => framework.installed && !framework.temporarilyDisabled);
+    const candidates = selectable.length > 0
+        ? selectable
+        : frameworks.filter((framework) => framework.installed);
+    const scoredCandidates = candidates.map((framework) => {
+        const explicitOverride = explicitDefault === framework.id
+            ? framework.installed && !framework.temporarilyDisabled
+                ? 40
+                : 0
+            : 0;
+        const providerPreference = providerPrefersClaude && framework.id === "claude"
+            ? framework.subscriptionReady
+                ? 18
+                : 6
+            : providerPrefersCodex && framework.id === "codex"
+                ? framework.subscriptionReady
+                    ? 18
+                    : 6
+                : 0;
+        const availabilityScore = (framework.installed ? 40 : -100) +
+            (framework.authReady ? 18 : -25) +
+            (framework.subscriptionReady ? 8 : 0) +
+            (framework.temporarilyDisabled ? -80 : 0);
+        const profileScore = computeProfileFitScore(framework.id, profile);
+        const metricsScore = computeMetricsScore(metrics[framework.id], profile.signals.fastIteration);
+        const selectionSignals = {
+            availability: availabilityScore,
+            profile: profileScore,
+            provider: providerPreference,
+            metrics: metricsScore,
+            explicitOverride,
+        };
+        return {
+            framework,
+            score: Object.values(selectionSignals).reduce((sum, value) => sum + value, 0),
+            selectionSignals,
+        };
+    });
+    const fallback = candidates[0] ??
+        frameworks.find((framework) => framework.installed) ??
+        frameworks[0];
+    const preferredCandidate = scoredCandidates.sort((left, right) => {
+        if (right.score !== left.score) {
+            return right.score - left.score;
+        }
+        return left.framework.id.localeCompare(right.framework.id);
+    })[0]?.framework ?? fallback;
+    const preferredSignals = scoredCandidates.find((entry) => entry.framework.id === preferredCandidate.id)?.selectionSignals ?? {};
+    const preferred = {
+        id: preferredCandidate.id,
+        reason: buildPreferredReason(preferredCandidate, profile, preferredSignals, explicitDefault, configuredSubscriptionProvider),
+    };
+    for (const framework of frameworks) {
+        framework.recommended = framework.id === preferred.id;
+        const scored = scoredCandidates.find((entry) => entry.framework.id === framework.id);
+        if (scored) {
+            framework.selectionScore = scored.score;
+            framework.selectionSignals = scored.selectionSignals;
+        }
+    }
+    return {
+        configuredSubscriptionProvider,
+        frameworks,
+        preferred,
+    };
+}
+export async function getTaskAgentFrameworkState(runtime, probe, profileInput) {
+    if (frameworkStateCache && frameworkStateCache.expiresAt > Date.now()) {
+        return computeTaskAgentFrameworkStateFromInventory(runtime, frameworkStateCache.value, probe, profileInput);
+    }
+    const value = await computeTaskAgentFrameworkState(runtime, probe, profileInput);
+    if (!profileInput) {
+        frameworkStateCache = {
+            expiresAt: Date.now() + 15_000,
+            value: {
+                configuredSubscriptionProvider: value.configuredSubscriptionProvider,
+                frameworks: value.frameworks.map((framework) => ({
+                    ...framework,
+                    recommended: false,
+                    selectionScore: undefined,
+                    selectionSignals: undefined,
+                })),
+            },
+        };
+    }
+    return value;
+}
+function computeTaskAgentFrameworkStateFromInventory(runtime, inventory, probe, profileInput) {
+    const clonedProbe = {
+        ...probe,
+        checkAvailableAgents: undefined,
+    };
+    frameworkStateCache = {
+        expiresAt: Date.now() + 15_000,
+        value: inventory,
+    };
+    return {
+        ...computeTaskAgentFrameworkStateFromCachedInventory(runtime, inventory, clonedProbe, profileInput),
+    };
+}
+function computeTaskAgentFrameworkStateFromCachedInventory(runtime, inventory, probe, profileInput) {
+    const metrics = probe?.getAgentMetrics?.() ?? {};
+    const frameworks = inventory.frameworks.map((framework) => ({
+        ...framework,
+        recommended: false,
+    }));
+    const profile = buildTaskAgentTaskProfile(profileInput);
+    const configuredSubscriptionProvider = inventory.configuredSubscriptionProvider;
+    const providerPrefersClaude = configuredSubscriptionProvider === "anthropic-subscription";
+    const providerPrefersCodex = configuredSubscriptionProvider === "openai-codex" ||
+        configuredSubscriptionProvider === "openai-subscription";
+    const explicitDefault = safeGetSetting(runtime, "PARALLAX_DEFAULT_AGENT_TYPE")
+        ?.toLowerCase()
+        .trim();
+    const candidates = frameworks.filter((framework) => framework.installed && !framework.temporarilyDisabled).length > 0
+        ? frameworks.filter((framework) => framework.installed && !framework.temporarilyDisabled)
+        : frameworks.filter((framework) => framework.installed);
+    const scoredCandidates = candidates.map((framework) => {
+        const explicitOverride = explicitDefault === framework.id
+            ? framework.installed && !framework.temporarilyDisabled
+                ? 40
+                : 0
+            : 0;
+        const providerPreference = providerPrefersClaude && framework.id === "claude"
+            ? framework.subscriptionReady
+                ? 18
+                : 6
+            : providerPrefersCodex && framework.id === "codex"
+                ? framework.subscriptionReady
+                    ? 18
+                    : 6
+                : 0;
+        const availabilityScore = (framework.installed ? 40 : -100) +
+            (framework.authReady ? 18 : -25) +
+            (framework.subscriptionReady ? 8 : 0) +
+            (framework.temporarilyDisabled ? -80 : 0);
+        const profileScore = computeProfileFitScore(framework.id, profile);
+        const metricsScore = computeMetricsScore(metrics[framework.id], profile.signals.fastIteration);
+        const selectionSignals = {
+            availability: availabilityScore,
+            profile: profileScore,
+            provider: providerPreference,
+            metrics: metricsScore,
+            explicitOverride,
+        };
+        return {
+            framework,
+            score: Object.values(selectionSignals).reduce((sum, value) => sum + value, 0),
+            selectionSignals,
+        };
+    });
+    const fallback = candidates[0] ??
+        frameworks.find((framework) => framework.installed) ??
+        frameworks[0];
+    const preferredCandidate = scoredCandidates.sort((left, right) => {
+        if (right.score !== left.score) {
+            return right.score - left.score;
+        }
+        return left.framework.id.localeCompare(right.framework.id);
+    })[0]?.framework ?? fallback;
+    const preferredSignals = scoredCandidates.find((entry) => entry.framework.id === preferredCandidate.id)?.selectionSignals ?? {};
+    const preferred = {
+        id: preferredCandidate.id,
+        reason: buildPreferredReason(preferredCandidate, profile, preferredSignals, explicitDefault, configuredSubscriptionProvider),
+    };
+    for (const framework of frameworks) {
+        framework.recommended = framework.id === preferred.id;
+        const scored = scoredCandidates.find((entry) => entry.framework.id === framework.id);
+        if (scored) {
+            framework.selectionScore = scored.score;
+            framework.selectionSignals = scored.selectionSignals;
+        }
+    }
+    frameworkStateCache = {
+        expiresAt: Date.now() + 15_000,
+        value: inventory,
+    };
+    return {
+        configuredSubscriptionProvider,
+        frameworks,
+        preferred,
+    };
+}
+function clampSignal(value) {
+    return Math.max(0, Math.min(1, value));
+}
+function kindBoost(kind, target) {
+    if (kind === "mixed")
+        return 0.25;
+    return kind === target ? 0.4 : 0;
+}
+export function buildTaskAgentTaskProfile(input) {
+    const text = [
+        input?.task?.trim(),
+        input?.repo?.trim(),
+        ...(input?.acceptanceCriteria ?? []).map((value) => value.trim()),
+    ]
+        .filter((value) => Boolean(value))
+        .join("\n");
+    const inferredKind = input?.threadKind ??
+        (OPS_SIGNAL_RE.test(text)
+            ? "ops"
+            : PLANNING_SIGNAL_RE.test(text)
+                ? "planning"
+                : RESEARCH_SIGNAL_RE.test(text) && !IMPLEMENTATION_SIGNAL_RE.test(text)
+                    ? "research"
+                    : IMPLEMENTATION_SIGNAL_RE.test(text)
+                        ? "coding"
+                        : RESEARCH_SIGNAL_RE.test(text)
+                            ? "mixed"
+                            : "coding");
+    const repoPresent = Boolean(input?.repo?.trim() || input?.workdir?.trim());
+    const subtaskCount = Math.max(1, input?.subtaskCount ?? 1);
+    const signals = {
+        implementation: clampSignal((IMPLEMENTATION_SIGNAL_RE.test(text) ? 0.7 : 0.2) +
+            (repoPresent ? 0.15 : 0) +
+            kindBoost(inferredKind, "coding")),
+        research: clampSignal((RESEARCH_SIGNAL_RE.test(text) ? 0.7 : 0.1) +
+            kindBoost(inferredKind, "research")),
+        planning: clampSignal((PLANNING_SIGNAL_RE.test(text) ? 0.75 : 0.1) +
+            kindBoost(inferredKind, "planning")),
+        ops: clampSignal((OPS_SIGNAL_RE.test(text) ? 0.75 : 0.05) + kindBoost(inferredKind, "ops")),
+        verification: clampSignal((VERIFICATION_SIGNAL_RE.test(text) ? 0.8 : 0.15) +
+            ((input?.acceptanceCriteria?.length ?? 0) > 0 ? 0.15 : 0)),
+        coordination: clampSignal((COORDINATION_SIGNAL_RE.test(text) ? 0.7 : 0.05) +
+            (subtaskCount > 1 ? 0.25 : 0)),
+        repoWork: clampSignal((REPO_SIGNAL_RE.test(text) ? 0.7 : 0.1) + (repoPresent ? 0.25 : 0)),
+        fastIteration: clampSignal((FAST_ITERATION_SIGNAL_RE.test(text) ? 0.75 : 0.15) +
+            (inferredKind === "coding" ? 0.1 : 0)),
+    };
+    return {
+        text,
+        kind: inferredKind,
+        subtaskCount,
+        repoPresent,
+        signals,
+    };
+}
+function computeProfileFitScore(frameworkId, profile) {
+    const capability = FRAMEWORK_CAPABILITY_PROFILES[frameworkId];
+    const weightedSum = profile.signals.implementation * capability.implementation * 18 +
+        profile.signals.research * capability.research * 16 +
+        profile.signals.planning * capability.planning * 14 +
+        profile.signals.ops * capability.ops * 12 +
+        profile.signals.verification * capability.verification * 14 +
+        profile.signals.coordination * capability.coordination * 14 +
+        profile.signals.repoWork * capability.repoWork * 10 +
+        profile.signals.fastIteration * capability.fastIteration * 10;
+    return Math.round(weightedSum);
+}
+function computeMetricsScore(metrics, fastIterationSignal) {
+    if (!metrics || metrics.spawned === 0) {
+        return 0;
+    }
+    const successRate = metrics.spawned > 0 ? metrics.completed / metrics.spawned : 0;
+    const stallRate = metrics.spawned > 0 ? metrics.stallCount / metrics.spawned : 0;
+    const durationBonus = metrics.completed > 0
+        ? Math.max(-8, Math.min(8, ((120_000 - metrics.avgCompletionMs) / 120_000) *
+            (4 + fastIterationSignal * 4)))
+        : 0;
+    return Math.round(successRate * 14 - stallRate * 12 + durationBonus);
+}
+function buildPreferredReason(framework, profile, selectionSignals, explicitDefault, configuredSubscriptionProvider) {
+    const dominantSignals = Object.entries(profile.signals)
+        .sort((left, right) => right[1] - left[1])
+        .slice(0, 2)
+        .map(([key]) => key);
+    if (explicitDefault === framework.id &&
+        selectionSignals.explicitOverride > 0) {
+        return `explicit PARALLAX_DEFAULT_AGENT_TYPE override, with ${FRAMEWORK_LABELS[framework.id]} still scoring well for ${dominantSignals.join(" + ")} work`;
+    }
+    if (configuredSubscriptionProvider === "anthropic-subscription" &&
+        framework.id === "claude" &&
+        framework.subscriptionReady) {
+        return `best fit for ${dominantSignals.join(" + ")} work while honoring the configured Claude subscription`;
+    }
+    if ((configuredSubscriptionProvider === "openai-codex" ||
+        configuredSubscriptionProvider === "openai-subscription") &&
+        framework.id === "codex" &&
+        framework.subscriptionReady) {
+        return `best fit for ${dominantSignals.join(" + ")} work while honoring the configured OpenAI subscription`;
+    }
+    if (framework.subscriptionReady) {
+        return `best overall score for ${dominantSignals.join(" + ")} work with subscription-backed auth already available`;
+    }
+    if (framework.authReady) {
+        return `best overall score for ${dominantSignals.join(" + ")} work with credentials already available`;
+    }
+    return `selected as the highest-scoring installed framework for ${dominantSignals.join(" + ")} work`;
+}
+export function clearTaskAgentFrameworkStateCache() {
+    frameworkStateCache = undefined;
+}
+export function isUsageExhaustedTaskAgentError(text) {
+    return TASK_AGENT_USAGE_EXHAUSTED_RE.test(text);
+}
+export function markTaskAgentFrameworkUnavailable(id, reason, cooldownMs = 30 * 60 * 1000) {
+    frameworkCooldowns.set(id, {
+        until: Date.now() + cooldownMs,
+        reason,
+    });
+    clearTaskAgentFrameworkStateCache();
+}
+export function markTaskAgentFrameworkHealthy(id) {
+    if (frameworkCooldowns.delete(id)) {
+        clearTaskAgentFrameworkStateCache();
+    }
+}
+export function formatTaskAgentFrameworkLine(framework) {
+    const parts = [
+        framework.installed ? "installed" : "not installed",
+        framework.authReady ? "credentials ready" : "credentials missing",
+    ];
+    if (framework.subscriptionReady) {
+        parts.push("uses the user's subscription");
+    }
+    if (framework.temporarilyDisabled) {
+        parts.push("temporarily disabled");
+    }
+    if (framework.recommended) {
+        parts.push("recommended");
+    }
+    return `- ${framework.label}: ${parts.join(", ")}. ${framework.reason}.`;
+}
+export function looksLikeTaskAgentRequest(text) {
+    return TASK_AGENT_COMPLEXITY_RE.test(text);
+}
+export function formatTaskAgentStatus(status) {
+    switch (status) {
+        case "ready":
+            return "idle";
+        case "busy":
+            return "working";
+        case "starting":
+            return "starting";
+        case "authenticating":
+            return "authenticating";
+        default:
+            return status;
+    }
+}
+export function truncateTaskAgentText(text, max = 120) {
+    const trimmed = text.trim().replace(/\s+/g, " ");
+    return trimmed.length > max ? `${trimmed.slice(0, max - 1)}...` : trimmed;
+}
+export function rewriteTaskAgentText(text) {
+    return text
+        .replace(/\bcoding agents\b/gi, "task agents")
+        .replace(/\bcoding agent\b/gi, "task agent")
+        .replace(/\bcoding sessions\b/gi, "task-agent sessions")
+        .replace(/\bcoding session\b/gi, "task-agent session");
+}
+export { FRAMEWORK_LABELS as TASK_AGENT_FRAMEWORK_LABELS };