/ 
App-karr-0.301
/ App::karr::ActivityLog

NAME

App::karr::ActivityLog - Activity log writer for karr board operations

VERSION

version 0.301

SYNOPSIS

use App::karr::ActivityLog;
use App::karr::Git;

my $git = App::karr::Git->new(dir => '.');
my $log = App::karr::ActivityLog->new(git => $git, role => 'agent');

$log->log_entry(
    agent   => 'agent-fox',
    action  => 'pick',
    task_id => 5,
    detail  => 'in-progress',
);

DESCRIPTION

Writes append-style JSON log entries to refs/karr/log/<identity> refs. Each entry receives an automatic timestamp if not provided.

The identity is <role>/<email>: the Git user email (sanitized for ref names) qualified by a role (user or agent). The role disambiguates a human and an AI agent that share one Git config. It defaults to the KARR_ROLE environment variable, or user.

METHODS

role

The actor role, user (default) or agent. Read from KARR_ROLE when not given explicitly.

identity

my $id = $log->identity;   # e.g. "agent/getty_conflict.industries"

The sanitized <role>/<email> string keying this actor's log.

log_entry

$log->log_entry(
    agent   => 'agent-fox',
    action  => 'pick',
    task_id => 5,
    detail  => 'in-progress',
    ts      => '2026-05-15T10:00:00Z',  # optional, auto-generated
);

Writes a JSON log line to the per-identity ref. The ref path is refs/karr/log/<role>/<sanitized_email>.

Returns the result of "write_ref" in Git.

entries

my @entries = $log->entries;

Returns the decoded log entries for this identity, oldest first. For the user role, falls back to the legacy bare-email ref when the role-qualified ref does not yet exist.

last_entry

my $entry = $log->last_entry;

The most recent decoded log entry for this identity, or undef if none.

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/karr/issues.

IRC

Join #langertha on irc.perl.org or message Getty directly.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <getty@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.