Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.gitignore:
- Around line 1-38: The .gitignore contains duplicated entries (e.g., repeated
lines like "!packages/**/*.png", ".DS_Store", ".env", ".npmrc", ".pnpm-store",
".qlty/*", "*.png", "*.tsbuildinfo", "coverage", "dist", "examples/report.md",
snapshot patterns, and "node_modules")—remove the duplicate lines so each ignore
pattern appears only once; edit the .gitignore to deduplicate all identical
lines (keeping a single canonical occurrence of each pattern) and ensure negated
patterns (like !packages/**/*.png) remain correctly placed and not duplicated.

In `@cspell.json`:
- Line 73: Move the "agentic" entry in cspell.json to the proper alphabetical
position: remove the duplicate at its current location and insert "agentic"
before "Instantiator" (and therefore before "asname") so the list remains
alphabetized; update the array to contain "agentic" only in its correct spot.

In `@packages/blocks/src/deepnote-file/llm-block-schema.test.ts`:
- Around line 31-45: The test object passed to deepnoteFileSchema.safeParse is
missing required top-level fields "environment" and "execution", causing
spurious failures; update the object in llm-block-schema.test.ts (the one
assigned to result) to include minimal valid "environment" and "execution"
entries that match deepnoteFileSchema (e.g., provide the minimal shapes expected
by the schema such as an environment object and an execution object/array or
their empty/default forms) so the safeParse covers the intended fields without
failing for missing top-level properties.

In `@packages/cli/package.json`:
- Around line 57-58: Update the package.json dependency entry for "marked" from
"^15.0.12" to "^17.0.3" (the dependency key is "marked") and then run your
package manager (npm install or yarn install) to refresh lockfile and
node_modules; verify no breaking changes by running the test suite or a quick
markdown rendering check after installing.

In `@packages/cli/src/commands/run.ts`:
- Around line 998-1004: The call to marked.use(markedTerminal()) is mutating
global marked state on every block completion inside the llmStreamed handling;
move the initialization so it runs once (e.g., at module top-level or inside
runDeepnoteProject before streaming begins) instead of inside the callback that
checks llmStreamed and llmTextBuffer. Locate the marked.use(markedTerminal())
invocation near the llmStreamed/llmTextBuffer block and remove it from the
callback; add a single initialization call for marked.use(markedTerminal()) near
the module initialization or at the start of runDeepnoteProject so that
marked.parse(llmTextBuffer) can be used without repeatedly mutating state.
Ensure markedTerminal is still imported where used.

In `@packages/mcp/src/tools/writing.ts`:
- Around line 413-417: The code computes a boolean `candidate` by checking
`spec.type` against a hardcoded list; this duplicates logic from
`@deepnote/runtime-core`. Replace the inline list and startsWith checks with the
shared exported set `executableBlockTypeSet` (and any helper like
`isExecutableBlockType` if available) so `candidate` is determined by checking
membership in `executableBlockTypeSet` and preserving the `input-` prefix rule
if that isn't covered by the shared symbol; update references to `spec.type`,
`candidate`, and import `executableBlockTypeSet` from `@deepnote/runtime-core` to
ensure consistency.

In `@packages/runtime-core/src/execution-engine.ts`:
- Around line 183-188: The code currently records blockIndex when building
allExecutableBlocks (the push that sets blockIndex) which can become stale after
earlier LLM insertions; instead stop storing a fixed blockIndex and resolve the
current index at execution/insertion time by using
notebook.blocks.indexOf(block) (or compute the target insertion position
relative to the current notebook.blocks array) right before inserting
LLM-generated blocks; update any usage of llmBlockIndex (the variable passed at
line ~224 and the similar code around 213-225) to recompute the index from the
live notebook.blocks array so generated blocks are inserted in the correct,
up-to-date location.

In `@packages/runtime-core/src/llm-handler.ts`:
- Around line 167-169: The current loop that calls mcpServers.forEach(await
server.connect()) runs outside the try/finally so if one connect() throws,
previously connected servers are never cleaned up; fix by either moving the
connect loop into the surrounding try block before the finally cleanup, or
explicitly track successfully connected servers (e.g., push to a
connectedServers array as each server.connect() resolves) and in the
catch/finally iterate that array to call the servers' cleanup method (the
existing close/disconnect code used later). Apply the same pattern to the other
connect sequence referenced around the 303-347 range.
- Around line 192-203: The DeepnoteBlock construction uses an unsafe "as any"
cast; replace it by explicitly typing the code block using Extract to preserve
the discriminated union (e.g., use Extract<DeepnoteBlock, { type: 'code' }> when
creating newBlock) and do the same for the markdown variant at the other site
(use Extract<DeepnoteBlock, { type: 'markdown' }>); update the object literals
(the one assigned to newBlock and the one around line ~281) so their shape
matches the Extract type (fields like id, blockGroup, sortingKey from
generateSortingKey(insertIndex), type, content, metadata, executionCount,
outputs for code blocks; the appropriate fields for markdown) and remove the "as
any" casts.

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@packages/cli/package.json`:
- Around line 57-58: The dependency "marked" currently set to a v17 range
conflicts with "marked-terminal" v7.3.0's peer constraint (requires <16); update
the "marked" entry in package.json to a compatible v15 (or any <16) release to
satisfy the peer dependency, then reinstall/update the lockfile (npm/yarn/pnpm)
and run the test/build to ensure nothing breaks; target the "marked" and
"marked-terminal" dependency entries when making the change.

In `@packages/cli/src/commands/run.ts`:
- Around line 274-279: The current branch silently no-ops when
file.project.notebooks is empty; update the logic in run.ts so when path &&
options.prompt and file.project.notebooks.length === 0 you either emit a clear
warning (e.g., processLogger.warn or console.warn) and then create a new
notebook and push the created LLM block into it, or throw a descriptive error;
use the existing createLlmBlock(...) to build the block and ensure you add a new
notebook object with a blocks array (containing the created block) to
file.project.notebooks instead of silently doing nothing (refer to lastNotebook,
file.project.notebooks, and createLlmBlock in your change).

In `@packages/runtime-core/src/llm-handler.ts`:
- Around line 38-40: The generateSortingKey function returns
lexicographic-unfriendly keys like "a1"/"a10" causing misordering; update
generateSortingKey(index: number) to emit fixed-width numeric keys by
zero-padding the index to a constant width (e.g. pad to 6 or more digits) so
lexicographic sorting preserves numeric order—adjust the padding width to
support your maximum expected inserts.
- Around line 52-84: The notebook serialization in llm-handler.ts currently
inlines every block and full outputs (loop over notebook.blocks,
collectedOutputs.get(block.id), pushing block.content and outputs into lines)
which can exceed token limits; fix by implementing bounded serialization: limit
the number of blocks processed (e.g., stop after MAX_BLOCKS), truncate
block.content to MAX_CHARS_PER_BLOCK with an explicit "[truncated]" marker, cap
output size by only including the first N output entries and first M
lines/characters per output (replace large HTML/image outputs with placeholders
like "[HTML output truncated]" or "[Image omitted]"), and ensure error/metadata
fields are stringified safely; add or use constants (MAX_BLOCKS,
MAX_CHARS_PER_BLOCK, MAX_OUTPUT_ENTRIES, MAX_OUTPUT_CHARS) and apply these
limits inside the for (const block of notebook.blocks) and outputs loop to
prevent unbounded growth.
- Around line 129-142: The code currently throws if OPENAI_API_KEY is missing
even when OPENAI_BASE_URL is set; change the guard to only require apiKey when
OPENAI_BASE_URL is not provided (i.e., if (!apiKey &&
!process.env.OPENAI_BASE_URL) throw ...). When creating the OpenAI client (new
OpenAI), pass a safe dummy apiKey when baseURL is present because the SDK
expects an apiKey parameter (e.g., apiKey || '' or a short placeholder) so the
constructor receives a value but real auth uses the custom base URL; keep
baseURL set from process.env.OPENAI_BASE_URL and leave setTracingDisabled(true)
unchanged.

---

Duplicate comments:
In @.gitignore:
- Around line 1-36: The .gitignore contains duplicated lines (e.g., repeated
entries like !packages/**/*.png, .DS_Store, .env, .npmrc, .pnpm-store, .qlty/*
directories, *.png, *.tsbuildinfo, coverage, dist, examples/report.md,
examples/snapshots/*_T*.snapshot.deepnote, node_modules) likely from a merge;
clean up the file by removing duplicate entries so each pattern appears only
once, leaving a single canonical copy of each ignore rule and preserving the
existing semantics/order.

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@packages/cli/src/commands/run.ts`:
- Around line 1003-1017: The current logic skips rendering final block outputs
when llmStreamed is set true for tool events but no text_delta arrives
(variables: llmStreamed, llmTextBuffer, result.outputs, renderOutput). Fix by
ensuring that after the streaming/text buffer handling you also render
result.outputs when they exist and haven't been printed: if llmStreamed is true
but llmTextBuffer is empty (or rendered was not written), iterate over
result.outputs and call renderOutput for each, and emit the trailing blank line
as done in the non-streamed branch; apply the same change to the other
equivalent block handling tool events so final outputs are never suppressed.
- Around line 248-253: The prompt-only run creates an in-memory convertedFile
with wasConverted: false which prevents materialization for --open; update the
convertedFile creation (where createPromptOnlyFile(...) is used and
convertedFile is assigned) to set wasConverted: true (or compute it from the
intent to open, e.g., options.open || true for prompt-only runs) so downstream
logic will write a temp file before upload/--open; ensure this change is applied
adjacent to the convertedFile assignment and consider using
absolutePath/workingDirectory as already computed so materialization succeeds
when isMachineOutput is false.
- Around line 193-208: The createLlmBlock function currently returns a
BlocksDeepnoteBlock and uses an unsafe "as any" cast; import the LlmBlock type
from "@deepnote/blocks", change the function signature to return LlmBlock (or
replace the return type with LlmBlock), remove the "as any" cast, and ensure the
constructed object matches the LlmBlock shape (id, blockGroup, sortingKey, type:
'llm', content, metadata, executionCount, outputs); adjust any property names if
needed so TypeScript accepts the object as LlmBlock without coercion.

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@packages/cli/src/commands/run.ts`:
- Around line 472-474: The debug output currently prints safeOptions but only
masks token, exposing options.prompt; update the creation of safeOptions in
run.ts (where debug is called and safeOptions is built) to also redact any
prompt content by replacing options.prompt (and any similarly named prompt field
if present) with a placeholder like '[redacted]' before JSON.stringify; ensure
you still spread the rest of options so nothing else changes and keep using the
debug(`Options: ${JSON.stringify(safeOptions)}`) call.
- Around line 273-279: The code currently always uses lastNotebook to append the
created LLM block, causing prompts passed with --notebook to be added to the
wrong notebook; update the logic in the run command to pick the target notebook
based on the provided options.notebook (e.g., find the notebook from
file.project.notebooks by id or index matching options.notebook) and then call
createLlmBlock(options.prompt, targetNotebook.blocks.length) and push it into
targetNotebook.blocks; if options.notebook is provided but no matching notebook
is found, throw an explicit error (instead of falling back to the last notebook)
to prevent out-of-scope appends.

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@examples/demo-agent-block.deepnote`:
- Around line 91-95: Update the npx invocation to pin the MCP server package to
a specific safe release: replace the unpinned package reference
'@modelcontextprotocol/server-filesystem' used in the npx args with a versioned
package specifier such as '@modelcontextprotocol/[email protected]'
(or a newer secure release) so the runtime installs a known, patched version;
locate the invocation that includes npx and the args array containing
'@modelcontextprotocol/server-filesystem' and './examples' and update that
package token accordingly.

In `@packages/blocks/src/blocks/agent-blocks.test.ts`:
- Around line 5-75: Add a negative test that asserts deepnoteBlockSchema rejects
an agent block when MCP server config is malformed: call
deepnoteBlockSchema.safeParse with an agent block where
metadata.deepnote_mcp_servers contains an invalid entry (e.g., missing the
required name field or wrong type for command), then assert
expect(result.success).toBe(false) and check result.error.issues includes the
path to metadata.deepnote_mcp_servers[0].name (or the offending field) to ensure
validation fails for that field; add this as a new it() test alongside the
existing agent tests.

In `@packages/blocks/src/deepnote-file/deepnote-file-schema.ts`:
- Around line 272-274: The deepnote_max_iterations schema currently uses
z.number() which allows negatives and fractions; change the field definition for
deepnote_max_iterations to enforce a positive integer (e.g., use
z.number().int().min(1).default(10)) so only valid iteration counts are accepted
by the schema (update any tests/consumers that assume numeric type if needed).

In `@packages/cli/README.md`:
- Line 149: Update the `--prompt <text>` option description in the CLI README to
explicitly state that invoking this option will append or create an agent block
in the notebook (i.e., it mutates notebook state) rather than just “runs” an
agent block; locate the table entry for `--prompt <text>` in the README and
modify the right-hand description to include wording like “appends/creates an
agent block in the notebook (mutates notebook state); requires `OPENAI_API_KEY`”
so the side effect is clear.
- Around line 184-189: The README examples currently show inline secrets (the
commands containing "OPENAI_API_KEY=sk-... deepnote run my-project.deepnote
--prompt ..." and "OPENAI_API_KEY=sk-... deepnote run --prompt ..."); update
those examples to demonstrate exporting the key once (e.g., use a single-line
export instruction) and then run the deepnote run commands without embedding the
key, and add a brief note warning against pasting API keys into command history.

In `@packages/cli/src/commands/run.test.ts`:
- Around line 2536-2560: Add a new test case that uses setupSuccessfulRun(),
calls action(...) with a prompt containing quotes, newlines and unicode (e.g.
include " and \n and emojis) both for the in-memory path (undefined) and/or with
HELLO_WORLD_FILE, then assert mockRunProject was called once and inspect the
created file from mockRunProject.mock.calls[0] (same pattern as the existing
tests) to verify the last notebook block's type is 'agent' and its content
exactly matches the special-character prompt string; use the same helpers
(action, mockRunProject, setupSuccessfulRun, HELLO_WORLD_FILE) and assertions
style as the two existing tests to catch escaping/parsing regressions.

In `@packages/cli/src/commands/run.ts`:
- Around line 249-251: The synthetic prompt path uses process.cwd() instead of
the resolved execution cwd, so change the creation of absolutePath to use the
already-computed workingDirectory variable; update the expression that builds
absolutePath (used when constructing convertedFile with originalPath) to
join(workingDirectory, 'prompt.deepnote') so that --cwd is respected for
prompt-only synthetic paths (refer to variables absolutePath, workingDirectory,
convertedFile, file, originalPath).

---

Duplicate comments:
In `@packages/runtime-core/src/agent-handler.ts`:
- Around line 129-134: The current guard reads process.env.OPENAI_API_KEY into
apiKey and throws if missing, but the error text claims OPENAI_BASE_URL is an
alternative; change the guard to first check process.env.OPENAI_BASE_URL and
only require OPENAI_API_KEY when OPENAI_BASE_URL is not set (or allow a
placeholder key when base URL is provided if your SDK requires any value).
Update the throw to reference both variables clearly and modify the check around
the apiKey variable in agent-handler.ts (the apiKey constant and the thrown
Error) so the code path that uses OPENAI_BASE_URL is reachable and the message
accurately reflects the required configuration.

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@examples/demo-agent-block.deepnote`:
- Around line 80-94: Step 6 currently tells the agent to save the report as
`examples/report.md` which will be resolved relative to the filesystem MCP root
(already `./examples`) and produce `./examples/examples/report.md`; update the
instruction to write the file path relative to the MCP root (e.g., `report.md`
or `./report.md`) so the filesystem MCP tool saves the report at
`./examples/report.md`; ensure the task text referencing the filesystem MCP
server (metadata.deepnote_mcp_servers entry) and the step that calls the
filesystem MCP tool reflect this corrected relative path.

In `@packages/blocks/src/blocks/agent-blocks.test.ts`:
- Around line 42-70: The test 'parses agent block with MCP servers' currently
only asserts the MCP server name allowing regressions that drop other fields;
update the assertions after deepnoteBlockSchema.safeParse to also verify
deepnote_mcp_servers[0].command equals 'npx', deepnote_mcp_servers[0].args
equals ['-y','@modelcontextprotocol/server-postgres'], and
deepnote_mcp_servers[0].env.DATABASE_URL contains the '${DATABASE_URL}'
placeholder (or exact string), so the parser is validated to preserve command,
args, and env fields.

In `@packages/blocks/src/deepnote-file/agent-block-schema.test.ts`:
- Around line 29-49: The test currently only asserts the length of
project.settings.mcpServers after parsing with deepnoteFileSchema, which can
miss shape regressions; update the test to assert the parsed MCP entries' fields
(for example verify each entry's name, command, args, and env where provided)
against the expected values so the schema actually preserves command/args/env
(use deepnoteFileSchema.safeParse result.data.project.settings?.mcpServers and
assert entries equal or match the expected objects).

In `@packages/blocks/src/deepnote-file/deepnote-file-schema.ts`:
- Around line 253-258: The schema mcpServerSchema currently uses z.string() for
the name and command fields which allows empty or whitespace-only values; update
those fields to trim whitespace and enforce at least one character, e.g. replace
name: z.string() and command: z.string() with name: z.string().trim().min(1) and
command: z.string().trim().min(1) so blank or whitespace-only server
names/commands are rejected at validation time.

In `@packages/blocks/src/python-code.test.ts`:
- Around line 984-1000: Replace the duplicate happy-path test in the "Agent
blocks" suite with an edge-case that verifies createPythonCode handles special
characters; update the it(...) case that currently builds an AgentBlock (id
'123', type 'agent', content 'Analyze the data', metadata.deepnote_agent_model
'gpt-4o') to instead use an AgentBlock whose content contains special characters
(quotes, newlines, non-ASCII, and comment-like sequences) and assert
createPythonCode returns properly escaped/commented Python output; locate the
test inside the describe('Agent blocks') block and modify the AgentBlock fixture
and expected result to validate correct handling by createPythonCode.

In `@packages/runtime-core/src/agent-handler.ts`:
- Around line 12-21: AgentBlockContext currently lacks any working-directory
info so relative MCP roots like "./examples" are forwarded unchanged; add a
workingDirectory (string) field to AgentBlockContext and update the code paths
that forward/consume MCP roots (the handler that forwards roots and the code
referenced around the same area) to resolve relative roots against this
workingDirectory using path.resolve(workingDirectory, root) (leave absolute
paths untouched). Ensure the new workingDirectory is threaded through wherever
AgentBlockContext is constructed so consumers use the resolved absolute paths.
- Around line 190-199: The created code block (newBlock) is never updated with
the agent execution results, so newBlock.outputs and newBlock.executionCount
remain empty while results are stored only in collectedOutputs; update newBlock
right after execution by assigning newBlock.outputs =
cloneDeep(collectedOutputs[newBlock.id] || collectedOutputs[correspondingId] ||
executionResult.outputs) and newBlock.executionCount =
executionResult.executionCount || (Array.isArray(newBlock.outputs) ?
newBlock.outputs.length ? (newBlock.outputs[0].execution_count ?? null) : null :
null); ensure you use the same identifiers used when mirroring results
(collectedOutputs, executionResult) and deep-copy the outputs before assigning
so saved notebooks/snapshots persist the executed outputs; apply the same fix in
the other insertion branch that mirrors results (the block handling the
alternate insert path).

---

Outside diff comments:
In `@packages/blocks/src/blocks/executable-blocks.ts`:
- Around line 18-28: The array used to construct the executableBlockTypes Set
contains a duplicate 'agent' entry which is accidental and should be removed;
edit the initializer for executableBlockTypes (the Set literal in
blocks/executable-blocks.ts) to delete the second 'agent' string so the list
only contains unique block types (and quickly scan the surrounding entries like
'code', 'sql', 'notebook-function', 'visualization', 'button', 'big-number' and
...INPUT_BLOCK_TYPES to ensure no other duplicates or a missing intended type).

In `@packages/blocks/src/deepnote-file/deepnote-file-schema.ts`:
- Around line 475-484: The union type ExecutableBlock contains a duplicated
member AgentBlock; edit the ExecutableBlock type declaration to remove the
redundant "AgentBlock" entry so each variant appears only once (locate the
ExecutableBlock type and delete the second AgentBlock union member).

In `@packages/runtime-core/src/execution-engine.ts`:
- Around line 18-27: The exported array executableBlockTypes contains a
duplicated 'agent' entry which causes callers to see it twice; remove the
duplicate string from the array literal so each ExecutableBlock['type'] appears
only once (update the exported executableBlockTypes definition to contain a
single 'agent' element).

---

Duplicate comments:
In `@packages/cli/src/commands/run.ts`:
- Around line 462-473: The debug serialization exposes sensitive prompt content
because safeOptions only masks token; update createRunAction to also redact
options.prompt before logging by creating safeOptions from options with token
replaced by '[redacted]' when present and prompt replaced by '[redacted]' when
present (leave other fields unchanged), then use JSON.stringify(safeOptions) in
the debug call so neither prompt nor token appear in logs.
- Around line 272-278: The code appends the synthetic agent block to the last
notebook (file.project.notebooks[file.project.notebooks.length - 1]) which
ignores a user-selected notebook via the --notebook option; change the logic to
compute the intended execution notebook (use the existing notebook selection
variable or option, e.g., a notebookIndex/notebookName passed in via
path/options) and append the block to that notebook (e.g., resolve
targetNotebook = file.project.notebooks[notebookIndex] or find by name) instead
of lastNotebook; update the push call to
targetNotebook.blocks.push(createAgentBlock(options.prompt,
targetNotebook.blocks.length)) and throw an error if the resolved targetNotebook
is missing.

In `@packages/runtime-core/src/agent-handler.ts`:
- Around line 38-40: The generateSortingKey function currently zero-pads and
creates keys like "a00000003", which breaks compatibility with existing notebook
keys ("a0"/"a1" and numeric "000004" styles) and causes incorrect lexicographic
ordering; change generateSortingKey to produce compact keys that preserve legacy
grouping by returning "a" + index.toString() (no pad) so agent-inserted blocks
remain in the expected "a" bucket and do not leapfrog numeric-only keys when
sorted by sortingKey.