Skip to content

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

Fix: Use public base URL in Use In Code SDK snippets (#653)

Bhavesh Patela9430bd7fdef
diff --git a/.changeset/fix-code-snippets-public-base-url.md b/.changeset/fix-code-snippets-public-base-url.md
new file mode 100644
index 000000000..51e912549
--- /dev/null
+++ b/.changeset/fix-code-snippets-public-base-url.md
@@ -0,0 +1,6 @@
+---
+"@truefoundry/trueforge": patch
+"@truefoundry/trueforge-ui": patch
+---
+
+Accept optional `base_url` on agent code-snippets (FE public host); fall back to request origin + `PUBLIC_BASE_URL` path.
diff --git a/.github/fern/openapi/openapi.json b/.github/fern/openapi/openapi.json
index 5844a788e..b2e500f11 100644
--- a/.github/fern/openapi/openapi.json
+++ b/.github/fern/openapi/openapi.json
@@ -98,7 +98,7 @@
"additionalProperties": false,
"properties": {
"base_url": {
- "description": "Origin to pass as the TrueForge SDK `baseUrl`.",
+ "description": "Public base URL for the TrueForge SDK `baseUrl`.",
"format": "uri",
"type": "string"
},
@@ -5798,6 +5798,17 @@
"minLength": 1,
"type": "string"
}
+ },
+ {
+ "description": "Public SDK base URL from the browser. When omitted, derived from the request origin and PUBLIC_BASE_URL.",
+ "in": "query",
+ "name": "base_url",
+ "required": false,
+ "schema": {
+ "description": "Public SDK base URL from the browser. When omitted, derived from the request origin and PUBLIC_BASE_URL.",
+ "format": "uri",
+ "type": "string"
+ }
}
],
"responses": {
@@ -5809,7 +5820,7 @@
}
}
},
- "description": "TypeScript SDK samples and the origin to use as `baseUrl`."
+ "description": "TypeScript SDK samples."
},
"404": {
"content": {
diff --git a/docs/openapi.json b/docs/openapi.json
index 5844a788e..b2e500f11 100644
--- a/docs/openapi.json
+++ b/docs/openapi.json
@@ -98,7 +98,7 @@
"additionalProperties": false,
"properties": {
"base_url": {
- "description": "Origin to pass as the TrueForge SDK `baseUrl`.",
+ "description": "Public base URL for the TrueForge SDK `baseUrl`.",
"format": "uri",
"type": "string"
},
@@ -5798,6 +5798,17 @@
"minLength": 1,
"type": "string"
}
+ },
+ {
+ "description": "Public SDK base URL from the browser. When omitted, derived from the request origin and PUBLIC_BASE_URL.",
+ "in": "query",
+ "name": "base_url",
+ "required": false,
+ "schema": {
+ "description": "Public SDK base URL from the browser. When omitted, derived from the request origin and PUBLIC_BASE_URL.",
+ "format": "uri",
+ "type": "string"
+ }
}
],
"responses": {
@@ -5809,7 +5820,7 @@
}
}
},
- "description": "TypeScript SDK samples and the origin to use as `baseUrl`."
+ "description": "TypeScript SDK samples."
},
"404": {
"content": {
diff --git a/packages/trueforge-sdk/reference.md b/packages/trueforge-sdk/reference.md
index 43d993f88..d35811b24 100644
--- a/packages/trueforge-sdk/reference.md
+++ b/packages/trueforge-sdk/reference.md
@@ -2965,7 +2965,7 @@ await client.internal.sessions.getOrCreateByExternalId({
</details>
## Internal Agents
-<details><summary><code>client.internal.agents.<a href="/src/api/resources/internal/resources/agents/client/Client.ts">getCodeSnippets</a>(agent_id) -> TrueForge.GetAgentCodeSnippetsResponse</code></summary>
+<details><summary><code>client.internal.agents.<a href="/src/api/resources/internal/resources/agents/client/Client.ts">getCodeSnippets</a>(agent_id, { ...params }) -> TrueForge.GetAgentCodeSnippetsResponse</code></summary>
<dl>
<dd>
@@ -3016,6 +3016,14 @@ await client.internal.agents.getCodeSnippets("agent_id");
<dl>
<dd>
+**request:** `TrueForge.internal.GetCodeSnippetsAgentsRequest`
+
+</dd>
+</dl>
+
+<dl>
+<dd>
+
**requestOptions:** `AgentsClient.RequestOptions`
</dd>
diff --git a/packages/trueforge-sdk/src/api/resources/internal/resources/agents/client/Client.ts b/packages/trueforge-sdk/src/api/resources/internal/resources/agents/client/Client.ts
index 08d8a7745..b3168d890 100644
--- a/packages/trueforge-sdk/src/api/resources/internal/resources/agents/client/Client.ts
+++ b/packages/trueforge-sdk/src/api/resources/internal/resources/agents/client/Client.ts
@@ -26,6 +26,7 @@ export class AgentsClient {
* TypeScript TrueForge SDK samples (stream and non-stream) for creating a session and turn against this agent.
*
* @param {string} agent_id - Immutable agent identifier.
+ * @param {TrueForge.internal.GetCodeSnippetsAgentsRequest} request
* @param {AgentsClient.RequestOptions} requestOptions - Request-specific configuration.
*
* @throws {@link TrueForge.NotFoundError}
@@ -37,15 +38,21 @@ export class AgentsClient {
*/
public getCodeSnippets(
agent_id: string,
+ request: TrueForge.internal.GetCodeSnippetsAgentsRequest = {},
requestOptions?: AgentsClient.RequestOptions,
): core.HttpResponsePromise<TrueForge.GetAgentCodeSnippetsResponse> {
- return core.HttpResponsePromise.fromPromise(this.__getCodeSnippets(agent_id, requestOptions));
+ return core.HttpResponsePromise.fromPromise(this.__getCodeSnippets(agent_id, request, requestOptions));
}
private async __getCodeSnippets(
agent_id: string,
+ request: TrueForge.internal.GetCodeSnippetsAgentsRequest = {},
requestOptions?: AgentsClient.RequestOptions,
): Promise<core.WithRawResponse<TrueForge.GetAgentCodeSnippetsResponse>> {
+ const { baseUrl } = request;
+ const _queryParams: Record<string, unknown> = {
+ base_url: baseUrl,
+ };
const _authRequest: core.AuthRequest = await this._options.authProvider.getAuthRequest();
const _headers: core.Fetcher.Args["headers"] = mergeHeaders(
_authRequest.headers,
@@ -60,7 +67,11 @@ export class AgentsClient {
),
method: "GET",
headers: _headers,
- queryString: core.url.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
+ queryString: core.url
+ .queryBuilder()
+ .addMany(_queryParams)
+ .mergeAdditional(requestOptions?.queryParams)
+ .build(),
timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1000,
maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
abortSignal: requestOptions?.abortSignal,
diff --git a/packages/trueforge-sdk/src/api/resources/internal/resources/agents/client/index.ts b/packages/trueforge-sdk/src/api/resources/internal/resources/agents/client/index.ts
index cb0ff5c3b..195f9aa8a 100644
--- a/packages/trueforge-sdk/src/api/resources/internal/resources/agents/client/index.ts
+++ b/packages/trueforge-sdk/src/api/resources/internal/resources/agents/client/index.ts
@@ -1 +1 @@
-export {};
+export * from "./requests/index.js";
diff --git a/packages/trueforge-sdk/src/api/resources/internal/resources/agents/client/requests/GetCodeSnippetsAgentsRequest.ts b/packages/trueforge-sdk/src/api/resources/internal/resources/agents/client/requests/GetCodeSnippetsAgentsRequest.ts
new file mode 100644
index 000000000..139efdb1a
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/resources/internal/resources/agents/client/requests/GetCodeSnippetsAgentsRequest.ts
@@ -0,0 +1,10 @@
+// This file was auto-generated by Fern from our API Definition.
+
+/**
+ * @example
+ * {}
+ */
+export interface GetCodeSnippetsAgentsRequest {
+ /** Public SDK base URL from the browser. When omitted, derived from the request origin and PUBLIC_BASE_URL. */
+ baseUrl?: string;
+}
diff --git a/packages/trueforge-sdk/src/api/resources/internal/resources/agents/client/requests/index.ts b/packages/trueforge-sdk/src/api/resources/internal/resources/agents/client/requests/index.ts
new file mode 100644
index 000000000..8dafa940b
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/resources/internal/resources/agents/client/requests/index.ts
@@ -0,0 +1 @@
+export type { GetCodeSnippetsAgentsRequest } from "./GetCodeSnippetsAgentsRequest.js";
diff --git a/packages/trueforge-sdk/src/api/resources/internal/resources/index.ts b/packages/trueforge-sdk/src/api/resources/internal/resources/index.ts
index d006bfdd8..18d24fb89 100644
--- a/packages/trueforge-sdk/src/api/resources/internal/resources/index.ts
+++ b/packages/trueforge-sdk/src/api/resources/internal/resources/index.ts
@@ -1,3 +1,4 @@
+export * from "./agents/client/requests/index.js";
export * as agents from "./agents/index.js";
export * from "./metrics/client/requests/index.js";
export * as metrics from "./metrics/index.js";
diff --git a/packages/trueforge-sdk/src/api/types/AgentCodeSnippets.ts b/packages/trueforge-sdk/src/api/types/AgentCodeSnippets.ts
index b86134ef0..bf525d9d6 100644
--- a/packages/trueforge-sdk/src/api/types/AgentCodeSnippets.ts
+++ b/packages/trueforge-sdk/src/api/types/AgentCodeSnippets.ts
@@ -3,7 +3,7 @@
import type * as TrueForge from "../index.js";
export interface AgentCodeSnippets {
- /** Origin to pass as the TrueForge SDK `baseUrl`. */
+ /** Public base URL for the TrueForge SDK `baseUrl`. */
baseUrl: string;
snippets: TrueForge.AgentCodeSnippet[];
}
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 748a3d783..db8a19d65 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
@@ -2,7 +2,12 @@ import type { TrueForge, TrueForgeApi } from '@truefoundry/trueforge-sdk';
import { readSessionIsCreateAgent } from '../../atoms/lib/sessionCreateAgent.js';
import type { AgentSessionsServer, SessionListEntry } from '../../server/types.js';
import { toListResult, toUiAgentSpec } from './chatServer.js';
-import { createTrueForgeClient, parseIsoDate, type CreateTrueForgeClientOptions } from './client.js';
+import {
+ createTrueForgeClient,
+ parseIsoDate,
+ resolveTrueForgeBaseUrl,
+ type CreateTrueForgeClientOptions,
+} from './client.js';
import { toUiEventItem } from './toUiTurnState.js';
import type { HarnessAgentSpec } from './types.js';
@@ -51,7 +56,11 @@ export function createHarnessAgentSessionsServer(
};
},
async getCodeSnippets({ agentId }) {
- const { data } = await client.internal.agents.getCodeSnippets(agentId);
+ const absoluteBaseUrl = resolveTrueForgeBaseUrl(options.baseUrl ?? '/');
+ const { data } = await client.internal.agents.getCodeSnippets(
+ agentId,
+ /^https?:\/\//i.test(absoluteBaseUrl) ? { baseUrl: absoluteBaseUrl } : undefined,
+ );
return data.snippets;
},
async listSessions(requestParams = {}) {
diff --git a/packages/trueforge-ui/test/plugins/trueforge-agent-server-adapter/agentSessionsServer.test.ts b/packages/trueforge-ui/test/plugins/trueforge-agent-server-adapter/agentSessionsServer.test.ts
index 17da68e81..10e7568a0 100644
--- a/packages/trueforge-ui/test/plugins/trueforge-agent-server-adapter/agentSessionsServer.test.ts
+++ b/packages/trueforge-ui/test/plugins/trueforge-agent-server-adapter/agentSessionsServer.test.ts
@@ -3,6 +3,7 @@ import assert from 'node:assert/strict';
import { describe, it, vi } from 'vitest';
import { createHarnessAgentSessionsServer } from '@/plugins/trueforge-agent-server-adapter/agentSessionsServer.js';
+import { resolveTrueForgeBaseUrl } from '@/plugins/trueforge-agent-server-adapter/client.js';
describe('createHarnessAgentSessionsServer', () => {
it('maps agent details and code snippets to the UI contract', async () => {
@@ -47,7 +48,7 @@ describe('createHarnessAgentSessionsServer', () => {
},
]);
assert.deepEqual(get.mock.calls[0], ['agent-1']);
- assert.deepEqual(getCodeSnippets.mock.calls[0], ['agent-1']);
+ assert.deepEqual(getCodeSnippets.mock.calls[0], ['agent-1', { baseUrl: resolveTrueForgeBaseUrl('/') }]);
});
it('maps listSessions and listSessionEvents onto the UI contract', async () => {
diff --git a/packages/trueforge/src/apis/agents.ts b/packages/trueforge/src/apis/agents.ts
index df7c611d0..80f3a5bcb 100644
--- a/packages/trueforge/src/apis/agents.ts
+++ b/packages/trueforge/src/apis/agents.ts
@@ -6,6 +6,7 @@ import type { AgentSpec } from '@truefoundry/trueforge-core/agent-session';
import type { Context } from 'hono';
import type { Authorizer } from '../auth/authorizer';
import { createdBySubjectFromRequestContext, type ResolveRequestContext } from '../auth/identity';
+import configuration from '../config';
import {
AgentExternalIdConflictError,
AgentNameConflictError,
@@ -145,11 +146,22 @@ export function createAgentsRouter<TTransaction>(deps: AgentsRouterDeps<TTransac
if (record === undefined) {
return c.json({ error: { message: `Agent not found: ${agentId}` } }, 404);
}
+ // Prefer FE-supplied public URL (avoids in-cluster Host). Else request origin + PUBLIC_BASE_URL path.
+ // e.g. origin https://sample.com + PUBLIC_BASE_URL https://example.com/trueforge
+ // → https://sample.com/trueforge
+ const requestedBaseUrl = c.req.valid('query').base_url;
+ const origin = new URL(c.req.url).origin;
+ let baseUrl = origin;
+ if (requestedBaseUrl) {
+ baseUrl = requestedBaseUrl;
+ } else if (configuration.PUBLIC_BASE_URL) {
+ baseUrl = new URL(new URL(configuration.PUBLIC_BASE_URL).pathname, origin).href;
+ }
return c.json(
{
data: buildAgentCodeSnippets({
agentName: record.name,
- baseUrl: new URL(c.req.url).origin,
+ baseUrl,
}),
},
200,
diff --git a/packages/trueforge/src/routes/agentRoutes.ts b/packages/trueforge/src/routes/agentRoutes.ts
index 113463292..998b88b58 100644
--- a/packages/trueforge/src/routes/agentRoutes.ts
+++ b/packages/trueforge/src/routes/agentRoutes.ts
@@ -6,6 +6,7 @@ import { createRoute, z } from '@hono/zod-openapi';
import {
CreateAgentRequestSchema,
DeleteAgentResponseSchema,
+ GetAgentCodeSnippetsRequestQuerySchema,
GetAgentCodeSnippetsResponseSchema,
GetAgentResponseSchema,
ListAgentsResponseSchema,
@@ -86,11 +87,12 @@ export const getAgentCodeSnippetsRoute = createRoute({
'x-excluded': true,
request: {
params: AgentIdParamsSchema,
+ query: GetAgentCodeSnippetsRequestQuerySchema,
},
responses: {
200: {
content: { 'application/json': { schema: GetAgentCodeSnippetsResponseSchema } },
- description: 'TypeScript SDK samples and the origin to use as `baseUrl`.',
+ description: 'TypeScript SDK samples.',
},
404: {
content: { 'application/json': { schema: RequestErrorResponseSchema } },
diff --git a/packages/trueforge/src/schemas/agent.ts b/packages/trueforge/src/schemas/agent.ts
index 8dc3f0068..84ba3be7c 100644
--- a/packages/trueforge/src/schemas/agent.ts
+++ b/packages/trueforge/src/schemas/agent.ts
@@ -62,7 +62,7 @@ export const AgentCodeSnippetSchema = z
export const AgentCodeSnippetsSchema = z
.object({
- base_url: z.url().describe('Origin to pass as the TrueForge SDK `baseUrl`.'),
+ base_url: z.url().describe('Public base URL for the TrueForge SDK `baseUrl`.'),
snippets: z.array(AgentCodeSnippetSchema),
})
.strict()
@@ -72,7 +72,20 @@ export const GetAgentCodeSnippetsResponseSchema = z
.object({ data: AgentCodeSnippetsSchema })
.openapi('GetAgentCodeSnippetsResponse');
+export const GetAgentCodeSnippetsRequestQuerySchema = z
+ .object({
+ base_url: z
+ .url()
+ .optional()
+ .describe(
+ 'Public SDK base URL from the browser. When omitted, derived from the request origin and PUBLIC_BASE_URL.',
+ ),
+ })
+ .strict()
+ .openapi('GetAgentCodeSnippetsRequestQuery');
+
export type CreateAgentRequest = z.infer<typeof CreateAgentRequestSchema>;
export type UpdateAgentRequest = z.infer<typeof UpdateAgentRequestSchema>;
export type Agent = z.infer<typeof AgentSchema>;
export type AgentCodeSnippets = z.infer<typeof AgentCodeSnippetsSchema>;
+export type GetAgentCodeSnippetsRequestQuery = z.infer<typeof GetAgentCodeSnippetsRequestQuerySchema>;
diff --git a/packages/trueforge/tests/unit/apis/agents.test.ts b/packages/trueforge/tests/unit/apis/agents.test.ts
index 43c08b50a..1c0f3b4cc 100644
--- a/packages/trueforge/tests/unit/apis/agents.test.ts
+++ b/packages/trueforge/tests/unit/apis/agents.test.ts
@@ -1,6 +1,7 @@
import { createAgentsRouter } from '../../../src/apis/agents';
import { TrueForgeAuthorizer, type AgentListAccess, type Authorizer } from '../../../src/auth/authorizer';
import { STANDALONE_REQUEST_CONTEXT } from '../../../src/auth/identity';
+import configuration from '../../../src/config';
import { migrateSqliteToLatest } from '../../../src/db/migrateSqlite';
import { SqliteAgentStore } from '../../../src/db/sqlite/agent-store/SqliteAgentStore';
import { createSqliteDb } from '../../../src/db/sqlite/client';
@@ -170,8 +171,20 @@ describe('agents router', () => {
const response = await router.request(`/${createdJson.data.id}/code-snippets`);
expect(response.status).toBe(200);
- const body = (await response.json()) as { data: { snippets: unknown[] } };
+ const body = (await response.json()) as { data: { base_url: string; snippets: unknown[] } };
+ expect(body.data.base_url).toBe(
+ configuration.PUBLIC_BASE_URL
+ ? new URL(new URL(configuration.PUBLIC_BASE_URL).pathname, 'http://localhost').href
+ : 'http://localhost',
+ );
expect(body.data.snippets.length).toBeGreaterThan(0);
+
+ const overridden = await router.request(
+ `/${createdJson.data.id}/code-snippets?base_url=${encodeURIComponent('https://sample.com/trueforge')}`,
+ );
+ expect(overridden.status).toBe(200);
+ const overriddenBody = (await overridden.json()) as { data: { base_url: string } };
+ expect(overriddenBody.data.base_url).toBe('https://sample.com/trueforge');
});
it('DELETE removes an agent by id and returns 404 when already gone', async () => {