@benjamolina/pi-antigravity-guard 0.3.0 → 0.4.1

package/README.md

@@ -12,11 +12,35 @@ Install the package in Pi, then run:
 
 Choose browser login, or choose manual login and paste the complete callback URL. The loopback callback uses fixed port `51121`; browser callback failures, remote shells, and port conflicts can use the manual callback-URL flow.
 
-Start a fresh text-only session with `--no-builtin-tools` and disable any active extension-provided tools. That flag does not disable extension tools by itself. Tools, tool history, and images are unsupported and rejected rather than silently changed.
+## Text registration is not tool enablement
 
-## Supported static catalog
+All seven rows below are registered for text. The exact `antigravity-gemini-3.8-flash` `off` route is enabled for tools from recorded direct evidence; every other production route is **not enabled for tools**, so its context with a declaration, assistant tool call, or tool result fails locally before any network request. Text-only requests retain their released behavior.
 
-The provider registers only these evidence-admitted public IDs, in this order. `off` is available for every row even though it is omitted from Pi's level map; omitted reasoning also selects that row's `off` route. Unsupported levels are not advertised and are rejected before transport.
+| Public ID | Exposed Pi levels | Tool state | Admission |
+|---|---|---|---|
+| `antigravity-gemini-3.8-flash` | off, low, medium, high | Enabled (off) | pi-json-tool-loop/gemini-3.8-flash-off-v1 |
+| `antigravity-gemini-3.7-flash` | off, low, medium, high | Disabled | missing-direct-evidence |
+| `antigravity-gemini-3.6-flash` | off, low, medium, high | Disabled | missing-direct-evidence |
+| `antigravity-gemini-3.1-pro` | off, low, high | Disabled | missing-direct-evidence |
+| `antigravity-claude-sonnet-4.6` | off, high | Disabled | claude-continuity-unproven |
+| `antigravity-claude-opus-4.6-thinking` | off, high | Disabled | claude-continuity-unproven |
+| `antigravity-gpt-oss-120b` | off, medium | Disabled | missing-direct-evidence |
+
+`off` is available for every row even though it is omitted from Pi's level map; omitted reasoning also selects that row's `off` route. Unsupported levels are not advertised and are rejected before transport. `antigravity-gemini-3.5-flash` is not registered or advertised as supported because its recorded HTTP-200 response lacks the strict terminal metadata required for admission. A future `fixture-qualified` route remains disabled for ordinary tool use; only separately authorized direct validation for the exact route may make it enabled.
+
+Claude Sonnet and Claude Opus remain disabled until declaration, call, result replay, thinking-signature, resume, interruption, and continuation evidence is recorded for each exact route. Only Gemini 3.8 Flash `off` is enabled by this package release.
+
+## Opt-in direct tool-loop validation
+
+Maintainers can run `npm run build:pi` followed by `npx tsx scripts/pi-tool-loop-probe.ts --live --expect-enabled` to verify the directly admitted Gemini 3.8 Flash `off` route. The isolated runner invokes Pi in `--mode json`, passes the deterministic non-terminating `pi_evidence_echo` prompt positionally, drains its event stream, and completes after Pi emits `agent_end` and the child exits. It stores only the passing route and sanitized assertions; it never stores message contents, tool details, names, IDs, arguments, credentials, headers, or raw provider output. Other routes remain fail-closed.
+
+## Tool preflight boundaries
+
+Tool-bearing requests are never silently downgraded to text. When an exact route is eventually enabled, declarations are retained in order and omitted or `auto` choice serializes as `AUTO`; explicit `none` serializes as `NONE`. Forced, required, named, unknown, and constrained-sampling choices are rejected before transport.
+
+Schemas must use the documented strict object-rooted subset. Unsupported keywords, references, unions, lossy constraints, empty objects, and oversized input are rejected rather than cleaned. Tool results must match the exact call ID and name, remain text-only, and are replayed in assistant source-call order; image-bearing or ambiguous results are rejected. A missing persisted result uses the documented failed response only during context reconstruction.
+
+## Text catalog limits and safety
 
 | Public ID | Exposed Pi levels | Context / output |
 |---|---|---:|
@@ -28,16 +52,10 @@ The provider registers only these evidence-admitted public IDs, in this order. `
 | `antigravity-claude-opus-4.6-thinking` | off, high | 250,000 / 64,000 |
 | `antigravity-gpt-oss-120b` | off, medium | 131,072 / 32,768 |
 
-Gemini 3.8 remains compatible with the released mapping: `antigravity-gemini-3.8-flash` sends `gemini-3.8-flash-tiered`; `off` sends native `thinkingLevel: "low"` with hidden thoughts, and `low`, `medium`, and `high` send their matching native level with visible thoughts.
-
-`antigravity-gemini-3.5-flash` is not registered or advertised as supported because its recorded HTTP-200 response lacks the strict terminal metadata required for admission.
-
-## Limits and safety
-
 An explicit `maxTokens` must be a positive integer no greater than the row's output limit. For a route with a positive finite thinking budget, it must also be greater than that budget. When `maxTokens` is omitted, the provider uses 4,096 unless a larger finite thinking budget needs a 1,024-token answer reserve, always bounded by the row's output limit. Custom `thinkingBudgets` are unsupported and rejected.
 
 - Costs are reported as zero because subscription usage is unpriced, not because access is free.
 - The catalog is static: it performs no startup or runtime model discovery, catalog synchronization, or dynamic registration.
-- It has no account rotation, quota fallback, model substitution, tool support, or image support.
+- It has no account rotation, quota fallback, model substitution, image support, or enabled tools beyond the directly admitted Gemini 3.8 Flash `off` route.
 
 To remove it, disable or uninstall `@benjamolina/pi-antigravity-guard` and reload Pi. Removal does not delete Pi-managed credentials or revoke tokens.

package/dist/catalog.d.ts

@@ -1,5 +1,26 @@
 export type StandardReasoningLevel = "off" | "minimal" | "low" | "medium" | "high";
 type NativeThinkingLevel = "low" | "medium" | "high";
+export interface ToolEvidenceRef {
+    readonly record: string;
+    readonly revision: string;
+    readonly publicModelId: string;
+    readonly reasoning: StandardReasoningLevel;
+    readonly wireModel: string;
+}
+export type ToolCapability = {
+    readonly state: "disabled";
+    readonly contractRevision: 1;
+    readonly reason: "missing-direct-evidence" | "stale-or-conflicting-evidence" | "claude-continuity-unproven";
+} | {
+    readonly state: "fixture-qualified";
+    readonly contractRevision: 1;
+    readonly fixtureEvidence: ToolEvidenceRef;
+} | {
+    readonly state: "enabled";
+    readonly contractRevision: 1;
+    readonly fixtureEvidence: ToolEvidenceRef;
+    readonly directEvidence: ToolEvidenceRef;
+};
 type NativeRoute = {
     readonly wireModel: string;
     readonly thinking: {
@@ -19,6 +40,9 @@ type IntegerBudgetRoute = {
     };
 };
 export type GenerationRoute = NativeRoute | IntegerBudgetRoute;
+type ConfiguredGenerationRoute = GenerationRoute & {
+    readonly tools: ToolCapability;
+};
 export interface CatalogEntry {
     readonly publicId: string;
     readonly descriptor: {
@@ -27,7 +51,7 @@ export interface CatalogEntry {
         readonly contextWindow: number;
         readonly maxTokens: number;
     };
-    readonly routes: Readonly<Partial<Record<StandardReasoningLevel, GenerationRoute>>>;
+    readonly routes: Readonly<Partial<Record<StandardReasoningLevel, ConfiguredGenerationRoute>>>;
     readonly replay: {
         readonly kind: "same-public-model" | "strip";
     };
@@ -57,6 +81,7 @@ declare const CATALOG: readonly [{
                 readonly thinkingLevel: "low";
                 readonly includeThoughts: false;
             };
+            readonly tools: ToolCapability;
         };
         readonly low: {
             readonly wireModel: "gemini-3.8-flash-tiered";
@@ -65,6 +90,7 @@ declare const CATALOG: readonly [{
                 readonly thinkingLevel: "low";
                 readonly includeThoughts: true;
             };
+            readonly tools: ToolCapability;
         };
         readonly medium: {
             readonly wireModel: "gemini-3.8-flash-tiered";
@@ -73,6 +99,7 @@ declare const CATALOG: readonly [{
                 readonly thinkingLevel: "medium";
                 readonly includeThoughts: true;
             };
+            readonly tools: ToolCapability;
         };
         readonly high: {
             readonly wireModel: "gemini-3.8-flash-tiered";
@@ -81,6 +108,7 @@ declare const CATALOG: readonly [{
                 readonly thinkingLevel: "high";
                 readonly includeThoughts: true;
             };
+            readonly tools: ToolCapability;
         };
     };
     readonly replay: {
@@ -111,6 +139,7 @@ declare const CATALOG: readonly [{
                 readonly budget: 0;
                 readonly includeThoughts: false;
             };
+            readonly tools: ToolCapability;
         };
         readonly low: {
             readonly wireModel: "gemini-3.7-flash-low";
@@ -119,6 +148,7 @@ declare const CATALOG: readonly [{
                 readonly budget: 1000;
                 readonly includeThoughts: true;
             };
+            readonly tools: ToolCapability;
         };
         readonly medium: {
             readonly wireModel: "gemini-3.7-flash-medium";
@@ -127,6 +157,7 @@ declare const CATALOG: readonly [{
                 readonly budget: 4000;
                 readonly includeThoughts: true;
             };
+            readonly tools: ToolCapability;
         };
         readonly high: {
             readonly wireModel: "gemini-3.7-flash-high";
@@ -135,6 +166,7 @@ declare const CATALOG: readonly [{
                 readonly budget: -1;
                 readonly includeThoughts: true;
             };
+            readonly tools: ToolCapability;
         };
     };
     readonly replay: {
@@ -163,6 +195,7 @@ declare const CATALOG: readonly [{
             readonly thinking: {
                 readonly kind: "omit";
             };
+            readonly tools: ToolCapability;
         };
         readonly low: {
             readonly wireModel: "gemini-3.6-flash-low";
@@ -171,6 +204,7 @@ declare const CATALOG: readonly [{
                 readonly budget: 1000;
                 readonly includeThoughts: true;
             };
+            readonly tools: ToolCapability;
         };
         readonly medium: {
             readonly wireModel: "gemini-3.6-flash-medium";
@@ -179,6 +213,7 @@ declare const CATALOG: readonly [{
                 readonly budget: 4000;
                 readonly includeThoughts: true;
             };
+            readonly tools: ToolCapability;
         };
         readonly high: {
             readonly wireModel: "gemini-3.6-flash-high";
@@ -187,6 +222,7 @@ declare const CATALOG: readonly [{
                 readonly budget: -1;
                 readonly includeThoughts: true;
             };
+            readonly tools: ToolCapability;
         };
     };
     readonly replay: {
@@ -215,6 +251,7 @@ declare const CATALOG: readonly [{
             readonly thinking: {
                 readonly kind: "omit";
             };
+            readonly tools: ToolCapability;
         };
         readonly low: {
             readonly wireModel: "gemini-3.1-pro-low";
@@ -223,6 +260,7 @@ declare const CATALOG: readonly [{
                 readonly budget: 1001;
                 readonly includeThoughts: true;
             };
+            readonly tools: ToolCapability;
         };
         readonly high: {
             readonly wireModel: "gemini-pro-agent";
@@ -231,6 +269,7 @@ declare const CATALOG: readonly [{
                 readonly budget: 10001;
                 readonly includeThoughts: true;
             };
+            readonly tools: ToolCapability;
         };
     };
     readonly replay: {
@@ -261,6 +300,7 @@ declare const CATALOG: readonly [{
                 readonly budget: 0;
                 readonly includeThoughts: false;
             };
+            readonly tools: ToolCapability;
         };
         readonly high: {
             readonly wireModel: "claude-sonnet-4-6";
@@ -269,6 +309,7 @@ declare const CATALOG: readonly [{
                 readonly budget: 1024;
                 readonly includeThoughts: true;
             };
+            readonly tools: ToolCapability;
         };
     };
     readonly replay: {
@@ -299,6 +340,7 @@ declare const CATALOG: readonly [{
                 readonly budget: 0;
                 readonly includeThoughts: false;
             };
+            readonly tools: ToolCapability;
         };
         readonly high: {
             readonly wireModel: "claude-opus-4-6-thinking";
@@ -307,6 +349,7 @@ declare const CATALOG: readonly [{
                 readonly budget: 1024;
                 readonly includeThoughts: true;
             };
+            readonly tools: ToolCapability;
         };
     };
     readonly replay: {
@@ -335,6 +378,7 @@ declare const CATALOG: readonly [{
             readonly thinking: {
                 readonly kind: "omit";
             };
+            readonly tools: ToolCapability;
         };
         readonly medium: {
             readonly wireModel: "gpt-oss-120b-medium";
@@ -343,6 +387,7 @@ declare const CATALOG: readonly [{
                 readonly budget: 8192;
                 readonly includeThoughts: true;
             };
+            readonly tools: ToolCapability;
         };
     };
     readonly replay: {
@@ -356,6 +401,10 @@ declare const CATALOG: readonly [{
 type Catalog = typeof CATALOG;
 export type AntigravityPublicModelId = Catalog[number]["publicId"];
 export type AntigravityWireModelId = Catalog[number]["routes"][keyof Catalog[number]["routes"]]["wireModel"];
+/** Constructs deterministic capability data for hermetic serializer tests only. */
+export declare function createEnabledToolCapability(evidence: ToolEvidenceRef): Extract<ToolCapability, {
+    readonly state: "enabled";
+}>;
 export declare function defineCatalog<T extends readonly {
     readonly publicId: string;
     readonly descriptor?: CatalogEntry["descriptor"];
@@ -367,6 +416,13 @@ export declare function defineCatalog<T extends readonly {
 export declare function listCatalogEntries(): readonly CatalogEntry[];
 export declare function getCatalogEntry(publicId: unknown): CatalogEntry | undefined;
 export declare function resolveGenerationRoute(entry: CatalogEntry, reasoning: unknown): GenerationRoute;
+export interface GenerationSelection {
+    readonly level: StandardReasoningLevel;
+    readonly route: GenerationRoute;
+    readonly tools: ToolCapability;
+}
+export declare function resolveGenerationSelection(entry: CatalogEntry, reasoning: unknown): GenerationSelection;
+export declare function resolveToolCapability(capability: ToolCapability, publicModelId: string, reasoning: StandardReasoningLevel, wireModel: string): ToolCapability;
 export declare function toPiModelDescriptor(entry: CatalogEntry): {
     id: string;
     name: string;

package/dist/catalog.js

@@ -8,10 +8,10 @@ const CATALOG = freeze(defineCatalog([{
             maxTokens: 65_536,
         },
         routes: {
-            off: { wireModel: "gemini-3.8-flash-tiered", thinking: { kind: "native-level", thinkingLevel: "low", includeThoughts: false } },
-            low: { wireModel: "gemini-3.8-flash-tiered", thinking: { kind: "native-level", thinkingLevel: "low", includeThoughts: true } },
-            medium: { wireModel: "gemini-3.8-flash-tiered", thinking: { kind: "native-level", thinkingLevel: "medium", includeThoughts: true } },
-            high: { wireModel: "gemini-3.8-flash-tiered", thinking: { kind: "native-level", thinkingLevel: "high", includeThoughts: true } },
+            off: { wireModel: "gemini-3.8-flash-tiered", thinking: { kind: "native-level", thinkingLevel: "low", includeThoughts: false }, tools: enabled({ record: "pi-json-tool-loop", revision: "gemini-3.8-flash-off-v1", publicModelId: "antigravity-gemini-3.8-flash", reasoning: "off", wireModel: "gemini-3.8-flash-tiered" }) },
+            low: { wireModel: "gemini-3.8-flash-tiered", thinking: { kind: "native-level", thinkingLevel: "low", includeThoughts: true }, tools: disabled("missing-direct-evidence") },
+            medium: { wireModel: "gemini-3.8-flash-tiered", thinking: { kind: "native-level", thinkingLevel: "medium", includeThoughts: true }, tools: disabled("missing-direct-evidence") },
+            high: { wireModel: "gemini-3.8-flash-tiered", thinking: { kind: "native-level", thinkingLevel: "high", includeThoughts: true }, tools: disabled("missing-direct-evidence") },
         },
         replay: { kind: "same-public-model" },
         response: { kind: "gemini-envelope", family: "gemini" },
@@ -24,10 +24,10 @@ const CATALOG = freeze(defineCatalog([{
             maxTokens: 65_536,
         },
         routes: {
-            off: { wireModel: "gemini-3.7-flash-low", thinking: { kind: "budget", budget: 0, includeThoughts: false } },
-            low: { wireModel: "gemini-3.7-flash-low", thinking: { kind: "budget", budget: 1000, includeThoughts: true } },
-            medium: { wireModel: "gemini-3.7-flash-medium", thinking: { kind: "budget", budget: 4000, includeThoughts: true } },
-            high: { wireModel: "gemini-3.7-flash-high", thinking: { kind: "budget", budget: -1, includeThoughts: true } },
+            off: { wireModel: "gemini-3.7-flash-low", thinking: { kind: "budget", budget: 0, includeThoughts: false }, tools: disabled("missing-direct-evidence") },
+            low: { wireModel: "gemini-3.7-flash-low", thinking: { kind: "budget", budget: 1000, includeThoughts: true }, tools: disabled("missing-direct-evidence") },
+            medium: { wireModel: "gemini-3.7-flash-medium", thinking: { kind: "budget", budget: 4000, includeThoughts: true }, tools: disabled("missing-direct-evidence") },
+            high: { wireModel: "gemini-3.7-flash-high", thinking: { kind: "budget", budget: -1, includeThoughts: true }, tools: disabled("missing-direct-evidence") },
         },
         replay: { kind: "strip" },
         response: { kind: "gemini-envelope", family: "gemini" },
@@ -40,10 +40,10 @@ const CATALOG = freeze(defineCatalog([{
             maxTokens: 65_536,
         },
         routes: {
-            off: { wireModel: "gemini-3.6-flash-low", thinking: { kind: "omit" } },
-            low: { wireModel: "gemini-3.6-flash-low", thinking: { kind: "budget", budget: 1000, includeThoughts: true } },
-            medium: { wireModel: "gemini-3.6-flash-medium", thinking: { kind: "budget", budget: 4000, includeThoughts: true } },
-            high: { wireModel: "gemini-3.6-flash-high", thinking: { kind: "budget", budget: -1, includeThoughts: true } },
+            off: { wireModel: "gemini-3.6-flash-low", thinking: { kind: "omit" }, tools: disabled("missing-direct-evidence") },
+            low: { wireModel: "gemini-3.6-flash-low", thinking: { kind: "budget", budget: 1000, includeThoughts: true }, tools: disabled("missing-direct-evidence") },
+            medium: { wireModel: "gemini-3.6-flash-medium", thinking: { kind: "budget", budget: 4000, includeThoughts: true }, tools: disabled("missing-direct-evidence") },
+            high: { wireModel: "gemini-3.6-flash-high", thinking: { kind: "budget", budget: -1, includeThoughts: true }, tools: disabled("missing-direct-evidence") },
         },
         replay: { kind: "strip" },
         response: { kind: "gemini-envelope", family: "gemini" },
@@ -56,9 +56,9 @@ const CATALOG = freeze(defineCatalog([{
             maxTokens: 65_535,
         },
         routes: {
-            off: { wireModel: "gemini-3.1-pro-low", thinking: { kind: "omit" } },
-            low: { wireModel: "gemini-3.1-pro-low", thinking: { kind: "budget", budget: 1001, includeThoughts: true } },
-            high: { wireModel: "gemini-pro-agent", thinking: { kind: "budget", budget: 10001, includeThoughts: true } },
+            off: { wireModel: "gemini-3.1-pro-low", thinking: { kind: "omit" }, tools: disabled("missing-direct-evidence") },
+            low: { wireModel: "gemini-3.1-pro-low", thinking: { kind: "budget", budget: 1001, includeThoughts: true }, tools: disabled("missing-direct-evidence") },
+            high: { wireModel: "gemini-pro-agent", thinking: { kind: "budget", budget: 10001, includeThoughts: true }, tools: disabled("missing-direct-evidence") },
         },
         replay: { kind: "strip" },
         response: { kind: "gemini-envelope", family: "gemini" },
@@ -71,8 +71,8 @@ const CATALOG = freeze(defineCatalog([{
             maxTokens: 64_000,
         },
         routes: {
-            off: { wireModel: "claude-sonnet-4-6", thinking: { kind: "budget", budget: 0, includeThoughts: false } },
-            high: { wireModel: "claude-sonnet-4-6", thinking: { kind: "budget", budget: 1024, includeThoughts: true } },
+            off: { wireModel: "claude-sonnet-4-6", thinking: { kind: "budget", budget: 0, includeThoughts: false }, tools: disabled("claude-continuity-unproven") },
+            high: { wireModel: "claude-sonnet-4-6", thinking: { kind: "budget", budget: 1024, includeThoughts: true }, tools: disabled("claude-continuity-unproven") },
         },
         replay: { kind: "strip" },
         response: { kind: "gemini-envelope", family: "claude" },
@@ -85,8 +85,8 @@ const CATALOG = freeze(defineCatalog([{
             maxTokens: 64_000,
         },
         routes: {
-            off: { wireModel: "claude-opus-4-6-thinking", thinking: { kind: "budget", budget: 0, includeThoughts: false } },
-            high: { wireModel: "claude-opus-4-6-thinking", thinking: { kind: "budget", budget: 1024, includeThoughts: true } },
+            off: { wireModel: "claude-opus-4-6-thinking", thinking: { kind: "budget", budget: 0, includeThoughts: false }, tools: disabled("claude-continuity-unproven") },
+            high: { wireModel: "claude-opus-4-6-thinking", thinking: { kind: "budget", budget: 1024, includeThoughts: true }, tools: disabled("claude-continuity-unproven") },
         },
         replay: { kind: "strip" },
         response: { kind: "gemini-envelope", family: "claude" },
@@ -99,13 +99,23 @@ const CATALOG = freeze(defineCatalog([{
             maxTokens: 32_768,
         },
         routes: {
-            off: { wireModel: "gpt-oss-120b-medium", thinking: { kind: "omit" } },
-            medium: { wireModel: "gpt-oss-120b-medium", thinking: { kind: "budget", budget: 8192, includeThoughts: true } },
+            off: { wireModel: "gpt-oss-120b-medium", thinking: { kind: "omit" }, tools: disabled("missing-direct-evidence") },
+            medium: { wireModel: "gpt-oss-120b-medium", thinking: { kind: "budget", budget: 8192, includeThoughts: true }, tools: disabled("missing-direct-evidence") },
         },
         replay: { kind: "strip" },
         response: { kind: "gemini-envelope", family: "gpt-oss" },
     }]));
 const lookup = new Map(CATALOG.map((entry) => [entry.publicId, entry]));
+function disabled(reason) {
+    return { state: "disabled", contractRevision: 1, reason };
+}
+function enabled(evidence) {
+    return { state: "enabled", contractRevision: 1, fixtureEvidence: evidence, directEvidence: evidence };
+}
+/** Constructs deterministic capability data for hermetic serializer tests only. */
+export function createEnabledToolCapability(evidence) {
+    return freeze({ state: "enabled", contractRevision: 1, fixtureEvidence: evidence, directEvidence: evidence });
+}
 function freeze(value) {
     if (typeof value === "object" && value !== null) {
         Object.freeze(value);
@@ -147,10 +157,25 @@ export function getCatalogEntry(publicId) {
     return typeof publicId === "string" ? lookup.get(publicId) : undefined;
 }
 export function resolveGenerationRoute(entry, reasoning) {
+    return resolveGenerationSelection(entry, reasoning).route;
+}
+export function resolveGenerationSelection(entry, reasoning) {
     const level = reasoning === undefined || reasoning === "off" ? "off" : reasoning;
     if (typeof level !== "string" || !entry.routes[level])
         throw new Error("Unsupported reasoning level");
-    return entry.routes[level];
+    const typedLevel = level;
+    const configured = entry.routes[typedLevel];
+    const { tools, ...route } = configured;
+    return { level: typedLevel, route, tools: resolveToolCapability(tools, entry.publicId, typedLevel, route.wireModel) };
+}
+export function resolveToolCapability(capability, publicModelId, reasoning, wireModel) {
+    if (capability.state === "disabled")
+        return capability;
+    const evidence = capability.state === "enabled" ? [capability.fixtureEvidence, capability.directEvidence] : [capability.fixtureEvidence];
+    if (capability.contractRevision !== 1 || evidence.some((item) => item.publicModelId !== publicModelId || item.reasoning !== reasoning || item.wireModel !== wireModel)) {
+        return freeze(disabled("stale-or-conflicting-evidence"));
+    }
+    return capability;
 }
 export function toPiModelDescriptor(entry) {
     return {

package/dist/context.d.ts

@@ -1,4 +1,6 @@
 import type { Context, Model, SimpleStreamOptions } from "@earendil-works/pi-ai";
+import { type GenerationSelection } from "./catalog.ts";
+import { type ToolReplayDiagnostics } from "./tool-context.ts";
 interface Part {
     text: string;
     thought?: true;
@@ -6,7 +8,12 @@ interface Part {
 }
 interface Content {
     role: "user" | "model";
-    parts: Part[];
+    parts: object[];
+}
+interface GeminiFunctionDeclaration {
+    readonly name: string;
+    readonly description: string;
+    readonly parametersJsonSchema: object;
 }
 export interface GenerationRequest {
     project: string;
@@ -16,6 +23,14 @@ export interface GenerationRequest {
         systemInstruction?: {
             parts: Part[];
         };
+        tools?: {
+            functionDeclarations: readonly GeminiFunctionDeclaration[];
+        }[];
+        toolConfig?: {
+            functionCallingConfig: {
+                mode: "AUTO" | "NONE";
+            };
+        };
         generationConfig: {
             temperature: number;
             maxOutputTokens: number;
@@ -41,5 +56,6 @@ export interface SerializeTextContextInput {
 }
 export declare class ContextSerializationError extends Error {
 }
+export declare function serializeContext(input: SerializeTextContextInput, injectedSelection?: GenerationSelection, onDiagnostics?: (diagnostics: ToolReplayDiagnostics) => void): GenerationRequest;
 export declare function serializeTextContext(input: SerializeTextContextInput): GenerationRequest;
 export {};

package/dist/context.js

@@ -1,10 +1,47 @@
-import { getCatalogEntry, resolveGenerationRoute } from "./catalog.js";
+import { getCatalogEntry, resolveGenerationSelection } from "./catalog.js";
+import { hasToolContext, prepareToolContext, replayToolHistory } from "./tool-context.js";
 const MAX_TEXT_BYTES = 8 * 1024 * 1024;
 const PROVIDER = "antigravity-guard";
 const RESERVED_HEADERS = new Set(["authorization", "host", "content-type", "content-length"]);
 const THINKING_LEVELS = ["low", "medium", "high"];
 export class ContextSerializationError extends Error {
 }
+export function serializeContext(input, injectedSelection, onDiagnostics) {
+    const context = input.context;
+    if (!hasToolContext(context))
+        return serializeTextContext(input);
+    const options = input.options;
+    const entry = isRecord(input.model) ? getCatalogEntry(field(input.model, "id", true)) : undefined;
+    if (!entry || !isRecord(context))
+        return serializeTextContext(input);
+    const selected = resolveGenerationSelection(entry, isRecord(options) ? option(options, "reasoning") : undefined);
+    const selection = injectedSelection ?? selected;
+    if (selection.level !== selected.level || selection.route.wireModel !== selected.route.wireModel)
+        fail("Invalid tool capability selection.");
+    if (selection.tools.state !== "enabled")
+        fail(capabilityError(entry.publicId, selection.level, selection.tools));
+    const prepared = prepareToolContext(field(context, "tools") ?? [], isRecord(options) ? field(options, "toolChoice") : undefined);
+    const { tools: _tools, messages, ...textContext } = context;
+    const { toolChoice: _choice, ...textOptions } = isRecord(options) ? options : {};
+    const text = serializeTextContext({ ...input, context: { ...textContext, messages: [{ role: "user", content: "placeholder", timestamp: 0 }] }, options: textOptions });
+    const sameModel = (message) => field(message, "role") === "assistant" && entry.replay.kind === "same-public-model" && isSameProviderAndModel(message, entry.publicId);
+    const signedToolReplay = geminiRequiresSignedToolReplay(selection.route.wireModel) ? {
+        requireSignedToolCalls: true,
+        isSameModel: sameModel,
+        toolCallSignature: (part, message) => sameModel(message) ? validThoughtSignature(field(part, "thoughtSignature")) : undefined,
+    } : undefined;
+    const contents = replayToolHistory(isDenseArray(messages), (part, message) => messagePart(part, field(message, "role") === "assistant", sameModel(message)), onDiagnostics, signedToolReplay, prepared?.declarations.length ?? 0);
+    const { systemInstruction, generationConfig } = text.request;
+    return { ...text, request: {
+            contents,
+            ...(systemInstruction ? { systemInstruction } : {}),
+            ...(prepared ? {
+                tools: [{ functionDeclarations: prepared.declarations.map(({ name, description, parameters }) => ({ name, description, parametersJsonSchema: parameters })) }],
+                ...(prepared.mode === "NONE" ? { toolConfig: { functionCallingConfig: { mode: "NONE" } } } : {}),
+            } : {}),
+            generationConfig,
+        } };
+}
 export function serializeTextContext(input) {
     try {
         if (!isRecord(input))
@@ -17,7 +54,10 @@ export function serializeTextContext(input) {
         const entry = isRecord(model) ? getCatalogEntry(field(model, "id", true)) : undefined;
         if (!isRecord(context) || !entry || typeof project !== "string" || typeof requestId !== "string")
             fail("Invalid text context.");
-        const route = resolveGenerationRoute(entry, option(options, "reasoning"));
+        const selection = resolveGenerationSelection(entry, option(options, "reasoning"));
+        const route = selection.route;
+        if (isToolBearingContext(context) && selection.tools.state !== "enabled")
+            fail(capabilityError(entry.publicId, selection.level, selection.tools));
         const systemPrompt = field(context, "systemPrompt");
         const tools = field(context, "tools");
         if (systemPrompt !== undefined && typeof systemPrompt !== "string")
@@ -62,42 +102,64 @@ export function serializeTextContext(input) {
         fail("Invalid text context.");
     }
 }
+function capabilityError(publicId, reasoning, capability) {
+    const reason = capability.state === "disabled" ? capability.reason : capability.state;
+    return `PI_TOOL_CAPABILITY_NOT_ENABLED: ${publicId}/${reasoning} is ${capability.state} (${reason}).`;
+}
+function isToolBearingContext(context) {
+    const tools = field(context, "tools");
+    if (tools !== undefined && isDenseArray(tools).length > 0)
+        return true;
+    const messages = isDenseArray(field(context, "messages", true));
+    for (const message of messages) {
+        if (!isRecord(message))
+            continue;
+        if (field(message, "role") === "toolResult")
+            return true;
+        const content = field(message, "content");
+        if (!Array.isArray(content))
+            continue;
+        for (const part of content)
+            if (isRecord(part) && field(part, "type") === "toolCall")
+                return true;
+    }
+    return false;
+}
 function messageParts(content, assistant, sameProviderAndModel) {
     if (typeof content === "string")
         return content ? [{ text: content }] : fail("A text conversation is required.");
     const parts = isDenseArray(content);
     if (!parts.length)
         fail("A text conversation is required.");
-    return parts.map((part) => {
-        if (!isRecord(part))
+    return parts.map((part) => messagePart(isRecord(part) ? part : fail("Only text context is supported by this provider."), assistant, sameProviderAndModel));
+}
+function messagePart(part, assistant, sameProviderAndModel) {
+    const type = field(part, "type", true);
+    if (type === "text") {
+        const text = field(part, "text", true);
+        if (typeof text !== "string")
             fail("Only text context is supported by this provider.");
-        const type = field(part, "type", true);
-        if (type === "text") {
-            const text = field(part, "text", true);
-            if (typeof text !== "string")
-                fail("Only text context is supported by this provider.");
-            const thoughtSignature = sameProviderAndModel ? validThoughtSignature(field(part, "textSignature")) : undefined;
-            if (!text && !thoughtSignature)
-                fail("Only text context is supported by this provider.");
-            return { text, ...(thoughtSignature ? { thoughtSignature } : {}) };
-        }
-        if (type === "thinking" && assistant && sameProviderAndModel) {
-            const text = field(part, "thinking", true);
-            if (typeof text !== "string")
-                fail("Only text context is supported by this provider.");
-            const thoughtSignature = validThoughtSignature(field(part, "thinkingSignature"));
-            if (!text && !thoughtSignature)
-                fail("Only text context is supported by this provider.");
-            return { thought: true, text, ...(thoughtSignature ? { thoughtSignature } : {}) };
-        }
-        if (type === "thinking" && assistant) {
-            const text = field(part, "thinking", true);
-            if (typeof text !== "string" || !text)
-                fail("Only text context is supported by this provider.");
-            return { text };
-        }
-        fail("Only text context is supported by this provider.");
-    });
+        const thoughtSignature = sameProviderAndModel ? validThoughtSignature(field(part, "textSignature")) : undefined;
+        if (!text && !thoughtSignature)
+            fail("Only text context is supported by this provider.");
+        return { text, ...(thoughtSignature ? { thoughtSignature } : {}) };
+    }
+    if (type === "thinking" && assistant && sameProviderAndModel) {
+        const text = field(part, "thinking", true);
+        if (typeof text !== "string")
+            fail("Only text context is supported by this provider.");
+        const thoughtSignature = validThoughtSignature(field(part, "thinkingSignature"));
+        if (!text && !thoughtSignature)
+            fail("Only text context is supported by this provider.");
+        return { thought: true, text, ...(thoughtSignature ? { thoughtSignature } : {}) };
+    }
+    if (type === "thinking" && assistant) {
+        const text = field(part, "thinking", true);
+        if (typeof text !== "string" || !text)
+            fail("Only text context is supported by this provider.");
+        return { text };
+    }
+    fail("Only text context is supported by this provider.");
 }
 function isSameProviderAndModel(message, publicId) {
     return field(message, "provider") === PROVIDER && field(message, "model") === publicId;
@@ -119,6 +181,10 @@ function resolveOutputTokens(maxTokens, maxAllowed, thinking) {
     }
     return thinking.kind === "budget" && thinking.budget > 0 ? Math.max(4096, thinking.budget + 1024) : 4096;
 }
+function geminiRequiresSignedToolReplay(wireModel) {
+    const match = /^gemini-(\d+)(?:[.-])/.exec(wireModel);
+    return match !== null && Number(match[1]) >= 3;
+}
 function validThoughtSignature(value) {
     if (typeof value !== "string" || !value || value.length % 4 !== 0)
         return undefined;