vybekiit 0.7.3 → 0.7.7

package/dist/global-skills/neon-functions/references/ai-sdk.md

@@ -32,6 +32,7 @@ The function's default export is a web-standard `{ fetch }` handler. The `@neon/
 ```typescript
 // src/index.ts
 import { neon } from "@neon/ai-sdk-provider";
+import { attachDatabasePool } from "@neon/functions";
 import { streamText, tool, stepCountIs, type ModelMessage } from "ai";
 import { z } from "zod";
 import { drizzle } from "drizzle-orm/node-postgres";
@@ -39,6 +40,7 @@ import { Pool } from "pg";
 import { todos } from "./db/schema";
 
 const pool = new Pool({ connectionString: process.env.DATABASE_URL, max: 5 });
+attachDatabasePool(pool);
 const db = drizzle(pool);
 
 export default {
@@ -68,7 +70,8 @@ export default {
     });
 
     return result.toUIMessageStreamResponse({
-      onError: (error) => (error instanceof Error ? error.message : String(error)),
+      onError: (error) =>
+        error instanceof Error ? error.message : String(error),
     });
   },
 };
@@ -91,7 +94,8 @@ const files = new Files({ adapter: neonFiles({ bucket: "images" }) });
 
 const result = streamText({
   model: neon("gpt-5-mini"),
-  system: "Use image_generation when the user asks for a picture, then describe it.",
+  system:
+    "Use image_generation when the user asks for a picture, then describe it.",
   messages,
   tools: {
     image_generation: neon.tools.imageGeneration({
@@ -106,7 +110,9 @@ const result = streamText({
       const base64 = imageResultBase64(tr.output);
       if (!base64) continue;
       const key = `generated/${randomUUID()}.jpg`;
-      await files.upload(key, Buffer.from(base64, "base64"), { contentType: "image/jpeg" });
+      await files.upload(key, Buffer.from(base64, "base64"), {
+        contentType: "image/jpeg",
+      });
       // …insert a row keyed by `key` into Postgres; serve later via files.url(key)
     }
   },

package/dist/global-skills/neon-functions/references/mastra-studio.md

@@ -2,7 +2,7 @@
 
 A Neon Function is a long-lived Node.js 24 process, which makes it a natural host for a [Mastra](https://mastra.ai) agent: the agent keeps running for the life of the request, and you point its model at the Neon AI Gateway so there are no extra provider keys. You can keep **running the agent on Neon Functions** while shipping its traces to a **Mastra Studio (Mastra Cloud) project** for observability — the agent runs on Neon, the traces are viewable in Mastra.
 
-The shape mirrors any other Node integration (see `references/sentry.md`): instantiate at module load, gate on env vars so local dev and unconfigured branches stay a no-op, and pass secrets at deploy time via `neon.ts`. `@mastra/core` and `@mastra/observability` bundle cleanly through `neon deploy`'s esbuild with no extra config.
+The shape mirrors any other Node integration (see [sentry.md](sentry.md)): instantiate at module load, gate on env vars so local dev and unconfigured branches stay a no-op, and pass secrets at deploy time via `neon.ts`. `@mastra/core` and `@mastra/observability` bundle cleanly through `neon deploy`'s esbuild with no extra config.
 
 ## 1. Define the agent against the Neon AI Gateway
 

package/dist/global-skills/neon-functions/references/mcp.md

@@ -17,10 +17,11 @@ import { eq } from "drizzle-orm";
 import { z } from "zod";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StreamableHTTPTransport } from "@hono/mcp";
+import { attachDatabasePool } from "@neon/functions";
 import { contacts } from "./db/schema";
 
-// One pool per isolate, reused across requests.
 const pool = new Pool({ connectionString: process.env.DATABASE_URL, max: 5 });
+attachDatabasePool(pool);
 const db = drizzle(pool);
 
 const mcpServer = new McpServer({ name: "contacts", version: "1.0.0" });
@@ -52,8 +53,15 @@ mcpServer.registerTool(
     inputSchema: { id: z.number().int().positive() },
   },
   async ({ id }) => {
-    const [row] = await db.delete(contacts).where(eq(contacts.id, id)).returning();
-    return { content: [{ type: "text", text: JSON.stringify(row ?? { error: "not found" }) }] };
+    const [row] = await db
+      .delete(contacts)
+      .where(eq(contacts.id, id))
+      .returning();
+    return {
+      content: [
+        { type: "text", text: JSON.stringify(row ?? { error: "not found" }) },
+      ],
+    };
   },
 );
 
@@ -124,7 +132,8 @@ Either way it's one check at the top of the `/mcp` route — reject anything tha
 ```typescript
 app.all("/mcp", async (c) => {
   const auth = c.req.header("authorization");
-  if (!(await isValidApiKey(auth))) return c.json({ error: "unauthorized" }, 401); // your check
+  if (!(await isValidApiKey(auth)))
+    return c.json({ error: "unauthorized" }, 401);
   if (!mcpServer.isConnected()) await mcpServer.connect(transport);
   return transport.handleRequest(c);
 });

package/dist/global-skills/neon-functions/references/sentry.md

@@ -1,18 +1,29 @@
-# Integrations and observability
+# Sentry error monitoring on Neon Functions
 
 A Neon Function is a **long-lived Node.js 24 process running a web-standard request/response handler** — not an edge worker or a short-lived lambda. That means any integration SDK that works in an ordinary Node process works here unchanged: you initialize it once at module load, before your handler starts serving requests, and it stays instrumented for the life of the isolate.
 
-This reference walks through wiring up Sentry for error and performance monitoring; the same shape (init module imported first, gated on an env var, secret passed at deploy time) applies to other Node SDKs (OpenTelemetry, logging, analytics).
+This reference walks through wiring up Sentry for errors, logs, and traces — including AI-agent tracing, since agents are the workload Functions are built for. The same shape (init module imported first, gated on an env var, secret passed at deploy time) applies to other Node SDKs — see [Other Node integrations](#other-node-integrations) at the end.
 
-## Sentry (error & performance monitoring)
+## Sentry (errors, logs, and traces)
 
-Because the runtime is a normal Node process, use the Node SDK `@sentry/node` — not an edge/serverless wrapper. It bundles cleanly through `neon deploy`'s esbuild with no extra build config.
+Because the runtime is a normal Node process, use the Node SDK `@sentry/node` — not an edge/serverless wrapper. **Use `@sentry/node` ≥10.67.0**: older versions fail to register their tracer against the OpenTelemetry API global the runtime pre-creates, and every span is silently non-recording while errors and logs keep working. The SDK bundles cleanly through `neon deploy`'s esbuild with no extra build config.
 
-There are three layers worth instrumenting, and errors from all of them flow into a single Sentry project:
+Sentry has distinct signals, and picking the right one is the main instrumentation decision:
 
-1. The HTTP framework (unhandled route errors).
-2. The Node function runtime (uncaught exceptions / unhandled rejections, captured by the SDK).
-3. The application's own caught failures — e.g. an agent that retries and falls back instead of throwing.
+1. **Errors** — unhandled route errors and failures your code can't recover from. Each becomes a grouped, alertable _issue_.
+2. **Logs** — recoverable failures and narrative events (a model attempt failed and the agent moved on, a retry, a fallback). Structured, searchable, linked to the trace — and they don't pollute the issue stream.
+3. **Traces** — the request's span tree: the incoming request, outbound fetches, and (for agents) the full model/tool call hierarchy with token usage.
+
+All three carry the same trace ID, so from an error you can pivot to the logs and spans of the same request.
+
+### Environment variables
+
+| Variable                    | Purpose                                                                                                                        |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `SENTRY_DSN`                | Project DSN; keep it configurable through the deployment environment.                                                          |
+| `SENTRY_RELEASE`            | Optional release identifier such as a commit SHA — unlocks regression detection.                                               |
+| `SENTRY_TRACES_SAMPLE_RATE` | Trace sample rate, default `1`. Agents are low-throughput and every trace is interesting; lower it for high-volume plain HTTP. |
+| `PRODUCTION_BRANCH`         | Your default branch's name, so it reports as environment `production` (see below).                                             |
 
 ### 1. Initialize before anything else
 
@@ -25,16 +36,25 @@ import * as Sentry from "@sentry/node";
 Sentry.init({
   dsn: process.env.SENTRY_DSN,
   enabled: Boolean(process.env.SENTRY_DSN),
-  tracesSampleRate: 1.0,
-  // NEON_BRANCH (the branch name) is injected on EVERY branch, including the default — so it
-  // can't be used as a truthy "is this a branch?" flag. Treat the project's default branch as
-  // "production" (its name passed in via neon.ts env) and tag every other branch by its name.
+  enableLogs: true,
+  tracesSampleRate: Number(process.env.SENTRY_TRACES_SAMPLE_RATE ?? 1),
+  traceLifecycle: "stream",
+  streamGenAiSpans: true,
+  integrations: [
+    Sentry.vercelAIIntegration({ force: true }),
+    Sentry.httpIntegration({ disableIncomingRequestSpans: true }),
+  ],
+  release: process.env.SENTRY_RELEASE,
   environment:
-    process.env.NEON_BRANCH && process.env.NEON_BRANCH !== process.env.PRODUCTION_BRANCH
+    process.env.NEON_BRANCH &&
+    process.env.NEON_BRANCH !== process.env.PRODUCTION_BRANCH
       ? process.env.NEON_BRANCH
       : "production",
 });
 
+process.on("SIGTERM", () => void Sentry.flush(2000));
+process.on("SIGINT", () => void Sentry.flush(2000));
+
 export { Sentry };
 ```
 
@@ -42,37 +62,66 @@ export { Sentry };
 // src/index.ts
 import "./instrument"; // MUST be the first import, before the framework/agent
 import { Sentry } from "./instrument";
+import { attachDatabasePool } from "@neon/functions";
 import { Hono } from "hono";
+import { Pool } from "pg";
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL, max: 5 });
+attachDatabasePool(pool, {
+  onUnexpectedError: (err) => Sentry.captureException(err),
+});
+
 // ... rest of the function
 ```
 
 - **Gate `enabled` on the DSN.** Local dev (`neon dev`) and any branch where you haven't configured the secret then become a no-op — no init, no noise — without changing code.
-- **Tag the environment off the injected branch name.** Each Neon branch runs its own copy of the function and the runtime injects `NEON_BRANCH` (the branch **name**, e.g. `main` or `preview/add-auth`) into every one of them — including the default branch. The same value is written into local dev by `neon env pull` / `neon-env run` / `neon dev`, so local and deployed runs agree. Because it's always present, don't use it as a boolean flag (that tags every branch the same). Instead compare it against your default branch name (pass it in as e.g. `PRODUCTION_BRANCH` via `neon.ts` `env`) so the default branch reads as `production` and feature/preview branches are tagged by name — keeping them separable in the Sentry dashboard.
+- **`enableLogs: true`** — the `Sentry.logger.*` API is off by default.
+- **`traceLifecycle: "stream"`** — sends each span as it finishes instead of holding the whole tree until the request ends, so spans that complete after the response (streaming agent calls) aren't lost. `streamGenAiSpans: true` is the default on current SDKs (sends gen_ai spans as standalone items so large prompts aren't truncated); set it to `false` on self-hosted Sentry.
+- **The two integrations:** `vercelAIIntegration({ force: true })` because `neon deploy` bundles your code, which defeats the integration's module detection; `httpIntegration({ disableIncomingRequestSpans: true })` because the request root span comes from the middleware in step 3 (the runtime's internal server would otherwise add a duplicate with an unhelpful name).
+- **Environment:** `NEON_BRANCH` is injected on every branch — including the default — and holds the branch **name** (e.g. `main`, `preview/add-auth`). Because it's always present, don't use it as a boolean flag; compare it against your default branch's name (passed in as `PRODUCTION_BRANCH`) so the default branch reads as `production` and other branches tag by name. Pass `SENTRY_ENVIRONMENT` explicitly per deploy to override.
+- **Flush on shutdown:** the runtime sends `SIGTERM`/`SIGINT` before evicting an idle isolate; Sentry buffers logs and batches spans, so flush or the tail gets dropped.
+- **Idle `pg` pool errors:** call `attachDatabasePool(pool)` (or pass `onUnexpectedError: (err) => Sentry.captureException(err)` on the first call). Don't `pool.end()` on SIGINT — Neon's pooler reclaims those connections. See [Connecting to Postgres](../SKILL.md#connecting-to-postgres).
 
 ### 2. Provide the DSN as a deploy-time secret
 
-The DSN is your own secret, so set it per-deployment (see "Environment variables" in `SKILL.md`). Either pass it on deploy:
+The DSN is your own secret, so set it per-deployment (see [Environment Variables](../SKILL.md#environment-variables)). Either pass it on deploy:
 
 ```bash
 neon functions deploy <slug> --src src/index.ts \
-  --env "SENTRY_DSN=https://…@…ingest.us.sentry.io/…"
+  --env "SENTRY_DSN=https://…@…ingest.us.sentry.io/…" \
+  --env "SENTRY_RELEASE=$(git rev-parse --short HEAD)" \
+  --env "SENTRY_TRACES_SAMPLE_RATE=1"
 ```
 
-or declare it under the function's `env` in `neon.ts` (read from `process.env` to avoid hardcoding):
+or declare it under the function's `env` in `neon.ts` (read from `process.env` to avoid hardcoding). Deploy env vars **persist and accumulate across deployments** — omitting `--env` on a later deploy does not clear a variable set earlier.
+
+### 3. Create the request span and catch route errors
+
+The runtime invokes your handler through its own ingress rather than a plain `node:http` server, so give each request an isolation scope and a root span yourself — one Hono middleware covers it, and everything else (gen_ai spans, logs, outbound fetches) nests under it with clean route names. The `flush` at the end matters: an idle isolate can be suspended, so buffered telemetry has to ship while the request is alive.
 
 ```typescript
-functions: {
-  <slug>: {
-    name: "…",
-    source: "src/index.ts",
-    env: { SENTRY_DSN: process.env.SENTRY_DSN! },
-  },
-}
+app.use("*", (c, next) =>
+  Sentry.withIsolationScope(() =>
+    Sentry.startSpan(
+      {
+        op: "http.server",
+        name: `${c.req.method} ${c.req.path}`,
+        forceTransaction: true,
+        attributes: {
+          "http.request.method": c.req.method,
+          "url.path": c.req.path,
+        },
+      },
+      async (span) => {
+        await next();
+        span.setAttribute("http.response.status_code", c.res.status);
+      },
+    ).finally(() => Sentry.flush(2000)),
+  ),
+);
 ```
 
-### 3. Catch unhandled route errors
-
-Wire a top-level error handler in your HTTP framework so any error thrown in a route is reported. With Hono, `onError` covers this. Watch out for one gotcha: framework middleware such as `cors()` usually does **not** decorate error responses, so re-add any headers you need on the 500 yourself.
+Then wire a top-level error handler so any error thrown in a route is reported. With Hono, `onError` covers this. Watch out for one gotcha: framework middleware such as `cors()` usually does **not** decorate error responses, so re-add any headers you need on the 500 yourself.
 
 ```typescript
 app.onError((err, c) => {
@@ -82,50 +131,114 @@ app.onError((err, c) => {
 });
 ```
 
-### 4. Report agent (and other swallowed) failures explicitly
+(There is a dedicated `@sentry/hono` package, but it is alpha and its Node entry point assumes the app is served by `@hono/node-server`, which is not how Functions run Hono — stick with `onError`.)
 
-Long-running agent workloads — the case Neon Functions are built for — typically **catch their own errors and fall back** (retry a different model, return a degraded result) rather than throwing. Those failures never reach the route error handler, so report them explicitly with the same `Sentry` instance, and tag them so you can filter and group in the dashboard.
+### 4. Errors are for failures; logs are for the story
 
-A representative agent that parses a page across several models reports three distinct cases:
+Long-running agent workloads — the case Neon Functions are built for — typically **catch their own errors and fall back** (retry a different model, return a degraded result) rather than throwing. It's tempting to `captureException` those too, but every recovered retry then opens a warning-level issue: the issue stream fills with things nobody needs to act on, and the terminal failures drown in them.
+
+Split by whether someone needs to act:
+
+- **`Sentry.captureException` — terminal, needs attention.** The agent exhausted every fallback; an invariant broke. These become issues, group, and alert.
+- **`Sentry.logger.*` — recoverable or narrative.** A model attempt failed and the agent moved on; an input couldn't be fetched; a milestone was reached. Structured log records, searchable by attribute and attached to the request's trace — the story you read _after_ an issue fires.
+
+A representative agent that tries several models in order:
 
 ```typescript
-// Recoverable: one model attempt failed, the agent will try the next model.
-Sentry.captureException(err, {
-  level: "warning",
-  tags: { component: "agent", phase: "parse-attempt", model },
-  extra: { url, source },
+for (const model of models) {
+  try {
+    const { text: summary } = await generateText({
+      model: neon(model),
+      prompt,
+      experimental_telemetry: { isEnabled: true },
+    });
+    Sentry.logger.info("summary produced", { component: "agent", model });
+    return c.json({ summary, model });
+  } catch (err) {
+    lastError = err;
+    Sentry.logger.warn("model attempt failed", {
+      component: "agent",
+      phase: "summarize-attempt",
+      model,
+      error: String(err),
+    });
+  }
+}
+
+Sentry.captureException(lastError, {
+  tags: { component: "agent", phase: "summarize-all-failed" },
+  contexts: { agent: { attempts: models.length } },
 });
+return c.json({ error: "all models failed" }, 502);
+```
+
+- Log **attributes** (the second argument — flat `string | number | boolean` values) are individually searchable and filterable in Sentry's Logs view.
+- On the remaining `captureException` calls, use `tags` for the dimensions you'll filter and group by, and `contexts` for structured per-event detail (`contexts` replaces the legacy `extra`).
+- Logs emitted during a request automatically link to its trace, so from the terminal error you can pull up every preceding attempt.
+
+### 5. Trace the agent itself
 
-// Terminal: every model failed.
-Sentry.captureException(err, {
-  level: "error",
-  tags: { component: "agent", phase: "parse-all-failed" },
-  extra: { url, source },
+If the function runs a [Vercel AI SDK](https://ai-sdk.dev) agent (see [references/ai-sdk.md](ai-sdk.md)), Sentry captures the full agent → model → tool span hierarchy with token usage per call — `gen_ai.invoke_agent`, `gen_ai.generate_content`, `gen_ai.execute_tool` spans in the request's trace, plus the **Insights → AI Agents** dashboard. On top of the init config from step 1:
+
+**Opt each call in** — the AI SDK only emits spans when asked — and **report stream errors**, because `streamText` never throws: failures surface as error parts inside the stream and the HTTP response just ends, so without `onError` a dead agent looks like an empty reply.
+
+```typescript
+const result = streamText({
+  model: neon(MODEL),
+  messages,
+  tools,
+  experimental_telemetry: { isEnabled: true },
+  onError: ({ error }) => {
+    Sentry.captureException(error, {
+      tags: { component: "agent", phase: "chat-stream" },
+    });
+  },
 });
+```
+
+**Flush when the stream completes.** The middleware's flush runs when the `Response` object is created — before the model finishes — and the gen_ai spans only end with the stream. Ship them from the stream's own finalizer, while the request is still alive:
 
-// Non-exception failure: the agent couldn't fetch the input page at all.
-Sentry.captureMessage("agent could not fetch page", {
-  level: "warning",
-  tags: { component: "agent", phase: "fetch" },
-  extra: { url, source },
+```typescript
+const stream = result.textStream
+  .pipeThrough(
+    new TransformStream<string, string>({
+      async flush() {
+        await new Promise((r) => setTimeout(r, 0));
+        await Sentry.flush(2000);
+      },
+    }),
+  )
+  .pipeThrough(new TextEncoderStream());
+return new Response(stream, {
+  headers: { "content-type": "text/plain; charset=utf-8" },
 });
 ```
 
-- Use `level` to separate recoverable (`warning`) from terminal (`error`) failures.
-- Use `tags` for the dimensions you'll filter/group by — `component`, `phase`, `model`.
-- Use `extra` for per-event context — the URL being processed, the content source.
+(Once the runtime's `waitUntil` is no longer a preview stub, `waitUntil(Sentry.flush(2000))` is the cleaner way to express this.)
+
+With telemetry enabled the AI SDK records prompts and outputs by default — set `recordInputs: false` / `recordOutputs: false` on the same `experimental_telemetry` object if conversation content must not leave the application. Optionally, group multi-turn chats into a timeline (**Explore → Conversations**) and attribute them to users — set both once per request before the model call:
+
+```typescript
+Sentry.setConversationId(chatId);
+Sentry.setUser({ id: userId });
+```
+
+Direct provider SDKs (`openai`, `@anthropic-ai/sdk`, `@langchain/*`, `@google/genai`) have equivalent Sentry auto-instrumentation, but it patches those modules at import time — which bundling defeats. The Vercel AI SDK path is bundle-safe (the `ai` package emits its own OTel spans), which is why it's the recommended route here. The same caveat applies to other module-patching instrumentation (`pg` spans, for example): if a specific library's spans are missing from a deployed function, bundling is the first thing to check.
 
 ### Verifying the wiring
 
-- Temporarily add a route that throws (`app.get("/debug-sentry", () => { throw new Error("sentry test"); })`), hit it, confirm the 500 surfaces in Sentry, then remove the route.
-- Trigger a real downstream failure (e.g. point a fetch at `https://httpstat.us/500`) to confirm the explicit agent-level captures fire.
+- **Errors:** temporarily add a route that throws (`app.get("/debug-sentry", () => { throw new Error("sentry test"); })`), hit it, confirm the 500 surfaces as an issue in Sentry, then remove the route.
+- **Logs:** trigger a recoverable failure (e.g. pass a bogus model name to the fallback path) and confirm the `Sentry.logger` records show up in **Explore → Logs**, linked to the same trace.
+- **Traces:** hit a real route and confirm a trace appears (**Explore → Traces**) with the spans you expect — the request root, outbound fetches, and (for agents) `gen_ai.*` spans with token counts. Two things to know before declaring it broken:
+  - **Streamed span ingestion lags several minutes behind errors and logs.** An error visible in seconds does not mean its trace is lost — check again after a few minutes.
+  - If spans **never** appear while errors and logs flow, check the SDK version — `@sentry/node` <10.67.0 cannot register its tracer against the runtime's pre-created OpenTelemetry API global. Upgrade, or on an older SDK run `delete globalThis[Symbol.for("opentelemetry.js.api.1")]` before `Sentry.init`.
 
 ## Other Node integrations
 
-The same pattern generalizes to any Node integration (OpenTelemetry, structured logging, product analytics):
+The same pattern generalizes to any Node integration (structured logging, analytics):
 
 1. Initialize once at module scope in a dedicated init module, imported before your handler.
 2. Gate it on an env var so local dev and unconfigured branches are a no-op.
 3. Pass secrets via `--env KEY=VALUE` on deploy or the function's `env` in `neon.ts`.
 
-Standard Node SDKs bundle through `neon deploy`'s esbuild without changes.
+Standard Node SDKs bundle through `neon deploy`'s esbuild without changes — but module-patching auto-instrumentation does not, and anything that registers OpenTelemetry globals contends with the runtime's own registration (see the version note at the top).

package/dist/global-skills/neon-functions/references/sse.md

@@ -1,6 +1,6 @@
 # Server-sent events (SSE) on Neon Functions
 
-SSE is the one-way (server → client) streaming counterpart to WebSockets: the browser opens a long-lived `GET` with [`EventSource`](https://developer.mozilla.org/en-US/docs/Web/API/EventSource) and the server pushes text frames down it. On Neon Functions there's **no adapter or extra library to install** — unlike the [Hono WebSocket helper](hono-websockets.md), an SSE endpoint is just a normal `fetch` handler that returns a `Response` whose body is a `ReadableStream` with `Content-Type: text/event-stream`. The runtime holds the response open as long as bytes keep flowing (15-minute heartbeat, see [Timeouts](../SKILL.md#timeouts-and-runtime-limits)).
+SSE is the one-way (server → client) streaming counterpart to WebSockets: the browser opens a long-lived `GET` with [`EventSource`](https://developer.mozilla.org/en-US/docs/Web/API/EventSource) and the server pushes text frames down it. On Neon Functions an SSE endpoint is just a normal `fetch` handler that returns a `Response` whose body is a `ReadableStream` with `Content-Type: text/event-stream` — there is no library to install and nothing to upgrade. The runtime holds the response open as long as bytes keep flowing (15-minute heartbeat, see [Timeouts](../SKILL.md#timeouts-and-runtime-limits)).
 
 Reach for SSE over WebSockets when you only need server → client updates (live counters, notifications, progress, token streams) — it's simpler to run (plain HTTP, no `upgrade`), and `EventSource` **reconnects on its own**, so there's no client backoff to write.
 
@@ -64,7 +64,10 @@ app.get("/events", (c) => {
     },
   });
   return new Response(stream, {
-    headers: { "Content-Type": "text/event-stream", "Cache-Control": "no-cache, no-transform" },
+    headers: {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache, no-transform",
+    },
   });
 });
 
@@ -76,16 +79,25 @@ export default app;
 The fan-out rule is identical to WebSockets ([Keeping clients in sync across isolates](../SKILL.md#keeping-clients-in-sync-across-isolates-do-not-skip-this)): each isolate keeps its **own** set of open streams, so broadcasting in-process only reaches the clients on that isolate. Hold a `Set` of stream controllers and pick a strategy there — **poll Postgres** by default (keeps Scale to Zero), or `LISTEN`/`NOTIFY` (shown below) for lowest latency on always-on compute. Keep the source-of-truth state in Postgres — module state doesn't survive eviction.
 
 ```typescript
+import { attachDatabasePool } from "@neon/functions";
 import { Pool, Client } from "pg";
 
 const encoder = new TextEncoder();
 const clients = new Set<ReadableStreamDefaultController<Uint8Array>>();
 const pool = new Pool({ connectionString: process.env.DATABASE_URL, max: 5 });
+attachDatabasePool(pool);
 const CHANNEL = "events";
 
 // One dedicated DIRECT connection per isolate to receive events (LISTEN needs a
 // real session — use DATABASE_URL_UNPOOLED, not the pooled URL).
-const listener = new Client({ connectionString: process.env.DATABASE_URL_UNPOOLED });
+// Don't call attachDatabasePool here: it would silence the idle drop that killed the feed.
+// An error listener keeps the isolate alive; the feed stays down until the isolate restarts.
+const listener = new Client({
+  connectionString: process.env.DATABASE_URL_UNPOOLED,
+});
+listener.on("error", (err) => {
+  console.error(err);
+});
 listener.connect().then(() => listener.query(`LISTEN ${CHANNEL}`));
 listener.on("notification", (msg) => {
   if (!msg.payload) return;
@@ -101,7 +113,10 @@ listener.on("notification", (msg) => {
 
 // Anywhere you mutate state, NOTIFY so every isolate pushes to its own streams.
 function publish(payload: unknown) {
-  return pool.query("SELECT pg_notify($1, $2)", [CHANNEL, JSON.stringify(payload)]);
+  return pool.query("SELECT pg_notify($1, $2)", [
+    CHANNEL,
+    JSON.stringify(payload),
+  ]);
 }
 ```
 
@@ -125,8 +140,10 @@ Send `data:` with no `event:` field to deliver the default `message` event, whic
 
 ```typescript
 const source = new EventSource(`${FUNCTION_URL}/events`); // GET only
-source.onmessage = (e) => console.log("update", e.data);  // default "message" events
-source.onerror = () => {/* EventSource auto-reconnects; nothing to do */};
+source.onmessage = (e) => console.log("update", e.data);
+source.onerror = () => {
+  /* EventSource auto-reconnects; nothing to do */
+};
 // source.close() to stop.
 ```
 

package/dist/global-skills/neon-object-storage/SKILL.md

@@ -5,17 +5,31 @@ description: >-
   and the database stay in sync across every branch. Use when a user wants
   object storage, a bucket, blob/file storage, or somewhere to put uploads,
   images, documents, avatars, or user-generated files for their app or agent —
-  especially when they already use (or are setting up) Neon Postgres and don't
+  especially when they already use (or are setting up) Lakebase Postgres and don't
   want to add a separate storage provider like AWS S3, Cloudflare R2, or
   Supabase Storage. Triggers include "object storage", "bucket", "blob
   storage", "file storage", "store uploads/images/files", "S3-compatible
-  storage", "presigned URL", "where do I put files", "Neon Object Storage",
-  "Neon Storage", and "storage that branches with my database".
+  storage", "presigned URL", "where do I put files", "storage logs",
+  "bucket logs", "Neon Object Storage", "Neon Storage", and "storage that
+  branches with my database".
+metadata:
+  parent: neon
+  source: https://github.com/neondatabase/agent-skills/tree/main/skills/neon-object-storage
 ---
 
+**FIRST**: Use the parent `neon` skill for a Neon overview, getting started with Neon, Neon development best practices, and more.
+
+If the `neon` skill is not installed, fetch it from https://neon.com/docs/ai/skills/neon/SKILL.md or install it with:
+
+```bash
+npx skills add neondatabase/agent-skills --skill neon
+```
+
 # Neon Object Storage
 
-This is a preview feature and only available in `us-east-2`. Neon Object Storage is S3-compatible object storage that branches with your projects: every branch gets its own isolated storage state, so files and database rows stay in sync across dev, preview, staging, and production.
+This is a public beta feature and only available in `us-east-2`.
+
+Neon Object Storage is S3-compatible object storage that branches with your projects: every branch gets its own isolated storage state, so files and database rows stay in sync across dev, preview, staging, and production.
 
 Use this skill to help the user store and serve files that branch alongside their database. Deliver a working bucket and upload/download flow, a branch-aware S3 client wired to the injected env vars, or a precise answer from the official Neon docs.
 
@@ -23,7 +37,7 @@ Use this skill to help the user store and serve files that branch alongside thei
 
 Reach for Neon Object Storage when the user needs to store files (images, uploads, generated assets, documents, backups) and any of the following are true:
 
-- **They already use Neon Postgres and don't want a second provider.** One backend, one bill, one CLI, one set of branches — instead of standing up and wiring a separate AWS S3 / R2 / Supabase Storage account. The same Neon credential that backs the database backs storage.
+- **They already use Lakebase Postgres and don't want a second provider.** One backend, one bill, one CLI, one set of branches — instead of standing up and wiring a separate AWS S3 / R2 / Supabase Storage account. The same Neon credential that backs the database backs storage.
 - **Files must stay in sync with the database across environments.** Storage branches _together with_ your Postgres data. Fork a branch and the child instantly inherits the parent's buckets and objects at that point in time — copy-on-write, so no data is duplicated. This is what makes agent, dev, preview, and test environments seamless: a preview branch gets a consistent snapshot of _both_ the rows and the files they reference, and writes on the child never touch the parent.
 - **They want safe, throwaway environments.** Upload, overwrite, and delete files in a preview/CI branch without any risk to production data, then drop the branch.
 - **They want standard S3 tooling.** It's built on S3 semantics and speaks the S3 API, so the AWS SDKs, `boto3`, the AWS CLI, and presigned URLs all work — reliable and familiar, with no proprietary client.
@@ -37,6 +51,10 @@ If the user has no Neon project, isn't on Postgres, and just needs a standalone
 - **Two access modes** — `private` buckets require a credential for every operation; `public_read` buckets allow anonymous reads with authenticated writes.
 - **One credential system** — The same Neon credential system used by Functions and the AI Gateway.
 
+## Availability
+
+Check this precondition before setting anything up: Neon Object Storage is a public beta feature available only on new projects in the `us-east-2` region. Confirm the user's Neon project is a new project in `us-east-2` before proceeding; it can't be enabled on existing projects.
+
 ## Setup
 
 Object storage is part of the `neon.ts` infrastructure-as-code config (see the `neon` skill for the branch-first workflow, `link`/`checkout`, and `neon.ts` basics). Declare buckets under `preview.buckets`, keyed by bucket name:
@@ -73,9 +91,7 @@ neon config apply    # create the declared buckets  (neon deploy is an alias)
 
 Buckets are **branch-scoped**: when a `neon.ts` is present, `neon checkout` applies the policy as it _creates_ a branch, so a fresh preview/CI branch comes up with its buckets already provisioned (and copy-on-write objects inherited from the parent). Checking out an _existing_ branch doesn't reconcile it — run `neon deploy` to apply changes. Provisioning (`config apply` / `deploy`), `link`, and `checkout` also pull the branch's S3 credentials into your local `.env.local`, so the same `env pull` step shown below happens for you on those commands.
 
-For typed, validated access to the injected S3 credentials, pass the same config object to `parseEnv` from `@neon/env` — it returns an `env.storage` namespace (`accessKeyId`, `secretAccessKey`, `endpoint`, `region`) derived from your `neon.ts`.
-
-## Environment variables
+## Environment Variables
 
 When `preview.buckets` is declared, Neon injects **AWS-standard** S3 env vars so the AWS SDKs work from the environment with zero extra config. Inside a deployed Neon Function these are injected automatically; locally, pull them onto disk (or inject them at runtime) via the CLI:
 
@@ -94,7 +110,9 @@ neon-env run -- <your dev command>
 
 Because the names are AWS-standard, the AWS SDK picks up the credentials, endpoint, and region from the environment automatically. Credentials are branch-scoped and valid for that branch and all its descendants.
 
-## Working with objects: the Files SDK (recommended)
+For typed, validated access to these credentials instead of reading `process.env` directly, pass the same `neon.ts` config object to `parseEnv` from `@neon/env` — it returns an `env.storage` namespace (`accessKeyId`, `secretAccessKey`, `endpoint`, `region`) derived from your config. See the `neon` skill.
+
+## Working with Objects: the Files SDK (Recommended)
 
 The simplest, most portable way to read and write objects is the [Files SDK](https://files-sdk.dev) with its `neon` adapter — a small, unified storage API (`upload`, `download`, `url`, `list`, `exists`, `copy`, `delete`, `signedUploadUrl`) over web-standard I/O. It uses the AWS S3 client under the hood, configured appropriately for Neon, and relabels errors as `Neon error` — so there's nothing to misconfigure. Reach for this first.
 
@@ -127,7 +145,7 @@ const url = await files.url("generated/cat.jpg", { expiresIn: 3600 });
 
 Swap the adapter import (`files-sdk/s3`, `files-sdk/r2`, `files-sdk/gcs`, …) and the rest of your code is unchanged.
 
-## Working with objects: the AWS S3 client (alternative)
+## Working with Objects: the AWS S3 Client (Alternative)
 
 Neon speaks the S3 API directly, so you can drop down to the AWS SDK whenever you prefer the native client or already depend on it. The credentials, endpoint, and region are read from the standard AWS env chain, so the only setting you pass is `forcePathStyle: true` — Neon requires path-style addressing, so the S3 client **must** set it:
 
@@ -139,8 +157,6 @@ const s3 = new S3Client({
 });
 ```
 
-If you prefer typed access instead of reading `process.env` directly, `parseEnv` (from `@neon/env`) returns a validated `env.storage` namespace (`accessKeyId`, `secretAccessKey`, `endpoint`, `region`) derived from your `neon.ts` — see the `neon` skill.
-
 Then upload, download, and presign with the raw command objects:
 
 ```typescript
@@ -173,19 +189,27 @@ const url = await getSignedUrl(
 );
 ```
 
-The canonical pattern for pairing storage with the database on a branch: an agent generates an image → `PutObject` into the `images` bucket → a row is inserted in Postgres → a presigned URL is returned on read. Store the bucket **key** (not the bytes) in a Postgres column, and presign on read. Because both the row and the object live on the same branch, they branch together and never drift.
+## Pairing Storage with the Database on a Branch
+
+The canonical pattern: an agent generates an image → `PutObject` into the `images` bucket → a row is inserted in Postgres → a presigned URL is returned on read. Store the bucket **key** (not the bytes) in a Postgres column, and presign on read. Because both the row and the object live on the same branch, they branch together and never drift.
+
+## CLI Bucket and Object Commands
 
 `neon` also has first-class bucket/object commands (`neon bucket create|list|delete`, `neon bucket object put|get|list|delete`) for scripting and one-off operations.
 
-## Availability
+## Built-in Branch Logs
+
+```bash
+neon logs query --branch production --source storage --since 1h
+```
 
-Neon Object Storage is a preview (early access) feature available only on new projects in the `us-east-2` region. Confirm the user's Neon project is a new project in `us-east-2` before proceeding; it can't be enabled on existing projects. If the user does not yet have access, point them to the private beta sign-up: https://neon.com/blog/were-building-backends#access
+Storage is one of the two sources branch logs cover today, alongside Neon Functions. Logs are scoped to a single branch, so pass `--branch` when the bucket you're debugging isn't on the branch you're checked out on. Everything else about logs — the required CLI version, filters, the SDK, and the Loki-compatible read API — is in the parent `neon` skill's **Observability** section.
 
 ## Neon Documentation
 
 The Neon documentation is the source of truth and Object Storage is evolving rapidly, so always verify against the official docs. Any doc page can be fetched as markdown by appending `.md` to the URL or by requesting `Accept: text/markdown`. Find the right page from the docs index (https://neon.com/docs/llms.txt) and the changelog announcements.
 
-## Further reading
+## Further Reading
 
 - https://neon.com/docs/storage/overview.md
 - https://neon.com/docs/storage/get-started.md