agents: add manifest-driven subagent packages and lifecycle tooling

[benvinegar]

Summary

• introduce a manifest-driven subagent package system under pi/subagents/*
• add runtime extensions for subagent lifecycle and utilities:
  • subagent_manage
  • subagent_util
• migrate sentry-agent to the new package format with its own manifest, skill, and utility script
• add operator CLI for subagents (baudbot subagents / bin/subagents.sh)
• wire deploy, health/security checks, heartbeat expectations, and control-agent runbook docs to the new model

Why

• makes subagents plug-and-play (install/enable/autostart/reconcile)
• keeps agent-specific prompts/utilities portable and composable
• improves token efficiency by encouraging package-local utility scripts

Tests

• npm run lint:shell
• npm run test:shell
• npm run test:js
• npm test

Additional verification

• live smoke test on a DigitalOcean VPS (Debian 13) for subagent lifecycle commands (list, autostart-on, reconcile, status, stop)

[greptile-apps]

Greptile Summary

Introduces a manifest-driven subagent package system that makes subagents plug-and-play with declarative lifecycle management. The PR migrates sentry-agent to the new format and adds CLI tooling for install/enable/autostart/start/stop/reconcile operations.

Key changes:

• New pi/subagents/* package structure with subagent.json manifests, SKILL.md prompts, and optional utility scripts
• subagent_manage tool for lifecycle operations (replaces manual agent_spawn calls)
• subagent_util tool for running package-local utility scripts with base64-encoded arguments
• Shell CLI via baudbot subagents for operator management
• Heartbeat integration to automatically discover expected sessions from manifests
• Deploy script updates to include subagents directory in artifact tracking
• Comprehensive test coverage for both TypeScript and shell implementations

Architecture benefits:

• Token efficiency via package-local utilities (avoids embedding logic in prompts)
• Portable agent packages with self-contained configs
• Declarative state management with manifest defaults + runtime overrides
• Consistent behavior between TypeScript extensions and shell CLI

The implementation is well-structured with proper validation, path traversal protection, and thorough testing. One minor style issue with shell quoting consistency noted.

Confidence Score: 5/5

• This PR is safe to merge - adds well-tested infrastructure with proper validation and security considerations
• The PR introduces a significant new subsystem with 2600+ lines of code, but demonstrates high quality: comprehensive unit and integration tests, proper input validation (manifest parsing, path traversal protection), consistent dual implementation (TypeScript + shell), good documentation, and integration with existing systems (heartbeat, deploy, security audit). The single style issue found is non-critical and doesn't affect functionality.
• No files require special attention - the shell quoting style issue in bin/subagents.sh is minor

Important Files Changed

Filename	Overview
pi/extensions/subagent-registry.ts	Core registry implementing manifest parsing, package discovery, state management, and model resolution - well-structured with proper validation
pi/extensions/subagent-manager.ts	Lifecycle management tool with session spawning, readiness checks, and state transitions - properly uses shellQuote for command construction
pi/extensions/subagent-util.ts	Utility runner tool with proper shell quoting, output truncation, and session name inference - clean implementation
bin/subagents.sh	Shell implementation of subagent lifecycle commands - has complex quoting in spawn_one that could be more robust
pi/subagents/sentry-agent/subagent.json	Manifest for sentry-agent migration to new package format - proper structure with utility declarations
bin/deploy.sh	Added subagents directory to deployment manifest and integrity tracking - consistent with existing patterns
pi/skills/control-agent/SKILL.md	Updated control agent instructions to use subagent_manage tool instead of manual spawn - cleaner approach

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    Start([Subagent Reconcile]) --> Discover[Discover packages from ~/.pi/agent/subagents]
    Discover --> ReadState[Read state from subagents-state.json]
    ReadState --> Loop{For each package}
    
    Loop --> CheckFlags{installed && enabled && autostart?}
    CheckFlags -->|No| Skip[Skip package]
    CheckFlags -->|Yes| CheckRunning{Session running?}
    
    CheckRunning -->|Yes| Skip
    CheckRunning -->|No| ResolveModel[Resolve model from profile]
    
    ResolveModel --> ValidatePaths[Validate cwd & skill_path]
    ValidatePaths --> SpawnTmux[Spawn tmux session with pi agent]
    
    SpawnTmux --> WaitAlias[Poll for ready_alias]
    WaitAlias --> CheckSocket{Socket exists & alive?}
    
    CheckSocket -->|Yes, within timeout| Success[✓ Started]
    CheckSocket -->|No, timeout exceeded| Timeout[⚠️ Readiness timeout]
    
    Skip --> Loop
    Success --> Loop
    Timeout --> Loop
    
    Loop -->|Done| End([Report: started/skipped/errors])

Loading

_{Last reviewed commit: 347902f}

[greptile-apps]

_{27 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}