lyra-ai-agent 0.1.1 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lyra-ai-agent",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "description": "lyra CLI: a Sui-native, policy-bound AI finance agent. Real on-chain work gated by deterministic policy, simulation, and approval",
   "license": "MIT",
@@ -50,11 +50,11 @@
     "@mysten/sui": "^1.45.2",
     "@opentui/core": "^0.1.97",
     "@opentui/solid": "^0.1.97",
-    "lyra-core": "^0.1.1",
-    "lyra-gateway": "^0.1.1",
-    "lyra-plugin-onchain": "^0.1.1",
-    "lyra-plugin-system": "^0.1.1",
-    "lyra-plugin-telegram": "^0.1.1",
+    "lyra-core": "^0.1.2",
+    "lyra-gateway": "^0.1.2",
+    "lyra-plugin-onchain": "^0.1.2",
+    "lyra-plugin-system": "^0.1.2",
+    "lyra-plugin-telegram": "^0.1.2",
     "picocolors": "^1.1.1",
     "qrcode-terminal": "^0.12.0",
     "solid-js": "^1.9.12"

package/src/commands/chat.tsx

@@ -55,10 +55,11 @@ import {
   type TelegramRuntimeContext,
   formatInboundPreview as formatTelegramInboundPreview,
 } from 'lyra-plugin-telegram'
+import { DEFAULT_LLM_MODEL, resolveLlmBaseUrl } from '../config/defaults'
 import { findAndLoadConfig } from '../config/load'
 import { writeConfigTs } from '../config/render'
 import { shortAddr } from '../util/format'
-import { buildOnchainContext, loadAgentFromEnv } from '../util/sui-runtime'
+import { buildOnchainContext, loadAgent } from '../util/sui-runtime'
 import {
   type TelegramDispatchSlot,
   buildTelegramDispatch,
@@ -78,9 +79,9 @@ export async function runChat(opts?: { cwd?: string; yolo?: boolean }): Promise<
   // `LYRA_AGENT_KEY` env (`suiprivkey1…`). No operator wallet, keystore
   // decrypt, or a Sui wallet dance. The deterministic policy (mirrored
   // on-chain by `lyra::policy`) bounds what the key may do.
-  const agent = loadAgentFromEnv()
+  const agent = loadAgent()
   if (!agent) {
-    console.log('No LYRA_AGENT_KEY set. Run `lyra init` first (or export a suiprivkey1… key).')
+    console.log('No agent key found. Run `lyra init` first (or export a suiprivkey1… key).')
     process.exit(1)
   }
   const agentAddress = agent.address
@@ -160,8 +161,11 @@ export async function runChat(opts?: { cwd?: string; yolo?: boolean }): Promise<
   const userLlmKey = process.env.OPENAI_API_KEY ?? process.env.LYRA_LLM_API_KEY
   // No personal key set → fall back to the hosted demo proxy so lyra runs keyless.
   const llmApiKey = userLlmKey ?? DEMO_LLM_TOKEN
-  const llmBaseUrl = process.env.LYRA_LLM_BASE_URL ?? (userLlmKey ? undefined : DEMO_LLM_BASE_URL)
-  const llmModel = process.env.LYRA_LLM_MODEL ?? config.brain?.model ?? 'gpt-4o-mini'
+  // With a personal key, default to the OpenAI endpoint; keyless uses the demo proxy.
+  const llmBaseUrl = userLlmKey
+    ? resolveLlmBaseUrl()
+    : (process.env.LYRA_LLM_BASE_URL ?? DEMO_LLM_BASE_URL)
+  const llmModel = process.env.LYRA_LLM_MODEL ?? config.brain?.model ?? DEFAULT_LLM_MODEL
 
   // Sub-brain factory for delegate.task (Phase 9.3). The factory creates a
   // fresh OpenAIBrain with a custom system prompt. Tools default to none for
@@ -1086,7 +1090,7 @@ export async function runChat(opts?: { cwd?: string; yolo?: boolean }): Promise<
 
 async function runModelPicker(config: LyraConfig, configPath: string): Promise<LyraConfig | null> {
   // Lyra uses a fixed OpenAI-compatible model (env-configured); no live catalog.
-  const model = process.env.LYRA_LLM_MODEL ?? config.brain?.model ?? 'gpt-4o-mini'
+  const model = process.env.LYRA_LLM_MODEL ?? config.brain?.model ?? DEFAULT_LLM_MODEL
   const updated: LyraConfig = {
     ...config,
     brain: { provider: 'openai-compatible', model },

package/src/commands/demo.ts

@@ -25,7 +25,7 @@ import onchainPlugin, {
   suiToMist,
 } from 'lyra-plugin-onchain'
 import { findAndLoadConfig } from '../config/load'
-import { buildOnchainContext, loadAgentFromEnv } from '../util/sui-runtime'
+import { buildOnchainContext, loadAgent } from '../util/sui-runtime'
 
 const SUI_TYPE = '0x2::sui::SUI'
 
@@ -60,9 +60,9 @@ export async function runDemo(opts: DemoOpts = {}): Promise<void> {
   }
   const { config } = found
 
-  const agent = loadAgentFromEnv()
+  const agent = loadAgent()
   if (!agent) {
-    console.log('No LYRA_AGENT_KEY set. Run `lyra init` first.')
+    console.log('No agent key found. Run `lyra init` first.')
     process.exit(1)
   }
 

package/src/commands/init/model-picker.ts

@@ -1,3 +1,5 @@
+import { DEFAULT_LLM_MODEL } from '../../config/defaults'
+
 export interface ModelPick {
   provider: string
   model: string | null
@@ -12,6 +14,6 @@ export interface ModelPick {
 export async function pickBrainModel(): Promise<ModelPick | null> {
   return {
     provider: 'openai-compatible',
-    model: process.env.LYRA_LLM_MODEL ?? 'gpt-4o-mini',
+    model: process.env.LYRA_LLM_MODEL ?? DEFAULT_LLM_MODEL,
   }
 }

package/src/commands/init.ts

@@ -1,7 +1,8 @@
 import { existsSync } from 'node:fs'
 import { mkdir, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
-import { cancel, intro, isCancel, outro, select } from '@clack/prompts'
+import { cancel, intro, isCancel, outro, password, select } from '@clack/prompts'
+import { Ed25519Keypair } from '@mysten/sui/keypairs/ed25519'
 import {
   type LyraNetwork,
   agentPaths,
@@ -9,24 +10,44 @@ import {
   placeholderAgentId,
   suiRpcUrl,
 } from 'lyra-core'
+import { keypairFromSecret } from 'lyra-plugin-onchain'
+import { DEFAULT_NETWORK, resolvePackageId } from '../config/defaults'
 import { writeConfigTs } from '../config/render'
-import { AGENT_KEY_ENV, loadAgentFromEnv } from '../util/sui-runtime'
+import { setDotenvVar } from '../util/dotenv'
+import { type SuiAgent, loadAgent, writeAgentKey } from '../util/sui-runtime'
 import { pickBrainModel } from './init/model-picker'
+import { deviceLink, resolveWebBase } from './login'
 
 /**
- * `lyra init` — bootstrap the agent config for Sui.
+ * `lyra init` — bootstrap the agent for Sui with ZERO env vars.
  *
- * On Sui there is no operator wallet, keystore, or funding step. The agent IS
- * the signer: one Ed25519 keypair, supplied via the `LYRA_AGENT_KEY` env var
- * (`suiprivkey1…`). init resolves that key, derives the agent's Sui address,
- * writes `~/.lyra/config.ts`, and seeds the starter memory files.
+ * The user answers ~1 prompt and the CLI works:
+ *   1. LLM key — reuse OPENAI_API_KEY if set, else prompt + persist to
+ *      `~/.lyra/.env` (mode 0600).
+ *   2. Agent — "Create new" (generate a fresh Ed25519 key, written to
+ *      `~/.lyra/agent.key`) OR "Login with web" (device-link to lyraai.space →
+ *      the SAME agent as the web wallet).
+ *   3. Config — network + package id defaults written to `~/.lyra/config.ts`.
+ *
+ * Non-interactive safe: when stdin is not a TTY, or `--yes` / `--new` is passed,
+ * prompts are skipped and init defaults to "Create new" using env-provided keys.
  */
-export async function runInit(opts?: { resume?: boolean }): Promise<void> {
+export interface InitOpts {
+  resume?: boolean
+  /** Skip all prompts; default to "Create new" (CI / non-TTY). */
+  yes?: boolean
+  /** Force "Create new" even in a TTY (skip the create/login choice). */
+  new?: boolean
+}
+
+export async function runInit(opts?: InitOpts): Promise<void> {
   const configPath = agentPaths.config
+  const interactive = !!process.stdin.isTTY && !opts?.yes
+  const forceNew = !!opts?.new || !interactive
 
   intro('lyra init')
 
-  if (existsSync(configPath) && !opts?.resume) {
+  if (existsSync(configPath) && !opts?.resume && interactive) {
     const choice = (await select({
       message: `${configPath} exists`,
       options: [
@@ -41,28 +62,97 @@ export async function runInit(opts?: { resume?: boolean }): Promise<void> {
     }
   }
 
-  // The agent key is sourced from the environment (never prompted/stored on
-  // disk). If it is missing we cannot derive the Sui address, so bail with a
-  // clear instruction.
-  const agent = loadAgentFromEnv()
-  if (!agent) {
-    cancel(
-      `No ${AGENT_KEY_ENV} set. Export your agent's Sui secret key first, e.g.\n  export ${AGENT_KEY_ENV}=suiprivkey1...\nThen re-run \`lyra init\`.`,
-    )
-    return
+  // 1) LLM key. Reuse OPENAI_API_KEY if present; else prompt + persist so the
+  //    CLI runs keyless next time. In non-interactive mode we just use whatever
+  //    the env provides (the CLI falls back to the hosted demo proxy if unset).
+  if (interactive && !process.env.OPENAI_API_KEY && !process.env.LYRA_LLM_API_KEY) {
+    const key = await password({
+      message: 'OpenAI API key (sk-…) — leave blank to use the hosted demo proxy',
+    })
+    if (isCancel(key)) {
+      cancel('Aborted.')
+      return
+    }
+    const trimmed = (key ?? '').toString().trim()
+    if (trimmed) {
+      const envPath = setDotenvVar('OPENAI_API_KEY', trimmed)
+      console.log(`  saved OPENAI_API_KEY → ${envPath}`)
+    }
+  }
+
+  // 2) Agent: create new (default) or login with web.
+  let agent: SuiAgent
+  let linkedOwner: string | null = null
+
+  let mode: 'create' | 'login' = 'create'
+  if (!forceNew) {
+    const picked = (await select({
+      message: 'How do you want your agent?',
+      options: [
+        {
+          value: 'create',
+          label: 'Create new — generate a fresh agent, you hold the key',
+        },
+        {
+          value: 'login',
+          label: 'Login with web — use the same agent as lyraai.space',
+        },
+      ],
+      initialValue: 'create',
+    })) as 'create' | 'login' | symbol
+    if (isCancel(picked)) {
+      cancel('Aborted.')
+      return
+    }
+    mode = picked
+  }
+
+  if (mode === 'login') {
+    try {
+      const result = await deviceLink({
+        base: resolveWebBase(),
+        fetchImpl: fetch,
+        sleep: (ms: number) => new Promise(r => setTimeout(r, ms)),
+        log: (m: string) => console.log(m),
+      })
+      linkedOwner = result.owner
+      // writeAgentKey already ran inside deviceLink; reload from disk.
+      const loaded = loadAgent()
+      if (!loaded) throw new Error('agent key was not written after login')
+      agent = loaded
+      console.log('')
+      console.log(`✓ Linked agent ${result.address} (same as your web wallet)`)
+    } catch (e) {
+      cancel(`Login failed: ${(e as Error).message}`)
+      return
+    }
+  } else {
+    // Create new: generate a fresh Ed25519 agent and persist the secret.
+    const kp = new Ed25519Keypair()
+    const secret = kp.getSecretKey()
+    const keyPath = writeAgentKey(secret)
+    agent = { keypair: keypairFromSecret(secret), address: kp.toSuiAddress() }
+    console.log('')
+    console.log(`✓ Created agent ${agent.address}`)
+    console.log(`  key  ${keyPath} (mode 0600 — back this up; it controls funds)`)
   }
 
-  const network = (await select({
-    message: 'Which Sui network?',
-    options: [
-      { value: 'mainnet' as LyraNetwork, label: 'Sui mainnet' },
-      { value: 'testnet' as LyraNetwork, label: 'Sui testnet' },
-    ],
-    initialValue: 'mainnet' as LyraNetwork,
-  })) as LyraNetwork
-  if (isCancel(network)) {
-    cancel('Aborted.')
-    return
+  // 3) Network. Skip the prompt when non-interactive (default mainnet).
+  let network: LyraNetwork = DEFAULT_NETWORK
+  if (interactive) {
+    const picked = (await select({
+      message: 'Which Sui network?',
+      options: [
+        { value: 'mainnet' as LyraNetwork, label: 'Sui mainnet' },
+        { value: 'testnet' as LyraNetwork, label: 'Sui testnet' },
+      ],
+      initialValue: DEFAULT_NETWORK as LyraNetwork,
+    })) as LyraNetwork | symbol
+    if (isCancel(picked)) {
+      cancel('Aborted.')
+      return
+    }
+    network = picked
   }
 
   const modelPick = await pickBrainModel()
@@ -85,7 +175,7 @@ export async function runInit(opts?: { resume?: boolean }): Promise<void> {
 
   const cfg = defineConfig({
     identity: {
-      operator: null,
+      operator: linkedOwner,
       agent: agent.address,
     },
     network,
@@ -102,15 +192,17 @@ export async function runInit(opts?: { resume?: boolean }): Promise<void> {
     header: '// Regenerated by `lyra init`. Edit freely; type-safe.',
   })
 
-  const packageId = process.env.LYRA_PACKAGE_ID
+  const packageId = resolvePackageId()
   const lines = [
     '',
     `  agent id    ${agentId}`,
     `  agent addr  ${agent.address}`,
+    linkedOwner ? `  owner       ${linkedOwner} (linked from web)` : '',
     `  network     ${network} (${suiRpcUrl(network)})`,
     `  config      ${configPath}`,
-    `  policy pkg  ${packageId ?? '(set LYRA_PACKAGE_ID for on-chain receipts)'}`,
-  ]
+    `  agent key   ${agentPaths.agentKey}`,
+    `  policy pkg  ${packageId}`,
+  ].filter(Boolean)
   if (modelPick) lines.push(`  brain       ${modelPick.model ?? '?'} (${modelPick.provider})`)
   if (telegramEnabled) lines.push('  telegram    enabled (TELEGRAM_BOT_TOKEN set)')
   lines.push(

package/src/commands/login.test.ts

@@ -0,0 +1,104 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { mkdtempSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { Ed25519Keypair } from '@mysten/sui/keypairs/ed25519'
+import { type LoginDeps, deviceLink, resolveWebBase } from './login'
+
+// Isolate the agent dir so writeAgentKey() (called on approval) doesn't touch
+// the real ~/.lyra.
+let prevRoot: string | undefined
+beforeEach(() => {
+  prevRoot = process.env.LYRA_ROOT
+  process.env.LYRA_ROOT = mkdtempSync(join(tmpdir(), 'lyra-login-'))
+})
+afterEach(() => {
+  if (prevRoot === undefined) Reflect.deleteProperty(process.env, 'LYRA_ROOT')
+  else process.env.LYRA_ROOT = prevRoot
+})
+
+/** Build a mock fetch over a scripted sequence of poll responses. */
+function mockFetch(start: unknown, polls: unknown[]): { fetchImpl: typeof fetch; calls: string[] } {
+  const calls: string[] = []
+  let pollIdx = 0
+  const fetchImpl = (async (url: string | URL | Request) => {
+    const u = String(url)
+    calls.push(u)
+    if (u.includes('/api/cli/login/start')) {
+      return new Response(JSON.stringify(start), { status: 200 })
+    }
+    if (u.includes('/api/cli/login/poll')) {
+      const body = polls[Math.min(pollIdx, polls.length - 1)]
+      pollIdx += 1
+      return new Response(JSON.stringify(body), { status: 200 })
+    }
+    return new Response('not found', { status: 404 })
+  }) as unknown as typeof fetch
+  return { fetchImpl, calls }
+}
+
+const baseDeps = (fetchImpl: typeof fetch): LoginDeps => ({
+  base: 'https://example.test',
+  fetchImpl,
+  sleep: async () => {},
+  log: () => {},
+  openBrowser: () => {},
+})
+
+describe('resolveWebBase', () => {
+  test('defaults to lyraai.space, env override wins', () => {
+    expect(resolveWebBase({})).toBe('https://lyraai.space')
+    expect(resolveWebBase({ LYRA_WEB_URL: 'http://localhost:3000' })).toBe('http://localhost:3000')
+  })
+})
+
+describe('deviceLink contract', () => {
+  test('calls start then poll, writes key on approved, returns address', async () => {
+    const kp = new Ed25519Keypair()
+    const agentKey = kp.getSecretKey()
+    const owner = `0x${'a'.repeat(64)}`
+    const { fetchImpl, calls } = mockFetch(
+      { code: 'ABCD', pollToken: 'tok-1', verifyUrl: 'https://example.test/cli', expiresInSec: 60 },
+      [{ status: 'pending' }, { status: 'approved', owner, agentKey }],
+    )
+    const res = await deviceLink(baseDeps(fetchImpl))
+    expect(res.owner).toBe(owner)
+    expect(res.address).toBe(kp.toSuiAddress())
+    // start first, then at least two polls.
+    expect(calls[0]).toContain('/api/cli/login/start')
+    expect(calls[1]).toContain('/api/cli/login/poll?pollToken=tok-1')
+    expect(calls.length).toBeGreaterThanOrEqual(3)
+  })
+
+  test('throws a friendly error on expired', async () => {
+    const { fetchImpl } = mockFetch(
+      { code: 'X', pollToken: 't', verifyUrl: 'https://example.test/cli', expiresInSec: 60 },
+      [{ status: 'expired' }],
+    )
+    await expect(deviceLink(baseDeps(fetchImpl))).rejects.toThrow(/expired/i)
+  })
+
+  test('throws on not_found', async () => {
+    const { fetchImpl } = mockFetch(
+      { code: 'X', pollToken: 't', verifyUrl: 'https://example.test/cli', expiresInSec: 60 },
+      [{ status: 'not_found' }],
+    )
+    await expect(deviceLink(baseDeps(fetchImpl))).rejects.toThrow(/not found/i)
+  })
+
+  test('times out when expiresInSec elapses without approval', async () => {
+    const { fetchImpl } = mockFetch(
+      { code: 'X', pollToken: 't', verifyUrl: 'https://example.test/cli', expiresInSec: 4 },
+      [{ status: 'pending' }],
+    )
+    // Advancing clock: each read jumps 1s, so a 4s window closes after a few
+    // polls without ever hitting the wall clock.
+    let t = 0
+    const now = (): number => {
+      t += 1000
+      return t
+    }
+    const deps: LoginDeps = { ...baseDeps(fetchImpl), now }
+    await expect(deviceLink(deps)).rejects.toThrow(/timed out/i)
+  })
+})

package/src/commands/login.ts

@@ -0,0 +1,156 @@
+/**
+ * `lyra login` — device-link the CLI to the same agent your web wallet
+ * controls on lyraai.space.
+ *
+ * Flow (matches the web server contract exactly):
+ *   1. POST {base}/api/cli/login/start  → { code, pollToken, verifyUrl, expiresInSec }
+ *   2. Show the user the verify URL + code; best-effort open the browser.
+ *   3. Poll GET {base}/api/cli/login/poll?pollToken=… every 2s until expiry.
+ *      → { status:'pending' } keep waiting
+ *      → { status:'approved', owner, agentKey } write the key, done
+ *      → { status:'expired' | 'not_found' } friendly error, exit non-zero.
+ *
+ * The approved `agentKey` is a `suiprivkey1…` string — the SAME secret the web
+ * derives for that owner — so the CLI and the web operate one identical agent.
+ */
+
+import { keypairFromSecret } from 'lyra-plugin-onchain'
+import { writeAgentKey } from '../util/sui-runtime'
+
+/** Default web origin; override with LYRA_WEB_URL for local/staging testing. */
+const DEFAULT_WEB_URL = 'https://lyraai.space'
+const POLL_INTERVAL_MS = 2000
+
+export interface LoginStart {
+  code: string
+  pollToken: string
+  verifyUrl: string
+  expiresInSec: number
+}
+
+export type LoginPoll =
+  | { status: 'pending' }
+  | { status: 'approved'; owner: string; agentKey: string }
+  | { status: 'expired' }
+  | { status: 'not_found' }
+
+export interface LoginResult {
+  owner: string
+  address: string
+  keyPath: string
+}
+
+export interface LoginDeps {
+  base: string
+  fetchImpl: typeof fetch
+  /** Sleep between polls (injectable so tests run instantly). */
+  sleep: (ms: number) => Promise<void>
+  /** Monotonic clock (injectable so timeout tests are deterministic). */
+  now?: () => number
+  log: (msg: string) => void
+  openBrowser?: (url: string) => void
+}
+
+const sleep = (ms: number): Promise<void> => new Promise(r => setTimeout(r, ms))
+
+/** Best-effort: open `url` in the user's default browser. Never throws. */
+function openBrowserBestEffort(url: string): void {
+  try {
+    const platform = process.platform
+    const cmd = platform === 'darwin' ? 'open' : platform === 'win32' ? 'start' : 'xdg-open'
+    // Lazy import so the happy path / tests don't pull in child_process.
+    const { spawn } = require('node:child_process') as typeof import('node:child_process')
+    const child = spawn(cmd, [url], { stdio: 'ignore', detached: true })
+    child.on('error', () => {})
+    child.unref()
+  } catch {
+    // Headless / no browser — the printed URL is the fallback.
+  }
+}
+
+/**
+ * Core device-link logic, dependency-injected so tests never hit the network.
+ * Resolves with the linked agent or throws a friendly Error on
+ * expiry/timeout/not_found.
+ */
+export async function deviceLink(deps: LoginDeps): Promise<LoginResult> {
+  const { base, fetchImpl, log } = deps
+
+  const startRes = await fetchImpl(`${base}/api/cli/login/start`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: '{}',
+  })
+  if (!startRes.ok) {
+    throw new Error(`login/start failed (HTTP ${startRes.status}) at ${base}`)
+  }
+  const start = (await startRes.json()) as LoginStart
+  if (!start?.code || !start?.pollToken || !start?.verifyUrl) {
+    throw new Error('login/start returned an unexpected response')
+  }
+
+  const linkUrl = `${start.verifyUrl}?code=${encodeURIComponent(start.code)}`
+  log('')
+  log('Approve this login in your browser:')
+  log(`  ${linkUrl}`)
+  log(`  (or enter code: ${start.code})`)
+  log('')
+  log('Waiting for approval…')
+  ;(deps.openBrowser ?? openBrowserBestEffort)(linkUrl)
+
+  const now = deps.now ?? Date.now
+  const expiresInSec = start.expiresInSec > 0 ? start.expiresInSec : 300
+  const deadline = now() + expiresInSec * 1000
+
+  while (now() < deadline) {
+    await deps.sleep(POLL_INTERVAL_MS)
+    const pollRes = await fetchImpl(
+      `${base}/api/cli/login/poll?pollToken=${encodeURIComponent(start.pollToken)}`,
+    )
+    if (!pollRes.ok) {
+      // Transient server hiccup — keep polling until the deadline.
+      continue
+    }
+    const poll = (await pollRes.json()) as LoginPoll
+    if (poll.status === 'approved') {
+      const keyPath = writeAgentKey(poll.agentKey)
+      const address = keypairFromSecret(poll.agentKey).toSuiAddress()
+      return { owner: poll.owner, address, keyPath }
+    }
+    if (poll.status === 'expired') {
+      throw new Error('Login request expired. Re-run `lyra login` and approve faster.')
+    }
+    if (poll.status === 'not_found') {
+      throw new Error('Login request not found (already used or invalid). Re-run `lyra login`.')
+    }
+    // pending → keep waiting.
+  }
+  throw new Error('Login timed out before approval. Re-run `lyra login`.')
+}
+
+/** Resolve the web base URL (env override → default). */
+export function resolveWebBase(env: NodeJS.ProcessEnv = process.env): string {
+  return env.LYRA_WEB_URL ?? DEFAULT_WEB_URL
+}
+
+/** Entry point for `lyra login`. Exits non-zero on failure. */
+export async function runLogin(): Promise<void> {
+  const base = resolveWebBase()
+  try {
+    const result = await deviceLink({
+      base,
+      fetchImpl: fetch,
+      sleep,
+      log: (m: string) => console.log(m),
+    })
+    console.log('')
+    console.log(`✓ Linked agent ${result.address} (same as your web wallet)`)
+    console.log(`  owner ${result.owner}`)
+    console.log(`  key   ${result.keyPath}`)
+    console.log('')
+    console.log('Next: `lyra` to chat · `lyra status` for health')
+  } catch (e) {
+    console.error(`lyra login: ${(e as Error).message}`)
+    process.exit(1)
+  }
+}

package/src/commands/status.ts

@@ -1,8 +1,9 @@
 import { existsSync, statSync } from 'node:fs'
 import { agentPaths, formatSui, getSuiBalanceMist, makeSuiClient, suiRpcUrl } from 'lyra-core'
 import { type SuiPolicy, policyFromEnv } from 'lyra-plugin-onchain'
+import { resolvePackageId, resolvePolicyEnv } from '../config/defaults'
 import { findAndLoadConfig } from '../config/load'
-import { loadAgentFromEnv } from '../util/sui-runtime'
+import { loadAgent } from '../util/sui-runtime'
 import { listAgentIds } from './_agents'
 
 export async function runStatus(opts?: { cwd?: string }): Promise<void> {
@@ -14,8 +15,8 @@ export async function runStatus(opts?: { cwd?: string }): Promise<void> {
   }
   const { config, path } = found
 
-  const agent = loadAgentFromEnv()
-  const agentAddress = agent?.address ?? config.identity.agent ?? '(no LYRA_AGENT_KEY)'
+  const agent = loadAgent()
+  const agentAddress = agent?.address ?? config.identity.agent ?? '(no agent key — run `lyra init`)'
 
   console.log(`config    ${path}`)
   console.log(`network   ${config.network}`)
@@ -25,11 +26,11 @@ export async function runStatus(opts?: { cwd?: string }): Promise<void> {
   console.log(`brain     ${config.brain.provider ?? '(not picked)'}`)
 
   // lyra::policy package + active deterministic policy summary.
-  const packageId = process.env.LYRA_PACKAGE_ID
-  console.log(`policy pkg ${packageId ?? '(LYRA_PACKAGE_ID unset)'}`)
+  const packageId = resolvePackageId()
+  console.log(`policy pkg ${packageId}`)
   const policyObjectId = process.env.LYRA_POLICY_OBJECT_ID
   if (policyObjectId) console.log(`policy obj ${policyObjectId}`)
-  const policy = policyFromEnv()
+  const policy = policyFromEnv(resolvePolicyEnv())
   if (policy) {
     console.log(`policy     ${summarizePolicy(policy)}`)
   } else {

package/src/commands/whoami.ts

@@ -8,12 +8,8 @@
  * on CLI), but they all resolve to the same agent.
  */
 
-import {
-  type SuiNetwork,
-  deriveAgentAddress,
-  makeSuiClient,
-  resolveOwnerVault,
-} from 'lyra-plugin-onchain'
+import { deriveAgentAddress, makeSuiClient, resolveOwnerVault } from 'lyra-plugin-onchain'
+import { resolveNetwork } from '../config/defaults'
 
 export async function runWhoami(opts: { owner?: string }): Promise<void> {
   const owner = opts.owner ?? process.env.LYRA_OWNER_ADDRESS
@@ -30,7 +26,7 @@ export async function runWhoami(opts: { owner?: string }): Promise<void> {
     process.exit(1)
     return
   }
-  const network = (process.env.LYRA_NETWORK as SuiNetwork) ?? 'mainnet'
+  const network = resolveNetwork()
   const client = makeSuiClient(network)
   const [bal, ov] = await Promise.all([
     client.getBalance({ owner: agent }).catch(() => null),

package/src/config/defaults.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, test } from 'bun:test'
+import {
+  DEFAULT_ALLOWED_COINS,
+  DEFAULT_ALLOWED_PROTOCOLS,
+  DEFAULT_AUTO_MAX_SUI,
+  DEFAULT_LLM_BASE_URL,
+  DEFAULT_LLM_MODEL,
+  DEFAULT_MAX_PER_TX_SUI,
+  DEFAULT_MAX_SLIPPAGE_BPS,
+  DEFAULT_NETWORK,
+  DEFAULT_PACKAGE_ID,
+  defaultPolicyEnv,
+  hasNoPolicyEnv,
+  resolveLlmBaseUrl,
+  resolveLlmModel,
+  resolveNetwork,
+  resolvePackageId,
+  resolvePolicyEnv,
+} from './defaults'
+
+describe('config defaults (zero-env-var)', () => {
+  test('exported constant values match the shared contract', () => {
+    expect(DEFAULT_PACKAGE_ID).toBe(
+      '0x8e984145d636037cebf5c402ac4b338567411ba6dd275948d7ff593b1ed01a04',
+    )
+    expect(DEFAULT_NETWORK).toBe('mainnet')
+    expect(DEFAULT_LLM_BASE_URL).toBe('https://api.openai.com/v1')
+    expect(DEFAULT_LLM_MODEL).toBe('gpt-4o-mini')
+    expect(DEFAULT_MAX_PER_TX_SUI).toBe(1)
+    expect(DEFAULT_AUTO_MAX_SUI).toBe(0.1)
+    expect(DEFAULT_MAX_SLIPPAGE_BPS).toBe(100)
+    expect(DEFAULT_ALLOWED_COINS).toEqual(['0x2::sui::SUI'])
+    expect(DEFAULT_ALLOWED_PROTOCOLS).toEqual([
+      'transfer',
+      'swap',
+      'deepbook',
+      'scallop',
+      'navi',
+      'walrus',
+    ])
+  })
+
+  test('resolvePackageId: default when env unset, env wins when set', () => {
+    expect(resolvePackageId({})).toBe(DEFAULT_PACKAGE_ID)
+    expect(resolvePackageId({ LYRA_PACKAGE_ID: '0xabc' })).toBe('0xabc')
+    // Blank/whitespace env falls back to the default.
+    expect(resolvePackageId({ LYRA_PACKAGE_ID: '   ' })).toBe(DEFAULT_PACKAGE_ID)
+  })
+
+  test('resolveNetwork: default mainnet, env override, ignores garbage', () => {
+    expect(resolveNetwork({})).toBe('mainnet')
+    expect(resolveNetwork({ LYRA_NETWORK: 'testnet' })).toBe('testnet')
+    expect(resolveNetwork({ LYRA_NETWORK: 'devnet' })).toBe('mainnet')
+  })
+
+  test('resolveLlmBaseUrl / resolveLlmModel: default then env override', () => {
+    expect(resolveLlmBaseUrl({})).toBe(DEFAULT_LLM_BASE_URL)
+    expect(resolveLlmBaseUrl({ LYRA_LLM_BASE_URL: 'https://gw' })).toBe('https://gw')
+    expect(resolveLlmModel({})).toBe(DEFAULT_LLM_MODEL)
+    expect(resolveLlmModel({ LYRA_LLM_MODEL: 'gpt-4o' })).toBe('gpt-4o')
+  })
+
+  test('defaultPolicyEnv produces a bounded LYRA_POLICY_* record', () => {
+    const env = defaultPolicyEnv()
+    expect(env.LYRA_POLICY_MAX_PER_TX_SUI).toBe('1')
+    expect(env.LYRA_POLICY_AUTO_MAX_SUI).toBe('0.1')
+    expect(env.LYRA_POLICY_MAX_SLIPPAGE_BPS).toBe('100')
+    expect(env.LYRA_POLICY_ALLOWED_COINS).toBe('0x2::sui::SUI')
+    expect(env.LYRA_POLICY_ALLOWED_PROTOCOLS).toBe('transfer,swap,deepbook,scallop,navi,walrus')
+  })
+
+  test('hasNoPolicyEnv: true with no policy vars, false when any set', () => {
+    expect(hasNoPolicyEnv({})).toBe(true)
+    expect(hasNoPolicyEnv({ OPENAI_API_KEY: 'x' })).toBe(true)
+    expect(hasNoPolicyEnv({ LYRA_POLICY_MAX_PER_TX_SUI: '5' })).toBe(false)
+  })
+
+  test('resolvePolicyEnv: seeds defaults only when no policy var is set', () => {
+    // No policy env → defaults applied.
+    const seeded = resolvePolicyEnv({})
+    expect(seeded.LYRA_POLICY_MAX_PER_TX_SUI).toBe('1')
+    expect(seeded.LYRA_POLICY_ALLOWED_PROTOCOLS).toContain('deepbook')
+
+    // Any policy env present → caller's env passed through untouched (no merge).
+    const userEnv = { LYRA_POLICY_MAX_PER_TX_SUI: '5' }
+    const passed = resolvePolicyEnv(userEnv)
+    expect(passed.LYRA_POLICY_MAX_PER_TX_SUI).toBe('5')
+    expect(passed.LYRA_POLICY_ALLOWED_PROTOCOLS).toBeUndefined()
+  })
+})

package/src/config/defaults.ts

@@ -0,0 +1,88 @@
+/**
+ * Zero-env-var defaults for the Lyra CLI.
+ *
+ * The whole point of `lyra init` is that a fresh user runs ONE prompt and the
+ * CLI works with no env vars. Every value here is the fallback used when the
+ * corresponding `LYRA_*` / `OPENAI_*` env var is unset. Env still WINS when set
+ * — these are last-resort defaults, never overrides.
+ */
+
+/** Deployed `lyra::policy` Move package on mainnet (on-chain receipts). */
+export const DEFAULT_PACKAGE_ID =
+  '0x8e984145d636037cebf5c402ac4b338567411ba6dd275948d7ff593b1ed01a04'
+
+/** Default Sui network. */
+export const DEFAULT_NETWORK = 'mainnet' as const
+
+/** Default OpenAI-compatible LLM endpoint + model. */
+export const DEFAULT_LLM_BASE_URL = 'https://api.openai.com/v1'
+export const DEFAULT_LLM_MODEL = 'gpt-4o-mini'
+
+/** Default deterministic policy bounds (mirrored on-chain by `lyra::policy`). */
+export const DEFAULT_MAX_PER_TX_SUI = 1
+export const DEFAULT_AUTO_MAX_SUI = 0.1
+export const DEFAULT_MAX_SLIPPAGE_BPS = 100
+export const DEFAULT_ALLOWED_COINS = ['0x2::sui::SUI']
+export const DEFAULT_ALLOWED_PROTOCOLS = [
+  'transfer',
+  'swap',
+  'deepbook',
+  'scallop',
+  'navi',
+  'walrus',
+]
+
+/**
+ * Resolve the package id: env override first, then the deployed default. Always
+ * returns a concrete id so on-chain receipts work with zero config.
+ */
+export function resolvePackageId(env: NodeJS.ProcessEnv = process.env): string {
+  const fromEnv = env.LYRA_PACKAGE_ID
+  return fromEnv && fromEnv.trim().length > 0 ? fromEnv.trim() : DEFAULT_PACKAGE_ID
+}
+
+/** Resolve the network: env override first, then `mainnet`. */
+export function resolveNetwork(env: NodeJS.ProcessEnv = process.env): 'mainnet' | 'testnet' {
+  const fromEnv = env.LYRA_NETWORK
+  return fromEnv === 'testnet' || fromEnv === 'mainnet' ? fromEnv : DEFAULT_NETWORK
+}
+
+/** Resolve the LLM base URL: env override first, then the OpenAI endpoint. */
+export function resolveLlmBaseUrl(env: NodeJS.ProcessEnv = process.env): string {
+  return env.LYRA_LLM_BASE_URL ?? DEFAULT_LLM_BASE_URL
+}
+
+/** Resolve the LLM model: env override first, then `gpt-4o-mini`. */
+export function resolveLlmModel(env: NodeJS.ProcessEnv = process.env): string {
+  return env.LYRA_LLM_MODEL ?? DEFAULT_LLM_MODEL
+}
+
+/**
+ * Build a `LYRA_POLICY_*`-shaped env record from the defaults, used only to seed
+ * `policyFromEnv` when the user has not set ANY `LYRA_POLICY_*` var. This keeps
+ * the agent bounded out of the box (never an unbounded auto-spender).
+ */
+export function defaultPolicyEnv(): Record<string, string> {
+  return {
+    LYRA_POLICY_MAX_PER_TX_SUI: String(DEFAULT_MAX_PER_TX_SUI),
+    LYRA_POLICY_AUTO_MAX_SUI: String(DEFAULT_AUTO_MAX_SUI),
+    LYRA_POLICY_MAX_SLIPPAGE_BPS: String(DEFAULT_MAX_SLIPPAGE_BPS),
+    LYRA_POLICY_ALLOWED_COINS: DEFAULT_ALLOWED_COINS.join(','),
+    LYRA_POLICY_ALLOWED_PROTOCOLS: DEFAULT_ALLOWED_PROTOCOLS.join(','),
+  }
+}
+
+/** True when the user set no `LYRA_POLICY_*` var (so defaults should apply). */
+export function hasNoPolicyEnv(env: NodeJS.ProcessEnv = process.env): boolean {
+  return !Object.keys(env).some(k => k.startsWith('LYRA_POLICY_'))
+}
+
+/**
+ * Resolve the deterministic policy env: the user's `LYRA_POLICY_*` vars if ANY
+ * are set, otherwise the bounded defaults. Pass the result to `policyFromEnv`.
+ */
+export function resolvePolicyEnv(
+  env: NodeJS.ProcessEnv = process.env,
+): Record<string, string | undefined> {
+  return hasNoPolicyEnv(env) ? { ...env, ...defaultPolicyEnv() } : env
+}

package/src/index.ts

@@ -3,6 +3,13 @@
  * commands/<name>.
  */
 
+import { loadDotenvFile } from './util/dotenv'
+
+// Zero-env-var startup: load `~/.lyra/.env` (e.g. the OPENAI_API_KEY that
+// `lyra init` persisted) into process.env before any command reads it. Real
+// shell env always wins — loadDotenvFile only fills UNSET keys.
+loadDotenvFile()
+
 const argv = process.argv.slice(2)
 // First arg starting with `--` means the user invoked the default subcommand
 // (chat) with flags, e.g. `lyra --yolo`. Treat it as if `chat` were implicit.
@@ -21,7 +28,15 @@ async function main(): Promise<void> {
     }
     case 'init': {
       const { runInit } = await import('./commands/init')
-      await runInit()
+      await runInit({
+        yes: argv.includes('--yes') || argv.includes('-y'),
+        new: argv.includes('--new'),
+      })
+      return
+    }
+    case 'login': {
+      const { runLogin } = await import('./commands/login')
+      await runLogin()
       return
     }
     case 'status': {
@@ -113,7 +128,8 @@ function printHelp(): void {
       'lyra: a Sui-native, policy-bound AI finance agent',
       '',
       'Commands:',
-      '  lyra init                bootstrap the agent config (uses LYRA_AGENT_KEY)',
+      '  lyra init                set up your agent (interactive; --new / --yes skip prompts)',
+      '  lyra login               link the same agent as lyraai.space (device-link)',
       '  lyra [--yolo]            interactive chat with your agent (default; --yolo skips approvals)',
       '  lyra status              show agent address + network + SUI balance + policy',
       '  lyra whoami [--owner 0x…] resolve the agent wallet an owner controls (same on web/CLI/TG)',
@@ -128,8 +144,10 @@ function printHelp(): void {
       '  lyra version             print CLI version  (aliases: --version, -v)',
       '  lyra help                show this message  (aliases: --help, -h)',
       '',
-      'Env: LYRA_AGENT_KEY (suiprivkey1…), LYRA_NETWORK, LYRA_PACKAGE_ID,',
-      '     LYRA_LLM_BASE_URL, LYRA_LLM_MODEL, OPENAI_API_KEY, LYRA_POLICY_*',
+      'Zero-config: `lyra init` writes ~/.lyra/agent.key + ~/.lyra/.env, so no env',
+      'vars are required. All env below are OPTIONAL overrides (env wins if set):',
+      '  LYRA_AGENT_KEY (suiprivkey1…), LYRA_NETWORK, LYRA_PACKAGE_ID, LYRA_WEB_URL,',
+      '  LYRA_LLM_BASE_URL, LYRA_LLM_MODEL, OPENAI_API_KEY, LYRA_POLICY_*',
       '',
     ].join('\n'),
   )

package/src/util/dotenv.ts

@@ -0,0 +1,67 @@
+/**
+ * Minimal `~/.lyra/.env` loader.
+ *
+ * `lyra init` persists the OpenAI key to `~/.lyra/.env` (mode 0600) so the CLI
+ * runs with zero shell env vars. On startup we read that file and fill any
+ * UNSET vars — real shell env always wins (we never clobber an existing value).
+ * Kept dependency-free (no dotenv pkg) and intentionally simple: `KEY=value`
+ * lines, `#` comments, optional surrounding quotes.
+ */
+
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+import { agentPaths } from 'lyra-core'
+
+/** Parse `KEY=value` lines (ignoring blanks/comments) into a record. */
+export function parseDotenv(text: string): Record<string, string> {
+  const out: Record<string, string> = {}
+  for (const raw of text.split('\n')) {
+    const line = raw.trim()
+    if (!line || line.startsWith('#')) continue
+    const eq = line.indexOf('=')
+    if (eq <= 0) continue
+    const key = line.slice(0, eq).trim()
+    let val = line.slice(eq + 1).trim()
+    if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+      val = val.slice(1, -1)
+    }
+    if (key) out[key] = val
+  }
+  return out
+}
+
+/**
+ * Load `~/.lyra/.env` into `process.env`, filling only UNSET keys. No-op when
+ * the file is absent. Returns the keys it actually set.
+ */
+export function loadDotenvFile(): string[] {
+  const path = agentPaths.dotenv
+  if (!existsSync(path)) return []
+  const parsed = parseDotenv(readFileSync(path, 'utf8'))
+  const set: string[] = []
+  for (const [k, v] of Object.entries(parsed)) {
+    if (process.env[k] === undefined) {
+      process.env[k] = v
+      set.push(k)
+    }
+  }
+  return set
+}
+
+/**
+ * Persist (or update) a single `KEY=value` in `~/.lyra/.env`, preserving other
+ * lines, and lock the file to mode 0600. Also updates `process.env[key]`.
+ */
+export function setDotenvVar(key: string, value: string): string {
+  const path = agentPaths.dotenv
+  mkdirSync(dirname(path), { recursive: true })
+  const existing = existsSync(path) ? parseDotenv(readFileSync(path, 'utf8')) : {}
+  existing[key] = value
+  const body = `${Object.entries(existing)
+    .map(([k, v]) => `${k}=${v}`)
+    .join('\n')}\n`
+  writeFileSync(path, body, { mode: 0o600 })
+  chmodSync(path, 0o600)
+  process.env[key] = value
+  return path
+}

package/src/util/sui-runtime.test.ts

@@ -0,0 +1,73 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { mkdtempSync, statSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { Ed25519Keypair } from '@mysten/sui/keypairs/ed25519'
+import { agentPaths } from 'lyra-core'
+import { loadAgent, loadAgentFromEnv, readAgentKeyFile, writeAgentKey } from './sui-runtime'
+
+// Isolate the agent dir per-test via LYRA_ROOT so we never touch the real
+// ~/.lyra. Also clear LYRA_AGENT_KEY so file-vs-env precedence is deterministic.
+// Use Reflect.deleteProperty (not the `delete` operator) for a true unset —
+// assigning `undefined` would leave the string "undefined" and break the loader.
+let prevRoot: string | undefined
+let prevKey: string | undefined
+
+function restoreEnv(key: string, prev: string | undefined): void {
+  if (prev === undefined) Reflect.deleteProperty(process.env, key)
+  else process.env[key] = prev
+}
+
+beforeEach(() => {
+  prevRoot = process.env.LYRA_ROOT
+  prevKey = process.env.LYRA_AGENT_KEY
+  process.env.LYRA_ROOT = mkdtempSync(join(tmpdir(), 'lyra-runtime-'))
+  Reflect.deleteProperty(process.env, 'LYRA_AGENT_KEY')
+})
+
+afterEach(() => {
+  restoreEnv('LYRA_ROOT', prevRoot)
+  restoreEnv('LYRA_AGENT_KEY', prevKey)
+})
+
+describe('writeAgentKey / readAgentKeyFile', () => {
+  test('writes the secret to ~/.lyra/agent.key with mode 0600', () => {
+    const secret = new Ed25519Keypair().getSecretKey()
+    const path = writeAgentKey(secret)
+    expect(path).toBe(agentPaths.agentKey)
+    expect(readAgentKeyFile()).toBe(secret)
+    // Permission bits masked to the low 9 (rwx for u/g/o) should be 0600.
+    expect(statSync(path).mode & 0o777).toBe(0o600)
+  })
+
+  test('readAgentKeyFile returns null when no key file exists', () => {
+    expect(readAgentKeyFile()).toBeNull()
+  })
+})
+
+describe('loadAgent (env-first, then file)', () => {
+  test('returns null when neither env nor file is present', () => {
+    expect(loadAgent()).toBeNull()
+    expect(loadAgentFromEnv()).toBeNull()
+  })
+
+  test('reads the on-disk key when LYRA_AGENT_KEY is unset', () => {
+    const kp = new Ed25519Keypair()
+    writeAgentKey(kp.getSecretKey())
+    // env unset → falls through to the file.
+    expect(loadAgentFromEnv()).toBeNull()
+    const agent = loadAgent()
+    expect(agent).not.toBeNull()
+    expect(agent?.address).toBe(kp.toSuiAddress())
+  })
+
+  test('LYRA_AGENT_KEY env wins over the on-disk key', () => {
+    const fileKp = new Ed25519Keypair()
+    const envKp = new Ed25519Keypair()
+    writeAgentKey(fileKp.getSecretKey())
+    process.env.LYRA_AGENT_KEY = envKp.getSecretKey()
+    const agent = loadAgent()
+    expect(agent?.address).toBe(envKp.toSuiAddress())
+    expect(agent?.address).not.toBe(fileKp.toSuiAddress())
+  })
+})

package/src/util/sui-runtime.ts

@@ -11,6 +11,9 @@
  * lyra-plugin-onchain tools read via `(ctx as any).onchain`.
  */
 
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+import { agentPaths } from 'lyra-core'
 import {
   type OnchainRuntimeContext,
   type SuiNetwork,
@@ -18,6 +21,7 @@ import {
   makeSuiClient,
   policyFromEnv,
 } from 'lyra-plugin-onchain'
+import { resolvePackageId, resolvePolicyEnv } from '../config/defaults'
 
 /** Env var holding the agent's Sui secret key (`suiprivkey1…` or base64 seed). */
 export const AGENT_KEY_ENV = 'LYRA_AGENT_KEY'
@@ -40,6 +44,43 @@ export function loadAgentFromEnv(): SuiAgent | null {
   return { keypair, address: keypair.toSuiAddress() }
 }
 
+/** Read the on-disk agent secret (`~/.lyra/agent.key`), or null if absent. */
+export function readAgentKeyFile(): string | null {
+  const path = agentPaths.agentKey
+  if (!existsSync(path)) return null
+  const secret = readFileSync(path, 'utf8').trim()
+  return secret.length > 0 ? secret : null
+}
+
+/**
+ * Resolve the agent keypair the file-aware way: `LYRA_AGENT_KEY` env wins if
+ * set, else the on-disk key at `~/.lyra/agent.key`, else null. This is the
+ * loader every command should use — it makes the agent key a zero-env-var
+ * concern (`lyra init` / `lyra login` write the file).
+ */
+export function loadAgent(): SuiAgent | null {
+  const fromEnv = loadAgentFromEnv()
+  if (fromEnv) return fromEnv
+  const secret = readAgentKeyFile()
+  if (!secret) return null
+  const keypair = keypairFromSecret(secret)
+  return { keypair, address: keypair.toSuiAddress() }
+}
+
+/**
+ * Persist the agent secret (`suiprivkey1…`) to `~/.lyra/agent.key` with mode
+ * 0600. Used by `lyra init` (create new) and `lyra login` (device-link).
+ */
+export function writeAgentKey(suiprivkey: string): string {
+  const path = agentPaths.agentKey
+  mkdirSync(dirname(path), { recursive: true })
+  writeFileSync(path, `${suiprivkey.trim()}\n`, { mode: 0o600 })
+  // writeFileSync's mode is masked by umask on create and ignored when the file
+  // already exists — chmod unconditionally so re-runs stay locked down.
+  chmodSync(path, 0o600)
+  return path
+}
+
 export interface BuildOnchainOpts {
   agent: SuiAgent
   network: SuiNetwork
@@ -57,14 +98,18 @@ export interface BuildOnchainOpts {
  * mirror comes from `policyFromEnv()` (the `LYRA_POLICY_*` vars).
  */
 export function buildOnchainContext(opts: BuildOnchainOpts): OnchainRuntimeContext {
-  const packageId = opts.packageId ?? process.env.LYRA_PACKAGE_ID ?? undefined
+  // packageId: explicit opt wins, then LYRA_PACKAGE_ID, then the deployed
+  // mainnet default — so on-chain receipts work with zero env config.
+  const packageId = opts.packageId ?? resolvePackageId()
   const policyObjectId = opts.policyObjectId ?? process.env.LYRA_POLICY_OBJECT_ID ?? undefined
   return {
     client: makeSuiClient(opts.network),
     keypair: opts.agent.keypair,
     agentAddress: opts.agent.address,
     network: opts.network,
-    policy: policyFromEnv(),
+    // Default to the bounded policy when no LYRA_POLICY_* is set (never an
+    // unbounded auto-spender out of the box).
+    policy: policyFromEnv(resolvePolicyEnv()),
     packageId: packageId || undefined,
     policyObjectId: policyObjectId || undefined,
     agentDir: opts.agentDir,