@benjamolina/pi-antigravity-guard 0.3.0 → 0.4.0

package/dist/tool-context.js

@@ -0,0 +1,162 @@
+import { canonicalJson, ToolPreflightError } from "./tool-contract.js";
+import { normalizeToolDeclarations } from "./tool-schema.js";
+export function hasToolContext(context) {
+    if (!isRecord(context))
+        return false;
+    const tools = value(context, "tools");
+    if (Array.isArray(tools) && tools.length > 0)
+        return true;
+    const messages = value(context, "messages");
+    return Array.isArray(messages) && messages.some((message) => {
+        if (!isRecord(message))
+            return false;
+        if (value(message, "role") === "toolResult")
+            return true;
+        const content = value(message, "content");
+        return Array.isArray(content) && content.some((part) => isRecord(part) && value(part, "type") === "toolCall");
+    });
+}
+export function prepareToolContext(tools, choice) {
+    const declarations = normalizeToolDeclarations(tools ?? []);
+    if (!declarations.length) {
+        if (choice === "auto")
+            throw new ToolPreflightError("PI_TOOL_CHOICE_WITHOUT_DECLARATIONS", "tools", "$");
+        if (choice !== undefined && choice !== "none")
+            unsupportedChoice();
+        return undefined;
+    }
+    if (choice !== undefined && choice !== "auto" && choice !== "none")
+        unsupportedChoice();
+    return { declarations, mode: choice === "none" ? "NONE" : "AUTO" };
+}
+export function replayToolHistory(messages, serializePart, onRecovery) {
+    const output = [];
+    const calls = new Set();
+    const results = new Set();
+    const recoveryCount = { value: 0 };
+    let pending;
+    const finalize = () => {
+        if (!pending)
+            return;
+        output.push({ role: "user", parts: pending.calls.map((call) => {
+                const actual = pending.results.get(call.id);
+                if (actual)
+                    return actual;
+                recoveryCount.value += 1;
+                return missingResult(call);
+            }) });
+        pending = undefined;
+    };
+    for (const message of messages) {
+        const current = record(message);
+        if (value(current, "role") === "toolResult") {
+            const id = nonempty(value(current, "toolCallId"), "PI_TOOL_RESULT_FOREIGN");
+            if (results.has(id))
+                history("PI_TOOL_RESULT_DUPLICATE");
+            if (!pending)
+                history(calls.has(id) ? "PI_TOOL_RESULT_SEPARATED" : "PI_TOOL_RESULT_FOREIGN");
+            const call = pending.calls.find((item) => item.id === id);
+            if (!call)
+                history(calls.has(id) ? "PI_TOOL_RESULT_SEPARATED" : "PI_TOOL_RESULT_FOREIGN");
+            if (value(current, "toolName") !== call.name)
+                history("PI_TOOL_RESULT_NAME_MISMATCH");
+            if (value(current, "addedToolNames") !== undefined && dense(value(current, "addedToolNames")).length)
+                history("PI_TOOL_CALL_INVALID");
+            const text = dense(value(current, "content")).map((item) => {
+                const part = record(item);
+                if (value(part, "type") !== "text" || typeof value(part, "text") !== "string")
+                    history("PI_TOOL_RESULT_MEDIA_UNSUPPORTED");
+                return value(part, "text");
+            }).join("\n\n");
+            const response = value(current, "isError") === true ? { error: text } : { result: text };
+            pending.results.set(id, { functionResponse: { name: call.name, id, response } });
+            results.add(id);
+            continue;
+        }
+        finalize();
+        const role = value(current, "role");
+        if (role !== "user" && role !== "assistant")
+            history("PI_TOOL_CALL_INVALID");
+        const rawContent = value(current, "content");
+        if (typeof rawContent === "string") {
+            if (!rawContent)
+                history("PI_TOOL_CALL_INVALID");
+            output.push({ role: role === "assistant" ? "model" : "user", parts: [{ text: rawContent }] });
+            continue;
+        }
+        const content = dense(rawContent);
+        const hasCalls = role === "assistant" && content.some((part) => value(record(part), "type") === "toolCall");
+        if (!hasCalls) {
+            output.push({ role: role === "assistant" ? "model" : "user", parts: content.map((part) => serializePart(record(part), current)) });
+            continue;
+        }
+        if (value(current, "stopReason") !== "toolUse")
+            history("PI_TOOL_CALL_INVALID");
+        const group = [];
+        const parts = content.map((item) => {
+            const part = record(item);
+            if (value(part, "type") !== "toolCall")
+                return serializePart(part, current);
+            const id = nonempty(value(part, "id"), "PI_TOOL_CALL_INVALID");
+            const name = nonempty(value(part, "name"), "PI_TOOL_CALL_INVALID");
+            if (!/^[A-Za-z_][A-Za-z0-9_.:-]*$/.test(name) || calls.has(id))
+                history(calls.has(id) ? "PI_TOOL_CALL_DUPLICATE" : "PI_TOOL_CALL_INVALID");
+            const args = canonicalJson(value(part, "arguments"), name, "$.arguments");
+            if (Array.isArray(args) || args === null)
+                history("PI_TOOL_CALL_INVALID");
+            calls.add(id);
+            group.push({ id, name });
+            return { functionCall: { name, args, id } };
+        });
+        output.push({ role: "model", parts });
+        pending = { calls: group, results: new Map() };
+    }
+    finalize();
+    onRecovery?.(recoveryCount.value);
+    return output;
+}
+function missingResult(call) {
+    return {
+        functionResponse: {
+            name: call.name,
+            id: call.id,
+            response: {
+                error: {
+                    code: "PI_TOOL_RESULT_MISSING",
+                    message: "Tool execution did not complete or its result was not recorded. Treat the call as failed; do not assume it had no side effects and do not retry it automatically.",
+                },
+            },
+        },
+    };
+}
+function history(code) {
+    throw new ToolPreflightError(code, "history", "$");
+}
+function record(value) {
+    if (!isRecord(value))
+        history("PI_TOOL_CALL_INVALID");
+    return value;
+}
+function dense(value) {
+    if (!Array.isArray(value) || Object.keys(value).length !== value.length)
+        history("PI_TOOL_CALL_INVALID");
+    return value;
+}
+function nonempty(value, code) {
+    if (typeof value !== "string" || !value.trim())
+        history(code);
+    return value;
+}
+function unsupportedChoice() {
+    throw new ToolPreflightError("PI_TOOL_CHOICE_UNSUPPORTED", "tools", "$");
+}
+function isRecord(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function value(record, name) {
+    const descriptor = Object.getOwnPropertyDescriptor(record, name);
+    return descriptor && "value" in descriptor ? descriptor.value : undefined;
+}

package/dist/tool-contract.d.ts

@@ -0,0 +1,17 @@
+export type JsonPrimitive = null | boolean | number | string;
+export type JsonValue = JsonPrimitive | readonly JsonValue[] | JsonObject;
+export interface JsonObject {
+    readonly [key: string]: JsonValue;
+}
+export declare class ToolPreflightError extends Error {
+    readonly code: string;
+    readonly declaration: string;
+    readonly path: string;
+    constructor(code: string, declaration: string, path: string);
+}
+export declare function ownData(value: unknown, name: string, declaration: string, path: string): unknown;
+export declare function plainObject(value: unknown, declaration: string, path: string): Record<string, unknown>;
+export declare function denseArray(value: unknown, declaration: string, path: string): readonly unknown[];
+export declare function canonicalJson(value: unknown, declaration: string, path: string, ancestors?: Set<object>): JsonValue;
+export declare function freeze<T>(value: T): T;
+export declare function fail(code: string, declaration: string, path: string): never;

package/dist/tool-contract.js

@@ -0,0 +1,65 @@
+export class ToolPreflightError extends Error {
+    code;
+    declaration;
+    path;
+    constructor(code, declaration, path) {
+        super(`${code}: declaration ${declaration} at ${path}`);
+        this.code = code;
+        this.declaration = declaration;
+        this.path = path;
+    }
+}
+export function ownData(value, name, declaration, path) {
+    const object = plainObject(value, declaration, path);
+    const descriptor = Object.getOwnPropertyDescriptor(object, name);
+    if (!descriptor || !("value" in descriptor))
+        return undefined;
+    return descriptor.value;
+}
+export function plainObject(value, declaration, path) {
+    if (typeof value !== "object" || value === null || Array.isArray(value) || (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) || Object.getOwnPropertySymbols(value).length > 0)
+        fail("PI_TOOL_SCHEMA_INVALID", declaration, path);
+    for (const name of Object.getOwnPropertyNames(value)) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, name);
+        if (!descriptor || !("value" in descriptor))
+            fail("PI_TOOL_SCHEMA_INVALID", declaration, path);
+    }
+    return value;
+}
+export function denseArray(value, declaration, path) {
+    if (!Array.isArray(value) || Object.keys(value).length !== value.length)
+        fail("PI_TOOL_SCHEMA_INVALID", declaration, path);
+    return value;
+}
+export function canonicalJson(value, declaration, path, ancestors = new Set()) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value === "number") {
+        if (Number.isFinite(value))
+            return value;
+        fail("PI_TOOL_SCHEMA_INVALID", declaration, path);
+    }
+    if (typeof value !== "object")
+        fail("PI_TOOL_SCHEMA_INVALID", declaration, path);
+    if (ancestors.has(value))
+        fail("PI_TOOL_SCHEMA_INVALID", declaration, path);
+    ancestors.add(value);
+    try {
+        if (Array.isArray(value))
+            return Object.freeze(denseArray(value, declaration, path).map((item, index) => canonicalJson(item, declaration, `${path}[${index}]`, ancestors)));
+        const object = plainObject(value, declaration, path);
+        const output = {};
+        for (const key of Object.keys(object).sort())
+            output[key] = canonicalJson(object[key], declaration, `${path}.${key}`, ancestors);
+        return Object.freeze(output);
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
+export function freeze(value) {
+    return Object.freeze(value);
+}
+export function fail(code, declaration, path) {
+    throw new ToolPreflightError(code, declaration, path);
+}

package/dist/tool-schema.d.ts

@@ -0,0 +1,7 @@
+import { type JsonObject } from "./tool-contract.ts";
+export interface ToolDeclaration {
+    readonly name: string;
+    readonly description: string;
+    readonly parameters: JsonObject;
+}
+export declare function normalizeToolDeclarations(value: unknown): readonly ToolDeclaration[];

package/dist/tool-schema.js

@@ -0,0 +1,125 @@
+import { canonicalJson, denseArray, fail, freeze, ownData, plainObject } from "./tool-contract.js";
+const TYPES = new Set(["object", "array", "string", "number", "integer", "boolean"]);
+const KEYWORDS = new Set(["type", "description", "nullable", "enum", "const", "properties", "required", "items"]);
+const MAX_SCHEMA_DEPTH = 32;
+const MAX_SCHEMA_NODES = 2048;
+const MAX_SCHEMA_BYTES = 256 * 1024;
+const MAX_TOTAL_SCHEMA_BYTES = 1024 * 1024;
+export function normalizeToolDeclarations(value) {
+    const tools = denseArray(value, "tools", "$");
+    const names = new Set();
+    const declarations = tools.map((tool, index) => normalizeDeclaration(tool, index, names));
+    let totalSchemaBytes = 0;
+    for (const declaration of declarations) {
+        totalSchemaBytes += Buffer.byteLength(JSON.stringify(declaration.parameters), "utf8");
+        if (totalSchemaBytes > MAX_TOTAL_SCHEMA_BYTES)
+            fail("PI_TOOL_SCHEMA_LIMIT", declaration.name, "$");
+    }
+    return freeze(declarations);
+}
+function normalizeDeclaration(value, index, names) {
+    const path = `$[${index}]`;
+    const tool = plainObject(value, `tool-${index}`, path);
+    const name = ownData(tool, "name", `tool-${index}`, path);
+    if (typeof name !== "string" || !/^[A-Za-z_][A-Za-z0-9_.:-]{0,63}$/.test(name))
+        fail("PI_TOOL_DECLARATION_INVALID", `tool-${index}`, `${path}.name`);
+    if (names.has(name))
+        fail("PI_TOOL_DECLARATION_DUPLICATE", name, `${path}.name`);
+    names.add(name);
+    const description = ownData(tool, "description", name, path);
+    if (typeof description !== "string" || !description.trim())
+        fail("PI_TOOL_DECLARATION_INVALID", name, `${path}.description`);
+    const constrainedSampling = ownData(tool, "constrainedSampling", name, path);
+    if (constrainedSampling !== undefined && constrainedSampling !== false)
+        fail("PI_TOOL_CONSTRAINED_SAMPLING_UNSUPPORTED", name, `${path}.constrainedSampling`);
+    const parameterRoot = plainObject(ownData(tool, "parameters", name, path), name, "$");
+    if (ownData(parameterRoot, "type", name, "$") !== "object")
+        fail("PI_TOOL_SCHEMA_INVALID", name, "$.type");
+    const parameters = normalizeSchema(parameterRoot, name, "$");
+    if (Buffer.byteLength(JSON.stringify(parameters), "utf8") > MAX_SCHEMA_BYTES)
+        fail("PI_TOOL_SCHEMA_LIMIT", name, "$");
+    return freeze({ name, description, parameters });
+}
+function normalizeSchema(value, declaration, path, state = { ancestors: new Set(), nodes: 0 }, depth = 0) {
+    if (depth > MAX_SCHEMA_DEPTH || ++state.nodes > MAX_SCHEMA_NODES)
+        fail("PI_TOOL_SCHEMA_LIMIT", declaration, path);
+    if (typeof value === "object" && value !== null) {
+        if (state.ancestors.has(value))
+            fail("PI_TOOL_SCHEMA_INVALID", declaration, path);
+        state.ancestors.add(value);
+    }
+    const schema = plainObject(value, declaration, path);
+    for (const key of Object.keys(schema))
+        if (!KEYWORDS.has(key))
+            fail("PI_TOOL_SCHEMA_UNSUPPORTED", declaration, `${path}.${key}`);
+    const type = ownData(schema, "type", declaration, path);
+    if (typeof type !== "string" || !TYPES.has(type))
+        fail("PI_TOOL_SCHEMA_INVALID", declaration, `${path}.type`);
+    const output = { type };
+    const description = ownData(schema, "description", declaration, path);
+    if (description !== undefined) {
+        if (typeof description !== "string")
+            fail("PI_TOOL_SCHEMA_INVALID", declaration, `${path}.description`);
+        output.description = description;
+    }
+    const nullable = ownData(schema, "nullable", declaration, path);
+    if (nullable !== undefined) {
+        if (typeof nullable !== "boolean")
+            fail("PI_TOOL_SCHEMA_INVALID", declaration, `${path}.nullable`);
+        output.nullable = nullable;
+    }
+    const enumValue = ownData(schema, "enum", declaration, path);
+    const constant = ownData(schema, "const", declaration, path);
+    if (enumValue !== undefined && constant !== undefined)
+        fail("PI_TOOL_SCHEMA_INVALID", declaration, `${path}.const`);
+    if (enumValue !== undefined)
+        output.enum = normalizeEnum(enumValue, type, nullable === true, declaration, `${path}.enum`);
+    if (constant !== undefined)
+        output.enum = freeze([validateEnumValue(constant, type, nullable === true, declaration, `${path}.const`)]);
+    if (type === "object")
+        normalizeObject(schema, output, declaration, path, state, depth);
+    else if (type === "array")
+        normalizeArray(schema, output, declaration, path, state, depth);
+    else if (ownData(schema, "properties", declaration, path) !== undefined || ownData(schema, "required", declaration, path) !== undefined || ownData(schema, "items", declaration, path) !== undefined)
+        fail("PI_TOOL_SCHEMA_INVALID", declaration, path);
+    return freeze(output);
+}
+function normalizeObject(schema, output, declaration, path, state, depth) {
+    if (ownData(schema, "items", declaration, path) !== undefined)
+        fail("PI_TOOL_SCHEMA_INVALID", declaration, `${path}.items`);
+    const properties = plainObject(ownData(schema, "properties", declaration, path), declaration, `${path}.properties`);
+    const names = Object.keys(properties).sort();
+    if (!names.length)
+        fail("PI_TOOL_SCHEMA_INVALID", declaration, `${path}.properties`);
+    const normalized = {};
+    for (const name of names)
+        normalized[name] = normalizeSchema(properties[name], declaration, `${path}.properties.${name}`, state, depth + 1);
+    output.properties = freeze(normalized);
+    const required = ownData(schema, "required", declaration, path);
+    if (required !== undefined) {
+        const values = denseArray(required, declaration, `${path}.required`);
+        if (values.some((name) => typeof name !== "string" || !Object.hasOwn(properties, name)) || new Set(values).size !== values.length)
+            fail("PI_TOOL_SCHEMA_INVALID", declaration, `${path}.required`);
+        output.required = freeze([...values].sort());
+    }
+}
+function normalizeArray(schema, output, declaration, path, state, depth) {
+    if (ownData(schema, "properties", declaration, path) !== undefined || ownData(schema, "required", declaration, path) !== undefined)
+        fail("PI_TOOL_SCHEMA_INVALID", declaration, path);
+    output.items = normalizeSchema(ownData(schema, "items", declaration, path), declaration, `${path}.items`, state, depth + 1);
+}
+function normalizeEnum(value, type, nullable, declaration, path) {
+    const values = denseArray(value, declaration, path);
+    if (!values.length)
+        fail("PI_TOOL_SCHEMA_INVALID", declaration, path);
+    const normalized = values.map((item, index) => validateEnumValue(item, type, nullable, declaration, `${path}[${index}]`));
+    if (new Set(normalized.map((item) => JSON.stringify(item))).size !== normalized.length)
+        fail("PI_TOOL_SCHEMA_INVALID", declaration, path);
+    return freeze(normalized);
+}
+function validateEnumValue(value, type, nullable, declaration, path) {
+    const json = canonicalJson(value, declaration, path);
+    if (typeof json === "object" || (json === null && !nullable) || (json !== null && (type === "integer" ? typeof json !== "number" || !Number.isInteger(json) : typeof json !== type)))
+        fail("PI_TOOL_SCHEMA_INVALID", declaration, path);
+    return json;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@benjamolina/pi-antigravity-guard",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Pi adapter for Antigravity Guard",
   "type": "module",
   "license": "MIT",