@penclipai/server 2026.426.0 → 2026.505.0

package/dist/routes/agents.js

@@ -3,7 +3,7 @@ import { generateKeyPairSync, randomUUID } from "node:crypto";
 import path from "node:path";
 import { agents as agentsTable, companies, heartbeatRuns, issues as issuesTable } from "@penclipai/db";
 import { and, desc, eq, inArray, not, sql } from "drizzle-orm";
-import { agentSkillSyncSchema, agentMineInboxQuerySchema, AGENT_DEFAULT_MAX_CONCURRENT_RUNS, createAgentKeySchema, createAgentHireSchema, createAgentSchema, deriveAgentUrlKey, isUuidLike, resetAgentSessionSchema, testAdapterEnvironmentSchema, upsertAgentInstructionsFileSchema, updateAgentInstructionsBundleSchema, updateAgentPermissionsSchema, updateAgentInstructionsPathSchema, wakeAgentSchema, updateAgentSchema, supportedEnvironmentDriversForAdapter, } from "@penclipai/shared";
+import { agentSkillSyncSchema, agentMineInboxQuerySchema, AGENT_DEFAULT_MAX_CONCURRENT_RUNS, createAgentKeySchema, createAgentHireSchema, createAgentSchema, deriveAgentUrlKey, isUuidLike, normalizeIssueIdentifier, resetAgentSessionSchema, testAdapterEnvironmentSchema, upsertAgentInstructionsFileSchema, updateAgentInstructionsBundleSchema, updateAgentPermissionsSchema, updateAgentInstructionsPathSchema, wakeAgentSchema, updateAgentSchema, supportedEnvironmentDriversForAdapter, } from "@penclipai/shared";
 import { readPaperclipSkillSyncPreference, writePaperclipSkillSyncPreference, } from "@penclipai/adapter-utils/server-utils";
 import { trackAgentCreated } from "@penclipai/shared/telemetry";
 import { validate } from "../middleware/validate.js";
@@ -12,8 +12,9 @@ import { conflict, forbidden, notFound, unprocessable } from "../errors.js";
 import { assertBoard, assertCompanyAccess, assertInstanceAdmin, getActorInfo } from "./authz.js";
 import { assertNoAgentHostWorkspaceCommandMutation, collectAgentAdapterWorkspaceCommandPaths, } from "./workspace-command-authz.js";
 import { environmentService } from "../services/environments.js";
+import { resolveEnvironmentExecutionTarget } from "../services/environment-execution-target.js";
 import { secretService } from "../services/secrets.js";
-import { detectAdapterModel, findActiveServerAdapter, findServerAdapter, listAdapterModels, refreshAdapterModels, requireServerAdapter, } from "../adapters/index.js";
+import { detectAdapterModel, findActiveServerAdapter, findServerAdapter, listAdapterModels, listAdapterModelProfiles, refreshAdapterModels, requireServerAdapter, } from "../adapters/index.js";
 import { redactEventPayload } from "../redaction.js";
 import { redactCurrentUserValue } from "../log-redaction.js";
 import { renderOrgChartSvg, renderOrgChartPng, ORG_CHART_STYLES } from "./org-chart-svg.js";
@@ -21,12 +22,14 @@ import { instanceSettingsService } from "../services/instance-settings.js";
 import { resolveExplicitRequestUiLocale } from "../ui-locale.js";
 import { runClaudeLogin } from "@penclipai/adapter-claude-local/server";
 import { DEFAULT_CODEBUDDY_LOCAL_MODEL, } from "@penclipai/adapter-codebuddy-local";
+import { DEFAULT_ACPX_LOCAL_AGENT, DEFAULT_ACPX_LOCAL_MODE, DEFAULT_ACPX_LOCAL_NON_INTERACTIVE_PERMISSIONS, DEFAULT_ACPX_LOCAL_PERMISSION_MODE, } from "@penclipai/adapter-acpx-local";
 import { DEFAULT_CODEX_LOCAL_BYPASS_APPROVALS_AND_SANDBOX, DEFAULT_CODEX_LOCAL_MODEL, } from "@penclipai/adapter-codex-local";
 import { DEFAULT_CURSOR_LOCAL_MODEL } from "@penclipai/adapter-cursor-local";
 import { DEFAULT_GEMINI_LOCAL_MODEL } from "@penclipai/adapter-gemini-local";
+import { DEFAULT_OPENCODE_LOCAL_MODEL } from "@penclipai/adapter-opencode-local";
 import { DEFAULT_QWEN_LOCAL_MODEL } from "@penclipai/adapter-qwen-local";
 import { ensureCodeBuddyModelConfiguredAndAvailable } from "@penclipai/adapter-codebuddy-local/server";
-import { ensureOpenCodeModelConfiguredAndAvailable } from "@penclipai/adapter-opencode-local/server";
+import { requireOpenCodeModelId } from "@penclipai/adapter-opencode-local/server";
 import { loadDefaultAgentInstructionsBundle, resolveDefaultAgentInstructionsBundleRole, } from "../services/default-agent-instructions.js";
 import { getTelemetryClient } from "../telemetry.js";
 import { assertEnvironmentSelectionForCompany } from "./environment-selection.js";
@@ -43,12 +46,15 @@ function readLiveRunsQueryInt(value, max, fallback = 0) {
     const parsed = Number(value);
     if (!Number.isFinite(parsed))
         return fallback;
-    return Math.max(0, Math.min(max, Math.trunc(parsed)));
+    if (parsed <= 0)
+        return fallback;
+    return Math.min(max, Math.trunc(parsed));
 }
 export function agentRoutes(db, options = {}) {
     // Legacy hardcoded maps — used as fallback when adapter module does not
     // declare capability flags explicitly.
     const DEFAULT_INSTRUCTIONS_PATH_KEYS = {
+        acpx_local: "instructionsFilePath",
         claude_local: "instructionsFilePath",
         codex_local: "instructionsFilePath",
         codebuddy_local: "instructionsFilePath",
@@ -111,6 +117,96 @@ export function agentRoutes(db, options = {}) {
             allowedDrivers: allowedEnvironmentDriversForAgent(adapterType),
         });
     }
+    /**
+     * Resolve the execution target the adapter should run its test probes against.
+     *
+     * - No environmentId / local environment → returns a local target so the
+     *   adapter probes the Paperclip host (legacy behavior).
+     * - SSH environment → builds an SSH execution target from the environment
+     *   config so the adapter probes the remote box. No lease is required:
+     *   the SSH spec is fully derived from the saved environment config.
+     * - Sandbox / plugin environments → currently fall back to local probing
+     *   with a warning check, since lifting a temporary sandbox lease for an
+     *   ad-hoc test invocation is out of scope for this iteration.
+     */
+    async function resolveAdapterTestExecutionContext(input) {
+        if (!input.environmentId) {
+            return { executionTarget: null, environmentName: null, fallbackChecks: [] };
+        }
+        const environment = await environmentsSvc.getById(input.environmentId);
+        if (!environment || environment.companyId !== input.companyId) {
+            return {
+                executionTarget: null,
+                environmentName: null,
+                fallbackChecks: [
+                    {
+                        code: "environment_not_found",
+                        level: "warn",
+                        message: "Selected environment was not found. Falling back to a local probe.",
+                    },
+                ],
+            };
+        }
+        if (environment.driver === "local") {
+            return { executionTarget: null, environmentName: environment.name, fallbackChecks: [] };
+        }
+        if (environment.driver === "ssh") {
+            try {
+                const target = await resolveEnvironmentExecutionTarget({
+                    db,
+                    companyId: input.companyId,
+                    adapterType: input.adapterType,
+                    environment: {
+                        id: environment.id,
+                        driver: environment.driver,
+                        config: environment.config ?? null,
+                    },
+                    leaseMetadata: null,
+                });
+                if (target) {
+                    return { executionTarget: target, environmentName: environment.name, fallbackChecks: [] };
+                }
+                return {
+                    executionTarget: null,
+                    environmentName: environment.name,
+                    fallbackChecks: [
+                        {
+                            code: "environment_target_unavailable",
+                            level: "warn",
+                            message: `Could not resolve an execution target for environment "${environment.name}". Falling back to a local probe.`,
+                        },
+                    ],
+                };
+            }
+            catch (err) {
+                return {
+                    executionTarget: null,
+                    environmentName: environment.name,
+                    fallbackChecks: [
+                        {
+                            code: "environment_target_failed",
+                            level: "warn",
+                            message: `Could not connect to environment "${environment.name}" to run the test. Falling back to a local probe.`,
+                            detail: err instanceof Error ? err.message : String(err),
+                        },
+                    ],
+                };
+            }
+        }
+        // sandbox / plugin / other drivers: not yet supported for ad-hoc adapter tests.
+        return {
+            executionTarget: null,
+            environmentName: environment.name,
+            fallbackChecks: [
+                {
+                    code: "environment_driver_not_supported_for_test",
+                    level: "warn",
+                    message: `Adapter testing inside ${environment.driver} environments is not yet supported. Falling back to a local probe; results may not reflect runs in "${environment.name}".`,
+                    hint: "Run a real heartbeat in the environment to verify end-to-end behavior.",
+                },
+            ],
+        };
+    }
     async function getCurrentUserRedactionOptions() {
         return {
             enabled: (await instanceSettings.getGeneral()).censorUsernameInLogs,
@@ -484,6 +580,66 @@ export function agentRoutes(db, options = {}) {
         normalizedRuntimeConfig.heartbeat = heartbeat;
         return normalizedRuntimeConfig;
     }
+    function listRuntimeModelProfileAdapterConfigs(runtimeConfig) {
+        const runtimeRecord = asRecord(runtimeConfig);
+        const modelProfiles = asRecord(runtimeRecord?.modelProfiles);
+        if (!modelProfiles)
+            return [];
+        const entries = [];
+        for (const [profileKey, rawProfile] of Object.entries(modelProfiles)) {
+            const profile = asRecord(rawProfile);
+            const adapterConfig = asRecord(profile?.adapterConfig);
+            if (!profile || !adapterConfig)
+                continue;
+            entries.push({
+                profileKey,
+                profile,
+                adapterConfig,
+                path: `runtimeConfig.modelProfiles.${profileKey}.adapterConfig`,
+            });
+        }
+        return entries;
+    }
+    function assertNoAgentRuntimeConfigAdapterConfigMutation(req, runtimeConfig) {
+        for (const entry of listRuntimeModelProfileAdapterConfigs(runtimeConfig)) {
+            assertNoAgentAdapterConfigMutation(req, entry.adapterConfig, entry.path);
+        }
+    }
+    async function normalizeMediatedAdapterConfigForPersistence(input) {
+        const normalizedAdapterConfig = await secretsSvc.normalizeAdapterConfigForPersistence(input.companyId, input.adapterConfig, { strictMode: strictSecretsMode });
+        await assertAdapterConfigConstraints(input.companyId, input.adapterType, input.constraintAdapterConfig
+            ? { ...input.constraintAdapterConfig, ...normalizedAdapterConfig }
+            : normalizedAdapterConfig);
+        return normalizedAdapterConfig;
+    }
+    async function normalizeRuntimeConfigAdapterConfigsForPersistence(companyId, adapterType, runtimeConfig, baseAdapterConfig) {
+        const entries = listRuntimeModelProfileAdapterConfigs(runtimeConfig);
+        if (entries.length === 0)
+            return runtimeConfig;
+        const adapterModelProfiles = await listAdapterModelProfiles(adapterType);
+        const normalizedRuntimeConfig = { ...runtimeConfig };
+        const modelProfiles = asRecord(runtimeConfig.modelProfiles) ?? {};
+        const normalizedModelProfiles = { ...modelProfiles };
+        normalizedRuntimeConfig.modelProfiles = normalizedModelProfiles;
+        for (const entry of entries) {
+            const adapterProfile = adapterModelProfiles.find((profile) => profile.key === entry.profileKey);
+            const adapterDefaultConfig = asRecord(adapterProfile?.adapterConfig) ?? {};
+            const normalizedAdapterConfig = await normalizeMediatedAdapterConfigForPersistence({
+                companyId,
+                adapterType,
+                adapterConfig: entry.adapterConfig,
+                constraintAdapterConfig: {
+                    ...baseAdapterConfig,
+                    ...adapterDefaultConfig,
+                },
+            });
+            normalizedModelProfiles[entry.profileKey] = {
+                ...entry.profile,
+                adapterConfig: normalizedAdapterConfig,
+            };
+        }
+        return normalizedRuntimeConfig;
+    }
     function generateEd25519PrivateKeyPem() {
         const { privateKey } = generateKeyPairSync("ed25519");
         return privateKey.export({ type: "pkcs8", format: "pem" }).toString();
@@ -500,6 +656,21 @@ export function agentRoutes(db, options = {}) {
     }
     function applyCreateDefaultsByAdapterType(adapterType, adapterConfig) {
         const next = { ...adapterConfig };
+        if (adapterType === "acpx_local") {
+            if (!asNonEmptyString(next.agent)) {
+                next.agent = DEFAULT_ACPX_LOCAL_AGENT;
+            }
+            if (!asNonEmptyString(next.mode)) {
+                next.mode = DEFAULT_ACPX_LOCAL_MODE;
+            }
+            if (!asNonEmptyString(next.permissionMode)) {
+                next.permissionMode = DEFAULT_ACPX_LOCAL_PERMISSION_MODE;
+            }
+            if (!asNonEmptyString(next.nonInteractivePermissions)) {
+                next.nonInteractivePermissions = DEFAULT_ACPX_LOCAL_NON_INTERACTIVE_PERMISSIONS;
+            }
+            return ensureGatewayDeviceKey(adapterType, next);
+        }
         if (adapterType === "codex_local") {
             if (!asNonEmptyString(next.model)) {
                 next.model = DEFAULT_CODEX_LOCAL_MODEL;
@@ -523,7 +694,10 @@ export function agentRoutes(db, options = {}) {
             next.model = DEFAULT_QWEN_LOCAL_MODEL;
             return ensureGatewayDeviceKey(adapterType, next);
         }
-        // OpenCode requires explicit model selection — no default
+        if (adapterType === "opencode_local" && !asNonEmptyString(next.model)) {
+            next.model = DEFAULT_OPENCODE_LOCAL_MODEL;
+            return ensureGatewayDeviceKey(adapterType, next);
+        }
         if (adapterType === "cursor" && !asNonEmptyString(next.model)) {
             next.model = DEFAULT_CURSOR_LOCAL_MODEL;
         }
@@ -549,15 +723,8 @@ export function agentRoutes(db, options = {}) {
         }
         if (adapterType !== "opencode_local")
             return;
-        const { config: runtimeConfig } = await secretsSvc.resolveAdapterConfigForRuntime(companyId, adapterConfig);
-        const runtimeEnv = asRecord(runtimeConfig.env) ?? {};
         try {
-            await ensureOpenCodeModelConfiguredAndAvailable({
-                model: runtimeConfig.model,
-                command: runtimeConfig.command,
-                cwd: runtimeConfig.cwd,
-                env: runtimeEnv,
-            });
+            requireOpenCodeModelId(adapterConfig.model);
         }
         catch (err) {
             const reason = err instanceof Error ? err.message : String(err);
@@ -577,7 +744,7 @@ export function agentRoutes(db, options = {}) {
         }
         return path.resolve(cwd, trimmed);
     }
-    async function materializeDefaultInstructionsBundleForNewAgent(agent) {
+    async function materializeDefaultInstructionsBundleForNewAgent(agent, input) {
         if (!adapterSupportsInstructionsBundle(agent.adapterType)) {
             return agent;
         }
@@ -588,20 +755,33 @@ export function agentRoutes(db, options = {}) {
             || Boolean(asNonEmptyString(adapterConfig.instructionsFilePath))
             || Boolean(asNonEmptyString(adapterConfig.agentsMdPath));
         if (hasExplicitInstructionsBundle) {
-            return agent;
-        }
-        const promptTemplate = typeof adapterConfig.promptTemplate === "string"
-            ? adapterConfig.promptTemplate
-            : "";
-        const files = promptTemplate.trim().length === 0
-            ? await loadDefaultAgentInstructionsBundle(resolveDefaultAgentInstructionsBundleRole(agent.role))
-            : { "AGENTS.md": promptTemplate };
-        const materialized = await instructions.materializeManagedBundle(agent, files, { entryFile: "AGENTS.md", replaceExisting: false });
+            const nextAdapterConfig = { ...adapterConfig };
+            const hadLegacyPrompt = Object.prototype.hasOwnProperty.call(nextAdapterConfig, "promptTemplate")
+                || Object.prototype.hasOwnProperty.call(nextAdapterConfig, "bootstrapPromptTemplate");
+            delete nextAdapterConfig.promptTemplate;
+            delete nextAdapterConfig.bootstrapPromptTemplate;
+            if (!hadLegacyPrompt)
+                return agent;
+            const updated = await svc.update(agent.id, { adapterConfig: nextAdapterConfig });
+            return updated ?? { ...agent, adapterConfig: nextAdapterConfig };
+        }
+        const files = input?.files
+            ?? await loadDefaultAgentInstructionsBundle(resolveDefaultAgentInstructionsBundleRole(agent.role));
+        const materialized = await instructions.materializeManagedBundle(agent, files, { entryFile: input?.entryFile ?? "AGENTS.md", replaceExisting: false });
         const nextAdapterConfig = { ...materialized.adapterConfig };
         delete nextAdapterConfig.promptTemplate;
+        delete nextAdapterConfig.bootstrapPromptTemplate;
         const updated = await svc.update(agent.id, { adapterConfig: nextAdapterConfig });
         return updated ?? { ...agent, adapterConfig: nextAdapterConfig };
     }
+    function assertNoNewAgentLegacyPromptTemplate(adapterType, adapterConfig) {
+        if (!adapterSupportsInstructionsBundle(adapterType))
+            return;
+        if (Object.prototype.hasOwnProperty.call(adapterConfig, "promptTemplate")
+            || Object.prototype.hasOwnProperty.call(adapterConfig, "bootstrapPromptTemplate")) {
+            throw unprocessable("New agents must use instructionsBundle/AGENTS.md instead of adapterConfig.promptTemplate or bootstrapPromptTemplate");
+        }
+    }
     async function assertCanManageInstructionsPath(req, targetAgent) {
         assertCompanyAccess(req, targetAgent.companyId);
         if (req.actor.type !== "board") {
@@ -609,14 +789,23 @@ export function agentRoutes(db, options = {}) {
         }
         await assertBoardCanManageAgentsForCompany(req, targetAgent.companyId);
     }
-    function assertNoAgentInstructionsConfigMutation(req, adapterConfig) {
+    function assertNoAgentInstructionsConfigMutation(req, adapterConfig, path = "adapterConfig") {
         if (req.actor.type !== "agent" || !adapterConfig)
             return;
-        const changedSensitiveKeys = KNOWN_INSTRUCTIONS_BUNDLE_KEYS.filter((key) => adapterConfig[key] !== undefined);
+        const changedSensitiveKeys = KNOWN_INSTRUCTIONS_BUNDLE_KEYS
+            .filter((key) => adapterConfig[key] !== undefined)
+            .map((key) => `${path}.${key}`);
         if (changedSensitiveKeys.length === 0)
             return;
         throw forbidden(`Agent-authenticated callers cannot modify instructions path or bundle configuration (${changedSensitiveKeys.join(", ")})`);
     }
+    function adapterConfigTouchesInstructionsConfig(adapterConfig) {
+        return KNOWN_INSTRUCTIONS_BUNDLE_KEYS.some((key) => adapterConfig[key] !== undefined);
+    }
+    function assertNoAgentAdapterConfigMutation(req, adapterConfig, path = "adapterConfig") {
+        assertNoAgentInstructionsConfigMutation(req, adapterConfig, path);
+        assertNoAgentHostWorkspaceCommandMutation(req, collectAgentAdapterWorkspaceCommandPaths(adapterConfig, path));
+    }
     function summarizeAgentUpdateDetails(patch) {
         const changedTopLevelKeys = Object.keys(patch).sort();
         const details = { changedTopLevelKeys };
@@ -765,11 +954,29 @@ export function agentRoutes(db, options = {}) {
         const refresh = typeof req.query.refresh === "string"
             ? ["1", "true", "yes"].includes(req.query.refresh.toLowerCase())
             : false;
+        const environmentId = asNonEmptyString(req.query.environmentId);
+        const environment = environmentId ? await environmentsSvc.getById(environmentId) : null;
+        if (environmentId && (!environment || environment.companyId !== companyId)) {
+            res.status(404).json({ error: "Environment not found" });
+            return;
+        }
+        if (type === "opencode_local" && environment && environment.driver !== "local") {
+            const adapter = requireServerAdapter(type);
+            res.json(adapter.models ?? []);
+            return;
+        }
         const models = refresh
             ? await refreshAdapterModels(type)
             : await listAdapterModels(type);
         res.json(models);
     });
+    router.get("/companies/:companyId/adapters/:type/model-profiles", async (req, res) => {
+        const companyId = req.params.companyId;
+        assertCompanyAccess(req, companyId);
+        const type = assertKnownAdapterType(req.params.type);
+        const profiles = await listAdapterModelProfiles(type);
+        res.json(profiles);
+    });
     router.get("/companies/:companyId/adapters/:type/detect-model", async (req, res) => {
         const companyId = req.params.companyId;
         await assertCanReadConfigurations(req, companyId);
@@ -783,13 +990,33 @@ export function agentRoutes(db, options = {}) {
         await assertCanReadConfigurations(req, companyId);
         const adapter = requireServerAdapter(type);
         const inputAdapterConfig = (req.body?.adapterConfig ?? {});
+        const requestedEnvironmentId = typeof req.body?.environmentId === "string" && req.body.environmentId.trim().length > 0
+            ? req.body.environmentId
+            : null;
         const normalizedAdapterConfig = await secretsSvc.normalizeAdapterConfigForPersistence(companyId, inputAdapterConfig, { strictMode: strictSecretsMode });
         const { config: runtimeAdapterConfig } = await secretsSvc.resolveAdapterConfigForRuntime(companyId, normalizedAdapterConfig);
+        const { executionTarget, environmentName, fallbackChecks } = await resolveAdapterTestExecutionContext({
+            companyId,
+            adapterType: type,
+            environmentId: requestedEnvironmentId,
+        });
         const result = await adapter.testEnvironment({
             companyId,
             adapterType: type,
             config: runtimeAdapterConfig,
+            executionTarget,
+            environmentName,
         });
+        if (fallbackChecks.length > 0) {
+            const checks = [...fallbackChecks, ...result.checks];
+            const status = checks.some((c) => c.level === "error")
+                ? "fail"
+                : checks.some((c) => c.level === "warn")
+                    ? "warn"
+                    : result.status;
+            res.json({ ...result, checks, status });
+            return;
+        }
         res.json(result);
     });
     router.get("/agents/:id/skills", async (req, res) => {
@@ -1199,18 +1426,24 @@ export function agentRoutes(db, options = {}) {
         const companyId = req.params.companyId;
         await assertCanCreateAgentsForCompany(req, companyId);
         const sourceIssueIds = parseSourceIssueIds(req.body);
-        const { desiredSkills: requestedDesiredSkills, sourceIssueId: _sourceIssueId, sourceIssueIds: _sourceIssueIds, ...hireInput } = req.body;
+        const { desiredSkills: requestedDesiredSkills, instructionsBundle, sourceIssueId: _sourceIssueId, sourceIssueIds: _sourceIssueIds, ...hireInput } = req.body;
         hireInput.adapterType = assertKnownAdapterType(hireInput.adapterType);
-        assertNoAgentHostWorkspaceCommandMutation(req, collectAgentAdapterWorkspaceCommandPaths(hireInput.adapterConfig));
-        assertNoAgentInstructionsConfigMutation(req, (hireInput.adapterConfig ?? {}));
-        const requestedAdapterConfig = applyCreateDefaultsByAdapterType(hireInput.adapterType, (hireInput.adapterConfig ?? {}));
+        const rawHireAdapterConfig = (hireInput.adapterConfig ?? {});
+        assertNoNewAgentLegacyPromptTemplate(hireInput.adapterType, rawHireAdapterConfig);
+        assertNoAgentAdapterConfigMutation(req, rawHireAdapterConfig);
+        assertNoAgentRuntimeConfigAdapterConfigMutation(req, hireInput.runtimeConfig);
+        const requestedAdapterConfig = applyCreateDefaultsByAdapterType(hireInput.adapterType, rawHireAdapterConfig);
         const desiredSkillAssignment = await resolveDesiredSkillAssignment(companyId, hireInput.adapterType, requestedAdapterConfig, Array.isArray(requestedDesiredSkills) ? requestedDesiredSkills : undefined);
-        const normalizedAdapterConfig = await secretsSvc.normalizeAdapterConfigForPersistence(companyId, desiredSkillAssignment.adapterConfig, { strictMode: strictSecretsMode });
-        await assertAdapterConfigConstraints(companyId, hireInput.adapterType, normalizedAdapterConfig);
+        const normalizedAdapterConfig = await normalizeMediatedAdapterConfigForPersistence({
+            companyId,
+            adapterType: hireInput.adapterType,
+            adapterConfig: desiredSkillAssignment.adapterConfig,
+        });
+        const normalizedRuntimeConfig = await normalizeRuntimeConfigAdapterConfigsForPersistence(companyId, hireInput.adapterType, normalizeNewAgentRuntimeConfig(hireInput.runtimeConfig), normalizedAdapterConfig);
         const normalizedHireInput = {
             ...hireInput,
             adapterConfig: normalizedAdapterConfig,
-            runtimeConfig: normalizeNewAgentRuntimeConfig(hireInput.runtimeConfig),
+            runtimeConfig: normalizedRuntimeConfig,
         };
         const company = await db
             .select()
@@ -1229,7 +1462,7 @@ export function agentRoutes(db, options = {}) {
             spentMonthlyCents: 0,
             lastHeartbeatAt: null,
         });
-        const agent = await materializeDefaultInstructionsBundleForNewAgent(createdAgent);
+        const agent = await materializeDefaultInstructionsBundleForNewAgent(createdAgent, instructionsBundle);
         let approval = null;
         const actor = getActorInfo(req);
         if (requiresApproval) {
@@ -1331,14 +1564,20 @@ export function agentRoutes(db, options = {}) {
         if (company.requireBoardApprovalForNewAgents) {
             throw conflict("Direct agent creation requires board approval. Use POST /api/companies/:companyId/agent-hires to create a pending hire approval.");
         }
-        const { desiredSkills: requestedDesiredSkills, ...createInput } = req.body;
+        const { desiredSkills: requestedDesiredSkills, instructionsBundle, ...createInput } = req.body;
         createInput.adapterType = assertKnownAdapterType(createInput.adapterType);
-        assertNoAgentHostWorkspaceCommandMutation(req, collectAgentAdapterWorkspaceCommandPaths(createInput.adapterConfig));
-        assertNoAgentInstructionsConfigMutation(req, (createInput.adapterConfig ?? {}));
-        const requestedAdapterConfig = applyCreateDefaultsByAdapterType(createInput.adapterType, (createInput.adapterConfig ?? {}));
+        const rawCreateAdapterConfig = (createInput.adapterConfig ?? {});
+        assertNoNewAgentLegacyPromptTemplate(createInput.adapterType, rawCreateAdapterConfig);
+        assertNoAgentAdapterConfigMutation(req, rawCreateAdapterConfig);
+        assertNoAgentRuntimeConfigAdapterConfigMutation(req, createInput.runtimeConfig);
+        const requestedAdapterConfig = applyCreateDefaultsByAdapterType(createInput.adapterType, rawCreateAdapterConfig);
         const desiredSkillAssignment = await resolveDesiredSkillAssignment(companyId, createInput.adapterType, requestedAdapterConfig, Array.isArray(requestedDesiredSkills) ? requestedDesiredSkills : undefined);
-        const normalizedAdapterConfig = await secretsSvc.normalizeAdapterConfigForPersistence(companyId, desiredSkillAssignment.adapterConfig, { strictMode: strictSecretsMode });
-        await assertAdapterConfigConstraints(companyId, createInput.adapterType, normalizedAdapterConfig);
+        const normalizedAdapterConfig = await normalizeMediatedAdapterConfigForPersistence({
+            companyId,
+            adapterType: createInput.adapterType,
+            adapterConfig: desiredSkillAssignment.adapterConfig,
+        });
+        const normalizedRuntimeConfig = await normalizeRuntimeConfigAdapterConfigsForPersistence(companyId, createInput.adapterType, normalizeNewAgentRuntimeConfig(createInput.runtimeConfig), normalizedAdapterConfig);
         await assertAgentEnvironmentSelection(companyId, createInput.adapterType, createInput.defaultEnvironmentId);
         await assertAgentDefaultEnvironmentSelection(companyId, createInput.defaultEnvironmentId, {
             allowedDrivers: allowedEnvironmentDriversForAgent(createInput.adapterType),
@@ -1347,12 +1586,12 @@ export function agentRoutes(db, options = {}) {
         const createdAgent = await svc.create(companyId, {
             ...createInput,
             adapterConfig: normalizedAdapterConfig,
-            runtimeConfig: normalizeNewAgentRuntimeConfig(createInput.runtimeConfig),
+            runtimeConfig: normalizedRuntimeConfig,
             status: "idle",
             spentMonthlyCents: 0,
             lastHeartbeatAt: null,
         });
-        const agent = await materializeDefaultInstructionsBundleForNewAgent(createdAgent);
+        const agent = await materializeDefaultInstructionsBundleForNewAgent(createdAgent, instructionsBundle);
         const actor = getActorInfo(req);
         await logActivity(db, {
             companyId,
@@ -1646,9 +1885,8 @@ export function agentRoutes(db, options = {}) {
                 res.status(422).json({ error: "adapterConfig must be an object" });
                 return;
             }
-            assertNoAgentInstructionsConfigMutation(req, adapterConfig);
-            assertNoAgentHostWorkspaceCommandMutation(req, collectAgentAdapterWorkspaceCommandPaths(adapterConfig));
-            const changingInstructionsConfig = Object.keys(adapterConfig).some((key) => KNOWN_INSTRUCTIONS_BUNDLE_KEYS.includes(key));
+            assertNoAgentAdapterConfigMutation(req, adapterConfig);
+            const changingInstructionsConfig = adapterConfigTouchesInstructionsConfig(adapterConfig);
             if (changingInstructionsConfig) {
                 await assertCanManageInstructionsPath(req, existing);
             }
@@ -1657,6 +1895,16 @@ export function agentRoutes(db, options = {}) {
         const requestedAdapterType = hasOwn(patchData, "adapterType")
             ? assertKnownAdapterType(patchData.adapterType)
             : existing.adapterType;
+        let requestedRuntimeConfig = null;
+        if (hasOwn(patchData, "runtimeConfig")) {
+            const runtimeConfig = asRecord(patchData.runtimeConfig);
+            if (!runtimeConfig) {
+                res.status(422).json({ error: "runtimeConfig must be an object" });
+                return;
+            }
+            assertNoAgentRuntimeConfigAdapterConfigMutation(req, runtimeConfig);
+            requestedRuntimeConfig = runtimeConfig;
+        }
         const touchesAdapterConfiguration = hasOwn(patchData, "adapterType") ||
             hasOwn(patchData, "adapterConfig");
         if (touchesAdapterConfiguration) {
@@ -1690,12 +1938,16 @@ export function agentRoutes(db, options = {}) {
                 rawEffectiveAdapterConfig = preserveInstructionsBundleConfig(existingAdapterConfig, rawEffectiveAdapterConfig);
             }
             const effectiveAdapterConfig = applyCreateDefaultsByAdapterType(requestedAdapterType, rawEffectiveAdapterConfig);
-            const normalizedEffectiveAdapterConfig = await secretsSvc.normalizeAdapterConfigForPersistence(existing.companyId, effectiveAdapterConfig, { strictMode: strictSecretsMode });
+            const normalizedEffectiveAdapterConfig = await normalizeMediatedAdapterConfigForPersistence({
+                companyId: existing.companyId,
+                adapterType: requestedAdapterType,
+                adapterConfig: effectiveAdapterConfig,
+            });
             patchData.adapterConfig = syncInstructionsBundleConfigFromFilePath(existing, normalizedEffectiveAdapterConfig);
         }
-        if (touchesAdapterConfiguration && requestedAdapterType === "opencode_local") {
-            const effectiveAdapterConfig = asRecord(patchData.adapterConfig) ?? {};
-            await assertAdapterConfigConstraints(existing.companyId, requestedAdapterType, effectiveAdapterConfig);
+        if (requestedRuntimeConfig) {
+            const baseAdapterConfig = asRecord(patchData.adapterConfig) ?? asRecord(existing.adapterConfig) ?? {};
+            patchData.runtimeConfig = await normalizeRuntimeConfigAdapterConfigsForPersistence(existing.companyId, requestedAdapterType, requestedRuntimeConfig, baseAdapterConfig);
         }
         if (touchesAdapterConfiguration || Object.prototype.hasOwnProperty.call(patchData, "defaultEnvironmentId")) {
             await assertAgentDefaultEnvironmentSelection(existing.companyId, Object.prototype.hasOwnProperty.call(patchData, "defaultEnvironmentId")
@@ -2042,14 +2294,21 @@ export function agentRoutes(db, options = {}) {
     router.get("/companies/:companyId/live-runs", async (req, res) => {
         const companyId = req.params.companyId;
         assertCompanyAccess(req, companyId);
-        const minCount = readLiveRunsQueryInt(req.query.minCount, 50);
-        const limit = readLiveRunsQueryInt(req.query.limit, 50);
+        // `minCount` is a padding floor for callers that want a minimum number of
+        // recent runs to render (e.g. dashboard cards). It must default to 0 so
+        // callers asking for "live runs" get only actually-live runs — otherwise
+        // every caller with no minCount param gets up to 50 historical runs
+        // padded in and renders bogus "live" counts.
+        const minCount = readLiveRunsQueryInt(req.query.minCount, 50, 0);
+        const limit = readLiveRunsQueryInt(req.query.limit, 50, 50);
         const columns = {
             id: heartbeatRuns.id,
             companyId: heartbeatRuns.companyId,
             status: heartbeatRuns.status,
             invocationSource: heartbeatRuns.invocationSource,
             triggerDetail: heartbeatRuns.triggerDetail,
+            contextCommentId: sql `${heartbeatRuns.contextSnapshot} ->> 'commentId'`.as("contextCommentId"),
+            contextWakeCommentId: sql `${heartbeatRuns.contextSnapshot} ->> 'wakeCommentId'`.as("contextWakeCommentId"),
             startedAt: heartbeatRuns.startedAt,
             finishedAt: heartbeatRuns.finishedAt,
             createdAt: heartbeatRuns.createdAt,
@@ -2075,8 +2334,8 @@ export function agentRoutes(db, options = {}) {
             .innerJoin(agentsTable, eq(heartbeatRuns.agentId, agentsTable.id))
             .where(and(eq(heartbeatRuns.companyId, companyId), inArray(heartbeatRuns.status, ["queued", "running"])))
             .orderBy(desc(heartbeatRuns.createdAt));
-        const liveRuns = limit > 0 ? await liveRunsQuery.limit(limit) : await liveRunsQuery;
-        const targetRunCount = limit > 0 ? Math.min(minCount, limit) : minCount;
+        const liveRuns = await liveRunsQuery.limit(limit);
+        const targetRunCount = Math.min(minCount, limit);
         if (targetRunCount > 0 && liveRuns.length < targetRunCount) {
             const activeIds = liveRuns.map((r) => r.id);
             const recentRuns = await db
@@ -2231,8 +2490,8 @@ export function agentRoutes(db, options = {}) {
     router.get("/issues/:issueId/live-runs", async (req, res) => {
         const rawId = req.params.issueId;
         const issueSvc = issueService(db);
-        const isIdentifier = /^[A-Z]+-\d+$/i.test(rawId);
-        const issue = isIdentifier ? await issueSvc.getByIdentifier(rawId) : await issueSvc.getById(rawId);
+        const identifier = normalizeIssueIdentifier(rawId);
+        const issue = identifier ? await issueSvc.getByIdentifier(identifier) : await issueSvc.getById(rawId);
         if (!issue) {
             res.status(404).json({ error: "Issue not found" });
             return;
@@ -2244,6 +2503,8 @@ export function agentRoutes(db, options = {}) {
             status: heartbeatRuns.status,
             invocationSource: heartbeatRuns.invocationSource,
             triggerDetail: heartbeatRuns.triggerDetail,
+            contextCommentId: sql `${heartbeatRuns.contextSnapshot} ->> 'commentId'`.as("contextCommentId"),
+            contextWakeCommentId: sql `${heartbeatRuns.contextSnapshot} ->> 'wakeCommentId'`.as("contextWakeCommentId"),
             startedAt: heartbeatRuns.startedAt,
             finishedAt: heartbeatRuns.finishedAt,
             createdAt: heartbeatRuns.createdAt,
@@ -2274,8 +2535,8 @@ export function agentRoutes(db, options = {}) {
     router.get("/issues/:issueId/active-run", async (req, res) => {
         const rawId = req.params.issueId;
         const issueSvc = issueService(db);
-        const isIdentifier = /^[A-Z]+-\d+$/i.test(rawId);
-        const issue = isIdentifier ? await issueSvc.getByIdentifier(rawId) : await issueSvc.getById(rawId);
+        const identifier = normalizeIssueIdentifier(rawId);
+        const issue = identifier ? await issueSvc.getByIdentifier(identifier) : await issueSvc.getById(rawId);
         if (!issue) {
             res.status(404).json({ error: "Issue not found" });
             return;