From 4123d229f430091a106eb1de0d980e5d65b77b3d Mon Sep 17 00:00:00 2001 From: Michael Grundberg Date: Thu, 1 Oct 2026 16:59:45 +0200 Subject: [PATCH] feat(sessions): accept a per-session Claude model on POST /api/sessions POST /api/sessions takes an optional `model`, and a Claude session launches with `claude --model `. It wins over the app-wide default model and writes nothing to disk, unlike `modelOverride`, which stays as it is and still writes the case's .claude/settings.local.json. Co-Authored-By: Claude Opus 5.5 (1M context) --- .../skills/codeman/reference/endpoints.md | 3 +- skills/codeman/reference/endpoints.md | 3 +- src/web/routes/session-routes.ts | 9 +- src/web/schemas.ts | 10 ++ .../session-routes-claude-model.test.ts | 94 +++++++++++++++++++ 5 files changed, 113 insertions(+), 6 deletions(-) create mode 100644 test/routes/session-routes-claude-model.test.ts diff --git a/plugins/codeman/skills/codeman/reference/endpoints.md b/plugins/codeman/skills/codeman/reference/endpoints.md index d8b26507..f7a5f622 100644 --- a/plugins/codeman/skills/codeman/reference/endpoints.md +++ b/plugins/codeman/skills/codeman/reference/endpoints.md @@ -384,7 +384,8 @@ every claude create path installs them, so a linked case and a raw path both get **The two-step alternative, `POST /api/v1/sessions`.** Use it when you need a session in a directory that is not a case (body takes `workingDir`, `mode`, `name`, `effort`, -`envOverrides`). Three differences that break copied code: +`envOverrides`, and for claude a per-session `model` passed as `--model`). Three +differences that break copied code: - The id is at **`.data.session.id`**, not quick-start's `.data.sessionId` (`session-routes.ts:878` returns `{ session: lightState }`). diff --git a/skills/codeman/reference/endpoints.md b/skills/codeman/reference/endpoints.md index d8b26507..f7a5f622 100644 --- a/skills/codeman/reference/endpoints.md +++ b/skills/codeman/reference/endpoints.md @@ -384,7 +384,8 @@ every claude create path installs them, so a linked case and a raw path both get **The two-step alternative, `POST /api/v1/sessions`.** Use it when you need a session in a directory that is not a case (body takes `workingDir`, `mode`, `name`, `effort`, -`envOverrides`). Three differences that break copied code: +`envOverrides`, and for claude a per-session `model` passed as `--model`). Three +differences that break copied code: - The id is at **`.data.session.id`**, not quick-start's `.data.sessionId` (`session-routes.ts:878` returns `{ session: lightState }`). diff --git a/src/web/routes/session-routes.ts b/src/web/routes/session-routes.ts index 6a7b78ad..33c82ac4 100644 --- a/src/web/routes/session-routes.ts +++ b/src/web/routes/session-routes.ts @@ -1073,9 +1073,10 @@ export function registerSessionRoutes( // genuinely different mechanisms: // 'flag' — the CLI takes --model, so read the value the caller sent // in that CLI's own config object. - // 'claude-settings-file' — claude alone, whose model is written to - // /.claude/settings.local.json rather than passed as - // a flag, so the app-wide default applies here. + // 'claude-settings-file' — claude alone, whose persistent model is written to + // /.claude/settings.local.json (`modelOverride`). A + // per-session `model` from the caller goes out as --model and + // wins; without one, the app-wide default applies. // 'none' — shell has no model; deepseek's is a composition entry in // the profile's config tree, not a session field // (docs/deepseek-integration.md). Both get nothing. @@ -1086,7 +1087,7 @@ export function registerSessionRoutes( | string | undefined) : modelSource?.source === 'claude-settings-file' - ? modelConfig?.defaultModel || undefined + ? body.model || modelConfig?.defaultModel || undefined : undefined; const claudeModeConfig = await ctx.getClaudeModeConfig(); // Section 6.3: force non-granted users to a classifier-guarded mode. diff --git a/src/web/schemas.ts b/src/web/schemas.ts index c12a83a9..e9859a73 100644 --- a/src/web/schemas.ts +++ b/src/web/schemas.ts @@ -526,6 +526,16 @@ export const CreateSessionSchema = z.object({ effort: effortLevelSchema, /** Model override to write to .claude/settings.local.json (e.g., "opus[1m]"). Empty string clears. */ modelOverride: z.string().max(50).optional(), + /** + * Claude model for THIS session only, passed as `claude --model `; nothing is written to + * disk. Wins over the app-wide default model. Same character set as the registry's + * `model-claude` pattern, so a value accepted here is never rejected at launch. + */ + model: z + .string() + .max(100) + .regex(/^[a-zA-Z0-9._\-[\]]+$/) + .optional(), openCodeConfig: OpenCodeConfigSchema, codexConfig: CodexConfigSchema, geminiConfig: GeminiConfigSchema, diff --git a/test/routes/session-routes-claude-model.test.ts b/test/routes/session-routes-claude-model.test.ts new file mode 100644 index 00000000..8b9ae957 --- /dev/null +++ b/test/routes/session-routes-claude-model.test.ts @@ -0,0 +1,94 @@ +/** + * @fileoverview `model` on POST /api/sessions — a Claude model for one session only. + * + * Claude's model reaches disk only through `modelOverride`, which writes it into the + * case's `.claude/settings.local.json` for every later run there. `model` is the + * per-session counterpart: it goes out as `claude --model `, wins over the app-wide + * default, and writes nothing. What the tests read is the model the session hands the + * mux when it starts, which is what becomes the `--model` flag. + * + * Uses app.inject(), so no real HTTP port is needed. + */ + +import { describe, it, expect, beforeEach, afterEach } from 'vitest'; +import Fastify, { type FastifyInstance } from 'fastify'; +import fastifyCookie from '@fastify/cookie'; +import { mkdtemp, readFile, rm } from 'node:fs/promises'; +import { join } from 'node:path'; +import { tmpdir } from 'node:os'; +import { createMockRouteContext, type MockRouteContext } from '../mocks/index.js'; +import { installRouteErrorHandler } from '../../src/web/route-error-handler.js'; +import { registerSessionRoutes } from '../../src/web/routes/session-routes.js'; + +interface Harness { + app: FastifyInstance; + ctx: MockRouteContext; +} + +async function createHarness(): Promise { + const app = Fastify({ logger: false }); + await app.register(fastifyCookie); + const ctx = createMockRouteContext(); + registerSessionRoutes(app, ctx); + installRouteErrorHandler(app); + await app.ready(); + return { app, ctx }; +} + +describe('POST /api/sessions model', () => { + let workingDir: string; + let harness: Harness; + + beforeEach(async () => { + workingDir = await mkdtemp(join(tmpdir(), 'codeman-session-model-')); + harness = await createHarness(); + }); + + afterEach(async () => { + await harness.app.close(); + await rm(workingDir, { recursive: true, force: true }); + }); + + /** Creates a session and starts it, then returns the model it handed the mux. */ + async function launchedModel(payload: Record): Promise { + const res = await harness.app.inject({ method: 'POST', url: '/api/sessions', payload: { workingDir, ...payload } }); + expect(res.statusCode).toBe(200); + const parsed = JSON.parse(res.body); + const id = (parsed.data?.session ?? parsed.session).id as string; + await harness.app.inject({ method: 'POST', url: `/api/sessions/${id}/interactive`, payload: {} }); + const calls = harness.ctx.mux.createSession.mock.calls; + expect(calls.length).toBeGreaterThan(0); + return (calls[calls.length - 1][0] as { model?: string }).model; + } + + it('launches a Claude session on the model the caller names', async () => { + expect(await launchedModel({ mode: 'claude', model: 'claude-fable-5-1' })).toBe('claude-fable-5-1'); + }); + + it('wins over the app-wide default model', async () => { + harness.ctx.getModelConfig.mockResolvedValue({ defaultModel: 'sonnet' }); + expect(await launchedModel({ mode: 'claude', model: 'opus' })).toBe('opus'); + }); + + it('leaves the app-wide default in charge when the caller names none', async () => { + harness.ctx.getModelConfig.mockResolvedValue({ defaultModel: 'sonnet' }); + expect(await launchedModel({ mode: 'claude' })).toBe('sonnet'); + }); + + it('writes no model into the case directory', async () => { + // The create still installs Codeman's workspace hooks into settings.local.json, so the + // file exists; what must not be in it is a model that would outlive this session. + await launchedModel({ mode: 'claude', model: 'opus' }); + const settings = await readFile(join(workingDir, '.claude', 'settings.local.json'), 'utf8').catch(() => '{}'); + expect(JSON.parse(settings)).not.toHaveProperty('model'); + }); + + it('rejects a model with characters the launch pattern refuses', async () => { + const res = await harness.app.inject({ + method: 'POST', + url: '/api/sessions', + payload: { workingDir, mode: 'claude', model: 'opus; rm -rf ~' }, + }); + expect(res.statusCode).toBe(400); + }); +});