The open-source agent harness - the runtime layer that turns an LLM into a working agent.
feat: add session metadata filter (#591)
Srajan Asthanaa000b47d0d6a
diff --git a/.changeset/list-sessions-metadata-deepobject-filter.md b/.changeset/list-sessions-metadata-deepobject-filter.mdnew file mode 100644index 000000000..15d4a14d2--- /dev/null+++ b/.changeset/list-sessions-metadata-deepobject-filter.md@@ -0,0 +1,7 @@+---+"@truefoundry/trueforge-core": patch+"@truefoundry/trueforge": patch+"@truefoundry/trueforge-sdk": patch+---++List sessions accepts `metadata[key]=value` query params (OpenAPI deepObject) for exact metadata containment filtering. Bare JSON-string `metadata` query params are rejected. Metadata keys are limited to 32 characters and cannot include `[]` or whitespace so they do not collide with the bracket query form.diff --git a/.github/fern/generators.yml b/.github/fern/generators.ymlindex eecb97c80..2829cb8b7 100644--- a/.github/fern/generators.yml+++ b/.github/fern/generators.yml@@ -24,7 +24,7 @@ api:prefer-undiscriminated-unions-with-literals: trueonly-include-referenced-schemas: truetype-dates-as-strings: true- object-query-parameters: false+ object-query-parameters: trueidiomatic-request-names: truerespect-nullable-schemas: truewrap-references-to-nullable-in-optional: false@@ -37,7 +37,7 @@ groups:ts-sdk:generators:- name: fernapi/fern-typescript-node-sdk- version: 3.88.3+ version: 3.91.0output:location: local-file-systempath: ../../packages/trueforge-sdk@@ -79,6 +79,8 @@ groups:default: './dist/cjs/index.js'allowExtraFields: trueallowCustomFetcher: true+ # Map query params (OpenAPI additionalProperties) as deepObject brackets, not JSON strings.+ deepObjectMapQueryParameters: trueenableInlineTypes: falsefetchSupport: nativefileResponseType: binary-responsediff --git a/.github/fern/openapi/openapi.json b/.github/fern/openapi/openapi.jsonindex dd5cee2fa..341f42cdd 100644--- a/.github/fern/openapi/openapi.json+++ b/.github/fern/openapi/openapi.json@@ -6925,6 +6925,17 @@"type": "boolean"}},+ {+ "description": "Exact metadata pairs as metadata[key]=value. Sessions must contain all pairs.",+ "explode": true,+ "in": "query",+ "name": "metadata",+ "required": false,+ "schema": {+ "$ref": "#/components/schemas/SessionMetadata"+ },+ "style": "deepObject"+ },{"description": "When set, returns only sessions created by this source type.","in": "query",diff --git a/docs/openapi.json b/docs/openapi.jsonindex dd5cee2fa..341f42cdd 100644--- a/docs/openapi.json+++ b/docs/openapi.json@@ -6925,6 +6925,17 @@"type": "boolean"}},+ {+ "description": "Exact metadata pairs as metadata[key]=value. Sessions must contain all pairs.",+ "explode": true,+ "in": "query",+ "name": "metadata",+ "required": false,+ "schema": {+ "$ref": "#/components/schemas/SessionMetadata"+ },+ "style": "deepObject"+ },{"description": "When set, returns only sessions created by this source type.","in": "query",diff --git a/packages/trueforge-core/src/agent-session/schemas/session.ts b/packages/trueforge-core/src/agent-session/schemas/session.tsindex 8fea9f5fb..914287fa8 100644--- a/packages/trueforge-core/src/agent-session/schemas/session.ts+++ b/packages/trueforge-core/src/agent-session/schemas/session.ts@@ -6,9 +6,13 @@ import { z } from '@hono/zod-openapi';import { AgentSpecSchema } from './agentSpec';import { CreatedBySubjectSchema } from './subject';-/** Max key length for session metadata (aligned with LLM gateway HeaderMetadata). */const SESSION_METADATA_MAX_KEY_LENGTH = 32;-/** Max value length for session metadata (aligned with LLM gateway HeaderMetadata). */+/**+ * Metadata keys: alphanumeric start; then alphanumeric, `.`, `_`, `:`, `-`.+ * Bans `[]` (collide with deepObject / reserved `metadata[key][op]`) and whitespace.+ */+const SESSION_METADATA_KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,31}$/;+/** Max value length for session metadata */const SESSION_METADATA_MAX_VALUE_LENGTH = 128;/** Max number of keys in session metadata. */const SESSION_METADATA_MAX_KEYS = 50;@@ -19,6 +23,7 @@ export const SessionMetadataSchema = z.string().min(1).max(SESSION_METADATA_MAX_KEY_LENGTH)+ .regex(SESSION_METADATA_KEY_PATTERN).describe(`Metadata key; 1–${String(SESSION_METADATA_MAX_KEY_LENGTH)} characters.`),z.string()diff --git a/packages/trueforge-core/src/agent-session/store/ISessionStore.ts b/packages/trueforge-core/src/agent-session/store/ISessionStore.tsindex 8b03baae2..7b2d5aa3e 100644--- a/packages/trueforge-core/src/agent-session/store/ISessionStore.ts+++ b/packages/trueforge-core/src/agent-session/store/ISessionStore.ts@@ -11,6 +11,7 @@ import type { SessionRecord } from '../models/SessionRecord';import type { TurnRecord } from '../models/TurnRecord';import type { PersistedTurnEvent, SessionEventItem } from '../schemas/events';import type { TokenPagination } from '../schemas/pagination';+import type { SessionMetadata } from '../schemas/session';import type { CancellationReason, TerminalTurnState } from '../schemas/turn';/**@@ -71,6 +72,12 @@ export interface ListSessionsInput {agent_ids: readonly string[];}| undefined;+ /**+ * When set, only sessions whose metadata contains all key/value pairs+ * (exact string equality; extra session keys are allowed).+ * `undefined` means no metadata filter; `{}` matches only sessions with empty metadata.+ */+ metadata: SessionMetadata | undefined;/** When set, only sessions whose `source.type` matches. */source_type: string | undefined;/**diff --git a/packages/trueforge-core/src/agent-session/store/InMemorySessionStore.ts b/packages/trueforge-core/src/agent-session/store/InMemorySessionStore.tsindex 05d2de4f2..a63dddc80 100644--- a/packages/trueforge-core/src/agent-session/store/InMemorySessionStore.ts+++ b/packages/trueforge-core/src/agent-session/store/InMemorySessionStore.ts@@ -283,6 +283,17 @@ export class InMemorySessionStore<continue;}}+ const metadataFilter = input.metadata;+ if (metadataFilter !== undefined) {+ const entries = Object.entries(metadataFilter);+ if (entries.length === 0) {+ if (Object.keys(stored.record.metadata).length > 0) {+ continue;+ }+ } else if (!entries.every(([key, value]) => stored.record.metadata[key] === value)) {+ continue;+ }+ }if (input.source_type !== undefined && stored.record.source?.type !== input.source_type) {continue;}diff --git a/packages/trueforge-core/tests/agent-session/schemas/session.test.ts b/packages/trueforge-core/tests/agent-session/schemas/session.test.tsnew file mode 100644index 000000000..3a88ef86e--- /dev/null+++ b/packages/trueforge-core/tests/agent-session/schemas/session.test.ts@@ -0,0 +1,25 @@+import { SessionMetadataSchema } from '../../../src/agent-session/schemas/session';++describe('SessionMetadataSchema keys', () => {+ it.each([['env'], ['Team'], ['a'], ['9start'], ['app.name'], ['tf:tenant'], ['foo_bar'], ['a-b'], ['k'.repeat(32)]])(+ 'accepts key %j',+ key => {+ expect(SessionMetadataSchema.parse({ [key]: 'v' })).toEqual({ [key]: 'v' });+ },+ );++ it.each([+ ['_leading'],+ ['.dotstart'],+ [':colon'],+ ['-dash'],+ ['has space'],+ ['env[prod]'],+ ['a/b'],+ ['a$b'],+ [''],+ ['k'.repeat(33)],+ ])('rejects key %j', key => {+ expect(SessionMetadataSchema.safeParse({ [key]: 'v' }).success).toBe(false);+ });+});diff --git a/packages/trueforge-core/tests/agent-session/store/storeContractSuite.ts b/packages/trueforge-core/tests/agent-session/store/storeContractSuite.tsindex 41ef288d3..6c3cd36ac 100644--- a/packages/trueforge-core/tests/agent-session/store/storeContractSuite.ts+++ b/packages/trueforge-core/tests/agent-session/store/storeContractSuite.ts@@ -218,6 +218,7 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {end_timestamp: undefined,agent_id: undefined,created_by_or_agent_ids: undefined,+ metadata: undefined,source_type: undefined,source_id: undefined,});@@ -247,6 +248,7 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {const filtered = await store.listSessions({agent_id: 'agent-abc',created_by_or_agent_ids: undefined,+ metadata: undefined,tenant_id: tenant,limit: 10,page_token: undefined,@@ -598,6 +600,7 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {const listed = await store.listSessions({agent_id: undefined,created_by_or_agent_ids: undefined,+ metadata: undefined,tenant_id: tenant,limit: 10,page_token: undefined,@@ -859,6 +862,7 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {const desc = await store.listSessions({agent_id: undefined,created_by_or_agent_ids: undefined,+ metadata: undefined,tenant_id: tenant,limit: 10,page_token: undefined,@@ -873,6 +877,7 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {const asc = await store.listSessions({agent_id: undefined,created_by_or_agent_ids: undefined,+ metadata: undefined,tenant_id: tenant,limit: 10,page_token: undefined,@@ -892,6 +897,7 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {const first = await store.listSessions({agent_id: undefined,created_by_or_agent_ids: undefined,+ metadata: undefined,tenant_id: tenant,limit: 2,page_token: undefined,@@ -906,6 +912,7 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {const second = await store.listSessions({agent_id: undefined,created_by_or_agent_ids: undefined,+ metadata: undefined,tenant_id: tenant,limit: 2,page_token: first.pagination.next_page_token,@@ -921,6 +928,7 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {const all = await store.listSessions({agent_id: undefined,created_by_or_agent_ids: undefined,+ metadata: undefined,tenant_id: tenant,limit: 10,page_token: undefined,@@ -938,6 +946,7 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {const bounded = await store.listSessions({agent_id: undefined,created_by_or_agent_ids: undefined,+ metadata: undefined,tenant_id: tenant,limit: 10,order: 'asc',@@ -965,6 +974,7 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {const listArgs = {agent_id: undefined,created_by_or_agent_ids: undefined,+ metadata: undefined,tenant_id: tenant,order: undefined,start_timestamp: undefined,@@ -993,6 +1003,7 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {const listArgs = {agent_id: undefined,created_by_or_agent_ids: undefined,+ metadata: undefined,tenant_id: tenant,order: 'desc' as const,start_timestamp: undefined,@@ -1015,6 +1026,75 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {expect(page2.pagination.next_page_token).toBeUndefined();});+ it('filters listSessions by metadata containment', async () => {+ const store = createStore();+ await store.createSession({+ tenant_id: tenant,+ session_id: 'prod-platform',+ created_by_subject: { subject_id: 'alice', subject_type: 'user', subject_display_name: 'alice' },+ agent: { type: 'inline', spec: makeAgentSpec() },+ custom: null,+ metadata: { env: 'prod', team: 'platform' },+ external_id: null,+ source: null,+ });+ await store.createSession({+ tenant_id: tenant,+ session_id: 'prod-only',+ created_by_subject: { subject_id: 'alice', subject_type: 'user', subject_display_name: 'alice' },+ agent: { type: 'inline', spec: makeAgentSpec() },+ custom: null,+ metadata: { env: 'prod' },+ external_id: null,+ source: null,+ });+ await store.createSession({+ tenant_id: tenant,+ session_id: 'staging',+ created_by_subject: { subject_id: 'alice', subject_type: 'user', subject_display_name: 'alice' },+ agent: { type: 'inline', spec: makeAgentSpec() },+ custom: null,+ metadata: { env: 'staging' },+ external_id: null,+ source: null,+ });+ await store.createSession({+ tenant_id: tenant,+ session_id: 'empty-meta',+ created_by_subject: { subject_id: 'alice', subject_type: 'user', subject_display_name: 'alice' },+ agent: { type: 'inline', spec: makeAgentSpec() },+ custom: null,+ metadata: {},+ external_id: null,+ source: null,+ });++ const listArgs = {+ agent_id: undefined,+ created_by_or_agent_ids: undefined,+ tenant_id: tenant,+ limit: 10,+ page_token: undefined,+ order: 'asc' as const,+ start_timestamp: undefined,+ end_timestamp: undefined,+ source_type: undefined,+ source_id: undefined,+ };++ const byEnv = await store.listSessions({ ...listArgs, metadata: { env: 'prod' } });+ expect(byEnv.data.map(s => s.session_id).sort()).toEqual(['prod-only', 'prod-platform']);++ const byBoth = await store.listSessions({+ ...listArgs,+ metadata: { env: 'prod', team: 'platform' },+ });+ expect(byBoth.data.map(s => s.session_id)).toEqual(['prod-platform']);++ const emptyOnly = await store.listSessions({ ...listArgs, metadata: {} });+ expect(emptyOnly.data.map(s => s.session_id)).toEqual(['empty-meta']);+ });+it('filters by creator or named-agent ids', async () => {const store = createStore();await store.createSession({@@ -1064,6 +1144,7 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {created_by_subject_id: 'alice',agent_ids: [],},+ metadata: undefined,tenant_id: tenant,limit: 10,page_token: undefined,@@ -1082,6 +1163,7 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {created_by_subject_id: 'alice',agent_ids: ['managed-agent'],},+ metadata: undefined,tenant_id: tenant,limit: 10,page_token: undefined,@@ -1099,6 +1181,7 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {created_by_subject_id: 'alice',agent_ids: ['managed-agent'],},+ metadata: undefined,tenant_id: tenant,limit: 10,page_token: undefined,@@ -1116,6 +1199,7 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {created_by_subject_id: 'nobody',agent_ids: [],},+ metadata: undefined,tenant_id: tenant,limit: 10,page_token: undefined,@@ -1172,6 +1256,7 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {const byType = await store.listSessions({agent_id: undefined,created_by_or_agent_ids: undefined,+ metadata: undefined,tenant_id: tenant,limit: 10,page_token: undefined,@@ -1186,6 +1271,7 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {const bySourceId = await store.listSessions({agent_id: undefined,created_by_or_agent_ids: undefined,+ metadata: undefined,tenant_id: tenant,limit: 10,page_token: undefined,@@ -1201,6 +1287,7 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {const unmatched = await store.listSessions({agent_id: undefined,created_by_or_agent_ids: undefined,+ metadata: undefined,tenant_id: tenant,limit: 10,page_token: undefined,diff --git a/packages/trueforge-sdk/src/api/resources/sessions/client/Client.ts b/packages/trueforge-sdk/src/api/resources/sessions/client/Client.tsindex ea143e750..acd4b93ab 100644--- a/packages/trueforge-sdk/src/api/resources/sessions/client/Client.ts+++ b/packages/trueforge-sdk/src/api/resources/sessions/client/Client.ts@@ -52,6 +52,7 @@ export class SessionsClient {endTimestamp,agentId,createdByMe,+ metadata,sourceType,sourceId,} = request;@@ -71,6 +72,7 @@ export class SessionsClient {end_timestamp: endTimestamp != null ? endTimestamp?.toISOString() : undefined,agent_id: agentId,created_by_me: createdByMe,+ metadata,source_type:sourceType != null? serializers.SessionSourceType.jsonOrThrow(sourceType, {diff --git a/packages/trueforge-sdk/src/api/resources/sessions/client/requests/ListSessionsRequest.ts b/packages/trueforge-sdk/src/api/resources/sessions/client/requests/ListSessionsRequest.tsindex c5ae193a9..730654000 100644--- a/packages/trueforge-sdk/src/api/resources/sessions/client/requests/ListSessionsRequest.ts+++ b/packages/trueforge-sdk/src/api/resources/sessions/client/requests/ListSessionsRequest.ts@@ -21,6 +21,8 @@ export interface ListSessionsRequest {agentId?: string;/** When true, only sessions created by the authenticated subject. */createdByMe?: boolean;+ /** Exact metadata pairs as metadata[key]=value. Sessions must contain all pairs. */+ metadata?: TrueForge.SessionMetadata;/** When set, returns only sessions created by this source type. */sourceType?: TrueForge.SessionSourceType;/** When set, returns only sessions from this specific source. Requires source_type. */diff --git a/packages/trueforge/src/apis/sessions.ts b/packages/trueforge/src/apis/sessions.tsindex e8993642a..c4043c152 100644--- a/packages/trueforge/src/apis/sessions.ts+++ b/packages/trueforge/src/apis/sessions.ts@@ -42,7 +42,8 @@ import {import type { ActiveTurnRegistry } from '../runtime/activeTurns';import { executorFromTurnId } from '../runtime/peeringIds';import { validateAgentSpec } from '../runtime/sessionResources';-import { isSessionAgentNameRef, type Session } from '../schemas/session';+import { honoQueriesToRecord } from '../schemas/deepObjectQuery';+import { isSessionAgentNameRef, parseListSessionsQuery, type Session } from '../schemas/session';import { newId } from '../utils/id';import { agentIfAccessible, canReadAgentBoundResource, resolveManagedAgentIds } from './agentAccess';@@ -482,7 +483,7 @@ export function createSessionsRouter(deps: SessionsRouterDeps) {};const listSessionsHandler: RouteHandler<typeof listSessionsRoute> = async c => {- const query = c.req.valid('query');+ const query = parseListSessionsQuery(honoQueriesToRecord(c.req.queries()));const requestContext = deps.resolveRequestContext(c);try {const managedAgentIds = query.created_by_me@@ -499,6 +500,7 @@ export function createSessionsRouter(deps: SessionsRouterDeps) {agent_ids: managedAgentIds,},tenant_id: requestContext.tenant_id,+ metadata: query.metadata,limit: query.limit,order: query.order,page_token: query.page_token,diff --git a/packages/trueforge/src/db/indexes.ts b/packages/trueforge/src/db/indexes.tsindex e08f53919..36eefa9ee 100644--- a/packages/trueforge/src/db/indexes.ts+++ b/packages/trueforge/src/db/indexes.ts@@ -13,6 +13,9 @@ export const SESSION_SOURCE_IDX = 'session_source_idx';/** Partial unique index on `agent (tenant_id, external_id) WHERE external_id IS NOT NULL`. */export const AGENT_EXTERNAL_ID_UQ = 'agent_external_id_uq';+/** GIN index for `session.metadata` containment queries (`@>`). */+export const SESSION_METADATA_GIN = 'session_metadata_gin';+/** `(tenant_id, created_by_subject.subject_id)` on agent. */export const AGENT_CREATED_BY_SUBJECT_ID_IDX = 'agent_created_by_subject_id_idx';diff --git a/packages/trueforge/src/db/postgres/migrations/20260904_000003_session_metadata_gin.ts b/packages/trueforge/src/db/postgres/migrations/20260904_000003_session_metadata_gin.tsnew file mode 100644index 000000000..c0f9760af--- /dev/null+++ b/packages/trueforge/src/db/postgres/migrations/20260904_000003_session_metadata_gin.ts@@ -0,0 +1,17 @@+import { sql, type Kysely } from 'kysely';+import { SESSION_METADATA_GIN } from '../../indexes';++/** GIN index for list-sessions metadata containment (`metadata @> …`). */+export async function up(db: Kysely<unknown>): Promise<void> {+ await sql`SET LOCAL lock_timeout = '5s'`.execute(db);+ await sql`+ CREATE INDEX ${sql.raw(SESSION_METADATA_GIN)}+ ON session+ USING GIN (metadata jsonb_path_ops)+ `.execute(db);+}++export async function down(db: Kysely<unknown>): Promise<void> {+ await sql`SET LOCAL lock_timeout = '5s'`.execute(db);+ await sql`DROP INDEX IF EXISTS ${sql.raw(SESSION_METADATA_GIN)}`.execute(db);+}diff --git a/packages/trueforge/src/db/postgres/session-store/queries/sessions.ts b/packages/trueforge/src/db/postgres/session-store/queries/sessions.tsindex ce99acddb..333bc7bca 100644--- a/packages/trueforge/src/db/postgres/session-store/queries/sessions.ts+++ b/packages/trueforge/src/db/postgres/session-store/queries/sessions.ts@@ -251,6 +251,13 @@ export async function listSessions(query = query.where('agent_id', '=', input.agent_id);}query = whereCreatedByOrAgentIds(query, input.created_by_or_agent_ids);+ if (input.metadata !== undefined) {+ if (Object.keys(input.metadata).length === 0) {+ query = query.where(sql<boolean>`metadata = '{}'::jsonb`);+ } else {+ query = query.where(sql<boolean>`metadata @> ${json(input.metadata)}`);+ }+ }if (input.source_type !== undefined) {query = query.where(sql`source->>'type'`, '=', input.source_type);}diff --git a/packages/trueforge/src/db/sqlite/session-store/queries/sessions.ts b/packages/trueforge/src/db/sqlite/session-store/queries/sessions.tsindex 689873ee5..9dbd6bdce 100644--- a/packages/trueforge/src/db/sqlite/session-store/queries/sessions.ts+++ b/packages/trueforge/src/db/sqlite/session-store/queries/sessions.ts@@ -268,6 +268,18 @@ export async function listSessions(query = query.where('agent_id', '=', input.agent_id);}query = whereCreatedByOrAgentIds(query, input.created_by_or_agent_ids);+ if (input.metadata !== undefined) {+ if (Object.keys(input.metadata).length === 0) {+ query = query.where(sql<boolean>`NOT EXISTS (SELECT 1 FROM json_each(metadata))`);+ } else {+ for (const [key, value] of Object.entries(input.metadata)) {+ // Match metadata keys exactly; some key names are parsed as JSON paths.+ query = query.where(+ sql<boolean>`EXISTS (SELECT 1 FROM json_each(metadata) WHERE key = ${key} AND atom = ${value})`,+ );+ }+ }+ }if (input.source_type !== undefined) {query = query.where(sql`json_extract(source, '$.type')`, '=', input.source_type);}diff --git a/packages/trueforge/src/schemas/deepObjectQuery.ts b/packages/trueforge/src/schemas/deepObjectQuery.tsnew file mode 100644index 000000000..7f61188f3--- /dev/null+++ b/packages/trueforge/src/schemas/deepObjectQuery.ts@@ -0,0 +1,103 @@+/**+ * Hono leaves OpenAPI deepObject query params flat (`foo[bar]=v`).+ * Fold those keys into a nested map before Zod validation.+ */+import { z } from '@hono/zod-openapi';++function deepObjectQueryIssue({ name, message }: { name: string; message: string }): z.ZodError {+ return new z.ZodError([+ {+ code: 'custom',+ path: [name],+ message,+ },+ ]);+}++function requireSingleString({ name, key, value }: { name: string; key: string; value: unknown }): string {+ if (typeof value === 'string') {+ return value;+ }+ if (Array.isArray(value)) {+ throw deepObjectQueryIssue({ name, message: `Query parameter "${key}" must appear at most once` });+ }+ throw deepObjectQueryIssue({ name, message: `Query parameter "${key}" must be a string` });+}++/** Normalize Hono `queries()` (string | string[]) into a flat record. */+export function honoQueriesToRecord(queries: Record<string, string[]>): Record<string, unknown> {+ const out: Record<string, unknown> = {};+ for (const [key, values] of Object.entries(queries)) {+ out[key] = values.length === 1 ? values[0] : values;+ }+ return out;+}++/**+ * Fold Hono's flat deepObject keys for one query param into `{ [name]: { key: value } }`.+ * Passes other keys through unchanged.+ *+ * - `name[key]=value` → map entry+ * - `name[key][…]=…` → rejected (only one bracket level)+ * - bare `name=…` → rejected+ */+export function foldDeepObjectQueryParam({+ query,+ name,+ maxKeys,+}: {+ query: object;+ name: string;+ maxKeys?: number;+}): Record<string, unknown> {+ const equalKey = new RegExp(`^${name}\\[([^\\]]+)\\]$`);+ const nestedBrackets = new RegExp(`^${name}\\[[^\\]]*\\]\\[[^\\]]+\\]`);++ const out: Record<string, unknown> = {};+ const folded: Record<string, string> = {};++ for (const [key, value] of Object.entries(query)) {+ if (key === name) {+ throw deepObjectQueryIssue({+ name,+ message: `Use ${name}[key]=value query parameters; bare ${name} is not supported`,+ });+ }++ if (nestedBrackets.test(key)) {+ throw deepObjectQueryIssue({+ name,+ message: `Nested ${name} query parameters like ${name}[key][…] are not supported; use ${name}[key]=value`,+ });+ }++ const equalMatch = equalKey.exec(key);+ if (equalMatch) {+ const mapKey = equalMatch[1];+ if (mapKey === undefined || mapKey.length === 0) {+ throw deepObjectQueryIssue({ name, message: `${name} filter key must be non-empty` });+ }+ if (Object.hasOwn(folded, mapKey)) {+ throw deepObjectQueryIssue({ name, message: `Duplicate ${name} filter key "${mapKey}"` });+ }+ folded[mapKey] = requireSingleString({ name, key, value });+ continue;+ }++ if (key.startsWith(`${name}[`)) {+ throw deepObjectQueryIssue({ name, message: `Invalid ${name} query parameter "${key}"` });+ }++ out[key] = value;+ }++ const filterKeyCount = Object.keys(folded).length;+ if (maxKeys !== undefined && filterKeyCount > maxKeys) {+ throw deepObjectQueryIssue({ name, message: `at most ${String(maxKeys)} ${name} filter keys` });+ }+ if (filterKeyCount > 0) {+ out[name] = folded;+ }++ return out;+}diff --git a/packages/trueforge/src/schemas/session.ts b/packages/trueforge/src/schemas/session.tsindex 2aa41b27d..cf3cd3265 100644--- a/packages/trueforge/src/schemas/session.ts+++ b/packages/trueforge/src/schemas/session.ts@@ -9,6 +9,7 @@ import {TokenPaginationSchema,} from '@truefoundry/trueforge-core/agent-session';import { NameSchema, PAGE_LIMIT } from './common';+import { foldDeepObjectQueryParam } from './deepObjectQuery';/** Create arm: bind by unique registry agent name. */export const SessionAgentNameRefSchema = z.object({ name: NameSchema }).strict().openapi('SessionAgentNameRef');@@ -68,6 +69,9 @@ const IsoTimestampQueryParam = z.iso.openapi({ type: 'string', format: 'date-time' }).transform(s => new Date(s));+/** Max metadata equality filters on list sessions (clause-budget style). */+export const LIST_SESSIONS_METADATA_FILTER_MAX_KEYS = 10;+export const ListSessionsRequestQuerySchema = z.object({limit: z.coerce@@ -101,6 +105,15 @@ export const ListSessionsRequestQuerySchema = z.optional().describe('When true, only sessions created by the authenticated subject.').openapi({ type: 'boolean' }),+ metadata: SessionMetadataSchema.optional()+ .openapi({+ param: {+ style: 'deepObject',+ explode: true,+ description: 'Exact metadata pairs as metadata[key]=value. Sessions must contain all pairs.',+ },+ })+ .transform(metadata => (metadata === undefined || Object.keys(metadata).length === 0 ? undefined : metadata)),source_type: SessionSourceTypeSchema.optional().describe('When set, returns only sessions created by this source type.',),@@ -116,6 +129,22 @@ export const ListSessionsRequestQuerySchema = z}).openapi('ListSessionsRequestQuery');+export type ListSessionsRequestQuery = z.infer<typeof ListSessionsRequestQuerySchema>;++/**+ * Parse list-sessions query after folding Hono's flat `metadata[key]` params.+ * OpenAPIHono's query validator cannot nest deepObject keys; callers pass `c.req.queries()`.+ */+export function parseListSessionsQuery(raw: object): ListSessionsRequestQuery {+ return ListSessionsRequestQuerySchema.parse(+ foldDeepObjectQueryParam({+ query: raw,+ name: 'metadata',+ maxKeys: LIST_SESSIONS_METADATA_FILTER_MAX_KEYS,+ }),+ );+}+export const GetSessionResponseSchema = z.object({data: SessionSchema,diff --git a/packages/trueforge/tests/unit/apis/sessionHttp.test.ts b/packages/trueforge/tests/unit/apis/sessionHttp.test.tsindex 9dea62d8e..3216b79a8 100644--- a/packages/trueforge/tests/unit/apis/sessionHttp.test.ts+++ b/packages/trueforge/tests/unit/apis/sessionHttp.test.ts@@ -498,6 +498,15 @@ describe('sessions HTTP agent binding', () => {);expect(tooLongKey.status).toBe(400);+ const badCharsetKey = await app.request(+ '/',+ jsonInit('POST', {+ agent: { spec: inlineSpec },+ metadata: { 'env[prod]': 'v' },+ }),+ );+ expect(badCharsetKey.status).toBe(400);+const tooLongValue = await app.request('/',jsonInit('POST', {@@ -508,6 +517,31 @@ describe('sessions HTTP agent binding', () => {expect(tooLongValue.status).toBe(400);});+ it('lists by metadata[key]=value containment and rejects bare metadata', async () => {+ const prod = await app.request(+ '/',+ jsonInit('POST', { agent: { spec: inlineSpec }, metadata: { env: 'prod', team: 'platform' } }),+ );+ expect(prod.status).toBe(201);+ const prodId = ((await prod.json()) as { data: { id: string } }).data.id;++ const staging = await app.request(+ '/',+ jsonInit('POST', { agent: { spec: inlineSpec }, metadata: { env: 'staging' } }),+ );+ expect(staging.status).toBe(201);+ const stagingId = ((await staging.json()) as { data: { id: string } }).data.id;++ const filtered = await app.request('/?metadata[env]=prod&metadata[team]=platform');+ expect(filtered.status).toBe(200);+ const filteredIds = ListSessionsResponseSchema.parse(await filtered.json()).data.map(session => session.id);+ expect(filteredIds).toContain(prodId);+ expect(filteredIds).not.toContain(stagingId);++ const bare = await app.request(`/?metadata=${encodeURIComponent(JSON.stringify({ env: 'prod' }))}`);+ expect(bare.status).toBe(400);+ });+it('POST get-or-create-by-external-id is idempotent and 403s for another creator', async () => {const publicPath = await app.request('/get-or-create-by-external-id',diff --git a/packages/trueforge/tests/unit/schemas/deepObjectQuery.test.ts b/packages/trueforge/tests/unit/schemas/deepObjectQuery.test.tsnew file mode 100644index 000000000..5e49c4f13--- /dev/null+++ b/packages/trueforge/tests/unit/schemas/deepObjectQuery.test.ts@@ -0,0 +1,82 @@+import { foldDeepObjectQueryParam, honoQueriesToRecord } from '../../../src/schemas/deepObjectQuery';++describe('honoQueriesToRecord', () => {+ it('unwraps single-value arrays', () => {+ expect(honoQueriesToRecord({ limit: ['10'], 'metadata[env]': ['prod'] })).toEqual({+ limit: '10',+ 'metadata[env]': 'prod',+ });+ });++ it('keeps multi-value arrays', () => {+ expect(honoQueriesToRecord({ tag: ['a', 'b'] })).toEqual({ tag: ['a', 'b'] });+ });+});++describe('foldDeepObjectQueryParam', () => {+ it('passes through unrelated scalars', () => {+ expect(foldDeepObjectQueryParam({ query: { limit: '10', order: 'asc' }, name: 'metadata' })).toEqual({+ limit: '10',+ order: 'asc',+ });+ });++ it('folds name[key]=value into a map under name', () => {+ expect(+ foldDeepObjectQueryParam({+ query: {+ limit: '5',+ 'metadata[env]': 'prod',+ 'metadata[team]': 'platform',+ },+ name: 'metadata',+ }),+ ).toEqual({+ limit: '5',+ metadata: { env: 'prod', team: 'platform' },+ });+ });++ it('omits name when no bracket params are present', () => {+ expect(foldDeepObjectQueryParam({ query: { agent_id: 'a1' }, name: 'metadata' })).toEqual({+ agent_id: 'a1',+ });+ });++ it('rejects bare name (JSON-string form)', () => {+ expect(() => foldDeepObjectQueryParam({ query: { metadata: '{"env":"prod"}' }, name: 'metadata' })).toThrow(+ /bare metadata is not supported/,+ );+ });++ it('rejects nested bracket forms', () => {+ expect(() => foldDeepObjectQueryParam({ query: { 'metadata[env][eq]': 'prod' }, name: 'metadata' })).toThrow(+ /Nested metadata query parameters/,+ );+ expect(() => foldDeepObjectQueryParam({ query: { 'metadata[env][in]': 'a,b' }, name: 'metadata' })).toThrow(+ /Nested metadata query parameters/,+ );+ });++ it('rejects multi-value params', () => {+ expect(() =>+ foldDeepObjectQueryParam({ query: { 'metadata[env]': ['prod', 'staging'] }, name: 'metadata' }),+ ).toThrow(/at most once/);+ });++ it('rejects more than the optional key cap', () => {+ const query: Record<string, unknown> = {};+ for (let i = 0; i < 11; i += 1) {+ query[`labels[k${String(i)}]`] = 'v';+ }+ expect(() => foldDeepObjectQueryParam({ query, name: 'labels', maxKeys: 10 })).toThrow(+ /at most 10 labels filter keys/,+ );+ });++ it('rejects malformed empty bracket keys', () => {+ expect(() => foldDeepObjectQueryParam({ query: { 'metadata[]': 'x' }, name: 'metadata' })).toThrow(+ /Invalid metadata/,+ );+ });+});