@xingular/harness 0.1.5 → 0.1.7

package/src/accounts/accounts.ts

@@ -45,8 +45,26 @@ function validProvider(provider: string): string {
 
 interface PendingLogin {
   accountId: string
+  provider: string
+  method: 'oauth' | 'api_key'
   cancel: () => void
   prompts: Map<string, { resolve: (value: string) => void; reject: (error: Error) => void }>
+  revision: number
+  events: Record<string, unknown>[]
+  prompt: Record<string, unknown> | null
+}
+
+export interface AccountLoginSnapshot {
+  accountId: string
+  loginId: string
+  provider: string
+  method: string
+  revision: number
+  status: 'running' | 'completed' | 'failed' | 'cancelled'
+  events: Record<string, unknown>[]
+  prompt: Record<string, unknown> | null
+  success: boolean | null
+  error: string | null
 }
 
 interface Probe {
@@ -71,7 +89,9 @@ export class Accounts {
   private readonly bus: Bus
   private readonly runtimes = new Map<string, Promise<ModelRuntime>>()
   private readonly logins = new Map<string, PendingLogin>()
+  private readonly latestLogins = new Map<string, AccountLoginSnapshot>()
   private readonly terminals = new Map<string, number>()
+  private installationDeviceIdPromise: Promise<string> | null = null
 
   constructor(options: AccountsOptions) {
     this.dir = options.dir
@@ -157,6 +177,25 @@ export class Accounts {
     }
   }
 
+  /** Pi's OAuth device ID belongs to this Harness installation, not to one isolated account. */
+  installationDeviceId(): Promise<string> {
+    if (!this.installationDeviceIdPromise) {
+      this.installationDeviceIdPromise = this.loadInstallationDeviceId().catch((error: unknown) => {
+        this.installationDeviceIdPromise = null
+        throw error
+      })
+    }
+    return this.installationDeviceIdPromise
+  }
+
+  private async loadInstallationDeviceId(): Promise<string> {
+    const { SettingsManager } = await import('@earendil-works/pi-coding-agent')
+    const settings = SettingsManager.create(process.cwd(), env.ensureSharedDir(this.dir))
+    const deviceId = settings.getOrCreateDeviceId()
+    await settings.flush()
+    return deviceId
+  }
+
   // ---- The Pi runtime ---------------------------------------------------------------------
 
   /** The lazily loaded Pi runtime of one account: its models and its credentials. Pi's own `~/.pi` is never used. */
@@ -250,7 +289,7 @@ export class Accounts {
         const keepLimitError = current.lastError !== null && store.isLimitCategory(current.lastError.category) && store.limitErrorActive(current.lastError)
         if (probe.signedIn === true && !keepLimitError) current.lastError = null
       } else {
-        current.lastError = { category: 'unknown', message: store.scrub(failure ?? ''), at: now(), resetsAt: null }
+        current.lastError = { category: classifyMessage(failure ?? '') ?? 'unknown', message: store.scrub(failure ?? ''), at: now(), resetsAt: null }
       }
     })
     if (previous !== state.health) store.audit(this.dir, account.id, 'health.changed', `${previous} → ${state.health} (status check)`)
@@ -295,6 +334,8 @@ export class Accounts {
   /** Deletes the account: removes its stored credentials and its runtime folder. Sessions pinned to it ask for another account next time they start. */
   async remove(accountId: string): Promise<AccountsOverview> {
     const account = this.find(accountId)
+    for (const login of this.logins.values()) if (login.accountId === accountId) login.cancel()
+    this.latestLogins.delete(accountId)
     await this.forgetCredentials(account).catch(() => undefined)
     await this.secrets.delete(secretKey(account.id, 'apiKey')).catch(() => undefined)
     store.forgetAccount(this.dir, account)
@@ -354,7 +395,7 @@ export class Accounts {
     return this.overview()
   }
 
-  private finishLogin(loginId: string, success: boolean, error: string | null): void {
+  private finishLogin(loginId: string, success: boolean, error: string | null, cancelled = false): void {
     const login = this.logins.get(loginId)
     if (!login) return
     this.logins.delete(loginId)
@@ -363,7 +404,25 @@ export class Accounts {
     store.audit(this.dir, login.accountId, success ? 'login.completed' : 'login.failed', error ?? '')
     // A fresh sign-in starts clean; a limit that still applies is reported again by the next run.
     if (success) store.updateState(this.dir, login.accountId, (current) => void (current.lastError = null))
-    this.bus.emit({ type: 'accounts.login', accountId: login.accountId, loginId, success, error })
+    login.revision += 1
+    const status: AccountLoginSnapshot['status'] = success ? 'completed' : cancelled ? 'cancelled' : 'failed'
+    if (this.latestLogins.get(login.accountId)?.loginId === loginId) {
+      this.latestLogins.set(login.accountId, {
+        accountId: login.accountId,
+        loginId,
+        provider: login.provider,
+        method: login.method,
+        revision: login.revision,
+        status,
+        // A terminal result is enough to reconcile the client. In particular, do not retain a
+        // device code after the attempt ends.
+        events: [],
+        prompt: null,
+        success,
+        error
+      })
+    }
+    this.bus.emit({ type: 'accounts.login', accountId: login.accountId, loginId, revision: login.revision, success, error })
     try {
       void this.refreshOne(this.find(login.accountId)).catch(() => undefined)
     } catch {
@@ -379,12 +438,55 @@ export class Accounts {
     const account = this.find(accountId)
     if (!provider) throw invalid('Choose which Pi provider to sign in to.')
     store.audit(this.dir, account.id, 'login.started', `${method ?? 'oauth'} · ${provider}`)
-    const runtime = await this.runtime(account)
     const loginId = randomUUID()
     const controller = new AbortController()
-    const login: PendingLogin = { accountId: account.id, prompts: new Map(), cancel: () => controller.abort() }
+    const login: PendingLogin = {
+      accountId: account.id,
+      provider,
+      method: method === 'api_key' ? 'api_key' : 'oauth',
+      prompts: new Map(),
+      cancel: () => controller.abort(),
+      revision: 0,
+      events: [],
+      prompt: null
+    }
     this.logins.set(loginId, login)
-    const event = (payload: Record<string, unknown>): void => this.bus.emit({ type: 'accounts.loginEvent', accountId: account.id, loginId, event: payload })
+    this.latestLogins.set(account.id, {
+      accountId: account.id,
+      loginId,
+      provider: login.provider,
+      method: login.method,
+      revision: 0,
+      status: 'running',
+      events: [],
+      prompt: null,
+      success: null,
+      error: null
+    })
+    const event = (payload: Record<string, unknown>): void => {
+      login.revision += 1
+      if (payload.type === 'prompt') login.prompt = payload
+      else if (payload.type === 'promptClosed' && login.prompt?.promptId === payload.promptId) login.prompt = null
+      else {
+        login.events.push(payload)
+        if (login.events.length > 50) login.events.shift()
+      }
+      if (this.latestLogins.get(account.id)?.loginId === loginId) {
+        this.latestLogins.set(account.id, {
+          accountId: account.id,
+          loginId,
+          provider: login.provider,
+          method: login.method,
+          revision: login.revision,
+          status: 'running',
+          events: login.events.map((step) => ({ ...step })),
+          prompt: login.prompt ? { ...login.prompt } : null,
+          success: null,
+          error: null
+        })
+      }
+      this.bus.emit({ type: 'accounts.loginEvent', accountId: account.id, loginId, revision: login.revision, event: payload })
+    }
     const interaction = {
       signal: controller.signal,
       notify: (notification: Record<string, unknown>) => event(notification),
@@ -400,24 +502,53 @@ export class Accounts {
           event({ type: 'prompt', promptId, prompt: { type: prompt.type, message: prompt.message, placeholder: prompt.placeholder ?? null, options: prompt.options ?? null } })
         })
     }
-    runtime
-      .login(provider, method === 'api_key' ? 'api_key' : 'oauth', interaction as never)
+    void this.runtime(account)
+      .then(async (runtime) => {
+        if (login.method !== 'oauth') return runtime.login(provider, login.method, interaction as never)
+        const deviceId = await this.installationDeviceId()
+        return runtime.login(provider, login.method, interaction as never, { getDeviceId: () => deviceId })
+      })
       .then(() => this.finishLogin(loginId, true, null))
-      .catch((error: unknown) => this.finishLogin(loginId, false, controller.signal.aborted ? 'Sign-in was cancelled.' : error instanceof Error ? error.message : String(error)))
+      .catch((error: unknown) => this.finishLogin(
+        loginId,
+        false,
+        controller.signal.aborted ? 'Sign-in was cancelled.' : error instanceof Error ? error.message : String(error),
+        controller.signal.aborted
+      ))
     return { loginId }
   }
 
+  /** Current in-memory sign-in progress for one account; codes and prompts are never written to disk. */
+  loginStatus(accountId: string): AccountLoginSnapshot | null {
+    this.find(accountId)
+    const snapshot = this.latestLogins.get(accountId)
+    return snapshot ? structuredClone(snapshot) : null
+  }
+
   loginRespond(loginId: string, promptId: string, value: string | null): void {
     const login = this.logins.get(loginId)
     const prompt = login?.prompts.get(promptId)
     if (!login || !prompt) throw new HarnessError('not_found', 'That sign-in step is no longer waiting.')
     login.prompts.delete(promptId)
+    // The renderer's recoverable snapshot must stop presenting a prompt as soon as it is answered.
+    const current = this.latestLogins.get(login.accountId)
+    if (current?.loginId === loginId && current.prompt?.promptId === promptId) {
+      login.prompt = null
+      current.revision += 1
+      login.revision = current.revision
+      current.prompt = null
+      this.latestLogins.set(login.accountId, current)
+      this.bus.emit({ type: 'accounts.loginEvent', accountId: login.accountId, loginId, revision: current.revision, event: { type: 'promptClosed', promptId } })
+    }
     if (value === null) prompt.reject(new Error('Cancelled.'))
     else prompt.resolve(value)
   }
 
   loginCancel(accountId: string, loginId?: string | null): void {
-    if (loginId) this.logins.get(loginId)?.cancel()
+    if (loginId) {
+      const login = this.logins.get(loginId)
+      if (login?.accountId === accountId) login.cancel()
+    } else for (const login of this.logins.values()) if (login.accountId === accountId) login.cancel()
     store.audit(this.dir, accountId, 'login.cancelled', '')
   }
 
@@ -428,6 +559,11 @@ export class Accounts {
    * account's stored credentials are written there (mode 0600) while the terminal runs, then
    * read back and removed.
    */
+  /** How many terminal sessions are running on this account right now. */
+  terminalCount(accountId: string): number {
+    return this.terminals.get(accountId) ?? 0
+  }
+
   async terminalBegin(account: Account): Promise<void> {
     const count = (this.terminals.get(account.id) ?? 0) + 1
     this.terminals.set(account.id, count)

package/src/cli.ts

@@ -12,6 +12,7 @@ import { resolve } from 'node:path'
 import { log } from './core/bus'
 import { createHarness, type HarnessOptions } from './harness'
 import { runPluginsCli, terminalAsk } from './plugins/cli'
+import { runHubCli } from './hub/cli'
 import { remoteDirectory, remotePolicy, remoteSecrets, remoteTools } from './server/remote'
 import { RpcPeer, stdioTransport } from './server/rpc'
 import { attach } from './server/serve'
@@ -19,16 +20,17 @@ import { runAppsCli, runWikiCli } from './terminal/cli'
 import { runStandaloneTerminal, standaloneArguments } from './terminal/standalone'
 
 const USAGE = `Usage: xingular-harness [--data <dir>] [--state <dir>]
-       xingular-harness <terminal | serve | wiki | mcp | plugins> [arguments]
+       xingular-harness <terminal | serve | wiki | mcp | plugins | hub> [arguments]
 
-  (no command)       Start the interactive Pi terminal
-  terminal           Start the interactive Pi terminal
+  (no command)       Start the interactive Harness terminal
+  terminal           Start the interactive Harness terminal
   serve --state <dir> [--data <dir>] [--name <product>] [--builtins <dir>]
         [--host-secrets] [--host-policy] [--host-tools] [--host-directory]
                      Serve the harness over newline-delimited JSON
   wiki <command>     Memory and Wiki commands for a terminal session
   mcp <command>      Connected-app commands for a terminal session
   plugins <command>  List, install, switch and trust plugins (plugins help)
+  hub <command>      Browse and install curated items (hub help)
 
 Standalone terminal options:
   --data <dir>       Data directory (default: ~/.xingular-harness/data)
@@ -91,6 +93,7 @@ function serveCommand(argv: string[]): Promise<number> {
 async function main(): Promise<number> {
   const argv = process.argv.slice(2)
   const [command, ...rest] = argv
+  if (command === 'terminal-frontend') return (await import('./terminal/tui/application')).runTerminalFrontend(rest)
   if (argv.includes('--help') || argv.includes('-h')) {
     process.stdout.write(USAGE)
     return 0
@@ -101,6 +104,7 @@ async function main(): Promise<number> {
   if (command === 'wiki') return runWikiCli(rest)
   if (command === 'mcp') return runAppsCli(rest)
   if (command === 'plugins') return runPluginsCli(rest, { ask: terminalAsk() })
+  if (command === 'hub') return runHubCli(rest)
   process.stdout.write(USAGE)
   return command ? 2 : 0
 }

package/src/harness.ts

@@ -5,6 +5,7 @@ import { mkdirSync } from 'node:fs'
 import { join } from 'node:path'
 
 import { Accounts } from './accounts/accounts'
+import { Hub, type HubOptions } from './hub/hub'
 import * as capabilities from './capabilities/api'
 import { ensureSharedDir, isolateProcess } from './accounts/env'
 import { fileSecretStore, type SecretStore } from './accounts/secrets'
@@ -41,6 +42,7 @@ import * as registry from './skills/registry'
 import { Terminals, type TerminalAssets } from './terminal/terminals'
 
 export interface HarnessOptions {
+  hub?: HubOptions
   /** Where knowledge and history live. May be set later with `open`. */
   dataRoot?: string | null
   /** Device-local state that never belongs in the data root: accounts, approvals, connections, sockets. */
@@ -54,11 +56,16 @@ export interface HarnessOptions {
   /** Replaces Pi, for tests. */
   sessionFactory?: SessionFactory
   maintainerFactory?: MaintainerFactory
+  /** Delegate maintenance execution to the embedding host through durable requests. */
+  externalMaintenance?: boolean
+  maintenanceExcludedTriggers?: string[]
+  /** Queue consolidation after every settled run (the default). False leaves memory to explicit proposals and scheduled merges. */
+  maintenanceRunTrigger?: boolean
   /** How long the maintenance queue stays empty before full memory blocks are condensed. */
   idleMs?: number
   /** Where the built commands a terminal session runs are, when they are not beside this package. */
   assets?: TerminalAssets
-  /** The `pi` executable a terminal session runs. Defaults to the one on the search path. */
+  /** Optional legacy executable override. The default is the Harness-owned terminal frontend. */
   piProgram?: () => string | null
   /** Folders of built-in skills, prompts, and rules, each laid out like `registry/`. */
   builtins?: string[]
@@ -102,6 +109,7 @@ class Env implements HarnessEnv {
 }
 
 export class Harness {
+  readonly hub: Hub
   readonly bus = new Bus()
   readonly env: Env
   readonly stateDir: string
@@ -129,6 +137,7 @@ export class Harness {
     // Before anything can start a session: no inherited credential, no `~/.pi`.
     isolateProcess(join(this.stateDir, 'accounts'))
     this.env = new Env(options.dataRoot || null, options.directory ?? EMPTY_DIRECTORY, options.productName ?? DEFAULT_PRODUCT_NAME, this.bus)
+    this.hub = new Hub(this, options.hub)
     this.policy = options.policy ?? {}
     registry.configureBuiltins(options.builtins ?? [])
     const secrets = options.secrets ?? fileSecretStore(join(this.stateDir, 'secrets.json'))
@@ -183,8 +192,8 @@ export class Harness {
       resolveCapabilities: (caller, tools, cwd) => capabilities.resolve(this, { agentId: caller.agentId ?? null, projectId: caller.projectId ?? null, cwd, tools }),
       factory: options.sessionFactory
     })
-    this.maintenance = new Maintenance({ env: this.env, bus: this.bus, accounts: this.accounts, factory: options.maintainerFactory, idleMs: options.idleMs })
-    this.terminals = new Terminals({ env: this.env, stateDir: this.stateDir, accounts: this.accounts, runs: this.runs, apps: this.apps, policy: this.policy, bus: this.bus, plugins: this.plugins, pluginControl: { list: (scope) => pluginApi.list(this, scope), attach: (params, on) => pluginApi.attach(this, params, on), trust: (scope) => pluginApi.trust(this, scope), untrust: (scope) => pluginApi.untrust(this, scope) }, assets: options.assets, program: options.piProgram })
+    this.maintenance = new Maintenance({ env: this.env, bus: this.bus, accounts: this.accounts, factory: options.maintainerFactory, idleMs: options.idleMs, external: options.externalMaintenance, excludedTriggers: options.maintenanceExcludedTriggers, runTrigger: options.maintenanceRunTrigger })
+    this.terminals = new Terminals({ env: this.env, stateDir: this.stateDir, accounts: this.accounts, runs: this.runs, apps: this.apps, policy: this.policy, bus: this.bus, plugins: this.plugins, pluginControl: { list: (scope) => pluginApi.list(this, scope), attach: (params, on) => pluginApi.attach(this, params, on), trust: (scope) => pluginApi.trust(this, scope), untrust: (scope) => pluginApi.untrust(this, scope) }, assets: options.assets, program: options.piProgram, hub: this.hub })
     this.ready = this.apps.start().catch((error) => log('connected apps', error instanceof Error ? error.message : String(error)))
     this.runs.listen((event, run) => {
       this.accounts.onRunEvent(event, run)
@@ -193,6 +202,7 @@ export class Harness {
       if ((event.type === 'completed' || event.type === 'failed') && run) {
         this.hooks.emit({ type: 'history.run.ended', runId: run.id, sessionId: run.sessionId, status: run.status, goal: run.goal ?? null, agentId: run.agentId ?? null, projectId: run.projectId ?? null, startedAt: run.startedAt, endedAt: run.endedAt ?? null, at: event.timestamp })
       }
+      if (event.type === 'completed' || event.type === 'failed' || (event.type === 'status.changed' && (event.payload as { status?: string }).status === 'interrupted')) this.maintenance.finishRun(event.runId, event.type !== 'completed')
       this.maintenance.onRunEvent(event)
     })
   }
@@ -215,8 +225,10 @@ export class Harness {
    * older Wiki is migrated.
    */
   open(dataRoot: string, agentIds: readonly string[] = []): Recovery {
+    if (this.hub.busy && this.env.dataRoot !== dataRoot) throw new HarnessError('hub_busy', 'Wait for the hub installation before changing the data location.')
     if (this.env.dataRoot && this.env.dataRoot !== dataRoot) closeIndex(this.env.dataRoot)
     this.env.dataRoot = dataRoot
+    this.hub.watch(dataRoot)
     const root = dataRoot
     this.hooks.watch(store.wikiDir(root))
     void this.hooks.reload()
@@ -281,6 +293,7 @@ export class Harness {
 
   /** Stops live runs and releases the index. */
   async close(): Promise<void> {
+    this.hub.close()
     this.maintenance.stop()
     await this.terminals.close()
     await this.runs.interruptAll()

package/src/hub/catalog.json

@@ -0,0 +1,123 @@
+{
+  "schemaVersion": 1,
+  "entries": [
+    {
+      "id": "xingular/evidence-first",
+      "title": "Evidence first",
+      "description": "Keep observations, inferences, and unknowns distinct.",
+      "publisher": "Xingular",
+      "license": "MIT",
+      "version": "1.0.0",
+      "category": "rule",
+      "channel": "official",
+      "tags": [
+        "rule"
+      ],
+      "requires": {
+        "harness": "0.1.6"
+      },
+      "sourceUrl": "https://github.com/tanntnny/xingular-hub/tree/main/entries/xingular/evidence-first/1.0.0",
+      "delivery": {
+        "kind": "registry",
+        "registryKind": "rules",
+        "url": "https://raw.githubusercontent.com/tanntnny/xingular-hub/main/entries/xingular/evidence-first/1.0.0/payload.json",
+        "sha256": "0f77661ea41e27bcb51aad982d15d493b893c5c1ba1eb6046a21315ddac07c5b",
+        "bundled": "{\n  \"items\": [\n    {\n      \"name\": \"hub-evidence-first\",\n      \"files\": [\n        {\n          \"path\": \"CONTENT.md\",\n          \"encoding\": \"utf8\",\n          \"content\": \"---\\nname: Evidence first\\ndescription: Distinguish observations, inferences, and unknowns.\\n---\\n\\nSupport factual claims with inspectable evidence. Label inferences and uncertainties. Correct a claim when better evidence changes it.\\n\"\n        }\n      ]\n    }\n  ]\n}\n"
+      }
+    },
+    {
+      "id": "xingular/github-connector",
+      "title": "GitHub connector",
+      "description": "A setup recipe for the GitHub MCP server; provide your own credentials.",
+      "publisher": "Xingular",
+      "license": "MIT",
+      "version": "1.0.0",
+      "category": "connector",
+      "channel": "official",
+      "tags": [
+        "connector"
+      ],
+      "requires": {
+        "harness": "0.1.6"
+      },
+      "sourceUrl": "https://github.com/tanntnny/xingular-hub/tree/main/entries/xingular/github-connector/1.0.0",
+      "delivery": {
+        "kind": "document",
+        "url": "https://raw.githubusercontent.com/tanntnny/xingular-hub/main/entries/xingular/github-connector/1.0.0/payload.json",
+        "sha256": "ec5bd9675e2977b9d880cf81732d84ac72b04af271048499415eaa6288896223",
+        "bundled": "{\n  \"id\": \"github-hub\",\n  \"name\": \"GitHub\",\n  \"description\": \"Repositories, issues, and pull requests\",\n  \"kind\": \"remote\",\n  \"docsUrl\": \"https://github.com/github/github-mcp-server\",\n  \"url\": \"https://api.githubcopilot.com/mcp/\",\n  \"auth\": \"headers\",\n  \"oauth\": null,\n  \"fields\": [\n    {\n      \"header\": \"Authorization\",\n      \"label\": \"Personal access token\",\n      \"prefix\": \"Bearer \",\n      \"help\": \"Provide a token for only the repositories and permissions you need.\"\n    }\n  ],\n  \"setup\": [\n    \"Create a personal access token in GitHub with the access you want to grant.\",\n    \"Review the connection before enabling it.\"\n  ],\n  \"notice\": null,\n  \"provenance\": null,\n  \"suggestedReadTools\": []\n}\n"
+      }
+    },
+    {
+      "id": "xingular/research-starter",
+      "title": "Research starter",
+      "description": "A starting agent for comparing sources and writing supported answers.",
+      "publisher": "Xingular",
+      "license": "MIT",
+      "version": "1.0.0",
+      "category": "agent-template",
+      "channel": "official",
+      "tags": [
+        "agent-template"
+      ],
+      "requires": {
+        "harness": "0.1.6"
+      },
+      "sourceUrl": "https://github.com/tanntnny/xingular-hub/tree/main/entries/xingular/research-starter/1.0.0",
+      "delivery": {
+        "kind": "document",
+        "url": "https://raw.githubusercontent.com/tanntnny/xingular-hub/main/entries/xingular/research-starter/1.0.0/payload.json",
+        "sha256": "a2f672583df6f4049cc153ba1e173192301220e5f8817f9ad5a4fe87af25f52b",
+        "bundled": "{\n  \"schemaVersion\": 1,\n  \"id\": \"research-starter\",\n  \"title\": \"Research starter\",\n  \"description\": \"Compare sources and explain the evidence behind an answer.\",\n  \"version\": \"1.0.0\",\n  \"author\": \"Xingular\",\n  \"license\": \"MIT\",\n  \"agent\": {\n    \"name\": \"Research starter\",\n    \"icon\": {\n      \"kind\": \"mascot\",\n      \"shape\": \"prism\",\n      \"color\": \"violet\",\n      \"material\": \"glass\"\n    },\n    \"description\": \"Investigates questions with sources.\",\n    \"instructions\": \"Help the user investigate a question. Start with reliable sources, explain what the evidence supports, cite the sources, and state unresolved questions. Ask the user when their goal is unclear.\",\n    \"model\": null,\n    \"effort\": \"high\",\n    \"tools\": [\n      \"read\",\n      \"grep\",\n      \"find\",\n      \"ls\",\n      \"web_search\",\n      \"web_fetch\"\n    ]\n  },\n  \"skills\": [],\n  \"connections\": []\n}\n"
+      }
+    },
+    {
+      "id": "xingular/source-review",
+      "title": "Review a source",
+      "description": "Check who wrote a source, what it supports, and what remains uncertain.",
+      "publisher": "Xingular",
+      "license": "MIT",
+      "version": "1.0.0",
+      "category": "skill",
+      "channel": "official",
+      "tags": [
+        "skill"
+      ],
+      "requires": {
+        "harness": "0.1.6"
+      },
+      "sourceUrl": "https://github.com/tanntnny/xingular-hub/tree/main/entries/xingular/source-review/1.0.0",
+      "delivery": {
+        "kind": "registry",
+        "registryKind": "skills",
+        "url": "https://raw.githubusercontent.com/tanntnny/xingular-hub/main/entries/xingular/source-review/1.0.0/payload.json",
+        "sha256": "bb0617889ee1ca39611a10952bec3086fa3986e9ce10a809c473c57acf47bc07",
+        "bundled": "{\n  \"items\": [\n    {\n      \"name\": \"hub-source-review\",\n      \"files\": [\n        {\n          \"path\": \"SKILL.md\",\n          \"encoding\": \"utf8\",\n          \"content\": \"---\\nname: hub-source-review\\ndescription: Review the evidence behind a source before using its claims.\\n---\\n\\n# Review a source\\n\\nRecord its author and date. Identify the original evidence. Write what the source supports and which uncertainties remain. Cite the source so the reader can inspect it.\\n\"\n        }\n      ]\n    }\n  ]\n}\n"
+      }
+    },
+    {
+      "id": "xingular/summarize-source",
+      "title": "Summarize a source",
+      "description": "Summarize a provided source and explain its limitations.",
+      "publisher": "Xingular",
+      "license": "MIT",
+      "version": "1.0.0",
+      "category": "prompt",
+      "channel": "official",
+      "tags": [
+        "prompt"
+      ],
+      "requires": {
+        "harness": "0.1.6"
+      },
+      "sourceUrl": "https://github.com/tanntnny/xingular-hub/tree/main/entries/xingular/summarize-source/1.0.0",
+      "delivery": {
+        "kind": "registry",
+        "registryKind": "prompts",
+        "url": "https://raw.githubusercontent.com/tanntnny/xingular-hub/main/entries/xingular/summarize-source/1.0.0/payload.json",
+        "sha256": "12a646d474fe3cd822970869c972d1d9400c7f6350388dc735dce5c31a22680a",
+        "bundled": "{\n  \"items\": [\n    {\n      \"name\": \"hub-summarize-source\",\n      \"files\": [\n        {\n          \"path\": \"CONTENT.md\",\n          \"encoding\": \"utf8\",\n          \"content\": \"---\\nname: summarize-source\\ndescription: Summarize the supplied source and its limits.\\n---\\n\\nSummarize the source below. Include its main claims, supporting evidence, limitations, and questions it leaves unanswered.\\n\\n$@\\n\"\n        }\n      ]\n    }\n  ]\n}\n"
+      }
+    }
+  ]
+}

package/src/hub/cli.ts

@@ -0,0 +1,59 @@
+import { homedir } from 'node:os'
+import { join, resolve } from 'node:path'
+import { Harness, type HarnessOptions } from '../harness'
+
+export const HUB_USAGE = `Usage: xingular-harness hub <list | show | install> [id@version] [options]
+
+  list [--refresh]             Browse the curated catalog and locally installed versions
+  show <id@version>            Show publisher, license, source, and delivery details
+  install <id@version>         Install the exact reviewed version, disabled and untrusted
+
+  --data <dir>                 Target data library (default: ~/.xingular-harness/data)
+  --state <dir>                Target device state (default: ~/.xingular-harness/state)
+  --refresh                    Refresh the public catalog; cached items remain usable offline
+`
+
+export async function runHubCli(argv: string[], dependencies: { home?: string; write?: (text: string) => void; createHarness?: (options: HarnessOptions) => Harness } = {}): Promise<number> {
+  const write = dependencies.write ?? ((text: string) => void process.stdout.write(text))
+  const args: string[] = []
+  const values: Record<string, string> = {}
+  let refresh = false
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index]
+    if (arg === '--refresh') refresh = true
+    else if (arg === '--data' || arg === '--state') {
+      const value = argv[++index]
+      if (!value || value.startsWith('--')) { write(`${arg} needs a directory.\n`); return 2 }
+      values[arg.slice(2)] = resolve(value)
+    } else if (arg.startsWith('--')) { write(`Unknown option ${arg}.\n`); return 2 }
+    else args.push(arg)
+  }
+  const [command, target] = args
+  if (!command || command === 'help') { write(HUB_USAGE); return 0 }
+  if (!['list', 'show', 'install'].includes(command)) { write(HUB_USAGE); return 2 }
+  const root = join(dependencies.home ?? homedir(), '.xingular-harness')
+  const options: HarnessOptions = { dataRoot: values.data ?? join(root, 'data'), stateDir: values.state ?? join(root, 'state') }
+  const harness = dependencies.createHarness?.(options) ?? new Harness(options)
+  try {
+    const overview = await harness.hub.list(refresh)
+    if (overview.error) write(`Catalog refresh failed: ${overview.error} Using ${overview.origin} content.\n`)
+    if (command === 'list') {
+      write(`Library: ${options.dataRoot}\n${overview.entries.map((entry) => `${entry.id}@${entry.version}  ${entry.category}  ${entry.title}${overview.installed.some((receipt) => receipt.entry.id === entry.id && receipt.entry.version === entry.version) ? ' · installed' : ''}`).join('\n')}\n`)
+      return 0
+    }
+    const split = target?.lastIndexOf('@') ?? -1
+    if (!target || split < 1) throw new Error('Name an exact item as publisher/name@version. Run hub list to see versions.')
+    const id = target.slice(0, split)
+    const version = target.slice(split + 1)
+    const entry = await harness.hub.get(id, version)
+    if (command === 'show') {
+      const { bundled: _bundled, ...delivery } = entry.delivery.kind === 'pi-package' ? { ...entry.delivery, bundled: undefined } : entry.delivery
+      write(`${entry.title} (${target})\n${entry.description}\nPublisher: ${entry.publisher}\nLicense: ${entry.license}\nSource: ${entry.sourceUrl}\nDelivery: ${JSON.stringify(delivery)}\n`)
+    } else {
+      const receipt = await harness.hub.install(id, version)
+      write(receipt.document ? `Saved ${target} in ${options.dataRoot}/hub/documents/${receipt.document}. Open this library in a compatible application to apply it.\n` : `Installed ${target}, switched off. Attach it separately${entry.delivery.kind === 'pi-package' ? ' and review/trust any code' : ''} before using it.\n`)
+    }
+    return 0
+  } catch (error) { write(`${error instanceof Error ? error.message : String(error)}\n`); return 1 }
+  finally { await harness.close() }
+}