The open-source agent harness - the runtime layer that turns an LLM into a working agent.
refactor: Push x-tfy-metadata attaching to truefoundry/ module (#865)
Chirag Jain8a2a77385a91
diff --git a/packages/trueforge/src/apis/schedules.ts b/packages/trueforge/src/apis/schedules.tsindex 75bbf9955..fba8ef5e8 100644--- a/packages/trueforge/src/apis/schedules.ts+++ b/packages/trueforge/src/apis/schedules.ts@@ -53,7 +53,6 @@ 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,@@ -110,7 +109,6 @@ 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 e7a8dd1b8..faef5f957 100644--- a/packages/trueforge/src/apis/turns.ts+++ b/packages/trueforge/src/apis/turns.ts@@ -40,6 +40,7 @@ import type { IMcpServerWithAuthStore } from '../db/mcpServerStore';import type { IModelProviderStore } from '../db/modelProviderStore';import type { ISandboxProviderStore } from '../db/sandboxProviderStore';import type { ISkillStore } from '../db/skillStore';+import type { TurnMetadata } from '../db/turnMetadata';import type { IWebSearchProviderStore } from '../db/webSearchProviderStore';import {createAndExecuteTurnRoute,@@ -55,16 +56,13 @@ import { StreamGoneError, type EventSubscription, type EventSubscriptionRegistryimport { validateSandboxFilePath } from '../runtime/sandboxFilePath';import {buildTurnSandbox,- gatewayTurnHeaders,getMcpConnection,getModelDetails,- parseGatewayMetadataHeader,resolveSandboxProvider,- withGatewayMetadataHeaders,- X_TFY_METADATA,} from '../runtime/sessionResources';import { checkSnapshotStatus } from '../sandbox/providerUtils';import { MAX_SESSION_TITLE_LENGTH } from '../schemas/session';+import { assertGatewayMetadataRequestHeaders } from '../truefoundry/gatewayMetadata';import { newId } from '../utils/id';import { resolveWebSearchProvider } from '../websearch/providers';import { canReadAgentBoundResource, canReadSession } from './agentAccess';@@ -142,15 +140,13 @@ 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;+ /** Raw inbound request headers. Absent for a schedule run. */+ requestHeaders?: Record<string, string>;deps: BeginTurnExecutionDeps;}@@ -169,7 +165,7 @@ function createTurnResolver(deps: {signal: AbortSignal;userRef: string;session: SessionHandle;- turnHeaders: Record<string, string>;+ turnMetadata: TurnMetadata;}): TurnResourceResolver {const {mcpServerStore,@@ -182,7 +178,7 @@ function createTurnResolver(deps: {signal,userRef,session,- turnHeaders,+ turnMetadata,} = deps;const tenant_id = session.tenant_id;const sessionId = session.session_id;@@ -193,13 +189,11 @@ function createTurnResolver(deps: {tenant_id,name,store: modelProviderStore,+ turnMetadata,});return {modelClient: new VercelAILLM({- providerConfig: {- ...resolved.providerConfig,- headers: { ...resolved.providerConfig.headers, ...turnHeaders },- },+ providerConfig: resolved.providerConfig,logger,signal,}),@@ -213,6 +207,7 @@ function createTurnResolver(deps: {name,store: mcpServerStore,userRef,+ turnMetadata,});if (connection === undefined) {throw new HTTPException(422, {@@ -221,10 +216,7 @@ function createTurnResolver(deps: {}return {url: connection.url,- headers: withGatewayMetadataHeaders({- headers: connection.headers,- metadataHeaders: turnHeaders,- }),+ headers: connection.headers,};},mcpRequestTimeoutMs: configuration.MCP_REQUEST_TIMEOUT_MS,@@ -405,9 +397,12 @@ export interface TurnEventDrainInput {export async function beginTurnExecution(params: BeginTurnExecutionParams,): Promise<{ turn: TurnHandle; drainInput: TurnEventDrainInput }> {- const { session, input, previous_turn_id: previousTurnId, userRef, resolveTurnHeaders, deps } = params;+ const { session, input, previous_turn_id: previousTurnId, userRef, requestHeaders, deps } = params;+ // Fail closed on a bad inbound header before minting a turn id / starting execution.+ assertGatewayMetadataRequestHeaders(requestHeaders);const sessionId = session.session_id;const turnId = newId();+ const sessionAgent = session.record.agent;const abortController = new AbortController();const tenant_id = session.tenant_id;@@ -426,7 +421,12 @@ export async function beginTurnExecution(signal: abortController.signal,userRef,session,- turnHeaders: resolveTurnHeaders({ session, turnId }),+ turnMetadata: {+ sessionId: session.session_id,+ turnId,+ ...(sessionAgent.type === 'reference' ? { agent: { id: sessionAgent.id, name: sessionAgent.name } } : {}),+ ...(requestHeaders === undefined ? {} : { requestHeaders }),+ },});// First turn only: derive the title from the first user message. The store@@ -783,15 +783,12 @@ export function createTurnsRouter(deps: TurnsRouterDeps) {referencedAgent = agent;}- const rawTfyMetadata = c.req.header(X_TFY_METADATA);- const requestMetadata = rawTfyMetadata === undefined ? undefined : parseGatewayMetadataHeader(rawTfyMetadata);-const turnParams: BeginTurnExecutionParams = {session,input: body.input,previous_turn_id: body.previous_turn_id,userRef: requestContext.subject.id,- resolveTurnHeaders: input => gatewayTurnHeaders({ ...input, requestMetadata }),+ requestHeaders: c.req.header(),deps: {...deps,modelProviderStore: deps.resolveModelProviderStore(c, referencedAgent),diff --git a/packages/trueforge/src/db/McpServerWithAuthStore.ts b/packages/trueforge/src/db/McpServerWithAuthStore.tsindex 027a40423..5810232bd 100644--- a/packages/trueforge/src/db/McpServerWithAuthStore.ts+++ b/packages/trueforge/src/db/McpServerWithAuthStore.ts@@ -15,6 +15,7 @@ import {type ResolveMcpAuthStatusesInput,type UpsertMcpServerInput,} from './mcpServerStore';+import type { TurnMetadata } from './turnMetadata';export class McpServerWithAuthStore<TTransaction = never> implements IMcpServerWithAuthStore<TTransaction> {readonly #store: IMcpServerStore<TTransaction>;@@ -51,7 +52,11 @@ export class McpServerWithAuthStore<TTransaction = never> implements IMcpServerWreturn this.#store.upsertServer(input, transaction);}- resolveInvokeHeaders(input: { record: McpServerRecord; userRef: string }): RemoteMcpHeaders {+ resolveInvokeHeaders(input: {+ record: McpServerRecord;+ userRef: string;+ turnMetadata?: TurnMetadata;+ }): RemoteMcpHeaders {const { record, userRef } = input;if (record.manifest.auth?.type === 'dcr') {return async () => {diff --git a/packages/trueforge/src/db/mcpServerStore.ts b/packages/trueforge/src/db/mcpServerStore.tsindex 3ed4fe735..44f4865f8 100644--- a/packages/trueforge/src/db/mcpServerStore.ts+++ b/packages/trueforge/src/db/mcpServerStore.ts@@ -7,6 +7,7 @@ import type {} from '../mcp/auth/types';import type { ResourceName } from '../schemas/common';import type { McpAuthStatus, McpServerManifest } from '../schemas/mcpServer';+import type { TurnMetadata } from './turnMetadata';export interface McpServerRecord {id: string;@@ -113,7 +114,11 @@ export interface IMcpServerWithAuthStore<TTransaction = never> extends IMcpServedeleteAuthorization(input: DeleteMcpAuthorizationInput): Promise<void>;/** Headers for MCP invoke; may be static or an async resolver that can return `authRequired`. */- resolveInvokeHeaders(input: { record: McpServerRecord; userRef: string }): RemoteMcpHeaders;+ resolveInvokeHeaders(input: {+ record: McpServerRecord;+ userRef: string;+ turnMetadata?: TurnMetadata;+ }): RemoteMcpHeaders;}/**diff --git a/packages/trueforge/src/db/modelProviderStore.ts b/packages/trueforge/src/db/modelProviderStore.tsindex fb4ce3d8f..2396f9751 100644--- a/packages/trueforge/src/db/modelProviderStore.ts+++ b/packages/trueforge/src/db/modelProviderStore.ts@@ -5,6 +5,7 @@*/import type { ResourceName } from '../schemas/common';import type { AvailableModel, ModelProviderManifest } from '../schemas/modelProvider';+import type { TurnMetadata } from './turnMetadata';export interface ModelProviderRecord {tenant_id: string;@@ -72,6 +73,11 @@ export interface IModelProviderStore<TTransaction = never> {upsertProvider(input: UpsertModelProviderInput, transaction?: TTransaction): Promise<ModelProviderRecord>;/** Flattens manifests into the FQN read view for GET /models. */listModels(input: ListModelProvidersInput, transaction?: TTransaction): Promise<AvailableModel[]>;+ /** Extra headers for a model invoke. */+ resolveInvokeHeaders(input: {+ record: ModelProviderRecord;+ turnMetadata?: TurnMetadata;+ }): Promise<Record<string, string>>;}/** Application-side flatten shared by both store implementations. */diff --git a/packages/trueforge/src/db/postgres/model-provider-store/PostgresModelProviderStore.ts b/packages/trueforge/src/db/postgres/model-provider-store/PostgresModelProviderStore.tsindex 176222c9a..e787b477b 100644--- a/packages/trueforge/src/db/postgres/model-provider-store/PostgresModelProviderStore.ts+++ b/packages/trueforge/src/db/postgres/model-provider-store/PostgresModelProviderStore.ts@@ -126,6 +126,10 @@ export class PostgresModelProviderStore implements IModelProviderStore<Transactireturn toRecord(row);}+ resolveInvokeHeaders(): Promise<Record<string, string>> {+ return Promise.resolve({});+ }+async listModels(input: ListModelProvidersInput, transaction?: Transaction<Database>): Promise<AvailableModel[]> {return flattenProviderModels(await this.listProviders(input, transaction));}diff --git a/packages/trueforge/src/db/sqlite/model-provider-store/SqliteModelProviderStore.ts b/packages/trueforge/src/db/sqlite/model-provider-store/SqliteModelProviderStore.tsindex b8fc06ebd..312d55bc2 100644--- a/packages/trueforge/src/db/sqlite/model-provider-store/SqliteModelProviderStore.ts+++ b/packages/trueforge/src/db/sqlite/model-provider-store/SqliteModelProviderStore.ts@@ -127,6 +127,10 @@ export class SqliteModelProviderStore implements IModelProviderStore<Transaction.executeTakeFirstOrThrow();}+ resolveInvokeHeaders(): Promise<Record<string, string>> {+ return Promise.resolve({});+ }+async listModels(input: ListModelProvidersInput, transaction?: Transaction<Database>): Promise<AvailableModel[]> {return flattenProviderModels(await this.listProviders(input, transaction));}diff --git a/packages/trueforge/src/db/turnMetadata.ts b/packages/trueforge/src/db/turnMetadata.tsnew file mode 100644index 000000000..fbc403052--- /dev/null+++ b/packages/trueforge/src/db/turnMetadata.ts@@ -0,0 +1,11 @@+/**+ * Fields a turn needs to stamp gateway metadata, plus the raw inbound request headers.+ * TrueFoundry stores read the headers they care about. Other stores ignore them.+ */+export interface TurnMetadata {+ sessionId: string;+ turnId: string;+ /** Saved agent. Inline sessions have no registry id to stamp. */+ agent?: { id: string; name: string | null };+ requestHeaders?: Record<string, string>;+}diff --git a/packages/trueforge/src/runtime/sessionResources.ts b/packages/trueforge/src/runtime/sessionResources.tsindex f2670ba92..dd2f6b7a6 100644--- a/packages/trueforge/src/runtime/sessionResources.ts+++ b/packages/trueforge/src/runtime/sessionResources.ts@@ -1,4 +1,4 @@-import type { AgentSpec, SessionHandle } from '@truefoundry/trueforge-core/agent-session';+import type { AgentSpec } from '@truefoundry/trueforge-core/agent-session';import {Sandbox,SkillMounter,@@ -13,12 +13,12 @@ import {import { HTTPException } from 'hono/http-exception';import { join } from 'node:path';import type { Logger } from 'winston';-import { z } from 'zod';-import configuration, { isTrueFoundryModeEnabled } from '../config';+import configuration from '../config';import type { IMcpServerStore, IMcpServerWithAuthStore } from '../db/mcpServerStore';import type { IModelProviderStore } from '../db/modelProviderStore';import type { ISandboxProviderStore } from '../db/sandboxProviderStore';import type { ISkillStore } from '../db/skillStore';+import type { TurnMetadata } from '../db/turnMetadata';import type { IWebSearchProviderStore } from '../db/webSearchProviderStore';import { LocalSandboxProvider } from '../sandbox/local/provider/LocalSandboxProvider';import { getCachedLocalSandboxSupport, isLocalSandboxFallbackEnabled } from '../sandbox/localRuntime';@@ -31,107 +31,6 @@ export interface McpConnection {headers: RemoteMcpHeaders;}-/** Gateway header carrying stringified JSON metadata. */-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> = {- [`${TFG_METADATA_PREFIX}.session_id`]: input.session.session_id,- [`${TFG_METADATA_PREFIX}.turn_id`]: input.turnId,- };- const { agent } = input.session;- if (agent.type === 'reference') {- metadata[`${TFG_METADATA_PREFIX}.agent_id`] = agent.id;- if (agent.name !== null) {- metadata[`${TFG_METADATA_PREFIX}.agent_name`] = agent.name;- }- }- return metadata;-}--/** Caller requestMetadata first; harness tfg.* always win */-export function mergeGatewayMetadata(input: {- session: SessionHandle;- turnId: string;- requestMetadata?: Record<string, string> | undefined;-}): Record<string, string> {- return {- ...input.requestMetadata,- ...buildGatewayMetadata({ session: input.session, turnId: input.turnId }),- };-}--export function gatewayMetadataHeaders(metadata: Record<string, string>): Record<string, string> {- if (Object.keys(metadata).length === 0) {- return {};- }- 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.- */-export function withGatewayMetadataHeaders(input: {- headers: RemoteMcpHeaders;- metadataHeaders: Record<string, string>;-}): RemoteMcpHeaders {- const { headers, metadataHeaders } = input;- if (Object.keys(metadataHeaders).length === 0) {- return headers;- }- if (typeof headers !== 'function') {- return { ...headers, ...metadataHeaders };- }- return async () => {- const result = await headers();- if ('authRequired' in result) {- return result;- }- return { headers: { ...result.headers, ...metadataHeaders } };- };-}-/** Split `provider/model` FQN. Returns undefined when the shape is not exactly one slash. */export function parseModelFqn(name: string): { providerName: string; modelName: string } | undefined {const slash = name.indexOf('/');@@ -153,10 +52,12 @@ export async function getModelDetails({tenant_id,name,store,+ turnMetadata,}: {tenant_id: string;name: string;store: IModelProviderStore;+ turnMetadata?: TurnMetadata;}): Promise<{providerConfig: VercelAIProviderConfig;defaultModelParams: ModelParams;@@ -195,7 +96,7 @@ export async function getModelDetails({name,baseUrl,apiKey: provider.manifest.auth?.api_key ?? '',- headers: {},+ headers: turnMetadata === undefined ? {} : await store.resolveInvokeHeaders({ record: provider, turnMetadata }),},defaultModelParams: model.properties.max_output_tokens ? { max_tokens: model.properties.max_output_tokens } : {},modelProperties: { contextLength: model.properties.context_length },@@ -213,11 +114,13 @@ export async function getMcpConnection({name,store,userRef,+ turnMetadata,}: {tenant_id: string;name: string;store: IMcpServerWithAuthStore;userRef: string;+ turnMetadata?: TurnMetadata;}): Promise<McpConnection | undefined> {const record = await store.getServer({ tenant_id, name });if (record === undefined) {@@ -225,7 +128,11 @@ export async function getMcpConnection({}return {url: record.manifest.url,- headers: store.resolveInvokeHeaders({ record, userRef }),+ headers: store.resolveInvokeHeaders({+ record,+ userRef,+ ...(turnMetadata === undefined ? {} : { turnMetadata }),+ }),};}diff --git a/packages/trueforge/src/truefoundry/InlineMcpServerStore.ts b/packages/trueforge/src/truefoundry/InlineMcpServerStore.tsindex 3d7b4135f..1ae552fc1 100644--- a/packages/trueforge/src/truefoundry/InlineMcpServerStore.ts+++ b/packages/trueforge/src/truefoundry/InlineMcpServerStore.ts@@ -10,8 +10,10 @@ import type {ResolveMcpAuthStatusesInput,UpsertMcpServerInput,} from '../db/mcpServerStore';+import type { TurnMetadata } from '../db/turnMetadata';import type { OAuthClientRecord } from '../mcp/auth/types';import { resolveConfiguredMcpRequestHeaders, resolveMcpAuthStatus, type McpAuthStatus } from '../schemas/mcpServer';+import { gatewayMetadataHeadersForTurn } from './gatewayMetadata';import type { InlineMcpServers } from './inlineResources';/**@@ -34,13 +36,22 @@ export class InlineMcpServerStore<TTransaction = never> implements IMcpServerWit/*** The manifest carries its own credentials, so they go to the upstream as written — no caller* bearer is added and nothing is stripped. That is what lets a token rotate per request.+ * When mid-turn, still stamp `x-tfy-metadata` the same way registry TrueFoundry invokes do.*/- resolveInvokeHeaders(input: { record: McpServerRecord; userRef: string }): RemoteMcpHeaders {+ resolveInvokeHeaders(input: {+ record: McpServerRecord;+ userRef: string;+ turnMetadata?: TurnMetadata;+ }): RemoteMcpHeaders {const manifest = this.#inline[input.record.name];if (manifest === undefined) {return this.#inner.resolveInvokeHeaders(input);}- return resolveConfiguredMcpRequestHeaders(manifest);+ const configured = resolveConfiguredMcpRequestHeaders(manifest);+ if (input.turnMetadata === undefined) {+ return configured;+ }+ return { ...configured, ...gatewayMetadataHeadersForTurn(input.turnMetadata) };}async getServer(input: GetMcpServerInput, transaction?: TTransaction): Promise<McpServerRecord | undefined> {diff --git a/packages/trueforge/src/truefoundry/TrueFoundryMcpServerStore.ts b/packages/trueforge/src/truefoundry/TrueFoundryMcpServerStore.tsindex 91c996dbf..25553b72a 100644--- a/packages/trueforge/src/truefoundry/TrueFoundryMcpServerStore.ts+++ b/packages/trueforge/src/truefoundry/TrueFoundryMcpServerStore.ts@@ -17,10 +17,12 @@ import {type ResolveMcpAuthStatusesInput,type UpsertMcpServerInput,} from '../db/mcpServerStore';+import type { TurnMetadata } from '../db/turnMetadata';import type { OAuthClientRecord } from '../mcp/auth/types';import { resolveMcpAuthStatus, type McpAuthStatus } from '../schemas/mcpServer';import { accessTokenForRequest, asTrueFoundryRequestContext, type ResolveAccessToken } from './accessToken';import { trueFoundryManaged } from './errors';+import { gatewayMetadataHeadersForTurn } from './gatewayMetadata';import { resolveDefaultGatewayUrl } from './mapEnabledModels';import {mapSfyMcpServers,@@ -101,8 +103,12 @@ export class TrueFoundryMcpServerStore<TTransaction = never> implements IMcpServ}/** Gateway Bearer (+ optional per-server overrides); SFY authorize first, else authRequired. */- resolveInvokeHeaders(input: { record: McpServerRecord; userRef: string }): RemoteMcpHeaders {- const { record, userRef } = input;+ resolveInvokeHeaders(input: {+ record: McpServerRecord;+ userRef: string;+ turnMetadata?: TurnMetadata;+ }): RemoteMcpHeaders {+ const { record, userRef, turnMetadata } = input;const headers = async (): Promise<Record<string, string>> => ({...withoutAuthorization(this.#perServerHeaders[record.name]),Authorization: `Bearer ${await this.#asUser()}`,@@ -126,7 +132,11 @@ export class TrueFoundryMcpServerStore<TTransaction = never> implements IMcpServ},};}- return { headers: await headers() };+ const invokeHeaders = await headers();+ if (turnMetadata === undefined) {+ return { headers: invokeHeaders };+ }+ return { headers: { ...invokeHeaders, ...gatewayMetadataHeadersForTurn(turnMetadata) } };};}diff --git a/packages/trueforge/src/truefoundry/TrueFoundryModelProviderStore.ts b/packages/trueforge/src/truefoundry/TrueFoundryModelProviderStore.tsindex 03a235aa9..3eede1b84 100644--- a/packages/trueforge/src/truefoundry/TrueFoundryModelProviderStore.ts+++ b/packages/trueforge/src/truefoundry/TrueFoundryModelProviderStore.ts@@ -11,9 +11,11 @@ import {type ModelProviderRecord,type UpsertModelProviderInput,} from '../db/modelProviderStore';+import type { TurnMetadata } from '../db/turnMetadata';import type { AvailableModel, ModelProviderManifest } from '../schemas/modelProvider';import { accessTokenForRequest, asTrueFoundryRequestContext, type ResolveAccessToken } from './accessToken';import { trueFoundryManaged } from './errors';+import { gatewayMetadataHeadersForTurn } from './gatewayMetadata';import {filterEnvModels,mapEnabledModels,@@ -86,6 +88,17 @@ export class TrueFoundryModelProviderStore<TTransaction = never> implements IModreturn flattenProviderModels(await this.listProviders(input, transaction));}+ resolveInvokeHeaders(input: {+ record: ModelProviderRecord;+ turnMetadata?: TurnMetadata;+ }): Promise<Record<string, string>> {+ void input.record;+ if (input.turnMetadata === undefined) {+ return Promise.resolve({});+ }+ return Promise.resolve(gatewayMetadataHeadersForTurn(input.turnMetadata));+ }+async #records(input: {tenant_id: string;filter?: { provider_account_name: string; name: string };diff --git a/packages/trueforge/src/truefoundry/gatewayMetadata.ts b/packages/trueforge/src/truefoundry/gatewayMetadata.tsnew file mode 100644index 000000000..c09ec78aa--- /dev/null+++ b/packages/trueforge/src/truefoundry/gatewayMetadata.ts@@ -0,0 +1,114 @@+import { HTTPException } from 'hono/http-exception';+import { z } from 'zod';+import type { TurnMetadata } from '../db/turnMetadata';++/** Gateway header carrying stringified JSON metadata. */+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;+}++/**+ * Reject a malformed inbound `x-tfy-metadata` before the turn starts.+ * No-op when the header is absent (e.g. schedule runs).+ */+export function assertGatewayMetadataRequestHeaders(headers: Record<string, string> | undefined): void {+ if (headers === undefined) {+ return;+ }+ const raw = headerValue(headers, X_TFY_METADATA);+ if (raw !== undefined) {+ parseGatewayMetadataHeader(raw);+ }+}++export function buildGatewayMetadata(input: {+ sessionId: string;+ turnId: string;+ agent?: { id: string; name: string | null };+}): Record<string, string> {+ // Session.metadata is intentionally omitted for now (Unicode-in-header risk); re-add later.+ const metadata: Record<string, string> = {+ [`${TFG_METADATA_PREFIX}.session_id`]: input.sessionId,+ [`${TFG_METADATA_PREFIX}.turn_id`]: input.turnId,+ };+ const { agent } = input;+ if (agent !== undefined) {+ metadata[`${TFG_METADATA_PREFIX}.agent_id`] = agent.id;+ if (agent.name !== null) {+ metadata[`${TFG_METADATA_PREFIX}.agent_name`] = agent.name;+ }+ }+ return metadata;+}++/** Caller requestMetadata first; harness tfg.* always win. */+export function mergeGatewayMetadata(input: {+ sessionId: string;+ turnId: string;+ agent?: { id: string; name: string | null };+ requestMetadata?: Record<string, string> | undefined;+}): Record<string, string> {+ return {+ ...input.requestMetadata,+ ...buildGatewayMetadata({+ sessionId: input.sessionId,+ turnId: input.turnId,+ ...(input.agent === undefined ? {} : { agent: input.agent }),+ }),+ };+}++export function gatewayMetadataHeaders(metadata: Record<string, string>): Record<string, string> {+ if (Object.keys(metadata).length === 0) {+ return {};+ }+ return { [X_TFY_METADATA]: JSON.stringify(metadata) };+}++/** Metadata header for a turn. Reads `x-tfy-metadata` from the raw request headers. */+export function gatewayMetadataHeadersForTurn(turnMetadata: TurnMetadata): Record<string, string> {+ const raw = headerValue(turnMetadata.requestHeaders, X_TFY_METADATA);+ return gatewayMetadataHeaders(+ mergeGatewayMetadata({+ sessionId: turnMetadata.sessionId,+ turnId: turnMetadata.turnId,+ ...(turnMetadata.agent === undefined ? {} : { agent: turnMetadata.agent }),+ requestMetadata: raw === undefined ? undefined : parseGatewayMetadataHeader(raw),+ }),+ );+}++function headerValue(headers: Record<string, string> | undefined, name: string): string | undefined {+ if (headers === undefined) {+ return undefined;+ }+ const target = name.toLowerCase();+ for (const [key, value] of Object.entries(headers)) {+ if (key.toLowerCase() === target) {+ return value;+ }+ }+ return undefined;+}diff --git a/packages/trueforge/tests/unit/runtime/sessionResources.test.ts b/packages/trueforge/tests/unit/runtime/sessionResources.test.tsindex 839655c29..37c9bddc4 100644--- a/packages/trueforge/tests/unit/runtime/sessionResources.test.ts+++ b/packages/trueforge/tests/unit/runtime/sessionResources.test.ts@@ -1,10 +1,4 @@-import {- AgentSpecSchema,- InMemorySessionStore,- Sessions,- type SessionAgent,- type SessionHandle,-} from '@truefoundry/trueforge-core/agent-session';+import { AgentSpecSchema } from '@truefoundry/trueforge-core/agent-session';import { HTTPException } from 'hono/http-exception';import { validateGitAgentSkills } from '../../../src/db/gitSkillMounts';import { migrateSqliteToLatest } from '../../../src/db/migrateSqlite';@@ -15,17 +9,7 @@ import { SqliteModelProviderStore } from '../../../src/db/sqlite/model-provider-import { SqliteSandboxProviderStore } from '../../../src/db/sqlite/sandbox-provider-store/SqliteSandboxProviderStore';import { SqliteSkillStore } from '../../../src/db/sqlite/skill-store/SqliteSkillStore';import { SqliteWebSearchProviderStore } from '../../../src/db/sqlite/web-search-provider-store/SqliteWebSearchProviderStore';-import {- buildGatewayMetadata,- getModelDetails,- localSandboxSessionSegment,- mergeGatewayMetadata,- parseGatewayMetadataHeader,- TFG_METADATA_PREFIX,- validateAgentSpec,- withGatewayMetadataHeaders,- X_TFY_METADATA,-} from '../../../src/runtime/sessionResources';+import { getModelDetails, localSandboxSessionSegment, validateAgentSpec } from '../../../src/runtime/sessionResources';import { setCachedLocalSandboxSupport } from '../../../src/sandbox/localRuntime';import type { ReasoningEffort } from '../../../src/schemas/modelProvider';import { hasConfiguredWebSearchProvider } from '../../../src/websearch/providers';@@ -34,128 +18,6 @@ jest.mock('../../../src/websearch/providers', () => ({hasConfiguredWebSearchProvider: jest.fn(() => Promise.resolve(false)),}));-async function createGatewayMetadataSession(input: { agent: SessionAgent }): Promise<SessionHandle> {- const sessions = new Sessions({ sessionStore: new InMemorySessionStore() });- return sessions.create({- tenant_id: 'tenant-1',- session_id: 'sess-1',- created_by_subject: { subject_id: 'user-1', subject_type: 'user', subject_display_name: 'user-1' },- agent: input.agent,- metadata: {},- external_id: null,- });-}--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({- agent: { type: 'reference', id: 'agent-1', name: 'my-agent' },- });-- expect(buildGatewayMetadata({ session, turnId: 'turn-1' })).toEqual({- [`${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',- });- });-});--describe('mergeGatewayMetadata', () => {- 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' },- });-- expect(- mergeGatewayMetadata({- session,- turnId: 'turn-1',- requestMetadata: {- 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 requestMetadata 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({- headers: async () => ({ headers: { Authorization: 'Bearer t' } }),- metadataHeaders: { [X_TFY_METADATA]: '{"k":"v"}' },- });- expect(typeof withAuth).toBe('function');- if (typeof withAuth !== 'function') {- throw new Error('expected async header resolver');- }- await expect(withAuth()).resolves.toEqual({- headers: {- Authorization: 'Bearer t',- [X_TFY_METADATA]: '{"k":"v"}',- },- });-- const authRequired = withGatewayMetadataHeaders({- headers: async () => ({- authRequired: { servers: [{ id: 'mcp', name: 'mcp', auth_url: 'https://auth.example' }] },- }),- metadataHeaders: { [X_TFY_METADATA]: '{"k":"v"}' },- });- expect(typeof authRequired).toBe('function');- if (typeof authRequired !== 'function') {- throw new Error('expected async header resolver');- }- await expect(authRequired()).resolves.toEqual({- authRequired: { servers: [{ id: 'mcp', name: 'mcp', auth_url: 'https://auth.example' }] },- });- });-});-describe('localSandboxSessionSegment', () => {it('keeps a single-segment session id and rejects missing or unsafe values', () => {expect(localSandboxSessionSegment('sess_1')).toBe('sess_1');diff --git a/packages/trueforge/tests/unit/truefoundry/TrueFoundryMcpServerStore.test.ts b/packages/trueforge/tests/unit/truefoundry/TrueFoundryMcpServerStore.test.tsindex f20e1ceb2..4cdf67db5 100644--- a/packages/trueforge/tests/unit/truefoundry/TrueFoundryMcpServerStore.test.ts+++ b/packages/trueforge/tests/unit/truefoundry/TrueFoundryMcpServerStore.test.ts@@ -3,6 +3,7 @@ import { createLogger } from 'winston';import type { AgentRecord } from '../../../src/db/agentStore';import { McpServerNotFoundError, type McpServerRecord } from '../../../src/db/mcpServerStore';import { createTrueFoundryRequestContext } from '../../../src/truefoundry/accessToken';+import { X_TFY_METADATA } from '../../../src/truefoundry/gatewayMetadata';import { MCP_PROXY_BASE_URL_TEMPLATE } from '../../../src/truefoundry/mapSfyMcpServers';import type { TrueFoundryMcpApiClient } from '../../../src/truefoundry/TrueFoundryMcpServerStore';import {@@ -325,6 +326,44 @@ describe('TrueFoundryMcpServerStore', () => {});});+ it('merges turn metadata after auth headers and leaves authRequired untouched', async () => {+ const { store, client } = createStore();+ const headers = store.resolveInvokeHeaders({+ record: dcrRecord(),+ userRef: 'user-1',+ turnMetadata: {+ sessionId: 'sess-1',+ turnId: 'turn-1',+ agent: { id: 'agent-1', name: 'named' },+ requestHeaders: { 'x-tfy-metadata': JSON.stringify({ env: 'prod' }) },+ },+ });+ if (typeof headers !== 'function') {+ throw new Error('expected async headers resolver for truefoundry MCP');+ }+ const resolved = await headers();+ expect(resolved).toEqual({+ headers: {+ Authorization: `Bearer ${ACCESS_TOKEN}`,+ [X_TFY_METADATA]: expect.any(String),+ },+ });+ if (!('headers' in resolved) || resolved.headers === undefined) {+ throw new Error('expected invoke headers');+ }+ expect(JSON.parse(resolved.headers[X_TFY_METADATA] ?? '')).toMatchObject({ env: 'prod' });++ client.getMcpAuthorize.mockResolvedValue({+ status: 'auth_required',+ authorization_url: 'https://consent.example/authorize',+ });+ await expect(headers()).resolves.toEqual({+ authRequired: {+ servers: [{ id: 'github', name: 'github', auth_url: 'https://consent.example/authorize' }],+ },+ });+ });+it('uses asUser for authorize and gateway Bearer, asAgent for SFY lookups with a saved agent', async () => {const { store, client } = createStore({ agent: AGENT });await expect(invoke(store)).resolves.toEqual({diff --git a/packages/trueforge/tests/unit/truefoundry/gatewayMetadata.test.ts b/packages/trueforge/tests/unit/truefoundry/gatewayMetadata.test.tsnew file mode 100644index 000000000..427c1d7b6--- /dev/null+++ b/packages/trueforge/tests/unit/truefoundry/gatewayMetadata.test.ts@@ -0,0 +1,115 @@+import { HTTPException } from 'hono/http-exception';+import {+ assertGatewayMetadataRequestHeaders,+ buildGatewayMetadata,+ gatewayMetadataHeadersForTurn,+ mergeGatewayMetadata,+ parseGatewayMetadataHeader,+ TFG_METADATA_PREFIX,+ X_TFY_METADATA,+} from '../../../src/truefoundry/gatewayMetadata';++const AGENT = { id: 'agent-1', name: 'my-agent' };++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('assertGatewayMetadataRequestHeaders', () => {+ it('is a no-op when the header is absent', () => {+ expect(() => assertGatewayMetadataRequestHeaders(undefined)).not.toThrow();+ expect(() => assertGatewayMetadataRequestHeaders({})).not.toThrow();+ });++ it('rejects a malformed header before callers mint a turn', () => {+ expect(() => assertGatewayMetadataRequestHeaders({ [X_TFY_METADATA]: 'not-json' })).toThrow(HTTPException);+ });+});++describe('buildGatewayMetadata', () => {+ it('stamps session/turn/agent fields only', () => {+ expect(buildGatewayMetadata({ sessionId: 'sess-1', turnId: 'turn-1', agent: AGENT })).toEqual({+ [`${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('omits agent fields when the session has no saved agent', () => {+ expect(buildGatewayMetadata({ sessionId: 'sess-1', turnId: 'turn-1' })).toEqual({+ [`${TFG_METADATA_PREFIX}.session_id`]: 'sess-1',+ [`${TFG_METADATA_PREFIX}.turn_id`]: 'turn-1',+ });+ });+});++describe('mergeGatewayMetadata', () => {+ it('keeps requestMetadata keys and overwrites spoofed tfg.* fields so order is maintained', () => {+ expect(+ mergeGatewayMetadata({+ sessionId: 'sess-1',+ turnId: 'turn-1',+ agent: AGENT,+ requestMetadata: {+ 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 requestMetadata is absent', () => {+ expect(mergeGatewayMetadata({ sessionId: 'sess-1', turnId: 'turn-1', agent: AGENT })).toEqual(+ buildGatewayMetadata({ sessionId: 'sess-1', turnId: 'turn-1', agent: AGENT }),+ );+ });+});++describe('gatewayMetadataHeadersForTurn', () => {+ it('reads x-tfy-metadata from the raw request headers', () => {+ const headers = gatewayMetadataHeadersForTurn({+ sessionId: 'sess-1',+ turnId: 'turn-1',+ agent: AGENT,+ requestHeaders: { 'X-Tfy-Metadata': JSON.stringify({ env: 'prod' }) },+ });++ expect(JSON.parse(headers[X_TFY_METADATA] ?? '')).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',+ });+ });+});diff --git a/packages/trueforge/tests/unit/truefoundry/inlineResources.test.ts b/packages/trueforge/tests/unit/truefoundry/inlineResources.test.tsindex 8ea0a1e8b..ea3bbb786 100644--- a/packages/trueforge/tests/unit/truefoundry/inlineResources.test.ts+++ b/packages/trueforge/tests/unit/truefoundry/inlineResources.test.ts@@ -1,6 +1,7 @@import { HTTPException } from 'hono/http-exception';import type { IMcpServerWithAuthStore, McpServerRecord } from '../../../src/db/mcpServerStore';import type { ISkillStore, SkillRecord } from '../../../src/db/skillStore';+import { TFG_METADATA_PREFIX, X_TFY_METADATA } from '../../../src/truefoundry/gatewayMetadata';import { InlineMcpServerStore } from '../../../src/truefoundry/InlineMcpServerStore';import { parseInlineMcpServers, parseInlineSkills } from '../../../src/truefoundry/inlineResources';import { InlineSkillStore } from '../../../src/truefoundry/InlineSkillStore';@@ -125,6 +126,34 @@ describe('InlineMcpServerStore', () => {});});+ it('stamps x-tfy-metadata on inline invokes when turnMetadata is present', () => {+ const { store } = mcpStoreWith({ 'docs-mcp': DOCS_MCP });+ const record = { ...registryServer, name: 'docs-mcp' };++ const headers = store.resolveInvokeHeaders({+ record,+ userRef: 'user-1',+ turnMetadata: {+ sessionId: 'sess-1',+ turnId: 'turn-1',+ agent: { id: 'agent-1', name: 'named' },+ requestHeaders: { 'x-tfy-metadata': JSON.stringify({ env: 'prod' }) },+ },+ });++ expect(headers).toEqual({+ Authorization: 'Bearer saas-token',+ [X_TFY_METADATA]: expect.any(String),+ });+ expect(JSON.parse((headers as Record<string, string>)[X_TFY_METADATA] ?? '')).toMatchObject({+ 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`]: 'named',+ });+ });+it('leaves a registry server to the store that knows how to authenticate it', () => {const { store, inner } = mcpStoreWith({ 'docs-mcp': DOCS_MCP });