@merkie/agentic 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Merkie
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,93 @@
+# @merkie/agentic
+
+> Batteries-included helpers for building LLM-powered apps with the [Vercel AI SDK](https://sdk.vercel.ai) and [OpenRouter](https://openrouter.ai).
+
+Most AI SDK setups are bring-your-own-everything. `@merkie/agentic` is the start of a
+framework that ships the boring-but-essential plumbing — observability,
+persistence, and resilience — so you can focus on your agent code instead of
+copy-pasting the same cost-tracking and logging boilerplate into every project.
+
+This first release ships two things:
+
+- **`createOpenRouter`** — a drop-in replacement for the provider factory that
+  auto-enables usage/cost accounting and reads your API key from the
+  environment.
+- **`logStream`** — pretty-prints an AI SDK stream in real time (reasoning,
+  messages, tool calls/results) with live token and cost accounting.
+
+> **Status:** early. The logging here will eventually be backed by a real
+> persistence/observability layer; `chalk` and friends are temporary.
+
+## Install
+
+```bash
+npm install @merkie/agentic ai @openrouter/ai-sdk-provider
+```
+
+`ai` and `@openrouter/ai-sdk-provider` are peer dependencies — you bring the
+versions your app already uses.
+
+Works in TypeScript and JavaScript, ESM and CommonJS.
+
+## Usage
+
+```ts
+import { streamText } from "ai";
+import { createOpenRouter, logStream } from "@merkie/agentic";
+
+// Reads OPENROUTER_API_KEY from the environment and turns on usage tracking.
+const openrouter = createOpenRouter();
+
+const result = streamText({
+  model: openrouter("openai/gpt-4o-mini"),
+  prompt: "Explain quantum tunneling in one paragraph.",
+});
+
+await logStream(result.fullStream);
+```
+
+CommonJS:
+
+```js
+const { createOpenRouter, logStream } = require("@merkie/agentic");
+```
+
+## API
+
+### `createOpenRouter(settings?)`
+
+Same signature and return type as `createOpenRouter` from
+`@openrouter/ai-sdk-provider`, with two defaults applied:
+
+| Default | Behavior | Override |
+| --- | --- | --- |
+| `apiKey` | Falls back to `process.env.OPENROUTER_API_KEY` | Pass `apiKey` |
+| `extraBody.usage.include` | `true` (returns cost + token usage) | Pass `extraBody.usage` |
+
+Every option you pass wins over the defaults, so it's 1:1 compatible with the
+upstream factory:
+
+```ts
+const openrouter = createOpenRouter({
+  apiKey: myKey,
+  extraBody: {
+    transforms: ["middle-out"],
+    usage: { include: false }, // opt back out if you want
+  },
+});
+```
+
+### `logStream(stream)`
+
+Consumes an `AsyncIterable` of AI SDK `TextStreamPart`s (i.e. the `fullStream`
+from `streamText`) and prints each event as it arrives. When the model is served
+through `createOpenRouter`, it also reports per-run cost and context-window
+usage on completion.
+
+```ts
+await logStream(result.fullStream);
+```
+
+## License
+
+MIT © Merkie

package/dist/index.cjs

@@ -0,0 +1,229 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createOpenRouter: () => createOpenRouter,
+  logStream: () => logStream
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/openrouter.ts
+var import_ai_sdk_provider = require("@openrouter/ai-sdk-provider");
+function createOpenRouter(settings = {}) {
+  const { apiKey, extraBody, ...rest } = settings;
+  const userUsage = extraBody && typeof extraBody === "object" && "usage" in extraBody ? extraBody.usage : void 0;
+  return (0, import_ai_sdk_provider.createOpenRouter)({
+    apiKey: apiKey ?? process.env.OPENROUTER_API_KEY,
+    ...rest,
+    extraBody: {
+      ...extraBody,
+      usage: {
+        include: true,
+        ...userUsage && typeof userUsage === "object" ? userUsage : {}
+      }
+    }
+  });
+}
+
+// src/logStream.ts
+var import_chalk = __toESM(require("chalk"), 1);
+var openRouterContextLengthCache = /* @__PURE__ */ new Map();
+function getOpenRouterCost(part) {
+  if (part.type !== "finish-step") return null;
+  const metadataUsage = part.providerMetadata?.openrouter?.usage;
+  const rawUsage = part.usage.raw;
+  const cost = metadataUsage?.cost ?? rawUsage?.cost;
+  const upstreamInferenceCost = metadataUsage?.costDetails?.upstreamInferenceCost ?? rawUsage?.cost_details?.upstream_inference_cost;
+  if (cost === 0 && upstreamInferenceCost != null) {
+    return upstreamInferenceCost;
+  }
+  return cost ?? upstreamInferenceCost ?? null;
+}
+function formatCost(cost) {
+  return `$${cost.toFixed(6)}`;
+}
+function formatTokens(tokens) {
+  return tokens.toLocaleString("en-US");
+}
+function parsePositiveInteger(value) {
+  if (typeof value === "number" && Number.isInteger(value) && value > 0) {
+    return value;
+  }
+  if (typeof value === "string") {
+    const parsed = Number(value);
+    if (Number.isInteger(parsed) && parsed > 0) {
+      return parsed;
+    }
+  }
+  return null;
+}
+function getOpenRouterContextLengthFromResponse(payload) {
+  const data = payload.data;
+  return parsePositiveInteger(data?.context_length) ?? parsePositiveInteger(data?.top_provider?.context_length);
+}
+async function fetchOpenRouterContextLength(modelId) {
+  const pathModelId = modelId.split("/").map(encodeURIComponent).join("/");
+  const response = await fetch(
+    `https://openrouter.ai/api/v1/model/${pathModelId}`
+  );
+  if (!response.ok) {
+    return null;
+  }
+  return getOpenRouterContextLengthFromResponse(await response.json());
+}
+function getOpenRouterContextLength(modelId) {
+  const cached = openRouterContextLengthCache.get(modelId);
+  if (cached) return cached;
+  const promise = fetchOpenRouterContextLength(modelId).catch(() => null);
+  openRouterContextLengthCache.set(modelId, promise);
+  return promise;
+}
+function getModelId(part) {
+  if (part.type === "start-step") {
+    const body = part.request.body;
+    if (body && typeof body === "object" && "model" in body) {
+      const model = body.model;
+      if (typeof model === "string" && model.length > 0) {
+        return model;
+      }
+    }
+  }
+  if (part.type === "finish-step") {
+    return part.response.modelId;
+  }
+  return null;
+}
+function getUsageTokens(usage) {
+  if (!usage) return null;
+  if (usage.inputTokens != null || usage.outputTokens != null) {
+    return (usage.inputTokens ?? 0) + (usage.outputTokens ?? 0);
+  }
+  return usage.totalTokens ?? null;
+}
+function formatContextUsage(usage, contextWindowTokens) {
+  const tokens = getUsageTokens(usage);
+  if (tokens == null) return "context used ?";
+  if (contextWindowTokens == null) {
+    return `context used ${formatTokens(tokens)} tokens`;
+  }
+  const percentage = tokens / contextWindowTokens * 100;
+  const formattedPercentage = percentage > 0 && percentage < 0.01 ? "<0.01" : percentage.toFixed(2);
+  return `${formattedPercentage}% context used (${formatTokens(tokens)} / ${formatTokens(contextWindowTokens)} tokens)`;
+}
+async function logStream(stream) {
+  let active = null;
+  let openRouterCost = 0;
+  let hasOpenRouterCost = false;
+  let latestStepUsage;
+  let contextWindowPromise;
+  const endActive = () => {
+    if (active) process.stdout.write("\n");
+    active = null;
+  };
+  const startContextWindowFetch = (modelId) => {
+    if (!modelId || contextWindowPromise) return;
+    contextWindowPromise = getOpenRouterContextLength(modelId);
+  };
+  for await (const part of stream) {
+    switch (part.type) {
+      case "start-step":
+        endActive();
+        startContextWindowFetch(getModelId(part));
+        console.log(import_chalk.default.dim("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 step \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"));
+        break;
+      case "finish-step": {
+        latestStepUsage = part.usage;
+        startContextWindowFetch(getModelId(part));
+        const cost = getOpenRouterCost(part);
+        if (cost != null) {
+          openRouterCost += cost;
+          hasOpenRouterCost = true;
+        }
+        break;
+      }
+      case "reasoning-delta":
+        if (active !== "reasoning") {
+          endActive();
+          process.stdout.write(import_chalk.default.magenta.bold("\u{1F9E0} reasoning  "));
+          active = "reasoning";
+        }
+        process.stdout.write(import_chalk.default.magenta(part.text));
+        break;
+      case "text-delta":
+        if (active !== "text") {
+          endActive();
+          process.stdout.write(import_chalk.default.white.bold("\u{1F4AC} message    "));
+          active = "text";
+        }
+        process.stdout.write(import_chalk.default.white(part.text));
+        break;
+      case "tool-call":
+        endActive();
+        console.log(
+          import_chalk.default.cyan.bold(`\u{1F527} tool call  ${part.toolName}`) + import_chalk.default.cyan(`(${JSON.stringify(part.input)})`)
+        );
+        break;
+      case "tool-result":
+        endActive();
+        console.log(
+          import_chalk.default.green.bold(`\u2705 tool result ${part.toolName} `) + import_chalk.default.green(JSON.stringify(part.output))
+        );
+        break;
+      case "tool-error":
+        endActive();
+        console.log(
+          import_chalk.default.red.bold(`\u274C tool error ${part.toolName} `) + import_chalk.default.red(String(part.error))
+        );
+        break;
+      case "error":
+        endActive();
+        console.log(import_chalk.default.red.bold("\u203C\uFE0F  stream error "), part.error);
+        break;
+      case "finish": {
+        endActive();
+        const contextWindowTokens = contextWindowPromise ? await contextWindowPromise : null;
+        console.log(
+          import_chalk.default.dim(
+            `
+\u2500\u2500 done (${part.finishReason}) \xB7 ${formatContextUsage(latestStepUsage, contextWindowTokens)}${hasOpenRouterCost ? ` \xB7 cost ${formatCost(openRouterCost)}` : ""} \u2500\u2500`
+          )
+        );
+        break;
+      }
+    }
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createOpenRouter,
+  logStream
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/openrouter.ts","../src/logStream.ts"],"sourcesContent":["export {\n\tcreateOpenRouter,\n\ttype OpenRouterProvider,\n\ttype OpenRouterProviderSettings,\n} from \"./openrouter.js\";\nexport { logStream } from \"./logStream.js\";\n","import {\n\tcreateOpenRouter as baseCreateOpenRouter,\n\ttype OpenRouterProvider,\n\ttype OpenRouterProviderSettings,\n} from \"@openrouter/ai-sdk-provider\";\n\n/**\n * Drop-in replacement for `createOpenRouter` from `@openrouter/ai-sdk-provider`.\n *\n * It behaves identically to the original, with two conveniences baked in:\n *\n *  1. `apiKey` defaults to `process.env.OPENROUTER_API_KEY` when you don't pass\n *     one, so the common case is just `createOpenRouter()`.\n *  2. `extraBody.usage.include` defaults to `true`, which tells OpenRouter to\n *     return cost + token accounting on every response. This is what powers the\n *     mid-run cost/usage tracking in {@link logStream}.\n *\n * Every option you pass through wins over the defaults — including `usage` — so\n * this is 1:1 compatible with the upstream `createOpenRouter`. You can override\n * the api key, add your own `extraBody`, flip `usage.include` off, etc.\n *\n * @example\n * ```ts\n * import { createOpenRouter } from \"@merkie/agentic\";\n *\n * // Reads OPENROUTER_API_KEY from the environment, usage tracking on.\n * const openrouter = createOpenRouter();\n *\n * const model = openrouter(\"openai/gpt-4o-mini\");\n * ```\n */\nexport function createOpenRouter(\n\tsettings: OpenRouterProviderSettings = {},\n): OpenRouterProvider {\n\tconst { apiKey, extraBody, ...rest } = settings;\n\n\tconst userUsage =\n\t\textraBody && typeof extraBody === \"object\" && \"usage\" in extraBody\n\t\t\t? (extraBody as Record<string, unknown>).usage\n\t\t\t: undefined;\n\n\treturn baseCreateOpenRouter({\n\t\tapiKey: apiKey ?? process.env.OPENROUTER_API_KEY,\n\t\t...rest,\n\t\textraBody: {\n\t\t\t...extraBody,\n\t\t\tusage: {\n\t\t\t\tinclude: true,\n\t\t\t\t...(userUsage && typeof userUsage === \"object\"\n\t\t\t\t\t? (userUsage as Record<string, unknown>)\n\t\t\t\t\t: {}),\n\t\t\t},\n\t\t},\n\t});\n}\n\nexport type { OpenRouterProvider, OpenRouterProviderSettings };\n","import type { LanguageModelUsage, TextStreamPart, ToolSet } from \"ai\";\nimport chalk from \"chalk\";\n\ntype OpenRouterUsageCost = {\n\tcost?: number;\n\tcostDetails?: {\n\t\tupstreamInferenceCost?: number | null;\n\t};\n};\n\ntype OpenRouterModelResponse = {\n\tdata?: {\n\t\tcontext_length?: unknown;\n\t\ttop_provider?: {\n\t\t\tcontext_length?: unknown;\n\t\t};\n\t};\n};\n\nconst openRouterContextLengthCache = new Map<string, Promise<number | null>>();\n\nfunction getOpenRouterCost(part: TextStreamPart<ToolSet>) {\n\tif (part.type !== \"finish-step\") return null;\n\n\tconst metadataUsage = part.providerMetadata?.openrouter?.usage as\n\t\t| OpenRouterUsageCost\n\t\t| undefined;\n\tconst rawUsage = part.usage.raw as\n\t\t| {\n\t\t\t\tcost?: number;\n\t\t\t\tcost_details?: { upstream_inference_cost?: number | null };\n\t\t  }\n\t\t| undefined;\n\n\tconst cost = metadataUsage?.cost ?? rawUsage?.cost;\n\tconst upstreamInferenceCost =\n\t\tmetadataUsage?.costDetails?.upstreamInferenceCost ??\n\t\trawUsage?.cost_details?.upstream_inference_cost;\n\n\t// OpenRouter credit usage reports `cost`; BYOK usage can report `cost: 0`\n\t// with the real provider charge in `upstreamInferenceCost`.\n\tif (cost === 0 && upstreamInferenceCost != null) {\n\t\treturn upstreamInferenceCost;\n\t}\n\n\treturn cost ?? upstreamInferenceCost ?? null;\n}\n\nfunction formatCost(cost: number) {\n\treturn `$${cost.toFixed(6)}`;\n}\n\nfunction formatTokens(tokens: number) {\n\treturn tokens.toLocaleString(\"en-US\");\n}\n\nfunction parsePositiveInteger(value: unknown) {\n\tif (typeof value === \"number\" && Number.isInteger(value) && value > 0) {\n\t\treturn value;\n\t}\n\n\tif (typeof value === \"string\") {\n\t\tconst parsed = Number(value);\n\t\tif (Number.isInteger(parsed) && parsed > 0) {\n\t\t\treturn parsed;\n\t\t}\n\t}\n\n\treturn null;\n}\n\nfunction getOpenRouterContextLengthFromResponse(payload: unknown) {\n\tconst data = (payload as OpenRouterModelResponse).data;\n\treturn (\n\t\tparsePositiveInteger(data?.context_length) ??\n\t\tparsePositiveInteger(data?.top_provider?.context_length)\n\t);\n}\n\nasync function fetchOpenRouterContextLength(modelId: string) {\n\tconst pathModelId = modelId.split(\"/\").map(encodeURIComponent).join(\"/\");\n\tconst response = await fetch(\n\t\t`https://openrouter.ai/api/v1/model/${pathModelId}`,\n\t);\n\n\tif (!response.ok) {\n\t\treturn null;\n\t}\n\n\treturn getOpenRouterContextLengthFromResponse(await response.json());\n}\n\nfunction getOpenRouterContextLength(modelId: string) {\n\tconst cached = openRouterContextLengthCache.get(modelId);\n\tif (cached) return cached;\n\n\tconst promise = fetchOpenRouterContextLength(modelId).catch(() => null);\n\topenRouterContextLengthCache.set(modelId, promise);\n\treturn promise;\n}\n\nfunction getModelId(part: TextStreamPart<ToolSet>) {\n\tif (part.type === \"start-step\") {\n\t\tconst body = part.request.body;\n\t\tif (body && typeof body === \"object\" && \"model\" in body) {\n\t\t\tconst model = body.model;\n\t\t\tif (typeof model === \"string\" && model.length > 0) {\n\t\t\t\treturn model;\n\t\t\t}\n\t\t}\n\t}\n\n\tif (part.type === \"finish-step\") {\n\t\treturn part.response.modelId;\n\t}\n\n\treturn null;\n}\n\nfunction getUsageTokens(usage: LanguageModelUsage | undefined) {\n\tif (!usage) return null;\n\n\t// Context usage is the stopping-point conversation size estimate:\n\t// the last step's input tokens are the full history before the final response,\n\t// and its output tokens are what will be appended to that history. An exact\n\t// \"next empty user message\" count would require another provider tokenization\n\t// pass because the stream does not emit usage for hypothetical future calls.\n\tif (usage.inputTokens != null || usage.outputTokens != null) {\n\t\treturn (usage.inputTokens ?? 0) + (usage.outputTokens ?? 0);\n\t}\n\n\treturn usage.totalTokens ?? null;\n}\n\nfunction formatContextUsage(\n\tusage: LanguageModelUsage | undefined,\n\tcontextWindowTokens: number | null,\n) {\n\tconst tokens = getUsageTokens(usage);\n\tif (tokens == null) return \"context used ?\";\n\n\tif (contextWindowTokens == null) {\n\t\treturn `context used ${formatTokens(tokens)} tokens`;\n\t}\n\n\tconst percentage = (tokens / contextWindowTokens) * 100;\n\tconst formattedPercentage =\n\t\tpercentage > 0 && percentage < 0.01 ? \"<0.01\" : percentage.toFixed(2);\n\n\treturn `${formattedPercentage}% context used (${formatTokens(tokens)} / ${formatTokens(contextWindowTokens)} tokens)`;\n}\n\n/**\n * Pretty-prints every event coming off an AI SDK full stream so you can watch\n * the model think, talk, and call tools in real time — and see live token /\n * cost accounting when the model is served through OpenRouter (see\n * {@link createOpenRouter}).\n *\n * Pass it the `fullStream` from `streamText`:\n *\n * @example\n * ```ts\n * import { streamText } from \"ai\";\n * import { createOpenRouter, logStream } from \"@merkie/agentic\";\n *\n * const openrouter = createOpenRouter();\n *\n * const result = streamText({\n *   model: openrouter(\"openai/gpt-4o-mini\"),\n *   prompt: \"Explain quantum tunneling in one paragraph.\",\n * });\n *\n * await logStream(result.fullStream);\n * ```\n */\nexport async function logStream(\n\tstream: AsyncIterable<TextStreamPart<ToolSet>>,\n): Promise<void> {\n\t// Track which \"channel\" (reasoning vs. text) we're currently writing to so we\n\t// only print a header when it changes, and stream deltas onto the same line.\n\tlet active: \"reasoning\" | \"text\" | null = null;\n\tlet openRouterCost = 0;\n\tlet hasOpenRouterCost = false;\n\tlet latestStepUsage: LanguageModelUsage | undefined;\n\tlet contextWindowPromise: Promise<number | null> | undefined;\n\n\tconst endActive = () => {\n\t\tif (active) process.stdout.write(\"\\n\");\n\t\tactive = null;\n\t};\n\n\tconst startContextWindowFetch = (modelId: string | null) => {\n\t\tif (!modelId || contextWindowPromise) return;\n\t\tcontextWindowPromise = getOpenRouterContextLength(modelId);\n\t};\n\n\tfor await (const part of stream) {\n\t\tswitch (part.type) {\n\t\t\tcase \"start-step\":\n\t\t\t\tendActive();\n\t\t\t\tstartContextWindowFetch(getModelId(part));\n\t\t\t\tconsole.log(chalk.dim(\"──────── step ────────\"));\n\t\t\t\tbreak;\n\n\t\t\tcase \"finish-step\": {\n\t\t\t\tlatestStepUsage = part.usage;\n\t\t\t\tstartContextWindowFetch(getModelId(part));\n\t\t\t\tconst cost = getOpenRouterCost(part);\n\t\t\t\tif (cost != null) {\n\t\t\t\t\topenRouterCost += cost;\n\t\t\t\t\thasOpenRouterCost = true;\n\t\t\t\t}\n\t\t\t\tbreak;\n\t\t\t}\n\n\t\t\tcase \"reasoning-delta\":\n\t\t\t\tif (active !== \"reasoning\") {\n\t\t\t\t\tendActive();\n\t\t\t\t\tprocess.stdout.write(chalk.magenta.bold(\"🧠 reasoning  \"));\n\t\t\t\t\tactive = \"reasoning\";\n\t\t\t\t}\n\t\t\t\tprocess.stdout.write(chalk.magenta(part.text));\n\t\t\t\tbreak;\n\n\t\t\tcase \"text-delta\":\n\t\t\t\tif (active !== \"text\") {\n\t\t\t\t\tendActive();\n\t\t\t\t\tprocess.stdout.write(chalk.white.bold(\"💬 message    \"));\n\t\t\t\t\tactive = \"text\";\n\t\t\t\t}\n\t\t\t\tprocess.stdout.write(chalk.white(part.text));\n\t\t\t\tbreak;\n\n\t\t\tcase \"tool-call\":\n\t\t\t\tendActive();\n\t\t\t\tconsole.log(\n\t\t\t\t\tchalk.cyan.bold(`🔧 tool call  ${part.toolName}`) +\n\t\t\t\t\t\tchalk.cyan(`(${JSON.stringify(part.input)})`),\n\t\t\t\t);\n\t\t\t\tbreak;\n\n\t\t\tcase \"tool-result\":\n\t\t\t\tendActive();\n\t\t\t\tconsole.log(\n\t\t\t\t\tchalk.green.bold(`✅ tool result ${part.toolName} `) +\n\t\t\t\t\t\tchalk.green(JSON.stringify(part.output)),\n\t\t\t\t);\n\t\t\t\tbreak;\n\n\t\t\tcase \"tool-error\":\n\t\t\t\tendActive();\n\t\t\t\tconsole.log(\n\t\t\t\t\tchalk.red.bold(`❌ tool error ${part.toolName} `) +\n\t\t\t\t\t\tchalk.red(String(part.error)),\n\t\t\t\t);\n\t\t\t\tbreak;\n\n\t\t\tcase \"error\":\n\t\t\t\tendActive();\n\t\t\t\tconsole.log(chalk.red.bold(\"‼️  stream error \"), part.error);\n\t\t\t\tbreak;\n\n\t\t\tcase \"finish\": {\n\t\t\t\tendActive();\n\t\t\t\tconst contextWindowTokens = contextWindowPromise\n\t\t\t\t\t? await contextWindowPromise\n\t\t\t\t\t: null;\n\t\t\t\tconsole.log(\n\t\t\t\t\tchalk.dim(\n\t\t\t\t\t\t`\\n── done (${part.finishReason}) · ${formatContextUsage(latestStepUsage, contextWindowTokens)}${hasOpenRouterCost ? ` · cost ${formatCost(openRouterCost)}` : \"\"} ──`,\n\t\t\t\t\t),\n\t\t\t\t);\n\t\t\t\tbreak;\n\t\t\t}\n\t\t}\n\t}\n}\n\nexport default logStream;\n"],"mappings":"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","names":["baseCreateOpenRouter","chalk"]}

package/dist/index.d.cts

@@ -0,0 +1,57 @@
+import { OpenRouterProviderSettings, OpenRouterProvider } from '@openrouter/ai-sdk-provider';
+export { OpenRouterProvider, OpenRouterProviderSettings } from '@openrouter/ai-sdk-provider';
+import { TextStreamPart, ToolSet } from 'ai';
+
+/**
+ * Drop-in replacement for `createOpenRouter` from `@openrouter/ai-sdk-provider`.
+ *
+ * It behaves identically to the original, with two conveniences baked in:
+ *
+ *  1. `apiKey` defaults to `process.env.OPENROUTER_API_KEY` when you don't pass
+ *     one, so the common case is just `createOpenRouter()`.
+ *  2. `extraBody.usage.include` defaults to `true`, which tells OpenRouter to
+ *     return cost + token accounting on every response. This is what powers the
+ *     mid-run cost/usage tracking in {@link logStream}.
+ *
+ * Every option you pass through wins over the defaults — including `usage` — so
+ * this is 1:1 compatible with the upstream `createOpenRouter`. You can override
+ * the api key, add your own `extraBody`, flip `usage.include` off, etc.
+ *
+ * @example
+ * ```ts
+ * import { createOpenRouter } from "@merkie/agentic";
+ *
+ * // Reads OPENROUTER_API_KEY from the environment, usage tracking on.
+ * const openrouter = createOpenRouter();
+ *
+ * const model = openrouter("openai/gpt-4o-mini");
+ * ```
+ */
+declare function createOpenRouter(settings?: OpenRouterProviderSettings): OpenRouterProvider;
+
+/**
+ * Pretty-prints every event coming off an AI SDK full stream so you can watch
+ * the model think, talk, and call tools in real time — and see live token /
+ * cost accounting when the model is served through OpenRouter (see
+ * {@link createOpenRouter}).
+ *
+ * Pass it the `fullStream` from `streamText`:
+ *
+ * @example
+ * ```ts
+ * import { streamText } from "ai";
+ * import { createOpenRouter, logStream } from "@merkie/agentic";
+ *
+ * const openrouter = createOpenRouter();
+ *
+ * const result = streamText({
+ *   model: openrouter("openai/gpt-4o-mini"),
+ *   prompt: "Explain quantum tunneling in one paragraph.",
+ * });
+ *
+ * await logStream(result.fullStream);
+ * ```
+ */
+declare function logStream(stream: AsyncIterable<TextStreamPart<ToolSet>>): Promise<void>;
+
+export { createOpenRouter, logStream };

package/dist/index.d.ts

@@ -0,0 +1,57 @@
+import { OpenRouterProviderSettings, OpenRouterProvider } from '@openrouter/ai-sdk-provider';
+export { OpenRouterProvider, OpenRouterProviderSettings } from '@openrouter/ai-sdk-provider';
+import { TextStreamPart, ToolSet } from 'ai';
+
+/**
+ * Drop-in replacement for `createOpenRouter` from `@openrouter/ai-sdk-provider`.
+ *
+ * It behaves identically to the original, with two conveniences baked in:
+ *
+ *  1. `apiKey` defaults to `process.env.OPENROUTER_API_KEY` when you don't pass
+ *     one, so the common case is just `createOpenRouter()`.
+ *  2. `extraBody.usage.include` defaults to `true`, which tells OpenRouter to
+ *     return cost + token accounting on every response. This is what powers the
+ *     mid-run cost/usage tracking in {@link logStream}.
+ *
+ * Every option you pass through wins over the defaults — including `usage` — so
+ * this is 1:1 compatible with the upstream `createOpenRouter`. You can override
+ * the api key, add your own `extraBody`, flip `usage.include` off, etc.
+ *
+ * @example
+ * ```ts
+ * import { createOpenRouter } from "@merkie/agentic";
+ *
+ * // Reads OPENROUTER_API_KEY from the environment, usage tracking on.
+ * const openrouter = createOpenRouter();
+ *
+ * const model = openrouter("openai/gpt-4o-mini");
+ * ```
+ */
+declare function createOpenRouter(settings?: OpenRouterProviderSettings): OpenRouterProvider;
+
+/**
+ * Pretty-prints every event coming off an AI SDK full stream so you can watch
+ * the model think, talk, and call tools in real time — and see live token /
+ * cost accounting when the model is served through OpenRouter (see
+ * {@link createOpenRouter}).
+ *
+ * Pass it the `fullStream` from `streamText`:
+ *
+ * @example
+ * ```ts
+ * import { streamText } from "ai";
+ * import { createOpenRouter, logStream } from "@merkie/agentic";
+ *
+ * const openrouter = createOpenRouter();
+ *
+ * const result = streamText({
+ *   model: openrouter("openai/gpt-4o-mini"),
+ *   prompt: "Explain quantum tunneling in one paragraph.",
+ * });
+ *
+ * await logStream(result.fullStream);
+ * ```
+ */
+declare function logStream(stream: AsyncIterable<TextStreamPart<ToolSet>>): Promise<void>;
+
+export { createOpenRouter, logStream };

package/dist/index.js

@@ -0,0 +1,193 @@
+// src/openrouter.ts
+import {
+  createOpenRouter as baseCreateOpenRouter
+} from "@openrouter/ai-sdk-provider";
+function createOpenRouter(settings = {}) {
+  const { apiKey, extraBody, ...rest } = settings;
+  const userUsage = extraBody && typeof extraBody === "object" && "usage" in extraBody ? extraBody.usage : void 0;
+  return baseCreateOpenRouter({
+    apiKey: apiKey ?? process.env.OPENROUTER_API_KEY,
+    ...rest,
+    extraBody: {
+      ...extraBody,
+      usage: {
+        include: true,
+        ...userUsage && typeof userUsage === "object" ? userUsage : {}
+      }
+    }
+  });
+}
+
+// src/logStream.ts
+import chalk from "chalk";
+var openRouterContextLengthCache = /* @__PURE__ */ new Map();
+function getOpenRouterCost(part) {
+  if (part.type !== "finish-step") return null;
+  const metadataUsage = part.providerMetadata?.openrouter?.usage;
+  const rawUsage = part.usage.raw;
+  const cost = metadataUsage?.cost ?? rawUsage?.cost;
+  const upstreamInferenceCost = metadataUsage?.costDetails?.upstreamInferenceCost ?? rawUsage?.cost_details?.upstream_inference_cost;
+  if (cost === 0 && upstreamInferenceCost != null) {
+    return upstreamInferenceCost;
+  }
+  return cost ?? upstreamInferenceCost ?? null;
+}
+function formatCost(cost) {
+  return `$${cost.toFixed(6)}`;
+}
+function formatTokens(tokens) {
+  return tokens.toLocaleString("en-US");
+}
+function parsePositiveInteger(value) {
+  if (typeof value === "number" && Number.isInteger(value) && value > 0) {
+    return value;
+  }
+  if (typeof value === "string") {
+    const parsed = Number(value);
+    if (Number.isInteger(parsed) && parsed > 0) {
+      return parsed;
+    }
+  }
+  return null;
+}
+function getOpenRouterContextLengthFromResponse(payload) {
+  const data = payload.data;
+  return parsePositiveInteger(data?.context_length) ?? parsePositiveInteger(data?.top_provider?.context_length);
+}
+async function fetchOpenRouterContextLength(modelId) {
+  const pathModelId = modelId.split("/").map(encodeURIComponent).join("/");
+  const response = await fetch(
+    `https://openrouter.ai/api/v1/model/${pathModelId}`
+  );
+  if (!response.ok) {
+    return null;
+  }
+  return getOpenRouterContextLengthFromResponse(await response.json());
+}
+function getOpenRouterContextLength(modelId) {
+  const cached = openRouterContextLengthCache.get(modelId);
+  if (cached) return cached;
+  const promise = fetchOpenRouterContextLength(modelId).catch(() => null);
+  openRouterContextLengthCache.set(modelId, promise);
+  return promise;
+}
+function getModelId(part) {
+  if (part.type === "start-step") {
+    const body = part.request.body;
+    if (body && typeof body === "object" && "model" in body) {
+      const model = body.model;
+      if (typeof model === "string" && model.length > 0) {
+        return model;
+      }
+    }
+  }
+  if (part.type === "finish-step") {
+    return part.response.modelId;
+  }
+  return null;
+}
+function getUsageTokens(usage) {
+  if (!usage) return null;
+  if (usage.inputTokens != null || usage.outputTokens != null) {
+    return (usage.inputTokens ?? 0) + (usage.outputTokens ?? 0);
+  }
+  return usage.totalTokens ?? null;
+}
+function formatContextUsage(usage, contextWindowTokens) {
+  const tokens = getUsageTokens(usage);
+  if (tokens == null) return "context used ?";
+  if (contextWindowTokens == null) {
+    return `context used ${formatTokens(tokens)} tokens`;
+  }
+  const percentage = tokens / contextWindowTokens * 100;
+  const formattedPercentage = percentage > 0 && percentage < 0.01 ? "<0.01" : percentage.toFixed(2);
+  return `${formattedPercentage}% context used (${formatTokens(tokens)} / ${formatTokens(contextWindowTokens)} tokens)`;
+}
+async function logStream(stream) {
+  let active = null;
+  let openRouterCost = 0;
+  let hasOpenRouterCost = false;
+  let latestStepUsage;
+  let contextWindowPromise;
+  const endActive = () => {
+    if (active) process.stdout.write("\n");
+    active = null;
+  };
+  const startContextWindowFetch = (modelId) => {
+    if (!modelId || contextWindowPromise) return;
+    contextWindowPromise = getOpenRouterContextLength(modelId);
+  };
+  for await (const part of stream) {
+    switch (part.type) {
+      case "start-step":
+        endActive();
+        startContextWindowFetch(getModelId(part));
+        console.log(chalk.dim("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 step \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"));
+        break;
+      case "finish-step": {
+        latestStepUsage = part.usage;
+        startContextWindowFetch(getModelId(part));
+        const cost = getOpenRouterCost(part);
+        if (cost != null) {
+          openRouterCost += cost;
+          hasOpenRouterCost = true;
+        }
+        break;
+      }
+      case "reasoning-delta":
+        if (active !== "reasoning") {
+          endActive();
+          process.stdout.write(chalk.magenta.bold("\u{1F9E0} reasoning  "));
+          active = "reasoning";
+        }
+        process.stdout.write(chalk.magenta(part.text));
+        break;
+      case "text-delta":
+        if (active !== "text") {
+          endActive();
+          process.stdout.write(chalk.white.bold("\u{1F4AC} message    "));
+          active = "text";
+        }
+        process.stdout.write(chalk.white(part.text));
+        break;
+      case "tool-call":
+        endActive();
+        console.log(
+          chalk.cyan.bold(`\u{1F527} tool call  ${part.toolName}`) + chalk.cyan(`(${JSON.stringify(part.input)})`)
+        );
+        break;
+      case "tool-result":
+        endActive();
+        console.log(
+          chalk.green.bold(`\u2705 tool result ${part.toolName} `) + chalk.green(JSON.stringify(part.output))
+        );
+        break;
+      case "tool-error":
+        endActive();
+        console.log(
+          chalk.red.bold(`\u274C tool error ${part.toolName} `) + chalk.red(String(part.error))
+        );
+        break;
+      case "error":
+        endActive();
+        console.log(chalk.red.bold("\u203C\uFE0F  stream error "), part.error);
+        break;
+      case "finish": {
+        endActive();
+        const contextWindowTokens = contextWindowPromise ? await contextWindowPromise : null;
+        console.log(
+          chalk.dim(
+            `
+\u2500\u2500 done (${part.finishReason}) \xB7 ${formatContextUsage(latestStepUsage, contextWindowTokens)}${hasOpenRouterCost ? ` \xB7 cost ${formatCost(openRouterCost)}` : ""} \u2500\u2500`
+          )
+        );
+        break;
+      }
+    }
+  }
+}
+export {
+  createOpenRouter,
+  logStream
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/openrouter.ts","../src/logStream.ts"],"sourcesContent":["import {\n\tcreateOpenRouter as baseCreateOpenRouter,\n\ttype OpenRouterProvider,\n\ttype OpenRouterProviderSettings,\n} from \"@openrouter/ai-sdk-provider\";\n\n/**\n * Drop-in replacement for `createOpenRouter` from `@openrouter/ai-sdk-provider`.\n *\n * It behaves identically to the original, with two conveniences baked in:\n *\n *  1. `apiKey` defaults to `process.env.OPENROUTER_API_KEY` when you don't pass\n *     one, so the common case is just `createOpenRouter()`.\n *  2. `extraBody.usage.include` defaults to `true`, which tells OpenRouter to\n *     return cost + token accounting on every response. This is what powers the\n *     mid-run cost/usage tracking in {@link logStream}.\n *\n * Every option you pass through wins over the defaults — including `usage` — so\n * this is 1:1 compatible with the upstream `createOpenRouter`. You can override\n * the api key, add your own `extraBody`, flip `usage.include` off, etc.\n *\n * @example\n * ```ts\n * import { createOpenRouter } from \"@merkie/agentic\";\n *\n * // Reads OPENROUTER_API_KEY from the environment, usage tracking on.\n * const openrouter = createOpenRouter();\n *\n * const model = openrouter(\"openai/gpt-4o-mini\");\n * ```\n */\nexport function createOpenRouter(\n\tsettings: OpenRouterProviderSettings = {},\n): OpenRouterProvider {\n\tconst { apiKey, extraBody, ...rest } = settings;\n\n\tconst userUsage =\n\t\textraBody && typeof extraBody === \"object\" && \"usage\" in extraBody\n\t\t\t? (extraBody as Record<string, unknown>).usage\n\t\t\t: undefined;\n\n\treturn baseCreateOpenRouter({\n\t\tapiKey: apiKey ?? process.env.OPENROUTER_API_KEY,\n\t\t...rest,\n\t\textraBody: {\n\t\t\t...extraBody,\n\t\t\tusage: {\n\t\t\t\tinclude: true,\n\t\t\t\t...(userUsage && typeof userUsage === \"object\"\n\t\t\t\t\t? (userUsage as Record<string, unknown>)\n\t\t\t\t\t: {}),\n\t\t\t},\n\t\t},\n\t});\n}\n\nexport type { OpenRouterProvider, OpenRouterProviderSettings };\n","import type { LanguageModelUsage, TextStreamPart, ToolSet } from \"ai\";\nimport chalk from \"chalk\";\n\ntype OpenRouterUsageCost = {\n\tcost?: number;\n\tcostDetails?: {\n\t\tupstreamInferenceCost?: number | null;\n\t};\n};\n\ntype OpenRouterModelResponse = {\n\tdata?: {\n\t\tcontext_length?: unknown;\n\t\ttop_provider?: {\n\t\t\tcontext_length?: unknown;\n\t\t};\n\t};\n};\n\nconst openRouterContextLengthCache = new Map<string, Promise<number | null>>();\n\nfunction getOpenRouterCost(part: TextStreamPart<ToolSet>) {\n\tif (part.type !== \"finish-step\") return null;\n\n\tconst metadataUsage = part.providerMetadata?.openrouter?.usage as\n\t\t| OpenRouterUsageCost\n\t\t| undefined;\n\tconst rawUsage = part.usage.raw as\n\t\t| {\n\t\t\t\tcost?: number;\n\t\t\t\tcost_details?: { upstream_inference_cost?: number | null };\n\t\t  }\n\t\t| undefined;\n\n\tconst cost = metadataUsage?.cost ?? rawUsage?.cost;\n\tconst upstreamInferenceCost =\n\t\tmetadataUsage?.costDetails?.upstreamInferenceCost ??\n\t\trawUsage?.cost_details?.upstream_inference_cost;\n\n\t// OpenRouter credit usage reports `cost`; BYOK usage can report `cost: 0`\n\t// with the real provider charge in `upstreamInferenceCost`.\n\tif (cost === 0 && upstreamInferenceCost != null) {\n\t\treturn upstreamInferenceCost;\n\t}\n\n\treturn cost ?? upstreamInferenceCost ?? null;\n}\n\nfunction formatCost(cost: number) {\n\treturn `$${cost.toFixed(6)}`;\n}\n\nfunction formatTokens(tokens: number) {\n\treturn tokens.toLocaleString(\"en-US\");\n}\n\nfunction parsePositiveInteger(value: unknown) {\n\tif (typeof value === \"number\" && Number.isInteger(value) && value > 0) {\n\t\treturn value;\n\t}\n\n\tif (typeof value === \"string\") {\n\t\tconst parsed = Number(value);\n\t\tif (Number.isInteger(parsed) && parsed > 0) {\n\t\t\treturn parsed;\n\t\t}\n\t}\n\n\treturn null;\n}\n\nfunction getOpenRouterContextLengthFromResponse(payload: unknown) {\n\tconst data = (payload as OpenRouterModelResponse).data;\n\treturn (\n\t\tparsePositiveInteger(data?.context_length) ??\n\t\tparsePositiveInteger(data?.top_provider?.context_length)\n\t);\n}\n\nasync function fetchOpenRouterContextLength(modelId: string) {\n\tconst pathModelId = modelId.split(\"/\").map(encodeURIComponent).join(\"/\");\n\tconst response = await fetch(\n\t\t`https://openrouter.ai/api/v1/model/${pathModelId}`,\n\t);\n\n\tif (!response.ok) {\n\t\treturn null;\n\t}\n\n\treturn getOpenRouterContextLengthFromResponse(await response.json());\n}\n\nfunction getOpenRouterContextLength(modelId: string) {\n\tconst cached = openRouterContextLengthCache.get(modelId);\n\tif (cached) return cached;\n\n\tconst promise = fetchOpenRouterContextLength(modelId).catch(() => null);\n\topenRouterContextLengthCache.set(modelId, promise);\n\treturn promise;\n}\n\nfunction getModelId(part: TextStreamPart<ToolSet>) {\n\tif (part.type === \"start-step\") {\n\t\tconst body = part.request.body;\n\t\tif (body && typeof body === \"object\" && \"model\" in body) {\n\t\t\tconst model = body.model;\n\t\t\tif (typeof model === \"string\" && model.length > 0) {\n\t\t\t\treturn model;\n\t\t\t}\n\t\t}\n\t}\n\n\tif (part.type === \"finish-step\") {\n\t\treturn part.response.modelId;\n\t}\n\n\treturn null;\n}\n\nfunction getUsageTokens(usage: LanguageModelUsage | undefined) {\n\tif (!usage) return null;\n\n\t// Context usage is the stopping-point conversation size estimate:\n\t// the last step's input tokens are the full history before the final response,\n\t// and its output tokens are what will be appended to that history. An exact\n\t// \"next empty user message\" count would require another provider tokenization\n\t// pass because the stream does not emit usage for hypothetical future calls.\n\tif (usage.inputTokens != null || usage.outputTokens != null) {\n\t\treturn (usage.inputTokens ?? 0) + (usage.outputTokens ?? 0);\n\t}\n\n\treturn usage.totalTokens ?? null;\n}\n\nfunction formatContextUsage(\n\tusage: LanguageModelUsage | undefined,\n\tcontextWindowTokens: number | null,\n) {\n\tconst tokens = getUsageTokens(usage);\n\tif (tokens == null) return \"context used ?\";\n\n\tif (contextWindowTokens == null) {\n\t\treturn `context used ${formatTokens(tokens)} tokens`;\n\t}\n\n\tconst percentage = (tokens / contextWindowTokens) * 100;\n\tconst formattedPercentage =\n\t\tpercentage > 0 && percentage < 0.01 ? \"<0.01\" : percentage.toFixed(2);\n\n\treturn `${formattedPercentage}% context used (${formatTokens(tokens)} / ${formatTokens(contextWindowTokens)} tokens)`;\n}\n\n/**\n * Pretty-prints every event coming off an AI SDK full stream so you can watch\n * the model think, talk, and call tools in real time — and see live token /\n * cost accounting when the model is served through OpenRouter (see\n * {@link createOpenRouter}).\n *\n * Pass it the `fullStream` from `streamText`:\n *\n * @example\n * ```ts\n * import { streamText } from \"ai\";\n * import { createOpenRouter, logStream } from \"@merkie/agentic\";\n *\n * const openrouter = createOpenRouter();\n *\n * const result = streamText({\n *   model: openrouter(\"openai/gpt-4o-mini\"),\n *   prompt: \"Explain quantum tunneling in one paragraph.\",\n * });\n *\n * await logStream(result.fullStream);\n * ```\n */\nexport async function logStream(\n\tstream: AsyncIterable<TextStreamPart<ToolSet>>,\n): Promise<void> {\n\t// Track which \"channel\" (reasoning vs. text) we're currently writing to so we\n\t// only print a header when it changes, and stream deltas onto the same line.\n\tlet active: \"reasoning\" | \"text\" | null = null;\n\tlet openRouterCost = 0;\n\tlet hasOpenRouterCost = false;\n\tlet latestStepUsage: LanguageModelUsage | undefined;\n\tlet contextWindowPromise: Promise<number | null> | undefined;\n\n\tconst endActive = () => {\n\t\tif (active) process.stdout.write(\"\\n\");\n\t\tactive = null;\n\t};\n\n\tconst startContextWindowFetch = (modelId: string | null) => {\n\t\tif (!modelId || contextWindowPromise) return;\n\t\tcontextWindowPromise = getOpenRouterContextLength(modelId);\n\t};\n\n\tfor await (const part of stream) {\n\t\tswitch (part.type) {\n\t\t\tcase \"start-step\":\n\t\t\t\tendActive();\n\t\t\t\tstartContextWindowFetch(getModelId(part));\n\t\t\t\tconsole.log(chalk.dim(\"──────── step ────────\"));\n\t\t\t\tbreak;\n\n\t\t\tcase \"finish-step\": {\n\t\t\t\tlatestStepUsage = part.usage;\n\t\t\t\tstartContextWindowFetch(getModelId(part));\n\t\t\t\tconst cost = getOpenRouterCost(part);\n\t\t\t\tif (cost != null) {\n\t\t\t\t\topenRouterCost += cost;\n\t\t\t\t\thasOpenRouterCost = true;\n\t\t\t\t}\n\t\t\t\tbreak;\n\t\t\t}\n\n\t\t\tcase \"reasoning-delta\":\n\t\t\t\tif (active !== \"reasoning\") {\n\t\t\t\t\tendActive();\n\t\t\t\t\tprocess.stdout.write(chalk.magenta.bold(\"🧠 reasoning  \"));\n\t\t\t\t\tactive = \"reasoning\";\n\t\t\t\t}\n\t\t\t\tprocess.stdout.write(chalk.magenta(part.text));\n\t\t\t\tbreak;\n\n\t\t\tcase \"text-delta\":\n\t\t\t\tif (active !== \"text\") {\n\t\t\t\t\tendActive();\n\t\t\t\t\tprocess.stdout.write(chalk.white.bold(\"💬 message    \"));\n\t\t\t\t\tactive = \"text\";\n\t\t\t\t}\n\t\t\t\tprocess.stdout.write(chalk.white(part.text));\n\t\t\t\tbreak;\n\n\t\t\tcase \"tool-call\":\n\t\t\t\tendActive();\n\t\t\t\tconsole.log(\n\t\t\t\t\tchalk.cyan.bold(`🔧 tool call  ${part.toolName}`) +\n\t\t\t\t\t\tchalk.cyan(`(${JSON.stringify(part.input)})`),\n\t\t\t\t);\n\t\t\t\tbreak;\n\n\t\t\tcase \"tool-result\":\n\t\t\t\tendActive();\n\t\t\t\tconsole.log(\n\t\t\t\t\tchalk.green.bold(`✅ tool result ${part.toolName} `) +\n\t\t\t\t\t\tchalk.green(JSON.stringify(part.output)),\n\t\t\t\t);\n\t\t\t\tbreak;\n\n\t\t\tcase \"tool-error\":\n\t\t\t\tendActive();\n\t\t\t\tconsole.log(\n\t\t\t\t\tchalk.red.bold(`❌ tool error ${part.toolName} `) +\n\t\t\t\t\t\tchalk.red(String(part.error)),\n\t\t\t\t);\n\t\t\t\tbreak;\n\n\t\t\tcase \"error\":\n\t\t\t\tendActive();\n\t\t\t\tconsole.log(chalk.red.bold(\"‼️  stream error \"), part.error);\n\t\t\t\tbreak;\n\n\t\t\tcase \"finish\": {\n\t\t\t\tendActive();\n\t\t\t\tconst contextWindowTokens = contextWindowPromise\n\t\t\t\t\t? await contextWindowPromise\n\t\t\t\t\t: null;\n\t\t\t\tconsole.log(\n\t\t\t\t\tchalk.dim(\n\t\t\t\t\t\t`\\n── done (${part.finishReason}) · ${formatContextUsage(latestStepUsage, contextWindowTokens)}${hasOpenRouterCost ? ` · cost ${formatCost(openRouterCost)}` : \"\"} ──`,\n\t\t\t\t\t),\n\t\t\t\t);\n\t\t\t\tbreak;\n\t\t\t}\n\t\t}\n\t}\n}\n\nexport default logStream;\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@merkie/agentic",
+  "version": "0.1.0",
+  "description": "Batteries-included helpers for building LLM-powered apps with the Vercel AI SDK and OpenRouter — automatic cost/usage tracking and pretty stream logging out of the box.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Merkie <archercalder@gmail.com>",
+  "homepage": "https://github.com/Merkie/agentic#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Merkie/agentic.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Merkie/agentic/issues"
+  },
+  "keywords": [
+    "ai",
+    "llm",
+    "agent",
+    "agents",
+    "openrouter",
+    "vercel-ai-sdk",
+    "ai-sdk",
+    "observability",
+    "cost-tracking",
+    "usage-tracking",
+    "streaming"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "chalk": "^5.6.2"
+  },
+  "peerDependencies": {
+    "@openrouter/ai-sdk-provider": ">=2",
+    "ai": ">=5"
+  },
+  "devDependencies": {
+    "@openrouter/ai-sdk-provider": "2.3.3",
+    "@types/node": "22.15.0",
+    "ai": "6.0.160",
+    "tsup": "^8.5.0",
+    "typescript": "5.4.5",
+    "vitest": "^3.2.4"
+  }
+}