Feat: perstack log command

[FL4TLiN3]

Description

Add a log viewing command for inspecting job/run history and events.

depends on #177

Use Case

Enable developers and operators to:

• View execution history for debugging
• Inspect specific checkpoints
• Filter events with jq-like queries
• Analyze run behavior post-execution

Proposed Solution

Add command to apps/perstack/src/:

src/
├── log.ts                 # New command
└── lib/
    └── log-filter.ts      # jq-like query implementation

CLI Options

perstack log --job <jobId>
perstack log --run <runId>
perstack log --checkpoint <checkpointId>
perstack log --filter <jq-like-query>

Options can be combined:

perstack log --job abc123 --filter '.type == "completeRun"'

Filter Examples

# Show only completeRun events
perstack log --job abc123 --filter '.type == "completeRun"'

# Show tool calls for specific skill
perstack log --run xyz789 --filter '.toolCalls[]? | select(.skillName == "base")'

# Show events after step 5
perstack log --job abc123 --filter '.stepNumber > 5'

Output Format

• Terminal output with colors (event type, timestamp, summary)
• JSON output with --json flag
• Pagination for large result sets

Acceptance Criteria

• --job shows all events for a job
• --run shows events for specific run
• --checkpoint shows checkpoint details (messages, status, etc.)
• --filter supports basic jq-like queries
• Output formatted for terminal with colors
• --json flag for machine-readable output
• Graceful handling of non-existent job/run/checkpoint

[github-actions]

I've analyzed the codebase to provide guidance on implementing the perstack log command feature request in issue #183.

Current Architecture

CLI Commands Location: /packages/perstack/src/

• Existing commands: run.ts, start.ts, status.ts, publish.ts, tag.ts, unpublish.ts
• All use Commander.js for CLI parsing

Storage System (@perstack/storage):

• Events: Stored as JSON files at perstack/jobs/{jobId}/{runId}/event-{timestamp}-{stepNumber}-{type}.json
• Jobs: Stored at perstack/jobs/{jobId}/job.json
• Checkpoints: Stored at perstack/jobs/{jobId}/checkpoints/{checkpointId}.json

Existing Functions (ready to use):

// From @perstack/storage
getEventsByRun(jobId, runId)      // Get event metadata
getEventContents(jobId, runId, maxStepNumber?)  // Get full event objects
getAllJobs()                       // Get all jobs
retrieveJob(jobId)                 // Get specific job
getCheckpointsByJobId(jobId)      // Get all checkpoints for a job

Event Types (from @perstack/core):

• startRun, startGeneration, retry, callTools, callInteractiveTool, callDelegate
• resolveToolResults, resolveThought, attemptCompletion, finishToolCall
• resumeToolCalls, finishAllToolCalls, continueToNextStep
• stopRunByInteractiveTool, stopRunByDelegate, stopRunByExceededMaxSteps, completeRun

Implementation Guidance

1. Command Structure (following existing patterns)

Create /packages/perstack/src/log.ts:

import { Command } from "commander"
import { getAllJobs, getEventContents, getCheckpointsByJobId } from "@perstack/storage"

export const logCommand = new Command()
  .command("log")
  .description("View execution history and events")
  .option("--job <jobId>", "Show events for a specific job")
  .option("--run <runId>", "Show events for a specific run")
  .option("--checkpoint <checkpointId>", "Show checkpoint details")
  .option("--filter <query>", "Filter events with jq-like query")
  .option("--json", "Output in JSON format")
  .action(async (options) => {
    // Implementation here
  })

2. Filter Implementation

For the jq-like filtering, consider using:

• Option A: jq-in-the-browser - Full jq implementation
• Option B: jmespath - JSON query language (simpler)
• Option C: Custom implementation using JavaScript filter/map

Create /packages/perstack/src/lib/log-filter.ts for the filtering logic.

3. Output Formatting

Use the existing @perstack/tui package for terminal output with colors. See how status.ts uses renderStatus from @perstack/tui.

4. Dependency Note

⚠️ Issue #177 plans to move CLI packages to apps/ directory. Once that's merged, the new command should be at:

• apps/perstack/src/log.ts (instead of packages/perstack/src/log.ts)

Recommended Implementation Order

1. Basic functionality (--job, --run, --checkpoint without filters)
2. JSON output (--json flag)
3. Filtering (--filter with basic queries)
4. Terminal formatting (colors, pagination)
5. Advanced filtering (complex jq-like queries)

Example Usage Pattern

Based on existing commands, the implementation should:

• Handle errors gracefully with try-catch
• Exit with process.exit(1) on errors
• Use console.error() for error messages
• Use console.log() for output

The storage functions are already available and tested, so the main work is building the CLI interface and filtering logic around them.

---

🤖 Bot Activity

✅ Done
---