@truefoundry/trueforge 0.2.0-rc.5 → 0.2.0-rc.6

package/dist/main.js

@@ -510,7 +510,9 @@ var init_config = __esm({
 });
 
 // src/db/agentStore.ts
-import { AgentSpecSchema } from "@truefoundry/trueforge-core/agent-session";
+import {
+  AgentSpecSchema
+} from "@truefoundry/trueforge-core/agent-session";
 function parseStoredAgentSpec(manifest) {
   return AgentSpecSchema.parse(manifest);
 }
@@ -2104,7 +2106,7 @@ function parseCommaSeparatedQuery(val) {
   }
   return val.split(",").map((part) => part.trim()).filter((part) => part.length > 0);
 }
-var NameSchema, PAGE_LIMIT, EVENTS_PAGE_LIMIT;
+var NameSchema, PAGE_LIMIT, EVENTS_PAGE_LIMIT, AGENTS_PAGE_DEFAULT, AGENTS_PAGE_LIMIT;
 var init_common = __esm({
   "src/schemas/common.ts"() {
     "use strict";
@@ -2114,6 +2116,8 @@ var init_common = __esm({
     ).openapi("ResourceName");
     PAGE_LIMIT = 25;
     EVENTS_PAGE_LIMIT = 100;
+    AGENTS_PAGE_DEFAULT = 50;
+    AGENTS_PAGE_LIMIT = 100;
   }
 });
 
@@ -3865,7 +3869,7 @@ var init_mcpServerStore = __esm({
 
 // src/schemas/schedule.ts
 import { z as z24 } from "@hono/zod-openapi";
-import { CreatedBySubjectSchema as CreatedBySubjectSchema4, TokenPaginationSchema } from "@truefoundry/trueforge-core/agent-session";
+import { CreatedBySubjectSchema as CreatedBySubjectSchema4, TokenPaginationSchema as TokenPaginationSchema2 } from "@truefoundry/trueforge-core/agent-session";
 var SCHEDULE_MIN_INTERVAL_SECONDS, CRON_FIELD, InvalidCronError, CronExpressionSchema, TimezoneSchema, IsoTimestamp, NullableIsoTimestamp, ScheduleTaskSchema, ScheduleStatusSchema, ScheduleManifestObjectSchema, ScheduleManifestSchema, ScheduleSchema, CreateScheduleRequestSchema, UpdateScheduleRequestSchema, GetScheduleResponseSchema, ListSchedulesResponseSchema, DeleteScheduleResponseSchema, ScheduleRunStatusSchema, ScheduleRunSchema, ListScheduleRunsResponseSchema, CreateScheduleRunRequestSchema, CreateScheduleRunResponseSchema, ExecuteScheduleRunRequestSchema;
 var init_schedule = __esm({
   "src/schemas/schedule.ts"() {
@@ -3923,7 +3927,7 @@ var init_schedule = __esm({
     GetScheduleResponseSchema = z24.object({ data: ScheduleSchema }).openapi("GetScheduleResponse");
     ListSchedulesResponseSchema = z24.object({
       data: z24.array(ScheduleSchema),
-      pagination: TokenPaginationSchema
+      pagination: TokenPaginationSchema2
     }).openapi("ListSchedulesResponse");
     DeleteScheduleResponseSchema = z24.object({}).openapi("DeleteScheduleResponse");
     ScheduleRunStatusSchema = z24.enum(["scheduled", "triggered", "failed"]).openapi("ScheduleRunStatus");
@@ -3941,7 +3945,7 @@ var init_schedule = __esm({
     }).strict().openapi("ScheduleRun");
     ListScheduleRunsResponseSchema = z24.object({
       data: z24.array(ScheduleRunSchema),
-      pagination: TokenPaginationSchema
+      pagination: TokenPaginationSchema2
     }).openapi("ListScheduleRunsResponse");
     CreateScheduleRunRequestSchema = z24.object({
       schedule_id: z24.string().min(1).max(64).describe("Immutable schedule identifier.")
@@ -4330,12 +4334,17 @@ __export(PostgresAgentStore_exports, {
   PostgresAgentStore: () => PostgresAgentStore
 });
 import { CreatedBySubjectSchema as CreatedBySubjectSchema5 } from "@truefoundry/trueforge-core/agent-session";
+import {
+  decodeOffsetPageToken as decodeOffsetPageToken3,
+  paginateOffsetRows as paginateOffsetRows2
+} from "@truefoundry/trueforge-core/agent-session/store/OffsetPageToken";
 import { sql as sql10 } from "kysely";
 function toRecord(row) {
   return {
     id: row.id,
     tenant_id: row.tenant_id,
     name: row.name,
+    description: row.description,
     manifest: parseStoredAgentSpec(row.manifest),
     external_id: row.external_id,
     created_by_subject: CreatedBySubjectSchema5.parse(row.created_by_subject),
@@ -4370,15 +4379,26 @@ var init_PostgresAgentStore = __esm({
       }
       async listAgents(input, transaction) {
         if (input.external_ids?.length === 0) {
-          return [];
+          return { data: [], pagination: { limit: input.limit ?? 0 } };
         }
         const db = transaction ?? this.#db;
         let query = db.selectFrom("agent").selectAll().where("tenant_id", "=", input.tenant_id);
         if (input.external_ids !== void 0) {
           query = query.where("external_id", "in", [...input.external_ids]);
         }
-        const rows = await query.orderBy("name").execute();
-        return rows.map(toRecord);
+        if (input.agent_name !== void 0) {
+          query = query.where(sql10`position(lower(${input.agent_name}) in lower(name)) > 0`);
+        }
+        query = query.orderBy("name");
+        if (input.limit === void 0) {
+          const rows2 = await query.execute();
+          const data2 = rows2.map(toRecord);
+          return { data: data2, pagination: { limit: data2.length } };
+        }
+        const offset = decodeOffsetPageToken3(input.page_token);
+        const rows = await query.limit(input.limit + 1).offset(offset).execute();
+        const { data, pagination } = paginateOffsetRows2(rows, input.limit, offset);
+        return { data: data.map(toRecord), pagination };
       }
       async getOwnedIds(input, transaction) {
         if (input.ids.length === 0) {
@@ -4414,6 +4434,7 @@ var init_PostgresAgentStore = __esm({
             id: newId(),
             tenant_id: input.tenant_id,
             name: input.name,
+            description: input.description,
             manifest: json(input.manifest),
             external_id: input.external_id,
             created_by_subject: json(input.created_by_subject),
@@ -4434,13 +4455,14 @@ var init_PostgresAgentStore = __esm({
         }
       }
       async updateAgent(input, transaction) {
-        if (input.manifest === void 0 && input.external_id === void 0) {
-          throw new Error("updateAgent requires manifest and/or external_id");
+        if (input.manifest === void 0 && input.description === void 0 && input.external_id === void 0) {
+          throw new Error("updateAgent requires manifest, description, and/or external_id");
         }
         const db = transaction ?? this.#db;
         try {
           const row = await db.updateTable("agent").set({
             ...input.manifest === void 0 ? {} : { manifest: json(input.manifest) },
+            ...input.description === void 0 ? {} : { description: input.description },
             ...input.external_id === void 0 ? {} : { external_id: input.external_id },
             updated_at: now()
           }).where("tenant_id", "=", input.tenant_id).where("id", "=", input.id).returningAll().executeTakeFirst();
@@ -5241,8 +5263,8 @@ var init_capabilities2 = __esm({
 
 // src/db/sqlite/session-store/queries/events.ts
 import {
-  decodeOffsetPageToken as decodeOffsetPageToken3,
-  paginateOffsetRows as paginateOffsetRows2
+  decodeOffsetPageToken as decodeOffsetPageToken4,
+  paginateOffsetRows as paginateOffsetRows3
 } from "@truefoundry/trueforge-core/agent-session/store/OffsetPageToken";
 import {
   decodeSessionEventPageToken as decodeSessionEventPageToken2,
@@ -5277,7 +5299,7 @@ async function appendToEvents2(db, input) {
   });
 }
 async function listTurnEvents2(db, input) {
-  const offset = decodeOffsetPageToken3(input.page_token);
+  const offset = decodeOffsetPageToken4(input.page_token);
   const limit = input.limit;
   const eventOrder = input.order === "desc" ? "desc" : "asc";
   const rows = await db.selectFrom("turn as t").leftJoin(
@@ -5293,7 +5315,7 @@ async function listTurnEvents2(db, input) {
       events.push(row.event);
     }
   }
-  return paginateOffsetRows2(events, limit, offset);
+  return paginateOffsetRows3(events, limit, offset);
 }
 async function resolveAncestorChain2(db, sessionId, anchor) {
   const chain = [...anchor.ancestor_ids, anchor.turn_id];
@@ -5859,7 +5881,7 @@ __export(SqliteSessionStore_exports, {
   SqliteSessionStore: () => SqliteSessionStore
 });
 import {
-  decodeOffsetPageToken as decodeOffsetPageToken4,
+  decodeOffsetPageToken as decodeOffsetPageToken5,
   encodeOffsetPageToken as encodeOffsetPageToken2
 } from "@truefoundry/trueforge-core/agent-session/store/OffsetPageToken";
 var SqliteSessionStore;
@@ -5936,7 +5958,7 @@ var init_SqliteSessionStore = __esm({
         return getTurn2(this.db, input);
       }
       async listTurns(input) {
-        const offset = decodeOffsetPageToken4(input.page_token);
+        const offset = decodeOffsetPageToken5(input.page_token);
         const result = await listTurns2(this.db, {
           session_id: input.session_id,
           limit: input.limit,
@@ -6635,12 +6657,17 @@ __export(SqliteAgentStore_exports, {
 import {
   CreatedBySubjectSchema as CreatedBySubjectSchema7
 } from "@truefoundry/trueforge-core/agent-session";
+import {
+  decodeOffsetPageToken as decodeOffsetPageToken6,
+  paginateOffsetRows as paginateOffsetRows4
+} from "@truefoundry/trueforge-core/agent-session/store/OffsetPageToken";
 import { sql as sql21 } from "kysely";
 function recordColumns5(eb) {
   return [
     "id",
     "tenant_id",
     "name",
+    "description",
     jsonText(eb.ref("manifest")).as("manifest"),
     "external_id",
     jsonText(eb.ref("created_by_subject")).as("created_by_subject"),
@@ -6670,15 +6697,26 @@ var init_SqliteAgentStore = __esm({
       }
       async listAgents(input, transaction) {
         if (input.external_ids?.length === 0) {
-          return [];
+          return { data: [], pagination: { limit: input.limit ?? 0 } };
         }
         const db = transaction ?? this.#db;
         let query = db.selectFrom("agent").select(recordColumns5).where("tenant_id", "=", input.tenant_id);
         if (input.external_ids !== void 0) {
           query = query.where("external_id", "in", [...input.external_ids]);
         }
-        const rows = await query.orderBy("name").execute();
-        return rows.map(toRecord3);
+        if (input.agent_name !== void 0) {
+          query = query.where(sql21`instr(lower(name), lower(${input.agent_name})) > 0`);
+        }
+        query = query.orderBy("name");
+        if (input.limit === void 0) {
+          const rows2 = await query.execute();
+          const data2 = rows2.map(toRecord3);
+          return { data: data2, pagination: { limit: data2.length } };
+        }
+        const offset = decodeOffsetPageToken6(input.page_token);
+        const rows = await query.limit(input.limit + 1).offset(offset).execute();
+        const { data, pagination } = paginateOffsetRows4(rows, input.limit, offset);
+        return { data: data.map(toRecord3), pagination };
       }
       async getOwnedIds(input, transaction) {
         if (input.ids.length === 0) {
@@ -6715,6 +6753,7 @@ var init_SqliteAgentStore = __esm({
             id: newId(),
             tenant_id: input.tenant_id,
             name: input.name,
+            description: input.description,
             manifest: jsonbBind(input.manifest),
             external_id: input.external_id,
             created_by_subject: jsonbBind(input.created_by_subject),
@@ -6736,13 +6775,14 @@ var init_SqliteAgentStore = __esm({
         }
       }
       async updateAgent(input, transaction) {
-        if (input.manifest === void 0 && input.external_id === void 0) {
-          throw new Error("updateAgent requires manifest and/or external_id");
+        if (input.manifest === void 0 && input.description === void 0 && input.external_id === void 0) {
+          throw new Error("updateAgent requires manifest, description, and/or external_id");
         }
         const db = transaction ?? this.#db;
         try {
           const row = await db.updateTable("agent").set({
             ...input.manifest === void 0 ? {} : { manifest: jsonbBind(input.manifest) },
+            ...input.description === void 0 ? {} : { description: input.description },
             ...input.external_id === void 0 ? {} : { external_id: input.external_id },
             updated_at: nowIso()
           }).where("tenant_id", "=", input.tenant_id).where("id", "=", input.id).returning(recordColumns5).executeTakeFirst();
@@ -6791,8 +6831,8 @@ import {
   CreatedBySubjectSchema as CreatedBySubjectSchema8
 } from "@truefoundry/trueforge-core/agent-session";
 import {
-  decodeOffsetPageToken as decodeOffsetPageToken5,
-  paginateOffsetRows as paginateOffsetRows3
+  decodeOffsetPageToken as decodeOffsetPageToken7,
+  paginateOffsetRows as paginateOffsetRows5
 } from "@truefoundry/trueforge-core/agent-session/store/OffsetPageToken";
 import { sql as sql22 } from "kysely";
 function scheduleColumns(eb) {
@@ -6959,7 +6999,7 @@ var init_SqliteScheduleStore = __esm({
         await db.deleteFrom("schedule").where("tenant_id", "=", input.tenant_id).where("id", "=", input.id).execute();
       }
       async listSchedules(input, transaction) {
-        const offset = decodeOffsetPageToken5(input.page_token);
+        const offset = decodeOffsetPageToken7(input.page_token);
         const db = transaction ?? this.#db;
         let query = db.selectFrom("schedule").select(scheduleColumns).where("tenant_id", "=", input.tenant_id);
         if (input.agent_names !== void 0) {
@@ -6967,7 +7007,7 @@ var init_SqliteScheduleStore = __esm({
         }
         query = whereCreatedByOrAgentIds2(query, input.created_by_or_agent_ids);
         const rows = await query.orderBy("created_at", "desc").orderBy("id").limit(input.limit + 1).offset(offset).execute();
-        const { data, pagination } = paginateOffsetRows3(rows, input.limit, offset);
+        const { data, pagination } = paginateOffsetRows5(rows, input.limit, offset);
         return { data: data.map(toScheduleRecord), pagination };
       }
       async getOwnedIds(input, transaction) {
@@ -6979,10 +7019,10 @@ var init_SqliteScheduleStore = __esm({
         return rows.map((row) => row.id);
       }
       async listRuns(input, transaction) {
-        const offset = decodeOffsetPageToken5(input.page_token);
+        const offset = decodeOffsetPageToken7(input.page_token);
         const db = transaction ?? this.#db;
         const rows = await db.selectFrom("schedule_run").select(runColumns).where("tenant_id", "=", input.tenant_id).where("schedule_id", "=", input.schedule_id).orderBy("scheduled_for", "desc").orderBy("id").limit(input.limit + 1).offset(offset).execute();
-        const { data, pagination } = paginateOffsetRows3(rows, input.limit, offset);
+        const { data, pagination } = paginateOffsetRows5(rows, input.limit, offset);
         return { data: data.map(toRunRecord), pagination };
       }
       async getRun(input, transaction) {
@@ -7709,8 +7749,8 @@ __export(PostgresScheduleStore_exports, {
 });
 import { CreatedBySubjectSchema as CreatedBySubjectSchema9 } from "@truefoundry/trueforge-core/agent-session";
 import {
-  decodeOffsetPageToken as decodeOffsetPageToken6,
-  paginateOffsetRows as paginateOffsetRows4
+  decodeOffsetPageToken as decodeOffsetPageToken8,
+  paginateOffsetRows as paginateOffsetRows6
 } from "@truefoundry/trueforge-core/agent-session/store/OffsetPageToken";
 import { sql as sql25 } from "kysely";
 function toScheduleRecord2(row) {
@@ -7855,7 +7895,7 @@ var init_PostgresScheduleStore = __esm({
         await db.deleteFrom("schedule").where("tenant_id", "=", input.tenant_id).where("id", "=", input.id).execute();
       }
       async listSchedules(input, transaction) {
-        const offset = decodeOffsetPageToken6(input.page_token);
+        const offset = decodeOffsetPageToken8(input.page_token);
         const db = transaction ?? this.#db;
         let query = db.selectFrom("schedule").selectAll().where("tenant_id", "=", input.tenant_id);
         if (input.agent_names !== void 0) {
@@ -7863,7 +7903,7 @@ var init_PostgresScheduleStore = __esm({
         }
         query = whereCreatedByOrAgentIds(query, input.created_by_or_agent_ids);
         const rows = await query.orderBy("created_at", "desc").orderBy("id").limit(input.limit + 1).offset(offset).execute();
-        const { data, pagination } = paginateOffsetRows4(rows, input.limit, offset);
+        const { data, pagination } = paginateOffsetRows6(rows, input.limit, offset);
         return { data: data.map(toScheduleRecord2), pagination };
       }
       async getOwnedIds(input, transaction) {
@@ -7875,10 +7915,10 @@ var init_PostgresScheduleStore = __esm({
         return rows.map((row) => row.id);
       }
       async listRuns(input, transaction) {
-        const offset = decodeOffsetPageToken6(input.page_token);
+        const offset = decodeOffsetPageToken8(input.page_token);
         const db = transaction ?? this.#db;
         const rows = await db.selectFrom("schedule_run").selectAll().where("tenant_id", "=", input.tenant_id).where("schedule_id", "=", input.schedule_id).orderBy("scheduled_for", "desc").orderBy("id").limit(input.limit + 1).offset(offset).execute();
-        const { data, pagination } = paginateOffsetRows4(rows, input.limit, offset);
+        const { data, pagination } = paginateOffsetRows6(rows, input.limit, offset);
         return { data: data.map(toRunRecord2), pagination };
       }
       async getRun(input, transaction) {
@@ -7998,101 +8038,160 @@ import { HTTPException as HTTPException2 } from "hono/http-exception";
 import { createRoute } from "@hono/zod-openapi";
 
 // src/schemas/agentImport.ts
+import { z as z3 } from "@hono/zod-openapi";
+import { AgentSpecSchema as AgentSpecSchema5, CreatedBySubjectSchema as CreatedBySubjectSchema3 } from "@truefoundry/trueforge-core/agent-session";
+
+// src/schemas/agent.ts
 init_common();
 import { z as z2 } from "@hono/zod-openapi";
-import { AgentSpecSchema as AgentSpecSchema4, CreatedBySubjectSchema as CreatedBySubjectSchema2 } from "@truefoundry/trueforge-core/agent-session";
+import {
+  AgentSpecSchema as AgentSpecSchema4,
+  CreatedBySubjectSchema as CreatedBySubjectSchema2,
+  TokenPaginationSchema
+} from "@truefoundry/trueforge-core/agent-session";
 var RESERVED_AGENT_NAMES = /* @__PURE__ */ new Set(["tfg", "trueforge"]);
-var ImportAgentItemSchema = z2.object({
+var AGENT_DESCRIPTION_MAX_LENGTH = 1024;
+var AgentDescriptionSchema = z2.string().trim().min(1).max(AGENT_DESCRIPTION_MAX_LENGTH);
+var CreateAgentRequestSchema = z2.object({
   name: NameSchema.refine((name) => !RESERVED_AGENT_NAMES.has(name), {
     message: "Agent name is reserved, cannot be used"
   }),
+  description: AgentDescriptionSchema,
+  manifest: AgentSpecSchema4
+}).strict().openapi("CreateAgentRequest");
+var UpdateAgentRequestSchema = z2.object({
+  description: AgentDescriptionSchema.optional(),
+  manifest: AgentSpecSchema4
+}).strict().openapi("UpdateAgentRequest");
+var AgentSchema = z2.object({
+  id: z2.string().min(1).describe("Immutable server-generated agent identifier."),
+  name: NameSchema,
+  description: AgentDescriptionSchema,
   manifest: AgentSpecSchema4,
-  tenant_id: z2.string().min(1).describe("Tenant to create the agent under."),
-  created_by_subject: CreatedBySubjectSchema2.describe("Original creator to persist on the agent.")
+  created_by_subject: CreatedBySubjectSchema2
+}).strict().openapi("Agent");
+var GetAgentResponseSchema = z2.object({ data: AgentSchema }).openapi("GetAgentResponse");
+var ListAgentsResponseSchema = z2.object({
+  data: z2.array(AgentSchema),
+  pagination: TokenPaginationSchema
+}).openapi("ListAgentsResponse");
+var DeleteAgentResponseSchema = z2.object({}).openapi("DeleteAgentResponse");
+var AgentCodeSnippetSampleCodeSchema = z2.object({
+  stream: z2.string().describe("SDK sample that streams turn events."),
+  non_stream: z2.string().describe("SDK sample that creates a turn without streaming.")
+}).strict().openapi("AgentCodeSnippetSampleCode");
+var AgentCodeSnippetSchema = z2.object({
+  label_name: z2.string().min(1),
+  language: z2.string().min(1),
+  icon: z2.url(),
+  sample_code: AgentCodeSnippetSampleCodeSchema
+}).strict().openapi("AgentCodeSnippet");
+var AgentCodeSnippetsSchema = z2.object({
+  base_url: z2.url().describe("Public base URL for the TrueForge SDK `baseUrl`."),
+  snippets: z2.array(AgentCodeSnippetSchema)
+}).strict().openapi("AgentCodeSnippets");
+var GetAgentCodeSnippetsResponseSchema = z2.object({ data: AgentCodeSnippetsSchema }).openapi("GetAgentCodeSnippetsResponse");
+var GetAgentCodeSnippetsRequestQuerySchema = z2.object({
+  base_url: z2.url().optional().describe(
+    "Public SDK base URL from the browser. When omitted, derived from the request origin and PUBLIC_BASE_URL."
+  )
+}).strict().openapi("GetAgentCodeSnippetsRequestQuery");
+
+// src/schemas/agentImport.ts
+init_common();
+var RESERVED_AGENT_NAMES2 = /* @__PURE__ */ new Set(["tfg", "trueforge"]);
+var ImportAgentItemSchema = z3.object({
+  name: NameSchema.refine((name) => !RESERVED_AGENT_NAMES2.has(name), {
+    message: "Agent name is reserved, cannot be used"
+  }),
+  description: AgentDescriptionSchema.optional(),
+  manifest: AgentSpecSchema5,
+  tenant_id: z3.string().min(1).describe("Tenant to create the agent under."),
+  created_by_subject: CreatedBySubjectSchema3.describe("Original creator to persist on the agent.")
 }).strict().openapi("ImportAgentItem");
-var ImportAgentsRequestSchema = z2.object({
-  agents: z2.array(ImportAgentItemSchema).describe("Agents to create; each carries tenant_id and created_by_subject.")
+var ImportAgentsRequestSchema = z3.object({
+  agents: z3.array(ImportAgentItemSchema).describe("Agents to create; each carries tenant_id and created_by_subject.")
 }).strict().openapi("ImportAgentsRequest");
-var ImportAgentItemResultSchema = z2.object({
-  name: z2.string().min(1),
-  tenant_id: z2.string().min(1),
-  status: z2.enum(["created", "exists", "failed"]),
-  agent_id: z2.string().min(1).optional(),
-  error: z2.string().optional()
+var ImportAgentItemResultSchema = z3.object({
+  name: z3.string().min(1),
+  tenant_id: z3.string().min(1),
+  status: z3.enum(["created", "exists", "failed"]),
+  agent_id: z3.string().min(1).optional(),
+  error: z3.string().optional()
 }).strict().openapi("ImportAgentItemResult");
-var ImportAgentsResultSchema = z2.object({
-  results: z2.array(ImportAgentItemResultSchema)
+var ImportAgentsResultSchema = z3.object({
+  results: z3.array(ImportAgentItemResultSchema)
 }).strict().openapi("ImportAgentsResult");
-var ImportAgentsResponseSchema = z2.object({
+var ImportAgentsResponseSchema = z3.object({
   data: ImportAgentsResultSchema
 }).strict().openapi("ImportAgentsResponse");
-var ImportSessionSnapshotSchema = z2.object({
-  session_id: z2.string().min(1),
-  tenant_id: z2.string().min(1),
-  created_by_subject: CreatedBySubjectSchema2,
-  agent_name: z2.string().min(1).nullable().optional(),
-  agent_id: z2.string().min(1).nullable().optional(),
-  agent_spec: z2.record(z2.string(), z2.unknown()).nullable().optional(),
-  title: z2.string().nullable(),
-  last_turn_id: z2.string().nullable(),
-  custom: z2.record(z2.string(), z2.unknown()).nullable(),
-  last_activity_timestamp_ms: z2.number(),
-  created_at: z2.string().min(1),
-  updated_at: z2.string().min(1)
+var ImportSessionSnapshotSchema = z3.object({
+  session_id: z3.string().min(1),
+  tenant_id: z3.string().min(1),
+  created_by_subject: CreatedBySubjectSchema3,
+  agent_name: z3.string().min(1).nullable().optional(),
+  agent_id: z3.string().min(1).nullable().optional(),
+  agent_spec: z3.record(z3.string(), z3.unknown()).nullable().optional(),
+  title: z3.string().nullable(),
+  last_turn_id: z3.string().nullable(),
+  custom: z3.record(z3.string(), z3.unknown()).nullable(),
+  last_activity_timestamp_ms: z3.number(),
+  created_at: z3.string().min(1),
+  updated_at: z3.string().min(1)
 }).loose().openapi("ImportSessionSnapshot");
-var ImportSessionThreadSchema = z2.object({
-  thread_id: z2.string().min(1),
-  context: z2.array(z2.unknown()),
-  current_context_usage: z2.unknown(),
-  parent: z2.unknown().nullable(),
-  completion: z2.unknown().nullable(),
-  agent_info: z2.unknown().nullable(),
-  capability_state: z2.record(z2.string(), z2.unknown()).nullable()
+var ImportSessionThreadSchema = z3.object({
+  thread_id: z3.string().min(1),
+  context: z3.array(z3.unknown()),
+  current_context_usage: z3.unknown(),
+  parent: z3.unknown().nullable(),
+  completion: z3.unknown().nullable(),
+  agent_info: z3.unknown().nullable(),
+  capability_state: z3.record(z3.string(), z3.unknown()).nullable()
 }).loose().openapi("ImportSessionThread");
-var ImportSessionEventSchema = z2.object({
-  id: z2.string().min(1),
-  created_at: z2.string().min(1)
+var ImportSessionEventSchema = z3.object({
+  id: z3.string().min(1),
+  created_at: z3.string().min(1)
 }).loose().openapi("ImportSessionEvent");
-var ImportSessionTurnSchema = z2.object({
-  turn_id: z2.string().min(1),
-  first_turn_id: z2.string().min(1),
-  previous_turn_id: z2.string().nullable(),
-  ancestor_ids: z2.array(z2.string()),
-  input: z2.array(z2.unknown()),
-  state: z2.unknown(),
-  checkpoint: z2.unknown(),
-  custom: z2.record(z2.string(), z2.unknown()).nullable(),
-  created_at: z2.string().min(1),
-  updated_at: z2.string().min(1),
-  threads: z2.array(ImportSessionThreadSchema),
-  events: z2.array(ImportSessionEventSchema)
+var ImportSessionTurnSchema = z3.object({
+  turn_id: z3.string().min(1),
+  first_turn_id: z3.string().min(1),
+  previous_turn_id: z3.string().nullable(),
+  ancestor_ids: z3.array(z3.string()),
+  input: z3.array(z3.unknown()),
+  state: z3.unknown(),
+  checkpoint: z3.unknown(),
+  custom: z3.record(z3.string(), z3.unknown()).nullable(),
+  created_at: z3.string().min(1),
+  updated_at: z3.string().min(1),
+  threads: z3.array(ImportSessionThreadSchema),
+  events: z3.array(ImportSessionEventSchema)
 }).loose().openapi("ImportSessionTurn");
-var ImportSessionRequestSchema = z2.object({
+var ImportSessionRequestSchema = z3.object({
   session: ImportSessionSnapshotSchema,
-  turns: z2.array(ImportSessionTurnSchema).min(1)
+  turns: z3.array(ImportSessionTurnSchema).min(1)
 }).openapi("ImportSessionRequest");
-var ImportSessionResultSchema = z2.object({
-  imported: z2.boolean(),
-  session_id: z2.string()
+var ImportSessionResultSchema = z3.object({
+  imported: z3.boolean(),
+  session_id: z3.string()
 }).openapi("ImportSessionResult");
-var ImportSessionResponseSchema = z2.object({ data: ImportSessionResultSchema }).openapi("ImportSessionResponse");
-var ImportSessionsCheckpointQuerySchema = z2.object({
-  tenant_id: z2.string().min(1).describe("Tenant whose imported-session watermark to read.")
+var ImportSessionResponseSchema = z3.object({ data: ImportSessionResultSchema }).openapi("ImportSessionResponse");
+var ImportSessionsCheckpointQuerySchema = z3.object({
+  tenant_id: z3.string().min(1).describe("Tenant whose imported-session watermark to read.")
 }).strict().openapi("ImportSessionsCheckpointQuery");
-var ImportSessionsCheckpointResponseSchema = z2.object({
-  data: z2.object({
-    created_at: z2.string().nullable()
+var ImportSessionsCheckpointResponseSchema = z3.object({
+  data: z3.object({
+    created_at: z3.string().nullable()
   })
 }).strict().openapi("ImportSessionsCheckpointResponse");
 
 // src/schemas/errors.ts
-import { z as z3 } from "@hono/zod-openapi";
-var RequestErrorResponseSchema = z3.object({
-  error: z3.object({
-    message: z3.string().describe("Human-readable explanation of the failure."),
-    type: z3.string().optional().describe("Optional error category (e.g. validation vs conflict)."),
-    code: z3.string().nullable().optional().describe("Optional machine-readable error code; null when not applicable."),
-    param: z3.string().nullable().optional().describe("Optional request field that caused the error; null when not field-specific.")
+import { z as z4 } from "@hono/zod-openapi";
+var RequestErrorResponseSchema = z4.object({
+  error: z4.object({
+    message: z4.string().describe("Human-readable explanation of the failure."),
+    type: z4.string().optional().describe("Optional error category (e.g. validation vs conflict)."),
+    code: z4.string().nullable().optional().describe("Optional machine-readable error code; null when not applicable."),
+    param: z4.string().nullable().optional().describe("Optional request field that caused the error; null when not field-specific.")
   })
 }).openapi("RequestErrorResponse");
 
@@ -8197,7 +8296,7 @@ var getImportSessionsCheckpointRoute = createRoute({
 import { extractErrorLogFields } from "@truefoundry/trueforge-core/core";
 import { HTTPException } from "hono/http-exception";
 import { fetch as undiciFetch2 } from "undici";
-import { z as z6 } from "zod";
+import { z as z7 } from "zod";
 
 // src/http/tls.ts
 import { readFileSync } from "fs";
@@ -8313,20 +8412,20 @@ function createInternalTlsDispatcher(options) {
 }
 
 // src/truefoundry/mapSfyAgentSkills.ts
-import { z as z4 } from "zod";
-var SfyRegistryManifestSchema = z4.object({
+import { z as z5 } from "zod";
+var SfyRegistryManifestSchema = z5.object({
   // Display label only — not TF ResourceName / DNS-label rules.
-  name: z4.string().min(1),
-  version: z4.number().int().positive(),
+  name: z5.string().min(1),
+  version: z5.number().int().positive(),
   // SFY field is `ml_repo`; TrueForge wire is `repository_name`.
-  ml_repo: z4.string().min(1),
-  source: z4.object({
-    description: z4.string().min(1).optional()
+  ml_repo: z5.string().min(1),
+  source: z5.object({
+    description: z5.string().min(1).optional()
   }).optional()
 });
-var SfyRegistrySkillSchema = z4.object({
-  latest_version: z4.object({
-    fqn: z4.string().min(1),
+var SfyRegistrySkillSchema = z5.object({
+  latest_version: z5.object({
+    fqn: z5.string().min(1),
     manifest: SfyRegistryManifestSchema
   })
 }).transform(({ latest_version }) => ({
@@ -8337,20 +8436,20 @@ var SfyRegistrySkillSchema = z4.object({
   repository_name: latest_version.manifest.ml_repo,
   version: latest_version.manifest.version
 }));
-var SfyRegistrySkillVersionSchema = z4.object({
-  agent_skill_id: z4.string().min(1),
-  fqn: z4.string().min(1),
+var SfyRegistrySkillVersionSchema = z5.object({
+  agent_skill_id: z5.string().min(1),
+  fqn: z5.string().min(1),
   manifest: SfyRegistryManifestSchema
 });
-var ResolvedAgentSkillVersionSchema = z4.object({
-  fqn: z4.string().min(1),
-  name: z4.string().min(1),
-  description: z4.string().min(1),
-  skill_md_content: z4.string().nullable().optional(),
-  presigned_url: z4.string().min(1).optional()
+var ResolvedAgentSkillVersionSchema = z5.object({
+  fqn: z5.string().min(1),
+  name: z5.string().min(1),
+  description: z5.string().min(1),
+  skill_md_content: z5.string().nullable().optional(),
+  presigned_url: z5.string().min(1).optional()
 });
-var ResolveAgentSkillVersionsResponseSchema = z4.object({
-  skills: z4.array(ResolvedAgentSkillVersionSchema)
+var ResolveAgentSkillVersionsResponseSchema = z5.object({
+  skills: z5.array(ResolvedAgentSkillVersionSchema)
 });
 function mapSfyRegistrySkills(rows) {
   return rows.map((row) => SfyRegistrySkillSchema.parse(row));
@@ -8374,48 +8473,48 @@ function mapResolvedAgentSkillVersions(payload) {
 }
 
 // src/truefoundry/mapSfyMcpServers.ts
-import { z as z5 } from "zod";
+import { z as z6 } from "zod";
 var MCP_PROXY_BASE_URL_TEMPLATE = "{{mcpProxyBaseURL}}";
-var IsoInstantSchema = z5.union([z5.string().min(1), z5.date()]).transform((value, ctx) => {
+var IsoInstantSchema = z6.union([z6.string().min(1), z6.date()]).transform((value, ctx) => {
   if (value instanceof Date) {
     if (!Number.isFinite(value.getTime())) {
       ctx.addIssue({ code: "custom", message: "Invalid Date" });
-      return z5.NEVER;
+      return z6.NEVER;
     }
     return value.toISOString();
   }
   const ms = Date.parse(value);
   if (!Number.isFinite(ms)) {
     ctx.addIssue({ code: "custom", message: "Invalid ISO timestamp" });
-    return z5.NEVER;
+    return z6.NEVER;
   }
   return new Date(ms).toISOString();
 });
-var SfyMcpServerRowSchema = z5.object({
-  id: z5.string().min(1),
-  name: z5.string().min(1),
-  proxyUrl: z5.string().min(1),
+var SfyMcpServerRowSchema = z6.object({
+  id: z6.string().min(1),
+  name: z6.string().min(1),
+  proxyUrl: z6.string().min(1),
   createdAt: IsoInstantSchema,
   updatedAt: IsoInstantSchema,
-  manifest: z5.object({
-    description: z5.string().min(1).optional(),
-    auth_data: z5.object({
-      type: z5.string().min(1).optional()
+  manifest: z6.object({
+    description: z6.string().min(1).optional(),
+    auth_data: z6.object({
+      type: z6.string().min(1).optional()
     }).optional()
   }).optional()
 });
-var SfyMcpAuthStatusAuthenticatedSchema = z5.object({ status: z5.literal("authenticated") });
-var SfyMcpAuthStatusNotRequiredSchema = z5.object({ status: z5.literal("authentication_not_required") });
-var SfyMcpAuthStatusRequiredSchema = z5.object({ status: z5.literal("authentication_required") });
+var SfyMcpAuthStatusAuthenticatedSchema = z6.object({ status: z6.literal("authenticated") });
+var SfyMcpAuthStatusNotRequiredSchema = z6.object({ status: z6.literal("authentication_not_required") });
+var SfyMcpAuthStatusRequiredSchema = z6.object({ status: z6.literal("authentication_required") });
 var SfyMcpAuthorizeRequiredSchema = SfyMcpAuthStatusRequiredSchema.extend({
-  authorization_endpoint: z5.url()
+  authorization_endpoint: z6.url()
 });
-var SfyMcpAuthStatusSchema = z5.discriminatedUnion("status", [
+var SfyMcpAuthStatusSchema = z6.discriminatedUnion("status", [
   SfyMcpAuthStatusAuthenticatedSchema,
   SfyMcpAuthStatusRequiredSchema,
   SfyMcpAuthStatusNotRequiredSchema
 ]);
-var SfyMcpAuthorizeResultSchema = z5.discriminatedUnion("status", [
+var SfyMcpAuthorizeResultSchema = z6.discriminatedUnion("status", [
   SfyMcpAuthStatusAuthenticatedSchema,
   SfyMcpAuthorizeRequiredSchema,
   SfyMcpAuthStatusNotRequiredSchema
@@ -8486,45 +8585,46 @@ var AGENT_PERMISSIONS_PATH = "v1/authorize/permissions";
 var VEND_TOKEN_PATH = "internal/vend-token";
 var AGENT_SKILLS_PAGE_SIZE = 100;
 var AGENT_SKILL_RESOLVE_CHUNK_SIZE = 50;
-var SessionSubjectSchema = z6.object({
-  subjectId: z6.string().min(1),
-  subjectType: z6.string().min(1),
-  subjectDisplayName: z6.string().nullable().optional(),
-  subjectSlug: z6.string().nullable().optional()
+var SessionSubjectSchema = z7.object({
+  subjectId: z7.string().min(1),
+  subjectType: z7.string().min(1),
+  subjectDisplayName: z7.string().nullable().optional(),
+  subjectSlug: z7.string().nullable().optional()
 });
-var GetSessionUserSchema = z6.object({
-  tenantName: z6.string().min(1),
-  roles: z6.array(z6.string()),
+var GetSessionUserSchema = z7.object({
+  tenantName: z7.string().min(1),
+  roles: z7.array(z7.string()),
   subject: SessionSubjectSchema
 });
-var GetSessionWireSchema = z6.object({
+var GetSessionWireSchema = z7.object({
   user: GetSessionUserSchema.nullable()
 });
-var ListResponseSchema = z6.union([
-  z6.array(z6.unknown()),
-  z6.object({
-    data: z6.array(z6.unknown()).catch([]),
-    pagination: z6.object({ total: z6.number().optional() }).optional()
+var ListResponseSchema = z7.union([
+  z7.array(z7.unknown()),
+  z7.object({
+    data: z7.array(z7.unknown()).catch([]),
+    pagination: z7.object({ total: z7.number().optional() }).optional()
   })
 ]);
-var ServiceFoundryErrorSchema = z6.object({
-  message: z6.union([z6.string(), z6.array(z6.string())]).optional()
+var ServiceFoundryErrorSchema = z7.object({
+  message: z7.union([z7.string(), z7.array(z7.string())]).optional()
 });
-var PutRemoteAgentResponseSchema = z6.object({
-  agentId: z6.string().min(1)
+var PutRemoteAgentResponseSchema = z7.object({
+  agentId: z7.string().min(1)
 });
-var AgentPermissionSchema = z6.enum(["READ_AGENT", "USE_AGENT", "MANAGE_AGENT", "DELETE_AGENT"]);
-var AgentPermissionsSchema = z6.record(
-  z6.string(),
-  z6.array(z6.string()).transform(
+var AgentPermissionSchema = z7.enum(["READ_AGENT", "USE_AGENT", "MANAGE_AGENT", "DELETE_AGENT"]);
+var AgentPermissionsSchema = z7.record(
+  z7.string(),
+  z7.array(z7.string()).transform(
     (permissions) => permissions.flatMap((permission) => {
       const parsed = AgentPermissionSchema.safeParse(permission);
       return parsed.success ? [parsed.data] : [];
     })
   )
 );
-var VendTokenResponseSchema = z6.object({
-  token: z6.string().min(1)
+var VendTokenResponseSchema = z7.object({
+  subjectToken: z7.string().min(1),
+  actorToken: z7.string().min(1)
 });
 var TFY_ASSUME_USER_HEADER = "x-tfy-assume-user";
 var TFY_SYSTEM_ASSUME_SUBJECT = "truefoundry";
@@ -8867,7 +8967,8 @@ var TrueFoundryServiceFoundryServerClient = class {
     return parsed.data;
   }
   /**
-   * Exchange a TrueFoundry API key for an agent-scoped token.
+   * Exchange a TrueFoundry API key for dual agent-scoped tokens.
+   * Wire `actorToken` is the agent identity (`asAgent`); wire `subjectToken` is the user with agent in `act` (`asUser`).
    * Authenticated with the server API key, not the user bearer.
    */
   async vendToken(input) {
@@ -8893,7 +8994,7 @@ var TrueFoundryServiceFoundryServerClient = class {
         cause: parsed.error
       });
     }
-    return parsed.data.token;
+    return parsed.data;
   }
   #parseListResponse(payload) {
     const parsed = ListResponseSchema.safeParse(payload);
@@ -9021,6 +9122,7 @@ function createAgentImportRouter(deps) {
         const created = await agentStore.createAgent({
           tenant_id: agent.tenant_id,
           name: agent.name,
+          description: agent.description ?? agent.name,
           manifest: agent.manifest,
           external_id: null,
           created_by_subject: agent.created_by_subject
@@ -9084,6 +9186,7 @@ function createAgentImportRouter(deps) {
 
 // src/apis/agents.ts
 import { OpenAPIHono as OpenAPIHono2 } from "@hono/zod-openapi";
+import { InvalidPageTokenError } from "@truefoundry/trueforge-core/agent-session";
 
 // src/auth/identity.ts
 init_config();
@@ -9120,11 +9223,15 @@ function asTrueFoundryRequestContext(context) {
   }
   return context;
 }
+function accessTokensFromCaller(context) {
+  const resolve3 = callerAccessToken(context);
+  return { asAgent: resolve3, asUser: resolve3 };
+}
 function agentAccessToken(input) {
   const { client, requestContext: context } = input;
   const agentId = requireTrueFoundryAgentExternalId(input.agent);
   let pending;
-  return () => {
+  const vended = () => {
     if (pending === void 0) {
       input.logger.info("Exchanging user context for agent access token", {
         subject: context.subject.id,
@@ -9137,6 +9244,10 @@ function agentAccessToken(input) {
     }
     return pending;
   };
+  return {
+    asAgent: async () => (await vended()).actorToken,
+    asUser: async () => (await vended()).subjectToken
+  };
 }
 function callerAccessToken(context) {
   if (context.user_credential === null) {
@@ -9149,7 +9260,7 @@ function callerAccessToken(context) {
 }
 function accessTokenForRequest(input) {
   if (input.agent === void 0) {
-    return callerAccessToken(input.requestContext);
+    return accessTokensFromCaller(input.requestContext);
   }
   const agentId = requireTrueFoundryAgentExternalId(input.agent);
   const cache = input.requestContext[accessTokenCache];
@@ -9157,14 +9268,14 @@ function accessTokenForRequest(input) {
   if (existing !== void 0) {
     return existing;
   }
-  const resolveAgentAccessToken = agentAccessToken({
+  const tokens = agentAccessToken({
     client: input.client,
     requestContext: input.requestContext,
     agent: input.agent,
     logger: input.logger
   });
-  cache.set(agentId, resolveAgentAccessToken);
-  return resolveAgentAccessToken;
+  cache.set(agentId, tokens);
+  return tokens;
 }
 
 // src/auth/identity.ts
@@ -9230,67 +9341,44 @@ init_agentStore();
 
 // src/routes/agentRoutes.ts
 import { createRoute as createRoute2, z as z8 } from "@hono/zod-openapi";
-
-// src/schemas/agent.ts
 init_common();
-import { z as z7 } from "@hono/zod-openapi";
-import { AgentSpecSchema as AgentSpecSchema5, CreatedBySubjectSchema as CreatedBySubjectSchema3 } from "@truefoundry/trueforge-core/agent-session";
-var RESERVED_AGENT_NAMES2 = /* @__PURE__ */ new Set(["tfg", "trueforge"]);
-var CreateAgentRequestSchema = z7.object({
-  name: NameSchema.refine((name) => !RESERVED_AGENT_NAMES2.has(name), {
-    message: "Agent name is reserved, cannot be used"
-  }),
-  manifest: AgentSpecSchema5
-}).strict().openapi("CreateAgentRequest");
-var UpdateAgentRequestSchema = z7.object({
-  manifest: AgentSpecSchema5
-}).strict().openapi("UpdateAgentRequest");
-var AgentSchema = z7.object({
-  id: z7.string().min(1).describe("Immutable server-generated agent identifier."),
-  name: NameSchema,
-  manifest: AgentSpecSchema5,
-  created_by_subject: CreatedBySubjectSchema3
-}).strict().openapi("Agent");
-var GetAgentResponseSchema = z7.object({ data: AgentSchema }).openapi("GetAgentResponse");
-var ListAgentsResponseSchema = z7.object({ data: z7.array(AgentSchema) }).openapi("ListAgentsResponse");
-var DeleteAgentResponseSchema = z7.object({}).openapi("DeleteAgentResponse");
-var AgentCodeSnippetSampleCodeSchema = z7.object({
-  stream: z7.string().describe("SDK sample that streams turn events."),
-  non_stream: z7.string().describe("SDK sample that creates a turn without streaming.")
-}).strict().openapi("AgentCodeSnippetSampleCode");
-var AgentCodeSnippetSchema = z7.object({
-  label_name: z7.string().min(1),
-  language: z7.string().min(1),
-  icon: z7.url(),
-  sample_code: AgentCodeSnippetSampleCodeSchema
-}).strict().openapi("AgentCodeSnippet");
-var AgentCodeSnippetsSchema = z7.object({
-  base_url: z7.url().describe("Public base URL for the TrueForge SDK `baseUrl`."),
-  snippets: z7.array(AgentCodeSnippetSchema)
-}).strict().openapi("AgentCodeSnippets");
-var GetAgentCodeSnippetsResponseSchema = z7.object({ data: AgentCodeSnippetsSchema }).openapi("GetAgentCodeSnippetsResponse");
-var GetAgentCodeSnippetsRequestQuerySchema = z7.object({
-  base_url: z7.url().optional().describe(
-    "Public SDK base URL from the browser. When omitted, derived from the request origin and PUBLIC_BASE_URL."
-  )
-}).strict().openapi("GetAgentCodeSnippetsRequestQuery");
+
+// src/routes/fernExtensions.ts
+var TOKEN_PAGINATION = {
+  cursor: "$request.page_token",
+  next_cursor: "$response.pagination.next_page_token",
+  results: "$response.data"
+};
 
 // src/routes/agentRoutes.ts
 var AgentIdParamsSchema = z8.object({
   agent_id: z8.string().min(1).max(64).describe("Immutable agent identifier.")
 });
+var ListAgentsQuerySchema = z8.object({
+  limit: z8.coerce.number().int().min(1).max(AGENTS_PAGE_LIMIT).optional().default(AGENTS_PAGE_DEFAULT).describe(`Page size. Defaults to ${String(AGENTS_PAGE_DEFAULT)}, max ${String(AGENTS_PAGE_LIMIT)}.`),
+  page_token: z8.string().optional().describe("Opaque token from a previous response `next_page_token`."),
+  agent_name: z8.string().trim().min(1).optional().describe("Case-insensitive substring match on agent name.")
+}).openapi("ListAgentsQuery");
 var listAgentsRoute = createRoute2({
   method: "get",
   path: "/",
   tags: ["Agents" /* AGENTS */],
   summary: "List agents",
-  description: "All configured agents for the tenant.",
+  description: "List configured agents for the tenant, ordered by name. Optional `agent_name` filters by substring.",
   "x-fern-sdk-group-name": ["agents"],
   "x-fern-sdk-method-name": "list",
+  "x-fern-pagination": TOKEN_PAGINATION,
+  request: {
+    query: ListAgentsQuerySchema
+  },
   responses: {
     200: {
       content: { "application/json": { schema: ListAgentsResponseSchema } },
-      description: "All configured agents."
+      description: "Paginated matching agents."
+    },
+    400: {
+      content: { "application/json": { schema: RequestErrorResponseSchema } },
+      description: "Invalid query parameters or page token."
     },
     401: {
       content: { "application/json": { schema: RequestErrorResponseSchema } },
@@ -9408,7 +9496,7 @@ var putAgentRoute = createRoute2({
   path: "/{agent_id}",
   tags: ["Agents" /* AGENTS */],
   summary: "Update an agent",
-  description: "Replaces the manifest for an existing agent keyed by immutable `agent_id`.",
+  description: "Update an existing agent by immutable id.",
   "x-fern-sdk-group-name": ["agents"],
   "x-fern-sdk-method-name": "update",
   request: {
@@ -9614,6 +9702,44 @@ async function checkSnapshotStatus({
 }
 
 // src/runtime/sessionResources.ts
+var X_TFY_METADATA = "x-tfy-metadata";
+var TFG_METADATA_PREFIX = "tfg";
+function buildGatewayMetadata(input) {
+  const metadata = {
+    [`${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;
+}
+function gatewayMetadataHeaders(metadata) {
+  if (Object.keys(metadata).length === 0) {
+    return {};
+  }
+  return { [X_TFY_METADATA]: JSON.stringify(metadata) };
+}
+function withGatewayMetadataHeaders(input) {
+  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 } };
+  };
+}
 function parseModelFqn(name) {
   const slash = name.indexOf("/");
   if (slash <= 0 || slash === name.length - 1) {
@@ -9794,11 +9920,19 @@ async function agentIfAccessible(input) {
 async function listAccessibleAgents(input) {
   const access = await input.authorizer.listAgentAccess({ context: input.context, action: input.action });
   if (access.kind === "all") {
-    return input.store.listAgents({ tenant_id: input.context.tenant_id });
+    return input.store.listAgents({
+      tenant_id: input.context.tenant_id,
+      agent_name: input.agent_name,
+      limit: input.limit,
+      page_token: input.page_token
+    });
   }
   return input.store.listAgents({
     tenant_id: input.context.tenant_id,
-    external_ids: access.agent_external_ids
+    external_ids: access.agent_external_ids,
+    agent_name: input.agent_name,
+    limit: input.limit,
+    page_token: input.page_token
   });
 }
 async function resolveManagedAgentIds(input) {
@@ -9807,11 +9941,14 @@ async function resolveManagedAgentIds(input) {
   if (access.kind === "all") {
     return [];
   }
-  const agents = await store.listAgents({
+  const { data } = await store.listAgents({
     tenant_id: context.tenant_id,
-    external_ids: access.agent_external_ids
+    external_ids: access.agent_external_ids,
+    agent_name: void 0,
+    limit: void 0,
+    page_token: void 0
   });
-  return agents.map((agent) => agent.id);
+  return data.map((agent) => agent.id);
 }
 async function canReadAgentBoundResource(input) {
   const { store, context, authorizer, created_by_subject_id, agent_id } = input;
@@ -9919,6 +10056,7 @@ function toWireAgent(record) {
   return {
     id: record.id,
     name: record.name,
+    description: record.description,
     manifest: record.manifest,
     created_by_subject: record.created_by_subject
   };
@@ -9943,14 +10081,25 @@ async function validateManifest({
 }
 function createAgentsRouter(deps) {
   const listHandler = async (c) => {
+    const { limit, page_token: pageToken, agent_name: agentName } = c.req.valid("query");
     const requestContext = deps.resolveRequestContext(c);
-    const records = await listAccessibleAgents({
-      store: deps.resolveAgentStore(c),
-      context: requestContext,
-      authorizer: deps.authorizer,
-      action: "read"
-    });
-    return c.json({ data: records.map(toWireAgent) }, 200);
+    try {
+      const { data, pagination } = await listAccessibleAgents({
+        store: deps.resolveAgentStore(c),
+        context: requestContext,
+        authorizer: deps.authorizer,
+        action: "read",
+        agent_name: agentName,
+        limit,
+        page_token: pageToken
+      });
+      return c.json({ data: data.map(toWireAgent), pagination }, 200);
+    } catch (error) {
+      if (error instanceof InvalidPageTokenError) {
+        return c.json({ error: { message: error.message } }, 400);
+      }
+      throw error;
+    }
   };
   const createHandler = async (c) => {
     const body = c.req.valid("json");
@@ -9967,6 +10116,7 @@ function createAgentsRouter(deps) {
       const record = await deps.resolveAgentStore(c).createAgent({
         tenant_id: requestContext.tenant_id,
         name: body.name,
+        description: body.description,
         manifest,
         external_id: null,
         created_by_subject: createdBySubjectFromRequestContext(requestContext)
@@ -10062,6 +10212,7 @@ function createAgentsRouter(deps) {
     const record = await deps.resolveAgentStore(c).updateAgent({
       tenant_id: requestContext.tenant_id,
       id: agentId,
+      ...body.description === void 0 ? {} : { description: body.description },
       manifest
     });
     if (record === void 0) {
@@ -10758,7 +10909,8 @@ import { z as z16 } from "@hono/zod-openapi";
 // src/schemas/mcpServer.ts
 init_common();
 import { z as z15 } from "@hono/zod-openapi";
-var McpServerTypeSchema = z15.enum(["remote", "truefoundry"]).openapi("MCPServerType");
+var MCP_SERVER_TYPES = ["remote", "truefoundry"];
+var McpServerTypeSchema = z15.enum(MCP_SERVER_TYPES).openapi("MCPServerType");
 var McpServerHeaderAuthSchema = z15.object({
   type: z15.literal("header").describe("Authenticate with static HTTP headers."),
   headers: z15.record(z15.string().min(1), z15.string().min(1)).refine((headers) => Object.keys(headers).length > 0, {
@@ -10772,14 +10924,21 @@ var McpServerDcrAuthSchema = z15.object({
 }).strict().openapi("MCPServerDcrAuth");
 var McpServerManifestAuthSchema = z15.discriminatedUnion("type", [McpServerHeaderAuthSchema, McpServerDcrAuthSchema]).describe("Optional auth settings. Omit when the server needs no credentials.").openapi("MCPServerManifestAuth");
 var McpServerDescriptionSchema = z15.string().trim().min(1).describe("Concise summary of what this MCP server provides.");
-var McpServerManifestObjectSchema = z15.object({
-  type: McpServerTypeSchema,
+var RemoteMcpServerManifestSchema = z15.object({
+  type: z15.literal(McpServerTypeSchema.enum.remote),
   name: NameSchema,
-  url: z15.url().describe("MCP endpoint URL. For `truefoundry`, the resolved AI Gateway proxy URL."),
+  url: z15.url().describe("MCP endpoint URL."),
   description: McpServerDescriptionSchema,
   auth: McpServerManifestAuthSchema.optional()
-}).strict();
-var McpServerManifestSchema = McpServerManifestObjectSchema.openapi("MCPServerManifest");
+}).strict().openapi("RemoteMCPServerManifest");
+var TrueFoundryMcpServerManifestSchema = z15.object({
+  type: z15.literal(McpServerTypeSchema.enum.truefoundry),
+  name: NameSchema,
+  url: z15.url().describe("Resolved AI Gateway proxy URL for this TrueFoundry-managed MCP server."),
+  description: McpServerDescriptionSchema,
+  auth: McpServerManifestAuthSchema.optional()
+}).strict().openapi("TrueFoundryMCPServerManifest");
+var McpServerManifestSchema = z15.discriminatedUnion("type", [RemoteMcpServerManifestSchema, TrueFoundryMcpServerManifestSchema]).openapi("MCPServerManifest");
 var McpAuthStatusSchema = z15.object({
   status: z15.enum(["authenticated", "auth_required", "not_required"]).describe("Current auth state for this MCP server."),
   authorization_url: z15.url().optional().describe("When auth is required, this contains the URL to redirect the user to for authorization.")
@@ -12422,7 +12581,7 @@ function createPermissionsRouter(deps) {
 // src/apis/schedules.ts
 import { OpenAPIHono as OpenAPIHono11 } from "@hono/zod-openapi";
 import {
-  InvalidPageTokenError
+  InvalidPageTokenError as InvalidPageTokenError2
 } from "@truefoundry/trueforge-core/agent-session";
 
 // src/controller/scheduleDispatch.ts
@@ -12636,15 +12795,6 @@ init_scheduleStore();
 init_common();
 import { createRoute as createRoute10, z as z25 } from "@hono/zod-openapi";
 init_schedule();
-
-// src/routes/fernExtensions.ts
-var TOKEN_PAGINATION = {
-  cursor: "$request.page_token",
-  next_cursor: "$response.pagination.next_page_token",
-  results: "$response.data"
-};
-
-// src/routes/scheduleRoutes.ts
 var ScheduleIdParamsSchema = z25.object({
   schedule_id: z25.string().min(1).max(64).describe("Immutable schedule identifier.")
 });
@@ -12954,7 +13104,7 @@ import { z as z26 } from "@hono/zod-openapi";
 import {
   EventType,
   SessionEventItemSchema,
-  TokenPaginationSchema as TokenPaginationSchema2,
+  TokenPaginationSchema as TokenPaginationSchema3,
   TurnCreatedEventSchema,
   TurnDoneEventSchema
 } from "@truefoundry/trueforge-core/agent-session";
@@ -12995,13 +13145,13 @@ var ListSessionEventsRequestQuerySchema = z26.object({
 }).openapi("ListSessionEventsRequestQuery");
 var ListSessionEventsResponseSchema = z26.object({
   data: z26.array(SessionEventItemSchema),
-  pagination: TokenPaginationSchema2
+  pagination: TokenPaginationSchema3
 }).openapi("ListSessionEventsResponse");
 
 // src/schemas/turn.ts
 init_common();
 import { z as z27 } from "@hono/zod-openapi";
-import { SessionEventSchema, TokenPaginationSchema as TokenPaginationSchema3, TurnSchema } from "@truefoundry/trueforge-core/agent-session";
+import { SessionEventSchema, TokenPaginationSchema as TokenPaginationSchema4, TurnSchema } from "@truefoundry/trueforge-core/agent-session";
 import { CreateTurnRequestSchema, TurnSchema as TurnSchema2 } from "@truefoundry/trueforge-core/agent-session";
 var SubscribeTurnQuerySchema = z27.object({
   // Query strings need coerce; map null/'' to undefined first so Number(null)→0
@@ -13024,7 +13174,7 @@ var GetTurnResponseSchema = z27.object({
 }).openapi("GetTurnResponse");
 var ListTurnsResponseSchema = z27.object({
   data: z27.array(TurnSchema),
-  pagination: TokenPaginationSchema3
+  pagination: TokenPaginationSchema4
 }).openapi("ListTurnsResponse");
 var ListTurnEventsRequestQuerySchema = z27.object({
   limit: z27.coerce.number().int().min(1).max(EVENTS_PAGE_LIMIT).optional().default(EVENTS_PAGE_LIMIT).describe(`Page size. Defaults to ${String(EVENTS_PAGE_LIMIT)}, max ${String(EVENTS_PAGE_LIMIT)}.`),
@@ -13033,7 +13183,7 @@ var ListTurnEventsRequestQuerySchema = z27.object({
 }).openapi("ListTurnEventsRequestQuery");
 var ListTurnEventsResponseSchema = z27.object({
   data: z27.array(SessionEventSchema),
-  pagination: TokenPaginationSchema3
+  pagination: TokenPaginationSchema4
 }).openapi("ListTurnEventsResponse");
 var DownloadSandboxFileRequestQuerySchema = z27.object({
   path: z27.string().min(1).describe(
@@ -13053,7 +13203,7 @@ import {
   SessionSchema,
   SessionSourceScheduleSchema,
   SessionSourceTypeSchema,
-  TokenPaginationSchema as TokenPaginationSchema4
+  TokenPaginationSchema as TokenPaginationSchema5
 } from "@truefoundry/trueforge-core/agent-session";
 
 // src/schemas/deepObjectQuery.ts
@@ -13196,7 +13346,7 @@ var GetSessionResponseSchema = z29.object({
 }).openapi("GetSessionResponse");
 var ListSessionsResponseSchema = z29.object({
   data: z29.array(SessionSchema),
-  pagination: TokenPaginationSchema4
+  pagination: TokenPaginationSchema5
 }).openapi("ListSessionsResponse");
 
 // src/routes/sessionRoutes.ts
@@ -14018,10 +14168,13 @@ function createTurnResolver(deps) {
     modelProviderStore,
     logger,
     signal,
-    tenant_id,
     userRef,
-    sessionId
+    session,
+    turnId
   } = deps;
+  const tenant_id = session.tenant_id;
+  const sessionId = session.session_id;
+  const metadataHeaders = isTrueFoundryModeEnabled() ? gatewayMetadataHeaders(buildGatewayMetadata({ session, turnId })) : {};
   return new TurnResourceResolver({
     llm: async (name) => {
       const resolved = await getModelDetails({
@@ -14031,7 +14184,10 @@ function createTurnResolver(deps) {
       });
       return {
         modelClient: new VercelAILLM({
-          providerConfig: resolved.providerConfig,
+          providerConfig: {
+            ...resolved.providerConfig,
+            headers: { ...resolved.providerConfig.headers, ...metadataHeaders }
+          },
           logger,
           signal
         }),
@@ -14051,7 +14207,13 @@ function createTurnResolver(deps) {
           message: `Unknown MCP server "${name}" \u2014 not configured`
         });
       }
-      return connection;
+      return {
+        url: connection.url,
+        headers: withGatewayMetadataHeaders({
+          headers: connection.headers,
+          metadataHeaders
+        })
+      };
     },
     mcpRequestTimeoutMs: config_default.MCP_REQUEST_TIMEOUT_MS,
     mcpConnectTimeoutMs: config_default.MCP_CONNECT_TIMEOUT_MS,
@@ -14164,6 +14326,7 @@ async function drainTurnEvents(input) {
 async function beginTurnExecution(params) {
   const { session, input, previous_turn_id: previousTurnId, userRef, deps } = params;
   const sessionId = session.session_id;
+  const turnId = mintPeeredTurnId(config_default.EXECUTOR_ID);
   const abortController = new AbortController();
   const tenant_id = session.tenant_id;
   const resolver = createTurnResolver({
@@ -14174,13 +14337,13 @@ async function beginTurnExecution(params) {
     modelProviderStore: deps.modelProviderStore,
     logger: deps.logger,
     signal: abortController.signal,
-    tenant_id,
     userRef,
-    sessionId
+    session,
+    turnId
   });
   const title = session.record.last_turn_id ? void 0 : deriveSessionTitle(input);
   const turn = await session.createTurn({
-    turn_id: mintPeeredTurnId(config_default.EXECUTOR_ID),
+    turn_id: turnId,
     input,
     previous_turn_id: previousTurnId,
     signal: abortController.signal,
@@ -14721,7 +14884,7 @@ function createSchedulesRouter(deps) {
       });
       return c.json({ data: data.map(toWireSchedule), pagination }, 200);
     } catch (error) {
-      if (error instanceof InvalidPageTokenError) {
+      if (error instanceof InvalidPageTokenError2) {
         return c.json({ error: { message: error.message } }, 400);
       }
       throw error;
@@ -14756,7 +14919,7 @@ function createSchedulesRouter(deps) {
       });
       return c.json({ data: data.map(toWireScheduleRun), pagination }, 200);
     } catch (error) {
-      if (error instanceof InvalidPageTokenError) {
+      if (error instanceof InvalidPageTokenError2) {
         return c.json({ error: { message: error.message } }, 400);
       }
       throw error;
@@ -17594,11 +17757,12 @@ function asError(value) {
 }
 function toPutRemoteAgentPayload({
   name,
+  description,
   manifest
 }) {
   return {
     name,
-    description: name,
+    description: (description || name).slice(0, AGENT_DESCRIPTION_MAX_LENGTH),
     model: manifest.model.name,
     mcp_servers: (manifest.mcp_servers ?? []).map((server) => server.name)
   };
@@ -17644,7 +17808,11 @@ var TrueFoundryAgentStore = class {
     try {
       ({ externalId } = await this.#client.putRemoteAgent({
         accessToken: await this.#resolveAccessToken(),
-        ...toPutRemoteAgentPayload({ name: input.name, manifest: input.manifest })
+        ...toPutRemoteAgentPayload({
+          name: input.name,
+          description: input.description,
+          manifest: input.manifest
+        })
       }));
       const updated = await this.#inner.updateAgent(
         { tenant_id: input.tenant_id, id: created.id, external_id: externalId },
@@ -17678,8 +17846,7 @@ var TrueFoundryAgentStore = class {
     }
   }
   async updateAgent(input, transaction) {
-    const nextManifest = input.manifest;
-    if (nextManifest === void 0) {
+    if (input.manifest === void 0 && input.description === void 0) {
       return this.#inner.updateAgent(input, transaction);
     }
     return this.#withUpdateLock(input, transaction, async (txn) => {
@@ -17687,16 +17854,23 @@ var TrueFoundryAgentStore = class {
       if (previous === void 0) {
         return void 0;
       }
+      const nextManifest = input.manifest ?? previous.manifest;
+      const nextDescription = input.description ?? previous.description;
       const { externalId } = await this.#client.putRemoteAgent({
         accessToken: await this.#resolveAccessToken(),
-        ...toPutRemoteAgentPayload({ name: previous.name, manifest: nextManifest })
+        ...toPutRemoteAgentPayload({
+          name: previous.name,
+          description: nextDescription,
+          manifest: nextManifest
+        })
       });
       try {
         return await this.#inner.updateAgent(
           {
             tenant_id: input.tenant_id,
             id: input.id,
-            manifest: nextManifest,
+            ...input.manifest === void 0 ? {} : { manifest: nextManifest },
+            ...input.description === void 0 ? {} : { description: nextDescription },
             ...externalId === previous.external_id ? {} : { external_id: externalId }
           },
           txn
@@ -17707,6 +17881,7 @@ var TrueFoundryAgentStore = class {
             accessToken: await this.#resolveAccessToken(),
             ...toPutRemoteAgentPayload({
               name: previous.name,
+              description: previous.description,
               manifest: previous.manifest
             })
           });
@@ -17936,18 +18111,21 @@ function resolveAuthorizeRedirectURL(input) {
 }
 var TrueFoundryMcpServerStore = class {
   #client;
-  #resolveAccessToken;
+  #asAgent;
+  #asUser;
   #subject;
   #perServerHeaders;
   #gatewayUrl;
   constructor(input) {
     this.#client = input.client;
-    this.#resolveAccessToken = accessTokenForRequest({
+    const tokens = accessTokenForRequest({
       client: input.client,
       requestContext: asTrueFoundryRequestContext(input.requestContext),
       agent: input.agent,
       logger: input.logger
     });
+    this.#asAgent = tokens.asAgent;
+    this.#asUser = tokens.asUser;
     this.#subject = input.requestContext.subject;
     this.#perServerHeaders = input.perServerHeaders ?? {};
   }
@@ -17956,7 +18134,7 @@ var TrueFoundryMcpServerStore = class {
     const { record, userRef } = input;
     const headers = async () => ({
       ...withoutAuthorization(this.#perServerHeaders[record.name]),
-      Authorization: `Bearer ${await this.#resolveAccessToken()}`
+      Authorization: `Bearer ${await this.#asUser()}`
     });
     return async () => {
       const status = await this.authorize({
@@ -17985,7 +18163,7 @@ var TrueFoundryMcpServerStore = class {
     if (input.names?.length === 0) {
       return [];
     }
-    const accessToken = await this.#resolveAccessToken();
+    const accessToken = await this.#asAgent();
     const [rows, gatewayUrl] = await Promise.all([
       this.#client.listMcpServers({
         accessToken,
@@ -17997,7 +18175,7 @@ var TrueFoundryMcpServerStore = class {
   }
   async getServer(input, transaction) {
     void transaction;
-    const accessToken = await this.#resolveAccessToken();
+    const accessToken = await this.#asAgent();
     const [row, gatewayUrl] = await Promise.all([
       this.#client.getMcpServerByName({ accessToken, name: input.name }),
       this.#resolveGatewayUrl()
@@ -18051,7 +18229,7 @@ var TrueFoundryMcpServerStore = class {
     out.set(
       record.name,
       await this.#client.getMcpAuthStatus({
-        accessToken: await this.#resolveAccessToken(),
+        accessToken: await this.#asUser(),
         mcpServerId: record.id,
         subjectId: this.#subject.id,
         subjectType: this.#subject.type
@@ -18066,7 +18244,7 @@ var TrueFoundryMcpServerStore = class {
       throw new McpServerNotFoundError(input.name);
     }
     return this.#client.getMcpAuthorize({
-      accessToken: await this.#resolveAccessToken(),
+      accessToken: await this.#asUser(),
       mcpServerId: record.id,
       redirectURL: resolveAuthorizeRedirectURL({
         ...input.returnTo !== void 0 ? { returnTo: input.returnTo } : {}
@@ -18080,7 +18258,7 @@ var TrueFoundryMcpServerStore = class {
       throw new McpServerNotFoundError(input.name);
     }
     await this.#client.deleteMcpAuth({
-      accessToken: await this.#resolveAccessToken(),
+      accessToken: await this.#asUser(),
       mcpServerId: record.id,
       subjectId: this.#subject.id,
       subjectType: this.#subject.type,
@@ -18089,7 +18267,7 @@ var TrueFoundryMcpServerStore = class {
   }
   async #resolveGatewayUrl() {
     if (this.#gatewayUrl === void 0) {
-      const installations = await this.#client.listGatewayInstallations(await this.#resolveAccessToken());
+      const installations = await this.#client.listGatewayInstallations(await this.#asAgent());
       this.#gatewayUrl = resolveDefaultGatewayUrl(installations);
     }
     return this.#gatewayUrl;
@@ -18110,15 +18288,18 @@ function toRecord2(input) {
 init_modelProviderStore();
 var TrueFoundryModelProviderStore = class {
   #client;
-  #resolveAccessToken;
+  #asAgent;
+  #asUser;
   constructor(input) {
     this.#client = input.client;
-    this.#resolveAccessToken = accessTokenForRequest({
+    const tokens = accessTokenForRequest({
       client: input.client,
       requestContext: asTrueFoundryRequestContext(input.requestContext),
       agent: input.agent,
       logger: input.logger
     });
+    this.#asAgent = tokens.asAgent;
+    this.#asUser = tokens.asUser;
   }
   async listProviders(input, transaction) {
     void transaction;
@@ -18151,19 +18332,19 @@ var TrueFoundryModelProviderStore = class {
     return flattenProviderModels(await this.listProviders(input, transaction));
   }
   async #records(input) {
-    const accessToken = await this.#resolveAccessToken();
+    const [agentToken, userToken] = await Promise.all([this.#asAgent(), this.#asUser()]);
     const [integrations, installations] = await Promise.all([
       this.#client.listProviderIntegrations({
-        accessToken,
+        accessToken: agentToken,
         ...input.filter !== void 0 ? { filter: input.filter } : {}
       }),
-      this.#client.listGatewayInstallations(accessToken)
+      this.#client.listGatewayInstallations(agentToken)
     ]);
     const gatewayUrl = resolveDefaultGatewayUrl(installations);
     return toRecords({
       tenant_id: input.tenant_id,
       gatewayUrl,
-      accessToken,
+      accessToken: userToken,
       models: mapEnabledModels({ integrations })
     });
   }