Skip to content

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

Move /internal apis to /api/internal

Chirag Jaindd1c5924cb56
diff --git a/packages/frontend/vite.config.ts b/packages/frontend/vite.config.ts
index 027d6d571..2658f2bd4 100644
--- a/packages/frontend/vite.config.ts
+++ b/packages/frontend/vite.config.ts
@@ -42,7 +42,7 @@ const apiProxy: ProxyOptions = {
},
};
-/** When UI+API share a public path, strip it so Harness still sees `/api` / `/internal`. */
+/** When UI+API share a public path, strip it so Harness still sees `/api`. */
const prefixedApiProxy: ProxyOptions =
BASE === '/'
? apiProxy
@@ -55,14 +55,11 @@ const proxy: Record<string, ProxyOptions> =
BASE === '/'
? {
'/api': apiProxy,
- '/internal': apiProxy,
}
: {
// Prefer the prefixed keys so `/trueforge/api` is not matched as a bare `/api` miss.
[`${BASE}api`]: prefixedApiProxy,
- [`${BASE}internal`]: prefixedApiProxy,
'/api': apiProxy,
- '/internal': apiProxy,
};
export default defineConfig({
@@ -95,7 +92,7 @@ export default defineConfig({
port: PORT,
// Fail if FRONTEND_PORT is taken — never silently hop to 3001/3010/etc.
strictPort: true,
- // Proxy both public SDK routes and internal UI-only routes to the Harness.
+ // Proxy API routes (including /api/internal) to the Harness.
proxy,
},
});
diff --git a/packages/trueforge-ui/test/plugins/trueforge-agent-server-adapter/agentMetricsServer.test.ts b/packages/trueforge-ui/test/plugins/trueforge-agent-server-adapter/agentMetricsServer.test.ts
index 86af1d409..a5b29b9dd 100644
--- a/packages/trueforge-ui/test/plugins/trueforge-agent-server-adapter/agentMetricsServer.test.ts
+++ b/packages/trueforge-ui/test/plugins/trueforge-agent-server-adapter/agentMetricsServer.test.ts
@@ -14,7 +14,7 @@ describe('createHarnessAgentMetricsServer', () => {
const fetch = vi.fn(async (input: Request | string | URL) => {
const url = new URL(input instanceof Request ? input.url : input);
const path = url.pathname;
- if (path === '/internal/metrics/charts') {
+ if (path === '/api/internal/metrics/charts') {
return Response.json({
data: {
charts: [
@@ -28,7 +28,7 @@ describe('createHarnessAgentMetricsServer', () => {
},
});
}
- if (path === '/internal/metrics/meters') {
+ if (path === '/api/internal/metrics/meters') {
return Response.json({
data: {
meters: [
@@ -108,7 +108,7 @@ describe('createHarnessAgentMetricsServer', () => {
const meterInput = fetch.mock.calls[1]?.[0];
const meterUrl = new URL(meterInput instanceof Request ? meterInput.url : String(meterInput));
- assert.equal(meterUrl.pathname, '/internal/metrics/meters');
+ assert.equal(meterUrl.pathname, '/api/internal/metrics/meters');
assert.deepEqual(Object.fromEntries(meterUrl.searchParams), {
agent_id: 'agent-1',
start_timestamp: range.startTimestamp,
diff --git a/packages/trueforge/.cursor/BUGBOT.md b/packages/trueforge/.cursor/BUGBOT.md
index e93d055a8..953b52a29 100644
--- a/packages/trueforge/.cursor/BUGBOT.md
+++ b/packages/trueforge/.cursor/BUGBOT.md
@@ -18,7 +18,7 @@ Flag `withTransaction` callbacks that `await` `fetch`, an SDK client, Redis, or
Wire fields stay `snake_case` (also covered at repo root). New endpoints must follow this convention; renaming shipped schemas breaks `packages/trueforge-sdk`.
-**Paths:** plural kebab under `/api/v1/{collection}`, nested `/…/{id}/{subcollection}`, settings `/api/v1/settings/{collection}`, catalogs `/api/v1/catalogs/{collection}`. Ids as `{resource}_id`; name-keyed ops use `{name}` — do not mix id and name across verbs for one resource.
+**Paths:** plural kebab under `/api/v1/{collection}`, nested `/…/{id}/{subcollection}`, settings `/api/v1/settings/{collection}`, catalogs `/api/v1/catalogs/{collection}`, internal `/api/internal/{collection}`. Ids as `{resource}_id`; name-keyed ops use `{name}` — do not mix id and name across verbs for one resource.
If a settings resource is one-per-tenant (e.g. sandbox provider), keep the plural path `/api/v1/settings/sandbox-providers` for URL consistency, but Fern methods are `get`/`create_or_update` returning a single object — not `list` returning an array.
diff --git a/packages/trueforge/AGENTS.md b/packages/trueforge/AGENTS.md
index 79d9a3071..5f3fe97e4 100644
--- a/packages/trueforge/AGENTS.md
+++ b/packages/trueforge/AGENTS.md
@@ -5,7 +5,7 @@
Wire fields stay `snake_case`. New endpoints MUST follow this; renames of shipped schemas break `packages/trueforge-sdk`.
-**Paths:** plural kebab under `/api/v1/{collection}`, nested `/…/{id}/{subcollection}`, settings `/api/v1/settings/{collection}`, catalogs `/api/v1/catalogs/{collection}`. Ids as `{resource}_id`; name-keyed ops use `{name}` — do not mix id and name across verbs for one resource.
+**Paths:** plural kebab under `/api/v1/{collection}`, nested `/…/{id}/{subcollection}`, settings `/api/v1/settings/{collection}`, catalogs `/api/v1/catalogs/{collection}`, internal `/api/internal/{collection}`. Ids as `{resource}_id`; name-keyed ops use `{name}` — do not mix id and name across verbs for one resource.
If a settings resource is one-per-tenant (e.g. sandbox provider), keep the plural path `/api/v1/settings/sandbox-providers` for URL consistency, but Fern methods are `get`/`create_or_update` returning a single object — not `list` returning an array.
diff --git a/packages/trueforge/src/apis/sessionMetrics.ts b/packages/trueforge/src/apis/sessionMetrics.ts
index 3e54af34e..7e9b5d9b6 100644
--- a/packages/trueforge/src/apis/sessionMetrics.ts
+++ b/packages/trueforge/src/apis/sessionMetrics.ts
@@ -1,5 +1,5 @@
/**
- * Internal session metrics APIs (mounted at /internal/metrics).
+ * Internal session metrics APIs (mounted at /api/internal/metrics).
*/
import { OpenAPIHono, type RouteHandler } from '@hono/zod-openapi';
import type { ResolveUserContext } from '../auth/identity';
diff --git a/packages/trueforge/src/apis/sessions.ts b/packages/trueforge/src/apis/sessions.ts
index 15204d93d..05dec33b2 100644
--- a/packages/trueforge/src/apis/sessions.ts
+++ b/packages/trueforge/src/apis/sessions.ts
@@ -1,5 +1,5 @@
/**
- * DB-backed sessions APIs (mounted at /api/v1/sessions and /internal/sessions).
+ * DB-backed sessions APIs (mounted at /api/v1/sessions and /api/internal/sessions).
*/
import { OpenAPIHono, type RouteHandler } from '@hono/zod-openapi';
import type { ISessionStore, SessionHandle, SessionRecord, Sessions } from '@truefoundry/trueforge-core/agent-session';
@@ -282,7 +282,7 @@ function createGetOrCreateSessionByExternalIdHandler(
};
}
-/** Internal session operations (mounted at /internal/sessions). */
+/** Internal session operations (mounted at /api/internal/sessions). */
export function createInternalSessionsRouter(deps: InternalSessionsRouterDeps) {
const router = new OpenAPIHono();
router.openapi(getOrCreateSessionByExternalIdRoute, createGetOrCreateSessionByExternalIdHandler(deps));
diff --git a/packages/trueforge/src/app.ts b/packages/trueforge/src/app.ts
index 2e04247dc..e305db4ee 100644
--- a/packages/trueforge/src/app.ts
+++ b/packages/trueforge/src/app.ts
@@ -317,7 +317,7 @@ export function createServerApp<TTransaction>(deps: ServerDeps<TTransaction>) {
),
);
app.route(
- '/internal/sessions',
+ '/api/internal/sessions',
withAuth(
createInternalSessionsRouter({
sessions: deps.sessions,
@@ -331,7 +331,7 @@ export function createServerApp<TTransaction>(deps: ServerDeps<TTransaction>) {
),
);
app.route(
- '/internal/metrics',
+ '/api/internal/metrics',
withAuth(
createInternalMetricsRouter({
sessionMetricsStore: deps.sessionMetricsStore,
diff --git a/packages/trueforge/src/routes/sessionMetricsRoutes.ts b/packages/trueforge/src/routes/sessionMetricsRoutes.ts
index 6b0647185..b8a162121 100644
--- a/packages/trueforge/src/routes/sessionMetricsRoutes.ts
+++ b/packages/trueforge/src/routes/sessionMetricsRoutes.ts
@@ -1,5 +1,5 @@
/**
- * Internal session metrics route definitions (mounted at /internal/metrics).
+ * Internal session metrics route definitions (mounted at /api/internal/metrics).
* Handlers are registered in apis/sessionMetrics.ts.
*/
import { createRoute } from '@hono/zod-openapi';
diff --git a/packages/trueforge/src/routes/sessionRoutes.ts b/packages/trueforge/src/routes/sessionRoutes.ts
index ba9e320ae..614a8c397 100644
--- a/packages/trueforge/src/routes/sessionRoutes.ts
+++ b/packages/trueforge/src/routes/sessionRoutes.ts
@@ -1,7 +1,7 @@
/**
* Session route definitions.
* Public DB-backed routes mount at /api/v1/sessions; internal operations mount
- * at /internal/sessions.
+ * at /api/internal/sessions.
* Handlers are registered in apis/sessions.ts.
*/
import { createRoute, z } from '@hono/zod-openapi';
diff --git a/packages/trueforge/tests/unit/apis/sessionHttp.test.ts b/packages/trueforge/tests/unit/apis/sessionHttp.test.ts
index e9175e694..52779be61 100644
--- a/packages/trueforge/tests/unit/apis/sessionHttp.test.ts
+++ b/packages/trueforge/tests/unit/apis/sessionHttp.test.ts
@@ -90,9 +90,9 @@ describe('sessions HTTP agent binding', () => {
logger: createLogger({ silent: true }),
};
app.route('/', createSessionsRouter(deps));
- app.route('/internal/sessions', createInternalSessionsRouter(deps));
+ app.route('/api/internal/sessions', createInternalSessionsRouter(deps));
app.route(
- '/internal/metrics',
+ '/api/internal/metrics',
createInternalMetricsRouter({
sessionMetricsStore,
resolveUserContext: deps.resolveUserContext,
@@ -180,7 +180,7 @@ describe('sessions HTTP agent binding', () => {
end_timestamp: end.toISOString(),
});
- const response = await app.request(`/internal/metrics/meters?${query.toString()}`);
+ const response = await app.request(`/api/internal/metrics/meters?${query.toString()}`);
expect(response.status).toBe(200);
const meters = GetSessionMetricsMeterResponseSchema.parse(await response.json());
@@ -192,7 +192,7 @@ describe('sessions HTTP agent binding', () => {
expect(meters.data.meters.find(meter => meter.name === 'p95_session_duration_ms')?.aggregate_value).toBe(0);
const sessionsChartResponse = await app.request(
- `/internal/metrics/charts-data?${query.toString()}&chart_name=sessions_over_time`,
+ `/api/internal/metrics/charts-data?${query.toString()}&chart_name=sessions_over_time`,
);
expect(sessionsChartResponse.status).toBe(200);
const sessionsChart = GetSessionMetricsChartDataResponseSchema.parse(await sessionsChartResponse.json());
@@ -200,7 +200,7 @@ describe('sessions HTTP agent binding', () => {
});
it('returns the static session metrics charts', async () => {
- const response = await app.request('/internal/metrics/charts');
+ const response = await app.request('/api/internal/metrics/charts');
expect(response.status).toBe(200);
const payload = GetSessionMetricsChartResponseSchema.parse(await response.json());
@@ -219,7 +219,7 @@ describe('sessions HTTP agent binding', () => {
end_timestamp: '2026-02-01T00:00:00.000Z',
});
- const response = await app.request(`/internal/metrics/meters?${query.toString()}`);
+ const response = await app.request(`/api/internal/metrics/meters?${query.toString()}`);
expect(response.status).toBe(400);
});
@@ -369,7 +369,7 @@ describe('sessions HTTP agent binding', () => {
expect(publicPath.status).toBe(404);
const created = await app.request(
- '/internal/sessions/get-or-create-by-external-id',
+ '/api/internal/sessions/get-or-create-by-external-id',
jsonInit('POST', { external_id: 'run-abc', agent: { spec: inlineSpec } }),
);
expect(created.status).toBe(201);
@@ -379,7 +379,7 @@ describe('sessions HTTP agent binding', () => {
expect(createdJson.data.agent.spec.instructions).toBe('inline');
const again = await app.request(
- '/internal/sessions/get-or-create-by-external-id',
+ '/api/internal/sessions/get-or-create-by-external-id',
jsonInit('POST', {
external_id: 'run-abc',
agent: { spec: { ...inlineSpec, instructions: 'ignored-on-get' } },
@@ -402,7 +402,7 @@ describe('sessions HTTP agent binding', () => {
external_id: 'run-theirs',
});
const forbidden = await app.request(
- '/internal/sessions/get-or-create-by-external-id',
+ '/api/internal/sessions/get-or-create-by-external-id',
jsonInit('POST', { external_id: 'run-theirs', agent: { spec: inlineSpec } }),
);
expect(forbidden.status).toBe(403);