Add cheap model profiles for local adapters (#4881)

## Thinking Path

> - Paperclip is a control plane for autonomous AI companies, where
adapters are the boundary between the board, agents, and execution
runtimes.
> - Local adapters currently expose a primary runtime configuration, but
operators often need a cheaper model lane for routine or low-risk work.
> - That cheap lane has to stay adapter-owned: runtime profile settings
should not mutate the primary adapter config or bypass existing
auth/secret mediation.
> - Issue creation also needs an ergonomic way to request primary,
cheap, or custom model behavior for a selected assignee.
> - This pull request adds a first-class `cheap` model profile contract
across adapter capabilities, heartbeat config resolution, agent
configuration, and issue creation.
> - The benefit is cheaper task execution can be configured and
requested explicitly while preserving adapter boundaries, secret
handling, and audit visibility.

## What Changed

- Added adapter model-profile capability metadata and a `cheap` profile
contract for supported local adapters.
- Applied `runtimeConfig.modelProfiles.cheap.adapterConfig` during
heartbeat config resolution, including requested/applied/fallback run
metadata.
- Added agent configuration UI for cheap model profile settings without
writing those settings into primary `adapterConfig`.
- Added New Issue assignee model lane controls for Primary / Cheap /
Custom and request payload handling.
- Added run ledger profile badges and Storybook stories for the new
cheap-lane UI states.
- Added tests for validators, heartbeat model profile application,
permission/secret mediation, UI payload helpers, and run ledger
rendering.
- Added committed UI verification screenshots under
`docs/pr-screenshots/pap-2837/`.
- Addressed Greptile review feedback around cheap-profile defaults,
shared profile types, and fallback test data.

## Verification

Local:

- `pnpm exec vitest run packages/shared/src/validators/issue.test.ts
server/src/__tests__/adapter-registry.test.ts
server/src/__tests__/agent-permissions-routes.test.ts
server/src/__tests__/heartbeat-model-profile.test.ts
ui/src/components/IssueRunLedger.test.tsx
ui/src/lib/agent-config-patch.test.ts
ui/src/lib/issue-assignee-overrides.test.ts
ui/src/lib/new-agent-runtime-config.test.ts` — passed, 8 files / 103
tests.
- `pnpm exec vitest run ui/src/lib/new-agent-runtime-config.test.ts
ui/src/components/IssueRunLedger.test.tsx` — passed after
Greptile/rebase follow-up, 2 files / 17 tests.
- `pnpm --filter @paperclipai/ui typecheck` — passed after
Greptile/rebase follow-up.
- `pnpm -r typecheck` — passed.
- `pnpm build` — passed.
- `pnpm test:run` — did not complete successfully in this local
worktree: it stopped in pre-existing `@paperclipai/adapter-utils`
sandbox/SSH fixture suites outside this PR diff. Failures were 5s local
timeouts plus `git init -b` unsupported by this machine's Git 2.21.0.
The branch-specific targeted suites above passed.
- Branch was fetched/rebased onto `public-gh/master`; `git rev-list
--left-right --count public-gh/master...HEAD` reports `0 9`.

Remote PR checks on latest head
`e30bf399146451c86cee98ed528d51d33fa5af5a`:

- `policy` — passed.
- `verify` — passed.
- `e2e` — passed.
- `Greptile Review` — passed, confidence score 5/5; Greptile review
threads resolved.
- `security/snyk (cryppadotta)` — passed.

Screenshots:

- [New issue cheap lane
desktop](https://github.com/paperclipai/paperclip/blob/PAP-2837-plan-cheap-model-for-adapters-that-can-support-it/docs/pr-screenshots/pap-2837/newissue-cheap-desktop.png)
- [New issue custom lane
desktop](https://github.com/paperclipai/paperclip/blob/PAP-2837-plan-cheap-model-for-adapters-that-can-support-it/docs/pr-screenshots/pap-2837/newissue-custom-desktop.png)
- [New issue unsupported adapter
desktop](https://github.com/paperclipai/paperclip/blob/PAP-2837-plan-cheap-model-for-adapters-that-can-support-it/docs/pr-screenshots/pap-2837/newissue-unsupported-desktop.png)
- [Run ledger model profile badges
desktop](https://github.com/paperclipai/paperclip/blob/PAP-2837-plan-cheap-model-for-adapters-that-can-support-it/docs/pr-screenshots/pap-2837/runledger-profile-badges-desktop.png)
- Mobile variants are also in `docs/pr-screenshots/pap-2837/`.

## Risks

- Medium: heartbeat config mediation now merges runtime model profiles
into adapter configs, so adapter secret normalization and host-command
restrictions must keep covering nested config paths.
- Medium: the UI adds another issue creation choice; unsupported
adapters must keep hiding the cheap lane and preserve primary behavior.
- Low migration risk: no database migration is included.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

OpenAI Codex coding agent using GPT-5-class reasoning with repo tool use
and command execution. Exact served model/context window was not exposed
by the runtime.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [ ] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] If this change affects the UI, I have included before/after
screenshots
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

ui/src/lib/agent-config-patch.test.ts

@@ -77,6 +77,92 @@ describe("buildAgentUpdatePatch", () => {
     });
   });
 
+  it("writes the cheap profile under runtimeConfig.modelProfiles, never on primary adapterConfig", () => {
+    const patch = buildAgentUpdatePatch(
+      makeAgent(),
+      makeOverlay({
+        modelProfiles: {
+          cheap: {
+            enabled: true,
+            adapterConfig: { model: "claude-haiku-4-5" },
+          },
+        },
+      }),
+    );
+
+    expect(patch).toEqual({
+      runtimeConfig: {
+        heartbeat: {
+          enabled: true,
+          intervalSec: 300,
+        },
+        modelProfiles: {
+          cheap: {
+            enabled: true,
+            adapterConfig: { model: "claude-haiku-4-5" },
+          },
+        },
+      },
+    });
+    // The primary adapterConfig is untouched.
+    expect(patch.adapterConfig).toBeUndefined();
+  });
+
+  it("merges cheap profile changes onto existing runtimeConfig.modelProfiles state", () => {
+    const agent = makeAgent();
+    agent.runtimeConfig = {
+      heartbeat: { enabled: true, intervalSec: 300 },
+      modelProfiles: {
+        cheap: {
+          enabled: false,
+          adapterConfig: { model: "old-cheap" },
+        },
+      },
+    };
+
+    const patch = buildAgentUpdatePatch(
+      agent,
+      makeOverlay({
+        modelProfiles: {
+          cheap: {
+            enabled: true,
+          },
+        },
+      }),
+    );
+
+    expect((patch.runtimeConfig as Record<string, unknown>).modelProfiles).toEqual({
+      cheap: {
+        enabled: true,
+        adapterConfig: { model: "old-cheap" },
+      },
+    });
+  });
+
+  it("clears the cheap profile when the overlay marks it cleared", () => {
+    const agent = makeAgent();
+    agent.runtimeConfig = {
+      heartbeat: { enabled: true, intervalSec: 300 },
+      modelProfiles: {
+        cheap: {
+          enabled: true,
+          adapterConfig: { model: "claude-haiku-4-5" },
+        },
+      },
+    };
+
+    const patch = buildAgentUpdatePatch(
+      agent,
+      makeOverlay({
+        modelProfiles: { cheap: { cleared: true } },
+      }),
+    );
+
+    expect(patch.runtimeConfig).toEqual({
+      heartbeat: { enabled: true, intervalSec: 300 },
+    });
+  });
+
   it("preserves adapter-agnostic keys when changing adapter types", () => {
     const patch = buildAgentUpdatePatch(
       makeAgent(),

ui/src/lib/agent-config-patch.ts

@@ -1,11 +1,22 @@
 import type { Agent } from "@paperclipai/shared";
 
+export interface AgentModelProfileOverlay {
+  enabled?: boolean;
+  adapterConfig?: Record<string, unknown>;
+  /**
+   * Mark the cheap profile for clearing. When true, the patch removes
+   * `runtimeConfig.modelProfiles.cheap` instead of merging into it.
+   */
+  cleared?: boolean;
+}
+
 export interface AgentConfigOverlay {
   identity: Record<string, unknown>;
   adapterType?: string;
   adapterConfig: Record<string, unknown>;
   heartbeat: Record<string, unknown>;
   runtime: Record<string, unknown>;
+  modelProfiles?: { cheap?: AgentModelProfileOverlay };
 }
 
 const ADAPTER_AGNOSTIC_KEYS = [
@@ -56,10 +67,47 @@ export function buildAgentUpdatePatch(agent: Agent, overlay: AgentConfigOverlay)
     patch.replaceAdapterConfig = true;
   }
 
-  if (Object.keys(overlay.heartbeat).length > 0) {
+  const cheapOverlay = overlay.modelProfiles?.cheap;
+  const hasModelProfileChange = cheapOverlay !== undefined;
+
+  if (Object.keys(overlay.heartbeat).length > 0 || hasModelProfileChange) {
     const existingRc = (agent.runtimeConfig ?? {}) as Record<string, unknown>;
-    const existingHb = (existingRc.heartbeat ?? {}) as Record<string, unknown>;
-    patch.runtimeConfig = { ...existingRc, heartbeat: { ...existingHb, ...overlay.heartbeat } };
+    const nextRuntimeConfig: Record<string, unknown> = (patch.runtimeConfig as Record<string, unknown> | undefined)
+      ?? { ...existingRc };
+
+    if (Object.keys(overlay.heartbeat).length > 0) {
+      const existingHb = (existingRc.heartbeat ?? {}) as Record<string, unknown>;
+      nextRuntimeConfig.heartbeat = { ...existingHb, ...overlay.heartbeat };
+    }
+
+    if (hasModelProfileChange) {
+      const existingProfiles = ((existingRc.modelProfiles ?? {}) as Record<string, unknown>);
+      const existingCheap = ((existingProfiles.cheap ?? {}) as Record<string, unknown>);
+      const nextProfiles = { ...existingProfiles };
+
+      if (cheapOverlay?.cleared) {
+        delete nextProfiles.cheap;
+      } else if (cheapOverlay) {
+        const mergedAdapterConfig = {
+          ...((existingCheap.adapterConfig ?? {}) as Record<string, unknown>),
+          ...(cheapOverlay.adapterConfig ?? {}),
+        };
+        const enabled = cheapOverlay.enabled ?? (existingCheap.enabled !== false);
+        nextProfiles.cheap = {
+          ...existingCheap,
+          enabled,
+          adapterConfig: mergedAdapterConfig,
+        };
+      }
+
+      if (Object.keys(nextProfiles).length === 0) {
+        delete nextRuntimeConfig.modelProfiles;
+      } else {
+        nextRuntimeConfig.modelProfiles = nextProfiles;
+      }
+    }
+
+    patch.runtimeConfig = nextRuntimeConfig;
   }
 
   if (Object.keys(overlay.runtime).length > 0) {

ui/src/lib/issue-assignee-overrides.test.ts

@@ -0,0 +1,97 @@
+// @vitest-environment node
+
+import { describe, expect, it } from "vitest";
+import { buildAssigneeAdapterOverrides } from "./issue-assignee-overrides";
+
+describe("buildAssigneeAdapterOverrides", () => {
+  it("returns null for adapters that do not accept issue overrides", () => {
+    expect(
+      buildAssigneeAdapterOverrides({
+        adapterType: "process",
+        lane: "custom",
+        modelOverride: "anything",
+        thinkingEffortOverride: "high",
+        chrome: true,
+      }),
+    ).toBeNull();
+  });
+
+  it("primary lane sends nothing", () => {
+    expect(
+      buildAssigneeAdapterOverrides({
+        adapterType: "claude_local",
+        lane: "primary",
+        modelOverride: "",
+        thinkingEffortOverride: "",
+        chrome: false,
+      }),
+    ).toBeNull();
+  });
+
+  it("cheap lane sends modelProfile=cheap and no adapterConfig", () => {
+    expect(
+      buildAssigneeAdapterOverrides({
+        adapterType: "codex_local",
+        lane: "cheap",
+        modelOverride: "ignored",
+        thinkingEffortOverride: "high",
+        chrome: false,
+      }),
+    ).toEqual({ modelProfile: "cheap" });
+  });
+
+  it("custom lane preserves explicit model + thinking effort + chrome overrides", () => {
+    expect(
+      buildAssigneeAdapterOverrides({
+        adapterType: "claude_local",
+        lane: "custom",
+        modelOverride: "claude-haiku-4-5",
+        thinkingEffortOverride: "high",
+        chrome: true,
+      }),
+    ).toEqual({
+      adapterConfig: {
+        model: "claude-haiku-4-5",
+        effort: "high",
+        chrome: true,
+      },
+    });
+  });
+
+  it("custom lane returns null when no fields are set", () => {
+    expect(
+      buildAssigneeAdapterOverrides({
+        adapterType: "codex_local",
+        lane: "custom",
+        modelOverride: "",
+        thinkingEffortOverride: "",
+        chrome: false,
+      }),
+    ).toBeNull();
+  });
+
+  it("custom lane uses adapter-specific keys for thinking effort", () => {
+    expect(
+      buildAssigneeAdapterOverrides({
+        adapterType: "codex_local",
+        lane: "custom",
+        modelOverride: "",
+        thinkingEffortOverride: "minimal",
+        chrome: false,
+      }),
+    ).toEqual({
+      adapterConfig: { modelReasoningEffort: "minimal" },
+    });
+    expect(
+      buildAssigneeAdapterOverrides({
+        adapterType: "opencode_local",
+        lane: "custom",
+        modelOverride: "",
+        thinkingEffortOverride: "max",
+        chrome: false,
+      }),
+    ).toEqual({
+      adapterConfig: { variant: "max" },
+    });
+  });
+});

ui/src/lib/issue-assignee-overrides.ts

@@ -0,0 +1,60 @@
+export const ISSUE_OVERRIDE_ADAPTER_TYPES = new Set([
+  "claude_local",
+  "codex_local",
+  "opencode_local",
+]);
+
+export type IssueModelLane = "primary" | "cheap" | "custom";
+
+export interface BuildAssigneeAdapterOverridesInput {
+  adapterType: string | null | undefined;
+  lane: IssueModelLane;
+  modelOverride: string;
+  thinkingEffortOverride: string;
+  chrome: boolean;
+}
+
+/**
+ * Build the `assigneeAdapterOverrides` payload sent to the issue create API.
+ *
+ * Lane semantics:
+ * - "primary" → no overrides, runs on the agent's primary model.
+ * - "cheap"   → `modelProfile: "cheap"` only; the runtime resolves the actual
+ *               adapter config from the agent's runtimeConfig + adapter default.
+ * - "custom"  → preserves the legacy explicit override path
+ *               (`adapterConfig.model`, thinking effort, chrome).
+ */
+export function buildAssigneeAdapterOverrides(
+  input: BuildAssigneeAdapterOverridesInput,
+): Record<string, unknown> | null {
+  const adapterType = input.adapterType ?? null;
+  if (!adapterType || !ISSUE_OVERRIDE_ADAPTER_TYPES.has(adapterType)) {
+    return null;
+  }
+
+  if (input.lane === "primary") {
+    return null;
+  }
+
+  if (input.lane === "cheap") {
+    return { modelProfile: "cheap" };
+  }
+
+  const adapterConfig: Record<string, unknown> = {};
+  if (input.modelOverride) adapterConfig.model = input.modelOverride;
+  if (input.thinkingEffortOverride) {
+    if (adapterType === "codex_local") {
+      adapterConfig.modelReasoningEffort = input.thinkingEffortOverride;
+    } else if (adapterType === "opencode_local") {
+      adapterConfig.variant = input.thinkingEffortOverride;
+    } else if (adapterType === "claude_local") {
+      adapterConfig.effort = input.thinkingEffortOverride;
+    }
+  }
+  if (adapterType === "claude_local" && input.chrome) {
+    adapterConfig.chrome = true;
+  }
+
+  if (Object.keys(adapterConfig).length === 0) return null;
+  return { adapterConfig };
+}

ui/src/lib/new-agent-hire-payload.ts

@@ -32,6 +32,8 @@ export function buildNewAgentHirePayload(input: {
     runtimeConfig: buildNewAgentRuntimeConfig({
       heartbeatEnabled: configValues.heartbeatEnabled,
       intervalSec: configValues.intervalSec,
+      cheapModel: configValues.cheapModel,
+      cheapModelEnabled: configValues.cheapModelEnabled,
     }),
     budgetMonthlyCents: 0,
   };

ui/src/lib/new-agent-runtime-config.test.ts

@@ -31,4 +31,35 @@ describe("buildNewAgentRuntimeConfig", () => {
       },
     });
   });
+
+  it("stores cheap model under modelProfiles.cheap, not primary adapterConfig", () => {
+    const config = buildNewAgentRuntimeConfig({
+      heartbeatEnabled: true,
+      intervalSec: 600,
+      cheapModel: "claude-sonnet-4-6",
+      cheapModelEnabled: true,
+    });
+
+    expect(config.modelProfiles).toEqual({
+      cheap: {
+        enabled: true,
+        adapterConfig: { model: "claude-sonnet-4-6" },
+      },
+    });
+    // primary heartbeat config still present
+    expect(config.heartbeat).toMatchObject({ enabled: true, intervalSec: 600 });
+  });
+
+  it("omits modelProfiles when no cheap model is configured", () => {
+    const config = buildNewAgentRuntimeConfig({ heartbeatEnabled: false });
+    expect(config.modelProfiles).toBeUndefined();
+  });
+
+  it("omits modelProfiles when cheap model is set but explicitly disabled", () => {
+    const config = buildNewAgentRuntimeConfig({
+      cheapModel: "claude-sonnet-4-6",
+      cheapModelEnabled: false,
+    });
+    expect(config.modelProfiles).toBeUndefined();
+  });
 });

ui/src/lib/new-agent-runtime-config.ts

@@ -4,8 +4,10 @@ import { defaultCreateValues } from "../components/agent-config-defaults";
 export function buildNewAgentRuntimeConfig(input?: {
   heartbeatEnabled?: boolean;
   intervalSec?: number;
-}) {
-  return {
+  cheapModel?: string;
+  cheapModelEnabled?: boolean;
+}): Record<string, unknown> {
+  const config: Record<string, unknown> = {
     heartbeat: {
       enabled: input?.heartbeatEnabled ?? defaultCreateValues.heartbeatEnabled,
       intervalSec: input?.intervalSec ?? defaultCreateValues.intervalSec,
@@ -14,4 +16,17 @@ export function buildNewAgentRuntimeConfig(input?: {
       maxConcurrentRuns: AGENT_DEFAULT_MAX_CONCURRENT_RUNS,
     },
   };
+
+  const cheapModel = input?.cheapModel?.trim() ?? "";
+  const cheapEnabled = input?.cheapModelEnabled ?? false;
+  if (cheapModel && cheapEnabled) {
+    config.modelProfiles = {
+      cheap: {
+        enabled: true,
+        adapterConfig: { model: cheapModel },
+      },
+    };
+  }
+
+  return config;
 }

ui/src/lib/queryKeys.ts

@@ -25,6 +25,8 @@ export const queryKeys = {
     configRevisions: (agentId: string) => ["agents", "config-revisions", agentId] as const,
     adapterModels: (companyId: string, adapterType: string) =>
       ["agents", companyId, "adapter-models", adapterType] as const,
+    adapterModelProfiles: (companyId: string, adapterType: string) =>
+      ["agents", companyId, "adapter-model-profiles", adapterType] as const,
     detectModel: (companyId: string, adapterType: string) =>
       ["agents", companyId, "detect-model", adapterType] as const,
   },