pine-assistant

Handle customer service, bills, reservations, and more via Pine AI — negotiate, cancel, dispute, book, and resolve from the terminal.

# Pine Assistant

Use the `pine` CLI to let Pine AI handle tasks on the user's behalf — customer service calls, bill negotiations, subscription cancellations, reservations, disputes, and more. Pine operates via phone calls, computer use (browser automation), emails, and faxes.

Pine is a **service with multiple sessions** — each task runs in its own session.

## CRITICAL: Always look up active sessions first

**NEVER claim you don't know about a session or task.** Before creating a new session, answering questions about Pine tasks, or saying you have no context, you MUST run:

```bash
pine sessions list --json
```

**Mandatory session lookup triggers:**
- The user mentions anything that could relate to a Pine task (a company name, account, refund, call, booking, etc.)
- The user asks you to do something that Pine could handle — check if a session already exists
- The user asks about progress, status, or follow-up on any task
- You are about to create a new session — verify no existing session covers the same task

**NEVER do any of these without listing sessions first:**
- Say "I don't have context about that" or "Can you remind me?"
- Create a duplicate session for a task that already exists
- Assume a task doesn't exist because you don't remember it

## Multi-session awareness

The user may have multiple Pine tasks running at the same time (e.g., one session negotiating a bill, another making a reservation). You MUST keep them separate:

1. Always track session IDs — never mix up sessions.
2. Use `pine sessions list --json` liberally to refresh your memory.
3. When the user asks about "my Pine task" or "how's that call going", use the session list to find the right session. If ambiguous, ask the user which task they mean.

## Authentication

Before any operation, check if already authenticated:

```bash
pine auth status --json
```

If the `authenticated` field is `false`, run the auth flow. **Ask the user for their Pine AI account email** (sign up at https://19pine.ai).

### Step 1: Request verification code

```bash
pine auth request --email USER_EMAIL
```

This sends a verification code and outputs JSON with a `request_token`. Tell the user: *"A verification code has been sent to your email. Check your inbox (and spam) and give me the code."*

### Step 2: Verify code and save credentials

Once the user provides the code:

```bash
pine auth verify --email USER_EMAIL --request-token REQUEST_TOKEN --code CODE
```

This verifies the code and saves credentials to `~/.pine/config.json` automatically.

### Interactive login (alternative for human users)

```bash
pine auth login
```

This interactive version prompts for email and code. It requires stdin access and may not work in all agent/scripted environments — prefer `request` + `verify` above.

### Token refresh

If operations fail with authentication errors or 401 responses, the token may have expired. Re-run the auth flow from the beginning.

## When to use

Pine Assistant can handle a wide range of tasks. Its primary strength is phone calls, but it also has built-in search and map capabilities, computer automation (browser), emails, and faxes. Use it when the user wants:

- **Customer service** (primary strength): negotiate bills, cancel subscriptions, dispute charges, file complaints, get refunds, resolve account issues
- **Search & discovery**: find restaurants, businesses, or service providers nearby. Pine can search, compare options, and then call to book.
- **Reservations & appointments**: book restaurants, schedule doctor/dentist appointments, make hotel reservations, reserve services
- **Outreach & research**: call businesses to gather information, compare quotes, verify hours or availability
- **Online tasks**: handle web-based account actions, submit forms on websites, send emails or faxes on the user's behalf

If the user asks Pine to do something, let Pine decide whether it can handle it — don't preemptively reject requests based on assumptions about Pine's capabilities.

## Resuming / following up on an existing session

If the user mentions anything that could relate to an existing Pine task — a company name, an account, a task description, or even vague references like "that refund" or "the call":

1. **Always** run `pine sessions list --json` to find matching sessions. Search by title or any keyword the user mentioned.
2. Check the session's **state**:
   - **Active** (`chat`, `task_processing`, etc.) → resume it. Send follow-up messages with `pine send "..." -s SESSION_ID --no-wait --json`.
   - **Finished** (`task_finished`, `task_cancelled`, etc.) → do NOT continue in that session. Instead, check its details for context, then create a **new session** and reference what you learned. This gives Pine a fresh task context while preserving continuity for the user.

**Never say "I don't have context" or "Can you remind me?"** — the session list is always available. Look it up.

## The Complete Flow

### Phase 1: Check existing sessions, then create if needed

1. **First**, run `pine sessions list --json` to check whether a session for this task already exists.
   - If an existing **active** session matches → resume it (see "Resuming" above).
   - If an existing session matches but is **finished** → read its details for context, then create a new session and include that context in your first message.
   - If no match → proceed to create.
2. Create a session and send the user's request in one step:

```bash
pine send "Negotiate my Comcast bill down. Account holder: Jane Doe, account #12345. Current bill is $120/mo, target is $80/mo. 10-year customer." --new --no-wait --json
```

The `--new` flag creates a session and returns a `session_created` JSON event with the `session_id`. Save this ID for follow-ups. The `--no-wait` flag sends the message without blocking for Pine's response (fire-and-forget) — **always use `--no-wait` to avoid hanging**.

Alternatively, create the session separately first:

```bash
pine sessions create --json
pine send "Negotiate my Comcast bill down." -s SESSION_ID --no-wait --json
```

4. Tell the user the session link: `https://www.19pine.ai/app/chat/SESSION_ID`
5. **Do NOT ask "want me to start?" or hand back control.** Continue handling Pine's responses autonomously.

### Phase 2: Information gathering

Pine will research the request and ask for details. Poll for conversation messages (includes both metadata and history):

```bash
pine sessions get SESSION_ID --json
```

To send follow-up messages:

```bash
pine send "checking in" -s SESSION_ID --no-wait --json
```

You will receive:
- **Text responses** asking questions — answer if you can, ask the user if you can't
- **Forms** requesting specific information — relay to the user, wait for answers, then reply with the filled values

Pine may send **multiple rounds** of questions/forms. Ask the user for what you don't know. **Do NOT try to start the task during this phase** — Pine is still gathering information.

**Real example**: User says "Negotiate my Comcast bill". Pine will:
- Research deals and plan a strategy
- Ask for: Full Name on Account, Service Address, Phone Number, Current Plan, etc.
- You relay the questions to the user, fill what you know, ask for the rest
- Pine may send more questions — keep answering

### Phase 3: Billing event (determines how the task starts)

After Pine has enough information, it will indicate one of these billing states:

- **No payment needed** (free tier or subscription) → run `pine task start SESSION_ID`
- **Payment completed** (user already paid) → run `pine task start SESSION_ID`
- **Payment required** — **relay the full billing details to the user**: current bill, potential savings, pre-authorized amount, and the payment URL. For percentage-based billing, explain that Pine only charges if it saves money. The user must review and confirm payment at the session URL. Do NOT start the task until payment is confirmed.
- **Task auto-started** — metered credits confirme