Files
supabase/apps/studio/data/content/notebooks/notebook-upsert-mutation.ts
Charis ddb3e2c442 feat(studio): create_notebook AI tool (#48938)
## Summary
- Adds a `create_notebook` AI assistant tool (`needsApproval: true`)
that lets the assistant create a new notebook after explicit user
approval.
- Cell SQL is promoted from untrusted to safe via
`acceptUntrustedSql`/`acceptUntrustedLogsSql` inside `execute`, using
the approval gate as the confirming user gesture (same pattern as
`execute_sql`).
- Input is validated against the existing agent-writable notebook
schema, which rejects any agent-supplied cell `id` at the schema level.
- Threads an optional auth-headers param through
`upsertContent`/`createNotebook`/`updateNotebook` so the tool can pass
its own bearer token server-side.
- Registers the tool in the tool-filter (`SCHEMA` category, alongside
`list_notebooks`/`get_notebook`) and adds a `## Notebooks` prompt
section guiding the assistant on when to use `create_notebook` vs.
one-off `execute_sql`.

Resolves FE-4082

## Test plan
- [x] `notebook-tools.test.ts` covers: tool registration,
`needsApproval`, cell-id rejection, valid input, PUT body shape, and the
returned id — all passing
- [x] Typecheck clean
- [x] Lint clean (no new warnings)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added AI-assisted notebook creation for saving multi-step
investigations.
* Added support for database and log SQL cells in newly created
notebooks.
* Notebook creation requires approval before saving and returns the
notebook’s name and identifier.
* Added support for custom request headers during notebook and content
operations.
* Added guidance for choosing between one-time SQL execution and
reusable notebooks when Explorer is enabled.

* **Improvements**
* Improved validation and normalization of notebook content before
saving.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
2026-08-11 11:54:49 -04:00

147 lines
4.3 KiB
TypeScript

import { useMutation, useQueryClient } from '@tanstack/react-query'
import { toast } from 'sonner'
import { upsertContent, type UpsertContentPayload } from '../content-upsert-mutation'
import { contentKeys } from '../keys'
import { writableNotebookSchema, type WritableNotebook } from './notebook-schema'
import type { ResponseError, UseCustomMutationOptions } from '@/types'
// TODO — Charis 2026-08-06
// UpsertContentPayload['type'] (generated from api-types) doesn't have 'notebook' yet — same
// gap tracked by the ContentBase TODO in content-query.ts. Widen locally and cast at the
// upsertContent call site until the generated type picks it up.
type NotebookUpsertPayload = Omit<UpsertContentPayload, 'type' | 'content'> & {
type: 'notebook'
content: WritableNotebook
}
function buildNotebookUpsertPayload({
id,
name,
description,
content,
}: {
id: string
name: string
description?: string
content: WritableNotebook
}): NotebookUpsertPayload {
writableNotebookSchema.parse(content)
return {
id,
name,
description,
type: 'notebook',
visibility: 'project',
content,
}
}
export type CreateNotebookVariables = {
projectRef: string
name: string
description?: string
content: WritableNotebook
}
export async function createNotebook(
{ projectRef, name, description, content }: CreateNotebookVariables,
signal?: AbortSignal,
headersInit?: HeadersInit
) {
const id = crypto.randomUUID()
const payload = buildNotebookUpsertPayload({ id, name, description, content })
await upsertContent(
{ projectRef, payload: payload as unknown as UpsertContentPayload },
signal,
headersInit
)
return { id }
}
export type CreateNotebookData = Awaited<ReturnType<typeof createNotebook>>
export type UpdateNotebookVariables = CreateNotebookVariables & { id: string }
export async function updateNotebook(
{ projectRef, id, name, description, content }: UpdateNotebookVariables,
signal?: AbortSignal,
headersInit?: HeadersInit
) {
const payload = buildNotebookUpsertPayload({ id, name, description, content })
return upsertContent(
{ projectRef, payload: payload as unknown as UpsertContentPayload },
signal,
headersInit
)
}
export type UpdateNotebookData = Awaited<ReturnType<typeof updateNotebook>>
export const useCreateNotebookMutation = ({
onError,
onSuccess,
...options
}: Omit<
UseCustomMutationOptions<CreateNotebookData, ResponseError, CreateNotebookVariables>,
'mutationFn'
> = {}) => {
const queryClient = useQueryClient()
return useMutation<CreateNotebookData, ResponseError, CreateNotebookVariables>({
mutationFn: (args) => createNotebook(args),
async onSuccess(data, variables, context) {
const { projectRef } = variables
await Promise.all([
queryClient.invalidateQueries({ queryKey: contentKeys.allContentLists(projectRef) }),
queryClient.invalidateQueries({ queryKey: contentKeys.infiniteList(projectRef) }),
])
await onSuccess?.(data, variables, context)
},
async onError(error, variables, context) {
if (onError === undefined) {
toast.error(`Failed to create notebook: ${error.message}`)
} else {
onError(error, variables, context)
}
},
...options,
})
}
export const useUpdateNotebookMutation = ({
onError,
onSuccess,
...options
}: Omit<
UseCustomMutationOptions<UpdateNotebookData, ResponseError, UpdateNotebookVariables>,
'mutationFn'
> = {}) => {
const queryClient = useQueryClient()
return useMutation<UpdateNotebookData, ResponseError, UpdateNotebookVariables>({
mutationFn: (args) => updateNotebook(args),
async onSuccess(data, variables, context) {
const { projectRef, id } = variables
await Promise.all([
queryClient.invalidateQueries({ queryKey: contentKeys.allContentLists(projectRef) }),
queryClient.invalidateQueries({ queryKey: contentKeys.infiniteList(projectRef) }),
queryClient.invalidateQueries({ queryKey: contentKeys.resource(projectRef, id) }),
])
await onSuccess?.(data, variables, context)
},
async onError(error, variables, context) {
if (onError === undefined) {
toast.error(`Failed to update notebook: ${error.message}`)
} else {
onError(error, variables, context)
}
},
...options,
})
}