lyra-core 0.1.0

package/src/plugins/context.ts

@@ -0,0 +1,226 @@
+import type { ClaudeAgent } from '../claude-plugins/types'
+import type { LyraNetwork } from '../config'
+import type { Listener } from '../events/listeners'
+import type { SandboxBackend } from '../sandbox/types'
+import type { ToolRegistry } from '../tools/registry'
+import type { ToolDef, ToolSchema } from '../tools/types'
+import type { HookBus, HookHandler, HookName } from './hooks'
+
+/** Vision inputs for image-capable models (provider-agnostic). */
+export type VisionInferImage = { bytes: Uint8Array; mediaType: string }
+export type VisionInferInput = {
+  prompt: string
+  images: VisionInferImage[]
+  maxOutputTokens?: number
+}
+export type VisionInferResult = {
+  content: string
+  model?: string | null
+  usage?: {
+    promptTokens?: number
+    completionTokens?: number
+    totalTokens?: number
+    cachedTokens?: number
+  }
+  finishReason?: string
+}
+export type VisionInferFn = (input: VisionInferInput) => Promise<VisionInferResult>
+
+/**
+ * Factory chat.tsx supplies for `delegate.task` to spin up a sub-brain. The
+ * implementation typically wraps `OGComputeBrain` with a custom system prompt
+ * + restricted tool surface.
+ */
+export interface DelegateBrainFactoryOpts {
+  systemPrompt: string
+  tools: ToolSchema[]
+}
+
+export interface DelegateBrainTurn {
+  content: string | null
+  finishReason?: string
+  toolCalls?: Array<{ id: string; name: string; args: unknown }>
+  usage?: {
+    totalTokens?: number
+    cachedTokens?: number
+    promptTokens?: number
+    completionTokens?: number
+  }
+}
+
+export interface DelegateBrainHandle {
+  infer(input: {
+    event: { id: string; source: 'stdin'; payload: { label: string; data: string }; ts: number }
+  }): Promise<DelegateBrainTurn>
+}
+
+export type DelegateBrainFactory = (opts: DelegateBrainFactoryOpts) => Promise<DelegateBrainHandle>
+
+/**
+ * Context handed to a plugin's `register(ctx)` function. Plugins use this
+ * to contribute tools, listeners, and lifecycle hooks; we deliberately
+ * keep the surface tiny so future plugin features extend it without
+ * breaking existing native plugins.
+ */
+export interface PluginContext {
+  registerTool: (def: ToolDef) => void
+  registerListener: (l: Listener) => void
+  addHook: <TIn = unknown, TOut = void>(name: HookName, fn: HookHandler<TIn, TOut>) => void
+  /** Network the agent is configured for. */
+  network: LyraNetwork
+  /** Agent state directory (`~/.lyra/agents/<id>/`). */
+  agentDir: string
+  /** Per-agent unique id (matches `iNFTAgentId(...)` for non-stub agents). */
+  agentId: string
+  /** Absolute path to ~/.lyra/config.ts. Plugins that persist user-level state write here. */
+  configPath: string
+  /** Imports surface from config (e.g. claudeCode toggle for skills + MCP discovery). */
+  imports: { claudeCode: boolean }
+  /**
+   * Mutable cell holding the user-disabled skill ids. Plugin tools that
+   * change the list update this, and the chat rebuilds the skill index from
+   * the current value next turn.
+   */
+  skillsDisabled: { current: string[] }
+  /** Path to the agent's activity log (~/.lyra/agents/<id>/activity.jsonl). */
+  activityLogPath: string
+  /** Workspace cwd. Used by tools that spawn subprocesses. */
+  workspaceRoot: string
+  /**
+   * Sub-brain factory (Phase 9.3 delegate.task). Chat.tsx supplies a closure
+   * that builds an OGComputeBrain with broker creds. Tools without a brain
+   * dependency ignore this.
+   */
+  delegateFactory?: DelegateBrainFactory
+  /** Claude Code agents discovered from the local plugin cache. */
+  claudeAgents: ClaudeAgent[]
+  /** Whether the configured brain supports image inputs. */
+  brainSupportsVision: boolean
+  /** Brain model label (string). Surfaces in tool error messages. */
+  brainModelLabel: string | null
+  /**
+   * v0.11 vision routing: when set, vision.analyze + browser.vision call
+   * this function (backed by a BrokerPool entry pinned to the configured
+   * vision provider). Null when no vision provider is configured.
+   */
+  visionInfer?: VisionInferFn | null
+  /**
+   * Phase 9.5: sandbox backend wrapping every spawn() in shell.run / code.execute /
+   * shell.process_start. Optional for back-compat: legacy callers + tests that
+   * don't supply one get a LocalBackend (passthrough) inside the plugin.
+   */
+  sandbox?: SandboxBackend
+  /**
+   * Phase 7 side-band runtime context for plugin-comms. Opaque to core; the
+   * plugin reads its concrete shape via a typed cast. Holding the field as
+   * `unknown` keeps core free of a back-edge to the comms package.
+   */
+  comms?: unknown
+  /**
+   * Phase 10 side-band runtime context for plugin-onchain. Same opaque
+   * pattern as `comms`.
+   */
+  onchain?: unknown
+  /**
+   * Phase 12 side-band runtime context for plugin-telegram. Same opaque
+   * pattern: chat.tsx (local) or build-runtime.ts (sandbox) builds the typed
+   * `TelegramRuntimeContext` and passes it; the plugin casts on read.
+   */
+  telegram?: unknown
+}
+
+export interface NativePlugin {
+  name: string
+  register: (ctx: PluginContext) => void | Promise<void>
+}
+
+export interface PluginLoadResult {
+  loaded: string[]
+  errors: { plugin: string; error: string }[]
+}
+
+export interface PluginLoaderDeps {
+  tools: ToolRegistry
+  hooks: HookBus
+  listeners: { register: (l: Listener) => void }
+  agentDir: string
+  agentId: string
+  network: LyraNetwork
+  configPath: string
+  imports: { claudeCode: boolean }
+  skillsDisabled: { current: string[] }
+  activityLogPath: string
+  workspaceRoot: string
+  delegateFactory?: DelegateBrainFactory
+  claudeAgents?: ClaudeAgent[]
+  brainSupportsVision?: boolean
+  brainModelLabel?: string | null
+  visionInfer?: VisionInferFn | null
+  /** Phase 9.5 sandbox backend, propagated to plugin context. Optional. */
+  sandbox?: SandboxBackend
+  /** Phase 7 side-band runtime context for plugin-comms. Opaque to core. */
+  comms?: unknown
+  /** Phase 10 side-band runtime context for plugin-onchain. Opaque to core. */
+  onchain?: unknown
+  /** Phase 12 side-band runtime context for plugin-telegram. Opaque to core. */
+  telegram?: unknown
+  /**
+   * Resolver for `name` → ESM module path. Defaults to dynamic import of
+   * `lyra-ai-plugin-<name>`. Tests pass a stub.
+   */
+  resolve?: (name: string) => Promise<{ default?: NativePlugin } & Partial<NativePlugin>>
+}
+
+export async function loadPlugins(
+  names: readonly string[],
+  deps: PluginLoaderDeps,
+): Promise<PluginLoadResult> {
+  const loaded: string[] = []
+  const errors: PluginLoadResult['errors'] = []
+  const ctx: PluginContext = {
+    registerTool: def => deps.tools.register(def),
+    registerListener: l => deps.listeners.register(l),
+    addHook: (name, fn) => deps.hooks.add(name, fn),
+    network: deps.network,
+    agentDir: deps.agentDir,
+    agentId: deps.agentId,
+    configPath: deps.configPath,
+    imports: deps.imports,
+    skillsDisabled: deps.skillsDisabled,
+    activityLogPath: deps.activityLogPath,
+    workspaceRoot: deps.workspaceRoot,
+    delegateFactory: deps.delegateFactory,
+    claudeAgents: deps.claudeAgents ?? [],
+    brainSupportsVision: deps.brainSupportsVision ?? false,
+    brainModelLabel: deps.brainModelLabel ?? null,
+    visionInfer: deps.visionInfer ?? null,
+    sandbox: deps.sandbox,
+    comms: deps.comms,
+    onchain: deps.onchain,
+    telegram: deps.telegram,
+  }
+  for (const name of names) {
+    try {
+      const mod = deps.resolve
+        ? await deps.resolve(name)
+        : ((await import(`lyra-ai-plugin-${name}`)) as {
+            default?: NativePlugin
+          } & Partial<NativePlugin>)
+      const plugin: NativePlugin | undefined =
+        mod.default && 'register' in mod.default
+          ? mod.default
+          : 'register' in mod && typeof mod.register === 'function'
+            ? (mod as unknown as NativePlugin)
+            : undefined
+      if (!plugin) {
+        errors.push({ plugin: name, error: 'no exported register(ctx)' })
+        continue
+      }
+      await plugin.register(ctx)
+      loaded.push(name)
+    } catch (e) {
+      errors.push({ plugin: name, error: (e as Error).message ?? String(e) })
+    }
+  }
+  return { loaded, errors }
+}

package/src/plugins/hooks.ts

@@ -0,0 +1,81 @@
+import type { ToolCall, ToolResult } from '../tools/types'
+
+/**
+ * Lifecycle hook surface. Plugins register handlers via `ctx.addHook(name, fn)`.
+ * Hooks run in registration order; pre-* hooks may return a replacement
+ * payload to mutate the input, while post-* hooks observe only.
+ *
+ * Phase 9.0 wires `pre_tool_call` + `post_tool_call` into the chat loop.
+ * The other 8 names exist as no-op stubs so plugins can target them now and
+ * future phases (LLM call, session lifecycle) can light them up without
+ * breaking the contract.
+ */
+export type HookName =
+  | 'pre_tool_call'
+  | 'post_tool_call'
+  | 'pre_llm_call'
+  | 'post_llm_call'
+  | 'pre_api_request'
+  | 'post_api_request'
+  | 'on_session_start'
+  | 'on_session_end'
+  | 'on_session_finalize'
+  | 'on_session_reset'
+
+export interface PreToolCallContext {
+  call: ToolCall
+}
+
+export interface PreToolCallResult {
+  /** Replacement call (e.g. permission injection edits args). undefined = no change. */
+  call?: ToolCall
+  /** If set, short-circuit dispatch with this result. */
+  short?: ToolResult
+}
+
+export interface PostToolCallContext {
+  call: ToolCall
+  result: ToolResult
+}
+
+export type HookHandler<TIn, TOut = void> = (
+  ctx: TIn,
+) => Promise<TOut | undefined> | TOut | undefined
+
+export class HookBus {
+  private readonly handlers = new Map<HookName, HookHandler<unknown, unknown>[]>()
+
+  add<TIn = unknown, TOut = void>(name: HookName, fn: HookHandler<TIn, TOut>): void {
+    const list = this.handlers.get(name) ?? []
+    list.push(fn as HookHandler<unknown, unknown>)
+    this.handlers.set(name, list)
+  }
+
+  /**
+   * Run pre-tool-call hooks in order. Each handler may return a replacement
+   * call or a short-circuit result. The first short-circuit wins. Returns the
+   * effective call + optional short-circuit.
+   */
+  async runPreToolCall(input: PreToolCallContext): Promise<PreToolCallResult> {
+    let current: ToolCall = input.call
+    const fns = this.handlers.get('pre_tool_call') ?? []
+    for (const fn of fns) {
+      const out = (await fn({ call: current })) as PreToolCallResult | undefined
+      if (!out) continue
+      if (out.short) return { short: out.short, call: current }
+      if (out.call) current = out.call
+    }
+    return { call: current }
+  }
+
+  async runPostToolCall(input: PostToolCallContext): Promise<void> {
+    const fns = this.handlers.get('post_tool_call') ?? []
+    for (const fn of fns) {
+      try {
+        await fn(input)
+      } catch {
+        // Post hooks must never break the chat loop.
+      }
+    }
+  }
+}

package/src/plugins/index.ts

@@ -0,0 +1,24 @@
+export {
+  HookBus,
+  type HookName,
+  type HookHandler,
+  type PreToolCallContext,
+  type PreToolCallResult,
+  type PostToolCallContext,
+} from './hooks'
+export {
+  loadPlugins,
+  type PluginContext,
+  type NativePlugin,
+  type PluginLoadResult,
+  type PluginLoaderDeps,
+  type DelegateBrainFactory,
+  type DelegateBrainFactoryOpts,
+  type DelegateBrainHandle,
+  type DelegateBrainTurn,
+  type VisionInferFn,
+  type VisionInferInput,
+  type VisionInferImage,
+  type VisionInferResult,
+} from './context'
+export { makeToolSearchTool, type ToolSearchArgs } from './tool-search'

package/src/plugins/plugins.test.ts

@@ -0,0 +1,196 @@
+import { describe, expect, it } from 'bun:test'
+import { z } from 'zod'
+import { ToolRegistry } from '../tools/registry'
+import type { ToolDef } from '../tools/types'
+import { type NativePlugin, loadPlugins } from './context'
+import { HookBus, type PreToolCallContext, type PreToolCallResult } from './hooks'
+import { makeToolSearchTool } from './tool-search'
+
+describe('ToolRegistry deferred-tool semantics', () => {
+  function makeTools() {
+    const r = new ToolRegistry()
+    r.register({
+      name: 'fs.read',
+      description: 'read a file',
+      schema: z.object({ path: z.string() }),
+      handler: () => ({ ok: true }),
+    })
+    r.register({
+      name: 'browser.navigate',
+      description: 'navigate the browser to a URL',
+      shouldDefer: true,
+      searchHint: 'browser web automation page',
+      schema: z.object({ url: z.string() }),
+      handler: () => ({ ok: true }),
+    })
+    return r
+  }
+
+  it('eager tools appear in schemas; deferred tools do not until unlocked', () => {
+    const r = makeTools()
+    const before = r.schemas().map(s => s.function.name)
+    expect(before).toContain('fs.read')
+    expect(before).not.toContain('browser.navigate')
+    r.unlock('browser.navigate')
+    const after = r.schemas().map(s => s.function.name)
+    expect(after).toContain('browser.navigate')
+  })
+
+  it('search by select:name returns exact tools', () => {
+    const r = makeTools()
+    const matches = r.search('select:fs.read,browser.navigate')
+    expect(matches.map(t => t.name).sort()).toEqual(['browser.navigate', 'fs.read'])
+  })
+
+  it('keyword search matches deferred tools via searchHint', () => {
+    const r = makeTools()
+    const matches = r.search('browser web')
+    expect(matches.map(t => t.name)).toContain('browser.navigate')
+  })
+
+  it('config glob deny propagates through schemas + dispatch', async () => {
+    const r = new ToolRegistry({ 'fs.*': false })
+    r.register({
+      name: 'fs.read',
+      description: 'x',
+      schema: z.object({}),
+      handler: () => ({ ok: true }),
+    })
+    expect(r.schemas()).toEqual([])
+    const out = await r.dispatch({ id: '1', name: 'fs.read', args: {} })
+    expect(out.ok).toBe(false)
+  })
+})
+
+describe('HookBus', () => {
+  it('runs pre_tool_call handlers in order, supports rewrite + short-circuit', async () => {
+    const bus = new HookBus()
+    bus.add<PreToolCallContext, PreToolCallResult>('pre_tool_call', ({ call }) => ({
+      call: { ...call, args: { mutated: true } },
+    }))
+    bus.add<PreToolCallContext, PreToolCallResult>('pre_tool_call', () => ({
+      short: { ok: false, error: 'denied' },
+    }))
+    const out = await bus.runPreToolCall({
+      call: { id: '1', name: 't', args: {} },
+    })
+    expect(out.short).toEqual({ ok: false, error: 'denied' })
+    expect(out.call?.args).toEqual({ mutated: true })
+  })
+
+  it('post_tool_call observers cannot break the loop', async () => {
+    const bus = new HookBus()
+    bus.add('post_tool_call', () => {
+      throw new Error('boom')
+    })
+    let observed = false
+    bus.add('post_tool_call', () => {
+      observed = true
+    })
+    await bus.runPostToolCall({
+      call: { id: '1', name: 't', args: {} },
+      result: { ok: true },
+    })
+    expect(observed).toBe(true)
+  })
+})
+
+describe('loadPlugins', () => {
+  it('discovers + invokes register(ctx) per plugin', async () => {
+    const r = new ToolRegistry()
+    const bus = new HookBus()
+    let listenerCount = 0
+    const plugin: NativePlugin = {
+      name: 'fake',
+      register: ctx => {
+        ctx.registerTool({
+          name: 'fake.tool',
+          description: 'x',
+          schema: z.object({}),
+          handler: () => ({ ok: true }),
+        })
+        ctx.addHook('pre_tool_call', () => undefined)
+      },
+    }
+    const result = await loadPlugins(['fake'], {
+      tools: r,
+      hooks: bus,
+      listeners: { register: () => listenerCount++ },
+      agentDir: '/tmp/agent',
+      agentId: 'agent-x',
+      network: 'mainnet',
+      configPath: '/tmp/agent/config.ts',
+      imports: { claudeCode: false },
+      skillsDisabled: { current: [] },
+      activityLogPath: '/tmp/agent/activity.jsonl',
+      workspaceRoot: '/tmp/agent',
+      resolve: async () => ({ default: plugin }),
+    })
+    expect(result.loaded).toEqual(['fake'])
+    expect(result.errors).toEqual([])
+    expect(r.find('fake.tool')).toBeDefined()
+  })
+
+  it('reports errors without throwing', async () => {
+    const r = new ToolRegistry()
+    const bus = new HookBus()
+    const result = await loadPlugins(['broken'], {
+      tools: r,
+      hooks: bus,
+      listeners: { register: () => {} },
+      agentDir: '/tmp/agent',
+      agentId: 'agent-x',
+      network: 'mainnet',
+      configPath: '/tmp/agent/config.ts',
+      imports: { claudeCode: false },
+      skillsDisabled: { current: [] },
+      activityLogPath: '/tmp/agent/activity.jsonl',
+      workspaceRoot: '/tmp/agent',
+      resolve: async () => {
+        throw new Error('module not found')
+      },
+    })
+    expect(result.loaded).toEqual([])
+    expect(result.errors[0]?.error).toContain('module not found')
+  })
+})
+
+describe('makeToolSearchTool', () => {
+  it('select query unlocks deferred tools', async () => {
+    const r = new ToolRegistry()
+    r.register({
+      name: 'fs.write',
+      description: 'write a file',
+      shouldDefer: true,
+      searchHint: 'filesystem write text file',
+      schema: z.object({ path: z.string(), text: z.string() }),
+      handler: () => ({ ok: true }),
+    })
+    const meta = makeToolSearchTool(r)
+    r.register(meta as ToolDef)
+    expect(r.schemas().map(s => s.function.name)).toContain('tool.search')
+    expect(r.schemas().map(s => s.function.name)).not.toContain('fs.write')
+    const result = await meta.handler({ query: 'select:fs.write' })
+    expect(result.ok).toBe(true)
+    expect(r.schemas().map(s => s.function.name)).toContain('fs.write')
+    const data = result.data as { tools: Array<{ name: string }> }
+    expect(data.tools.map(t => t.name)).toEqual(['fs.write'])
+  })
+
+  it('keyword query matches by description and hint', async () => {
+    const r = new ToolRegistry()
+    r.register({
+      name: 'browser.navigate',
+      description: 'navigate the browser',
+      shouldDefer: true,
+      searchHint: 'browser web automation',
+      schema: z.object({ url: z.string() }),
+      handler: () => ({ ok: true }),
+    })
+    const meta = makeToolSearchTool(r)
+    r.register(meta as ToolDef)
+    const result = await meta.handler({ query: 'browser web' })
+    const data = result.data as { matched: number }
+    expect(data.matched).toBe(1)
+  })
+})

package/src/plugins/tool-search.ts

@@ -0,0 +1,49 @@
+import { z } from 'zod'
+import type { ToolRegistry } from '../tools/registry'
+import type { ToolDef } from '../tools/types'
+import { coerceInt } from '../tools/zod-helpers'
+import { zodToJsonSchema } from '../tools/zod-schema'
+
+const ToolSearchSchema = z.object({
+  query: z.string().min(1, 'query is required'),
+  max_results: coerceInt.refine(n => n > 0 && n <= 20, 'max_results must be 1..20').optional(),
+})
+
+export type ToolSearchArgs = z.infer<typeof ToolSearchSchema>
+
+/**
+ * `tool.search` meta-tool: brain calls this to hydrate deferred tool
+ * schemas. Mirrors Claude Code's ToolSearch surface, accepts either an
+ * explicit `select:foo,bar` query or a free-text keyword query.
+ */
+export function makeToolSearchTool(registry: ToolRegistry): ToolDef<ToolSearchArgs> {
+  return {
+    name: 'tool.search',
+    description:
+      'Look up deferred tool schemas. Use `select:name1,name2` to fetch by name, or free-text keywords (e.g., "filesystem read") to search descriptions and hints. Returns matching tools with their full parameter schema; the brain can immediately call them next turn.',
+    alwaysLoad: true,
+    searchHint: 'meta search deferred tools schemas',
+    schema: ToolSearchSchema,
+    handler: args => {
+      const max = args.max_results ?? 5
+      const matches = registry.search(args.query, max)
+      const schemas = matches.map(t => {
+        registry.unlock(t.name)
+        return {
+          name: t.name,
+          description: t.description,
+          parameters: t.parametersOverride ?? zodToJsonSchema(t.schema),
+          searchHint: t.searchHint,
+        }
+      })
+      return {
+        ok: true,
+        data: {
+          query: args.query,
+          matched: schemas.length,
+          tools: schemas,
+        },
+      }
+    },
+  }
+}

package/src/public/card.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, test } from 'bun:test'
+import { cardToTextRecords, emptyCard, parseCard, renderCard } from './card'
+
+describe('card', () => {
+  test('parses frontmatter + body', () => {
+    const md = `---
+name: Alice
+bio: research lyra
+skills:
+  - research
+  - writing
+---
+
+Free-form body here.`
+    const c = parseCard(md)
+    expect(c.frontmatter.name).toBe('Alice')
+    expect(c.frontmatter.bio).toBe('research lyra')
+    expect(c.frontmatter.skills).toEqual(['research', 'writing'])
+    expect(c.body.trim()).toBe('Free-form body here.')
+  })
+
+  test('rejects missing name', () => {
+    expect(() => parseCard('---\nbio: no name\n---\nbody')).toThrow()
+  })
+
+  test('round-trips via render', () => {
+    const c = {
+      frontmatter: { name: 'Bob', bio: 'hi', skills: ['code'] },
+      body: 'Body.',
+    }
+    const rendered = renderCard(c)
+    const parsed = parseCard(rendered)
+    expect(parsed.frontmatter.name).toBe('Bob')
+    expect(parsed.frontmatter.skills).toEqual(['code'])
+  })
+
+  test('emptyCard is parseable after setting a name', () => {
+    const c = emptyCard()
+    c.frontmatter.name = 'Temp'
+    const rendered = renderCard(c)
+    const parsed = parseCard(rendered)
+    expect(parsed.frontmatter.name).toBe('Temp')
+  })
+
+  test('cardToTextRecords includes address + agent:inft when present', () => {
+    const c = {
+      frontmatter: {
+        name: 'Alice',
+        bio: 'hi',
+        skills: ['research', 'writing'],
+        inft: 'eip155:5003:0xabc:42',
+        avatar: '0xdeadbeef',
+      },
+      body: '',
+    }
+    const r = cardToTextRecords(c, '0xC635e6Eb223aE14143E23cEEa9440bC773dc87Ec')
+    expect(r.address).toBe('0xC635e6Eb223aE14143E23cEEa9440bC773dc87Ec')
+    expect(r['agent:bio']).toBe('hi')
+    expect(r['agent:skills']).toBe('research,writing')
+    expect(r['agent:inft']).toBe('eip155:5003:0xabc:42')
+    expect(r.avatar).toBe('0xdeadbeef')
+  })
+
+  test('cardToTextRecords omits empty fields', () => {
+    const c = emptyCard()
+    c.frontmatter.name = 'NoExtras'
+    const r = cardToTextRecords(c)
+    expect(Object.keys(r)).toHaveLength(0)
+  })
+})