coze_lab 0.1.44 → 0.1.45

package/README.md

@@ -5,56 +5,52 @@ Configure local AI agents (Claude Code, Codex, OpenClaw) to report traces to Coz
 ## Usage
 
 ```bash
-# First-time setup — triggers browser OAuth authorization
-npx coze_lab --agent=<type>
-
-# Per-agent setup. Cloud/local is inferred from coze-bridge config or CLOUD_ENV=1.
+# Per-agent setup. Local/cloud is inferred from ~/.coze/agents/<agentId>/config.json.
 npx coze_lab --agent-id=<agentId>
 
-# Auth-only commands (no agent configuration)
-npx coze_lab --login      # Device Code login only
-npx coze_lab --status     # Show current authorization status
-npx coze_lab --refresh    # Force-refresh the access token
-npx coze_lab --logout     # Clear cached credentials
+# Cloud compatibility mode when the caller already knows the framework.
+npx coze_lab --cloud --agent=<claude-code|codex|openclaw>
+
+# Send a one-off trace selfcheck. Uses --agent-id patToken locally, or env token in cloud.
+npx coze_lab --verify --agent-id=<agentId> --pair-code=<pairCode>
 ```
 
 ### Parameters
 
 | Parameter | Required | Values / Effect |
 |-----------|----------|-----------------|
-| `--agent` | ✓ (for setup) | `claude-code`, `codex`, `openclaw` |
-| `--agent-id` | — | Resolve `~/.coze/agents/<agentId>/config.json` and write per-agent config. Cloud mode is inferred from `deployType=cloud`, `CLOUD_ENV=1`, or bridge cloud-only fields |
-| `--cloud` | — | Backward-compatible override for old manual callers. New callers should rely on `--agent-id` auto-detection |
-| `--codex-home` | — | Override Codex config home for non-cloud/custom runs |
-| `--login` | — | Run the Device Code login flow only |
-| `--status` | — | Print local token status (valid / expiring / expired) |
-| `--refresh` | — | Force-refresh the access token via `refresh_token` |
-| `--logout` | — | Clears cached credentials |
-
-> **Note — traces are collected into a shared CozeLoop workspace.**
+| `--agent-id` | Local setup | Resolve `~/.coze/agents/<agentId>/config.json`, infer framework/workspace, and read `patToken` for local trace upload |
+| `--agent` | Cloud compatibility only | `claude-code`, `codex`, `openclaw` when no agent config is available |
+| `--cloud` | Optional | Forces cloud mode; token must come from `COZELOOP_API_TOKEN` or `COZE_API_TOKEN` |
+| `--codex-home` | Optional | Override Codex config home for custom cloud runs |
+| `--force` | Optional | Force OpenClaw plugin rewrite/reinstall and gateway restart |
+| `--verify` | Optional | Send a test trace; local requires `--agent-id` with `patToken`, cloud requires env token |
+| `--pair-code` | Optional | Add a trace lookup code to selfcheck metadata |
+
+> **Note - traces are collected into a shared CozeLoop workspace.**
 > All traces from this tool are uploaded to a single fixed workspace
-> (`COZELOOP_WORKSPACE_ID`) maintained by the CozeLoop team — they are **not**
-> sent to each user's personal workspace. The OAuth authorization only proves
-> your identity for trace ingestion; it does not select a workspace.
+> (`COZELOOP_WORKSPACE_ID`) maintained by the CozeLoop team; they are not sent
+> to each user's personal workspace.
 
+## What It Does
 
-## What it does
+1. **Token resolution** - Local mode reads `patToken` from `~/.coze/agents/<agentId>/config.json`. Cloud mode reads `COZELOOP_API_TOKEN` or `COZE_API_TOKEN` from the environment.
+2. **Agent detection** - Verifies the specified agent binary is installed locally.
+3. **Environment checks** - Python >= 3.8 + `cozeloop` SDK for Claude Code and Codex; SDK is auto-installed via pip if missing. Agent version whitelist warnings are non-fatal.
+4. **Hook configuration** - Writes hook scripts and config files for the selected agent.
+5. **Selfcheck** - Sends a test trace with the resolved token.
 
-1. **Authorization** — Checks `~/.cozeloop/credentials.json` for a cached OAuth token.
-   - Token valid → skip authorization, proceed.
-   - Token expiring (< 10 min) → silently refresh via `refresh_token`.
-   - No token / refresh failed → launches Device Code OAuth flow: opens browser, displays verification URL, polls until user approves.
-2. **Agent detection** — Verifies the specified agent binary is installed locally.
-3. **Environment checks** — Python ≥ 3.8 + `cozeloop` SDK (Claude Code & Codex only; SDK auto-installed via pip if missing), agent version whitelist check.
-4. **Hook configuration** — Writes hook scripts and config files for the selected agent.
+There is no Device Code login, OAuth cache, or refresh-token fallback. Legacy
+`--login`, `--status`, `--refresh`, `--logout`, and local `--agent=<type>`
+commands fail with a migration message.
 
-## Per-agent hook files
+## Per-Agent Hook Files
 
-| Agent | Hook script | Config file | Credentials |
-|-------|------------|-------------|-------------|
-| `claude-code` | `~/.claude/hooks/cozeloop_hook.py` | `~/.claude/settings.json` | `.claude/settings.local.json` (project-scoped) |
-| `codex` | `~/.codex/hooks/cozeloop_hook.py` | `~/.codex/hooks.json` | `~/.codex/hooks/cozeloop.env` |
-| `openclaw` | — (Node.js plugin) | `~/.openclaw/openclaw.json` | inline in config |
+| Agent | Hook script | Config file | Token environment |
+|-------|-------------|-------------|-------------------|
+| `claude-code` | `~/.claude/hooks/cozeloop_hook.py` | `~/.claude/settings.json` or agent workspace `.claude/settings.json` | `.claude/settings.local.json` |
+| `codex` | `<CODEX_HOME>/hooks/cozeloop_hook.py` | `<CODEX_HOME>/hooks.json` | `<CODEX_HOME>/hooks/cozeloop.env` |
+| `openclaw` | Node.js plugin | `~/.openclaw/openclaw.json` | inline `authorization` |
 
 For cloud Codex with `--agent-id=<agentId>`, Codex hooks are written to
 `~/.coze/agents/<agentId>/codex-home` by default. The directory is created if it
@@ -66,32 +62,26 @@ Codex home. For cloud Codex, check
 `~/.coze/agents/<agentId>/codex-home/hooks/cozeloop.log`. If that file is not
 created after a new Codex turn, Codex did not load or execute the hook.
 
-## Token lifecycle
+## Token Lifecycle
 
-OAuth tokens are stored in `~/.cozeloop/credentials.json` (mode 600).
-For local `--agent-id=<agentId>` setup, if
-`~/.coze/agents/<agentId>/config.json` contains `patToken`, onboarding uses that
-PAT directly and skips the OAuth device-code flow.
+Local setup requires `~/.coze/agents/<agentId>/config.json` to contain
+`patToken`. Onboarding writes that PAT into the selected agent's hook
+configuration and marks the source as `agent_config.patToken`.
 
-In cloud mode, trace verification and hook uploads prefer
-`COZELOOP_API_TOKEN` and fall back to `COZE_API_TOKEN`. The selfcheck result is
-authoritative: if the token does not have trace ingest permission, onboard still
-writes the hook configuration but reports `verify=fail` with `token_source`.
-For Python SDK uploads, `OTEL_ENDPOINT` is not used as the SDK base URL; set
-`COZELOOP_API_BASE_URL` only when the SDK ingest endpoint should be overridden.
+Cloud setup and verification prefer `COZELOOP_API_TOKEN` and fall back to
+`COZE_API_TOKEN`. The selfcheck result is authoritative: if the token does not
+have trace ingest permission, cloud onboard still writes hook configuration but
+reports `verify=fail` with `token_source`.
 
-**At hook execution time** (Claude Code / Codex), per-agent PAT setups use the
-token written by onboarding. Otherwise, the Python hook script automatically:
-1. Reads `~/.cozeloop/credentials.json`
-2. If the token expires in < 10 minutes, calls the Coze refresh API
-3. Updates `credentials.json` with the new token
-4. Passes the fresh token to the CozeLoop SDK before uploading traces
+At hook execution time, Claude Code, Codex, and OpenClaw use only the token
+written by onboarding or injected by cloud env. They do not read
+`~/.cozeloop/credentials.json` and do not refresh tokens locally. If a token is
+revoked or rotated, rerun `npx coze_lab --agent-id=<agentId>`.
 
-This means traces continue to upload without interruption even across token expiry, as long as the refresh token is still valid.
-
-**For OpenClaw**, the token is read from `openclaw.json` at startup. Re-run `npx coze_lab --agent=openclaw` to refresh it if OpenClaw reports auth errors.
+For Python SDK uploads, `OTEL_ENDPOINT` is not used as the SDK base URL; set
+`COZELOOP_API_BASE_URL` only when the SDK ingest endpoint should be overridden.
 
-## Supported versions
+## Supported Versions
 
 | Agent | Supported versions |
 |-------|--------------------|
@@ -99,4 +89,4 @@ This means traces continue to upload without interruption even across token expi
 | `codex` | 0.134.x, 1.0.x, 1.1.x |
 | `openclaw` | 2026.3.x, 2026.4.x, 2026.5.x |
 
-Versions outside this list will show a yellow warning but onboarding will continue.
+Versions outside this list show a warning but onboarding continues.