@xingular/harness 0.0.0-stage → 0.1.0

package/src/skills/registry.ts

@@ -0,0 +1,394 @@
+// Canonical skills, prompts, and rules under `<data root>/registry/`. Each item is a Markdown
+// file (a skill may also be a folder with `SKILL.md`) with optional `name`/`description`
+// frontmatter. These files are the single source of truth. Items are enabled globally and per
+// project; enabled items are loaded automatically, and any item can be retrieved on demand.
+//
+// Built-in items ship with the harness or the application that embeds it, in folders laid out
+// like `registry/`. They are read-only and on everywhere until a person switches one off; an
+// item of the same id in the data root replaces the built-in one.
+import { lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync } from 'node:fs'
+import { basename, dirname, join } from 'node:path'
+
+import { invalid } from '../core/errors'
+import * as frontmatter from '../core/frontmatter'
+import { atomicWrite, now, readJsonOr, safeRelative } from '../core/fs'
+import { findProject } from '../core/projects'
+import { compareText, lines, takeChars } from '../core/text'
+import * as store from '../memory/store'
+import * as attachments from '../plugins/attachments'
+
+export const KINDS = ['skills', 'prompts', 'rules'] as const
+export type RegistryKind = (typeof KINDS)[number]
+
+export interface RegistryItem {
+  /** `<kind>/<name>`, stable across edits. */
+  id: string
+  kind: string
+  name: string
+  description: string
+  path: string
+  /** Set on an item that ships with the harness or the application, not on a person's own. */
+  builtin?: true
+}
+
+export interface SkillBundleInput {
+  name: string
+  files: { path: string; content: string; encoding: 'utf8' | 'base64' }[]
+}
+
+const MAX_SKILL_BUNDLES = 20
+const MAX_SKILL_FILES = 100
+const MAX_SKILL_IMPORT_BYTES = 10 * 1024 * 1024
+
+let builtinDirs: string[] = []
+
+/** The folders built-in items are read from, each laid out like `registry/`. Later folders win. */
+export function configureBuiltins(directories: readonly string[]): void {
+  builtinDirs = [...directories]
+}
+
+function itemFrom(kind: string, stem: string, file: string): RegistryItem | null {
+  let text: string
+  try {
+    text = readFileSync(file, 'utf8')
+  } catch {
+    return null
+  }
+  const parsed = frontmatter.parse(text)
+  const name = parsed?.front.name
+  const description = parsed?.front.description
+  // A frontmatter block whose name or description is not text is treated as no frontmatter.
+  const usable = parsed !== null && (name === undefined || name === null || typeof name === 'string') && (description === undefined || description === null || typeof description === 'string')
+  const body = usable ? parsed.body : text
+  return {
+    id: `${kind}/${stem}`,
+    kind,
+    name: usable && typeof name === 'string' ? name : stem.replace(/[-_]/g, ' '),
+    description: usable && typeof description === 'string' ? description : takeChars(lines(body).find((line) => line.trim() && !line.startsWith('#')) ?? '', 160),
+    path: file
+  }
+}
+
+const stemOf = (name: string): string => (name.lastIndexOf('.') > 0 ? name.slice(0, name.lastIndexOf('.')) : name)
+
+/** The name and description of a skill or prompt file anywhere on disk, read the way a registry item is. */
+export function describeFile(file: string): { name: string; description: string } | null {
+  const stem = basename(file) === 'SKILL.md' ? basename(dirname(file)) : stemOf(basename(file))
+  const item = itemFrom('', stem, file)
+  return item && { name: item.name, description: item.description }
+}
+
+function itemsIn(directory: string): RegistryItem[] {
+  const items: RegistryItem[] = []
+  for (const kind of KINDS) {
+    let names: string[]
+    try {
+      names = readdirSync(join(directory, kind))
+    } catch {
+      continue
+    }
+    for (const name of names) {
+      const path = join(directory, kind, name)
+      const stem = stemOf(name)
+      if (stem.startsWith('.')) continue
+      const file = store.isDir(path) ? join(path, 'SKILL.md') : name.endsWith('.md') ? path : null
+      const item = file && itemFrom(kind, stem, file)
+      if (item) items.push(item)
+    }
+  }
+  return items
+}
+
+export function list(root: string): RegistryItem[] {
+  const items = new Map<string, RegistryItem>()
+  for (const directory of builtinDirs) for (const item of itemsIn(directory)) items.set(item.id, { ...item, builtin: true })
+  for (const item of itemsIn(join(root, 'registry'))) items.set(item.id, item)
+  return [...items.values()].sort((left, right) => compareText(left.id, right.id))
+}
+
+function enablementPath(root: string): string {
+  return join(root, 'config/registry-enabled.json')
+}
+
+/** Key for items enabled everywhere. Older data roots used `personal`, which is read the same way. */
+export const GLOBAL_KEY = 'global'
+
+/**
+ * The registry's earlier enablement file as it is on disk: ids keyed by project id, or `global`
+ * for everyone. The choices now live with every other plugin's (`plugins/attachments.ts`), which
+ * reads this file until the first change is saved.
+ */
+export function enablement(root: string): Record<string, unknown> {
+  const map = readJsonOr<unknown>(enablementPath(root), {})
+  return map && typeof map === 'object' && !Array.isArray(map) ? (map as Record<string, unknown>) : {}
+}
+
+export function enablementIds(map: Record<string, unknown>, key: string): string[] {
+  const ids = map[key]
+  return Array.isArray(ids) ? ids.filter((id): id is string => typeof id === 'string') : []
+}
+
+/** Built-in items a person switched off. Everything else built in is on everywhere. */
+export const BUILTIN_OFF_KEY = 'builtinOff'
+
+/** Whether an id names a registry item, as `<kind>/<name>`. */
+export const isItemId = (id: string): boolean => KINDS.some((kind) => id.startsWith(`${kind}/`))
+
+/**
+ * Items active for a caller. A built-in is on until it is switched off; a person's own is off
+ * until it is switched on, everywhere, for the caller's project, or for the calling agent.
+ */
+export function enabledFor(root: string, projectId: string | null, agentId: string | null = null): RegistryItem[] {
+  const choices = attachments.load(root)
+  return list(root).filter((item) => attachments.attached(choices, [item.id], { agentId, projectId }, !!item.builtin))
+}
+
+/** An item's Markdown body without frontmatter. */
+export function itemBody(item: RegistryItem): string {
+  try {
+    const text = readFileSync(item.path, 'utf8')
+    return frontmatter.split(text)?.body ?? text
+  } catch {
+    return ''
+  }
+}
+
+export interface RegistryResources {
+  ids: string[]
+  skillPaths: string[]
+  promptPaths: string[]
+}
+
+/** What a Pi session needs to load enabled items natively. Rule text reaches the model through the compiled prompt. */
+export function resources(root: string, projectId: string | null, agentId: string | null = null): RegistryResources {
+  const items = enabledFor(root, projectId, agentId)
+  return {
+    ids: items.map((item) => item.id),
+    skillPaths: items.filter((item) => item.kind === 'skills').map((item) => item.path),
+    promptPaths: items.filter((item) => item.kind === 'prompts').map((item) => item.path)
+  }
+}
+
+// Prefix of the entries an earlier version of the harness linked into a Pi agent folder's `skills/`.
+const LINKED_SKILL_PREFIX = 'agentx-'
+
+function isLinkedSkill(path: string): boolean {
+  let meta
+  try {
+    meta = lstatSync(path)
+  } catch {
+    return false
+  }
+  if (meta.isSymbolicLink()) return true
+  if (!meta.isDirectory()) return false
+  // A single-file skill was linked as `agentx-<name>/SKILL.md` inside a folder the harness made.
+  try {
+    const entries = readdirSync(path)
+    return entries.length === 1 && entries[0] === 'SKILL.md' && lstatSync(join(path, 'SKILL.md')).isSymbolicLink()
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Removes the `agentx-<name>` links an earlier version kept in a terminal session's `skills/`
+ * folder, leaving the user's own skills alone. Enabled skills now reach a session as paths.
+ */
+export function removeLinkedSkills(skillsDir: string): void {
+  let names: string[]
+  try {
+    names = readdirSync(skillsDir)
+  } catch {
+    return
+  }
+  for (const name of names) {
+    const path = join(skillsDir, name)
+    if (!name.startsWith(LINKED_SKILL_PREFIX) || !isLinkedSkill(path)) continue
+    if (lstatSync(path).isSymbolicLink()) unlinkSync(path)
+    else rmSync(path, { recursive: true, force: true })
+  }
+}
+
+export interface RegistryState {
+  items: RegistryItem[]
+  enabled: Record<string, unknown>
+}
+
+/**
+ * Enablement as a person sees it, in the earlier file's shape: ids keyed by project id, `global`
+ * for everyone (built-ins that are on count as enabled everywhere), and the built-ins switched off.
+ */
+function shown(items: readonly RegistryItem[], choices: attachments.Attachments): Record<string, unknown> {
+  const builtin = items.filter((item) => item.builtin).map((item) => item.id)
+  const off = choices.global.off.filter((id) => builtin.includes(id))
+  const global = choices.global.on.filter((id) => isItemId(id) && !builtin.includes(id))
+  const map: Record<string, unknown> = { [GLOBAL_KEY]: [...global, ...builtin.filter((id) => !off.includes(id))] }
+  for (const [projectId, entries] of Object.entries(choices.projects)) map[projectId] = entries.on.filter(isItemId)
+  if (off.length) map[BUILTIN_OFF_KEY] = off
+  return map
+}
+
+export function state(root: string): RegistryState {
+  const items = list(root)
+  return { items, enabled: shown(items, attachments.load(root)) }
+}
+
+/** Sets enabled items for a project, or globally when `projectId` is `null`. */
+export function setEnabled(root: string, projectId: string | null, ids: string[]): RegistryState {
+  if (projectId) findProject(root, projectId)
+  const items = list(root)
+  const unknown = ids.find((id) => !items.some((item) => item.id === id))
+  if (unknown !== undefined) throw invalid(`Unknown registry item ${unknown}.`)
+  const builtin = items.filter((item) => item.builtin).map((item) => item.id)
+  const choices = attachments.load(root)
+  const entries = projectId ? (choices.projects[projectId] ??= { on: [], off: [] }) : choices.global
+  // Only the registry's own ids are replaced; other plugins' choices in the same scope stay.
+  entries.on = [...entries.on.filter((id) => !isItemId(id)), ...ids.filter((id) => !builtin.includes(id))]
+  entries.off = entries.off.filter((id) => !isItemId(id) || (!ids.includes(id) && !(!projectId && builtin.includes(id))))
+  // A built-in left out of the global list was switched off.
+  if (!projectId) entries.off.push(...builtin.filter((id) => !ids.includes(id)))
+  attachments.save(root, choices)
+  return { items, enabled: shown(items, choices) }
+}
+
+function kindDir(root: string, kind: string): string {
+  if (!(KINDS as readonly string[]).includes(kind)) throw invalid('Unknown registry kind.')
+  return join(root, 'registry', kind)
+}
+
+/** Creates a starter item from a name: a Markdown file, or a skill folder with `SKILL.md`. */
+export function create(root: string, kind: string, rawName: string): RegistryState {
+  const directory = kindDir(root, kind)
+  const name = rawName.trim()
+  const slug = Array.from(name.toLowerCase(), (character) => (/^[a-z0-9]$/.test(character) ? character : '-')).join('').split('-').filter(Boolean).join('-')
+  if (!slug || slug.length > 64) throw invalid('Use a short name with letters or numbers.')
+  const description = 'Describe when to use this.'
+  const target = kind === 'skills' ? join(directory, slug) : join(directory, `${slug}.md`)
+  let exists = true
+  try {
+    lstatSync(target)
+  } catch {
+    exists = false
+  }
+  if (exists) throw invalid('An item with that name already exists.')
+  if (kind === 'skills') atomicWrite(join(target, 'SKILL.md'), `---\nname: ${slug}\ndescription: ${description}\n---\n\n# ${name}\n\nSteps the agent should follow.\n`)
+  else atomicWrite(target, `---\nname: ${name}\ndescription: ${description}\n---\n\n`)
+  return state(root)
+}
+
+/** Imports complete user-owned skill folders without replacing existing or built-in items. */
+export function importSkills(root: string, bundles: SkillBundleInput[]): RegistryState {
+  if (!Array.isArray(bundles) || bundles.length === 0 || bundles.length > MAX_SKILL_BUNDLES) {
+    throw invalid(`Import between 1 and ${MAX_SKILL_BUNDLES} skills at a time.`)
+  }
+
+  const directory = kindDir(root, 'skills')
+  mkdirSync(directory, { recursive: true })
+  const existing = new Set(list(root).map((item) => item.id))
+  const seen = new Set<string>()
+  let totalBytes = 0
+  const prepared = bundles.map((bundle) => {
+    if (!bundle || typeof bundle.name !== 'string' || !Array.isArray(bundle.files) || bundle.files.length === 0 || bundle.files.length > MAX_SKILL_FILES) {
+      throw invalid('Each skill needs a name and a bounded list of files.')
+    }
+    const name = bundle.name.trim()
+    if (name.length > 64) throw invalid('Use a skill name with at most 64 letters or numbers.')
+    const slug = Array.from(name.toLowerCase(), (character) => (/^[a-z0-9]$/.test(character) ? character : '-')).join('').split('-').filter(Boolean).join('-')
+    if (!slug || slug.length > 64) throw invalid('Use a skill name with at most 64 letters or numbers.')
+    const id = `skills/${slug}`
+    if (existing.has(id) || seen.has(id)) throw invalid(`The skill “${name}” already exists.`)
+    try {
+      lstatSync(join(directory, slug))
+      throw invalid(`The skill “${name}” already exists.`)
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+    }
+    seen.add(id)
+
+    const files = new Map<string, Uint8Array>()
+    for (const file of bundle.files) {
+      if (!file || typeof file.path !== 'string' || file.path.length > 240 || typeof file.content !== 'string' || !['utf8', 'base64'].includes(file.encoding)) {
+        throw invalid(`The skill “${name}” contains an invalid file.`)
+      }
+      let relative: string
+      try {
+        relative = safeRelative(file.path)
+      } catch {
+        throw invalid(`The skill “${name}” contains a path outside its folder.`)
+      }
+      if (relative.includes('\0') || relative.split('/').some((part) => part.startsWith('.') || part.includes(':'))) {
+        throw invalid(`The skill “${name}” contains an unsupported file path.`)
+      }
+      const portablePath = relative.normalize('NFC').toLowerCase()
+      if ([...files.keys()].some((path) => path.normalize('NFC').toLowerCase() === portablePath)) throw invalid(`The skill “${name}” contains a duplicate file path.`)
+      let byteLength: number
+      if (file.encoding === 'base64') {
+        if (!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(file.content)) {
+          throw invalid(`The file “${relative}” is not valid base64.`)
+        }
+        if (file.content.length > Math.ceil(MAX_SKILL_IMPORT_BYTES / 3) * 4) throw invalid('The skill import is larger than 10 MiB.')
+        byteLength = Math.floor(file.content.length * 3 / 4) - (file.content.endsWith('==') ? 2 : file.content.endsWith('=') ? 1 : 0)
+      } else {
+        byteLength = Buffer.byteLength(file.content, 'utf8')
+      }
+      totalBytes += byteLength
+      if (totalBytes > MAX_SKILL_IMPORT_BYTES) throw invalid('The skill import is larger than 10 MiB.')
+      const bytes = file.encoding === 'base64' ? Buffer.from(file.content, 'base64') : Buffer.from(file.content, 'utf8')
+      if (file.encoding === 'base64' && bytes.toString('base64') !== file.content) throw invalid(`The file “${relative}” is not valid base64.`)
+      files.set(relative, bytes)
+    }
+    if (!files.has('SKILL.md')) throw invalid(`The skill “${name}” must include SKILL.md at its root.`)
+    return { name, slug, files }
+  })
+
+  const staging = mkdtempSync(join(directory, '.agent-template-import-'))
+  const installed: string[] = []
+  try {
+    for (const bundle of prepared) {
+      const target = join(staging, bundle.slug)
+      for (const [relative, bytes] of bundle.files) {
+        const path = join(target, ...relative.split('/'))
+        mkdirSync(dirname(path), { recursive: true })
+        writeFileSync(path, bytes, { flag: 'wx' })
+      }
+    }
+    for (const bundle of prepared) {
+      const target = join(directory, bundle.slug)
+      renameSync(join(staging, bundle.slug), target)
+      installed.push(target)
+    }
+  } catch (error) {
+    for (const target of installed) rmSync(target, { recursive: true, force: true })
+    throw error
+  } finally {
+    rmSync(staging, { recursive: true, force: true })
+  }
+  return state(root)
+}
+
+/**
+ * Writes a skill, prompt, or rule (an accepted proposal), keeping an existing item's location.
+ * The previous content and the new content are recorded as Wiki revisions of the item.
+ */
+export function writeItem(root: string, kind: string, name: string, description: string, body: string, reason: string): string {
+  const plural = kind === 'skill' ? 'skills' : kind === 'prompt' ? 'prompts' : kind === 'rule' ? 'rules' : null
+  if (!plural) throw invalid('Only skills, prompts, and rules can be written.')
+  const stem = store.slug(name)
+  const id = `${plural}/${stem}`
+  const existing = list(root).find((item) => item.id === id)
+  // A built-in is never edited in place: the accepted text becomes the person's own item.
+  const path = existing && !existing.builtin ? existing.path : plural === 'skills' ? join(kindDir(root, plural), stem, 'SKILL.md') : join(kindDir(root, plural), `${stem}.md`)
+  const text = frontmatter.serialize({ name: plural === 'skills' ? stem : name.trim(), ...(description.trim() ? { description: description.trim() } : {}) }, body)
+  const wiki = store.wikiDir(root)
+  if (existing) {
+    try {
+      store.snapshot(wiki, id, readFileSync(existing.path, 'utf8'), 'user', 'Before accepted proposal')
+    } catch {
+      // Nothing readable to keep.
+    }
+  }
+  atomicWrite(path, text)
+  store.snapshot(wiki, id, text, 'user', reason)
+  store.log(wiki, `- ${now()} · user · ${existing ? 'updated' : 'created'} \`${id}\` · ${reason}`)
+  return id
+}

package/src/terminal/cli.ts

@@ -0,0 +1,149 @@
+// `agentx-wiki` and `agentx-mcp`: the harness's memory, Wiki, and connected apps as commands,
+// for a `pi` terminal session's shell. Each command maps onto one call to the session socket.
+import type { WikiCall } from '../tools/definitions'
+import { connectionFromEnv, socketCall } from './client'
+
+export const WIKI_COMMAND = 'agentx-wiki'
+export const APPS_COMMAND = 'agentx-mcp'
+
+export const USAGE = `Usage: ${WIKI_COMMAND} <command> [arguments]
+
+  entrypoint                         Your context pack: memory blocks, rules, skills, project map
+  search <query> [--kind K] [--namespace NS]
+                                     Search every namespace (K: page, fact, skill, rule, prompt)
+  read <id or path>                  Read one page, fact, skill, rule, or prompt
+  list [namespace] [--kind K]        List namespaces and pages, or all entries of a kind
+  skill [name]                       Load a skill, or list skills
+  facts [query] [--namespace NS]     Recall facts (also: memory)
+  history <query> [--scope all] [--since YYYY-MM-DD]
+                                     Search earlier conversations and runs (also: recall)
+  history-read <run id>              Read one earlier run (also: recall-read)
+  block append <label> <text>        Add to a memory block (user, project, or a shared block)
+  block replace <label> --old <text> --new <text>
+                                     Replace one exact passage in a memory block
+  block rethink <label> <text>       Rewrite a whole memory block
+  propose <json | ->                 Record knowledge, e.g. {"kind":"fact","title":"…","body":"…",
+                                     "type":"preference","sourceRefs":[{"kind":"run","ref":"current"}]}
+`
+
+export const APPS_USAGE = `Usage: ${APPS_COMMAND} <command>
+
+  list                               The app and connected-app tools this session may use
+  call <tool-name> '<JSON arguments>'
+                                     Use one of them
+`
+
+export type CliCommand = { kind: 'call'; call: WikiCall; params: Record<string, unknown> } | { kind: 'help' } | { kind: 'stdin-propose' }
+
+function options(args: string[]): { positional: string[]; flags: Record<string, string> } {
+  const positional: string[] = []
+  const flags: Record<string, string> = {}
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index]
+    if (arg.startsWith('--') && index + 1 < args.length) {
+      flags[arg.slice(2)] = args[index + 1]
+      index += 1
+    } else {
+      positional.push(arg)
+    }
+  }
+  return { positional, flags }
+}
+
+export function parseCli(argv: string[]): CliCommand {
+  const [command, ...rest] = argv
+  const { positional, flags } = options(rest)
+  const joined = positional.join(' ').trim()
+  switch (command) {
+    case 'entrypoint':
+      return { kind: 'call', call: 'wiki.entrypoint', params: {} }
+    case 'search':
+      if (!joined) return { kind: 'help' }
+      return { kind: 'call', call: 'wiki.search', params: { query: joined, ...(flags.kind ? { kinds: [flags.kind] } : {}), ...(flags.namespace ? { namespace: flags.namespace } : {}) } }
+    case 'read':
+      if (!joined) return { kind: 'help' }
+      return { kind: 'call', call: 'wiki.read', params: { id: joined } }
+    case 'list':
+      return { kind: 'call', call: 'wiki.list', params: { ...(joined ? { namespace: joined } : {}), ...(flags.kind ? { kind: flags.kind } : {}) } }
+    case 'skill':
+      return { kind: 'call', call: 'wiki.skill', params: joined ? { name: joined } : {} }
+    case 'facts':
+    case 'memory':
+      return { kind: 'call', call: 'wiki.memory', params: { ...(joined ? { query: joined } : {}), ...(flags.namespace ? { namespace: flags.namespace } : {}) } }
+    case 'history':
+    case 'recall':
+      if (!joined) return { kind: 'help' }
+      return { kind: 'call', call: 'recall.search', params: { query: joined, ...(flags.scope ? { scope: flags.scope } : {}), ...(flags.since ? { since: flags.since } : {}) } }
+    case 'history-read':
+    case 'recall-read':
+      if (!joined) return { kind: 'help' }
+      return { kind: 'call', call: 'recall.read', params: { run: joined } }
+    case 'block': {
+      const [action, label, ...words] = positional
+      const body = words.join(' ').trim()
+      if (action === 'append' && label && body) return { kind: 'call', call: 'memory.append', params: { block: label, text: body } }
+      if (action === 'rethink' && label && body) return { kind: 'call', call: 'memory.rethink', params: { block: label, body } }
+      if (action === 'replace' && label && flags.old !== undefined && flags.new !== undefined) return { kind: 'call', call: 'memory.replace', params: { block: label, old: flags.old, new: flags.new } }
+      return { kind: 'help' }
+    }
+    case 'propose': {
+      if (joined === '-') return { kind: 'stdin-propose' }
+      try {
+        const params = JSON.parse(joined) as unknown
+        if (params && typeof params === 'object' && !Array.isArray(params)) return { kind: 'call', call: 'wiki.propose', params: params as Record<string, unknown> }
+      } catch {
+        // Falls through to help.
+      }
+      return { kind: 'help' }
+    }
+    default:
+      return { kind: 'help' }
+  }
+}
+
+async function readStdin(): Promise<string> {
+  let text = ''
+  for await (const chunk of process.stdin) text += chunk.toString()
+  return text
+}
+
+const errorText = (error: unknown): string => (error instanceof Error ? error.message : String(error))
+
+/** Runs `agentx-wiki <argv>`; returns the exit code. */
+export async function runWikiCli(argv: string[]): Promise<number> {
+  const command = parseCli(argv)
+  if (command.kind === 'help') {
+    process.stdout.write(USAGE)
+    return argv.length ? 2 : 0
+  }
+  try {
+    const connection = connectionFromEnv()
+    const result =
+      command.kind === 'stdin-propose'
+        ? await socketCall<string>(connection, 'wiki.propose', JSON.parse(await readStdin()) as Record<string, unknown>)
+        : await socketCall<string>(connection, command.call, command.params)
+    process.stdout.write(`${typeof result === 'string' ? result : JSON.stringify(result)}\n`)
+    return 0
+  } catch (error) {
+    process.stderr.write(`${errorText(error)}\n`)
+    return 1
+  }
+}
+
+/** Runs `agentx-mcp <argv>`; returns the exit code. */
+export async function runAppsCli(argv: string[]): Promise<number> {
+  const [command, name, args] = argv
+  if (command !== 'list' && !(command === 'call' && name)) {
+    process.stdout.write(APPS_USAGE)
+    return argv.length ? 2 : 0
+  }
+  try {
+    const connection = connectionFromEnv()
+    const result = command === 'list' ? await socketCall(connection, 'mcp.list', {}, 90_000) : await socketCall(connection, 'mcp.call', { name, args: JSON.parse(args ?? '{}') as unknown }, 1_230_000)
+    process.stdout.write(`${JSON.stringify(result)}\n`)
+    return 0
+  } catch (error) {
+    process.stderr.write(`${errorText(error)}\n`)
+    return 1
+  }
+}

package/src/terminal/client.ts

@@ -0,0 +1,74 @@
+// How a process outside the harness (the `pi` command's extension, the `agentx-wiki` and
+// `agentx-mcp` commands) reaches it: one newline-delimited JSON request and reply per
+// connection to the session socket, authorized by the token the harness put in its environment.
+import { createConnection } from 'node:net'
+
+export const SOCKET_ENV = 'XINGULAR_HARNESS_SOCKET'
+export const TOKEN_ENV = 'XINGULAR_HARNESS_TOKEN'
+
+export class SocketError extends Error {
+  constructor(
+    readonly code: string,
+    message: string
+  ) {
+    super(message)
+  }
+}
+
+export interface SocketConnection {
+  socket: string
+  token: string
+}
+
+export function connectionFromEnv(env: NodeJS.ProcessEnv = process.env): SocketConnection {
+  const socket = env[SOCKET_ENV]
+  const token = env[TOKEN_ENV]
+  if (!socket || !token) throw new SocketError('not_configured', `This command only works inside a terminal session the harness started (${SOCKET_ENV} and ${TOKEN_ENV} are not set).`)
+  return { socket, token }
+}
+
+function request<T>(connection: SocketConnection, body: Record<string, unknown>, what: string, timeoutMs: number): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const stream = createConnection(connection.socket)
+    let buffer = ''
+    let settled = false
+    const finish = (action: () => void) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      stream.end()
+      action()
+    }
+    const timer = setTimeout(() => {
+      stream.destroy()
+      finish(() => reject(new SocketError('timeout', `The harness did not answer ${what}.`)))
+    }, timeoutMs)
+    stream.on('connect', () => stream.write(`${JSON.stringify({ token: connection.token, ...body })}\n`))
+    stream.on('data', (chunk) => {
+      buffer += chunk.toString('utf8')
+      const newline = buffer.indexOf('\n')
+      if (newline < 0) return
+      try {
+        const reply = JSON.parse(buffer.slice(0, newline)) as { result?: T; error?: { code?: string; message?: string } | string }
+        if (reply.error) {
+          const error = typeof reply.error === 'string' ? { message: reply.error } : reply.error
+          finish(() => reject(new SocketError(error.code ?? 'error', error.message ?? `${what} failed.`)))
+        } else finish(() => resolve(reply.result as T))
+      } catch {
+        finish(() => reject(new SocketError('invalid_reply', 'The harness sent an unreadable reply.')))
+      }
+    })
+    stream.on('error', (error) => finish(() => reject(new SocketError('unavailable', `The harness is not reachable: ${error.message}.`))))
+    stream.on('close', () => finish(() => reject(new SocketError('unavailable', 'The harness closed the connection.'))))
+  })
+}
+
+/** A memory, Wiki, recall, or connected-app call made on behalf of the session that owns the token. */
+export function socketCall<T = unknown>(connection: SocketConnection, call: string, params: Record<string, unknown> = {}, timeoutMs = 120_000, control?: string): Promise<T> {
+  return request<T>(connection, { call, params, ...(control ? { control } : {}) }, call, timeoutMs)
+}
+
+/** Telemetry and decisions from the native `pi` process. Approvals may wait on a person, so the default wait is long. */
+export function terminalCall<T = Record<string, unknown>>(event: string, data: Record<string, unknown> = {}, timeoutMs = 600_000): Promise<T> {
+  return request<T>(connectionFromEnv(), { event, data }, event, timeoutMs)
+}