lyra-core 0.1.0

package/src/skills/types.ts

@@ -0,0 +1,37 @@
+/**
+ * Phase 9.1 skills surface. Mirrors Claude Code's SKILL.md frontmatter so
+ * imports.claudeCode picks up the entire ~/.claude ecosystem free.
+ */
+export type SkillSource = 'lyra' | 'lyra-plugin' | 'claude-code' | 'claude-plugin'
+
+export interface SkillFrontmatter {
+  /** Unique name used by the brain to reference this skill. Required. */
+  name: string
+  /** One-line summary the brain sees in the skill index. Required. */
+  description: string
+  version?: string
+  license?: string
+  /** Comma-separated globs (e.g. `*.test.ts,*.spec.ts`) that auto-trigger the skill on fs.* paths. */
+  filePattern?: string
+  /** Regex (string) that auto-triggers the skill on shell.run commands. */
+  bashPattern?: string
+  /**
+   * Claude Code commands set this to distinguish slash-only invocations from
+   * model-invokable skills. Skills omit it; commands set it (any value).
+   */
+  argumentHint?: string
+}
+
+export interface SkillRef {
+  /** `<source-prefix>:<dir-name>` (e.g. `lyra:dogfood`, `claude-code:tmux`). */
+  id: string
+  /** Display name from frontmatter (falls back to directory name). */
+  name: string
+  description: string
+  /** Absolute path to SKILL.md. */
+  path: string
+  source: SkillSource
+  /** When set, marketplace > plugin > version triple from `~/.claude/plugins/cache/...` paths. */
+  pluginCoord?: { marketplace: string; plugin: string; version: string }
+  frontmatter: SkillFrontmatter
+}

package/src/storage/encryption.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, test } from 'bun:test'
+import { decrypt, encrypt, packEnvelope, unpackEnvelope } from './encryption'
+
+describe('encryption', () => {
+  test('round-trips a short message', () => {
+    const plaintext = new TextEncoder().encode('hello lyra')
+    const env = encrypt(plaintext, 'testpass1234')
+    const out = decrypt(env, 'testpass1234')
+    expect(new TextDecoder().decode(out)).toBe('hello lyra')
+  })
+
+  test('wrong passphrase fails', () => {
+    const env = encrypt(new TextEncoder().encode('secret'), 'right-password')
+    expect(() => decrypt(env, 'wrong-password')).toThrow()
+  })
+
+  test('packs + unpacks round-trip', () => {
+    const env = encrypt(new TextEncoder().encode('pack me'), 'pw')
+    const packed = packEnvelope(env)
+    const unpacked = unpackEnvelope(packed)
+    expect(Array.from(unpacked.salt)).toEqual(Array.from(env.salt))
+    expect(Array.from(unpacked.iv)).toEqual(Array.from(env.iv))
+    expect(Array.from(unpacked.tag)).toEqual(Array.from(env.tag))
+    expect(Array.from(unpacked.ciphertext)).toEqual(Array.from(env.ciphertext))
+  })
+
+  test('unpack throws on truncated input', () => {
+    expect(() => unpackEnvelope(new Uint8Array(20))).toThrow('envelope shorter than header')
+  })
+})

package/src/storage/encryption.ts

@@ -0,0 +1,87 @@
+import { createCipheriv, createDecipheriv, randomBytes, scryptSync } from 'node:crypto'
+
+const SCRYPT_N = 1 << 15
+const SCRYPT_R = 8
+const SCRYPT_P = 1
+const SCRYPT_MAXMEM = 64 * 1024 * 1024
+const KEY_LEN = 32
+const IV_LEN = 12
+const TAG_LEN = 16
+const SALT_LEN = 16
+
+/**
+ * AES-256-GCM symmetric encryption, scrypt-derived key from a passphrase.
+ * MVP pattern: each agent has one symmetric key derived from the operator
+ * passphrase. Same scrypt parameters as the wallet keystore for consistency.
+ *
+ * Post-MVP: replace with TEE-sealed key for /agent/ partition + ECIES to
+ * operator pubkey for /user/ partition (section 22 wallet architecture).
+ */
+
+export interface EncryptedEnvelope {
+  /** Random 16-byte salt used to derive the symmetric key. */
+  salt: Uint8Array
+  /** Random 12-byte GCM IV. */
+  iv: Uint8Array
+  /** 16-byte GCM auth tag. */
+  tag: Uint8Array
+  /** Ciphertext. */
+  ciphertext: Uint8Array
+}
+
+export function encrypt(plaintext: Uint8Array, passphrase: string): EncryptedEnvelope {
+  const salt = randomBytes(SALT_LEN)
+  const iv = randomBytes(IV_LEN)
+  const key = scryptSync(passphrase, salt, KEY_LEN, {
+    N: SCRYPT_N,
+    r: SCRYPT_R,
+    p: SCRYPT_P,
+    maxmem: SCRYPT_MAXMEM,
+  })
+  const cipher = createCipheriv('aes-256-gcm', key, iv)
+  const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()])
+  const tag = cipher.getAuthTag()
+  return {
+    salt,
+    iv,
+    tag: new Uint8Array(tag),
+    ciphertext: new Uint8Array(ciphertext),
+  }
+}
+
+export function decrypt(envelope: EncryptedEnvelope, passphrase: string): Uint8Array {
+  const key = scryptSync(passphrase, envelope.salt, KEY_LEN, {
+    N: SCRYPT_N,
+    r: SCRYPT_R,
+    p: SCRYPT_P,
+    maxmem: SCRYPT_MAXMEM,
+  })
+  const decipher = createDecipheriv('aes-256-gcm', key, envelope.iv)
+  decipher.setAuthTag(envelope.tag)
+  const plaintext = Buffer.concat([decipher.update(envelope.ciphertext), decipher.final()])
+  return new Uint8Array(plaintext)
+}
+
+/** Pack envelope into a single byte buffer for storage: salt || iv || tag || ciphertext. */
+export function packEnvelope(envelope: EncryptedEnvelope): Uint8Array {
+  const total = SALT_LEN + IV_LEN + TAG_LEN + envelope.ciphertext.length
+  const out = new Uint8Array(total)
+  out.set(envelope.salt, 0)
+  out.set(envelope.iv, SALT_LEN)
+  out.set(envelope.tag, SALT_LEN + IV_LEN)
+  out.set(envelope.ciphertext, SALT_LEN + IV_LEN + TAG_LEN)
+  return out
+}
+
+/** Unpack a packed envelope back into its fields. */
+export function unpackEnvelope(packed: Uint8Array): EncryptedEnvelope {
+  if (packed.length < SALT_LEN + IV_LEN + TAG_LEN) {
+    throw new Error('envelope shorter than header')
+  }
+  return {
+    salt: packed.slice(0, SALT_LEN),
+    iv: packed.slice(SALT_LEN, SALT_LEN + IV_LEN),
+    tag: packed.slice(SALT_LEN + IV_LEN, SALT_LEN + IV_LEN + TAG_LEN),
+    ciphertext: packed.slice(SALT_LEN + IV_LEN + TAG_LEN),
+  }
+}

package/src/storage/factory.ts

@@ -0,0 +1,31 @@
+import { join } from 'node:path'
+import { agentPaths } from '../paths'
+import { SqliteStorage } from './sqlite'
+import type { Storage } from './types'
+
+let singleton: SqliteStorage | null = null
+
+/**
+ * Shared, content-addressed local store at `~/.lyra/storage.sqlite`.
+ * Blobs are addressed by their `0x`+sha256 CID, so a single store serves all
+ * agents (a blob put by one is fetchable by hash from any). KV/log entries are
+ * namespaced by streamId. Replaces the prior decentralized storage backend.
+ */
+export function getStorage(): Storage {
+  if (!singleton) {
+    singleton = new SqliteStorage(join(agentPaths.root, 'storage.sqlite'))
+  }
+  return singleton
+}
+
+/**
+ * Back-compat shim for the old "download blob by on-chain root hash" call.
+ * Blobs are content-addressed (rootHash === CID), so this is just `getBlob`.
+ * The network arg is ignored; kept so existing call sites need no reshaping.
+ */
+export async function downloadBlobByRoot(
+  _network: unknown,
+  rootHash: string,
+): Promise<Uint8Array | null> {
+  return getStorage().getBlob(rootHash)
+}

package/src/storage/index.ts

@@ -0,0 +1,11 @@
+export type { Storage } from './types'
+export { LocalStubStorage } from './local-stub'
+export { SqliteStorage } from './sqlite'
+export { getStorage, downloadBlobByRoot } from './factory'
+export {
+  encrypt,
+  decrypt,
+  packEnvelope,
+  unpackEnvelope,
+  type EncryptedEnvelope,
+} from './encryption'

package/src/storage/local-stub.ts

@@ -0,0 +1,70 @@
+import { createHash } from 'node:crypto'
+import { appendFile, mkdir, readFile, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import type { Storage } from './types'
+
+/**
+ * Local-disk Storage stub. Layout under `${root}/storage-stub`:
+ *   kv/<streamId>/<url-encoded-key>         — latest value
+ *   log/<streamId>.jsonl                    — append-only JSONL
+ *   blob/<cid>                              — immutable by content hash
+ */
+export class LocalStubStorage implements Storage {
+  constructor(private readonly root: string) {}
+
+  private kvPath(stream: string, key: string): string {
+    return join(this.root, 'storage-stub', 'kv', stream, encodeURIComponent(key))
+  }
+
+  private logPath(stream: string): string {
+    return join(this.root, 'storage-stub', 'log', `${stream}.jsonl`)
+  }
+
+  private blobPath(cid: string): string {
+    return join(this.root, 'storage-stub', 'blob', cid)
+  }
+
+  async putKV(stream: string, key: string, value: Uint8Array): Promise<void> {
+    const p = this.kvPath(stream, key)
+    await mkdir(join(p, '..'), { recursive: true })
+    await writeFile(p, value)
+  }
+
+  async getKV(stream: string, key: string): Promise<Uint8Array | null> {
+    return await readOrNull(this.kvPath(stream, key))
+  }
+
+  async appendLog(stream: string, entry: Uint8Array): Promise<string> {
+    const p = this.logPath(stream)
+    await mkdir(join(p, '..'), { recursive: true })
+    const cid = cidOf(entry)
+    const line = JSON.stringify({ cid, hex: Buffer.from(entry).toString('hex'), ts: Date.now() })
+    await appendFile(p, `${line}\n`)
+    return cid
+  }
+
+  async putBlob(bytes: Uint8Array): Promise<string> {
+    const cid = cidOf(bytes)
+    const p = this.blobPath(cid)
+    await mkdir(join(p, '..'), { recursive: true })
+    await writeFile(p, bytes)
+    return cid
+  }
+
+  async getBlob(cid: string): Promise<Uint8Array | null> {
+    return await readOrNull(this.blobPath(cid))
+  }
+}
+
+async function readOrNull(path: string): Promise<Uint8Array | null> {
+  try {
+    return new Uint8Array(await readFile(path))
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code === 'ENOENT') return null
+    throw e
+  }
+}
+
+function cidOf(bytes: Uint8Array): string {
+  return `0x${createHash('sha256').update(bytes).digest('hex')}`
+}

package/src/storage/sqlite.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'bun:test'
+import { SqliteStorage } from './sqlite'
+
+const enc = (s: string) => new TextEncoder().encode(s)
+const dec = (b: Uint8Array | null) => (b ? new TextDecoder().decode(b) : null)
+
+describe('SqliteStorage', () => {
+  it('round-trips a content-addressed blob', async () => {
+    const s = new SqliteStorage(':memory:')
+    const cid = await s.putBlob(enc('hello sui'))
+    expect(cid).toMatch(/^0x[0-9a-f]{64}$/)
+    // Same bytes -> same CID (content addressed, idempotent).
+    expect(await s.putBlob(enc('hello sui'))).toBe(cid)
+    expect(dec(await s.getBlob(cid))).toBe('hello sui')
+    expect(await s.getBlob('0xdeadbeef')).toBeNull()
+    s.close()
+  })
+
+  it('stores + overwrites KV and appends to the log', async () => {
+    const s = new SqliteStorage(':memory:')
+    await s.putKV('stream1', 'k', enc('v1'))
+    await s.putKV('stream1', 'k', enc('v2'))
+    expect(dec(await s.getKV('stream1', 'k'))).toBe('v2')
+    expect(await s.getKV('stream1', 'missing')).toBeNull()
+    const cid = await s.appendLog('stream1', enc('entry'))
+    expect(cid).toMatch(/^0x[0-9a-f]{64}$/)
+    s.close()
+  })
+})

package/src/storage/sqlite.ts

@@ -0,0 +1,95 @@
+import { Database } from 'bun:sqlite'
+import { createHash } from 'node:crypto'
+import { mkdirSync } from 'node:fs'
+import { dirname } from 'node:path'
+import type { Storage } from './types'
+
+/**
+ * SQLite-backed Storage (via `bun:sqlite`). Replaces the prior decentralized
+ * blob backend with a local, zero-infra store — ideal for the agent's
+ * encrypted memory and easy to demo. Implements the same three primitives:
+ *   - KV:   mutable value per (stream, key)
+ *   - Log:  append-only entries, each addressed by content CID
+ *   - Blob: immutable, content-addressed bytes
+ *
+ * CID convention matches LocalStubStorage: `0x` + sha256(bytes) hex.
+ */
+export class SqliteStorage implements Storage {
+  private readonly db: Database
+
+  /** @param path SQLite file path (defaults to in-memory). Parent dir is created. */
+  constructor(path = ':memory:') {
+    if (path !== ':memory:') {
+      mkdirSync(dirname(path), { recursive: true })
+    }
+    this.db = new Database(path, { create: true })
+    this.db.run('PRAGMA journal_mode = WAL;')
+    this.db.run(
+      `CREATE TABLE IF NOT EXISTS kv (
+         stream TEXT NOT NULL,
+         key    TEXT NOT NULL,
+         value  BLOB NOT NULL,
+         PRIMARY KEY (stream, key)
+       );`,
+    )
+    this.db.run(
+      `CREATE TABLE IF NOT EXISTS log (
+         id     INTEGER PRIMARY KEY AUTOINCREMENT,
+         stream TEXT NOT NULL,
+         cid    TEXT NOT NULL,
+         entry  BLOB NOT NULL,
+         ts     INTEGER NOT NULL
+       );`,
+    )
+    this.db.run('CREATE INDEX IF NOT EXISTS log_stream_idx ON log (stream, id);')
+    this.db.run(
+      `CREATE TABLE IF NOT EXISTS blob (
+         cid   TEXT PRIMARY KEY,
+         bytes BLOB NOT NULL
+       );`,
+    )
+  }
+
+  async putKV(stream: string, key: string, value: Uint8Array): Promise<void> {
+    this.db
+      .query('INSERT OR REPLACE INTO kv (stream, key, value) VALUES (?, ?, ?)')
+      .run(stream, key, value)
+  }
+
+  async getKV(stream: string, key: string): Promise<Uint8Array | null> {
+    const row = this.db
+      .query('SELECT value FROM kv WHERE stream = ? AND key = ?')
+      .get(stream, key) as { value: Uint8Array } | null
+    return row ? new Uint8Array(row.value) : null
+  }
+
+  async appendLog(stream: string, entry: Uint8Array): Promise<string> {
+    const cid = cidOf(entry)
+    this.db
+      .query('INSERT INTO log (stream, cid, entry, ts) VALUES (?, ?, ?, ?)')
+      .run(stream, cid, entry, Date.now())
+    return cid
+  }
+
+  async putBlob(bytes: Uint8Array): Promise<string> {
+    const cid = cidOf(bytes)
+    this.db.query('INSERT OR IGNORE INTO blob (cid, bytes) VALUES (?, ?)').run(cid, bytes)
+    return cid
+  }
+
+  async getBlob(cid: string): Promise<Uint8Array | null> {
+    const row = this.db.query('SELECT bytes FROM blob WHERE cid = ?').get(cid) as {
+      bytes: Uint8Array
+    } | null
+    return row ? new Uint8Array(row.bytes) : null
+  }
+
+  /** Close the underlying database handle. */
+  close(): void {
+    this.db.close()
+  }
+}
+
+function cidOf(bytes: Uint8Array): string {
+  return `0x${createHash('sha256').update(bytes).digest('hex')}`
+}

package/src/storage/types.ts

@@ -0,0 +1,21 @@
+/**
+ * Storage interface abstracting Sui Storage's three primitives as used by lyra:
+ *   - KV: mutable key→value per namespace
+ *   - Log: append-only, returns CID per entry
+ *   - Blob: immutable bytes, content-addressed
+ *
+ * Phase 1 ships a local-disk stub. Phase 5 ships the real @0gfoundation/0g-ts-sdk
+ * backend + on-chain-event replay for KV reads (per verified architecture).
+ */
+export interface Storage {
+  /** Put a value into a named stream under a key. */
+  putKV(streamId: string, key: string, value: Uint8Array): Promise<void>
+  /** Get the latest value for (streamId, key) or null. */
+  getKV(streamId: string, key: string): Promise<Uint8Array | null>
+  /** Append an entry to a stream's log. Returns CID (rootHash) of the entry. */
+  appendLog(streamId: string, entry: Uint8Array): Promise<string>
+  /** Upload immutable bytes, returns content CID. */
+  putBlob(bytes: Uint8Array): Promise<string>
+  /** Retrieve bytes by CID. */
+  getBlob(cid: string): Promise<Uint8Array | null>
+}