npm package: @pioneer-platform/pioneer-agent
Description: Shared agent infrastructure for Pioneer CLI and Desktop applications
Author: Pioneer Platform
Latest version: 0.1.0

# @pioneer-platform/pioneer-agent

Shared agent infrastructure for Pioneer CLI and Desktop applications.

## Overview

This package provides core agent functionality for connecting to pioneer-server with:
- Agent metadata management (persistent ID, capabilities, status)
- Pioneer SDK integration with built-in pioneer-events WebSocket
- Automatic heartbeat and status tracking
- Event publishing/subscription

## Features

- ✅ **Agent Metadata** - Persistent agent ID, name, type, capabilities
- ✅ **Pioneer SDK Integration** - Uses pioneer-events for WebSocket
- ✅ **Heartbeat** - Automatic 30s heartbeat to keep connection alive
- ✅ **Status Tracking** - online, idle, busy, offline states
- ✅ **Event System** - Publish/subscribe to agent events
- ✅ **Type-Safe** - Full TypeScript support

## Installation

```bash
npm install @pioneer-platform/pioneer-agent
```

## Usage

### Basic Setup

```typescript
import { PioneerAgentClient } from '@pioneer-platform/pioneer-agent';

const agent = new PioneerAgentClient({
  pioneerUrl: 'http://localhost:9001',
  pioneerWss: 'ws://localhost:9001',
  pioneerApiKey: process.env.PIONEER_API_KEY,
  agentType: 'cli', // or 'desktop', 'webapp', 'service'
  appVersion: '1.0.0',
  workingDirectory: process.cwd(),
});

// Connect to pioneer-server
await agent.connect();

console.log('Agent ID:', agent.getAgentId());
console.log('Connected:', agent.isConnected());
```

### Agent Metadata

Agent metadata is automatically persisted to `~/.pioneer/agent-metadata.json`:

```json
{
  "id": "pioneer-cli-abc12345",
  "name": "pioneer@hostname",
  "type": "cli",
  "directory": "/path/to/project",
  "hostname": "macbook-pro",
  "username": "user",
  "platform": "darwin",
  "arch": "arm64",
  "nodeVersion": "v20.11.0",
  "version": "1.0.0",
  "pid": 12345,
  "registeredAt": 1234567890,
  "lastHeartbeat": 1234567890,
  "capabilities": {
    "mcp": true,
    "a2a": true,
    "inference": true,
    "fileSystem": true
  },
  "status": "online"
}
```

### Update Agent Status

```typescript
// Update status
agent.updateStatus('busy');

// Status will be synced to server via pioneer-events
```

### Publish Events

```typescript
// Publish custom event
agent.publishEvent('task:started', {
  taskId: '123',
  taskName: 'Build Project',
});

// Subscribe to events
agent.onEvent('task:complete', (data) => {
  console.log('Task completed:', data);
});
```

### Access Pioneer SDK

```typescript
// Get the underlying SDK instance
const sdk = agent.getSDK();

// Access SDK data
console.log('Balances:', sdk.balances);
console.log('Pubkeys:', sdk.pubkeys);
```

### Cleanup

```typescript
// Disconnect when done
agent.disconnect();
```

## Agent Types

- `cli` - Command-line interface agents
- `desktop` - Desktop application agents
- `webapp` - Web application agents
- `service` - Background service agents

## Architecture

```
PioneerAgentClient
  ├── AgentMetadataManager (persistent metadata)
  ├── Pioneer SDK (with built-in WebSocket)
  ├── Heartbeat Timer (30s interval)
  └── Event System (publish/subscribe)
```

## Pioneer-Events Integration

The agent uses pioneer-sdk's built-in pioneer-events system for all WebSocket communication:

- **Authentication** via `queryKey` and `username`
- **Heartbeat** published as `agent:heartbeat` events
- **Status** published as `agent:status` events
- **Custom Events** via `publishEvent()` method

No custom Socket.IO code needed - everything goes through pioneer-sdk!

## Development

```bash
# Build
npm run build

# Watch mode
npm run dev

# Clean
npm run clean
```

## License

MIT