@shipfox/api-agent 2.0.0

package/src/core/resolve-agent-config.test.ts

@@ -0,0 +1,441 @@
+import crypto from 'node:crypto';
+import type {AgentThinking, SupportedModelProviderId} from '@shipfox/api-agent-dto';
+import {
+  getAgentWorkspaceSettings,
+  setDefaultHarness,
+  setDefaultModelProvider,
+  type UpsertModelProviderConfigParams,
+  upsertModelProviderConfig,
+} from '#db/index.js';
+import {
+  InvalidAgentModelError,
+  UnsupportedHarnessProviderError,
+  UnsupportedHarnessThinkingError,
+  UnsupportedModelProviderError,
+} from './errors.js';
+import * as harnessCatalog from './harness/index.js';
+import {catalogDefaultAgentResolver, resolveAgentConfig} from './resolve-agent-config.js';
+import {createWorkspaceAgentDefaultsResolver} from './workspace-agent-defaults-resolver.js';
+
+describe('resolveAgentConfig', () => {
+  test('resolves model provider from explicit step, workspace, instance, then catalog default', () => {
+    const workspaceProviderConfigs = new Map([
+      ['openai' as const, {defaultModel: 'gpt-5.5-pro', defaultThinking: 'medium' as const}],
+      [
+        'google' as const,
+        {defaultModel: 'gemini-3.1-pro-preview', defaultThinking: 'low' as const},
+      ],
+    ]);
+
+    const explicit = resolveAgentConfig(
+      {provider: 'google'},
+      {
+        workspaceDefaultProviderId: 'openai',
+        workspaceProviderConfigs,
+        instanceDefaultProvider: 'anthropic',
+      },
+    );
+    const workspace = resolveAgentConfig(
+      {},
+      {workspaceDefaultProviderId: 'openai', workspaceProviderConfigs},
+    );
+    const instance = resolveAgentConfig({}, {instanceDefaultProvider: 'anthropic'});
+    const catalog = resolveAgentConfig({});
+
+    expect(explicit.provider).toBe('google');
+    expect(workspace.provider).toBe('openai');
+    expect(instance.provider).toBe('anthropic');
+    expect(catalog.provider).toBe('anthropic');
+  });
+
+  test('resolves model from explicit step, workspace, instance match, then catalog default', () => {
+    const workspaceProviderConfigs = new Map([
+      ['openai' as const, {defaultModel: 'gpt-5.5-pro', defaultThinking: 'medium' as const}],
+      ['anthropic' as const, {defaultModel: null, defaultThinking: 'low' as const}],
+    ]);
+
+    const explicit = resolveAgentConfig(
+      {provider: 'openai', model: 'gpt-5.5-pro'},
+      {workspaceProviderConfigs},
+    );
+    const workspace = resolveAgentConfig({provider: 'openai'}, {workspaceProviderConfigs});
+    const instance = resolveAgentConfig(
+      {},
+      {
+        instanceDefaultProvider: 'anthropic',
+        instanceDefaultModel: 'claude-opus-4-8',
+      },
+    );
+    const workspaceLatest = resolveAgentConfig({provider: 'anthropic'}, {workspaceProviderConfigs});
+    const catalog = resolveAgentConfig({provider: 'deepseek'});
+
+    expect(explicit.model).toBe('gpt-5.5-pro');
+    expect(workspace.model).toBe('gpt-5.5-pro');
+    expect(instance.model).toBe('claude-opus-4-8');
+    expect(workspaceLatest.model).toBe('claude-opus-4-8');
+    expect(catalog.model).toBe('deepseek-v4-pro');
+  });
+
+  test('resolves custom provider models from workspace configs', () => {
+    const workspaceProviderConfigs = new Map([
+      [
+        'local-vllm',
+        {
+          kind: 'custom' as const,
+          defaultModel: null,
+          defaultThinking: 'medium' as const,
+          models: [{id: 'llama-3.1', label: 'Llama 3.1'}],
+        },
+      ],
+    ]);
+
+    const resolved = resolveAgentConfig(
+      {provider: 'local-vllm'},
+      {workspaceProviderConfigs, workspaceDefaultProviderId: 'local-vllm'},
+    );
+    const invalidModel = () =>
+      resolveAgentConfig(
+        {provider: 'local-vllm', model: 'missing-model'},
+        {workspaceProviderConfigs},
+      );
+
+    expect(resolved).toEqual({
+      harness: 'pi',
+      provider: 'local-vllm',
+      model: 'llama-3.1',
+      thinking: 'medium',
+    });
+    expect(invalidModel).toThrow(InvalidAgentModelError);
+  });
+
+  test('uses instance model and thinking only for the resolved instance model provider', () => {
+    const resolved = resolveAgentConfig(
+      {provider: 'openai'},
+      {
+        instanceDefaultProvider: 'anthropic',
+        instanceDefaultModel: 'claude-opus-4-8',
+        instanceDefaultThinking: 'low',
+      },
+    );
+
+    expect(resolved).toEqual({
+      harness: 'pi',
+      provider: 'openai',
+      model: 'gpt-5.5-pro',
+      thinking: 'xhigh',
+    });
+  });
+
+  test('resolves harness from explicit step, then default', () => {
+    const explicit = resolveAgentConfig({harness: 'claude'});
+    const workspace = resolveAgentConfig({}, {workspaceDefaultHarnessId: 'claude'});
+    const fallback = resolveAgentConfig({});
+
+    expect(explicit.harness).toBe('claude');
+    expect(workspace.harness).toBe('claude');
+    expect(fallback.harness).toBe('pi');
+  });
+
+  test('resolves thinking from explicit step, workspace, instance match, then default', () => {
+    const workspaceProviderConfigs = new Map([
+      ['openai' as const, {defaultModel: 'gpt-5.5-pro', defaultThinking: 'medium' as const}],
+    ]);
+
+    const explicit = resolveAgentConfig(
+      {provider: 'openai', thinking: 'low'},
+      {workspaceProviderConfigs},
+    );
+    const workspace = resolveAgentConfig({provider: 'openai'}, {workspaceProviderConfigs});
+    const instance = resolveAgentConfig(
+      {},
+      {instanceDefaultProvider: 'anthropic', instanceDefaultThinking: 'medium'},
+    );
+    const fallback = resolveAgentConfig({provider: 'deepseek'});
+
+    expect(explicit.thinking).toBe('low');
+    expect(workspace.thinking).toBe('medium');
+    expect(instance.thinking).toBe('medium');
+    expect(fallback.thinking).toBe('xhigh');
+  });
+
+  test('throws for unsupported providers and unavailable models', () => {
+    expect(() => resolveAgentConfig({provider: 'amazon-bedrock'})).toThrow(
+      UnsupportedModelProviderError,
+    );
+    expect(() => resolveAgentConfig({provider: 'anthropic', model: 'not-a-model'})).toThrow(
+      InvalidAgentModelError,
+    );
+  });
+
+  test('rejects explicit provider values incompatible with the harness', () => {
+    const resolve = () => resolveAgentConfig({harness: 'claude', provider: 'openai'});
+
+    expect(resolve).toThrow(UnsupportedHarnessProviderError);
+  });
+
+  test('skips incompatible default providers for the selected harness', () => {
+    const workspaceProviderConfigs = new Map([
+      ['openai' as const, {defaultModel: 'gpt-5.5-pro', defaultThinking: 'medium' as const}],
+    ]);
+
+    const resolved = resolveAgentConfig(
+      {harness: 'claude'},
+      {
+        workspaceDefaultProviderId: 'openai',
+        workspaceProviderConfigs,
+        instanceDefaultProvider: 'deepseek',
+      },
+    );
+
+    expect(resolved.provider).toBe('anthropic');
+  });
+
+  test('keeps custom providers pi-only', () => {
+    const workspaceProviderConfigs = new Map([
+      [
+        'local-vllm',
+        {
+          kind: 'custom' as const,
+          defaultModel: null,
+          defaultThinking: 'medium' as const,
+          models: [{id: 'llama-3.1', label: 'Llama 3.1'}],
+        },
+      ],
+    ]);
+
+    const pi = resolveAgentConfig({provider: 'local-vllm'}, {workspaceProviderConfigs});
+    const claude = () =>
+      resolveAgentConfig({harness: 'claude', provider: 'local-vllm'}, {workspaceProviderConfigs});
+
+    expect(pi.provider).toBe('local-vllm');
+    expect(claude).toThrow(UnsupportedHarnessProviderError);
+  });
+
+  test('rejects explicit models outside the harness catalog', () => {
+    const resolve = () =>
+      resolveAgentConfig({harness: 'claude', provider: 'anthropic', model: 'gpt-5.5-pro'});
+
+    expect(resolve).toThrow(InvalidAgentModelError);
+  });
+
+  test('skips default models outside the harness catalog', () => {
+    const resolved = resolveAgentConfig(
+      {harness: 'claude', provider: 'anthropic'},
+      {
+        instanceDefaultProvider: 'anthropic',
+        instanceDefaultModel: 'not-a-model',
+      },
+    );
+
+    expect(resolved.model).toBe('claude-opus-4-8');
+  });
+
+  test('does not evaluate catalog model fallback before a valid workspace default model', () => {
+    vi.spyOn(harnessCatalog, 'listHarnessProviderModels').mockImplementation(
+      (harness, provider) => {
+        if (new Error('capture catalog lookup stack').stack?.includes('catalogDefaultModel')) {
+          throw new InvalidAgentModelError(harness, provider, '');
+        }
+        return [{id: 'claude-opus-4-8', label: 'Claude Opus 4.8'}];
+      },
+    );
+    const workspaceProviderConfigs = new Map([
+      ['anthropic' as const, {defaultModel: 'claude-opus-4-8', defaultThinking: 'medium' as const}],
+    ]);
+
+    const resolved = resolveAgentConfig({provider: 'anthropic'}, {workspaceProviderConfigs});
+
+    expect(resolved.model).toBe('claude-opus-4-8');
+  });
+
+  test('validates thinking against the selected harness', () => {
+    const claudeOff = () => resolveAgentConfig({harness: 'claude', thinking: 'off'});
+    const piMax = () => resolveAgentConfig({harness: 'pi', thinking: 'max'});
+
+    expect(claudeOff).toThrow(UnsupportedHarnessThinkingError);
+    expect(piMax).toThrow(UnsupportedHarnessThinkingError);
+  });
+
+  test('ignores stale provider thinking defaults outside the selected harness', () => {
+    const workspaceProviderConfigs = new Map([
+      ['anthropic' as const, {defaultModel: 'claude-opus-4-8', defaultThinking: 'off' as const}],
+    ]);
+
+    const resolved = resolveAgentConfig(
+      {harness: 'claude', provider: 'anthropic'},
+      {workspaceProviderConfigs},
+    );
+
+    expect(resolved.thinking).toBe('xhigh');
+  });
+
+  test('falls through to the instance default when the workspace default model provider is null', () => {
+    const resolved = resolveAgentConfig(
+      {},
+      {workspaceDefaultProviderId: null, instanceDefaultProvider: 'anthropic'},
+    );
+
+    expect(resolved.provider).toBe('anthropic');
+  });
+
+  test('skips a stored workspace default model provider that is no longer supported', () => {
+    const resolved = resolveAgentConfig(
+      {},
+      {workspaceDefaultProviderId: 'amazon-bedrock' as SupportedModelProviderId},
+    );
+
+    expect(resolved.provider).toBe('anthropic');
+  });
+
+  test('skips an unknown instance default model', () => {
+    const resolved = resolveAgentConfig(
+      {},
+      {
+        instanceDefaultProvider: 'anthropic',
+        instanceDefaultModel: 'not-a-model',
+      },
+    );
+
+    expect(resolved.model).toBe('claude-opus-4-8');
+  });
+
+  test('catalogDefaultAgentResolver uses catalog-only defaults', () => {
+    const resolved = catalogDefaultAgentResolver({provider: 'openai'});
+
+    expect(resolved).toEqual({
+      harness: 'pi',
+      provider: 'openai',
+      model: 'gpt-5.5-pro',
+      thinking: 'xhigh',
+    });
+  });
+});
+
+describe('createWorkspaceAgentDefaultsResolver', () => {
+  let workspaceId: string;
+
+  beforeEach(() => {
+    workspaceId = crypto.randomUUID();
+  });
+
+  test('preloads workspace settings and model provider configs for resolution', async () => {
+    await upsertModelProviderConfig(
+      createModelProviderConfigParams({
+        workspaceId,
+        providerId: 'openai',
+        defaultModel: 'gpt-5.5-pro',
+        defaultThinking: 'medium',
+      }),
+    );
+    await setDefaultModelProvider({workspaceId, providerId: 'openai'});
+    await setDefaultHarness({workspaceId, harnessId: 'claude'});
+
+    const resolver = await createWorkspaceAgentDefaultsResolver(workspaceId);
+    const resolved = resolver({});
+    const settings = await getAgentWorkspaceSettings(workspaceId);
+
+    expect(settings?.defaultProviderId).toBe('openai');
+    expect(settings?.defaultHarnessId).toBe('claude');
+    expect(resolved).toEqual({
+      harness: 'claude',
+      provider: 'anthropic',
+      model: 'claude-opus-4-8',
+      thinking: 'xhigh',
+    });
+  });
+
+  test('falls back to catalog defaults when no workspace settings exist', async () => {
+    const resolver = await createWorkspaceAgentDefaultsResolver(workspaceId);
+
+    const resolved = resolver({});
+
+    expect(resolved).toEqual({
+      harness: 'pi',
+      provider: 'anthropic',
+      model: 'claude-opus-4-8',
+      thinking: 'xhigh',
+    });
+  });
+
+  test('uses workspace model provider config defaults when settings row does not exist', async () => {
+    await upsertModelProviderConfig(
+      createModelProviderConfigParams({
+        workspaceId,
+        providerId: 'openai',
+        defaultModel: 'gpt-5.5-pro',
+        defaultThinking: 'medium',
+      }),
+    );
+
+    const resolver = await createWorkspaceAgentDefaultsResolver(workspaceId);
+    const resolved = resolver({provider: 'openai'});
+
+    expect(resolved).toEqual({
+      harness: 'pi',
+      provider: 'openai',
+      model: 'gpt-5.5-pro',
+      thinking: 'medium',
+    });
+  });
+
+  test('uses catalog model when the workspace model provider config keeps latest selected', async () => {
+    await upsertModelProviderConfig(
+      createModelProviderConfigParams({
+        workspaceId,
+        providerId: 'openai',
+        defaultModel: null,
+        defaultThinking: 'medium',
+      }),
+    );
+
+    const resolver = await createWorkspaceAgentDefaultsResolver(workspaceId);
+    const resolved = resolver({provider: 'openai'});
+
+    expect(resolved).toEqual({
+      harness: 'pi',
+      provider: 'openai',
+      model: 'gpt-5.5-pro',
+      thinking: 'medium',
+    });
+  });
+
+  test('uses custom workspace defaults without filtering the provider config', async () => {
+    await upsertModelProviderConfig({
+      workspaceId,
+      providerId: 'local-vllm',
+      kind: 'custom',
+      displayName: 'Local vLLM',
+      api: 'openai-responses',
+      baseUrl: 'http://127.0.0.1:11434/v1',
+      headers: [],
+      models: [{id: 'llama-3.1', label: 'Llama 3.1'}],
+      defaultModel: null,
+      defaultThinking: 'low',
+    });
+    await setDefaultModelProvider({workspaceId, providerId: 'local-vllm'});
+
+    const resolver = await createWorkspaceAgentDefaultsResolver(workspaceId);
+    const resolved = resolver({});
+
+    expect(resolved).toEqual({
+      harness: 'pi',
+      provider: 'local-vllm',
+      model: 'llama-3.1',
+      thinking: 'low',
+    });
+  });
+});
+
+function createModelProviderConfigParams(params: {
+  workspaceId: string;
+  providerId: SupportedModelProviderId;
+  defaultModel: string | null;
+  defaultThinking: AgentThinking;
+}): UpsertModelProviderConfigParams {
+  return {
+    workspaceId: params.workspaceId,
+    providerId: params.providerId,
+    defaultModel: params.defaultModel,
+    defaultThinking: params.defaultThinking,
+  };
+}

package/src/core/resolve-agent-config.ts

@@ -0,0 +1,272 @@
+import {
+  type AgentThinking,
+  agentThinkingByHarness,
+  type CustomAgentModelDto,
+  DEFAULT_HARNESS,
+  getHarnessDescriptor,
+  getModelProviderEntry,
+  type Harness,
+  type ModelProviderRef,
+  type SupportedModelProviderId,
+} from '@shipfox/api-agent-dto';
+import {
+  InvalidAgentModelError,
+  UnsupportedHarnessProviderError,
+  UnsupportedHarnessThinkingError,
+  UnsupportedModelProviderError,
+} from './errors.js';
+import {listHarnessProviderModels} from './harness/index.js';
+
+export interface ContextualAgentConfig {
+  readonly harness?: Harness | undefined;
+  readonly provider?: string | undefined;
+  readonly model?: string | undefined;
+  readonly thinking?: AgentThinking | undefined;
+}
+
+export interface ResolvedAgentConfig {
+  readonly harness: Harness;
+  readonly provider: ModelProviderRef;
+  readonly model: string;
+  readonly thinking: AgentThinking;
+}
+
+export type AgentDefaultsResolver = (step: ContextualAgentConfig) => ResolvedAgentConfig;
+
+export interface AgentConfigResolutionContext {
+  readonly workspaceDefaultHarnessId?: Harness | null | undefined;
+  readonly workspaceDefaultProviderId?: ModelProviderRef | null | undefined;
+  readonly workspaceProviderConfigs?: ReadonlyMap<ModelProviderRef, WorkspaceProviderDefaults>;
+  readonly instanceDefaultProvider?: SupportedModelProviderId | undefined;
+  readonly instanceDefaultModel?: string | undefined;
+  readonly instanceDefaultThinking?: AgentThinking | undefined;
+}
+
+interface WorkspaceProviderDefaults {
+  readonly kind?: 'builtin' | 'custom' | undefined;
+  readonly defaultModel: string | null;
+  readonly defaultThinking: AgentThinking;
+  readonly models?: readonly CustomAgentModelDto[] | null | undefined;
+}
+
+type ModelCandidateResolver = () => string | null | undefined;
+
+export function resolveAgentConfig(
+  step: ContextualAgentConfig,
+  ctx: AgentConfigResolutionContext = {},
+): ResolvedAgentConfig {
+  const harness = step.harness ?? ctx.workspaceDefaultHarnessId ?? DEFAULT_HARNESS;
+  const provider = resolveProvider(step, ctx, harness);
+  const workspaceProviderConfig = ctx.workspaceProviderConfigs?.get(provider);
+  const model = resolveModel({
+    step,
+    ctx,
+    harness,
+    provider,
+    workspaceProviderConfig,
+  });
+  const thinking = resolveThinking({step, ctx, harness, provider, workspaceProviderConfig});
+
+  return {harness, provider, model, thinking};
+}
+
+export const catalogDefaultAgentResolver: AgentDefaultsResolver = (step) =>
+  resolveAgentConfig(step);
+
+function resolveProvider(
+  step: ContextualAgentConfig,
+  ctx: AgentConfigResolutionContext,
+  harness: Harness,
+): ModelProviderRef {
+  const descriptor = getHarnessDescriptor(harness);
+  if (step.provider !== undefined) {
+    const provider = resolveSupportedProvider(step.provider, ctx);
+    if (!isHarnessCompatible(harness, provider, ctx.workspaceProviderConfigs?.get(provider))) {
+      throw new UnsupportedHarnessProviderError(
+        harness,
+        step.provider,
+        descriptor.supportedProviderIds,
+      );
+    }
+    return provider;
+  }
+
+  const candidates = [
+    ctx.workspaceDefaultProviderId,
+    ctx.instanceDefaultProvider,
+    descriptor.defaultProviderId,
+  ];
+  for (const candidate of candidates) {
+    if (candidate === undefined || candidate === null) continue;
+
+    const workspaceProviderConfig = ctx.workspaceProviderConfigs?.get(candidate);
+    if (!isHarnessCompatible(harness, candidate, workspaceProviderConfig)) continue;
+
+    return resolveSupportedProvider(candidate, ctx);
+  }
+
+  return descriptor.defaultProviderId;
+}
+
+function resolveSupportedProvider(
+  provider: string,
+  ctx: AgentConfigResolutionContext,
+): ModelProviderRef {
+  const workspaceProviderConfig = ctx.workspaceProviderConfigs?.get(provider);
+  if (workspaceProviderConfig?.kind === 'custom') return provider;
+
+  const entry = getModelProviderEntry(provider);
+  if (entry === undefined || entry.support_status !== 'supported') {
+    throw new UnsupportedModelProviderError(provider);
+  }
+  return provider as SupportedModelProviderId;
+}
+
+function resolveModel(params: {
+  step: ContextualAgentConfig;
+  ctx: AgentConfigResolutionContext;
+  harness: Harness;
+  provider: ModelProviderRef;
+  workspaceProviderConfig: WorkspaceProviderDefaults | undefined;
+}): string {
+  if (params.step.model !== undefined) {
+    validateModel(
+      params.harness,
+      params.provider,
+      params.step.model,
+      params.workspaceProviderConfig,
+    );
+    return params.step.model;
+  }
+
+  const candidates: ModelCandidateResolver[] = [() => params.workspaceProviderConfig?.defaultModel];
+  if (params.workspaceProviderConfig?.kind === 'custom') {
+    candidates.push(() => customDefaultModel(params.workspaceProviderConfig));
+  } else {
+    candidates.push(
+      () => instanceDefaultModel(params.provider, params.ctx),
+      () => catalogDefaultModel(params.harness, params.provider),
+    );
+  }
+
+  for (const resolveCandidate of candidates) {
+    const candidate = resolveCandidate();
+    if (candidate === undefined || candidate === null) continue;
+    if (
+      modelIsAvailable(params.harness, params.provider, candidate, params.workspaceProviderConfig)
+    ) {
+      return candidate;
+    }
+  }
+
+  throw new InvalidAgentModelError(params.harness, params.provider, '');
+}
+
+function catalogDefaultModel(harness: Harness, provider: ModelProviderRef): string {
+  const catalogModels = listProviderModels(harness, provider);
+  const entry = getModelProviderEntry(provider);
+  if (entry === undefined || entry.support_status !== 'supported') {
+    throw new UnsupportedModelProviderError(provider);
+  }
+  if (
+    entry.default_model !== null &&
+    catalogModels.some((candidate) => candidate.id === entry.default_model)
+  ) {
+    return entry.default_model;
+  }
+
+  const firstModel = catalogModels[0];
+  if (firstModel === undefined) throw new InvalidAgentModelError(harness, provider, '');
+  return firstModel.id;
+}
+
+function instanceDefaultModel(
+  provider: ModelProviderRef,
+  ctx: AgentConfigResolutionContext,
+): string | undefined {
+  return provider === ctx.instanceDefaultProvider ? ctx.instanceDefaultModel : undefined;
+}
+
+function instanceDefaultThinking(
+  provider: ModelProviderRef,
+  ctx: AgentConfigResolutionContext,
+): AgentThinking | undefined {
+  return provider === ctx.instanceDefaultProvider ? ctx.instanceDefaultThinking : undefined;
+}
+
+function customDefaultModel(
+  workspaceProviderConfig: WorkspaceProviderDefaults | undefined,
+): string | undefined {
+  if (workspaceProviderConfig?.kind !== 'custom') return undefined;
+  return workspaceProviderConfig.models?.[0]?.id;
+}
+
+function validateModel(
+  harness: Harness,
+  provider: ModelProviderRef,
+  model: string,
+  workspaceProviderConfig: WorkspaceProviderDefaults | undefined,
+): void {
+  if (modelIsAvailable(harness, provider, model, workspaceProviderConfig)) return;
+  throw new InvalidAgentModelError(harness, provider, model);
+}
+
+function modelIsAvailable(
+  harness: Harness,
+  provider: ModelProviderRef,
+  model: string,
+  workspaceProviderConfig: WorkspaceProviderDefaults | undefined,
+): boolean {
+  if (workspaceProviderConfig?.kind === 'custom') {
+    return workspaceProviderConfig.models?.some((candidate) => candidate.id === model) ?? false;
+  }
+
+  return listProviderModels(harness, provider).some((candidate) => candidate.id === model);
+}
+
+function listProviderModels(harness: Harness, provider: ModelProviderRef): readonly {id: string}[] {
+  return listHarnessProviderModels(harness, provider);
+}
+
+function isHarnessCompatible(
+  harness: Harness,
+  provider: ModelProviderRef,
+  workspaceProviderConfig: WorkspaceProviderDefaults | undefined,
+): boolean {
+  if (workspaceProviderConfig?.kind === 'custom') return harness === 'pi';
+
+  return getHarnessDescriptor(harness).supportedProviderIds.includes(provider);
+}
+
+function resolveThinking(params: {
+  step: ContextualAgentConfig;
+  ctx: AgentConfigResolutionContext;
+  harness: Harness;
+  provider: ModelProviderRef;
+  workspaceProviderConfig: WorkspaceProviderDefaults | undefined;
+}): AgentThinking {
+  const thinkingSchema = agentThinkingByHarness[params.harness];
+  const descriptor = getHarnessDescriptor(params.harness);
+
+  if (params.step.thinking !== undefined) {
+    if (!thinkingSchema.safeParse(params.step.thinking).success) {
+      throw new UnsupportedHarnessThinkingError(
+        params.harness,
+        params.step.thinking,
+        descriptor.thinkingLevels,
+      );
+    }
+    return params.step.thinking;
+  }
+
+  const candidates = [
+    params.workspaceProviderConfig?.defaultThinking,
+    instanceDefaultThinking(params.provider, params.ctx),
+    descriptor.defaultThinking,
+  ];
+  for (const candidate of candidates) {
+    if (candidate !== undefined && thinkingSchema.safeParse(candidate).success) return candidate;
+  }
+
+  return descriptor.defaultThinking;
+}