Skip to content

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.ts
index 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.ts
index 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 EventSubscriptionRegistry
import { 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' | '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;
+ /** 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.ts
index 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 IMcpServerW
return 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.ts
index 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 IMcpServe
deleteAuthorization(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.ts
index 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.ts
index 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<Transacti
return 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 IMod
return 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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 });