lyra-core 0.1.0

package/src/index.test.ts

@@ -0,0 +1,6 @@
+import { expect, test } from 'bun:test'
+import { VERSION } from './index'
+
+test('core package loads and exposes VERSION', () => {
+  expect(VERSION).toBe('0.0.0')
+})

package/src/index.ts

@@ -0,0 +1,314 @@
+// lyra-core: always-on infrastructure for the lyra harness.
+export const VERSION = '0.0.0'
+
+export * from './config'
+export { formatSui } from './format'
+export { agentPaths, placeholderAgentId } from './paths'
+
+export type {
+  LyraEvent,
+  EventPayload,
+  EventSource,
+  Listener,
+  RouterDeps,
+} from './events'
+export { EventQueue, newEventId, listeners, routeLoop } from './events'
+
+export type {
+  ToolCall,
+  ToolDef,
+  ToolResult,
+  ToolSchema,
+  JSONSchema,
+  FetchEscalation,
+  EscalationDeps,
+} from './tools'
+export {
+  ToolRegistry,
+  zodToJsonSchema,
+  coerceBool,
+  coerceInt,
+  detectFetchEscalation,
+  mergeEscalationResult,
+  runEscalation,
+} from './tools'
+
+export type {
+  ApplyResult,
+  CommandScope,
+  CommandSurface,
+  ParsedSlash,
+  PermissionApi,
+  PermissionToggleMode,
+  SlashCommand,
+} from './commands'
+export {
+  COMMAND_REGISTRY,
+  applyPerms,
+  applyYolo,
+  commandsForSurface,
+  findCommand,
+  parseSlash,
+  suggestForPrefix,
+} from './commands'
+
+export type {
+  Brain,
+  BrainCompactionEvent,
+  BrainInferInput,
+  BrainTurn,
+  BrainMessage,
+  BrainProvider,
+  BrainProviderOpts,
+  CompactionOpts,
+  FrozenPrefix,
+  HistoryPersist,
+  FsHistoryPersistOpts,
+  OpenAIBrainOpts,
+  SummarizeFn,
+} from './brain'
+export {
+  StubBrain,
+  OpenAIBrain,
+  DEFAULT_BASE_URL,
+  DEMO_LLM_BASE_URL,
+  DEMO_LLM_TOKEN,
+  DEFAULT_MODEL,
+  DEFAULT_CHANNEL_KEY,
+  DEFAULT_MAX_OUTPUT_TOKENS,
+  previewToolArgs,
+  inferToolOk,
+  buildFrozenPrefix,
+  renderFrozenPrefix,
+  DEFAULT_SYSTEM_PROMPT,
+  DEFAULT_COMPACTION_OPTS,
+  SUMMARY_SYSTEM_PROMPT,
+  estimateTokens,
+  shouldCompact,
+  compactHistory,
+  createFsHistoryPersist,
+  sanitizeChannelKey,
+} from './brain'
+
+export type {
+  MemoryType,
+  MemoryPartition,
+  MemoryFrontmatter,
+  MemoryTopic,
+  MemoryIndexEntry,
+  MemoryIndex,
+  EditOp,
+  EditAction,
+  ThreatScanResult,
+} from './memory'
+export {
+  parseTopic,
+  stringifyTopic,
+  scanForThreats,
+  applyEdit,
+  EditError,
+  parseIndex,
+  stringifyIndex,
+  readIndexFile,
+  writeIndexFile,
+  addEntryLine,
+  removeEntryLine,
+  readTopic,
+  writeTopic,
+  topicPath,
+  makeMemorySaveTool,
+  type MemorySaveArgs,
+  makeMemoryReadTool,
+  type MemoryReadArgs,
+  makeMemoryListTool,
+  type MemoryListArgs,
+  type MemoryListAgentFile,
+  ensureSyntheticIndexEntries,
+  STANDARD_SYNTHETIC_INDEX_FILES,
+  type SyntheticIndexFile,
+  type SyntheticIndexResult,
+  INDEX_LINE_LIMIT,
+  INDEX_BYTE_LIMIT,
+  MEMORY_BLOB_VERSION,
+  deriveMemoryKey,
+  encryptMemoryBytes,
+  decryptMemoryBytes,
+  PACK_BLOB_VERSION,
+  encodePackBlob,
+  decodePackBlob,
+  isV2Envelope,
+  type PackBlob,
+  type EncodePackOpts,
+  gatherAgentPack,
+  gatherUserPack,
+  writeAgentPack,
+  writeUserPack,
+  type GatherResult,
+} from './memory'
+
+export type { Storage } from './storage'
+export {
+  LocalStubStorage,
+  SqliteStorage,
+  getStorage,
+  downloadBlobByRoot,
+  encrypt as encryptBytes,
+  decrypt as decryptBytes,
+  packEnvelope,
+  unpackEnvelope,
+  type EncryptedEnvelope,
+} from './storage'
+
+export {
+  encryptKey,
+  decryptKey,
+  generateAgentKeypair,
+  generateAgentWallet,
+  saveKeystore,
+  loadKeystore,
+  type EncryptedKeystore,
+  type AgentWalletMaterial,
+  drainAgentEOA,
+  computeSweepAmount,
+  SWEEP_GAS_RESERVE_MIST,
+  type DrainAgentResult,
+} from './wallet'
+
+export {
+  makeSuiClient,
+  suiRpcUrl,
+  keypairFromSecret,
+  getSuiBalanceMist,
+} from './chain'
+
+export {
+  Runtime,
+  type RuntimeDeps,
+  type AgentIdentity,
+  type IdentityProvider,
+  ActivityLog,
+  type ActivityEntry,
+} from './runtime'
+
+export {
+  acquireScopedLock,
+  clearStaleScopedLock,
+  DEFAULT_LOCK_TTL_SECONDS,
+  type AcquireScopedLockOpts,
+  type AcquireScopedLockResult,
+  type ClearStaleScopedLockReason,
+  type ClearStaleScopedLockResult,
+  type ScopedLockHandle,
+} from './locks'
+
+export {
+  PairingStore,
+  PAIRING_ALPHABET,
+  PAIRING_CODE_LENGTH,
+  PAIRING_CODE_TTL_SECONDS,
+  PAIRING_RATE_LIMIT_SECONDS,
+  PAIRING_LOCKOUT_SECONDS,
+  PAIRING_MAX_PENDING_PER_PLATFORM,
+  PAIRING_MAX_FAILED_ATTEMPTS,
+  type PairingStoreOpts,
+  type PendingEntry,
+  type ApprovedEntry,
+  type PendingListing,
+  type ApprovedListing,
+  type ApproveResult,
+} from './pairing'
+
+export {
+  encryptToPubkey,
+  decryptWithPrivkey,
+  generateBootstrapKeypair,
+  type Option3Envelope,
+} from './migration'
+
+export {
+  HookBus,
+  type HookName,
+  type HookHandler,
+  type PreToolCallContext,
+  type PreToolCallResult,
+  type PostToolCallContext,
+  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,
+  makeToolSearchTool,
+  type ToolSearchArgs,
+} from './plugins'
+
+export {
+  detectDangerousCommand,
+  DANGEROUS_PATTERNS,
+  PathGuard,
+  type PathGuardOpts,
+  type PathGuardResult,
+  redactEnv,
+  type EnvRedactResult,
+  PermissionService,
+  type PermissionMode,
+  type PermissionDecision,
+  type PermissionRequest,
+  type PermissionPrompter,
+  type PermissionServiceOpts,
+  type DangerousMatch,
+} from './permission'
+
+export type { SkillFrontmatter, SkillRef, SkillSource } from './skills'
+export {
+  scanSkills,
+  parseFrontmatter as parseSkillFrontmatter,
+  matchTriggers as matchSkillTriggers,
+  matchFilePattern,
+  matchBashPattern,
+  type SkillScannerOptions,
+  type SkillTriggerMatch,
+} from './skills'
+
+export {
+  discoverMcpServers,
+  McpManager,
+  McpStdioClient,
+  type McpDiscoveryOptions,
+  type McpServerConfig,
+  type McpServerStdio,
+  type McpServerHttp,
+  type McpToolMeta,
+  type McpDiscoveryResult,
+} from './mcp'
+
+export {
+  discoverClaudeExtras,
+  type ClaudeExtrasOptions,
+  type ClaudeCommand,
+  type ClaudeAgent,
+  type ClaudeExtrasDiscoveryResult,
+} from './claude-plugins'
+
+export {
+  LocalBackend,
+  MacOSSandboxExecBackend,
+  DockerBackend,
+  makeSandboxBackend,
+  buildSeatbeltProfile,
+  type SandboxBackend,
+  type SandboxBackendOpts,
+  type SandboxMode,
+  type SandboxSpawnRequest,
+  type WrappedSpawn,
+  type SeatbeltProfileOpts,
+  type MakeSandboxOpts,
+  type DockerBackendOpts,
+} from './sandbox'

package/src/locks.test.ts

@@ -0,0 +1,259 @@
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import {
+  DEFAULT_LOCK_TTL_SECONDS,
+  acquireScopedLock,
+  clearStaleScopedLock,
+  isZombieLinux,
+} from './locks'
+
+let testDir: string
+
+beforeEach(() => {
+  testDir = mkdtempSync(join(tmpdir(), 'lyra-locks-test-'))
+})
+
+afterEach(() => {
+  rmSync(testDir, { recursive: true, force: true })
+})
+
+describe('acquireScopedLock', () => {
+  it('acquires when no prior holder exists', () => {
+    const r = acquireScopedLock({ scope: 'test', identity: 'token-a', rootDir: testDir })
+    expect(r.acquired).toBe(true)
+    expect(r.handle).toBeDefined()
+    r.handle?.releaseFn()
+  })
+
+  it('rejects when another live process holds it', () => {
+    const r1 = acquireScopedLock({ scope: 'test', identity: 'token-a', rootDir: testDir })
+    expect(r1.acquired).toBe(true)
+
+    const r2 = acquireScopedLock({ scope: 'test', identity: 'token-a', rootDir: testDir })
+    expect(r2.acquired).toBe(false)
+    expect(r2.existing?.pid).toBe(process.pid)
+
+    r1.handle?.releaseFn()
+  })
+
+  it('different identities do not collide on same scope', () => {
+    const a = acquireScopedLock({ scope: 'test', identity: 'token-a', rootDir: testDir })
+    const b = acquireScopedLock({ scope: 'test', identity: 'token-b', rootDir: testDir })
+    expect(a.acquired).toBe(true)
+    expect(b.acquired).toBe(true)
+    a.handle?.releaseFn()
+    b.handle?.releaseFn()
+  })
+
+  it('release allows re-acquire', () => {
+    const r1 = acquireScopedLock({ scope: 'test', identity: 'token-a', rootDir: testDir })
+    expect(r1.acquired).toBe(true)
+    r1.handle?.releaseFn()
+
+    const r2 = acquireScopedLock({ scope: 'test', identity: 'token-a', rootDir: testDir })
+    expect(r2.acquired).toBe(true)
+    r2.handle?.releaseFn()
+  })
+
+  it('release is idempotent', () => {
+    const r1 = acquireScopedLock({ scope: 'test', identity: 'token-a', rootDir: testDir })
+    r1.handle?.releaseFn()
+    r1.handle?.releaseFn()
+    const r2 = acquireScopedLock({ scope: 'test', identity: 'token-a', rootDir: testDir })
+    expect(r2.acquired).toBe(true)
+    r2.handle?.releaseFn()
+  })
+
+  it('reclaims a stale lock from a dead PID', () => {
+    // Manually plant a lock file with a fake PID that won't exist
+    const fakePid = 999999
+    const lockFile = findLockFile(testDir, 'test', 'token-a')
+    writeFileSync(
+      lockFile,
+      JSON.stringify({
+        pid: fakePid,
+        scope: 'test',
+        identityHash: 'fake',
+        startedAt: 0,
+        updatedAt: 0,
+        ttl: DEFAULT_LOCK_TTL_SECONDS,
+      }),
+    )
+
+    const r = acquireScopedLock({ scope: 'test', identity: 'token-a', rootDir: testDir })
+    expect(r.acquired).toBe(true)
+    r.handle?.releaseFn()
+  })
+
+  it('reclaims a TTL-expired lock from a live process', () => {
+    // Plant a lock file with a real PID but ancient updatedAt
+    const lockFile = findLockFile(testDir, 'test', 'token-a')
+    const veryOld = Math.floor(Date.now() / 1000) - 99999
+    writeFileSync(
+      lockFile,
+      JSON.stringify({
+        pid: process.pid,
+        scope: 'test',
+        identityHash: 'fake',
+        startedAt: veryOld,
+        updatedAt: veryOld,
+        ttl: 60,
+      }),
+    )
+
+    const r = acquireScopedLock({ scope: 'test', identity: 'token-a', rootDir: testDir })
+    expect(r.acquired).toBe(true)
+    r.handle?.releaseFn()
+  })
+
+  it('refreshFn returns true while owner holds the lock', () => {
+    const r = acquireScopedLock({ scope: 'test', identity: 'token-a', rootDir: testDir })
+    expect(r.handle?.refreshFn()).toBe(true)
+    r.handle?.releaseFn()
+  })
+
+  it('refreshFn returns false after release', () => {
+    const r = acquireScopedLock({ scope: 'test', identity: 'token-a', rootDir: testDir })
+    r.handle?.releaseFn()
+    expect(r.handle?.refreshFn()).toBe(false)
+  })
+
+  it('hashes the identity into the lock filename', () => {
+    const a = acquireScopedLock({ scope: 'test', identity: 'token-a', rootDir: testDir })
+    const b = acquireScopedLock({ scope: 'test', identity: 'token-different', rootDir: testDir })
+    expect(a.acquired).toBe(true)
+    expect(b.acquired).toBe(true)
+    a.handle?.releaseFn()
+    b.handle?.releaseFn()
+  })
+
+  it('records stable shape: pid + startedAt + updatedAt + ttl', () => {
+    const r = acquireScopedLock({ scope: 'test', identity: 'token-a', rootDir: testDir, ttl: 600 })
+    expect(r.acquired).toBe(true)
+    r.handle?.releaseFn()
+  })
+
+  it('respects custom rootDir', () => {
+    const r = acquireScopedLock({ scope: 'test', identity: 'token-a', rootDir: testDir })
+    expect(r.acquired).toBe(true)
+    r.handle?.releaseFn()
+  })
+})
+
+describe('isZombieLinux', () => {
+  it('returns false on non-linux platforms', () => {
+    if (process.platform === 'linux') return // platform-specific guard
+    expect(isZombieLinux(process.pid)).toBe(false)
+  })
+
+  it('returns false for the live current process on linux', () => {
+    if (process.platform !== 'linux') return
+    expect(isZombieLinux(process.pid)).toBe(false)
+  })
+
+  it('returns false when /proc/<pid>/status is unreadable', () => {
+    // pid 999999 vanishingly unlikely to exist; readFile will throw.
+    expect(isZombieLinux(999_999)).toBe(false)
+  })
+})
+
+describe('acquireScopedLock evicts dead-pid lock', () => {
+  it('reclaims when the lockfile records a pid that no longer exists', () => {
+    // Take the lock, write a tampered record claiming a vanishingly-unlikely
+    // pid is the holder, then re-acquire. The stale-detection path
+    // (process.kill(pid, 0) → ESRCH) should treat it as gone and reclaim.
+    const path = findLockFile(testDir, 'test', 'dead-pid')
+    writeFileSync(
+      path,
+      JSON.stringify({
+        pid: 999_998, // unlikely to exist on the test host
+        scope: 'test',
+        identityHash: 'whatever',
+        startedAt: Math.floor(Date.now() / 1000),
+        updatedAt: Math.floor(Date.now() / 1000),
+        ttl: 300,
+      }),
+    )
+    const r = acquireScopedLock({ scope: 'test', identity: 'dead-pid', rootDir: testDir })
+    expect(r.acquired).toBe(true)
+    r.handle?.releaseFn()
+  })
+})
+
+describe('clearStaleScopedLock', () => {
+  it('returns no-lock when nothing exists', () => {
+    const r = clearStaleScopedLock({ scope: 'test', identity: 'fresh', rootDir: testDir })
+    expect(r.cleared).toBe(false)
+    expect(r.reason).toBe('no-lock')
+  })
+
+  it('returns alive-pid when a live PID holds the lock', () => {
+    const a = acquireScopedLock({ scope: 'test', identity: 'live', rootDir: testDir })
+    expect(a.acquired).toBe(true)
+    const r = clearStaleScopedLock({ scope: 'test', identity: 'live', rootDir: testDir })
+    expect(r.cleared).toBe(false)
+    expect(r.reason).toBe('alive-pid')
+    a.handle?.releaseFn()
+  })
+
+  it('clears a dead-PID lock and reports cleared-stale', () => {
+    const path = findLockFile(testDir, 'test', 'dead')
+    writeFileSync(
+      path,
+      JSON.stringify({
+        pid: 999_997,
+        scope: 'test',
+        identityHash: 'x',
+        startedAt: Math.floor(Date.now() / 1000),
+        updatedAt: Math.floor(Date.now() / 1000),
+        ttl: 600,
+      }),
+    )
+    const r = clearStaleScopedLock({ scope: 'test', identity: 'dead', rootDir: testDir })
+    expect(r.cleared).toBe(true)
+    expect(r.reason).toBe('cleared-stale')
+    // Re-clear should now return no-lock.
+    const r2 = clearStaleScopedLock({ scope: 'test', identity: 'dead', rootDir: testDir })
+    expect(r2.cleared).toBe(false)
+    expect(r2.reason).toBe('no-lock')
+  })
+
+  it('clears a TTL-expired lock and reports cleared-ttl', () => {
+    const path = findLockFile(testDir, 'test', 'expired')
+    const ancient = Math.floor(Date.now() / 1000) - 9999
+    writeFileSync(
+      path,
+      JSON.stringify({
+        pid: process.pid,
+        scope: 'test',
+        identityHash: 'x',
+        startedAt: ancient,
+        updatedAt: ancient,
+        ttl: 60,
+      }),
+    )
+    const r = clearStaleScopedLock({ scope: 'test', identity: 'expired', rootDir: testDir })
+    expect(r.cleared).toBe(true)
+    expect(r.reason).toBe('cleared-ttl')
+  })
+
+  it('does not delete a lock owned by current process within TTL', () => {
+    const a = acquireScopedLock({ scope: 'test', identity: 'mine', rootDir: testDir })
+    expect(a.acquired).toBe(true)
+    const r = clearStaleScopedLock({ scope: 'test', identity: 'mine', rootDir: testDir })
+    expect(r.cleared).toBe(false)
+    expect(r.reason).toBe('alive-pid')
+    // Lock still acquireable by us via refresh:
+    expect(a.handle?.refreshFn()).toBe(true)
+    a.handle?.releaseFn()
+  })
+})
+
+function findLockFile(dir: string, scope: string, identity: string): string {
+  // Mirror the internal hash logic (sha256 first 16 hex chars)
+  const { createHash } = require('node:crypto') as typeof import('node:crypto')
+  const hash = createHash('sha256').update(identity).digest('hex').slice(0, 16)
+  return join(dir, `${scope}-${hash}.lock`)
+}