veryfront 0.1.1224 → 0.1.1226

package/README.md

@@ -37,7 +37,7 @@ deno init --npm veryfront
 The default starter is `ai-agent`. Choose another template directly:
 
 ```bash
-npx veryfront init <PROJECT_NAME> --template <TEMPLATE>
+npx veryfront@latest init <PROJECT_NAME> --template <TEMPLATE>
 ```
 
 Available starters: `ai-agent`, `minimal`, `agentic-workflow`.

package/esm/cli/main.d.ts

@@ -5,7 +5,7 @@
  *
  * @example
  * ```sh
- * npx veryfront dev
+ * npx veryfront@latest dev
  * ```
  */
 import "../_dnt.polyfills.js";

package/esm/cli/main.js

@@ -5,7 +5,7 @@
  *
  * @example
  * ```sh
- * npx veryfront dev
+ * npx veryfront@latest dev
  * ```
  */
 // Set the CLI logger preset before importing modules that may log during initialization.

package/esm/cli/shared/deployment/deploy-project.d.ts.map

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

package/esm/cli/shared/deployment/deploy-project.js

@@ -456,10 +456,55 @@ function isMatchingVeryfrontHostedUrl(url, target) {
         parsed.slug === target.projectSlug.toLowerCase() &&
         parsed.environment === target.environmentName.toLowerCase();
 }
+const MAX_JWT_SEGMENT_CODE_UNITS = 8 * 1024;
+/** Decode one base64url JWT segment into a plain object, or null if it is not one. */
+function decodeJwtSegment(segment) {
+    if (segment === undefined)
+        return null;
+    if (segment.length === 0 || segment.length > MAX_JWT_SEGMENT_CODE_UNITS)
+        return null;
+    try {
+        const base64 = segment.replaceAll("-", "+").replaceAll("_", "/");
+        const binary = atob(base64 + "=".repeat((4 - base64.length % 4) % 4));
+        const bytes = Uint8Array.from(binary, (character) => character.charCodeAt(0));
+        const parsed = JSON.parse(new TextDecoder().decode(bytes));
+        return typeof parsed === "object" && parsed !== null ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Whether a stored credential could satisfy the protected-environment gate.
+ *
+ * The gate reads `userId` from the verified JWT payload and has no API-key
+ * branch, so presenting an opaque key only leaks it. Reads what the gate
+ * reads, and withholds anything it cannot recognise.
+ */
+function isSessionCredential(apiToken) {
+    const segments = apiToken.split(".");
+    if (segments.length !== 3)
+        return false;
+    const header = decodeJwtSegment(segments[0]);
+    if (header === null || typeof readUntrustedOwnDataProperty(header, "alg") !== "string") {
+        return false;
+    }
+    const payload = decodeJwtSegment(segments[1]);
+    if (payload === null)
+        return false;
+    const userId = readUntrustedOwnDataProperty(payload, "userId");
+    return typeof userId === "string" && userId.length > 0;
+}
 function buildEnvironmentReadinessProbes(target) {
     const route = target.route === undefined ? "/" : target.route;
     if (route === null)
         return [];
+    // Without a session credential the probe cannot get past the gate. Its
+    // challenge still proves routing resolves and the proxy is serving this
+    // environment — the most this step can establish, and the deployment it
+    // would otherwise fail is already committed and verified. Same allowance the
+    // protected custom-domain probe below already makes.
+    const canAuthenticate = isSessionCredential(target.apiToken);
     const targetUrl = buildEnvironmentProbeUrl(target.url, route);
     if (target.protected && !isMatchingVeryfrontHostedUrl(new URL(targetUrl), target)) {
         return [
@@ -470,15 +515,15 @@ function buildEnvironmentReadinessProbes(target) {
             },
             {
                 url: buildEnvironmentProbeUrl(buildCanonicalEnvironmentUrl(target.projectSlug, target.environmentName), route),
-                authenticate: true,
-                acceptAuthenticationChallenge: false,
+                authenticate: canAuthenticate,
+                acceptAuthenticationChallenge: !canAuthenticate,
             },
         ];
     }
     return [{
             url: target.protected ? secureEnvironmentProbeUrl(targetUrl) : targetUrl,
-            authenticate: target.protected,
-            acceptAuthenticationChallenge: false,
+            authenticate: target.protected && canAuthenticate,
+            acceptAuthenticationChallenge: target.protected && !canAuthenticate,
         }];
 }
 function isVeryfrontSignInUrl(url) {
@@ -499,6 +544,16 @@ function isSignInRedirect(response, requestUrl) {
         return false;
     }
 }
+/** A challenge is a sign-in redirect, a 401, or a 403; say which one arrived. */
+function describeAuthenticationChallenge(probe, status, signInRedirect) {
+    if (probe.authenticate) {
+        return `Could not authenticate the protected environment URL ${probe.url}. Run veryfront login and deploy again.`;
+    }
+    if (signInRedirect) {
+        return `Environment URL ${probe.url} redirected to sign-in. Check its protection settings and deploy again.`;
+    }
+    return `Environment URL ${probe.url} returned HTTP ${status}. Check its protection settings and deploy again.`;
+}
 function isTransientEnvironmentStatus(status) {
     return status === 404 || status === 408 || status === 425 || status === 429 || status >= 500;
 }
@@ -551,18 +606,25 @@ export async function waitForEnvironmentReady(target, options = {}) {
                 if (ready)
                     break;
                 if (authenticationChallenge) {
-                    const message = probe.authenticate
-                        ? `Could not authenticate the protected environment URL ${probe.url}. Run veryfront login and deploy again.`
-                        : `Environment URL ${probe.url} redirected to sign-in. Check its protection settings and deploy again.`;
-                    throw new Error(message);
+                    // A bare Error here reaches the operator as `unknown-error`.
+                    throw DEPLOYMENT_ERROR.create({
+                        detail: describeAuthenticationChallenge(probe, response.status, signInRedirect),
+                        context: { url: probe.url, status: response.status },
+                    });
                 }
                 if (!isTransientEnvironmentStatus(response.status)) {
-                    throw new Error(`Environment URL ${probe.url} returned HTTP ${response.status}. Check the environment configuration and deploy again.`);
+                    throw DEPLOYMENT_ERROR.create({
+                        detail: `Environment URL ${probe.url} returned HTTP ${response.status}. Check the environment configuration and deploy again.`,
+                        context: { url: probe.url, status: response.status },
+                    });
                 }
             }
             const remainingMs = deadline - Date.now();
             if (remainingMs <= 0) {
-                throw new Error(`Environment URL ${probe.url} did not become ready within ${Math.ceil(timeoutMs / 1000)}s (last response: ${lastResponse}). Check the deployment and run deploy again.`);
+                throw DEPLOYMENT_ERROR.create({
+                    detail: `Environment URL ${probe.url} did not become ready within ${Math.ceil(timeoutMs / 1000)}s (last response: ${lastResponse}). Check the deployment and run deploy again.`,
+                    context: { url: probe.url, timeoutMs },
+                });
             }
             await wait(Math.min(pollIntervalMs, remainingMs));
         }

package/esm/cli/shared/update-check.d.ts

@@ -1,12 +1,27 @@
-/**
- * Non-blocking update check
- *
- * Checks for newer CLI versions after command execution.
- * Cached for 24 hours. Never blocks command output.
- *
- * @module cli/shared/update-check
- */
+import { type FileSystem } from "../../src/platform/index.js";
+export declare const UPDATE_REGISTRY_URL = "https://registry.npmjs.org/veryfront/latest";
+export declare const UPDATE_INSTALL_COMMAND = "npm install -g veryfront@latest";
+interface UpdateCacheLocation {
+    directory: string;
+    file: string;
+}
+type UpdateCheckFileSystem = Pick<FileSystem, "readTextFile" | "mkdir" | "writeTextFile">;
+type UpdateCheckFetcher = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+export interface UpdateCheckOptions {
+    shouldSkip?: () => boolean;
+    cacheLocation?: UpdateCacheLocation | null;
+    fileSystem?: UpdateCheckFileSystem;
+    fetcher?: UpdateCheckFetcher;
+    now?: () => number;
+    printNotice?: (current: string, latest: string) => void;
+    debug?: (message: string) => void;
+}
 export declare function compareVersions(current: string, latest: string): boolean;
 export declare function shouldSkip(): boolean;
-export declare function checkForUpdates(currentVersion: string): Promise<void>;
+export declare function getUpdateInstallCommand(context?: {
+    standalone: boolean;
+    executablePath: string;
+}): string;
+export declare function checkForUpdates(currentVersion: string, options?: UpdateCheckOptions): Promise<void>;
+export {};
 //# sourceMappingURL=update-check.d.ts.map

package/esm/cli/shared/update-check.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"update-check.d.ts","sourceRoot":"","sources":["../../../src/cli/shared/update-check.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AA2BH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAQxE;AAED,wBAAgB,UAAU,IAAI,OAAO,CAMpC;AASD,wBAAsB,eAAe,CACnC,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,IAAI,CAAC,CAiDf"}
+{"version":3,"file":"update-check.d.ts","sourceRoot":"","sources":["../../../src/cli/shared/update-check.ts"],"names":[],"mappings":"AAYA,OAAO,EAAoB,KAAK,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAShF,eAAO,MAAM,mBAAmB,gDAAgD,CAAC;AACjF,eAAO,MAAM,sBAAsB,oCAAoC,CAAC;AAUxE,UAAU,mBAAmB;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,KAAK,qBAAqB,GAAG,IAAI,CAAC,UAAU,EAAE,cAAc,GAAG,OAAO,GAAG,eAAe,CAAC,CAAC;AAC1F,KAAK,kBAAkB,GAAG,CACxB,KAAK,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,EAC7B,IAAI,CAAC,EAAE,WAAW,KACf,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEvB,MAAM,WAAW,kBAAkB;IACjC,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC;IAC3B,aAAa,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAC3C,UAAU,CAAC,EAAE,qBAAqB,CAAC;IACnC,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAC7B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACxD,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AAWD,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAQxE;AAED,wBAAgB,UAAU,IAAI,OAAO,CAMpC;AAED,wBAAgB,uBAAuB,CACrC,OAAO,GAAE;IAAE,UAAU,EAAE,OAAO,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAGrD,GACA,MAAM,CAkBR;AA+BD,wBAAsB,eAAe,CACnC,cAAc,EAAE,MAAM,EACtB,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,IAAI,CAAC,CAmDf"}

package/esm/cli/shared/update-check.js

@@ -6,23 +6,29 @@
  *
  * @module cli/shared/update-check
  */
+import * as dntShim from "../../_dnt.shims.js";
 import { getEnv } from "../../src/platform/index.js";
 import { createFileSystem } from "../../src/platform/index.js";
 import { join } from "../../src/platform/compat/path/index.js";
 import { getEnvironmentConfig } from "../../src/config/index.js";
 import { isJsonMode } from "./json-output.js";
 import { brand, dim, warning as warningColor } from "../ui/colors.js";
-import { isQuiet } from "../utils/index.js";
+import { cliLogger, isQuiet } from "../utils/index.js";
 import { detectCI } from "./interactive.js";
 const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
-const REGISTRY_URL = "https://jsr.io/@veryfront/veryfront/meta.json";
-const INSTALL_CMD = "deno install -gArf jsr:@veryfront/veryfront";
-function getCacheFile() {
+export const UPDATE_REGISTRY_URL = "https://registry.npmjs.org/veryfront/latest";
+export const UPDATE_INSTALL_COMMAND = "npm install -g veryfront@latest";
+const HOMEBREW_UPDATE_COMMAND = "brew upgrade veryfront/tap/veryfront";
+const INSTALL_SCRIPT_COMMAND = "curl -fsSL https://veryfront.com/install.sh | sh";
+const STABLE_SEMVER_PATTERN = /^\d+\.\d+\.\d+$/;
+class UpdateCheckFailure extends Error {
+}
+function getCacheLocation() {
     const env = getEnvironmentConfig();
     if (!env.homeDir)
         return null;
-    const cacheDir = join(env.homeDir, ".cache", "veryfront");
-    return join(cacheDir, "update-check.json");
+    const directory = join(env.homeDir, ".cache", "veryfront");
+    return { directory, file: join(directory, "update-check.json") };
 }
 export function compareVersions(current, latest) {
     const c = current.split(".").map(Number);
@@ -46,54 +52,88 @@ export function shouldSkip() {
         return true;
     return false;
 }
+export function getUpdateInstallCommand(context = {
+    standalone: dntShim.Deno.build.standalone ?? false,
+    executablePath: dntShim.Deno.execPath(),
+}) {
+    if (!context.standalone)
+        return UPDATE_INSTALL_COMMAND;
+    const executablePath = context.executablePath.replaceAll("\\", "/").toLowerCase();
+    if (executablePath.includes("/node_modules/veryfront/bin/")) {
+        return UPDATE_INSTALL_COMMAND;
+    }
+    if (executablePath.includes("/cellar/") ||
+        executablePath.includes("/homebrew/") ||
+        executablePath.includes("/linuxbrew/")) {
+        return HOMEBREW_UPDATE_COMMAND;
+    }
+    if (!executablePath.endsWith(".exe"))
+        return INSTALL_SCRIPT_COMMAND;
+    return UPDATE_INSTALL_COMMAND;
+}
 function printUpdateNotice(current, latest) {
     console.error();
     console.error(`  ${warningColor("!")} Update available: ${current} → ${latest}`);
-    console.error(`  ${dim("Run:")} ${brand(INSTALL_CMD)}`);
+    console.error(`  ${dim("Run:")} ${brand(getUpdateInstallCommand())}`);
     console.error();
 }
-export async function checkForUpdates(currentVersion) {
-    if (shouldSkip())
+async function fetchLatestVersion(fetcher) {
+    const response = await fetcher(UPDATE_REGISTRY_URL);
+    if (!response.ok) {
+        await response.body?.cancel();
+        throw new UpdateCheckFailure(`Veryfront could not check for updates: npm registry returned ${response.status}.`);
+    }
+    const data = await response.json();
+    const latestVersion = data && typeof data === "object" && "version" in data
+        ? data.version
+        : undefined;
+    if (typeof latestVersion !== "string" || !STABLE_SEMVER_PATTERN.test(latestVersion)) {
+        throw new UpdateCheckFailure("Veryfront could not check for updates: npm registry returned an invalid version.");
+    }
+    return latestVersion;
+}
+export async function checkForUpdates(currentVersion, options = {}) {
+    if ((options.shouldSkip ?? shouldSkip)())
         return;
-    const cacheFile = getCacheFile();
-    if (!cacheFile)
+    const cacheLocation = options.cacheLocation === undefined
+        ? getCacheLocation()
+        : options.cacheLocation;
+    if (!cacheLocation)
         return;
-    const fs = createFileSystem();
+    const fs = options.fileSystem ?? createFileSystem();
+    const now = options.now ?? Date.now;
+    const notice = options.printNotice ?? printUpdateNotice;
+    const debug = options.debug ?? ((message) => cliLogger.debug(message));
     try {
-        const raw = await fs.readTextFile(cacheFile);
+        const raw = await fs.readTextFile(cacheLocation.file);
         const cache = JSON.parse(raw);
-        if (Date.now() - cache.lastCheck < CHECK_INTERVAL_MS) {
+        if (now() - cache.lastCheck < CHECK_INTERVAL_MS) {
             if (cache.latestVersion &&
                 compareVersions(currentVersion, cache.latestVersion)) {
-                printUpdateNotice(currentVersion, cache.latestVersion);
+                notice(currentVersion, cache.latestVersion);
             }
             return;
         }
     }
     catch {
-        // No cache — proceed
+        // No cache. Continue with the registry check.
     }
     try {
-        const resp = await fetch(REGISTRY_URL);
-        if (!resp.ok) {
-            await resp.body?.cancel();
-            return;
-        }
-        const data = await resp.json();
-        const latestVersion = data.latest;
-        if (!latestVersion)
-            return;
-        const env = getEnvironmentConfig();
-        if (!env.homeDir)
-            return;
-        const cacheDir = join(env.homeDir, ".cache", "veryfront");
-        await fs.mkdir(cacheDir, { recursive: true });
-        await fs.writeTextFile(cacheFile, JSON.stringify({ lastCheck: Date.now(), latestVersion }));
+        const latestVersion = await fetchLatestVersion(options.fetcher ?? fetch);
         if (compareVersions(currentVersion, latestVersion)) {
-            printUpdateNotice(currentVersion, latestVersion);
+            notice(currentVersion, latestVersion);
+        }
+        try {
+            await fs.mkdir(cacheLocation.directory, { recursive: true });
+            await fs.writeTextFile(cacheLocation.file, JSON.stringify({ lastCheck: now(), latestVersion }));
+        }
+        catch {
+            debug("Veryfront could not cache the update check.");
         }
     }
-    catch {
-        // Network error — silently ignore
+    catch (error) {
+        debug(error instanceof UpdateCheckFailure
+            ? error.message
+            : "Veryfront could not complete the update check.");
     }
 }

package/esm/cli/templates/manifest.js

@@ -66,7 +66,7 @@ export default {
                 "globals.css": "@import \"tailwindcss\";\n",
                 "globals.d.ts": "declare module \"*.css\";\n",
                 "public/favicon.svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 64 64\">\n  <rect width=\"64\" height=\"64\" fill=\"#fff\"/>\n  <circle cx=\"32\" cy=\"32\" r=\"20\" fill=\"#000\"/>\n</svg>\n",
-                "README.md": "# Docs Agent\n\nA chatbot that answers questions from your own documents using Retrieval-Augmented Generation (RAG).\n\n## What's included\n\n- Q&A agent with source citation\n- Embedding-based semantic search with convention-based model selection\n- Document upload supporting PDF, DOCX, XLSX, PPTX, CSV, HTML, RTF, EPUB, TXT, and Markdown\n- `ragStore()` with local JSON storage by default, and Veryfront Cloud RAG when bootstrap is present\n- Veryfront Cloud AI Gateway routing for generation and embeddings when bootstrap is present\n- Original uploaded files stored in Veryfront Cloud project uploads when cloud bootstrap is present\n- Sample content in `/content` indexed through a dedicated ingestion route\n\n## Getting started\n\n1. Set your Veryfront Cloud bootstrap vars:\n\n   ```bash\n   export VERYFRONT_API_TOKEN=vf_...\n   export VERYFRONT_PROJECT_SLUG=my-project\n   ```\n\n2. Start the dev server:\n\n   ```bash\n   npx veryfront dev\n   ```\n\n3. Index the sample docs in `content/`:\n\n   ```bash\n   curl -X POST http://localhost:3000/api/ingest\n   ```\n\n4. Open the app and upload a document or ask a question.\n\nIf you are using a self-hosted Veryfront API, also set `VERYFRONT_API_URL`.\n\n## Cloud mode\n\nWith `VERYFRONT_API_TOKEN` and `VERYFRONT_PROJECT_SLUG` set, the template uses\nVeryfront Cloud automatically:\n\n- Agent generation routes through Veryfront Cloud model routing.\n- Query and document embeddings route through Veryfront Cloud embedding routing.\n- `veryfront-cloud/openai/...` and `veryfront-cloud/google/...` models use AI Gateway.\n- RAG documents, chunks, and embeddings are stored in the target project.\n\nThe default cloud embedding model is\n`veryfront-cloud/openai/text-embedding-3-small`. Set\n`VERYFRONT_DEFAULT_EMBEDDING_MODEL` only when you need a different embedding\nmodel.\n\n## Architecture\n\nRAG grounds LLM responses in your documents through three pipelines: **Ingestion**, **Query**, and **RAG**. These pipelines are orchestrated around a shared vector store.\n\n```mermaid\nflowchart LR\n    ChatUI_L[\"Chat UI\"]\n\n    subgraph IngestionFlow[\"Ingestion Pipeline\"]\n        D[\"Documents\"] --> EXT[\"Extraction\"] --> DC[\"Chunking\"] --> DE[\"Document\\nEmbedding\"] --> ING[\"Storage\"]\n    end\n\n    subgraph QueryFlow[\"Query Pipeline\"]\n        Q[\"Query\"] --> QE[\"Query\\nEmbedding\"] --> SS[\"Similarity\\nSearch\"]\n    end\n\n    subgraph RAGFlow[\"RAG Pipeline\"]\n        BF[\"beforeStream\\nHook\"] --> RET[\"Retrieval\"] --> AUG[\"Augmentation\"] --> AG[\"Agent\"] --> GEN[\"Generation\"]\n    end\n\n    EMB((\"Embedding\\nModel\"))\n    GEN_LLM((\"Generative\\nModel\"))\n    VS[(\"Vector\\nStore\")]\n    ChatUI_R[\"Chat UI\"]\n\n    ChatUI_L --> D\n    ChatUI_L --> Q\n\n    QE -.- EMB\n    DE -.- EMB\n\n    SS --> VS\n    ING --> VS\n\n    Q --> BF\n    VS --> RET\n    AG -.- GEN_LLM\n    GEN -.- GEN_LLM\n    GEN --> ChatUI_R\n```\n\n### Pipelines\n\n**Ingestion**: Documents are parsed into plain text via the built-in kreuzberg extraction engine (supporting PDF, DOCX, XLSX, PPTX, HTML, RTF, EPUB, and 76+ formats), split into overlapping chunks (~1000 chars, 200 char overlap), and stored in the default `ragStore()`. In local mode that means `data/index.json`; with Veryfront Cloud bootstrap it upgrades to the cloud RAG backend automatically. The original uploaded binary is also stored in the project's Veryfront Cloud uploads store so remote projects retain the source file, not just the extracted text. Uploaded files are ingested by the upload route. Bundled files in `content/` are ingested by the `/api/ingest` route.\n\n**Query**: The user's query is embedded into the same vector space as the documents, then compared against all stored chunks using cosine similarity to find the top-*k* most relevant results.\n\n**RAG**: The `beforeStream` hook in the AG-UI route intercepts each message before it reaches the agent. It searches the document store for relevant chunks, assembles them into context, and prepends them as retrieved reference data. The agent then generates a cited response streamed back to the user.\n\n## Structure\n\n```\nstore.ts                        RAG store config\nagents/rag.ts                   Q&A agent with citation instructions\ncontent/\n  getting-started.md            Sample document\n  architecture.md               Sample document\napp/\n  api/ag-ui/route.ts             AG-UI endpoint\n  api/ingest/route.ts            Bundled content ingestion\n  api/uploads/route.ts           Upload, list, and delete uploads\n  uploads/page.tsx               Upload management panel\n  page.tsx                       Chat UI\n  layout.tsx                     Chat shell with sidebar and tabs\n```\n\n## Framework usage\n\n| What | Framework | Template code |\n|------|-----------|---------------|\n| Chat UI + streaming | app-mode `Chat` | `page.tsx` |\n| Upload management | `AttachmentsPanel`, `useUploadsRegistry` | `uploads/page.tsx` |\n| Source display | Built into the `Chat` preset | `page.tsx` |\n| Upload API route | `createUploadHandler` | 1 line in `route.ts` |\n| AG-UI route | `createAgUiHandler` | 1 line in `route.ts` |\n| Agent definition | `agent()` | Config object in `agents/rag.ts` |\n| RAG retrieval | `beforeStream` hook | Context injection in `api/ag-ui/route.ts` |\n| Vector store | `ragStore()` | Config in `store.ts` |\n\n## Adding documents\n\n- Drop files into `content/`, then run `curl -X POST http://localhost:3000/api/ingest`\n- Or use the upload panel in the UI for PDF, DOCX, XLSX, PPTX, CSV, HTML, RTF, EPUB, TXT, and MD files\n\n## Production notes\n\nThis is a starter template, not a production-ready setup. For production, consider:\n\n- **Vector store**: Replace the default store with pgvector, Pinecone, or Qdrant for datasets beyond ~10k chunks\n- **Reranking**: Add a cross-encoder reranker (e.g. Cohere Rerank) after retrieval to improve precision\n- **Hybrid search**: Combine dense vectors with BM25 keyword matching for better recall\n",
+                "README.md": "# Docs Agent\n\nA chatbot that answers questions from your own documents using Retrieval-Augmented Generation (RAG).\n\n## What's included\n\n- Q&A agent with source citation\n- Embedding-based semantic search with convention-based model selection\n- Document upload supporting PDF, DOCX, XLSX, PPTX, CSV, HTML, RTF, EPUB, TXT, and Markdown\n- `ragStore()` with local JSON storage by default, and Veryfront Cloud RAG when bootstrap is present\n- Veryfront Cloud AI Gateway routing for generation and embeddings when bootstrap is present\n- Original uploaded files stored in Veryfront Cloud project uploads when cloud bootstrap is present\n- Sample content in `/content` indexed through a dedicated ingestion route\n\n## Getting started\n\n1. Set your Veryfront Cloud bootstrap vars:\n\n   ```bash\n   export VERYFRONT_API_TOKEN=vf_...\n   export VERYFRONT_PROJECT_SLUG=my-project\n   ```\n\n2. Start the dev server:\n\n   ```bash\n   npx veryfront@latest dev\n   ```\n\n3. Index the sample docs in `content/`:\n\n   ```bash\n   curl -X POST http://localhost:3000/api/ingest\n   ```\n\n4. Open the app and upload a document or ask a question.\n\nIf you are using a self-hosted Veryfront API, also set `VERYFRONT_API_URL`.\n\n## Cloud mode\n\nWith `VERYFRONT_API_TOKEN` and `VERYFRONT_PROJECT_SLUG` set, the template uses\nVeryfront Cloud automatically:\n\n- Agent generation routes through Veryfront Cloud model routing.\n- Query and document embeddings route through Veryfront Cloud embedding routing.\n- `veryfront-cloud/openai/...` and `veryfront-cloud/google/...` models use AI Gateway.\n- RAG documents, chunks, and embeddings are stored in the target project.\n\nThe default cloud embedding model is\n`veryfront-cloud/openai/text-embedding-3-small`. Set\n`VERYFRONT_DEFAULT_EMBEDDING_MODEL` only when you need a different embedding\nmodel.\n\n## Architecture\n\nRAG grounds LLM responses in your documents through three pipelines: **Ingestion**, **Query**, and **RAG**. These pipelines are orchestrated around a shared vector store.\n\n```mermaid\nflowchart LR\n    ChatUI_L[\"Chat UI\"]\n\n    subgraph IngestionFlow[\"Ingestion Pipeline\"]\n        D[\"Documents\"] --> EXT[\"Extraction\"] --> DC[\"Chunking\"] --> DE[\"Document\\nEmbedding\"] --> ING[\"Storage\"]\n    end\n\n    subgraph QueryFlow[\"Query Pipeline\"]\n        Q[\"Query\"] --> QE[\"Query\\nEmbedding\"] --> SS[\"Similarity\\nSearch\"]\n    end\n\n    subgraph RAGFlow[\"RAG Pipeline\"]\n        BF[\"beforeStream\\nHook\"] --> RET[\"Retrieval\"] --> AUG[\"Augmentation\"] --> AG[\"Agent\"] --> GEN[\"Generation\"]\n    end\n\n    EMB((\"Embedding\\nModel\"))\n    GEN_LLM((\"Generative\\nModel\"))\n    VS[(\"Vector\\nStore\")]\n    ChatUI_R[\"Chat UI\"]\n\n    ChatUI_L --> D\n    ChatUI_L --> Q\n\n    QE -.- EMB\n    DE -.- EMB\n\n    SS --> VS\n    ING --> VS\n\n    Q --> BF\n    VS --> RET\n    AG -.- GEN_LLM\n    GEN -.- GEN_LLM\n    GEN --> ChatUI_R\n```\n\n### Pipelines\n\n**Ingestion**: Documents are parsed into plain text via the built-in kreuzberg extraction engine (supporting PDF, DOCX, XLSX, PPTX, HTML, RTF, EPUB, and 76+ formats), split into overlapping chunks (~1000 chars, 200 char overlap), and stored in the default `ragStore()`. In local mode that means `data/index.json`; with Veryfront Cloud bootstrap it upgrades to the cloud RAG backend automatically. The original uploaded binary is also stored in the project's Veryfront Cloud uploads store so remote projects retain the source file, not just the extracted text. Uploaded files are ingested by the upload route. Bundled files in `content/` are ingested by the `/api/ingest` route.\n\n**Query**: The user's query is embedded into the same vector space as the documents, then compared against all stored chunks using cosine similarity to find the top-*k* most relevant results.\n\n**RAG**: The `beforeStream` hook in the AG-UI route intercepts each message before it reaches the agent. It searches the document store for relevant chunks, assembles them into context, and prepends them as retrieved reference data. The agent then generates a cited response streamed back to the user.\n\n## Structure\n\n```\nstore.ts                        RAG store config\nagents/rag.ts                   Q&A agent with citation instructions\ncontent/\n  getting-started.md            Sample document\n  architecture.md               Sample document\napp/\n  api/ag-ui/route.ts             AG-UI endpoint\n  api/ingest/route.ts            Bundled content ingestion\n  api/uploads/route.ts           Upload, list, and delete uploads\n  uploads/page.tsx               Upload management panel\n  page.tsx                       Chat UI\n  layout.tsx                     Chat shell with sidebar and tabs\n```\n\n## Framework usage\n\n| What | Framework | Template code |\n|------|-----------|---------------|\n| Chat UI + streaming | app-mode `Chat` | `page.tsx` |\n| Upload management | `AttachmentsPanel`, `useUploadsRegistry` | `uploads/page.tsx` |\n| Source display | Built into the `Chat` preset | `page.tsx` |\n| Upload API route | `createUploadHandler` | 1 line in `route.ts` |\n| AG-UI route | `createAgUiHandler` | 1 line in `route.ts` |\n| Agent definition | `agent()` | Config object in `agents/rag.ts` |\n| RAG retrieval | `beforeStream` hook | Context injection in `api/ag-ui/route.ts` |\n| Vector store | `ragStore()` | Config in `store.ts` |\n\n## Adding documents\n\n- Drop files into `content/`, then run `curl -X POST http://localhost:3000/api/ingest`\n- Or use the upload panel in the UI for PDF, DOCX, XLSX, PPTX, CSV, HTML, RTF, EPUB, TXT, and MD files\n\n## Production notes\n\nThis is a starter template, not a production-ready setup. For production, consider:\n\n- **Vector store**: Replace the default store with pgvector, Pinecone, or Qdrant for datasets beyond ~10k chunks\n- **Reranking**: Add a cross-encoder reranker (e.g. Cohere Rerank) after retrieval to improve precision\n- **Hybrid search**: Combine dense vectors with BM25 keyword matching for better recall\n",
                 "store.ts": "import { ragStore } from \"veryfront/embedding\";\n\nexport const store = ragStore({\n  storagePath: \"data/index.json\",\n  contentDir: \"content\",\n});\n",
                 "tsconfig.json": "{\n  \"compilerOptions\": {\n    \"target\": \"ES2022\",\n    \"module\": \"ESNext\",\n    \"moduleResolution\": \"bundler\",\n    \"strict\": true,\n    \"jsx\": \"react-jsx\",\n    \"skipLibCheck\": true,\n    \"esModuleInterop\": true,\n    \"noEmit\": true,\n    \"allowImportingTsExtensions\": true,\n    \"paths\": {\n      \"@/*\": [\"./*\"],\n      \"react-markdown@*\": [\"./node_modules/react-markdown\"],\n      \"remark-gfm@*\": [\"./node_modules/remark-gfm\"]\n    }\n  },\n  \"include\": [\"**/*.ts\", \"**/*.tsx\"],\n  \"exclude\": [\"node_modules\"]\n}\n"
             }

package/esm/deno.d.ts

@@ -387,6 +387,7 @@ declare namespace _default {
         build: string;
         "build:proxy-lock": string;
         "build:npm": string;
+        "verify:dist": string;
         release: string;
         test: string;
         "test:unit": string;

package/esm/deno.js

@@ -1,6 +1,6 @@
 export default {
     "name": "veryfront",
-    "version": "0.1.1224",
+    "version": "0.1.1226",
     "license": "Apache-2.0",
     "nodeModulesDir": "auto",
     "minimumDependencyAge": {
@@ -463,6 +463,7 @@ export default {
         "build": "deno task build:prepare && deno run -A scripts/build/compile-binary.ts --output ./bin/veryfront",
         "build:proxy-lock": "deno cache --node-modules-dir=none --lock scripts/build/proxy-deno.lock cli/proxy-main.ts",
         "build:npm": "deno run -A scripts/build/generate-integrations-module.ts && deno task generate && deno run --config=scripts/test.deno.json --frozen -A scripts/build/build-npm-dnt.ts",
+        "verify:dist": "deno task build && deno task build:npm",
         "release": "deno run -A scripts/release.ts",
         "test": "deno task generate && DENO_TESTING=1 VF_DISABLE_LRU_INTERVAL=1 SSR_TRANSFORM_PER_PROJECT_LIMIT=0 REVALIDATION_PER_PROJECT_LIMIT=0 NODE_ENV=production LOG_FORMAT=text deno test --preload=src/testing/preload.ts --no-check --parallel --allow-all '--ignore=tests/e2e,tests/integration/compiled-binary-e2e.test.ts,scripts' --unstable-worker-options --unstable-net",
         "test:unit": "deno task generate && DENO_TESTING=1 VF_DISABLE_LRU_INTERVAL=1 SSR_TRANSFORM_PER_PROJECT_LIMIT=0 REVALIDATION_PER_PROJECT_LIMIT=0 NODE_ENV=production LOG_FORMAT=text deno test --preload=src/testing/preload.ts --no-check --parallel --allow-all --v8-flags=--max-old-space-size=8192 '--ignore=tests,src/workflow/__tests__' --unstable-worker-options --unstable-net $(find src cli -name '*.test.ts*' ! -name '*.integration.test.ts*')",

package/esm/extensions/ext-llm-openai/src/openai-tool-input.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"openai-tool-input.d.ts","sourceRoot":"","sources":["../../../../src/extensions/ext-llm-openai/src/openai-tool-input.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,qCAAqC,UAAY,CAAC;AAC/D,eAAO,MAAM,yCAAyC,OAAQ,CAAC;AAE/D,MAAM,MAAM,8BAA8B,GAAG;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAIF,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,8BAA8B,EACtC,MAAM,EAAE,MAAM,EAAE,EAChB,QAAQ,EAAE,MAAM,GACf,OAAO,GAAG,WAAW,GAAG,SAAS,CAgBnC;AAED,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAE/E;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAOvD"}
+{"version":3,"file":"openai-tool-input.d.ts","sourceRoot":"","sources":["../../../../src/extensions/ext-llm-openai/src/openai-tool-input.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,qCAAqC,UAAY,CAAC;AAC/D,eAAO,MAAM,yCAAyC,OAAQ,CAAC;AAE/D,MAAM,MAAM,8BAA8B,GAAG;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAIF,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,8BAA8B,EACtC,MAAM,EAAE,MAAM,EAAE,EAChB,QAAQ,EAAE,MAAM,GACf,OAAO,GAAG,WAAW,GAAG,SAAS,CA+BnC;AAED,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAE/E;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAOvD"}

package/esm/extensions/ext-llm-openai/src/openai-tool-input.js

@@ -2,18 +2,32 @@ export const MAX_OPENAI_STREAM_TOOL_ARGUMENT_BYTES = 1_048_576;
 export const MAX_OPENAI_STREAM_TOOL_ARGUMENT_FRAGMENTS = 4_096;
 const TOOL_ARGUMENT_ENCODER = new TextEncoder();
 export function appendOpenAIStreamToolArgument(budget, chunks, fragment) {
-    if (budget.fragments >= MAX_OPENAI_STREAM_TOOL_ARGUMENT_FRAGMENTS) {
-        return "fragments";
-    }
     const fragmentBytes = TOOL_ARGUMENT_ENCODER.encode(fragment).byteLength;
+    // Zero-byte fragments never advance the byte budget, so they are the only
+    // ones that can arrive without bound -- and they are what the fragment cap
+    // exists to stop. Both provider streams exercise it exactly that way, by
+    // flooding empty deltas.
+    //
+    // Counting non-empty fragments here too made the cap bind long before the
+    // byte budget: at typical delta sizes, 4096 fragments is roughly 2-8% of the
+    // 1 MiB a tool call is nominally allowed, which left the byte limit
+    // unreachable. Fragment count is chosen by the provider's tokenizer rather
+    // than by the caller, so the same tool call passed or failed depending on how
+    // the stream happened to be chunked.
+    if (fragmentBytes === 0) {
+        if (budget.fragments >= MAX_OPENAI_STREAM_TOOL_ARGUMENT_FRAGMENTS) {
+            return "fragments";
+        }
+        budget.fragments++;
+        return undefined;
+    }
     if (fragmentBytes > MAX_OPENAI_STREAM_TOOL_ARGUMENT_BYTES - budget.bytes) {
         return "bytes";
     }
-    budget.fragments++;
+    // Content is bounded by bytes: every fragment kept here is at least one byte,
+    // so the array cannot outgrow the byte budget.
     budget.bytes += fragmentBytes;
-    if (fragment.length > 0) {
-        chunks.push(fragment);
-    }
+    chunks.push(fragment);
     return undefined;
 }
 export function joinOpenAIStreamToolArguments(chunks) {

package/esm/src/agent/runtime/index.d.ts.map

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

package/esm/src/agent/runtime/index.js

@@ -38,6 +38,7 @@ import { runWithRemoteIntegrationToolDiscoveryScope } from "../../integrations/r
 import { prepareAgentRuntimeStep, withIntegrationToolDiscoveryStatus, } from "./agent-runtime-step.js";
 import { buildStreamedAssistantMessage } from "./streamed-assistant-message.js";
 import { flattenSystemInstructions, hasRuntimeToolInventory, withRuntimeToolInventory, } from "./tool-inventory.js";
+import { captureAgentRunRuntimeContext, withAgentRunRuntimeContext, withAgentRunRuntimeContextMetadata, } from "./run-runtime-context.js";
 // Re-export from submodules
 export { closeSSEStream, generateMessageId, sendSSE } from "./sse-utils.js";
 export { RunAlreadyExistsError, RunCancelledError, RunNotActiveError, RunResumeSessionManager, WaitConflictError, WaitNotPendingError, } from "./resume-session.js";
@@ -488,6 +489,7 @@ export class AgentRuntime {
      */
     async generate(input, context, modelOverride, maxOutputTokensOverride, abortSignal, options) {
         throwIfAborted(abortSignal);
+        const runRuntimeContext = captureAgentRunRuntimeContext();
         const transport = await this.resolveModelTransport(context, modelOverride, "generate");
         const requestedModel = transport.requestedModel;
         const resolvedModelString = transport.resolvedModelString;
@@ -497,6 +499,8 @@ export class AgentRuntime {
             setSpanAttributes(span, {
                 "agent.id": this.id,
                 "agent.model": resolvedModelString,
+                "run.started_at_utc": runRuntimeContext.runStartedAtUtc,
+                "run.current_date_utc": runRuntimeContext.currentDateUtc,
             });
             const inputMessages = normalizeInput(input);
             const messages = await this.prepareTurnMessages(inputMessages);
@@ -512,7 +516,7 @@ export class AgentRuntime {
             return chain.execute(agentContext, () => runWithRemoteIntegrationToolDiscoveryScope(() => this.executeAgentLoop(systemPrompt, messages, {
                 agentId: this.id,
                 projectId: tryGetCacheKeyContext()?.projectId,
-            }, context, supportsToolCalling, resolvedModelString, transport.languageModel, transport.headers, transport.providerOptions, transport.reasoning, maxOutputTokensOverride, requestedModel, this.createGenerateReplacementTools(options?.toolReplacements, options?.retainSkillLoaderTools), abortSignal)));
+            }, context, runRuntimeContext, supportsToolCalling, resolvedModelString, transport.languageModel, transport.headers, transport.providerOptions, transport.reasoning, maxOutputTokensOverride, requestedModel, this.createGenerateReplacementTools(options?.toolReplacements, options?.retainSkillLoaderTools), abortSignal)));
         });
     }
     /**
@@ -520,6 +524,11 @@ export class AgentRuntime {
      * Returns a ReadableStream in the veryfront stream event format.
      */
     async stream(messages, context, callbacks, modelOverride, maxOutputTokensOverride, abortSignal) {
+        const runRuntimeContext = captureAgentRunRuntimeContext();
+        setOtelActiveSpanAttributes({
+            "run.started_at_utc": runRuntimeContext.runStartedAtUtc,
+            "run.current_date_utc": runRuntimeContext.currentDateUtc,
+        });
         const transport = await this.resolveModelTransport(context, modelOverride, "stream");
         const requestedModel = transport.requestedModel;
         const resolvedModelString = transport.resolvedModelString;
@@ -593,7 +602,11 @@ export class AgentRuntime {
                             model: resolvedModelString,
                         },
                     });
-                    inFlight = chain.execute(agentContext, () => runWithRemoteIntegrationToolDiscoveryScope(() => this.executeAgentLoopStreaming(systemPrompt, memoryMessages, controller, encoder, callbacks, textPartId, toolContext, context, supportsToolCalling, resolvedModelString, languageModel, transport.headers, transport.providerOptions, transport.reasoning, maxOutputTokensOverride, streamAbortSignal, requestedModel)));
+                    sendSSE(controller, encoder, {
+                        type: "data-veryfront.runtime_context",
+                        data: runRuntimeContext,
+                    });
+                    inFlight = chain.execute(agentContext, () => runWithRemoteIntegrationToolDiscoveryScope(() => this.executeAgentLoopStreaming(systemPrompt, memoryMessages, controller, encoder, callbacks, textPartId, toolContext, context, runRuntimeContext, supportsToolCalling, resolvedModelString, languageModel, transport.headers, transport.providerOptions, transport.reasoning, maxOutputTokensOverride, streamAbortSignal, requestedModel)));
                     const response = await inFlight;
                     throwIfAborted(streamAbortSignal);
                     callbacks?.onFinish?.(response);
@@ -644,7 +657,7 @@ export class AgentRuntime {
     /**
      * Execute agent loop (with tool calling)
      */
-    async executeAgentLoop(systemPrompt, messages, toolContextBase, runtimeContext, supportsToolCalling, modelString, resolvedModel, headers, providerOptions, reasoning, maxOutputTokensOverride, temperatureModelString, toolReplacements, abortSignal) {
+    async executeAgentLoop(systemPrompt, messages, toolContextBase, runtimeContext, runRuntimeContext, supportsToolCalling, modelString, resolvedModel, headers, providerOptions, reasoning, maxOutputTokensOverride, temperatureModelString, toolReplacements, abortSignal) {
         return withSpan("agent.execution_loop", async (loopSpan) => {
             const { maxAgentSteps } = getPlatformCapabilities();
             const maxSteps = this.computeMaxSteps(maxAgentSteps);
@@ -774,9 +787,10 @@ export class AgentRuntime {
                         "model.id": effectiveModel,
                         "messages.count": currentMessages.length,
                     });
+                    const providerSystemPrompt = withAgentRunRuntimeContext(currentSystemPrompt, runRuntimeContext);
                     const result = await generateText({
                         model: languageModel,
-                        system: currentSystemPrompt,
+                        system: providerSystemPrompt,
                         messages: convertToTextGenerationRuntimeRequestMessages(currentMessages),
                         tools: runtimeTools,
                         experimental_repairToolCall: repairToolCall,
@@ -871,7 +885,7 @@ export class AgentRuntime {
                         toolCalls,
                         status: this.status,
                         usage: totalUsage,
-                        metadata: response.finishReason ? { finishReason: response.finishReason } : undefined,
+                        metadata: withAgentRunRuntimeContextMetadata(runRuntimeContext, response.finishReason ? { finishReason: response.finishReason } : undefined),
                     };
                 }
                 this.status = "tool_execution";
@@ -1141,7 +1155,9 @@ export class AgentRuntime {
                 toolCalls,
                 status: this.status,
                 usage: totalUsage,
-                metadata: { warning: `Max steps (${maxSteps}) reached` },
+                metadata: withAgentRunRuntimeContextMetadata(runRuntimeContext, {
+                    warning: `Max steps (${maxSteps}) reached`,
+                }),
             };
         });
     }
@@ -1150,7 +1166,7 @@ export class AgentRuntime {
      * Emits veryfront stream events (message-start/message-finish + step-start/step-end)
      * while consuming model-runtime `streamText()` parts internally.
      */
-    async executeAgentLoopStreaming(systemPrompt, messages, controller, encoder, callbacks, textPartId, toolContextBase, runtimeContext, supportsToolCalling, modelString, resolvedModel, headers, providerOptions, reasoning, maxOutputTokensOverride, abortSignal, temperatureModelString) {
+    async executeAgentLoopStreaming(systemPrompt, messages, controller, encoder, callbacks, textPartId, toolContextBase, runtimeContext, runRuntimeContext, supportsToolCalling, modelString, resolvedModel, headers, providerOptions, reasoning, maxOutputTokensOverride, abortSignal, temperatureModelString) {
         const { maxAgentSteps } = getPlatformCapabilities();
         const maxSteps = this.computeMaxSteps(maxAgentSteps);
         const effectiveModel = resolveRuntimeModel(modelString || this.config.model);
@@ -1247,9 +1263,10 @@ export class AgentRuntime {
             const temperature = this.resolveTemperature(temperatureModelString ?? effectiveModel, providerOptions);
             const maxOutputTokens = this.resolveMaxOutputTokens(effectiveModel, maxOutputTokensOverride);
             const genAiProviderName = resolveRuntimeGenAiProviderName(effectiveModel);
+            const providerSystemPrompt = withAgentRunRuntimeContext(currentSystemPrompt, runRuntimeContext);
             const streamSource = createRuntimeStreamSource((streamSignal) => streamText({
                 model: languageModel,
-                system: currentSystemPrompt,
+                system: providerSystemPrompt,
                 messages: convertToTextGenerationRuntimeRequestMessages(currentMessages),
                 tools: runtimeTools,
                 experimental_repairToolCall: repairToolCall,
@@ -1626,7 +1643,7 @@ export class AgentRuntime {
             toolCalls,
             status: "completed",
             usage: totalUsage,
-            metadata: finalFinishReason ? { finishReason: finalFinishReason } : undefined,
+            metadata: withAgentRunRuntimeContextMetadata(runRuntimeContext, finalFinishReason ? { finishReason: finalFinishReason } : undefined),
         };
     }
     /**