@mohou/host 1.0.20

package/src/kernel/model-stream.ts

@@ -0,0 +1,86 @@
+/**
+ * Turn a callback-shaped model call into a stream the method can `for await`.
+ * Awaiting the same object waits for the final string. Iteration does not start a second call.
+ */
+export function modelStream<Event>(
+  run: (emit: (event: Event) => void) => Promise<string>,
+): AsyncIterable<Event> & Promise<string> {
+  const queued: Event[] = []
+  let waiting: { resolve: (step: IteratorResult<Event>) => void; reject: (error: unknown) => void } | undefined
+  let settled = false
+  let failure: unknown
+  let started = false
+  let resolveText: (value: string) => void
+  let rejectText: (error: unknown) => void
+  const text = new Promise<string>((resolve, reject) => {
+    resolveText = resolve
+    rejectText = reject
+  })
+  void text.catch(() => undefined)
+
+  const push = (event: Event): void => {
+    if (waiting !== undefined) {
+      const resume = waiting
+      waiting = undefined
+      resume.resolve({ value: event, done: false })
+      return
+    }
+    queued.push(event)
+  }
+
+  const finish = (): void => {
+    const resume = waiting
+    waiting = undefined
+    if (resume === undefined) return
+    if (failure instanceof Error) resume.reject(failure)
+    else resume.resolve({ value: undefined, done: true })
+  }
+
+  const start = (): void => {
+    if (started) return
+    started = true
+    run(push).then((value) => {
+      settled = true
+      resolveText(value)
+      finish()
+    }, (error: unknown) => {
+      settled = true
+      failure = error
+      rejectText(error)
+      finish()
+    })
+  }
+
+  const iterator: AsyncIterator<Event> = {
+    next() {
+      start()
+      const event = queued.shift()
+      if (event !== undefined) return Promise.resolve({ value: event, done: false })
+      if (failure !== undefined) return Promise.reject(failure instanceof Error ? failure : new Error('model stream failed'))
+      if (settled) return Promise.resolve({ value: undefined, done: true })
+      return new Promise((resolve, reject) => {
+        waiting = { resolve, reject }
+      })
+    },
+  }
+
+  return {
+    [Symbol.asyncIterator]() {
+      start()
+      return iterator
+    },
+    then(onFulfilled, onRejected) {
+      start()
+      return text.then(onFulfilled, onRejected)
+    },
+    catch(onRejected) {
+      start()
+      return text.catch(onRejected)
+    },
+    finally(onFinally) {
+      start()
+      return text.finally(onFinally)
+    },
+    [Symbol.toStringTag]: 'Promise',
+  } as AsyncIterable<Event> & Promise<string>
+}

package/src/kernel/present.ts

@@ -0,0 +1,4 @@
+/** Omit a key when the value is undefined, for exact optional properties. */
+export function present<Key extends string, Value>(key: Key, value: Value | undefined): Partial<Record<Key, Value>> {
+  return value === undefined ? {} : { [key]: value } as Record<Key, Value>
+}

package/src/kernel/working-directory.ts

@@ -0,0 +1,35 @@
+import type { AppAgentOptions } from '@mohou/contract'
+
+import { HostError } from './codes.ts'
+
+/** Directories Host already knows. A missing base is not filled from `process.cwd()`. */
+export interface WorkingDirectoryInput {
+  readonly cwdType?: AppAgentOptions['cwdType']
+  readonly cwd?: string
+  readonly appDir: string
+  readonly processDirectory: string
+  readonly createTemp: () => string
+}
+
+function isAbsolute(path: string): boolean {
+  return path.startsWith('/') || /^[A-Za-z]:[\\/]/.test(path)
+}
+
+/**
+ * Resolve the directory an agent run uses.
+ * A path with no mode means `custom`. A path plus another mode fails.
+ * @param input - call options plus host-owned directories
+ */
+export function resolveWorkingDirectory(input: WorkingDirectoryInput): string {
+  const mode = input.cwdType ?? (input.cwd === undefined ? 'process' : 'custom')
+  if (input.cwd !== undefined && mode !== 'custom') {
+    throw new HostError('cwd-invalid', 'cwd requires cwdType custom')
+  }
+  if (mode === 'app') return input.appDir
+  if (mode === 'process') return input.processDirectory
+  if (mode === 'temp') return input.createTemp()
+  if (input.cwd === undefined || !isAbsolute(input.cwd)) {
+    throw new HostError('cwd-invalid', 'custom cwd must be an absolute path')
+  }
+  return input.cwd
+}

package/src/metrics/codes.ts

@@ -0,0 +1,22 @@
+/** Codes the metrics call emits. */
+
+export const metricsCodes = ['metrics-unreadable'] as const
+
+/** A metrics failure. Callers match `code`. */
+export type MetricsCode = (typeof metricsCodes)[number]
+
+/** Failure from `ctx.system.metrics`. The message is for a person. */
+export class MetricsError extends Error {
+  readonly code: MetricsCode
+
+  /**
+   * @param code - one of {@link metricsCodes}
+   * @param message - human text; not the match key
+   * @param options - optional `cause`
+   */
+  constructor(code: MetricsCode, message: string, options?: { cause?: unknown }) {
+    super(message, options)
+    this.name = 'MetricsError'
+    this.code = code
+  }
+}

package/src/metrics/read.ts

@@ -0,0 +1,48 @@
+import { arch, cpus, freemem, hostname, loadavg, platform, totalmem, uptime } from 'node:os'
+
+import type { AppSystemMetrics } from '@mohou/contract'
+
+import { MetricsError } from './codes.ts'
+
+/**
+ * Read one OS snapshot. Windows does not provide a load average, so that field is null.
+ * A missing CPU list or a zero memory total throws. Zeros are not filled in.
+ */
+function readLoadavg(osPlatform: NodeJS.Platform): AppSystemMetrics['loadavg'] {
+  if (osPlatform === 'win32') return null
+  const load = loadavg()
+  const one = load[0]
+  const five = load[1]
+  const fifteen = load[2]
+  if (one === undefined || five === undefined || fifteen === undefined) {
+    throw new MetricsError('metrics-unreadable', 'load average is unreadable')
+  }
+  return { '1m': one, '5m': five, '15m': fifteen }
+}
+
+export function readMetrics(now: Date = new Date(), osPlatform: NodeJS.Platform = platform()): AppSystemMetrics {
+  try {
+    const cpu = cpus()
+    const first = cpu[0]
+    const total = totalmem()
+    if (first === undefined || total === 0) {
+      throw new MetricsError('metrics-unreadable', 'OS snapshot is unreadable')
+    }
+    const free = freemem()
+    const used = total - free
+    const load = readLoadavg(osPlatform)
+    return {
+      platform: platform(),
+      arch: arch(),
+      hostname: hostname(),
+      uptimeSec: uptime(),
+      loadavg: load,
+      memory: { total, free, used, usedRatio: used / total },
+      cpu: { count: cpu.length, model: first.model, speedMHz: first.speed },
+      collectedAt: now.toISOString(),
+    }
+  } catch (error) {
+    if (error instanceof MetricsError) throw error
+    throw new MetricsError('metrics-unreadable', 'OS snapshot is unreadable', { cause: error })
+  }
+}

package/src/owner/read.ts

@@ -0,0 +1,85 @@
+import { existsSync, statSync } from 'node:fs'
+
+import type { AppSummary } from '../apps/registry.ts'
+import type { HostEvent } from '../events/host-events.ts'
+import { listHistory, readAppCommit, type HistoryNode } from '../history/store.ts'
+import { storageDatabase } from '../storage/layout.ts'
+import { openStorage } from '../storage/open.ts'
+
+/** Owner table export cap. Host policy, not a locked number. */
+export const DEFAULT_OWNER_ROW_CAP = 1_000
+
+interface Registry {
+  get: (appId: string) => Promise<AppSummary>
+}
+
+/**
+ * Owner reads. Not authoring tools. Panel HTTP calls these through the loopback routes.
+ * @param registry - registered apps
+ */
+export function createOwnerReads(registry: Registry, maxRows = DEFAULT_OWNER_ROW_CAP) {
+  return {
+    readStorage: (appId: string) => readStorage(registry, appId),
+    readTable: (appId: string, table: string) => readTable(registry, appId, table, maxRows),
+    readHistory: (appId: string) => readHistory(registry, appId),
+    readCommit: (appId: string, commitId: string) => readCommit(registry, appId, commitId),
+  }
+}
+
+async function readStorage(registry: Registry, appId: string): Promise<{ bytes: number; tables: string[] }> {
+  const app = await registry.get(appId)
+  const file = storageDatabase(app.directory)
+  if (!existsSync(file)) return { bytes: 0, tables: [] }
+  const storage = await openStorage(app.directory)
+  try {
+    return { bytes: statSync(file).size, tables: storage.listTables() }
+  } finally {
+    storage.close()
+  }
+}
+
+async function readTable(registry: Registry, appId: string, table: string, maxRows: number): Promise<{ rows: unknown[] }> {
+  const app = await registry.get(appId)
+  const file = storageDatabase(app.directory)
+  if (!existsSync(file)) return { rows: [] }
+  const storage = await openStorage(app.directory)
+  try {
+    return { rows: storage.exportTable(table, maxRows) }
+  } finally {
+    storage.close()
+  }
+}
+
+async function readHistory(registry: Registry, appId: string): Promise<HistoryNode[]> {
+  const app = await registry.get(appId)
+  const listed = await listHistory(app.directory)
+  const nodes = [...listed.nodes]
+  const seen = new Set(nodes.map(node => node.id))
+  for (const tip of listed.tips) {
+    if (seen.has(tip.commitId)) continue
+    const commit = await readAppCommit(app.directory, tip.commitId)
+    nodes.push({
+      id: tip.commitId,
+      message: commit.message,
+      time: commit.time,
+      parentIds: commit.parentIds,
+    })
+    seen.add(tip.commitId)
+  }
+  return nodes
+}
+
+async function readCommit(registry: Registry, appId: string, commitId: string) {
+  const app = await registry.get(appId)
+  return readAppCommit(app.directory, commitId)
+}
+
+/** Owner refetch. Does not compile. A missing app throws before any event. */
+export async function reloadView(
+  registry: Registry,
+  publish: (event: HostEvent) => void,
+  appId: string,
+): Promise<void> {
+  const app = await registry.get(appId)
+  publish({ type: 'app:reload', appId: app.id })
+}

package/src/pwsh/client.ts

@@ -0,0 +1,47 @@
+import type { CommandHandle, CommandPolicy } from '../shell/command.ts'
+import { createCommand } from '../shell/command.ts'
+import { PwshError } from './codes.ts'
+
+/** UTF-8 preamble. It stays on the first line so later error lines stay accurate. */
+const ENCODING_PREAMBLE = '[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false); $OutputEncoding = [System.Text.UTF8Encoding]::new($false); '
+
+/**
+ * Executables to try, in order. Windows falls back to Windows PowerShell.
+ * macOS and Linux only try `pwsh`. Bash is never a fallback.
+ * @param platform - `process.platform`
+ */
+export function pwshCandidates(platform = process.platform): readonly string[] {
+  return platform === 'win32' ? ['pwsh', 'powershell.exe'] : ['pwsh']
+}
+
+/**
+ * Build `ctx.pwsh`. Each command is a fresh non-interactive PowerShell.
+ * It is not a translation of `ctx.bash`.
+ * @param policy - resolved host bounds
+ * @param callSignal - aborting it stops the child
+ * @param shell - executable name; tests inject a missing one
+ */
+export function createPwsh(policy: CommandPolicy, callSignal?: AbortSignal, shell?: string): CommandHandle {
+  const candidates = shell === undefined ? [...pwshCandidates()] : [shell]
+  let index = 0
+  const handle = createCommand(
+    policy,
+    callSignal,
+    command => [candidates[index] ?? 'pwsh', '-NoLogo', '-NoProfile', '-NonInteractive', '-Command', `${ENCODING_PREAMBLE}${command}`],
+    () => new PwshError('pwsh-unavailable', 'pwsh is not available'),
+  )
+  return {
+    async run(command) {
+      try {
+        return await handle.run(command)
+      } catch (error) {
+        if (error instanceof PwshError && index < candidates.length - 1) {
+          index += 1
+          return handle.run(command)
+        }
+        throw error
+      }
+    },
+    dispose: () => handle.dispose(),
+  }
+}

package/src/pwsh/codes.ts

@@ -0,0 +1,21 @@
+/** Codes the PowerShell call emits. Timeout and output cap are not codes. */
+
+export const pwshCodes = ['pwsh-unavailable'] as const
+
+/** A PowerShell failure. Callers match `code`. */
+export type PwshCode = (typeof pwshCodes)[number]
+
+/** Failure from `ctx.pwsh`. The message is for a person. */
+export class PwshError extends Error {
+  readonly code: PwshCode
+
+  /**
+   * @param code - one of {@link pwshCodes}
+   * @param message - human text; not the match key
+   */
+  constructor(code: PwshCode, message: string) {
+    super(message)
+    this.name = 'PwshError'
+    this.code = code
+  }
+}

package/src/shell/command.ts

@@ -0,0 +1,172 @@
+import { type ChildProcess, spawn } from 'node:child_process'
+
+/** Injected bounds. The numbers are host policy and are not locked here. */
+export interface CommandPolicy {
+  readonly timeoutMs: number
+  readonly maxOutputBytes: number
+}
+
+/** One command result. A non-zero exit is not a failure code. */
+export interface CommandResult {
+  stdout: string
+  stderr: string
+  exitCode: number
+}
+
+/** A live shell binding. `dispose` waits until every child has exited. */
+export interface CommandHandle {
+  run(command: string): Promise<CommandResult>
+  dispose(): Promise<void>
+}
+
+/** Result used when host policy stops the child. Not a failure code. */
+const STOPPED = 124
+
+/** Drop credential-shaped names. Match is case-insensitive. */
+const SENSITIVE_ENV = /KEY|SECRET|TOKEN|PASSWORD/i
+
+/** Parent environment minus key, secret, token, and password entries. */
+export function scrubShellEnv(env: NodeJS.ProcessEnv = process.env): Record<string, string> {
+  const next: Record<string, string> = {}
+  for (const [key, value] of Object.entries(env)) {
+    if (value !== undefined && !SENSITIVE_ENV.test(key)) next[key] = value
+  }
+  return next
+}
+
+/**
+ * Spawn one command. `argv` is the full executable plus arguments.
+ * Stopping a child uses `kill()` with no signal so Windows can terminate it.
+ * @param policy - resolved host bounds
+ * @param callSignal - aborting it stops the child
+ * @param argv - executable and arguments for this command
+ * @param unavailable - error when the executable is missing
+ */
+export function createCommand(
+  policy: CommandPolicy,
+  callSignal: AbortSignal | undefined,
+  argv: (command: string) => string[],
+  unavailable: () => Error,
+): CommandHandle {
+  const children = new Set<ChildProcess>()
+  return {
+    run: command => run(policy, callSignal, argv(command), children, unavailable),
+    dispose: () => dispose(children),
+  }
+}
+
+async function run(
+  policy: CommandPolicy,
+  callSignal: AbortSignal | undefined,
+  argv: string[],
+  children: Set<ChildProcess>,
+  unavailable: () => Error,
+): Promise<CommandResult> {
+  if (callSignal?.aborted) return { stdout: '', stderr: '', exitCode: STOPPED }
+  const [executable, ...args] = argv
+  if (executable === undefined) throw unavailable()
+  const child = spawn(executable, args, {
+    env: scrubShellEnv(),
+    stdio: ['ignore', 'pipe', 'pipe'],
+    // A new process group on POSIX so stop() can signal descendants. Windows uses taskkill /T.
+    detached: process.platform !== 'win32',
+  })
+  children.add(child)
+  const stdout = collect(child.stdout, policy.maxOutputBytes, () => {
+    stop(child)
+  })
+  const stderr = collect(child.stderr, policy.maxOutputBytes, () => {
+    stop(child)
+  })
+  const timer = setTimeout(() => {
+    stop(child)
+  }, policy.timeoutMs)
+  const onAbort = () => {
+    stop(child)
+  }
+  callSignal?.addEventListener('abort', onAbort, { once: true })
+  try {
+    const exitCode = await exited(child, unavailable)
+    return {
+      stdout: await stdout,
+      stderr: await stderr,
+      exitCode: exitCode ?? STOPPED,
+    }
+  } finally {
+    clearTimeout(timer)
+    callSignal?.removeEventListener('abort', onAbort)
+    children.delete(child)
+  }
+}
+
+function collect(stream: NodeJS.ReadableStream | null, maxBytes: number, onCap: () => void): Promise<string> {
+  if (stream === null) return Promise.resolve('')
+  const chunks: Buffer[] = []
+  let total = 0
+  return new Promise((resolve) => {
+    stream.on('data', (chunk: Buffer) => {
+      const remaining = maxBytes - total
+      if (remaining <= 0) {
+        onCap()
+        return
+      }
+      const slice = chunk.subarray(0, remaining)
+      chunks.push(slice)
+      total += slice.byteLength
+      if (chunk.byteLength > remaining) onCap()
+    })
+    stream.on('end', () => {
+      resolve(Buffer.concat(chunks).toString('utf8'))
+    })
+    stream.on('error', () => {
+      resolve(Buffer.concat(chunks).toString('utf8'))
+    })
+  })
+}
+
+export function stopChild(
+  child: ChildProcess,
+  platform = process.platform,
+  killTree: (pid: number) => void = (pid) => {
+    spawn('taskkill', ['/PID', String(pid), '/T', '/F'], { stdio: 'ignore' })
+  },
+): void {
+  if (child.exitCode !== null || child.signalCode !== null) return
+  const pid = child.pid
+  if (pid === undefined) return
+  if (platform === 'win32') {
+    killTree(pid)
+    return
+  }
+  try {
+    process.kill(-pid, 'SIGTERM')
+  } catch {
+    child.kill()
+  }
+}
+
+function stop(child: ChildProcess): void {
+  stopChild(child)
+}
+
+function exited(child: ChildProcess, unavailable: () => Error): Promise<number | null> {
+  if (child.exitCode !== null) return Promise.resolve(child.exitCode)
+  return new Promise((resolve, reject) => {
+    child.once('error', (error: NodeJS.ErrnoException) => {
+      if (error.code === 'ENOENT') {
+        reject(unavailable())
+        return
+      }
+      reject(error)
+    })
+    child.once('exit', (code) => {
+      resolve(code)
+    })
+  })
+}
+
+async function dispose(children: Set<ChildProcess>): Promise<void> {
+  const pending = [...children]
+  for (const child of pending) stop(child)
+  await Promise.all(pending.map(child => exited(child, () => new Error('shell is not available')).catch(() => null)))
+}

package/src/storage/codes.ts

@@ -0,0 +1,33 @@
+/** Codes the storage engine emits. */
+
+export const storageCodes = [
+  'storage-not-json',
+  'storage-corrupt',
+  'storage-forbidden',
+  'storage-sql',
+  'storage-statement',
+  'storage-too-large',
+  'storage-version',
+  'storage-backup-too-large',
+  'storage-migration',
+  'cancelled',
+] as const
+
+/** A storage failure. Callers match `code`. */
+export type StorageCode = (typeof storageCodes)[number]
+
+/** Failure from the storage engine. The message is for a person. */
+export class StorageError extends Error {
+  readonly code: StorageCode
+
+  /**
+   * @param code - one of {@link storageCodes}
+   * @param message - human text; not the match key
+   * @param options - optional `cause`
+   */
+  constructor(code: StorageCode, message: string, options?: { cause?: unknown }) {
+    super(message, options)
+    this.name = 'StorageError'
+    this.code = code
+  }
+}

package/src/storage/layout.ts

@@ -0,0 +1,44 @@
+import path from 'node:path'
+
+/**
+ * On-disk names for one app's storage. Product code asks this module for a path.
+ * Do not spell the directory or the database file anywhere else.
+ */
+export const storageLayout = {
+  dir: 'storage',
+  database: 'app.sqlite',
+  backup: 'backup.sqlite',
+  backupMeta: 'backup.json',
+  blocked: 'blocked.json',
+  quarantineSuffix: '.quarantine',
+} as const
+
+/** The storage directory. Listing and history skip this name. */
+export function storageDir(appDir: string): string {
+  return path.join(appDir, storageLayout.dir)
+}
+
+/** The live database file. */
+export function storageDatabase(appDir: string): string {
+  return path.join(storageDir(appDir), storageLayout.database)
+}
+
+/** The one pre-migration snapshot. */
+export function storageBackup(appDir: string): string {
+  return path.join(storageDir(appDir), storageLayout.backup)
+}
+
+/** Metadata for {@link storageBackup}. */
+export function storageBackupMeta(appDir: string): string {
+  return path.join(storageDir(appDir), storageLayout.backupMeta)
+}
+
+/** Checksums a restore must not apply again. */
+export function storageBlocked(appDir: string): string {
+  return path.join(storageDir(appDir), storageLayout.blocked)
+}
+
+/** Marker left beside a quarantined database. A later open does not replace the file. */
+export function storageQuarantine(appDir: string): string {
+  return `${storageDatabase(appDir)}${storageLayout.quarantineSuffix}`
+}