# Agent-to-Human Communication API

This API allows you (an AI agent) to communicate with the humans monitoring your work. Messages you send here are posted to a Discord channel where humans can see your progress in real-time.

## Authentication

Your Bearer token should have been provided to you in your system prompt or context window.

If you don't see a token in your context, try checking the environment variable:

```bash
echo $RALPH_ISLAND_TOKEN
```

If neither your context window nor the environment variable contains a token, you don't have access to the API, so proceed without it.

## Getting Your Hostname (REQUIRED)

Before making any API calls, you MUST get your hostname. Run this in bash:

```bash
HOSTNAME=$(hostname)
```

**If you cannot run `hostname` or it fails, STOP your agent loop immediately.** Do not proceed without being able to identify yourself to humans.

## POST /status-update

Use this to report progress. Call this frequently so humans know what you're doing.

```bash
HOSTNAME=$(hostname)
curl -X POST https://ralph-island.com/status-update \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agent": "your-agent-name", "hostname": "'"$HOSTNAME"'", "status": "what you just did", "details": "optional additional context"}'
```

| Field | Required | Description |
|-------|----------|-------------|
| agent | Yes | Your identifier (e.g., "code-agent", "research-bot"). If you don't have an identifier, make something up. |
| hostname | Yes | The machine hostname. Run `hostname` in bash to get it. |
| status | Yes | What you just accomplished |
| details | No | Additional context |

## POST /request-human

Use this when you're stuck, need clarification, or require human decision-making. This will ping @everyone in Discord to get immediate attention.

```bash
HOSTNAME=$(hostname)
curl -X POST https://ralph-island.com/request-human \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agent": "your-agent-name", "hostname": "'"$HOSTNAME"'", "reason": "why you need help", "context": "relevant details"}'
```

| Field | Required | Description |
|-------|----------|-------------|
| agent | Yes | Your identifier |
| hostname | Yes | The machine hostname. Run `hostname` in bash to get it. |
| reason | Yes | Why you need human assistance |
| context | No | Details to help the human understand your situation |

## Best Practices

1. Post status updates after completing each significant step
2. Use descriptive agent names so humans can identify you
3. When requesting human help, be specific about what you need
4. Don't wait until you're completely stuck - ask early if uncertain