Debugger

from afk.debugger import Debugger, DebuggerConfig

debugger = Debugger(
    DebuggerConfig(
        verbosity="detailed",
        redact_secrets=True,
        include_content=True,
    )
)

runner = debugger.runner()

from afk.core import Runner, RunnerConfig

runner = Runner(config=RunnerConfig(debug=True))

handle = await runner.run_handle(agent, user_message="inspect this run")
await debugger.attach(handle)  # prints formatted events

from afk.tools import tool, ToolResult, ToolDeferredHandle

@tool(args_model=BuildArgs, name="build_project")
async def build_project(args: BuildArgs) -> ToolResult[dict[str, str]]:
    future = asyncio.create_task(run_long_build(args.path))
    return ToolResult(
        success=True,
        deferred=ToolDeferredHandle(
            ticket_id="build-123",
            tool_name="build_project",
            status="running",
            summary="Build started",
            resume_hint="Continue documentation while build runs",
        ),
        metadata={"background_task": future},
    )

await memory.put_state(
    thread_id,
    f"bgtool:{run_id}:{ticket_id}:state",
    {
        "run_id": run_id,
        "thread_id": thread_id,
        "ticket_id": ticket_id,
        "tool_name": "build_project",
        "status": "completed",  # or "failed"
        "output": {"status": "ok", "artifact": "dist/app"},
        "error": None,
    },
)