intellicrack.core.tool_progress

Progress a running tool call reports, carried from the tool back to the operator.

The orchestrator runs each tool call with a reporter bound for that call. Whatever carries out the call – a server’s tool, reached through the MCP tool source – picks the reporter up with current_progress_reporter() when the call starts, and reports through it for as long as the call runs, even from another task. The orchestrator turns each report into a ToolProgress for the call and hands it to the UI, which shows it beside the running call.

RunningToolCalls runs each call as a task of its own, which is what lets the operator cancel one call while the turn goes on.

type ToolProgressReporter = Callable[[float, float | None, str | None], None]: Reports how far a call has got, its total if known, and a message.

class ToolProgress[source]

Bases: object

How far one running tool call has got.

Variables:

call_id (str) – The call.
progress (float) – How far it has got.
total (float | None) – The total it is working towards, or None when unknown.
message (str | None) – What the tool said about it, already cleaned, or None.

call_id: str

progress: float

total: float | None

message: str | None

property fraction: float | None

How much of the total is done.

Returns:: A value from 0 to 1, or None when the total is unknown.
Return type:: float | None

describe()[source]

Render the progress for the operator.

Returns:: How far the call has got, out of what total, and what the tool said, such as 3/10: indexing sections.
Return type:: str

__init__(call_id, progress, total=None, message=None)

Parameters:

call_id (str)
progress (float)
total (float | None)
message (str | None)

Return type:

None

current_progress_reporter()[source]

Find the reporter bound for the tool call running in this context.

Returns:: The reporter, or None outside a tool call.
Return type:: ToolProgressReporter | None

reporting_progress(reporter)[source]

Bind a reporter for the tool call that runs inside the block.

Parameters:: reporter (ToolProgressReporter) – Receives the call’s progress.
Yields:: None – Control passes to the block.
Return type:: Generator[None]

exception ToolCallCancelledError[source]

Bases: Exception

Raised for a tool call the operator cancelled on its own.

class RunningToolCalls[source]

Bases: object

The tool calls running now, which the operator can cancel one at a time.

Each call runs as its own task with a progress reporter bound, so the operator can stop one call and let the turn go on, and see how far each one has got meanwhile. Everything here runs on the orchestrator’s loop.

__init__()[source]

Start with no calls running.

Return type:: None

set_progress_callback(callback)[source]

Choose who receives running calls’ progress.

Parameters:: callback (Callable[[ToolProgress], None] | None) – Receives each report, or None to stop reporting.
Return type:: None

property running: list[str]

The ids of the calls running now.

Returns:: The call ids.
Return type:: list[str]

async run(call_id, work)[source]

Run one call as a task of its own, with its progress reported.

Parameters:

call_id (str) – The call.
work (Callable[[], Awaitable[_T]]) – Carries the call out.

Returns:

What the call returned.

Return type:

_T

Raises:

ToolCallCancelledError – If the operator cancelled this call.
CancelledError – If whoever awaits the call was cancelled, which cancels the call with it.

async cancel(call_id)[source]

Cancel one running call and wait for it to stop.

Parameters:: call_id (str) – The call.
Returns:: Whether the call was running and has now stopped.
Return type:: bool

cancel_all()[source]

Cancel every running call as part of cancelling the whole turn.

Return type:: None