Skip to content

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

Clarify session resource admission and return 422 for semantic misses.

debajyoti-truefoundry2f371506fbd5
diff --git a/fern/openapi/openapi.json b/fern/openapi/openapi.json
index 2368f52e9..3c8770537 100644
--- a/fern/openapi/openapi.json
+++ b/fern/openapi/openapi.json
@@ -3495,7 +3495,7 @@
}
}
},
- "description": "The agent spec is valid but requires a capability this server does not provide (e.g. sandbox or skills)."
+ "description": "The agent spec is valid but references a resource this server does not provide (e.g. model, MCP server, skill, or sandbox)."
}
},
"summary": "Create a session",
@@ -3651,7 +3651,7 @@
}
}
},
- "description": "The agent spec is valid but requires a capability this server does not provide (e.g. sandbox or skills)."
+ "description": "The agent spec is valid but references a resource this server does not provide (e.g. model, MCP server, skill, or sandbox)."
}
},
"summary": "Update a session",
@@ -3982,6 +3982,16 @@
}
},
"description": "Requested action cannot be performed on the session because it is no longer usable."
+ },
+ "422": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "The session is valid but a required resource is no longer available (e.g. model, MCP server, skill, or sandbox provider)."
}
},
"summary": "Create and execute a turn in a session",
diff --git a/packages/harness/src/agent-session/schemas/agentSpec.ts b/packages/harness/src/agent-session/schemas/agentSpec.ts
index b9e90f761..f5a527e1a 100644
--- a/packages/harness/src/agent-session/schemas/agentSpec.ts
+++ b/packages/harness/src/agent-session/schemas/agentSpec.ts
@@ -31,21 +31,10 @@ const ModelParamsSchema = z
.loose() // this ensures extra model params are allowed
.openapi('ModelParams');
-/** Same shape as server `parseModelFqn`: exactly one slash, non-empty provider and model. */
-function isModelFqn(name: string): boolean {
- const slash = name.indexOf('/');
- if (slash <= 0 || slash === name.length - 1) {
- return false;
- }
- return !name.includes('/', slash + 1);
-}
-
+// Opaque runtime identifier; the hosting server owns naming conventions (e.g. provider/model).
const ModelSpecSchema = z
.object({
- name: z
- .string()
- .min(1, 'model.name must not be empty')
- .refine(isModelFqn, { message: 'model.name must be a fully qualified "provider/model"' }),
+ name: z.string().min(1, 'model.name must not be empty'),
params: ModelParamsSchema.optional(),
})
.openapi('AgentSpecModel');
diff --git a/packages/harness/tests/agent-session/agentSpecModel.test.ts b/packages/harness/tests/agent-session/agentSpecModel.test.ts
new file mode 100644
index 000000000..3504b72f9
--- /dev/null
+++ b/packages/harness/tests/agent-session/agentSpecModel.test.ts
@@ -0,0 +1,14 @@
+import { AgentSpecSchema } from '../../src/agent-session/schemas/agentSpec';
+
+describe('AgentSpecSchema model.name', () => {
+ it('accepts opaque non-empty identifiers including non-FQN shapes', () => {
+ expect(AgentSpecSchema.parse({ model: { name: 'gpt-4' } }).model.name).toBe('gpt-4');
+ expect(AgentSpecSchema.parse({ model: { name: 'provider/model' } }).model.name).toBe('provider/model');
+ expect(AgentSpecSchema.parse({ model: { name: 'a/b/c' } }).model.name).toBe('a/b/c');
+ });
+
+ it('rejects empty model.name', () => {
+ const result = AgentSpecSchema.safeParse({ model: { name: '' } });
+ expect(result.success).toBe(false);
+ });
+});
diff --git a/packages/sdk/.fern/metadata.json b/packages/sdk/.fern/metadata.json
index a23ff9d6f..744af4f79 100644
--- a/packages/sdk/.fern/metadata.json
+++ b/packages/sdk/.fern/metadata.json
@@ -27,10 +27,9 @@
"streamType": "web",
"useDefaultRequestParameterValues": true
},
- "originGitCommit": "c499a2b97a1791a40e2ced533b26065c809d364b",
+ "originGitCommit": "c24ef42326caa6104fd615e295fd903d199516c1",
"originGitCommitIsDirty": true,
- "invokedBy": "ci",
+ "invokedBy": "manual",
"requestedVersion": "0.0.0",
- "ciProvider": "github",
"sdkVersion": "0.0.0"
}
diff --git a/packages/sdk/src/api/resources/sessions/client/Client.ts b/packages/sdk/src/api/resources/sessions/client/Client.ts
index 0c9c4e8f5..f2670f282 100644
--- a/packages/sdk/src/api/resources/sessions/client/Client.ts
+++ b/packages/sdk/src/api/resources/sessions/client/Client.ts
@@ -943,6 +943,17 @@ export class SessionsClient {
}),
_response.rawResponse,
);
+ case 422:
+ throw new TrueHarness.UnprocessableEntityError(
+ serializers.RequestErrorResponse.parseOrThrow(_response.error.body, {
+ unrecognizedObjectKeys: "passthrough",
+ allowUnrecognizedUnionMembers: true,
+ allowUnrecognizedEnumValues: true,
+ skipValidation: true,
+ breadcrumbsPrefix: ["response"],
+ }),
+ _response.rawResponse,
+ );
default:
throw new errors.TrueHarnessError({
statusCode: _response.error.statusCode,
diff --git a/packages/sdk/tests/wire/sessions.test.ts b/packages/sdk/tests/wire/sessions.test.ts
index 629e68c9e..c7073dc8d 100644
--- a/packages/sdk/tests/wire/sessions.test.ts
+++ b/packages/sdk/tests/wire/sessions.test.ts
@@ -781,6 +781,26 @@ describe("SessionsClient", () => {
}).rejects.toThrow(TrueHarnessTypes.PreconditionFailedError);
});
+ test("create_turn (5)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueHarness({ maxRetries: 0, baseUrl: server.baseUrl });
+ const rawRequestBody = {};
+ const rawResponseBody = { error: { message: "message" } };
+
+ server
+ .mockEndpoint()
+ .post("/api/v1/sessions/session_id/turns")
+ .jsonBody(rawRequestBody)
+ .respondWith()
+ .statusCode(422)
+ .jsonBody(rawResponseBody)
+ .build();
+
+ await expect(async () => {
+ return await client.sessions.createTurn("session_id");
+ }).rejects.toThrow(TrueHarnessTypes.UnprocessableEntityError);
+ });
+
test("get_turn (1)", async () => {
const server = mockServerPool.createServer();
const client = new TrueHarness({ maxRetries: 0, baseUrl: server.baseUrl });
diff --git a/packages/server/src/apis/mcpServers.ts b/packages/server/src/apis/mcpServers.ts
index 39fa8e90f..d54117db9 100644
--- a/packages/server/src/apis/mcpServers.ts
+++ b/packages/server/src/apis/mcpServers.ts
@@ -7,7 +7,6 @@ import {
RemoteMCP,
withTimeout,
} from '@truefoundry/utils-core/core';
-import { HTTPException } from 'hono/http-exception';
import type { Logger } from 'winston';
import type { McpCatalog } from '../catalog/McpCatalog';
import configuration from '../config';
@@ -100,7 +99,7 @@ export function createMcpServersRouter(deps: McpServersRouterDeps) {
};
const listConfiguredHandler: RouteHandler<typeof listConfiguredMcpServersRoute> = async c => {
- const records = await deps.mcpServerStore.listServers(TENANT_ID);
+ const records = await deps.mcpServerStore.listServers({ tenant_id: TENANT_ID, names: undefined });
const nowMs = Date.now();
// Only DCR servers have tokens; batch the lookup.
const dcrIds = records.filter(record => record.manifest.auth?.type === 'dcr').map(record => record.id);
@@ -151,21 +150,15 @@ export function createMcpServersRouter(deps: McpServersRouterDeps) {
const listToolsHandler: RouteHandler<typeof listMcpServerToolsRoute> = async c => {
const { name } = c.req.valid('param');
// Same url + header resolution as turn execution (DCR via resolveMcpAuth, header/no-auth static).
- let connection;
- try {
- connection = await getMcpConnection({
- tenant_id: TENANT_ID,
- name,
- store: deps.mcpServerStore,
- tokenStore: deps.tokenStore,
- clientName: configuration.OAUTH_CLIENT_NAME,
- });
- } catch (error) {
- // getMcpConnection throws HTTPException(400) for unknown names; settings wire uses 404.
- if (error instanceof HTTPException && error.status === 400) {
- return c.json({ error: { message: `MCP server not found: ${name}` } }, 404);
- }
- throw error;
+ const connection = await getMcpConnection({
+ tenant_id: TENANT_ID,
+ name,
+ store: deps.mcpServerStore,
+ tokenStore: deps.tokenStore,
+ clientName: configuration.OAUTH_CLIENT_NAME,
+ });
+ if (connection === undefined) {
+ return c.json({ error: { message: `MCP server not found: ${name}` } }, 404);
}
const remote = new RemoteMCP({
id: name,
@@ -268,7 +261,7 @@ export function createMcpServersRouter(deps: McpServersRouterDeps) {
export function createAvailableMcpServersRouter(store: IMcpServerStore) {
const router = new OpenAPIHono();
router.openapi(listAvailableMcpServersRoute, async c => {
- const records = await store.listServers(TENANT_ID);
+ const records = await store.listServers({ tenant_id: TENANT_ID, names: undefined });
return c.json(
{
data: records.map(record => ({ name: record.name, url: record.manifest.url })),
diff --git a/packages/server/src/apis/skills.ts b/packages/server/src/apis/skills.ts
index 8473b3fb6..6512b7c30 100644
--- a/packages/server/src/apis/skills.ts
+++ b/packages/server/src/apis/skills.ts
@@ -30,7 +30,7 @@ export function createSkillsRouter(deps: SkillsRouterDeps) {
};
const listConfiguredHandler: RouteHandler<typeof listConfiguredSkillsRoute> = async c => {
- const records = await deps.skillStore.listSkills(TENANT_ID);
+ const records = await deps.skillStore.listSkills({ tenant_id: TENANT_ID, names: undefined });
return c.json({ data: records.map(toConfiguredSkill) }, 200);
};
@@ -56,7 +56,7 @@ export function createSkillsRouter(deps: SkillsRouterDeps) {
export function createAvailableSkillsRouter(store: ISkillStore) {
const router = new OpenAPIHono();
router.openapi(listAvailableSkillsRoute, async c => {
- const records = await store.listSkills(TENANT_ID);
+ const records = await store.listSkills({ tenant_id: TENANT_ID, names: undefined });
return c.json(
{
data: records.map(record => ({
diff --git a/packages/server/src/apis/turns.ts b/packages/server/src/apis/turns.ts
index 894f86a4f..4e5353a0e 100644
--- a/packages/server/src/apis/turns.ts
+++ b/packages/server/src/apis/turns.ts
@@ -45,7 +45,7 @@ import { mintPeeredTurnId } from '../runtime/peeringIds';
import {
buildTurnSandbox,
getMcpConnection,
- getProviderConfig,
+ getModelProviderConfig,
resolveGitSkills,
resolveSandboxProvider,
} from '../runtime/sessionResources';
@@ -103,14 +103,21 @@ function createTurnResolver(deps: {
signal,
});
},
- mcp: async name =>
- getMcpConnection({
+ mcp: async name => {
+ const connection = await getMcpConnection({
tenant_id: TENANT_ID,
name,
store: mcpServerStore,
tokenStore,
clientName: configuration.OAUTH_CLIENT_NAME,
- }),
+ });
+ if (connection === undefined) {
+ throw new HTTPException(422, {
+ message: `Unknown MCP server "${name}" — not configured`,
+ });
+ }
+ return connection;
+ },
mcpRequestTimeoutMs: configuration.MCP_REQUEST_TIMEOUT_MS,
mcpConnectTimeoutMs: configuration.MCP_CONNECT_TIMEOUT_MS,
sandboxProvider: async ({ spec, existingSandboxId, tracing }) => {
@@ -293,7 +300,7 @@ export function createTurnsRouter(deps: TurnsRouterDeps) {
const abortController = new AbortController();
const modelName = session.agent_spec.model.name;
- const providerConfig = await getProviderConfig({
+ const providerConfig = await getModelProviderConfig({
tenant_id: TENANT_ID,
name: modelName,
store: deps.modelProviderStore,
diff --git a/packages/server/src/db/mcpServerStore.ts b/packages/server/src/db/mcpServerStore.ts
index bda019cfb..07c4b3b63 100644
--- a/packages/server/src/db/mcpServerStore.ts
+++ b/packages/server/src/db/mcpServerStore.ts
@@ -34,6 +34,12 @@ export interface GetMcpServerInput {
name: string;
}
+export interface ListMcpServersInput {
+ tenant_id: string;
+ /** `undefined` lists all; empty returns `[]` without querying; otherwise `WHERE name IN (...)`. */
+ names: readonly string[] | undefined;
+}
+
export interface UpsertMcpServerInput {
tenant_id: string;
name: ResourceName;
@@ -41,7 +47,7 @@ export interface UpsertMcpServerInput {
}
export interface IMcpServerStore extends IOAuthClientStore {
- listServers(tenantId: string): Promise<McpServerRecord[]>;
+ listServers(input: ListMcpServersInput): Promise<McpServerRecord[]>;
getServer(input: GetMcpServerInput): Promise<McpServerRecord | undefined>;
/**
* Creates the server or replaces `manifest` (+ `updated_at`) only.
diff --git a/packages/server/src/db/postgres/mcp-server-store/PostgresMcpServerStore.ts b/packages/server/src/db/postgres/mcp-server-store/PostgresMcpServerStore.ts
index 7900c6bec..6bdf06dd6 100644
--- a/packages/server/src/db/postgres/mcp-server-store/PostgresMcpServerStore.ts
+++ b/packages/server/src/db/postgres/mcp-server-store/PostgresMcpServerStore.ts
@@ -6,6 +6,7 @@ import {
toStoredOAuthClientRecord,
type GetMcpServerInput,
type IMcpServerStore,
+ type ListMcpServersInput,
type McpServerRecord,
type UpsertMcpServerInput,
} from '../../mcpServerStore';
@@ -30,13 +31,15 @@ export class PostgresMcpServerStore implements IMcpServerStore {
this.#db = db;
}
- async listServers(tenantId: string): Promise<McpServerRecord[]> {
- const rows = await this.#db
- .selectFrom('mcp_server')
- .selectAll()
- .where('tenant_id', '=', tenantId)
- .orderBy('name')
- .execute();
+ async listServers(input: ListMcpServersInput): Promise<McpServerRecord[]> {
+ if (input.names?.length === 0) {
+ return [];
+ }
+ let query = this.#db.selectFrom('mcp_server').selectAll().where('tenant_id', '=', input.tenant_id);
+ if (input.names !== undefined) {
+ query = query.where('name', 'in', [...input.names]);
+ }
+ const rows = await query.orderBy('name').execute();
return rows.map(toRecord);
}
diff --git a/packages/server/src/db/postgres/skill-store/PostgresSkillStore.ts b/packages/server/src/db/postgres/skill-store/PostgresSkillStore.ts
index 2b95724ff..ea175a204 100644
--- a/packages/server/src/db/postgres/skill-store/PostgresSkillStore.ts
+++ b/packages/server/src/db/postgres/skill-store/PostgresSkillStore.ts
@@ -1,5 +1,11 @@
import type { Kysely, Selectable } from 'kysely';
-import { type GetSkillInput, type ISkillStore, type SkillRecord, type UpsertSkillInput } from '../../skillStore';
+import {
+ type GetSkillInput,
+ type ISkillStore,
+ type ListSkillsInput,
+ type SkillRecord,
+ type UpsertSkillInput,
+} from '../../skillStore';
import { json, now } from '../sqlExpressions';
import type { Database, SkillTable } from '../types';
@@ -20,13 +26,15 @@ export class PostgresSkillStore implements ISkillStore {
this.#db = db;
}
- async listSkills(tenantId: string): Promise<SkillRecord[]> {
- const rows = await this.#db
- .selectFrom('skill')
- .selectAll()
- .where('tenant_id', '=', tenantId)
- .orderBy('name')
- .execute();
+ async listSkills(input: ListSkillsInput): Promise<SkillRecord[]> {
+ if (input.names?.length === 0) {
+ return [];
+ }
+ let query = this.#db.selectFrom('skill').selectAll().where('tenant_id', '=', input.tenant_id);
+ if (input.names !== undefined) {
+ query = query.where('name', 'in', [...input.names]);
+ }
+ const rows = await query.orderBy('name').execute();
return rows.map(toRecord);
}
diff --git a/packages/server/src/db/skillStore.ts b/packages/server/src/db/skillStore.ts
index 937b65115..54d6df858 100644
--- a/packages/server/src/db/skillStore.ts
+++ b/packages/server/src/db/skillStore.ts
@@ -21,6 +21,12 @@ export interface GetSkillInput {
name: string;
}
+export interface ListSkillsInput {
+ tenant_id: string;
+ /** `undefined` lists all; empty returns `[]` without querying; otherwise `WHERE name IN (...)`. */
+ names: readonly string[] | undefined;
+}
+
export interface UpsertSkillInput {
tenant_id: string;
name: ResourceName;
@@ -28,7 +34,7 @@ export interface UpsertSkillInput {
}
export interface ISkillStore {
- listSkills(tenantId: string): Promise<SkillRecord[]>;
+ listSkills(input: ListSkillsInput): Promise<SkillRecord[]>;
getSkill(input: GetSkillInput): Promise<SkillRecord | undefined>;
/** Single-row write: creates the skill or replaces the whole manifest. */
upsertSkill(input: UpsertSkillInput): Promise<SkillRecord>;
diff --git a/packages/server/src/db/sqlite/mcp-server-store/SqliteMcpServerStore.ts b/packages/server/src/db/sqlite/mcp-server-store/SqliteMcpServerStore.ts
index 551484c08..e65eca826 100644
--- a/packages/server/src/db/sqlite/mcp-server-store/SqliteMcpServerStore.ts
+++ b/packages/server/src/db/sqlite/mcp-server-store/SqliteMcpServerStore.ts
@@ -7,6 +7,7 @@ import {
toStoredOAuthClientRecord,
type GetMcpServerInput,
type IMcpServerStore,
+ type ListMcpServersInput,
type McpServerRecord,
type OAuthClient,
type OAuthServer,
@@ -34,13 +35,15 @@ export class SqliteMcpServerStore implements IMcpServerStore {
this.#db = db;
}
- async listServers(tenantId: string): Promise<McpServerRecord[]> {
- return await this.#db
- .selectFrom('mcp_server')
- .select(recordColumns)
- .where('tenant_id', '=', tenantId)
- .orderBy('name')
- .execute();
+ async listServers(input: ListMcpServersInput): Promise<McpServerRecord[]> {
+ if (input.names?.length === 0) {
+ return [];
+ }
+ let query = this.#db.selectFrom('mcp_server').select(recordColumns).where('tenant_id', '=', input.tenant_id);
+ if (input.names !== undefined) {
+ query = query.where('name', 'in', [...input.names]);
+ }
+ return await query.orderBy('name').execute();
}
async getServer(input: GetMcpServerInput): Promise<McpServerRecord | undefined> {
diff --git a/packages/server/src/db/sqlite/skill-store/SqliteSkillStore.ts b/packages/server/src/db/sqlite/skill-store/SqliteSkillStore.ts
index 3395122bd..a3a726510 100644
--- a/packages/server/src/db/sqlite/skill-store/SqliteSkillStore.ts
+++ b/packages/server/src/db/sqlite/skill-store/SqliteSkillStore.ts
@@ -1,6 +1,12 @@
import type { ExpressionBuilder, Kysely } from 'kysely';
import type { SkillManifest } from '../../../schemas/skill';
-import { type GetSkillInput, type ISkillStore, type SkillRecord, type UpsertSkillInput } from '../../skillStore';
+import {
+ type GetSkillInput,
+ type ISkillStore,
+ type ListSkillsInput,
+ type SkillRecord,
+ type UpsertSkillInput,
+} from '../../skillStore';
import { jsonbBind, jsonText, nowIso } from '../sqlExpressions';
import type { Database } from '../types';
@@ -22,13 +28,15 @@ export class SqliteSkillStore implements ISkillStore {
this.#db = db;
}
- async listSkills(tenantId: string): Promise<SkillRecord[]> {
- return await this.#db
- .selectFrom('skill')
- .select(recordColumns)
- .where('tenant_id', '=', tenantId)
- .orderBy('name')
- .execute();
+ async listSkills(input: ListSkillsInput): Promise<SkillRecord[]> {
+ if (input.names?.length === 0) {
+ return [];
+ }
+ let query = this.#db.selectFrom('skill').select(recordColumns).where('tenant_id', '=', input.tenant_id);
+ if (input.names !== undefined) {
+ query = query.where('name', 'in', [...input.names]);
+ }
+ return await query.orderBy('name').execute();
}
async getSkill(input: GetSkillInput): Promise<SkillRecord | undefined> {
diff --git a/packages/server/src/routes/sessionRoutes.ts b/packages/server/src/routes/sessionRoutes.ts
index 627f33d63..8a56341e6 100644
--- a/packages/server/src/routes/sessionRoutes.ts
+++ b/packages/server/src/routes/sessionRoutes.ts
@@ -48,7 +48,7 @@ export const createSessionRoute = createRoute({
422: {
content: { 'application/json': { schema: RequestErrorResponseSchema } },
description:
- 'The agent spec is valid but requires a capability this server does not provide (e.g. sandbox or skills).',
+ 'The agent spec is valid but references a resource this server does not provide (e.g. model, MCP server, skill, or sandbox).',
},
},
});
@@ -125,7 +125,7 @@ export const updateSessionRoute = createRoute({
422: {
content: { 'application/json': { schema: RequestErrorResponseSchema } },
description:
- 'The agent spec is valid but requires a capability this server does not provide (e.g. sandbox or skills).',
+ 'The agent spec is valid but references a resource this server does not provide (e.g. model, MCP server, skill, or sandbox).',
},
},
});
diff --git a/packages/server/src/routes/turnRoutes.ts b/packages/server/src/routes/turnRoutes.ts
index d93c68425..7afef5ef1 100644
--- a/packages/server/src/routes/turnRoutes.ts
+++ b/packages/server/src/routes/turnRoutes.ts
@@ -143,6 +143,11 @@ Use \`previous_turn_id\` to chain to the session's last turn (defaults to \`auto
content: { 'application/json': { schema: RequestErrorResponseSchema } },
description: 'Requested action cannot be performed on the session because it is no longer usable.',
},
+ 422: {
+ content: { 'application/json': { schema: RequestErrorResponseSchema } },
+ description:
+ 'The session is valid but a required resource is no longer available (e.g. model, MCP server, skill, or sandbox provider).',
+ },
},
});
diff --git a/packages/server/src/runtime/sessionResources.ts b/packages/server/src/runtime/sessionResources.ts
index 18ca9d180..8429656f4 100644
--- a/packages/server/src/runtime/sessionResources.ts
+++ b/packages/server/src/runtime/sessionResources.ts
@@ -45,10 +45,9 @@ export function parseModelFqn(name: string): { providerName: string; modelName:
/**
* Load turn-ready LLM config for a configured FQN (`provider/model`).
- * Missing provider/model → HTTPException(400) (e.g. deleted after admit).
- * Malformed FQN after admit is an invariant → plain Error (500).
+ * Malformed FQN or missing provider/model → HTTPException(422).
*/
-export async function getProviderConfig({
+export async function getModelProviderConfig({
tenant_id,
name,
store,
@@ -57,20 +56,21 @@ export async function getProviderConfig({
name: string;
store: IModelProviderStore;
}): Promise<VercelAIProviderConfig> {
- // AgentSpecSchema already required provider/model; failure here is corrupt stored spec.
const parsed = parseModelFqn(name);
if (parsed === undefined) {
- throw new Error(`Model name must be a fully qualified "provider/model": ${name}`);
+ throw new HTTPException(422, {
+ message: `Model name must be a fully qualified "provider/model": ${name}`,
+ });
}
const provider = await store.getProvider({ tenant_id, name: parsed.providerName });
if (provider === undefined) {
- throw new HTTPException(400, {
+ throw new HTTPException(422, {
message: `Unknown model "${name}" — provider not configured`,
});
}
const model = provider.manifest.models.find(entry => entry.name === parsed.modelName);
if (model === undefined) {
- throw new HTTPException(400, {
+ throw new HTTPException(422, {
message: `Unknown model "${name}" — not configured on provider`,
});
}
@@ -119,7 +119,7 @@ function dcrHeadersResolver(params: {
/**
* Load MCP url + headers for a configured server.
* DCR uses resolveMcpAuth; header / no-auth use resolveConfiguredMcpRequestHeaders.
- * Throws HTTPException(400) if the server is not registered.
+ * Returns undefined when the server is not registered — callers choose the response.
*/
export async function getMcpConnection({
tenant_id,
@@ -133,12 +133,10 @@ export async function getMcpConnection({
store: IMcpServerStore;
tokenStore: IOAuthTokenStore;
clientName: string;
-}): Promise<McpConnection> {
+}): Promise<McpConnection | undefined> {
const record = await store.getServer({ tenant_id, name });
if (record === undefined) {
- throw new HTTPException(400, {
- message: `Unknown MCP server "${name}" — not configured`,
- });
+ return undefined;
}
if (record.manifest.auth?.type === 'dcr') {
return {
@@ -160,7 +158,7 @@ export async function getMcpConnection({
/**
* Expand agent_spec skill names into git mounts from the skill store.
* Wire url/path/ref/description on the request are ignored — the store row wins.
- * Throws HTTPException(400) if any name is not registered.
+ * Throws HTTPException(422) if any name is not registered.
*/
export async function resolveGitSkills({
tenant_id,
@@ -171,11 +169,17 @@ export async function resolveGitSkills({
skills: readonly { name: string }[];
store: ISkillStore;
}): Promise<GitSkill[]> {
+ if (skills.length === 0) {
+ return [];
+ }
+ const names = skills.map(skill => skill.name);
+ const records = await store.listSkills({ tenant_id, names });
+ const byName = new Map(records.map(record => [record.name, record]));
const resolved: GitSkill[] = [];
for (const skill of skills) {
- const record = await store.getSkill({ tenant_id, name: skill.name });
+ const record = byName.get(skill.name);
if (record === undefined) {
- throw new HTTPException(400, {
+ throw new HTTPException(422, {
message: `Unknown skill "${skill.name}" — not configured`,
});
}
@@ -249,7 +253,7 @@ export function buildTurnSandbox(input: {
/**
* Cross-checks an AgentSpec against configured models / MCP / skills and
- * sandbox capability. Throws HTTPException: 400 unknown refs, 422 missing sandbox.
+ * sandbox capability. Throws HTTPException(422) for semantic failures.
* Skills are admitted by name only; mounts expand at turn time.
*/
export async function validateAgentSpec({
@@ -267,20 +271,21 @@ export async function validateAgentSpec({
skillStore: ISkillStore;
sandboxProviderStore: ISandboxProviderStore;
}): Promise<void> {
- // FQN shape is enforced by AgentSpecSchema; parse failure here is an invariant.
const parsed = parseModelFqn(spec.model.name);
if (parsed === undefined) {
- throw new Error(`Model name must be a fully qualified "provider/model": ${spec.model.name}`);
+ throw new HTTPException(422, {
+ message: `Model name must be a fully qualified "provider/model": ${spec.model.name}`,
+ });
}
const provider = await modelProviderStore.getProvider({ tenant_id, name: parsed.providerName });
if (provider === undefined) {
- throw new HTTPException(400, {
+ throw new HTTPException(422, {
message: `Unknown model "${spec.model.name}" — provider not configured`,
});
}
const model = provider.manifest.models.find(entry => entry.name === parsed.modelName);
if (model === undefined) {
- throw new HTTPException(400, {
+ throw new HTTPException(422, {
message: `Unknown model "${spec.model.name}" — not configured on provider`,
});
}
@@ -288,7 +293,7 @@ export async function validateAgentSpec({
if (reasoningEffort !== undefined) {
const efforts = model.properties.reasoning_efforts;
if (!efforts?.includes(reasoningEffort)) {
- throw new HTTPException(400, {
+ throw new HTTPException(422, {
message: efforts
? `Reasoning effort "${reasoningEffort}" is not supported by model "${spec.model.name}"`
: `Model "${spec.model.name}" does not support configurable reasoning effort`,
@@ -296,26 +301,34 @@ export async function validateAgentSpec({
}
}
- for (const server of spec.mcp_servers ?? []) {
- const record = await mcpServerStore.getServer({ tenant_id, name: server.name });
- if (record === undefined) {
- throw new HTTPException(400, {
- message: `Unknown MCP server "${server.name}" — not configured`,
+ const requestedMcpServers = spec.mcp_servers ?? [];
+ if (requestedMcpServers.length > 0) {
+ const names = requestedMcpServers.map(server => server.name);
+ const configuredNames = new Set(
+ (await mcpServerStore.listServers({ tenant_id, names })).map(record => record.name),
+ );
+ const unknown = requestedMcpServers.find(server => !configuredNames.has(server.name));
+ if (unknown !== undefined) {
+ throw new HTTPException(422, {
+ message: `Unknown MCP server "${unknown.name}" — not configured`,
});
}
}
- for (const skill of spec.skills ?? []) {
- const record = await skillStore.getSkill({ tenant_id, name: skill.name });
- if (record === undefined) {
- throw new HTTPException(400, {
- message: `Unknown skill "${skill.name}" — not configured`,
+ const requestedSkills = spec.skills ?? [];
+ if (requestedSkills.length > 0) {
+ const names = requestedSkills.map(skill => skill.name);
+ const configuredNames = new Set((await skillStore.listSkills({ tenant_id, names })).map(record => record.name));
+ const unknown = requestedSkills.find(skill => !configuredNames.has(skill.name));
+ if (unknown !== undefined) {
+ throw new HTTPException(422, {
+ message: `Unknown skill "${unknown.name}" — not configured`,
});
}
}
const wantsSandbox = spec.config?.sandbox?.enabled === true;
- const hasSkills = (spec.skills?.length ?? 0) > 0;
+ const hasSkills = requestedSkills.length > 0;
if (wantsSandbox || hasSkills) {
const record = await sandboxProviderStore.getSandboxProvider(tenant_id);
if (record === undefined) {
diff --git a/packages/server/tests/db/mcpServerStoreContractSuite.ts b/packages/server/tests/db/mcpServerStoreContractSuite.ts
index 7b9e7e3a2..3856137d7 100644
--- a/packages/server/tests/db/mcpServerStoreContractSuite.ts
+++ b/packages/server/tests/db/mcpServerStoreContractSuite.ts
@@ -80,7 +80,7 @@ export function runMcpServerStoreContractSuite(getStore: () => IMcpServerStore):
expect(updated.created_at).toBe(created.created_at);
expect(Date.parse(updated.updated_at)).toBeGreaterThanOrEqual(Date.parse(created.updated_at));
- const servers = await store.listServers(TENANT);
+ const servers = await store.listServers({ tenant_id: TENANT, names: undefined });
expect(servers).toEqual([updated]);
});
@@ -94,11 +94,34 @@ export function runMcpServerStoreContractSuite(getStore: () => IMcpServerStore):
});
await store.upsertServer({ tenant_id: 'other-tenant', name: 'linear', manifest: manifest() });
- const servers = await store.listServers(TENANT);
+ const servers = await store.listServers({ tenant_id: TENANT, names: undefined });
expect(servers.map(server => server.name)).toEqual(['deepwiki', 'linear']);
expect(servers.every(server => server.tenant_id === TENANT)).toBe(true);
});
+ it('listServers filters by names and returns empty for an empty name list', async () => {
+ const store = getStore();
+ await store.upsertServer({ tenant_id: TENANT, name: 'linear', manifest: manifest() });
+ await store.upsertServer({
+ tenant_id: TENANT,
+ name: 'deepwiki',
+ manifest: manifest({ name: 'deepwiki', url: 'https://mcp.deepwiki.com/mcp' }),
+ });
+ await store.upsertServer({
+ tenant_id: TENANT,
+ name: 'notion',
+ manifest: manifest({ name: 'notion', url: 'https://mcp.notion.com/mcp' }),
+ });
+
+ const filtered = await store.listServers({
+ tenant_id: TENANT,
+ names: ['notion', 'missing', 'deepwiki'],
+ });
+ expect(filtered.map(server => server.name)).toEqual(['deepwiki', 'notion']);
+
+ await expect(store.listServers({ tenant_id: TENANT, names: [] })).resolves.toEqual([]);
+ });
+
it('upsert leaves oauth columns null and does not clear a saved OAuth client', async () => {
const store = getStore();
const created = await store.upsertServer({
diff --git a/packages/server/tests/db/skillStoreContractSuite.ts b/packages/server/tests/db/skillStoreContractSuite.ts
index fd3821313..3931fb526 100644
--- a/packages/server/tests/db/skillStoreContractSuite.ts
+++ b/packages/server/tests/db/skillStoreContractSuite.ts
@@ -67,7 +67,7 @@ export function runSkillStoreContractSuite(getStore: () => ISkillStore): void {
expect(updated.created_at).toBe(created.created_at);
expect(Date.parse(updated.updated_at)).toBeGreaterThanOrEqual(Date.parse(created.updated_at));
- const skills = await store.listSkills(TENANT);
+ const skills = await store.listSkills({ tenant_id: TENANT, names: undefined });
expect(skills).toEqual([updated]);
});
@@ -89,8 +89,35 @@ export function runSkillStoreContractSuite(getStore: () => ISkillStore): void {
manifest: manifest(),
});
- const skills = await store.listSkills(TENANT);
+ const skills = await store.listSkills({ tenant_id: TENANT, names: undefined });
expect(skills.map(skill => skill.name)).toEqual(['algorithmic-art', 'web-artifacts']);
expect(skills.every(skill => skill.tenant_id === TENANT)).toBe(true);
});
+
+ it('listSkills filters by names and returns empty for an empty name list', async () => {
+ const store = getStore();
+ await store.upsertSkill({ tenant_id: TENANT, name: 'algorithmic-art', manifest: manifest() });
+ await store.upsertSkill({
+ tenant_id: TENANT,
+ name: 'web-artifacts',
+ manifest: manifest({
+ name: 'web-artifacts',
+ path: 'skills/web-artifacts-builder',
+ description: 'Build web artifacts.',
+ }),
+ });
+ await store.upsertSkill({
+ tenant_id: TENANT,
+ name: 'demo',
+ manifest: manifest({ name: 'demo', path: 'skills/demo', description: 'Demo skill.' }),
+ });
+
+ const filtered = await store.listSkills({
+ tenant_id: TENANT,
+ names: ['demo', 'missing', 'web-artifacts'],
+ });
+ expect(filtered.map(skill => skill.name)).toEqual(['demo', 'web-artifacts']);
+
+ await expect(store.listSkills({ tenant_id: TENANT, names: [] })).resolves.toEqual([]);
+ });
}
diff --git a/packages/server/tests/unit/runtime/getMcpConnection.test.ts b/packages/server/tests/unit/runtime/getMcpConnection.test.ts
index 0c37820ea..1cf253bf7 100644
--- a/packages/server/tests/unit/runtime/getMcpConnection.test.ts
+++ b/packages/server/tests/unit/runtime/getMcpConnection.test.ts
@@ -78,6 +78,10 @@ describe('getMcpConnection', () => {
tokenStore,
clientName: 'test-client',
});
+ expect(connection).toBeDefined();
+ if (connection === undefined) {
+ throw new Error('expected connection');
+ }
expect(connection.url).toBe(mcpUrl);
expect(typeof connection.headers).toBe('function');
@@ -131,7 +135,8 @@ describe('getMcpConnection', () => {
tokenStore,
clientName: 'test-client',
});
- if (typeof connection.headers !== 'function') {
+ expect(connection).toBeDefined();
+ if (connection === undefined || typeof connection.headers !== 'function') {
throw new Error('expected async headers resolver');
}
await expect(connection.headers()).resolves.toEqual({
@@ -157,6 +162,10 @@ describe('getMcpConnection', () => {
tokenStore,
clientName: 'test-client',
});
+ expect(connection).toBeDefined();
+ if (connection === undefined) {
+ throw new Error('expected connection');
+ }
expect(connection.url).toBe('https://mcp.open.example/mcp');
expect(connection.headers).toEqual({});
@@ -181,8 +190,24 @@ describe('getMcpConnection', () => {
tokenStore,
clientName: 'test-client',
});
+ expect(connection).toBeDefined();
+ if (connection === undefined) {
+ throw new Error('expected connection');
+ }
expect(connection.url).toBe('https://mcp.header.example/mcp');
expect(connection.headers).toEqual({ Authorization: 'Bearer static-token' });
});
+
+ it('returns undefined when the server is not registered', async () => {
+ await expect(
+ getMcpConnection({
+ tenant_id: TENANT_ID,
+ name: 'missing-mcp',
+ store: mcpServerStore,
+ tokenStore,
+ clientName: 'test-client',
+ }),
+ ).resolves.toBeUndefined();
+ });
});
diff --git a/packages/server/tests/unit/runtime/sessionResources.test.ts b/packages/server/tests/unit/runtime/sessionResources.test.ts
index 6cc2f64d9..85a0220f3 100644
--- a/packages/server/tests/unit/runtime/sessionResources.test.ts
+++ b/packages/server/tests/unit/runtime/sessionResources.test.ts
@@ -9,8 +9,8 @@ import { SqliteSandboxProviderStore } from '../../../src/db/sqlite/sandbox-provi
import { SqliteSkillStore } from '../../../src/db/sqlite/skill-store/SqliteSkillStore';
import { validateAgentSpec } from '../../../src/runtime/sessionResources';
-describe('validateAgentSpec sandbox gate', () => {
- async function setup() {
+describe('validateAgentSpec', () => {
+ async function setup(options?: { reasoningEfforts?: string[] | undefined }) {
const db = createSqliteDb(':memory:');
await migrateSqliteToLatest(db);
const modelProviderStore = new SqliteModelProviderStore(db);
@@ -24,7 +24,11 @@ describe('validateAgentSpec sandbox gate', () => {
{
model_id: 'test-model',
name: 'test-model',
- properties: { context_length: 128000, max_output_tokens: 4096 },
+ properties: {
+ context_length: 128000,
+ max_output_tokens: 4096,
+ ...(options?.reasoningEfforts !== undefined ? { reasoning_efforts: options.reasoningEfforts } : {}),
+ },
},
],
},
@@ -37,6 +41,110 @@ describe('validateAgentSpec sandbox gate', () => {
};
}
+ it('rejects malformed model FQN with 422', async () => {
+ const stores = await setup();
+ await expect(
+ validateAgentSpec({
+ spec: AgentSpecSchema.parse({
+ model: { name: 'not-a-fqn' },
+ instructions: 'test',
+ }),
+ tenant_id: TENANT_ID,
+ ...stores,
+ }),
+ ).rejects.toMatchObject({
+ status: 422,
+ message: expect.stringContaining('fully qualified "provider/model"'),
+ } satisfies Partial<HTTPException>);
+ });
+
+ it('rejects unknown model provider with 422', async () => {
+ const stores = await setup();
+ await expect(
+ validateAgentSpec({
+ spec: AgentSpecSchema.parse({
+ model: { name: 'missing-provider/test-model' },
+ instructions: 'test',
+ }),
+ tenant_id: TENANT_ID,
+ ...stores,
+ }),
+ ).rejects.toMatchObject({
+ status: 422,
+ message: expect.stringContaining('provider not configured'),
+ } satisfies Partial<HTTPException>);
+ });
+
+ it('rejects unknown model on provider with 422', async () => {
+ const stores = await setup();
+ await expect(
+ validateAgentSpec({
+ spec: AgentSpecSchema.parse({
+ model: { name: 'test-provider/missing-model' },
+ instructions: 'test',
+ }),
+ tenant_id: TENANT_ID,
+ ...stores,
+ }),
+ ).rejects.toMatchObject({
+ status: 422,
+ message: expect.stringContaining('not configured on provider'),
+ } satisfies Partial<HTTPException>);
+ });
+
+ it('rejects unsupported reasoning effort with 422', async () => {
+ const stores = await setup({ reasoningEfforts: ['low', 'high'] });
+ await expect(
+ validateAgentSpec({
+ spec: AgentSpecSchema.parse({
+ model: { name: 'test-provider/test-model', params: { reasoning_effort: 'medium' } },
+ instructions: 'test',
+ }),
+ tenant_id: TENANT_ID,
+ ...stores,
+ }),
+ ).rejects.toMatchObject({
+ status: 422,
+ message: expect.stringContaining('Reasoning effort "medium"'),
+ } satisfies Partial<HTTPException>);
+ });
+
+ it('rejects unknown MCP server with 422', async () => {
+ const stores = await setup();
+ await expect(
+ validateAgentSpec({
+ spec: AgentSpecSchema.parse({
+ model: { name: 'test-provider/test-model' },
+ instructions: 'test',
+ mcp_servers: [{ name: 'missing-mcp' }],
+ }),
+ tenant_id: TENANT_ID,
+ ...stores,
+ }),
+ ).rejects.toMatchObject({
+ status: 422,
+ message: expect.stringContaining('Unknown MCP server "missing-mcp"'),
+ } satisfies Partial<HTTPException>);
+ });
+
+ it('rejects unknown skill with 422', async () => {
+ const stores = await setup();
+ await expect(
+ validateAgentSpec({
+ spec: AgentSpecSchema.parse({
+ model: { name: 'test-provider/test-model' },
+ instructions: 'test',
+ skills: [{ name: 'missing-skill' }],
+ }),
+ tenant_id: TENANT_ID,
+ ...stores,
+ }),
+ ).rejects.toMatchObject({
+ status: 422,
+ message: expect.stringContaining('Unknown skill "missing-skill"'),
+ } satisfies Partial<HTTPException>);
+ });
+
it('rejects sandbox.enabled when no sandbox provider is configured', async () => {
const stores = await setup();
await expect(