@nylorun/runtime 0.14.0-beta → 0.15.1-beta

package/dist/gates/handler.js

@@ -0,0 +1,55 @@
+/**
+ * Serves one model call in the gates service: opens the Tenant's vault (the database's one
+ * Tenant; a call naming another is refused) and calls the model
+ * through `inProcessModelGate`, the same code the loop ran before the gate, so outcomes,
+ * retries, classification and redaction are unchanged. The meter records the call's usage in
+ * the Tenant's ledger. Logs one line per call, never the prompt, the output or a credential.
+ */
+import { classifyThrown } from "../model/classify.js";
+import { inProcessModelGate } from "./in-process.js";
+import { createMeter } from "./meter.js";
+import { GateRefusal } from "./tenant-vaults.js";
+export function createModelCallHandler(options) {
+    const { vaults, logger, settings } = options;
+    const meter = createMeter({ logger });
+    return {
+        async call(named, signal) {
+            const started = Date.now();
+            let request = named;
+            let outcome;
+            try {
+                const vault = await vaults.open(named.tenantId);
+                const call = { ...named, tenantId: vault.tenantId };
+                request = call;
+                const gate = inProcessModelGate({
+                    root: vault.root,
+                    readHostModel: () => vault.readHostModel(),
+                    writeHostCredential: (credential) => vault.writeHostCredential(credential),
+                    ...(settings ? { settings } : {}),
+                });
+                outcome = await meter.call(vault.store, call, () => gate.call(call, signal));
+            }
+            catch (error) {
+                if (signal.aborted) {
+                    logger.info("model_call", { ...fields(request), ms: Date.now() - started, outcome: "aborted" });
+                    throw error;
+                }
+                outcome = error instanceof GateRefusal ? error.outcome : classifyThrown(error);
+            }
+            logger.info("model_call", {
+                ...fields(request),
+                ms: Date.now() - started,
+                outcome: typeof outcome === "object" && outcome !== null && "kind" in outcome
+                    ? outcome.code
+                    : "ok",
+            });
+            return outcome;
+        },
+    };
+}
+const fields = (request) => ({
+    tenant: request.tenantId,
+    session: request.sessionId,
+    effect: request.effectId,
+    ...(request.call.model?.id ? { model: request.call.model.id } : {}),
+});

package/dist/gates/http-client.d.ts

@@ -0,0 +1,12 @@
+import type { ModelGate } from "./model-gate.js";
+/** Above the gate's 600 s provider request timeout. */
+export declare const GATE_CLIENT_TIMEOUT_MS = 630000;
+export interface HttpModelGateOptions {
+    /** The gates service, e.g. `http://gateway:4100` (`NYLORUN_GATES_URL`). */
+    readonly url: string;
+    /** `NYLORUN_GATES_TOKEN`. */
+    readonly token: string;
+    /** How long the connection may stay silent. Default `GATE_CLIENT_TIMEOUT_MS`. */
+    readonly timeoutMs?: number;
+}
+export declare function httpModelGate(options: HttpModelGateOptions): ModelGate;

package/dist/gates/http-client.js

@@ -0,0 +1,160 @@
+/**
+ * The loop's client of the gates service (blueprint §15, P1.1): each vault-backed model call
+ * is one POST to the gate and one JSON answer, `gates/contract.ts`. The loop never sees the
+ * model credential.
+ *
+ * Over `node:http`, not `fetch`: the gate answers only when the call has finished, and
+ * `fetch`'s default 300 s headers timeout would end every longer call. The only timeout here
+ * is the socket's idle time, above the gate's own 600 s provider timeout.
+ *
+ * A failure of the hop is a failure outcome, never a throw: `resolveEffect` marks anything
+ * thrown `uncertain`. Only an abort of the caller's signal throws. The client never retries;
+ * the gate retries the provider.
+ */
+import { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { failure } from "../model/classify.js";
+import { MODEL_CALLS_PATH, TENANT_HEADER, } from "./contract.js";
+/** How long a cancel may take; the call it stops ends with the provider timeout anyway. */
+const CANCEL_TIMEOUT_MS = 2_000;
+/** Above the gate's 600 s provider request timeout. */
+export const GATE_CLIENT_TIMEOUT_MS = 630_000;
+export function httpModelGate(options) {
+    const endpoint = new URL(MODEL_CALLS_PATH, options.url);
+    const send = endpoint.protocol === "https:" ? httpsRequest : httpRequest;
+    const timeoutMs = options.timeoutMs ?? GATE_CLIENT_TIMEOUT_MS;
+    const where = new URL(options.url).origin;
+    return {
+        recovers: true,
+        async cancel(request) {
+            const url = new URL(`${MODEL_CALLS_PATH}/${encodeURIComponent(request.effectId)}/cancel`, options.url);
+            await new Promise((resolve) => {
+                const outgoing = send(url, {
+                    method: "POST",
+                    headers: {
+                        authorization: `Bearer ${options.token}`,
+                        [TENANT_HEADER]: request.tenantId,
+                        "content-length": 0,
+                    },
+                    timeout: CANCEL_TIMEOUT_MS,
+                }, (response) => {
+                    response.resume();
+                    response.on("end", resolve);
+                    response.on("error", () => resolve());
+                });
+                outgoing.on("timeout", () => outgoing.destroy());
+                outgoing.on("error", () => resolve());
+                outgoing.end();
+            });
+        },
+        async call(request, signal) {
+            signal.throwIfAborted();
+            const body = {
+                sessionId: request.sessionId,
+                turnId: request.turnId,
+                agentId: request.agentId,
+                effectId: request.effectId,
+                invocationId: request.invocationId,
+                call: request.call,
+            };
+            const payload = Buffer.from(JSON.stringify(body), "utf8");
+            return new Promise((resolve, reject) => {
+                let settled = false;
+                /** True once the whole request was handed to the socket. */
+                let sent = false;
+                /** True once the gate's answer started; its body settles the call. */
+                let responded = false;
+                let timedOut = false;
+                const settle = (outcome) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    signal.removeEventListener("abort", onAbort);
+                    resolve(outcome);
+                };
+                const onAbort = () => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    outgoing.destroy();
+                    reject(signal.reason ?? new Error("aborted"));
+                };
+                const lost = (error) => settle(timedOut
+                    ? failure("transient", `Model gate at ${where} sent nothing for ${Math.round(timeoutMs / 1000)} s`, true)
+                    : sent
+                        ? failure("transient", `Model gate connection lost mid-call${error ? ` (${error.message})` : ""}; the provider may have billed the call`, true)
+                        : failure("transient", `Model gate unreachable at ${where}${error ? ` (${error.message})` : ""}`, true));
+                const outgoing = send(endpoint, {
+                    method: "POST",
+                    headers: {
+                        authorization: `Bearer ${options.token}`,
+                        "content-type": "application/json",
+                        "content-length": payload.byteLength,
+                        [TENANT_HEADER]: request.tenantId,
+                        "idempotency-key": request.effectId,
+                    },
+                    timeout: timeoutMs,
+                }, (response) => {
+                    responded = true;
+                    readBody(response).then((text) => settle(answer(response.statusCode ?? 0, text)), (error) => lost(error));
+                });
+                outgoing.on("socket", (socket) => socket.setKeepAlive(true, 30_000));
+                outgoing.on("finish", () => {
+                    sent = true;
+                });
+                outgoing.on("timeout", () => {
+                    timedOut = true;
+                    outgoing.destroy();
+                });
+                outgoing.on("error", (error) => {
+                    if (signal.aborted)
+                        return;
+                    lost(error);
+                });
+                outgoing.on("close", () => {
+                    if (!signal.aborted && !responded)
+                        lost();
+                });
+                signal.addEventListener("abort", onAbort, { once: true });
+                outgoing.end(payload);
+            });
+        },
+    };
+}
+function readBody(response) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        response.on("data", (chunk) => chunks.push(chunk));
+        response.on("end", () => {
+            if (response.complete)
+                resolve(Buffer.concat(chunks).toString("utf8"));
+            else
+                reject(new Error("response ended early"));
+        });
+        response.on("error", reject);
+        response.on("aborted", () => reject(new Error("response aborted")));
+    });
+}
+/** The outcome a gate answer stands for. */
+function answer(status, text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        parsed = undefined;
+    }
+    if (status === 200) {
+        if (typeof parsed === "object" && parsed !== null && "outcome" in parsed)
+            return parsed.outcome;
+        return failure("transient", "Model gate answered without an outcome", false);
+    }
+    const message = parsed?.error?.message;
+    if (status === 401)
+        return failure("auth", "The model gate refused this Runtime's token: the runtime and gateway containers must share NYLORUN_GATES_TOKEN", false);
+    if (status === 409)
+        return failure("invalid_request", `The call's request changed under the same effect id${message ? `: ${message}` : ""}`, false);
+    if (status === 400)
+        return failure("invalid_request", message ?? "The model gate refused the call", false);
+    return failure("transient", `Model gate answered ${status}${message ? `: ${message}` : ""}`, true);
+}

package/dist/gates/in-process.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The Model Gate in the caller's own process: `piModel` with the Tenant's host model. Used
+ * when nothing separates the loop from the credential anyway (the ephemeral Runtime,
+ * embedding, tests), and by the gates service itself to serve each call.
+ */
+import type { Credential } from "@earendil-works/pi-ai";
+import { type ModelCallSettings } from "../model/pi-model.js";
+import type { SessionStore } from "../store/types.js";
+import type { Logger } from "../tenant/types.js";
+import type { HostModelSecret } from "../vault/service.js";
+import type { ModelGate } from "./model-gate.js";
+export interface InProcessModelGateOptions {
+    /** The Tenant's home: `piModel` redacts secrets it finds there from failure messages. */
+    readonly root?: string;
+    readonly readHostModel: () => Promise<HostModelSecret | undefined>;
+    /** Writes back a credential pi-ai refreshed (OAuth). */
+    readonly writeHostCredential: (credential: Credential) => Promise<void>;
+    readonly settings?: ModelCallSettings;
+}
+/**
+ * The in-process gate of an open Tenant: reads its host model from its own vault and records
+ * each call in its usage ledger. Only a Runtime without the gates service (embedding, the
+ * ephemeral Runtime, tests) builds one.
+ */
+export declare function tenantModelGate(options: {
+    readonly store: SessionStore;
+    readonly kek: () => Buffer;
+    readonly root: string;
+    readonly logger: Logger;
+    readonly settings?: ModelCallSettings;
+}): ModelGate;
+export declare function inProcessModelGate(options: InProcessModelGateOptions): ModelGate;

package/dist/gates/in-process.js

@@ -0,0 +1,42 @@
+import { piModel } from "../model/pi-model.js";
+import { HostModelVault } from "../vault/host-model.js";
+import { createMeter } from "./meter.js";
+/**
+ * The in-process gate of an open Tenant: reads its host model from its own vault and records
+ * each call in its usage ledger. Only a Runtime without the gates service (embedding, the
+ * ephemeral Runtime, tests) builds one.
+ */
+export function tenantModelGate(options) {
+    const vault = new HostModelVault({ store: options.store, kek: options.kek });
+    const gate = inProcessModelGate({
+        root: options.root,
+        readHostModel: () => vault.readHostModel(),
+        writeHostCredential: (credential) => vault.updateHostCredential(credential),
+        ...(options.settings ? { settings: options.settings } : {}),
+    });
+    const meter = createMeter({ logger: options.logger });
+    return {
+        call: (request, signal) => meter.call(options.store, request, () => gate.call(request, signal)),
+    };
+}
+export function inProcessModelGate(options) {
+    return {
+        async call(request, signal) {
+            // One adapter per call, as before the gate: it reads the host model when invoked.
+            const adapter = piModel({
+                ...(options.root !== undefined ? { root: options.root } : {}),
+                readHostModel: options.readHostModel,
+                writeHostCredential: options.writeHostCredential,
+                ...(options.settings ? { settings: options.settings } : {}),
+            });
+            return adapter(request.call, {
+                // The Runtime never journals the provider request (harness `durable.ts`), and
+                // `piModel` doesn't read it.
+                request: undefined,
+                invocationId: request.invocationId,
+                signal,
+                reportPreparedCall() { },
+            });
+        },
+    };
+}

package/dist/gates/inflight.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The model calls (and, from F4.1, the remote MCP tool calls) the gates service is running or
+ * has just finished, by caller key (blueprint §15, P1.2). A call with an `Idempotency-Key` (the loop's effect id) runs under its own
+ * controller, so it outlives its client: when the runtime that sent it dies or shuts down, the
+ * runtime that takes the session over re-sends the call and joins it, or gets the outcome kept
+ * here, instead of calling the provider again.
+ *
+ * In memory, one gateway only (M2): a gateway restart loses these, and a re-sent call runs
+ * again (the ledger flags the duplicate). Outcomes are kept `ttlMs` after they settle; a call
+ * that throws (an abort) is not kept.
+ */
+import type { ModelGateOutcome } from "./model-gate.js";
+/** A re-send whose request differs from the call already running under its key. */
+export declare class InflightConflict extends Error {
+    readonly name = "InflightConflict";
+}
+export interface InflightCalls<T = ModelGateOutcome> {
+    /**
+     * Joins the call under `key`, or starts it with `start` under the entry's own signal.
+     * Rejects with `InflightConflict` when `hash` differs from the running call's.
+     */
+    run(key: string, hash: string, start: (signal: AbortSignal) => Promise<T>): Promise<T>;
+    /** True while a call runs under `key`, or its outcome is still kept. */
+    has(key: string): boolean;
+    /** Aborts the call under `key` and forgets it; nothing when there is none. */
+    cancel(key: string): void;
+    /** Aborts every running call (gateway shutdown). */
+    close(): void;
+    /** Entries held: running, or settled within the TTL. */
+    readonly size: number;
+}
+export interface InflightCallsOptions {
+    /** How long a settled outcome is kept. Default 30 minutes. */
+    readonly ttlMs?: number;
+    /** Most entries; the oldest settled ones go first. Default 10,000. */
+    readonly max?: number;
+    readonly now?: () => number;
+}
+export declare function createInflightCalls<T = ModelGateOutcome>(options?: InflightCallsOptions): InflightCalls<T>;

package/dist/gates/inflight.js

@@ -0,0 +1,70 @@
+/** A re-send whose request differs from the call already running under its key. */
+export class InflightConflict extends Error {
+    name = "InflightConflict";
+}
+export function createInflightCalls(options = {}) {
+    const ttlMs = options.ttlMs ?? 30 * 60_000;
+    const max = options.max ?? 10_000;
+    const now = options.now ?? Date.now;
+    const entries = new Map();
+    /** Drops expired outcomes, then the oldest settled ones while over `max`. */
+    function prune() {
+        const expired = now() - ttlMs;
+        for (const [key, entry] of entries)
+            if (entry.settledAt !== undefined && entry.settledAt <= expired)
+                entries.delete(key);
+        if (entries.size <= max)
+            return;
+        for (const [key, entry] of entries) {
+            if (entries.size <= max)
+                break;
+            if (entry.settledAt !== undefined)
+                entries.delete(key);
+        }
+    }
+    return {
+        run(key, hash, start) {
+            prune();
+            const existing = entries.get(key);
+            if (existing) {
+                if (existing.hash !== hash)
+                    return Promise.reject(new InflightConflict(`A different request is already running under ${key}`));
+                return existing.promise;
+            }
+            const controller = new AbortController();
+            const promise = start(controller.signal).then((outcome) => {
+                entry.settledAt = now();
+                return outcome;
+            }, (error) => {
+                if (entries.get(key) === entry)
+                    entries.delete(key);
+                throw error;
+            });
+            // Nobody may be waiting (the client went away); a rejection is not an unhandled one.
+            promise.catch(() => { });
+            const entry = { hash, controller, promise };
+            entries.set(key, entry);
+            return promise;
+        },
+        has(key) {
+            prune();
+            return entries.has(key);
+        },
+        cancel(key) {
+            const entry = entries.get(key);
+            if (!entry)
+                return;
+            entries.delete(key);
+            entry.controller.abort(new Error("The caller cancelled the call"));
+        },
+        close() {
+            for (const entry of entries.values())
+                if (entry.settledAt === undefined)
+                    entry.controller.abort(new Error("The gateway is shutting down"));
+            entries.clear();
+        },
+        get size() {
+            return entries.size;
+        },
+    };
+}

package/dist/gates/mcp-handler.d.ts

@@ -0,0 +1,35 @@
+import { openMcpServer, type McpToolPage } from "../mcp/connect.js";
+import { type McpServerRef } from "../mcp/pool.js";
+import type { Logger } from "../tenant/types.js";
+import type { McpAnswer } from "./tool-contract.js";
+import { type TenantVaults } from "./tenant-vaults.js";
+/** A connection unused this long is closed; the next request opens it again. */
+export declare const GATE_MCP_IDLE_MS: number;
+export interface McpHandlerOptions {
+    readonly vaults: TenantVaults;
+    readonly logger: Logger;
+    /** Default `GATE_MCP_IDLE_MS`. */
+    readonly idleMs?: number;
+    readonly now?: () => number;
+    /** Tests replace how a server is opened. */
+    readonly open?: typeof openMcpServer;
+}
+export interface McpHandler {
+    connect(tenantId: string | undefined, server: McpServerRef): Promise<McpAnswer<null>>;
+    list(tenantId: string | undefined, server: McpServerRef, cursor: string | undefined, signal: AbortSignal): Promise<McpAnswer<McpToolPage>>;
+    /** One `tools/call`; the raw `CallToolResult` on success. */
+    call(tenantId: string | undefined, request: {
+        server: McpServerRef;
+        effectId: string;
+        name: string;
+        arguments: Record<string, unknown>;
+    }, signal: AbortSignal): Promise<McpAnswer<Record<string, unknown>>>;
+    close(server: McpServerRef): Promise<void>;
+    /** Closes connections idle past the timeout. */
+    sweep(): Promise<void>;
+    /** Closes every connection (gateway shutdown). */
+    closeAll(): Promise<void>;
+    /** Open connections (tests). */
+    readonly size: number;
+}
+export declare function createMcpHandler(options: McpHandlerOptions): McpHandler;

package/dist/gates/mcp-handler.js

@@ -0,0 +1,142 @@
+import { openMcpServer, } from "../mcp/connect.js";
+import { findServer } from "../mcp/pool.js";
+import { GateRefusal } from "./tenant-vaults.js";
+/** A connection unused this long is closed; the next request opens it again. */
+export const GATE_MCP_IDLE_MS = 15 * 60_000;
+/** The server is not one the session may reach through the gate. */
+class NotDeclared extends Error {
+}
+export function createMcpHandler(options) {
+    const { vaults, logger } = options;
+    const idleMs = options.idleMs ?? GATE_MCP_IDLE_MS;
+    const now = options.now ?? Date.now;
+    const open = options.open ?? openMcpServer;
+    const live = new Map();
+    const opening = new Map();
+    const keyOf = (server) => JSON.stringify([server.sessionId, server.agentId ?? null, server.capabilityId, server.serverName]);
+    /** The declared remote server, from the session's pinned manifest. */
+    async function declared(vault, server) {
+        const session = await vault.session(server.sessionId);
+        if (!session)
+            throw new NotDeclared(`Session ${server.sessionId} not found`);
+        const found = findServer(session.manifest, server.agentId, server.capabilityId, server.serverName);
+        if (!found)
+            throw new NotDeclared(`MCP server '${server.serverName}' is not declared`);
+        if (found.server.type === "stdio")
+            throw new NotDeclared(`MCP server '${server.serverName}' is a stdio server, which runs beside the loop`);
+        return found.server;
+    }
+    async function connection(tenantId, server) {
+        const key = keyOf(server);
+        const existing = live.get(key);
+        if (existing)
+            return existing;
+        let pending = opening.get(key);
+        if (!pending) {
+            pending = (async () => {
+                const vault = await vaults.open(tenantId);
+                const manifest = await declared(vault, server);
+                const connection = await open({
+                    server: manifest,
+                    authorize: (url) => vault.authorizeMcp(server.sessionId, { url, serverName: server.serverName }),
+                    pluginData: "",
+                });
+                const entry = { connection, lastUsedAt: now(), active: 0 };
+                live.set(key, entry);
+                return entry;
+            })().finally(() => opening.delete(key));
+            opening.set(key, pending);
+        }
+        return pending;
+    }
+    async function answer(what, server, run, extra = {}) {
+        const started = now();
+        try {
+            const result = await run();
+            logger.info("mcp_request", { what, ...fields(server), ...extra, ms: now() - started, outcome: "ok" });
+            return { ok: true, result };
+        }
+        catch (error) {
+            const failed = errorOf(error);
+            logger.info("mcp_request", {
+                what,
+                ...fields(server),
+                ...extra,
+                ms: now() - started,
+                outcome: failed.code === undefined ? "failed" : String(failed.code),
+            });
+            return { ok: false, error: failed };
+        }
+    }
+    async function use(tenantId, server, run) {
+        const entry = await connection(tenantId, server);
+        entry.active += 1;
+        try {
+            return await run(entry);
+        }
+        finally {
+            entry.active -= 1;
+            entry.lastUsedAt = now();
+        }
+    }
+    return {
+        connect: (tenantId, server) => answer("connect", server, async () => {
+            await connection(tenantId, server);
+            return null;
+        }),
+        list: (tenantId, server, cursor, signal) => answer("list", server, () => use(tenantId, server, (entry) => entry.connection.client.listTools(cursor ? { cursor } : undefined, { signal }))),
+        call: (tenantId, request, signal) => answer("call", request.server, () => use(tenantId, request.server, (entry) => entry.connection.client.callTool({ name: request.name, arguments: request.arguments }, { signal })), { effect: request.effectId }),
+        async close(server) {
+            const key = keyOf(server);
+            const entry = live.get(key);
+            if (!entry)
+                return;
+            live.delete(key);
+            await entry.connection.close().catch(() => { });
+        },
+        async sweep() {
+            const cutoff = now() - idleMs;
+            const idle = [];
+            for (const [key, entry] of live) {
+                if (entry.active > 0 || entry.lastUsedAt > cutoff)
+                    continue;
+                live.delete(key);
+                idle.push(entry);
+            }
+            await Promise.all(idle.map((entry) => entry.connection.close().catch(() => { })));
+        },
+        async closeAll() {
+            const all = [...live.values()];
+            live.clear();
+            await Promise.all(all.map((entry) => entry.connection.close().catch(() => { })));
+        },
+        get size() {
+            return live.size;
+        },
+    };
+}
+function fields(server) {
+    return {
+        session: server.sessionId,
+        capability: server.capabilityId,
+        server: server.serverName,
+        ...(server.agentId === undefined ? {} : { agent: server.agentId }),
+    };
+}
+/** An error as the loop's `diagnosticFromError` reads it. */
+function errorOf(error) {
+    if (error instanceof GateRefusal)
+        return { message: error.outcome.message };
+    const message = error instanceof Error ? error.message.slice(0, 2000) : String(error);
+    const code = error && typeof error === "object" && "code" in error && typeof error.code === "number"
+        ? error.code
+        : undefined;
+    const credentialIds = error && typeof error === "object" && "credentialIds" in error
+        ? error.credentialIds
+        : undefined;
+    return {
+        message,
+        ...(code === undefined ? {} : { code }),
+        ...(credentialIds === undefined ? {} : { credentialIds: [...credentialIds] }),
+    };
+}

package/dist/gates/meter.d.ts

@@ -0,0 +1,24 @@
+import type { ModelBudgetRow, ModelUsageRow, ModelUsageTotals, SessionStore } from "../store/types.js";
+import type { Logger } from "../tenant/types.js";
+import type { ModelGateOutcome, ModelGateRequest } from "./model-gate.js";
+export interface Meter {
+    /**
+     * Runs `call` for `request` unless a budget's cap is reached, then records its usage in
+     * `store`. A reached cap answers a `budget_exhausted` failure without calling.
+     */
+    call(store: SessionStore, request: ModelGateRequest, call: () => Promise<ModelGateOutcome>): Promise<ModelGateOutcome>;
+}
+export interface MeterOptions {
+    readonly logger: Logger;
+    readonly now?: () => Date;
+}
+export declare function createMeter(options: MeterOptions): Meter;
+/** The ledger row of an outcome that carries usage; undefined for a failure. */
+export declare function usageRow(request: ModelGateRequest, outcome: ModelGateOutcome, at: Date): Omit<ModelUsageRow, "duplicate"> | undefined;
+/**
+ * Why the budget refuses another call, or undefined. Calls in flight count at the scope's
+ * average cost per recorded call.
+ */
+export declare function capReached(budget: Pick<ModelBudgetRow, "scope" | "scopeId" | "period" | "limitUsd" | "limitTokens">, spent: ModelUsageTotals, inflight: number): string | undefined;
+/** When the UTC `period` containing `now` started, as an ISO time. */
+export declare function periodStart(period: "day" | "month", now: Date): string;