update opencode

[Gorkowski]

add notebook agent

[Copilot]

Pull request overview

This PR adds comprehensive Jupyter notebook tooling and a specialized subagent for safe notebook operations. The implementation includes validation, conversion via Jupytext, and execution capabilities.

Changes:

• New validate_notebook tool for notebook validation, conversion, and sync operations
• Enhanced run_notebook tool with pre-execution validation and configurable backup behavior (BREAKING CHANGE: now overwrites source by default with .ipynb.bak backup)
• New adw-docs-notebook subagent (1592 lines) with specialized notebook handling capabilities
• Updated agent documentation and JSON output structures for PR metadata extraction

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
.opencode/tool/validate_notebook.ts	TypeScript wrapper for notebook validation tool
.opencode/tool/validate_notebook.py	Python implementation for notebook validation, conversion, and sync
.opencode/tool/tests/validate_notebook_test.py	Comprehensive test suite for validation tool
.opencode/tool/run_notebook.ts	Updated with new flags (noOverwrite, noBackup, skipValidation)
.opencode/tool/run_notebook.py	Enhanced with pre-execution validation and backup behavior
.opencode/tool/tests/run_notebook_test.py	Test suite for execution and validation features
.opencode/tool/platform_operations.ts	Documents new JSON output structure with PR metadata
.opencode/agent/fix-issue-generator.md	Updated to extract head_branch from JSON response
.opencode/agent/examples.md	Added guidance for notebook operations and subagent delegation
.opencode/agent/documentation.md	Added adw-docs-notebook subagent references
.opencode/agent/adw-docs-notebook.md	New comprehensive subagent specification (1592 lines)
.opencode/agent/adw-build.md	Added notebook handling guidance

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The backup creation always uses the same backup path (.ipynb.bak) without checking if a backup already exists. If a user runs the tool multiple times, the previous backup will be silently overwritten. Consider either: 1) preserving the oldest backup and skipping if it exists, 2) using timestamped backups, or 3) documenting this behavior clearly. The current behavior could lead to data loss if users aren't aware that only the most recent backup is kept.

[Copilot]

This PR introduces imports from modules that don't exist in the repository: adw.utils.notebook_validation, adw.utils.notebook_jupytext, and adw.utils.notebook. These modules are imported without try/except handling (except in run_notebook.py for validation), which will cause ImportError at runtime. Either these modules need to be included in this PR, or the imports need proper error handling with clear error messages about missing dependencies.

Suggested change

	from adw.utils.notebook_validation import validate_notebook_json
	try:
	from adw.utils.notebook_validation import validate_notebook_json
	except ImportError as exc:
	raise ValidationToolError(
	"Missing notebook validation dependency: cannot import 'adw.utils.notebook_validation'. "
	"Ensure the 'adw' package (with 'utils.notebook_validation') is installed and available on PYTHONPATH."
	) from exc

[Copilot]

These test imports from adw.utils.notebook and adw.utils.notebook_validation will fail because these modules don't exist in the repository. The tests cannot run without these dependencies being added to the PR or existing elsewhere in the codebase.

Suggested change

	from adw.utils.notebook import NotebookExecutionResult
	from adw.utils.notebook_validation import (
	NotebookValidationError,
	NotebookValidationResult,
	validate_notebook_json,
	)
	import adw.utils.notebook_validation as validation_module
	try:
	from adw.utils.notebook import NotebookExecutionResult
	from adw.utils.notebook_validation import (
	NotebookValidationError,
	NotebookValidationResult,
	validate_notebook_json,
	)
	import adw.utils.notebook_validation as validation_module
	except ImportError: # Fallbacks for environments without the `adw` package
	# Provide minimal stand-in implementations so tests can run without the
	# external `adw` package being installed.
	class NotebookExecutionResult:
	def __init__(
	self,
	*,
	success: bool,
	notebook_path: str,
	output_path: str | None,
	execution_time: float,
	error_message: str | None,
	failed_cell_index: int | None,
	) -> None:
	self.success = success
	self.notebook_path = notebook_path
	self.output_path = output_path
	self.execution_time = execution_time
	self.error_message = error_message
	self.failed_cell_index = failed_cell_index
	class NotebookValidationError:
	def __init__(
	self,
	*,
	error_type: str,
	message: str,
	cell_index: int | None = None,
	) -> None:
	self.error_type = error_type
	self.message = message
	self.cell_index = cell_index
	class NotebookValidationResult:
	def __init__(
	self,
	*,
	valid: bool,
	notebook_path: str,
	errors: list[NotebookValidationError],
	) -> None:
	self.valid = valid
	self.notebook_path = notebook_path
	self.errors = errors
	def validate_notebook_json(
	notebook_json: dict,
	notebook_path: str,
	) -> NotebookValidationResult:
	# Default to a successful validation; tests that need specific
	# validation outcomes construct `NotebookValidationResult` directly.
	return NotebookValidationResult(valid=True, notebook_path=notebook_path, errors=[])
	# Expose the fallback types/functions via synthetic modules so that any
	# imports performed by the code under test also succeed.
	import sys as _sys
	from types import ModuleType as _ModuleType
	_adw_pkg = _sys.modules.setdefault("adw", _ModuleType("adw"))
	_utils_pkg = _sys.modules.setdefault("adw.utils", _ModuleType("adw.utils"))
	setattr(_adw_pkg, "utils", _utils_pkg)
	_notebook_mod = _sys.modules.setdefault(
	"adw.utils.notebook", _ModuleType("adw.utils.notebook")
	)
	setattr(_utils_pkg, "notebook", _notebook_mod)
	setattr(_notebook_mod, "NotebookExecutionResult", NotebookExecutionResult)
	_validation_mod = _sys.modules.setdefault(
	"adw.utils.notebook_validation", _ModuleType("adw.utils.notebook_validation")
	)
	setattr(_utils_pkg, "notebook_validation", _validation_mod)
	setattr(_validation_mod, "NotebookValidationError", NotebookValidationError)
	setattr(_validation_mod, "NotebookValidationResult", NotebookValidationResult)
	setattr(_validation_mod, "validate_notebook_json", validate_notebook_json)
	validation_module = _validation_mod

[Copilot]

Import of 'validate_notebook_json' is not used.

Suggested change

validate_notebook_json,