Skip to content

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

chore: Keep product specific metadata out of turn signatures (#768)

Srajan Asthana13c7c4feacfc
diff --git a/.changeset/schedule-turn-gateway-metadata.md b/.changeset/schedule-turn-gateway-metadata.md
new file mode 100644
index 000000000..74b83648f
--- /dev/null
+++ b/.changeset/schedule-turn-gateway-metadata.md
@@ -0,0 +1,5 @@
+---
+"@truefoundry/trueforge": patch
+---
+
+Keep TrueFoundry gateway metadata out of the turns engine behind a required per-turn headers resolver, and keep stamping harness `tfg.*` metadata on schedule-run turns.
diff --git a/packages/trueforge/src/apis/schedules.ts b/packages/trueforge/src/apis/schedules.ts
index da3dcc62d..64afc962e 100644
--- a/packages/trueforge/src/apis/schedules.ts
+++ b/packages/trueforge/src/apis/schedules.ts
@@ -52,6 +52,7 @@ import {
import type { ActiveTurnRegistry } from '../runtime/activeTurns';
import { minIntervalSeconds, nextTriggerAfter } from '../runtime/cron';
import type { EventSubscriptionRegistry } from '../runtime/event-subscription';
+import { gatewayTurnHeaders } from '../runtime/sessionResources';
import {
InvalidCronError,
SCHEDULE_MIN_INTERVAL_SECONDS,
@@ -108,6 +109,7 @@ export async function startScheduleRunOnRequest<TTransaction>(params: {
input: prepared.input,
previous_turn_id: prepared.previous_turn_id,
userRef: prepared.userRef,
+ resolveTurnHeaders: gatewayTurnHeaders,
deps: {
activeTurns: deps.activeTurns,
eventSubscriptions: deps.eventSubscriptions,
diff --git a/packages/trueforge/src/apis/turns.ts b/packages/trueforge/src/apis/turns.ts
index 5d933410f..e47e67f75 100644
--- a/packages/trueforge/src/apis/turns.ts
+++ b/packages/trueforge/src/apis/turns.ts
@@ -33,7 +33,7 @@ import { streamSSE } from 'hono/streaming';
import type { Logger } from 'winston';
import type { Authorizer } from '../auth/authorizer';
import type { ResolveRequestContext } from '../auth/identity';
-import configuration, { isTrueFoundryModeEnabled } from '../config';
+import configuration from '../config';
import type { AgentRecord, IAgentStore } from '../db/agentStore';
import type { IMcpServerWithAuthStore } from '../db/mcpServerStore';
import type { IModelProviderStore } from '../db/modelProviderStore';
@@ -52,10 +52,9 @@ import { StreamGoneError, type EventSubscription, type EventSubscriptionRegistry
import { validateSandboxFilePath } from '../runtime/sandboxFilePath';
import {
buildTurnSandbox,
- gatewayMetadataHeaders,
+ gatewayTurnHeaders,
getMcpConnection,
getModelDetails,
- mergeGatewayMetadata,
parseGatewayMetadataHeader,
resolveSandboxProvider,
withGatewayMetadataHeaders,
@@ -138,6 +137,18 @@ export type BeginTurnExecutionDeps = Pick<TurnsRouterDeps, 'activeTurns' | 'even
skillStore: Pick<ISkillStore, 'resolveTurnSkills'>;
};
+/** Extra LLM/MCP headers resolved after turn id is minted. */
+type ResolveTurnHeaders = (input: { session: SessionHandle; turnId: string }) => Record<string, string>;
+
+interface BeginTurnExecutionParams {
+ session: SessionHandle;
+ input: TurnInputItem[] | undefined;
+ previous_turn_id: string | undefined;
+ userRef: string;
+ resolveTurnHeaders: ResolveTurnHeaders;
+ deps: BeginTurnExecutionDeps;
+}
+
/**
* Builds the per-turn resolver. Agent / MCP / sandbox / LLM lookups are wired
* the same way: async factories over the corresponding stores.
@@ -153,8 +164,7 @@ function createTurnResolver(deps: {
signal: AbortSignal;
userRef: string;
session: SessionHandle;
- turnId: string;
- tfyMetadata: Record<string, string> | undefined;
+ turnHeaders: Record<string, string>;
}): TurnResourceResolver {
const {
mcpServerStore,
@@ -167,14 +177,10 @@ function createTurnResolver(deps: {
signal,
userRef,
session,
- turnId,
- tfyMetadata,
+ turnHeaders,
} = deps;
const tenant_id = session.tenant_id;
const sessionId = session.session_id;
- const metadataHeaders = isTrueFoundryModeEnabled()
- ? gatewayMetadataHeaders(mergeGatewayMetadata({ session, turnId, tfyMetadata }))
- : {};
return new TurnResourceResolver({
llm: async name => {
@@ -187,7 +193,7 @@ function createTurnResolver(deps: {
modelClient: new VercelAILLM({
providerConfig: {
...resolved.providerConfig,
- headers: { ...resolved.providerConfig.headers, ...metadataHeaders },
+ headers: { ...resolved.providerConfig.headers, ...turnHeaders },
},
logger,
signal,
@@ -212,7 +218,7 @@ function createTurnResolver(deps: {
url: connection.url,
headers: withGatewayMetadataHeaders({
headers: connection.headers,
- metadataHeaders,
+ metadataHeaders: turnHeaders,
}),
};
},
@@ -391,15 +397,10 @@ export interface TurnEventDrainInput {
* Shared create-turn engine: persist the turn, start execution, and return the
* drain inputs. Does not wait for events and does not write HTTP/SSE.
*/
-export async function beginTurnExecution(params: {
- session: SessionHandle;
- input: TurnInputItem[] | undefined;
- previous_turn_id: string | undefined;
- userRef: string;
- tfyMetadata?: Record<string, string> | undefined;
- deps: BeginTurnExecutionDeps;
-}): Promise<{ turn: TurnHandle; drainInput: TurnEventDrainInput }> {
- const { session, input, previous_turn_id: previousTurnId, userRef, tfyMetadata, deps } = params;
+export async function beginTurnExecution(
+ params: BeginTurnExecutionParams,
+): Promise<{ turn: TurnHandle; drainInput: TurnEventDrainInput }> {
+ const { session, input, previous_turn_id: previousTurnId, userRef, resolveTurnHeaders, deps } = params;
const sessionId = session.session_id;
const turnId = newId();
@@ -416,8 +417,7 @@ export async function beginTurnExecution(params: {
signal: abortController.signal,
userRef,
session,
- turnId,
- tfyMetadata,
+ turnHeaders: resolveTurnHeaders({ session, turnId }),
});
// First turn only: derive the title from the first user message. The store
@@ -468,14 +468,7 @@ export async function beginTurnExecution(params: {
* Non-stream create-turn: begin execution and resolve once the first event is
* dual-written so immediate subscribe cannot 412. Same as `stream: false`.
*/
-export async function startTurnInProcess(params: {
- session: SessionHandle;
- input: TurnInputItem[] | undefined;
- previous_turn_id: string | undefined;
- userRef: string;
- tfyMetadata?: Record<string, string> | undefined;
- deps: BeginTurnExecutionDeps;
-}): Promise<TurnHandle> {
+export async function startTurnInProcess(params: BeginTurnExecutionParams): Promise<TurnHandle> {
const { turn, drainInput } = await beginTurnExecution(params);
// Same unawaited drain scheduling as Hono streamSSE's run(cb).
@@ -782,14 +775,14 @@ export function createTurnsRouter(deps: TurnsRouterDeps) {
}
const rawTfyMetadata = c.req.header(X_TFY_METADATA);
- const tfyMetadata = rawTfyMetadata === undefined ? undefined : parseGatewayMetadataHeader(rawTfyMetadata);
+ const requestMetadata = rawTfyMetadata === undefined ? undefined : parseGatewayMetadataHeader(rawTfyMetadata);
- const turnParams = {
+ const turnParams: BeginTurnExecutionParams = {
session,
input: body.input,
previous_turn_id: body.previous_turn_id,
userRef: requestContext.subject.id,
- tfyMetadata,
+ resolveTurnHeaders: input => gatewayTurnHeaders({ ...input, requestMetadata }),
deps: {
...deps,
modelProviderStore: deps.resolveModelProviderStore(c, referencedAgent),
diff --git a/packages/trueforge/src/runtime/sessionResources.ts b/packages/trueforge/src/runtime/sessionResources.ts
index c1287be3e..7a01b042d 100644
--- a/packages/trueforge/src/runtime/sessionResources.ts
+++ b/packages/trueforge/src/runtime/sessionResources.ts
@@ -14,7 +14,7 @@ import { HTTPException } from 'hono/http-exception';
import { join } from 'node:path';
import type { Logger } from 'winston';
import { z } from 'zod';
-import configuration from '../config';
+import configuration, { isTrueFoundryModeEnabled } from '../config';
import type { IMcpServerStore, IMcpServerWithAuthStore } from '../db/mcpServerStore';
import type { IModelProviderStore } from '../db/modelProviderStore';
import type { ISandboxProviderStore } from '../db/sandboxProviderStore';
@@ -73,14 +73,14 @@ export function buildGatewayMetadata(input: { session: SessionHandle; turnId: st
return metadata;
}
-/** Inbound x-tfy-metadata first; harness tfg.* always win */
+/** Caller requestMetadata first; harness tfg.* always win */
export function mergeGatewayMetadata(input: {
session: SessionHandle;
turnId: string;
- tfyMetadata?: Record<string, string> | undefined;
+ requestMetadata?: Record<string, string> | undefined;
}): Record<string, string> {
return {
- ...input.tfyMetadata,
+ ...input.requestMetadata,
...buildGatewayMetadata({ session: input.session, turnId: input.turnId }),
};
}
@@ -92,6 +92,21 @@ export function gatewayMetadataHeaders(metadata: Record<string, string>): Record
return { [X_TFY_METADATA]: JSON.stringify(metadata) };
}
+/**
+ * Per-turn gateway headers for LLM/MCP calls: harness tfg.* stamps over caller
+ * metadata. Empty outside TrueFoundry mode. Every turn start must wire this in.
+ */
+export function gatewayTurnHeaders(input: {
+ session: SessionHandle;
+ turnId: string;
+ requestMetadata?: Record<string, string> | undefined;
+}): Record<string, string> {
+ if (!isTrueFoundryModeEnabled()) {
+ return {};
+ }
+ return gatewayMetadataHeaders(mergeGatewayMetadata(input));
+}
+
/**
* Merge gateway metadata into MCP invoke headers. Preserves authRequired;
* metadata is applied after auth/per-server headers.
diff --git a/packages/trueforge/tests/unit/runtime/sessionResources.test.ts b/packages/trueforge/tests/unit/runtime/sessionResources.test.ts
index c48863b1e..5bb8a7c89 100644
--- a/packages/trueforge/tests/unit/runtime/sessionResources.test.ts
+++ b/packages/trueforge/tests/unit/runtime/sessionResources.test.ts
@@ -92,7 +92,7 @@ describe('buildGatewayMetadata', () => {
});
describe('mergeGatewayMetadata', () => {
- it('keeps tfyMetadata keys and overwrites spoofed tfg.* fields so order is maintained', async () => {
+ it('keeps requestMetadata keys and overwrites spoofed tfg.* fields so order is maintained', async () => {
const session = await createGatewayMetadataSession({
agent: { type: 'reference', id: 'agent-1', name: 'my-agent' },
});
@@ -101,7 +101,7 @@ describe('mergeGatewayMetadata', () => {
mergeGatewayMetadata({
session,
turnId: 'turn-1',
- tfyMetadata: {
+ requestMetadata: {
env: 'prod',
[`${TFG_METADATA_PREFIX}.session_id`]: 'spoofed-session',
[`${TFG_METADATA_PREFIX}.turn_id`]: 'spoofed-turn',
@@ -118,7 +118,7 @@ describe('mergeGatewayMetadata', () => {
});
});
- it('matches harness-only stamps when tfyMetadata is absent', async () => {
+ it('matches harness-only stamps when requestMetadata is absent', async () => {
const session = await createGatewayMetadataSession({
agent: { type: 'reference', id: 'agent-1', name: 'my-agent' },
});