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.mdnew file mode 100644index 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.tsxindex 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.tsindex 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): strinif (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): strinview: 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): strintimeRange: 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.tsnew file mode 100644index 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.tsxindex 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 jsdomimport { 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.tsindex 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.tsnew file mode 100644index 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');+ });+});