glirastes 0.4.0 → 0.5.1

package/dist/cjs/runtime/turn-snapshot.js

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTurnSnapshot = createTurnSnapshot;
+exports.assertPromptPinForResume = assertPromptPinForResume;
+exports.isToolRevoked = isToolRevoked;
+const policy_overlay_js_1 = require("./policy-overlay.js");
+function deepFreeze(value) {
+    if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const child of Object.values(value)) {
+            deepFreeze(child);
+        }
+    }
+    return value;
+}
+function clone(value) {
+    return structuredClone(value);
+}
+function minBudget(local, agent, policy) {
+    return {
+        maxModelSteps: Math.min(local.maxModelSteps, agent.maxModelSteps, policy.maxModelSteps),
+        maxToolCalls: Math.min(local.maxToolCalls, agent.maxToolCalls, policy.maxToolCalls),
+        totalTimeoutMs: Math.min(local.totalTimeoutMs, agent.totalTimeoutMs, policy.totalTimeoutMs),
+        toolTimeoutMs: Math.min(local.toolTimeoutMs, agent.toolTimeoutMs, policy.toolTimeoutMs),
+        maxInputTokens: Math.min(local.maxInputTokens, agent.maxInputTokens, policy.maxInputTokens),
+        maxOutputTokens: Math.min(local.maxOutputTokens, agent.maxOutputTokens, policy.maxOutputTokens),
+        maxEstimatedCostUsd: Math.min(local.maxEstimatedCostUsd, agent.maxEstimatedCostUsd, policy.maxEstimatedCostUsd),
+        maxRepeatedFingerprint: Math.min(local.maxRepeatedFingerprint, agent.maxRepeatedFingerprint, policy.maxRepeatedFingerprint),
+        maxConsecutiveErrors: Math.min(local.maxConsecutiveErrors, agent.maxConsecutiveErrors, policy.maxConsecutiveErrors),
+        delegation: {
+            maxDepth: Math.min(local.delegation.maxDepth, agent.delegation.maxDepth, policy.delegation.maxDepth),
+            maxBreadth: Math.min(local.delegation.maxBreadth, agent.delegation.maxBreadth, policy.delegation.maxBreadth),
+            sharedBudget: local.delegation.sharedBudget
+                || agent.delegation.sharedBudget
+                || policy.delegation.sharedBudget,
+        },
+    };
+}
+/**
+ * Applies the signed `toolOverrides` deltas of a Platform policy revision to
+ * its reported `toolPolicies` (`applyPolicyOverlay`). A revision composed by
+ * the local runtime source carries no deltas and stays as it is; one a
+ * consumer takes straight from a Platform deployment no longer runs a tool
+ * the Platform disabled, and switches a confirmation off only for tools the
+ * local code report names in `relaxableToolIds` (D16). Applying the same
+ * deltas twice changes nothing.
+ */
+function withPlatformDecisions(policyRevision, relaxableToolIds) {
+    const deltas = policyRevision.toolOverrides ?? [];
+    if (deltas.length === 0)
+        return policyRevision;
+    return {
+        ...policyRevision,
+        toolPolicies: (0, policy_overlay_js_1.applyPolicyOverlay)(policyRevision.toolPolicies, deltas, relaxableToolIds ? { relaxableToolIds } : {}).policies,
+    };
+}
+function createTurnSnapshot(options) {
+    const { agentRevision, manifestRevision, policyRevision, principal, } = options;
+    const tenantIds = new Set([
+        agentRevision.tenantId,
+        manifestRevision.tenantId,
+        policyRevision.tenantId,
+        principal.tenantId,
+    ]);
+    if (tenantIds.size !== 1) {
+        throw new Error('Cannot create turn snapshot across tenant boundaries');
+    }
+    if (manifestRevision.environmentId !== policyRevision.environmentId) {
+        throw new Error('Cannot create turn snapshot with mismatched environments');
+    }
+    const snapshot = {
+        turnId: options.turnId,
+        startedAt: options.startedAt ?? new Date().toISOString(),
+        principal: clone(principal),
+        agentRevision: clone(agentRevision),
+        manifestRevision: clone(manifestRevision),
+        policyRevision: clone(withPlatformDecisions(policyRevision, options.relaxableToolIds)),
+        budget: minBudget(options.localLimits, agentRevision.budget, policyRevision.budget),
+        ...(options.promptPin ? { promptPin: clone(options.promptPin) } : {}),
+    };
+    return deepFreeze(snapshot);
+}
+/**
+ * Resuming a turn must never silently change its prompt revision. A turn that
+ * pinned a prompt bundle can only resume on the identical revision and digest.
+ */
+function assertPromptPinForResume(snapshot, pin) {
+    const pinned = snapshot.promptPin;
+    if (!pinned)
+        return;
+    if (!pin) {
+        throw new Error('Cannot resume a turn without its pinned prompt revision');
+    }
+    if (pin.revisionId !== pinned.revisionId || pin.revision !== pinned.revision) {
+        throw new Error('Resumed prompt revision does not match the pinned prompt revision');
+    }
+    if (pin.bundleDigest !== pinned.bundleDigest) {
+        throw new Error('Resumed prompt bundle digest does not match the pinned digest');
+    }
+}
+function isToolRevoked(snapshot, toolId, revocations, at = new Date()) {
+    const timestamp = at.getTime();
+    return revocations.some((revocation) => {
+        if (revocation.environmentId !== snapshot.manifestRevision.environmentId)
+            return false;
+        if (Date.parse(revocation.effectiveAt) > timestamp)
+            return false;
+        return revocation.toolIds.includes(toolId)
+            || revocation.agentRevisionIds.includes(snapshot.agentRevision.revisionId)
+            || revocation.policyRevisionIds.includes(snapshot.policyRevision.revisionId);
+    });
+}

package/dist/cjs/server/adapters/nextjs/approval-binding.d.ts

@@ -0,0 +1,334 @@
+import { type AiSdkApprovalGate } from '../../../runtime/ai-sdk/engine.js';
+/**
+ * Approvals the server asked for, bound to the call they were asked for.
+ *
+ * When a tool call needs the user's approval, the AI SDK ends the turn with an
+ * approval request. The browser sends the whole history back with the answer,
+ * and the SDK then runs the approved call with the tool name and input *from
+ * that history*, which the client wrote. Without a binding, a forged history
+ * runs any tool with any input, and an old approved history runs it again.
+ *
+ * The binding is the approval id itself. The AI SDK sends the id to the
+ * client, keeps it through `addToolApprovalResponse`, returns it in the
+ * history and passes it on through `convertToModelMessages`; no other field of
+ * an approval request survives that round trip (the stream chunk has only
+ * `approvalId` and `toolCallId`). The id has the form
+ *
+ *   glirastes-approval.v1.<issuedAtMs>.<expiresAtMs>.<nonce>.<mac>
+ *
+ * where `mac` is an HMAC-SHA-256, keyed with a server secret, over the issue
+ * time, the expiry, the nonce, the scope, the tool call id, the tool name and
+ * the canonical JSON of the input. The expiry is the issuing handler's
+ * decision and is signed, so a handler with a longer `approvalMaxAgeMs` that
+ * shares the secret cannot accept what the issuer would refuse; the verifier
+ * applies its own maximum age on top. (The format gained the expiry before
+ * 0.5.0 was published, which is why it is still `v1`.)
+ */
+export declare const DEFAULT_APPROVAL_MAX_AGE_MS: number;
+/** The longest `approvalMaxAgeMs` accepted: 24 hours. */
+export declare const MAX_APPROVAL_MAX_AGE_MS: number;
+/**
+ * Throws unless `value` is a usable maximum approval age: a whole number of milliseconds above 0
+ * and at most 24 hours. A fractional age would sign an expiry the id format cannot carry.
+ */
+export declare function assertApprovalMaxAge(value: unknown): asserts value is number;
+export declare const APPROVAL_SECRET_ENV = "GLIRASTES_APPROVAL_SECRET";
+export type ApprovalDenialCode = 'approval_not_issued' | 'approval_expired' | 'approval_already_used' | 'approval_store_unavailable' | 'approval_not_runnable';
+/**
+ * Optional single-use store. `consume(approvalId, expiresAtMs, { scope })`
+ * returns false when the id was used before, in any scope: single use is by
+ * id alone. It is called only for an approval that verified and is about to
+ * run, so forged ids never reach it.
+ *
+ * - `approvalId`: the canonical id of the verified approval, never the text
+ *   the client sent.
+ * - `expiresAtMs`: the expiry signed into the id; keep the id at least until
+ *   then.
+ * - `scope`: the quota scope, for limiting how many live ids one caller may
+ *   hold. It is `JSON.stringify([tenantId, subjectId])` for a managed turn,
+ *   else `JSON.stringify([value])` with the value `approvalScope(request)`
+ *   returned, else `caller:<hmac>` (base64url HMAC-SHA-256 under the approval secret of
+ *   the request's `Authorization` header, else its `Cookie` header; the raw
+ *   header is never passed), else `''` for a request without credentials.
+ *   The `caller:` key is not signed into the id and can change between the
+ *   request for an approval and its answer; use it for quotas, never for
+ *   single use.
+ */
+export interface ApprovalStore {
+    consume: (approvalId: string, expiresAtMs: number, context?: {
+        scope: string;
+    }) => boolean | Promise<boolean>;
+}
+/**
+ * Default size of the in-process single-use store (a few MB at most). With
+ * the per-scope default, at least 100 scopes must use up their quota before
+ * the store is full for everyone.
+ */
+export declare const DEFAULT_MEMORY_APPROVAL_STORE_ENTRIES = 20000;
+/** Default share of the in-process store one scope may hold. */
+export declare const DEFAULT_MEMORY_APPROVAL_STORE_ENTRIES_PER_SCOPE = 200;
+/** Approved calls that can run in one request; more is refused (`too_many_approvals`). */
+export declare const MAX_RUNNABLE_APPROVALS_PER_REQUEST = 32;
+/**
+ * A single-use store in this process's memory. Each id is kept until its
+ * approval has expired (plus the allowed clock skew), after which it can no
+ * longer verify anyway. The store is bounded: when it holds `maxEntries` live
+ * ids, or the approval's scope holds `maxEntriesPerScope`, `consume` throws,
+ * which the handler reports as `approval_store_unavailable`, rather than
+ * forgetting a live id and letting it run again. The per-scope quota keeps
+ * one scope from filling the store for everyone else. The scope is the one
+ * `ApprovalStore` describes: the managed tenant and subject, else
+ * `approvalScope`, else a key derived from the request's credentials
+ * (`caller:<hmac>`), else `''`, which all requests without credentials share.
+ * A caller who varies their credentials gets a fresh quota per value; the
+ * global `maxEntries` still bounds them, and only consumed genuine approvals
+ * create entries.
+ *
+ * It protects one process only. Instances behind a load balancer each have
+ * their own memory, so an approved history replayed to another instance runs
+ * there again unless they share an `approvalStore`.
+ */
+export declare function createMemoryApprovalStore(options?: {
+    maxEntries?: number;
+    maxEntriesPerScope?: number;
+    now?: () => number;
+}): ApprovalStore;
+/** The in-process store every handler of this process shares when none is configured. */
+export declare function defaultApprovalStore(): ApprovalStore;
+export interface ApprovalCall {
+    readonly toolCallId: string;
+    readonly toolName: string;
+    readonly input: unknown;
+}
+export type ApprovalVerification = 
+/**
+ * `key` names the approval for single use: the canonical id, rebuilt from
+ * the issue time, the nonce and the MAC this binder computed, never from the
+ * presented text. `expiresAtMs` is the signed expiry: the latest moment any
+ * handler with this secret can accept the approval, so a single-use store
+ * must keep the key until then, even when this handler's own maximum age
+ * ends earlier.
+ */
+{
+    readonly ok: true;
+    readonly expiresAtMs: number;
+    readonly key: string;
+} | {
+    readonly ok: false;
+    readonly code: 'approval_not_issued' | 'approval_expired';
+};
+export interface ApprovalBinder {
+    issue: (call: ApprovalCall) => string;
+    verify: (call: ApprovalCall & {
+        approvalId: string;
+    }) => ApprovalVerification;
+    readonly maxAgeMs: number;
+    /**
+     * A store quota key for a caller's credentials: `caller:` and an
+     * HMAC-SHA-256 of them under the approval secret. The credentials are not
+     * kept; the key reveals nothing about them without the secret.
+     */
+    callerQuotaKey?: (credentials: string) => string;
+}
+export declare class ApprovalSecretMissingError extends Error {
+    readonly code = "approval_secret_missing";
+    constructor();
+}
+/**
+ * JSON with sorted keys, so an input hashes the same after any JSON round
+ * trip. A non-finite number (`JSON.parse` turns `1e999` into `Infinity`)
+ * throws a RangeError: `JSON.stringify` would write it as `null`, so an
+ * approval for `null` would also hold for it.
+ */
+export declare function canonicalJson(value: unknown): string;
+/**
+ * The binder scope of a principal. Tenant and subject are encoded as a JSON
+ * array, so ids that contain a separator cannot make two principals share a
+ * scope (`acme:ops` + `alice` and `acme` + `ops:alice`).
+ */
+export declare function approvalScope(principal: {
+    tenantId: string;
+    subjectId: string;
+} | undefined): string;
+export declare function createApprovalBinder(options: {
+    secret: string;
+    /** Who the approval is for, e.g. tenant and subject; part of the MAC. */
+    scope?: string;
+    maxAgeMs?: number;
+    now?: () => number;
+}): ApprovalBinder;
+/**
+ * The binder of a request. The secret is the configured one, else
+ * `GLIRASTES_APPROVAL_SECRET`. Without one, and when approvals can occur, a
+ * production process refuses to serve them (`ApprovalSecretMissingError`);
+ * any other process derives a random secret that lives as long as the process
+ * and warns once. Approvals then do not survive a restart or reach another
+ * instance, which is why they are refused in production.
+ */
+export declare function resolveApprovalBinder(options: {
+    secret?: string;
+    env?: Record<string, string | undefined>;
+    hasApprovalTools: boolean;
+    scope?: string;
+    maxAgeMs?: number;
+    now?: () => number;
+    warn?: (message: string) => void;
+}): ApprovalBinder;
+type Chunk = {
+    type: string;
+};
+/**
+ * Gives every approval request of a UI message stream an id bound to the
+ * call it announced (tool name and input come from the preceding
+ * `tool-input-available` chunk, which is also what the client stores).
+ */
+export declare function bindApprovalRequests<T extends Chunk>(stream: ReadableStream<T>, binder: ApprovalBinder): ReadableStream<T>;
+export type ApprovalHistoryErrorCode = 'duplicate_tool_call_id' | 'duplicate_approval_id' | 'approval_malformed' | 'tool_part_malformed' | 'too_many_approvals';
+/** A history the handler refuses as a whole (HTTP 400) instead of repairing it. */
+export declare class ApprovalHistoryError extends Error {
+    readonly code: ApprovalHistoryErrorCode;
+    constructor(code: ApprovalHistoryErrorCode, message: string);
+}
+/**
+ * Refuses a history that the AI SDK could read in more than one way.
+ *
+ * - Every tool part has a string tool call id, and a dynamic tool part a
+ *   tool name that is a non-empty string (`tool_part_malformed`): the AI SDK
+ *   converts any value and looks the tool up with it.
+ * - A tool call id may belong to one tool part only, in the whole history
+ *   (`duplicate_tool_call_id`). The AI SDK maps an approval response to a
+ *   tool call by the tool call id alone (`collectToolApprovals` keeps the last
+ *   tool call of an id, and the model message sanitizer keeps the first one of
+ *   a message), so a second part with the same id can lend its tool name and
+ *   input to the approval of the other one.
+ * - An approval id may belong to one tool part only, in the whole history
+ *   (`duplicate_approval_id`). Every part with an `approval` becomes an
+ *   approval request with that id, and `collectToolApprovals` keeps the last
+ *   request of an id, so a copy of a genuine id on another part would take
+ *   over the genuine part's approved answer.
+ * - An `approval` is an object with a non-empty string `id`, and its
+ *   `approved`, when set, is a boolean (`approval_malformed`). The AI SDK
+ *   turns any value other than `null` / `undefined` into an approval response
+ *   and treats a truthy one as approved.
+ *
+ * The AI SDK's own client never writes any of these: its UI message reducer
+ * (`updateToolPart` / `updateDynamicToolPart` in `processUIMessageStream`)
+ * updates the existing part of a tool call id in place, also for a
+ * provider-executed tool whose result arrives later, an approval continuation
+ * goes on in the same assistant message, and every approval request carries
+ * its own id. There is therefore no legitimate shape with a repeated id, and
+ * none is allowed.
+ */
+export declare function assertUnambiguousToolHistory(messages: ReadonlyArray<unknown>): void;
+export interface DeniedApproval {
+    readonly toolCallId: string;
+    readonly code: ApprovalDenialCode;
+}
+/** An approved call of the history that passed every check of this request. */
+export interface VerifiedApproval {
+    readonly toolCallId: string;
+    readonly toolName: string;
+    readonly input: unknown;
+}
+/**
+ * Checks, before anything runs, every tool part of the request history that
+ * carries an approval, whatever its state, its answer and whether or not the
+ * provider executed it. The history must first pass
+ * `assertUnambiguousToolHistory` (this function calls it and throws
+ * `ApprovalHistoryError`).
+ *
+ * - An approved part that the AI SDK can run in this request (no result yet,
+ *   or provider-executed, and in the last block of a last assistant message,
+ *   see `runnableBlockOf`) needs an approval id issued for exactly this tool
+ *   call id, tool name and input, not older than the maximum age, not used
+ *   before in this history and not consumed before by the store (with the
+ *   request's scope). More than `MAX_RUNNABLE_APPROVALS_PER_REQUEST` of them
+ *   refuse the request (`too_many_approvals`) before any is consumed. A part that
+ *   fails is rewritten to `output-denied` with the code as its reason, so the
+ *   model messages carry a denied result for it and the AI SDK runs nothing.
+ *   The request continues: the model sees the denial and answers.
+ * - Every other approved part without a result (an earlier block, an
+ *   earlier message, a history with any trailing message) is rewritten to
+ *   `output-denied` with the reason `approval_not_runnable` (or
+ *   `approval_not_issued` with an id that verifies for nothing, when its id
+ *   was not issued for it). It is neither consumed nor handed to the gate.
+ * - Every other part with an approval (one that holds its result, an
+ *   unanswered request, a refusal) needs an id issued for this tool call id,
+ *   tool name and input; age and use do not count. A part that fails loses
+ *   its approval (an `output-denied` part, which the AI SDK cannot convert
+ *   without one, gets an id of its own that verifies for nothing). Such parts
+ *   are not refused, because an honest history holds them after a secret
+ *   rotation, a restart of a process without a configured secret, or from
+ *   0.4.0; they run nothing either way.
+ *
+ * The invariants this establishes, together with `assertUnambiguousToolHistory`:
+ *
+ * 1. Every approved part without a result that is left in the history is in
+ *    `verified`, so it passed binding, age, single use and the cap. Every
+ *    other approved part either holds its result or is denied. The AI SDK
+ *    runs an approved call only from a part without a result, so it can run
+ *    only verified calls, whatever it treats as the last step; this does not
+ *    depend on predicting which shapes it runs (tested against the installed
+ *    `ai` for the shapes the reviews found).
+ * 2. Every approval id left in the history belongs to exactly one tool part
+ *    and was issued for that part's tool call id, tool name and model input
+ *    (the input `convertToModelMessages` writes, `rawInput` for an
+ *    `output-error` part without input). The AI SDK pairs an approved answer
+ *    with a call by approval id → the one request with that id, emitted from
+ *    the same part → its tool call id, which is unique → the tool call
+ *    emitted from that same part. So an approved answer can only ever pair
+ *    with the call its id was issued for.
+ */
+export declare function enforceApprovalBindings(messages: ReadonlyArray<unknown>, options: {
+    binder: ApprovalBinder;
+    store?: ApprovalStore;
+    scope?: string;
+    /**
+     * The tools this server runs itself. A client cannot mark one of them as
+     * provider-executed: the flag is removed from their parts, so an approved
+     * part of a local tool is always checked, consumed and run as a local
+     * call (and never consumed for a run that does not happen).
+     */
+    localToolNames?: ReadonlySet<string>;
+}): Promise<{
+    messages: unknown[];
+    denied: DeniedApproval[];
+    verified: VerifiedApproval[];
+}>;
+/** Why the execution gate refused a call; the tool error the model sees starts with it. */
+export type ApprovalExecutionRefusal = 'approval_not_verified' | 'approval_already_used';
+export declare class ApprovalExecutionRefusedError extends Error {
+    readonly code: ApprovalExecutionRefusal;
+    constructor(code: ApprovalExecutionRefusal, toolName: string);
+}
+/**
+ * The second layer of the binding, checked where the tool executes.
+ *
+ * The AI SDK never executes a call within the run whose `needsApproval`
+ * answered true: it emits the approval request and the run ends (traced in
+ * `ai` 6.0: `runToolsTransformation` stops at `isApprovalNeeded`, and only
+ * `collectToolApprovals` on the next request's history executes an approved
+ * call). So a gated tool executes only
+ *
+ * - for an approval this request verified, with exactly its tool call id,
+ *   tool name and canonical input, once; or
+ * - for a live call whose `needsApproval` this run answered with false.
+ *
+ * Everything else, including a call whose `needsApproval` was never asked,
+ * is refused.
+ */
+export declare function createApprovalExecutionGate(verified: ReadonlyArray<VerifiedApproval>): AiSdkApprovalGate;
+interface GateableTool {
+    needsApproval?: unknown;
+    execute?: (input: unknown, options?: unknown) => unknown;
+    [key: string]: unknown;
+}
+/**
+ * Puts the gate on every tool for which `isGated` says it can ask for
+ * approval. The gated tool records its own `needsApproval` answers and checks
+ * the gate in its own `execute`, so a stream handler that builds AI SDK tools
+ * from these objects itself is held to the gate as well; `createAiSdkTools`
+ * finds the gate on the tool and checks it with the input before validation.
+ */
+export declare function gateApprovalTools<T extends Record<string, unknown>>(tools: T, gate: AiSdkApprovalGate, isGated: (toolName: string, tool: GateableTool) => boolean): T;
+export {};