feat: add "Ask AI on a block" popover for block-document blocks - #798

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

packages/ai-config/src/createBlockContextItem.ts (1)

16-32: 🗄️ Data Integrity & Integration | 🔵 Trivial | ⚡ Quick win

Export a typed block item variant here. AiRunContextItem only covers the base fields, so the block-specific keys added in this factory stay untyped through the public API. Extending the schema or exporting a BlockAiRunContextItem type would make those fields safe for consumers.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/ai-config/src/createBlockContextItem.ts` around lines 16 - 32, The
block item factory is returning block-specific fields that are not represented
in the public type, so consumers only see the base AiRunContextItem shape.
Update createBlockContextItem and the related schema/types to expose a typed
block variant, such as a BlockAiRunContextItem, and ensure the block-specific
keys like blockDocumentId, blockId, blockType, subtitle, blockInstanceId, and
panelId are included in the exported type/schema used by
AiRunContextItemSchema.parse.

apps/sqlrooms-cli-ui/src/createCliBlockDocumentAiAdapter.ts (1)

42-46: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Error message says "worksheet block" instead of generic block-document terminology.

Rest of the migration renames worksheet-scoped naming to block-document terminology; this thrown error text is a leftover.

✏️ Suggested wording

         throw new Error(
           result.error ??
             result.message ??
-            'Failed to update worksheet block.',
+            'Failed to update block document block.',
         );

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/sqlrooms-cli-ui/src/createCliBlockDocumentAiAdapter.ts` around lines 42
- 46, The thrown error in createCliBlockDocumentAiAdapter still uses
worksheet-specific wording, which is inconsistent with the block-document
migration. Update the fallback message in the error handling path that throws
from result.error/result.message so it uses generic block-document terminology
instead of “worksheet block,” and keep the change localized to the
createCliBlockDocumentAiAdapter flow.

apps/sqlrooms-cli-ui/src/__tests__/createCliBlockDocumentAiAdapter.test.ts (1)

8-8: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add coverage for the new updateBlock adapter method.

The suite covers addBlock success/failure but not the newly added updateBlock (success path invoking block-document.update-block, and failure path throwing on result.success === false).

As per coding guidelines, "Add or update tests when changing behavior or public API, when practical."

Also applies to: 53-56, 89-89

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/sqlrooms-cli-ui/src/__tests__/createCliBlockDocumentAiAdapter.test.ts`
at line 8, Add test coverage in createCliBlockDocumentAiAdapter.test for the new
updateBlock method on createCliBlockDocumentAiAdapter, covering both the success
path where it invokes block-document.update-block and the failure path where it
throws when result.success is false. Mirror the existing addBlock test patterns
so the new adapter behavior is asserted consistently, and make sure the new
cases are added alongside the current createCliBlockDocumentAiAdapter suite.

Source: Coding guidelines

apps/sqlrooms-cli-ui/src/ai/createCliBlockDocumentAiTools.ts (1)

152-160: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Minor: map guidance in usageHint doesn't name the actual tool.

The html-app branch names the concrete tool (${KnownBlockDocumentTools.add_html_app_block}), but the map branch just says "a direct worksheet map tool when available" instead of referencing ${KnownBlockDocumentTools.create_block_document_map_block}. Since that constant already exists, using it here would keep the guidance consistent and reduce ambiguity for the agent.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/sqlrooms-cli-ui/src/ai/createCliBlockDocumentAiTools.ts` around lines
152 - 160, The map guidance in createCliBlockDocumentAiTools’s usageHint is too
vague because it does not name the concrete map tool. Update the map branch so
it references KnownBlockDocumentTools.create_block_document_map_block
explicitly, matching the style used for embedded_html_app_agent and
add_html_app_block, and keep the rest of the usageHint wording unchanged.

apps/sqlrooms-cli-ui/src/ai/createCliBlockDocumentAgentTool.ts (3)

290-317: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Same identifier reused for both the schema value and its inferred type.

BlockDocumentAgentInputSchema is declared as a const (the zod schema) and then re-declared as a type via z.infer<typeof BlockDocumentAgentInputSchema> (line 315-317). This is legal TypeScript since types and values live in separate namespaces, but reusing the exact same name for both is easy to misread at call sites like BlockDocumentAgentInputSchema['targetBlock'] (a type position). A distinct name for the inferred type (e.g. BlockDocumentAgentInput) would improve readability.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/sqlrooms-cli-ui/src/ai/createCliBlockDocumentAgentTool.ts` around lines
290 - 317, The schema value and inferred type currently share the same
identifier, which makes `BlockDocumentAgentInputSchema` hard to read and easy to
confuse in type positions. Rename the inferred `z.infer<typeof
BlockDocumentAgentInputSchema>` alias to a distinct type name such as
`BlockDocumentAgentInput`, and update any references in
`createCliBlockDocumentAgentTool` that use the inferred type so the schema
constant and type are clearly separated.

---

415-423: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Hardcoded tool name instead of constant reference.

Line 419 hardcodes the literal string create_block_document_map_block instead of interpolating ${KnownBlockDocumentTools.create_block_document_map_block} like every other tool reference in this description (including the line right above it). Functionally harmless today since the constant's value matches, but it will silently go stale if the tool key is ever renamed.

🔧 Proposed fix

     ? `1. For a new map, call ${KnownBlockDocumentTools.create_block_document_map_block} directly
-2. For an existing map, call ${KnownBlockDocumentTools.list_blocks} and pass statefulBlock.blockInstanceId as mapId to create_block_document_map_block`
+2. For an existing map, call ${KnownBlockDocumentTools.list_blocks} and pass statefulBlock.blockInstanceId as mapId to ${KnownBlockDocumentTools.create_block_document_map_block}`

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/sqlrooms-cli-ui/src/ai/createCliBlockDocumentAgentTool.ts` around lines
415 - 423, The MAP worksheet guidance in createCliBlockDocumentAgentTool uses a
hardcoded tool name for the existing-map case, which can drift from the source
constant. Update the string in the map-block instructions to reference
KnownBlockDocumentTools.create_block_document_map_block consistently in both
branches, matching the other tool references in this block so the prompt stays
aligned if the tool key changes.

---

453-462: 🎯 Functional Correctness | 🔵 Trivial | 💤 Low value

Validation error message is discarded in the friendly output on failure.

When the blockInstanceId guard throws (a plain Error, not AiAgentError), the catch block collapses finalOutput to the generic 'Worksheet update failed.' even though the thrown message is a precise, actionable diagnostic (e.g. "dashboard block X is missing blockInstanceId."). The detail is preserved in error, but if finalOutput is what's surfaced to the end user/chat, this specific failure mode becomes indistinguishable from any other error.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/sqlrooms-cli-ui/src/ai/createCliBlockDocumentAgentTool.ts` around lines
453 - 462, The blockInstanceId validation in createCliBlockDocumentAgentTool is
throwing a plain Error with a useful diagnostic, but the catch path turns the
user-facing finalOutput into the generic failure text. Update the failure
handling around the try/catch so the specific validation message from the thrown
error is preserved in finalOutput when the error is not an AiAgentError, while
still keeping the existing fallback for truly generic failures; use the
createCliBlockDocumentAgentTool flow and the targetBlock guard as the key
locations to adjust.

apps/sqlrooms-cli-ui/src/ai/__tests__/createCliBlockDocumentAiTools.test.ts (1)

1-140: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Missing coverage for targetBlockId chart-editing wiring.

This test suite covers the rename, move_block, and HTML-app-block behavior, but doesn't exercise the new targetBlockId parameter that createCliBlockDocumentAiTools now forwards to createBlockDocumentChartTools for in-place chart edits. A quick test asserting createBlockDocumentChartTools/chartTools receive targetBlockId when supplied would guard this new capability against regressions.
As per coding guidelines, **/*.{js,ts,jsx,tsx}: "Add or update tests when changing behavior or public API, when practical."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/sqlrooms-cli-ui/src/ai/__tests__/createCliBlockDocumentAiTools.test.ts`
around lines 1 - 140, Add test coverage for the new targetBlockId wiring in
createCliBlockDocumentAiTools. Update the test setup to pass a targetBlockId
through createOptions and assert that createBlockDocumentChartTools (and the
returned chartTools path) receives it when chart tools are created. Use the
existing createCliBlockDocumentAiTools and createOptions helpers, plus the
chartTools/createBlockDocumentChartTools symbols, so the in-place chart editing
behavior is guarded against regressions.

Source: Coding guidelines

apps/sqlrooms-cli-ui/src/createBlockDocumentAgent.ts (1)

218-229: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Tight coupling between extraTools gating and the outer experimentalEnabled flag.

extraTools checks the closure-captured experimentalEnabled rather than the htmlAppBlocksEnabled/mapBlocksEnabled values threaded into blockDocumentAgentOptions. Today they're always equal (htmlAppBlocksEnabled: experimentalEnabled, mapBlocksEnabled: experimentalEnabled), so there's no active bug, but if these two flags are ever decoupled (e.g., enabling maps without enabling HTML apps), extraTools would silently provide/withhold the wrong tool set relative to what getBlockDocumentAgentInstructions/selectTargetBlockTools expect.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/sqlrooms-cli-ui/src/createBlockDocumentAgent.ts` around lines 218 - 229,
The extraTools gating is too tightly coupled to the outer experimentalEnabled
flag instead of the blockDocumentAgentOptions feature flags. Update
createBlockDocumentAgent so extraTools decides which tools to expose based on
the same htmlAppBlocksEnabled and mapBlocksEnabled values used by
getBlockDocumentAgentInstructions and selectTargetBlockTools, rather than
assuming they always match experimentalEnabled. Keep the tool map in sync with
those flags so each tool is included or omitted independently and future flag
decoupling does not change behavior unexpectedly.

apps/sqlrooms-cli-ui/src/store.ts (1)

180-187: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Drop blockDocumentAgentToolName from BLOCK_DOCUMENT_OPTIONS unless it’s wired into the command factory; it isn’t consumed anywhere and reads as dead config.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/sqlrooms-cli-ui/src/store.ts` around lines 180 - 187, Remove the unused
blockDocumentAgentToolName entry from BLOCK_DOCUMENT_OPTIONS in store.ts unless
it is actually passed through the command factory; the current constant only
defines dead config. Check the BLOCK_DOCUMENT_OPTIONS object and any related
command creation path to confirm nothing consumes
CLI_BLOCK_DOCUMENT_AGENT_TOOL_NAME, and keep the options object limited to
values that are wired into the worksheet/block-document setup.

packages/documents/src/BlockDocumentStatefulBlockRendererContext.tsx (2)

29-40: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Missing tsdoc on new exported types/hook.

BlockDocumentBlockHeaderActionsRenderContext, BlockDocumentBlockHeaderActionsRenderer, and useBlockDocumentRenderBlockHeaderActions are all new public exports without tsdoc.

As per coding guidelines, "Add tsdoc to exported types and functions in @sqlrooms/* packages."

Also applies to: 124-128

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/documents/src/BlockDocumentStatefulBlockRendererContext.tsx` around
lines 29 - 40, Add tsdoc for the new public exports in
BlockDocumentStatefulBlockRendererContext: document
BlockDocumentBlockHeaderActionsRenderContext and
BlockDocumentBlockHeaderActionsRenderer, and also add tsdoc to
useBlockDocumentRenderBlockHeaderActions. Make the comments describe the purpose
of each export and its parameters/shape so the API is documented consistently
with other `@sqlrooms` exports.

Source: Coding guidelines

---

29-40: 🎯 Functional Correctness | 🔵 Trivial | 💤 Low value

Deduplicate the shared header-actions types

BlockDocumentBlockHeaderActionsRenderContext and BlockDocumentBlockHeaderActionsRenderer are duplicated in both renderer-context files. Extract them into a shared module so the shape stays in sync across chart and stateful block renderers.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/documents/src/BlockDocumentStatefulBlockRendererContext.tsx` around
lines 29 - 40, The header-actions context and renderer types are duplicated
across the renderer-context files, so move
BlockDocumentBlockHeaderActionsRenderContext and
BlockDocumentBlockHeaderActionsRenderer into a shared module and update both the
chart and stateful block renderer contexts to import them. Keep the shared
definitions as the single source of truth so both callers use the same shape
without drifting.

apps/sqlrooms-cli-ui/src/context/formatRunContextInstructions.ts (1)

82-119: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Consider unit tests for the new block-context formatting branches.

formatBlockContextInstructions has distinct branches (unresolved/deleted block vs. resolved, plus type-specific delegation text for dashboard/html-app/map/chart) that aren't covered by any provided tests.

As per coding guidelines, "Add or update tests when changing behavior or public API, when practical."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/sqlrooms-cli-ui/src/context/formatRunContextInstructions.ts` around
lines 82 - 119, Add unit tests for formatBlockContextInstructions to cover both
branches: unresolved/deleted blocks returning the “Target block is unresolved or
deleted” message, and resolved blocks returning the “Target block” message with
artifact title and instanceId. Also add type-specific assertions for the
dashboard, HTML app, map, and chart delegation text so the new behavior in
formatBlockContextInstructions is locked down.

Source: Coding guidelines

apps/sqlrooms-cli-ui/src/ai/startBlockScopedChat.ts (1)

1-67: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add unit tests for the new session-orchestration flow.

This file introduces non-trivial branching (missing artifact, session reuse vs creation, session-creation failure, analysis-start timeout) with no accompanying tests, unlike the sibling packages called out as tested in the PR description.

As per coding guidelines, "Add or update tests when changing behavior or public API, when practical."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/sqlrooms-cli-ui/src/ai/startBlockScopedChat.ts` around lines 1 - 67, Add
unit tests for startBlockScopedChat to cover the new session-orchestration
branches: missing/non-worksheet artifact, existing session reuse, new session
creation, session creation failure, and analysis-start timeout. Mock
useRoomStore, findAiSessionForArtifactWithContextItem, toast, and
revealAssistant so you can assert the correct calls and early returns without
relying on real state. Focus the tests around startBlockScopedChat and the
session/artifact store interactions to match the behavior introduced here.

Source: Coding guidelines

apps/sqlrooms-cli-ui/src/components/useAssistantContextItems.ts (2)

13-27: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Missing test coverage for the new block-context selection/validation logic.

This adds substantial new behavior — deriving BlockAiTargets from document nodes, building block-kind selector items, and validating selected block context ids against live document content — with no accompanying test updates in this cohort. As per coding guidelines, **/*.{js,ts,jsx,tsx} changes should add or update tests when changing behavior or public API, when practical.

Also applies to: 36-71, 105-108, 144-174, 189-191, 205-214, 223-223, 245-257

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/sqlrooms-cli-ui/src/components/useAssistantContextItems.ts` around lines
13 - 27, Add or update tests for the new block-context behavior in
useAssistantContextItems: cover deriving BlockAiTarget values from
blockDocumentNodeToBlock, building block-kind selector items in
getAssistantContextItems, and validating selected block ids against current
document content in the useMemo/useRoomStore flow. Add cases for
parseBlockContextItemId, blockContextItemId, and defaultBlockTitle handling so
the selection/filtering logic is verified when document nodes or artifact types
change.

Source: Coding guidelines

---

245-257: 🚀 Performance & Scalability | 🔵 Trivial | ⚡ Quick win

Full node→block conversion on every validation check is wasteful.

For each selected block context id, this validates by calling blockDocumentNodeToBlock(node) (which does a full zod safeParse per node type) over every node in the document just to compare block?.id === blockContext.blockId. This recomputes inside useMemo whenever blockDocuments changes (i.e. on every document edit), and scales as O(selectedIds * nodeCount) with repeated zod parsing overhead that isn't needed for a simple id lookup.

♻️ Suggested direction

Expose a lightweight id-only lookup (e.g. reuse the internal nodeId(node) helper from packages/documents/src/BlockDocumentSliceConfig.ts instead of the full blockDocumentNodeToBlock conversion) so validation doesn't pay for full schema parsing on every node.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/sqlrooms-cli-ui/src/components/useAssistantContextItems.ts` around lines
245 - 257, The block-context validation in useAssistantContextItems is doing
full blockDocumentNodeToBlock conversion for every node just to compare ids,
which is too expensive. Replace that scan with a lightweight id-only lookup
using the existing nodeId helper from BlockDocumentSliceConfig (or an equivalent
internal id accessor) so the useMemo check avoids zod parsing. Keep the logic in
the blockContext branch and ensure the comparison still matches
blockContext.blockId against the node’s id without materializing full blocks.

apps/sqlrooms-cli-ui/src/context/getRunContext.ts (1)

91-96: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Avoid double-parsing the matched node.

blockDocumentNodeToBlock is called once per candidate inside .find, then re-called on the matched node to obtain block. Consider tracking the parsed block during the search to skip the redundant re-parse.

♻️ Proposed refactor

-  const node = blockDocument?.content.content.find((candidate) => {
-    const block = blockDocumentNodeToBlock(candidate);
-    return block?.id === parsedId.blockId;
-  });
-  const block = node ? blockDocumentNodeToBlock(node) : undefined;
-  if (!block) return undefined;
+  let block: ReturnType<typeof blockDocumentNodeToBlock> | undefined;
+  for (const candidate of blockDocument?.content.content ?? []) {
+    const candidateBlock = blockDocumentNodeToBlock(candidate);
+    if (candidateBlock?.id === parsedId.blockId) {
+      block = candidateBlock;
+      break;
+    }
+  }
+  if (!block) return undefined;

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/sqlrooms-cli-ui/src/context/getRunContext.ts` around lines 91 - 96, The
matching logic in getRunContext currently parses each candidate with
blockDocumentNodeToBlock inside the find callback and then parses the winning
node again afterward. Refactor this blockId lookup to reuse the parsed block
from the search phase so the matched candidate is not decoded twice; keep the
behavior the same by returning or storing the parsed Block alongside the node
and using that value directly when setting block.

packages/ai-core/src/components/BlockAiPromptPopover.tsx (1)

1-149: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add tests for the new BlockAiPromptPopover public component.

This is a new exported component (from @sqlrooms/ai-core, re-exported via @sqlrooms/ai) with non-trivial interactive behavior (Enter-to-submit, Escape-to-close, disabled/running guards, controlled/uncontrolled open state). The PR description only confirms tests passing for @sqlrooms/documents, @sqlrooms/ai-config, and @sqlrooms/artifacts — not @sqlrooms/ai-core. Consider adding RTL-based tests covering submit-on-Enter, no-submit-on-Shift+Enter, Escape-to-close, and disabled/running states.

Do you want me to draft a test file for this component?

As per coding guidelines, "Add or update tests when changing behavior or public API, when practical."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/ai-core/src/components/BlockAiPromptPopover.tsx` around lines 1 -
149, Add RTL coverage for the new public BlockAiPromptPopover component so its
interactive behavior is verified in `@sqlrooms/ai-core`. Create tests around
BlockAiPromptPopover for submit-on-Enter, no submit on Shift+Enter, Escape
closing the popover, and disabled/isRunning guards, including both controlled
and uncontrolled open state paths. Use the component’s key symbols
(BlockAiPromptPopover, handleSubmit, handleKeyDown, setOpen) to locate the
behavior and assert the trigger, textarea, and submit button wiring works as
intended.

Source: Coding guidelines

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

packages/ai-config/src/createBlockContextItem.ts (1)

1-41: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Missing tsdoc on exported schema/type/function.

BlockAiRunContextItemSchema, BlockAiRunContextItem, and createBlockContextItem are all exported public API from this @sqlrooms/* package but have no tsdoc comments.

As per coding guidelines, "Add tsdoc to exported types and functions in @sqlrooms/* packages."

📝 Proposed tsdoc additions

+/**
+ * Schema for a run-context item that targets a specific block within a block document.
+ */
 export const BlockAiRunContextItemSchema = AiRunContextItemSchema.extend({
   kind: z.literal('block'),
   blockDocumentId: z.string(),
   blockId: z.string(),
   blockType: z.string(),
   blockInstanceId: z.string().optional(),
   panelId: z.string().optional(),
 });

+/** Inferred type for a block-scoped AI run-context item. */
 export type BlockAiRunContextItem = z.infer<typeof BlockAiRunContextItemSchema>;

+/**
+ * Constructs and validates a block-scoped AI run-context item.
+ */
 export function createBlockContextItem(fields: {

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/ai-config/src/createBlockContextItem.ts` around lines 1 - 41, Add
tsdoc comments for the exported public API in createBlockContextItem.ts:
BlockAiRunContextItemSchema, BlockAiRunContextItem, and createBlockContextItem.
Describe what each schema/type/function represents and the key fields/behavior
so the generated docs align with the `@sqlrooms/`* guideline for exported types
and functions.

Source: Coding guidelines

apps/sqlrooms-cli-ui/src/ai/createCliBlockDocumentAgentTool.ts (1)

543-552: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Redundant AiAgentError branch — both arms return the same value.

error instanceof AiAgentError ? errorMessage : error instanceof Error ? errorMessage : ... returns errorMessage in both the AiAgentError and generic Error cases (and AiAgentError presumably extends Error), so the extra check is dead weight.

♻️ Simplify

-        const friendlyMessage =
-          error instanceof AiAgentError
-            ? errorMessage
-            : error instanceof Error
-              ? errorMessage
-              : 'Worksheet update failed.';
+        const friendlyMessage =
+          error instanceof Error ? errorMessage : 'Worksheet update failed.';

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/sqlrooms-cli-ui/src/ai/createCliBlockDocumentAgentTool.ts` around lines
543 - 552, The friendly message selection in createCliBlockDocumentAgentTool is
redundant because the AiAgentError branch and the generic Error branch both
return the same value. Simplify the catch block by removing the AiAgentError
instanceof check and keep a single Error case that uses errorMessage, with the
fallback message only for non-Error values.

packages/documents/src/BlockDocumentStatefulBlockRendererContext.tsx (1)

49-49: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Add tsdoc for new header-actions fields.

hasOwnHeaderActions, the context's renderBlockHeaderActions, and the provider prop of the same name lack doc comments, unlike the new useBlockDocumentRenderBlockHeaderActions() hook which is documented. As per coding guidelines, "Add tsdoc to exported types and functions in @sqlrooms/* packages."

Also applies to: 59-59, 72-77

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/documents/src/BlockDocumentStatefulBlockRendererContext.tsx` at line
49, Add TSDoc for the new header-actions API surface in
BlockDocumentStatefulBlockRendererContext: document the exported
hasOwnHeaderActions field, the renderBlockHeaderActions context property, and
the matching provider prop so they match the style of
useBlockDocumentRenderBlockHeaderActions(). Update the relevant exported
type/interface and provider declaration in
BlockDocumentStatefulBlockRendererContext.tsx, keeping the comments concise and
aligned with the existing documentation conventions for `@sqlrooms/`* exports.

Source: Coding guidelines

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

packages/mosaic/src/dashboard/MosaicDashboard.tsx (1)

29-33: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Missing tsdoc on headerActions (inconsistent with sibling type in this file).

MosaicDashboardProps.headerActions (Line 143) has a doc comment, but MosaicDashboardRootProps.headerActions here does not.

As per coding guidelines, "Add tsdoc to exported types and functions in @sqlrooms/* packages."

📝 Proposed fix

 export type MosaicDashboardRootProps = PropsWithChildren<{
   dashboardId: string;
   readOnly?: boolean;
+  /** Actions rendered at the end of the dashboard toolbar. */
   headerActions?: ReactNode;
 }>;

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/mosaic/src/dashboard/MosaicDashboard.tsx` around lines 29 - 33, Add
tsdoc for the exported MosaicDashboardRootProps.headerActions field to match the
documented sibling prop in MosaicDashboardProps. Update the
MosaicDashboardRootProps type near the headerActions declaration in
MosaicDashboard.tsx so the exported type complies with the `@sqlrooms/`* tsdoc
guideline and stays consistent with the rest of the file.

Source: Coding guidelines

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

packages/ai-core/src/components/context/types.ts (1)

53-54: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Missing tsdoc for new exported prop fields.

side and avoidCollisions are added to the exported ContextSelectorSearchDropdownProps without documentation comments.

As per coding guidelines, "Add tsdoc to exported types and functions in @sqlrooms/* packages."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/ai-core/src/components/context/types.ts` around lines 53 - 54, Add
tsdoc comments for the newly exported ContextSelectorSearchDropdownProps fields
so they comply with the `@sqlrooms` documentation guideline. Update the type
definition in types.ts to document both side and avoidCollisions with brief
descriptions, keeping the comments alongside the existing prop declarations and
matching the style used for other exported types in this package.

Source: Coding guidelines

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".