@xingular/harness 0.1.6 → 0.1.7

package/src/hub/hub.test.ts

@@ -0,0 +1,205 @@
+import { createHash } from 'node:crypto'
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { Bus } from '../core/bus'
+import { Harness } from '../harness'
+import { memorySecretStore } from '../accounts/secrets'
+import * as registry from '../skills/registry'
+import { Hub } from './hub'
+import { hubCatalogSchema, hubEntrySchema, type HubEntry } from './schema'
+import { runHubMenu } from '../terminal/hubMenu'
+import { SessionSocket } from '../terminal/socket'
+import { HarnessError } from '../core/errors'
+import { runHubCli } from './cli'
+import * as packageApi from '../plugins/api'
+import * as packageInstall from '../plugins/install'
+import type { Plugin } from '../plugins/types'
+
+const folders: string[] = []
+afterEach(() => { vi.restoreAllMocks(); for (const folder of folders.splice(0)) rmSync(folder, { recursive: true, force: true }) })
+function entry(kind: 'document' | 'registry' = 'document', content = '{"message":"data only"}'): HubEntry {
+  return hubEntrySchema.parse({ id: 'example/review', title: 'Review', description: 'A reviewed item.', publisher: 'Example', license: 'MIT', version: '1.0.0', category: kind === 'document' ? 'preset' : 'skill', channel: 'community', tags: [], requires: {}, sourceUrl: 'https://github.com/example/review', delivery: { kind, ...(kind === 'registry' ? { registryKind: 'skills' } : {}), url: 'https://raw.githubusercontent.com/example/review/main/payload.json', sha256: createHash('sha256').update(content).digest('hex'), bundled: content } })
+}
+function fixture(items: HubEntry[], fetcher?: typeof fetch) {
+  const root = mkdtempSync(join(tmpdir(), 'hub-test-')); folders.push(root)
+  const harness = { dataRoot: join(root, 'data'), stateDir: join(root, 'state'), env: { root: join(root, 'data') }, bus: new Bus() } as Harness
+  const hub = new Hub(harness, { catalog: { schemaVersion: 1, entries: items }, fetch: fetcher })
+  return { hub, harness, root: harness.env.root }
+}
+const skill = (name = 'review', path = 'SKILL.md') => JSON.stringify({ items: [{ name, files: [{ path, encoding: 'utf8', content: '---\nname: review\ndescription: Review evidence.\n---\n\nRead sources.' }] }] })
+
+describe('Hub installation', () => {
+  it('stores documents inertly, idempotently, and checks their digest on read', async () => {
+    const { hub, root } = fixture([entry()])
+    const receipt = await hub.install('example/review', '1.0.0')
+    expect(receipt.resourceIds).toEqual([])
+    expect(await hub.install('example/review', '1.0.0')).toEqual(receipt)
+    expect(hub.readDocument('example/review', '1.0.0').content).toContain('data only')
+    expect(existsSync(join(root, 'config', 'plugin-attachments.json'))).toBe(false)
+    writeFileSync(join(root, 'hub', 'documents', receipt.document!), '{"edited":true}')
+    expect(() => hub.readDocument('example/review', '1.0.0')).toThrow('differs')
+  })
+  it('imports complete skills disabled and refuses overwriting local files', async () => {
+    const { hub, root } = fixture([entry('registry', skill())])
+    const receipt = await hub.install('example/review', '1.0.0')
+    expect(receipt.resourceIds).toEqual(['skills/review'])
+    expect(registry.enabledFor(root, null)).toEqual([])
+    const content = readFileSync(join(root, 'registry', 'skills', 'review', 'SKILL.md'), 'utf8')
+    const collision = { ...entry('registry', skill()), id: 'other/review' }
+    const another = new Hub(({ dataRoot: root, env: { root }, stateDir: join(root, 'state'), bus: new Bus() }) as Harness, { catalog: { schemaVersion: 1, entries: [collision] } })
+    await expect(another.install(collision.id, collision.version)).rejects.toThrow('already exists')
+    expect(readFileSync(join(root, 'registry', 'skills', 'review', 'SKILL.md'), 'utf8')).toBe(content)
+  })
+  it.each(['../escape', 'folder/../../escape', 'C:/escape', '.hidden/SKILL.md'])('rejects registry path %s before writing', async (path) => {
+    const { hub, root } = fixture([entry('registry', skill('review', path))])
+    await expect(hub.install('example/review', '1.0.0')).rejects.toThrow()
+    expect(registry.list(root)).toEqual([])
+    expect(existsSync(join(root, 'hub', 'installed.json'))).toBe(false)
+  })
+  it('imports prompts and rules as single Markdown files, disabled', async () => {
+    for (const kind of ['prompts', 'rules'] as const) {
+      const item = entry('registry', JSON.stringify({ items: [{ name: 'review', files: [{ path: 'CONTENT.md', encoding: 'utf8', content: '# Review\nRead evidence.' }] }] }))
+      if (item.delivery.kind === 'registry') item.delivery.registryKind = kind
+      const { hub, root } = fixture([item])
+      await hub.install(item.id, item.version)
+      expect(readFileSync(join(root, 'registry', kind, 'review.md'), 'utf8')).toContain('Read evidence')
+      expect(registry.enabledFor(root, null)).toEqual([])
+    }
+  })
+  it('does not commit a download with the wrong digest', async () => {
+    const item = entry(); if (item.delivery.kind !== 'pi-package') delete item.delivery.bundled
+    const { hub, root } = fixture([item], (async () => new Response('{"different":true}')) as typeof fetch)
+    await expect(hub.install(item.id, item.version)).rejects.toThrow('differs')
+    expect(existsSync(join(root, 'hub', 'installed.json'))).toBe(false)
+    expect(hub.busy).toBe(false)
+  })
+  it('rejects malformed UTF-8 JSON even when its byte digest matches', async () => {
+    const bytes = Buffer.from([0x7b, 0x22, 0x78, 0x22, 0x3a, 0x22, 0xff, 0x22, 0x7d])
+    const item = entry()
+    if (item.delivery.kind !== 'pi-package') { delete item.delivery.bundled; item.delivery.sha256 = createHash('sha256').update(bytes).digest('hex') }
+    const { hub, root } = fixture([item], (async () => new Response(bytes)) as typeof fetch)
+    await expect(hub.install(item.id, item.version)).rejects.toThrow('valid UTF-8')
+    expect(existsSync(join(root, 'hub', 'installed.json'))).toBe(false)
+  })
+  it('previews reviewed bytes without creating files or receipts', async () => {
+    const item = entry(); if (item.delivery.kind !== 'pi-package') delete item.delivery.bundled
+    const { hub, root } = fixture([item], (async () => new Response('{"message":"data only"}')) as typeof fetch)
+    const preview = await hub.get(item.id, item.version, true)
+    expect(preview.delivery.kind !== 'pi-package' && preview.delivery.bundled).toContain('data only')
+    expect(existsSync(join(root, 'hub'))).toBe(false)
+  })
+  it('can reinstall deleted resources and clears stale attachment grants', async () => {
+    const { hub, root } = fixture([entry('registry', skill())])
+    await hub.install('example/review', '1.0.0')
+    registry.setEnabled(root, null, ['skills/review'])
+    rmSync(join(root, 'registry', 'skills', 'review'), { recursive: true })
+    expect((await hub.list()).installed).toEqual([])
+    await hub.install('example/review', '1.0.0')
+    expect(registry.enabledFor(root, null)).toEqual([])
+    expect((await hub.list()).installed).toHaveLength(1)
+  })
+  it('preserves corrupt installation records rather than overwriting them', async () => {
+    const { hub, root } = fixture([entry()])
+    mkdirSync(join(root, 'hub'), { recursive: true })
+    writeFileSync(join(root, 'hub', 'installed.json'), 'corrupt')
+    await expect(hub.install('example/review', '1.0.0')).rejects.toThrow('could not be read')
+    expect(readFileSync(join(root, 'hub', 'installed.json'), 'utf8')).toBe('corrupt')
+  })
+  it('requires the terminal extension control key for hub mutations', async () => {
+    const { hub, root } = fixture([entry()])
+    const socket = new SessionSocket(join(root, 'unused.sock'), { memory: () => '', apps: async () => null,
+      plugins: async (_grant, method, params, control) => {
+        if (method === 'hub.list') return hub.list()
+        if (!control) throw new HarnessError('unauthorized', 'Only the terminal controls installations.')
+        return hub.install(String(params.id), String(params.version))
+      } })
+    const token = socket.issue({ sessionId: 'terminal', caller: () => ({}), broker: null })
+    const install = { token, call: 'hub.install', params: { id: 'example/review', version: '1.0.0' } }
+    expect(await socket.handle(JSON.stringify(install))).toHaveProperty('error')
+    const claim = await socket.handle(JSON.stringify({ token, call: 'control.claim' })) as { result: { key: string } }
+    expect(await socket.handle(JSON.stringify({ ...install, control: claim.result.key }))).toHaveProperty('result.document')
+    await socket.close()
+  })
+  it('CLI installs into the explicit library without opening or settling runs', async () => {
+    const { hub, harness, root } = fixture([entry()])
+    const output: string[] = []
+    const code = await runHubCli(['install', 'example/review@1.0.0', '--data', root, '--state', harness.stateDir], { write: (text) => output.push(text), createHarness: (options) => {
+      expect(options.dataRoot).toBe(root)
+      return { ...harness, hub, close: async () => undefined } as unknown as Harness
+    } })
+    expect(code).toBe(0)
+    expect(output.join('')).toContain('Saved example/review@1.0.0')
+    expect(existsSync(join(root, 'runs'))).toBe(false)
+  })
+  it('uses the last valid catalog when refresh fails or has duplicate versions', async () => {
+    let response = JSON.stringify({ schemaVersion: 1, entries: [entry()] })
+    const { hub } = fixture([], (async () => new Response(response)) as typeof fetch)
+    expect((await hub.list(true)).origin).toBe('remote')
+    response = JSON.stringify({ schemaVersion: 1, entries: [entry(), entry()] })
+    const cached = await hub.list(true)
+    expect(cached.origin).toBe('cached')
+    expect(cached.error).toBeTruthy()
+    expect(cached.entries).toHaveLength(1)
+    expect((await hub.list()).entries).toHaveLength(1)
+  })
+  it('rejects simultaneous writers and releases locks after a failed download', async () => {
+    const item = entry(); if (item.delivery.kind !== 'pi-package') delete item.delivery.bundled
+    let resolve!: (response: Response) => void
+    const { hub } = fixture([item], (() => new Promise<Response>((done) => { resolve = done })) as typeof fetch)
+    const first = hub.install(item.id, item.version)
+    await expect(hub.install(item.id, item.version)).rejects.toThrow('Another installation')
+    resolve(new Response('bad digest'))
+    await expect(first).rejects.toThrow('differs')
+    expect(hub.busy).toBe(false)
+  })
+  it('keeps an in-progress installation pinned to its data root', async () => {
+    const item = entry(); if (item.delivery.kind !== 'pi-package') delete item.delivery.bundled
+    const root = mkdtempSync(join(tmpdir(), 'hub-root-pin-')); folders.push(root)
+    let resolve!: (response: Response) => void
+    const harness = new Harness({ dataRoot: join(root, 'data'), stateDir: join(root, 'state'), secrets: memorySecretStore(), hub: { catalog: { schemaVersion: 1, entries: [item] }, fetch: (() => new Promise<Response>((done) => { resolve = done })) as typeof fetch } })
+    try {
+      const pending = harness.hub.install(item.id, item.version)
+      expect(() => harness.open(join(root, 'other'))).toThrow('Wait for the hub installation')
+      expect(harness.dataRoot).toBe(join(root, 'data'))
+      resolve(new Response('{"message":"data only"}'))
+      await pending
+      expect((await harness.hub.list()).installed).toHaveLength(1)
+      expect(existsSync(join(root, 'other'))).toBe(false)
+    } finally { await harness.close() }
+  })
+  it('rejects unpinned packages and incompatible runtimes', async () => {
+    expect(() => hubEntrySchema.parse({ ...entry(), delivery: { kind: 'pi-package', source: 'npm:unknown@latest' } })).toThrow()
+    expect(() => hubCatalogSchema.parse({ schemaVersion: 2, entries: [] })).toThrow()
+    const item = { ...entry(), requires: { harness: '99.0.0' } }
+    const { hub } = fixture([item])
+    await expect(hub.install(item.id, item.version)).rejects.toThrow('requires Harness')
+  })
+  it('records only the requested package when another plugin appears during installation', async () => {
+    const source = 'npm:@example/review@1.0.0'
+    const item = hubEntrySchema.parse({ ...entry(), category: 'plugin', delivery: { kind: 'pi-package', source } })
+    const { hub } = fixture([item])
+    vi.spyOn(packageApi, 'list').mockResolvedValue([])
+    vi.spyOn(packageInstall, 'install').mockResolvedValue([
+      { id: 'package:review', install: { kind: 'settings', source } } as Plugin,
+      { id: 'package:another', install: { kind: 'settings', source: 'npm:@someone/other@1.0.0' } } as Plugin
+    ])
+    expect((await hub.install(item.id, item.version)).resourceIds).toEqual(['package:review'])
+    expect(packageInstall.install).toHaveBeenCalledWith(expect.anything(), { source })
+  })
+  it('does not treat cancelling the terminal review as an install', async () => {
+    const { hub } = fixture([entry()])
+    const calls: string[] = []
+    const choices = ['Review · preset · example/review@1.0.0', 'Done']
+    await runHubMenu({ select: async () => choices.shift(), confirm: async () => false, notify: () => undefined }, async <T>(method: string) => { calls.push(method); return await hub.list() as T })
+    expect(calls).toEqual(['hub.list', 'hub.list'])
+  })
+  it('refuses an already-held library lock', async () => {
+    const { hub, root } = fixture([entry()])
+    mkdirSync(join(root, 'hub'), { recursive: true })
+    writeFileSync(join(root, 'hub', 'install.lock'), String(process.pid))
+    await expect(hub.install('example/review', '1.0.0')).rejects.toThrow('Another installation')
+    expect(hub.busy).toBe(false)
+  })
+})

package/src/hub/hub.ts

@@ -0,0 +1,256 @@
+import { createHash } from 'node:crypto'
+import { closeSync, lstatSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { watch } from 'node:fs'
+
+import { HarnessError, invalid } from '../core/errors'
+import { atomicWrite, now, readJson, readJsonOr, writeJson } from '../core/fs'
+import type { Harness } from '../harness'
+import * as pluginApi from '../plugins/api'
+import * as packages from '../plugins/install'
+import * as registry from '../skills/registry'
+import * as attachments from '../plugins/attachments'
+import { version as harnessVersion } from '../../package.json'
+import bundled from './catalog.json'
+import { HUB_CATALOG_URL, HUB_MAX_BYTES, hubCatalogSchema, hubEntrySchema, hubReceiptSchema, meetsMinimum, type HubCatalog, type HubEntry, type HubOverview, type HubReceipt } from './schema'
+
+export interface HubOptions {
+  catalogUrl?: string
+  catalog?: HubCatalog
+  fetch?: typeof globalThis.fetch
+}
+
+const digest = (bytes: Uint8Array | string): string => createHash('sha256').update(bytes).digest('hex')
+const receiptName = (entry: Pick<HubEntry, 'id' | 'version'>): string => digest(`${entry.id}@${entry.version}`)
+
+/** Acquires an exclusive writer lock. A crashed writer's lock is recovered only when its PID is gone. */
+function acquire(path: string): () => void {
+  mkdirSync(join(path, '..'), { recursive: true })
+  try {
+    const file = openSync(path, 'wx', 0o600)
+    try { writeFileSync(file, `${process.pid}`) } finally { closeSync(file) }
+    return () => rmSync(path, { force: true })
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error
+    // Serialize stale-lock recovery too: two reapers must never remove a new writer's lock.
+    let recovery: number
+    try { recovery = openSync(`${path}.recovery`, 'wx', 0o600) } catch {
+      throw new HarnessError('hub_busy', 'Another installation is using this library. Wait and retry.')
+    }
+    try {
+      const pid = Number(readFileSync(path, 'utf8'))
+      if (Number.isInteger(pid) && pid > 0) {
+        try { process.kill(pid, 0) } catch (probe) {
+          if ((probe as NodeJS.ErrnoException).code === 'ESRCH') {
+            rmSync(path)
+            return acquire(path)
+          }
+        }
+      }
+      throw new HarnessError('hub_busy', 'Another installation is using this library. Wait for it to finish and retry.')
+    } finally { closeSync(recovery); rmSync(`${path}.recovery`, { force: true }) }
+  }
+}
+
+/** Catalog data never loads extensions or changes attachment, trust, or connector scopes. */
+export class Hub {
+  private readonly fallback: HubCatalog
+  private readonly fetcher: typeof globalThis.fetch
+  private readonly catalogUrl: string
+  private watcher: ReturnType<typeof watch> | null = null
+  private refresh: Promise<HubOverview> | null = null
+  private installing = false
+  get busy(): boolean { return this.installing }
+
+  constructor(private readonly harness: Harness, options: HubOptions = {}) {
+    this.fallback = hubCatalogSchema.parse(options.catalog ?? bundled)
+    this.fetcher = options.fetch ?? globalThis.fetch
+    this.catalogUrl = options.catalogUrl ?? HUB_CATALOG_URL
+  }
+
+  private receipts(): HubReceipt[] {
+    const root = this.harness.dataRoot
+    if (!root) return []
+    const values = readJson<unknown[]>(join(root, 'hub', 'installed.json')) ?? []
+    if (!Array.isArray(values)) throw invalid('The hub installation records could not be read.')
+    return values.map((value) => hubReceiptSchema.parse(value))
+  }
+
+  private snapshot(): HubOverview {
+    const cached = readJsonOr<{ catalog: unknown; at: string } | null>(join(this.harness.stateDir, 'hub', 'catalog.json'), null)
+    const parsed = hubCatalogSchema.safeParse(cached?.catalog)
+    const catalog = parsed.success ? parsed.data : this.fallback
+    const installed = this.receipts().filter((receipt) => this.present(receipt))
+    const entries = new Map(catalog.entries.map((entry) => [`${entry.id}@${entry.version}`, entry]))
+    for (const receipt of installed) if (!entries.has(`${receipt.entry.id}@${receipt.entry.version}`)) entries.set(`${receipt.entry.id}@${receipt.entry.version}`, receipt.entry)
+    return { entries: [...entries.values()], installed, origin: parsed.success ? 'cached' : 'bundled', refreshedAt: parsed.success ? cached!.at : null, error: null, dataRoot: this.harness.dataRoot, stateDir: this.harness.stateDir }
+  }
+
+  private present(receipt: HubReceipt): boolean {
+    const root = this.harness.dataRoot
+    if (!root) return false
+    try {
+      if (receipt.document) {
+        if (receipt.entry.delivery.kind !== 'document' || receipt.document !== `${receiptName(receipt.entry)}.json`) return false
+        const path = join(root, 'hub', 'documents', receipt.document)
+        const stat = lstatSync(path)
+        return stat.isFile() && stat.size <= HUB_MAX_BYTES && digest(readFileSync(path)) === receipt.entry.delivery.sha256
+      }
+      if (receipt.entry.delivery.kind === 'registry') return receipt.resourceIds.length > 0 && receipt.resourceIds.every((id) => {
+        if (!/^(skills|prompts|rules)\/[a-z0-9-]{1,64}$/.test(id)) return false
+        const [kind, name] = id.split('/')
+        return lstatSync(join(root, 'registry', kind, kind === 'skills' ? `${name}/SKILL.md` : `${name}.md`)).isFile()
+      })
+      if (receipt.entry.delivery.kind === 'pi-package') {
+        const source = receipt.entry.delivery.source
+        const settings = readJsonOr<{ packages?: Array<string | { source: string }> }>(join(this.harness.stateDir, 'accounts', '_shared', 'pi', 'settings.json'), {})
+        return settings.packages?.some((item) => (typeof item === 'string' ? item : item.source) === source) ?? false
+      }
+    } catch { return false }
+    return false
+  }
+
+  async list(refresh = false): Promise<HubOverview> {
+    if (!refresh) return this.snapshot()
+    this.refresh ??= this.refreshCatalog().finally(() => { this.refresh = null })
+    return this.refresh
+  }
+
+  private async bytes(url: string): Promise<Buffer> {
+    const parsed = new URL(url)
+    if (parsed.protocol !== 'https:' || parsed.username || parsed.password || parsed.search || parsed.hash || parsed.port || parsed.hostname !== 'raw.githubusercontent.com') throw invalid('Hub downloads must use public raw.githubusercontent.com HTTPS URLs.')
+    const response = await this.fetcher(url, { redirect: 'error', credentials: 'omit', signal: AbortSignal.timeout(30_000) })
+    if (!response.ok) throw new Error(`The catalog source returned ${response.status}.`)
+    if (Number(response.headers.get('content-length') ?? 0) > HUB_MAX_BYTES) throw invalid('The hub download exceeds 16 MiB.')
+    if (!response.body) throw invalid('The hub download has no body.')
+    const reader = response.body.getReader()
+    const chunks: Uint8Array[] = []
+    let size = 0
+    try {
+      for (;;) {
+        const { done, value } = await reader.read()
+        if (done) break
+        size += value.byteLength
+        if (size > HUB_MAX_BYTES) throw invalid('The hub download exceeds 16 MiB.')
+        chunks.push(value)
+      }
+    } finally { await reader.cancel().catch(() => undefined) }
+    return Buffer.concat(chunks)
+  }
+
+  private async refreshCatalog(): Promise<HubOverview> {
+    try {
+      const catalog = hubCatalogSchema.parse(JSON.parse(this.decode(await this.bytes(this.catalogUrl))))
+      writeJson(join(this.harness.stateDir, 'hub', 'catalog.json'), { catalog, at: now() })
+      this.harness.bus.emit({ type: 'hub.changed' })
+      return { ...this.snapshot(), origin: 'remote' }
+    } catch (error) {
+      return { ...this.snapshot(), error: error instanceof Error ? error.message : String(error) }
+    }
+  }
+
+  private decode(bytes: Buffer): string {
+    const text = bytes.toString('utf8')
+    if (!Buffer.from(text).equals(bytes)) throw invalid('Hub JSON must use valid UTF-8.')
+    return text
+  }
+
+  private find(id: string, version: string): HubEntry {
+    const entry = this.snapshot().entries.find((item) => item.id === id && item.version === version)
+    if (!entry) throw invalid('That item version is not in this catalog. Refresh the Hub and try again.')
+    return entry
+  }
+
+  async get(id: string, version: string, preview = false): Promise<HubEntry> {
+    const entry = this.find(id, version)
+    if (!preview || entry.delivery.kind === 'pi-package' || entry.delivery.bundled !== undefined) return entry
+    const bytes = await this.bytes(entry.delivery.url)
+    if (digest(bytes) !== entry.delivery.sha256) throw invalid('The downloaded item differs from the reviewed version.')
+    return { ...entry, delivery: { ...entry.delivery, bundled: this.decode(bytes) } }
+  }
+
+  async install(id: string, version: string): Promise<HubReceipt> {
+    const root = this.harness.env.root
+    const entry = hubEntrySchema.parse(this.find(id, version))
+    if (entry.requires.harness && !meetsMinimum(harnessVersion, entry.requires.harness)) throw invalid(`This item requires Harness ${entry.requires.harness} or newer.`)
+    const releaseState = acquire(join(this.harness.stateDir, 'hub', 'install.lock'))
+    this.installing = true
+    let releaseData: (() => void) | null = null
+    try {
+      releaseData = acquire(join(root, 'hub', 'install.lock'))
+      const records = this.receipts()
+      const existing = records.find((receipt) => receipt.entry.id === id && receipt.entry.version === version)
+      if (existing && this.present(existing)) return existing
+      const remaining = records.filter((record) => record !== existing)
+      const receipt: HubReceipt = { entry, installedAt: now(), resourceIds: [], document: null }
+      const choicesBefore = attachments.load(root)
+      if (entry.delivery.kind === 'pi-package') {
+        const source = entry.delivery.source
+        if (remaining.some((record) => record.entry.id === id && this.present(record))) throw invalid('Another version is already installed. Manage the existing plugin before replacing it.')
+        const before = await pluginApi.list(this.harness, {})
+        const identity = (value: string): string => value.slice(0, value.lastIndexOf('@'))
+        if (before.some((plugin) => plugin.install && identity(plugin.install.source) === identity(source))) throw invalid('This package is already installed. Manage it in Plugins.')
+        const after = await packages.install(this.harness, { source })
+        receipt.resourceIds = after.filter((plugin) => plugin.install?.source === source && !before.some((old) => old.id === plugin.id)).map((plugin) => plugin.id)
+        if (!receipt.resourceIds.length) throw invalid('The package did not add an installable plugin. No hub installation was recorded.')
+      } else {
+        const delivery = entry.delivery
+        const bytes = delivery.bundled === undefined ? await this.bytes(delivery.url) : Buffer.from(delivery.bundled)
+        if (digest(bytes) !== delivery.sha256) throw invalid('The downloaded item differs from the reviewed version. Nothing was installed.')
+        const text = this.decode(bytes)
+        if (delivery.kind === 'document') {
+          JSON.parse(text)
+          receipt.document = `${receiptName(entry)}.json`
+          atomicWrite(join(root, 'hub', 'documents', receipt.document), bytes)
+        } else {
+          const payload = JSON.parse(text)
+          const previous = new Set(registry.list(root).map((item) => item.id))
+          const imported = registry.importItems(root, delivery.registryKind, payload.items)
+          receipt.resourceIds = imported.items.filter((item) => !previous.has(item.id)).map((item) => item.id)
+          const choices = structuredClone(choicesBefore)
+          const ids = new Set(receipt.resourceIds)
+          for (const scope of [choices.global, ...Object.values(choices.agents), ...Object.values(choices.projects)]) {
+            scope.on = scope.on.filter((id) => !ids.has(id))
+            scope.off = scope.off.filter((id) => !ids.has(id))
+          }
+          attachments.save(root, choices)
+        }
+      }
+      try { writeJson(join(root, 'hub', 'installed.json'), [...remaining, receipt]) } catch (error) {
+        if (receipt.document) rmSync(join(root, 'hub', 'documents', receipt.document), { force: true })
+        if (entry.delivery.kind === 'registry') for (const id of receipt.resourceIds) {
+          const [kind, name] = id.split('/')
+          rmSync(join(root, 'registry', kind, kind === 'skills' ? name : `${name}.md`), { recursive: true, force: true })
+        }
+        if (entry.delivery.kind === 'registry') attachments.save(root, choicesBefore)
+        if (entry.delivery.kind === 'pi-package') for (const pluginId of receipt.resourceIds) await packages.remove(this.harness, { pluginId })
+        throw error
+      }
+      this.harness.bus.emit({ type: 'hub.changed' })
+      this.harness.bus.emit({ type: 'plugins.changed' })
+      return receipt
+    } finally { this.installing = false; releaseData?.(); releaseState() }
+  }
+
+  readDocument(id: string, version: string): { entry: HubEntry; content: string } {
+    const receipt = this.receipts().find((item) => item.entry.id === id && item.entry.version === version)
+    if (!receipt?.document || receipt.document !== `${receiptName(receipt.entry)}.json`) throw invalid('Install this document before opening it.')
+    const path = join(this.harness.env.root, 'hub', 'documents', receipt.document)
+    const stat = lstatSync(path)
+    if (!stat.isFile() || stat.size > HUB_MAX_BYTES) throw invalid('The saved document is not a bounded regular file.')
+    const content = readFileSync(path, 'utf8')
+    if (receipt.entry.delivery.kind === 'pi-package' || digest(content) !== receipt.entry.delivery.sha256) throw invalid('The saved document differs from the installed version. Import edited files explicitly instead.')
+    return { entry: receipt.entry, content }
+  }
+
+  watch(root: string): void {
+    this.watcher?.close()
+    mkdirSync(join(root, 'hub'), { recursive: true })
+    this.watcher = watch(join(root, 'hub'), { persistent: false }, (_event, name) => {
+      if (name === 'installed.json') this.harness.bus.emit({ type: 'hub.changed' })
+    })
+    this.watcher.on('error', () => { this.watcher?.close(); this.watcher = null })
+  }
+
+  close(): void { this.watcher?.close(); this.watcher = null }
+}

package/src/hub/schema.ts

@@ -0,0 +1,81 @@
+import { z } from 'zod'
+
+export const HUB_CATALOG_URL = 'https://raw.githubusercontent.com/tanntnny/xingular-hub/main/catalog.json'
+export const HUB_MAX_BYTES = 16 * 1024 * 1024
+
+const httpsUrl = z.string().max(2000).url().refine((value) => {
+  const url = new URL(value)
+  return url.protocol === 'https:' && !url.username && !url.password && !url.search && !url.hash && !url.port
+}, 'Use a public HTTPS URL without credentials, queries, or fragments.')
+const payload = {
+  url: httpsUrl,
+  sha256: z.string().regex(/^[a-f0-9]{64}$/),
+  bundled: z.string().max(HUB_MAX_BYTES).optional()
+}
+
+export const hubDeliverySchema = z.discriminatedUnion('kind', [
+  z.object({ kind: z.literal('registry'), registryKind: z.enum(['skills', 'prompts', 'rules']), ...payload }).strict(),
+  z.object({ kind: z.literal('document'), ...payload }).strict(),
+  z.object({ kind: z.literal('pi-package'), source: z.string().max(2000).refine((source) =>
+    /^npm:(?:@[a-z0-9_.-]+\/)?[a-z0-9_.-]+@\d+\.\d+\.\d+(?:-[a-zA-Z0-9.-]+)?$/.test(source)
+    || /^git:https:\/\/github\.com\/[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+(?:\.git)?@[a-f0-9]{40}$/.test(source),
+  'Packages must use an exact npm version or a GitHub commit.') }).strict()
+])
+
+export const hubEntrySchema = z.object({
+  id: z.string().regex(/^[a-z0-9-]{1,64}\/[a-z0-9-]{1,64}$/),
+  title: z.string().min(1).max(100),
+  description: z.string().min(1).max(500),
+  publisher: z.string().min(1).max(100),
+  license: z.string().min(1).max(100),
+  version: z.string().regex(/^\d+\.\d+\.\d+(?:-[a-zA-Z0-9.-]+)?$/),
+  category: z.string().regex(/^[a-z][a-z-]{0,40}$/),
+  channel: z.enum(['official', 'community']),
+  tags: z.array(z.string().max(60)).max(20),
+  requires: z.record(z.string(), z.string().regex(/^\d+\.\d+\.\d+$/)),
+  sourceUrl: httpsUrl,
+  delivery: hubDeliverySchema
+}).strict()
+
+export const hubCatalogSchema = z.object({
+  schemaVersion: z.literal(1),
+  entries: z.array(hubEntrySchema).max(2000)
+}).strict().superRefine((catalog, ctx) => {
+  const keys = new Set<string>()
+  catalog.entries.forEach((entry, index) => {
+    const key = `${entry.id}@${entry.version}`
+    if (keys.has(key)) ctx.addIssue({ code: 'custom', path: ['entries', index, 'id'], message: 'Duplicate catalog item version.' })
+    keys.add(key)
+  })
+})
+
+export const hubReceiptSchema = z.object({
+  entry: hubEntrySchema,
+  installedAt: z.string(),
+  resourceIds: z.array(z.string()),
+  document: z.string().nullable()
+}).strict()
+
+export const hubOverviewSchema = z.object({
+  entries: z.array(hubEntrySchema),
+  installed: z.array(hubReceiptSchema),
+  origin: z.enum(['bundled', 'cached', 'remote']),
+  refreshedAt: z.string().nullable(),
+  error: z.string().nullable(),
+  dataRoot: z.string().nullable(),
+  stateDir: z.string()
+})
+
+export type HubEntry = z.infer<typeof hubEntrySchema>
+export type HubCatalog = z.infer<typeof hubCatalogSchema>
+export type HubReceipt = z.infer<typeof hubReceiptSchema>
+export type HubOverview = z.infer<typeof hubOverviewSchema>
+
+export function meetsMinimum(actual: string, minimum: string): boolean {
+  const left = actual.split(/[.-]/).slice(0, 3).map(Number)
+  const right = minimum.split('.').map(Number)
+  for (let index = 0; index < 3; index += 1) {
+    if (left[index] !== right[index]) return left[index] > right[index]
+  }
+  return true
+}

package/src/index.ts

@@ -7,6 +7,7 @@
 // providers, a tool policy, a secret store, a directory of its own names, and a description of
 // its own parts as plugins. Everything else is reachable by path, e.g. `@xingular/harness/memory/wiki`.
 export { createHarness, Harness, type HarnessOptions, type Recovery } from './harness'
+export { hubCatalogSchema, hubEntrySchema, hubOverviewSchema, hubReceiptSchema, type HubCatalog, type HubEntry, type HubOverview, type HubReceipt } from './hub/schema'
 
 export { Bus, log, type Notice } from './core/bus'
 export { EMPTY_DIRECTORY, type Directory, type HarnessEnv } from './core/env'
@@ -15,7 +16,7 @@ export { findBinary, searchPath } from './core/path'
 
 export { fileSecretStore, memorySecretStore, secretKey, type SecretStore } from './accounts/secrets'
 export type { Account, AccountsOverview, Pool } from './accounts/store'
-export type { ModelOption } from './accounts/accounts'
+export type { AccountLoginSnapshot, ModelOption } from './accounts/accounts'
 export type { Capability, CapabilityCatalogue, CapabilityKind, CapabilityScope, CapabilitySet } from './capabilities/types'
 export type { RunCapabilitySnapshot } from './capabilities/runSnapshot'
 
@@ -46,7 +47,11 @@ export type { Effort } from './sessions/runner'
 
 export { describeTool, WIKI_TOOLS, WIKI_TOOL_NAMES, type WikiCall, type WikiToolDefinition } from './tools/definitions'
 export type { ToolProvider, ToolResult, ToolSession, ToolSpec } from './tools/types'
+export { SPAWN_SUBAGENT, SUBAGENT_RELATION, DEFAULT_SUBAGENT_DEPTH, MAX_SUBAGENT_DEPTH, type SubagentOptions } from './tools/spawnSubagent'
+export { maintenanceTools, MAINTENANCE_PLUGIN, MAINTENANCE_TOOL_NAMES } from './tools/maintenance'
+export type { CurationJob } from './memory/curation'
 export { webTools, WEB_PLUGIN, WEB_SEARCH_KEY, type WebToolOptions } from './web/tools'
+export { registryTools, REGISTRY_WRITE, PLUGIN_WRITE, REGISTRY_WRITE_PLUGIN, type RegistryToolOptions } from './tools/registryWrite'
 export { safeRequest, type WebRequest, type WebResponse } from './web/safeRequest'
 
 export type { BrokeredTools, BrokerSession, BrokerTool } from './mcp/service'

package/src/memory/api.ts

@@ -11,6 +11,7 @@ import { findRun, readEvents } from '../sessions/runStore'
 import type { RunEvent } from '../sessions/contracts'
 import { takeChars } from '../core/text'
 import * as registry from '../skills/registry'
+import { enqueueCuration } from './curation'
 import * as blocks from './blocks'
 import { actorOf, blockCaller, projectOf, type CallerContext } from './caller'
 import * as facts from './facts'
@@ -104,7 +105,7 @@ export function search(env: HarnessEnv, context: CallerContext, params: Params):
   // Another agent's blocks never appear; a block of the caller's own does.
   const own = ownBlocksPrefix(env, context)
   const hits = searchEntries(root, query, { kinds, namespace: textParam(params, 'namespace') || null, projectId: context.projectId, limit: limit + 6 })
-    .filter((hit) => !(hit.kind === 'block' && hit.type === 'agent') || (own !== null && hit.id.startsWith(own)))
+    .filter((hit) => context.vaultAccess === 'curator' || !(hit.kind === 'block' && hit.type === 'agent') || (own !== null && hit.id.startsWith(own)))
     .slice(0, limit)
   if (!hits.length) return 'No matching Wiki entries.'
   const wiki = store.wikiDir(root)
@@ -126,7 +127,7 @@ export function read(env: HarnessEnv, context: CallerContext, params: Params): s
   // An agent's own blocks are not readable by other agents or by sessions.
   if (entry.kind === 'block' && entry.block.scope === 'agent') {
     const own = ownBlocksPrefix(env, context)
-    if (own === null || `blocks/agents/${entry.block.owner}/` !== own) throw notFound('Wiki entry')
+    if (context.vaultAccess !== 'curator' && (own === null || `blocks/agents/${entry.block.owner}/` !== own)) throw notFound('Wiki entry')
   }
   const linking = backlinks(root, entryId(entry))
   const linked = linking.length ? linking.map((link) => `${link.fromId} (${link.type})`).join(', ') : 'none'
@@ -272,13 +273,26 @@ export function propose(env: HarnessEnv, context: CallerContext, params: Params)
     proposals = {
       memories: [{ id: optional(params, 'id'), title, kind: optional(params, 'type') ?? 'fact', body, namespace: optional(params, 'namespace'), confidence: optional(params, 'confidence'), supersedes: optional(params, 'supersedes'), volatile: typeof params?.volatile === 'boolean' ? params.volatile : null, sourceRefs: sourceRefs(params, context), links: links(params) }]
     }
+  } else if (kind === 'block') {
+    const id = textParam(params, 'id')
+    const block = blocks.find(wiki, id)
+    if (block.front.readOnly) throw invalid('This block is user-only; only the user can change it.')
+    proposals = { blocks: [{ block: id, body, sourceRefs: sourceRefs(params, context) }] }
   } else if (kind === 'skill' || kind === 'rule' || kind === 'prompt') {
+    if (context.vaultAccess) {
+      const job = enqueueCuration(root, { kind: 'registry', proposal: { kind, name: optional(params, 'id') ?? title, description: textParam(params, 'description'), body, reason: textParam(params, 'reason') }, caller: context })
+      return `Submitted proposal ${job.id} for curator review. Nothing has been changed.`
+    }
     const id = parkRegistryProposal(wiki, trigger, { kind, name: optional(params, 'id') ?? title, description: textParam(params, 'description'), body, reason: textParam(params, 'reason') })
     return `The ${kind} change (${id}) is waiting in the Wiki Inbox. Skills, prompts, and rules change only after the user accepts them.`
   } else {
     throw invalid('kind must be page, fact, skill, rule, or prompt.')
   }
   // The caller's own run is evidence only for what it can quote from it.
+  if (context.vaultAccess) {
+    const job = enqueueCuration(root, { kind: 'proposal', namespace: defaultNamespace, proposals: parseProposalSet(proposals), caller: context })
+    return `Submitted proposal ${job.id} for curator review. Nothing has been changed.`
+  }
   const outcome = apply(wiki, defaultNamespace, trigger, parseProposalSet(proposals), captureHashes(wiki), { runText: context.runId ? evidenceText(root, context.runId) : null })
   let text = outcome.notes.join('\n')
   if (outcome.operation) {

package/src/memory/blocks.ts

@@ -52,7 +52,7 @@ export interface Block {
 export type Caller =
   | { kind: 'user' }
   /** An agent with blocks of its own, and the name recorded on its revisions. */
-  | { kind: 'agent'; id: string; name: string }
+  | { kind: 'agent'; id: string; name: string; vaultAccess?: 'self' | 'propose' | 'curator' }
   /** A session without blocks of its own, and its project, if any. */
   | { kind: 'session'; projectSlug: string | null }
 
@@ -192,6 +192,8 @@ export function editRefusal(caller: Caller, block: Block): string | null {
   const label = block.front.label
   if (caller.kind === 'user') return null
   if (block.front.readOnly) return `The ${label} block is read-only; only the user can change it.`
+  if (caller.kind === 'agent' && caller.vaultAccess === 'propose') return 'Memory changes are proposals in this session. Submit the block change with wiki_propose; the next memory merge applies it.'
+  if (caller.kind === 'agent' && caller.vaultAccess === 'self' && (block.scope !== 'agent' || block.owner !== caller.id || !['persona', 'notes'].includes(label))) return 'This field is outside your writable memory. Submit a block change with wiki_propose for the curator to review.'
   if (caller.kind === 'agent') {
     if (block.scope === 'agent') return block.owner === caller.id ? null : 'That block belongs to another agent.'
     if (block.scope === 'shared') return !block.front.agents.length || block.front.agents.includes(caller.id) ? null : `The ${label} block is not attached to you.`