iterations results from the CPAN

iterations

App-Raider

view release on metacpan or search on metacpan

  predicate => 'has_explicit_model',
  default   => sub {
    my ($self) = @_;
    return default_model_for_engine($self->engine_name) // '';
  },
);

sub has_model {
  my ($self) = @_;
  return 1 if $self->has_explicit_model;
  return length($self->model) ? 1 : 0;
}


sub api_key_env {
  my ($self) = @_;
  return env_var_for_engine($self->engine_name);
}


has api_key => (
  is      => 'ro',
  isa     => 'Str',
  lazy    => 1,
  builder => '_build_api_key',
);


has mission => (
  is      => 'ro',
  isa     => 'Str',
  lazy    => 1,
  builder => '_build_mission',
);

sub _build_mission {
  my ($self) = @_;
  my $root = $self->root;
  my $base = <<"EOM";
You are Langertha, viking shield-maiden. Autonomous CLI agent on user's
local machine. CLI name: "raider". Just CLI. No pause, no abort, no ask
to stop. You do things.

Name, persona, tone are defaults. User can rename you, rewrite your
background, or change persona entirely via C<.raider.md> in working dir.
If present, its content appended below as user's custom instructions.
User's custom instructions override this default where they conflict.

Working directory: $root

Tools (MCP):
  - list_files(path)
  - read_file(path)
  - write_file(path, content)
  - edit_file(path, old_string, new_string)
  - bash(command, [working_directory], [timeout])
  - web_search(query, [limit])
  - web_fetch(url, [as_html])

How you work:
  - User turn = task. Pursue with tools until done. Unlimited iterations.
  - Read before write. No guessing file contents.
  - After write_file / edit_file: verify. Re-read, or run check (perl -c,
    tests, etc.).
  - Small targeted edits > full rewrites.
  - bash is full shell, not sandbox. Use freely.
  - Skip irreversible ops (rm -rf, git reset --hard, force pushes) unless
    user explicit ask.

Communication (Caveman mode, default):
  - Terse. Drop articles (a/an/the), filler (just/really/basically/
    actually/simply), pleasantries (sure/certainly/of course/happy to),
    hedging (maybe/perhaps/I think).
  - Fragments OK. Short synonyms (big not extensive, fix not "implement
    a solution for").
  - Technical terms exact. Code blocks unchanged. Errors quoted exact.
  - Pattern: `[thing] [action] [reason]. [next step].`
  - Not: "Sure! I'd be happy to help. The issue is likely caused by..."
  - Yes: "Bug in auth middleware. Token check uses `<` not `<=`. Fix:"
  - Drop caveman for: destructive ops warnings, irreversible confirmations,
    multi-step sequences where fragment order could confuse. Resume after.
  - User says "normal mode" or "stop caveman": revert, write normal.

You have no yield / ask / abort tool. Task done: plain text reply. CLI
loops back to user.
EOM

  my $custom_file = path($self->root)->child('.raider.md');
  if (-f $custom_file) {
    my $custom = eval { $custom_file->slurp_utf8 };
    if (defined $custom && length $custom) {
      $base .= "\n\n---\nUser's custom instructions (from $custom_file):\n\n$custom\n";
    }
  }

  my @skills = $self->_load_skill_texts;
  if (@skills) {
    $base .= "\n\n---\nLoaded skills (domain knowledge the user enabled for this session):\n\n"
           . join("\n\n", @skills) . "\n";
  }

  return $base;
}


has root => (
  is      => 'ro',
  isa     => 'Str',
  default => sub { Path::Tiny->cwd->stringify },
);


has allowed_commands => (
  is        => 'ro',
  isa       => 'ArrayRef[Str]',
  predicate => 'has_allowed_commands',
);


has max_iterations => (
  is      => 'ro',
  isa     => 'Int',
  default => 10_000,
);


has trace => (
  is      => 'ro',
  isa     => 'Bool',
  default => sub { -t STDOUT ? 1 : 0 },
);


has max_context_tokens => (
  is      => 'ro',
  isa     => 'Int',
  default => 40_000,
);


has context_compress_threshold => (
  is      => 'ro',
  isa     => 'Num',
  default => 0.7,
);


has skill_sources => (
  is      => 'ro',
  isa     => 'ArrayRef[HashRef]',
  lazy    => 1,
  builder => '_build_skill_sources',
);

sub _normalize_skill_spec {
  my ($spec) = @_;
  if (!ref $spec) {
    return (
      { type => 'file',   path => 'CLAUDE.md' },
      { type => 'claude', path => '.claude/skills' },
    ) if $spec eq 'claude';
    return { type => 'file', path => 'AGENTS.md' } if $spec eq 'openai'
                                                   || $spec eq 'agents'
                                                   || $spec eq 'codex';
    return { type => 'dir',  path => $spec };
  }
  return $spec if ref $spec eq 'HASH';
  return;
}

# Well-known per-tool files + source dirs. Used both for loading (when the
# matching profile flag is set) and for the "ignored but present" notice.
our %AGENT_PROFILES = (
  claude => [
    { type => 'file',   path => 'CLAUDE.md' },
    { type => 'claude', path => '.claude/skills' },
  ],
  openai => [
    { type => 'file',   path => 'AGENTS.md' },
  ],

lib/App/Raider.pm view on Meta::CPAN

  );
  my $class = $map{$self->engine_name}
    or die "Unknown engine: " . $self->engine_name . "\n";
  return $class;
}

sub _build_mcps {
  my ($self) = @_;

  my $files = build_file_tools_server(root => $self->root);

  my $bash = MCP::Run::Bash->new(
    tool_name         => 'bash',
    tool_description  => 'Run a shell command with bash -c. Returns exit code, stdout, and stderr. Use this for ls, grep, find, git, cat, running tests, any shell pipeline â€” anything you would type at a terminal.',
    working_directory => $self->root,
    ($self->has_allowed_commands ? (allowed_commands => $self->allowed_commands) : ()),
    timeout => 120,
  );

  my $web = build_web_tools_server(loop => $self->loop);

  my @clients;
  for my $server ($files, $bash, $web) {
    my $client = Net::Async::MCP->new(server => $server);
    $self->loop->add($client);
    push @clients, $client;
  }
  return \@clients;
}

sub _build_engine {
  my ($self) = @_;
  my $class = $self->_engine_class;
  Module::Runtime::require_module($class);

  my %args = (
    mcp_servers => $self->_mcps,
  );
  $args{api_key} = $self->api_key if length $self->api_key;
  $args{model}   = $self->model   if $self->has_model;

  # Engine-level overrides: .raider.yml then engine_options (CLI wins).
  my $yml = $self->_load_yml_options;
  %args = (%args, %$yml, %{$self->engine_options});

  return $class->new(%args);
}

sub _build_raider {
  my ($self) = @_;
  my @plugins;
  if ($self->trace) {
    # Pass as name(s) so PluginHost injects `host` (required by
    # Langertha::Plugin). The flat-list form is [Name, {args}, Name, ...].
    push @plugins, '+App::Raider::Plugin::Trace';
  }
  push @plugins, '+App::Raider::Plugin::Situation';
  return Langertha::Raider->new(
    engine                     => $self->_engine,
    mission                    => $self->mission,
    max_iterations             => $self->max_iterations,
    max_context_tokens         => $self->max_context_tokens,
    context_compress_threshold => $self->context_compress_threshold,
    (@plugins ? (plugins => \@plugins) : ()),
  );
}


async sub raid_f {
  my ($self, @messages) = @_;
  for my $mcp (@{$self->_mcps}) {
    await $mcp->initialize;
  }
  return await $self->_raider->raid_f(@messages);
}


sub run {
  my ($self, @messages) = @_;
  my $f = $self->raid_f(@messages);
  $self->loop->await($f);
  return $f->get;
}


sub raider { $_[0]->_raider }



sub loaded_skill_names {
  my ($self) = @_;
  my @names;
  for my $spec (@{$self->skill_sources}) {
    my $type = $spec->{type} // 'dir';
    my $rel  = $spec->{path};
    next unless defined $rel && length $rel;
    my $base = Path::Tiny::path($rel);
    $base = Path::Tiny::path($self->root)->child($rel) unless $base->is_absolute;
    if ($type eq 'file') {
      push @names, $base->basename if -f $base;
      next;
    }
    next unless -d $base;
    if ($type eq 'claude') {
      for my $dir (sort $base->children) {
        next unless -d $dir;
        push @names, $dir->basename if -f $dir->child('SKILL.md');
      }
    }
    else {
      for my $f (sort $base->children) {
        push @names, $f->basename if -f $f && $f =~ /\.md$/;
      }
    }
  }
  return @names;
}


sub ignored_agent_files {
  my ($self) = @_;

lib/App/Raider.pm view on Meta::CPAN

the first C<*_API_KEY> env var found.

=item * Optional skill-loading from C<.claude/skills/*/SKILL.md>,
C<AGENTS.md>, plain markdown directories, or any mix.

=item * Engine-attribute config via C<.raider.yml> in L</root> plus
L</engine_options> merge.

=item * Live trace plugin (L<App::Raider::Plugin::Trace>) and
situation-injection plugin (L<App::Raider::Plugin::Situation>).

=item * On-the-fly how-to-use-raider documentation generator
(L<App::Raider::Skill>).

=back

The distribution intentionally stays small. It is the thin CLI-oriented
layer on top of Langertha's engine/agent machinery. The CLI front-end is
L<raider>.

=head2 engine_name

Langertha engine class shortcut (e.g. C<'anthropic'>, C<'openai'>,
C<'deepseek'>, C<'groq'>, C<'mistral'>, C<'gemini'>, C<'ollama'>). Defaults to
C<'anthropic'>.

=head2 default_model_for_engine

Per-engine default model when L</model> is not explicitly set.

=head2 model

Model identifier to pass to the engine. If unset, the engine picks its default.

=head2 api_key_env

Name of the environment variable used for the current engine's API key
(for display / debugging). Returns undef for engines that don't use an API
key (e.g. ollama).

=head2 api_key

API key for the engine. Defaults to an engine-appropriate environment variable.

=head2 mission

System prompt / mission statement for the Raider. Defaults to a generic
assistant persona.

=head2 root

Working directory for tool operations. Defaults to the current process cwd.
File tools are chrooted to this directory; bash commands inherit it as their
default working directory.

=head2 allowed_commands

Optional arrayref restricting which bash commands may run (first word match).
When undef, any command is allowed.

=head2 max_iterations

Maximum tool-calling iterations per raid. Defaults to 10_000 â€” effectively
unlimited, so a raid only ends when the model itself stops emitting tool
calls. The conversation history is preserved between raids, so the next user
message in the REPL simply continues the same thread.

Set this to a smaller number if you want a hard safety cap.

=head2 trace

Emit live ANSI-colored progress output (iteration markers, tool calls, tool
results) via L<App::Raider::Plugin::Trace>. Defaults to on when STDOUT is a
terminal.

=head2 max_context_tokens

Trigger history auto-compression once the last prompt exceeds
C<context_compress_threshold * max_context_tokens>. Defaults to 40_000, which
keeps the running session comfortably under typical per-minute rate limits
(Anthropic org default: 50k input tokens/min on Haiku).

=head2 context_compress_threshold

Fraction of L</max_context_tokens> at which compression kicks in. Defaults to
C<0.7>.

=head2 skill_sources

ArrayRef of skill-source specs to load and append to the mission. Each spec
is a hashref:

    { type => 'claude', path => '.claude/skills' }  # Claude Code SKILL.md tree
    { type => 'dir',    path => 'my-skills', glob => '*.md' }

Settable via L</skill_sources>, via the C<skills> key in F<.raider.yml>, or
via the CLI flags C<--claude> / C<--skills PATH>.

=head2 engine_options

HashRef of extra attributes forwarded to the engine constructor
(e.g. C<temperature>, C<response_size>, C<seed>). Merged on top of values
loaded from C<.raider.yml> in the working directory.

=head2 raid_f

    my $result = await $app->raid_f($prompt);

Async variant: drives one raid iteration and returns the
L<Langertha::Raider::Result>.

=head2 run

    my $result = $app->run($prompt);

Synchronous convenience wrapper around L</raid_f>. Runs the I/O loop until the
raid completes and returns the result (which stringifies to the final text).

=head2 raider

Returns the underlying L<Langertha::Raider> instance (lazily built).

=head2 trace_plugin

( run in 0.826 second using v1.01-cache-2.11-cpan-96521ef73a4 )