@averta-security/sdk-core 0.1.0-beta.0

package/LICENSE.md

@@ -0,0 +1,26 @@
+# Averta Proprietary SDK License
+
+Draft template. Have counsel approve before publishing.
+
+Copyright (c) 2026 Averta LTD. All rights reserved.
+
+This SDK is licensed, not sold.
+
+Subject to an active Averta account, subscription, order form, or other written agreement between you and Averta LTD (the "Agreement"), Averta LTD grants you a limited, non-exclusive, non-transferable, revocable license to install, copy, and use this SDK solely to integrate your applications with Averta services.
+
+You may reproduce this SDK only as reasonably necessary for development, testing, build, deployment, backup, and production operation of applications that are authorized to use Averta services.
+
+You may not, except as expressly permitted by the Agreement or applicable law:
+
+1. sell, sublicense, redistribute, publish, rent, lease, or make this SDK available as a standalone product;
+2. use this SDK to build, train, operate, or support a competing product or service;
+3. reverse engineer, decompile, disassemble, or attempt to derive source code or non-public implementation details from this SDK;
+4. remove or alter proprietary notices, license notices, or attribution notices;
+5. use this SDK to access Averta services without authorization or in violation of applicable usage limits, security controls, or documentation;
+6. use this SDK in a way that violates law, infringes third-party rights, or compromises the security or integrity of Averta services.
+
+No rights are granted except those expressly stated in this license or the Agreement. Averta LTD and its licensors retain all right, title, and interest in and to this SDK.
+
+This license terminates automatically when your Agreement terminates or when you stop being authorized to use Averta services. Upon termination, you must stop using this SDK and remove it from systems where continued use is not authorized.
+
+Support, service-level commitments, warranties, indemnities, liability limits, and governing law are controlled by the Agreement. If no Agreement applies, this SDK is provided "as is" and "as available", without warranties of any kind, and Averta LTD will not be liable for damages arising from use of this SDK.

package/README.md

@@ -0,0 +1,80 @@
+# @averta-security/sdk-core
+
+Shared runtime primitives for Averta JavaScript SDK adapters.
+
+Most applications should install a provider adapter such as `@averta-security/sdk-openai` or `@averta-security/sdk-anthropic` instead of importing this package directly. Install `@averta-security/sdk-core` directly only when you are building an Averta adapter or handling shared SDK types and errors.
+
+## Installation
+
+```sh
+npm install @averta-security/sdk-core
+```
+
+Requirements:
+
+- Node.js 18 or newer.
+- ESM runtime or bundler support.
+
+## Exports
+
+```ts
+import {
+  AvertaDecisionClient,
+  AvertaSdkError,
+  ensureRequestContext,
+} from "@averta-security/sdk-core";
+import type { AvertaRequestContext, DecisionResponse } from "@averta-security/sdk-core";
+```
+
+The public surface includes:
+
+- `AvertaDecisionClient` for low-level calls to Averta's `/v1/decide` endpoint.
+- `AvertaSdkError` for structured SDK errors.
+- Request context helpers for `conversationId`, `requestId`, and `traceId`.
+- Shared lifecycle helpers used by provider adapters.
+- Shared types for decision payloads, provider metadata, tool calls, tool results, and output decisions.
+
+## Decision Client
+
+```ts
+import { AvertaDecisionClient } from "@averta-security/sdk-core";
+
+const client = new AvertaDecisionClient({
+  avertaApiKey: process.env.AVERTA_API_KEY!,
+  sdk: {
+    name: "custom-adapter",
+    version: "0.1.0",
+  },
+});
+```
+
+Options:
+
+- `avertaApiKey`: required Averta API key.
+- `avertaBaseUrl`: optional Averta API base URL. Defaults to `https://api.averta.io`.
+- `decisionTimeoutMs`: optional decision request timeout in milliseconds. Defaults to `30000`. Set to `0` to disable the SDK-managed timeout.
+- `fetch`: optional custom `fetch` implementation.
+- `sdk`: adapter name and version metadata sent to Averta.
+
+## Errors
+
+SDK failures throw `AvertaSdkError`.
+
+```ts
+try {
+  await guardedOperation();
+} catch (error) {
+  if (error instanceof AvertaSdkError) {
+    console.error(error.code, error.statusCode);
+    console.error(error.checkpointDecision);
+  }
+}
+```
+
+`checkpointDecision` is present when the error came from a block or failed checkpoint decision.
+
+## Packaging
+
+This package publishes built JavaScript and TypeScript declarations from `dist`. TypeScript source, tests, and build configuration are not included in the npm package.
+
+This package is proprietary software. See `LICENSE.md`.

package/dist/decision-client.d.ts

@@ -0,0 +1,16 @@
+import type { DecisionClientOptions, DecisionPreflightInput, OutputDecisionInput, DecisionResponse, ToolCallDecisionInput, ToolResultDecisionInput } from "./types.ts";
+export declare class AvertaDecisionClient {
+    private readonly avertaBaseUrl;
+    private readonly decisionTimeoutMs;
+    private readonly fetchImpl;
+    private readonly sdk;
+    constructor(options: DecisionClientOptions);
+    private readonly avertaApiKey;
+    preflight(input: Omit<DecisionPreflightInput, "sdk">): Promise<DecisionResponse>;
+    checkToolCall(input: ToolCallDecisionInput): Promise<DecisionResponse>;
+    checkToolResult(input: ToolResultDecisionInput): Promise<DecisionResponse>;
+    checkOutput(input: OutputDecisionInput): Promise<DecisionResponse>;
+    private sendDecisionRequest;
+    private createTransportError;
+    private createRequestError;
+}

package/dist/decision-client.js

@@ -0,0 +1,485 @@
+import { AvertaSdkError } from "./errors.js";
+import { ensureRequestContext } from "./ids.js";
+import { isObject } from "./values.js";
+const DEFAULT_AVERTA_BASE_URL = "https://api.averta.io";
+const DEFAULT_DECISION_TIMEOUT_MS = 30_000;
+function parseReasons(payload) {
+    if (!Array.isArray(payload)) {
+        return null;
+    }
+    const reasons = payload.filter((reason) => isObject(reason) &&
+        typeof reason.code === "string" &&
+        typeof reason.message === "string");
+    if (reasons.length !== payload.length) {
+        return null;
+    }
+    return reasons;
+}
+function parseBlockedTools(payload) {
+    if (payload === undefined) {
+        return undefined;
+    }
+    if (!Array.isArray(payload)) {
+        return null;
+    }
+    if (!payload.every((tool) => typeof tool === "string")) {
+        return null;
+    }
+    return payload;
+}
+function parseTool(payload) {
+    if (payload === undefined) {
+        return undefined;
+    }
+    if (!isObject(payload) ||
+        typeof payload.kind !== "string" ||
+        typeof payload.name !== "string") {
+        return null;
+    }
+    return {
+        kind: payload.kind,
+        name: payload.name,
+    };
+}
+function parseRewriteAction(payload) {
+    if (payload === undefined) {
+        return undefined;
+    }
+    if (!isObject(payload) ||
+        !isObject(payload.rewrite)) {
+        return null;
+    }
+    const category = payload.rewrite.category;
+    if (category !== "secret_disclosure" &&
+        category !== "system_prompt_disclosure" &&
+        category !== "harmful_output") {
+        return null;
+    }
+    return {
+        rewrite: {
+            category,
+        },
+    };
+}
+function parseRunId(payload) {
+    if (payload === undefined) {
+        return undefined;
+    }
+    if (typeof payload !== "string" || !payload.trim()) {
+        return null;
+    }
+    return payload;
+}
+function parseDecisionResponse(payload) {
+    if (!isObject(payload) ||
+        payload.decision !== "allow" &&
+            payload.decision !== "block" &&
+            payload.decision !== "restrict_tools" &&
+            payload.decision !== "rewrite" ||
+        typeof payload.decision_id !== "string" ||
+        typeof payload.event_id !== "string" ||
+        typeof payload.policy_id !== "string") {
+        throw new AvertaSdkError("Averta returned an invalid decision response.", "invalid_decision_response");
+    }
+    const blockedTools = parseBlockedTools(payload.blocked_tools);
+    const tool = parseTool(payload.tool);
+    const actions = parseRewriteAction(payload.actions);
+    const reasons = parseReasons(payload.reasons);
+    const runId = parseRunId(payload.run_id);
+    if (blockedTools === null ||
+        tool === null ||
+        actions === null ||
+        reasons === null ||
+        runId === null ||
+        (payload.decision === "rewrite" && actions?.rewrite === undefined) ||
+        (payload.decision === "restrict_tools" && blockedTools === undefined)) {
+        throw new AvertaSdkError("Averta returned an invalid decision response.", "invalid_decision_response");
+    }
+    return {
+        actions,
+        decision: payload.decision,
+        decisionId: payload.decision_id,
+        eventId: payload.event_id,
+        policyId: payload.policy_id,
+        runId,
+        reasons,
+        blockedTools,
+        tool,
+    };
+}
+function assertDecisionForCheckpoint(checkpointType, decision) {
+    const isValidDecision = checkpointType === "request"
+        ? decision === "allow" ||
+            decision === "block" ||
+            decision === "restrict_tools"
+        : checkpointType === "tool_call"
+            ? decision === "allow" || decision === "block"
+            : checkpointType === "tool_result"
+                ? decision === "allow" || decision === "block"
+                : decision === "allow" ||
+                    decision === "block" ||
+                    decision === "rewrite";
+    if (!isValidDecision) {
+        throw new AvertaSdkError("Averta returned an invalid decision response.", "invalid_decision_response");
+    }
+}
+function hasForwardedTools(input) {
+    if (input.decision === "block") {
+        return false;
+    }
+    if (!input.tools || input.tools.length === 0) {
+        return false;
+    }
+    const blockedTools = new Set(input.blockedTools ?? []);
+    return input.tools.some((tool) => !blockedTools.has(tool.name));
+}
+function toProviderPayload(provider) {
+    if (typeof provider.model !== "string" || !provider.model.trim()) {
+        throw new AvertaSdkError("Guarded provider requests must include a model.", "missing_provider_model");
+    }
+    return {
+        model: provider.model,
+        name: provider.name,
+        operation: provider.operation,
+        streaming: provider.streaming ?? false,
+    };
+}
+function toToolsPayload(tools) {
+    if (!tools) {
+        return undefined;
+    }
+    return tools.map((tool) => ({
+        ...(tool.description ? { description: tool.description } : {}),
+        ...(tool.inputSchema ? { input_schema: tool.inputSchema } : {}),
+        name: tool.name,
+        type: tool.type,
+    }));
+}
+function toToolCallPayload(toolCall) {
+    return {
+        ...(toolCall.arguments && toolCall.arguments.value !== undefined
+            ? {
+                arguments: {
+                    value: toolCall.arguments.value,
+                },
+            }
+            : {}),
+        call_id: toolCall.callId,
+        tool: {
+            kind: toolCall.tool.kind,
+            name: toolCall.tool.name,
+        },
+    };
+}
+function toToolCallContextPayload(context) {
+    return {
+        messages: context.messages.map((message) => {
+            if (message.role === "assistant") {
+                return {
+                    ...(message.text !== undefined ? { text: message.text } : {}),
+                    ...(message.toolCalls
+                        ? {
+                            tool_calls: message.toolCalls.map(toToolCallPayload),
+                        }
+                        : {}),
+                    role: "assistant",
+                };
+            }
+            if (message.role === "tool") {
+                return {
+                    call_id: message.callId,
+                    content: {
+                        value: message.content.value,
+                    },
+                    role: "tool",
+                };
+            }
+            return {
+                role: "user",
+                text: message.text,
+            };
+        }),
+    };
+}
+function toCheckpointPayload(input) {
+    if (input.checkpointType === "request") {
+        return {
+            payload: input.payload,
+            ...(input.tools ? { tools: toToolsPayload(input.tools) } : {}),
+        };
+    }
+    if (input.checkpointType === "tool_call") {
+        return {
+            context: toToolCallContextPayload(input.context),
+            model_response_tool_calls: input.modelResponseToolCalls.map(toToolCallPayload),
+            tool_call: input.toolCall,
+        };
+    }
+    if (input.checkpointType === "tool_result") {
+        return {
+            tool_result: input.toolResult,
+        };
+    }
+    return {
+        output: input.output,
+    };
+}
+function normalizeDecisionTimeoutMs(timeoutMs) {
+    if (timeoutMs === undefined) {
+        return DEFAULT_DECISION_TIMEOUT_MS;
+    }
+    if (!Number.isFinite(timeoutMs) || timeoutMs < 0) {
+        throw new AvertaSdkError("Averta decision timeout must be a non-negative finite number.", "invalid_decision_timeout");
+    }
+    return timeoutMs;
+}
+function createDecisionAbortState(input) {
+    let rejectAbortPromise;
+    let timeoutId;
+    let timedOut = false;
+    const abortPromise = new Promise((_resolve, reject) => {
+        rejectAbortPromise = reject;
+    });
+    if (input.timeoutMs === 0) {
+        if (!input.signal) {
+            return {
+                signal: undefined,
+                abortPromise: undefined,
+                didCallerAbort: () => false,
+                didTimeout: () => false,
+                dispose: () => { },
+            };
+        }
+        const abortFromCaller = () => {
+            rejectAbortPromise?.(new AvertaSdkError("Averta decision request was aborted.", "decision_request_aborted", {
+                cause: input.signal?.reason,
+            }));
+        };
+        input.signal.addEventListener("abort", abortFromCaller, { once: true });
+        return {
+            signal: input.signal,
+            abortPromise,
+            didCallerAbort: () => input.signal?.aborted === true,
+            didTimeout: () => false,
+            dispose: () => {
+                input.signal?.removeEventListener("abort", abortFromCaller);
+            },
+        };
+    }
+    const controller = new AbortController();
+    const abortFromCaller = () => {
+        controller.abort(input.signal?.reason);
+        rejectAbortPromise?.(new AvertaSdkError("Averta decision request was aborted.", "decision_request_aborted", {
+            cause: input.signal?.reason,
+        }));
+    };
+    if (input.signal) {
+        input.signal.addEventListener("abort", abortFromCaller, { once: true });
+        if (input.signal.aborted) {
+            abortFromCaller();
+        }
+    }
+    timeoutId = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+        rejectAbortPromise?.(new AvertaSdkError("Averta decision request timed out.", "decision_request_timeout"));
+    }, input.timeoutMs);
+    return {
+        signal: controller.signal,
+        abortPromise,
+        didCallerAbort: () => input.signal?.aborted === true && !timedOut,
+        didTimeout: () => timedOut,
+        dispose: () => {
+            if (timeoutId) {
+                clearTimeout(timeoutId);
+            }
+            input.signal?.removeEventListener("abort", abortFromCaller);
+        },
+    };
+}
+export class AvertaDecisionClient {
+    avertaBaseUrl;
+    decisionTimeoutMs;
+    fetchImpl;
+    sdk;
+    constructor(options) {
+        this.avertaBaseUrl = options.avertaBaseUrl ?? DEFAULT_AVERTA_BASE_URL;
+        this.decisionTimeoutMs = normalizeDecisionTimeoutMs(options.decisionTimeoutMs);
+        this.fetchImpl = options.fetch ?? fetch;
+        this.sdk = options.sdk;
+        this.avertaApiKey = options.avertaApiKey;
+    }
+    avertaApiKey;
+    async preflight(input) {
+        const response = await this.sendDecisionRequest({
+            checkpointType: "request",
+            provider: input.provider,
+            payload: input.payload,
+            ...(input.tools ? { tools: input.tools } : {}),
+            requestContext: input.requestContext,
+            signal: input.signal,
+        });
+        assertDecisionForCheckpoint("request", response.decision);
+        if (hasForwardedTools({
+            blockedTools: response.blockedTools,
+            decision: response.decision,
+            tools: input.tools,
+        }) &&
+            !response.runId) {
+            throw new AvertaSdkError("Averta returned an invalid decision response.", "invalid_decision_response");
+        }
+        return response;
+    }
+    async checkToolCall(input) {
+        const response = await this.sendDecisionRequest({
+            checkpointType: "tool_call",
+            provider: input.provider,
+            requestContext: input.requestContext,
+            signal: input.signal,
+            context: input.context,
+            modelResponseToolCalls: input.modelResponseToolCalls,
+            toolCall: {
+                ...(input.arguments && input.arguments.value !== undefined
+                    ? {
+                        arguments: {
+                            value: input.arguments.value,
+                        },
+                    }
+                    : {}),
+                call_id: input.callId,
+                run_id: input.runId,
+                tool: {
+                    kind: input.tool.kind,
+                    name: input.tool.name,
+                },
+            },
+        });
+        assertDecisionForCheckpoint("tool_call", response.decision);
+        if (!response.tool) {
+            throw new AvertaSdkError("Averta returned an invalid decision response.", "invalid_decision_response");
+        }
+        return response;
+    }
+    async checkToolResult(input) {
+        const response = await this.sendDecisionRequest({
+            checkpointType: "tool_result",
+            toolResult: {
+                call_id: input.callId,
+                content: {
+                    value: input.content.value,
+                },
+            },
+            provider: input.provider,
+            requestContext: input.requestContext,
+            signal: input.signal,
+        });
+        assertDecisionForCheckpoint("tool_result", response.decision);
+        if (!response.runId || !response.tool) {
+            throw new AvertaSdkError("Averta returned an invalid decision response.", "invalid_decision_response");
+        }
+        return response;
+    }
+    async checkOutput(input) {
+        const response = await this.sendDecisionRequest({
+            checkpointType: "output",
+            output: {
+                content: {
+                    value: input.content.value,
+                },
+                rewrite_attempt: input.rewriteAttempt,
+            },
+            provider: input.provider,
+            requestContext: input.requestContext,
+            signal: input.signal,
+        });
+        assertDecisionForCheckpoint("output", response.decision);
+        return response;
+    }
+    async sendDecisionRequest(input) {
+        if (input.signal?.aborted) {
+            throw new AvertaSdkError("Averta decision request was aborted.", "decision_request_aborted", {
+                cause: input.signal.reason,
+            });
+        }
+        const abortState = createDecisionAbortState({
+            signal: input.signal,
+            timeoutMs: this.decisionTimeoutMs,
+        });
+        try {
+            const requestPromise = (async () => {
+                const response = await this.fetchImpl(`${this.avertaBaseUrl}/v1/decide`, {
+                    method: "POST",
+                    headers: {
+                        "content-type": "application/json",
+                        authorization: `Bearer ${this.avertaApiKey}`,
+                    },
+                    ...(abortState.signal ? { signal: abortState.signal } : {}),
+                    body: JSON.stringify({
+                        checkpoint_type: input.checkpointType,
+                        sdk: this.sdk,
+                        provider: toProviderPayload(input.provider),
+                        ...toCheckpointPayload(input),
+                        request_context: toRequestContextPayload(ensureRequestContext(input.requestContext)),
+                    }),
+                });
+                const payload = await response.json().catch((error) => {
+                    if (error instanceof SyntaxError) {
+                        return null;
+                    }
+                    throw error;
+                });
+                if (!response.ok) {
+                    throw this.createRequestError(payload, "Averta decision request failed.", "decision_request_failed", response.status);
+                }
+                return parseDecisionResponse(payload);
+            })();
+            return abortState.abortPromise
+                ? await Promise.race([requestPromise, abortState.abortPromise])
+                : await requestPromise;
+        }
+        catch (error) {
+            if (error instanceof AvertaSdkError) {
+                throw error;
+            }
+            throw this.createTransportError(error, abortState);
+        }
+        finally {
+            abortState.dispose();
+        }
+    }
+    createTransportError(cause, abortState) {
+        if (abortState.didTimeout()) {
+            return new AvertaSdkError("Averta decision request timed out.", "decision_request_timeout", {
+                cause,
+            });
+        }
+        if (abortState.didCallerAbort()) {
+            return new AvertaSdkError("Averta decision request was aborted.", "decision_request_aborted", {
+                cause,
+            });
+        }
+        return new AvertaSdkError("Averta decision request failed.", "decision_request_failed", {
+            cause,
+        });
+    }
+    createRequestError(payload, fallbackMessage, fallbackCode, statusCode) {
+        const message = isObject(payload) &&
+            isObject(payload.error) &&
+            typeof payload.error.message === "string"
+            ? payload.error.message
+            : fallbackMessage;
+        const code = isObject(payload) &&
+            isObject(payload.error) &&
+            typeof payload.error.code === "string"
+            ? payload.error.code
+            : fallbackCode;
+        return new AvertaSdkError(message, code, statusCode);
+    }
+}
+function toRequestContextPayload(input) {
+    return {
+        ...(input.conversationId ? { conversation_id: input.conversationId } : {}),
+        request_id: input.requestId,
+        trace_id: input.traceId,
+    };
+}

package/dist/errors.d.ts

@@ -0,0 +1,12 @@
+import type { DecisionResponse } from "./types.ts";
+export type AvertaSdkErrorOptions = {
+    cause?: unknown;
+    checkpointDecision?: DecisionResponse;
+    statusCode?: number;
+};
+export declare class AvertaSdkError extends Error {
+    readonly checkpointDecision?: DecisionResponse;
+    readonly code: string;
+    readonly statusCode?: number;
+    constructor(message: string, code: string, statusCodeOrOptions?: number | AvertaSdkErrorOptions, options?: AvertaSdkErrorOptions);
+}

package/dist/errors.js

@@ -0,0 +1,20 @@
+export class AvertaSdkError extends Error {
+    checkpointDecision;
+    code;
+    statusCode;
+    constructor(message, code, statusCodeOrOptions, options) {
+        const resolvedOptions = typeof statusCodeOrOptions === "number" ? options : statusCodeOrOptions;
+        super(message, resolvedOptions?.cause === undefined
+            ? undefined
+            : {
+                cause: resolvedOptions.cause,
+            });
+        this.name = "AvertaSdkError";
+        this.code = code;
+        this.statusCode =
+            typeof statusCodeOrOptions === "number"
+                ? statusCodeOrOptions
+                : resolvedOptions?.statusCode;
+        this.checkpointDecision = resolvedOptions?.checkpointDecision;
+    }
+}

package/dist/filter-tools.d.ts

@@ -0,0 +1 @@
+export declare function filterToolsByIdentity<T>(tools: readonly T[] | undefined, blockedTools: readonly string[] | undefined, getIdentity: (tool: T) => string | null | undefined): T[] | undefined;

package/dist/filter-tools.js

@@ -0,0 +1,13 @@
+export function filterToolsByIdentity(tools, blockedTools, getIdentity) {
+    if (!tools) {
+        return undefined;
+    }
+    if (!blockedTools || blockedTools.length === 0) {
+        return [...tools];
+    }
+    const blocked = new Set(blockedTools);
+    return tools.filter((tool) => {
+        const identity = getIdentity(tool);
+        return !identity || !blocked.has(identity);
+    });
+}

package/dist/guard-flow.d.ts

@@ -0,0 +1,90 @@
+import { AvertaSdkError } from "./errors.ts";
+import type { AvertaProviderMetadata, AvertaRequestContext, DecisionPayload, DecisionResponse, NormalizedToolDefinition, OutputDecisionInput, ToolCallContext, ToolCallDecisionInput, ToolCallDecisionCandidate, ToolResultDecisionInput } from "./types.ts";
+type DecisionClientWithPreflight = {
+    preflight(input: {
+        provider: AvertaProviderMetadata;
+        payload: DecisionPayload;
+        requestContext?: AvertaRequestContext;
+        tools?: NormalizedToolDefinition[];
+    }): Promise<DecisionResponse>;
+};
+type DecisionClientWithToolResultDecision = {
+    checkToolResult(input: ToolResultDecisionInput): Promise<DecisionResponse>;
+};
+type DecisionClientWithToolCallDecision = {
+    checkToolCall(input: ToolCallDecisionInput): Promise<DecisionResponse>;
+};
+type DecisionClientWithOutputDecision = {
+    checkOutput(input: OutputDecisionInput): Promise<DecisionResponse>;
+};
+export type PendingToolResultDecisionCandidate = {
+    callId: string;
+    content: {
+        value: unknown;
+    };
+};
+export type PreparedGuardedRequest<TTool> = {
+    blockedTools?: string[];
+    filteredTools: TTool[] | undefined;
+    runId?: string;
+};
+export declare function mergeBlockedTools(...blockedToolLists: Array<readonly string[] | undefined>): string[] | undefined;
+export declare function resolveContinuationRunId(decisions: Array<{
+    runId?: string;
+}>): string;
+export declare function throwDecisionError(decision: DecisionResponse, fallbackMessage: string, fallbackCode: string): never;
+export declare function createDecisionError(decision: DecisionResponse, fallbackMessage: string, fallbackCode: string): AvertaSdkError;
+export declare function checkToolCallsForRun(input: {
+    context: ToolCallContext;
+    decisionClient: DecisionClientWithToolCallDecision;
+    provider: AvertaProviderMetadata;
+    requestContext?: AvertaRequestContext;
+    responseToolCalls: ToolCallDecisionCandidate[];
+    runId: string | undefined;
+}): Promise<DecisionResponse[]>;
+export declare function prepareGuardedRequest<TTool>(input: {
+    decisionClient: DecisionClientWithPreflight & DecisionClientWithToolResultDecision;
+    filterTools: (tools: readonly TTool[] | undefined, blockedTools: readonly string[] | undefined) => TTool[] | undefined;
+    getPreflightInput: () => {
+        payload: DecisionPayload;
+        tools?: NormalizedToolDefinition[];
+    };
+    onRequestDecision?: (event: {
+        decision: DecisionResponse;
+        forwardedTools: TTool[];
+        originalTools: TTool[];
+        provider: AvertaProviderMetadata;
+    }) => void;
+    onToolResultDecision?: (event: {
+        decision: DecisionResponse;
+        provider: AvertaProviderMetadata;
+        tool: {
+            kind: string;
+            name: string;
+        };
+    }) => void;
+    originalTools: readonly TTool[] | undefined;
+    pendingToolResults: readonly PendingToolResultDecisionCandidate[];
+    provider: AvertaProviderMetadata;
+    requestContext?: AvertaRequestContext;
+}): Promise<PreparedGuardedRequest<TTool>>;
+export declare function guardNonStreamingOutput<TResult>(input: {
+    decisionClient: DecisionClientWithOutputDecision;
+    hasToolCalls: (result: TResult) => boolean;
+    initialResult: TResult;
+    onDecision?: (event: {
+        decision: DecisionResponse;
+        outputText: string;
+        provider: AvertaProviderMetadata;
+        rewriteAttempt: number;
+    }) => void;
+    provider: AvertaProviderMetadata;
+    readOutputText: (result: TResult) => string;
+    requestContext?: AvertaRequestContext;
+    rewrite: (input: {
+        decision: DecisionResponse;
+        outputText: string;
+        rewriteInstruction: string;
+    }) => Promise<TResult>;
+}): Promise<TResult>;
+export {};

package/dist/guard-flow.js

@@ -0,0 +1,180 @@
+import { AvertaSdkError } from "./errors.js";
+import { buildOutputRewriteInstruction } from "./output-rewrite.js";
+export function mergeBlockedTools(...blockedToolLists) {
+    const merged = new Set();
+    for (const blockedTools of blockedToolLists) {
+        if (!blockedTools) {
+            continue;
+        }
+        for (const blockedTool of blockedTools) {
+            merged.add(blockedTool);
+        }
+    }
+    return merged.size > 0 ? [...merged] : undefined;
+}
+export function resolveContinuationRunId(decisions) {
+    const runId = [...decisions]
+        .reverse()
+        .map((decision) => decision.runId)
+        .find((candidate) => typeof candidate === "string" && candidate.length > 0);
+    if (!runId) {
+        throw new AvertaSdkError("Averta did not return a run identifier for an active tool chain.", "missing_tool_run_id");
+    }
+    return runId;
+}
+export function throwDecisionError(decision, fallbackMessage, fallbackCode) {
+    throw createDecisionError(decision, fallbackMessage, fallbackCode);
+}
+export function createDecisionError(decision, fallbackMessage, fallbackCode) {
+    const reason = decision.reasons[0];
+    return new AvertaSdkError(reason?.message ?? fallbackMessage, reason?.code ?? fallbackCode, {
+        checkpointDecision: decision,
+    });
+}
+export async function checkToolCallsForRun(input) {
+    if (input.responseToolCalls.length === 0) {
+        return [];
+    }
+    if (!input.runId) {
+        throw new AvertaSdkError("Averta did not return a run identifier for an active tool chain.", "missing_tool_run_id");
+    }
+    const runId = input.runId;
+    return Promise.all(input.responseToolCalls.map((toolCall) => input.decisionClient.checkToolCall({
+        ...(toolCall.arguments && toolCall.arguments.value !== undefined
+            ? {
+                arguments: {
+                    value: toolCall.arguments.value,
+                },
+            }
+            : {}),
+        callId: toolCall.callId,
+        context: input.context,
+        modelResponseToolCalls: input.responseToolCalls,
+        provider: input.provider,
+        requestContext: input.requestContext,
+        runId,
+        tool: {
+            kind: toolCall.tool.kind,
+            name: toolCall.tool.name,
+        },
+    })));
+}
+export async function prepareGuardedRequest(input) {
+    let blockedTools;
+    let filteredTools;
+    let runId;
+    if (input.pendingToolResults.length > 0) {
+        const decisions = [];
+        for (const toolResult of input.pendingToolResults) {
+            const decision = await input.decisionClient.checkToolResult({
+                callId: toolResult.callId,
+                content: {
+                    value: toolResult.content.value,
+                },
+                provider: input.provider,
+                requestContext: input.requestContext,
+            });
+            decisions.push(decision);
+            blockedTools = mergeBlockedTools(blockedTools, decision.blockedTools);
+            input.onToolResultDecision?.({
+                decision,
+                provider: input.provider,
+                tool: decision.tool,
+            });
+            if (decision.decision === "block") {
+                throwDecisionError(decision, "The tool result was blocked by Averta.", "tool_result_blocked");
+            }
+        }
+        filteredTools = input.filterTools(input.originalTools, blockedTools);
+        runId = resolveContinuationRunId(decisions);
+    }
+    else {
+        const preflightInput = input.getPreflightInput();
+        const decision = await input.decisionClient.preflight({
+            provider: input.provider,
+            payload: preflightInput.payload,
+            requestContext: input.requestContext,
+            tools: preflightInput.tools,
+        });
+        blockedTools = mergeBlockedTools(blockedTools, decision.blockedTools);
+        filteredTools = input.filterTools(input.originalTools, blockedTools);
+        runId = decision.runId;
+        input.onRequestDecision?.({
+            decision,
+            originalTools: input.originalTools ? [...input.originalTools] : [],
+            forwardedTools: filteredTools ?? [],
+            provider: input.provider,
+        });
+        if (decision.decision === "block") {
+            throwDecisionError(decision, "The request was blocked by Averta.", "request_blocked");
+        }
+    }
+    return {
+        blockedTools,
+        filteredTools,
+        runId,
+    };
+}
+export async function guardNonStreamingOutput(input) {
+    if (input.hasToolCalls(input.initialResult)) {
+        return input.initialResult;
+    }
+    const outputText = input.readOutputText(input.initialResult);
+    if (!outputText) {
+        return input.initialResult;
+    }
+    const outputDecision = await input.decisionClient.checkOutput({
+        content: {
+            value: outputText,
+        },
+        provider: input.provider,
+        requestContext: input.requestContext,
+        rewriteAttempt: 0,
+    });
+    input.onDecision?.({
+        decision: outputDecision,
+        outputText,
+        provider: input.provider,
+        rewriteAttempt: 0,
+    });
+    if (outputDecision.decision === "allow") {
+        return input.initialResult;
+    }
+    if (outputDecision.decision === "block") {
+        throwDecisionError(outputDecision, "The output was blocked by Averta.", "output_blocked");
+    }
+    const rewriteInstruction = buildOutputRewriteInstruction(outputDecision);
+    if (!rewriteInstruction) {
+        throw new AvertaSdkError("Averta returned an invalid rewrite decision.", "invalid_decision_response");
+    }
+    const rewrittenResult = await input.rewrite({
+        decision: outputDecision,
+        outputText,
+        rewriteInstruction,
+    });
+    if (input.hasToolCalls(rewrittenResult)) {
+        throw new AvertaSdkError("Averta rewrite responses must not create new tool calls.", "invalid_rewrite_response");
+    }
+    const rewrittenOutputText = input.readOutputText(rewrittenResult);
+    if (!rewrittenOutputText) {
+        return rewrittenResult;
+    }
+    const rewrittenDecision = await input.decisionClient.checkOutput({
+        content: {
+            value: rewrittenOutputText,
+        },
+        provider: input.provider,
+        requestContext: input.requestContext,
+        rewriteAttempt: 1,
+    });
+    input.onDecision?.({
+        decision: rewrittenDecision,
+        outputText: rewrittenOutputText,
+        provider: input.provider,
+        rewriteAttempt: 1,
+    });
+    if (rewrittenDecision.decision !== "allow") {
+        throwDecisionError(rewrittenDecision, "The rewritten output was blocked by Averta.", "output_rewrite_blocked");
+    }
+    return rewrittenResult;
+}

package/dist/ids.d.ts

@@ -0,0 +1,4 @@
+import type { AvertaRequestContext, PreparedAvertaRequestContext } from "./types.ts";
+export declare function createRequestId(): string;
+export declare function createTraceId(): string;
+export declare function ensureRequestContext(requestContext?: AvertaRequestContext): PreparedAvertaRequestContext;

package/dist/ids.js

@@ -0,0 +1,16 @@
+function buildId(prefix) {
+    return `${prefix}_${crypto.randomUUID()}`;
+}
+export function createRequestId() {
+    return buildId("req");
+}
+export function createTraceId() {
+    return buildId("trc");
+}
+export function ensureRequestContext(requestContext) {
+    return {
+        ...requestContext,
+        requestId: requestContext?.requestId ?? createRequestId(),
+        traceId: requestContext?.traceId ?? createTraceId(),
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { AvertaDecisionClient } from "./decision-client.ts";
+export { AvertaSdkError } from "./errors.ts";
+export { createRequestId, createTraceId, ensureRequestContext } from "./ids.ts";
+export { filterToolsByIdentity } from "./filter-tools.ts";
+export { checkToolCallsForRun, guardNonStreamingOutput, mergeBlockedTools, prepareGuardedRequest, resolveContinuationRunId, throwDecisionError, } from "./guard-flow.ts";
+export { buildOutputRewriteInstruction } from "./output-rewrite.ts";
+export { buildForwardedToolInput, omitProviderFields } from "./provider-input.ts";
+export { StreamingOutputGuard } from "./streaming-output-guard.ts";
+export { isObject, readTrimmedString } from "./values.ts";
+export type { AvertaSdkErrorOptions, } from "./errors.ts";
+export type { AvertaProviderMetadata, AvertaRequestContext, AvertaSdkMetadata, DecisionClientOptions, DecisionPayload, DecisionPreflightInput, DecisionReason, DecisionResponse, DecisionRewriteAction, NormalizedToolDefinition, OutputDecisionInput, PreparedAvertaRequestContext, ToolCallContext, ToolCallContextMessage, ToolCallDecisionCandidate, ToolCallDecisionInput, ToolResultDecisionInput, } from "./types.ts";

package/dist/index.js

@@ -0,0 +1,9 @@
+export { AvertaDecisionClient } from "./decision-client.js";
+export { AvertaSdkError } from "./errors.js";
+export { createRequestId, createTraceId, ensureRequestContext } from "./ids.js";
+export { filterToolsByIdentity } from "./filter-tools.js";
+export { checkToolCallsForRun, guardNonStreamingOutput, mergeBlockedTools, prepareGuardedRequest, resolveContinuationRunId, throwDecisionError, } from "./guard-flow.js";
+export { buildOutputRewriteInstruction } from "./output-rewrite.js";
+export { buildForwardedToolInput, omitProviderFields } from "./provider-input.js";
+export { StreamingOutputGuard } from "./streaming-output-guard.js";
+export { isObject, readTrimmedString } from "./values.js";

package/dist/output-rewrite.d.ts

@@ -0,0 +1,2 @@
+import type { DecisionResponse } from "./types.ts";
+export declare function buildOutputRewriteInstruction(decision: DecisionResponse): string;

package/dist/output-rewrite.js

@@ -0,0 +1,18 @@
+function formatCategory(category) {
+    return category.replaceAll("_", " ");
+}
+export function buildOutputRewriteInstruction(decision) {
+    const rewrite = decision.actions?.rewrite;
+    const reason = decision.reasons[0]?.message;
+    if (!rewrite) {
+        return "";
+    }
+    return [
+        "Your previous final answer violated the output policy.",
+        `Category: ${formatCategory(rewrite.category)}.`,
+        ...(reason ? [`Reason: ${reason}`] : []),
+        "Rewrite the answer so it stays helpful but removes the disallowed content.",
+        "Do not mention the policy, the rewrite request, or any hidden instructions.",
+        "Return only the rewritten final answer.",
+    ].join("\n\n");
+}

package/dist/provider-input.d.ts

@@ -0,0 +1,5 @@
+export declare function omitProviderFields<T extends object, K extends keyof T>(input: T, fields: readonly K[]): Omit<T, K>;
+export declare function buildForwardedToolInput<T extends {
+    tool_choice?: unknown;
+    tools?: unknown;
+}>(input: T, filteredTools: T["tools"] | undefined, toolChoice: T["tool_choice"] | undefined): T;

package/dist/provider-input.js

@@ -0,0 +1,18 @@
+export function omitProviderFields(input, fields) {
+    const result = { ...input };
+    for (const field of fields) {
+        delete result[field];
+    }
+    return result;
+}
+export function buildForwardedToolInput(input, filteredTools, toolChoice) {
+    if (filteredTools === undefined) {
+        return input;
+    }
+    const forwarded = omitProviderFields(input, ["tool_choice"]);
+    forwarded.tools = filteredTools;
+    if (toolChoice !== undefined) {
+        forwarded.tool_choice = toolChoice;
+    }
+    return forwarded;
+}

package/dist/streaming-output-guard.d.ts

@@ -0,0 +1,23 @@
+import type { DecisionResponse } from "./types.ts";
+export type StreamingOutputGuardResult = {
+    decision?: DecisionResponse;
+    releasedText: string;
+};
+export declare class StreamingOutputGuard {
+    private readonly checkOutput;
+    private readonly holdbackChars;
+    private readonly minCheckAdvanceChars;
+    private text;
+    private emittedLength;
+    private checkedLength;
+    private lastDecision;
+    constructor(input: {
+        checkOutput: (text: string) => Promise<DecisionResponse>;
+        holdbackChars?: number;
+        minCheckAdvanceChars?: number;
+    });
+    get currentText(): string;
+    append(delta: string): Promise<StreamingOutputGuardResult>;
+    finalize(): Promise<StreamingOutputGuardResult>;
+    private maybeRelease;
+}

package/dist/streaming-output-guard.js

@@ -0,0 +1,69 @@
+import { AvertaSdkError } from "./errors.js";
+import { createDecisionError } from "./guard-flow.js";
+const DEFAULT_HOLDBACK_CHARS = 96;
+const DEFAULT_MIN_CHECK_ADVANCE_CHARS = 48;
+export class StreamingOutputGuard {
+    checkOutput;
+    holdbackChars;
+    minCheckAdvanceChars;
+    text = "";
+    emittedLength = 0;
+    checkedLength = 0;
+    lastDecision;
+    constructor(input) {
+        this.checkOutput = input.checkOutput;
+        this.holdbackChars = input.holdbackChars ?? DEFAULT_HOLDBACK_CHARS;
+        this.minCheckAdvanceChars =
+            input.minCheckAdvanceChars ?? DEFAULT_MIN_CHECK_ADVANCE_CHARS;
+    }
+    get currentText() {
+        return this.text;
+    }
+    async append(delta) {
+        this.text += delta;
+        return this.maybeRelease(false);
+    }
+    async finalize() {
+        return this.maybeRelease(true);
+    }
+    async maybeRelease(finalize) {
+        const releasableLength = finalize
+            ? this.text.length
+            : Math.max(0, this.text.length - this.holdbackChars);
+        if (releasableLength <= this.checkedLength) {
+            return {
+                decision: finalize && this.checkedLength === this.text.length
+                    ? this.lastDecision
+                    : undefined,
+                releasedText: "",
+            };
+        }
+        const uncheckedLength = releasableLength - this.checkedLength;
+        if (!finalize && uncheckedLength < this.minCheckAdvanceChars) {
+            return {
+                decision: undefined,
+                releasedText: "",
+            };
+        }
+        const nextText = this.text.slice(0, releasableLength);
+        const decision = await this.checkOutput(nextText);
+        if (decision.decision === "block") {
+            throw createDecisionError(decision, "The output was blocked by Averta.", "output_blocked");
+        }
+        if (decision.decision === "rewrite") {
+            const reason = decision.reasons[0];
+            throw new AvertaSdkError(reason?.message ??
+                "Averta required an output rewrite during streaming, which is not supported yet.", reason?.code ?? "streaming_output_rewrite_required", {
+                checkpointDecision: decision,
+            });
+        }
+        this.lastDecision = decision;
+        this.checkedLength = releasableLength;
+        const releasedText = this.text.slice(this.emittedLength, releasableLength);
+        this.emittedLength = releasableLength;
+        return {
+            decision: finalize && releasableLength === this.text.length ? decision : undefined,
+            releasedText,
+        };
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,131 @@
+export type AvertaRequestContext = {
+    conversationId?: string;
+    requestId?: string;
+    traceId?: string;
+};
+export type PreparedAvertaRequestContext = AvertaRequestContext & {
+    requestId: string;
+    traceId: string;
+};
+export type AvertaSdkMetadata = {
+    name: string;
+    version: string;
+};
+export type AvertaProviderMetadata = {
+    name: string;
+    operation: string;
+    model: string;
+    streaming?: boolean;
+};
+export type NormalizedToolDefinition = {
+    name: string;
+    type: string;
+    description?: string;
+    inputSchema?: Record<string, unknown>;
+};
+export type DecisionPayload = {
+    text: string;
+};
+export type DecisionPreflightInput = {
+    sdk: AvertaSdkMetadata;
+    provider: AvertaProviderMetadata;
+    payload: unknown;
+    signal?: AbortSignal;
+    tools?: NormalizedToolDefinition[];
+    requestContext?: AvertaRequestContext;
+};
+export type ToolResultDecisionInput = {
+    callId: string;
+    content: {
+        value: unknown;
+    };
+    provider: AvertaProviderMetadata;
+    requestContext?: AvertaRequestContext;
+    signal?: AbortSignal;
+};
+export type ToolCallDecisionInput = {
+    arguments?: {
+        value: unknown;
+    };
+    callId: string;
+    context: ToolCallContext;
+    modelResponseToolCalls: ToolCallDecisionCandidate[];
+    provider: AvertaProviderMetadata;
+    requestContext?: AvertaRequestContext;
+    runId: string;
+    signal?: AbortSignal;
+    tool: {
+        kind: string;
+        name: string;
+    };
+};
+export type ToolCallDecisionCandidate = {
+    arguments?: {
+        value: unknown;
+    };
+    callId: string;
+    tool: {
+        kind: string;
+        name: string;
+    };
+};
+export type ToolCallContextMessage = {
+    role: "user";
+    text: string;
+} | {
+    role: "assistant";
+    text?: string;
+    toolCalls?: ToolCallDecisionCandidate[];
+} | {
+    callId: string;
+    content: {
+        value: unknown;
+    };
+    role: "tool";
+};
+export type ToolCallContext = {
+    messages: ToolCallContextMessage[];
+};
+export type OutputDecisionInput = {
+    content: {
+        value: string;
+    };
+    provider: AvertaProviderMetadata;
+    requestContext?: AvertaRequestContext;
+    rewriteAttempt: number;
+    signal?: AbortSignal;
+};
+export type DecisionReason = {
+    code: string;
+    message: string;
+};
+export type DecisionRewriteAction = {
+    category: "secret_disclosure" | "system_prompt_disclosure" | "harmful_output";
+};
+export type DecisionResponse = {
+    actions?: {
+        rewrite?: DecisionRewriteAction;
+    };
+    blockedTools?: string[];
+    decision: "allow" | "block" | "restrict_tools" | "rewrite";
+    decisionId: string;
+    eventId: string;
+    policyId: string;
+    runId?: string;
+    reasons: DecisionReason[];
+    tool?: {
+        kind: string;
+        name: string;
+    };
+};
+export type DecisionClientOptions = {
+    avertaApiKey: string;
+    avertaBaseUrl?: string;
+    /**
+     * Maximum time to wait for an Averta decision request. Defaults to 30000.
+     * Set to 0 to disable the SDK-managed timeout.
+     */
+    decisionTimeoutMs?: number;
+    fetch?: typeof fetch;
+    sdk: AvertaSdkMetadata;
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/values.d.ts

@@ -0,0 +1,2 @@
+export declare function isObject(value: unknown): value is Record<string, unknown>;
+export declare function readTrimmedString(value: unknown): string | null;

package/dist/values.js

@@ -0,0 +1,6 @@
+export function isObject(value) {
+    return typeof value === "object" && value !== null;
+}
+export function readTrimmedString(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : null;
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@averta-security/sdk-core",
+  "version": "0.1.0-beta.0",
+  "description": "Shared Averta SDK decision-plane runtime primitives.",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE.md",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "clean": "node --input-type=module -e \"import { rmSync } from 'node:fs'; rmSync('dist', { recursive: true, force: true });\"",
+    "build": "npm run clean && node ../../node_modules/typescript/bin/tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "typecheck": "node ../../node_modules/typescript/bin/tsc -p tsconfig.json --noEmit",
+    "test": "node --test --experimental-strip-types \"src/**/*.test.ts\""
+  }
+}