bapung/ngn-agent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
ngn-agent/.planning/phases/08-cron-reporting/08-CONTEXT.md
Bagas Purwa Sentika 47d0b80be8 feat(08-cron-reporting): create archive-stale-sessions.sh with dry-run toggle 
- Created ~/.hermes/scripts/archive-stale-sessions.sh (1146 bytes, executable)
- Script has DRY_RUN=true safe default (export only, no prune)
- Export uses date-stamped JSONL filename
- Prune gated behind DRY_RUN=false with --older-than 30 --yes
- set -euo pipefail strict error handling
- Created ~/.hermes/archive/sessions/ archive directory
- Progress echo statements for Telegram delivery
2026-06-15 22:45:14 +08:00

7.0 KiB
Raw Permalink Blame History

Phase 8: Cron Reporting - Context

Gathered: 2026-06-14 Status: Ready for planning

## Phase Boundary

Set up daily operational reporting and weekly stale session lifecycle management using Hermes' built-in cron and session management capabilities.

In scope: Daily report cron job via Telegram, Jira progress updates for active sessions, weekly stale session summary, weekly stale session archive using hermes sessions export + hermes sessions prune

Out of scope: Session lifecycle skill (Phase 7 already done), tool provisioning (Phase 9), portable setup script (Phase 9), auto-closing Jira tickets (user must specify), modifying Jira ticket statuses without user instruction

## Implementation Decisions

Report Schedule

  • D-01: Daily report runs at 09:00 SGT (UTC+8) — Hermes cron job using hermes cron create
  • D-02: Weekly stale session summary runs Sunday 20:00 SGT (UTC+8) — separate cron job
  • D-03: Weekly stale session archive runs Sunday 20:00 SGT (UTC+8) — same cron job as summary (archive after summary)

Daily Report Content

  • D-04: Daily report updates all Jira tickets linked to active sessions with last activity and progress (session → Jira is 1-to-many mapping)
  • D-05: Do NOT update Jira ticket statuses — only add comments with session progress/state
  • D-06: Daily report delivered via Telegram to user's DM channel
  • D-07: Report includes: list of active sessions, last activity timestamp, Jira ticket keys updated

Weekly Stale Report

  • D-08: Weekly report summarizes all inactive sessions (>30d since last activity) — session title, last activity date, linked Jira ticket
  • D-09: Delivered via Telegram to user's DM channel
  • D-10: No auto-comments on stale tickets — only reported in the summary

Session Archive

  • D-11: Use native Hermes commands — no custom scripts:
    • Export: hermes sessions export --older-than 30d --output ~/.hermes/archive/sessions/sessions-$(date +%Y%m%d).jsonl
    • Prune: hermes sessions prune --older-than 30d --confirm (after export verification)
  • D-12: Archive location: ~/.hermes/archive/sessions/
  • D-13: Run weekly Sunday 20:00 SGT, after the stale summary report

Jira Integration

  • D-14: Active sessions with linked Jira tickets get daily progress comments added automatically
  • D-15: Stale sessions with Jira tickets are mentioned in the weekly summary only (no auto-comment)
  • D-16: Ticket status transitions only happen when user explicitly asks

Cron Job Mechanism

  • D-17: Both cron jobs use Hermes skill-backed cron (hermes cron create with a skill that defines the report behavior)
  • D-18: The daily report skill references the existing session skill (Phase 7) and ngn-jira skill (Phase 4) for operations
  • D-19: The stale archive step uses no_agent: true mode (deterministic CLI commands, no LLM cost)

Technical Corrections from Research

  • hermes sessions export has NO --older-than flag — exports ALL sessions, filters by --source or --session-id only. Archive script must export all then prune --older-than 30 --yes to clean up.
  • hermes sessions prune uses --yes (not --confirm)
  • hermes sessions list has NO --json flag
  • Jira-session mapping lives in hindsight memory (saved by Phase 7 session skill), not in the session DB — cron agent must use hindsight_recall to discover which Jira tickets belong to which sessions
  • System timezone already SGT (+08) — no TZ configuration needed
  • Three cron jobs required: Daily report (09:00 SGT), weekly stale summary (Sunday 20:00 SGT), weekly archive (Sunday 20:05 SGT — 5 min after summary to avoid race conditions)

the agent's Discretion

  • Report formatting: Telegram message structure — planner designs based on 4096-char limit
  • Cron job naming: Standard naming convention for the three cron jobs
  • Dry-run phase: First archive via hermes sessions export sessions.jsonl then review JSONL before enabling prune

<canonical_refs>

Canonical References

Downstream agents MUST read these before planning or implementing.

Hermes Documentation

  • ~/.hermes/config.yaml §cron: — Existing cron configuration (wrap_response, max_parallel_jobs)
  • ~/.hermes/config.yaml §TELEGRAM_HOME_CHANNEL — Delivery channel for cron output
  • hermes cron create --help — Cron job creation syntax

Session Management

  • hermes sessions export --help — Session export to JSONL
  • hermes sessions prune --help — Session pruning
  • hermes sessions list --help — Session listing

Completed Phases (Dependencies)

  • .planning/phases/05-hindsight-memory-provider/05-01-SUMMARY.md — Hindsight active for cross-session insights
  • .planning/phases/07-main-session-skill/07-01-SUMMARY.md — Session lifecycle skill creates structured sessions with Jira links

Project Documents

  • initial-plan.md §func daily_report() — Original reporting spec
  • .planning/REQUIREMENTS.md §CRON-01, CRON-02, CRON-03 — Requirement definitions
  • .planning/ROADMAP.md §Phase 8 — Phase goal and success criteria

Existing Skills (Referenced by cron skills)

  • ~/.hermes/skills/ngn-agent/session/SKILL.md — Session lifecycle skill
  • ~/.hermes/skills/ngn-agent/jira/SKILL.md — Jira query skill </canonical_refs>

<code_context>

Existing Code Insights

Reusable Assets

  • Hermes cron system: Fully operational in gateway — hermes cron create with skill-backed or no_agent jobs
  • Telegram delivery: TELEGRAM_HOME_CHANNEL already set to user's DM (474440517)
  • Session DB: SQLite-based, queryable via hermes sessions list --json
  • ngn-jira script: Available in Docker for Jira operations

Established Patterns

  • Skill-backed cron: Cron job that loads a SKILL.md and lets the agent compose the report
  • no_agent cron: Deterministic commands without LLM involvement (for archive step)

Integration Points

  • hermes cron create → Register daily report job
  • hermes cron create --no-agent → Register archive job
  • ~/.hermes/archive/sessions/ → Archive storage directory (create) </code_context>
## Specific Ideas
  • The daily report should be a Hermes skill that instructs the agent to query session DB for active sessions, then update each session's Jira ticket with a progress comment, then compose a Telegram summary
  • The stale archive should be a no_agent cron: hermes sessions export ... && hermes sessions prune ...
  • Start with dry-run on archive: run export manually first, verify JSONL, then enable the prune
  • SGT (UTC+8) timezone should be set explicitly in the cron job or system config
## Deferred Ideas
  • Auto-close tickets for archived sessions — user wants manual control
  • Teams gateway delivery — only Telegram for now
  • Custom archive dashboard — JSONL files are searchable via grep/FTS5

Phase: 8-Cron Reporting Context gathered: 2026-06-14

Reference in New Issue View Git Blame Copy Permalink