feat: agent baseUrl & model passthrough

[dean0x]

Summary

• Add baseUrl and model fields to per-agent configuration (~/.autobeat/config.json), enabling custom API endpoints and model selection for Claude Code, Codex CLI, and Gemini CLI
• Thread model through the entire task lifecycle: domain types → MCP tools → CLI → spawn pipeline → database persistence (migration v16)
• Inject baseUrl as the provider-specific env var (ANTHROPIC_BASE_URL, OPENAI_BASE_URL, GEMINI_BASE_URL) at spawn time with user env var precedence
• Auto-disable Claude Code experimental beta headers when a custom baseUrl is configured (prevents proxy failures)
• Add --model/-m flag to beat run and beat orchestrate CLI commands
• Extend ConfigureAgent and ListAgents MCP tools with baseUrl/model support, including Claude-specific warning when baseUrl is set without an API key

Test plan

• Build compiles cleanly (npm run build)
• 1,546 tests passing across all grouped test suites
• Agent config: round-trip save/load for baseUrl/model, no field clobbering, empty string clears key, trailing slash normalized
• Agent adapters: baseUrl env var injection per adapter, user env precedence, --model flag in args, config model fallback, per-task model override, Claude experimental betas auto-disable
• Task repository: save/load task with model field, backward compat for null model
• MCP adapter: DelegateTask/ConfigureAgent/ListAgents with model and baseUrl, Claude warning when baseUrl set without apiKey
• CLI: --model flag parsing on beat run and beat orchestrate
• Manual: beat agents config set claude baseUrl https://proxy.example.com → verify shown in beat agents config show claude
• Manual: beat run --model claude-sonnet-4-6 "hello" → verify --model in spawned args

[greptile-apps]

Greptile Summary

This PR threads baseUrl and model configuration through the full autobeat stack — agent config file, domain types, MCP tools, CLI flags, the spawn pipeline, and SQLite persistence (migration v16). The implementation is thorough and well-tested (dedicated test suites for agent-config round-trips, adapter env/arg injection, task-repository persistence, and MCP tool responses).

Key changes:

• AgentConfig gains baseUrl and model; saveAgentConfig normalises trailing slashes and treats empty string as a delete
• BaseAgentAdapter.resolveBaseUrl() / resolveModel() implement the correct resolution order (per-task > agent-config > CLI default) with user-env-var precedence for baseUrl
• ClaudeAdapter overrides resolveBaseUrl to auto-set CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 when a base URL is active, preventing proxy failures
• AGENT_BASE_URL_ENV provides a single source of truth for provider → env-var mapping
• Migration v16 adds a nullable model TEXT column to tasks with correct backward compatibility (null → undefined)
• Two minor style findings: ClaudeProcessSpawner silently discards _model (safe today but a latent trap), and the 'baseUrl cleared'/'model cleared' message branches in the MCP set handler are unreachable through the MCP path due to Zod's url()/min(1) validators

Confidence Score: 5/5

Safe to merge — all remaining findings are P2 style/cleanup items with no correctness or data-integrity impact.

The feature is fully implemented end-to-end with correct precedence logic, env-var safety, backward-compatible migration, and comprehensive tests (1,546 passing). The two findings are both P2: one is a latent trap in a class confirmed unused in the production path, and the other is unreachable dead code in a message-building branch. Neither affects current behaviour.

src/implementations/process-spawner.ts (model silently discarded), src/adapters/mcp-adapter.ts (dead message branches)

Important Files Changed

Filename	Overview
src/implementations/base-agent-adapter.ts	Adds resolveBaseUrl() and resolveModel() helpers; threads both into spawn() with correct env-var/config precedence ordering.
src/implementations/claude-adapter.ts	Overrides resolveBaseUrl() to auto-inject CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 when a base URL is active; logic is sound and stripping order is correct.
src/implementations/process-spawner.ts	Signature updated to accept _model but the parameter is silently ignored; confirmed unused in the production agentRegistry path but the discard is not obvious from the call site.
src/adapters/mcp-adapter.ts	Model field added to all schemas and threaded through correctly; the 'baseUrl cleared' / 'model cleared' message branches in the set action are unreachable dead code due to Zod validation.
src/core/configuration.ts	Extends AgentConfig with baseUrl/model; saveAgentConfig now handles empty-string-as-delete and trailing-slash normalisation correctly.
src/implementations/database.ts	Migration v16 adds nullable model TEXT column to tasks; backward-compatible and correctly placed in the migration sequence.
src/implementations/task-repository.ts	model column added to all SELECT/INSERT/UPDATE statements and the Zod row schema; null → undefined coercion on read is correct.
src/core/domain.ts	Model field added to Task, TaskRequest, and all schedule/pipeline/loop/orchestration request types; createTask and createOrchestration correctly propagate it.
src/services/orchestration-manager.ts	Correctly spreads model into loop creation only when defined (!== undefined guard prevents accidental undefined spread).
src/core/agents.ts	Adds AGENT_BASE_URL_ENV map as the single source of truth for provider-to-env-var mapping; spawn signature updated with optional model param.

Sequence Diagram

sequenceDiagram
    participant CLI as beat run / MCP tool
    participant TM as TaskManager
    participant Repo as TaskRepository (DB)
    participant WP as EventDrivenWorkerPool
    participant Reg as AgentRegistry
    participant Adapter as ClaudeAdapter / CodexAdapter / GeminiAdapter
    participant Proc as Child Process

    CLI->>TM: delegate(TaskRequest { model? })
    TM->>Repo: save(Task { model? })
    Note over Repo: migration v16 — model TEXT column
    TM->>WP: enqueue(task)

    WP->>Reg: getAdapter(task.agent)
    Reg-->>WP: AgentAdapter
    WP->>Adapter: spawn(prompt, cwd, taskId, task.model)

    Note over Adapter: resolveModel(taskModel)<br/>1. per-task model<br/>2. agentConfig.model<br/>3. CLI default (none)

    Note over Adapter: resolveBaseUrl()<br/>1. user env var (skip inject)<br/>2. agentConfig.baseUrl

    Adapter->>Adapter: buildArgs(prompt, resolvedModel)<br/>e.g. [--model, claude-opus-4-5, --, prompt]
    Adapter->>Proc: spawn(cmd, args, { env: {ANTHROPIC_BASE_URL?, ...} })

Loading

Comments Outside Diff (1)

1. src/adapters/mcp-adapter.ts, line 418-429 (link)

   Dead code: 'baseUrl cleared' and 'model cleared' message branches are unreachable via MCP

   Because ConfigureAgentSchema validates baseUrl with z.string().url() (rejects empty strings) and model with z.string().min(1) (rejects empty strings), neither value can ever be an empty/falsy string after parseResult.data is destructured. The ternary's false-branch in each push:

   messages.push(baseUrl ? `baseUrl set to ${baseUrl}` : 'baseUrl cleared');
   // ...
   messages.push(model ? `model set to ${model}` : 'model cleared');

   …can never be reached through the MCP set action. The 'baseUrl cleared' / 'model cleared' paths are only reachable through saveAgentConfig directly (e.g. the CLI path, which permits empty strings). Consider simplifying to unconditional strings here, or adding a comment explaining that these branches are unreachable from MCP but kept for potential direct callers:

   messages.push(`baseUrl set to ${baseUrl}`);
   // ...
   messages.push(`model set to ${model}`);

_{Reviews (1): Last reviewed commit: "fix: shepherd review fixes — model threa..." | Re-trigger Greptile}

[greptile-apps]

_model silently dropped in ClaudeProcessSpawner

ClaudeProcessSpawner accepts the model parameter but discards it entirely. This is confirmed safe today — bootstrap.ts registers this class as the processSpawner service but that service is never retrieved by any production consumer (the agentRegistry uses ClaudeAdapter directly). However, the silent discard creates a trap: if ClaudeProcessSpawner is ever re-wired into a live spawn path, tasks that specify a model will silently use the CLI's default model instead of the requested one, with no error or warning.

Consider either:

• Adding a TODO/FIXME comment that explicitly documents the model is intentionally not forwarded, or
• Implementing it the same way ClaudeAdapter.buildArgs does (['--model', model]) so the class is a complete implementation of the updated interface.

[dean0x]

Code Review Findings

I've analyzed the code review reports and identified blocking issues requiring attention before merge:

CRITICAL (5 issues - 95% confidence)

• Model field silently dropped on DB roundtrip for loops, schedules, and pipelines
• Orchestration model field not persisted to database

HIGH (6 issues - 80-92% confidence)

• Repeated loadAgentConfig() calls (3x per spawn)
• JSON Schema validation inconsistent for model field
• Partial-write risk in ConfigureAgent set action
• Missing baseUrl validation in CLI path
• Duplicate test blocks in test file

Posting inline comments on specific files now.

[dean0x]

BLOCKING ISSUES (80%+ confidence)

CRITICAL (95% confidence)

1. Model field stripped on DB roundtrip (4 locations)

Files affected:

• (TaskRequestSchema)
• (TaskRequestSchema)
• (PipelineStepsSchema)
• (LoopConfigSchema)

The model field is not included in these Zod boundary schemas. When data is persisted to the database and then loaded back, Zod's .parse() strips unknown keys, causing model to be silently lost. This breaks per-task model overrides for:

• Loops after server restart or recovery
• Scheduled tasks after persistence roundtrip
• Scheduled pipeline steps
• Scheduled loop iterations

Fix: Add model: z.string().optional() to each schema:

// TaskRequestSchema
agent: z.enum(AGENT_PROVIDERS_TUPLE).optional(),
model: z.string().optional(),

// PipelineStepsSchema (within step object)
agent: z.enum(AGENT_PROVIDERS_TUPLE).optional(),
model: z.string().optional(),

// LoopConfigSchema
agent: z.enum(AGENT_PROVIDERS_TUPLE).optional(),
model: z.string().optional(),

2. Orchestration model not persisted to database

Files affected:

• src/implementations/orchestration-repository.ts:25-58 (OrchestrationRowSchema, OrchestrationRow)
• src/implementations/orchestration-repository.ts:279-314 (toRow/rowToOrchestration methods)
• src/implementations/database.ts (no migration for model column)

The Orchestration domain type includes model?: string but:

1. No database migration adds a model column to the orchestrations table
2. OrchestrationRowSchema, OrchestrationRow, toRow(), and rowToOrchestration() don't include model

Result: model is in-memory only and lost on persistence. After server restart, OrchestratorStatus and beat orchestrate status will never show the model.

Fixes required:

1. Add migration v17 in database.ts: ALTER TABLE orchestrations ADD COLUMN model TEXT
2. Add model: z.string().nullable() to OrchestrationRowSchema
3. Add readonly model: string | null to OrchestrationRow interface
4. Update toRow(): add model: orchestration.model ?? null
5. Update rowToOrchestration(): add model: data.model ?? undefined
6. Add model to INSERT and UPDATE SQL statements

---

HIGH (80-92% confidence)

3. loadAgentConfig() called 3x per spawn

File: src/implementations/base-agent-adapter.ts:76, 103, 116

Each spawn() invocation calls loadAgentConfig() three times:

• Line 76: in resolveAuth()
• Line 103: in resolveBaseUrl()
• Line 116: in resolveModel()

Each call reads ~/.autobeat/config.json from disk and parses JSON. Under concurrent task delegation (multiple workers spawning in parallel), this triples disk I/O.

Fix: Load config once at the start of spawn() and pass it to all three resolution methods.

4. JSON Schema model field validation inconsistent

Files: src/adapters/mcp-adapter.ts (multiple tool definitions)

The model field JSON Schema definitions are inconsistent:

• DelegateTask (line ~600): Has minLength: 1, maxLength: 200
• ScheduleTask (line ~756): Missing constraints
• CreatePipeline steps (line ~888): Missing constraints
• CreatePipeline top-level (line ~912): Missing constraints
• SchedulePipeline steps (line ~954): Missing constraints
• SchedulePipeline top-level (line ~1011): Missing constraints
• CreateLoop (line ~1105): Missing constraints
• ScheduleLoop (line ~1257): Missing constraints
• CreateOrchestrator (line ~1300): Missing constraints
• ConfigureAgent (line ~1408): Missing constraints

MCP clients rely on JSON Schema for validation. Inconsistent constraints cause confusion and may allow invalid values to be sent.

Fix: Add minLength: 1, maxLength: 200 to all model field definitions in inputSchema blocks.

5. ConfigureAgent set action — partial-write risk

File: src/adapters/mcp-adapter.ts:2983-3065

The set action saves apiKey, baseUrl, and model sequentially with early returns. If apiKey saves but baseUrl fails, the method returns an error while apiKey is already persisted. The caller sees isError: true and may assume nothing changed, but the disk has a partial update.

Fixes (choose one):

1. Batch write: Build merged config object first, then write once
2. Partial state in error: Return savedFields array in error so caller knows current state

6. CLI baseUrl validation missing

File: src/cli/commands/agents.ts:106

The CLI beat agents config set <agent> baseUrl <value> accepts any string without validation. The MCP path validates with z.string().url(), but the CLI path skips validation. Malformed URLs (file:///, javascript:, non-URLs) would be injected as environment variables for spawned processes.

Fix: Validate with new URL(value) before calling saveAgentConfig.

---

Recommendation: These issues must be addressed before merge. The CRITICAL issues (5 instances) cause silent data loss where the feature appears to work initially but fails after persistence. The HIGH issues prevent the feature from working correctly in production workloads.

[dean0x]

MEDIUM-CONFIDENCE SUGGESTIONS (60-79%)

These don't block merge but should be tracked for next release:

Complexity

• Duplicated Claude baseUrl warning logic (88% confidence): The warning 'Warning: Claude requires an API key when using a custom baseUrl...' appears in 3 places (check action, set action, ListAgents). Extract to shared helper.

• handleConfigureAgent complexity growing (85% confidence): The method is now 154 lines with nested conditionals. Extract set case into handleConfigureAgentSet() and check case into handleConfigureAgentCheck().

• mcp-adapter.ts at 3086 lines (80% confidence): File continues to grow. Consider extracting Zod schemas and tool definitions into separate files (mcp-schemas.ts, mcp-tool-definitions.ts).

Performance

• loadAgentConfig() re-read in ListAgents and ConfigureAgent (82% confidence): The handlers call loadAgentConfig() multiple times per request. Cache at handler start and reuse.

• saveAgentConfig() loads config twice on sequential calls (70% confidence): ConfigureAgent set calls saveAgentConfig 3 times for apiKey/baseUrl/model. Batch into single read-modify-write cycle.

Architecture

• ProcessSpawner interface duplication (80% confidence): ProcessSpawner.spawn() and AgentAdapter.spawn() now have identical signatures. Consider deprecating ProcessSpawner and migrating tests to mock AgentAdapter.

Testing

• No test for TaskManager.retry() preserving model (82% confidence): The production code threads model: originalTask.model but no test verifies it survives retry operation.

• No test for TaskManager.resume() preserving model (82% confidence): Same as retry - production code is correct but unverified by tests.

• No tests for ScheduleHandler model threading (80% confidence): handlePipelineTrigger and createScheduledLoop thread model but service-layer tests don't verify this.

---

SUMMARY

Blocking Issues: 6 (including 2 CRITICAL with 95% confidence, 4 HIGH with 80-92%)
Should-Fix Issues: 1 (test duplication - 85% confidence)
Medium-Confidence: 10+ suggestions

The PR demonstrates strong architectural consistency for the model passthrough feature across all layers. However, the 5 CRITICAL data-loss issues in persistence schemas and the HIGH-severity validation gaps must be fixed before merge. These are not architectural concerns but implementation gaps where the feature was added to domain types and APIs but not fully integrated into the persistence and validation layers.

Once fixed, this will be a clean, well-tested feature addition.