lyra-ai-agent 0.1.0

package/src/commands/status.ts

@@ -0,0 +1,84 @@
+import { existsSync, statSync } from 'node:fs'
+import { agentPaths, formatSui, getSuiBalanceMist, makeSuiClient, suiRpcUrl } from 'lyra-core'
+import { type SuiPolicy, policyFromEnv } from 'lyra-plugin-onchain'
+import { findAndLoadConfig } from '../config/load'
+import { loadAgentFromEnv } from '../util/sui-runtime'
+import { listAgentIds } from './_agents'
+
+export async function runStatus(opts?: { cwd?: string }): Promise<void> {
+  const cwd = opts?.cwd ?? process.cwd()
+  const found = await findAndLoadConfig(cwd)
+  if (!found) {
+    console.log('No lyra.config.ts found. Run `lyra init` first.')
+    process.exit(1)
+  }
+  const { config, path } = found
+
+  const agent = loadAgentFromEnv()
+  const agentAddress = agent?.address ?? config.identity.agent ?? '(no LYRA_AGENT_KEY)'
+
+  console.log(`config    ${path}`)
+  console.log(`network   ${config.network}`)
+  console.log(`rpc       ${suiRpcUrl(config.network)}`)
+  console.log(`plugins   ${config.plugins.join(', ')}`)
+  console.log(`agent     ${agentAddress}`)
+  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 policyObjectId = process.env.LYRA_POLICY_OBJECT_ID
+  if (policyObjectId) console.log(`policy obj ${policyObjectId}`)
+  const policy = policyFromEnv()
+  if (policy) {
+    console.log(`policy     ${summarizePolicy(policy)}`)
+  } else {
+    console.log('policy     (none configured — set LYRA_POLICY_* to bound the agent)')
+  }
+
+  // Live SUI balance for the agent (pays gas for every PTB).
+  if (agent) {
+    try {
+      const client = makeSuiClient(config.network)
+      const mist = await getSuiBalanceMist(client, agent.address)
+      console.log(`balance   ${formatSui(mist)} SUI`)
+    } catch (e) {
+      console.log(`balance   (rpc error: ${(e as Error).message.slice(0, 80)})`)
+    }
+  }
+
+  const ids = await listAgentIds()
+  if (ids.length === 0) {
+    console.log('\nNo agents found in ~/.lyra/agents. Re-run `lyra init`.')
+    return
+  }
+
+  for (const id of ids) {
+    console.log('')
+    console.log(`agent dir ${id}`)
+    console.log(`dir       ${agentPaths.agent(id).dir}`)
+    const activityPath = agentPaths.agent(id).activityLog
+    if (existsSync(activityPath)) {
+      const sz = statSync(activityPath).size
+      console.log(`activity  ${sz} bytes`)
+    }
+  }
+}
+
+/** One-line summary of the deterministic off-chain policy mirror. */
+function summarizePolicy(policy: SuiPolicy): string {
+  const parts: string[] = []
+  const autonomy = policy.autonomy ?? (policy.readOnly ? 'readonly' : 'auto')
+  parts.push(`autonomy=${autonomy}`)
+  if (policy.maxMistPerTx !== undefined)
+    parts.push(`maxPerTx=${formatSui(policy.maxMistPerTx)} SUI`)
+  if (policy.autoMaxMistPerTx !== undefined)
+    parts.push(`autoMax=${formatSui(policy.autoMaxMistPerTx)} SUI`)
+  if (policy.maxSlippageBps !== undefined) parts.push(`slippage=${policy.maxSlippageBps}bps`)
+  if (policy.coinAllowlist?.length) parts.push(`coins=${policy.coinAllowlist.length}`)
+  if (policy.protocolAllowlist?.length) parts.push(`protocols=${policy.protocolAllowlist.length}`)
+  if (policy.recipientAllowlist?.length)
+    parts.push(`recipients=${policy.recipientAllowlist.length}`)
+  if (policy.expiryMs) parts.push(`expires=${new Date(policy.expiryMs).toISOString().slice(0, 16)}`)
+  return parts.join(', ')
+}

package/src/commands/telegram-remove.ts

@@ -0,0 +1,45 @@
+import { cancel, intro, note, outro } from '@clack/prompts'
+import { findAndLoadConfig } from '../config/load'
+import { writeConfigTs } from '../config/render'
+
+export interface TelegramRemoveOpts {
+  yes?: boolean
+}
+
+/**
+ * `lyra telegram remove` — disable the telegram plugin in config and remind the
+ * operator to unset the env vars. On Sui the token lives only in the
+ * environment, so there is no on-disk blob to delete.
+ */
+export async function runTelegramRemove(_opts: TelegramRemoveOpts = {}): Promise<void> {
+  intro('lyra telegram remove')
+
+  const loaded = await findAndLoadConfig()
+  if (!loaded) {
+    cancel('No lyra.config.ts found. Run `lyra init` first.')
+    return
+  }
+  const { config, path: configPath } = loaded
+
+  const plugins = (config.plugins ?? []).filter(p => p !== 'telegram')
+  if (plugins.length !== (config.plugins ?? []).length) {
+    await writeConfigTs(configPath, { ...config, plugins })
+    note('Removed `telegram` from config.plugins.')
+  } else {
+    note('telegram plugin was not enabled.')
+  }
+
+  note(
+    [
+      'Unset the env vars to fully disable the bot:',
+      '',
+      '  unset TELEGRAM_BOT_TOKEN TELEGRAM_USERNAME TELEGRAM_CHAT_ID',
+      '',
+      'The bot token at @BotFather is STILL VALID. To fully revoke, run /token',
+      'in @BotFather and pick "Revoke" for this bot.',
+    ].join('\n'),
+    'reminder',
+  )
+
+  outro('telegram removed')
+}

package/src/commands/telegram-setup.ts

@@ -0,0 +1,84 @@
+import { cancel, intro, isCancel, note, outro, password, spinner, text } from '@clack/prompts'
+import { findAndLoadConfig } from '../config/load'
+import { writeConfigTs } from '../config/render'
+import { fetchBotInfo, looksLikeBotToken, parseAllowedUserIds } from '../util/telegram-secrets'
+
+/**
+ * `lyra telegram setup` — validate a bot token and print the env vars to set.
+ *
+ * On Sui the bot token is NOT stored on disk (there is no operator wallet to
+ * encrypt it with). It lives only in the environment, so this command's job is
+ * to validate the token + allowlist and hand back the exact `export` lines.
+ */
+export async function runTelegramSetup(): Promise<void> {
+  intro('lyra telegram setup')
+
+  const loaded = await findAndLoadConfig()
+  if (!loaded) {
+    cancel('No lyra.config.ts found. Run `lyra init` first.')
+    return
+  }
+  const { config, path: configPath } = loaded
+
+  const token = await password({
+    message: 'Bot token (from @BotFather)',
+    validate: v => (v && looksLikeBotToken(v) ? undefined : 'Expected a token like 123456:ABC...'),
+  })
+  if (isCancel(token)) {
+    cancel('Aborted.')
+    return
+  }
+
+  const sPing = spinner()
+  sPing.start('Validating token via getMe')
+  let info: Awaited<ReturnType<typeof fetchBotInfo>>
+  try {
+    info = await fetchBotInfo(String(token))
+    sPing.stop(`bot ok: @${info.username} (id ${info.id})`)
+  } catch (e) {
+    sPing.stop(`getMe failed: ${(e as Error).message.slice(0, 200)}`)
+    cancel('Token rejected.')
+    return
+  }
+
+  const idsRaw = await text({
+    message: 'Allowed Telegram user id (blank = open access). Sets TELEGRAM_CHAT_ID.',
+    placeholder: '',
+    validate: v => {
+      const r = parseAllowedUserIds(v ?? '')
+      return r.ok ? undefined : r.reason
+    },
+  })
+  if (isCancel(idsRaw)) {
+    cancel('Aborted.')
+    return
+  }
+  const parsed = parseAllowedUserIds(String(idsRaw ?? ''))
+  const chatId = parsed.ok && parsed.ids.length > 0 ? parsed.ids[0] : null
+
+  // Enable the telegram plugin in config so `lyra` loads the listener when the
+  // env token is present.
+  if (!(config.plugins ?? []).includes('telegram')) {
+    await writeConfigTs(configPath, {
+      ...config,
+      plugins: [...(config.plugins ?? []), 'telegram'],
+    })
+  }
+
+  note(
+    [
+      'Set these in your environment (e.g. .env), then run `lyra`:',
+      '',
+      `  export TELEGRAM_BOT_TOKEN=${token}`,
+      `  export TELEGRAM_USERNAME=${info.username}`,
+      ...(chatId
+        ? [`  export TELEGRAM_CHAT_ID=${chatId}`]
+        : ['  # TELEGRAM_CHAT_ID unset = open access']),
+      '',
+      `Then open https://t.me/${info.username} and send any message.`,
+    ].join('\n'),
+    'next step',
+  )
+
+  outro(`telegram setup validated (@${info.username})`)
+}

package/src/commands/telegram-status.ts

@@ -0,0 +1,48 @@
+import { cancel, intro, log, outro, spinner } from '@clack/prompts'
+import { findAndLoadConfig } from '../config/load'
+import { fetchBotInfo, telegramSecretsFromEnv } from '../util/telegram-secrets'
+
+/**
+ * `lyra telegram status` — read the env-configured bot token, ping getMe, and
+ * report the resolved config.
+ */
+export async function runTelegramStatus(): Promise<void> {
+  intro('lyra telegram status')
+
+  const loaded = await findAndLoadConfig()
+  if (!loaded) {
+    cancel('No lyra.config.ts found. Run `lyra init` first.')
+    return
+  }
+  const { config } = loaded
+
+  const secrets = telegramSecretsFromEnv()
+  if (!secrets) {
+    log.warn('No TELEGRAM_BOT_TOKEN in the environment.')
+    log.info('Run `lyra telegram setup` for the env vars to set.')
+    outro('not configured')
+    return
+  }
+
+  const sPing = spinner()
+  sPing.start('Pinging Telegram getMe')
+  try {
+    const info = await fetchBotInfo(secrets.botToken)
+    sPing.stop(`bot ok: @${info.username} (id ${info.id})`)
+  } catch (e) {
+    sPing.stop(`getMe failed: ${(e as Error).message.slice(0, 200)}`)
+    log.warn('Token may have been revoked at @BotFather. Re-run `lyra telegram setup`.')
+    return
+  }
+
+  log.info(
+    [
+      'source           env (TELEGRAM_BOT_TOKEN)',
+      `bot username     @${secrets.botUsername ?? '(set TELEGRAM_USERNAME)'}`,
+      `allowed user ids ${secrets.allowedUserIds.length === 0 ? '(open access)' : secrets.allowedUserIds.join(', ')}`,
+      `plugin enabled   ${(config.plugins ?? []).includes('telegram') ? 'yes' : 'no — add `telegram` to plugins'}`,
+    ].join('\n'),
+  )
+
+  outro('telegram configured via env')
+}

package/src/commands/telegram.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'bun:test'
+import { parseTelegramArgs } from './telegram'
+
+describe('parseTelegramArgs', () => {
+  it('errors on missing subcommand', () => {
+    const r = parseTelegramArgs([])
+    expect('error' in r).toBe(true)
+    if ('error' in r) expect(r.error).toContain('usage')
+  })
+
+  it('errors on unknown subcommand', () => {
+    const r = parseTelegramArgs(['nuke'])
+    expect('error' in r).toBe(true)
+    if ('error' in r) expect(r.error).toContain('nuke')
+  })
+
+  it('parses setup', () => {
+    const r = parseTelegramArgs(['setup'])
+    expect('error' in r).toBe(false)
+    if (!('error' in r)) expect(r.sub).toBe('setup')
+  })
+
+  it('parses status', () => {
+    const r = parseTelegramArgs(['status'])
+    if (!('error' in r)) expect(r.sub).toBe('status')
+  })
+
+  it('parses remove without --yes', () => {
+    const r = parseTelegramArgs(['remove'])
+    if (!('error' in r)) {
+      expect(r.sub).toBe('remove')
+      expect(r.yes).toBeFalsy()
+    }
+  })
+
+  it('parses remove --yes', () => {
+    const r = parseTelegramArgs(['remove', '--yes'])
+    if (!('error' in r)) {
+      expect(r.sub).toBe('remove')
+      expect(r.yes).toBe(true)
+    }
+  })
+
+  it('parses remove -y', () => {
+    const r = parseTelegramArgs(['remove', '-y'])
+    if (!('error' in r)) {
+      expect(r.yes).toBe(true)
+    }
+  })
+})

package/src/commands/telegram.ts

@@ -0,0 +1,44 @@
+/**
+ * `lyra telegram <subcommand>` — argv dispatcher.
+ *
+ * Subcommands:
+ *   setup    interactive wizard: validate token, encrypt + persist locally
+ *   status   confirm token still valid + show stored config
+ *   remove   delete the encrypted local blob (does NOT revoke at @BotFather)
+ */
+
+export interface TelegramArgs {
+  sub: 'setup' | 'status' | 'remove'
+  yes?: boolean
+}
+
+const VALID_SUBS = ['setup', 'status', 'remove'] as const
+
+export function parseTelegramArgs(argv: string[]): TelegramArgs | { error: string } {
+  const sub = argv[0]
+  if (!sub) return { error: 'usage: lyra telegram <setup | status | remove>' }
+  const valid = (VALID_SUBS as readonly string[]).includes(sub)
+  if (!valid) return { error: `unknown subcommand '${sub}' (expected: ${VALID_SUBS.join(' | ')})` }
+  const yes = argv.includes('--yes') || argv.includes('-y')
+  return { sub: sub as TelegramArgs['sub'], yes }
+}
+
+export async function runTelegram(args: TelegramArgs): Promise<void> {
+  switch (args.sub) {
+    case 'setup': {
+      const { runTelegramSetup } = await import('./telegram-setup')
+      await runTelegramSetup()
+      return
+    }
+    case 'status': {
+      const { runTelegramStatus } = await import('./telegram-status')
+      await runTelegramStatus()
+      return
+    }
+    case 'remove': {
+      const { runTelegramRemove } = await import('./telegram-remove')
+      await runTelegramRemove({ yes: args.yes })
+      return
+    }
+  }
+}

package/src/commands/whoami.ts

@@ -0,0 +1,62 @@
+/**
+ * `lyra whoami [--owner 0x…]` — resolve which agent wallet belongs to an owner.
+ *
+ * Multi-tenant identity: an owner's personal wallet deterministically maps to one
+ * agent wallet (the SAME derivation the web + Telegram use). This command shows
+ * that mapping + the agent's balance so the owner can fund it. The owner proves
+ * identity differently per surface (SIWS on web, /link on Telegram, this config
+ * on CLI), but they all resolve to the same agent.
+ */
+
+import {
+  type SuiNetwork,
+  deriveAgentAddress,
+  makeSuiClient,
+  resolveOwnerVault,
+} from 'lyra-plugin-onchain'
+
+export async function runWhoami(opts: { owner?: string }): Promise<void> {
+  const owner = opts.owner ?? process.env.LYRA_OWNER_ADDRESS
+  if (!owner) {
+    console.error('lyra whoami: pass --owner <0x…> (your wallet) or set LYRA_OWNER_ADDRESS')
+    process.exit(1)
+    return
+  }
+  let agent: string
+  try {
+    agent = deriveAgentAddress(owner)
+  } catch (e) {
+    console.error(`lyra whoami: ${(e as Error).message}`)
+    process.exit(1)
+    return
+  }
+  const network = (process.env.LYRA_NETWORK as SuiNetwork) ?? 'mainnet'
+  const client = makeSuiClient(network)
+  const [bal, ov] = await Promise.all([
+    client.getBalance({ owner: agent }).catch(() => null),
+    resolveOwnerVault(owner, network).catch(() => null),
+  ])
+  const sui = bal ? (Number(bal.totalBalance) / 1e9).toFixed(6) : '?'
+
+  console.log('')
+  console.log(`  owner    ${owner}`)
+  console.log(`  agent    ${agent}   (gas float ${sui} SUI)`)
+  console.log(`  network  ${network}`)
+  if (ov) {
+    console.log(`  vault    ${ov.vaultId}`)
+    console.log(
+      `  treasury ${(Number(ov.vaultMist) / 1e9).toFixed(6)} SUI  (policy ${ov.policyId.slice(0, 10)}…)`,
+    )
+    console.log('')
+    console.log('  The agent spends the treasury from the vault via policy-enforced')
+    console.log('  vault_spend; you (owner) can withdraw or revoke any time.')
+  } else {
+    console.log('  vault    not provisioned')
+    console.log('')
+    console.log('  Provision a non-custodial vault from the web console (owner-signed),')
+    console.log('  then the agent spends the treasury under your on-chain AgentPolicy.')
+  }
+  console.log('')
+  console.log('  Same owner → same agent + vault on web + CLI + Telegram (deterministic).')
+  console.log('')
+}

package/src/config/load.ts

@@ -0,0 +1,35 @@
+import { existsSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { type LyraConfig, agentPaths } from 'lyra-core'
+
+/**
+ * Load the user's `lyra.config.ts`.
+ *
+ * Phase 6.6: canonical location is `~/.lyra/config.ts` (returned by
+ * `agentPaths.config`). If that file exists, it wins. Otherwise, fall back
+ * to walking upward from cwd looking for `lyra.config.ts` (legacy v0.5.0
+ * pattern, kept so existing dev setups still work without a migration step).
+ */
+export async function findAndLoadConfig(
+  startDir: string = process.cwd(),
+): Promise<{ config: LyraConfig; path: string } | null> {
+  const canonical = agentPaths.config
+  if (existsSync(canonical)) {
+    const mod = (await import(canonical)) as { default: LyraConfig }
+    if (!mod.default) throw new Error(`lyra config at ${canonical} has no default export`)
+    return { config: mod.default, path: canonical }
+  }
+
+  let dir = resolve(startDir)
+  while (true) {
+    const candidate = resolve(dir, 'lyra.config.ts')
+    if (existsSync(candidate)) {
+      const mod = (await import(candidate)) as { default: LyraConfig }
+      if (!mod.default) throw new Error(`lyra.config.ts at ${candidate} has no default export`)
+      return { config: mod.default, path: candidate }
+    }
+    const parent = resolve(dir, '..')
+    if (parent === dir) return null
+    dir = parent
+  }
+}

package/src/config/render.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, test } from 'bun:test'
+import type { LyraConfig } from 'lyra-core'
+import { renderConfigTs } from './render'
+
+const baseConfig: LyraConfig = {
+  identity: { operator: null, agent: null },
+  network: 'mainnet',
+  storage: { network: 'mainnet' },
+  brain: { provider: null, model: null },
+  plugins: ['system'],
+  tools: {},
+  imports: { claudeCode: true },
+}
+
+describe('renderConfigTs sandbox block', () => {
+  test('fresh config (no sandbox set) emits default + commented examples for each tier', () => {
+    const out = renderConfigTs(baseConfig)
+    // Active default
+    expect(out).toContain(`sandbox: { mode: 'none' }`)
+    // Commented OPTION 2 (os)
+    expect(out).toContain('OPTION 2: os')
+    expect(out).toContain(`//  sandbox: { mode: 'os' }`)
+    // Commented OPTION 3 (docker)
+    expect(out).toContain('OPTION 3: docker')
+    expect(out).toContain(`//    mode: 'docker'`)
+    expect(out).toContain(`//    dockerImage: 'nikolaik/python-nodejs:python3.11-nodejs20'`)
+    expect(out).toContain('//    dockerMountWorkspace: false')
+    // LYRA_SANDBOX_MODE override hint
+    expect(out).toContain('LYRA_SANDBOX_MODE')
+  })
+
+  test('config with sandbox.mode="os" already set emits the chosen value, not the template', () => {
+    const out = renderConfigTs({ ...baseConfig, sandbox: { mode: 'os' } })
+    expect(out).toContain(`"mode": "os"`)
+    // No verbose template when operator already chose
+    expect(out).not.toContain('OPTION 2: os')
+    expect(out).not.toContain('OPTION 3: docker')
+  })
+
+  test('config with sandbox.mode="docker" + image emits the full chosen object', () => {
+    const out = renderConfigTs({
+      ...baseConfig,
+      sandbox: {
+        mode: 'docker',
+        dockerImage: 'custom/img:tag',
+        dockerMountWorkspace: true,
+      },
+    })
+    expect(out).toContain(`"mode": "docker"`)
+    expect(out).toContain(`"dockerImage": "custom/img:tag"`)
+    expect(out).toContain(`"dockerMountWorkspace": true`)
+    expect(out).not.toContain('OPTION')
+  })
+
+  test('annotated template documents resource caps with hermes default values', () => {
+    const out = renderConfigTs(baseConfig)
+    expect(out).toContain('// dockerCpu: 1')
+    expect(out).toContain('// dockerMemoryMb: 5120')
+    expect(out).toContain('// dockerDiskMb: 51200')
+    expect(out).toContain('// dockerNoNetwork: true')
+  })
+
+  test('config with sandbox docker + resource caps emits chosen numeric values', () => {
+    const out = renderConfigTs({
+      ...baseConfig,
+      sandbox: {
+        mode: 'docker',
+        dockerCpu: 2,
+        dockerMemoryMb: 4096,
+        dockerNoNetwork: true,
+      },
+    })
+    expect(out).toContain(`"dockerCpu": 2`)
+    expect(out).toContain(`"dockerMemoryMb": 4096`)
+    expect(out).toContain(`"dockerNoNetwork": true`)
+    expect(out).not.toContain('OPTION')
+  })
+
+  test('output is valid TypeScript (parses as a default-export module)', async () => {
+    const out = renderConfigTs(baseConfig)
+    const { writeFile, rm, mkdtemp } = await import('node:fs/promises')
+    const { tmpdir } = await import('node:os')
+    const { join } = await import('node:path')
+    const dir = await mkdtemp(join(tmpdir(), 'lyra-render-test-'))
+    const path = join(dir, 'config.ts')
+    try {
+      await writeFile(path, out, 'utf8')
+      const mod = await import(path)
+      expect(mod.default).toBeDefined()
+      expect(mod.default.sandbox).toEqual({ mode: 'none' })
+      expect(mod.default.network).toBe('mainnet')
+    } finally {
+      await rm(dir, { recursive: true, force: true })
+    }
+  })
+})

package/src/config/render.ts

@@ -0,0 +1,99 @@
+import { mkdir, writeFile } from 'node:fs/promises'
+import { dirname } from 'node:path'
+import type { LyraConfig } from 'lyra-core'
+
+export interface RenderConfigOpts {
+  header?: string
+}
+
+/**
+ * Serialize an LyraConfig into a `~/.lyra/config.ts` file body.
+ *
+ * Phase 6.6: the config lives at `~/.lyra/config.ts` which is outside any
+ * workspace, so it MUST NOT import `lyra-core` (the import won't
+ * resolve from `~/.lyra/`). We emit a plain `export default { ... }` object;
+ * the runtime loader treats it as `LyraConfig` directly.
+ */
+export function renderConfigTs(cfg: LyraConfig, opts: RenderConfigOpts = {}): string {
+  const header = opts.header ?? ''
+  const operatorLine = cfg.operator ? `  operator: ${JSON.stringify(cfg.operator)},\n` : ''
+  // Emit either the operator's chosen sandbox config OR an annotated
+  // "OPTION 1/2/3" block so the operator can opt in by uncommenting. Default
+  // mode stays `none` (passthrough); documentation IS the UX.
+  const sandboxBlock = renderSandboxBlock(cfg.sandbox)
+  return `${header ? `${header}\n\n` : ''}export default {
+  identity: ${JSON.stringify(cfg.identity)},
+  network: ${JSON.stringify(cfg.network)},
+  storage: { network: ${JSON.stringify(cfg.storage.network)} },
+  brain: {
+    provider: ${JSON.stringify(cfg.brain.provider)},
+    model: ${JSON.stringify(cfg.brain.model)},
+  },
+  plugins: ${JSON.stringify(cfg.plugins)},
+  tools: ${JSON.stringify(cfg.tools)},
+  imports: { claudeCode: ${cfg.imports.claudeCode} },
+${operatorLine}${sandboxBlock}}
+`
+}
+
+function renderSandboxBlock(sandbox: LyraConfig['sandbox']): string {
+  // Phase 11: deploy-target sandbox metadata (id/providerAddress/endpoint/
+  // snapshotName) OR Phase 9.5 limb-sandbox mode = anything non-default → emit
+  // verbatim. Only surface the doc-comment template when the operator has
+  // touched neither.
+  const hasNonDefaultLimbMode = sandbox?.mode && sandbox.mode !== 'none'
+  if (hasNonDefaultLimbMode) {
+    return `  sandbox: ${JSON.stringify(sandbox, null, 2).replace(/\n/g, '\n  ')},\n`
+  }
+  // Fresh install: write the active default + commented examples for the
+  // other tiers. Operator can opt in by uncommenting and editing.
+  return `  sandbox: { mode: 'none' },
+  // ---------------------------------------------------------------------------
+  //  Limb sandbox (Phase 9.5). Defense-in-depth beneath the permission floor:
+  //  even when the modal grants 'allow session' or YOLO disables prompts,
+  //  the sandbox profile/container blocks writes outside an allowlist.
+  //  All shell.run / code.execute / shell.process_start spawns route through
+  //  the chosen backend. fs.* and browser.* still run on the host (PathGuard
+  //  applies). Override at runtime via LYRA_SANDBOX_MODE=os|docker|none.
+  //
+  //  OPTION 1: none (default): passthrough, fastest, permission floor only.
+  //
+  //  OPTION 2: os (macOS sandbox-exec / seatbelt). Allows writes to agentDir +
+  //    cwd + /tmp/lyra-* + /var/folders. Denies reads of ~/.ssh, ~/.aws,
+  //    ~/Library/Keychains, ~/.config/gcloud. Linux bubblewrap pending.
+  //  sandbox: { mode: 'os' },
+  //
+  //  OPTION 3: docker (long-lived container per session), every shell-class
+  //    spawn through 'docker exec'. Auto-detects Docker Desktop or Podman.
+  //    Default image 'nikolaik/python-nodejs:python3.11-nodejs20' (matches
+  //    hermes; ~700 MB; bash + python3 + node + npm + git on standard PATH).
+  //    Override with 'oven/bun:1' (~250 MB) if you only need bun/ts.
+  //    'dockerMountWorkspace: true' bind-mounts your launch cwd into
+  //    /workspace (off by default for max isolation). 'dockerRuntimePath'
+  //    forces a specific runtime binary. Resource caps are unset by default
+  //    (container competes fairly with host work). Set them to mirror hermes'
+  //    production hardening: dockerCpu=1, dockerMemoryMb=5120, dockerDiskMb=
+  //    51200 (Linux+overlay2 only). dockerNoNetwork=true blocks all internet
+  //    access from the container (max paranoia for code.execute).
+  //  sandbox: {
+  //    mode: 'docker',
+  //    dockerImage: 'nikolaik/python-nodejs:python3.11-nodejs20',
+  //    dockerMountWorkspace: false,
+  //    // dockerRuntimePath: '/opt/homebrew/bin/podman',
+  //    // dockerCpu: 1,           // CPU cores cap
+  //    // dockerMemoryMb: 5120,   // 5 GB memory cap
+  //    // dockerDiskMb: 51200,    // 50 GB disk cap (Linux + overlay2 only)
+  //    // dockerNoNetwork: true,  // block all network from inside container
+  //  },
+  // ---------------------------------------------------------------------------
+`
+}
+
+export async function writeConfigTs(
+  path: string,
+  cfg: LyraConfig,
+  opts: RenderConfigOpts = {},
+): Promise<void> {
+  await mkdir(dirname(path), { recursive: true })
+  await writeFile(path, renderConfigTs(cfg, opts), 'utf8')
+}