use LLM::Agent;          # brings in every LLM::Agent:: module below

my $loop = LLM::Agent::Loop.new(backends => [$primary, $fallback]);

# The conversation is history; what is true today is a run context,
# rendered into the request and never into the transcript.
my $context = LLM::Agent::RunContext.new(
    head-sections => [ identity => 'You are a coding assistant.' ],
    facts         => [ date => Date.today.Str, cwd => $*CWD.Str ],
);

my $run = $loop.run([$user], :$context);

start react whenever $run.events -> $event {
    print $event.text if $event ~~ LLM::Agent::Event::Token;
}

my %outcome = await $run.result;
say %outcome<final>;

use LLM::Agent;
use LLM::Chat::Backend::OpenAICompatible;
use MCP::Client;
use MCP::Client::Registry;
use MCP::Client::Policy;

# --- 1. The loop first, because the shims hang off it. ---------------
#
# It needs the backends and nothing else yet: `provider` and `session`
# can be handed to a second Loop built at the end, or — as here — the
# loop is built once and the policy is wired to it. Either order works
# as long as the shims come from the loop that will run.

my @backends = (
    LLM::Chat::Backend::OpenAICompatible.new(
        api_url => 'https://openrouter.ai/api/v1',
        api_key => %*ENV<OPENROUTER_API_KEY>,
        model   => 'moonshotai/kimi-k2',
    ),
    LLM::Chat::Backend::OpenAICompatible.new(   # the fallback
        api_url => 'http://localhost:5001/v1',
        model   => 'local',
    ),
);

# --- 2. The transcript. ----------------------------------------------

my $path = "$*HOME/.local/state/myagent/{DateTime.now.Str}.jsonl";
my $session = LLM::Agent::Session.create(
    path => $path,
    meta => { agent => 'myagent', cwd => $*CWD.Str, model => @backends[0].model },
);

# --- 3. The tool servers, then a registry over them. ------------------
#
# NOTE THE FORWARD DECLARATION. The client needs the elicitation hook at
# construction and the policy needs the client, so one of the two must be
# named before it exists. This is the idiom MCP::Client::Policy's own Pod
# uses, and it is the only way round the cycle.

my $loop;                       # forward-declared: the shims come from it
my $policy;                     # forward-declared: the client's hook needs it

my $fs = MCP::Client.connect-stdio(
    command   => 'raku-mcp',
    args      => ['--pack=FileSystem', '--root=' ~ $*CWD],

    # A server's own questions go to the same human, through the same
    # lock the permission prompts use.
    on-elicit => -> %request { $policy.elicit-hook.(%request) },

    # Server logs become Log events on the run's Supply. THE log-level IS
    # LOAD-BEARING: since the 2026-07-28 revision a modern server sends
    # nothing at all without one, and a silent hook looks exactly like a
    # server that had nothing to say.
    on-log    => -> %params { $loop.log-hook.(%params) },
    log-level => 'info',
);

my $registry = MCP::Client::Registry.new;
$registry.add($fs, prefix => 'fs');

# --- 4. The policy, over the registry. --------------------------------
#
# Rules name tools AS THIS POLICY SEES THEM. Over a registry that is the
# prefixed name (fs_read); under one it is the bare name (read).
#
# `grants` pre-seeds the "always allow" answers from last time, which is
# what stops a resumed session re-asking every question.

$policy = MCP::Client::Policy.new(
    provider => $registry,
    rules    => [
        |MCP::Client::Policy.default-rules,
        { tool => 'fs_write', decision => 'allow', under => 'scratch' },
    ],
    roots    => { fs => $*CWD.Str },
    grants   => $session.grants,

    # wrap-ask emits AskPending / AskAnswered around the real asker, so a
    # TUI can render "waiting on you" from the same event stream it
    # renders tokens from. The asker still blocks, and still holds the
    # policy's lock: treat it as a leaf.
    #
    # DEFERRED INTO A CLOSURE, like on-elicit above and for the same
    # reason: `$loop.wrap-ask(...)` here would call a method on a type
    # object, because $loop does not exist until step 7.
    on-ask   => -> %request { $loop.wrap-ask(&ask-the-human).(%request) },
);

# --- 5. Delegation, if the model is to have subagents. -----------------
#
# OPTIONAL, and a composer like the two above it: it publishes the
# policy's catalogue plus a `task` tool, and answers a task call with a
# child run's final message. Stacked OVER the policy here, so everything
# a child does still goes through the same permissions.
#
# `loop` is deferred for the same reason on-ask was — and `spawn` is the
# whole of the app's side: build a child however you like, hand back
# something with `.run` and `.session-path`. See LLM::Agent::Subagents.

my $provider = LLM::Agent::Subagents.new(
    inner => $policy,
    types => [
        { name => 'reviewer', description => 'Reviews a diff. Read-only.' },
        { name => 'tester',   description => 'Runs the tests, reports failures.' },
    ],
    spawn   => -> %spec { build-child(%spec) },
    loop    => { $loop },
    session => $session,
);

# --- 6. Compaction. ---------------------------------------------------
#
# The counter is SHARED between the loop and the compactor: the loop's is
# the one calibrated against what the provider actually billed.

my $counter = LLM::Agent::TokenCount::Usage.new;

my $compactor = LLM::Agent::Compactor.new(
    backend        => @backends[0],
    counter        => $counter,
    context-budget => 128_000,
    # Optional, off by default, and the cheapest thing in this file: old
    # tool results are stubbed in place — no request, no summary — and
    # only summarized when that was not enough. See the Compactor's Pod.
    age-observations => True,
);

# --- 7. And the loop it all hangs off. --------------------------------
#
# `provider` is the TOP of the stack — the subagent composer here, or
# $policy directly when there is no delegation. The loop cannot tell how
# deep it goes.
#
# `steer-source` is the one seam pointing the other way: the shims above
# turn something the app is asked into an event, and this is the loop
# asking the app a question — "has the user said anything since the last
# round?" It is a thunk taking NO arguments and answering a list of Str,
# each of which becomes an ordinary user turn, and it is called at a round
# boundary with nothing in flight, so a steer can never land in the middle
# of a tool batch. The queue behind it, its lock, and whether three queued
# lines are three messages or one are all the app's business — see
# LLM::Agent::Loop's `Steering: a user turn between rounds`. Omit it
# entirely for a loop the user cannot interrupt.

my @steers;                      # the app's queue: UI pushes, loop drains
my $steer-lock = Lock.new;

$loop = LLM::Agent::Loop.new(
    :@backends, :$counter, :$session, :$compactor, :$provider,
    steer-source => {
        $steer-lock.protect: { my @taken = @steers; @steers = (); @taken }
    },
);

# --- 8. The run context: what is true RIGHT NOW. -----------------------
#
# Built fresh per run, and NOT baked into a message. Identity and the
# instruction files go in the head (stable across turns, so a backend's
# prefix cache keeps working); the facts and anything volatile go in the
# tail, rendered after the conversation and closest to generation.
#
# Note what is NOT here: the tool catalogue. The API's own `tools`
# parameter is the single source of truth for what can be called, and a
# prose copy of it in the prompt is one more thing to drift.

my $context = LLM::Agent::RunContext.new(
    head-sections => [
        identity     => 'You are a coding assistant working in a checked-out repository.',
        instructions => LLM::Agent::Prompt::instructions-from-files(['AGENTS.md']),
    ],
    facts => [
        platform => "{$*KERNEL.name} ({$*KERNEL.hardware})",
        date     => Date.today.Str,
        cwd      => $*CWD.Str,
        branch   => $branch,          # undefined facts are dropped
    ],
);

# --- 9. Run. ----------------------------------------------------------

my $question = LLM::Chat::Conversation::Message.new(
    role => 'user', content => 'Make the tests pass.',
);

# NOTE what is NOT here: `$session.append-message($question)`. The loop
# writes every message it is handed that the transcript does not already
# have, IN THE ORDER IT IS HANDED THEM. Appending the question here as
# well would put it in the file twice over, and the loop's seed-session
# check would then refuse the very run that wrote it. Let `run` own the
# writing; see the resume recipe below for the one case where an app
# appends a turn itself.
#
# And note what the conversation IS: one user turn. There is no system
# message in it at all — the identity lives in the context now, so it is
# re-rendered every run instead of fossilising at index 0.
my $run = $loop.run([$question], :$context);

# And while that is in flight, the user thinks of something else. It is
# delivered at the next round boundary, as a user turn: no cancel, no
# second run, and nothing lands in the middle of a tool batch.
$steer-lock.protect: { @steers.push: 'stop after the first failing test' };

my $session = LLM::Agent::Session.load(path => $path);

note "dropped a partial final line" if $session.warnings;

my @messages = $session.messages;        # compaction already applied
my $policy   = MCP::Client::Policy.new(  # the human is not asked twice
    :$provider, :&on-ask, grants => $session.grants,
);

# Rebuilt, not replayed: today's date, today's branch, today's AGENTS.md.
my $context = LLM::Agent::RunContext.new(
    head-sections => [ identity => IDENTITY, instructions => $instructions ],
    facts         => [ date => Date.today.Str, cwd => $*CWD.Str, |@git-facts ],
);

# What the LAST run was told, if you want to notice that the world moved.
my %was = $session.last-run-context<facts>.list.map({ .[0] => .[1] }).Hash;
note "the working directory has changed since this session was last run"
    if %was<cwd>.defined && %was<cwd> ne $*CWD.Str;

my $next = LLM::Chat::Conversation::Message.new(role => 'user', content => $more);
$session.append-message($next);

$loop.run([|@messages, $next], :$context);