lyra-core 0.1.0

package/src/locks.ts

@@ -0,0 +1,233 @@
+// Process-scoped advisory locks via PID-file pattern.
+//
+// Used by long-running listeners (telegram bot poller, etc.) to ensure only
+// one process per scope+identity holds the resource. Mirrors hermes's
+// acquire_scoped_lock from gateway/status.py.
+//
+// Lock file lives at ~/.lyra/locks/<scope>-<sha256(identity).slice(0,16)>.lock
+// O_CREAT|O_EXCL atomic create. Stale-detection via process.kill(pid, 0).
+// TTL eviction is a belt-and-suspenders fallback against crashed holders that
+// the kernel hasn't reaped yet (rare but real on macOS).
+
+import { createHash } from 'node:crypto'
+import { closeSync, mkdirSync, openSync, readFileSync, unlinkSync, writeSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+export interface AcquireScopedLockOpts {
+  scope: string
+  identity: string
+  ttl?: number
+  rootDir?: string
+}
+
+export interface ScopedLockHandle {
+  releaseFn: () => void
+  refreshFn: () => boolean
+}
+
+export interface AcquireScopedLockResult {
+  acquired: boolean
+  handle?: ScopedLockHandle
+  existing?: { pid: number; startedAt: number; updatedAt: number }
+}
+
+export const DEFAULT_LOCK_TTL_SECONDS = 300
+
+interface LockRecord {
+  pid: number
+  scope: string
+  identityHash: string
+  startedAt: number
+  updatedAt: number
+  ttl: number
+}
+
+function lockDir(rootDir?: string): string {
+  return rootDir ?? join(homedir(), '.lyra', 'locks')
+}
+
+function lockPath(scope: string, identity: string, rootDir?: string): string {
+  const hash = createHash('sha256').update(identity).digest('hex').slice(0, 16)
+  return join(lockDir(rootDir), `${scope}-${hash}.lock`)
+}
+
+function readLock(path: string): LockRecord | null {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8')) as LockRecord
+  } catch {
+    return null
+  }
+}
+
+// process.kill(pid, 0) succeeds against zombie (defunct) processes on Linux
+// because the kernel keeps the PID slot until the parent reaps it. A zombie
+// can never refresh its lock or service work, so we treat it as gone. See
+// feedback-tg-token-lock-zombie-after-upgrade.md. Exported for tests; not
+// public API.
+export function isZombieLinux(pid: number): boolean {
+  try {
+    const status = readFileSync(`/proc/${pid}/status`, 'utf8')
+    const m = status.match(/^State:\s+(\S)/m)
+    return m?.[1] === 'Z'
+  } catch {
+    return false
+  }
+}
+
+type StaleReason = 'live' | 'pid-dead' | 'zombie' | 'ttl'
+
+// Single source of truth for "is this lock record dead, and if so, why?"
+// `attemptOnce` only cares whether it can reclaim; `clearStaleScopedLock`
+// reports the reason back to operators. Both go through this so the policy
+// (TTL > kill(0) ESRCH > linux zombie) stays in one place.
+function classifyStale(record: LockRecord, now: number): StaleReason {
+  if (now - record.updatedAt > record.ttl) return 'ttl'
+  if (record.pid === process.pid) return 'live'
+  try {
+    process.kill(record.pid, 0)
+  } catch (e) {
+    const code = (e as NodeJS.ErrnoException).code
+    if (code === 'EPERM') return 'live'
+    return 'pid-dead'
+  }
+  if (process.platform === 'linux' && isZombieLinux(record.pid)) return 'zombie'
+  return 'live'
+}
+
+function isStale(record: LockRecord, now: number): boolean {
+  return classifyStale(record, now) !== 'live'
+}
+
+function attemptOnce(
+  path: string,
+  scope: string,
+  identityHash: string,
+  ttl: number,
+): AcquireScopedLockResult {
+  let fd: number
+  try {
+    fd = openSync(path, 'wx')
+  } catch {
+    const existing = readLock(path)
+    const now = Math.floor(Date.now() / 1000)
+    if (!existing || isStale(existing, now)) {
+      try {
+        unlinkSync(path)
+      } catch {
+        /* race with another reclaimer */
+      }
+      return { acquired: false }
+    }
+    return {
+      acquired: false,
+      existing: {
+        pid: existing.pid,
+        startedAt: existing.startedAt,
+        updatedAt: existing.updatedAt,
+      },
+    }
+  }
+
+  const now = Math.floor(Date.now() / 1000)
+  const record: LockRecord = {
+    pid: process.pid,
+    scope,
+    identityHash,
+    startedAt: now,
+    updatedAt: now,
+    ttl,
+  }
+  try {
+    writeSync(fd, JSON.stringify(record))
+  } finally {
+    closeSync(fd)
+  }
+
+  let released = false
+  const releaseFn = (): void => {
+    if (released) return
+    released = true
+    try {
+      const current = readLock(path)
+      if (current?.pid === process.pid) unlinkSync(path)
+    } catch {
+      /* best-effort */
+    }
+  }
+  const refreshFn = (): boolean => {
+    if (released) return false
+    try {
+      const current = readLock(path)
+      if (current?.pid !== process.pid) return false
+      const next: LockRecord = { ...current, updatedAt: Math.floor(Date.now() / 1000) }
+      const fd2 = openSync(path, 'w')
+      try {
+        writeSync(fd2, JSON.stringify(next))
+      } finally {
+        closeSync(fd2)
+      }
+      return true
+    } catch {
+      return false
+    }
+  }
+  return { acquired: true, handle: { releaseFn, refreshFn } }
+}
+
+export function acquireScopedLock(opts: AcquireScopedLockOpts): AcquireScopedLockResult {
+  const ttl = opts.ttl ?? DEFAULT_LOCK_TTL_SECONDS
+  const path = lockPath(opts.scope, opts.identity, opts.rootDir)
+  mkdirSync(lockDir(opts.rootDir), { recursive: true })
+  const identityHash = createHash('sha256').update(opts.identity).digest('hex').slice(0, 16)
+
+  for (let i = 0; i < 3; i++) {
+    const result = attemptOnce(path, opts.scope, identityHash, ttl)
+    if (result.acquired) return result
+    if (result.existing) return result
+  }
+  return { acquired: false }
+}
+
+export type ClearStaleScopedLockReason =
+  | 'no-lock'
+  | 'alive-pid'
+  | 'cleared-stale'
+  | 'cleared-zombie'
+  | 'cleared-ttl'
+  | 'cleared-unreadable'
+
+export interface ClearStaleScopedLockResult {
+  cleared: boolean
+  reason: ClearStaleScopedLockReason
+}
+
+/**
+ * Inspect the lock file at `(scope, identity)` and remove it iff it's stale
+ * (PID dead, zombie on Linux, or TTL expired). Never deletes a lock held by a
+ * live foreign PID — caller must wait for it.
+ *
+ * Used at gateway boot to proactively reap zombie/crashed listener locks so
+ * the new TG listener can acquire its bot-token slot without the 30s/6min
+ * retry waltz from `recovery.ts:scheduleStartRetry`.
+ */
+export function clearStaleScopedLock(opts: AcquireScopedLockOpts): ClearStaleScopedLockResult {
+  const path = lockPath(opts.scope, opts.identity, opts.rootDir)
+  const existing = readLock(path)
+  if (!existing) return { cleared: false, reason: 'no-lock' }
+  const reason = classifyStale(existing, Math.floor(Date.now() / 1000))
+  if (reason === 'live') return { cleared: false, reason: 'alive-pid' }
+  try {
+    unlinkSync(path)
+  } catch {
+    return { cleared: false, reason: 'cleared-unreadable' }
+  }
+  switch (reason) {
+    case 'zombie':
+      return { cleared: true, reason: 'cleared-zombie' }
+    case 'pid-dead':
+      return { cleared: true, reason: 'cleared-stale' }
+    case 'ttl':
+      return { cleared: true, reason: 'cleared-ttl' }
+  }
+}

package/src/mcp/discovery.test.ts

@@ -0,0 +1,97 @@
+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 { discoverMcpServers } from './discovery'
+
+let scratch: string
+
+beforeEach(async () => {
+  scratch = await mkdtemp(join(tmpdir(), 'lyra-mcp-'))
+})
+
+afterEach(async () => {
+  await rm(scratch, { recursive: true, force: true })
+})
+
+describe('discoverMcpServers', () => {
+  it('reads ~/.lyra/.mcp.json + ~/.claude/.mcp.json', async () => {
+    const lyraPath = join(scratch, 'lyra.mcp.json')
+    const claudePath = join(scratch, 'claude.mcp.json')
+    await writeFile(
+      lyraPath,
+      JSON.stringify({
+        mcpServers: {
+          alpha: { command: 'bun', args: ['run', 'a.ts'] },
+        },
+      }),
+    )
+    await writeFile(
+      claudePath,
+      JSON.stringify({
+        mcpServers: {
+          beta: { type: 'http', url: 'https://example.com/mcp', headers: { 'X-Foo': '1' } },
+        },
+      }),
+    )
+    const out = await discoverMcpServers({
+      lyraMcpPath: lyraPath,
+      claudeMcpPath: claudePath,
+      claudePluginsCacheRoot: join(scratch, 'doesnotexist'),
+      importsClaudeCode: true,
+    })
+    expect(out.servers).toHaveLength(2)
+    const alpha = out.servers.find(s => s.name === 'alpha')
+    expect(alpha?.type).toBe('stdio')
+    if (alpha?.type === 'stdio') {
+      expect(alpha.command).toBe('bun')
+      expect(alpha.args).toEqual(['run', 'a.ts'])
+    }
+    const beta = out.servers.find(s => s.name === 'beta')
+    expect(beta?.type).toBe('http')
+    if (beta?.type === 'http') expect(beta.url).toBe('https://example.com/mcp')
+  })
+
+  it('substitutes ${CLAUDE_PLUGIN_ROOT} from plugin cache layout', async () => {
+    const cacheRoot = join(scratch, 'cache')
+    const versionDir = join(cacheRoot, 'mp', 'plug', '1.0.0')
+    await mkdir(versionDir, { recursive: true })
+    await writeFile(
+      join(versionDir, '.mcp.json'),
+      JSON.stringify({
+        mcpServers: {
+          plug: {
+            command: 'bun',
+            args: ['run', '--cwd', '${CLAUDE_PLUGIN_ROOT}', 'start'],
+            env: { PLUG_ROOT: '${CLAUDE_PLUGIN_ROOT}/data' },
+          },
+        },
+      }),
+    )
+    const out = await discoverMcpServers({
+      lyraMcpPath: join(scratch, 'doesnotexist'),
+      claudeMcpPath: join(scratch, 'doesnotexist'),
+      claudePluginsCacheRoot: cacheRoot,
+      importsClaudeCode: true,
+    })
+    expect(out.servers).toHaveLength(1)
+    const s = out.servers[0]!
+    expect(s.type).toBe('stdio')
+    if (s.type === 'stdio') {
+      expect(s.args).toEqual(['run', '--cwd', versionDir, 'start'])
+      expect(s.env?.PLUG_ROOT).toBe(`${versionDir}/data`)
+    }
+  })
+
+  it('honors importsClaudeCode=false (only lyra path scanned)', async () => {
+    const claudePath = join(scratch, 'claude.mcp.json')
+    await writeFile(claudePath, JSON.stringify({ mcpServers: { foo: { command: 'bun' } } }))
+    const out = await discoverMcpServers({
+      lyraMcpPath: join(scratch, 'doesnotexist'),
+      claudeMcpPath: claudePath,
+      claudePluginsCacheRoot: join(scratch, 'doesnotexist'),
+      importsClaudeCode: false,
+    })
+    expect(out.servers).toEqual([])
+  })
+})

package/src/mcp/discovery.ts

@@ -0,0 +1,150 @@
+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 { McpDiscoveryResult, McpServerConfig } from './types'
+
+interface RawMcpFile {
+  mcpServers?: Record<string, RawMcpServer>
+}
+
+interface RawMcpServer {
+  command?: string
+  args?: string[]
+  env?: Record<string, string>
+  type?: 'stdio' | 'http'
+  url?: string
+  headers?: Record<string, string>
+}
+
+export interface McpDiscoveryOptions {
+  /** Whether to scan ~/.claude/.mcp.json + ~/.claude/plugins/cache/. Default true. */
+  importsClaudeCode?: boolean
+  /** Override for ~/.claude/.mcp.json. */
+  claudeMcpPath?: string
+  /** Override for ~/.claude/plugins/cache/. */
+  claudePluginsCacheRoot?: string
+  /** Override for ~/.lyra/.mcp.json (lyra-native MCP servers). */
+  lyraMcpPath?: string
+}
+
+export async function discoverMcpServers(
+  opts: McpDiscoveryOptions = {},
+): Promise<McpDiscoveryResult> {
+  const importsClaudeCode = opts.importsClaudeCode ?? true
+  const lyraMcpPath = opts.lyraMcpPath ?? join(homedir(), '.lyra', '.mcp.json')
+  const claudeMcpPath = opts.claudeMcpPath ?? join(homedir(), '.claude', '.mcp.json')
+  const claudePluginsCacheRoot =
+    opts.claudePluginsCacheRoot ?? join(homedir(), '.claude', 'plugins', 'cache')
+
+  const sources: McpDiscoveryResult['sources'] = []
+  const collected = new Map<string, McpServerConfig>()
+  await loadFromFile(lyraMcpPath, undefined, collected, sources)
+  if (importsClaudeCode) {
+    await loadFromFile(claudeMcpPath, undefined, collected, sources)
+    await loadFromCache(claudePluginsCacheRoot, collected, sources)
+  }
+  return { servers: [...collected.values()], sources }
+}
+
+async function loadFromFile(
+  path: string,
+  pluginRoot: string | undefined,
+  out: Map<string, McpServerConfig>,
+  sources: McpDiscoveryResult['sources'],
+): Promise<void> {
+  let raw: string
+  try {
+    raw = await readFile(path, 'utf8')
+  } catch {
+    return
+  }
+  let parsed: RawMcpFile
+  try {
+    parsed = JSON.parse(raw) as RawMcpFile
+  } catch {
+    return
+  }
+  if (!parsed.mcpServers) return
+  for (const [name, server] of Object.entries(parsed.mcpServers)) {
+    const config = normalize(name, server, pluginRoot)
+    if (!config) continue
+    if (out.has(name)) continue
+    out.set(name, config)
+    sources.push({ server: name, path })
+  }
+}
+
+async function loadFromCache(
+  cacheRoot: string,
+  out: Map<string, McpServerConfig>,
+  sources: McpDiscoveryResult['sources'],
+): Promise<void> {
+  let marketplaces: Dirent[]
+  try {
+    const s = await stat(cacheRoot)
+    if (!s.isDirectory()) return
+    marketplaces = (await readdir(cacheRoot, { withFileTypes: true })) as Dirent[]
+  } catch {
+    return
+  }
+  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)
+      // Pick the newest version dir (lexicographic, sufficient for semver).
+      versionDirs.sort()
+      const latest = versionDirs[versionDirs.length - 1]
+      if (!latest) continue
+      const versionDir = join(pluginDir, latest)
+      const mcpPath = join(versionDir, '.mcp.json')
+      await loadFromFile(mcpPath, versionDir, out, sources)
+    }
+  }
+}
+
+function normalize(
+  name: string,
+  raw: RawMcpServer,
+  pluginRoot: string | undefined,
+): McpServerConfig | null {
+  if (raw.type === 'http') {
+    if (!raw.url) return null
+    return { name, type: 'http', url: raw.url, headers: raw.headers }
+  }
+  if (!raw.command) return null
+  return {
+    name,
+    type: 'stdio',
+    command: raw.command,
+    args: raw.args?.map(a => substitutePluginRoot(a, pluginRoot)),
+    env: raw.env
+      ? Object.fromEntries(
+          Object.entries(raw.env).map(([k, v]) => [k, substitutePluginRoot(v, pluginRoot)]),
+        )
+      : undefined,
+    pluginRoot,
+  }
+}
+
+function substitutePluginRoot(s: string, pluginRoot: string | undefined): string {
+  if (!pluginRoot) return s
+  return s
+    .replaceAll('${CLAUDE_PLUGIN_ROOT}', pluginRoot)
+    .replaceAll('$CLAUDE_PLUGIN_ROOT', pluginRoot)
+}

package/src/mcp/index.ts

@@ -0,0 +1,10 @@
+export { discoverMcpServers, type McpDiscoveryOptions } from './discovery'
+export { McpStdioClient } from './stdio-client'
+export { McpManager } from './manager'
+export type {
+  McpServerConfig,
+  McpServerStdio,
+  McpServerHttp,
+  McpToolMeta,
+  McpDiscoveryResult,
+} from './types'

package/src/mcp/manager.test.ts

@@ -0,0 +1,97 @@
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { ToolRegistry } from '../tools/registry'
+import type { ToolDef } from '../tools/types'
+import { McpManager } from './manager'
+
+let scratch: string
+let serverPath: string
+
+beforeEach(async () => {
+  scratch = await mkdtemp(join(tmpdir(), 'lyra-mcp-server-'))
+  serverPath = join(scratch, 'server.ts')
+  // Minimal stdio MCP server: handles initialize, tools/list, tools/call.
+  await writeFile(
+    serverPath,
+    `process.stdin.setEncoding('utf8')
+let buf = ''
+process.stdin.on('data', chunk => {
+  buf += chunk
+  let nl = buf.indexOf('\\n')
+  while (nl !== -1) {
+    const line = buf.slice(0, nl).trim()
+    buf = buf.slice(nl + 1)
+    nl = buf.indexOf('\\n')
+    if (!line) continue
+    const msg = JSON.parse(line)
+    if (msg.method === 'initialize') {
+      process.stdout.write(JSON.stringify({
+        jsonrpc: '2.0', id: msg.id,
+        result: { protocolVersion: '2024-11-05', capabilities: {}, serverInfo: { name: 'fake', version: '1.0.0' } },
+      }) + '\\n')
+    } else if (msg.method === 'tools/list') {
+      process.stdout.write(JSON.stringify({
+        jsonrpc: '2.0', id: msg.id,
+        result: { tools: [{ name: 'echo', description: 'echoes input', inputSchema: { type: 'object', properties: { text: { type: 'string' } }, required: ['text'] } }] },
+      }) + '\\n')
+    } else if (msg.method === 'tools/call') {
+      process.stdout.write(JSON.stringify({
+        jsonrpc: '2.0', id: msg.id,
+        result: { content: [{ type: 'text', text: msg.params.arguments.text }] },
+      }) + '\\n')
+    }
+  }
+})
+`,
+  )
+})
+
+afterEach(async () => {
+  await rm(scratch, { recursive: true, force: true })
+})
+
+describe('McpManager', () => {
+  it('spawns stdio server, registers tool, dispatches via registry', async () => {
+    const mgr = new McpManager([
+      { name: 'fake', type: 'stdio', command: 'bun', args: ['run', serverPath] },
+    ])
+    const reg = new ToolRegistry()
+    const result = await mgr.registerAll(def => reg.register(def))
+    expect(result.registered).toBe(1)
+    expect(result.failed).toEqual([])
+
+    const tool = reg.find('mcp.fake.echo') as ToolDef
+    expect(tool).toBeDefined()
+    expect(tool.shouldDefer).toBe(true)
+    expect(tool.parametersOverride?.properties).toEqual({ text: { type: 'string' } })
+
+    const out = await reg.dispatch({ id: '1', name: 'mcp.fake.echo', args: { text: 'hi' } })
+    expect(out.ok).toBe(true)
+    expect(out.data).toMatchObject({ content: [{ type: 'text', text: 'hi' }] })
+
+    mgr.closeAll()
+  })
+
+  it('reports failed servers without throwing', async () => {
+    const mgr = new McpManager([{ name: 'broken', type: 'stdio', command: '/does/not/exist' }])
+    const reg = new ToolRegistry()
+    const result = await mgr.registerAll(def => reg.register(def))
+    expect(result.registered).toBe(0)
+    expect(result.failed).toHaveLength(1)
+    expect(result.failed[0]!.server).toBe('broken')
+    mgr.closeAll()
+  })
+
+  it('flags http servers as not yet supported', async () => {
+    const mgr = new McpManager([
+      { name: 'http-thing', type: 'http', url: 'https://example.com/mcp' },
+    ])
+    const reg = new ToolRegistry()
+    const result = await mgr.registerAll(def => reg.register(def))
+    expect(result.registered).toBe(0)
+    expect(result.failed[0]!.error).toContain('http MCP')
+    mgr.closeAll()
+  })
+})

package/src/mcp/manager.ts

@@ -0,0 +1,110 @@
+import { z } from 'zod'
+import type { JSONSchema, ToolDef } from '../tools/types'
+import { McpStdioClient } from './stdio-client'
+import type { McpServerConfig, McpToolMeta } from './types'
+
+/**
+ * Lifecycle manager for one or more MCP servers. Spawns each subprocess at
+ * registration time, calls `tools/list`, and registers each remote tool as
+ * `mcp.<server>.<tool>` with `shouldDefer: true` so the brain only sees the
+ * full schema after `tool.search`.
+ *
+ * Lifecycle: caller invokes `closeAll()` on session end (chat exit).
+ */
+export class McpManager {
+  private readonly clients = new Map<string, McpStdioClient>()
+  private readonly toolMeta = new Map<string, McpToolMeta>()
+
+  constructor(public readonly servers: readonly McpServerConfig[]) {}
+
+  async registerAll(register: (def: ToolDef) => void): Promise<{
+    registered: number
+    failed: { server: string; error: string }[]
+  }> {
+    const failed: { server: string; error: string }[] = []
+    let registered = 0
+    await Promise.all(
+      this.servers.map(async server => {
+        if (server.type === 'http') {
+          failed.push({ server: server.name, error: 'http MCP not yet supported (Phase 9.4)' })
+          return
+        }
+        try {
+          const client = new McpStdioClient(server)
+          this.clients.set(server.name, client)
+          const tools = await client.listTools()
+          for (const t of tools) {
+            const id = `mcp.${server.name}.${t.name}`
+            const meta: McpToolMeta = {
+              server: server.name,
+              toolName: t.name,
+              description: t.description ?? '',
+              inputSchema: t.inputSchema ?? defaultSchema(),
+            }
+            this.toolMeta.set(id, meta)
+            register(this.makeToolDef(id, meta))
+            registered++
+          }
+        } catch (e) {
+          failed.push({ server: server.name, error: (e as Error).message })
+          const dead = this.clients.get(server.name)
+          dead?.close()
+          this.clients.delete(server.name)
+        }
+      }),
+    )
+    return { registered, failed }
+  }
+
+  closeAll(): void {
+    for (const client of this.clients.values()) client.close()
+    this.clients.clear()
+  }
+
+  private makeToolDef(id: string, meta: McpToolMeta): ToolDef {
+    const head = meta.description ? `${meta.description.trim()}\n\n` : ''
+    const description = `${head}(MCP tool from server '${meta.server}', mapped to '${meta.toolName}'.)`
+    return {
+      name: id,
+      description,
+      shouldDefer: true,
+      searchHint: `mcp ${meta.server} ${meta.toolName}`,
+      schema: z.unknown(),
+      parametersOverride: toJsonSchemaShape(meta.inputSchema),
+      handler: async args => {
+        const client = this.clients.get(meta.server)
+        if (!client) {
+          return { ok: false, error: `mcp server '${meta.server}' not running` }
+        }
+        try {
+          const result = await client.callTool(meta.toolName, args ?? {})
+          return { ok: true, data: result }
+        } catch (e) {
+          return { ok: false, error: (e as Error).message }
+        }
+      },
+    }
+  }
+}
+
+function defaultSchema(): JSONSchema {
+  return {
+    type: 'object',
+    properties: {},
+    additionalProperties: true,
+  }
+}
+
+function toJsonSchemaShape(raw: unknown): JSONSchema {
+  if (!raw || typeof raw !== 'object') return defaultSchema()
+  const r = raw as Record<string, unknown>
+  if (r.type !== 'object' && !('properties' in r)) return defaultSchema()
+  return {
+    type: 'object',
+    properties: (r.properties as Record<string, unknown>) ?? {},
+    required: Array.isArray(r.required) ? (r.required as string[]) : undefined,
+    additionalProperties:
+      typeof r.additionalProperties === 'boolean' ? (r.additionalProperties as boolean) : true,
+    description: typeof r.description === 'string' ? (r.description as string) : undefined,
+  }
+}