Skip to content

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.md
new file mode 100644
index 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.yml
index eecb97c80..2829cb8b7 100644
--- a/.github/fern/generators.yml
+++ b/.github/fern/generators.yml
@@ -24,7 +24,7 @@ api:
prefer-undiscriminated-unions-with-literals: true
only-include-referenced-schemas: true
type-dates-as-strings: true
- object-query-parameters: false
+ object-query-parameters: true
idiomatic-request-names: true
respect-nullable-schemas: true
wrap-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.0
output:
location: local-file-system
path: ../../packages/trueforge-sdk
@@ -79,6 +79,8 @@ groups:
default: './dist/cjs/index.js'
allowExtraFields: true
allowCustomFetcher: true
+ # Map query params (OpenAPI additionalProperties) as deepObject brackets, not JSON strings.
+ deepObjectMapQueryParameters: true
enableInlineTypes: false
fetchSupport: native
fileResponseType: binary-response
diff --git a/.github/fern/openapi/openapi.json b/.github/fern/openapi/openapi.json
index 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.json
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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/,
+ );
+ });
+});