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.mdnew file mode 100644index 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.tsindex 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.tsindex 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 EventSubscriptionRegistryimport { validateSandboxFilePath } from '../runtime/sandboxFilePath';import {buildTurnSandbox,- gatewayMetadataHeaders,+ gatewayTurnHeaders,getMcpConnection,getModelDetails,- mergeGatewayMetadata,parseGatewayMetadataHeader,resolveSandboxProvider,withGatewayMetadataHeaders,@@ -138,6 +137,18 @@ export type BeginTurnExecutionDeps = Pick<TurnsRouterDeps, 'activeTurns' | 'evenskillStore: 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.tsindex 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: streturn 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>): Recordreturn { [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.tsindex 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' },});