@truefoundry/assistant-ui-runtime 0.1.21 → 0.1.22

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

@@ -19,7 +19,7 @@ import {
     reasoningEffortsForModel,
 } from "./modelReasoningEffort.js";
 import { normalizeAgentSpecForGateway } from "./normalizeAgentSpec.js";
-import type { TfyAgentSpec } from "./types.js";
+import type { TfyAgentSpec, TfySaveAgentResult } from "./types.js";
 
 // ---------------------------------------------------------------------------
 // Selector rows — FE base + TFY mount fields
@@ -408,6 +408,61 @@ export function toCamelCaseDeep(value: unknown): unknown {
     return value;
 }
 
+/** Keys are user data (e.g. metadata tag names) — copied verbatim, never case-converted. */
+function stringRecordFromCp(raw: unknown): Record<string, string> | undefined {
+    if (!isRecord(raw)) return undefined;
+    const out: Record<string, string> = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (typeof value === "string") out[key] = value;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+
+/**
+ * Variable names are user keys and must survive verbatim. Values appear as
+ * plain strings in new manifests and `{ default_value }` records in older
+ * ones; both collapse to the resolved string.
+ */
+function variablesFromCp(raw: unknown): Record<string, string> | undefined {
+    if (!isRecord(raw)) return undefined;
+    const out: Record<string, string> = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (typeof value === "string") {
+            out[key] = value;
+        } else if (isRecord(value) && typeof value.default_value === "string") {
+            out[key] = value.default_value;
+        }
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+
+/**
+ * Rebuild the gateway ResponseFormat from the wire shape. Only the envelope
+ * key changes case (`json_schema` → `jsonSchema`); the `schema` body is a
+ * user-authored JSON schema whose property names must not be rewritten.
+ */
+function responseFormatFromCp(raw: unknown): TfyAgentSpec["responseFormat"] {
+    if (!isRecord(raw)) return undefined;
+    if (raw.type === "text") return { type: "text" };
+    if (raw.type === "json_object") return { type: "json_object" };
+    if (raw.type !== "json_schema") return undefined;
+    const wireSchema = isRecord(raw.json_schema) ? raw.json_schema : undefined;
+    if (wireSchema == null || typeof wireSchema.name !== "string") return undefined;
+    return {
+        type: "json_schema",
+        jsonSchema: {
+            name: wireSchema.name,
+            ...(typeof wireSchema.description === "string"
+                ? { description: wireSchema.description }
+                : {}),
+            ...(isRecord(wireSchema.schema) ? { schema: wireSchema.schema } : {}),
+            ...(typeof wireSchema.strict === "boolean" || wireSchema.strict === null
+                ? { strict: wireSchema.strict }
+                : {}),
+        },
+    };
+}
+
 /**
  * Map a CP AgentManifest (snake_case wire) → FE AgentSpec for Edit seeding.
  * Skills/MCP keep `{ id, name }` for draft pickers plus runtime fields
@@ -485,11 +540,39 @@ export function agentSpecFromCpManifest(manifest: unknown): TfyAgentSpec | undef
     const config =
         configRaw != null ? (toCamelCaseDeep(configRaw) as TfyAgentSpec["config"]) : undefined;
 
+    // Wire-named pass-through fields (description, messages, collaborators)
+    // need no mount remapping — one camelCase pass and a shape guard each.
+    // Guards drop malformed values instead of seeding the editor with garbage.
+    const camel = toCamelCaseDeep(manifest) as Record<string, unknown>;
+    const description =
+        typeof camel.description === "string" ? camel.description : undefined;
+    const messages = Array.isArray(camel.messages)
+        ? (camel.messages as TfyAgentSpec["messages"])
+        : undefined;
+    const collaborators = Array.isArray(camel.collaborators)
+        ? (camel.collaborators as TfyAgentSpec["collaborators"])
+        : undefined;
+
+    // User-keyed fields are read from the RAW manifest: their keys are data
+    // (tag names like "TFY_ALPHA_ENABLE_OPENUI", variable names like
+    // "my_city", JSON-schema property names), and case-converting them
+    // corrupts saved agents (e.g. "TFY_ALPHA…" → "tfyAlpha…" → on the next
+    // save "_t_f_y__a_l_p_h_a__…").
+    const variables = variablesFromCp(manifest.variables);
+    const tags = stringRecordFromCp(manifest.tags);
+    const responseFormat = responseFormatFromCp(manifest.response_format);
+
     return {
         model,
         ...(typeof manifest.instructions === "string"
             ? { instructions: manifest.instructions }
             : {}),
+        ...(description != null ? { description } : {}),
+        ...(variables != null ? { variables } : {}),
+        ...(messages != null ? { messages } : {}),
+        ...(responseFormat != null ? { responseFormat } : {}),
+        ...(tags != null ? { tags } : {}),
+        ...(collaborators != null ? { collaborators } : {}),
         ...(config != null ? { config } : {}),
         ...(skills.length > 0 ? { skills } : {}),
         ...(mcpServers.length > 0 ? { mcpServers } : {}),
@@ -544,7 +627,7 @@ export async function listAgents(
 // ---------------------------------------------------------------------------
 
 /** Platform feature flags baked into every saved agent manifest. */
-export const SAVE_AGENT_METADATA_TAGS = {
+export const SAVE_AGENT_TAGS = {
     agent: "tfy-ai-gateway-agent",
     TFY_ALPHA_ENABLE_OPENUI: "true",
     TFY_ALPHA_ENABLE_ASK_USER: "true",
@@ -601,10 +684,47 @@ function skillMountForCp(mount: unknown): Record<string, unknown> {
     return snake;
 }
 
+/**
+ * Snake-case only the response_format envelope (`jsonSchema` → `json_schema`);
+ * the `schema` body is a user-authored JSON schema whose property names must
+ * not be rewritten. Inverse of {@link responseFormatFromCp}.
+ */
+function responseFormatForCp(
+    responseFormat: NonNullable<TfyAgentSpec["responseFormat"]>,
+): Record<string, unknown> {
+    const out: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(responseFormat)) {
+        if (key === "jsonSchema" && isRecord(value)) {
+            const inner: Record<string, unknown> = {};
+            for (const [innerKey, innerValue] of Object.entries(value)) {
+                inner[camelToSnakeKey(innerKey)] =
+                    innerKey === "schema" ? innerValue : toSnakeCaseDeep(innerValue);
+            }
+            out.json_schema = inner;
+            continue;
+        }
+        out[camelToSnakeKey(key)] = toSnakeCaseDeep(value);
+    }
+    return out;
+}
+
 /**
  * Build CP `manifest` for `PUT /api/svc/v1/agents`.
- * Normalizes UI catalog mounts, snake_cases gateway fields, hardcodes type /
- * metadata_tags / collaborators.
+ *
+ * Wire-named spec fields are snake-cased and spread so any field the host
+ * puts on the spec reaches the wire without this adapter enumerating it.
+ * tags / variables / responseFormat are pulled out FIRST because
+ * their keys are user data — snake-casing a tag named
+ * "TFY_ALPHA_ENABLE_OPENUI" would corrupt it to "_t_f_y__a_l_p_h_a__…" —
+ * and re-attached verbatim after the spread.
+ *
+ * Field order matters:
+ *  1. `...snake` — everything wire-named the host provided.
+ *  2. description / tags / collaborators — CP requires these, so
+ *     platform defaults fill in only when the host omitted them.
+ *  3. mcp_servers / skills — overwrite the spread values because catalog
+ *     mounts need remapping to gateway registry shapes (mcpMountForCp /
+ *     skillMountForCp), which plain snake-casing cannot do.
  */
 export function buildSaveAgentManifest(
     agentName: string,
@@ -613,24 +733,51 @@ export function buildSaveAgentManifest(
     const spec = normalizeAgentSpecForGateway(agentSpec);
     const mcpServers = (spec.mcpServers ?? []).map(mcpMountForCp);
     const skills = (spec.skills ?? []).map(skillMountForCp);
-    // CP AgentManifest requires description; not on FE AgentSpec yet.
-    const rawDescription = (agentSpec as { description?: unknown }).description;
-    const description = typeof rawDescription === "string" ? rawDescription : "";
+    const { tags, variables, responseFormat, ...wireFields } = spec;
+    const snake = toSnakeCaseDeep(wireFields) as Record<string, unknown>;
 
     return {
         type: "truefoundry-agent",
         name: agentName,
-        description,
-        model: toSnakeCaseDeep(spec.model),
-        metadata_tags: { ...SAVE_AGENT_METADATA_TAGS },
-        collaborators: [...SAVE_AGENT_COLLABORATORS],
-        ...(spec.instructions != null ? { instructions: spec.instructions } : {}),
-        ...(spec.config != null ? { config: toSnakeCaseDeep(spec.config) } : {}),
+        ...snake,
+        description: typeof snake.description === "string" ? snake.description : "",
+        tags: tags ?? { ...SAVE_AGENT_TAGS },
+        collaborators: Array.isArray(snake.collaborators)
+            ? snake.collaborators
+            : [...SAVE_AGENT_COLLABORATORS],
+        ...(variables != null ? { variables } : {}),
+        ...(responseFormat != null
+            ? { response_format: responseFormatForCp(responseFormat) }
+            : {}),
         ...(mcpServers.length > 0 ? { mcp_servers: mcpServers } : {}),
         ...(skills.length > 0 ? { skills } : {}),
     };
 }
 
+function nonEmptyString(value: unknown): string | undefined {
+    return typeof value === "string" && value !== "" ? value : undefined;
+}
+
+/**
+ * Normalize CP save responses into
+ * `{ agentId, versionId }`. Observed live shapes (both camelCase, wrapped):
+ *   { data: { id: "<versionId>", agentId: "<agentId>", fqn, version, … } } //agent-playground
+ *   { data: { id: "<agentId>", name, manifest } }  — no separate version //trueforge
+ * `id` is a version id only when a distinct `agentId` accompanies it;
+ * otherwise `id` is the agent itself and no version id is known.
+ */
+export function saveAgentResultFromCp(raw: unknown): TfySaveAgentResult {
+    const root = isRecord(raw) ? raw : {};
+    const data = isRecord(root.data) ? root.data : {};
+    const agentId = nonEmptyString(data.agentId) ?? nonEmptyString(data.id);
+    const versionId =
+        nonEmptyString(data.agentId) != null ? nonEmptyString(data.id) : undefined;
+    return {
+        ...(agentId != null ? { agentId } : {}),
+        ...(versionId != null ? { versionId } : {}),
+    };
+}
+
 /**
  * Upsert a named agent on the Control Plane.
  * `PUT /api/svc/v1/agents` with `{ manifest }` — name is the upsert key.
@@ -638,11 +785,12 @@ export function buildSaveAgentManifest(
 export async function saveAgent(
     opts: CpCredentials,
     req: SaveAgentRequest<TfyAgentSpec>,
-): Promise<unknown> {
+): Promise<TfySaveAgentResult> {
     const manifest = buildSaveAgentManifest(req.agentName, req.agentSpec);
-    return cpFetch(opts, "/api/svc/v1/agents", {
+    const raw = await cpFetch<unknown>(opts, "/api/svc/v1/agents", {
         method: "PUT",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({ manifest }),
     });
+    return saveAgentResultFromCp(raw);
 }

package/src/plugins/truefoundry-agent-server-adapter/createTrueFoundryAgentUIServer.ts

@@ -15,7 +15,7 @@ import {
     createTrueFoundryChatServer,
     type TrueFoundryChatServer,
 } from "./chatServer.js";
-import type { TfyAgentSpec } from "./types.js";
+import type { TfyAgentSpec, TfySaveAgentResult } from "./types.js";
 
 export type CreateTrueFoundryAgentUIServerOptions = {
     apiKey: string;
@@ -37,7 +37,7 @@ export type TrueFoundryAgentUIServer<TSpec extends TfyAgentSpec = TfyAgentSpec>
             TfySkillSelectorEntry,
             TfyConnectorSelectorEntry,
             TfyAgentSelectorEntry,
-            unknown
+            TfySaveAgentResult
         >;
 
 function credentialsKey(opts: CreateTrueFoundryAgentUIServerOptions): string {

package/src/plugins/truefoundry-agent-server-adapter/index.ts

@@ -17,9 +17,32 @@ export {
 
 export {
     type RequireApprovalToolSelectorItem,
-    type RequireApprovalToolsSelectorTag, type TfyAgentSpec, type TfyCreateSessionRequest, type TfyFinishReason, type TfyListSessionsParams, type TfyMcpServerInitInfo, type TfyMcpServerMount, type TfyMcpToolInfo,
-    type TfyModelMessageUsage, type TfyModelParams, type TfyResponseFormat, type TfyRuntimeConfig, type TfySession, type TfySkillMount, type TfySubject, type TfySystemToolInfo, type TfyThreadState, type TfyToolInfo, type TfyTurn, type TfyTurnCancelledReason, type TfyTurnState, type TfyTurnStateDoneOutput, type ToolsSelectorItem,
-    type ToolsSelectorTag
+    type RequireApprovalToolsSelectorTag,
+    type TfyAgentSpec,
+    type TfyCollaborator,
+    type TfyCreateSessionRequest,
+    type TfyFinishReason,
+    type TfyListSessionsParams,
+    type TfyMcpServerInitInfo,
+    type TfyMcpServerMount,
+    type TfyMcpToolInfo,
+    type TfyModelMessageUsage,
+    type TfyModelParams,
+    type TfyResponseFormat,
+    type TfyRuntimeConfig,
+    type TfySaveAgentResult,
+    type TfySession,
+    type TfySkillMount,
+    type TfySubject,
+    type TfySystemToolInfo,
+    type TfyThreadState,
+    type TfyToolInfo,
+    type TfyTurn,
+    type TfyTurnCancelledReason,
+    type TfyTurnState,
+    type TfyTurnStateDoneOutput,
+    type ToolsSelectorItem,
+    type ToolsSelectorTag,
 } from "./types.js";
 
 export {

package/src/plugins/truefoundry-agent-server-adapter/types.ts

@@ -16,6 +16,7 @@ import type {
     AgentSpec,
     CreateSessionRequest,
     ListSessionsParams,
+    SaveAgentResult,
     Session,
     Turn,
     TurnState,
@@ -63,6 +64,11 @@ export type TfyMcpServerMount = RuntimeMcpServerMount & TruefoundryGatewayApi.Mc
 // AgentSpec — the concrete TrueFoundry agent definition
 // ---------------------------------------------------------------------------
 
+export interface TfyCollaborator {
+    subject: string;
+    roleId: string;
+}
+
 export interface TfyAgentSpec
     extends AgentSpec<
         TruefoundryGatewayApi.Model,
@@ -72,8 +78,12 @@ export interface TfyAgentSpec
     > {
     responseFormat?: TruefoundryGatewayApi.ResponseFormat;
     messages?: TruefoundryGatewayApi.AgentSpecUserMessage[];
+    tags?: Record<string, string>;
+    collaborators?: TfyCollaborator[];
 }
 
+export type TfySaveAgentResult = SaveAgentResult;
+
 // ---------------------------------------------------------------------------
 // Turn — runtime base narrowed to the gateway's concrete state shapes
 // ---------------------------------------------------------------------------

package/src/plugins/truefoundry-agent-server-adapter/types.typecheck.ts

@@ -15,6 +15,7 @@ import type {
     TfyAgentSpec,
     TfyFinishReason,
     TfyMcpServerMount,
+    TfySaveAgentResult,
     TfySkillMount,
     TfySubject,
     TfyTurn,
@@ -162,3 +163,16 @@ export const withEndTimestamp: NonNullable<
     startTimestamp: "2026-01-01T00:00:00Z",
     endTimestamp: "2026-02-01T00:00:00Z",
 };
+
+export const savedAgent: TfyAgentSpec = {
+    model: { name: "openai-main/gpt-4.1" },
+    description: "Demo",
+    tags: { env: "test" },
+    collaborators: [{ subject: "team:everyone", roleId: "agent-access" }],
+    variables: { city: "Berlin" },
+};
+
+export const saveResult: TfySaveAgentResult = {
+    agentId: "ag_1",
+    versionId: "ver_1",
+};

package/src/server/index.ts

@@ -35,6 +35,7 @@ export type {
     UserToolResponseEvent,
     TurnInputItem,
     TurnStateRunning,
+    TurnDoneMetrics,
     TurnStateDone,
     TurnStateCancelled,
     TurnStateError,
@@ -94,6 +95,13 @@ export type {
     UpdateSandboxProviderRequest,
     SandboxCatalogServer,
     CatalogServer,
+    AgentDetail,
+    CodeSnippetSampleCode,
+    CodeSnippet,
+    SessionListMetrics,
+    SessionListEntry,
+    ListSessionEventsParams,
+    AgentSessionsServer,
     AgentUIServerPort,
     AgentUIServer,
 } from "./types.js";

package/src/server/types.ts

@@ -132,6 +132,7 @@ export interface AgentSpec<
   config?: TConfig;
   instructions?: string;
   variables?: Record<string, string>;
+  description?: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -179,10 +180,12 @@ export type PageParams = {
 };
 
 export 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;
 }
 
 export type PreviousTurnIdInput = "auto" | "none" | string;
@@ -228,11 +231,26 @@ export type TurnInputItem =
 
 export 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.
+ */
+export interface TurnDoneMetrics {
+  totalInputTokens: number;
+  totalOutputTokens: number;
+  totalTokens: number;
+  totalCacheReadTokens: number;
+  totalCacheWriteTokens: number;
+  totalReasoningTokens: number;
+}
+
 export type TurnStateDone = {
   status: "done";
   output?: unknown;
   requiredActions?: ActionRequiredEvent[];
   completedAt: string;
+  /** Present when the host reports per-turn token totals. */
+  metrics?: TurnDoneMetrics;
 };
 
 export type TurnStateCancelled = {
@@ -352,6 +370,8 @@ export interface SaveAgentRequest<TSpec extends AgentSpec = AgentSpec> {
 export 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;
 }
@@ -775,20 +795,129 @@ export interface CatalogServer<
   sandboxCatalog?: TSandboxCatalog;
 }
 
+// ---------------------------------------------------------------------------
+// AgentSessions — optional agent-detail shell (Overview + sessions under agent)
+// ---------------------------------------------------------------------------
+
+/**
+ * Published agent identity + spec for the agent-detail Overview (read-only).
+ * Host widens `TSpec` (and may extend this DTO) for mounts / config / extras.
+ */
+export 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. */
+export interface CodeSnippetSampleCode {
+  stream: string;
+  nonStream: string;
+}
+
+/**
+ * One language row for Use In Code.
+ * Host maps wire `sample_code` / `non_stream` → camelCase here.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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). */
+export interface ListSessionEventsParams extends Pick<PageParams, "limit" | "pageToken"> {
+  sessionId: string;
+}
+
 /**
- * Composed host port: chat + builder + optional settings catalog.
+ * 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`.
+ */
+export 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`.
  */
 export type AgentUIServerPort<
   TChat extends AgentChatServer = AgentChatServer,
   TBuilder extends AgentBuilderServer = AgentBuilderServer,
   TCatalog extends CatalogServer = CatalogServer,
-> = TChat & TBuilder & { catalog?: TCatalog };
+  TSessions extends AgentSessionsServer = AgentSessionsServer,
+> = TChat & TBuilder & { catalog?: TCatalog; sessions?: TSessions };
 
 /** Host-facing alias used by trueforge-ui. */
 export type AgentUIServer = AgentUIServerPort;