agentping

# AgentPing - Agent-Human Interaction Protocol ## Overview AgentPing provides structured communication between AI agents and humans. Instead of unstructured text, agents create typed "pings" that render appropriately across surfaces (CLI, web UI, Slack, Telegram). **Phase 2 Status (Production Ready):** - ✅ 198 React components with Cyber-Premium dark theme - ✅ 38 E2E tests passing across 5 browsers (Chromium, Firefox, WebKit, Mobile) - ✅ Full ADA compliance with WCAG 2.1 AA standards - ✅ Responsive design (mobile, tablet, desktop) - ✅ Tailwind CSS v4 integration - ✅ Storybook documentation for P0/P1 components ## Quick Decision Tree ``` Agent needs human input? | +-> Simple yes/no? | +-> Use `agentping approve "Deploy to production?"` | +-> Multiple options? | +-> Use `agentping select --options "A,B,C" "Choose approach"` | +-> Open-ended question? | +-> Use `agentping ask "What should I focus on?"` | +-> Multiple steps to approve? | +-> Use `agentping approve-steps --file steps.json` | +-> Just informing (no response)? +-> Use `agentping notify "Task completed"` ``` ## Installation ```bash # Via npm (global) npm install -g @agentping/cli # Via pnpm (monorepo) pnpm add @agentping/cli # Verify agentping --version ``` ## Core Commands ### 1. Approval (Yes/No) Request approval for an action: ```bash # Basic approval agentping approve "Deploy to production?" # With JSON output for agents agentping approve "Run database migration?" --json # With timeout agentping approve "Execute build?" --timeout 60 # Exit codes: 0=approved, 1=denied, 2=timeout, 3=error ``` JSON Output: ```json { "approved": true, "action": "approved", "enrichment": { "directives": [ {"type": "constraint", "rule": "run during low-traffic hours"} ], "notes": "approved for staging first" } } ``` ### 2. Ask (Freeform Question) Ask a question and wait for response: ```bash # Open-ended question agentping ask "What should I prioritize?" # With suggested options agentping ask "Which approach?" --options "A,B,C" # JSON output for parsing agentping ask "Database choice?" --options "postgres,mysql,sqlite" --json ``` JSON Output: ```json { "action": "answered", "data": { "type": "answer", "value": "postgres" }, "enrichment": { "notes": "we already use postgres in prod" } } ``` ### 3. Select (Multiple Choice) Present options for selection: ```bash # Single selection agentping select --title "Choose framework" --options "React,Vue,Svelte" # Multiple selection allowed agentping select --title "Select features" --options "auth,api,ui" --multiple # From JSON file agentping select --file options.json --json ``` Options JSON format: ```json { "title": "Choose deployment target", "options": [ {"id": "prod", "label": "Production", "description": "Live environment"}, {"id": "staging", "label": "Staging", "description": "Pre-production"} ], "allowMultiple": false } ``` ### 4. Step Approval (Multi-Step) Request approval for multiple steps: ```bash agentping approve-steps --file steps.json --json ``` Steps JSON format: ```json { "title": "Database Migration Plan", "context": "Migrating to new schema version", "steps": [ {"id": "backup", "description": "Create backup", "risk": "low", "reversible": true}, {"id": "migrate", "description": "Run migration", "risk": "medium", "reversible": true}, {"id": "verify", "description": "Verify integrity", "risk": "low", "reversible": true} ], "allowPartial": true } ``` JSON Output: ```json { "action": "selected", "data": { "type": "step_approval", "approvedSteps": ["backup", "verify"], "deniedSteps": ["migrate"] }, "enrichment": { "directives": [ {"type": "constraint", "rule": "wait for QA sign-off before migrate"} ] } } ``` ### 5. Notify (Fire-and-Forget) Send notification without waiting for response: ```bash # Info notification agentping notify "Build completed successfully" # Warning agentping notify --level warning "Tests are slow (>5m)" # Error agentping notify --level error "Deployment failed" ``` ### 6. Daemon Management Control the AgentPing daemon: ```bash # Start daemon agentping daemon start # Check status agentping daemon status # Stop daemon agentping daemon stop # Restart agentping daemon restart ``` ## Web UI Development ### Running the Development Server ```bash # Start daemon (in background) cd packages/adapters/daemon pnpm dev & # Start web UI (in foreground) cd packages/adapters/web-ui pnpm dev # Open browser to http://localhost:7891 ``` ### Running Storybook ```bash cd packages/adapters/web-ui pnpm storybook # Open browser to http://localhost:6006 ``` **Available Stories:** - P0 Components: Badge, Spinner, StatusIndicator, ProgressBar, ToggleSwitch, SearchInput, TextArea, Slider, DatePicker, MultiSelect - P1 Components: PingCard, StepChecklist, SelectionList, EnrichmentPanel, QuickActions See [Component Reference](./references/components.md) for full inventory. ### Running E2E Tests ```bash # Install Playwright browsers npx playwright install # Build required packages pnpm --filter @agentping/core build pnpm --filter @agentping/storage-sqlite build pnpm --filter @agentping/http-api build pnpm --filter @agentping/daemon build # Run E2E tests (38 tests × 5 browsers = 190 test runs) cd packages/adapters/web-ui pnpm test:e2e # View HTML report npx playwright show-report ``` **Test Coverage:** - All 10 ping types (Notification, Approval, Question, Selection, StepApproval, Research, Review, TaskWorkflow, Secret, Custom) - All P1 components (PingCard, StepChecklist, SelectionList, QuickActions, EnrichmentPanel) - Responsive layouts (mobile, tablet, desktop) - Keyboard navigation (j/k for navigation, 'a' for approve) - Accessibility (ARIA roles, screen reader support) ## Agent-First JSON Interface All commands support `--json` flag for structured output. Agents should: 1. Always use `--json` flag 2. Parse exit codes: 0=success, 1=denied, 2=timeout, 3=error 3. Handle enrichment directives in responses ### Input via stdin ```bash # Pipe JSON input echo '{"title":"Deploy?","action":"deploy to prod"}' | agentping approve --stdin --json # From file cat ping.json | agentping approve --stdin --json ``` ### Environment Variables ```bash AGENTPING_URL=http://localhost:7890 # API endpoint AGENTPING_TIMEOUT=300 # Default timeout (seconds) AGENTPING_AGENT_ID=my-agent # Default agent ID AGENTPING_SESSION_ID=session-123 # Default session ID ``` ## Ping Types Reference | Type | Use Case | Response | |------|----------|----------| | `notification` | FYI, no response | Auto-dismissed | | `question` | Open-ended query | Text answer | | `approval` | Yes/no decision | approved/denied | | `step_approval` | Multi-step approval | Selected steps | | `selection` | Pick from options | Selected IDs | | `research_request` | Research direction | Direction IDs | | `review_request` | Review content | Feedback | | `secret` | Sensitive input | Masked value | | `custom` | Extensible | Custom data | ## Directive Types Humans can enrich responses with directives: | Directive | Purpose | Example | |-----------|---------|---------| | `focus_on` | Direct attention | `{"type":"focus_on","target":"auth flow"}` | | `skip` | Ignore something | `{"type":"skip","target":"unit tests"}` | | `constraint` | Add rule | `{"type":"constraint","rule":"no breaking changes"}` | | `prioritize` | Set priority | `{"type":"prioritize","items":["security","perf"]}` | | `timeline` | Time constraint | `{"type":"timeline","deadline":"EOD","flexibility":"soft"}` | | `reference` | Provide link | `{"type":"reference","url":"https://..."}` | | `alternative` | Suggest option | `{"type":"alternative","suggestion":"use Redis"}` | ## Design System AgentPing uses the **Cyber-Premium** dark theme with: - **Background**: Deep black (#050505) with subtle elevation layers - **Text**: High-contrast (#ededed primary, #a1a1aa secondary) - **Accents**: Neon cyan (#00e5ff), green (#00ff9d), pink (#ff2a6d), amber (#ffb800) - **Effects**: Glassmorphism, neon glows, smooth animations - **Typography**: Inter (sans), JetBrains Mono (code) See [Design Standards](./references/design-standards.md) for complete reference. ## Accessibility (ADA Compliance) All components meet WCAG 2.1 AA standards: - ✅ Contrast ratios: 4.5:1 (normal text), 3:1 (large text, interactive) - ✅ Focus indicators: 2px cyan outline on keyboard navigation - ✅ Touch targets: 44×44px minimum (mobile), 32px (desktop) - ✅ Screen reader support: ARIA roles, labels, live regions - ✅ Keyboard navigation: Tab, Enter/Space, Escape, Arrow keys - ✅ Reduced motion: Respects `prefers-reduced-motion` See [Design Standards](./references/design-standards.md) for component-specific ADA checklists. ## Adapter Development Create custom adapters for new platforms: ```bash # Generate adapter scaffold agentping adapter create --name myplatform --template default ``` This creates: ``` adapters/myplatform/ +-- parser.ts # Message -> PingSpec +-- renderer.ts # Response -> Native format +-- config.yaml # Platform settings +-- index.ts # Barrel export ``` ### Parser Interface ```typescript interface IInteractionParser { readonly name: string; readonly priority: number; // Higher = tried first canParse(ping: Ping): boolean; parse(ping: Ping): ParsedInteraction; } ``` ### ParsedInteraction Output ```typescript interface ParsedInteraction { interactionType: string; // UI component hint quickActions: QuickAction[]; // 1-click responses uiHints: Record<string, unknown>; fallbackText: string; // Text-only fallback fallbackOptions: string[]; // Simple options } ``` ## Error Handling Exit codes: - `0` - Success (approved/answered) - `1` - Denied/rejected - `2` - Timeout - `3` - Error (network, validation, etc.) Error JSON format: ```json { "error": true, "code": "TIMEOUT", "message": "Response timeout after 300s", "pingId": "ping-abc123" } ``` ## Examples for AI Agents ### Claude Code Integration ```bash # Before destructive operation result=$(agentping approve "Delete 47 files from /src?" --json) if [ $? -eq 0 ]; then rm -rf /src/old/* fi # Get user direction direction=$(agentping ask "Which feature should I implement first?" \ --options "auth,api,dashboard" --json | jq -r '.data.value') ```