@xingular/harness 0.0.0-stage → 0.1.0

package/src/capabilities/runSnapshot.ts

@@ -0,0 +1,59 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { HarnessError, invalid } from '../core/errors'
+import { readJson, safeId, writeJson } from '../core/fs'
+import type { CapabilitySet } from './types'
+
+export interface RunCapabilitySnapshot {
+  version: 1
+  caller: { agentId: string | null; projectId: string | null }
+  tools: string[]
+  connectors: string[]
+  contributions: string[]
+}
+
+const path = (root: string, runId: string): string => join(root, 'runs', safeId(runId), 'capabilities.json')
+
+function strings(value: unknown): string[] {
+  return Array.isArray(value) ? [...new Set(value.filter((item): item is string => typeof item === 'string' && item.length > 0))] : []
+}
+
+export function capabilitySet(value: unknown): CapabilitySet {
+  if (!value || typeof value !== 'object' || (value as { version?: unknown }).version !== 1) throw invalid('A capability set must use version 1.')
+  const record = value as Record<string, unknown>
+  return { version: 1, tools: strings(record.tools), connectors: strings(record.connectors), contributions: strings(record.contributions) }
+}
+
+/** Writes a run's capability set once. A resumed or duplicate launch cannot replace it. */
+export function freezeRun(root: string, runId: string, caller: { agentId?: string | null; projectId?: string | null }, set: CapabilitySet): RunCapabilitySnapshot {
+  const target = path(root, runId)
+  const snapshot: RunCapabilitySnapshot = {
+    version: 1,
+    caller: { agentId: caller.agentId ?? null, projectId: caller.projectId ?? null },
+    tools: strings(set.tools),
+    connectors: strings(set.connectors),
+    contributions: strings(set.contributions)
+  }
+  const existing = existsSync(target) ? readJson<RunCapabilitySnapshot>(target) : null
+  if (existing) {
+    if (JSON.stringify(existing) !== JSON.stringify(snapshot)) throw new HarnessError('capabilities_frozen', 'This run already has a different frozen capability set.')
+    return existing
+  }
+  writeJson(target, snapshot)
+  return snapshot
+}
+
+export function loadRun(root: string, runId: string): RunCapabilitySnapshot | null {
+  const stored = readJson<unknown>(path(root, runId))
+  if (!stored || typeof stored !== 'object' || (stored as { version?: unknown }).version !== 1) return null
+  const record = stored as Record<string, unknown>
+  const caller = record.caller && typeof record.caller === 'object' ? record.caller as Record<string, unknown> : {}
+  return {
+    version: 1,
+    caller: { agentId: typeof caller.agentId === 'string' ? caller.agentId : null, projectId: typeof caller.projectId === 'string' ? caller.projectId : null },
+    tools: strings(record.tools),
+    connectors: strings(record.connectors),
+    contributions: strings(record.contributions)
+  }
+}

package/src/capabilities/types.ts

@@ -0,0 +1,34 @@
+import type { AttachScope, Attachment } from '../plugins/attachments'
+import type { ContributionKind, ContributionState, PluginSource } from '../plugins/types'
+
+export type CapabilityKind = ContributionKind | 'plugin'
+
+/** One item the caller can switch on or off, or that a plugin makes available. */
+export interface Capability {
+  id: string
+  pluginId: string
+  kind: CapabilityKind
+  name: string
+  description: string
+  source: PluginSource
+  state: ContributionState
+  attachment: Attachment | null
+}
+
+export interface CapabilityCatalogue {
+  plugins: import('../plugins/types').Plugin[]
+  capabilities: Capability[]
+}
+
+/** The callable capabilities a run starts with. Permission to run still goes through the gate. */
+export interface CapabilitySet {
+  version: 1
+  tools: string[]
+  connectors: string[]
+  contributions: string[]
+}
+
+export interface CapabilityScope extends AttachScope {
+  cwd?: string | null
+  accountId?: string | null
+}

package/src/cli.ts

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+// The `xingular-harness` command.
+//
+//   xingular-harness serve --state <dir> [--data <dir>] [--name <product>] [--builtins <dir>]…
+//                          [--host-secrets] [--host-policy] [--host-tools] [--host-directory]
+//       Serves the harness to a host process over stdin/stdout (newline-delimited JSON).
+//   xingular-harness wiki <command>     Memory and Wiki, from inside a terminal session.
+//   xingular-harness mcp <command>      Connected apps, from inside a terminal session.
+//   xingular-harness plugins <command>  List, install, switch and trust plugins.
+import { log } from './core/bus'
+import { createHarness, type HarnessOptions } from './harness'
+import { runPluginsCli, terminalAsk } from './plugins/cli'
+import { remoteDirectory, remotePolicy, remoteSecrets, remoteTools } from './server/remote'
+import { RpcPeer, stdioTransport } from './server/rpc'
+import { attach } from './server/serve'
+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]
+
+  (no command)       Start the interactive Pi terminal
+  terminal           Start the interactive Pi 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)
+
+Standalone terminal options:
+  --data <dir>       Data directory (default: ~/.xingular-harness/data)
+  --state <dir>      State directory (default: ~/.xingular-harness/state)
+`
+
+function flags(argv: string[]): { values: Record<string, string[]>; switches: Set<string> } {
+  const values: Record<string, string[]> = {}
+  const switches = new Set<string>()
+  for (let index = 0; index < argv.length; index += 1) {
+    const name = argv[index]
+    if (!name.startsWith('--')) continue
+    const next = argv[index + 1]
+    if (next !== undefined && !next.startsWith('--')) {
+      ;(values[name.slice(2)] ??= []).push(next)
+      index += 1
+    } else switches.add(name.slice(2))
+  }
+  return { values, switches }
+}
+
+function serveCommand(argv: string[]): Promise<number> {
+  const { values, switches } = flags(argv)
+  const stateDir = values.state?.[0]
+  if (!stateDir) {
+    process.stderr.write('serve needs --state <dir>.\n')
+    return Promise.resolve(2)
+  }
+  const peer = new RpcPeer(stdioTransport())
+  const options: HarnessOptions = {
+    stateDir,
+    dataRoot: values.data?.[0] ?? null,
+    productName: values.name?.[0],
+    builtins: values.builtins,
+    ...(switches.has('host-secrets') ? { secrets: remoteSecrets(peer) } : {}),
+    ...(switches.has('host-policy') ? { policy: remotePolicy(peer) } : {}),
+    ...(switches.has('host-directory') ? { directory: remoteDirectory(peer) } : {})
+  }
+  const harness = createHarness(options)
+  if (switches.has('host-tools')) harness.sessions.provide(remoteTools(peer))
+  attach(harness, peer)
+  return new Promise<number>((resolve) => {
+    let closing = false
+    const shutdown = (): void => {
+      if (closing) return
+      closing = true
+      void Promise.race([harness.close(), new Promise((done) => setTimeout(done, 5000))]).then(() => resolve(0))
+    }
+    peer.handle('harness.shutdown', () => void setImmediate(shutdown))
+    process.stdin.on('end', shutdown)
+    process.on('SIGTERM', shutdown)
+    process.on('SIGINT', shutdown)
+    peer.send({ notice: { type: 'ready' } })
+    log('ready')
+  })
+}
+
+async function main(): Promise<number> {
+  const argv = process.argv.slice(2)
+  const [command, ...rest] = argv
+  if (argv.includes('--help') || argv.includes('-h')) {
+    process.stdout.write(USAGE)
+    return 0
+  }
+  const terminalArgs = standaloneArguments(argv)
+  if (terminalArgs !== null) return runStandaloneTerminal(terminalArgs)
+  if (command === 'serve') return serveCommand(rest)
+  if (command === 'wiki') return runWikiCli(rest)
+  if (command === 'mcp') return runAppsCli(rest)
+  if (command === 'plugins') return runPluginsCli(rest, { ask: terminalAsk() })
+  process.stdout.write(USAGE)
+  return command ? 2 : 0
+}
+
+void main().then(
+  (code) => process.exit(code),
+  (error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`)
+    process.exit(1)
+  }
+)

package/src/core/bus.ts

@@ -0,0 +1,34 @@
+// Notices: what the harness tells whoever embeds it. Run events travel separately, through the
+// run tracker; a notice says that some state changed and should be read again.
+
+export interface Notice {
+  /** `accounts.changed`, `accounts.login`, `accounts.loginEvent`, `wiki.changed`, `wiki.maintenance`, … */
+  type: string
+  [key: string]: unknown
+}
+
+export type NoticeListener = (notice: Notice) => void
+
+export class Bus {
+  private readonly listeners = new Set<NoticeListener>()
+
+  on(listener: NoticeListener): () => void {
+    this.listeners.add(listener)
+    return () => this.listeners.delete(listener)
+  }
+
+  emit(notice: Notice): void {
+    for (const listener of this.listeners) {
+      try {
+        listener(notice)
+      } catch (error) {
+        log('a notice listener failed', error instanceof Error ? error.message : String(error))
+      }
+    }
+  }
+}
+
+/** Diagnostics go to stderr; stdout may be carrying a protocol. */
+export function log(...parts: unknown[]): void {
+  process.stderr.write(`[harness] ${parts.map((part) => (typeof part === 'string' ? part : JSON.stringify(part))).join(' ')}\n`)
+}

package/src/core/changes.ts

@@ -0,0 +1,33 @@
+// A note that something in a Wiki was written: a fact, a memory block, or a page. The memory
+// code calls `noteChange` after the file is in place; whoever wants to react listens. Listeners
+// run inline and must only take the note down: a write never waits for, or fails with, a listener.
+export interface Change {
+  /** The Wiki folder the entry is in. */
+  wiki: string
+  id: string
+  /** The file that was written. */
+  path: string
+  /** Its new contents, front matter included. */
+  text: string
+  actor: string
+  reason: string
+}
+
+type Listener = (change: Change) => void
+
+const listeners = new Set<Listener>()
+
+export function noteChange(change: Change): void {
+  for (const listener of listeners) {
+    try {
+      listener(change)
+    } catch {
+      // A listener must never break the write it is told about.
+    }
+  }
+}
+
+export function onChange(listener: Listener): () => void {
+  listeners.add(listener)
+  return () => void listeners.delete(listener)
+}

package/src/core/env.ts

@@ -0,0 +1,27 @@
+// What every harness module is given: where the data lives, and what the embedding application
+// knows that the harness does not.
+
+/** Names the harness shows but does not own. Every lookup may answer `null`. */
+export interface Directory {
+  /** An agent's display name. */
+  agentName(agentId: string): string | null
+  /** The agent a conversation belongs to, when the session id is not the agent's own id. */
+  sessionAgent(sessionId: string): string | null
+}
+
+/** The name used when an application gives none. */
+export const DEFAULT_PRODUCT_NAME = 'Xingular Harness'
+
+export const EMPTY_DIRECTORY: Directory = { agentName: () => null, sessionAgent: () => null }
+
+export interface HarnessEnv {
+  /** The data root: `wiki/`, `registry/`, `runs/`, `config/`, `index.sqlite`. */
+  root: string
+  directory: Directory
+  /** How the harness names itself to a model and in the Wiki it creates. */
+  productName: string
+}
+
+export function createEnv(root: string, options: Partial<Omit<HarnessEnv, 'root'>> = {}): HarnessEnv {
+  return { root, directory: options.directory ?? EMPTY_DIRECTORY, productName: options.productName ?? DEFAULT_PRODUCT_NAME }
+}

package/src/core/errors.ts

@@ -0,0 +1,32 @@
+/** A typed failure: a stable code, a message a person can read, and an optional hint on what to do next. */
+export class HarnessError extends Error {
+  readonly code: string
+  readonly retryHint: string | null
+
+  constructor(code: string, message: string, retryHint: string | null = null) {
+    super(message)
+    this.name = 'HarnessError'
+    this.code = code
+    this.retryHint = retryHint
+  }
+
+  withHint(hint: string): HarnessError {
+    return new HarnessError(this.code, this.message, hint)
+  }
+}
+
+export const invalid = (message: string): HarnessError => new HarnessError('invalid_request', message)
+export const notFound = (what: string): HarnessError => new HarnessError('not_found', `${what} was not found.`)
+
+export interface ErrorShape {
+  code: string
+  message: string
+  retryHint?: string | null
+}
+
+export function toErrorShape(error: unknown, fallbackCode = 'harness_error'): ErrorShape {
+  if (error instanceof HarnessError) return { code: error.code, message: error.message, retryHint: error.retryHint }
+  const code = (error as { code?: unknown } | null)?.code
+  if (error instanceof Error && typeof code === 'string' && code.startsWith('E')) return { code: 'io_error', message: error.message }
+  return { code: fallbackCode, message: error instanceof Error ? error.message : String(error) }
+}

package/src/core/frontmatter.ts

@@ -0,0 +1,47 @@
+// Markdown files with a YAML frontmatter block (`---` … `---`), used by Wiki pages, facts, blocks and registry items.
+import { parse as parseYaml, stringify } from 'yaml'
+
+import { HarnessError } from './errors'
+
+export function split(text: string): { yaml: string; body: string } | null {
+  const rest = text.startsWith('---\n') ? text.slice(4) : text.startsWith('---\r\n') ? text.slice(5) : null
+  if (rest === null) return null
+  const end = rest.indexOf('\n---')
+  if (end < 0) return null
+  return { yaml: rest.slice(0, end), body: rest.slice(end + 4).replace(/^[\r\n]+/, '') }
+}
+
+/** The frontmatter as a plain object and the body, or `null` when the block is missing or is not a mapping. */
+export function parse(text: string): { front: Record<string, unknown>; body: string } | null {
+  const parts = split(text)
+  if (!parts) return null
+  try {
+    const front = parseYaml(parts.yaml)
+    if (!front || typeof front !== 'object' || Array.isArray(front)) return null
+    return { front: front as Record<string, unknown>, body: parts.body }
+  } catch {
+    return null
+  }
+}
+
+/** The text after a readable frontmatter block, or the whole text when there is none. */
+export function bodyOf(text: string): string {
+  const parts = split(text)
+  if (!parts) return text
+  try {
+    parseYaml(parts.yaml)
+    return parts.body
+  } catch {
+    return text
+  }
+}
+
+export function serialize(front: Record<string, unknown>, body: string): string {
+  let yaml: string
+  try {
+    yaml = stringify(front, { lineWidth: 0 })
+  } catch (error) {
+    throw new HarnessError('invalid_data', error instanceof Error ? error.message : String(error))
+  }
+  return `---\n${yaml}---\n\n${body.trimEnd()}\n`
+}

package/src/core/fs.test.ts

@@ -0,0 +1,38 @@
+import { mkdtempSync, readdirSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { expect, test } from 'vitest'
+
+import { parse, serialize } from './frontmatter'
+import { appendLine, readJson, readText, safeId, safeRelative, writeJson } from './fs'
+
+test('atomic write replaces contents', () => {
+  const path = join(mkdtempSync(join(tmpdir(), 'harness-')), 'nested/value.json')
+  writeJson(path, { a: 1 })
+  writeJson(path, { a: 2 })
+  expect(readJson<{ a: number }>(path)?.a).toBe(2)
+  expect(readdirSync(dirname(path))).toHaveLength(1)
+  expect(readJson(join(dirname(path), 'missing.json'))).toBeNull()
+})
+
+test('rejects unsafe ids and paths', () => {
+  expect(safeId('abc-123')).toBe('abc-123')
+  expect(() => safeId('../x')).toThrow()
+  expect(safeRelative('src/main.rs')).toBe('src/main.rs')
+  expect(() => safeRelative('../secret')).toThrow()
+  expect(() => safeRelative('/etc/passwd')).toThrow()
+})
+
+test('appends whole lines', () => {
+  const path = join(mkdtempSync(join(tmpdir(), 'harness-')), 'log.md')
+  appendLine(path, 'one')
+  appendLine(path, 'two')
+  expect(readText(path)).toBe('one\ntwo\n')
+})
+
+test('frontmatter round-trips', () => {
+  const text = serialize({ id: 'a', title: 'Has: a colon', tags: ['x'] }, 'Body\n\n')
+  expect(text.startsWith('---\n')).toBe(true)
+  expect(parse(text)).toEqual({ front: { id: 'a', title: 'Has: a colon', tags: ['x'] }, body: 'Body\n' })
+  expect(parse('no frontmatter')).toBeNull()
+})

package/src/core/fs.ts

@@ -0,0 +1,92 @@
+import { randomUUID } from 'node:crypto'
+import { closeSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeSync } from 'node:fs'
+import { basename, dirname, isAbsolute, join, normalize, sep } from 'node:path'
+
+import { HarnessError, invalid } from './errors'
+
+/** Writes through a temporary sibling file and renames it into place so readers never see a partial file. */
+export function atomicWrite(path: string, contents: string | Uint8Array): void {
+  const parent = dirname(path)
+  mkdirSync(parent, { recursive: true })
+  const temporary = join(parent, `.${basename(path)}.${randomUUID()}.tmp`)
+  const file = openSync(temporary, 'w')
+  try {
+    writeSync(file, contents as string)
+    fsyncSync(file)
+  } finally {
+    closeSync(file)
+  }
+  try {
+    renameSync(temporary, path)
+  } catch (error) {
+    rmSync(temporary, { force: true })
+    throw error
+  }
+}
+
+export function writeJson(path: string, value: unknown): void {
+  atomicWrite(path, `${JSON.stringify(value, null, 2)}\n`)
+}
+
+/** `null` when the file does not exist; a file that exists but does not parse is an error. */
+export function readJson<T>(path: string): T | null {
+  let text: string
+  try {
+    text = readFileSync(path, 'utf8')
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null
+    throw error
+  }
+  try {
+    return JSON.parse(text) as T
+  } catch (error) {
+    throw new HarnessError('invalid_data', `Stored data could not be read: ${error instanceof Error ? error.message : String(error)}`)
+  }
+}
+
+/** `readJson` for callers that treat an unreadable file like a missing one. */
+export function readJsonOr<T>(path: string, fallback: T): T {
+  try {
+    return readJson<T>(path) ?? fallback
+  } catch {
+    return fallback
+  }
+}
+
+export function readText(path: string): string | null {
+  try {
+    return readFileSync(path, 'utf8')
+  } catch {
+    return null
+  }
+}
+
+export function appendLine(path: string, line: string): void {
+  let next = readText(path) ?? ''
+  if (next && !next.endsWith('\n')) next += '\n'
+  atomicWrite(path, `${next}${line}\n`)
+}
+
+/** Accepts only IDs that are safe as a single path segment. */
+export function safeId(id: string): string {
+  if (id.length > 0 && id.length <= 128 && /^[A-Za-z0-9_-]+$/.test(id)) return id
+  throw invalid('Invalid identifier.')
+}
+
+/** Accepts a relative path that stays inside its base directory. */
+export function safeRelative(path: string): string {
+  const parts = path.split(/[\\/]/)
+  if (!path || isAbsolute(path) || parts.some((part) => part === '' || part === '.' || part === '..')) {
+    throw invalid('Path must stay inside the working directory.')
+  }
+  return normalize(path).split(sep).join('/')
+}
+
+/** Millisecond UTC timestamp, the format every record uses. */
+export function now(): string {
+  return new Date().toISOString()
+}
+
+export function newId(): string {
+  return randomUUID()
+}