@pentoshi/clai 4.1.0 → 4.2.0

package/dist/llm/request-fingerprint.js

@@ -0,0 +1,313 @@
+import { createHash } from "node:crypto";
+export const REQUEST_FINGERPRINT_VERSION = 1;
+export const REQUEST_FINGERPRINT_SERIALIZER_VERSION = 1;
+function byteLength(value) {
+    return Buffer.byteLength(value, "utf8");
+}
+function updateChunk(hash, value) {
+    const bytes = byteLength(value);
+    hash.update(`${bytes}:`, "utf8");
+    hash.update(value, "utf8");
+    return bytes;
+}
+function sha256(value) {
+    return createHash("sha256").update(value, "utf8").digest("hex");
+}
+function chainedSha256(previous, value) {
+    const hash = createHash("sha256");
+    hash.update("clai.request-fingerprint.prefix.v1\0", "utf8");
+    if (previous)
+        hash.update(previous, "hex");
+    updateChunk(hash, value);
+    return hash.digest("hex");
+}
+function skipWhitespace(source, index) {
+    let next = index;
+    while (next < source.length && /\s/.test(source[next]))
+        next += 1;
+    return next;
+}
+function scanJsonString(source, start) {
+    if (source[start] !== '"')
+        throw new Error("expected JSON string");
+    for (let index = start + 1; index < source.length; index += 1) {
+        if (source[index] === "\\") {
+            index += 1;
+            continue;
+        }
+        if (source[index] === '"')
+            return index + 1;
+    }
+    throw new Error("unterminated JSON string");
+}
+function scanJsonValue(source, start) {
+    const first = source[start];
+    if (first === '"')
+        return scanJsonString(source, start);
+    if (first !== "{" && first !== "[") {
+        let end = start;
+        while (end < source.length && !/[\s,}\]]/.test(source[end]))
+            end += 1;
+        if (end === start)
+            throw new Error("expected JSON value");
+        return end;
+    }
+    let depth = 0;
+    let inString = false;
+    for (let index = start; index < source.length; index += 1) {
+        const character = source[index];
+        if (inString) {
+            if (character === "\\") {
+                index += 1;
+            }
+            else if (character === '"') {
+                inString = false;
+            }
+            continue;
+        }
+        if (character === '"') {
+            inString = true;
+            continue;
+        }
+        if (character === "{" || character === "[") {
+            depth += 1;
+            continue;
+        }
+        if (character === "}" || character === "]") {
+            depth -= 1;
+            if (depth === 0)
+                return index + 1;
+        }
+    }
+    throw new Error("unterminated JSON value");
+}
+function rootJsonFields(source) {
+    let index = skipWhitespace(source, 0);
+    if (source[index] !== "{")
+        throw new Error("expected JSON object");
+    index = skipWhitespace(source, index + 1);
+    const fields = [];
+    while (source[index] !== "}") {
+        const start = index;
+        const keyEnd = scanJsonString(source, index);
+        const name = JSON.parse(source.slice(index, keyEnd));
+        index = skipWhitespace(source, keyEnd);
+        if (source[index] !== ":")
+            throw new Error("expected JSON field separator");
+        const valueStart = skipWhitespace(source, index + 1);
+        const end = scanJsonValue(source, valueStart);
+        fields.push({ name, start, valueStart, end });
+        index = skipWhitespace(source, end);
+        if (source[index] === ",") {
+            index = skipWhitespace(source, index + 1);
+            continue;
+        }
+        if (source[index] === "}")
+            break;
+        throw new Error("expected JSON field delimiter");
+    }
+    if (skipWhitespace(source, index + 1) !== source.length) {
+        throw new Error("unexpected JSON suffix");
+    }
+    return fields;
+}
+function arrayElements(source, range) {
+    let index = skipWhitespace(source, range.start);
+    if (source[index] !== "[")
+        return [];
+    index = skipWhitespace(source, index + 1);
+    const elements = [];
+    while (source[index] !== "]") {
+        const start = index;
+        const end = scanJsonValue(source, start);
+        elements.push({ start, end });
+        index = skipWhitespace(source, end);
+        if (source[index] === ",") {
+            index = skipWhitespace(source, index + 1);
+            continue;
+        }
+        if (source[index] === "]")
+            break;
+        throw new Error("expected JSON array delimiter");
+    }
+    return elements;
+}
+function sectionKind(fieldName) {
+    if (fieldName === "system" || fieldName === "systemInstruction") {
+        return "instructions";
+    }
+    if (fieldName === "tools")
+        return "tools";
+    if (fieldName === "messages" || fieldName === "contents" || fieldName === "input") {
+        return "history";
+    }
+    return "settings";
+}
+function serializerId(input) {
+    switch (input.provider) {
+        case "anthropic":
+            return "anthropic-messages";
+        case "gemini":
+            return "gemini-generate-content";
+        case "meta":
+            return "meta-responses";
+        case "ollama":
+            return "ollama-chat";
+        case "aws-mantle":
+            return /(?:^|[./-])(?:anthropic|claude)(?:[./-]|$)/i.test(input.model)
+                ? "anthropic-messages"
+                : "chat-completions";
+        default:
+            return "chat-completions";
+    }
+}
+function freezeFingerprint(serializer, body, sections, prefixes) {
+    return Object.freeze({
+        version: REQUEST_FINGERPRINT_VERSION,
+        serializer: Object.freeze({
+            id: serializer,
+            version: REQUEST_FINGERPRINT_SERIALIZER_VERSION,
+        }),
+        body: Object.freeze({ ...body }),
+        sections: Object.freeze(sections.map((section) => Object.freeze({ ...section }))),
+        prefixes: Object.freeze(prefixes.map((prefix) => Object.freeze({ ...prefix }))),
+    });
+}
+function wireOnlyFingerprint(input, body) {
+    return freezeFingerprint(serializerId(input), { byteLength: byteLength(body), sha256: sha256(body) }, [], [
+        {
+            ordinal: 1,
+            section: "wire",
+            boundary: "wire",
+            byteLength: byteLength(body),
+            sha256: sha256(body),
+        },
+    ]);
+}
+/**
+ * Captures hashes and byte counts from the exact JSON string passed to fetch.
+ * The returned value has no request body, header, URL, or decoded JSON values.
+ */
+export function fingerprintFinalRequest(input, body) {
+    if (typeof body !== "string")
+        return undefined;
+    try {
+        JSON.parse(body);
+        const fields = rootJsonFields(body);
+        const sections = new Map();
+        const sectionOrder = [];
+        const appendSection = (kind, value, itemCount = 0) => {
+            let section = sections.get(kind);
+            if (!section) {
+                section = {
+                    kind,
+                    hash: createHash("sha256").update(`clai.request-fingerprint.section.${kind}.v1\0`, "utf8"),
+                    byteLength: 0,
+                    itemCount: 0,
+                };
+                sections.set(kind, section);
+                sectionOrder.push(section);
+            }
+            section.byteLength += updateChunk(section.hash, value);
+            section.itemCount += itemCount;
+        };
+        const boundaries = [];
+        for (const field of fields) {
+            const kind = sectionKind(field.name);
+            const fieldValue = body.slice(field.start, field.end);
+            const history = kind === "history"
+                ? arrayElements(body, { start: field.valueStart, end: field.end })
+                : [];
+            appendSection(kind, fieldValue, history.length);
+            for (let index = 0; index < history.length; index += 1) {
+                boundaries.push({
+                    end: history[index].end,
+                    section: "history",
+                    boundary: "history-item",
+                    historyItems: index + 1,
+                });
+            }
+            boundaries.push({
+                end: field.end,
+                section: kind,
+                boundary: "field",
+                ...(kind === "history" ? { historyItems: history.length } : {}),
+            });
+        }
+        boundaries.push({
+            end: body.length,
+            section: "wire",
+            boundary: "wire",
+        });
+        let cursor = 0;
+        let previous;
+        let prefixBytes = 0;
+        const prefixes = [];
+        for (const boundary of boundaries) {
+            const chunk = body.slice(cursor, boundary.end);
+            prefixBytes += byteLength(chunk);
+            previous = chainedSha256(previous, chunk);
+            prefixes.push({
+                ordinal: prefixes.length + 1,
+                section: boundary.section,
+                boundary: boundary.boundary,
+                byteLength: prefixBytes,
+                sha256: previous,
+                ...(boundary.historyItems !== undefined
+                    ? { historyItems: boundary.historyItems }
+                    : {}),
+            });
+            cursor = boundary.end;
+        }
+        const sectionFingerprints = sectionOrder.map((section) => ({
+            section: section.kind,
+            byteLength: section.byteLength,
+            sha256: section.hash.digest("hex"),
+            ...(section.kind === "history" ? { itemCount: section.itemCount } : {}),
+        }));
+        return freezeFingerprint(serializerId(input), { byteLength: byteLength(body), sha256: sha256(body) }, sectionFingerprints, prefixes);
+    }
+    catch {
+        return wireOnlyFingerprint(input, body);
+    }
+}
+function historyItemPrefix(fingerprint, historyItems) {
+    return fingerprint.prefixes.find((prefix) => prefix.section === "history" &&
+        prefix.boundary === "history-item" &&
+        prefix.historyItems === historyItems);
+}
+function stableHistoryItems(fingerprint) {
+    return fingerprint.prefixes.reduce((largest, prefix) => prefix.section === "history" &&
+        prefix.boundary === "history-item" &&
+        prefix.historyItems !== undefined &&
+        prefix.historyItems > largest
+        ? prefix.historyItems
+        : largest, 0);
+}
+function sectionSha256(fingerprint, section) {
+    return fingerprint.sections.find((entry) => entry.section === section)
+        ?.sha256;
+}
+export function classifyPrefixAffinity(prior, next) {
+    if (!prior || !next)
+        return "unknown";
+    if (prior.serializer.id !== next.serializer.id)
+        return "not_eligible";
+    const items = stableHistoryItems(prior);
+    if (items === 0)
+        return "unknown";
+    const priorPrefix = historyItemPrefix(prior, items);
+    const nextPrefix = historyItemPrefix(next, items);
+    if (!priorPrefix || !nextPrefix)
+        return "unknown";
+    if (sectionSha256(prior, "instructions") !==
+        sectionSha256(next, "instructions") ||
+        sectionSha256(prior, "tools") !== sectionSha256(next, "tools")) {
+        return "not_eligible";
+    }
+    if (priorPrefix.sha256 === nextPrefix.sha256) {
+        return "exact_append_eligible";
+    }
+    return "partial_prefix_eligible";
+}
+//# sourceMappingURL=request-fingerprint.js.map

package/dist/llm/request-fingerprint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-fingerprint.js","sourceRoot":"","sources":["../../src/llm/request-fingerprint.ts"],"names":[],"mappings":"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"}

package/dist/llm/request-plan.d.ts

@@ -0,0 +1,119 @@
+import type { ChatMessage, ProviderId, ReasoningArtifactReplayDecision, ReasoningArtifactReplayTarget, ReasoningPreference, RequestFingerprintSerializerId, ToolChoice, ToolDefinition } from "../types.js";
+import { type CachePolicySpec, type ContextLimitSpec, type ProfileReplayScope, type ProfileTriState, type ReasoningControlDialect, type ReasoningGeneration } from "./provider-profile.js";
+/**
+ * Canonical request plan (doc 03 §"Canonical request plan", doc 06 §3).
+ *
+ * One immutable, renderer-neutral object describes what a logical generation
+ * will send: route, timeline with stable/mutable boundaries, tools, replay
+ * decisions for every artifact, controls, images, route policy, budget, and a
+ * privacy-safe cache-prefix fingerprint. Provider serializers emit their wire
+ * bodies from a compiled plan; nothing dispatches from ad hoc message arrays
+ * past this boundary.
+ */
+export declare const REQUEST_PLAN_VERSION: 1;
+export declare const REQUEST_PLAN_COMPILER_VERSION: 1;
+export type RequestPlanSectionKind = "instructions" | "history" | "live";
+export interface RequestPlanBoundary {
+    readonly kind: RequestPlanSectionKind;
+    /** Inclusive index into `timeline.messages`. */
+    readonly messageStart: number;
+    /** Exclusive index into `timeline.messages`. */
+    readonly messageEnd: number;
+    readonly messageCount: number;
+}
+export type RequestPlanControlSuppression = "observed-rejection" | "capability-denied";
+export interface RequestPlanControls {
+    readonly reasoning?: ReasoningPreference | undefined;
+    readonly controlSuppression?: RequestPlanControlSuppression | undefined;
+    readonly temperature: number;
+    readonly topP?: number | undefined;
+    readonly requestedMaxTokens?: number | undefined;
+    readonly stream: boolean;
+}
+export interface RequestPlanRoute {
+    readonly provider: ProviderId;
+    readonly model: string;
+    readonly serializer: RequestFingerprintSerializerId;
+    readonly serializerVersion: 1;
+    readonly compilerVersion: 1;
+    readonly endpointHash?: string | undefined;
+}
+export interface RequestPlanArtifactDecision {
+    readonly messageIndex: number;
+    readonly decision: ReasoningArtifactReplayDecision;
+}
+export type RequestPlanCacheSectionName = "instructions" | "tools" | "history" | "artifacts" | "settings";
+export interface RequestPlanCacheSection {
+    readonly ordinal: number;
+    readonly section: RequestPlanCacheSectionName;
+    readonly sha256: string;
+    readonly byteLength: number;
+    readonly estimatedTokens: number;
+    readonly itemCount: number;
+}
+export interface RequestPlanCacheFingerprint {
+    readonly prefixMessageCount: number;
+    readonly replayedArtifactCount: number;
+    readonly sections: readonly RequestPlanCacheSection[];
+    readonly prefixSha256: string;
+}
+export interface RequestPlanRoutePolicy {
+    readonly reasoningGeneration: ReasoningGeneration;
+    readonly controlDialect: ReasoningControlDialect;
+    readonly controlStatus: ProfileTriState;
+    readonly replayScope: ProfileReplayScope;
+    readonly cache: CachePolicySpec;
+    readonly limits: ContextLimitSpec;
+}
+export interface RequestPlanV1 {
+    readonly version: 1;
+    readonly route: RequestPlanRoute;
+    readonly timeline: {
+        readonly messages: readonly ChatMessage[];
+        readonly sections: readonly RequestPlanBoundary[];
+        /** Every message excluded from the cacheable prefix, in timeline order. */
+        readonly mutableMessageIndexes: readonly number[];
+    };
+    readonly tools: {
+        readonly definitions: readonly ToolDefinition[];
+        readonly choice?: ToolChoice | undefined;
+        readonly parallelToolCalls?: boolean | undefined;
+    };
+    readonly replay: {
+        readonly target: ReasoningArtifactReplayTarget;
+        readonly decisions: readonly RequestPlanArtifactDecision[];
+    };
+    readonly controls: RequestPlanControls;
+    readonly images: {
+        readonly visionAccepted: boolean;
+        readonly imageMessageIndexes: readonly number[];
+        readonly imageCount: number;
+    };
+    readonly policy: RequestPlanRoutePolicy;
+    readonly budget: {
+        readonly plannedAdmissions: 1;
+    };
+    readonly cache: {
+        readonly policy: CachePolicySpec;
+        readonly fingerprint: RequestPlanCacheFingerprint;
+    };
+}
+export interface CompileRequestPlanInput {
+    readonly provider: ProviderId;
+    readonly model: string;
+    readonly messages: readonly ChatMessage[];
+    readonly stream: boolean;
+    /** Raw endpoint string; only its normalized hash is retained. */
+    readonly endpoint?: string | undefined;
+    readonly reasoning?: ReasoningPreference | undefined;
+    readonly tools?: readonly ToolDefinition[] | undefined;
+    readonly toolChoice?: ToolChoice | undefined;
+    readonly parallelToolCalls?: boolean | undefined;
+    readonly temperature?: number | undefined;
+    readonly maxTokens?: number | undefined;
+}
+/**
+ * Deterministically compile one immutable plan. Compilation is pure: the same
+ * inputs always produce a deep-equal plan with identical section hashes.
+ */
+export declare function compileRequestPlan(input: CompileRequestPlanInput): RequestPlanV1;