lyra-core 0.1.0

package/src/commands/registry.ts

@@ -0,0 +1,255 @@
+/**
+ * Shared slash-command registry. The TUI autocomplete popup, TG
+ * `setMyCommands` registration, and the various bypass dispatchers all read
+ * from this single source so command lists never drift between surfaces.
+ */
+
+export type CommandSurface = 'tui' | 'tg'
+
+/**
+ * - `local`  : runs in the CLI process (TUI handler, local TG via chat-telegram)
+ * - `gateway`: runs in the gateway process (sandbox harness or local-mode gateway daemon)
+ * - `both`   : valid in either surface; routing decided by where the command arrives
+ */
+export type CommandScope = 'local' | 'gateway' | 'both'
+
+export interface SlashCommand {
+  /** Command name without leading slash, e.g. "yolo". Lowercased. */
+  name: string
+  /** One-line human description used in TUI menu + TG client menu. */
+  description: string
+  /** Surfaces the command should appear in for discovery. */
+  surfaces: CommandSurface[]
+  /** Where the command actually executes. */
+  scope: CommandScope
+  /** True when the command short-circuits before brain.infer (control commands). */
+  bypassesBrain: boolean
+  /** Optional argument hint shown next to the name in menus, e.g. "off|prompt|strict". */
+  argHint?: string
+}
+
+export const COMMAND_REGISTRY: SlashCommand[] = [
+  {
+    name: 'yolo',
+    description: 'Toggle approval prompts on/off',
+    surfaces: ['tui', 'tg'],
+    scope: 'both',
+    bypassesBrain: true,
+  },
+  {
+    name: 'perms',
+    description: 'Set permission mode',
+    surfaces: ['tui', 'tg'],
+    scope: 'both',
+    bypassesBrain: true,
+    argHint: 'off|prompt|strict',
+  },
+  {
+    name: 'reset',
+    description: 'Clear conversation history for this channel',
+    surfaces: ['tui', 'tg'],
+    scope: 'both',
+    bypassesBrain: true,
+  },
+  {
+    name: 'sync',
+    description: 'Force memory sync to Sui Storage',
+    surfaces: ['tui'],
+    scope: 'local',
+    bypassesBrain: true,
+  },
+  {
+    name: 'model',
+    description: 'Show brain model switch hint',
+    surfaces: ['tui'],
+    scope: 'local',
+    bypassesBrain: true,
+  },
+  {
+    name: 'jobs',
+    description: 'List active marketplace jobs',
+    surfaces: ['tui'],
+    scope: 'local',
+    bypassesBrain: true,
+  },
+  {
+    name: 'help',
+    description: 'Show all commands',
+    surfaces: ['tui'],
+    scope: 'local',
+    bypassesBrain: true,
+  },
+  {
+    name: 'exit',
+    description: 'Quit lyra',
+    surfaces: ['tui'],
+    scope: 'local',
+    bypassesBrain: true,
+  },
+  {
+    name: 'quit',
+    description: 'Quit lyra',
+    surfaces: ['tui'],
+    scope: 'local',
+    bypassesBrain: true,
+  },
+  {
+    name: 'stop',
+    description: 'Cancel current turn',
+    surfaces: ['tg'],
+    scope: 'gateway',
+    bypassesBrain: true,
+  },
+  {
+    name: 'new',
+    description: 'Start a fresh session',
+    surfaces: ['tg'],
+    scope: 'gateway',
+    bypassesBrain: true,
+  },
+  {
+    name: 'status',
+    description: 'Show agent status',
+    surfaces: ['tg'],
+    scope: 'gateway',
+    bypassesBrain: true,
+  },
+  {
+    name: 'approve',
+    description: 'Approve the pending request',
+    surfaces: ['tg'],
+    scope: 'gateway',
+    bypassesBrain: true,
+  },
+  {
+    name: 'deny',
+    description: 'Deny the pending request',
+    surfaces: ['tg'],
+    scope: 'gateway',
+    bypassesBrain: true,
+  },
+  {
+    name: 'background',
+    description: 'Move the current turn to background',
+    surfaces: ['tg'],
+    scope: 'gateway',
+    bypassesBrain: true,
+  },
+  {
+    name: 'restart',
+    description: 'Restart the active session',
+    surfaces: ['tg'],
+    scope: 'gateway',
+    bypassesBrain: true,
+  },
+]
+
+export function commandsForSurface(surface: CommandSurface): SlashCommand[] {
+  return COMMAND_REGISTRY.filter(c => c.surfaces.includes(surface))
+}
+
+export function findCommand(name: string): SlashCommand | undefined {
+  const needle = name.replace(/^\/+/, '').toLowerCase()
+  return COMMAND_REGISTRY.find(c => c.name === needle)
+}
+
+export interface ParsedSlash {
+  /** Raw command name lowercased, no leading slash. */
+  name: string
+  /** Whitespace-split argv after the command. */
+  args: string[]
+  /** Resolved registry entry when name matches a known command, otherwise undefined. */
+  command?: SlashCommand
+}
+
+/**
+ * Parse a leading-slash message into name + args. Returns null when the input
+ * doesn't start with a slash. Unknown command names still return a parsed
+ * shape (with `command` undefined) so callers can distinguish "not a slash"
+ * from "slash but unknown".
+ */
+export function parseSlash(text: string): ParsedSlash | null {
+  const trimmed = text.trimStart()
+  if (!trimmed.startsWith('/')) return null
+  const stripped = trimmed.slice(1).trimEnd()
+  if (stripped.length === 0) return null
+  const parts = stripped.split(/\s+/)
+  const name = (parts[0] ?? '').toLowerCase()
+  if (name.length === 0) return null
+  const args = parts.slice(1)
+  return { name, args, command: findCommand(name) }
+}
+
+/**
+ * Filter commands by surface and prefix for autocomplete suggestions.
+ * Empty or single-`/` query returns all commands for the surface.
+ */
+export function suggestForPrefix(surface: CommandSurface, query: string): SlashCommand[] {
+  const stripped = query.replace(/^\/+/, '').toLowerCase()
+  const all = commandsForSurface(surface)
+  if (stripped.length === 0) return all
+  return all.filter(c => c.name.startsWith(stripped))
+}
+
+/**
+ * Permission modes operators can flip via /yolo and /perms. Matches
+ * `PermissionMode` from `../permission` but redeclared here to avoid the
+ * commands module taking a transitive dependency on the permission service.
+ */
+export type PermissionToggleMode = 'off' | 'prompt' | 'strict'
+
+export interface PermissionApi {
+  getMode(): PermissionToggleMode
+  setMode(mode: PermissionToggleMode): void
+}
+
+export interface ApplyResult {
+  /** Operator-facing message describing the new state. */
+  message: string
+  /** Mode after the operation, for callers that mirror UI state. */
+  mode: PermissionToggleMode
+}
+
+/**
+ * Toggle approval prompts between `off` (YOLO) and `prompt` (re-enable).
+ * `strict` flips to `prompt` on toggle to give an off-ramp from lockdown.
+ * Single source of truth; consumed by TUI `/yolo`, TG-local `/yolo`, and
+ * gateway TG `/yolo` so wording stays in lockstep.
+ */
+export function applyYolo(permission: PermissionApi): ApplyResult {
+  const cur = permission.getMode()
+  const next: PermissionToggleMode = cur === 'off' ? 'prompt' : 'off'
+  permission.setMode(next)
+  return {
+    mode: next,
+    message:
+      next === 'off'
+        ? 'YOLO ON. Approval prompts disabled for this session.'
+        : 'YOLO OFF. Approvals back on.',
+  }
+}
+
+/**
+ * Set the permission mode explicitly. `arg === undefined` returns the current
+ * mode without mutation. Returns the same `{ message, mode }` shape so callers
+ * have one branch instead of two for "show vs set".
+ */
+export function applyPerms(
+  permission: PermissionApi,
+  arg: string | undefined,
+): ApplyResult | { message: string; mode: PermissionToggleMode; error: true } {
+  if (!arg) {
+    const mode = permission.getMode()
+    return { mode, message: `perms: ${mode}` }
+  }
+  const lower = arg.toLowerCase()
+  if (lower !== 'off' && lower !== 'prompt' && lower !== 'strict') {
+    return {
+      mode: permission.getMode(),
+      message: `unknown perms mode '${arg}'. try: off | prompt | strict`,
+      error: true,
+    }
+  }
+  permission.setMode(lower as PermissionToggleMode)
+  return { mode: lower as PermissionToggleMode, message: `perms set to ${lower}` }
+}

package/src/config.ts

@@ -0,0 +1,201 @@
+/**
+ * User-facing configuration shape for `lyra.config.ts`.
+ *
+ * Example:
+ *
+ *   import { defineConfig } from 'lyra-core'
+ *
+ *   export default defineConfig({
+ *     network: 'mainnet',                     // or 'testnet'
+ *     storage: { network: 'mainnet' },
+ *     brain: { model: 'gpt-4o-mini' },        // chosen at `lyra init`
+ *     plugins: ['onchain', 'system'],
+ *     tools: { 'defi.*': false, 'shell.run': false },
+ *     imports: { claudeCode: true },
+ *   })
+ */
+
+export type LyraNetwork = 'testnet' | 'mainnet'
+
+export type LyraPlugin = 'onchain' | 'comms' | 'system' | 'telegram'
+
+export type OperatorSourceKind = 'raw-privkey' | 'keystore-file'
+
+/**
+ * Persisted hint about which operator source to use when commands like
+ * `lyra` (chat) and `lyra drain` need to talk to the operator wallet
+ * again. Stores enough metadata to reconstruct the signer without re-prompting
+ * the user from scratch (passphrases / QR scans still happen per-session).
+ */
+export interface OperatorSourceHint {
+  source: OperatorSourceKind
+  /** Only for `keystore-file`: absolute or `~`-prefixed path to the JSON keystore. */
+  keystorePath?: string
+}
+
+export interface LyraConfig {
+  identity: {
+    /** Operator wallet address that encrypts (and can recover) the agent keystore. */
+    operator: string | null
+    /** Agent EOA address (separate key, signs + pays gas). */
+    agent: string | null
+  }
+  network: LyraNetwork
+  storage: {
+    network: LyraNetwork
+  }
+  brain: {
+    provider: string | null
+    model: string | null
+    /** Max assistant output tokens per turn. Default 4096. */
+    maxOutputTokens?: number
+    /**
+     * Model context window. Used for auto-compaction trigger. Default
+     * 1_000_000. Override for smaller models.
+     */
+    contextWindow?: number
+    /**
+     * Pre-flight summarize-fold of older history when the running estimate
+     * breaches `threshold * contextWindow`. Set to `null` to disable.
+     * Default: { threshold: 0.5, keepRecent: 8 }.
+     */
+    compaction?: {
+      threshold?: number
+      keepRecent?: number
+    } | null
+    /**
+     * Persist channel histories to JSONL under
+     * `~/.lyra/agents/<id>/conversations/`. Loaded on boot, appended per
+     * turn, atomically rewritten on compaction. Default true.
+     */
+    persistConversations?: boolean
+  }
+  plugins: LyraPlugin[]
+  /** Glob-level tool allow/deny. Right-most match wins. */
+  tools: Record<string, boolean>
+  imports: {
+    claudeCode: boolean
+  }
+  /**
+   * Which operator source to use when reconnecting. Optional so legacy configs
+   * still parse; commands fall back to the interactive picker when missing.
+   */
+  operator?: OperatorSourceHint | null
+  /**
+   * Permission system. `prompt` (default) prompts on dangerous commands;
+   * `strict` always denies them; `off` is YOLO (no prompts). The `--yolo` CLI
+   * flag and `/yolo` TUI slash both flip the active service to 'off' for the
+   * current session without rewriting the file.
+   */
+  approvals?: {
+    mode: 'strict' | 'prompt' | 'off'
+    /** Always-approved patterns (regex against `kind|command|path` signature). */
+    allowlist?: string[]
+  }
+  /**
+   * Skills system. `disabled` is the persistent list of skill ids that should
+   * never auto-load or appear in the index.
+   */
+  skills?: {
+    disabled?: string[]
+  }
+  /**
+   * Operator-supplied additions to the system prompt. `append` is concatenated
+   * under a `# Operator instructions` header AFTER lyra's built-in safety +
+   * tool-use scaffolding. Can NOT replace the base prompt; use it for personal
+   * rules ("always reply in Indonesian", "prefer Bun over npm").
+   */
+  prompt?: {
+    append?: string | null
+  }
+  /**
+   * Multimodal vision routing. Vision limbs (vision.analyze, browser.vision)
+   * call this OpenAI-compatible provider; the brain stays on `brain.provider`.
+   * Set `null` to disable; tools then return a clear "not configured" error.
+   */
+  vision?: {
+    provider?: string | null
+  }
+  /**
+   * Structural sandbox for limb spawns. Defense-in-depth BENEATH the permission
+   * floor — even when `s` (allow session) or yolo grants a destructive command,
+   * the sandbox profile prevents writes outside an allowlist (agentDir +
+   * workspaceRoot + /tmp/lyra-* + /var/folders).
+   *
+   *  - `none` (default): passthrough. Permission floor only.
+   *  - `os`: native OS sandbox. macOS = sandbox-exec wrapper. Linux = bubblewrap.
+   *  - `docker`: long-lived container per session, every spawn through `docker exec`.
+   */
+  sandbox?: {
+    mode?: 'none' | 'os' | 'docker'
+    /**
+     * docker mode only: container image. Default `oven/bun:1`. Compatible with
+     * Docker Desktop AND Podman. Override for custom tooling.
+     */
+    dockerImage?: string
+    /**
+     * docker mode only: bind-mount the host's workspaceRoot into the container
+     * at /workspace. Default `false` for max isolation.
+     */
+    dockerMountWorkspace?: boolean
+    /**
+     * docker mode only: force a specific container runtime binary. Auto-detect
+     * by default (tries docker, then podman).
+     */
+    dockerRuntimePath?: string
+    /** docker mode only: CPU cores cap (`--cpus`). Default unlimited. */
+    dockerCpu?: number
+    /** docker mode only: memory cap in MB (`--memory <N>m`). Default unlimited. */
+    dockerMemoryMb?: number
+    /**
+     * docker mode only: per-container writable-layer disk cap in MB. Linux +
+     * overlay2 with pquota only — silently dropped on macOS / podman.
+     */
+    dockerDiskMb?: number
+    /**
+     * docker mode only: block all network access from inside the container
+     * (`--network=none`). Default false.
+     */
+    dockerNoNetwork?: boolean
+  }
+}
+
+export type LyraConfigInput = Partial<LyraConfig> & Pick<LyraConfig, 'network'>
+
+const DEFAULT_CONFIG: Omit<LyraConfig, 'network' | 'storage'> = {
+  identity: { operator: null, agent: null },
+  brain: { provider: null, model: null },
+  plugins: ['onchain', 'system'],
+  tools: {},
+  imports: { claudeCode: true },
+  operator: null,
+  approvals: { mode: 'prompt', allowlist: [] },
+  skills: { disabled: [] },
+  prompt: { append: null },
+  vision: { provider: undefined },
+  sandbox: { mode: 'none' },
+}
+
+export function defineConfig(input: LyraConfigInput): LyraConfig {
+  return {
+    ...DEFAULT_CONFIG,
+    identity: input.identity ?? DEFAULT_CONFIG.identity,
+    network: input.network,
+    storage: input.storage ?? { network: input.network },
+    brain: input.brain ?? DEFAULT_CONFIG.brain,
+    plugins: input.plugins ?? DEFAULT_CONFIG.plugins,
+    tools: input.tools ?? DEFAULT_CONFIG.tools,
+    imports: input.imports ?? DEFAULT_CONFIG.imports,
+    operator: input.operator ?? DEFAULT_CONFIG.operator,
+    approvals: input.approvals ?? DEFAULT_CONFIG.approvals,
+    skills: input.skills ?? DEFAULT_CONFIG.skills,
+    prompt: input.prompt ?? DEFAULT_CONFIG.prompt,
+    vision: input.vision ?? DEFAULT_CONFIG.vision,
+    sandbox: input.sandbox ?? DEFAULT_CONFIG.sandbox,
+  }
+}
+
+export const NETWORK_RPC: Record<LyraNetwork, string> = {
+  mainnet: 'https://fullnode.mainnet.sui.io:443',
+  testnet: 'https://fullnode.testnet.sui.io:443',
+}

package/src/economy/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Economy module. The legacy decentralized-compute self-funding manager was
+ * removed with the 0G compute backend (Lyra uses an API-key LLM). Reserved
+ * for Sui-native economy primitives (treasury limits, spend caps, etc.).
+ */
+export {}

package/src/events/index.ts

@@ -0,0 +1,4 @@
+export type { LyraEvent, EventPayload, EventSource } from './types'
+export { EventQueue, newEventId } from './queue'
+export { type Listener, listeners } from './listeners'
+export { routeLoop, type RouterDeps } from './router'

package/src/events/listeners.ts

@@ -0,0 +1,37 @@
+import type { EventQueue } from './queue'
+
+/**
+ * A Listener watches some source (stdin, chain, a2a, ...) and pushes events
+ * onto the queue. Plugins contribute listeners via `registerListener()`.
+ */
+export interface Listener {
+  name: string
+  source: string
+  start(queue: EventQueue): Promise<void>
+  stop(): Promise<void>
+}
+
+class ListenerRegistry {
+  private registered: Listener[] = []
+
+  register(l: Listener): void {
+    if (this.registered.some(x => x.name === l.name)) {
+      throw new Error(`Listener already registered: ${l.name}`)
+    }
+    this.registered.push(l)
+  }
+
+  list(): readonly Listener[] {
+    return this.registered
+  }
+
+  async startAll(queue: EventQueue): Promise<void> {
+    await Promise.all(this.registered.map(l => l.start(queue)))
+  }
+
+  async stopAll(): Promise<void> {
+    await Promise.all(this.registered.map(l => l.stop()))
+  }
+}
+
+export const listeners = new ListenerRegistry()

package/src/events/queue.test.ts

@@ -0,0 +1,43 @@
+import { expect, test } from 'bun:test'
+import { EventQueue, newEventId } from './queue'
+
+test('FIFO ordering', async () => {
+  const q = new EventQueue()
+  for (let i = 0; i < 3; i++) {
+    q.enqueue({
+      id: newEventId(),
+      source: 'stdin',
+      payload: { label: `e${i}`, data: i },
+      ts: Date.now(),
+    })
+  }
+  const a = await q.dequeue()
+  const b = await q.dequeue()
+  const c = await q.dequeue()
+  expect(a.payload.label).toBe('e0')
+  expect(b.payload.label).toBe('e1')
+  expect(c.payload.label).toBe('e2')
+})
+
+test('dequeue awaits when empty', async () => {
+  const q = new EventQueue()
+  const pending = q.dequeue()
+  setTimeout(() => {
+    q.enqueue({
+      id: 'late',
+      source: 'stdin',
+      payload: { label: 'late', data: null },
+      ts: Date.now(),
+    })
+  }, 10)
+  const ev = await pending
+  expect(ev.payload.label).toBe('late')
+})
+
+test('closed queue throws on enqueue', () => {
+  const q = new EventQueue()
+  q.close()
+  expect(() =>
+    q.enqueue({ id: 'x', source: 'stdin', payload: { label: 'x', data: null }, ts: 0 }),
+  ).toThrow()
+})

package/src/events/queue.ts

@@ -0,0 +1,63 @@
+import type { LyraEvent } from './types'
+
+/**
+ * Minimal in-memory FIFO queue. Async-iterable so consumers `for await` over
+ * incoming events. Enqueue resolves immediately; dequeue awaits the next event.
+ */
+export class EventQueue {
+  private buffer: LyraEvent[] = []
+  private waiters: Array<(ev: LyraEvent) => void> = []
+  private closed = false
+
+  enqueue(ev: LyraEvent): void {
+    if (this.closed) throw new Error('EventQueue closed')
+    const w = this.waiters.shift()
+    if (w) {
+      w(ev)
+      return
+    }
+    this.buffer.push(ev)
+  }
+
+  async dequeue(): Promise<LyraEvent> {
+    const head = this.buffer.shift()
+    if (head) return head
+    if (this.closed) throw new Error('EventQueue closed')
+    return new Promise<LyraEvent>(resolve => {
+      this.waiters.push(resolve)
+    })
+  }
+
+  /** Close and wake all waiters with error. */
+  close(): void {
+    this.closed = true
+    for (const w of this.waiters) {
+      Promise.resolve().then(() => w({} as LyraEvent))
+    }
+    this.waiters = []
+  }
+
+  get length(): number {
+    return this.buffer.length
+  }
+
+  get isClosed(): boolean {
+    return this.closed
+  }
+
+  async *[Symbol.asyncIterator](): AsyncGenerator<LyraEvent> {
+    while (!this.closed) {
+      try {
+        yield await this.dequeue()
+      } catch {
+        return
+      }
+    }
+  }
+}
+
+let counter = 0
+export function newEventId(): string {
+  counter += 1
+  return `${Date.now().toString(36)}-${counter.toString(36)}`
+}

package/src/events/router.ts

@@ -0,0 +1,42 @@
+import type { Brain, BrainTurn } from '../brain/types'
+import type { ToolRegistry } from '../tools/registry'
+import type { EventQueue } from './queue'
+import type { LyraEvent } from './types'
+
+export interface RouterDeps {
+  brain: Brain
+  tools: ToolRegistry
+  onTurn?: (ev: LyraEvent, turn: BrainTurn) => void | Promise<void>
+}
+
+/**
+ * Pulls events from the queue, assembles a prompt via the brain, executes any
+ * returned tool_calls until the brain produces a final message, and yields
+ * the turn back via `onTurn`.
+ */
+export async function routeLoop(queue: EventQueue, deps: RouterDeps): Promise<void> {
+  for await (const ev of queue) {
+    if (!ev.source) continue // closed sentinel
+    await handleOne(ev, deps)
+  }
+}
+
+async function handleOne(ev: LyraEvent, deps: RouterDeps): Promise<void> {
+  // Seed conversation with the triggering event (stub does echo; real brain
+  // in phase 3 will load memory, assemble frozen prefix, etc.)
+  const turn = await deps.brain.infer({ event: ev })
+
+  // Resolve any tool calls in a single iteration for MVP — phase 3 extends
+  // this to a proper multi-turn loop.
+  for (const call of turn.toolCalls ?? []) {
+    const tool = deps.tools.find(call.name)
+    if (!tool) continue
+    try {
+      await tool.handler(call.args)
+    } catch {
+      // Tool errors are surfaced in activity log by the runtime, not here.
+    }
+  }
+
+  await deps.onTurn?.(ev, turn)
+}

package/src/events/types.ts

@@ -0,0 +1,28 @@
+/** Sources that can enqueue events into the runtime. */
+export type EventSource =
+  | 'stdin'
+  | 'cron'
+  | 'webhook'
+  | 'a2a'
+  | 'marketplace'
+  | 'chain'
+  | 'internal'
+  | 'telegram'
+
+export interface EventPayload {
+  /** Short human-readable label for logs/status. */
+  label: string
+  /** Arbitrary structured data. Listener-specific shape. */
+  data: unknown
+  /** Any peer address (ECIES pubkey or .0g name) that originated this event. */
+  peer?: string
+  /** Per-listener hint about which memory topics are relevant for this event. */
+  memoryHint?: string[]
+}
+
+export interface LyraEvent {
+  id: string
+  source: EventSource
+  payload: EventPayload
+  ts: number
+}

package/src/format.ts

@@ -0,0 +1,13 @@
+/**
+ * Render a MIST amount as a 6-decimal SUI string. Matches the statusline,
+ * `lyra balance`, and ledger output styles. Always emits exactly 6 decimal
+ * places (zero-padded) so columns align. 1 SUI = 1e9 MIST.
+ */
+export function formatSui(mist: bigint | string | number): string {
+  const m = typeof mist === 'bigint' ? mist : BigInt(mist)
+  const neg = m < 0n
+  const abs = neg ? -m : m
+  const whole = abs / 1_000_000_000n
+  const frac = (abs % 1_000_000_000n).toString().padStart(9, '0').slice(0, 6)
+  return `${neg ? '-' : ''}${whole}.${frac}`
+}