perp-cli 0.9.8 → 0.12.0

package/README.md

@@ -19,7 +19,7 @@ npx -y perp-cli --json portfolio
 - **4 Exchanges** — trade, bridge, arbitrage across Pacifica, Hyperliquid, Lighter, Aster
 - **Funding Rate Arb** — perp-perp + spot-perp scan & one-command dual-leg execution
 - **Portfolio** — single call returns balances, positions, risk level across all exchanges
-- **Funds** — deposit, withdraw, CCTP bridge, internal transfer in one group
+- **Funds** — deposit, withdraw, transfer, multi-provider bridge (cctp/relay/debridge), inter-exchange rebalance — all in one group
 - **Bots** — TWAP, grid, DCA, trailing-stop with background job management
 - **Agent-First Design** — `--json`, `--fields`, `--ndjson`, `--dry-run`, runtime schema introspection
 - **Safety** — pre-trade validation, response sanitization, client-id deduplication
@@ -42,7 +42,7 @@ perp wallet show
 
 Same EVM key works for both Hyperliquid and Lighter.
 
-> **Lighter API Key Index:** Indexes 0–3 are reserved by Lighter's frontend (web/mobile). perp-cli defaults to index `4`. Override with `LIGHTER_API_KEY_INDEX` env var or `--key-index` flag on `manage setup-api-key`. Valid range: 4–254.
+> **Lighter API Key Index:** Indexes 0–3 are reserved by Lighter's frontend (web/mobile). perp-cli defaults to index `4`. Override with `LIGHTER_API_KEY_INDEX` env var, or use `perp wallet agent approve lighter --api-key-index <n>` for managed agent slots. Valid range: 4–254.
 
 ## Command Groups
 
@@ -52,9 +52,8 @@ Same EVM key works for both Hyperliquid and Lighter.
 | `account` | Balance, positions, orders, margin |
 | `trade` | Market/limit/stop orders, close, scale, split execution |
 | `arb` | Funding rate arb — scan, exec, close, monitor (perp-perp & spot-perp) |
-| `bot` | 19 strategies, APEX orchestrator, REFLECT analytics, presets |
-| `funds` | Deposit, withdraw, transfer, CCTP bridge |
-| `bridge` | Cross-chain USDC bridge (deBridge DLN) |
+| `strategy` | 19 bot algorithms (grid, dca, twap, APEX, REFLECT, presets) + nested scripted plans |
+| `funds` | Deposit, withdraw, transfer, cross-chain bridge (multi-provider), inter-exchange rebalance |
 | `risk` | Risk limits, liquidation distance, guardrails |
 | `wallet` | Multi-wallet management & on-chain balances |
 | `history` | Execution log, PnL, performance breakdown |
@@ -63,9 +62,7 @@ Same EVM key works for both Hyperliquid and Lighter.
 | `dashboard` | Live web dashboard |
 | `settings` | CLI settings (referrals, defaults) |
 | `backtest` | Strategy backtesting |
-| `plan` | Multi-step composite execution plans |
-| `rebalance` | Cross-exchange balance management |
-| `jobs` | Background job management (tmux) |
+| `background` | Background process supervisor (tmux sessions for strategies, alerts, etc.) |
 | `alerts` | Telegram funding rate alerts with background daemon |
 | `agent` | Schema introspection, capabilities, health check |
 | `setup` | Interactive setup wizard (alias: `init`) |
@@ -117,28 +114,39 @@ perp --json arb exec <SYM> spot:<exch> <perpEx> <$>  # spot+perp entry
 perp --json arb config                               # show arb defaults
 perp --json arb history                              # past arb trade performance (alias: log)
 
-# Funds (deposit, withdraw, transfer)
+# Funds (deposit, withdraw, transfer, bridge, rebalance)
 perp --json funds deposit hyperliquid 100
 perp --json funds withdraw pacifica 50
-perp --json funds transfer 100 <ADDRESS>             # HL internal transfer
+perp --json funds transfer 100 <ADDRESS>             # HL internal transfer (instant)
+perp --json funds bridge quote --from solana --to arbitrum --amount 100
+perp --json funds bridge send --from solana --to arbitrum --amount 100   # auto-cheapest provider
+perp --json funds bridge exchange --from pacifica --to hyperliquid --amount 100
+perp --json funds rebalance check                    # balances across exchanges
+perp --json funds rebalance plan                     # compute optimal moves
+perp --json funds rebalance execute --auto-bridge    # withdraw → bridge → deposit
 perp --json funds info                               # all routes & limits
 
 # Risk
 perp --json risk limits --max-leverage 5
 perp --json risk liquidation-distance
 
-# Bots (19 strategies)
-perp bot list-strategies                             # list all available strategies
-perp bot run <strategy> [symbol]                     # run any strategy
-perp bot apex [symbol]                               # APEX autonomous orchestrator
-perp bot reflect                                     # trading performance analysis
-perp bot preset-list                                 # list strategy presets
-perp --json bot twap <SYM> buy <SIZE> 30m
-perp --json bot grid <SYM> --range 5 --grids 10 --size 100
-
-# Bridge (cross-chain USDC)
-perp --json bridge quote --from solana --to arbitrum --amount 100
-perp --json bridge send --from solana --to arbitrum --amount 100
+# Strategies (19 bot algorithms + nested scripted plans)
+perp strategy list-strategies                        # list all available strategies
+perp strategy run <strategy> [symbol]                # run any strategy
+perp strategy apex [symbol]                          # APEX autonomous orchestrator
+perp strategy reflect                                # trading performance analysis
+perp strategy preset-list                            # list strategy presets
+perp --json strategy twap <SYM> buy <SIZE> 30m
+perp --json strategy grid <SYM> --range 5 --grids 10 --size 100
+perp strategy plan example                           # scripted multi-step plan format
+perp --json strategy plan validate <FILE>            # validate scripted plan
+perp --json strategy plan execute <FILE> --dry-run   # dry-run scripted plan
+
+# Background process supervisor (tmux)
+perp background list                                 # list running jobs
+perp background stop <ID>                            # stop a job
+perp background logs <ID> -f                         # follow logs
+
 ```
 
 ## Telegram Alerts
@@ -231,9 +239,6 @@ Built following [agent-first CLI principles](https://justin.poehnelt.com/posts/r
 perp --json portfolio
 # → { "ok": true, "data": {...}, "meta": { "timestamp": "..." } }
 
-# Runtime schema introspection (don't guess commands — query this)
-perp --json agent schema
-
 # Filter output to specific fields (saves tokens)
 perp --json --fields totalEquity,risk portfolio
 

package/dist/_stderr-filter.js

@@ -0,0 +1,30 @@
+"use strict";
+// Install a stderr filter that drops known noisy SDK warnings when --json
+// or --ndjson is set. Module body runs at import time — must be the FIRST
+// import in src/index.ts so it activates before SDK module bodies.
+if (process.argv.includes("--json") || process.argv.includes("--ndjson")) {
+    const _suppressPatterns = [
+        /'--chain evm' is deprecated/,
+        /\[hyperliquid\] Failed to load asset map/,
+        /\[lighter\] Account index not available/,
+        /Failed to initialize SymbolConversion/,
+        /HyperliquidAPIError/,
+    ];
+    // Wrap at the lowest level (_write on the Writable) so we catch writes
+    // even if a downstream module replaces process.stderr.write itself.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const stderr = process.stderr;
+    const _origStderrWriteRaw = stderr._write.bind(stderr);
+    stderr._write = function (chunk, encoding, callback) {
+        const s = typeof chunk === "string"
+            ? chunk
+            : (chunk instanceof Uint8Array || Buffer.isBuffer(chunk))
+                ? Buffer.from(chunk).toString()
+                : "";
+        if (_suppressPatterns.some(re => re.test(s))) {
+            callback();
+            return;
+        }
+        return _origStderrWriteRaw(chunk, encoding, callback);
+    };
+}

package/dist/agent-wallet/expiry.d.ts

@@ -0,0 +1,15 @@
+import type { AgentMeta } from "../settings.js";
+/**
+ * Returns true if the agent's expiry timestamp is in the past.
+ */
+export declare function isExpired(meta: AgentMeta): boolean;
+/**
+ * Returns the number of days (float) until the agent expires.
+ * Negative if already expired.
+ */
+export declare function daysUntilExpiry(meta: AgentMeta): number;
+/**
+ * Returns a human-readable expiry string, e.g.
+ * "expires in 7 days (2026-05-05)" or "expired 3 days ago (2026-04-25)".
+ */
+export declare function formatExpiry(meta: AgentMeta): string;

package/dist/agent-wallet/expiry.js

@@ -0,0 +1,26 @@
+/**
+ * Returns true if the agent's expiry timestamp is in the past.
+ */
+export function isExpired(meta) {
+    return Date.now() >= new Date(meta.expiresAt).getTime();
+}
+/**
+ * Returns the number of days (float) until the agent expires.
+ * Negative if already expired.
+ */
+export function daysUntilExpiry(meta) {
+    const ms = new Date(meta.expiresAt).getTime() - Date.now();
+    return ms / (1000 * 60 * 60 * 24);
+}
+/**
+ * Returns a human-readable expiry string, e.g.
+ * "expires in 7 days (2026-05-05)" or "expired 3 days ago (2026-04-25)".
+ */
+export function formatExpiry(meta) {
+    const days = daysUntilExpiry(meta);
+    const dateStr = new Date(meta.expiresAt).toISOString().slice(0, 10);
+    if (days < 0) {
+        return `expired ${Math.abs(days).toFixed(0)} days ago (${dateStr})`;
+    }
+    return `expires in ${days.toFixed(0)} days (${dateStr})`;
+}

package/dist/agent-wallet/lighter-keystore.d.ts

@@ -0,0 +1,34 @@
+/** Pure: deterministic absolute path for the keystore file. */
+export declare function lighterKeystorePath(accountIndex: number, slot: number): string;
+/**
+ * Encrypt a 40-byte Lighter L2 private key (hex) and write it to
+ * `~/.perp/lighter-agents/<accountIndex>-<slot>.json` with mode 0600.
+ *
+ * Returns the absolute path of the written file.
+ */
+export declare function saveLighterKey(accountIndex: number, slot: number, privateKeyHex: string, passphrase: string): string;
+/**
+ * Read + decrypt a stored Lighter L2 private key. Returns the hex string
+ * without `0x` prefix.
+ *
+ * Throws (no fallback):
+ *   - LIGHTER_KEYSTORE_NOT_FOUND if the file is missing
+ *   - LIGHTER_KEYSTORE_DECRYPT_FAILED if the passphrase is wrong / file corrupt
+ */
+export declare function loadLighterKey(accountIndex: number, slot: number, passphrase: string): string;
+/**
+ * Idempotent delete. Returns true if a file was removed, false if absent.
+ */
+export declare function deleteLighterKey(accountIndex: number, slot: number): boolean;
+/**
+ * One-time bridge from legacy env-based storage to the keystore.
+ *
+ * Triggered on a single, narrow condition: env has `LIGHTER_API_KEY` AND the
+ * target keystore file does not yet exist. After successful save, clears the
+ * three legacy env entries from `~/.perp/.env` so they cannot be re-read.
+ *
+ * NOT a fallback (SSOT Rule #2): runs at most once per install (post-clear, the
+ * trigger condition is permanently false). Single-direction (env → keystore);
+ * never reads from keystore back to env.
+ */
+export declare function migrateFromEnvIfPresent(): void;

package/dist/agent-wallet/lighter-keystore.js

@@ -0,0 +1,232 @@
+/**
+ * Lighter L2 agent keystore (SSOT Rule #3 — encrypted at-rest).
+ *
+ * Lighter's L2 signing key is a 40-byte secp256k1 private key — a non-OWS-native
+ * curve, so it cannot live in `~/.ows/wallets/` like Aster/HL/PAC agent keypairs.
+ * Per the FIXME(2d-spike) in src/commands/agent.ts and SSOT Rule #3 in CLAUDE.md,
+ * we persist these keys at `~/.perp/lighter-agents/<accountIndex>-<slot>.json`
+ * using the same AES-256-GCM + scrypt encryption scheme OWS uses.
+ *
+ * Empty passphrase ("") is acceptable — mirrors the HL/PAC pattern. Security
+ * model = file mode 0600 + obfuscation, NOT cryptographic strength against a
+ * local attacker. A non-empty passphrase upgrades the threat model.
+ *
+ * No fallbacks (SSOT Rule #2): missing files / wrong passphrase throw with
+ * remediation pointing the user at `perp wallet agent approve lighter --rotate`.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, chmodSync, } from "fs";
+import { resolve } from "path";
+import { randomBytes, scryptSync, createCipheriv, createDecipheriv, } from "node:crypto";
+import { PerpError } from "../errors.js";
+const KDF_PARAMS = { dklen: 32, n: 65536, p: 1, r: 8 };
+const SCRYPT_OPTS = { N: KDF_PARAMS.n, r: KDF_PARAMS.r, p: KDF_PARAMS.p, maxmem: 128 * 1024 * 1024 };
+const REMEDIATION = "perp wallet agent approve lighter --rotate";
+function lighterAgentsDir() {
+    return resolve(process.env["HOME"] ?? "~", ".perp", "lighter-agents");
+}
+/** Pure: deterministic absolute path for the keystore file. */
+export function lighterKeystorePath(accountIndex, slot) {
+    return resolve(lighterAgentsDir(), `${accountIndex}-${slot}.json`);
+}
+function ensureDir() {
+    const dir = lighterAgentsDir();
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+    else {
+        // best-effort tighten permissions if dir exists with looser mode
+        try {
+            chmodSync(dir, 0o700);
+        }
+        catch { /* non-fatal */ }
+    }
+    return dir;
+}
+function stripHexPrefix(hex) {
+    return hex.startsWith("0x") || hex.startsWith("0X") ? hex.slice(2) : hex;
+}
+/**
+ * Encrypt a 40-byte Lighter L2 private key (hex) and write it to
+ * `~/.perp/lighter-agents/<accountIndex>-<slot>.json` with mode 0600.
+ *
+ * Returns the absolute path of the written file.
+ */
+export function saveLighterKey(accountIndex, slot, privateKeyHex, passphrase) {
+    const dir = ensureDir();
+    const path = resolve(dir, `${accountIndex}-${slot}.json`);
+    const cleanHex = stripHexPrefix(privateKeyHex).toLowerCase();
+    if (!/^[0-9a-f]+$/.test(cleanHex) || cleanHex.length === 0) {
+        throw new PerpError("INVALID_PARAMS", "Lighter L2 private key must be hex", {
+            remediation: REMEDIATION,
+        });
+    }
+    const salt = randomBytes(32);
+    const iv = randomBytes(12);
+    const dk = scryptSync(Buffer.from(passphrase, "utf-8"), salt, KDF_PARAMS.dklen, SCRYPT_OPTS);
+    const cipher = createCipheriv("aes-256-gcm", dk, iv);
+    const ciphertext = Buffer.concat([
+        cipher.update(Buffer.from(cleanHex, "utf-8")),
+        cipher.final(),
+    ]);
+    const authTag = cipher.getAuthTag();
+    const file = {
+        version: 1,
+        accountIndex,
+        slot,
+        crypto: {
+            cipher: "aes-256-gcm",
+            cipherparams: { iv: iv.toString("hex") },
+            ciphertext: ciphertext.toString("hex"),
+            auth_tag: authTag.toString("hex"),
+            kdf: "scrypt",
+            kdfparams: {
+                dklen: KDF_PARAMS.dklen,
+                n: KDF_PARAMS.n,
+                p: KDF_PARAMS.p,
+                r: KDF_PARAMS.r,
+                salt: salt.toString("hex"),
+            },
+        },
+        createdAt: new Date().toISOString(),
+    };
+    writeFileSync(path, JSON.stringify(file, null, 2), { mode: 0o600 });
+    // Re-tighten in case writeFileSync overwrote an existing file with a looser umask
+    try {
+        chmodSync(path, 0o600);
+    }
+    catch { /* non-fatal */ }
+    return path;
+}
+/**
+ * Read + decrypt a stored Lighter L2 private key. Returns the hex string
+ * without `0x` prefix.
+ *
+ * Throws (no fallback):
+ *   - LIGHTER_KEYSTORE_NOT_FOUND if the file is missing
+ *   - LIGHTER_KEYSTORE_DECRYPT_FAILED if the passphrase is wrong / file corrupt
+ */
+export function loadLighterKey(accountIndex, slot, passphrase) {
+    // One-time data migration: if a legacy `LIGHTER_API_KEY` env var is set and
+    // the new keystore file does not exist yet, materialize the keystore from env
+    // before continuing. This is NOT a runtime fallback — it's a single-pass
+    // upgrade path that runs at most once per install.
+    migrateFromEnvIfPresent();
+    const path = lighterKeystorePath(accountIndex, slot);
+    if (!existsSync(path)) {
+        throw new PerpError("KEY_NOT_FOUND", `LIGHTER_KEYSTORE_NOT_FOUND: ${path}`, { remediation: REMEDIATION });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch (e) {
+        throw new PerpError("SIGNATURE_FAILED", `LIGHTER_KEYSTORE_DECRYPT_FAILED: corrupt JSON — ${e instanceof Error ? e.message : String(e)}`, { remediation: REMEDIATION });
+    }
+    if (parsed.version !== 1 || parsed.crypto?.cipher !== "aes-256-gcm" || parsed.crypto?.kdf !== "scrypt") {
+        throw new PerpError("SIGNATURE_FAILED", "LIGHTER_KEYSTORE_DECRYPT_FAILED: unsupported version or cipher", { remediation: REMEDIATION });
+    }
+    const salt = Buffer.from(parsed.crypto.kdfparams.salt, "hex");
+    const iv = Buffer.from(parsed.crypto.cipherparams.iv, "hex");
+    const ciphertext = Buffer.from(parsed.crypto.ciphertext, "hex");
+    const authTag = Buffer.from(parsed.crypto.auth_tag, "hex");
+    const dk = scryptSync(Buffer.from(passphrase, "utf-8"), salt, parsed.crypto.kdfparams.dklen, {
+        N: parsed.crypto.kdfparams.n,
+        r: parsed.crypto.kdfparams.r,
+        p: parsed.crypto.kdfparams.p,
+        maxmem: 128 * 1024 * 1024,
+    });
+    try {
+        const decipher = createDecipheriv("aes-256-gcm", dk, iv);
+        decipher.setAuthTag(authTag);
+        const plain = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+        return plain.toString("utf-8");
+    }
+    catch (e) {
+        throw new PerpError("SIGNATURE_FAILED", `LIGHTER_KEYSTORE_DECRYPT_FAILED: ${e instanceof Error ? e.message : String(e)}`, { remediation: REMEDIATION });
+    }
+}
+/**
+ * Idempotent delete. Returns true if a file was removed, false if absent.
+ */
+export function deleteLighterKey(accountIndex, slot) {
+    const path = lighterKeystorePath(accountIndex, slot);
+    if (!existsSync(path))
+        return false;
+    unlinkSync(path);
+    return true;
+}
+/**
+ * One-time bridge from legacy env-based storage to the keystore.
+ *
+ * Triggered on a single, narrow condition: env has `LIGHTER_API_KEY` AND the
+ * target keystore file does not yet exist. After successful save, clears the
+ * three legacy env entries from `~/.perp/.env` so they cannot be re-read.
+ *
+ * NOT a fallback (SSOT Rule #2): runs at most once per install (post-clear, the
+ * trigger condition is permanently false). Single-direction (env → keystore);
+ * never reads from keystore back to env.
+ */
+export function migrateFromEnvIfPresent() {
+    const envKey = process.env["LIGHTER_API_KEY"];
+    if (!envKey || envKey.length === 0)
+        return;
+    const accountIndexStr = process.env["LIGHTER_ACCOUNT_INDEX"];
+    const apiKeyIndexStr = process.env["LIGHTER_API_KEY_INDEX"];
+    const accountIndex = accountIndexStr ? parseInt(accountIndexStr, 10) : NaN;
+    const slot = apiKeyIndexStr ? parseInt(apiKeyIndexStr, 10) : NaN;
+    // If we lack the indices needed to address the keystore slot, bail silently.
+    // Migration only runs when the env trio is fully populated.
+    if (!Number.isFinite(accountIndex) || accountIndex < 0)
+        return;
+    if (!Number.isFinite(slot) || slot < 0)
+        return;
+    const target = lighterKeystorePath(accountIndex, slot);
+    if (existsSync(target))
+        return;
+    saveLighterKey(accountIndex, slot, envKey, "");
+    process.stderr.write(`[lighter] migrated LIGHTER_API_KEY env → ~/.perp/lighter-agents/${accountIndex}-${slot}.json (SSOT Rule #3)\n`);
+    // Clear the legacy env entries from ~/.perp/.env so the trigger never fires
+    // again. setEnvVar(name, "") rewrites the file with the empty value.
+    try {
+        // Inline lazy import to avoid a circular dep at module-load time.
+        // setEnvVar is sync; the dynamic import is deliberately resolved lazily.
+        void clearEnvLegacyKeys();
+    }
+    catch {
+        // best-effort — file may be locked or read-only; the in-memory delete below
+        // still prevents this process from re-triggering migration.
+    }
+    delete process.env["LIGHTER_API_KEY"];
+    delete process.env["LIGHTER_ACCOUNT_INDEX"];
+    delete process.env["LIGHTER_API_KEY_INDEX"];
+}
+// Async helper deliberately split out so migrateFromEnvIfPresent stays sync.
+function clearEnvLegacyKeys() {
+    // Use the same .env parser/writer the rest of the CLI uses so we don't
+    // accidentally drop comments or other entries.
+    // Sync read + write via fs.
+    const PERP_DIR = resolve(process.env["HOME"] ?? "~", ".perp");
+    const ENV_FILE = resolve(PERP_DIR, ".env");
+    if (!existsSync(ENV_FILE))
+        return;
+    const lines = readFileSync(ENV_FILE, "utf-8").split("\n");
+    const out = [];
+    const dropKeys = new Set([
+        "LIGHTER_API_KEY",
+        "LIGHTER_ACCOUNT_INDEX",
+        "LIGHTER_API_KEY_INDEX",
+    ]);
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#")) {
+            out.push(line);
+            continue;
+        }
+        const eqIdx = trimmed.indexOf("=");
+        if (eqIdx > 0 && dropKeys.has(trimmed.slice(0, eqIdx))) {
+            continue;
+        }
+        out.push(line);
+    }
+    writeFileSync(ENV_FILE, out.join("\n"), { mode: 0o600 });
+}

package/dist/agent-wallet/passphrase.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Resolve master passphrase from (in precedence order):
+ *   1. opts.flag  (--passphrase)
+ *   2. process.env.OWS_PASSPHRASE
+ *   3. stdin (only if process.stdin.isTTY === false)
+ *
+ * Returns null if no path provides one AND stdin IS TTY (caller may prompt).
+ * Throws PASSPHRASE_REQUIRED with remediation if no path provides one AND
+ * stdin is non-TTY (AC-16).
+ */
+export declare function resolvePassphrase(opts: {
+    flag?: string;
+}): Promise<string | null>;

package/dist/agent-wallet/passphrase.js

@@ -0,0 +1,54 @@
+import { PerpError } from "../errors.js";
+const REMEDIATION = "Provide passphrase via --passphrase flag, OWS_PASSPHRASE env var, or stdin pipe (echo $PP | perp ...)";
+/**
+ * Resolve master passphrase from (in precedence order):
+ *   1. opts.flag  (--passphrase)
+ *   2. process.env.OWS_PASSPHRASE
+ *   3. stdin (only if process.stdin.isTTY === false)
+ *
+ * Returns null if no path provides one AND stdin IS TTY (caller may prompt).
+ * Throws PASSPHRASE_REQUIRED with remediation if no path provides one AND
+ * stdin is non-TTY (AC-16).
+ */
+export async function resolvePassphrase(opts) {
+    // 1. CLI flag (allow empty string when explicitly passed via --passphrase '')
+    if (opts.flag !== undefined) {
+        return opts.flag;
+    }
+    // 2. Environment variable (allow empty string when explicitly set; treat
+    // unset as absent)
+    if ("OWS_PASSPHRASE" in process.env) {
+        return process.env["OWS_PASSPHRASE"] ?? "";
+    }
+    // 3. stdin pipe — only when stdin is not a TTY
+    if (process.stdin.isTTY === false) {
+        const piped = await readStdin();
+        if (piped !== null) {
+            return piped;
+        }
+        // stdin was non-TTY but empty — throw rather than falling through to prompt
+        throw new PerpError("PASSPHRASE_REQUIRED", "No passphrase provided and stdin is non-TTY", {
+            remediation: REMEDIATION,
+        });
+    }
+    // stdin IS TTY — caller decides whether to prompt interactively
+    return null;
+}
+/**
+ * Read all bytes from stdin until EOF, trim trailing newlines.
+ * Returns null if stdin produced zero bytes.
+ */
+async function readStdin() {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        process.stdin.setEncoding("utf-8");
+        process.stdin.on("data", (chunk) => {
+            chunks.push(typeof chunk === "string" ? chunk : chunk.toString("utf-8"));
+        });
+        process.stdin.on("end", () => {
+            const raw = chunks.join("").replace(/\r?\n$/, "");
+            resolve(raw.length > 0 ? raw : null);
+        });
+        process.stdin.on("error", reject);
+    });
+}

package/dist/agent-wallet/signing-strategy.d.ts

@@ -0,0 +1,67 @@
+import type { AgentMeta } from "../settings.js";
+/**
+ * Interface for agent-key signing strategies.
+ * The AsterAdapter consumes this interface, never a concrete class.
+ *
+ * Signature shape mirrors EvmSigner.signTypedData(domain, types, message) so
+ * call sites can cast to `EvmSigner & AgentSigningStrategy` and dispatch
+ * uniformly. The return type differs from EvmSigner (which returns string):
+ * AgentSigningStrategy returns { signature, r, s, v } so callers can pull
+ * raw r/s/v if needed.
+ */
+export interface AgentSigningStrategy {
+    signTypedData(domain: Record<string, unknown>, types: Record<string, Array<{
+        name: string;
+        type: string;
+    }>>, message: Record<string, unknown>): Promise<{
+        signature: string;
+        r: string;
+        s: string;
+        v: number;
+    }>;
+    getAddress(): string;
+}
+/**
+ * Strategy: pass the OWS api-key token in the passphrase slot.
+ * This is the default (Option A γ-path). Validity depends on Step 0a spike.
+ * Wraps OwsEvmSigner.create(walletName, owsKeyToken).
+ */
+export declare class TokenAsPassphraseStrategy implements AgentSigningStrategy {
+    private _walletName;
+    private _owsKeyToken;
+    private _address;
+    constructor(walletName: string, owsKeyToken: string, address: string);
+    getAddress(): string;
+    signTypedData(domain: Record<string, unknown>, types: Record<string, Array<{
+        name: string;
+        type: string;
+    }>>, message: Record<string, unknown>): Promise<{
+        signature: string;
+        r: string;
+        s: string;
+        v: number;
+    }>;
+}
+/**
+ * Strategy: read the token from the OWS keyfile by api-key id and pass it
+ * explicitly. Stub until Step 0a determines whether this path is needed.
+ */
+export declare class ExplicitTokenStrategy implements AgentSigningStrategy {
+    constructor(_walletName: string, _apiKeyId: string, _address: string);
+    getAddress(): string;
+    signTypedData(_domain: Record<string, unknown>, _types: Record<string, Array<{
+        name: string;
+        type: string;
+    }>>, _message: Record<string, unknown>): Promise<{
+        signature: string;
+        r: string;
+        s: string;
+        v: number;
+    }>;
+}
+/**
+ * Factory: returns the appropriate signing strategy for the given agent meta +
+ * OWS api-key token. Defaults to TokenAsPassphraseStrategy per Option A γ-path.
+ * Will switch based on Step 0a spike outcome.
+ */
+export declare function agentSigningStrategyFor(meta: AgentMeta, owsKeyToken: string): AgentSigningStrategy;

package/dist/agent-wallet/signing-strategy.js

@@ -0,0 +1,51 @@
+/**
+ * Strategy: pass the OWS api-key token in the passphrase slot.
+ * This is the default (Option A γ-path). Validity depends on Step 0a spike.
+ * Wraps OwsEvmSigner.create(walletName, owsKeyToken).
+ */
+export class TokenAsPassphraseStrategy {
+    _walletName;
+    _owsKeyToken;
+    _address;
+    constructor(walletName, owsKeyToken, address) {
+        this._walletName = walletName;
+        this._owsKeyToken = owsKeyToken;
+        this._address = address;
+    }
+    getAddress() {
+        return this._address;
+    }
+    async signTypedData(domain, types, message) {
+        // Lazy import to avoid loading OWS bindings unless this strategy is used
+        const { OwsEvmSigner } = await import("../signer/ows-evm.js");
+        const signer = OwsEvmSigner.create(this._walletName, this._owsKeyToken);
+        const hexSig = await signer.signTypedData(domain, types, message);
+        // Parse r, s, v from the 65-byte hex signature
+        const sig = hexSig.startsWith("0x") ? hexSig.slice(2) : hexSig;
+        const r = `0x${sig.slice(0, 64)}`;
+        const s = `0x${sig.slice(64, 128)}`;
+        const v = parseInt(sig.slice(128, 130), 16);
+        return { signature: hexSig, r, s, v };
+    }
+}
+/**
+ * Strategy: read the token from the OWS keyfile by api-key id and pass it
+ * explicitly. Stub until Step 0a determines whether this path is needed.
+ */
+export class ExplicitTokenStrategy {
+    constructor(_walletName, _apiKeyId, _address) { }
+    getAddress() {
+        throw new Error("ExplicitTokenStrategy.getAddress(): not implemented — pending Step 0a spike outcome");
+    }
+    async signTypedData(_domain, _types, _message) {
+        throw new Error("ExplicitTokenStrategy.signTypedData(): not implemented — pending Step 0a spike outcome");
+    }
+}
+/**
+ * Factory: returns the appropriate signing strategy for the given agent meta +
+ * OWS api-key token. Defaults to TokenAsPassphraseStrategy per Option A γ-path.
+ * Will switch based on Step 0a spike outcome.
+ */
+export function agentSigningStrategyFor(meta, owsKeyToken) {
+    return new TokenAsPassphraseStrategy(meta.agentWalletName, owsKeyToken, meta.agentEvmAddress);
+}