feat(sdk/typescript): model#variant reasoning-effort parity in harness providers

Mirrors the Python SDK: splitModelVariant/resolveModelAndVariant helper,
variant?: string through HarnessConfig/HarnessOptions, opencode passes
--variant, codex now passes -m at all (it previously sent no model to the
CLI — same bug the Python provider had) plus -c model_reasoning_effort,
claude/gemini strip the suffix. Attribution overlay and usage metrics key
off the base model.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: AbirAbbas

sdk/typescript/src/agent/Agent.ts

@@ -41,6 +41,7 @@ import { AIClient } from '../ai/AIClient.js';
 import { AgentFieldClient } from '../client/AgentFieldClient.js';
 import type { HarnessRunner } from '../harness/runner.js';
 import type { HarnessOptions, HarnessResult } from '../harness/types.js';
+import { splitModelVariant } from '../harness/modelVariant.js';
 import { MemoryClient } from '../memory/MemoryClient.js';
 import { MemoryEventClient } from '../memory/MemoryEventClient.js';
 import {
@@ -412,9 +413,13 @@ export class Agent {
 
       const providerName = options?.provider ?? this.config.harnessConfig?.provider;
       const harnessName = providerName ? String(providerName).replace(/-/g, '_') : null;
-      const modelName = String(
+      // Usage is recorded against the base model — a "#variant"
+      // reasoning-effort suffix on the configured model never reaches the
+      // provider and must not reach the tracker either.
+      const rawModelName = String(
         result.model ?? options?.model ?? this.config.harnessConfig?.model ?? providerName ?? 'harness'
       );
+      const modelName = splitModelVariant(rawModelName).model ?? rawModelName;
 
       tracker.record({
         model: modelName,

sdk/typescript/src/harness/index.ts

@@ -1,5 +1,7 @@
 export type { HarnessConfig, HarnessOptions, Metrics, RawResult, HarnessResult } from './types.js';
 export { createHarnessResult, createMetrics, createRawResult } from './types.js';
+export type { ModelVariant } from './modelVariant.js';
+export { MODEL_VARIANT_SEP, splitModelVariant, resolveModelAndVariant } from './modelVariant.js';
 export type { HarnessProvider } from './providers/base.js';
 export { buildProvider, SUPPORTED_PROVIDERS } from './providers/factory.js';
 export { HarnessRunner } from './runner.js';

sdk/typescript/src/harness/modelVariant.ts

@@ -0,0 +1,47 @@
+/**
+ * Separator for the `provider/model#variant` model-string syntax. `#` is
+ * safe because provider model ids never contain it (`:` is taken by
+ * OpenRouter suffixes like `:free`, `@` by Vertex-style ids).
+ */
+export const MODEL_VARIANT_SEP = '#';
+
+export interface ModelVariant {
+  model?: string;
+  variant?: string;
+}
+
+/**
+ * Split a `provider/model#variant` string into `{ model, variant }`.
+ *
+ * The `#variant` suffix carries a provider-specific reasoning-effort
+ * variant (e.g. `high`, `minimal`) through config surfaces that only
+ * hold a model string. A bare model string passes through as
+ * `{ model }`; non-string or empty input yields `{}`.
+ */
+export function splitModelVariant(model: unknown): ModelVariant {
+  if (typeof model !== 'string' || !model.trim()) {
+    return {};
+  }
+  const sepIndex = model.indexOf(MODEL_VARIANT_SEP);
+  const base = sepIndex === -1 ? model : model.slice(0, sepIndex);
+  const variant = sepIndex === -1 ? '' : model.slice(sepIndex + 1);
+  return {
+    model: base.trim() || undefined,
+    variant: variant.trim() || undefined,
+  };
+}
+
+/**
+ * Resolve `{ model, variant }` from harness options.
+ *
+ * An explicit `options.variant` wins over a `#variant` suffix on
+ * `options.model`; the returned model never carries the suffix.
+ */
+export function resolveModelAndVariant(options: Record<string, unknown>): ModelVariant {
+  const { model, variant } = splitModelVariant(options.model);
+  const explicit = options.variant;
+  if (typeof explicit === 'string' && explicit.trim()) {
+    return { model, variant: explicit.trim() };
+  }
+  return { model, variant };
+}

sdk/typescript/src/harness/providers/claude.ts

@@ -1,6 +1,7 @@
 import type { HarnessProvider } from './base.js';
 import type { RawResult } from '../types.js';
 import { createMetrics, createRawResult } from '../types.js';
+import { resolveModelAndVariant } from '../modelVariant.js';
 
 type QueryInput = {
   prompt: string;
@@ -39,7 +40,10 @@ export class ClaudeCodeProvider implements HarnessProvider {
     }
 
     const agentOptions: Record<string, unknown> = {};
-    if (options.model !== undefined) agentOptions.model = options.model;
+    // claude-agent-sdk has no reasoning-effort knob; strip any "#variant"
+    // suffix so the SDK receives a valid model id, and drop the variant.
+    const { model: modelValue } = resolveModelAndVariant(options);
+    if (modelValue !== undefined) agentOptions.model = modelValue;
     if (options.cwd !== undefined) agentOptions.cwd = options.cwd;
     if (options.maxTurns !== undefined) agentOptions.max_turns = options.maxTurns;
     if (options.tools !== undefined) agentOptions.allowed_tools = options.tools;

sdk/typescript/src/harness/providers/codex.ts

@@ -2,6 +2,7 @@ import type { HarnessProvider } from './base.js';
 import type { RawResult } from '../types.js';
 import { createRawResult, createMetrics } from '../types.js';
 import { runCli, parseJsonl, extractFinalText } from '../cli.js';
+import { resolveModelAndVariant } from '../modelVariant.js';
 
 export class CodexProvider implements HarnessProvider {
   private readonly bin: string;
@@ -19,6 +20,19 @@ export class CodexProvider implements HarnessProvider {
     if (options.permissionMode === 'auto') {
       cmd.push('--full-auto');
     }
+
+    // Model via -m; reasoning effort has no dedicated flag — it's the
+    // model_reasoning_effort config key. The effort comes from a "#variant"
+    // suffix on the model (or an explicit options.variant), e.g.
+    // "gpt-5.3-codex#high".
+    const { model: modelValue, variant: variantValue } = resolveModelAndVariant(options);
+    if (modelValue) {
+      cmd.push('-m', modelValue);
+    }
+    if (variantValue) {
+      cmd.push('-c', `model_reasoning_effort=${variantValue}`);
+    }
+
     cmd.push(prompt);
 
     const startApi = Date.now();
@@ -50,7 +64,7 @@ export class CodexProvider implements HarnessProvider {
       return createRawResult({
         result: resultText,
         messages: events,
-        metrics: createMetrics({ durationApiMs: Date.now() - startApi, numTurns, sessionId }),
+        metrics: createMetrics({ durationApiMs: Date.now() - startApi, numTurns, sessionId, model: modelValue }),
         isError,
         errorMessage: isError ? stderr.trim() : undefined,
       });

sdk/typescript/src/harness/providers/gemini.ts

@@ -2,6 +2,7 @@ import type { HarnessProvider } from './base.js';
 import type { RawResult } from '../types.js';
 import { createRawResult, createMetrics } from '../types.js';
 import { runCli } from '../cli.js';
+import { resolveModelAndVariant } from '../modelVariant.js';
 
 export class GeminiProvider implements HarnessProvider {
   private readonly bin: string;
@@ -19,8 +20,11 @@ export class GeminiProvider implements HarnessProvider {
     if (options.permissionMode === 'auto') {
       cmd.push('--sandbox');
     }
-    if (options.model) {
-      cmd.push('-m', String(options.model));
+    // gemini has no reasoning-effort flag; strip any "#variant" suffix so
+    // the CLI still receives a valid model id.
+    const { model: modelValue } = resolveModelAndVariant(options);
+    if (modelValue) {
+      cmd.push('-m', modelValue);
     }
     cmd.push('-p', prompt);
 

sdk/typescript/src/harness/providers/opencode.ts

@@ -2,6 +2,7 @@ import type { HarnessProvider } from './base.js';
 import type { RawResult } from '../types.js';
 import { createRawResult, createMetrics } from '../types.js';
 import { runCli } from '../cli.js';
+import { resolveModelAndVariant } from '../modelVariant.js';
 import {
   isOpenRouterRequest,
   openRouterAttributionHeaders,
@@ -31,9 +32,16 @@ export class OpenCodeProvider implements HarnessProvider {
 
     const env: Record<string, string> = { ...(options.env as Record<string, string>) };
 
-    // Pass model via -m flag on the run subcommand (not env var).
-    if (options.model) {
-      cmd.push('-m', String(options.model));
+    // Pass model via -m flag on the run subcommand (not env var). A
+    // "#variant" suffix on the model (or an explicit options.variant) maps
+    // to --variant — opencode's provider-specific reasoning effort (e.g.
+    // high, max, minimal).
+    const { model: modelValue, variant: variantValue } = resolveModelAndVariant(options);
+    if (modelValue) {
+      cmd.push('-m', modelValue);
+    }
+    if (variantValue) {
+      cmd.push('--variant', variantValue);
     }
 
     // Handle system prompt - prepend to user prompt since OpenCode
@@ -46,14 +54,15 @@ export class OpenCodeProvider implements HarnessProvider {
     // Prompt is the positional `message` arg to `opencode run`.
     cmd.push(effectivePrompt);
 
-    const explicitModel = typeof options.model === 'string' ? options.model : undefined;
+    // The attribution overlay keys off the base model — a "#variant" suffix
+    // would otherwise leak into the config's model slug.
     if (
-      explicitModel &&
-      isOpenRouterRequest({ model: explicitModel }) &&
+      modelValue &&
+      isOpenRouterRequest({ model: modelValue }) &&
       !env.OPENCODE_CONFIG_CONTENT &&
       !process.env.OPENCODE_CONFIG_CONTENT
     ) {
-      const modelSlug = explicitModel.slice('openrouter/'.length);
+      const modelSlug = modelValue.slice('openrouter/'.length);
       const headers = openRouterAttributionHeaders({ env: { ...process.env, ...env } });
       if (modelSlug && Object.keys(headers).length > 0) {
         env.OPENCODE_CONFIG_CONTENT = JSON.stringify({
@@ -82,6 +91,7 @@ export class OpenCodeProvider implements HarnessProvider {
           durationApiMs: Date.now() - startApi,
           numTurns: resultText ? 1 : 0,
           sessionId: '',
+          model: modelValue,
         }),
         isError,
         errorMessage: isError ? stderr.trim() : undefined,

sdk/typescript/src/harness/runner.ts

@@ -93,6 +93,7 @@ export class HarnessRunner {
       for (const key of [
         'provider',
         'model',
+        'variant',
         'maxTurns',
         'maxBudgetUsd',
         'maxRetries',

sdk/typescript/src/harness/types.ts

@@ -1,6 +1,11 @@
 export interface HarnessConfig {
   provider: 'claude-code' | 'codex' | 'gemini' | 'opencode';
   model?: string;
+  /**
+   * Provider-specific reasoning-effort variant (e.g. `high`, `minimal`).
+   * Wins over a `#variant` suffix on `model`.
+   */
+  variant?: string;
   maxTurns?: number;
   maxBudgetUsd?: number;
   maxRetries?: number;
@@ -20,6 +25,11 @@ export interface HarnessConfig {
 export interface HarnessOptions {
   provider?: string;
   model?: string;
+  /**
+   * Provider-specific reasoning-effort variant (e.g. `high`, `minimal`).
+   * Wins over a `#variant` suffix on `model`.
+   */
+  variant?: string;
   maxTurns?: number;
   maxBudgetUsd?: number;
   maxRetries?: number;

sdk/typescript/tests/harness_model_variant.test.ts

@@ -0,0 +1,78 @@
+import { describe, it, expect } from 'vitest';
+
+import {
+  MODEL_VARIANT_SEP,
+  resolveModelAndVariant,
+  splitModelVariant,
+} from '../src/harness/modelVariant.js';
+
+describe('splitModelVariant', () => {
+  it('parses a #variant suffix into model and variant', () => {
+    expect(splitModelVariant('openrouter/z-ai/glm-5.2#high')).toEqual({
+      model: 'openrouter/z-ai/glm-5.2',
+      variant: 'high',
+    });
+  });
+
+  it('passes a bare model through with no variant', () => {
+    expect(splitModelVariant('deepseek/deepseek-v4-flash')).toEqual({
+      model: 'deepseek/deepseek-v4-flash',
+      variant: undefined,
+    });
+  });
+
+  it('handles missing, empty, or non-string model', () => {
+    expect(splitModelVariant(undefined)).toEqual({});
+    expect(splitModelVariant(null)).toEqual({});
+    expect(splitModelVariant('')).toEqual({});
+    expect(splitModelVariant('  ')).toEqual({});
+    expect(splitModelVariant(42)).toEqual({});
+  });
+
+  it('treats empty halves around the separator as absent', () => {
+    expect(splitModelVariant('model#')).toEqual({ model: 'model', variant: undefined });
+    expect(splitModelVariant('#high')).toEqual({ model: undefined, variant: 'high' });
+  });
+
+  it('splits on the first separator only', () => {
+    expect(splitModelVariant('a#b#c')).toEqual({ model: 'a', variant: 'b#c' });
+  });
+
+  it('trims whitespace around both halves', () => {
+    expect(splitModelVariant(' openai/gpt-5 # high ')).toEqual({
+      model: 'openai/gpt-5',
+      variant: 'high',
+    });
+  });
+
+  it('uses # as the separator', () => {
+    expect(MODEL_VARIANT_SEP).toBe('#');
+  });
+});
+
+describe('resolveModelAndVariant', () => {
+  it('lets an explicit variant option win over the suffix', () => {
+    expect(resolveModelAndVariant({ model: 'openai/gpt-5#low', variant: 'max' })).toEqual({
+      model: 'openai/gpt-5',
+      variant: 'max',
+    });
+  });
+
+  it('uses the suffix when no explicit option is set', () => {
+    expect(resolveModelAndVariant({ model: 'openai/gpt-5#minimal' })).toEqual({
+      model: 'openai/gpt-5',
+      variant: 'minimal',
+    });
+  });
+
+  it('ignores a whitespace-only explicit variant', () => {
+    expect(resolveModelAndVariant({ model: 'openai/gpt-5#low', variant: '  ' })).toEqual({
+      model: 'openai/gpt-5',
+      variant: 'low',
+    });
+  });
+
+  it('returns nothing for empty options', () => {
+    expect(resolveModelAndVariant({})).toEqual({ model: undefined, variant: undefined });
+  });
+});