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.jsonindex 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.tsindex 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.tsnew file mode 100644index 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.jsonindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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 \`autocontent: { '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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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-proviimport { 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(