Skip to content

The open-source agent harness - the runtime layer that turns an LLM into a working agent.

feat: display metadata to session details (#909)

harshil-20966d9154154b45
diff --git a/.changeset/session-metadata-header-action.md b/.changeset/session-metadata-header-action.md
new file mode 100644
index 000000000..83b1e3ad1
--- /dev/null
+++ b/.changeset/session-metadata-header-action.md
@@ -0,0 +1,6 @@
+---
+"@truefoundry/trueforge-assistant-ui-runtime": patch
+"@truefoundry/trueforge-ui": patch
+---
+
+Display session metadata at the top of the session detail header
diff --git a/packages/assistant-ui-runtime/src/server/types.ts b/packages/assistant-ui-runtime/src/server/types.ts
index 46f35621e..80bf150e6 100644
--- a/packages/assistant-ui-runtime/src/server/types.ts
+++ b/packages/assistant-ui-runtime/src/server/types.ts
@@ -187,6 +187,8 @@ export interface Session<TSpec extends AgentSpec = AgentSpec> {
metrics?: SessionListMetrics;
createdAt: string;
updatedAt: string;
+ /** Arbitrary caller key-value metadata strings. */
+ metadata?: Record<string, string>;
}
export interface CreateSessionRequest<TSpec extends AgentSpec = AgentSpec> {
@@ -934,6 +936,8 @@ export interface SessionListEntry<TSpec extends AgentSpec = AgentSpec> {
agentName?: string | null;
/** Present when bound to a mutable / draft agent spec. */
agentSpec?: TSpec;
+ /** Arbitrary caller key-value metadata strings. */
+ metadata?: Record<string, string>;
}
/** Params for `AgentSessionsServer.listSessionEvents` (session event timeline). */
diff --git a/packages/trueforge-ui/src/atoms/agent-details/AgentSessionDetailHeader.tsx b/packages/trueforge-ui/src/atoms/agent-details/AgentSessionDetailHeader.tsx
index b3f75cc16..1cbd1c06d 100644
--- a/packages/trueforge-ui/src/atoms/agent-details/AgentSessionDetailHeader.tsx
+++ b/packages/trueforge-ui/src/atoms/agent-details/AgentSessionDetailHeader.tsx
@@ -22,6 +22,7 @@ export function AgentSessionDetailHeader({
title,
sessionId,
onClose,
+ metadata,
resumeHref,
onResume,
resumeLabel,
@@ -30,61 +31,83 @@ export function AgentSessionDetailHeader({
}: AgentSessionDetailHeaderProps) {
const PermissionGuard = useSlot('PermissionGuard');
const ShareSessionDialog = useSlot('ShareSessionDialog');
+ const hasMetadata = metadata != null && Object.keys(metadata).length > 0;
return (
- <div className="flex shrink-0 items-center gap-3 border-b border-border p-3">
- <div className="flex min-w-0 flex-1 items-center gap-1.5 pb-0.5">
- <h2 className="min-w-0 truncate text-sm font-semibold leading-none text-text-primary">{title}</h2>
- <code className="min-w-0 truncate font-mono text-xs leading-none text-text-secondary">{sessionId}</code>
- </div>
- {canShare ? (
- <ShareSessionDialog sessionId={sessionId} trigger={<SessionsShareTrigger />} />
- ) : (
- <PermissionGuard allowed={false}>
- <SessionsShareTrigger />
- </PermissionGuard>
- )}
- {resumeLabel != null && resumeHref != null && canResume ? (
- <a
- href={resumeHref}
- target="_blank"
- rel="noopener noreferrer"
- className={auiButtonClass({ variant: 'secondary', size: 'large' })}
- >
- {resumeLabel}
- <Icon name="square-arrow-out-up-right" className="shrink-0" />
- </a>
- ) : resumeLabel != null && resumeHref != null ? (
- <PermissionGuard allowed={false}>
- <Button.Secondary type="button" size="large">
- {resumeLabel}
- <Icon name="square-arrow-out-up-right" className="shrink-0" />
- </Button.Secondary>
- </PermissionGuard>
- ) : resumeLabel != null && onResume != null ? (
- <PermissionGuard allowed={canResume}>
- <Button.Secondary
- type="button"
- size="large"
- onClick={() => {
- if (canResume) onResume();
- }}
+ <div className="flex shrink-0 flex-col border-b border-border">
+ <div className="flex shrink-0 items-center gap-3 p-3">
+ <div className="flex min-w-0 flex-1 items-center gap-1.5 pb-0.5">
+ <h2 className="min-w-0 truncate text-sm font-semibold leading-none text-text-primary">{title}</h2>
+ <code className="min-w-0 truncate font-mono text-xs leading-none text-text-secondary">{sessionId}</code>
+ </div>
+ {canShare ? (
+ <ShareSessionDialog sessionId={sessionId} trigger={<SessionsShareTrigger />} />
+ ) : (
+ <PermissionGuard allowed={false}>
+ <SessionsShareTrigger />
+ </PermissionGuard>
+ )}
+ {resumeLabel != null && resumeHref != null && canResume ? (
+ <a
+ href={resumeHref}
+ target="_blank"
+ rel="noopener noreferrer"
+ className={auiButtonClass({ variant: 'secondary', size: 'large' })}
>
{resumeLabel}
- </Button.Secondary>
- </PermissionGuard>
+ <Icon name="square-arrow-out-up-right" className="shrink-0" />
+ </a>
+ ) : resumeLabel != null && resumeHref != null ? (
+ <PermissionGuard allowed={false}>
+ <Button.Secondary type="button" size="large">
+ {resumeLabel}
+ <Icon name="square-arrow-out-up-right" className="shrink-0" />
+ </Button.Secondary>
+ </PermissionGuard>
+ ) : resumeLabel != null && onResume != null ? (
+ <PermissionGuard allowed={canResume}>
+ <Button.Secondary
+ type="button"
+ size="large"
+ onClick={() => {
+ if (canResume) onResume();
+ }}
+ >
+ {resumeLabel}
+ </Button.Secondary>
+ </PermissionGuard>
+ ) : null}
+ <button
+ type="button"
+ aria-label="Close session details"
+ className={cn(
+ 'inline-flex size-8 shrink-0 items-center justify-center rounded-md text-text-secondary',
+ 'hover:bg-ghost-button-hover hover:text-text-primary',
+ )}
+ onClick={onClose}
+ >
+ <Icon name="xmark" className="size-4" />
+ </button>
+ </div>
+ {hasMetadata ? (
+ <div
+ className="flex flex-wrap items-center gap-1.5 border-t border-border px-3 py-2"
+ data-slot="session-metadata-tags"
+ >
+ {Object.entries(metadata).map(([key, value]) => (
+ <div
+ key={key}
+ className="inline-flex max-w-full items-center gap-1.5 rounded-full border border-border bg-secondary-bg/40 px-2.5 py-1 text-xs"
+ >
+ <Icon name="tag" className="size-3 shrink-0 text-text-secondary" />
+ <span className="shrink-0 font-mono text-text-secondary">{key}</span>
+ <span className="truncate font-mono font-medium text-text-primary" title={value}>
+ {value}
+ </span>
+ </div>
+ ))}
+ </div>
) : null}
- <button
- type="button"
- aria-label="Close session details"
- className={cn(
- 'inline-flex size-8 shrink-0 items-center justify-center rounded-md text-text-secondary',
- 'hover:bg-ghost-button-hover hover:text-text-primary',
- )}
- onClick={onClose}
- >
- <Icon name="xmark" className="size-4" />
- </button>
</div>
);
}
diff --git a/packages/trueforge-ui/src/atoms/agent-details/AgentSessions.tsx b/packages/trueforge-ui/src/atoms/agent-details/AgentSessions.tsx
index 8fe911106..782b3b34e 100644
--- a/packages/trueforge-ui/src/atoms/agent-details/AgentSessions.tsx
+++ b/packages/trueforge-ui/src/atoms/agent-details/AgentSessions.tsx
@@ -315,7 +315,7 @@ export function AgentSessions({
resumeHref != null ? { resumeHref, resumeLabel } : shell != null ? { onResume: handleResume, resumeLabel } : {};
const detailPanel = (
- <section className="flex h-full min-w-0 flex-col bg-primary-bg">
+ <section className="isolate flex h-full min-w-0 flex-col bg-primary-bg">
{selectedSessionId == null ? (
<div className="flex flex-1 items-center justify-center px-6 text-sm text-text-secondary">
Select a session to view details
@@ -329,6 +329,7 @@ export function AgentSessions({
<AgentSessionDetailHeader
title={selectedTitle}
sessionId={selectedSessionId}
+ metadata={detailSession?.metadata ?? selectedEntry?.metadata}
onClose={clearSelectedSession}
canResume={canResume}
canShare={canResume}
@@ -441,7 +442,7 @@ export function AgentSessions({
<Separator
id="agent-sessions-resizer"
aria-label="Resize session list"
- className="group/resizer relative z-10 w-0 cursor-col-resize focus-visible:outline-none"
+ className="group/resizer relative z-30 w-0 cursor-col-resize focus-visible:outline-none"
>
<div aria-hidden className="absolute inset-y-0 -left-1.25 w-2.75" />
<div aria-hidden className="absolute inset-y-0 left-0 w-px bg-border transition-colors" />
diff --git a/packages/trueforge-ui/src/atoms/agent-details/types.ts b/packages/trueforge-ui/src/atoms/agent-details/types.ts
index 6c24f7c8d..768801438 100644
--- a/packages/trueforge-ui/src/atoms/agent-details/types.ts
+++ b/packages/trueforge-ui/src/atoms/agent-details/types.ts
@@ -52,6 +52,8 @@ export type AgentSessionDetailHeaderProps = {
title: string;
sessionId: string;
onClose: () => void;
+ /** Session metadata key-value pairs. */
+ metadata?: Record<string, string>;
/**
* When set with `resumeLabel`, shows Resume Chat / Resume Agent building as a
* new-tab link (session deep link). Preferred over `onResume` when both are set.
diff --git a/packages/trueforge-ui/src/icons/IconRegistry.tsx b/packages/trueforge-ui/src/icons/IconRegistry.tsx
index 31bbf86cd..8253770e0 100644
--- a/packages/trueforge-ui/src/icons/IconRegistry.tsx
+++ b/packages/trueforge-ui/src/icons/IconRegistry.tsx
@@ -73,6 +73,7 @@ import {
SquareArrowOutUpRight,
SquarePen,
Sun,
+ Tag,
Terminal,
Trash2,
TriangleAlert,
@@ -201,6 +202,7 @@ const defaults: Record<string, IconEntry> = {
'user-cog': UserCog,
users: Users,
lightbulb: Lightbulb,
+ tag: Tag,
link: Link2,
wrench: Wrench,
cpu: Cpu,
diff --git a/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/agentSessionsServer.ts b/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/agentSessionsServer.ts
index 2d40f6b83..91e0f083f 100644
--- a/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/agentSessionsServer.ts
+++ b/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/agentSessionsServer.ts
@@ -38,6 +38,7 @@ function toSessionListEntry(session: TrueForgeApi.Session): HarnessSessionListEn
...(session.agent.type === 'reference' && session.agent.name !== null ? { agentName: session.agent.name } : {}),
...(session.agent.type === 'inline' ? { agentSpec: toUiAgentSpec(session.agent.spec) } : {}),
...(session.source?.type === 'schedule' ? { sourceType: session.source.type } : {}),
+ ...(session.metadata != null && Object.keys(session.metadata).length > 0 ? { metadata: session.metadata } : {}),
};
}
diff --git a/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/chatServer.ts b/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/chatServer.ts
index 5e6262398..c9f110902 100644
--- a/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/chatServer.ts
+++ b/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/chatServer.ts
@@ -101,6 +101,7 @@ function toUiSession(session: TrueForgeApi.Session): HarnessUiSession {
// unlabelled; `isMutable` alone keeps them out of the composer.
...(session.agent.type === 'reference' && session.agent.name !== null ? { agentName: session.agent.name } : {}),
...(session.agent.type === 'inline' ? { agentSpec: toUiAgentSpec(session.agent.spec) } : {}),
+ ...(session.metadata != null && Object.keys(session.metadata).length > 0 ? { metadata: session.metadata } : {}),
};
}
diff --git a/packages/trueforge-ui/test/atoms/AgentSessionDetailHeader.test.tsx b/packages/trueforge-ui/test/atoms/AgentSessionDetailHeader.test.tsx
index 197175c55..080441cc9 100644
--- a/packages/trueforge-ui/test/atoms/AgentSessionDetailHeader.test.tsx
+++ b/packages/trueforge-ui/test/atoms/AgentSessionDetailHeader.test.tsx
@@ -103,4 +103,39 @@ describe('AgentSessionDetailHeader', () => {
expect(screen.getByRole('button', { name: 'Resume Chat' })).toBeDisabled();
expect(screen.queryByRole('link', { name: /Resume Chat/i })).not.toBeInTheDocument();
});
+
+ it('renders session metadata tags directly in the header when metadata is provided', () => {
+ const { container } = render(
+ <AgentSessionDetailHeader
+ title="Help me find more details"
+ sessionId="sess-1"
+ onClose={() => undefined}
+ metadata={{ agentName: 'ask-ai-devtest', tenantName: 'truefoundry' }}
+ />,
+ );
+
+ const metadataContainer = container.querySelector('[data-slot="session-metadata-tags"]');
+ expect(metadataContainer).toBeInTheDocument();
+ expect(screen.getByText('agentName')).toBeInTheDocument();
+ expect(screen.getByText('ask-ai-devtest')).toBeInTheDocument();
+ expect(screen.getByText('tenantName')).toBeInTheDocument();
+ expect(screen.getByText('truefoundry')).toBeInTheDocument();
+ });
+
+ it('does not render session metadata section when metadata is empty or undefined', () => {
+ const { container, rerender } = render(
+ <AgentSessionDetailHeader
+ title="Help me find more details"
+ sessionId="sess-1"
+ onClose={() => undefined}
+ metadata={{}}
+ />,
+ );
+ expect(container.querySelector('[data-slot="session-metadata-tags"]')).not.toBeInTheDocument();
+
+ rerender(
+ <AgentSessionDetailHeader title="Help me find more details" sessionId="sess-1" onClose={() => undefined} />,
+ );
+ expect(container.querySelector('[data-slot="session-metadata-tags"]')).not.toBeInTheDocument();
+ });
});
diff --git a/packages/trueforge-ui/test/atoms/SessionsPage.test.tsx b/packages/trueforge-ui/test/atoms/SessionsPage.test.tsx
index 66b4a2ca4..78de15a5a 100644
--- a/packages/trueforge-ui/test/atoms/SessionsPage.test.tsx
+++ b/packages/trueforge-ui/test/atoms/SessionsPage.test.tsx
@@ -229,6 +229,27 @@ describe('SessionsPage', () => {
expect(getSession).toHaveBeenCalledWith({ sessionId: 'sess-1' });
});
+ it('renders session metadata tags in detail header when session has metadata', async () => {
+ window.history.replaceState(null, '', '/?view=sessions&sessionId=sess-1');
+ const getSession = vi.fn(async (): Promise<Session> => ({
+ id: 'sess-1',
+ title: 'Session with metadata',
+ isMutable: false,
+ createdAt: namedRow.createdAt,
+ updatedAt: namedRow.updatedAt,
+ metadata: { env: 'production', cluster: 'us-west-2' },
+ }));
+ renderPage({
+ listSessions: vi.fn(async () => ({ data: [] })),
+ getSession,
+ });
+
+ expect(await screen.findByText('env')).toBeInTheDocument();
+ expect(screen.getByText('production')).toBeInTheDocument();
+ expect(screen.getByText('cluster')).toBeInTheDocument();
+ expect(screen.getByText('us-west-2')).toBeInTheDocument();
+ });
+
it('toasts and keeps the inline failure when a non-share detail load is forbidden', async () => {
window.history.replaceState(null, '', '/?view=sessions&sessionId=sess-1');
const forbidden = Object.assign(new Error('Only the session creator can access this session'), {