@thirdfy/agent-cli 0.1.6 → 0.1.8

package/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+All notable changes to `@thirdfy/agent-cli` are documented here. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.8] - 2026-04-07
+
+**npm:** [`@thirdfy/agent-cli@0.1.8`](https://www.npmjs.com/package/@thirdfy/agent-cli/v/0.1.8)  
+**Git tag:** `v0.1.8`
+
+### Added
+
+- **Managed custodial lifecycle validation:** Added CLI E2E path for managed wallet delegation parity (`e2e:managed:delegation:parity`) and integrated coverage into production certification flow.
+
+### Changed
+
+- **Self execution diagnostics:** `doctor self` is now routed as an offline/local command and no longer depends on capabilities negotiation.
+- **Managed wallet command routing:** Removed thin wrapper indirection and wired `managed wallet init/grant` directly to delegation custodial handlers.
+
+### Fixed
+
+- **Effect check payload safety:** Hardened relaxed-mode effect-check fallback so warning payload shape remains deterministic in edge paths.
+- **Managed wallet integration test contract:** Validation-only detection now correctly uses `executionLane === 'validation_only'`, with explicit auth env isolation for deterministic header assertions.
+
+## [0.1.7] - 2026-04-05
+
+**npm:** [`@thirdfy/agent-cli@0.1.7`](https://www.npmjs.com/package/@thirdfy/agent-cli/v/0.1.7)  
+**Git tag:** [`v0.1.7`](https://github.com/thirdfy/agent-cli/releases/tag/v0.1.7)
+
+### Added
+
+- **Login and local config:** `thirdfy-agent login`, `logout` (including `logout --all` for local clear plus owner-session revoke when applicable), `whoami`, and `config set` / `config show` with defaults persisted under `~/.thirdfy/config.json`. Credential precedence remains: CLI flags, then environment variables, then saved config (see README).
+- **Custodial delegation (MetaMask-compatible path):** `delegation init-custodial` and `delegation custodial-grant` alongside the existing `delegation create` / `delegation activate` lifecycle.
+- **Delegation operator ergonomics:** `delegation show` as an alias for `delegation status`; expanded delegation inspection and parity-focused behavior for automation.
+- **E2E / certification:** Delegation parity and production certification scripts (`e2e:self:delegation:parity`, `e2e:delegation:prod:certify`) and related gates documented in internal runbooks.
+
+### Changed
+
+- **`delegation redeem`:** Respects the effective run mode (flag / env / profile) when building the execution path.
+- **Swap amount handling:** Clearer separation between *missing* and *ambiguous* amount-unit errors; stricter validation of human-form amounts (including excess precision) and decimals handling for `amountInHuman` flows.
+
+### Fixed
+
+- **Config and bootstrap:** Safer bootstrap output, tighter validation, preserved config semantics on upgrade paths, and `config set` rejects prototype-path keys to avoid confusing or unsafe key shapes.
+- **Login / token handling:** Stricter verification of token shape after login and safer config cloning for delegation-related routing.
+- **E2E:** Session-auth paths keep a dev-mock wallet fallback where intended so local and CI simulations stay stable.
+
+### Tooling
+
+- **Release workflow:** When a version is already published to npm, CI skips `npm publish` so tag-based runs can still create or align GitHub releases without duplicate-publish failures.
+
+---
+
+## [0.1.6] - 2026-03-30
+
+Prior release; see [git compare `v0.1.6...v0.1.7`](https://github.com/thirdfy/agent-cli/compare/v0.1.6...v0.1.7) for the full commit list.

package/README.md

@@ -42,8 +42,8 @@ export THIRDFY_OWNER_SESSION_TOKEN="..."
 
 thirdfy-agent actions --agent-api-key "$AGENT_API_KEY" --json
 thirdfy-agent profile init --profile personal --json
-thirdfy-agent preflight --agent-api-key "$AGENT_API_KEY" --action swap --params '{"tokenIn":"0x...","tokenOut":"0x...","amountIn":"1000000"}' --estimated-amount-usd 25 --json
-thirdfy-agent run --agent-api-key "$AGENT_API_KEY" --action swap --params '{"tokenIn":"0x...","tokenOut":"0x...","amountIn":"1000000"}' --estimated-amount-usd 25 --json
+thirdfy-agent preflight --agent-api-key "$AGENT_API_KEY" --action swap --params '{"tokenIn":"0x...","tokenOut":"0x...","amountInRaw":"1000000"}' --estimated-amount-usd 25 --json
+thirdfy-agent run --agent-api-key "$AGENT_API_KEY" --action swap --params '{"tokenIn":"0x...","tokenOut":"0x...","amountInRaw":"1000000"}' --estimated-amount-usd 25 --json
 thirdfy-agent intent-status --intent-id "<intentId>" --json
 ```
 
@@ -51,12 +51,37 @@ By default, the CLI targets production (`https://api.thirdfy.com`). Use `--api-b
 
 ## Auth model
 
-- `AGENT_API_KEY`: execution identity and policy-aware action access (`actions --agent-api-key`, `preflight`, `run`)
-- `THIRDFY_AUTH_TOKEN`: Privy-native owner/account auth (`agent register`, `agent key *`, `delegation *`, `credentials *`, `credits balance`)
-- `THIRDFY_OWNER_SESSION_TOKEN`: wallet-sign owner auth session (`agent register`, `agent key *`)
+- `AGENT_API_KEY`: execution identity for `preflight`, `run`, `self-exec`, and policy-aware discovery.
+- `THIRDFY_AUTH_TOKEN`: owner/account auth for onboarding and delegation commands.
+- `THIRDFY_OWNER_SESSION_TOKEN`: wallet-sign owner session for onboarding and owner operations.
+
+CLI precedence now supports login/config defaults:
+
+1. explicit flag
+2. environment variable
+3. `~/.thirdfy/config.json` (from `thirdfy-agent login` / `config set`)
 
 Execution-only workflows can run with only `AGENT_API_KEY` after onboarding is complete.
 
+### Login / logout / config UX
+
+```bash
+# Store auth defaults once
+thirdfy-agent login --auth-token "$THIRDFY_AUTH_TOKEN" --agent-api-key "$AGENT_API_KEY" --json
+
+# Inspect config
+thirdfy-agent whoami --json
+thirdfy-agent config set --key runMode --value self --json
+
+# Local-only logout (default)
+thirdfy-agent logout --json
+
+# Local clear + server owner-session revoke (if present)
+thirdfy-agent logout --all --json
+```
+
+`logout --all` is provider-agnostic: it attempts owner-session revocation when a session token exists, then always clears local credentials.
+
 ### Wallet-sign onboarding path
 
 ```bash
@@ -85,6 +110,12 @@ thirdfy-agent agent register --owner-session-token "$THIRDFY_OWNER_SESSION_TOKEN
 - `--run-mode self` -> self-custody rail (`build-tx` flow; default for `profile=personal`)
 - `--run-mode hybrid` -> self-custody + governance mirror metadata (default for `profile=builder`)
 
+Auth expectations by mode:
+
+- `self`: requires execution identity (`agentApiKey`) today; keyless self lane is blocked with deterministic `SELF_OPEN_DISABLED`.
+- `hybrid`: requires execution identity and governed mirror semantics.
+- `thirdfy`: requires execution identity and delegated governance path.
+
 Selection precedence:
 
 1. `--run-mode`
@@ -102,6 +133,63 @@ thirdfy-agent whoami --json
 
 `profile use --profile <name>` resets run mode to that profile default unless `--run-mode` is explicitly provided.
 
+### One-command self execution (BYOW)
+
+Use `--broadcast` with `run --run-mode self` to keep one deterministic command for build/sign/send:
+
+```bash
+thirdfy-agent run \
+  --agent-api-key "$AGENT_API_KEY" \
+  --run-mode self \
+  --broadcast \
+  --action swap \
+  --params '{"tokenIn":"0x...","tokenOut":"0x...","amountInRaw":"1000000","chainId":8453}' \
+  --json
+```
+
+The default `run --run-mode self` behavior is still unsigned-only (advanced users can sign externally).
+
+Self lane effect-check controls:
+
+```bash
+# strict: fail if no observable token delta
+thirdfy-agent self-exec ... --effect-check strict --json
+
+# relaxed (default): retry/read balances, warn on mismatch, do not false-fail the tx
+thirdfy-agent self-exec ... --effect-check relaxed --json
+
+# off: skip post-trade token-delta verification
+thirdfy-agent self-exec ... --effect-check off --json
+```
+
+Signer diagnostics:
+
+```bash
+thirdfy-agent doctor self --json
+```
+
+## Swap amount contract (agent-safe)
+
+For `--action swap`, CLI enforces an explicit amount unit contract:
+
+- Provide exactly one of:
+  - `amountInRaw` (base units integer string), or
+  - `amountInHuman` + `tokenInDecimals` (CLI converts to `amountInRaw`)
+- Legacy `amountIn` is accepted only as raw integer compatibility input.
+- Ambiguous payloads (both/none) fail with `AMOUNT_UNIT_AMBIGUOUS`.
+
+Examples:
+
+```bash
+# Raw/base units
+thirdfy-agent run --agent-api-key "$AGENT_API_KEY" --action swap \
+  --params '{"tokenIn":"0x...","tokenOut":"0x...","amountInRaw":"1000000","chainId":8453}' --json
+
+# Human units + decimals
+thirdfy-agent run --agent-api-key "$AGENT_API_KEY" --action swap \
+  --params '{"tokenIn":"0x...","tokenOut":"0x...","amountInHuman":"1.5","tokenInDecimals":6,"chainId":8453}' --json
+```
+
 ## Jeff shorthand rail
 
 Jeff-friendly aliases map directly to core commands:
@@ -118,6 +206,8 @@ Jeff-friendly aliases map directly to core commands:
 - Profiles: `profile init`, `profile use`, `profile show`, `whoami`
 - Onboarding: `agent auth challenge`, `agent auth verify`, `agent register`, `agent key rotate`, `agent key revoke`
 - Governance readiness: `delegation create`, `delegation activate`, `delegation status`, `credentials upsert`, `credentials status`
+- Delegation operations: `delegation show`, `delegation inspect`, `delegation revoke`
+- Delegation execution helpers: `delegation balance`, `delegation redeem`
 - Account: `credits balance`
 
 ## Delegation lifecycle (canonical)
@@ -149,6 +239,61 @@ thirdfy-agent delegation status \
   --agent-key "0xYOUR_AGENT_KEY" \
   --verify \
   --json
+
+thirdfy-agent delegation inspect \
+  --auth-token "$THIRDFY_AUTH_TOKEN" \
+  --agent-key "0xYOUR_AGENT_KEY" \
+  --verify \
+  --json
+
+thirdfy-agent delegation revoke \
+  --auth-token "$THIRDFY_AUTH_TOKEN" \
+  --agent-key "0xYOUR_AGENT_KEY" \
+  --reason "user_revoked" \
+  --json
+
+thirdfy-agent delegation balance \
+  --auth-token "$THIRDFY_AUTH_TOKEN" \
+  --agent-key "0xYOUR_AGENT_KEY" \
+  --json
+
+thirdfy-agent delegation redeem \
+  --run-mode thirdfy \
+  --agent-api-key "$AGENT_API_KEY" \
+  --action swap \
+  --params '{"tokenIn":"0x...","tokenOut":"0x...","amountInRaw":"1000000"}' \
+  --estimated-amount-usd 5 \
+  --json
+```
+
+### MetaMask custodial-compatible lifecycle (new)
+
+```bash
+thirdfy-agent delegation init-custodial \
+  --auth-token "$THIRDFY_AUTH_TOKEN" \
+  --chain-id 8453 \
+  --json
+
+thirdfy-agent delegation custodial-grant \
+  --auth-token "$THIRDFY_AUTH_TOKEN" \
+  --agent-key "0xYOUR_AGENT_KEY" \
+  --token-address "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" \
+  --max-usd-per-day 250 \
+  --json
+```
+
+The CLI keeps compatibility with legacy `delegation create` + `delegation activate` during migration.
+
+`delegation show` is a direct alias to `delegation status` for gator-style operator ergonomics.
+
+Managed easy-wallet command group:
+
+```bash
+thirdfy-agent managed wallet init --auth-token "$THIRDFY_AUTH_TOKEN" --json
+# or: --owner-session-token "$THIRDFY_OWNER_SESSION_TOKEN"
+thirdfy-agent managed wallet grant --auth-token "$THIRDFY_AUTH_TOKEN" --agent-key "0xYOUR_AGENT_KEY" --token-address "0x..." --max-usd-per-day 250 --json
+# or: --owner-session-token "$THIRDFY_OWNER_SESSION_TOKEN"
+thirdfy-agent managed run --agent-api-key "$AGENT_API_KEY" --run-mode thirdfy --action swap --params '{"tokenIn":"0x...","tokenOut":"0x...","amountInRaw":"1000000"}' --json
 ```
 
 ## More docs
@@ -164,11 +309,16 @@ thirdfy-agent delegation status \
 npm run validate:cli-contract-schemas
 npm test
 npm run smoke:cli
+npm run e2e:managed:delegation:parity
 ```
 
 ## Release
 
+Version history and user-facing notes: [CHANGELOG.md](./CHANGELOG.md) (for example [0.1.7](https://github.com/thirdfy/agent-cli/releases/tag/v0.1.7) — login/config UX, custodial delegation helpers, swap and config hardening).
+
 ```bash
 npm version patch
 npm publish --access public
 ```
+
+After publishing, push the matching tag (for example `v0.1.7`) so the [Release workflow](.github/workflows/release.yml) can create a GitHub release. If the package version is already on npm, the workflow skips republishing and still creates the release when triggered by a tag.