pi-sap-aicore 0.3.3 → 0.3.4

package/CHANGELOG.md

@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.4] - 2026-07-01
+
+### Fixed
+
+- Direct GCP Vertex AI (Gemini) foundation route now sends pi tool schemas via
+  Gemini's `parametersJsonSchema` (full JSON Schema) instead of the legacy
+  `parameters` field (a restricted OpenAPI 3.0 subset). The legacy field rejected
+  common JSON Schema constructs with HTTP 400 — `const` ("Unknown name const")
+  and non-string `enum` values ("enum[0] (TYPE_STRING)") — which broke Gemini
+  foundation models (e.g. `gemini-3.5-flash`) on tool-heavy coding-agent turns.
+- SAP AI Core orchestration route no longer sends `reasoning_effort` alongside
+  function tools for `gpt-*` models. SAP's `/v1/chat/completions` (the only
+  endpoint reachable through the orchestration SDK) rejects that combination for
+  gpt-5.x with a 400 pointing to `/v1/responses`, which is a foundation-models
+  deployment endpoint the orchestration SDK cannot target. `reasoning_effort` is
+  still sent on text-only turns; SAP continues to spend reasoning tokens
+  internally on tool turns (governed by `max_completion_tokens`).
+
+### Added
+
+- Added `npm test` (`scripts/test-vertex-tool-schema.mjs`), a fast,
+  credential-free regression test asserting the Vertex/Gemini adapter emits
+  `parametersJsonSchema` and preserves `const`/boolean-`enum` constructs. Wired
+  into `prepublishOnly`. The live `validate:foundation` matrix also gained a
+  complex-tool-schema scenario that exercises the real HTTP tool path.
+
 ## [0.3.3] - 2026-07-01
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-sap-aicore",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "SAP AI Core (orchestration + foundation) provider for the pi coding agent",
   "license": "MIT",
   "author": "Tim Pearson (https://github.com/ttiimmaahh)",
@@ -31,8 +31,9 @@
   },
   "scripts": {
     "update-models": "node scripts/update-models.mjs",
+    "test": "node scripts/test-vertex-tool-schema.mjs",
     "validate:foundation": "node scripts/validate-foundation-executables.mjs",
-    "prepublishOnly": "tsc --noEmit"
+    "prepublishOnly": "tsc --noEmit && npm test"
   },
   "dependencies": {
     "@sap-ai-sdk/ai-api": "^2.12.0",

package/scripts/fixtures/complex-tool-extension.mjs

@@ -0,0 +1,59 @@
+// Test-only pi extension: registers a `record_choice` tool whose parameter
+// schema contains the exact JSON Schema constructs that Gemini's legacy
+// OpenAPI `parameters` field rejects (`const`, boolean `enum`, nested anyOf).
+//
+// Loaded by scripts/validate-foundation-executables.mjs to exercise the real
+// HTTP tool-schema path end-to-end. If an adapter serializes tool schemas
+// incorrectly, the provider returns HTTP 400 and the live scenario fails.
+//
+// The tool simply writes its stringified args to OUTPUT_FILE so the validator
+// can assert a real side effect (proving the model both received the schema
+// and successfully issued a tool call against it).
+
+import { writeFileSync } from "node:fs";
+
+/** @param {import("@earendil-works/pi-coding-agent").ExtensionAPI} pi */
+export default function (pi) {
+	pi.registerTool({
+		name: "record_choice",
+		label: "Record Choice",
+		description:
+			"Record a processing choice. Call this once with mode set to 'fast'.",
+		promptSnippet: "record_choice: record a processing choice",
+		// Raw JSON Schema (cast through unknown) with the constructs that broke
+		// Gemini's legacy `parameters` field. TypeBox typing is bypassed on
+		// purpose — we are validating wire serialization, not TS ergonomics.
+		parameters: /** @type {any} */ ({
+			type: "object",
+			properties: {
+				mode: {
+					anyOf: [{ const: "fast" }, { const: "slow" }],
+					description: "Processing mode",
+				},
+				verbose: {
+					anyOf: [{ type: "boolean" }, { enum: [false] }],
+					description: "Verbose flag",
+				},
+				steps: {
+					type: "array",
+					items: {
+						type: "object",
+						properties: {
+							kind: { anyOf: [{ const: "read" }, { const: "write" }] },
+						},
+					},
+				},
+			},
+			required: ["mode"],
+		}),
+		async execute(_toolCallId, params) {
+			const outputFile = process.env.COMPLEX_TOOL_OUTPUT_FILE;
+			if (outputFile) {
+				writeFileSync(outputFile, JSON.stringify(params ?? {}));
+			}
+			return {
+				content: [{ type: "text", text: "COMPLEX_TOOL_OK" }],
+			};
+		},
+	});
+}

package/scripts/test-vertex-tool-schema.mjs

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+// Offline regression test for the Vertex/Gemini tool-schema translation.
+//
+// The live validator (validate-foundation-executables.mjs) only ever sent the
+// trivial `bash` tool, whose schema is a flat object with one string property.
+// That never exercised the JSON Schema constructs Gemini's legacy `parameters`
+// (OpenAPI 3.0 subset) rejects — `const` and non-string `enum` values — so a
+// real 400 in production slipped past a "green" validation run.
+//
+// This test asserts the translator emits `parametersJsonSchema` (full JSON
+// Schema) rather than the legacy `parameters` field, and that the failing
+// constructs survive the translation intact. It makes NO network calls.
+//
+// Usage from repo root:
+//   node scripts/test-vertex-tool-schema.mjs
+
+import { pathToFileURL } from "node:url";
+import { join } from "node:path";
+
+const ROOT = new URL("..", import.meta.url).pathname;
+
+const { piContextToVertexGenerateContent } = await import(
+	pathToFileURL(join(ROOT, "src/translate-foundation-vertexai.ts")).href
+);
+
+let failures = 0;
+function check(condition, message) {
+	if (condition) {
+		console.log(`  ✓ ${message}`);
+		return;
+	}
+	console.error(`  ❌ ${message}`);
+	failures++;
+}
+
+// A schema that reproduces every class from the reported production 400:
+//   - `const` keyword                        → "Unknown name const"
+//   - boolean `enum` value (`false`)         → "enum[0] (TYPE_STRING), false"
+//   - nested anyOf/items                     → deep property paths in the error
+const context = {
+	systemPrompt: "system",
+	messages: [{ role: "user", content: "hi" }],
+	tools: [
+		{
+			name: "complex_tool",
+			description: "reproduces the reported Gemini 400 schema classes",
+			parameters: {
+				type: "object",
+				properties: {
+					mode: { anyOf: [{ const: "fast" }, { const: "slow" }] },
+					flag: { anyOf: [{ type: "boolean" }, { enum: [false] }] },
+					items: {
+						type: "array",
+						items: {
+							type: "object",
+							properties: {
+								kind: { anyOf: [{ const: "a" }, { const: "b" }] },
+							},
+						},
+					},
+				},
+				required: ["mode"],
+			},
+		},
+	],
+};
+
+const out = piContextToVertexGenerateContent(context);
+const fd = out.tools?.[0]?.functionDeclarations?.[0];
+
+check(!!fd, "tool is translated to a functionDeclaration");
+check(
+	fd && Object.hasOwn(fd, "parametersJsonSchema"),
+	"emits `parametersJsonSchema` (full JSON Schema field Gemini accepts)",
+);
+check(
+	fd && !Object.hasOwn(fd, "parameters"),
+	"does NOT emit legacy `parameters` (OpenAPI subset that 400s on const/enum)",
+);
+
+const serialized = JSON.stringify(fd?.parametersJsonSchema ?? {});
+check(
+	serialized.includes('"const"'),
+	"`const` keyword survives translation (not stripped/rewritten)",
+);
+check(
+	serialized.includes("false"),
+	"boolean `enum` value survives translation",
+);
+
+if (failures > 0) {
+	console.error(`\n❌ vertex tool-schema test: ${failures} check(s) failed`);
+	process.exit(1);
+}
+console.log("\n✅ vertex tool-schema translation test passed");

package/scripts/validate-foundation-executables.mjs

@@ -7,6 +7,14 @@
 //   - aws-bedrock   → Anthropic/Claude models
 //   - gcp-vertexai  → Gemini models
 //
+// Each family now also runs a complex-tool-schema scenario (const/enum/anyOf)
+// that reproduces the real HTTP tool path — the trivial bash tool alone never
+// exercised the JSON Schema constructs that broke Gemini's `parameters` field.
+//
+// For a fast, credential-free regression check of the Vertex tool-schema
+// serialization specifically, run:
+//   node scripts/test-vertex-tool-schema.mjs
+//
 // Usage from repo root:
 //   node scripts/validate-foundation-executables.mjs
 //
@@ -65,11 +73,12 @@ function runPi(args, options = {}) {
 	};
 }
 
-function baseArgs(model) {
+function baseArgs(model, extraExtensions = []) {
+	const extensions = ["-e", "./index.ts"];
+	for (const ext of extraExtensions) extensions.push("-e", ext);
 	return [
 		"--no-extensions",
-		"-e",
-		"./index.ts",
+		...extensions,
 		"--model",
 		`sap-aicore-foundation/${model}`,
 		"--no-context-files",
@@ -131,6 +140,48 @@ function validateToolUse(scenario, workDir) {
 	console.log(`  ✓ tool execution side effect`);
 }
 
+// Exercises the real HTTP tool-schema path with a schema containing the
+// constructs that broke Gemini in production (`const`, boolean `enum`, nested
+// anyOf). The trivial `bash` tool never covered these, which is why the
+// production 400 slipped past an otherwise-green validation run.
+function validateComplexToolSchema(scenario, workDir) {
+	const extension = join(ROOT, "scripts/fixtures/complex-tool-extension.mjs");
+	const outputFile = join(
+		workDir,
+		`${scenario.name.replaceAll("/", "-")}-complex-tool.json`,
+	);
+	const prompt =
+		"Call the record_choice tool exactly once with mode set to 'fast'. " +
+		"Then say done.";
+	const result = runPi([...baseArgs(scenario.model, [extension]), prompt], {
+		env: { ...process.env, COMPLEX_TOOL_OUTPUT_FILE: outputFile },
+	});
+	assert(
+		!/status code 400|Invalid (JSON payload|value at)|Unknown name/.test(
+			result.combined,
+		),
+		`${scenario.name} complex-tool scenario hit a schema rejection (HTTP 400)`,
+		truncate(result.combined),
+	);
+	assert(
+		result.status === 0,
+		`${scenario.name} complex-tool scenario exited ${result.status}`,
+		truncate(result.combined),
+	);
+	let actual = "";
+	try {
+		actual = readFileSync(outputFile, "utf8");
+	} catch {
+		// handled below
+	}
+	assert(
+		/"mode"\s*:\s*"fast"/.test(actual),
+		`${scenario.name} complex-tool scenario did not produce a valid tool call`,
+		`expected ${outputFile} to contain mode=fast\nmodel output:\n${truncate(result.combined)}`,
+	);
+	console.log(`  \u2713 complex tool schema (const/enum/anyOf)`);
+}
+
 function validateImage(scenario, workDir) {
 	const imagePath = join(workDir, "tiny.png");
 	writeFileSync(imagePath, tinyPng);
@@ -163,6 +214,7 @@ try {
 		console.log(`${scenario.name}  model=${scenario.model}`);
 		validateText(scenario);
 		validateToolUse(scenario, workDir);
+		validateComplexToolSchema(scenario, workDir);
 		if (!SKIP_IMAGE) validateImage(scenario, workDir);
 		console.log("");
 	}

package/src/stream.ts

@@ -363,6 +363,7 @@ function reasoningParams(
 	model: Model<Api>,
 	reasoning: string | undefined,
 	effectiveMaxTokens: number,
+	hasTools: boolean,
 ): Partial<LlmModelParams> {
 	if (!reasoning || reasoning === "off") return {};
 
@@ -402,6 +403,21 @@ function reasoningParams(
 		};
 	}
 	if (model.id.startsWith("gpt-")) {
+		// SAP orchestration's chat/completions endpoint does NOT accept
+		// `reasoning_effort` alongside function tools for gpt-5.x. Confirmed
+		// against SAP's Supported Parameters list (which omits reasoning_effort
+		// entirely) and the runtime 400 from gpt-5.5:
+		//   "Function tools with reasoning_effort are not supported for
+		//    gpt-5.5-...-dz-std in /v1/chat/completions. Please use /v1/responses
+		//    instead."
+		// The Responses API (/v1/responses) is a foundation-models deployment
+		// endpoint, unreachable through the orchestration SDK, so we can't switch
+		// endpoints here. Drop reasoning_effort on tool turns so the request
+		// succeeds; SAP still spends reasoning tokens internally (governed by
+		// max_completion_tokens / max_tokens). Text-only turns keep explicit
+		// reasoning depth. Applies to all gpt-* since SAP may tighten the older
+		// gpt-5/5.4 ids the same way.
+		if (hasTools) return {};
 		const effort =
 			model.thinkingLevelMap?.[
 				reasoning as keyof NonNullable<typeof model.thinkingLevelMap>
@@ -422,6 +438,7 @@ function modelSupportsTemperature(modelId: string): boolean {
 function buildLlmParams(
 	model: Model<Api>,
 	options: SimpleStreamOptions | undefined,
+	hasTools: boolean,
 ): LlmModelParams {
 	// Pi may pass a maxTokens budget smaller than the model's hard cap (e.g.
 	// to reserve room for thinking). Respect it; otherwise fall back to the
@@ -431,6 +448,7 @@ function buildLlmParams(
 		model,
 		options?.reasoning,
 		effectiveMaxTokens,
+		hasTools,
 	);
 	const params: LlmModelParams = {
 		max_tokens: effectiveMaxTokens,
@@ -655,7 +673,7 @@ export function streamSapAiCore(
 			const { messages, tools } = piContextToOrchestration(context);
 
 			const { OrchestrationClient } = await importOrchestration();
-			const llmParams = buildLlmParams(model, options);
+			const llmParams = buildLlmParams(model, options, tools.length > 0);
 
 			debugLog({
 				requestId,

package/src/translate-foundation-vertexai.ts

@@ -23,7 +23,11 @@ export type VertexTool = {
 	functionDeclarations: Array<{
 		name: string;
 		description: string;
-		parameters: Record<string, unknown>;
+		// Gemini's `parameters` field is a restricted OpenAPI 3.0 Schema subset
+		// that rejects `const` and non-string `enum` values. `parametersJsonSchema`
+		// accepts full JSON Schema (anyOf/oneOf/const/boolean enums), which is what
+		// pi tool definitions actually use. See pi-ai google-shared convertTools.
+		parametersJsonSchema: Record<string, unknown>;
 	}>;
 };
 
@@ -139,7 +143,11 @@ function piToolToVertexFunctionDeclaration(
 	return {
 		name: tool.name,
 		description: tool.description,
-		parameters: tool.parameters as unknown as Record<string, unknown>,
+		// Use `parametersJsonSchema` (full JSON Schema) instead of the legacy
+		// `parameters` OpenAPI subset. The latter rejects `const` and non-string
+		// `enum` values that pi tool schemas commonly contain, causing HTTP 400
+		// "Unknown name const" / "enum[0] (TYPE_STRING)" errors from Gemini.
+		parametersJsonSchema: tool.parameters as unknown as Record<string, unknown>,
 	};
 }