Skip to content

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

feat: require and backfill source for model.message events (#992)

Sujai Kumar Gupta26c77c4d5d4f
diff --git a/.changeset/model-message-model-field.md b/.changeset/model-message-model-field.md
new file mode 100644
index 000000000..b55348e32
--- /dev/null
+++ b/.changeset/model-message-model-field.md
@@ -0,0 +1,6 @@
+---
+'@truefoundry/trueforge-core': patch
+'@truefoundry/trueforge': patch
+---
+
+Add optional AgentSpec-shaped `model` (`{ name: provider/model, params? }`) on `model.message` events, stamp it from the bound agent definition for new turns, and backfill the session tip turn's events / turn output from the session agent model FQN.
diff --git a/.github/fern/openapi/openapi.json b/.github/fern/openapi/openapi.json
index 186354aad..f390510d9 100644
--- a/.github/fern/openapi/openapi.json
+++ b/.github/fern/openapi/openapi.json
@@ -2788,6 +2788,9 @@
"description": "Unique identifier for the event (monotonic ULID).",
"type": "string"
},
+ "model": {
+ "$ref": "#/components/schemas/Model"
+ },
"name": {
"description": "Optional participant name.",
"type": "string"
diff --git a/docs/openapi.json b/docs/openapi.json
index 186354aad..f390510d9 100644
--- a/docs/openapi.json
+++ b/docs/openapi.json
@@ -2788,6 +2788,9 @@
"description": "Unique identifier for the event (monotonic ULID).",
"type": "string"
},
+ "model": {
+ "$ref": "#/components/schemas/Model"
+ },
"name": {
"description": "Optional participant name.",
"type": "string"
diff --git a/packages/trueforge-core/src/agent-session/TurnResourceResolver.ts b/packages/trueforge-core/src/agent-session/TurnResourceResolver.ts
index 32c40606c..0c19b32ba 100644
--- a/packages/trueforge-core/src/agent-session/TurnResourceResolver.ts
+++ b/packages/trueforge-core/src/agent-session/TurnResourceResolver.ts
@@ -1,10 +1,11 @@
import type { Logger } from 'winston';
import type { ILLM } from '../core/llm/ILLM';
+import type { ModelParams } from '../core/llm/model';
import type { ToolSource } from '../core/mcp/IMCPServer';
import { RemoteMCP, type RemoteMcpHeaders } from '../core/mcp/RemoteMCP';
import type { ToolSelectorConfig } from '../core/mcp/ToolSelectorPolicy';
import { ToolSet } from '../core/mcp/ToolSet';
-import type { AgentDefinition, ModelParams } from '../core/runtime/AgentDefinition';
+import type { AgentDefinition } from '../core/runtime/AgentDefinition';
import type { AgentInfo } from '../core/runtime/AgentThread.types';
import type { HarnessSandbox, SandboxInfo } from '../core/sandbox/Sandbox';
import type { AgentTracing } from '../core/tracing/AgentTracing';
@@ -216,6 +217,7 @@ export class TurnResourceResolver<
return {
definition: {
modelClient: resolvedModel.modelClient,
+ modelName,
modelProperties: resolvedModel.modelProperties,
// Sub-agents receive the delegated task as a user message; their system
// prompt is SUB_AGENT_IDENTITY (added by AgentThread), not user instructions.
diff --git a/packages/trueforge-core/src/agent-session/schemas/agentSpec.ts b/packages/trueforge-core/src/agent-session/schemas/agentSpec.ts
index d9996c5e8..05816f763 100644
--- a/packages/trueforge-core/src/agent-session/schemas/agentSpec.ts
+++ b/packages/trueforge-core/src/agent-session/schemas/agentSpec.ts
@@ -5,6 +5,7 @@ import {
DEFAULT_PREVIEW_NUMBER_OF_CHARACTERS,
DEFAULT_TOTAL_TOOL_TOKEN_THRESHOLD,
} from '../../core/capabilities/builtins/LargeToolResponse';
+import { ModelSchema } from '../../core/llm/model';
import { ResponseFormatSchema } from '../../core/llm/responseFormat';
import {
DEFAULT_DISABLE_TOOLS,
@@ -17,37 +18,6 @@ import {
export const DEFAULT_AGENT_CONFIG_ITERATION_LIMIT = 512;
-// --- Model ---
-
-const ModelParamsSchema = z
- .object({
- max_tokens: z.number().optional().describe('Maximum tokens to generate in the model response.'),
- temperature: z.number().optional().describe('Sampling temperature; higher values increase randomness.'),
- top_p: z.number().optional().describe('Nucleus sampling probability mass.'),
- top_k: z.number().optional().describe('Top-k sampling; keep only the k highest-probability tokens.'),
- parallel_tool_calls: z
- .boolean()
- .optional()
- .describe('Whether the model may emit multiple tool calls in one response.'),
- reasoning_effort: z.string().optional().describe('Provider-specific reasoning effort (e.g. low/medium/high).'),
- })
- .loose() // this ensures extra model params are allowed
- .describe(
- 'Model call parameters passed through to the provider. Known keys are documented; extra keys are allowed and forwarded as-is.',
- )
- .openapi('ModelParams');
-
-// Opaque runtime identifier; the hosting server owns naming conventions (e.g. provider/model).
-const ModelSchema = z
- .object({
- name: z
- .string()
- .min(1, 'model.name must not be empty')
- .describe('Model FQN: `provider/model`, e.g. `openai/gpt-5.2`.'),
- params: ModelParamsSchema.optional(),
- })
- .openapi('Model');
-
// --- MCP servers ---
// Literal tool name (not a tag).
diff --git a/packages/trueforge-core/src/core/capabilities/builtins/ContextCompaction.ts b/packages/trueforge-core/src/core/capabilities/builtins/ContextCompaction.ts
index 46b6afd28..71fe7593e 100644
--- a/packages/trueforge-core/src/core/capabilities/builtins/ContextCompaction.ts
+++ b/packages/trueforge-core/src/core/capabilities/builtins/ContextCompaction.ts
@@ -23,7 +23,7 @@ export function resolveCompactionThresholdTokens(input: {
}
if (input.modelContextLength !== undefined) {
const ratioThreshold = Math.floor(input.modelContextLength * DEFAULT_CONTEXT_COMPACTION_RATIO);
- const configuredMaxOutputTokens = input.modelParams?.['max_completion_tokens'] ?? input.modelParams?.['max_tokens'];
+ const configuredMaxOutputTokens = input.modelParams?.['max_completion_tokens'] ?? input.modelParams?.max_tokens;
if (
typeof configuredMaxOutputTokens === 'number' &&
Number.isFinite(configuredMaxOutputTokens) &&
diff --git a/packages/trueforge-core/src/core/events/schema.ts b/packages/trueforge-core/src/core/events/schema.ts
index c55bdb402..2091dcfe3 100644
--- a/packages/trueforge-core/src/core/events/schema.ts
+++ b/packages/trueforge-core/src/core/events/schema.ts
@@ -10,6 +10,7 @@ import {
LLMToolMessageSchema,
LLMUserMessageSchema,
} from '../llm/LLMTypes';
+import { ModelSchema } from '../llm/model';
import { CurrentContextUsageSchema } from '../runtime/contextUsage';
/**
@@ -239,6 +240,8 @@ export const ModelMessageEventSchema = EnrichedAssistantMessageSchema.omit({ rol
.describe('Model finish reason; null when the provider omitted it.'),
created_at: z.string().describe('ISO 8601 event timestamp.'),
usage: ModelMessageUsageSchema.optional(),
+ // Optional: legacy rows may lack model when the session agent FQN cannot be backfilled.
+ model: ModelSchema.optional(),
})
.openapi('ModelMessageEvent');
diff --git a/packages/trueforge-core/src/core/index.ts b/packages/trueforge-core/src/core/index.ts
index cf99164bd..6ff8d866a 100644
--- a/packages/trueforge-core/src/core/index.ts
+++ b/packages/trueforge-core/src/core/index.ts
@@ -4,7 +4,9 @@
*/
// Runtime
-export type { AgentDefinition, ModelParams } from './runtime/AgentDefinition';
+export { ModelParamsSchema, ModelSchema } from './llm/model';
+export type { Model, ModelParams } from './llm/model';
+export type { AgentDefinition } from './runtime/AgentDefinition';
export { AgentThread } from './runtime/AgentThread';
export type {
AgentInfo,
diff --git a/packages/trueforge-core/src/core/llm/model.ts b/packages/trueforge-core/src/core/llm/model.ts
new file mode 100644
index 000000000..8c079eccf
--- /dev/null
+++ b/packages/trueforge-core/src/core/llm/model.ts
@@ -0,0 +1,32 @@
+import { z } from '@hono/zod-openapi';
+
+export const ModelParamsSchema = z
+ .object({
+ max_tokens: z.number().optional().describe('Maximum tokens to generate in the model response.'),
+ temperature: z.number().optional().describe('Sampling temperature; higher values increase randomness.'),
+ top_p: z.number().optional().describe('Nucleus sampling probability mass.'),
+ top_k: z.number().optional().describe('Top-k sampling; keep only the k highest-probability tokens.'),
+ parallel_tool_calls: z
+ .boolean()
+ .optional()
+ .describe('Whether the model may emit multiple tool calls in one response.'),
+ reasoning_effort: z.string().optional().describe('Provider-specific reasoning effort (e.g. low/medium/high).'),
+ })
+ .loose()
+ .describe(
+ 'Model call parameters passed through to the provider. Known keys are documented; extra keys are allowed and forwarded as-is.',
+ )
+ .openapi('ModelParams');
+
+export const ModelSchema = z
+ .object({
+ name: z
+ .string()
+ .min(1, 'model.name must not be empty')
+ .describe('Model FQN: `provider/model`, e.g. `openai/gpt-5.2`.'),
+ params: ModelParamsSchema.optional(),
+ })
+ .openapi('Model');
+
+export type ModelParams = z.infer<typeof ModelParamsSchema>;
+export type Model = z.infer<typeof ModelSchema>;
diff --git a/packages/trueforge-core/src/core/runtime/AgentDefinition.ts b/packages/trueforge-core/src/core/runtime/AgentDefinition.ts
index 6357c2d02..fbea47a4c 100644
--- a/packages/trueforge-core/src/core/runtime/AgentDefinition.ts
+++ b/packages/trueforge-core/src/core/runtime/AgentDefinition.ts
@@ -1,19 +1,16 @@
import type { ILLM } from '../llm/ILLM';
import type { LLMUserMessage } from '../llm/LLMTypes';
+import type { ModelParams } from '../llm/model';
import type { ResponseFormat } from '../llm/responseFormat';
import type { IToolSet } from '../mcp/IMCPServer';
-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 {
modelClient: ILLM;
+ modelName: string;
modelProperties?:
| {
/** Maximum combined input/output context for the resolved model, when known. */
diff --git a/packages/trueforge-core/src/core/runtime/AgentThread.ts b/packages/trueforge-core/src/core/runtime/AgentThread.ts
index 31290b619..978caaaaa 100644
--- a/packages/trueforge-core/src/core/runtime/AgentThread.ts
+++ b/packages/trueforge-core/src/core/runtime/AgentThread.ts
@@ -46,6 +46,7 @@ import {
type LLMUserMessage,
type RawAssistantMessage,
} from '../llm/LLMTypes';
+import { ModelSchema, type Model } from '../llm/model';
import { toOpenAIResponseFormat } from '../llm/responseFormat';
import { toOpenAIChatMessage } from '../llm/toOpenAIChatMessage';
import { estimateTokensForString } from '../llm/usage';
@@ -235,18 +236,28 @@ function toContextAssistantMessage(
return forContext;
}
+function modelFromDefinition(definition: AgentDefinition): Model {
+ const params = definition.modelParams;
+ return ModelSchema.parse({
+ name: definition.modelName,
+ ...(params && Object.keys(params).length > 0 ? { params } : {}),
+ });
+}
+
function buildModelMessageEvent({
assistantMessage,
threadId,
finishReason,
usage,
id,
+ model,
}: {
assistantMessage: InternalEnrichedAssistantMessage;
threadId: string;
finishReason: FinishReason | null;
usage: ModelMessageUsage | undefined;
id: string;
+ model: Model;
}): ModelMessageEvent {
// `thinking_blocks` / `source` stay on the context message for replay; strip them from the client event.
// `reasoning_content` stays on the event for UI replay (exact streamed concat).
@@ -267,6 +278,7 @@ function buildModelMessageEvent({
thread_id: threadId,
finish_reason: finishReason,
...(usage && { usage }),
+ model,
};
return event;
}
@@ -1099,11 +1111,13 @@ export class AgentThread {
const llmStream = this.definition.modelClient.create(requestBody);
// We start the delta stream with a model message event.
+ // `model` FQN is known from the bound client before any chunk arrives.
yield {
type: EventType.MODEL_MESSAGE,
thread_id: this.threadId,
created_at: new Date().toISOString(),
id: modelMessageEventId,
+ model: modelFromDefinition(this.definition),
} satisfies ModelMessageEvent;
let firstDeltaTimestamped = false;
@@ -1170,6 +1184,7 @@ export class AgentThread {
finishReason,
usage: modelMessageUsage,
id: modelMessageEventId,
+ model: modelFromDefinition(this.definition),
});
let completion: SubAgentCompletion | undefined;
diff --git a/packages/trueforge-core/tests/agent-session/builtinsFromSpec.test.ts b/packages/trueforge-core/tests/agent-session/builtinsFromSpec.test.ts
index 34663804c..00ca03041 100644
--- a/packages/trueforge-core/tests/agent-session/builtinsFromSpec.test.ts
+++ b/packages/trueforge-core/tests/agent-session/builtinsFromSpec.test.ts
@@ -14,11 +14,12 @@ import {
import type { AgentDefinition } from '../../src/core/runtime/AgentDefinition';
import { NOOP_AGENT_TRACING } from '../../src/core/tracing/NoopAgentTracing';
import { WebSearchProviders, type IWebSearchProvider } from '../../src/core/web-search/WebSearchProvider';
-import { makeMockILLM, makeSilentLogger } from '../core/harnessMocks';
+import { TEST_MODEL_NAME, makeMockILLM, makeSilentLogger } from '../core/harnessMocks';
function makeDefinition(): AgentDefinition {
return {
modelClient: makeMockILLM(),
+ modelName: TEST_MODEL_NAME,
};
}
diff --git a/packages/trueforge-core/tests/agent-session/capabilityState.test.ts b/packages/trueforge-core/tests/agent-session/capabilityState.test.ts
index f6866bf0d..eafe13295 100644
--- a/packages/trueforge-core/tests/agent-session/capabilityState.test.ts
+++ b/packages/trueforge-core/tests/agent-session/capabilityState.test.ts
@@ -20,6 +20,7 @@ import {
makeTestResolver,
mintTestTurnId,
TEST_ACTIVE_EXECUTOR_ID,
+ TEST_MODEL_NAME,
} from './testHelpers';
function makePlanShapedCapability(options: {
@@ -281,6 +282,7 @@ describe('capability_state (tfy.plan fixture)', () => {
const thread = new AgentThread({
definition: {
modelClient: makeMockILLM({ create: jest.fn().mockImplementation(() => emptyLlmStream()) }),
+ modelName: TEST_MODEL_NAME,
},
threadId: MAIN_THREAD_ID,
title: 'main',
diff --git a/packages/trueforge-core/tests/agent-session/resolveAgentSpec.test.ts b/packages/trueforge-core/tests/agent-session/resolveAgentSpec.test.ts
index 7be5397c7..cc9af1652 100644
--- a/packages/trueforge-core/tests/agent-session/resolveAgentSpec.test.ts
+++ b/packages/trueforge-core/tests/agent-session/resolveAgentSpec.test.ts
@@ -85,6 +85,7 @@ describe('TurnResourceResolver.resolveAgentDefinition', () => {
});
expect(definition.modelParams?.['max_tokens']).toBe(expected);
+ expect(definition.modelName).toBe('provider/model');
expect(definition.modelProperties?.contextLength).toBe(128_000);
});
});
diff --git a/packages/trueforge-core/tests/agent-session/testHelpers.ts b/packages/trueforge-core/tests/agent-session/testHelpers.ts
index 281f5cea4..7326fe88c 100644
--- a/packages/trueforge-core/tests/agent-session/testHelpers.ts
+++ b/packages/trueforge-core/tests/agent-session/testHelpers.ts
@@ -21,9 +21,9 @@ import type {
import { getEmptyUsage } from '../../src/core/llm/LLMTypes';
import { getEmptyCurrentContextUsage } from '../../src/core/runtime/contextUsage';
import type { Sandbox } from '../../src/core/sandbox/Sandbox';
-import { makeMockILLM, makeSilentLogger } from '../core/harnessMocks';
+import { makeMockILLM, makeSilentLogger, TEST_MODEL, TEST_MODEL_NAME } from '../core/harnessMocks';
-export { makeMockILLM, makeSilentLogger };
+export { makeMockILLM, makeSilentLogger, TEST_MODEL, TEST_MODEL_NAME };
/** Turn ids are opaque, caller-minted strings; tests only need uniqueness. */
export function mintTestTurnId(): string {
@@ -294,5 +294,6 @@ export function makeModelMessageEvent() {
created_at: new Date().toISOString(),
thread_id: MAIN_THREAD_ID,
content: 'hi',
+ model: TEST_MODEL,
};
}
diff --git a/packages/trueforge-core/tests/core/harnessMocks.ts b/packages/trueforge-core/tests/core/harnessMocks.ts
index ddc1cd805..ccb345aac 100644
--- a/packages/trueforge-core/tests/core/harnessMocks.ts
+++ b/packages/trueforge-core/tests/core/harnessMocks.ts
@@ -1,6 +1,7 @@
import type { Logger } from 'winston';
import winston from 'winston';
import type { ILLM } from '../../src/core/llm/ILLM';
+import type { Model } from '../../src/core/llm/model';
import type { AgentToolSchema, IToolSet, ListToolsResponse } from '../../src/core/mcp/IMCPServer';
import type { SandboxProvider } from '../../src/core/sandbox/provider/Provider';
import { Sandbox } from '../../src/core/sandbox/Sandbox';
@@ -8,6 +9,10 @@ import { NOOP_AGENT_TRACING } from '../../src/core/tracing/NoopAgentTracing';
export const OBJECT_INPUT_SCHEMA = { type: 'object' as const, properties: {} };
+export const TEST_MODEL_NAME = 'test/test-model';
+
+export const TEST_MODEL: Model = { name: TEST_MODEL_NAME };
+
/** Minimal typed ILLM stub — both methods required by the interface. */
export function makeMockILLM(overrides: Partial<ILLM> = {}): ILLM {
return {
diff --git a/packages/trueforge-core/tests/core/llm/toOpenAIChatMessage.test.ts b/packages/trueforge-core/tests/core/llm/toOpenAIChatMessage.test.ts
index a20251ba4..9c5f02b21 100644
--- a/packages/trueforge-core/tests/core/llm/toOpenAIChatMessage.test.ts
+++ b/packages/trueforge-core/tests/core/llm/toOpenAIChatMessage.test.ts
@@ -9,7 +9,7 @@ import { ResponseFormatSchema, toOpenAIResponseFormat } from '../../../src/core/
import { toOpenAIChatMessage } from '../../../src/core/llm/toOpenAIChatMessage';
import { AgentThread } from '../../../src/core/runtime/AgentThread';
import { NOOP_AGENT_TRACING } from '../../../src/core/tracing/NoopAgentTracing';
-import { makeSilentLogger } from '../harnessMocks';
+import { makeSilentLogger, TEST_MODEL_NAME } from '../harnessMocks';
const toolInfo = {
type: 'mcp' as const,
@@ -171,6 +171,7 @@ describe('AgentThread LLM request mapping (end-to-end)', () => {
logger: makeSilentLogger(),
definition: {
modelClient,
+ modelName: TEST_MODEL_NAME,
instruction: 'test',
toolSets: [],
responseFormat: ResponseFormatSchema.parse({
diff --git a/packages/trueforge-core/tests/core/runtime/modelMessageReasoningContent.test.ts b/packages/trueforge-core/tests/core/runtime/modelMessageReasoningContent.test.ts
index 4010f813d..8510070b3 100644
--- a/packages/trueforge-core/tests/core/runtime/modelMessageReasoningContent.test.ts
+++ b/packages/trueforge-core/tests/core/runtime/modelMessageReasoningContent.test.ts
@@ -5,7 +5,7 @@ import { AgentThread } from '../../../src/core/runtime/AgentThread';
import { InternalEventType, type AgentThreadAppendContext } from '../../../src/core/runtime/AgentThread.types';
import { NOOP_AGENT_TRACING } from '../../../src/core/tracing/NoopAgentTracing';
import '../harnessMocks';
-import { makeSilentLogger } from '../harnessMocks';
+import { makeSilentLogger, TEST_MODEL_NAME } from '../harnessMocks';
const silentLogger = makeSilentLogger();
@@ -70,6 +70,7 @@ describe('AgentThread model.message reasoning_content', () => {
logger: silentLogger,
definition: {
modelClient,
+ modelName: TEST_MODEL_NAME,
instruction: 'test',
toolSets: [],
},
diff --git a/packages/trueforge-core/tests/core/runtime/unknownToolLogging.test.ts b/packages/trueforge-core/tests/core/runtime/unknownToolLogging.test.ts
index 9f5361e8c..93aeafb01 100644
--- a/packages/trueforge-core/tests/core/runtime/unknownToolLogging.test.ts
+++ b/packages/trueforge-core/tests/core/runtime/unknownToolLogging.test.ts
@@ -5,7 +5,7 @@ import { AgentThread } from '../../../src/core/runtime/AgentThread';
import { makeUnknownToolInfo, toToolCallInfo } from '../../../src/core/runtime/contextUtils';
import { NOOP_AGENT_TRACING } from '../../../src/core/tracing/NoopAgentTracing';
import '../harnessMocks';
-import { makeSilentLogger } from '../harnessMocks';
+import { makeSilentLogger, TEST_MODEL_NAME } from '../harnessMocks';
const silentLogger = makeSilentLogger();
const warn = jest.spyOn(silentLogger, 'warn');
@@ -95,6 +95,7 @@ describe('AgentThread unknown tool logging', () => {
logger: silentLogger,
definition: {
modelClient,
+ modelName: TEST_MODEL_NAME,
instruction: 'test',
toolSets: [],
},
diff --git a/packages/trueforge-core/tests/orchestration/orchestration.test.ts b/packages/trueforge-core/tests/orchestration/orchestration.test.ts
index 3dceffddb..3414406e5 100644
--- a/packages/trueforge-core/tests/orchestration/orchestration.test.ts
+++ b/packages/trueforge-core/tests/orchestration/orchestration.test.ts
@@ -4,7 +4,7 @@ import { AgentThread } from '../../src/core/runtime/AgentThread';
import { InternalEventType } from '../../src/core/runtime/AgentThread.types';
import { AgentThreadOrchestrator } from '../../src/core/runtime/AgentThreadOrchestrator';
import { NOOP_AGENT_TRACING } from '../../src/core/tracing/NoopAgentTracing';
-import { makeSilentLogger } from '../core/harnessMocks';
+import { makeSilentLogger, TEST_MODEL_NAME } from '../core/harnessMocks';
import { llmCreateInputs, runTurn, textReplyStream } from './helpers/helpers';
const THREAD_ID = 'main';
@@ -45,6 +45,8 @@ describe('orchestration: mocked LLM and no tools', () => {
create: jest.fn().mockImplementation(() => textReplyStream(REPLY)),
createNonStream: jest.fn().mockImplementation(() => textReplyStream(REPLY)),
},
+ modelName: TEST_MODEL_NAME,
+
instruction: INSTRUCTION,
messages: undefined,
modelParams: undefined,
diff --git a/packages/trueforge-core/tests/orchestration/orchestrationApproval.test.ts b/packages/trueforge-core/tests/orchestration/orchestrationApproval.test.ts
index 51b884cb5..6ca11c554 100644
--- a/packages/trueforge-core/tests/orchestration/orchestrationApproval.test.ts
+++ b/packages/trueforge-core/tests/orchestration/orchestrationApproval.test.ts
@@ -7,7 +7,7 @@ import { AgentThread } from '../../src/core/runtime/AgentThread';
import { InternalEventType, type AgentThreadConstructorInput } from '../../src/core/runtime/AgentThread.types';
import { AgentThreadOrchestrator } from '../../src/core/runtime/AgentThreadOrchestrator';
import { NOOP_AGENT_TRACING } from '../../src/core/tracing/NoopAgentTracing';
-import { makeSilentLogger } from '../core/harnessMocks';
+import { makeSilentLogger, TEST_MODEL_NAME } from '../core/harnessMocks';
import {
llmCreateInputs,
runTurn,
@@ -304,7 +304,11 @@ describe('AgentThreadOrchestrator.applyApprovalPolicies', () => {
toolSet = makeApprovalGatedWriteNoteToolSet().toolSet;
const thread = new AgentThread({
definition: {
- modelClient: { create: jest.fn(), createNonStream: jest.fn() },
+ modelClient: {
+ create: jest.fn(),
+ createNonStream: jest.fn(),
+ },
+ modelName: TEST_MODEL_NAME,
instruction: INSTRUCTION,
messages: undefined,
modelParams: undefined,
@@ -474,6 +478,8 @@ function makeApprovalHarness(finalReply: string): {
.mockImplementation(() => textReplyStream(finalReply)),
createNonStream: jest.fn(),
},
+ modelName: TEST_MODEL_NAME,
+
instruction: INSTRUCTION,
messages: undefined,
modelParams: undefined,
diff --git a/packages/trueforge-core/tests/orchestration/orchestrationUserMessageReset.test.ts b/packages/trueforge-core/tests/orchestration/orchestrationUserMessageReset.test.ts
index fbca0cd8c..2cebfa7af 100644
--- a/packages/trueforge-core/tests/orchestration/orchestrationUserMessageReset.test.ts
+++ b/packages/trueforge-core/tests/orchestration/orchestrationUserMessageReset.test.ts
@@ -6,7 +6,7 @@ import type { AgentThreadConstructorInput, ContextMessage } from '../../src/core
import { InternalEventType } from '../../src/core/runtime/AgentThread.types';
import { AgentThreadOrchestrator } from '../../src/core/runtime/AgentThreadOrchestrator';
import { NOOP_AGENT_TRACING } from '../../src/core/tracing/NoopAgentTracing';
-import { makeSilentLogger } from '../core/harnessMocks';
+import { makeSilentLogger, TEST_MODEL, TEST_MODEL_NAME } from '../core/harnessMocks';
import { llmCreateInputs, runExecute, textReplyStream } from './helpers/helpers';
const MAIN_ID = 'main';
@@ -64,6 +64,8 @@ function baseThreadInput(
create: jest.fn().mockImplementation(() => textReplyStream(ROOT_REPLY)),
createNonStream: jest.fn().mockImplementation(() => textReplyStream(ROOT_REPLY)),
},
+ modelName: TEST_MODEL_NAME,
+
instruction: INSTRUCTION,
messages: undefined,
modelParams: undefined,
@@ -110,6 +112,7 @@ describe('orchestration: user-message reset', () => {
}),
createNonStream: jest.fn(),
},
+ modelName: TEST_MODEL_NAME,
instruction: undefined,
messages: undefined,
modelParams: undefined,
@@ -198,6 +201,7 @@ describe('orchestration: user-message reset', () => {
thread_id: CHILD_ID,
content: FINISHED_CHILD_ANSWER,
finish_reason: 'stop',
+ model: TEST_MODEL,
},
send_to_parent: {
role: 'tool',
diff --git a/packages/trueforge-core/tests/orchestration/orchestrationWithTools.test.ts b/packages/trueforge-core/tests/orchestration/orchestrationWithTools.test.ts
index 6db326c38..a1a1a8111 100644
--- a/packages/trueforge-core/tests/orchestration/orchestrationWithTools.test.ts
+++ b/packages/trueforge-core/tests/orchestration/orchestrationWithTools.test.ts
@@ -9,7 +9,7 @@ import {
type AgentThreadOrchestratorInput,
} from '../../src/core/runtime/AgentThreadOrchestrator';
import { NOOP_AGENT_TRACING } from '../../src/core/tracing/NoopAgentTracing';
-import { makeSilentLogger } from '../core/harnessMocks';
+import { makeSilentLogger, TEST_MODEL_NAME } from '../core/harnessMocks';
import { createSubAgentStream, llmCreateInputs, runTurn, textReplyStream } from './helpers/helpers';
const ROOT_ID = 'thread_root';
@@ -121,6 +121,8 @@ describe('orchestration: dynamic sub-agent', () => {
.mockImplementation(() => textReplyStream(ROOT_FINAL)),
createNonStream: jest.fn(),
},
+ modelName: TEST_MODEL_NAME,
+
instruction: INSTRUCTION,
// Undefined
messages: undefined,
@@ -161,6 +163,8 @@ describe('orchestration: dynamic sub-agent', () => {
const agentDefinition: AgentDefinition = {
modelClient: childLLM,
+ modelName: TEST_MODEL_NAME,
+
instruction: undefined,
messages: [{ role: 'user', content: request.input }],
modelParams: parentDefinition.modelParams,
diff --git a/packages/trueforge-sdk/src/api/types/ModelMessageEvent.ts b/packages/trueforge-sdk/src/api/types/ModelMessageEvent.ts
index 65016a942..cfbb973ca 100644
--- a/packages/trueforge-sdk/src/api/types/ModelMessageEvent.ts
+++ b/packages/trueforge-sdk/src/api/types/ModelMessageEvent.ts
@@ -11,6 +11,8 @@ export interface ModelMessageEvent {
finishReason?: TrueForge.FinishReason | null;
/** Unique identifier for the event (monotonic ULID). */
id: string;
+ /** Catalog model FQN (`provider/model`) that produced this message. */
+ model?: TrueForge.ModelMessageEventModel;
/** Optional participant name. */
name?: string;
reasoningContent?: string;
diff --git a/packages/trueforge-sdk/src/api/types/ModelMessageEventModel.ts b/packages/trueforge-sdk/src/api/types/ModelMessageEventModel.ts
new file mode 100644
index 000000000..2498b4a0d
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/types/ModelMessageEventModel.ts
@@ -0,0 +1,12 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as TrueForge from "../index.js";
+
+/**
+ * Catalog model FQN (`provider/model`) that produced this message.
+ */
+export interface ModelMessageEventModel {
+ /** Model FQN: `provider/model`, e.g. `openai/gpt-5.2`. */
+ name: string;
+ params?: TrueForge.ModelParams;
+}
diff --git a/packages/trueforge-sdk/src/api/types/index.ts b/packages/trueforge-sdk/src/api/types/index.ts
index e05a49b08..a4895e9ea 100644
--- a/packages/trueforge-sdk/src/api/types/index.ts
+++ b/packages/trueforge-sdk/src/api/types/index.ts
@@ -141,6 +141,7 @@ export * from "./ModelMessageDeltaEvent.js";
export * from "./ModelMessageEvent.js";
export * from "./ModelMessageEventContent.js";
export * from "./ModelMessageEventContentOneItem.js";
+export * from "./ModelMessageEventModel.js";
export * from "./ModelMessageUsage.js";
export * from "./ModelMessageUsageInputTokensBreakdown.js";
export * from "./ModelParams.js";
diff --git a/packages/trueforge-sdk/src/serialization/types/ModelMessageEvent.ts b/packages/trueforge-sdk/src/serialization/types/ModelMessageEvent.ts
index 0b68a9a0c..1b526a487 100644
--- a/packages/trueforge-sdk/src/serialization/types/ModelMessageEvent.ts
+++ b/packages/trueforge-sdk/src/serialization/types/ModelMessageEvent.ts
@@ -5,6 +5,7 @@ import * as core from "../../core/index.js";
import type * as serializers from "../index.js";
import { FinishReason } from "./FinishReason.js";
import { ModelMessageEventContent } from "./ModelMessageEventContent.js";
+import { ModelMessageEventModel } from "./ModelMessageEventModel.js";
import { ModelMessageUsage } from "./ModelMessageUsage.js";
import { ToolCall } from "./ToolCall.js";
@@ -16,6 +17,7 @@ export const ModelMessageEvent: core.serialization.ObjectSchema<
createdAt: core.serialization.property("created_at", core.serialization.string()),
finishReason: core.serialization.property("finish_reason", FinishReason.optionalNullable()),
id: core.serialization.string(),
+ model: ModelMessageEventModel.optional(),
name: core.serialization.string().optional(),
reasoningContent: core.serialization.property("reasoning_content", core.serialization.string().optional()),
refusal: core.serialization.string().optionalNullable(),
@@ -31,6 +33,7 @@ export declare namespace ModelMessageEvent {
created_at: string;
finish_reason?: (FinishReason.Raw | null | undefined) | null;
id: string;
+ model?: ModelMessageEventModel.Raw | null;
name?: string | null;
reasoning_content?: string | null;
refusal?: (string | null | undefined) | null;
diff --git a/packages/trueforge-sdk/src/serialization/types/ModelMessageEventModel.ts b/packages/trueforge-sdk/src/serialization/types/ModelMessageEventModel.ts
new file mode 100644
index 000000000..5f0111fb5
--- /dev/null
+++ b/packages/trueforge-sdk/src/serialization/types/ModelMessageEventModel.ts
@@ -0,0 +1,21 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as TrueForge from "../../api/index.js";
+import * as core from "../../core/index.js";
+import type * as serializers from "../index.js";
+import { ModelParams } from "./ModelParams.js";
+
+export const ModelMessageEventModel: core.serialization.ObjectSchema<
+ serializers.ModelMessageEventModel.Raw,
+ TrueForge.ModelMessageEventModel
+> = core.serialization.object({
+ name: core.serialization.string(),
+ params: ModelParams.optional(),
+});
+
+export declare namespace ModelMessageEventModel {
+ export interface Raw {
+ name: string;
+ params?: ModelParams.Raw | null;
+ }
+}
diff --git a/packages/trueforge-sdk/src/serialization/types/index.ts b/packages/trueforge-sdk/src/serialization/types/index.ts
index e05a49b08..a4895e9ea 100644
--- a/packages/trueforge-sdk/src/serialization/types/index.ts
+++ b/packages/trueforge-sdk/src/serialization/types/index.ts
@@ -141,6 +141,7 @@ export * from "./ModelMessageDeltaEvent.js";
export * from "./ModelMessageEvent.js";
export * from "./ModelMessageEventContent.js";
export * from "./ModelMessageEventContentOneItem.js";
+export * from "./ModelMessageEventModel.js";
export * from "./ModelMessageUsage.js";
export * from "./ModelMessageUsageInputTokensBreakdown.js";
export * from "./ModelParams.js";
diff --git a/packages/trueforge/src/db/postgres/migrations/20261009_000001_model_message_model_backfill.ts b/packages/trueforge/src/db/postgres/migrations/20261009_000001_model_message_model_backfill.ts
new file mode 100644
index 000000000..83cfe5ef9
--- /dev/null
+++ b/packages/trueforge/src/db/postgres/migrations/20261009_000001_model_message_model_backfill.ts
@@ -0,0 +1,100 @@
+import { sql, type Kysely } from 'kysely';
+
+/**
+ * Backfill `model` on model.message session events and turn state.output for each
+ * session's latest tip turn only (`session.last_turn_id`).
+ *
+ * Prefers `thread.created.agent_info.model` for sub-agent threads when present;
+ * otherwise the session agent FQN (`provider/model`) as `{ name: fqn }`.
+ */
+export async function up<TDatabase>(db: Kysely<TDatabase>): Promise<void> {
+ await sql`SET LOCAL lock_timeout = '5s'`.execute(db);
+
+ await sql`
+ UPDATE session_event e
+ SET event = jsonb_set(
+ e.event,
+ '{model}',
+ jsonb_build_object('name', resolved.model_name),
+ true
+ )
+ FROM (
+ SELECT
+ se.session_id,
+ se.turn_id,
+ se.event_id,
+ COALESCE(
+ (
+ SELECT tc.event #>> '{agent_info,model}'
+ FROM session_event tc
+ WHERE tc.session_id = se.session_id
+ AND tc.event->>'type' = 'thread.created'
+ AND tc.event->>'thread_id' = se.event->>'thread_id'
+ LIMIT 1
+ ),
+ s.agent_spec #>> '{model,name}',
+ a.manifest #>> '{model,name}'
+ ) AS model_name
+ FROM session_event se
+ JOIN session s
+ ON s.session_id = se.session_id
+ LEFT JOIN agent a
+ ON a.tenant_id = s.tenant_id
+ AND a.id = s.agent_id
+ WHERE s.last_turn_id IS NOT NULL
+ AND se.turn_id = s.last_turn_id
+ AND se.event->>'type' = 'model.message'
+ AND se.event->'model' IS NULL
+ ) resolved
+ WHERE e.session_id = resolved.session_id
+ AND e.turn_id = resolved.turn_id
+ AND e.event_id = resolved.event_id
+ AND resolved.model_name IS NOT NULL
+ `.execute(db);
+
+ await sql`
+ UPDATE turn t
+ SET state = jsonb_set(
+ t.state,
+ '{output,model}',
+ jsonb_build_object('name', resolved.model_name),
+ true
+ )
+ FROM (
+ SELECT
+ tu.session_id,
+ tu.turn_id,
+ COALESCE(
+ (
+ SELECT tc.event #>> '{agent_info,model}'
+ FROM session_event tc
+ WHERE tc.session_id = tu.session_id
+ AND tc.event->>'type' = 'thread.created'
+ AND tc.event->>'thread_id' = tu.state->'output'->>'thread_id'
+ LIMIT 1
+ ),
+ s.agent_spec #>> '{model,name}',
+ a.manifest #>> '{model,name}'
+ ) AS model_name
+ FROM turn tu
+ JOIN session s
+ ON s.session_id = tu.session_id
+ LEFT JOIN agent a
+ ON a.tenant_id = s.tenant_id
+ AND a.id = s.agent_id
+ WHERE s.last_turn_id IS NOT NULL
+ AND tu.turn_id = s.last_turn_id
+ AND tu.state->'output'->>'type' = 'model.message'
+ AND tu.state->'output'->'model' IS NULL
+ ) resolved
+ WHERE t.session_id = resolved.session_id
+ AND t.turn_id = resolved.turn_id
+ AND resolved.model_name IS NOT NULL
+ `.execute(db);
+}
+
+/** Data backfill — not reversed. */
+export function down(db: Kysely<unknown>): Promise<void> {
+ void db;
+ return Promise.reject(new Error('20261009_000001_model_message_model_backfill is irreversible'));
+}
diff --git a/packages/trueforge/src/db/sqlite/migrations/20261009_000001_model_message_model_backfill.ts b/packages/trueforge/src/db/sqlite/migrations/20261009_000001_model_message_model_backfill.ts
new file mode 100644
index 000000000..1856ab535
--- /dev/null
+++ b/packages/trueforge/src/db/sqlite/migrations/20261009_000001_model_message_model_backfill.ts
@@ -0,0 +1,94 @@
+import { sql, type Kysely } from 'kysely';
+
+/**
+ * SQLite mirror of postgres/migrations/20261009_000001_model_message_model_backfill.ts.
+ * Backfills only each session's tip turn (`last_turn_id`).
+ * Prefers `thread.created.agent_info.model` when the event's thread has one.
+ */
+export async function up<TDatabase>(db: Kysely<TDatabase>): Promise<void> {
+ await db.transaction().execute(async trx => {
+ await sql`
+ UPDATE session_event
+ SET event = jsonb_set(
+ event,
+ '$.model',
+ jsonb(json_object('name', resolved.model_name))
+ )
+ FROM (
+ SELECT
+ se.session_id AS sid,
+ se.turn_id AS tid,
+ se.event_id AS eid,
+ COALESCE(
+ (
+ SELECT json_extract(tc.event, '$.agent_info.model')
+ FROM session_event tc
+ WHERE tc.session_id = se.session_id
+ AND json_extract(tc.event, '$.type') = 'thread.created'
+ AND json_extract(tc.event, '$.thread_id') = json_extract(se.event, '$.thread_id')
+ ),
+ json_extract(s.agent_spec, '$.model.name'),
+ json_extract(a.manifest, '$.model.name')
+ ) AS model_name
+ FROM session_event se
+ JOIN session s
+ ON s.session_id = se.session_id
+ LEFT JOIN agent a
+ ON a.tenant_id = s.tenant_id
+ AND a.id = s.agent_id
+ WHERE s.last_turn_id IS NOT NULL
+ AND se.turn_id = s.last_turn_id
+ AND json_extract(se.event, '$.type') = 'model.message'
+ AND json_extract(se.event, '$.model') IS NULL
+ ) resolved
+ WHERE session_event.session_id = resolved.sid
+ AND session_event.turn_id = resolved.tid
+ AND session_event.event_id = resolved.eid
+ AND resolved.model_name IS NOT NULL
+ `.execute(trx);
+
+ await sql`
+ UPDATE turn
+ SET state = jsonb_set(
+ state,
+ '$.output.model',
+ jsonb(json_object('name', resolved.model_name))
+ )
+ FROM (
+ SELECT
+ t.session_id AS sid,
+ t.turn_id AS tid,
+ COALESCE(
+ (
+ SELECT json_extract(tc.event, '$.agent_info.model')
+ FROM session_event tc
+ WHERE tc.session_id = t.session_id
+ AND json_extract(tc.event, '$.type') = 'thread.created'
+ AND json_extract(tc.event, '$.thread_id') = json_extract(t.state, '$.output.thread_id')
+ ),
+ json_extract(s.agent_spec, '$.model.name'),
+ json_extract(a.manifest, '$.model.name')
+ ) AS model_name
+ FROM turn t
+ JOIN session s
+ ON s.session_id = t.session_id
+ LEFT JOIN agent a
+ ON a.tenant_id = s.tenant_id
+ AND a.id = s.agent_id
+ WHERE s.last_turn_id IS NOT NULL
+ AND t.turn_id = s.last_turn_id
+ AND json_extract(t.state, '$.output.type') = 'model.message'
+ AND json_extract(t.state, '$.output.model') IS NULL
+ ) resolved
+ WHERE turn.session_id = resolved.sid
+ AND turn.turn_id = resolved.tid
+ AND resolved.model_name IS NOT NULL
+ `.execute(trx);
+ });
+}
+
+/** Data backfill — not reversed. */
+export function down(db: Kysely<unknown>): Promise<void> {
+ void db;
+ return Promise.reject(new Error('20261009_000001_model_message_model_backfill is irreversible'));
+}
diff --git a/python/trueforge_sdk/src/trueforge_sdk/__init__.py b/python/trueforge_sdk/src/trueforge_sdk/__init__.py
index c4ccacf02..76e9965d5 100644
--- a/python/trueforge_sdk/src/trueforge_sdk/__init__.py
+++ b/python/trueforge_sdk/src/trueforge_sdk/__init__.py
@@ -150,6 +150,7 @@ if typing.TYPE_CHECKING:
ModelMessageEvent,
ModelMessageEventContent,
ModelMessageEventContentOneItem,
+ ModelMessageEventModel,
ModelMessageUsage,
ModelMessageUsageInputTokensBreakdown,
ModelParams,
@@ -463,6 +464,7 @@ _dynamic_imports: typing.Dict[str, str] = {
"ModelMessageEvent": ".types",
"ModelMessageEventContent": ".types",
"ModelMessageEventContentOneItem": ".types",
+ "ModelMessageEventModel": ".types",
"ModelMessageUsage": ".types",
"ModelMessageUsageInputTokensBreakdown": ".types",
"ModelParams": ".types",
@@ -786,6 +788,7 @@ __all__ = [
"ModelMessageEvent",
"ModelMessageEventContent",
"ModelMessageEventContentOneItem",
+ "ModelMessageEventModel",
"ModelMessageUsage",
"ModelMessageUsageInputTokensBreakdown",
"ModelParams",
diff --git a/python/trueforge_sdk/src/trueforge_sdk/types/__init__.py b/python/trueforge_sdk/src/trueforge_sdk/types/__init__.py
index 6a92da596..f7bd9bb6a 100644
--- a/python/trueforge_sdk/src/trueforge_sdk/types/__init__.py
+++ b/python/trueforge_sdk/src/trueforge_sdk/types/__init__.py
@@ -149,6 +149,7 @@ if typing.TYPE_CHECKING:
from .model_message_event import ModelMessageEvent
from .model_message_event_content import ModelMessageEventContent
from .model_message_event_content_one_item import ModelMessageEventContentOneItem
+ from .model_message_event_model import ModelMessageEventModel
from .model_message_usage import ModelMessageUsage
from .model_message_usage_input_tokens_breakdown import ModelMessageUsageInputTokensBreakdown
from .model_params import ModelParams
@@ -419,6 +420,7 @@ _dynamic_imports: typing.Dict[str, str] = {
"ModelMessageEvent": ".model_message_event",
"ModelMessageEventContent": ".model_message_event_content",
"ModelMessageEventContentOneItem": ".model_message_event_content_one_item",
+ "ModelMessageEventModel": ".model_message_event_model",
"ModelMessageUsage": ".model_message_usage",
"ModelMessageUsageInputTokensBreakdown": ".model_message_usage_input_tokens_breakdown",
"ModelParams": ".model_params",
@@ -713,6 +715,7 @@ __all__ = [
"ModelMessageEvent",
"ModelMessageEventContent",
"ModelMessageEventContentOneItem",
+ "ModelMessageEventModel",
"ModelMessageUsage",
"ModelMessageUsageInputTokensBreakdown",
"ModelParams",
diff --git a/python/trueforge_sdk/src/trueforge_sdk/types/model_message_event.py b/python/trueforge_sdk/src/trueforge_sdk/types/model_message_event.py
index e3b4157bf..7ae8f5b39 100644
--- a/python/trueforge_sdk/src/trueforge_sdk/types/model_message_event.py
+++ b/python/trueforge_sdk/src/trueforge_sdk/types/model_message_event.py
@@ -7,6 +7,7 @@ from ..core.pydantic_utilities import IS_PYDANTIC_V2
from ..core.unchecked_base_model import UncheckedBaseModel
from .finish_reason import FinishReason
from .model_message_event_content import ModelMessageEventContent
+from .model_message_event_model import ModelMessageEventModel
from .model_message_usage import ModelMessageUsage
from .tool_call import ToolCall
@@ -32,6 +33,11 @@ class ModelMessageEvent(UncheckedBaseModel):
Unique identifier for the event (monotonic ULID).
"""
+ model: typing.Optional[ModelMessageEventModel] = pydantic.Field(default=None)
+ """
+ Catalog model FQN (`provider/model`) that produced this message.
+ """
+
name: typing.Optional[str] = pydantic.Field(default=None)
"""
Optional participant name.
diff --git a/python/trueforge_sdk/src/trueforge_sdk/types/model_message_event_model.py b/python/trueforge_sdk/src/trueforge_sdk/types/model_message_event_model.py
new file mode 100644
index 000000000..c376a505e
--- /dev/null
+++ b/python/trueforge_sdk/src/trueforge_sdk/types/model_message_event_model.py
@@ -0,0 +1,29 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+import pydantic
+from ..core.pydantic_utilities import IS_PYDANTIC_V2
+from ..core.unchecked_base_model import UncheckedBaseModel
+from .model_params import ModelParams
+
+
+class ModelMessageEventModel(UncheckedBaseModel):
+ """
+ Catalog model FQN (`provider/model`) that produced this message.
+ """
+
+ name: str = pydantic.Field()
+ """
+ Model FQN: `provider/model`, e.g. `openai/gpt-5.2`.
+ """
+
+ params: typing.Optional[ModelParams] = None
+
+ if IS_PYDANTIC_V2:
+ model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow") # type: ignore # Pydantic v2
+ else:
+
+ class Config:
+ smart_union = True
+ extra = pydantic.Extra.allow