@promus/cli 0.24.17

package/src/commands/pairing.ts

@@ -0,0 +1,81 @@
+/**
+ * `promus pairing <subcommand>` — argv dispatcher for the DM pairing flow.
+ *
+ * Subcommands:
+ *   list                          show pending codes + approved users
+ *   approve <platform> <code>     approve a pairing code (case-insensitive)
+ *   revoke <platform> <userId>    revoke an approved user
+ *   clear-pending [platform]      drop all pending codes
+ *
+ * Platform is `telegram` for Phase 12. Future platforms (discord, slack) will
+ * reuse the same command surface.
+ */
+
+export interface PairingArgs {
+  sub: 'list' | 'approve' | 'revoke' | 'clear-pending'
+  platform?: string
+  code?: string
+  userId?: string
+  yes?: boolean
+}
+
+const VALID_SUBS = ['list', 'approve', 'revoke', 'clear-pending'] as const
+
+export type PairingParseResult = PairingArgs | { error: string }
+
+export function parsePairingArgs(argv: string[]): PairingParseResult {
+  const sub = argv[0]
+  if (!sub) {
+    return {
+      error:
+        'usage: promus pairing <list | approve <platform> <code> | revoke <platform> <userId> | clear-pending [platform]>',
+    }
+  }
+  if (!(VALID_SUBS as readonly string[]).includes(sub)) {
+    return { error: `unknown subcommand '${sub}' (expected: ${VALID_SUBS.join(' | ')})` }
+  }
+  const positional = argv.slice(1).filter(a => !a.startsWith('-'))
+  const yes = argv.includes('--yes') || argv.includes('-y')
+
+  if (sub === 'approve') {
+    if (positional.length < 2) {
+      return { error: 'usage: promus pairing approve <platform> <code>' }
+    }
+    return { sub: 'approve', platform: positional[0], code: positional[1], yes }
+  }
+  if (sub === 'revoke') {
+    if (positional.length < 2) {
+      return { error: 'usage: promus pairing revoke <platform> <userId>' }
+    }
+    return { sub: 'revoke', platform: positional[0], userId: positional[1], yes }
+  }
+  if (sub === 'clear-pending') {
+    return { sub: 'clear-pending', platform: positional[0], yes }
+  }
+  return { sub: 'list', platform: positional[0], yes }
+}
+
+export async function runPairing(args: PairingArgs): Promise<void> {
+  switch (args.sub) {
+    case 'list': {
+      const { runPairingList } = await import('./pairing-list')
+      await runPairingList({ platform: args.platform })
+      return
+    }
+    case 'approve': {
+      const { runPairingApprove } = await import('./pairing-approve')
+      await runPairingApprove({ platform: args.platform!, code: args.code! })
+      return
+    }
+    case 'revoke': {
+      const { runPairingRevoke } = await import('./pairing-revoke')
+      await runPairingRevoke({ platform: args.platform!, userId: args.userId!, yes: args.yes })
+      return
+    }
+    case 'clear-pending': {
+      const { runPairingClear } = await import('./pairing-clear')
+      await runPairingClear({ platform: args.platform, yes: args.yes })
+      return
+    }
+  }
+}

package/src/commands/pause.ts

@@ -0,0 +1,99 @@
+import { cancel, confirm, intro, isCancel, note, outro, spinner } from '@clack/prompts'
+import { SANDBOX_PROVIDER_URL_GALILEO, SandboxProviderClient } from '@promus/core'
+import { findAndLoadConfig } from '../config/load'
+import { loadOrPickOperatorSigner } from './init/operator-picker'
+import { ensureSandboxArchived } from './init/sandbox-provision'
+
+interface PauseOpts {
+  yes?: boolean
+}
+
+/**
+ * `promus pause`: archive a started sandbox to stop the runtime burn.
+ *
+ * Use during dev gaps to extend deposit runway. Sandbox UUID + endpoint
+ * preserved; resume via `promus resume` (~2-5 min cold restore).
+ *
+ * Does NOT require operator-keystore unlock. Only needs the operator wallet
+ * to sign the provider HTTP request (action=archive). Fast, low-friction.
+ */
+export async function runPause(opts: PauseOpts = {}): Promise<void> {
+  intro('promus pause')
+
+  const loaded = await findAndLoadConfig()
+  if (!loaded) {
+    cancel('No promus.config.ts found.')
+    return
+  }
+  const { config } = loaded
+  if (config.deployTarget !== 'sandbox' || !config.sandbox?.id) {
+    cancel(
+      `Agent is not deployed to a sandbox. (deployTarget=${config.deployTarget ?? 'local'}). Nothing to pause.`,
+    )
+    return
+  }
+
+  const sandboxId = config.sandbox.id
+  const operator = await loadOrPickOperatorSigner({
+    network: config.network,
+    hint: config.operator,
+  })
+  if (!operator) {
+    cancel('No operator wallet available; cannot sign archive request.')
+    return
+  }
+
+  if (!opts.yes) {
+    const ok = await confirm({
+      message: `Pause sandbox ${sandboxId.slice(0, 8)}? Burn stops; resume with \`promus resume\`.`,
+      initialValue: true,
+    })
+    if (isCancel(ok) || !ok) {
+      cancel('Aborted.')
+      await operator.close?.()
+      return
+    }
+  }
+
+  const operatorAccount = await operator.account()
+  const provider = new SandboxProviderClient({
+    endpoint: SANDBOX_PROVIDER_URL_GALILEO,
+    operator: operatorAccount,
+  })
+
+  const sBox = spinner()
+  sBox.start('Archiving sandbox')
+  try {
+    const result = await ensureSandboxArchived(provider, sandboxId, {
+      onProgress: msg => sBox.message(msg),
+    })
+    if (result.alreadyArchived) {
+      sBox.stop(`sandbox ${sandboxId.slice(0, 8)} already archived (no-op)`)
+    } else {
+      sBox.stop(`sandbox ${sandboxId.slice(0, 8)} archived (was ${result.initialState})`)
+    }
+    outro(
+      [
+        '',
+        `  sandbox       ${sandboxId} (preserved)`,
+        `  endpoint      ${config.sandbox.endpoint} (preserved)`,
+        `  state before  ${result.initialState}`,
+        '  state now     archived',
+        '  burn          stopped',
+        '',
+        'To wake: promus resume',
+      ].join('\n'),
+    )
+  } catch (e) {
+    sBox.stop(`pause failed: ${(e as Error).message.slice(0, 200)}`)
+    note(
+      [
+        'The sandbox could not transition to archived.',
+        'Run `promus status` to inspect, or retry. If the underlying state is bad, `promus upgrade --reprovision` is the escape hatch.',
+      ].join('\n'),
+      'recoverable',
+    )
+  } finally {
+    await operator.close?.()
+  }
+}

package/src/commands/profile.ts

@@ -0,0 +1,184 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { cancel, intro, note, outro, spinner } from '@clack/prompts'
+import {
+  MemorySyncManager,
+  OPERATOR_BLOB_SCOPES,
+  agentPaths,
+  deriveBlobKey,
+  explorerTxUrl,
+  fetchAndDecryptKeystore,
+  iNFTAgentId,
+} from '@promus/core'
+import type { Address, Hex } from 'viem'
+import { findAndLoadConfig } from '../config/load'
+import { withSilencedConsole } from '../util/silence-console'
+import { loadOrPickOperatorSigner } from './init/operator-picker'
+
+/**
+ * `promus profile init` — v0.23.0 entry point for the user-partition profile
+ * slot. Three things happen:
+ *
+ *   1. Seed `user/profile.md` on disk if missing (idempotent; never clobbers
+ *      a non-empty existing file).
+ *   2. Derive the operator-scoped PROFILE AES key via one EIP-712 sign.
+ *   3a. SANDBOX mode: POST /admin/profile-key (EIP-191-signed) so the daemon
+ *       picks up the key live + fires a one-shot restore for the slot.
+ *   3b. LOCAL mode: trigger a /sync that encrypts profile.md + anchors the
+ *       PROFILE slot on chain in the same batched updateSlots tx as the
+ *       other slots.
+ *
+ * Idempotent: re-running after the first time only re-anchors if profile.md
+ * content changed since the last flush.
+ */
+export async function runProfileInit(): Promise<void> {
+  intro('promus profile init')
+
+  note(
+    [
+      'Legacy command. v0.23.1+ folds profile-key derivation into promus init.',
+      'Run this only if your agent was created before v0.23.1.',
+    ].join('\n'),
+    'profile init (legacy)',
+  )
+
+  const loaded = await findAndLoadConfig()
+  if (!loaded) {
+    cancel('No promus config found. Run `promus init` first.')
+    return
+  }
+  const { config } = loaded
+  if (!config.identity.iNFT || !config.identity.agent) {
+    cancel('Config has no iNFT or agent. Run `promus init` first.')
+    return
+  }
+
+  const network = config.network
+  const contractAddress = config.identity.iNFT.contract as Address
+  const tokenId = BigInt(config.identity.iNFT.tokenId)
+  const agentAddress = config.identity.agent as Address
+  const finalAgentId = iNFTAgentId({ contractAddress, tokenId })
+  const paths = agentPaths.agent(finalAgentId)
+
+  // 1. seed profile.md if missing
+  const profilePath = `${paths.memoryDir}/user/profile.md`
+  await mkdir(`${paths.memoryDir}/user`, { recursive: true })
+  let seededNow = false
+  try {
+    const existing = await readFile(profilePath, 'utf8')
+    if (existing.trim().length === 0) throw new Error('empty-file')
+  } catch {
+    const template =
+      '---\nname: profile\ndescription: User profile (operator-scoped, never anchored with agent key).\ntype: user\n---\n# User profile\n\n(empty, fills as we chat)\n'
+    await writeFile(profilePath, template, 'utf8')
+    seededNow = true
+  }
+  if (seededNow) console.log(`seeded ${profilePath}`)
+
+  // 2. derive PROFILE scope key + (sandbox) keystore-decrypt or (local) full sync
+  const operator = await loadOrPickOperatorSigner({ network, hint: config.operator })
+  if (!operator) {
+    cancel('No operator wallet available.')
+    return
+  }
+
+  const sUnlock = spinner()
+  sUnlock.start('Deriving PROFILE scope key via operator')
+  let profileKey: Buffer
+  try {
+    profileKey = await deriveBlobKey(operator, agentAddress, OPERATOR_BLOB_SCOPES.PROFILE)
+    sUnlock.stop('PROFILE key derived')
+  } catch (e) {
+    sUnlock.stop(`derive failed: ${(e as Error).message.slice(0, 160)}`)
+    await operator.close?.()
+    return
+  }
+
+  // 3a. SANDBOX path: POST /admin/profile-key
+  if (config.deployTarget === 'sandbox' && config.sandbox?.endpoint && config.sandbox.id) {
+    const { SandboxClient } = await import('../sandbox/client')
+    const operatorAccount = await operator.account()
+    const client = new SandboxClient({
+      endpoint: config.sandbox.endpoint,
+      sandboxId: config.sandbox.id,
+      operator: operatorAccount,
+    })
+    const sShip = spinner()
+    sShip.start('Shipping PROFILE key to sandbox /admin/profile-key')
+    try {
+      const profileScopeKeyHex = `0x${profileKey.toString('hex')}` as `0x${string}`
+      const result = await client.setProfileKey(profileScopeKeyHex)
+      if (result.ok) {
+        sShip.stop('sandbox accepted PROFILE key')
+        outro(
+          [
+            '',
+            '  next flush will encrypt profile.md + anchor on chain',
+            '  next boot will restore the slot from chain',
+          ].join('\n'),
+        )
+      } else {
+        sShip.stop(`sandbox rejected: ${result.reason ?? 'unknown'}`)
+      }
+    } catch (e) {
+      sShip.stop(`shipment failed: ${(e as Error).message.slice(0, 200)}`)
+    }
+    await operator.close?.()
+    return
+  }
+
+  // 3b. LOCAL path: full sync with profileKey injected
+  const sUnlock2 = spinner()
+  sUnlock2.start('Fetching keystore + decrypting via operator (for local /sync)')
+  let agentPrivkey: Hex
+  try {
+    const decrypted = await withSilencedConsole(() =>
+      fetchAndDecryptKeystore({
+        network,
+        contractAddress,
+        tokenId,
+        signer: operator,
+        agentAddress,
+        cachePath: paths.keystore,
+      }),
+    )
+    agentPrivkey = decrypted.privkeyHex
+    sUnlock2.stop(`unlocked (source: ${decrypted.source})`)
+  } catch (e) {
+    sUnlock2.stop(`unlock failed: ${(e as Error).message.slice(0, 160)}`)
+    await operator.close?.()
+    return
+  }
+  await operator.close?.()
+
+  const sFlush = spinner()
+  sFlush.start('Encrypting profile.md + anchoring on chain')
+  try {
+    const res = await withSilencedConsole(async () => {
+      const sync = new MemorySyncManager({
+        network,
+        agentId: finalAgentId,
+        agentPrivkey,
+        agentAddress,
+        contractAddress,
+        tokenId,
+        profileKey,
+      })
+      await sync.init()
+      return await sync.flushAll()
+    })
+    if (res.txHash) {
+      sFlush.stop(`anchored ${res.changedSlots.length} slot(s)`)
+      outro(
+        [
+          '',
+          `  slots: ${res.changedSlots.join(', ')}`,
+          `  tx: ${explorerTxUrl(network, res.txHash)}`,
+        ].join('\n'),
+      )
+    } else {
+      sFlush.stop('nothing to anchor (profile.md unchanged since last sync)')
+    }
+  } catch (e) {
+    sFlush.stop(`flush failed: ${(e as Error).message.slice(0, 200)}`)
+  }
+}

package/src/commands/restore.ts

@@ -0,0 +1,221 @@
+import { mkdir, writeFile } from 'node:fs/promises'
+import { cancel, intro, isCancel, note, outro, password, spinner } from '@clack/prompts'
+import {
+  type EncryptedKeystore,
+  agentPaths,
+  decryptKey,
+  defineConfig,
+  explorerTokenUrl,
+  fetchAndDecryptKeystore,
+  iNFTAgentId,
+  restoreKeystoreFromStorage,
+  sniffKeystoreVersion,
+} from '@promus/core'
+import { type Address, bytesToHex } from 'viem'
+import { privateKeyToAccount } from 'viem/accounts'
+import { writeConfigTs } from '../config/render'
+import { type ParsedINFTRef, parseINFTRef } from './_inft-ref'
+import { pickOperatorSigner } from './init/operator-picker'
+
+export async function runRestore(opts: { ref: string; cwd?: string }): Promise<void> {
+  const configPath = agentPaths.config
+
+  intro('promus restore')
+
+  let parsed: ParsedINFTRef
+  try {
+    parsed = parseINFTRef(opts.ref)
+  } catch (e) {
+    cancel((e as Error).message)
+    return
+  }
+
+  const s1 = spinner()
+  s1.start(`Fetching iNFT #${parsed.tokenId} on ${parsed.network}`)
+
+  let encryptedBytes: Uint8Array
+  let operatorAddressOnChain: Address
+  try {
+    const downloaded = await restoreKeystoreFromStorage({
+      network: parsed.network,
+      contractAddress: parsed.contract,
+      tokenId: parsed.tokenId,
+    })
+    if (!downloaded) {
+      s1.stop('keystore slot is unset or predates storage-backed recovery')
+      note(
+        [
+          'This iNFT does not have an encrypted keystore uploaded to 0G Storage.',
+          'Either the slot still holds a bootstrap placeholder, or the agent was',
+          'minted before the recovery path was live. If you have a local keystore,',
+          'copy it to ~/.promus/agents/<id>/keystore.json manually.',
+        ].join('\n'),
+        'cannot restore',
+      )
+      return
+    }
+    encryptedBytes = downloaded.encryptedBytes
+    operatorAddressOnChain = downloaded.owner
+    s1.stop(`fetched ${encryptedBytes.byteLength} bytes from 0G Storage`)
+  } catch (e) {
+    s1.stop(`fetch failed: ${(e as Error).message}`)
+    return
+  }
+
+  const version = sniffKeystoreVersion(encryptedBytes)
+
+  const agentId = iNFTAgentId({ contractAddress: parsed.contract, tokenId: parsed.tokenId })
+  const paths = agentPaths.agent(agentId)
+  let privkeyHex: `0x${string}`
+  let agentAddress: Address
+
+  if (version === 1) {
+    note(
+      'Detected legacy v1 (passphrase) keystore. After restore, run `promus migrate-keystore` to upgrade to v2 (operator-wallet-encrypted).',
+      'legacy keystore',
+    )
+    const pass = await password({
+      message: 'Passphrase for the agent keystore',
+      validate: v => (v && v.length >= 1 ? undefined : 'Required.'),
+    })
+    if (isCancel(pass)) {
+      cancel('Aborted.')
+      return
+    }
+    try {
+      const ks = JSON.parse(new TextDecoder().decode(encryptedBytes)) as EncryptedKeystore
+      const privkey = decryptKey(ks, pass)
+      privkeyHex = bytesToHex(privkey)
+      agentAddress = privateKeyToAccount(privkeyHex).address
+    } catch (e) {
+      cancel(`decrypt failed: ${(e as Error).message}. Wrong passphrase or corrupted keystore.`)
+      return
+    }
+    await mkdir(paths.dir, { recursive: true })
+    await writeFile(paths.keystore, new TextDecoder().decode(encryptedBytes), 'utf8')
+  } else if (version === 2) {
+    const picked = await pickOperatorSigner({ network: parsed.network })
+    if (!picked) return
+    const operator = picked.signer
+    const pickedAddr = await operator.address()
+    if (pickedAddr.toLowerCase() !== operatorAddressOnChain.toLowerCase()) {
+      // Hard abort: decrypt is provably impossible from a different wallet,
+      // and keeping the WC session open while we ask the user to retype the
+      // agent address gives the WC event bus time to fire `chainChanged` /
+      // `accountsChanged`, which crashes universal-provider with an uncaught
+      // TypeError when the chain isn't in our config. Cancel + disconnect now.
+      await operator.close?.()
+      cancel(
+        [
+          'Operator wallet mismatch.',
+          `  iNFT owner:  ${operatorAddressOnChain}`,
+          `  you connected: ${pickedAddr}`,
+          '',
+          'You must connect the same wallet that owns this iNFT, then retry.',
+          'If the iNFT-owning key only exists in your local keystore (e.g.',
+          'macOS Keychain), import it into your mobile wallet first, or pick',
+          'a different operator source on the next run.',
+        ].join('\n'),
+      )
+      return
+    }
+
+    const sUnlock = spinner()
+    sUnlock.start('Decrypting keystore via operator wallet signature')
+    try {
+      // We don't know the agent address yet (it's encoded into the typed data).
+      // Best path: read the agent address from the iNFT's text records or
+      // attempt decrypt by trying the address derived from a successful
+      // decrypt. For MVP we ask the user since restoring on a fresh machine
+      // means they can't easily derive it.
+      sUnlock.stop('need agent address')
+      const agentAddrInput = (await password({
+        message: 'Agent EOA address (0x…) — find it on the iNFT subname or your records',
+        validate: v => {
+          if (!v) return 'Required.'
+          if (!/^0x[0-9a-fA-F]{40}$/.test(v)) return 'Must be a 20-byte hex address.'
+          return undefined
+        },
+      })) as string | symbol
+      if (isCancel(agentAddrInput)) {
+        cancel('Aborted.')
+        await operator.close?.()
+        return
+      }
+      agentAddress = agentAddrInput as Address
+
+      const sDecrypt = spinner()
+      sDecrypt.start('Sign typed data + decrypt')
+      const decrypted = await fetchAndDecryptKeystore({
+        network: parsed.network,
+        contractAddress: parsed.contract,
+        tokenId: parsed.tokenId,
+        signer: operator,
+        agentAddress,
+        cachePath: paths.keystore,
+      })
+      privkeyHex = decrypted.privkeyHex
+      const derived = privateKeyToAccount(privkeyHex).address
+      if (derived.toLowerCase() !== agentAddress.toLowerCase()) {
+        sDecrypt.stop('decrypt produced unexpected agent address')
+        cancel(
+          `Decrypted privkey points to ${derived} but you said ${agentAddress}. Aborting to prevent stale config.`,
+        )
+        await operator.close?.()
+        return
+      }
+      sDecrypt.stop(`decrypted (source: ${decrypted.source})`)
+    } catch (e) {
+      cancel(`decrypt failed: ${(e as Error).message}`)
+      await operator.close?.()
+      return
+    }
+    await operator.close?.()
+  } else {
+    cancel(`Unknown keystore version: ${version}. This blob may be corrupted.`)
+    return
+  }
+
+  const cfg = defineConfig({
+    identity: {
+      iNFT: {
+        contract: parsed.contract,
+        tokenId: parsed.tokenId.toString(),
+        network: parsed.network,
+      },
+      operator: operatorAddressOnChain,
+      agent: agentAddress,
+    },
+    network: parsed.network,
+    storage: { network: parsed.network },
+    brain: { provider: null, model: null },
+    plugins: ['onchain', 'comms', 'system'],
+    tools: {},
+    imports: { claudeCode: true },
+    operator: null,
+  })
+  await writeConfigTs(configPath, cfg, {
+    header: '// Regenerated by `promus restore`. Edit freely; type-safe.',
+    subname: null,
+  })
+
+  outro(
+    [
+      '',
+      `  agent id   ${agentId}`,
+      `  agent EOA  ${agentAddress}`,
+      `  operator   ${operatorAddressOnChain}`,
+      `  iNFT       #${parsed.tokenId.toString()} at ${parsed.contract}`,
+      `             ${explorerTokenUrl(parsed.network, parsed.contract, parsed.tokenId)}`,
+      `  config     ${configPath}`,
+      `  keystore   ${paths.keystore}`,
+      '',
+      'Next: `promus` to chat, or `promus topup --compute 5` if ledger is dry.',
+      version === 1
+        ? 'Then: `promus migrate-keystore` to upgrade to v2 (drops the passphrase).'
+        : '',
+    ]
+      .filter(Boolean)
+      .join('\n'),
+  )
+}