@promus/cli 0.24.17

package/README.md

@@ -0,0 +1,18 @@
+# promus
+
+CLI binary for **promus**: the first fully on-chain sovereign agent harness on 0G.
+
+## Install
+
+```bash
+bun add -g promus
+promus init
+```
+
+Requires [bun](https://bun.sh) ≥ 1.1.
+
+## Commands
+
+`promus init` boots the wizard (mints an iNFT, opens a 0G Compute ledger, generates the agent EOA). After that: `promus` for chat, `promus status`, `promus logs`, `promus topup`, `promus ledger`, `promus drain`, `promus sync`, `promus inspect`, `promus deploy`, `promus upgrade`, `promus help` for the full list.
+
+See the [root README](https://github.com/JemIIahh/promus#readme) for architecture, concepts, and the full command reference.

package/bin/promus

@@ -0,0 +1,33 @@
+#!/usr/bin/env bun
+// Register the @opentui/solid JSX transform plugin BEFORE any .tsx file
+// loads. bunfig.toml's `preload` only fires when bun discovers bunfig.toml
+// in the cwd lookup chain — running `promus` from outside the repo (e.g.
+// `cd ~ && promus`, or as an installed npm bin) skips it entirely, leaving
+// JSX compiled as React.createElement and the chat TUI rendering blank.
+// Importing the preload module here registers the plugin regardless of
+// cwd. The plugin is idempotent so this is a no-op if bunfig.toml ALSO
+// loaded it.
+import '@opentui/solid/preload'
+
+// Polyfill Error.captureStackTrace for bun + follow-redirects compatibility.
+// follow-redirects@1.16 (transitive via @0glabs/0g-serving-broker → axios) calls
+// Error.captureStackTrace(this, ctor) inside a CustomError constructor whose
+// prototype is set to Error AFTER createErrorType returns. Bun's strict-mode
+// validator rejects the call when bun's workspace resolver loads the module
+// (the failure is cwd-dependent: only triggers when bun's cwd is inside this
+// monorepo). Wrapping the original keeps Node parity without monkey-patching
+// follow-redirects itself.
+const _origCapture = Error.captureStackTrace
+if (typeof _origCapture === 'function') {
+  Error.captureStackTrace = (target, ctor) => {
+    if (!target || typeof target !== 'object') return
+    try {
+      _origCapture(target, ctor)
+    } catch {
+      try {
+        target.stack = new Error().stack
+      } catch {}
+    }
+  }
+}
+import '../src/index'

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@promus/cli",
+  "version": "0.24.17",
+  "type": "module",
+  "description": "Promus CLI: sovereign agent gateway on Arbitrum. Runs `promus init` to mint an iNFT and bring up your agent",
+  "license": "MIT",
+  "homepage": "https://github.com/JemIIahh/promus",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JemIIahh/promus.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/JemIIahh/promus/issues"
+  },
+  "keywords": ["arbitrum", "promus", "agent", "ai", "cli", "tui", "sovereign", "gateway", "inft"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.1"
+  },
+  "files": ["src", "bin", "README.md"],
+  "bin": {
+    "promus": "./bin/promus"
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "scripts": {
+    "build": "tsc -b",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.8.2",
+    "@opentui/core": "^0.1.97",
+    "@opentui/solid": "^0.1.97",
+    "@promus/core": "0.24.17",
+    "@promus/gateway": "0.24.17",
+    "@promus/plugin-comms": "0.24.17",
+    "@promus/plugin-onchain": "0.24.17",
+    "@promus/plugin-system": "0.24.17",
+    "@promus/plugin-telegram": "0.24.17",
+    "picocolors": "^1.1.1",
+    "qrcode-terminal": "^0.12.0",
+    "solid-js": "^1.9.12",
+    "viem": "^2.21.55"
+  },
+  "devDependencies": {
+    "@types/qrcode-terminal": "^0.12.2"
+  }
+}

package/src/commands/_agents.ts

@@ -0,0 +1,14 @@
+import { existsSync } from 'node:fs'
+import { readdir } from 'node:fs/promises'
+import { agentPaths } from '@promus/core'
+
+export async function listAgentIds(): Promise<string[]> {
+  if (!existsSync(agentPaths.agentsDir)) return []
+  const entries = await readdir(agentPaths.agentsDir, { withFileTypes: true })
+  return entries.filter(e => e.isDirectory()).map(e => e.name)
+}
+
+export async function pickDefaultAgent(): Promise<string | null> {
+  const ids = await listAgentIds()
+  return ids[0] ?? null
+}

package/src/commands/_inft-ref.ts

@@ -0,0 +1,43 @@
+import { type PromusNetwork, NETWORK_CHAIN_ID, networkFromChainId } from '@promus/core'
+import type { Address } from 'viem'
+
+/**
+ * Parse a CAIP-style or 0G-flavor iNFT ref string into its parts. Used by
+ * `promus restore` and `promus inspect` to take a single positional argument
+ * pointing at any iNFT on either 0G network.
+ *
+ * Accepted forms:
+ *   `eip155:<chainId>:0xCONTRACT:<tokenId>`
+ *   `0g-mainnet:0xCONTRACT:<tokenId>`
+ *   `0g-testnet:0xCONTRACT:<tokenId>`
+ */
+export interface ParsedINFTRef {
+  network: PromusNetwork
+  contract: Address
+  tokenId: bigint
+}
+
+export function parseINFTRef(ref: string): ParsedINFTRef {
+  const parts = ref.split(':')
+  if (parts.length === 4 && parts[0] === 'eip155') {
+    const chainId = Number(parts[1])
+    const contract = parts[2] as Address
+    const tokenId = BigInt(parts[3]!)
+    const network = networkFromChainId(chainId)
+    if (!network) {
+      const known = Object.values(NETWORK_CHAIN_ID).join(' or ')
+      throw new Error(`Unknown chain id ${chainId} (expected ${known})`)
+    }
+    return { network, contract, tokenId }
+  }
+  if (parts.length === 3 && (parts[0] === '0g-mainnet' || parts[0] === '0g-testnet')) {
+    return {
+      network: parts[0] as PromusNetwork,
+      contract: parts[1] as Address,
+      tokenId: BigInt(parts[2]!),
+    }
+  }
+  throw new Error(
+    `Unrecognized iNFT ref '${ref}'. Expected 'eip155:<chain>:0xCONTRACT:<tokenId>' or '0g-mainnet:0xCONTRACT:<tokenId>'.`,
+  )
+}

package/src/commands/_unlock.ts

@@ -0,0 +1,74 @@
+import { spinner } from '@clack/prompts'
+import {
+  type PromusConfig,
+  type PromusNetwork,
+  agentPaths,
+  fetchAndDecryptKeystore,
+  iNFTAgentId,
+} from '@promus/core'
+import type { Address, Hex } from 'viem'
+import { withSilencedConsole } from '../util/silence-console'
+import { loadOrPickOperatorSigner } from './init/operator-picker'
+
+export interface UnlockedAgent {
+  agentPrivkey: Hex
+  agentAddress: Address
+  network: PromusNetwork
+  close: () => Promise<void>
+}
+
+/**
+ * Shared operator-unlock dance for any command that needs the agent privkey:
+ *  1. pick the operator signer (keystore / WC / keychain) per config hint
+ *  2. fetch the encrypted keystore from 0G Storage
+ *  3. decrypt via operator signature
+ *
+ * Returns null if the operator picker is cancelled or the keystore can't be
+ * decrypted; caller should bail out early on null.
+ *
+ * The unlock spinner is rendered with the passed `spinnerLabel` so each caller
+ * keeps its own copy.
+ *
+ * Caller MUST call `close()` once done with the privkey, even on success, to
+ * release WC sessions / keystore tmpfiles.
+ */
+export async function unlockAgentSigner(
+  config: PromusConfig,
+  spinnerLabel = 'Fetching encrypted keystore + decrypting via operator wallet',
+): Promise<UnlockedAgent | null> {
+  if (!config.identity.iNFT || !config.identity.agent) return null
+  const network = config.network
+  const agentAddress = config.identity.agent as Address
+  const inftContract = config.identity.iNFT.contract as Address
+  const inftTokenId = BigInt(config.identity.iNFT.tokenId)
+  const finalAgentId = iNFTAgentId({ contractAddress: inftContract, tokenId: inftTokenId })
+  const paths = agentPaths.agent(finalAgentId)
+
+  const operator = await loadOrPickOperatorSigner({ network, hint: config.operator })
+  if (!operator) return null
+
+  const close = async () => {
+    await operator.close?.()
+  }
+
+  const s = spinner()
+  s.start(spinnerLabel)
+  try {
+    const decrypted = await withSilencedConsole(() =>
+      fetchAndDecryptKeystore({
+        network,
+        contractAddress: inftContract,
+        tokenId: inftTokenId,
+        signer: operator,
+        agentAddress,
+        cachePath: paths.keystore,
+      }),
+    )
+    s.stop(`unlocked (keystore source: ${decrypted.source})`)
+    return { agentPrivkey: decrypted.privkeyHex, agentAddress, network, close }
+  } catch (e) {
+    s.stop(`unlock failed: ${(e as Error).message.slice(0, 160)}`)
+    await close()
+    return null
+  }
+}

package/src/commands/admin-autotopup-tick.ts

@@ -0,0 +1,73 @@
+import { existsSync } from 'node:fs'
+import { agentPaths, iNFTAgentId, placeholderAgentId } from '@promus/core'
+import { type Address, getAddress } from 'viem'
+import { findAndLoadConfig } from '../config/load'
+import { SandboxClient } from '../sandbox/client'
+import { loadOrPickOperatorSigner } from './init/operator-picker'
+
+export async function runAdminAutotopupTick(): Promise<void> {
+  const found = await findAndLoadConfig()
+  if (!found) {
+    console.error('No promus.config.ts found. Run `promus init` first.')
+    process.exit(1)
+  }
+  const { config } = found
+
+  if (config.deployTarget === 'sandbox' && config.sandbox?.endpoint && config.sandbox.id) {
+    const signer = await loadOrPickOperatorSigner({
+      network: config.network,
+      hint: config.operator,
+    })
+    if (!signer) {
+      console.error('failed to load operator signer (cancelled or no key)')
+      process.exit(1)
+    }
+    const operatorAccount = await signer.account()
+    const client = new SandboxClient({
+      endpoint: config.sandbox.endpoint,
+      sandboxId: config.sandbox.id,
+      operator: operatorAccount,
+    })
+    try {
+      const result = await client.triggerAutoTopupTick()
+      console.log(JSON.stringify(result, null, 2))
+      if (!result.ok) process.exitCode = 1
+    } catch (e) {
+      console.error(`autotopup-tick failed: ${(e as Error).message.slice(0, 240)}`)
+      process.exit(1)
+    }
+    return
+  }
+
+  if (!config.identity.agent) {
+    console.error('No agent address in config. Run `promus init` first.')
+    process.exit(1)
+  }
+  // Slug derivation must match gateway-stop.ts (iNFT-based when minted, else
+  // address-placeholder); the daemon writes its sock under the same dir.
+  const slug = config.identity.iNFT
+    ? iNFTAgentId({
+        contractAddress: getAddress(config.identity.iNFT.contract as Address),
+        tokenId: BigInt(config.identity.iNFT.tokenId),
+      })
+    : placeholderAgentId(config.identity.agent)
+  const sockPath = `${agentPaths.agent(slug).dir}/gateway.sock`
+  if (!existsSync(sockPath)) {
+    console.error(
+      `Gateway socket not found at ${sockPath}. Start the gateway with \`promus gateway start\` or run \`promus\` first.`,
+    )
+    process.exit(1)
+  }
+  const r = await fetch('http://localhost/admin/autotopup/tick', {
+    method: 'POST',
+    unix: sockPath,
+  } as RequestInit & { unix: string })
+  if (!r.ok) {
+    const detail = await r.text().catch(() => '')
+    console.error(`autotopup-tick failed (${r.status}): ${detail}`)
+    process.exit(1)
+  }
+  const body = (await r.json()) as { ok: boolean; reason?: string }
+  console.log(JSON.stringify(body, null, 2))
+  if (!body.ok) process.exitCode = 1
+}

package/src/commands/admin.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, test } from 'bun:test'
+import { parseAdminArgs, runAdmin } from './admin'
+
+describe('parseAdminArgs', () => {
+  test('errors with usage when no subcommand', () => {
+    const r = parseAdminArgs([])
+    expect('error' in r).toBe(true)
+    if (!('error' in r)) throw new Error('unreachable')
+    expect(r.error).toMatch(/usage/i)
+    expect(r.error).toMatch(/autotopup-tick/)
+  })
+
+  test('errors on unknown subcommand', () => {
+    const r = parseAdminArgs(['nope'])
+    expect('error' in r).toBe(true)
+    if (!('error' in r)) throw new Error('unreachable')
+    expect(r.error).toMatch(/unknown subcommand/)
+    expect(r.error).toMatch(/'nope'/)
+  })
+
+  test('parses autotopup-tick', () => {
+    const r = parseAdminArgs(['autotopup-tick'])
+    expect('error' in r).toBe(false)
+    if ('error' in r) throw new Error(r.error)
+    expect(r.sub).toBe('autotopup-tick')
+  })
+})
+
+describe('runAdmin dispatch', () => {
+  test('runAdmin is callable + accepts AdminArgs shape', () => {
+    expect(typeof runAdmin).toBe('function')
+    expect(runAdmin.length).toBe(1)
+  })
+})

package/src/commands/admin.ts

@@ -0,0 +1,32 @@
+// `promus admin <sub>` — operator-only ops dispatch. Mirrors `pairing.ts` shape.
+
+export interface AdminArgs {
+  sub: 'autotopup-tick'
+}
+
+const VALID_SUBS = ['autotopup-tick'] as const
+
+export type AdminParseResult = AdminArgs | { error: string }
+
+export function parseAdminArgs(argv: string[]): AdminParseResult {
+  const sub = argv[0]
+  if (!sub) {
+    return {
+      error: `usage: promus admin <${VALID_SUBS.join(' | ')}>`,
+    }
+  }
+  if (!(VALID_SUBS as readonly string[]).includes(sub)) {
+    return { error: `unknown subcommand '${sub}' (expected: ${VALID_SUBS.join(' | ')})` }
+  }
+  return { sub: sub as AdminArgs['sub'] }
+}
+
+export async function runAdmin(args: AdminArgs): Promise<void> {
+  switch (args.sub) {
+    case 'autotopup-tick': {
+      const { runAdminAutotopupTick } = await import('./admin-autotopup-tick')
+      await runAdminAutotopupTick()
+      return
+    }
+  }
+}

package/src/commands/balance.test.ts

@@ -0,0 +1,10 @@
+import { describe, expect, test } from 'bun:test'
+import { runBalance } from './balance'
+
+describe('promus balance command surface', () => {
+  test('runBalance is exported and callable', () => {
+    expect(typeof runBalance).toBe('function')
+    // function signature: (opts: { agent?, cwd? }) → Promise<void>
+    expect(runBalance.length).toBe(1)
+  })
+})

package/src/commands/balance.ts

@@ -0,0 +1,112 @@
+import {
+  type PromusNetwork,
+  NETWORK_RPC,
+  format0G,
+  getLedgerDetailReadOnly,
+  getSandboxBillingReserve,
+} from '@promus/core'
+import { http, type Address, createPublicClient } from 'viem'
+import { findAndLoadConfig } from '../config/load'
+
+export interface BalanceOpts {
+  agent?: string
+  cwd?: string
+}
+
+/**
+ * Operator-facing aggregator for the agent's full economic position. Mirrors
+ * `account.balance` brain tool but renders for terminals.
+ *
+ * Why: pre-v0.21.9, getting a full picture took `cast balance` × 2 networks +
+ * `promus ledger balance` (needs unlock) + a separate cast for sandbox billing.
+ * Operators kept under-counting by ~10x because the locked-in-providers split
+ * wasn't surfaced anywhere.
+ */
+export async function runBalance(opts: BalanceOpts): Promise<void> {
+  const found = await findAndLoadConfig(opts.cwd)
+  if (!found) {
+    console.error('No promus.config.ts found. Run `promus init` first.')
+    process.exit(1)
+  }
+  const { config } = found
+  const agentAddress = (opts.agent ?? config.identity.agent) as Address | undefined
+  if (!agentAddress) {
+    console.error('No agent address. Run `promus init` first or pass `--agent 0x...`.')
+    process.exit(1)
+  }
+
+  const network = config.network as PromusNetwork
+  const operatorAddress = config.identity.operator as Address | undefined
+  const isSandbox = config.deployTarget === 'sandbox'
+
+  const mainnetClient = createPublicClient({ transport: http(NETWORK_RPC['0g-mainnet']) })
+  const testnetClient = createPublicClient({ transport: http(NETWORK_RPC['0g-testnet']) })
+
+  const [eoaMainnetWei, eoaTestnetWei, ledger, sandboxReserve] = await Promise.all([
+    mainnetClient.getBalance({ address: agentAddress }).catch(() => 0n),
+    testnetClient.getBalance({ address: agentAddress }).catch(() => 0n),
+    getLedgerDetailReadOnly({ network, agentAddress }).catch(() => null),
+    isSandbox && operatorAddress
+      ? getSandboxBillingReserve({ recipient: operatorAddress }).catch(() => 0n)
+      : Promise.resolve(null),
+  ])
+
+  console.log('')
+  console.log(`agent       ${agentAddress}${config.subname ? ` (${config.subname}.promus.0g)` : ''}`)
+  console.log(`network     ${network}`)
+  console.log(`target      ${config.deployTarget ?? 'local'}`)
+  console.log('')
+  console.log('mainnet (chain 16661)')
+  console.log(`  EOA balance               ${format0G(eoaMainnetWei)} 0G`)
+  if (ledger) {
+    console.log(`  compute ledger total      ${format0G(ledger.totalBalance)} 0G`)
+    console.log(`    available               ${format0G(ledger.availableBalance)} 0G`)
+    console.log(`    locked in providers     ${format0G(ledger.lockedBalance)} 0G`)
+  } else {
+    console.log('  compute ledger            (not opened — call `promus topup --compute N` to seed)')
+  }
+  console.log('')
+  console.log('testnet/galileo (chain 16602)')
+  console.log(`  EOA balance               ${format0G(eoaTestnetWei)} 0G`)
+  if (isSandbox && operatorAddress) {
+    if (sandboxReserve !== null) {
+      console.log(
+        `  sandbox billing reserve   ${format0G(sandboxReserve)} 0G  (operator ${operatorAddress})`,
+      )
+    } else {
+      console.log('  sandbox billing reserve   (unavailable — RPC error)')
+    }
+  } else if (isSandbox) {
+    console.log('  sandbox billing reserve   (operator address missing in config)')
+  }
+
+  console.log('')
+  console.log('position summary')
+  const mainnetTotal = eoaMainnetWei + (ledger?.totalBalance ?? 0n)
+  const testnetTotal = eoaTestnetWei + (sandboxReserve ?? 0n)
+  console.log(`  mainnet total             ${format0G(mainnetTotal)} 0G  (EOA + ledger)`)
+  console.log(`  testnet total             ${format0G(testnetTotal)} 0G  (EOA + sandbox reserve)`)
+
+  const warnings: string[] = []
+  if (eoaMainnetWei < 2_000_000_000_000_000_000n) {
+    warnings.push(
+      'EOA mainnet below 2 0G notify threshold — auto-topup will fire wallet-low events',
+    )
+  }
+  if (ledger && ledger.availableBalance < 500_000_000_000_000_000n) {
+    warnings.push(
+      'Compute ledger available below 0.5 0G — auto-topup may transfer from EOA into provider envelopes',
+    )
+  }
+  if (isSandbox && sandboxReserve !== null && sandboxReserve < 1_000_000_000_000_000_000n) {
+    warnings.push(
+      'Sandbox billing reserve below 1 0G — top up via `promus topup --sandbox N` to extend container runtime',
+    )
+  }
+  if (warnings.length) {
+    console.log('')
+    console.log('warnings')
+    for (const w of warnings) console.log(`  · ${w}`)
+  }
+  console.log('')
+}