Skip to content

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

chore: Forward inbound from create-turn to TrueFoundry-mode gateway calls (#764)

Srajan Asthanaffcd60d8949c
diff --git a/.changeset/create-turn-tfy-metadata.md b/.changeset/create-turn-tfy-metadata.md
new file mode 100644
index 000000000..6a71c076e
--- /dev/null
+++ b/.changeset/create-turn-tfy-metadata.md
@@ -0,0 +1,5 @@
+---
+"@truefoundry/trueforge": patch
+---
+
+Forward inbound `x-tfy-metadata` from create-turn to TrueFoundry-mode gateway calls, merged with harness session, turn, and agent ids.
diff --git a/packages/trueforge/src/apis/turns.ts b/packages/trueforge/src/apis/turns.ts
index b08613086..42480a5a5 100644
--- a/packages/trueforge/src/apis/turns.ts
+++ b/packages/trueforge/src/apis/turns.ts
@@ -51,13 +51,15 @@ import { StreamGoneError, type EventSubscription, type EventSubscriptionRegistry
import { mintPeeredTurnId } from '../runtime/peeringIds';
import { validateSandboxFilePath } from '../runtime/sandboxFilePath';
import {
- buildGatewayMetadata,
buildTurnSandbox,
gatewayMetadataHeaders,
getMcpConnection,
getModelDetails,
+ mergeGatewayMetadata,
+ parseGatewayMetadataHeader,
resolveSandboxProvider,
withGatewayMetadataHeaders,
+ X_TFY_METADATA,
} from '../runtime/sessionResources';
import { checkSnapshotStatus } from '../sandbox/providerUtils';
import { canReadAgentBoundResource } from './agentAccess';
@@ -148,6 +150,7 @@ function createTurnResolver(deps: {
userRef: string;
session: SessionHandle;
turnId: string;
+ tfyMetadata: Record<string, string> | undefined;
}): TurnResourceResolver {
const {
mcpServerStore,
@@ -160,11 +163,12 @@ function createTurnResolver(deps: {
userRef,
session,
turnId,
+ tfyMetadata,
} = deps;
const tenant_id = session.tenant_id;
const sessionId = session.session_id;
const metadataHeaders = isTrueFoundryModeEnabled()
- ? gatewayMetadataHeaders(buildGatewayMetadata({ session, turnId }))
+ ? gatewayMetadataHeaders(mergeGatewayMetadata({ session, turnId, tfyMetadata }))
: {};
return new TurnResourceResolver({
@@ -387,9 +391,10 @@ export async function beginTurnExecution(params: {
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, deps } = params;
+ const { session, input, previous_turn_id: previousTurnId, userRef, tfyMetadata, deps } = params;
const sessionId = session.session_id;
const turnId = mintPeeredTurnId(configuration.EXECUTOR_ID);
@@ -406,6 +411,7 @@ export async function beginTurnExecution(params: {
userRef,
session,
turnId,
+ tfyMetadata,
});
// First turn only: derive the title from the first user message. The store
@@ -460,6 +466,7 @@ export async function startTurnInProcess(params: {
input: TurnInputItem[] | undefined;
previous_turn_id: string | undefined;
userRef: string;
+ tfyMetadata?: Record<string, string> | undefined;
deps: BeginTurnExecutionDeps;
}): Promise<TurnHandle> {
const { turn, drainInput } = await beginTurnExecution(params);
@@ -767,11 +774,15 @@ export function createTurnsRouter(deps: TurnsRouterDeps) {
referencedAgent = agent;
}
+ const rawTfyMetadata = c.req.header(X_TFY_METADATA);
+ const tfyMetadata = rawTfyMetadata === undefined ? undefined : parseGatewayMetadataHeader(rawTfyMetadata);
+
const turnParams = {
session,
input: body.input,
previous_turn_id: body.previous_turn_id,
userRef: requestContext.subject.id,
+ tfyMetadata,
deps: {
...deps,
modelProviderStore: deps.resolveModelProviderStore(c, referencedAgent),
diff --git a/packages/trueforge/src/runtime/sessionResources.ts b/packages/trueforge/src/runtime/sessionResources.ts
index 57ef96ea2..ce75c31ef 100644
--- a/packages/trueforge/src/runtime/sessionResources.ts
+++ b/packages/trueforge/src/runtime/sessionResources.ts
@@ -13,6 +13,7 @@ import {
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 type { IMcpServerStore, IMcpServerWithAuthStore } from '../db/mcpServerStore';
import type { IModelProviderStore } from '../db/modelProviderStore';
@@ -34,6 +35,27 @@ export const X_TFY_METADATA = 'x-tfy-metadata';
/** Prefix for harness-owned keys */
export const TFG_METADATA_PREFIX = 'tfg';
+const GatewayMetadataSchema = z.record(z.string().min(1), z.string());
+
+/**
+ * Parse inbound `x-tfy-metadata`. Rejects malformed values rather than dropping them.
+ */
+export function parseGatewayMetadataHeader(raw: string): Record<string, string> {
+ let decoded: unknown;
+ try {
+ decoded = JSON.parse(raw);
+ } catch (error) {
+ throw new HTTPException(400, { message: `${X_TFY_METADATA} must be a JSON object`, cause: error });
+ }
+ const parsed = GatewayMetadataSchema.safeParse(decoded);
+ if (!parsed.success) {
+ throw new HTTPException(400, {
+ message: `${X_TFY_METADATA} must be a JSON object of string values`,
+ });
+ }
+ return parsed.data;
+}
+
export function buildGatewayMetadata(input: { session: SessionHandle; turnId: string }): Record<string, string> {
// Session.metadata is intentionally omitted for now (Unicode-in-header risk); re-add later.
const metadata: Record<string, string> = {
@@ -50,6 +72,18 @@ export function buildGatewayMetadata(input: { session: SessionHandle; turnId: st
return metadata;
}
+/** Inbound x-tfy-metadata first; harness tfg.* always win */
+export function mergeGatewayMetadata(input: {
+ session: SessionHandle;
+ turnId: string;
+ tfyMetadata?: Record<string, string> | undefined;
+}): Record<string, string> {
+ return {
+ ...input.tfyMetadata,
+ ...buildGatewayMetadata({ session: input.session, turnId: input.turnId }),
+ };
+}
+
export function gatewayMetadataHeaders(metadata: Record<string, string>): Record<string, string> {
if (Object.keys(metadata).length === 0) {
return {};
diff --git a/packages/trueforge/tests/unit/apis/turns.test.ts b/packages/trueforge/tests/unit/apis/turns.test.ts
index d7e61d99d..1d893d6e3 100644
--- a/packages/trueforge/tests/unit/apis/turns.test.ts
+++ b/packages/trueforge/tests/unit/apis/turns.test.ts
@@ -193,6 +193,62 @@ describe('turns', () => {
});
});
+ describe('create turn x-tfy-metadata', () => {
+ it('rejects a malformed header before starting the turn', async () => {
+ const db = createSqliteDb(':memory:');
+ await migrateSqliteToLatest(db);
+ const sessionStore = new SqliteSessionStore(db);
+ const sessions = new Sessions({ sessionStore });
+ await sessionStore.createSession({
+ tenant_id: 'default',
+ session_id: 's1',
+ created_by_subject: {
+ subject_id: STANDALONE_REQUEST_CONTEXT.subject.id,
+ subject_type: STANDALONE_REQUEST_CONTEXT.subject.type,
+ subject_display_name: STANDALONE_REQUEST_CONTEXT.subject.display_name,
+ },
+ agent: {
+ type: 'inline',
+ spec: AgentSpecSchema.parse({
+ model: { name: 'test-provider/test-model' },
+ instructions: 'test',
+ }),
+ },
+ custom: null,
+ metadata: {},
+ external_id: null,
+ source: null,
+ });
+
+ const app = new OpenAPIHono();
+ app.route(
+ '/',
+ createTurnsRouter({
+ sessions,
+ sessionStore,
+ activeTurns: new ActiveTurnRegistry(),
+ resolveModelProviderStore: () => new SqliteModelProviderStore(db),
+ resolveMcpServerStore: () => mcpServerStoreWithAuth(db, new SqliteOAuthTokenStore(db)),
+ resolveSkillStore: () => new SqliteSkillStore(db),
+ resolveAgentStore: () => new SqliteAgentStore(db),
+ eventSubscriptions: new EventSubscriptionRegistry(undefined),
+ resolveSandboxProviderStore: () => new SqliteSandboxProviderStore(db),
+ logger: createLogger({ silent: true }),
+ resolveRequestContext: () => STANDALONE_REQUEST_CONTEXT,
+ authorizer: new TrueForgeAuthorizer(),
+ }),
+ );
+
+ const response = await app.request('/s1/turns', {
+ method: 'POST',
+ headers: { 'content-type': 'application/json', 'x-tfy-metadata': 'not-json' },
+ body: JSON.stringify({ stream: false }),
+ });
+ expect(response.status).toBe(400);
+ expect(await response.text()).toContain('x-tfy-metadata must be a JSON object');
+ });
+ });
+
describe('create turn non-streaming', () => {
it('returns the running turn JSON after dual-writing turn.created so subscribe can attach', async () => {
const logger = createLogger({ silent: true });
diff --git a/packages/trueforge/tests/unit/runtime/sessionResources.test.ts b/packages/trueforge/tests/unit/runtime/sessionResources.test.ts
index 9bf1c2566..376665160 100644
--- a/packages/trueforge/tests/unit/runtime/sessionResources.test.ts
+++ b/packages/trueforge/tests/unit/runtime/sessionResources.test.ts
@@ -18,6 +18,8 @@ import {
buildGatewayMetadata,
getModelDetails,
localSandboxSessionSegment,
+ mergeGatewayMetadata,
+ parseGatewayMetadataHeader,
TFG_METADATA_PREFIX,
validateAgentSpec,
withGatewayMetadataHeaders,
@@ -38,6 +40,30 @@ async function createGatewayMetadataSession(input: { agent: SessionAgent }): Pro
});
}
+describe('parseGatewayMetadataHeader', () => {
+ it('parses a JSON object of string values', () => {
+ expect(parseGatewayMetadataHeader(JSON.stringify({ env: 'prod', team: 'platform' }))).toEqual({
+ env: 'prod',
+ team: 'platform',
+ });
+ });
+
+ it.each([
+ ['not json', 'not-json'],
+ ['an array', '[]'],
+ ['a scalar', '"nope"'],
+ ['a value that is not a string', JSON.stringify({ env: 1 })],
+ ])('rejects %s rather than silently dropping caller metadata', (_case, raw) => {
+ expect(() => parseGatewayMetadataHeader(raw)).toThrow(HTTPException);
+ });
+
+ it('keeps the parse failure as the cause, so a bad header can be debugged', () => {
+ expect(() => parseGatewayMetadataHeader('not-json')).toThrow(
+ expect.objectContaining({ cause: expect.any(SyntaxError) }),
+ );
+ });
+});
+
describe('buildGatewayMetadata', () => {
it('stamps session/turn/agent fields only', async () => {
const session = await createGatewayMetadataSession({
@@ -53,6 +79,44 @@ describe('buildGatewayMetadata', () => {
});
});
+describe('mergeGatewayMetadata', () => {
+ it('keeps tfyMetadata keys and overwrites spoofed tfg.* fields so order is maintained', async () => {
+ const session = await createGatewayMetadataSession({
+ agent: { type: 'reference', id: 'agent-1', name: 'my-agent' },
+ });
+
+ expect(
+ mergeGatewayMetadata({
+ session,
+ turnId: 'turn-1',
+ tfyMetadata: {
+ env: 'prod',
+ [`${TFG_METADATA_PREFIX}.session_id`]: 'spoofed-session',
+ [`${TFG_METADATA_PREFIX}.turn_id`]: 'spoofed-turn',
+ [`${TFG_METADATA_PREFIX}.agent_id`]: 'spoofed-agent',
+ [`${TFG_METADATA_PREFIX}.agent_name`]: 'spoofed-name',
+ },
+ }),
+ ).toEqual({
+ env: 'prod',
+ [`${TFG_METADATA_PREFIX}.session_id`]: 'sess-1',
+ [`${TFG_METADATA_PREFIX}.turn_id`]: 'turn-1',
+ [`${TFG_METADATA_PREFIX}.agent_id`]: 'agent-1',
+ [`${TFG_METADATA_PREFIX}.agent_name`]: 'my-agent',
+ });
+ });
+
+ it('matches harness-only stamps when tfyMetadata is absent', async () => {
+ const session = await createGatewayMetadataSession({
+ agent: { type: 'reference', id: 'agent-1', name: 'my-agent' },
+ });
+
+ expect(mergeGatewayMetadata({ session, turnId: 'turn-1' })).toEqual(
+ buildGatewayMetadata({ session, turnId: 'turn-1' }),
+ );
+ });
+});
+
describe('withGatewayMetadataHeaders', () => {
it('merges into async header resolvers and preserves authRequired', async () => {
const withAuth = withGatewayMetadataHeaders({