dsh-pollyreach

Readme

# dsh-pollyreach

A distributable [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) bundle for PollyReach. It registers seven native model-callable tools plus the PollyReach skill, and includes secure shell CLIs for manual use.

## Included capabilities

- Register and securely persist a PollyReach credential.
- Complete account activation and retrieve the assigned phone number.
- Submit outbound phone tasks and poll for full results.
- Check credit balance without treating a zero balance as an invalid token.
- Retrieve unread incoming-call data without flattening the API response.
- Update the inbound answering prompt.

## Requirements

- Node.js 22.19 or newer.
- DeepSeek Harness `@deepseek-ai/dsh` developer preview compatible with `dsh-tools 0.0.1-rc.1`.
- `curl` and `jq` only if you use the optional shell scripts.

## Install

Install a local checkout into an existing profile:

```bash
dsh plugin --profile demo add /absolute/path/to/pollyreach-dsh-plugin
dsh --profile demo --dump-config
dsh --profile demo
```

Install a packed release:

```bash
npm pack
dsh plugin --profile demo add ./dsh-pollyreach-1.0.3.tgz
```

After publishing to npm, users can install it with:

```bash
dsh plugin --profile demo add dsh-pollyreach@1.0.3
```

Remove it with:

```bash
dsh plugin --profile demo remove dsh-pollyreach
```

The bundle contributes `cordis.patch.yml`; users do not need to edit the generated profile manifest manually.

## Native tools

| Tool | Purpose |
|---|---|
| `pollyreach_register` | Register and atomically save a new credential |
| `pollyreach_activation_status` | Check/poll activation and save the assigned number |
| `pollyreach_send_call` | Submit one outbound task |
| `pollyreach_query_call` | Poll for the actual outbound result |
| `pollyreach_balance` | Return the complete balance response |
| `pollyreach_inbound_calls` | Return unread incoming-call data |
| `pollyreach_update_inbound_prompt` | Change incoming-call behavior |

The plugin also registers `SKILL.md` through `ctx.skills`, so the Harness skill catalog can load behavioral guidance on demand.

## Configuration

Override defaults in the profile's `cordis.patch.yml`. Patch rows replace the whole config object, so include every value you want to preserve:

```yaml
- id: pollyreach-tools
  name: dsh-pollyreach
  config:
    apiBaseUrl: https://api.pollyreach.ai
    credentialsPath: ~/.config/PollyReach/key.json
    source: openclaw
    requestTimeoutMs: 30000
    pollIntervalMs: 2000
    activationMaxAttempts: 60
    queryMaxAttempts: 300
    inboundMaxAttempts: 10
```

`source` defaults to `openclaw` because that is the current PollyReach device-registration API contract, even though the client runtime is DeepSeek Harness.

## Credential security

The registration tool stores this shape at `~/.config/PollyReach/key.json`:

```json
{
  "token": "redacted",
  "agent_name": "my-agent",
  "activation_url": "https://agent.pollyreach.ai/auth?code=example",
  "ai_virtual_phone": null
}
```

The directory is created with restrictive permissions and the file is atomically written with mode `0600`. The token is intentionally omitted from the registration tool result. Never commit the real file; `examples/key.example.json` contains placeholders only.

## Optional shell CLI

The scripts are useful for diagnostics outside the model tool pipeline:

```bash
scripts/register.sh "Agent Name" "AI agent powered by DeepSeek Harness"
scripts/activation.sh
scripts/send.sh 'Call +1... and ask ...'
scripts/query.sh
scripts/balance.sh
scripts/inbound.sh
scripts/prompt_update.sh 'Answer professionally and take a detailed message.'
```

They read the same credential file automatically; tokens are never command-line arguments. Tests can override endpoints and paths with `POLLYREACH_API_BASE_URL` and `POLLYREACH_CREDENTIALS_FILE`.

## Validate and package

```bash
npm install
npm run check
npm run pack:check
```

No real PollyReach account is required for tests; network calls are mocked. Before publishing, test the packed tarball against a disposable dsh profile:

```bash
npm pack
dsh plugin --profile pollyreach-smoke add ./dsh-pollyreach-1.0.3.tgz
dsh --profile pollyreach-smoke --dump-config
```

## Compatibility note

This package targets the current DeepSeek Harness developer preview (`@deepseek-ai/dsh` 0.1.0-rc.7 and `@deepseek-ai/dsh-tools` 0.0.1-rc.1). Preview APIs may change; update and retest the pinned peer version before publishing a new release.

## License

MIT