@intentface/latch-core 0.9.1

package/dist/harness/web-fetch.js

@@ -0,0 +1,247 @@
+import TurndownService from "turndown";
+import { isBlockedHost, isBlockedResolved } from "@intentface/latch-net";
+import { pinnedFetch } from "@intentface/latch-net/pinned";
+/**
+ * Robust URL fetching for the `web_fetch` tool — mirrors eve's implementation
+ * so pages come back as clean markdown/text instead of raw HTML, with a
+ * browser User-Agent, content negotiation, a timeout, a Cloudflare-challenge
+ * retry, a size cap, and head-truncation. Runs in the app process (not the
+ * sandbox); private/loopback hosts are blocked (SSRF).
+ */
+const MAX_RESPONSE_SIZE = 5 * 1024 * 1024; // 5 MB
+const DEFAULT_TIMEOUT_MS = 30_000;
+const MAX_TIMEOUT_MS = 120_000;
+const MAX_OUTPUT_LINES = 2000;
+const MAX_OUTPUT_BYTES = 50 * 1024;
+const MAX_REDIRECTS = 4;
+// Browser-like UA so servers return full content, not bot-degraded pages.
+const BROWSER_USER_AGENT = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36";
+const HONEST_UA = "intentface-latch-agent";
+/**
+ * Anthropic caps images at 5 MB of source data; staying under it here beats a
+ * provider error after the fetch already succeeded.
+ */
+const MAX_MEDIA_SIZE = 4.5 * 1024 * 1024;
+/**
+ * What media the body is, if it's a type worth showing the model. The
+ * Content-Type header decides when it's one of ours; magic bytes rescue the
+ * common case of a server that lies (application/octet-stream, text/plain) —
+ * sniffing is deliberately limited to unambiguous signatures.
+ */
+export function detectMedia(contentType, bytes) {
+    const declared = contentType.split(";")[0].trim().toLowerCase();
+    if (declared === "image/png" ||
+        declared === "image/jpeg" ||
+        declared === "image/gif" ||
+        declared === "image/webp" ||
+        declared === "application/pdf") {
+        return declared;
+    }
+    if (declared === "image/jpg")
+        return "image/jpeg";
+    // Magic bytes, only when the declared type doesn't commit to something else
+    // textual (an HTML page that happens to start with %PDF is not a PDF).
+    if (declared.startsWith("text/") || declared.includes("html"))
+        return null;
+    const ascii = (start, s) => bytes.length >= start + s.length &&
+        s.split("").every((ch, i) => bytes[start + i] === ch.charCodeAt(0));
+    if (ascii(0, "%PDF-"))
+        return "application/pdf";
+    if (bytes.length >= 8 && bytes[0] === 0x89 && ascii(1, "PNG"))
+        return "image/png";
+    if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff)
+        return "image/jpeg";
+    if (ascii(0, "GIF87a") || ascii(0, "GIF89a"))
+        return "image/gif";
+    if (ascii(0, "RIFF") && ascii(8, "WEBP"))
+        return "image/webp";
+    return null;
+}
+/**
+ * Full SSRF gate for one hop: protocol, the string-level blocklist, and the DNS
+ * backstop (a public NAME that resolves to a private address — the string check
+ * alone cannot see that). Applied to the initial URL AND every redirect target.
+ */
+async function blockedReason(t) {
+    if (t.protocol !== "http:" && t.protocol !== "https:") {
+        return "Only http(s) URLs are allowed.";
+    }
+    if (isBlockedHost(t.hostname) || (await isBlockedResolved(t.hostname))) {
+        return "Host is not allowed.";
+    }
+    return null;
+}
+function buildHeaders(format) {
+    const accept = format === "markdown"
+        ? "text/markdown;q=1.0, text/x-markdown;q=0.9, text/plain;q=0.8, text/html;q=0.7, */*;q=0.1"
+        : format === "text"
+            ? "text/plain;q=1.0, text/markdown;q=0.9, text/html;q=0.8, */*;q=0.1"
+            : "text/html;q=1.0, application/xhtml+xml;q=0.9, text/plain;q=0.8, */*;q=0.1";
+    return { Accept: accept, "Accept-Language": "en-US,en;q=0.9", "User-Agent": BROWSER_USER_AGENT };
+}
+/** HTML → Markdown (Turndown), dropping script/style/meta/link noise. */
+export function convertHtmlToMarkdown(html) {
+    const service = new TurndownService({
+        bulletListMarker: "-",
+        codeBlockStyle: "fenced",
+        emDelimiter: "*",
+        headingStyle: "atx",
+        hr: "---",
+    });
+    service.remove(["script", "style", "meta", "link"]);
+    return service.turndown(html);
+}
+const ENTITY_MAP = {
+    "&": "&",
+    ">": ">",
+    "&lt;": "<",
+    "&nbsp;": " ",
+    "&quot;": '"',
+    "&#39;": "'",
+    "&#x27;": "'",
+    "&#x2f;": "/",
+};
+/** Strip HTML to readable text (no Turndown) — for `format: "text"`. */
+export function extractTextFromHtml(html) {
+    let text = html.replace(/<(script|style|noscript)\b[^>]*>[\s\S]*?<\/\1>/gi, "");
+    text = text.replace(/<\/(p|div|br|h[1-6]|li|tr|blockquote|pre|section|article|header|footer|nav|aside|main|figure|figcaption|details|summary)>/gi, "\n");
+    text = text.replace(/<br\s*\/?>/gi, "\n");
+    text = text.replace(/<[^>]+>/g, "");
+    text = text.replace(/&[a-z#0-9]+;/gi, (m) => ENTITY_MAP[m.toLowerCase()] ?? m);
+    return text
+        .split("\n")
+        .map((line) => line.replace(/[ \t]+/g, " ").trim())
+        .join("\n")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+}
+/** Keep the HEAD of long content (the start = the article, not the footer). */
+function headTruncate(text) {
+    let out = text;
+    let truncated = false;
+    const lines = out.split("\n");
+    if (lines.length > MAX_OUTPUT_LINES) {
+        out = lines.slice(0, MAX_OUTPUT_LINES).join("\n");
+        truncated = true;
+    }
+    if (Buffer.byteLength(out) > MAX_OUTPUT_BYTES) {
+        out = out.slice(0, MAX_OUTPUT_BYTES);
+        truncated = true;
+    }
+    return { text: out, truncated };
+}
+export async function webFetch(args) {
+    const format = args.format ?? "markdown";
+    let u;
+    try {
+        u = new URL(args.url);
+    }
+    catch {
+        return { ok: false, error: "Invalid URL." };
+    }
+    // Non-positive / NaN timeouts fall back to the default rather than reaching
+    // AbortSignal.timeout(), which throws a RangeError outside our error result.
+    const requested = args.timeout != null && Number.isFinite(args.timeout) && args.timeout > 0 ? args.timeout * 1000 : DEFAULT_TIMEOUT_MS;
+    const timeoutMs = Math.min(requested, MAX_TIMEOUT_MS);
+    const signal = AbortSignal.timeout(timeoutMs);
+    const headers = buildHeaders(format);
+    /**
+     * Follow redirects MANUALLY so each hop is re-gated: with `redirect: "follow"`
+     * a public URL that 302s to an internal address (e.g. cloud metadata) would be
+     * fetched transparently, and only the first host would ever be checked.
+     */
+    const fetchGuarded = async (start, reqHeaders) => {
+        let current = start;
+        for (let hop = 0;; hop++) {
+            const bad = await blockedReason(current);
+            if (bad)
+                return { error: bad };
+            // Pinned fetch: the SSRF vetting also runs inside the connection's own
+            // DNS lookup, so `blockedReason` above is the well-messaged pre-check,
+            // not the last line of defense against rebinding.
+            const res = await pinnedFetch(current, { headers: reqHeaders, signal, redirect: "manual" });
+            const location = res.status >= 300 && res.status < 400 ? res.headers.get("location") : null;
+            if (!location)
+                return res;
+            if (hop >= MAX_REDIRECTS)
+                return { error: "Too many redirects." };
+            try {
+                current = new URL(location, current);
+            }
+            catch {
+                return { error: "Invalid redirect location." };
+            }
+        }
+    };
+    let response;
+    try {
+        const initial = await fetchGuarded(u, headers);
+        if ("error" in initial)
+            return { ok: false, error: initial.error };
+        // Cloudflare may block browser UAs from non-browser TLS; retry honestly.
+        if (initial.status === 403 && initial.headers.get("cf-mitigated") === "challenge") {
+            const retry = await fetchGuarded(u, { ...headers, "User-Agent": HONEST_UA });
+            if ("error" in retry)
+                return { ok: false, error: retry.error };
+            response = retry;
+        }
+        else {
+            response = initial;
+        }
+    }
+    catch (e) {
+        const msg = e instanceof Error
+            ? e.name === "TimeoutError" || e.name === "AbortError"
+                ? `Request timed out after ${timeoutMs / 1000}s`
+                : // undici wraps connect-time failures (incl. the pinned fetch's
+                    // SSRF block) as `TypeError: fetch failed` with the reason in
+                    // `cause` — surface it or the block looks like a network blip.
+                    e.cause instanceof Error && e.cause.message
+                        ? `${e.message}: ${e.cause.message}`
+                        : e.message
+            : "Fetch failed";
+        return { ok: false, error: msg };
+    }
+    if (!response.ok)
+        return { ok: false, error: `Request failed with status ${response.status}` };
+    const declared = response.headers.get("content-length");
+    if (declared && Number.parseInt(declared, 10) > MAX_RESPONSE_SIZE) {
+        return { ok: false, error: "Response too large (exceeds 5 MB)." };
+    }
+    const buffer = await response.arrayBuffer();
+    if (buffer.byteLength > MAX_RESPONSE_SIZE) {
+        return { ok: false, error: "Response too large (exceeds 5 MB)." };
+    }
+    const contentType = response.headers.get("content-type") ?? "";
+    // Images and PDFs come back as bytes so the model can SEE them (the tool's
+    // toModelOutput turns them into provider image/document blocks). Text-decoding
+    // them — the previous behavior — produced mojibake the model couldn't use.
+    const mediaType = detectMedia(contentType, new Uint8Array(buffer));
+    if (mediaType) {
+        if (buffer.byteLength > MAX_MEDIA_SIZE) {
+            return {
+                ok: false,
+                error: `Media too large for model input (${(buffer.byteLength / (1024 * 1024)).toFixed(1)} MB, max ${MAX_MEDIA_SIZE / (1024 * 1024)} MB).`,
+            };
+        }
+        return {
+            ok: true,
+            kind: "media",
+            status: response.status,
+            contentType,
+            mediaType,
+            data: Buffer.from(buffer).toString("base64"),
+            bytes: buffer.byteLength,
+        };
+    }
+    const isHtml = contentType.includes("text/html");
+    const body = new TextDecoder().decode(buffer);
+    const raw = format === "markdown" && isHtml
+        ? convertHtmlToMarkdown(body)
+        : format === "text" && isHtml
+            ? extractTextFromHtml(body)
+            : body;
+    const { text: content, truncated } = headTruncate(raw);
+    return { ok: true, kind: "text", status: response.status, contentType, content, truncated };
+}
+//# sourceMappingURL=web-fetch.js.map

package/dist/harness/web-fetch.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @intentface/latch-core
+ *
+ * Foundational types & seams. The Runtime (composition root + operations facade)
+ * and the executor land in later pieces; this is the vocabulary everything else
+ * is built on.
+ */
+export * from "./principal.js";
+export * from "./message.js";
+export * from "./storage.js";
+export * from "./context.js";
+export * from "./current-date.js";
+export * from "./agent.js";
+export * from "./memory.js";
+export * from "./runtime.js";
+export * from "./connections.js";
+export * from "./scheduler.js";
+export * from "./vault.js";
+export * from "./projections.js";
+export * from "./compaction.js";
+export * from "./pricing.js";
+export * from "./prompt-caching.js";
+export * from "./telemetry.js";
+export * from "./limits.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,25 @@
+/**
+ * @intentface/latch-core
+ *
+ * Foundational types & seams. The Runtime (composition root + operations facade)
+ * and the executor land in later pieces; this is the vocabulary everything else
+ * is built on.
+ */
+export * from "./principal.js";
+export * from "./message.js";
+export * from "./storage.js";
+export * from "./context.js";
+export * from "./current-date.js";
+export * from "./agent.js";
+export * from "./memory.js";
+export * from "./runtime.js";
+export * from "./connections.js";
+export * from "./scheduler.js";
+export * from "./vault.js";
+export * from "./projections.js";
+export * from "./compaction.js";
+export * from "./pricing.js";
+export * from "./prompt-caching.js";
+export * from "./telemetry.js";
+export * from "./limits.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC"}

package/dist/limits.d.ts

@@ -0,0 +1,152 @@
+import type { TurnTrigger } from "./telemetry.js";
+/**
+ * Limits — per org / user / agent budgets on turns, tokens and cost.
+ *
+ * The split is the same as every other seam: the HOST decides which counters a
+ * turn counts against and what the caps are (`limitsFor` — derived from the
+ * principal, the agent and how the turn started), and where the counters live
+ * (`LimitStore`, a table the drizzle package implements). The RUNTIME counts
+ * and enforces:
+ *
+ *   • admission — before a turn opens, the turn is RESERVED: one atomic
+ *     increment of every policy's turn counter that returns the new count. The
+ *     first policy whose count is now over its cap refuses the turn with
+ *     {@link LimitExceededError} (the HTTP handler maps it to 429 +
+ *     Retry-After) and the reservation is released. Increment-then-check means
+ *     N concurrent requests against a one-turn cap get counts 1..N and exactly
+ *     one is admitted — there is no read-then-write window to race through.
+ *     Token and cost caps are checked against usage already settled; an
+ *     in-flight turn's spend lands at settlement, so those caps can be
+ *     overshot by at most the concurrent in-flight turns (bounded further by
+ *     the mid-turn stop).
+ *   • mid-turn — the tool loop stops once this turn's tokens reach the
+ *     tightest remaining token budget (the model's last text is kept; no
+ *     further steps run). Without this a single long agentic turn could blow
+ *     through a whole day's budget after being admitted at 99%.
+ *   • settlement — tokens and cost are added to every policy's counter when
+ *     the turn finishes (resumes and subagent turns included).
+ *
+ * Windows are fixed, aligned to the epoch: `windowStart = floor(now / windowMs)
+ * * windowMs`. Fixed windows are what people expect from "per day" / "per
+ * hour", cost one row per (key, window) and need no sliding-log storage. A
+ * refusal says when the window turns over.
+ */
+/** One counter a turn counts against, plus its caps in the window. */
+export interface LimitPolicy {
+    /** Stable counter key — e.g. `org:o1`, `user:o1:u1`, `agent:o1:support`. Name the scope in it. */
+    key: string;
+    /** Fixed window length in ms (see `MINUTE_MS` … `DAY_MS`). */
+    windowMs: number;
+    /** Caps within one window. An omitted cap is unlimited. */
+    max: {
+        /** Turns admitted (a resume doesn't count; a subagent turn does). */
+        turns?: number;
+        /** Input + output tokens. */
+        tokens?: number;
+        /** Cost in the pricing seam's currency (0 when no pricing is configured). */
+        cost?: number;
+    };
+    /** How a refusal names this budget to the user, e.g. "your organization's daily token budget". */
+    label?: string;
+}
+/** What has been counted against one policy in the current window. */
+export interface LimitUsage {
+    turns: number;
+    tokens: number;
+    cost: number;
+}
+export interface LimitWindowRef {
+    key: string;
+    windowStart: number;
+    windowMs: number;
+}
+/**
+ * Counter storage — one row per (key, window). Both methods must be atomic per
+ * row (the drizzle implementation upserts with `SET n = n + excluded.n`).
+ */
+export interface LimitStore {
+    /** Current usage for each window ref; absent rows read as zero. */
+    read(refs: LimitWindowRef[]): Promise<Record<string, LimitUsage>>;
+    /**
+     * Add usage to each window (creating the row) and return each window's usage
+     * AFTER the add, keyed by `usageKey`. Atomic per row and the returned value
+     * must be the row's post-increment state (`INSERT … ON CONFLICT DO UPDATE …
+     * RETURNING`): admission reserves a turn with it. Partial usage: omitted
+     * fields add 0; negative values release a reservation.
+     */
+    add(entries: (LimitWindowRef & {
+        usage: Partial<LimitUsage>;
+    })[]): Promise<Record<string, LimitUsage>>;
+    /** Drop windows that ended before `before` (retention; called by `runtime.cron()`). */
+    prune?(before: number): Promise<void>;
+}
+/** The limits seam as `createRuntime({ limits })` takes it. */
+export interface LatchLimits<P> {
+    store: LimitStore;
+    /**
+     * The counters this turn counts against. Empty → unlimited. Called per turn
+     * (admission), so it may read a policy table; keep it cheap.
+     */
+    limitsFor(input: {
+        principal: P;
+        /** The agent ref as resolved for the turn. */
+        agent: string;
+        trigger: TurnTrigger;
+    }): LimitPolicy[] | Promise<LimitPolicy[]>;
+    /** A turn was refused. For metrics/alerts; must not throw. */
+    onRefused?(input: {
+        principal: P;
+        agent: string;
+        trigger: TurnTrigger;
+        policy: LimitPolicy;
+        usage: LimitUsage;
+        retryAfterMs: number;
+    }): void | Promise<void>;
+}
+export declare const MINUTE_MS = 60000;
+export declare const HOUR_MS: number;
+export declare const DAY_MS: number;
+/** The start of the fixed window containing `now`. */
+export declare const windowStartOf: (now: number, windowMs: number) => number;
+/** `LimitWindowRef` for a policy at `now`. */
+export declare const windowRef: (policy: LimitPolicy, now: number) => LimitWindowRef;
+/**
+ * Map key for one window in `LimitStore.read`'s result. The window LENGTH is
+ * part of it: the same counter key may carry a per-hour and a per-day policy,
+ * and their aligned windows share a start on the hour.
+ */
+export declare const usageKey: (ref: LimitWindowRef) => string;
+/**
+ * Thrown (and mapped to HTTP 429) when a turn is refused at admission.
+ * `code` is stable so hosts can match it structurally.
+ */
+export declare class LimitExceededError extends Error {
+    readonly policy: LimitPolicy;
+    readonly usage: LimitUsage;
+    /** Milliseconds until the window turns over and the budget resets. */
+    readonly retryAfterMs: number;
+    readonly code: "limit_exceeded";
+    constructor(policy: LimitPolicy, usage: LimitUsage, 
+    /** Milliseconds until the window turns over and the budget resets. */
+    retryAfterMs: number);
+}
+export declare function isLimitExceededError(e: unknown): e is LimitExceededError;
+/**
+ * Admission decision over usage that ALREADY includes this turn's reservation
+ * (`nextTurn: false`), or over settled usage when the turn is to be counted on
+ * top (`nextTurn: true`). Returns the first exhausted policy, or null when every
+ * budget has room.
+ */
+export declare function exceededPolicy(policies: LimitPolicy[], usage: Record<string, LimitUsage>, now: number, opts: {
+    nextTurn: boolean;
+}): {
+    policy: LimitPolicy;
+    usage: LimitUsage;
+    retryAfterMs: number;
+} | null;
+/**
+ * The tightest remaining token budget across policies (for the mid-turn stop),
+ * or undefined when no policy caps tokens.
+ */
+export declare function remainingTokens(policies: LimitPolicy[], usage: Record<string, LimitUsage>, now: number): number | undefined;
+//# sourceMappingURL=limits.d.ts.map

package/dist/limits.d.ts.map

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

package/dist/limits.js

@@ -0,0 +1,97 @@
+export const MINUTE_MS = 60_000;
+export const HOUR_MS = 60 * MINUTE_MS;
+export const DAY_MS = 24 * HOUR_MS;
+/** The start of the fixed window containing `now`. */
+export const windowStartOf = (now, windowMs) => Math.floor(now / windowMs) * windowMs;
+/** `LimitWindowRef` for a policy at `now`. */
+export const windowRef = (policy, now) => ({
+    key: policy.key,
+    windowStart: windowStartOf(now, policy.windowMs),
+    windowMs: policy.windowMs,
+});
+/**
+ * Map key for one window in `LimitStore.read`'s result. The window LENGTH is
+ * part of it: the same counter key may carry a per-hour and a per-day policy,
+ * and their aligned windows share a start on the hour.
+ */
+export const usageKey = (ref) => `${ref.key}@${ref.windowStart}/${ref.windowMs}`;
+const ZERO = { turns: 0, tokens: 0, cost: 0 };
+/**
+ * Thrown (and mapped to HTTP 429) when a turn is refused at admission.
+ * `code` is stable so hosts can match it structurally.
+ */
+export class LimitExceededError extends Error {
+    policy;
+    usage;
+    retryAfterMs;
+    code = "limit_exceeded";
+    constructor(policy, usage, 
+    /** Milliseconds until the window turns over and the budget resets. */
+    retryAfterMs) {
+        const what = policy.label ?? `the ${describeWindow(policy.windowMs)} limit for ${policy.key}`;
+        super(`Limit reached: ${what}. Try again in ${describeDuration(retryAfterMs)}.`);
+        this.policy = policy;
+        this.usage = usage;
+        this.retryAfterMs = retryAfterMs;
+        this.name = "LimitExceededError";
+    }
+}
+export function isLimitExceededError(e) {
+    return e?.code === "limit_exceeded";
+}
+/**
+ * Admission decision over usage that ALREADY includes this turn's reservation
+ * (`nextTurn: false`), or over settled usage when the turn is to be counted on
+ * top (`nextTurn: true`). Returns the first exhausted policy, or null when every
+ * budget has room.
+ */
+export function exceededPolicy(policies, usage, now, opts) {
+    for (const policy of policies) {
+        const ref = windowRef(policy, now);
+        const u = usage[usageKey(ref)] ?? ZERO;
+        const turns = u.turns + (opts.nextTurn ? 1 : 0);
+        const over = (policy.max.turns !== undefined && turns > policy.max.turns) ||
+            (policy.max.tokens !== undefined && u.tokens >= policy.max.tokens) ||
+            (policy.max.cost !== undefined && u.cost >= policy.max.cost);
+        if (over)
+            return { policy, usage: u, retryAfterMs: ref.windowStart + ref.windowMs - now };
+    }
+    return null;
+}
+/**
+ * The tightest remaining token budget across policies (for the mid-turn stop),
+ * or undefined when no policy caps tokens.
+ */
+export function remainingTokens(policies, usage, now) {
+    let min;
+    for (const policy of policies) {
+        if (policy.max.tokens === undefined)
+            continue;
+        const u = usage[usageKey(windowRef(policy, now))] ?? ZERO;
+        const left = Math.max(0, policy.max.tokens - u.tokens);
+        min = min === undefined ? left : Math.min(min, left);
+    }
+    return min;
+}
+function describeWindow(ms) {
+    if (ms % DAY_MS === 0)
+        return ms === DAY_MS ? "daily" : `${ms / DAY_MS}-day`;
+    if (ms % HOUR_MS === 0)
+        return ms === HOUR_MS ? "hourly" : `${ms / HOUR_MS}-hour`;
+    if (ms % MINUTE_MS === 0)
+        return ms === MINUTE_MS ? "per-minute" : `${ms / MINUTE_MS}-minute`;
+    return `${Math.round(ms / 1000)}s`;
+}
+function describeDuration(ms) {
+    const s = Math.ceil(ms / 1000);
+    if (s < 90)
+        return `${s}s`;
+    const m = Math.ceil(s / 60);
+    if (m < 90)
+        return `${m} min`;
+    const h = Math.ceil(m / 60);
+    if (h < 36)
+        return `${h} h`;
+    return `${Math.ceil(h / 24)} d`;
+}
+//# sourceMappingURL=limits.js.map

package/dist/limits.js.map

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