@providerkit/core 0.1.0

package/dist/watchdog.js

@@ -0,0 +1,85 @@
+// The stream-idle watchdog.
+//
+// A provider that stops sending bytes is indistinguishable from a long prefill
+// — except that it never ends, and every SDK's default is to wait forever. A
+// queued route or a wedged prefill upstream hangs the caller indefinitely, and
+// the symptom is the worst kind: nothing. No error, no log, no timeout.
+//
+// So the seam gives itself a deadline. Any byte of any kind re-arms it
+// (reasoning models emit thinking deltas continuously, so silence really is
+// silence). When it fires, the watchdog aborts ITS OWN controller and the
+// caller's signal is only bridged in — which is what keeps a person's Stop
+// distinguishable from our timeout. One is their cancel and is never retried;
+// the other is ours, is transient, and fires while nothing has streamed yet,
+// so the retry is always safe.
+import { ProviderError } from "./errors.js";
+/** No byte at all for this long and the stream is considered wedged. */
+export const STREAM_IDLE_MS = 60_000;
+export function streamWatch(opts = {}) {
+    const provider = opts.provider ?? "provider";
+    const idleMs = opts.idleMs ?? STREAM_IDLE_MS;
+    const callerSignal = opts.signal;
+    const started = Date.now();
+    const timeout = new AbortController();
+    let firstChunk = null;
+    let idle = false;
+    let disposed = false;
+    // The bridge is structural rather than an event listener: AbortSignal.any
+    // aborts synchronously when an input is ALREADY aborted, which is the race
+    // no listener can catch (the event fired before we subscribed).
+    const signal = callerSignal ? AbortSignal.any([callerSignal, timeout.signal]) : timeout.signal;
+    const idleError = (cause) => new ProviderError(provider, "timeout", `stream went ${idleMs / 1000}s without a byte`, {
+        cause,
+    });
+    function arm() {
+        const timer = setTimeout(() => {
+            idle = true;
+            timeout.abort(idleError());
+        }, idleMs);
+        // An orphaned watch — its consumer gone, dispose never called — must not
+        // hold a Node event loop open for a full deadline.
+        timer.unref?.();
+        return timer;
+    }
+    let timer = arm();
+    return {
+        signal,
+        sawByte() {
+            firstChunk ??= Date.now() - started;
+            clearTimeout(timer);
+            if (!disposed && !signal.aborted)
+                timer = arm();
+        },
+        firstChunkMs: () => firstChunk,
+        classify(err) {
+            // Our deadline, not theirs — and not the caller's Stop.
+            if (idle && !(callerSignal?.aborted ?? false))
+                return idleError(err);
+            return err;
+        },
+        dispose() {
+            disposed = true;
+            clearTimeout(timer);
+        },
+    };
+}
+/**
+ * Wrap a stream so every chunk re-arms `watch`, and a failure is re-classified
+ * through it. Disposes on any exit — completion, throw, or the consumer
+ * breaking out of the loop.
+ */
+export async function* watchChunks(watch, chunks) {
+    try {
+        for await (const chunk of chunks) {
+            watch.sawByte();
+            yield chunk;
+        }
+    }
+    catch (err) {
+        throw watch.classify(err);
+    }
+    finally {
+        watch.dispose();
+    }
+}
+//# sourceMappingURL=watchdog.js.map

package/dist/watchdog.js.map

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

package/dist/zod.d.ts

@@ -0,0 +1,32 @@
+import { z } from "zod";
+import { type Tool, type ToolContext } from "./tools.ts";
+import type { JsonObjectSchema } from "./types.ts";
+/** A zod schema as the JSON Schema every provider's tool contract wants. */
+export declare function toJsonObjectSchema(schema: z.ZodType, label?: string): JsonObjectSchema;
+export interface ZodToolSpec<I, O> {
+    name: string;
+    description: string;
+    input: z.ZodType<I>;
+    run: (input: I, ctx: ToolContext) => Promise<O>;
+    summarize?: (output: O) => string;
+    timeoutMs?: number;
+    isReadOnly?: boolean;
+    needsApproval?: boolean;
+    isConcurrencySafe?: boolean;
+    isTerminal?: boolean;
+    /**
+     * Clamp overflow to the bounds the schema already advertised instead of
+     * rejecting the call. Worth it for a TERMINAL tool, which gets no second
+     * chance: a forced-submit salvage turn runs exactly once, and discarding an
+     * otherwise-valid answer over a few extra characters loses the whole run.
+     * Off by default — an ordinary tool can simply be called again.
+     */
+    clampOverflow?: boolean;
+}
+/**
+ * A tool whose arguments are validated by zod, with the failure reported to
+ * the MODEL in words it can act on — `topic: expected string, received number`
+ * beats a stack trace it cannot read.
+ */
+export declare function zodTool<I, O>(spec: ZodToolSpec<I, O>): Tool<I, O>;
+//# sourceMappingURL=zod.d.ts.map

package/dist/zod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod.d.ts","sourceRoot":"","sources":["../src/zod.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAc,KAAK,IAAI,EAAE,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAErE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD,4EAA4E;AAC5E,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,KAAK,SAAW,GAAG,gBAAgB,CASxF;AAED,MAAM,WAAW,WAAW,CAAC,CAAC,EAAE,CAAC;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IACpB,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IAChD,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,MAAM,CAAC;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAyBjE"}

package/dist/zod.js

@@ -0,0 +1,49 @@
+// The optional zod ergonomics — `@providerkit/core/zod`.
+//
+// Kept behind its own entry point so the core stays dependency-free for
+// consumers that have no zod (a browser extension counting every byte, for
+// one). Import this and tools become typed end to end.
+import { z } from "zod";
+import { defineTool } from "./tools.js";
+import { clampToSchema } from "./schema.js";
+/** A zod schema as the JSON Schema every provider's tool contract wants. */
+export function toJsonObjectSchema(schema, label = "schema") {
+    const json = z.toJSONSchema(schema, { io: "input" });
+    if (json.type !== "object") {
+        // Every provider requires an object at the top level of a tool's
+        // parameters; a bare string or array is rejected at the wire, far from
+        // here, with a message that names none of this.
+        throw new Error(`providerkit: ${label} must be an object schema, got ${String(json.type)}`);
+    }
+    return json;
+}
+/**
+ * A tool whose arguments are validated by zod, with the failure reported to
+ * the MODEL in words it can act on — `topic: expected string, received number`
+ * beats a stack trace it cannot read.
+ */
+export function zodTool(spec) {
+    const inputSchema = toJsonObjectSchema(spec.input, `Tool "${spec.name}" input`);
+    return defineTool({
+        name: spec.name,
+        description: spec.description,
+        inputSchema,
+        ...(spec.summarize ? { summarize: spec.summarize } : {}),
+        ...(spec.timeoutMs !== undefined ? { timeoutMs: spec.timeoutMs } : {}),
+        ...(spec.isReadOnly !== undefined ? { isReadOnly: spec.isReadOnly } : {}),
+        ...(spec.needsApproval !== undefined ? { needsApproval: spec.needsApproval } : {}),
+        ...(spec.isConcurrencySafe !== undefined ? { isConcurrencySafe: spec.isConcurrencySafe } : {}),
+        ...(spec.isTerminal !== undefined ? { isTerminal: spec.isTerminal } : {}),
+        validate: (raw) => {
+            const candidate = spec.clampOverflow ? clampToSchema(raw, inputSchema) : raw;
+            const parsed = spec.input.safeParse(candidate);
+            if (parsed.success)
+                return parsed.data;
+            throw new Error(parsed.error.issues
+                .map((issue) => `${issue.path.join(".") || "input"}: ${issue.message}`)
+                .join("; "));
+        },
+        run: spec.run,
+    });
+}
+//# sourceMappingURL=zod.js.map

package/dist/zod.js.map

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

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@providerkit/core",
+  "version": "0.1.0",
+  "description": "The layer under your agent loop: one seam for every LLM provider, plus the failure handling you only learn in production.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Gustavo Salom\u00e9",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./zod": {
+      "types": "./dist/zod.d.ts",
+      "default": "./dist/zod.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "llm",
+    "openai",
+    "anthropic",
+    "gemini",
+    "agent",
+    "streaming",
+    "sse",
+    "retry",
+    "tool-calling"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src test",
+    "format": "prettier --write .",
+    "sync:docs": "cp ../README.md ../LICENSE .",
+    "prepublishOnly": "bun run lint && bun run typecheck && bun run test && bun run build && bun run sync:docs",
+    "release": "bun publish --access public",
+    "release:patch": "bun pm version patch && bun publish --access public",
+    "release:minor": "bun pm version minor && bun publish --access public",
+    "release:major": "bun pm version major && bun publish --access public",
+    "release:alpha": "bun publish --access public --tag alpha"
+  },
+  "peerDependencies": {
+    "zod": "^4"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.2",
+    "zod": "^4.3.6"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/providerkit/providerkit.git"
+  },
+  "homepage": "https://providerkit.dev",
+  "bugs": {
+    "url": "https://github.com/providerkit/providerkit/issues"
+  }
+}

package/src/context.ts

@@ -0,0 +1,150 @@
+// Deciding when a conversation no longer fits, and where to cut it.
+//
+// Everything here is pure and testable. The model call that writes the summary
+// and the row that stores it belong to the caller — what is decidable without
+// I/O is decided here.
+import type { ChatMessage } from "./types.ts";
+
+/**
+ * What the answer needs after the prompt: an output budget, plus the tools'
+ * own schemas, plus the slack no provider documents.
+ *
+ * Absolute rather than a percentage on purpose — a 1M window does not need a
+ * 100k cushion, and a 128k window needs more than 12k.
+ */
+export const CONTEXT_RESERVE_TOKENS = 32_000;
+
+/**
+ * Four characters per token — the rule of thumb every provider's own
+ * calculator agrees with to within a fifth, which is all the precision this
+ * needs. It decides WHEN to fold: folding one turn early costs a cheap model
+ * call, folding one turn late costs the whole turn.
+ */
+export function estimateTokens(text: string): number {
+  return Math.ceil(text.length / 4);
+}
+
+function textOf(message: ChatMessage): string {
+  if (message.role === "user" && typeof message.content !== "string") {
+    // Only the words are countable; an image's cost is the provider's own
+    // arithmetic and no character count approximates it.
+    return message.content.map((part) => (part.type === "text" ? part.text : "")).join("");
+  }
+  return typeof message.content === "string" ? message.content : "";
+}
+
+/** What one message costs to re-send: its words, its reasoning, and the
+ *  arguments of any calls it made. */
+export function messageTokens(message: ChatMessage): number {
+  const extra =
+    message.role === "assistant"
+      ? (message.reasoning ?? "") +
+        (message.toolCalls?.map((call) => call.name + call.arguments).join("") ?? "")
+      : "";
+  return estimateTokens(textOf(message) + extra);
+}
+
+export function conversationTokens(messages: readonly ChatMessage[]): number {
+  return messages.reduce((total, message) => total + messageTokens(message), 0);
+}
+
+/**
+ * The provider's own input count says the wall is close — fold before the next
+ * step rather than after the 400.
+ *
+ * Takes the REPORTED count, not an estimate, because it is the only figure
+ * that is not a guess. Estimate only when there is no reported count yet.
+ */
+export function needsCompaction(inputTokens: number, contextWindow: number): boolean {
+  return inputTokens >= contextWindow - CONTEXT_RESERVE_TOKENS;
+}
+
+/**
+ * How much of the window the history BEHIND the current turn may spend: a
+ * tenth, floored so a small window still gets a usable memory. The tail stays
+ * verbatim and the summary is short, so the rest is what folding buys back.
+ */
+export function historyBudgetTokens(contextWindow: number): number {
+  return Math.max(6_000, Math.floor(contextWindow * 0.1));
+}
+
+/**
+ * Where to cut so the messages AFTER the cut fit `budget`, walking backwards
+ * from the newest.
+ *
+ * Two invariants the cut must respect, and both are correctness rather than
+ * taste:
+ *
+ *  1. Never split a tool call from its result. Every provider rejects a tool
+ *     result whose call is missing, so a cut landing between them produces a
+ *     400 on the very next turn — the failure compaction was called to avoid.
+ *  2. Never cut into the system prompt. It is not history.
+ *
+ * Returns the index the kept tail starts at, or 0 when everything already fits.
+ */
+export function pickCut(messages: readonly ChatMessage[], budget: number): number {
+  const firstNonSystem = messages.findIndex((message) => message.role !== "system");
+  // Nothing but a system prompt: there is no history to fold.
+  if (firstNonSystem === -1) return messages.length;
+
+  // The newest message is always kept, budget or not. A conversation whose
+  // latest turn alone overruns the budget is not fixable by cutting history,
+  // and answering a summary instead of the question the person just asked is
+  // never the right failure.
+  const latest = messages.length - 1;
+  let cut = latest;
+  let total = messageTokens(messages[latest]!);
+
+  for (let i = latest - 1; i >= firstNonSystem; i--) {
+    total += messageTokens(messages[i]!);
+    if (total > budget) break;
+    cut = i;
+  }
+
+  // Walk back off any tool result whose assistant turn would be left behind
+  // it. Bounded by the first non-system message, so it can never run off the
+  // front. This can exceed the budget by a message or two, which is the right
+  // trade: an orphaned tool result is a hard 400, not an overrun.
+  while (cut > firstNonSystem && messages[cut]!.role === "tool") cut--;
+
+  return cut;
+}
+
+/**
+ * Fold `messages` into `[…system, summary, …tail]`.
+ *
+ * The summary arrives as a user turn rather than a system one: a system
+ * message added mid-conversation reads to the model as a new instruction, and
+ * several providers require the system block to be first and singular anyway.
+ */
+export function applyCompaction(
+  messages: readonly ChatMessage[],
+  cut: number,
+  summary: string,
+): ChatMessage[] {
+  const system = messages.filter((message) => message.role === "system");
+  const tail = messages.slice(cut).filter((message) => message.role !== "system");
+  return [
+    ...system,
+    { role: "user", content: `[Earlier conversation, summarized]\n\n${summary}` },
+    ...tail,
+  ];
+}
+
+/**
+ * The context window for a model, when nothing volunteered one.
+ *
+ * The ladder exists because the endpoints disagree about whether to tell you:
+ * OpenRouter, LM Studio and Ollama publish `context_length`; Anthropic and
+ * OpenAI do not. A reported number always wins; this is the floor under it.
+ *
+ * A conservative default is the right failure: too small folds one turn early
+ * and costs a cheap call, too large hits a hard 400 mid-run.
+ */
+export function guessContextWindow(model: string): number {
+  const id = model.toLowerCase();
+  if (/gemini|gpt-4\.1|grok-4|llama-4/.test(id)) return 1_000_000;
+  if (/claude|gpt-5|o[34]|deepseek|kimi|glm|qwen/.test(id)) return 200_000;
+  if (/gpt-4o|mistral|command-r/.test(id)) return 128_000;
+  return 128_000;
+}