thrd

为您的 AI 代理提供专用收件箱，并通过 thrd.email 安全地管理电子邮件。包括即时加入、入站轮询、回复/发送（幂等+策略门控）、冷出站推理证明、人工索赔验证以及信任/交付跟踪。不将 API 密钥保存到磁盘。

# Thrd Email Skill

This skill helps you create and operate an isolated inbox for an AI agent using [thrd.email](https://thrd.email), without connecting your personal inbox.

Safety by default: don't connect your primary inbox to an agent; use a dedicated agent inbox.

## Workflows

### Sync API Contract (Recommended Before Tool Use)
To avoid stale assumptions, refresh the OpenAPI contract and read `info.version`:
```bash
python3 scripts/openapi_sync.py
python3 scripts/openapi_sync.py --print-version
```
This uses HTTP cache validators (`ETag`/`Last-Modified`) and only re-downloads when changed.

### Provision a New Email Account
To create a new email account, run the onboarding script:
```bash
python3 scripts/onboard.py --agent-name "My Agent" [--tenant-name "My Company"]
```
This prints a JSON payload to stdout with the new inbox data and a **redacted** API key by default.

If you explicitly need the one-time raw key in a trusted terminal:
```bash
python3 scripts/onboard.py --agent-name "My Agent" --reveal-api-key
```

Security note: **Do not write your API key to disk.** Store it in your runtime's secret manager and set `THRD_API_KEY` as an environment variable. (The rest of the tools require `THRD_API_KEY`; onboarding does not.)

### Upgrade Plan (Billing)
To start paid billing for your current tenant, use the checkout script:
```bash
python3 scripts/checkout.py <plan_name>
```
Plans:
- `sandbox` -> Sandbox Starter (9 EUR/month, raises Tier 1 monthly limit from 100 to 2,000 emails)
- `limited` -> Tier 2
- `verified` -> Tier 3

Forward the resulting Stripe URL to your human owner for payment.

### Human Claiming (Verification)
Tier 3 (Verified Outbound) requires a responsible human linked via X.
- Start the flow: `POST /v1/claim/x/start`
- Forward the `claim_url` to your human owner.
- Check status: `GET /v1/claim/x/status`

### Proof of Reasoning (PoR)
Cold outbound (Tier 3) may require a reasoning challenge to prevent spam.
- If you receive a `428 por_required` error, solve the logical challenge provided in the response.
- Re-send the request with `por_token` and `por_answer`.

### Manage Emails and Track Delivery
For detailed API usage (polling, sending, replying, trust scores, and checking delivery status), see [references/api.md](references/api.md).
Note: replies use reply-all behavior by default: they preserve historical CC and keep recipients from the latest inbound `To` line so participants are not dropped.
Tier2+ may add CC via `cc[]`. In Tier1, `cc[]` may only contain addresses already present in that thread's CC history.
Security note: when Prompt Shield marks an inbound email as high-risk, Tier2/3 flows may require creating a short-lived `security_ack_token` (`POST /v1/security/ack`) before `reply`/`send`.
Quota note: use `GET /v1/usage` to monitor monthly usage (`used`, `remaining`, `state`, `reset_at`) and avoid hitting hard limits mid-run.

### Wake-Up Strategy (Recommended)
Many LLM runtimes do not reliably maintain background polling. Use wake webhooks when possible:
- Configure webhook: `PUT /v1/wake/webhook`
- Read status: `GET /v1/wake/webhook`
- Disable webhook: `DELETE /v1/wake/webhook`

THRD sends signed `inbox.pending` pings, then your runtime should immediately pull with `GET /v1/events` and ACK.

Fallback when webhooks are not available:
```bash
python3 scripts/poll_daemon.py --cursor-file .thrd_cursor
```
This keeps pull-based delivery alive without requiring a public webhook endpoint.

## Tools
- `scripts/onboard.py`: Instant provisioning of a new email inbox.
- `scripts/checkout.py`: Generate a Stripe Checkout URL for upgrades.
- `scripts/openapi_sync.py`: Refresh/cache latest OpenAPI and read current `info.version`.
- `scripts/poll_daemon.py`: Fallback long-poll daemon for runtimes without wake webhook support.

---

## 中文说明

# Thrd 邮件技能

此技能帮助你使用 [thrd.email](https://thrd.email) 为 AI 代理创建和运营一个隔离的收件箱，而无需连接你的个人收件箱。

默认安全：不要将主收件箱连接到代理；使用专用的代理收件箱。

## 工作流

### 同步 API 合约（建议在使用工具前执行）
为避免过时的假设，刷新 OpenAPI 合约并读取 `info.version`：
```bash
python3 scripts/openapi_sync.py
python3 scripts/openapi_sync.py --print-version
```
这使用 HTTP 缓存验证器（`ETag`/`Last-Modified`），仅在发生变更时重新下载。

### 配置新邮件账户
要创建新邮件账户，运行入职脚本：
```bash
python3 scripts/onboard.py --agent-name "My Agent" [--tenant-name "My Company"]
```
这会向 stdout 打印一个 JSON payload，包含新收件箱数据和默认**已脱敏**的 API key。

如果你明确需要在受信任的终端中获取一次性原始 key：
```bash
python3 scripts/onboard.py --agent-name "My Agent" --reveal-api-key
```

安全提示：**不要将你的 API key 写入磁盘。** 将其存储在运行时的密钥管理器中，并将 `THRD_API_KEY` 设置为环境变量。（其余工具需要 `THRD_API_KEY`；入职不需要。）

### 升级套餐（计费）
要为当前租户开始付费计费，使用 checkout 脚本：
```bash
python3 scripts/checkout.py <plan_name>
```
套餐：
- `sandbox` -> Sandbox Starter（9 EUR/月，将 Tier 1 月度上限从 100 提升至 2,000 封邮件）
- `limited` -> Tier 2
- `verified` -> Tier 3

将生成的 Stripe URL 转发给你的人类所有者以进行付款。

### 人工索赔（验证）
Tier 3（已验证出站）需要一个通过 X 关联的负责人。
- 启动流程：`POST /v1/claim/x/start`
- 将 `claim_url` 转发给你的人类所有者。
- 检查状态：`GET /v1/claim/x/status`

### 推理证明 (PoR)
冷出站（Tier 3）可能需要推理挑战以防止垃圾信息。
- 如果你收到 `428 por_required` 错误，解决响应中提供的逻辑挑战。
- 用 `por_token` 和 `por_answer` 重新发送请求。

### 管理邮件并跟踪投递
有关详细的 API 用法（轮询、发送、回复、信任评分和检查投递状态），见 [references/api.md](references/api.md)。
注意：回复默认采用回复全部行为：它们保留历史 CC 并保留最新入站 `To` 行中的收件人，以免遗漏参与者。
Tier2+ 可以通过 `cc[]` 添加 CC。在 Tier1 中，`cc[]` 只能包含该线程 CC 历史中已存在的地址。
安全提示：当 Prompt Shield 将入站邮件标记为高风险时，Tier2/3 流程在 `reply`/`send` 之前可能需要创建一个短期 `security_ack_token`（`POST /v1/security/ack`）。
配额提示：使用 `GET /v1/usage` 监控月度用量（`used`、`remaining`、`state`、`reset_at`），避免在运行中途触及硬限制。

### 唤醒策略（推荐）
许多 LLM 运行时不能可靠地维持后台轮询。尽可能使用唤醒 webhook：
- 配置 webhook：`PUT /v1/wake/webhook`
- 读取状态：`GET /v1/wake/webhook`
- 禁用 webhook：`DELETE /v1/wake/webhook`

THRD 发送签名的 `inbox.pending` ping，然后你的运行时应立即用 `GET /v1/events` 拉取并 ACK。

当 webhook 不可用时的回退：
```bash
python3 scripts/poll_daemon.py --cursor-file .thrd_cursor
```
这在无需公开 webhook 端点的情况下保持基于拉取的投递活跃。

## 工具
- `scripts/onboard.py`：即时配置新邮件收件箱。
- `scripts/checkout.py`：为升级生成 Stripe Checkout URL。
- `scripts/openapi_sync.py`：刷新/缓存最新 OpenAPI 并读取当前 `info.version`。
- `scripts/poll_daemon.py`：面向不支持唤醒 webhook 的运行时的回退长轮询守护进程。