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

Inline comments:
In `@packages/runtime-core/src/agent-handler.ts`:
- Around line 18-26: The AgentBlockContext.onAgentEvent type currently forces
Promise<void> which prevents sync handlers and leaves async errors unobserved;
change the onAgentEvent signature to accept void | Promise<void> in the
AgentBlockContext interface and then update the stream processing loop to await
the result of each call to onAgentEvent for events like "text_delta",
"reasoning_delta", "tool_called", and "tool_output" so both sync and async
handlers are supported and errors are propagated; also update the corresponding
ExecutionOptions type in execution-engine.ts to match the new void |
Promise<void> signature so callers compile.

In `@packages/runtime-core/src/execution-engine.ts`:
- Around line 249-287: addAndExecuteCodeBlock currently only records
outputs/executionCount and loses success/error details; change it to capture and
persist the full execution result from kernel.execute (including success,
outputs, executionCount, and any error or computed outputText) into blockOutputs
and collectedOutputs so that a failing result (result.success === false) is not
treated as success and thrown exceptions are converted to a unified result
object and passed to the same flow; specifically update the logic around
kernel.execute, the construction pushed to blockOutputs and collectedOutputs,
and the returned value so both tool responses and host callbacks (e.g.,
onBlockDone) receive the identical full result object rather than just
outputs/executionCount.

---

Outside diff comments:
In `@packages/runtime-core/src/execution-engine.test.ts`:
- Around line 833-847: Add one real runtime test that does not mock
executeAgentBlock at the module boundary so the new helper path is exercised:
undo or avoid the module mock for executeAgentBlock (remove or restore
mockExecuteAgentBlock via vi.unmock/vi.importActual) and call the actual
execution flow with the AGENT_FIXTURE so
AgentBlockContext.addAndExecuteCodeBlock, AgentBlockContext.addMarkdownBlock,
and the async onAgentEvent flow run; then assert that inserted block reporting
(addedBlockIds/blockOutputs/finalOutput and any events) matches expected values.
Ensure the test triggers error/edge cases and special characters from the
fixture so the real helper logic and event handling are covered rather than
returning a mocked result.

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

Inline comments:
In `@packages/runtime-core/src/agent-handler.ts`:
- Line 104: Remove the leftover commented-out line "const outputs =
collectedOutputs.get(block.id)" in the agent handler; locate the commented
statement near the logic that references collectedOutputs and block.id (in the
function handling agent blocks) and delete it so no dead commented code remains,
ensuring there are no other unused commented variables left after the refactor.
- Around line 69-76: The map callback in blocks.map is shadowing and redundantly
re-reading collectedOutputs.get(block.id): remove the inner const outputs =
collectedOutputs.get(block.id) and the nested if, use the single outputs
variable obtained once (const outputs = collectedOutputs.get(block.id)) and,
when outputs is non-null and outputs.outputs.length > 0, return { ...block,
outputs: outputs.outputs }; otherwise return the original block — update the
callback in agent-handler.ts accordingly to eliminate the unreachable shadowed
declaration.

---

Outside diff comments:
In `@packages/runtime-core/src/agent-handler.ts`:
- Around line 237-239: The code that builds outputStr in agent-handler.ts should
explicitly handle undefined instead of relying on JSON.stringify(undefined)
returning undefined; update the logic in the block around toolOutput / outputStr
(variables toolOutput and outputStr, and the context.onAgentEvent call) so that
if toolOutput is undefined you set outputStr to '' (empty string), otherwise if
it's a string keep it, and otherwise set it to JSON.stringify(toolOutput);
ensure the resulting outputStr is always a string before calling
context.onAgentEvent with type 'tool_output'.

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

Inline comments:
In `@packages/runtime-core/src/agent-handler.ts`:
- Around line 69-73: The mapping currently only overrides a block when
collectedOutputs.get(block.id) exists and has outputs.length > 0, which allows
stale block.outputs to persist when an entry exists with outputs: []; change the
condition so any presence of an entry in collectedOutputs for block.id (i.e.,
outputs != null / outputs !== undefined) causes the block to be returned with
outputs set to outputs.outputs (including the empty array); leave the original
block untouched only when there is no map entry for that id (refer to the
blocks.map callback, collectedOutputs.get(block.id), and the outputs.outputs
property).
- Around line 15-23: Update the callback result types so successful and failed
tool returns are serializable and include the execution output: replace
AddAndExecuteCodeBlockResult with a discriminated union where success: true
includes a required executionText (string) carrying stdout/stderr/results, and
success: false includes a SerializableError type (e.g., { message: string;
name?: string; stack?: string; code?: string }) instead of raw Error; do the
same for AddMarkdownBlockResult (e.g., success true includes renderedText or
content string). Then update the AgentBlockContext signatures for
addAndExecuteCodeBlock and addMarkdownBlock to return the new result types so
the agent always receives serializable output and meaningful error information.

---

Outside diff comments:
In `@packages/runtime-core/src/agent-handler.ts`:
- Around line 171-203: The MCP clients and their tool enumeration are created
outside the try/finally, so a failure partway leaves open stdio transports; move
the whole client startup and tools collection into the protected scope and track
started clients incrementally (e.g., push each created client from
mergedMcpConfig.map/createMCPClient into a local startedClients array as you
create them), then in the finally iterate startedClients and call the client's
shutdown method (client.close() or client.dispose() as available) to ensure
Experimental_StdioMCPTransport stdio pipes are cleaned up; also ensure
addCodeBlockTool and addMarkdownBlockTool registration
(context.addAndExecuteCodeBlock / context.addMarkdownBlock) happens after
clients/tools are successfully created so partial startups are cleaned up
consistently.

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

Outside diff comments:
In `@packages/runtime-core/src/agent-handler.ts`:
- Around line 173-184: The current use of Promise.all over mergedMcpConfig to
createMCPClient instances means a single Experimental_StdioMCPTransport failure
will reject the entire agent run and skip cleanup; change the creation to handle
per-client failures (e.g., map mergedMcpConfig to individual try/catch or
Promise.allSettled, logging errors for failed createMCPClient calls and only
collecting successful clients into mcpClients) so that
createMCPClient/Experimental_StdioMCPTransport failures degrade gracefully and
allow normal cleanup and operation with remaining clients.
- Around line 158-161: The fallback model string is invalid: update the model
selection logic that sets the modelName (using
block.metadata.deepnote_agent_model and process.env.OPENAI_MODEL) to use a real
OpenAI model identifier instead of "gpt-5" — replace that fallback with the
current available model (e.g., "gpt-4.5") so modelName resolves to a valid model
when deepnote_agent_model === 'auto' and OPENAI_MODEL is unset.

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

Inline comments:
In `@packages/runtime-core/src/execution-engine.ts`:
- Around line 236-242: Replace direct reads of process.env for agent provider
settings with the runtime-provided environment in RuntimeConfig.env: use the
existing runtimeConfig.env (the env passed into the engine at RuntimeConfig.env)
to obtain OPENAI_API_KEY and related overrides instead of process.env (affecting
the apiKey check that currently reads process.env.OPENAI_API_KEY and the
forwarded context created around lines 310-315). Ensure the error message
reflects the actual env source and mentions available overrides (e.g.,
OPENAI_API_KEY, OPENAI_BASE_URL, model override keys) when missing, and update
the logic that builds the forwarded context to copy relevant keys from
runtimeConfig.env so embedders can supply base URL and model overrides without
mutating process state.

---

Outside diff comments:
In `@packages/runtime-core/src/agent-handler.ts`:
- Around line 171-205: The MCP client setup can leak processes if
createMCPClient() or client.tools() rejects; ensure partial clients are closed
on failure by wrapping the creation and tools-fetching in a try/catch/finally
and, on any error, iterate the already-created mcpClients and call their
shutdown/close/dispose method (e.g., client.close() or client.shutdown(), using
the actual API) to stop underlying Experimental_StdioMCPTransport processes
before rethrowing; similarly, ensure any created clients are closed in the
existing cleanup/finally block so mergedMcpConfig, createMCPClient, mcpClients,
mcpToolSets and client.tools() failures do not leave stray stdio transports
running.

---

Duplicate comments:
In `@packages/runtime-core/src/execution-engine.ts`:
- Around line 252-286: The addAndExecuteCodeBlock function currently discards
successful execution details and only returns {success: true} while errors
return raw Error objects and failed runs aren't recorded in
blockOutputs/collectedOutputs, so change addAndExecuteCodeBlock to capture the
full, serializable execution result from kernel.execute (including outputs and
executionCount and a serializable error/message on failure), store that same
result into blockOutputs and collectedOutputs for every run (success or
failure), and return that single unified result structure so the tool response
and any host callbacks (e.g., onBlockDone consumers) consume the exact same
serializable execution result.

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

Inline comments:
In `@packages/runtime-core/src/execution-engine.test.ts`:
- Around line 836-847: Add new Vitest cases in execution-engine.test.ts that
exercise the ExecutionEngine context helpers: call
context.addAndExecuteCodeBlock(...) and context.addMarkdownBlock(...) (or the
instance method names used in the suite) and assert they insert blocks into the
engine's store, invoke kernel.execute (mock the kernel.execute and assert it was
called with the expected code, language and context), emit the same
callbacks/events the existing tests expect (spy/mock any callback handlers used
in the suite), and verify error propagation by having the mocked kernel.execute
reject to ensure the helper surfaces the failure; reuse existing mocks like
mockExecuteAgentBlock where appropriate and add new mocks/spies for
kernel.execute and block insertion assertions.

---

Duplicate comments:
In `@packages/runtime-core/src/execution-engine.ts`:
- Around line 261-295: The addAndExecuteCodeBlock helper currently buffers
execution results and defers emitting them, causing failures (result.success ===
false) to be misreported later; modify addAndExecuteCodeBlock to emit the full
inserted-block result immediately after kernel.execute returns or throws: after
computing result.outputs and result.executionCount, call the existing
onOutput/new-output handler (the same callback used elsewhere) with the outputs
and then call onBlockDone/onBlockFinished with either success: true or success:
false and the Error (do this in both the successful path and the catch path),
and still update collectedOutputs and blockOutputs as now; ensure you do not
rely on later post-processing in executeAgentBlock to flip success to
true—preserve and pass the original success/error through immediately so
inserted block runs reach onOutput and onBlockDone inline.
- Around line 245-250: Replace the direct process.env lookup for OPENAI_API_KEY
with the runtime-configured env (use RuntimeConfig.env.OPENAI_API_KEY) in the
block that currently throws the Error, and update the thrown error text to
reflect sourcing from RuntimeConfig.env (remove or correct the misleading
OPENAI_BASE_URL fallback mention); i.e., change the const apiKey assignment to
read from RuntimeConfig.env and adjust the throw new Error message in the same
block to instruct configuring OPENAI_API_KEY via RuntimeConfig.env or equivalent
embedder configuration.