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.mdnew file mode 100644index 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.tsindex 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 EventSubscriptionRegistryimport { 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.tsindex 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: streturn 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.tsindex 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.tsindex 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({