Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

feat(studio): add assistant notebook run tool (#49361)

Saxon Fletcherdcac820571c2
diff --git a/apps/studio/data/logs/execute-logs-sql-mutation.ts b/apps/studio/data/logs/execute-logs-sql-mutation.ts
index cb241ea64df..608245f8562 100644
--- a/apps/studio/data/logs/execute-logs-sql-mutation.ts
+++ b/apps/studio/data/logs/execute-logs-sql-mutation.ts
@@ -94,6 +94,7 @@ export interface ExecuteLogsSqlVariables {
*/
endpoint: AnalyticsSqlEndpoint
signal?: AbortSignal
+ headers?: HeadersInit
}
export interface ExecuteLogsSqlResult {
@@ -115,6 +116,7 @@ export async function executeLogsSql({
range,
endpoint,
signal,
+ headers,
}: ExecuteLogsSqlVariables): Promise<ExecuteLogsSqlResult> {
const data = await executeAnalyticsSql({
projectRef,
@@ -124,6 +126,7 @@ export async function executeLogsSql({
iso_timestamp_end: range.to,
key: 'sql-editor',
signal,
+ headers,
})
const body = (data ?? {}) as { result?: unknown[]; error?: unknown }
diff --git a/apps/studio/lib/ai/prompts.ts b/apps/studio/lib/ai/prompts.ts
index d5599d7bf21..f659ccd3ea5 100644
--- a/apps/studio/lib/ai/prompts.ts
+++ b/apps/studio/lib/ai/prompts.ts
@@ -808,6 +808,8 @@ export const NOTEBOOKS_PROMPT = `
- Use \`create_notebook\` for a saved, shareable, multi-step investigation or dashboard the user will revisit — e.g. "build me a signup funnel notebook" or "create a notebook to track auth errors".
- Use \`update_notebook\` to edit an existing notebook — insert, replace, delete, or move cells — instead of recreating it from scratch.
- Use \`delete_notebook\` only when the user explicitly asks to delete a whole notebook — never to remove a cell from one still in use; that's \`update_notebook\` with a \`delete_cell\` operation. Deleting a notebook is irreversible — warn the user before calling it, the same way you would for any other irreversible operation.
+- When the user asks to read or analyze a notebook using its current results, call \`get_notebook\` and then \`run_notebook\`. The run tool presents all query cells for one user approval, executes them in notebook order, and returns only the results allowed by the organization's sharing level. Do not replace it with one \`execute_sql\` call per cell.
+- Questions only about a notebook's saved structure or query configuration do not require \`run_notebook\`.
- Use \`execute_sql\` for a single ad-hoc question with no need to persist it.
- When the request clearly calls for a notebook, call \`create_notebook\`, \`update_notebook\`, or \`delete_notebook\` directly; all three tools handle user approval.
- \`update_notebook\` requires \`expected_updated_at\`, the \`updated_at\` you got from \`get_notebook\`. If the notebook changed since, the call is rejected — call \`get_notebook\` again and reissue \`update_notebook\` against the current content.
diff --git a/apps/studio/lib/ai/tool-filter.test.ts b/apps/studio/lib/ai/tool-filter.test.ts
index c681d754493..6721995742c 100644
--- a/apps/studio/lib/ai/tool-filter.test.ts
+++ b/apps/studio/lib/ai/tool-filter.test.ts
@@ -14,6 +14,7 @@ describe('TOOL_CATEGORY_MAP', () => {
it('should categorize tools correctly', () => {
expect(TOOL_CATEGORY_MAP['execute_sql']).toBe(TOOL_CATEGORIES.UI)
expect(TOOL_CATEGORY_MAP['list_tables']).toBe(TOOL_CATEGORIES.SCHEMA)
+ expect(TOOL_CATEGORY_MAP['run_notebook']).toBe(TOOL_CATEGORIES.SCHEMA)
})
})
@@ -222,12 +223,14 @@ describe('createPrivacyMessageTool', () => {
description: 'Original description',
inputSchema: z.object({}),
execute: vitest.fn(),
+ toModelOutput: vitest.fn(),
}
const privacyTool = createPrivacyMessageTool(originalTool)
expect(privacyTool.description).toContain('Original description')
expect(privacyTool.description).toContain('Requires opting in')
+ expect(privacyTool.toModelOutput).toBeUndefined()
const result = await privacyTool.execute({}, {})
expect(result.status).toContain("You don't have permission to use this tool")
diff --git a/apps/studio/lib/ai/tool-filter.ts b/apps/studio/lib/ai/tool-filter.ts
index 5215344dbe6..82de291da6b 100644
--- a/apps/studio/lib/ai/tool-filter.ts
+++ b/apps/studio/lib/ai/tool-filter.ts
@@ -40,6 +40,7 @@ export const toolSetValidationSchema = z.record(
'list_databases',
'list_notebooks',
'get_notebook',
+ 'run_notebook',
'create_notebook',
'update_notebook',
'delete_notebook',
@@ -97,6 +98,7 @@ export const TOOL_CATEGORY_MAP: Record<string, ToolCategory> = {
list_databases: TOOL_CATEGORIES.SCHEMA,
list_notebooks: TOOL_CATEGORIES.SCHEMA,
get_notebook: TOOL_CATEGORIES.SCHEMA,
+ run_notebook: TOOL_CATEGORIES.SCHEMA,
create_notebook: TOOL_CATEGORIES.SCHEMA,
update_notebook: TOOL_CATEGORIES.SCHEMA,
delete_notebook: TOOL_CATEGORIES.SCHEMA,
@@ -178,6 +180,9 @@ export function createPrivacyMessageTool(toolInstance: Tool<any, any>) {
...toolInstance,
description,
execute: async (_args: any, _context: any) => ({ status: privacyMessage }),
+ // The original transformer expects the original tool's output shape. The privacy
+ // stub returns only a status message, so retaining it can crash the response stream.
+ toModelOutput: undefined,
}
}
diff --git a/apps/studio/lib/ai/tools/index.test.ts b/apps/studio/lib/ai/tools/index.test.ts
index 983c21d73bf..9fa86ca2fa7 100644
--- a/apps/studio/lib/ai/tools/index.test.ts
+++ b/apps/studio/lib/ai/tools/index.test.ts
@@ -89,6 +89,7 @@ describe('ai/tools getTools', () => {
expect(tools).not.toHaveProperty('list_notebooks')
expect(tools).not.toHaveProperty('get_notebook')
+ expect(tools).not.toHaveProperty('run_notebook')
})
it('includes notebook tools only when isExplorerEnabled is true', async () => {
@@ -96,5 +97,6 @@ describe('ai/tools getTools', () => {
expect(tools).toHaveProperty('list_notebooks')
expect(tools).toHaveProperty('get_notebook')
+ expect(tools).toHaveProperty('run_notebook')
})
})
diff --git a/apps/studio/lib/ai/tools/index.ts b/apps/studio/lib/ai/tools/index.ts
index 6b487d0c8a7..e70d7cdd7ba 100644
--- a/apps/studio/lib/ai/tools/index.ts
+++ b/apps/studio/lib/ai/tools/index.ts
@@ -78,7 +78,14 @@ export const getTools = async ({
connectionString,
}),
...getReportTools({ projectRef, authorization }),
- ...(isExplorerEnabled ? getNotebookTools({ projectRef, authorization }) : {}),
+ ...(isExplorerEnabled
+ ? getNotebookTools({
+ projectRef,
+ connectionString,
+ authorization,
+ aiOptInLevel,
+ })
+ : {}),
...(baseUrl ? getIncidentTools({ baseUrl }) : {}),
}
}
diff --git a/apps/studio/lib/ai/tools/mock-tools.test.ts b/apps/studio/lib/ai/tools/mock-tools.test.ts
index c64203029a7..d41b7f50aee 100644
--- a/apps/studio/lib/ai/tools/mock-tools.test.ts
+++ b/apps/studio/lib/ai/tools/mock-tools.test.ts
@@ -117,6 +117,29 @@ describe('ai/tools/mock-tools getMockTools', () => {
).rejects.toThrow(/not found/i)
})
+ it('shares deterministic run_notebook output with eval models', async () => {
+ const mockTools = await getMockTools(undefined, new AbortController().signal)
+ if (!mockTools.run_notebook.execute) throw new Error('execute is undefined')
+ if (!mockTools.run_notebook.toModelOutput) throw new Error('toModelOutput is undefined')
+
+ const output = await mockTools.run_notebook.execute(
+ { id: AUTH_HEALTH_NOTEBOOK_ID, expected_updated_at: MOCK_NOTEBOOKS_DATA[0].updated_at },
+ { toolCallId: 'test', messages: [], context: {} }
+ )
+ const modelOutput = mockTools.run_notebook.toModelOutput({
+ toolCallId: 'test',
+ input: { id: AUTH_HEALTH_NOTEBOOK_ID, expected_updated_at: output.updated_at },
+ output,
+ })
+
+ expect(modelOutput).toMatchObject({
+ type: 'json',
+ value: {
+ cells: expect.arrayContaining([expect.objectContaining({ rows: [] })]),
+ },
+ })
+ })
+
it('overrides create_notebook needsApproval to false, unlike the real tool', async () => {
const mockTools = await getMockTools(undefined, new AbortController().signal)
diff --git a/apps/studio/lib/ai/tools/mock-tools.ts b/apps/studio/lib/ai/tools/mock-tools.ts
index 6e9dec44e85..6d586a04e45 100644
--- a/apps/studio/lib/ai/tools/mock-tools.ts
+++ b/apps/studio/lib/ai/tools/mock-tools.ts
@@ -427,7 +427,7 @@ const MOCK_DATABASES_DATA = [
},
]
-// All five notebook tools are real, locally-defined ai-SDK tools, so wrap them and
+// All notebook tools are real, locally-defined ai-SDK tools, so wrap them and
// override only execute/needsApproval — evals must validate the model's arguments
// against the exact schemas production uses (agentCellSchema's `.strict()` rejection of
// agent-authored cell ids, update_notebook's real operations schema, etc).
@@ -436,10 +436,11 @@ function createMockNotebookTools(store: MockNotebookStore) {
list_databases,
list_notebooks,
get_notebook,
+ run_notebook,
create_notebook,
update_notebook,
delete_notebook,
- } = getNotebookTools()
+ } = getNotebookTools({ aiOptInLevel: 'schema_and_log_and_data' })
return {
list_databases: {
@@ -485,6 +486,38 @@ function createMockNotebookTools(store: MockNotebookStore) {
}
},
},
+ run_notebook: {
+ ...run_notebook,
+ // The eval harness cannot answer approval gates. Nothing executes here; return a
+ // deterministic empty result for each query cell in notebook order.
+ needsApproval: false,
+ execute: async (
+ { id }: { id: string; expected_updated_at: string },
+ _options: ToolExecutionOptions<unknown>
+ ) => {
+ const notebook = store.get(id)
+ if (!notebook) throw new Error(`Notebook ${id} not found.`)
+
+ return {
+ id,
+ name: notebook.name,
+ updated_at: notebook.updated_at,
+ cells: notebook.content.cells.flatMap((cell) =>
+ cell._tag === 'markdown_cell'
+ ? []
+ : [
+ {
+ cell_id: cell._id,
+ title: cell.title?.trim() || 'Untitled query',
+ source: cell._tag === 'log_cell' ? ('logs' as const) : ('database' as const),
+ status: 'success' as const,
+ rows: [],
+ },
+ ]
+ ),
+ }
+ },
+ },
create_notebook: {
...create_notebook,
// The eval harness can't answer an approval gate (generate-assistant-response
diff --git a/apps/studio/lib/ai/tools/notebook-run-output.ts b/apps/studio/lib/ai/tools/notebook-run-output.ts
new file mode 100644
index 00000000000..0ec4d573ca2
--- /dev/null
+++ b/apps/studio/lib/ai/tools/notebook-run-output.ts
@@ -0,0 +1,97 @@
+import type { JSONValue } from 'ai'
+import { z } from 'zod'
+
+import type { AiOptInLevel } from '@/hooks/misc/useOrgOptedIntoAi'
+
+const jsonValueSchema: z.ZodType<JSONValue> = z.lazy(() =>
+ z.union([
+ z.null(),
+ z.string(),
+ z.number(),
+ z.boolean(),
+ z.array(jsonValueSchema),
+ z.record(jsonValueSchema),
+ ])
+)
+
+export const notebookRunOutputSchema = z
+ .object({
+ id: z.string(),
+ name: z.string(),
+ updated_at: z.string(),
+ cells: z.array(
+ z
+ .object({
+ cell_id: z.string(),
+ title: z.string(),
+ source: z.enum(['database', 'logs']),
+ status: z.enum(['success', 'error']),
+ rows: z.array(jsonValueSchema).optional(),
+ error: z.object({ message: z.string() }).strict().optional(),
+ message: z.string().optional(),
+ })
+ .strict()
+ ),
+ })
+ .strict()
+
+export type NotebookRunOutput = z.infer<typeof notebookRunOutputSchema>
+export type NotebookRunCellOutput = NotebookRunOutput['cells'][number]
+
+const HIDDEN_RESULT_MESSAGE =
+ 'The query ran, but its rows were not shared with the Assistant at the current permission level.'
+const HIDDEN_ERROR_MESSAGE =
+ 'The query failed. The user can review the error in the notebook run results.'
+export const INVALID_NOTEBOOK_RUN_OUTPUT_MESSAGE =
+ 'The notebook was run, but its results were not shared with the Assistant because the saved output could not be safely validated.'
+
+/**
+ * Validates persisted output before applying sharing permissions. `source` is trusted only
+ * after this strict parse because history tool output originates from the client.
+ */
+export function sanitizeNotebookRunOutput(
+ output: NotebookRunOutput,
+ aiOptInLevel: AiOptInLevel
+): NotebookRunOutput
+export function sanitizeNotebookRunOutput(
+ output: unknown,
+ aiOptInLevel: AiOptInLevel
+): NotebookRunOutput | typeof INVALID_NOTEBOOK_RUN_OUTPUT_MESSAGE
+export function sanitizeNotebookRunOutput(
+ output: unknown,
+ aiOptInLevel: AiOptInLevel
+): NotebookRunOutput | typeof INVALID_NOTEBOOK_RUN_OUTPUT_MESSAGE {
+ const parsedOutput = notebookRunOutputSchema.safeParse(output)
+ if (!parsedOutput.success) return INVALID_NOTEBOOK_RUN_OUTPUT_MESSAGE
+
+ return {
+ ...parsedOutput.data,
+ cells: parsedOutput.data.cells.map((cell) => {
+ const canShareRows =
+ aiOptInLevel === 'schema_and_log_and_data' ||
+ (cell.source === 'logs' && aiOptInLevel === 'schema_and_log')
+
+ if (cell.status === 'success') {
+ return canShareRows
+ ? cell
+ : {
+ cell_id: cell.cell_id,
+ title: cell.title,
+ source: cell.source,
+ status: cell.status,
+ message: HIDDEN_RESULT_MESSAGE,
+ }
+ }
+
+ return canShareRows
+ ? cell
+ : {
+ cell_id: cell.cell_id,
+ title: cell.title,
+ source: cell.source,
+ status: cell.status,
+ error: { message: HIDDEN_ERROR_MESSAGE },
+ }
+ }),
+ }
+}
diff --git a/apps/studio/lib/ai/tools/notebook-tools.test.ts b/apps/studio/lib/ai/tools/notebook-tools.test.ts
index 65d60afaf87..a473d170140 100644
--- a/apps/studio/lib/ai/tools/notebook-tools.test.ts
+++ b/apps/studio/lib/ai/tools/notebook-tools.test.ts
@@ -2,6 +2,7 @@ import { components } from 'api-types'
import { HttpResponse } from 'msw'
import { describe, expect, it } from 'vitest'
+import { sanitizeNotebookRunOutput, type NotebookRunOutput } from './notebook-run-output'
import {
decodeNotebookToolError,
encodeNotebookToolError,
@@ -109,13 +110,14 @@ function mockGetNotebook() {
describe('ai/tools/notebook-tools', () => {
describe('getNotebookTools', () => {
- it('should return list_databases, list_notebooks, get_notebook, create_notebook, update_notebook, and delete_notebook tools', () => {
+ it('should return all notebook tools', () => {
const tools = getNotebookTools()
expect(Object.keys(tools)).toEqual([
'list_databases',
'list_notebooks',
'get_notebook',
+ 'run_notebook',
'create_notebook',
'update_notebook',
'delete_notebook',
@@ -129,9 +131,10 @@ describe('ai/tools/notebook-tools', () => {
expect(tools.get_notebook.needsApproval).toBeUndefined()
})
- it('should require approval to create, update, or delete a notebook', () => {
+ it('should require approval to run, create, update, or delete a notebook', () => {
const tools = getNotebookTools()
+ expect(tools.run_notebook.needsApproval).toBe(true)
expect(tools.create_notebook.needsApproval).toBe(true)
expect(tools.update_notebook.needsApproval).toBe(true)
expect(tools.delete_notebook.needsApproval).toBe(true)
@@ -201,6 +204,280 @@ describe('ai/tools/notebook-tools', () => {
})
})
+ describe('run_notebook', () => {
+ function mockGetNotebook(content: unknown = NOTEBOOK_CONTENT) {
+ addAPIMock({
+ method: 'get',
+ path: '/platform/projects/:ref/content/item/:id',
+ response: () =>
+ HttpResponse.json<GetUserContentByIdResponse>({
+ id: 'notebook-1',
+ name: 'Signup funnel',
+ description: undefined,
+ visibility: 'project',
+ favorite: false,
+ folder_id: null,
+ inserted_at: '2026-01-01T00:00:00.000Z',
+ updated_at: '2026-01-01T00:00:00.000Z',
+ owner_id: 1,
+ project_id: 1,
+ type: 'notebook',
+ content,
+ } as unknown as GetUserContentByIdResponse),
+ })
+ }
+
+ it('runs database and log cells in notebook order and skips markdown', async () => {
+ mockGetNotebook()
+ const executionOrder: string[] = []
+
+ addAPIMock({
+ method: 'post',
+ path: '/platform/pg-meta/:ref/query',
+ response: () => {
+ executionOrder.push('database')
+ return HttpResponse.json([{ email: '[email protected]' }])
+ },
+ })
+ addAPIMock({
+ method: 'post',
+ path: '/platform/projects/:ref/analytics/endpoints/logs.all.otel',
+ response: () => {
+ executionOrder.push('logs')
+ return HttpResponse.json<{ result: unknown[] }>({
+ result: [{ event_message: 'started' }],
+ })
+ },
+ })
+
+ const tools = getNotebookTools({
+ projectRef: 'test-project',
+ connectionString: 'encrypted-connection-string',
+ authorization: 'Bearer token',
+ aiOptInLevel: 'schema_and_log_and_data',
+ })
+ if (!tools.run_notebook.execute) throw new Error('execute is undefined')
+
+ const result = await tools.run_notebook.execute(
+ {
+ id: 'notebook-1',
+ expected_updated_at: '2026-01-01T00:00:00.000Z',
+ },
+ { toolCallId: 'test', messages: [], context: {} }
+ )
+
+ expect(executionOrder).toEqual(['database', 'logs'])
+ expect(result).toMatchObject({
+ id: 'notebook-1',
+ name: 'Signup funnel',
+ cells: [
+ {
+ cell_id: 'cell-2',
+ source: 'database',
+ status: 'success',
+ rows: [{ email: '[email protected]' }],
+ },
+ {
+ cell_id: 'cell-3',
+ source: 'logs',
+ status: 'success',
+ rows: [{ event_message: 'started' }],
+ },
+ ],
+ })
+ })
+
+ it('continues primary and log cells when the read replica lookup fails', async () => {
+ mockGetNotebook({
+ schema_version: 1,
+ cells: [
+ {
+ _tag: 'database_cell',
+ _id: 'primary-cell',
+ title: 'Primary query',
+ sql: 'select 1 as primary',
+ row_limit: 100,
+ },
+ {
+ _tag: 'database_cell',
+ _id: 'replica-cell',
+ title: 'Replica query',
+ sql: 'select 1 as replica',
+ row_limit: 100,
+ database_identifier: 'replica-1',
+ },
+ {
+ _tag: 'log_cell',
+ _id: 'log-cell',
+ title: 'Log query',
+ sql: 'select event_message from edge_logs limit 10',
+ time_range: { _tag: 'relative_time_range', unit: 'hour', amount: 1 },
+ },
+ ],
+ })
+
+ addAPIMock({
+ method: 'get',
+ path: '/platform/projects/:ref/databases',
+ response: () =>
+ HttpResponse.json<APIErrorBody>({ message: 'Replica lookup failed' }, { status: 500 }),
+ })
+ addAPIMock({
+ method: 'post',
+ path: '/platform/pg-meta/:ref/query',
+ response: () => HttpResponse.json([{ primary: 1 }]),
+ })
+ addAPIMock({
+ method: 'post',
+ path: '/platform/projects/:ref/analytics/endpoints/logs.all.otel',
+ response: () =>
+ HttpResponse.json<{ result: unknown[] }>({
+ result: [{ event_message: 'started' }],
+ }),
+ })
+
+ const tools = getNotebookTools({
+ projectRef: 'test-project',
+ connectionString: 'encrypted-connection-string',
+ authorization: 'Bearer token',
+ aiOptInLevel: 'schema_and_log_and_data',
+ })
+ if (!tools.run_notebook.execute) throw new Error('execute is undefined')
+
+ const result = await tools.run_notebook.execute(
+ {
+ id: 'notebook-1',
+ expected_updated_at: '2026-01-01T00:00:00.000Z',
+ },
+ { toolCallId: 'test', messages: [], context: {} }
+ )
+
+ expect(result).toEqual({
+ id: 'notebook-1',
+ name: 'Signup funnel',
+ updated_at: '2026-01-01T00:00:00.000Z',
+ cells: [
+ {
+ cell_id: 'primary-cell',
+ title: 'Primary query',
+ source: 'database',
+ status: 'success',
+ rows: [{ primary: 1 }],
+ },
+ {
+ cell_id: 'replica-cell',
+ title: 'Replica query',
+ source: 'database',
+ status: 'error',
+ error: { message: 'Replica lookup failed' },
+ },
+ {
+ cell_id: 'log-cell',
+ title: 'Log query',
+ source: 'logs',
+ status: 'success',
+ rows: [{ event_message: 'started' }],
+ },
+ ],
+ })
+ })
+
+ it('rejects the run when the notebook changed after it was read', async () => {
+ mockGetNotebook()
+ const tools = getNotebookTools({ projectRef: 'test-project' })
+ if (!tools.run_notebook.execute) throw new Error('execute is undefined')
+
+ await expect(
+ tools.run_notebook.execute(
+ { id: 'notebook-1', expected_updated_at: '2025-12-31T00:00:00.000Z' },
+ { toolCallId: 'test', messages: [], context: {} }
+ )
+ ).rejects.toMatchObject({
+ metadata: { exposeToAssistant: true },
+ })
+ })
+
+ it('shares each source result only at its permitted opt-in level', () => {
+ const output: NotebookRunOutput = {
+ id: 'notebook-1',
+ name: 'Signup funnel',
+ updated_at: '2026-01-01T00:00:00.000Z',
+ cells: [
+ {
+ cell_id: 'database-cell',
+ title: 'Customers',
+ source: 'database' as const,
+ status: 'success' as const,
+ rows: [{ email: '[email protected]' }],
+ },
+ {
+ cell_id: 'log-cell',
+ title: 'Errors',
+ source: 'logs' as const,
+ status: 'success' as const,
+ rows: [{ event_message: 'failed' }],
+ },
+ ],
+ }
+
+ const schemaCells = sanitizeNotebookRunOutput(output, 'schema').cells
+ expect(schemaCells[0]).not.toHaveProperty('rows')
+ expect(schemaCells[1]).not.toHaveProperty('rows')
+
+ const logCells = sanitizeNotebookRunOutput(output, 'schema_and_log').cells
+ expect(logCells[0]).not.toHaveProperty('rows')
+ expect(logCells[1]).toMatchObject({ rows: [{ event_message: 'failed' }] })
+ expect(sanitizeNotebookRunOutput(output, 'schema_and_log_and_data')).toEqual(output)
+ })
+
+ it('allowlists unshared cell fields according to status', () => {
+ const output: NotebookRunOutput = {
+ id: 'notebook-1',
+ name: 'Signup funnel',
+ updated_at: '2026-01-01T00:00:00.000Z',
+ cells: [
+ {
+ cell_id: 'success-cell',
+ title: 'Customers',
+ source: 'database',
+ status: 'success',
+ rows: [{ secret: 'row value' }],
+ error: { message: 'client-controlled error' },
+ },
+ {
+ cell_id: 'error-cell',
+ title: 'Failed customers query',
+ source: 'database',
+ status: 'error',
+ rows: [{ secret: 'row value' }],
+ message: 'client-controlled message',
+ error: { message: 'client-controlled error' },
+ },
+ ],
+ }
+
+ expect(sanitizeNotebookRunOutput(output, 'schema').cells).toEqual([
+ {
+ cell_id: 'success-cell',
+ title: 'Customers',
+ source: 'database',
+ status: 'success',
+ message:
+ 'The query ran, but its rows were not shared with the Assistant at the current permission level.',
+ },
+ {
+ cell_id: 'error-cell',
+ title: 'Failed customers query',
+ source: 'database',
+ status: 'error',
+ error: {
+ message: 'The query failed. The user can review the error in the notebook run results.',
+ },
+ },
+ ])
+ })
+ })
+
describe('list_notebooks', () => {
it('should list notebooks with summary fields, forwarding the authorization header and cursor', async () => {
let capturedRequest: Request | undefined
diff --git a/apps/studio/lib/ai/tools/notebook-tools.ts b/apps/studio/lib/ai/tools/notebook-tools.ts
index 568c1582838..5272f155f5d 100644
--- a/apps/studio/lib/ai/tools/notebook-tools.ts
+++ b/apps/studio/lib/ai/tools/notebook-tools.ts
@@ -1,7 +1,13 @@
import { acceptUntrustedSql, untrustedSql } from '@supabase/pg-meta'
-import { tool } from 'ai'
+import { tool, type JSONValue } from 'ai'
import { z } from 'zod'
+import {
+ sanitizeNotebookRunOutput,
+ type NotebookRunCellOutput,
+ type NotebookRunOutput,
+} from './notebook-run-output'
+import { resolveLogTimeRange } from '@/components/interfaces/QuerySources/LogTimeRange.utils'
import { deleteContents } from '@/data/content/content-delete-mutation'
import { getContent } from '@/data/content/content-infinite-query'
import {
@@ -17,13 +23,29 @@ import {
type WritableNotebook,
} from '@/data/content/notebooks/notebook-schema'
import { createNotebook, upsertNotebook } from '@/data/content/notebooks/notebook-upsert-mutation'
+import { executeLogsSql } from '@/data/logs/execute-logs-sql-mutation'
import { acceptUntrustedLogsSql, untrustedLogSql } from '@/data/logs/safe-analytics-sql'
+import { QUERY_SOURCE_REGISTRY } from '@/data/query-sources/query-source-registry'
import { getReadReplicas } from '@/data/read-replicas/replicas-query'
+import { executeSql } from '@/data/sql/execute-sql-mutation'
+import { applyAutoLimit } from '@/data/sql/utils'
+import type { AiOptInLevel } from '@/hooks/misc/useOrgOptedIntoAi'
import type { Notebooks } from '@/types'
export type NotebookToolsContext = {
projectRef?: string
+ connectionString?: string
authorization?: string
+ aiOptInLevel?: AiOptInLevel
+}
+
+function getErrorMessage(error: unknown): string {
+ if (error instanceof Error) return error.message
+ if (typeof error === 'object' && error !== null && 'message' in error) {
+ const message = (error as { message?: unknown }).message
+ if (typeof message === 'string') return message
+ }
+ return 'An unexpected error occurred while running this query.'
}
const notebookToolErrorMetadataSchema = z.object({
@@ -98,7 +120,7 @@ function assertValidDatabaseIdentifiers(
}
export const getNotebookTools = (ctx: NotebookToolsContext = {}) => {
- const { projectRef, authorization } = ctx
+ const { projectRef, connectionString, authorization, aiOptInLevel = 'schema' } = ctx
const authHeaders = authorization ? { Authorization: authorization } : undefined
return {
@@ -181,6 +203,140 @@ export const getNotebookTools = (ctx: NotebookToolsContext = {}) => {
}
},
}),
+ run_notebook: tool({
+ description:
+ 'Asks the user to run every database and logs query cell in a notebook, in notebook order, and returns each result according to the organization data-sharing permissions. Requires one user approval before any cell executes.',
+ inputSchema: z.object({
+ id: z.string().describe('The id of the notebook to run.'),
+ expected_updated_at: z
+ .string()
+ .describe(
+ 'The `updated_at` received from `get_notebook`. The run is rejected if the notebook changed since.'
+ ),
+ }),
+ needsApproval: true,
+ execute: async ({ id, expected_updated_at }) => {
+ const notebook = await getNotebook({ projectRef, id }, undefined, authHeaders)
+
+ if (notebook.updated_at !== expected_updated_at) {
+ throw new NotebookToolError(
+ `Notebook "${id}" changed since expected_updated_at (${expected_updated_at}); it is now ${notebook.updated_at}. Call get_notebook again and reissue run_notebook against the current content.`,
+ { exposeToAssistant: true }
+ )
+ }
+
+ const queryCells = notebook.content.cells.filter(
+ (cell) => cell._tag === 'database_cell' || cell._tag === 'log_cell'
+ )
+ const shouldLookupReplica = queryCells.some(
+ (cell) =>
+ cell._tag === 'database_cell' &&
+ cell.database_identifier !== undefined &&
+ cell.database_identifier !== projectRef
+ )
+ let databases: Awaited<ReturnType<typeof getReadReplicas>> = []
+ let replicaLookupFailure: { error: unknown } | undefined
+ if (shouldLookupReplica) {
+ try {
+ databases = await getReadReplicas({ projectRef }, undefined, authHeaders)
+ } catch (error) {
+ replicaLookupFailure = { error }
+ }
+ }
+
+ const cells: NotebookRunCellOutput[] = []
+
+ // This execute function only runs after the AI SDK approval gate above resolves true.
+ // That approval is the explicit user gesture which promotes every persisted cell's
+ // untrusted SQL immediately before execution. Run sequentially to preserve notebook
+ // order and avoid racing cells that may depend on earlier writes.
+ for (const cell of queryCells) {
+ const title = cell.title?.trim() || 'Untitled query'
+
+ try {
+ if (cell._tag === 'log_cell') {
+ const result = await executeLogsSql({
+ projectRef: projectRef ?? '',
+ sql: acceptUntrustedLogsSql(cell.unchecked_sql),
+ range: resolveLogTimeRange(cell.time_range),
+ endpoint: QUERY_SOURCE_REGISTRY.logs.endpoint,
+ headers: authHeaders,
+ })
+ if (result.error) throw result.error
+ cells.push({
+ cell_id: cell._id,
+ title,
+ source: 'logs',
+ status: 'success',
+ // The analytics response crossed a JSON fetch boundary, although its shared
+ // data-layer type remains `unknown[]` because individual endpoints vary.
+ rows: result.rows as JSONValue[],
+ })
+ continue
+ }
+
+ const isReplicaTarget =
+ cell.database_identifier !== undefined && cell.database_identifier !== projectRef
+
+ if (isReplicaTarget && replicaLookupFailure !== undefined) {
+ throw replicaLookupFailure.error
+ }
+
+ const selectedConnectionString = !isReplicaTarget
+ ? connectionString
+ : databases?.find((database) => database.identifier === cell.database_identifier)
+ ?.connectionString
+
+ if (!selectedConnectionString) {
+ throw new Error(
+ `Unable to run query: connection string is missing for database "${cell.database_identifier ?? projectRef ?? 'primary'}"`
+ )
+ }
+
+ const limitedSql = applyAutoLimit(
+ acceptUntrustedSql(cell.unchecked_sql),
+ cell.row_limit
+ )
+ const { result } = await executeSql<JSONValue[]>(
+ {
+ projectRef,
+ connectionString: selectedConnectionString,
+ sql: limitedSql.sql,
+ isStatementTimeoutDisabled: true,
+ },
+ undefined,
+ authHeaders
+ )
+ cells.push({
+ cell_id: cell._id,
+ title,
+ source: 'database',
+ status: 'success',
+ rows: Array.isArray(result) ? result : [],
+ })
+ } catch (error) {
+ cells.push({
+ cell_id: cell._id,
+ title,
+ source: cell._tag === 'log_cell' ? 'logs' : 'database',
+ status: 'error',
+ error: { message: getErrorMessage(error) },
+ })
+ }
+ }
+
+ return {
+ id: notebook.id,
+ name: notebook.name,
+ updated_at: notebook.updated_at,
+ cells,
+ } satisfies NotebookRunOutput
+ },
+ toModelOutput: ({ output }) => ({
+ type: 'json',
+ value: sanitizeNotebookRunOutput(output, aiOptInLevel),
+ }),
+ }),
create_notebook: tool({
description:
'Asks the user to create a new notebook with the given cells. Requires user approval before creating.',
diff --git a/apps/studio/lib/ai/tools/tool-sanitizer.test.ts b/apps/studio/lib/ai/tools/tool-sanitizer.test.ts
index 14705228f16..27b5bdca214 100644
--- a/apps/studio/lib/ai/tools/tool-sanitizer.test.ts
+++ b/apps/studio/lib/ai/tools/tool-sanitizer.test.ts
@@ -10,9 +10,83 @@ import {
createAssistantMessageWithUpdateNotebookTool,
createLongConversation,
} from '../test-fixtures'
+import { INVALID_NOTEBOOK_RUN_OUTPUT_MESSAGE, type NotebookRunOutput } from './notebook-run-output'
import { NO_DATA_PERMISSIONS, sanitizeMessagePart } from './tool-sanitizer'
+const notebookRunPart = {
+ type: 'tool-run_notebook',
+ state: 'output-available',
+ toolCallId: 'run-1',
+ input: { id: 'notebook-1', expected_updated_at: '2026-01-01T00:00:00.000Z' },
+ output: {
+ id: 'notebook-1',
+ name: 'Notebook',
+ updated_at: '2026-01-01T00:00:00.000Z',
+ cells: [
+ {
+ cell_id: 'db',
+ title: 'Database',
+ source: 'database',
+ status: 'success',
+ rows: [{ secret: 'database value' }],
+ },
+ {
+ cell_id: 'logs',
+ title: 'Logs',
+ source: 'logs',
+ status: 'success',
+ rows: [{ secret: 'log value' }],
+ },
+ ],
+ },
+} as unknown as ToolUIPart
+
describe('messages are sanitized based on opt-in level', () => {
+ test('notebook runs sanitize database and log rows independently', () => {
+ const schemaOutput = (sanitizeMessagePart(notebookRunPart, 'schema') as ToolUIPart)
+ .output as NotebookRunOutput
+ const logOutput = (sanitizeMessagePart(notebookRunPart, 'schema_and_log') as ToolUIPart)
+ .output as NotebookRunOutput
+ const dataOutput = (
+ sanitizeMessagePart(notebookRunPart, 'schema_and_log_and_data') as ToolUIPart
+ ).output as NotebookRunOutput
+
+ expect(schemaOutput.cells[0].rows).toBeUndefined()
+ expect(schemaOutput.cells[1].rows).toBeUndefined()
+ expect(logOutput.cells[0].rows).toBeUndefined()
+ expect(logOutput.cells[1].rows).toEqual([{ secret: 'log value' }])
+ expect(dataOutput.cells[0].rows).toEqual([{ secret: 'database value' }])
+ expect(dataOutput.cells[1].rows).toEqual([{ secret: 'log value' }])
+ })
+
+ test.each([
+ ['a non-object output', 'client-controlled output'],
+ ['an object without cells', { status: 'privacy message' }],
+ [
+ 'a cell with an untrusted source label',
+ {
+ id: 'notebook-1',
+ name: 'Notebook',
+ updated_at: '2026-01-01T00:00:00.000Z',
+ cells: [
+ {
+ cell_id: 'db',
+ title: 'Database',
+ source: 'untrusted-source',
+ status: 'success',
+ rows: [{ secret: 'database value' }],
+ },
+ ],
+ },
+ ],
+ ])('notebook runs fail closed for %s', (_description, output) => {
+ const malformedPart = { ...notebookRunPart, output } as ToolUIPart
+
+ expect((sanitizeMessagePart(malformedPart, 'schema_and_log') as ToolUIPart).output).toBe(
+ INVALID_NOTEBOOK_RUN_OUTPUT_MESSAGE
+ )
+ })
+
test('messages are sanitized at disabled level', () => {
const messages = [
createAssistantMessageWithExecuteSqlTool('SELECT email FROM users', [
diff --git a/apps/studio/lib/ai/tools/tool-sanitizer.ts b/apps/studio/lib/ai/tools/tool-sanitizer.ts
index 766bdd0dbe1..44c54d17a6c 100644
--- a/apps/studio/lib/ai/tools/tool-sanitizer.ts
+++ b/apps/studio/lib/ai/tools/tool-sanitizer.ts
@@ -1,6 +1,7 @@
import type { ToolUIPart, UIMessage } from 'ai'
import type { ToolName } from '../tool-filter'
+import { sanitizeNotebookRunOutput } from './notebook-run-output'
import type { AiOptInLevel } from '@/hooks/misc/useOrgOptedIntoAi'
interface ToolSanitizer {
@@ -47,9 +48,18 @@ const updateNotebookSanitizer: ToolSanitizer = {
},
}
+const runNotebookSanitizer: ToolSanitizer = {
+ toolName: 'run_notebook',
+ sanitize: (tool, optInLevel) => ({
+ ...tool,
+ output: sanitizeNotebookRunOutput(tool.output, optInLevel),
+ }),
+}
+
export const ALL_TOOL_SANITIZERS = {
[executeSqlSanitizer.toolName]: executeSqlSanitizer,
[updateNotebookSanitizer.toolName]: updateNotebookSanitizer,
+ [runNotebookSanitizer.toolName]: runNotebookSanitizer,
}
export function sanitizeMessagePart(