lyra-core 0.1.0

package/src/brain/types.ts

@@ -0,0 +1,129 @@
+import type { LyraEvent } from '../events/types'
+import type { ToolCall, ToolSchema } from '../tools/types'
+
+export interface BrainMessage {
+  role: 'system' | 'user' | 'assistant' | 'tool'
+  content: string
+  /** Required on `tool` role: the id of the assistant tool_call this responds to. */
+  toolCallId?: string
+  /**
+   * Required on `assistant` role messages that issued tool_calls. Without this
+   * the next round-trip's `tool` message has no preceding `tool_calls` to
+   * reference, and the OpenAI-compat endpoint rejects with HTTP 400
+   * "messages with role 'tool' must be a response to a preceeding message
+   * with 'tool_calls'".
+   */
+  toolCalls?: Array<{ id: string; name: string; args: unknown }>
+}
+
+/**
+ * Per-tool-call lifecycle event surfaced to the dispatcher for UI rendering.
+ * Distinct from the brain-construction `onToolCall` (which actually EXECUTES
+ * the tool); this is fire-and-forget for "show what the agent is doing right
+ * now" surfaces (TG progress message, future TUI bridge, etc.).
+ *
+ * Errors thrown by the observer are swallowed by the brain.
+ */
+export interface BrainToolEvent {
+  /** 'start' fires BEFORE tool execution; 'end' fires AFTER. */
+  kind: 'start' | 'end'
+  /** Fully-qualified tool name, e.g. `shell.run`. */
+  tool: string
+  /** Tool-call id; correlates start ↔ end pair within the same turn. */
+  callId: string
+  /** Short stringified args preview (≤ ~80 chars). Present on 'start'. */
+  argsPreview?: string
+  /** Tool execution success. Heuristic from result content. Present on 'end'. */
+  ok?: boolean
+}
+
+/**
+ * Compaction event surfaced when the brain auto-folds older history into a
+ * summary message. Subscribers (TUI primarily) use this to push a system row
+ * so the operator knows the summary fired. Errors thrown by the observer are
+ * swallowed by the brain.
+ */
+export interface BrainCompactionEvent {
+  /** Channel whose history was compacted. */
+  channelKey: string
+  /** Number of messages BEFORE compaction (full history length). */
+  from: number
+  /** Number of messages AFTER compaction (summary + kept recent). */
+  to: number
+  /** Token estimate of the pre-compaction history. */
+  promptTokens: number
+}
+
+export interface BrainInferInput {
+  /** The event that woke the brain. */
+  event: LyraEvent
+  /** Optional multi-turn context beyond the event payload. */
+  history?: BrainMessage[]
+  /** Optional tool allowlist override (defaults to all registered tools). */
+  toolWhitelist?: string[]
+  /**
+   * Channel partition for this turn's history. Each surface keeps its own
+   * conversation context: TUI/stdin is `'tui:stdin'`, Telegram DM is
+   * `agent:<name>:telegram:dm:<chatId>`, A2A drains use `a2a:<peer>`,
+   * marketplace uses `'marketplace'`. Missing key falls back to `'default'`.
+   *
+   * Backward-compatible: omitting the key keeps the legacy single-history
+   * behavior under the `'default'` channel.
+   */
+  channelKey?: string
+  /**
+   * Cancel the in-flight turn. Aborts the upstream HTTP fetch (so Sui
+   * Compute stops billing the round-trip immediately) and short-circuits
+   * the tool-call loop. The promise rejects with a DOMException whose
+   * `.name === 'AbortError'`. Caller should catch that and treat it as
+   * a clean operator-driven cancel, not an error.
+   */
+  signal?: AbortSignal
+  /**
+   * Per-turn observer of tool-call lifecycle. Fired by the brain before and
+   * after each tool execution. Use for UI streaming (TG progress message,
+   * TUI bridge) without bothering the brain-construction onToolCall (which
+   * is the actual tool executor). Errors swallowed by the brain.
+   */
+  onToolEvent?: (ev: BrainToolEvent) => void
+  /**
+   * Per-turn observer of compaction events. Fires when the pre-flight
+   * threshold check triggers a summarize-fold of older messages. TUI
+   * surfaces this as a system row; TG dispatchers leave it silent.
+   */
+  onCompactionEvent?: (ev: BrainCompactionEvent) => void
+}
+
+export interface BrainTurn {
+  content: string | null
+  toolCalls: ToolCall[]
+  reasoningContent?: string
+  finishReason?: string
+  usage?: {
+    promptTokens?: number
+    completionTokens?: number
+    totalTokens?: number
+    cachedTokens?: number
+  }
+}
+
+export interface Brain {
+  infer(input: BrainInferInput): Promise<BrainTurn>
+  /**
+   * v0.20.0: clear a channel's history. Optional so legacy non-OG brains
+   * (StubBrain etc) don't have to implement it.
+   */
+  clearChannel?(channelKey?: string): Promise<void> | void
+}
+
+export interface BrainProvider {
+  name: string
+  build(opts: BrainProviderOpts): Promise<Brain>
+}
+
+export interface BrainProviderOpts {
+  systemPrompt: string
+  tools: ToolSchema[]
+  maxTokens?: number
+  maxOutputTokens?: number
+}

package/src/chain.ts

@@ -0,0 +1,35 @@
+import { SuiClient, getFullnodeUrl } from '@mysten/sui/client'
+import { Ed25519Keypair } from '@mysten/sui/keypairs/ed25519'
+import type { LyraNetwork } from './config'
+
+/**
+ * Sui chain helpers for Lyra core. One agent keypair signs and pays gas; the
+ * deterministic policy (enforced on-chain by `lyra::policy`) bounds what it may
+ * do. Mirrors the patterns in `plugin-onchain/src/client.ts`.
+ */
+
+/** Canonical Sui fullnode JSON-RPC URL for a network. */
+export function suiRpcUrl(network: LyraNetwork): string {
+  return getFullnodeUrl(network)
+}
+
+/** A Sui JSON-RPC client for the given network. */
+export function makeSuiClient(network: LyraNetwork): SuiClient {
+  return new SuiClient({ url: getFullnodeUrl(network) })
+}
+
+/**
+ * Build a keypair from a secret. Accepts a Sui bech32 secret
+ * (`suiprivkey1...`, preferred) or a base64-encoded 32-byte seed.
+ */
+export function keypairFromSecret(secret: string): Ed25519Keypair {
+  const s = secret.trim()
+  if (s.startsWith('suiprivkey')) return Ed25519Keypair.fromSecretKey(s)
+  return Ed25519Keypair.fromSecretKey(Uint8Array.from(Buffer.from(s, 'base64')))
+}
+
+/** Total SUI balance of an address, in MIST (1 SUI = 1e9 MIST). */
+export async function getSuiBalanceMist(client: SuiClient, address: string): Promise<bigint> {
+  const { totalBalance } = await client.getBalance({ owner: address })
+  return BigInt(totalBalance)
+}

package/src/claude-plugins/discovery.test.ts

@@ -0,0 +1,71 @@
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { discoverClaudeExtras } from './discovery'
+
+let scratch: string
+
+beforeEach(async () => {
+  scratch = await mkdtemp(join(tmpdir(), 'lyra-claude-extras-'))
+})
+
+afterEach(async () => {
+  await rm(scratch, { recursive: true, force: true })
+})
+
+describe('discoverClaudeExtras', () => {
+  it('discovers commands + agents from plugin cache layout', async () => {
+    const versionDir = join(scratch, 'cache', 'mp', 'plug', '0.1.0')
+    await mkdir(join(versionDir, 'commands'), { recursive: true })
+    await mkdir(join(versionDir, 'agents'), { recursive: true })
+    await writeFile(
+      join(versionDir, 'commands', 'setup.md'),
+      '---\nname: setup\ndescription: Build pragma\n---\n\n# Setup body\n',
+    )
+    await writeFile(
+      join(versionDir, 'agents', 'thymos.md'),
+      '---\nname: thymos\ndescription: scalper\nmodel: sonnet\n---\n\n# Agent body\n',
+    )
+    const out = await discoverClaudeExtras({
+      claudePluginsCacheRoot: join(scratch, 'cache'),
+      importsClaudeCode: true,
+    })
+    expect(out.commands).toHaveLength(1)
+    expect(out.commands[0]!).toMatchObject({
+      id: 'plug:setup',
+      name: 'setup',
+      description: 'Build pragma',
+      source: { marketplace: 'mp', plugin: 'plug', version: '0.1.0' },
+    })
+    expect(out.commands[0]!.body).toContain('Setup body')
+    expect(out.agents).toHaveLength(1)
+    expect(out.agents[0]!).toMatchObject({
+      id: 'plug:thymos',
+      name: 'thymos',
+      model: 'sonnet',
+    })
+    expect(out.agents[0]!.body).toContain('Agent body')
+  })
+
+  it('returns empty when imports.claudeCode is false', async () => {
+    const out = await discoverClaudeExtras({
+      claudePluginsCacheRoot: join(scratch, 'cache'),
+      importsClaudeCode: false,
+    })
+    expect(out).toEqual({ commands: [], agents: [] })
+  })
+
+  it('skips files without frontmatter (still parses but with empty meta)', async () => {
+    const versionDir = join(scratch, 'cache', 'mp', 'plug', '0.1.0')
+    await mkdir(join(versionDir, 'commands'), { recursive: true })
+    await writeFile(join(versionDir, 'commands', 'foo.md'), 'no frontmatter just body')
+    const out = await discoverClaudeExtras({
+      claudePluginsCacheRoot: join(scratch, 'cache'),
+      importsClaudeCode: true,
+    })
+    expect(out.commands).toHaveLength(1)
+    expect(out.commands[0]!.name).toBe('foo')
+    expect(out.commands[0]!.body).toBe('no frontmatter just body')
+  })
+})

package/src/claude-plugins/discovery.ts

@@ -0,0 +1,152 @@
+import type { Dirent } from 'node:fs'
+import { readFile, readdir, stat } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import type { ClaudeAgent, ClaudeCommand, ClaudeExtrasDiscoveryResult } from './types'
+
+export interface ClaudeExtrasOptions {
+  importsClaudeCode?: boolean
+  /** Override for ~/.claude/plugins/cache/. */
+  claudePluginsCacheRoot?: string
+}
+
+export async function discoverClaudeExtras(
+  opts: ClaudeExtrasOptions = {},
+): Promise<ClaudeExtrasDiscoveryResult> {
+  const importsClaudeCode = opts.importsClaudeCode ?? true
+  if (!importsClaudeCode) return { commands: [], agents: [] }
+  const cacheRoot = opts.claudePluginsCacheRoot ?? join(homedir(), '.claude', 'plugins', 'cache')
+  const commands: ClaudeCommand[] = []
+  const agents: ClaudeAgent[] = []
+
+  let marketplaces: Dirent[]
+  try {
+    const s = await stat(cacheRoot)
+    if (!s.isDirectory()) return { commands, agents }
+    marketplaces = (await readdir(cacheRoot, { withFileTypes: true })) as Dirent[]
+  } catch {
+    return { commands, agents }
+  }
+
+  for (const market of marketplaces) {
+    if (!market.isDirectory()) continue
+    const marketDir = join(cacheRoot, market.name)
+    let plugins: Dirent[]
+    try {
+      plugins = (await readdir(marketDir, { withFileTypes: true })) as Dirent[]
+    } catch {
+      continue
+    }
+    for (const plugin of plugins) {
+      if (!plugin.isDirectory()) continue
+      const pluginDir = join(marketDir, plugin.name)
+      let versions: Dirent[]
+      try {
+        versions = (await readdir(pluginDir, { withFileTypes: true })) as Dirent[]
+      } catch {
+        continue
+      }
+      const versionDirs = versions
+        .filter(v => v.isDirectory())
+        .map(v => v.name)
+        .sort()
+      const latest = versionDirs[versionDirs.length - 1]
+      if (!latest) continue
+      const versionDir = join(pluginDir, latest)
+      const source = { marketplace: market.name, plugin: plugin.name, version: latest }
+      await collectFromDir(join(versionDir, 'commands'), source, 'command', commands, agents)
+      await collectFromDir(join(versionDir, 'agents'), source, 'agent', commands, agents)
+    }
+  }
+  return { commands, agents }
+}
+
+async function collectFromDir(
+  dir: string,
+  source: { marketplace: string; plugin: string; version: string },
+  kind: 'command' | 'agent',
+  commands: ClaudeCommand[],
+  agents: ClaudeAgent[],
+): Promise<void> {
+  let entries: Dirent[]
+  try {
+    const s = await stat(dir)
+    if (!s.isDirectory()) return
+    entries = (await readdir(dir, { withFileTypes: true })) as Dirent[]
+  } catch {
+    return
+  }
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith('.md')) continue
+    const filePath = join(dir, entry.name)
+    let raw: string
+    try {
+      raw = await readFile(filePath, 'utf8')
+    } catch {
+      continue
+    }
+    const parsed = parseFile(raw)
+    if (!parsed) continue
+    const id = `${source.plugin}:${parsed.name ?? entry.name.replace(/\.md$/, '')}`
+    const name = parsed.name ?? entry.name.replace(/\.md$/, '')
+    if (kind === 'command') {
+      commands.push({
+        id,
+        name,
+        description: parsed.description ?? '',
+        argumentHint: parsed.argumentHint,
+        path: filePath,
+        body: parsed.body,
+        source,
+      })
+    } else {
+      agents.push({
+        id,
+        name,
+        description: parsed.description ?? '',
+        model: parsed.model,
+        path: filePath,
+        body: parsed.body,
+        source,
+      })
+    }
+  }
+}
+
+interface ParsedFile {
+  name?: string
+  description?: string
+  argumentHint?: string
+  model?: string
+  body: string
+}
+
+function parseFile(raw: string): ParsedFile | null {
+  if (!raw.startsWith('---')) {
+    return { body: raw }
+  }
+  const end = raw.indexOf('\n---', 4)
+  if (end === -1) return { body: raw }
+  const block = raw.slice(4, end)
+  const body = raw.slice(end + 4).replace(/^\n/, '')
+  const out: ParsedFile = { body }
+  for (const line of block.split('\n')) {
+    const m = line.match(/^([a-zA-Z][a-zA-Z0-9_-]*):\s*(.*)$/)
+    if (!m?.[1]) continue
+    const key = m[1]
+    const value = unquote(m[2] ?? '')
+    if (key === 'name') out.name = value
+    else if (key === 'description') out.description = value
+    else if (key === 'argument-hint' || key === 'argumentHint') out.argumentHint = value
+    else if (key === 'model') out.model = value
+  }
+  return out
+}
+
+function unquote(s: string): string {
+  const t = s.trim()
+  if ((t.startsWith('"') && t.endsWith('"')) || (t.startsWith("'") && t.endsWith("'"))) {
+    return t.slice(1, -1)
+  }
+  return t
+}

package/src/claude-plugins/index.ts

@@ -0,0 +1,6 @@
+export { discoverClaudeExtras, type ClaudeExtrasOptions } from './discovery'
+export type {
+  ClaudeCommand,
+  ClaudeAgent,
+  ClaudeExtrasDiscoveryResult,
+} from './types'

package/src/claude-plugins/types.ts

@@ -0,0 +1,38 @@
+/**
+ * Phase 9.2 Bundle 8 surfaces: Claude Code commands + agents discovered from
+ * the local plugin cache. Both are markdown files with YAML frontmatter; the
+ * body is the prompt that lyra inlines when the command/agent fires.
+ */
+
+export interface ClaudeCommand {
+  /** `<plugin>:<name>` (lyra drops the marketplace prefix; the cmd surface is flat). */
+  id: string
+  /** Bare command name (e.g. `setup`, `mode`, `commit`). */
+  name: string
+  description: string
+  /** Optional argument-hint shown after the slash command in help. */
+  argumentHint?: string
+  /** Absolute path to the markdown file. */
+  path: string
+  /** Body without frontmatter; this is the prompt template lyra inlines. */
+  body: string
+  /** Source plugin coordinates (marketplace, plugin, version). */
+  source: { marketplace: string; plugin: string; version: string }
+}
+
+export interface ClaudeAgent {
+  /** `<plugin>:<name>` */
+  id: string
+  name: string
+  description: string
+  /** Optional model hint from frontmatter (e.g. `sonnet`). lyra ignores it (uses configured brain). */
+  model?: string
+  path: string
+  body: string
+  source: { marketplace: string; plugin: string; version: string }
+}
+
+export interface ClaudeExtrasDiscoveryResult {
+  commands: ClaudeCommand[]
+  agents: ClaudeAgent[]
+}

package/src/commands/index.ts

@@ -0,0 +1,16 @@
+export {
+  COMMAND_REGISTRY,
+  applyPerms,
+  applyYolo,
+  commandsForSurface,
+  findCommand,
+  parseSlash,
+  suggestForPrefix,
+  type ApplyResult,
+  type CommandScope,
+  type CommandSurface,
+  type ParsedSlash,
+  type PermissionApi,
+  type PermissionToggleMode,
+  type SlashCommand,
+} from './registry'

package/src/commands/registry.test.ts

@@ -0,0 +1,186 @@
+import { describe, expect, it } from 'bun:test'
+import {
+  COMMAND_REGISTRY,
+  commandsForSurface,
+  findCommand,
+  parseSlash,
+  suggestForPrefix,
+} from './registry'
+
+describe('COMMAND_REGISTRY', () => {
+  it('has no duplicate names', () => {
+    const names = COMMAND_REGISTRY.map(c => c.name)
+    const set = new Set(names)
+    expect(set.size).toBe(names.length)
+  })
+
+  it('every entry has at least one surface', () => {
+    for (const c of COMMAND_REGISTRY) {
+      expect(c.surfaces.length).toBeGreaterThan(0)
+    }
+  })
+
+  it('every entry has a non-empty description', () => {
+    for (const c of COMMAND_REGISTRY) {
+      expect(c.description.length).toBeGreaterThan(0)
+    }
+  })
+
+  it('all names are lowercase, no leading slash', () => {
+    for (const c of COMMAND_REGISTRY) {
+      expect(c.name).toBe(c.name.toLowerCase())
+      expect(c.name.startsWith('/')).toBe(false)
+    }
+  })
+
+  it('contains the cross-surface bypass commands required for v0.20.0', () => {
+    expect(findCommand('yolo')).toBeDefined()
+    expect(findCommand('perms')).toBeDefined()
+    expect(findCommand('reset')).toBeDefined()
+    expect(findCommand('yolo')?.surfaces).toEqual(['tui', 'tg'])
+    expect(findCommand('perms')?.surfaces).toEqual(['tui', 'tg'])
+    expect(findCommand('reset')?.surfaces).toEqual(['tui', 'tg'])
+  })
+})
+
+describe('commandsForSurface', () => {
+  it('returns only TUI commands when surface=tui', () => {
+    const tui = commandsForSurface('tui')
+    expect(tui.length).toBeGreaterThan(0)
+    for (const c of tui) expect(c.surfaces).toContain('tui')
+  })
+
+  it('returns only TG commands when surface=tg', () => {
+    const tg = commandsForSurface('tg')
+    expect(tg.length).toBeGreaterThan(0)
+    for (const c of tg) expect(c.surfaces).toContain('tg')
+  })
+
+  it('cross-surface commands appear in both lists', () => {
+    const tui = commandsForSurface('tui').map(c => c.name)
+    const tg = commandsForSurface('tg').map(c => c.name)
+    expect(tui).toContain('yolo')
+    expect(tg).toContain('yolo')
+    expect(tui).toContain('perms')
+    expect(tg).toContain('perms')
+    expect(tui).toContain('reset')
+    expect(tg).toContain('reset')
+  })
+
+  it('TUI-only commands do not appear in TG', () => {
+    const tg = commandsForSurface('tg').map(c => c.name)
+    expect(tg).not.toContain('sync')
+    expect(tg).not.toContain('model')
+    expect(tg).not.toContain('jobs')
+    expect(tg).not.toContain('help')
+  })
+
+  it('TG-only commands do not appear in TUI', () => {
+    const tui = commandsForSurface('tui').map(c => c.name)
+    expect(tui).not.toContain('stop')
+    expect(tui).not.toContain('new')
+    expect(tui).not.toContain('status')
+    expect(tui).not.toContain('approve')
+  })
+})
+
+describe('findCommand', () => {
+  it('resolves bare names', () => {
+    expect(findCommand('yolo')?.name).toBe('yolo')
+  })
+
+  it('strips leading slashes', () => {
+    expect(findCommand('/yolo')?.name).toBe('yolo')
+    expect(findCommand('//yolo')?.name).toBe('yolo')
+  })
+
+  it('is case-insensitive', () => {
+    expect(findCommand('YOLO')?.name).toBe('yolo')
+    expect(findCommand('Yolo')?.name).toBe('yolo')
+  })
+
+  it('returns undefined for unknown names', () => {
+    expect(findCommand('definitely-not-a-command')).toBeUndefined()
+  })
+})
+
+describe('parseSlash', () => {
+  it('returns null for non-slash input', () => {
+    expect(parseSlash('hello')).toBeNull()
+    expect(parseSlash('  hi /yolo')).toBeNull()
+  })
+
+  it('returns null for empty slash', () => {
+    expect(parseSlash('/')).toBeNull()
+    expect(parseSlash('   /   ')).toBeNull()
+  })
+
+  it('parses bare command name', () => {
+    const r = parseSlash('/yolo')
+    expect(r?.name).toBe('yolo')
+    expect(r?.args).toEqual([])
+    expect(r?.command?.name).toBe('yolo')
+  })
+
+  it('parses command with args', () => {
+    const r = parseSlash('/perms strict')
+    expect(r?.name).toBe('perms')
+    expect(r?.args).toEqual(['strict'])
+    expect(r?.command?.name).toBe('perms')
+  })
+
+  it('lowercases the command name', () => {
+    const r = parseSlash('/YOLO')
+    expect(r?.name).toBe('yolo')
+  })
+
+  it('preserves arg case', () => {
+    const r = parseSlash('/perms STRICT')
+    expect(r?.args).toEqual(['STRICT'])
+  })
+
+  it('returns parsed shape with undefined command for unknown names', () => {
+    const r = parseSlash('/wat is this')
+    expect(r?.name).toBe('wat')
+    expect(r?.args).toEqual(['is', 'this'])
+    expect(r?.command).toBeUndefined()
+  })
+
+  it('tolerates leading whitespace', () => {
+    const r = parseSlash('   /yolo on')
+    expect(r?.name).toBe('yolo')
+    expect(r?.args).toEqual(['on'])
+  })
+})
+
+describe('suggestForPrefix', () => {
+  it('returns all surface commands for empty query', () => {
+    const all = commandsForSurface('tui')
+    expect(suggestForPrefix('tui', '')).toEqual(all)
+    expect(suggestForPrefix('tui', '/')).toEqual(all)
+  })
+
+  it('filters by prefix', () => {
+    const out = suggestForPrefix('tui', 'y')
+    const names = out.map(c => c.name)
+    expect(names).toContain('yolo')
+    expect(names).not.toContain('perms')
+  })
+
+  it('strips leading slash from query', () => {
+    expect(suggestForPrefix('tui', '/y').map(c => c.name)).toContain('yolo')
+  })
+
+  it('is case-insensitive on query', () => {
+    expect(suggestForPrefix('tui', 'YO').map(c => c.name)).toContain('yolo')
+  })
+
+  it('returns empty when nothing matches', () => {
+    expect(suggestForPrefix('tui', 'xyz-no-match')).toEqual([])
+  })
+
+  it('respects surface filter', () => {
+    const tg = suggestForPrefix('tg', 'sy').map(c => c.name)
+    expect(tg).not.toContain('sync')
+  })
+})