@benjamolina/pi-antigravity-guard 0.2.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # Pi Antigravity Guard
 
-`@benjamolina/pi-antigravity-guard` is a Pi extension that registers the text-only `antigravity-guard` provider. It exposes exactly one selectable model, `antigravity-gemini-3.8-flash`, which is sent to Antigravity as `gemini-3.8-flash-tiered`.
+`@benjamolina/pi-antigravity-guard` is a static Pi extension that registers the text-only `antigravity-guard` provider. It uses Pi-managed OAuth credentials and the existing Antigravity OAuth endpoint and quota path; it does not provide alternate credential routes, quota pools, fallback, or model substitution.
 
 ## Use
 
@@ -12,15 +12,46 @@ 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
 
-`@benjamolina/pi-antigravity-guard@0.2.0` supports Pi reasoning levels `low`, `medium`, and `high`. An authorized live matrix against `gemini-3.8-flash-tiered` confirmed all three levels; `minimal` was rejected twice with zero usage and is not exposed. Each supported level is sent as the matching native `thinkingLevel` with visible thoughts enabled. When reasoning is off or omitted, the request uses native `low` thinking without returning visible thoughts. Custom `thinkingBudgets` are unsupported and rejected.
+All seven rows below are registered for text. Every production route is currently **not enabled for tools**, so a context with a declaration, assistant tool call, or tool result fails locally before any network request. Text-only requests retain their released behavior.
 
-## Limits and safety
+| Public ID | Exposed Pi levels | Tool state | Why tools are unavailable |
+|---|---|---|---|
+| `antigravity-gemini-3.8-flash` | off, low, medium, high | Disabled | missing-direct-evidence |
+| `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. No route is enabled by this package release.
+
+## 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 |
+|---|---|---:|
+| `antigravity-gemini-3.8-flash` | off, low, medium, high | 1,048,576 / 65,536 |
+| `antigravity-gemini-3.7-flash` | off, low, medium, high | 1,048,576 / 65,536 |
+| `antigravity-gemini-3.6-flash` | off, low, medium, high | 1,048,576 / 65,536 |
+| `antigravity-gemini-3.1-pro` | off, low, high | 1,048,576 / 65,535 |
+| `antigravity-claude-sonnet-4.6` | off, high | 250,000 / 64,000 |
+| `antigravity-claude-opus-4.6-thinking` | off, high | 250,000 / 64,000 |
+| `antigravity-gpt-oss-120b` | off, medium | 131,072 / 32,768 |
+
+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.
 
-- This provider stores credentials through Pi's OAuth lifecycle and never reads or changes OpenCode account files; each is independent.
 - Costs are reported as zero because subscription usage is unpriced, not because access is free.
-- The public-to-wire model mapping remains separate from availability and entitlement. The documented reasoning levels are limited to the authorized live matrix results above.
-- It has no account rotation, quota fallback, model substitution, or tool support.
+- 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, image support, or enabled tools.
 
 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

@@ -0,0 +1,446 @@
+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: {
+        readonly kind: "native-level";
+        readonly thinkingLevel: NativeThinkingLevel;
+        readonly includeThoughts: boolean;
+    };
+};
+type IntegerBudgetRoute = {
+    readonly wireModel: string;
+    readonly thinking: {
+        readonly kind: "budget";
+        readonly budget: number;
+        readonly includeThoughts: boolean;
+    } | {
+        readonly kind: "omit";
+    };
+};
+export type GenerationRoute = NativeRoute | IntegerBudgetRoute;
+type ConfiguredGenerationRoute = GenerationRoute & {
+    readonly tools: ToolCapability;
+};
+export interface CatalogEntry {
+    readonly publicId: string;
+    readonly descriptor: {
+        readonly name: string;
+        readonly thinkingLevelMap: Readonly<Record<"minimal" | "low" | "medium" | "high", string | null>>;
+        readonly contextWindow: number;
+        readonly maxTokens: number;
+    };
+    readonly routes: Readonly<Partial<Record<StandardReasoningLevel, ConfiguredGenerationRoute>>>;
+    readonly replay: {
+        readonly kind: "same-public-model" | "strip";
+    };
+    readonly response: {
+        readonly kind: "gemini-envelope";
+        readonly family: "gemini" | "claude" | "gpt-oss";
+    };
+}
+declare const CATALOG: readonly [{
+    readonly publicId: "antigravity-gemini-3.8-flash";
+    readonly descriptor: {
+        readonly name: "Gemini 3.8 Flash (Antigravity, text only)";
+        readonly thinkingLevelMap: {
+            readonly minimal: null;
+            readonly low: "low";
+            readonly medium: "medium";
+            readonly high: "high";
+        };
+        readonly contextWindow: 1048576;
+        readonly maxTokens: 65536;
+    };
+    readonly routes: {
+        readonly off: {
+            readonly wireModel: "gemini-3.8-flash-tiered";
+            readonly thinking: {
+                readonly kind: "native-level";
+                readonly thinkingLevel: "low";
+                readonly includeThoughts: false;
+            };
+            readonly tools: ToolCapability;
+        };
+        readonly low: {
+            readonly wireModel: "gemini-3.8-flash-tiered";
+            readonly thinking: {
+                readonly kind: "native-level";
+                readonly thinkingLevel: "low";
+                readonly includeThoughts: true;
+            };
+            readonly tools: ToolCapability;
+        };
+        readonly medium: {
+            readonly wireModel: "gemini-3.8-flash-tiered";
+            readonly thinking: {
+                readonly kind: "native-level";
+                readonly thinkingLevel: "medium";
+                readonly includeThoughts: true;
+            };
+            readonly tools: ToolCapability;
+        };
+        readonly high: {
+            readonly wireModel: "gemini-3.8-flash-tiered";
+            readonly thinking: {
+                readonly kind: "native-level";
+                readonly thinkingLevel: "high";
+                readonly includeThoughts: true;
+            };
+            readonly tools: ToolCapability;
+        };
+    };
+    readonly replay: {
+        readonly kind: "same-public-model";
+    };
+    readonly response: {
+        readonly kind: "gemini-envelope";
+        readonly family: "gemini";
+    };
+}, {
+    readonly publicId: "antigravity-gemini-3.7-flash";
+    readonly descriptor: {
+        readonly name: "Gemini 3.7 Flash (Antigravity, text only)";
+        readonly thinkingLevelMap: {
+            readonly minimal: null;
+            readonly low: "low";
+            readonly medium: "medium";
+            readonly high: "high";
+        };
+        readonly contextWindow: 1048576;
+        readonly maxTokens: 65536;
+    };
+    readonly routes: {
+        readonly off: {
+            readonly wireModel: "gemini-3.7-flash-low";
+            readonly thinking: {
+                readonly kind: "budget";
+                readonly budget: 0;
+                readonly includeThoughts: false;
+            };
+            readonly tools: ToolCapability;
+        };
+        readonly low: {
+            readonly wireModel: "gemini-3.7-flash-low";
+            readonly thinking: {
+                readonly kind: "budget";
+                readonly budget: 1000;
+                readonly includeThoughts: true;
+            };
+            readonly tools: ToolCapability;
+        };
+        readonly medium: {
+            readonly wireModel: "gemini-3.7-flash-medium";
+            readonly thinking: {
+                readonly kind: "budget";
+                readonly budget: 4000;
+                readonly includeThoughts: true;
+            };
+            readonly tools: ToolCapability;
+        };
+        readonly high: {
+            readonly wireModel: "gemini-3.7-flash-high";
+            readonly thinking: {
+                readonly kind: "budget";
+                readonly budget: -1;
+                readonly includeThoughts: true;
+            };
+            readonly tools: ToolCapability;
+        };
+    };
+    readonly replay: {
+        readonly kind: "strip";
+    };
+    readonly response: {
+        readonly kind: "gemini-envelope";
+        readonly family: "gemini";
+    };
+}, {
+    readonly publicId: "antigravity-gemini-3.6-flash";
+    readonly descriptor: {
+        readonly name: "Gemini 3.6 Flash (Antigravity, text only)";
+        readonly thinkingLevelMap: {
+            readonly minimal: null;
+            readonly low: "low";
+            readonly medium: "medium";
+            readonly high: "high";
+        };
+        readonly contextWindow: 1048576;
+        readonly maxTokens: 65536;
+    };
+    readonly routes: {
+        readonly off: {
+            readonly wireModel: "gemini-3.6-flash-low";
+            readonly thinking: {
+                readonly kind: "omit";
+            };
+            readonly tools: ToolCapability;
+        };
+        readonly low: {
+            readonly wireModel: "gemini-3.6-flash-low";
+            readonly thinking: {
+                readonly kind: "budget";
+                readonly budget: 1000;
+                readonly includeThoughts: true;
+            };
+            readonly tools: ToolCapability;
+        };
+        readonly medium: {
+            readonly wireModel: "gemini-3.6-flash-medium";
+            readonly thinking: {
+                readonly kind: "budget";
+                readonly budget: 4000;
+                readonly includeThoughts: true;
+            };
+            readonly tools: ToolCapability;
+        };
+        readonly high: {
+            readonly wireModel: "gemini-3.6-flash-high";
+            readonly thinking: {
+                readonly kind: "budget";
+                readonly budget: -1;
+                readonly includeThoughts: true;
+            };
+            readonly tools: ToolCapability;
+        };
+    };
+    readonly replay: {
+        readonly kind: "strip";
+    };
+    readonly response: {
+        readonly kind: "gemini-envelope";
+        readonly family: "gemini";
+    };
+}, {
+    readonly publicId: "antigravity-gemini-3.1-pro";
+    readonly descriptor: {
+        readonly name: "Gemini 3.1 Pro (Antigravity, text only)";
+        readonly thinkingLevelMap: {
+            readonly minimal: null;
+            readonly low: "low";
+            readonly medium: null;
+            readonly high: "high";
+        };
+        readonly contextWindow: 1048576;
+        readonly maxTokens: 65535;
+    };
+    readonly routes: {
+        readonly off: {
+            readonly wireModel: "gemini-3.1-pro-low";
+            readonly thinking: {
+                readonly kind: "omit";
+            };
+            readonly tools: ToolCapability;
+        };
+        readonly low: {
+            readonly wireModel: "gemini-3.1-pro-low";
+            readonly thinking: {
+                readonly kind: "budget";
+                readonly budget: 1001;
+                readonly includeThoughts: true;
+            };
+            readonly tools: ToolCapability;
+        };
+        readonly high: {
+            readonly wireModel: "gemini-pro-agent";
+            readonly thinking: {
+                readonly kind: "budget";
+                readonly budget: 10001;
+                readonly includeThoughts: true;
+            };
+            readonly tools: ToolCapability;
+        };
+    };
+    readonly replay: {
+        readonly kind: "strip";
+    };
+    readonly response: {
+        readonly kind: "gemini-envelope";
+        readonly family: "gemini";
+    };
+}, {
+    readonly publicId: "antigravity-claude-sonnet-4.6";
+    readonly descriptor: {
+        readonly name: "Claude Sonnet 4.6 (Antigravity, text only)";
+        readonly thinkingLevelMap: {
+            readonly minimal: null;
+            readonly low: null;
+            readonly medium: null;
+            readonly high: "high";
+        };
+        readonly contextWindow: 250000;
+        readonly maxTokens: 64000;
+    };
+    readonly routes: {
+        readonly off: {
+            readonly wireModel: "claude-sonnet-4-6";
+            readonly thinking: {
+                readonly kind: "budget";
+                readonly budget: 0;
+                readonly includeThoughts: false;
+            };
+            readonly tools: ToolCapability;
+        };
+        readonly high: {
+            readonly wireModel: "claude-sonnet-4-6";
+            readonly thinking: {
+                readonly kind: "budget";
+                readonly budget: 1024;
+                readonly includeThoughts: true;
+            };
+            readonly tools: ToolCapability;
+        };
+    };
+    readonly replay: {
+        readonly kind: "strip";
+    };
+    readonly response: {
+        readonly kind: "gemini-envelope";
+        readonly family: "claude";
+    };
+}, {
+    readonly publicId: "antigravity-claude-opus-4.6-thinking";
+    readonly descriptor: {
+        readonly name: "Claude Opus 4.6 Thinking (Antigravity, text only)";
+        readonly thinkingLevelMap: {
+            readonly minimal: null;
+            readonly low: null;
+            readonly medium: null;
+            readonly high: "high";
+        };
+        readonly contextWindow: 250000;
+        readonly maxTokens: 64000;
+    };
+    readonly routes: {
+        readonly off: {
+            readonly wireModel: "claude-opus-4-6-thinking";
+            readonly thinking: {
+                readonly kind: "budget";
+                readonly budget: 0;
+                readonly includeThoughts: false;
+            };
+            readonly tools: ToolCapability;
+        };
+        readonly high: {
+            readonly wireModel: "claude-opus-4-6-thinking";
+            readonly thinking: {
+                readonly kind: "budget";
+                readonly budget: 1024;
+                readonly includeThoughts: true;
+            };
+            readonly tools: ToolCapability;
+        };
+    };
+    readonly replay: {
+        readonly kind: "strip";
+    };
+    readonly response: {
+        readonly kind: "gemini-envelope";
+        readonly family: "claude";
+    };
+}, {
+    readonly publicId: "antigravity-gpt-oss-120b";
+    readonly descriptor: {
+        readonly name: "GPT-OSS 120B (Antigravity, text only)";
+        readonly thinkingLevelMap: {
+            readonly minimal: null;
+            readonly low: null;
+            readonly medium: "medium";
+            readonly high: null;
+        };
+        readonly contextWindow: 131072;
+        readonly maxTokens: 32768;
+    };
+    readonly routes: {
+        readonly off: {
+            readonly wireModel: "gpt-oss-120b-medium";
+            readonly thinking: {
+                readonly kind: "omit";
+            };
+            readonly tools: ToolCapability;
+        };
+        readonly medium: {
+            readonly wireModel: "gpt-oss-120b-medium";
+            readonly thinking: {
+                readonly kind: "budget";
+                readonly budget: 8192;
+                readonly includeThoughts: true;
+            };
+            readonly tools: ToolCapability;
+        };
+    };
+    readonly replay: {
+        readonly kind: "strip";
+    };
+    readonly response: {
+        readonly kind: "gemini-envelope";
+        readonly family: "gpt-oss";
+    };
+}];
+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"];
+    readonly routes: Readonly<Record<string, {
+        readonly wireModel: string;
+        readonly thinking?: GenerationRoute["thinking"];
+    }>>;
+}[]>(entries: T): T;
+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;
+    reasoning: boolean;
+    thinkingLevelMap: {
+        high: string | null;
+        low: string | null;
+        medium: string | null;
+        minimal: string | null;
+    };
+    input: "text"[];
+    cost: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+    };
+    contextWindow: number;
+    maxTokens: number;
+};
+export {};