Skip to content

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

feat: support deep-linking for agents library (#946)

harshil-20967cc39c2537e6
diff --git a/.changeset/library-agent-name-deep-link.md b/.changeset/library-agent-name-deep-link.md
new file mode 100644
index 000000000..e2dd558cf
--- /dev/null
+++ b/.changeset/library-agent-name-deep-link.md
@@ -0,0 +1,5 @@
+---
+'@truefoundry/trueforge-ui': patch
+---
+
+Support deep-linking the agents library with `?agent_name=` to seed and sync the search box.
diff --git a/packages/trueforge-ui/src/atoms/AgentsLibrary.tsx b/packages/trueforge-ui/src/atoms/AgentsLibrary.tsx
index 436e07639..38693a7d0 100644
--- a/packages/trueforge-ui/src/atoms/AgentsLibrary.tsx
+++ b/packages/trueforge-ui/src/atoms/AgentsLibrary.tsx
@@ -1,6 +1,6 @@
'use client';
-import { useCallback, useEffect, useState } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
import { useResourcePermissions } from '../hooks/useResourcePermissions.js';
import { useSessionShareSearch } from '../hooks/useSessionShareSearch.js';
@@ -11,6 +11,7 @@ import { libraryAgentId, useShellMode } from '../server/ShellModeContext.js';
import type { AgentLibraryEntry, AgentSpec, Schedule } from '../server/types.js';
import { useSlot } from '../theme/SlotsProvider.js';
import { hasCreatedBySubject } from '../utils/createdBySubject.js';
+import { readLibraryShareSearch, replaceLibraryShareSearch } from '../utils/libraryShareUrl.js';
import { replaceScheduleShareSearch } from '../utils/scheduleShareUrl.js';
import { AgentOverflowMenu } from './AgentOverflowMenu.js';
import { CreatedByCell } from './CreatedByCell.js';
@@ -353,8 +354,9 @@ export function AgentsLibrary({ onSelectAgent }: AgentsLibraryProps) {
const sessionsServer = useOptionalAgentSessionsServer();
const scheduleServer = useOptionalScheduleServer();
const SlottedAgentLibraryRow = useSlot('AgentLibraryRow');
- const [query, setQuery] = useState('');
+ const [query, setQuery] = useState(() => readLibraryShareSearch(window.location.search).agentName ?? '');
const [scheduleByAgent, setScheduleByAgent] = useState<Map<string, AgentScheduleSummary> | null>(null);
+ const skipNextLibraryShareSyncRef = useRef(false);
const open = shell.libraryOpen;
const canMutate = shell.isComposerEnabled === true;
@@ -364,9 +366,26 @@ export function AgentsLibrary({ onSelectAgent }: AgentsLibraryProps) {
const canOpenAgentSchedules = showSchedulesColumn && canOpenAgentDetails;
useEffect(() => {
- if (!open) setQuery('');
+ if (!open) {
+ setQuery('');
+ return;
+ }
+ // Re-seed when a stay-mounted library reopens; skip one sync so we don't wipe the URL.
+ skipNextLibraryShareSyncRef.current = true;
+ setQuery(readLibraryShareSearch(window.location.search).agentName ?? '');
}, [open]);
+ useEffect(() => {
+ if (!open) return;
+ if (skipNextLibraryShareSyncRef.current) {
+ skipNextLibraryShareSyncRef.current = false;
+ return;
+ }
+ replaceLibraryShareSearch({
+ agentName: query.trim().length === 0 ? null : query,
+ });
+ }, [open, query]);
+
const closeLibrary = useCallback(() => {
shell.setLibraryOpen(false);
setQuery('');
diff --git a/packages/trueforge-ui/src/routing/paths.ts b/packages/trueforge-ui/src/routing/paths.ts
index 32397c291..0c4b9409f 100644
--- a/packages/trueforge-ui/src/routing/paths.ts
+++ b/packages/trueforge-ui/src/routing/paths.ts
@@ -1,3 +1,4 @@
+import { clearLibraryShareSearch } from '../utils/libraryShareUrl.js';
import {
clearScheduleShareSearch,
readScheduleShareSearch,
@@ -156,6 +157,17 @@ export function sanitizeSearchForPlace(place: RoutePlace, search: string): strin
if (place.type === 'sessionsBrowser') {
writeSessionShareSearch(params, { tab: null });
clearScheduleShareSearch(params);
+ clearLibraryShareSearch(params);
+ } else if (place.type === 'library') {
+ writeSessionShareSearch(params, {
+ sessionId: null,
+ agentId: null,
+ tab: null,
+ view: null,
+ timeRange: null,
+ });
+ clearScheduleShareSearch(params);
+ // Keep `agent_name` — owned by the library place.
} else if (place.type === 'libraryAgent') {
const share = readSessionShareSearch(search);
const scheduleShare = readScheduleShareSearch(search);
@@ -165,6 +177,7 @@ export function sanitizeSearchForPlace(place: RoutePlace, search: string): strin
...(share.sessionId != null && share.agentId !== place.agentId ? { sessionId: null, agentId: null } : {}),
});
clearScheduleShareSearch(params);
+ clearLibraryShareSearch(params);
if (share.tab === 'schedules') {
writeScheduleShareSearch(params, {
status: scheduleShare.status,
@@ -180,6 +193,7 @@ export function sanitizeSearchForPlace(place: RoutePlace, search: string): strin
view: null,
timeRange: null,
});
+ clearLibraryShareSearch(params);
// Keep `agent` / `status` / `q` — owned by the schedules place.
} else {
writeSessionShareSearch(params, {
@@ -190,6 +204,7 @@ export function sanitizeSearchForPlace(place: RoutePlace, search: string): strin
timeRange: null,
});
clearScheduleShareSearch(params);
+ clearLibraryShareSearch(params);
}
const next = params.toString();
return next.length > 0 ? `?${next}` : '';
diff --git a/packages/trueforge-ui/src/utils/libraryShareUrl.ts b/packages/trueforge-ui/src/utils/libraryShareUrl.ts
new file mode 100644
index 000000000..a49116406
--- /dev/null
+++ b/packages/trueforge-ui/src/utils/libraryShareUrl.ts
@@ -0,0 +1,41 @@
+export const LIBRARY_AGENT_NAME_QUERY = 'agent_name';
+
+export const LIBRARY_SHARE_CHANGE_EVENT = 'trueforge-library-share';
+
+export type LibraryShareSearch = {
+ /** Agent name search; `null` when empty. */
+ agentName: string | null;
+};
+
+export type LibraryShareWrite = {
+ agentName?: string | null;
+};
+
+function nonEmpty(value: string | null): string | null {
+ return value != null && value.length > 0 ? value : null;
+}
+
+export function readLibraryShareSearch(search: string): LibraryShareSearch {
+ const params = new URLSearchParams(search.startsWith('?') ? search.slice(1) : search);
+ return {
+ agentName: nonEmpty(params.get(LIBRARY_AGENT_NAME_QUERY)),
+ };
+}
+
+export function writeLibraryShareSearch(params: URLSearchParams, next: LibraryShareWrite): void {
+ if (next.agentName === null) params.delete(LIBRARY_AGENT_NAME_QUERY);
+ else if (next.agentName != null) params.set(LIBRARY_AGENT_NAME_QUERY, next.agentName);
+}
+
+/** Drop library-owned query keys (used when leaving the library place). */
+export function clearLibraryShareSearch(params: URLSearchParams): void {
+ params.delete(LIBRARY_AGENT_NAME_QUERY);
+}
+
+export function replaceLibraryShareSearch(next: LibraryShareWrite): string {
+ const url = new URL(window.location.href);
+ writeLibraryShareSearch(url.searchParams, next);
+ window.history.replaceState(window.history.state, '', url);
+ window.dispatchEvent(new Event(LIBRARY_SHARE_CHANGE_EVENT));
+ return url.search;
+}
diff --git a/packages/trueforge-ui/test/atoms/AgentsLibrary.test.tsx b/packages/trueforge-ui/test/atoms/AgentsLibrary.test.tsx
index ad7c5999c..d1c411746 100644
--- a/packages/trueforge-ui/test/atoms/AgentsLibrary.test.tsx
+++ b/packages/trueforge-ui/test/atoms/AgentsLibrary.test.tsx
@@ -1,6 +1,7 @@
// @vitest-environment jsdom
import { fireEvent, render, screen, waitFor, within } from '@testing-library/react';
import type { ReactNode } from 'react';
+import { useEffect } from 'react';
import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
import { AgentsLibrary } from '@/atoms/AgentsLibrary.js';
@@ -482,6 +483,41 @@ describe('AgentsLibrary', () => {
expect(screen.queryByText('Build one in a chat, then save it as an agent.')).not.toBeInTheDocument();
});
+ it('seeds search from agent_name on first paint and keeps the URL in sync', async () => {
+ window.history.replaceState(null, '', '/library?agent_name=ask-ai-clone&theme=dark');
+ const searchAgents = vi.fn(async ({ query }: { query?: string } = {}) => ({
+ data: query === 'ask-ai-clone' ? [{ name: 'ask-ai-clone', agentId: 'agent-clone' }] : [],
+ }));
+ const server = createMockAgentUIServer({ searchAgents });
+
+ function DeepLinkLibrary() {
+ const shell = useShellMode();
+ useEffect(() => {
+ shell.setLibraryOpen(true);
+ }, [shell]);
+ if (!shell.libraryOpen) return null;
+ return <AgentsLibrary />;
+ }
+
+ renderLibrary(<DeepLinkLibrary />, { server });
+
+ expect(await screen.findByPlaceholderText('Search agents')).toHaveValue('ask-ai-clone');
+ expect(new URL(window.location.href).searchParams.get('agent_name')).toBe('ask-ai-clone');
+ await waitFor(() => {
+ expect(searchAgents).toHaveBeenCalled();
+ });
+ // First enabled fetch must already use the deep-link name (no unfiltered preamble).
+ expect(searchAgents.mock.calls[0]?.[0]).toEqual(expect.objectContaining({ query: 'ask-ai-clone' }));
+ expect(await screen.findByRole('button', { name: 'Try agent ask-ai-clone' })).toBeInTheDocument();
+ expect(new URL(window.location.href).searchParams.get('theme')).toBe('dark');
+
+ fireEvent.change(screen.getByPlaceholderText('Search agents'), { target: { value: '' } });
+ await waitFor(() => {
+ expect(new URL(window.location.href).searchParams.get('agent_name')).toBeNull();
+ });
+ expect(new URL(window.location.href).searchParams.get('theme')).toBe('dark');
+ });
+
it('closes via Escape', () => {
renderLibrary(<LibraryHarness />);
diff --git a/packages/trueforge-ui/test/routing/paths.test.ts b/packages/trueforge-ui/test/routing/paths.test.ts
index c317bb34d..b09f27792 100644
--- a/packages/trueforge-ui/test/routing/paths.test.ts
+++ b/packages/trueforge-ui/test/routing/paths.test.ts
@@ -139,6 +139,16 @@ describe('sanitizeSearchForPlace', () => {
expect(sanitizeSearchForPlace({ type: 'library' }, scheduleSearch)).toBe('?theme=dark');
});
+ it('keeps library agent_name on the library place and clears it elsewhere', () => {
+ const librarySearch = '?theme=dark&agent_name=ask-ai-clone&sessionId=sess-1&agentId=agent-1&q=digest';
+ expect(sanitizeSearchForPlace({ type: 'library' }, librarySearch)).toBe('?theme=dark&agent_name=ask-ai-clone');
+ expect(sanitizeSearchForPlace({ type: 'root' }, librarySearch)).toBe('?theme=dark');
+ expect(sanitizeSearchForPlace({ type: 'schedules' }, librarySearch)).toBe('?theme=dark&q=digest');
+ expect(sanitizeSearchForPlace({ type: 'libraryAgent', agentId: 'agent-1' }, librarySearch)).toBe(
+ '?theme=dark&sessionId=sess-1&agentId=agent-1',
+ );
+ });
+
it('keeps embedded schedule state on an agent Schedules tab', () => {
const search = '?theme=dark&agentId=agent-1&tab=schedules&agent=stale&status=paused&q=digest&isNew=true';
expect(sanitizeSearchForPlace({ type: 'libraryAgent', agentId: 'agent-1' }, search)).toBe(
diff --git a/packages/trueforge-ui/test/utils/libraryShareUrl.test.ts b/packages/trueforge-ui/test/utils/libraryShareUrl.test.ts
new file mode 100644
index 000000000..54a9a26b3
--- /dev/null
+++ b/packages/trueforge-ui/test/utils/libraryShareUrl.test.ts
@@ -0,0 +1,44 @@
+import {
+ clearLibraryShareSearch,
+ readLibraryShareSearch,
+ replaceLibraryShareSearch,
+ writeLibraryShareSearch,
+} from '@/utils/libraryShareUrl.js';
+
+describe('libraryShareUrl', () => {
+ it('reads agent_name from the search string', () => {
+ expect(readLibraryShareSearch('?agent_name=ask-ai-clone&theme=dark')).toEqual({
+ agentName: 'ask-ai-clone',
+ });
+ expect(readLibraryShareSearch('?agent_name=&theme=dark')).toEqual({
+ agentName: null,
+ });
+ expect(readLibraryShareSearch('?theme=dark')).toEqual({
+ agentName: null,
+ });
+ });
+
+ it('writes and clears library-owned keys without touching host keys', () => {
+ const params = new URLSearchParams('theme=dark&agent_name=old');
+ writeLibraryShareSearch(params, { agentName: 'ask-ai-clone' });
+ expect(params.toString()).toBe('theme=dark&agent_name=ask-ai-clone');
+
+ writeLibraryShareSearch(params, { agentName: null });
+ expect(params.toString()).toBe('theme=dark');
+
+ writeLibraryShareSearch(params, { agentName: 'again' });
+ clearLibraryShareSearch(params);
+ expect(params.toString()).toBe('theme=dark');
+ });
+
+ it('replaceLibraryShareSearch updates the address bar', () => {
+ window.history.replaceState(null, '', '/library?theme=dark');
+ replaceLibraryShareSearch({ agentName: 'ask-ai-clone' });
+ expect(new URL(window.location.href).searchParams.get('agent_name')).toBe('ask-ai-clone');
+ expect(new URL(window.location.href).searchParams.get('theme')).toBe('dark');
+
+ replaceLibraryShareSearch({ agentName: null });
+ expect(new URL(window.location.href).searchParams.get('agent_name')).toBeNull();
+ expect(new URL(window.location.href).searchParams.get('theme')).toBe('dark');
+ });
+});