MingaAgent.ToolRouter (Minga v0.1.0)

Routes file tool operations through buffer forks and changesets.

Tools call this module instead of directly doing filesystem I/O. The routing decision tree for each file operation:

Is there an open buffer for this path AND a fork store is active? YES: route through Buffer.Fork (in-memory, instant, undo integration)
Is there an active changeset? YES: route through Changeset overlay (filesystem-level isolation)
Neither: fall through to direct I/O (returns :passthrough)

Buffer.Fork handles files the user has open in a buffer. Changeset handles files that aren't open, or external tools that need a coherent filesystem view. A session can use both simultaneously.

This module is stateless. The fork store pid and changeset pid come from the caller (stored in session state, captured in tool closures).

Summary

Types

changeset()

Changeset reference (nil when changeset is disabled).

context()

Routing context passed by tool callbacks.

fork_store()

Fork store reference (nil when fork routing is disabled).

Functions

active?(arg1)

Returns true if any routing is active (fork store or changeset).

context(fork_store, changeset)

Builds a routing context from the fork store and changeset pids.

delete_file(arg1, path)

Deletes a file, routing through changeset if active.

edit_file(ctx, path, old_text, new_text)

Edits a file by find-and-replace, routing through fork or changeset.

has_forks?(map)

Returns true if a fork store is active and has forks.

read_file(ctx, path)

Reads a file, routing through fork or changeset if active.

working_dir(arg1)

Returns the working directory for shell commands.

write_file(ctx, path, content)

Writes a file, routing through fork or changeset if active.

Types

changeset()

@type changeset() :: pid() | nil

Changeset reference (nil when changeset is disabled).

context()

@type context() :: %{fork_store: fork_store(), changeset: changeset()}

Routing context passed by tool callbacks.

fork_store()

@type fork_store() :: pid() | nil

Fork store reference (nil when fork routing is disabled).

Functions

active?(arg1)

@spec active?(context()) :: boolean()

Returns true if any routing is active (fork store or changeset).

context(fork_store, changeset)

@spec context(fork_store(), changeset()) :: context()

Builds a routing context from the fork store and changeset pids.

delete_file(arg1, path)

@spec delete_file(context(), String.t()) :: :ok | :passthrough | {:error, term()}

Deletes a file, routing through changeset if active.

Buffer forks don't support deletion (you can't delete an open buffer through a fork). Falls through to changeset or passthrough.

edit_file(ctx, path, old_text, new_text)

@spec edit_file(context(), String.t(), String.t(), String.t()) ::
  :ok | :passthrough | {:error, term()}

Edits a file by find-and-replace, routing through fork or changeset.

has_forks?(map)

@spec has_forks?(context()) :: boolean()

Returns true if a fork store is active and has forks.

read_file(ctx, path)

@spec read_file(context(), String.t()) :: {:ok, binary()} | {:error, term()}

Reads a file, routing through fork or changeset if active.

Forks take priority: if there's a fork for this path, read from it. Otherwise try the changeset. If neither, fall through to buffer/filesystem.

working_dir(arg1)

@spec working_dir(context()) :: String.t() | nil

Returns the working directory for shell commands.

Returns the changeset overlay directory if active, nil otherwise. (Buffer forks don't affect the filesystem view for shell commands.)

write_file(ctx, path, content)

@spec write_file(context(), String.t(), binary()) ::
  :ok | :passthrough | {:error, term()}

Writes a file, routing through fork or changeset if active.

If a buffer is open for this path and a fork store exists, creates a fork (lazily) and writes to it. Otherwise tries changeset. Returns :passthrough if neither is active.