tools.notebook_tools module

Tools for interacting with the Notebook Engine and Git version control.

These tools allow agents (primarily the Librarian subagent) to read instance and global tables of contents, retrieve specific state pages, and examine git version history for the notebook.

async tools.notebook_tools.get_notebook_toc(ctx, instance_uid=None, page=-1, page_size=10)

Read a paginated slice of one notebook instance’s table of contents.

Resolves the target instance UID (falling back to the current context’s {platform}:{channel_id} and normalizing a bare channel id by prefixing the platform), then delegates to plugins.notebook_engine.read_toc() to fetch that page of TOC entries from the notebook store on the filesystem. This is the agent’s way of browsing what state pages exist for a channel before fetching one in full.

Registered in this module’s TOOLS list as get_notebook_toc and invoked through the inference worker’s tool dispatch (used primarily by the Librarian subagent); no direct Python callers were found outside the test suite.

Parameters:

• ctx (ToolContext) – The tool context, used for platform/channel_id defaults.

• instance_uid (str | None) – Explicit {platform}:{channel_id} UID, or None to use the current context.

• page (int) – Page number to read, with -1 meaning the latest page.

• page_size (int) – Number of TOC entries per page.

Returns:

The paginated table-of-contents payload returned by the notebook engine.

Return type:

dict

async tools.notebook_tools.get_global_notebook_toc(ctx, page=-1, page_size=10)

Read a paginated slice of the global, cross-instance table of contents.

Unlike get_notebook_toc(), this is not scoped to one channel: it delegates straight to plugins.notebook_engine.read_global_toc() to page through TOC entries spanning every notebook instance, letting the agent survey notebook activity across the whole deployment.

Registered in this module’s TOOLS list as get_global_notebook_toc and invoked through the inference worker’s tool dispatch (used primarily by the Librarian subagent); no direct Python callers were found outside the test suite.

Parameters:

• ctx (ToolContext) – The tool context (accepted for dispatch uniformity; not used here).

• page (int) – Page number to read, with -1 meaning the latest page.

• page_size (int) – Number of TOC entries per page.

Returns:

The paginated global table-of-contents payload returned by the notebook engine.

Return type:

dict

async tools.notebook_tools.get_notebook_page(ctx, instance_uid=None, page_num=-1)

Read the full content of one notebook state page for an instance.

Where get_notebook_toc() lists pages, this fetches the body of a single page. It resolves the instance UID the same way (context default plus platform-prefix normalization) and delegates to plugins.notebook_engine.read_state_page() to load the page from the notebook store on the filesystem, returning a structured error dict when no such page exists rather than raising.

Registered in this module’s TOOLS list as get_notebook_page and invoked through the inference worker’s tool dispatch (used primarily by the Librarian subagent); no direct Python callers were found outside the test suite.

Parameters:

• ctx (ToolContext) – The tool context, used for platform/channel_id defaults.

• instance_uid (str | None) – Explicit {platform}:{channel_id} UID, or None to use the current context.

• page_num (int) – Page number to read, with -1 meaning the active page.

Returns:

The page contents from the notebook engine, or a dict with an error key when the page is not found.

Return type:

dict

async tools.notebook_tools.get_notebook_git_log(ctx, instance_uid=None, count=10)

Retrieve recent git commit history for the notebook repository.

Gives the agent visibility into how the notebook has changed over time by reading the underlying git log. It grabs the shared NotebookStateManager via plugins.notebook_engine.get_notebook_state_manager() and calls its _git manager, choosing get_instance_logs when an instance UID is supplied (normalized with a platform prefix) or get_recent_logs for a global view. The blocking git calls are wrapped in asyncio.to_thread() so they do not stall the event loop, and they read the notebook git repository on the filesystem.

Registered in this module’s TOOLS list as get_notebook_git_log and invoked through the inference worker’s tool dispatch (used primarily by the Librarian subagent); no direct Python callers were found outside the test suite.

Parameters:

• ctx (ToolContext) – The tool context, used for the platform default when normalizing a bare instance UID.

• instance_uid (str | None) – Optional {platform}:{channel_id} UID to filter the log to one instance; None returns global recent logs.

• count (int) – Maximum number of commits to return.

Returns:

One mapping per commit (hash, message, and related metadata) as produced by the notebook git manager.

Return type:

list[dict[str, str]]

async tools.notebook_tools.get_notebook_git_diff(ctx, commit_hash)

Retrieve the unified diff for a specific notebook commit.

Lets the agent inspect exactly what a given commit (surfaced by get_notebook_git_log()) changed in the notebook. It obtains the shared NotebookStateManager via plugins.notebook_engine.get_notebook_state_manager() and calls its _git manager’s get_diff for the commit, running that blocking git operation in asyncio.to_thread() so the event loop stays responsive; the diff is read from the notebook git repository on the filesystem.

Registered in this module’s TOOLS list as get_notebook_git_diff and invoked through the inference worker’s tool dispatch (used primarily by the Librarian subagent); no direct Python callers were found outside the test suite.

Parameters:

• ctx (ToolContext) – The tool context (accepted for dispatch uniformity; not used here).

• commit_hash (str) – The git commit hash to diff.

Returns:

A mapping with the requested commit hash and the unified diff text.

Return type:

dict[str, str]

async tools.notebook_tools.write_notebook_entry(ctx, entry, instance_uid=None, commit_message=None)

Append a new entry to an instance’s notebook and commit it to git.

This is the only write tool in the module: it resolves the instance UID the usual way (context default plus platform-prefix normalization) and delegates to plugins.notebook_engine.write_entry(), which appends the note to the notebook store and records a git commit (optionally with the supplied message). It therefore mutates the notebook state and the notebook git repository on the filesystem.

Registered in this module’s TOOLS list as write_notebook_entry and invoked through the inference worker’s tool dispatch (used primarily by the Librarian subagent); no direct Python callers were found outside the test suite.

Parameters:

• ctx (ToolContext) – The tool context, used for platform/channel_id defaults.

• entry (str) – The note content to append.

• instance_uid (str | None) – Explicit {platform}:{channel_id} UID, or None to use the current context.

• commit_message (str | None) – Optional custom git commit message; the engine supplies a default when omitted.

Returns:

The result payload from the notebook engine describing the written entry and resulting commit.

Return type:

dict

async tools.notebook_tools.get_instance_conversation_history(ctx, instance_uid=None, limit=50)

Retrieve recent conversation history for a specific instance.

Unlike the notebook-state tools above, this reads live chat rather than saved notes: it splits the resolved instance UID into platform and channel, constructs a message_cache.MessageCache over the context’s Redis connection, and fetches the most recent messages from the Redis-backed message cache. It then flattens them into [role]: content lines so the Librarian can review what was actually said before summarizing it into the notebook.

Registered in this module’s TOOLS list as get_instance_conversation_history and invoked through the inference worker’s tool dispatch (used primarily by the Librarian subagent); no direct Python callers were found outside the test suite.

Parameters:

• ctx (ToolContext) – The tool context, used for the platform default and the Redis connection.

• instance_uid (str | None) – Explicit {platform}:{channel_id} UID, or None to use the current context.

• limit (int) – Maximum number of recent messages to retrieve.

Returns:

A mapping with the resolved instance_uid, a newline-joined history string of formatted messages, and their count.

Return type:

dict