Skip to content

The open-source agent harness - the runtime layer that turns an LLM into a working agent.

Drop AgentDefinition.model; let the bound ILLM own model identity. (#88)

pranjaltrvd0fe8aabad99f
diff --git a/packages/harness/src/agent-session/SessionHandle.ts b/packages/harness/src/agent-session/SessionHandle.ts
index b2492c84c..2950830dd 100644
--- a/packages/harness/src/agent-session/SessionHandle.ts
+++ b/packages/harness/src/agent-session/SessionHandle.ts
@@ -445,15 +445,11 @@ export class SessionHandle<
signal: params.signal,
tracing: input.tracing,
});
+ // Model override (request.model) is resolved inside resolveAgentDefinition
+ // into modelClient — do not re-label a stale client here.
const childDefinition: AgentDefinition = {
...definition,
toolSets: params.parentDefinition.toolSets ?? definition.toolSets,
- ...(params.request.model !== undefined
- ? {
- model: params.request.model,
- modelClient: definition.modelClient,
- }
- : {}),
// The delegated task goes in as the initial user message; the sub-agent
// system prompt is SUB_AGENT_IDENTITY (added by AgentThread.buildInstruction).
instruction: undefined,
diff --git a/packages/harness/src/agent-session/TurnResourceResolver.ts b/packages/harness/src/agent-session/TurnResourceResolver.ts
index e9a50c6c0..dd0704594 100644
--- a/packages/harness/src/agent-session/TurnResourceResolver.ts
+++ b/packages/harness/src/agent-session/TurnResourceResolver.ts
@@ -193,10 +193,12 @@ export class TurnResourceResolver<
});
}),
);
+ // Sub-agents may request a different catalog model via agent_info.model;
+ // resolve that name so modelClient matches the override (not just a label).
+ const modelName = agentInfo?.model ?? spec.model.name;
return {
definition: {
- model: spec.model.name,
- modelClient: await this.deps.llm(spec.model.name),
+ modelClient: await this.deps.llm(modelName),
// Sub-agents receive the delegated task as a user message; their system
// prompt is SUB_AGENT_IDENTITY (added by AgentThread), not user instructions.
instruction: agentInfo ? undefined : spec.instructions,
diff --git a/packages/harness/src/core/capabilities/builtins/ContextCompaction.ts b/packages/harness/src/core/capabilities/builtins/ContextCompaction.ts
index 9ba342596..365caf0bc 100644
--- a/packages/harness/src/core/capabilities/builtins/ContextCompaction.ts
+++ b/packages/harness/src/core/capabilities/builtins/ContextCompaction.ts
@@ -1,6 +1,5 @@
-import type { ChatCompletionCreateParams } from 'openai/resources/chat';
import { EventType, newEventId } from '../../events/schema';
-import type { ILLM } from '../../llm/ILLM';
+import type { ILLM, LLMCreateParams } from '../../llm/ILLM';
import type { AgentDefinition } from '../../runtime/AgentDefinition';
import type { ContextMessage } from '../../runtime/AgentThread.types';
import { internalSystemMessage, isInternalSystemMessage, isLLMContextMessage } from '../../runtime/contextUtils';
@@ -170,12 +169,10 @@ function createSummarizationCandidate(context: ContextMessage[]) {
}
export class ContextCompaction implements PreLLMAgentContextProcessor {
- private model: string;
private modelClient: ILLM;
private compactionThresholdTokens: number;
- constructor(input: { model: string; modelClient: ILLM; compactionThresholdTokens: number }) {
- this.model = input.model;
+ constructor(input: { modelClient: ILLM; compactionThresholdTokens: number }) {
this.modelClient = input.modelClient;
this.compactionThresholdTokens = input.compactionThresholdTokens;
}
@@ -188,8 +185,8 @@ export class ContextCompaction implements PreLLMAgentContextProcessor {
return;
}
- const body: ChatCompletionCreateParams = {
- model: this.model,
+ // Model identity is owned by modelClient — omit OpenAI's required `model` field.
+ const body: LLMCreateParams = {
messages: [
{ role: 'user', content: createSummarizationCandidate(execution.context) },
{ role: 'user', content: PROMPT },
@@ -235,7 +232,6 @@ export function contextCompaction(options: {
return {
preLLMProcessors: [
new ContextCompaction({
- model: options.definition.model,
modelClient: options.definition.modelClient,
compactionThresholdTokens: threshold,
}),
diff --git a/packages/harness/src/core/index.ts b/packages/harness/src/core/index.ts
index 6c47ab0cd..45d460042 100644
--- a/packages/harness/src/core/index.ts
+++ b/packages/harness/src/core/index.ts
@@ -81,7 +81,7 @@ export {
export { ToolSet } from './mcp/ToolSet';
// LLM contracts
-export type { AgentMetadata, ILLM } from './llm/ILLM';
+export type { AgentMetadata, ILLM, LLMCreateParams, LLMCreateParamsStreaming } from './llm/ILLM';
export { ResponseFormatSchema, toOpenAIResponseFormat } from './llm/responseFormat';
export type { ResponseFormat } from './llm/responseFormat';
export { SUPPORTED_REASONING_EFFORTS, VERCEL_AI_PROVIDER_NAMES, VercelAILLM } from './llm/VercelAILLM';
diff --git a/packages/harness/src/core/llm/ILLM.ts b/packages/harness/src/core/llm/ILLM.ts
index e7af95f9a..ebe5f4403 100644
--- a/packages/harness/src/core/llm/ILLM.ts
+++ b/packages/harness/src/core/llm/ILLM.ts
@@ -3,9 +3,17 @@ import type { ExtendedChatCompletionChunk, RawAssistantMessageWithUsage } from '
export type AgentMetadata = Record<string, string>;
+/**
+ * OpenAI chat-completion request shapes with `model` removed.
+ * The bound ILLM client owns model identity (e.g. VercelAILLM providerConfig);
+ * callers must not invent a model string just to satisfy OpenAI's required field.
+ */
+export type LLMCreateParams = Omit<ChatCompletionCreateParams, 'model'>;
+export type LLMCreateParamsStreaming = Omit<ChatCompletionCreateParamsStreaming, 'model'>;
+
export interface ILLM {
create(
- body: ChatCompletionCreateParamsStreaming,
+ body: LLMCreateParamsStreaming,
): AsyncGenerator<ExtendedChatCompletionChunk, RawAssistantMessageWithUsage, unknown>;
- createNonStream(body: ChatCompletionCreateParams): Promise<RawAssistantMessageWithUsage>;
+ createNonStream(body: LLMCreateParams): Promise<RawAssistantMessageWithUsage>;
}
diff --git a/packages/harness/src/core/llm/VercelAILLM.ts b/packages/harness/src/core/llm/VercelAILLM.ts
index 3d4c661da..d6f5c444f 100644
--- a/packages/harness/src/core/llm/VercelAILLM.ts
+++ b/packages/harness/src/core/llm/VercelAILLM.ts
@@ -29,14 +29,13 @@ import type {
import { APICallError, jsonSchema, Output, streamText } from 'ai';
import type {
ChatCompletionContentPart,
- ChatCompletionCreateParams,
ChatCompletionCreateParamsStreaming,
ChatCompletionMessageParam,
ChatCompletionTool,
} from 'openai/resources/chat';
import type { Logger } from 'winston';
import { extractErrorLogFields } from '../util/errorLogFields';
-import type { ILLM } from './ILLM';
+import type { ILLM, LLMCreateParams, LLMCreateParamsStreaming } from './ILLM';
import {
type CompletionUsage,
type ExtendedChatCompletionChunk,
@@ -1300,7 +1299,7 @@ export class VercelAILLM implements ILLM {
}
async *create(
- body: ChatCompletionCreateParamsStreaming,
+ body: LLMCreateParamsStreaming,
): AsyncGenerator<ExtendedChatCompletionChunk, RawAssistantMessageWithUsage, unknown> {
const { providerConfig } = this.config;
const model = buildLanguageModel(providerConfig);
@@ -1364,7 +1363,7 @@ export class VercelAILLM implements ILLM {
warnings => {
if (warnings !== undefined && warnings.length > 0) {
this.logger.warn('Provider adjusted the request', {
- model: body.model,
+ model: providerConfig.name,
warnings: warnings.map(describeCallWarning),
});
}
@@ -1376,10 +1375,11 @@ export class VercelAILLM implements ILLM {
);
// Synthetic chunk fields; id is unique per stream instance.
+ // Label chunks with the catalog name — providerConfig.modelId is the wire id.
const chunkMeta: ChunkMeta = {
id: `vc-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 7)}`,
created: Math.floor(Date.now() / 1000),
- model: body.model,
+ model: providerConfig.name,
};
try {
@@ -1394,7 +1394,7 @@ export class VercelAILLM implements ILLM {
}
}
- async createNonStream(body: ChatCompletionCreateParams): Promise<RawAssistantMessageWithUsage> {
+ async createNonStream(body: LLMCreateParams): Promise<RawAssistantMessageWithUsage> {
// Drain the streaming generator — reuses the same accumulation and error handling path.
const llmStream = this.create({ ...body, stream: true });
let result = await llmStream.next();
diff --git a/packages/harness/src/core/runtime/AgentDefinition.ts b/packages/harness/src/core/runtime/AgentDefinition.ts
index 91e97049f..ae98d4581 100644
--- a/packages/harness/src/core/runtime/AgentDefinition.ts
+++ b/packages/harness/src/core/runtime/AgentDefinition.ts
@@ -8,9 +8,11 @@ export type ModelParams = Record<string, unknown>;
/**
* Static definition of an agent. Represents the authored configuration,
* not the execution state. Inherited by sub-agent definitions.
+ *
+ * Model identity lives on `modelClient` (e.g. VercelAILLM providerConfig),
+ * not as a parallel string on this definition.
*/
export interface AgentDefinition {
- model: string;
modelClient: ILLM;
instruction?: string | undefined;
messages?: readonly LLMUserMessage[] | undefined;
diff --git a/packages/harness/src/core/runtime/AgentThread.ts b/packages/harness/src/core/runtime/AgentThread.ts
index cd7ae77a6..98caa91e5 100644
--- a/packages/harness/src/core/runtime/AgentThread.ts
+++ b/packages/harness/src/core/runtime/AgentThread.ts
@@ -1,8 +1,4 @@
-import type {
- ChatCompletionCreateParamsStreaming,
- ChatCompletionMessageParam,
- ChatCompletionTool,
-} from 'openai/resources/chat';
+import type { ChatCompletionMessageParam, ChatCompletionTool } from 'openai/resources/chat';
import type { Logger } from 'winston';
import type { AgentCapability, CapabilityState } from '../capabilities/AgentCapability';
import type {
@@ -39,6 +35,7 @@ import {
type UserToolResponseMessage,
} from '../events/schema';
import { InstructionBuilder, ROOT_AGENT_IDENTITY } from '../InstructionBuilder';
+import type { LLMCreateParamsStreaming } from '../llm/ILLM';
import {
type CompletionUsage,
type ExtendedChatCompletionChunk,
@@ -760,7 +757,7 @@ export class AgentThread {
return { ...this.metrics };
}
- private transformToLLMRequest(tools: ChatCompletionTool[]): ChatCompletionCreateParamsStreaming {
+ private transformToLLMRequest(tools: ChatCompletionTool[]): LLMCreateParamsStreaming {
let messages: ChatCompletionMessageParam[] = [];
if (this.instruction) {
@@ -790,8 +787,8 @@ export class AgentThread {
// modelParams may include provider extensions (e.g. reasoning_effort) beyond the SDK's
// ChatCompletionCreateParamsStreaming field set; assign after constructing the typed body.
- const requestBody: ChatCompletionCreateParamsStreaming = {
- model: this.definition.model,
+ // Model identity is owned by modelClient — do not set `model` on the request.
+ const requestBody: LLMCreateParamsStreaming = {
messages,
stream: true,
...(this.definition.responseFormat !== undefined
@@ -810,7 +807,7 @@ export class AgentThread {
}
private computeAssistantMessageUsage(params: {
- requestBody: ChatCompletionCreateParamsStreaming;
+ requestBody: LLMCreateParamsStreaming;
usage: CompletionUsage;
toolMapping: Map<string, MappedMCPTool>;
}): ModelMessageUsage {
diff --git a/packages/harness/tests/agent-session/builtinsFromSpec.test.ts b/packages/harness/tests/agent-session/builtinsFromSpec.test.ts
index 03adde315..2e2e0c90b 100644
--- a/packages/harness/tests/agent-session/builtinsFromSpec.test.ts
+++ b/packages/harness/tests/agent-session/builtinsFromSpec.test.ts
@@ -11,7 +11,6 @@ import { makeMockILLM, makeSilentLogger } from '../core/harnessMocks';
function makeDefinition(): AgentDefinition {
return {
- model: 'provider/model',
modelClient: makeMockILLM(),
};
}
diff --git a/packages/harness/tests/agent-session/capabilityState.test.ts b/packages/harness/tests/agent-session/capabilityState.test.ts
index dd254ea71..ac342af02 100644
--- a/packages/harness/tests/agent-session/capabilityState.test.ts
+++ b/packages/harness/tests/agent-session/capabilityState.test.ts
@@ -271,7 +271,6 @@ describe('capability_state (tfy.plan fixture)', () => {
};
const thread = new AgentThread({
definition: {
- model: 'test-model',
modelClient: makeMockILLM({ create: jest.fn().mockImplementation(() => emptyLlmStream()) }),
},
threadId: MAIN_THREAD_ID,
diff --git a/packages/harness/tests/core/llm/toOpenAIChatMessage.test.ts b/packages/harness/tests/core/llm/toOpenAIChatMessage.test.ts
index a02a60c10..808c0afef 100644
--- a/packages/harness/tests/core/llm/toOpenAIChatMessage.test.ts
+++ b/packages/harness/tests/core/llm/toOpenAIChatMessage.test.ts
@@ -1,5 +1,4 @@
-import type { ChatCompletionCreateParamsStreaming } from 'openai/resources/chat';
-import type { ILLM } from '../../../src/core/llm/ILLM';
+import type { ILLM, LLMCreateParamsStreaming } from '../../../src/core/llm/ILLM';
import type {
ExtendedChatCompletionChunk,
InternalEnrichedAssistantMessage,
@@ -153,9 +152,9 @@ describe('AgentThread LLM request mapping (end-to-end)', () => {
}
it('forwards thinking_blocks, reasoning_content, and provider_specific_fields; strips tool_info', async () => {
- let capturedBody: ChatCompletionCreateParamsStreaming | undefined;
+ let capturedBody: LLMCreateParamsStreaming | undefined;
const modelClient: ILLM = {
- create: jest.fn().mockImplementation((body: ChatCompletionCreateParamsStreaming) => {
+ create: jest.fn().mockImplementation((body: LLMCreateParamsStreaming) => {
capturedBody = body;
return finalAnswerStream();
}),
@@ -169,7 +168,6 @@ describe('AgentThread LLM request mapping (end-to-end)', () => {
tracing: NOOP_AGENT_TRACING,
logger: makeSilentLogger(),
definition: {
- model: 'test-model',
modelClient,
instruction: 'test',
toolSets: [],
diff --git a/packages/harness/tests/core/runtime/unknownToolLogging.test.ts b/packages/harness/tests/core/runtime/unknownToolLogging.test.ts
index 5b2b27b28..9f5361e8c 100644
--- a/packages/harness/tests/core/runtime/unknownToolLogging.test.ts
+++ b/packages/harness/tests/core/runtime/unknownToolLogging.test.ts
@@ -94,7 +94,6 @@ describe('AgentThread unknown tool logging', () => {
tracing: NOOP_AGENT_TRACING,
logger: silentLogger,
definition: {
- model: 'test-model',
modelClient,
instruction: 'test',
toolSets: [],