@truefoundry/assistant-ui-runtime 0.1.21 → 0.1.22

package/dist/{types-CQnbe6Qh.d.ts → types-CUUft1YT.d.ts}

@@ -314,6 +314,7 @@ interface AgentSpec<TModel extends Model = Model, TSkill extends SkillMount = Sk
     config?: TConfig;
     instructions?: string;
     variables?: Record<string, string>;
+    description?: string;
 }
 interface Session<TSpec extends AgentSpec = AgentSpec> {
     id: string;
@@ -346,10 +347,12 @@ type PageParams = {
     pageToken?: string;
 };
 interface ListSessionsParams extends PageParams {
-    /** Host-owned agent identity filter. Hosts that key agents by name pass that name here. */
+    /** Host-owned agent identity filter. Omit for all sessions (current user). */
     agentId?: string;
-    /** Host-specific filter (e.g. TFY startTimestamp). */
+    /** Inclusive lower bound on session activity (ISO-8601). */
     startTimestamp?: string;
+    /** Inclusive upper bound on session activity (ISO-8601). */
+    endTimestamp?: string;
 }
 type PreviousTurnIdInput = "auto" | "none" | string;
 type UserMessageContent = string | Array<{
@@ -386,11 +389,25 @@ type TurnInputItem = UserMessage | UserToolApprovalEvent | UserToolResponseEvent
 type TurnStateRunning = {
     status: "running";
 };
+/**
+ * Aggregated token metrics on a finished turn (`turn.done.state.metrics`).
+ * Host maps wire snake_case (`total_input_tokens`, …) → camelCase here.
+ */
+interface TurnDoneMetrics {
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    totalTokens: number;
+    totalCacheReadTokens: number;
+    totalCacheWriteTokens: number;
+    totalReasoningTokens: number;
+}
 type TurnStateDone = {
     status: "done";
     output?: unknown;
     requiredActions?: ActionRequiredEvent[];
     completedAt: string;
+    /** Present when the host reports per-turn token totals. */
+    metrics?: TurnDoneMetrics;
 };
 type TurnStateCancelled = {
     status: "cancelled";
@@ -491,6 +508,8 @@ interface SaveAgentRequest<TSpec extends AgentSpec = AgentSpec> {
 interface SaveAgentResult {
     /** Immutable id allocated by the host registry. */
     agentId?: string;
+    /** Version id allocated by the host registry for this save. */
+    versionId?: string;
     /** Timestamp returned when the active mutable session was updated. */
     sessionUpdatedAt?: string;
 }
@@ -827,18 +846,110 @@ interface CatalogServer<TModelCatalog extends ModelCatalogServer = ModelCatalogS
     sandboxCatalog?: TSandboxCatalog;
 }
 /**
- * Composed host port: chat + builder + optional settings catalog.
+ * Published agent identity + spec for the agent-detail Overview (read-only).
+ * Host widens `TSpec` (and may extend this DTO) for mounts / config / extras.
+ */
+interface AgentDetail<TSpec extends AgentSpec = AgentSpec> {
+    agentId: string;
+    /** Display name (e.g. "release-notes-writer"). */
+    name: string;
+    agentSpec: TSpec;
+}
+/** Stream vs non-stream bodies for one language on the Use In Code tab. */
+interface CodeSnippetSampleCode {
+    stream: string;
+    nonStream: string;
+}
+/**
+ * One language row for Use In Code.
+ * Host maps wire `sample_code` / `non_stream` → camelCase here.
+ */
+interface CodeSnippet<TSample extends CodeSnippetSampleCode = CodeSnippetSampleCode> {
+    /** Sidebar label (e.g. "TypeScript"). */
+    labelName: string;
+    /** Highlighter / tab id (e.g. "typescript"). */
+    language: string;
+    icon?: string;
+    sampleCode: TSample;
+}
+/**
+ * Aggregated session metrics for the sessions list sidebar.
+ * Host maps wire snake_case (`total_turns`, `total_cost_in_usd`, …) → camelCase.
+ */
+interface SessionListMetrics {
+    totalTurns: number;
+    totalCostInUsd: number;
+    totalDurationMs: number;
+}
+/**
+ * One row in the Agent Sessions list (left pane).
+ *
+ * Binding: `agentName` → named / immutable agent; `agentSpec` → mutable / draft.
+ * Host may send one, both, or neither depending on how the session was created.
+ */
+interface SessionListEntry<TSpec extends AgentSpec = AgentSpec> {
+    id: string;
+    title?: string | null;
+    createdAt: string;
+    updatedAt: string;
+    lastActivityAt: string;
+    metrics: SessionListMetrics;
+    /** Present when bound to a published (immutable) agent. */
+    agentName?: string | null;
+    /** Present when bound to a mutable / draft agent spec. */
+    agentSpec?: TSpec;
+}
+/** Params for `AgentSessionsServer.listSessionEvents` (session event timeline). */
+interface ListSessionEventsParams extends Pick<PageParams, "limit" | "pageToken"> {
+    sessionId: string;
+}
+/**
+ * Optional plug-in for agent-detail UI: Overview, Use In Code, sessions list,
+ * and per-session event timeline. Omit `sessions` on `AgentUIServerPort` when
+ * the host has no agent-detail surface.
+ *
+ * Read-only — create/update/delete stay on `AgentChatServer` / `AgentBuilderServer`.
+ */
+interface AgentSessionsServer<TSpec extends AgentSpec = AgentSpec, TDetail extends AgentDetail<TSpec> = AgentDetail<TSpec>, TSnippet extends CodeSnippet = CodeSnippet, TListEntry extends SessionListEntry<TSpec> = SessionListEntry<TSpec>, TList extends ListSessionsParams = ListSessionsParams> {
+    /** Fetch published agent details by id for the Overview tab. */
+    getAgent(req: {
+        agentId: string;
+    }): Promise<TDetail>;
+    /** Fetch Use In Code snippets for the agent (one row per language). */
+    getCodeSnippets(req: {
+        agentId: string;
+    }): Promise<TSnippet[]>;
+    /**
+     * List sessions for the current user. Pass `agentId` to scope to one agent;
+     * omit for all sessions. Use `startTimestamp` / `endTimestamp` for date filters.
+     */
+    listSessions(req?: TList): Promise<ListResult<TListEntry>>;
+    /**
+     * Fetch the session event timeline (right pane). Paginate with `pageToken`
+     * until exhausted; rebuild turns from `turn.created` / `turn.done` +
+     * nested `TurnEvent`s. Per-turn token metrics live on `turn.done.state.metrics`.
+     */
+    listSessionEvents(req: ListSessionEventsParams): Promise<ListResult<SessionEventItem>>;
+}
+/**
+ * Composed host port: chat + builder + optional settings catalog + optional
+ * agent-detail / sessions shell.
  *
  * `catalog` is optional — if the host passes it, settings UI can call
  * `useCatalogServer()` / show modelCatalog, connectorCatalog, and skillCatalog;
  * if omitted, those surfaces stay hidden.
  *
+ * `sessions` is optional — if the host passes it, agent-detail UI can call
+ * `useAgentSessionsServer()` / Overview + sessions under an agent; if omitted,
+ * that surface stays hidden.
+ *
  * trueforge-ui re-exports this as `AgentUIServer`.
  */
-type AgentUIServerPort<TChat extends AgentChatServer = AgentChatServer, TBuilder extends AgentBuilderServer = AgentBuilderServer, TCatalog extends CatalogServer = CatalogServer> = TChat & TBuilder & {
+type AgentUIServerPort<TChat extends AgentChatServer = AgentChatServer, TBuilder extends AgentBuilderServer = AgentBuilderServer, TCatalog extends CatalogServer = CatalogServer, TSessions extends AgentSessionsServer = AgentSessionsServer> = TChat & TBuilder & {
     catalog?: TCatalog;
+    sessions?: TSessions;
 };
 /** Host-facing alias used by trueforge-ui. */
 type AgentUIServer = AgentUIServerPort;
 
-export type { ModelCatalogServer as $, AgentSpec as A, ConnectorBase as B, CatalogServer as C, ConnectorCatalogEntry as D, ConnectorCatalogServer as E, ConnectorConfigBase as F, ConnectorSelectorEntry as G, ConnectorState as H, CreateConnectorRequest as I, CreateModelProviderRequest as J, CreateSandboxProviderRequest as K, CreateSandboxRequest as L, McpAuthRequiredEvent as M, CreateSessionRequest as N, CreateSkillRequest as O, CreateSkillRequestBase as P, DefinedSkill as Q, GithubSkill as R, Session as S, TurnEvent as T, UserToolResponseEvent as U, ImportGithubSkillRequest as V, ListResult as W, ListSessionsOrder as X, ListSessionsParams as Y, McpServerMount as Z, Model as _, AgentChatServer as a, ToolResponseEvent as a$, ModelEntry as a0, ModelMessageEvent as a1, ModelParams as a2, ModelProperties as a3, ModelProviderBase as a4, ModelProviderCatalogEntry as a5, ModelProviderConfigBase as a6, ModelSelection as a7, ModelSelectorEntry as a8, PageParams as a9, ToolApprovalRequiredEvent as aA, ToolBase as aB, ToolCall as aC, ToolResponseRequiredEvent as aD, TurnState as aE, TurnStateDone as aF, TurnStreamData as aG, TurnStreamingEvent as aH, UpdateConnectorRequest as aI, UpdateModelProviderRequest as aJ, UpdateSandboxProviderRequest as aK, UpdateSandboxRequest as aL, UpdateSessionRequest as aM, UserMessage as aN, DeltaEvents as aO, ActionRequiredEvent as aP, AgentInfo as aQ, AgentParent as aR, ChunkDeltaToolCall as aS, McpInitializeEvent as aT, McpServerAuthInfo as aU, ModelMessageContentPart as aV, ModelMessageDeltaEvent as aW, ThreadDoneEvent as aX, ToolCallFunction as aY, ToolCallRef as aZ, ToolInfo as a_, PreviousTurnIdInput as aa, ProviderEntry as ab, ProviderType as ac, RegistrySkill as ad, SandboxBase as ae, SandboxCatalogEntry as af, SandboxCatalogServer as ag, SandboxConfig as ah, SandboxCreatedEvent as ai, SandboxProviderBase as aj, SandboxProviderCatalogEntry as ak, SandboxProviderConfig as al, SandboxProviderListEntry as am, SandboxSnapshotSyncStatus as an, SaveAgentRequest as ao, SaveAgentResult as ap, SearchAgentSelectorParams as aq, SearchAgentsParams as ar, SelectRegistrySkillRequest as as, SessionEventItem as at, SkillBase as au, SkillCatalogEntry as av, SkillCatalogServer as aw, SkillConfigBase as ax, SkillMount as ay, SkillSelectorEntry as az, ThreadCreatedEvent as b, TurnCreatedEvent as b0, TurnDoneEvent as b1, TurnStateCancelled as b2, TurnStateError as b3, TurnStateRunning as b4, UserMessageContent as b5, UserToolApprovalEvent as c, Turn as d, TurnInputItem as e, AgentBuilderCapabilitiesResponse as f, AgentBuilderServer as g, AgentCapabilityConfig as h, AgentLibraryEntry as i, AgentRuntimeConfig as j, AgentSelectorEntry as k, AgentSkill as l, AgentUIServer as m, AgentUIServerPort as n, ApprovalDecision as o, AuthenticateConnectorRequest as p, ConnectorAuth as q, ConnectorAuthApiKey as r, ConnectorAuthNone as s, ConnectorAuthOAuth as t, ConnectorAuthPublic as u, ConnectorAuthPublicApiKey as v, ConnectorAuthPublicNone as w, ConnectorAuthPublicOAuth as x, ConnectorAuthType as y, ConnectorAuthenticationResult as z };
+export type { ListSessionEventsParams as $, AgentSpec as A, ConnectorAuthPublicNone as B, CatalogServer as C, ConnectorAuthPublicOAuth as D, ConnectorAuthType as E, ConnectorAuthenticationResult as F, ConnectorBase as G, ConnectorCatalogEntry as H, ConnectorCatalogServer as I, ConnectorConfigBase as J, ConnectorSelectorEntry as K, ConnectorState as L, McpAuthRequiredEvent as M, CreateConnectorRequest as N, CreateModelProviderRequest as O, CreateSandboxProviderRequest as P, CreateSandboxRequest as Q, CreateSessionRequest as R, Session as S, TurnEvent as T, UserToolResponseEvent as U, CreateSkillRequest as V, CreateSkillRequestBase as W, DefinedSkill as X, GithubSkill as Y, ImportGithubSkillRequest as Z, ListResult as _, AgentChatServer as a, McpInitializeEvent as a$, ListSessionsOrder as a0, ListSessionsParams as a1, McpServerMount as a2, Model as a3, ModelCatalogServer as a4, ModelEntry as a5, ModelMessageEvent as a6, ModelParams as a7, ModelProperties as a8, ModelProviderBase as a9, SessionListMetrics as aA, SkillBase as aB, SkillCatalogEntry as aC, SkillCatalogServer as aD, SkillConfigBase as aE, SkillMount as aF, SkillSelectorEntry as aG, ToolApprovalRequiredEvent as aH, ToolBase as aI, ToolCall as aJ, ToolResponseRequiredEvent as aK, TurnDoneMetrics as aL, TurnState as aM, TurnStateDone as aN, TurnStreamData as aO, TurnStreamingEvent as aP, UpdateConnectorRequest as aQ, UpdateModelProviderRequest as aR, UpdateSandboxProviderRequest as aS, UpdateSandboxRequest as aT, UpdateSessionRequest as aU, UserMessage as aV, DeltaEvents as aW, ActionRequiredEvent as aX, AgentInfo as aY, AgentParent as aZ, ChunkDeltaToolCall as a_, ModelProviderCatalogEntry as aa, ModelProviderConfigBase as ab, ModelSelection as ac, ModelSelectorEntry as ad, PageParams as ae, PreviousTurnIdInput as af, ProviderEntry as ag, ProviderType as ah, RegistrySkill as ai, SandboxBase as aj, SandboxCatalogEntry as ak, SandboxCatalogServer as al, SandboxConfig as am, SandboxCreatedEvent as an, SandboxProviderBase as ao, SandboxProviderCatalogEntry as ap, SandboxProviderConfig as aq, SandboxProviderListEntry as ar, SandboxSnapshotSyncStatus as as, SaveAgentRequest as at, SaveAgentResult as au, SearchAgentSelectorParams as av, SearchAgentsParams as aw, SelectRegistrySkillRequest as ax, SessionEventItem as ay, SessionListEntry as az, ThreadCreatedEvent as b, McpServerAuthInfo as b0, ModelMessageContentPart as b1, ModelMessageDeltaEvent as b2, ThreadDoneEvent as b3, ToolCallFunction as b4, ToolCallRef as b5, ToolInfo as b6, ToolResponseEvent as b7, TurnCreatedEvent as b8, TurnDoneEvent as b9, TurnStateCancelled as ba, TurnStateError as bb, TurnStateRunning as bc, UserMessageContent as bd, UserToolApprovalEvent as c, Turn as d, TurnInputItem as e, AgentBuilderCapabilitiesResponse as f, AgentBuilderServer as g, AgentCapabilityConfig as h, AgentDetail as i, AgentLibraryEntry as j, AgentRuntimeConfig as k, AgentSelectorEntry as l, AgentSessionsServer as m, AgentSkill as n, AgentUIServer as o, AgentUIServerPort as p, ApprovalDecision as q, AuthenticateConnectorRequest as r, CodeSnippet as s, CodeSnippetSampleCode as t, ConnectorAuth as u, ConnectorAuthApiKey as v, ConnectorAuthNone as w, ConnectorAuthOAuth as x, ConnectorAuthPublic as y, ConnectorAuthPublicApiKey as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@truefoundry/assistant-ui-runtime",
-  "version": "0.1.21",
+  "version": "0.1.22",
   "description": "TrueFoundry Gateway agent runtime adapter for assistant-ui",
   "license": "Apache-2.0",
   "repository": {

package/src/index.ts

@@ -93,6 +93,7 @@ export type {
     Session,
     Turn,
     TurnState,
+    TurnDoneMetrics,
     TurnStateDone,
     TurnInputItem,
     AgentSpec,
@@ -158,6 +159,13 @@ export type {
     UpdateSandboxProviderRequest,
     SandboxCatalogServer,
     CatalogServer,
+    AgentDetail,
+    CodeSnippetSampleCode,
+    CodeSnippet,
+    SessionListMetrics,
+    SessionListEntry,
+    ListSessionEventsParams,
+    AgentSessionsServer,
     AgentUIServerPort,
     AgentUIServer,
     ProviderEntry,
@@ -208,6 +216,8 @@ export {
     type TfyConnectorSelectorEntry,
     type TfyAgentSelectorEntry,
     type TfyAgentSpec,
+    type TfyCollaborator,
+    type TfySaveAgentResult,
     type TfySkillMount,
     type TfyMcpServerMount,
     type TfyModelParams,

package/src/plugins/truefoundry-agent-server-adapter/cp.test.ts

@@ -9,8 +9,9 @@ import {
     normalizeMcpServers,
     resolveGatewayURL,
     saveAgent,
+    saveAgentResultFromCp,
     SAVE_AGENT_COLLABORATORS,
-    SAVE_AGENT_METADATA_TAGS,
+    SAVE_AGENT_TAGS,
     toCamelCaseDeep,
     toSnakeCaseDeep,
 } from "./cp.js";
@@ -467,7 +468,7 @@ describe("toSnakeCaseDeep", () => {
 });
 
 describe("buildSaveAgentManifest", () => {
-    it("hardcodes type / metadata_tags / collaborators and snake_cases spec fields", () => {
+    it("spreads the snake-cased spec and defaults missing tags / collaborators", () => {
         const manifest = buildSaveAgentManifest("my-agent", {
             model: {
                 name: "ai-foundry/claude-sonnet-4-6",
@@ -502,7 +503,7 @@ describe("buildSaveAgentManifest", () => {
                 name: "ai-foundry/claude-sonnet-4-6",
                 params: { max_tokens: 8192, reasoning_effort: "medium" },
             },
-            metadata_tags: { ...SAVE_AGENT_METADATA_TAGS },
+            tags: { ...SAVE_AGENT_TAGS },
             collaborators: [...SAVE_AGENT_COLLABORATORS],
             instructions: "Be helpful",
             config: {
@@ -527,6 +528,45 @@ describe("buildSaveAgentManifest", () => {
         });
     });
 
+    it("keeps host tags, collaborators, and extra spec fields", () => {
+        const manifest = buildSaveAgentManifest("named", {
+            model: {
+                name: "openai-main/gpt-4.1",
+                params: { maxTokens: 4096, temperature: 0.2 },
+            },
+            description: "My agent",
+            instructions: "Be concise",
+            variables: { city: "Berlin" },
+            messages: [{ role: "user", content: "Hello {{city}}" }],
+            responseFormat: {
+                type: "json_schema",
+                jsonSchema: { name: "answer", schema: { type: "object" } },
+            },
+            tags: { env: "test", owner: "platform" },
+            collaborators: [
+                { subject: "user:ada@example.com", roleId: "agent-manager" },
+            ],
+        } as never);
+
+        expect(manifest.description).toBe("My agent");
+        expect(manifest.tags).toEqual({ env: "test", owner: "platform" });
+        expect(manifest.collaborators).toEqual([
+            { subject: "user:ada@example.com", role_id: "agent-manager" },
+        ]);
+        expect(manifest.variables).toEqual({ city: "Berlin" });
+        expect(manifest.messages).toEqual([
+            { role: "user", content: "Hello {{city}}" },
+        ]);
+        expect(manifest.response_format).toEqual({
+            type: "json_schema",
+            json_schema: { name: "answer", schema: { type: "object" } },
+        });
+        expect(manifest.model).toEqual({
+            name: "openai-main/gpt-4.1",
+            params: { max_tokens: 4096, temperature: 0.2 },
+        });
+    });
+
     it("normalizes UI catalog mounts and defaults enable_tools / preload", () => {
         const manifest = buildSaveAgentManifest("draft-save", {
             model: { name: "openai-main/gpt-4.1" },
@@ -572,7 +612,7 @@ describe("buildSaveAgentManifest", () => {
 describe("saveAgent", () => {
     it("PUTs { manifest } to /api/svc/v1/agents", async () => {
         const fetchMock = vi.fn(async () =>
-            Response.json({ id: "ag_1", name: "my-agent" }),
+            Response.json({ data: { id: "ag_1", name: "my-agent" } }),
         );
         vi.stubGlobal("fetch", fetchMock);
 
@@ -581,10 +621,11 @@ describe("saveAgent", () => {
             {
                 agentName: "my-agent",
                 agentSpec: { model: { name: "openai-main/gpt-4.1" } },
+                intent: "create",
             },
         );
 
-        expect(result).toEqual({ id: "ag_1", name: "my-agent" });
+        expect(result).toEqual({ agentId: "ag_1" });
         expect(fetchMock).toHaveBeenCalledWith(
             "https://cp.example/api/svc/v1/agents",
             expect.objectContaining({
@@ -604,7 +645,195 @@ describe("saveAgent", () => {
         expect(body.manifest.type).toBe("truefoundry-agent");
         expect(body.manifest.name).toBe("my-agent");
         expect(body.manifest.model).toEqual({ name: "openai-main/gpt-4.1" });
-        expect(body.manifest.metadata_tags).toEqual(SAVE_AGENT_METADATA_TAGS);
+        expect(body.manifest.tags).toEqual(SAVE_AGENT_TAGS);
         expect(body.manifest.collaborators).toEqual([...SAVE_AGENT_COLLABORATORS]);
     });
+
+    it("extracts agentId and versionId from a wrapped CP version response", async () => {
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async () =>
+                Response.json({
+                    data: { id: "ver_9", agentId: "ag_1", name: "my-agent" },
+                }),
+            ),
+        );
+
+        const result = await saveAgent(
+            { apiKey: "key", cpURL: "https://cp.example/" },
+            {
+                agentName: "my-agent",
+                agentSpec: { model: { name: "openai-main/gpt-4.1" } },
+                intent: "update",
+            },
+        );
+
+        expect(result).toEqual({ agentId: "ag_1", versionId: "ver_9" });
+    });
+});
+
+describe("saveAgentResultFromCp", () => {
+    it("reads { data: { id, name } } (no agentId) as the agent itself", () => {
+        expect(
+            saveAgentResultFromCp({ data: { id: "ag_1", name: "my-agent" } }),
+        ).toEqual({ agentId: "ag_1" });
+    });
+
+    it("reads { data: { id, agentId } } as version + agent", () => {
+        expect(
+            saveAgentResultFromCp({ data: { id: "ver_1", agentId: "ag_2" } }),
+        ).toEqual({ agentId: "ag_2", versionId: "ver_1" });
+    });
+
+    it("returns {} for malformed payloads", () => {
+        expect(saveAgentResultFromCp(null)).toEqual({});
+        expect(saveAgentResultFromCp({ id: "not-wrapped" })).toEqual({});
+    });
+});
+
+describe("old saved-agent manifest round-trip", () => {
+    const oldManifest = {
+        type: "truefoundry-agent",
+        name: "ask-ai-agent",
+        description: "Answer questions",
+        model: {
+            name: "openai-main/gpt-4.1",
+            params: { max_tokens: 8192, reasoning_effort: "medium" },
+        },
+        instructions: "Be helpful",
+        // Variable names are user keys — `my_city` must never become `myCity`.
+        variables: {
+            city: "Berlin",
+            my_city: { default_value: "Pune", description: "home town" },
+        },
+        messages: [{ role: "user", content: "Hello {{city}}" }],
+        // Uppercase tag keys are the regression case: snake-casing them once
+        // produced "_t_f_y__a_l_p_h_a__…" on the wire.
+        tags: {
+            env: "prod",
+            owner: "platform",
+            TFY_ALPHA_ENABLE_OPENUI: "true",
+        },
+        collaborators: [
+            { subject: "team:everyone", role_id: "agent-access" },
+        ],
+        response_format: {
+            type: "json_schema",
+            json_schema: {
+                name: "answer",
+                // Schema property names are user data — `user_name` must
+                // survive both directions verbatim.
+                schema: {
+                    type: "object",
+                    properties: { user_name: { type: "string" } },
+                },
+            },
+        },
+        config: {
+            iteration_limit: 50,
+            ask_user_questions: { enabled: true },
+            sandbox: { enabled: true, file_downloads: true },
+        },
+        mcp_servers: [
+            {
+                type: "truefoundry-mcp-registry",
+                name: "gmail",
+                enable_tools: ["@read-only"],
+                preload: true,
+            },
+        ],
+        skills: [
+            {
+                type: "truefoundry-skills-registry",
+                fqn: "agent-skill:tfy/skills/web:1",
+                preload: false,
+            },
+        ],
+    };
+
+    it("reads snake_case fields into camelCase spec and writes them back", () => {
+        const spec = agentSpecFromCpManifest(oldManifest);
+        expect(spec?.description).toBe("Answer questions");
+        // User keys verbatim; `{ default_value }` records collapse to strings.
+        expect(spec?.variables).toEqual({ city: "Berlin", my_city: "Pune" });
+        expect(spec?.messages).toEqual([
+            { role: "user", content: "Hello {{city}}" },
+        ]);
+        expect(spec?.tags).toEqual({
+            env: "prod",
+            owner: "platform",
+            TFY_ALPHA_ENABLE_OPENUI: "true",
+        });
+        expect(spec?.collaborators).toEqual([
+            { subject: "team:everyone", roleId: "agent-access" },
+        ]);
+        expect(spec?.responseFormat).toEqual({
+            type: "json_schema",
+            jsonSchema: {
+                name: "answer",
+                schema: {
+                    type: "object",
+                    properties: { user_name: { type: "string" } },
+                },
+            },
+        });
+        expect(spec?.model.params).toEqual({
+            maxTokens: 8192,
+            reasoningEffort: "medium",
+        });
+        expect(spec?.config).toEqual({
+            iterationLimit: 50,
+            askUserQuestions: { enabled: true },
+            sandbox: { enabled: true, fileDownloads: true },
+        });
+
+        const saved = buildSaveAgentManifest("ask-ai-agent", spec!);
+        expect(saved.description).toBe("Answer questions");
+        expect(saved.variables).toEqual({ city: "Berlin", my_city: "Pune" });
+        expect(saved.messages).toEqual([
+            { role: "user", content: "Hello {{city}}" },
+        ]);
+        expect(saved.tags).toEqual({
+            env: "prod",
+            owner: "platform",
+            TFY_ALPHA_ENABLE_OPENUI: "true",
+        });
+        expect(saved.collaborators).toEqual([
+            { subject: "team:everyone", role_id: "agent-access" },
+        ]);
+        expect(saved.response_format).toEqual({
+            type: "json_schema",
+            json_schema: {
+                name: "answer",
+                schema: {
+                    type: "object",
+                    properties: { user_name: { type: "string" } },
+                },
+            },
+        });
+        expect(saved.model).toEqual({
+            name: "openai-main/gpt-4.1",
+            params: { max_tokens: 8192, reasoning_effort: "medium" },
+        });
+        expect(saved.config).toEqual({
+            iteration_limit: 50,
+            ask_user_questions: { enabled: true },
+            sandbox: { enabled: true, file_downloads: true },
+        });
+        expect(saved.mcp_servers).toEqual([
+            {
+                type: "truefoundry-mcp-registry",
+                name: "gmail",
+                enable_tools: ["@read-only"],
+                preload: true,
+            },
+        ]);
+        expect(saved.skills).toEqual([
+            {
+                type: "truefoundry-skills-registry",
+                fqn: "agent-skill:tfy/skills/web:1",
+                preload: false,
+            },
+        ]);
+    });
 });