@mohou/host 1.0.20

package/src/install/install.ts

@@ -0,0 +1,230 @@
+import { spawn } from 'node:child_process'
+import { readFile, rm, writeFile } from 'node:fs/promises'
+
+import { InstallError } from './codes.ts'
+import { installLayout, packageLock, packageManifest } from './layout.ts'
+
+/** Names an app must not install. The message names the replacement. */
+const DENIED: Record<string, string> = {
+  react: 'use the UI kit',
+  'react-dom': 'use the UI kit',
+  lodash: 'use the platform lodash import',
+  'lodash-es': 'use the platform lodash import',
+  axios: 'use ctx.http',
+  typescript: 'typescript is not an app dependency',
+  motion: 'use the platform motion import',
+  'framer-motion': 'use the platform motion import',
+}
+
+/** Platform scope. These packages are already provided. */
+const PLATFORM_SCOPE = '@mohou/'
+
+const NAME = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/
+const VERSION = /^[0-9A-Za-z.^~=*-]+$/
+
+/** Install timeout when the caller omits one. Host policy, not a locked number. */
+export const DEFAULT_INSTALL_TIMEOUT_MS = 120_000
+
+export interface InstallRequest {
+  packages: Array<{ name: string; version?: string }>
+  remove: string[]
+}
+
+export interface InstallResult {
+  ok: boolean
+  packages: Record<string, string>
+  lockfile: string | null
+  code?: 'install-denied' | 'install-failed'
+  message?: string
+}
+
+/** Runs `npm install` in the app directory. Tests replace this. */
+export type NpmRun = (appDir: string, signal: AbortSignal) => Promise<{ exitCode: number; stderr: string }>
+
+/**
+ * Read or change one app's dependencies. This is the only writer of `package.json`.
+ * A failed install restores the previous manifest and lockfile.
+ * @param appDir - absolute app directory
+ * @param request - admitted add and remove lists; both empty means read
+ * @param options - timeout and the npm runner
+ */
+export async function installApp(
+  appDir: string,
+  request: InstallRequest,
+  options: { timeoutMs?: number; run?: NpmRun } = {},
+): Promise<InstallResult> {
+  const current = await readManifest(appDir)
+  if (request.packages.length === 0 && request.remove.length === 0) {
+    return { ok: true, packages: current.packages, lockfile: current.lockfile }
+  }
+  const denied = deniedSpec(request)
+  if (denied !== undefined) return { ok: false, packages: current.packages, lockfile: current.lockfile, ...denied }
+  const next = applyRequest(current.packages, request)
+  const previousJson = current.raw
+  const previousLock = current.lockRaw
+  await writeManifest(appDir, next)
+  const controller = new AbortController()
+  const timer = setTimeout(() => {
+    controller.abort()
+  }, options.timeoutMs ?? DEFAULT_INSTALL_TIMEOUT_MS)
+  try {
+    const run = options.run ?? runNpm
+    const result = await run(appDir, controller.signal)
+    if (result.exitCode !== 0) {
+      await restore(appDir, previousJson, previousLock)
+      return failed(current, 'install-failed', result.stderr || 'npm install failed')
+    }
+    const pinned = await pinResolved(appDir, next)
+    await writeManifest(appDir, pinned)
+    return { ok: true, packages: pinned, lockfile: installLayout.lockfile }
+  } catch (error) {
+    await restore(appDir, previousJson, previousLock)
+    const message = controller.signal.aborted
+      ? 'npm install timed out'
+      : error instanceof Error ? error.message : 'npm install failed'
+    return failed(current, 'install-failed', message)
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+/** Spawn npm. Package names stay in `package.json`, not on the command line. */
+export function runNpm(appDir: string, signal: AbortSignal): Promise<{ exitCode: number; stderr: string }> {
+  const bin = process.platform === 'win32' ? 'npm.cmd' : 'npm'
+  return new Promise((resolve, reject) => {
+    const child = spawn(bin, ['install', '--ignore-scripts', '--omit=dev'], {
+      cwd: appDir,
+      signal,
+      windowsHide: true,
+      shell: process.platform === 'win32',
+    })
+    let stderr = ''
+    child.stderr.on('data', (chunk: Buffer) => {
+      stderr += chunk.toString('utf8')
+    })
+    child.once('error', reject)
+    child.once('close', (code) => {
+      resolve({ exitCode: code ?? 1, stderr })
+    })
+  })
+}
+
+function deniedSpec(request: InstallRequest): { code: 'install-denied'; message: string } | undefined {
+  for (const item of request.packages) {
+    const reason = denyName(item.name) ?? denyVersion(item.version)
+    if (reason !== undefined) return { code: 'install-denied', message: reason }
+  }
+  for (const name of request.remove) {
+    const reason = denyName(name)
+    if (reason !== undefined) return { code: 'install-denied', message: reason }
+  }
+  return undefined
+}
+
+function denyName(name: string): string | undefined {
+  if (!NAME.test(name)) return `package name is not a plain npm name: ${name}`
+  if (name.startsWith(PLATFORM_SCOPE)) return `use the platform import instead of installing ${name}`
+  const replacement = DENIED[name]
+  return replacement === undefined ? undefined : `${name} is denied: ${replacement}`
+}
+
+function denyVersion(version: string | undefined): string | undefined {
+  if (version === undefined) return undefined
+  if (!VERSION.test(version)) return `package version is not a plain range: ${version}`
+  return undefined
+}
+
+function applyRequest(current: Record<string, string>, request: InstallRequest): Record<string, string> {
+  const removed = new Set(request.remove)
+  const next: Record<string, string> = {}
+  for (const [name, version] of Object.entries(current)) {
+    if (!removed.has(name)) next[name] = version
+  }
+  for (const item of request.packages) next[item.name] = item.version ?? '*'
+  return next
+}
+
+async function readManifest(appDir: string): Promise<{
+  packages: Record<string, string>
+  lockfile: string | null
+  raw?: string
+  lockRaw?: string
+}> {
+  const raw = await readFile(packageManifest(appDir), 'utf8').catch(() => undefined)
+  const lockRaw = await readFile(packageLock(appDir), 'utf8').catch(() => undefined)
+  if (raw === undefined) {
+    return {
+      packages: {},
+      lockfile: lockRaw === undefined ? null : installLayout.lockfile,
+      ...lockRaw === undefined ? {} : { lockRaw },
+    }
+  }
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw) as unknown
+  } catch (error) {
+    throw new InstallError('install-failed', 'package.json is not JSON', { cause: error })
+  }
+  const dependencies = isRecord(parsed) ? parsed.dependencies : undefined
+  const packages: Record<string, string> = {}
+  if (isRecord(dependencies)) {
+    for (const [name, version] of Object.entries(dependencies)) {
+      if (typeof version === 'string') packages[name] = version
+    }
+  }
+  return {
+    packages,
+    lockfile: lockRaw === undefined ? null : installLayout.lockfile,
+    raw,
+    ...lockRaw === undefined ? {} : { lockRaw },
+  }
+}
+
+async function writeManifest(appDir: string, packages: Record<string, string>): Promise<void> {
+  const body = {
+    private: true,
+    dependencies: packages,
+  }
+  await writeFile(packageManifest(appDir), `${JSON.stringify(body, null, 2)}\n`)
+}
+
+async function restore(appDir: string, raw: string | undefined, lockRaw: string | undefined): Promise<void> {
+  const manifest = packageManifest(appDir)
+  const lock = packageLock(appDir)
+  if (raw === undefined) await rm(manifest, { force: true })
+  else await writeFile(manifest, raw)
+  if (lockRaw === undefined) await rm(lock, { force: true })
+  else await writeFile(lock, lockRaw)
+}
+
+async function pinResolved(appDir: string, requested: Record<string, string>): Promise<Record<string, string>> {
+  const text = await readFile(packageLock(appDir), 'utf8').catch(() => undefined)
+  if (text === undefined) return requested
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(text) as unknown
+  } catch {
+    return requested
+  }
+  const pinned = { ...requested }
+  if (!isRecord(parsed)) return pinned
+  const packages = isRecord(parsed.packages) ? parsed.packages : {}
+  for (const name of Object.keys(pinned)) {
+    const entry = packages[`${installLayout.modules}/${name}`]
+    const version = isRecord(entry) && typeof entry.version === 'string' ? entry.version : undefined
+    if (version !== undefined) pinned[name] = version
+  }
+  return pinned
+}
+
+function failed(
+  current: { packages: Record<string, string>; lockfile: string | null },
+  code: 'install-failed',
+  message: string,
+): InstallResult {
+  return { ok: false, packages: current.packages, lockfile: current.lockfile, code, message }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}

package/src/install/layout.ts

@@ -0,0 +1,16 @@
+import path from 'node:path'
+
+/** npm files this host writes. Spell them here, not at each read. */
+export const installLayout = {
+  manifest: 'package.json',
+  lockfile: 'package-lock.json',
+  modules: 'node_modules',
+} as const
+
+export function packageManifest(appDir: string): string {
+  return path.join(appDir, installLayout.manifest)
+}
+
+export function packageLock(appDir: string): string {
+  return path.join(appDir, installLayout.lockfile)
+}

package/src/kernel/bind-brain.ts

@@ -0,0 +1,117 @@
+import type { AppAgentEvent, AppLlmEvent } from '@mohou/contract'
+import { ProviderError, assertKnownModel, type RuntimeAgentOptions, type RuntimeLlmOptions, type RuntimeProvider, type RuntimeProviderConfig } from '@mohou/runtime-provider'
+
+import { HostError } from './codes.ts'
+import { admitModelBudget, callWithRetry, stripSchemaFence, type ModelPolicy, DEFAULT_MODEL_POLICY } from './model-policy.ts'
+import { present } from './present.ts'
+import { resolveWorkingDirectory } from './working-directory.ts'
+
+function choice(options: { provider?: string; model?: string } | undefined): { provider?: string; model?: string } {
+  return {
+    ...present('provider', options?.provider),
+    ...present('model', options?.model),
+  }
+}
+
+/** What Host needs to route model calls. Push is the app's `ctx.push`. */
+export interface BrainBinding {
+  readonly provider: RuntimeProvider
+  readonly config?: RuntimeProviderConfig
+  readonly appDir: string
+  readonly processDirectory: string
+  readonly createTemp: () => string
+  readonly push: (name: string, params: unknown) => void
+}
+
+/** App-facing model calls after the brain has started. */
+export interface BoundBrain {
+  llm(prompt: string, options?: RuntimeLlmOptions): Promise<string>
+  agent(goal: string, options?: RuntimeAgentOptions): Promise<string>
+  stop(): Promise<void>
+}
+
+/**
+ * Configure and start one injected brain, then route `llm` and `agent`.
+ * Host does not choose the vendor. `start` throwing fails the caller.
+ * @param binding - the provider Shell selected, plus directories and push
+ */
+export async function bindBrain(binding: BrainBinding, policy: ModelPolicy = DEFAULT_MODEL_POLICY): Promise<BoundBrain> {
+  binding.provider.configure?.(binding.config ?? {})
+  await binding.provider.start()
+  return {
+    async llm(prompt, options) {
+      const budget = admitModelBudget(options, policy)
+      await assertKnownModel(binding.provider, choice(options))
+      return callWithRetry(budget.retryTimes, options?.signal, async () => {
+        const text = await binding.provider.llm(prompt, llmCall(options, budget.maxTokens))
+        return options?.schema === undefined ? text : stripSchemaFence(text)
+      })
+    },
+    async agent(goal, options) {
+      try {
+        const budget = admitModelBudget(options, policy)
+        await assertKnownModel(binding.provider, choice(options))
+        const cwd = resolveWorkingDirectory({
+          ...present('cwdType', options?.cwdType),
+          ...present('cwd', options?.cwd),
+          appDir: binding.appDir,
+          processDirectory: binding.processDirectory,
+          createTemp: binding.createTemp,
+        })
+        const controller = new AbortController()
+        if (options?.signal?.aborted) controller.abort()
+        else options?.signal?.addEventListener('abort', () => {
+          controller.abort()
+        }, { once: true })
+        let completedTurns = 0
+        const onEvent = (event: AppAgentEvent): void => {
+          try {
+            options?.onEvent?.(event)
+          } catch {
+            // A throwing observer does not abort the run.
+          }
+          if (event.type === 'turn' && event.phase === 'end') {
+            completedTurns += 1
+            if (completedTurns >= budget.maxIterations) controller.abort()
+          }
+        }
+        return await callWithRetry(budget.retryTimes, options?.signal, () => binding.provider.agent(goal, {
+          ...options,
+          cwd,
+          cwdType: 'custom',
+          signal: controller.signal,
+          onEvent,
+        }))
+      } catch (error) {
+        throw namedAgent(error)
+      }
+    },
+    // The host owns the shared provider. A finished app call must not clear it.
+    stop: () => Promise.resolve(),
+  }
+}
+
+function llmCall(options: RuntimeLlmOptions | undefined, maxTokens: number): RuntimeLlmOptions {
+  const budgeted = { ...options, maxTokens: options?.maxTokens ?? maxTokens }
+  if (options?.stream !== true) {
+    const { onEvent: _ignored, ...quiet } = budgeted
+    return quiet
+  }
+  const onEvent = (event: AppLlmEvent): void => {
+    try {
+      options.onEvent?.(event)
+    } catch {
+      // A throwing observer does not abort the completion.
+    }
+  }
+  return { ...budgeted, onEvent }
+}
+
+function namedAgent(error: unknown): Error {
+  if (error instanceof ProviderError) {
+    return new ProviderError(error.code, `agent: ${error.message}`, { cause: error })
+  }
+  if (error instanceof HostError) return new HostError(error.code, `agent: ${error.message}`)
+  const message = error instanceof Error ? error.message : 'agent failed'
+  return new ProviderError('provider-unhealthy', `agent: ${message}`, { cause: error })
+}

package/src/kernel/call.ts

@@ -0,0 +1,134 @@
+import type {
+  AppAgentEvent,
+  AppApiMethod,
+  AppConfig,
+  AppContext,
+  AppCredentials,
+  AppHttpRequest,
+  AppHttpResponse,
+  AppId,
+  AppLlmEvent,
+  AppStorage,
+  AppSystemMetrics,
+  AppWorkbench,
+} from '@mohou/contract'
+
+import type { CredentialProvider } from '../credentials/provider.ts'
+import type { BoundBrain } from './bind-brain.ts'
+import { HostError } from './codes.ts'
+import { modelStream } from './model-stream.ts'
+import { present } from './present.ts'
+
+/** Ports already constructed outside the kernel. The call loop only binds them. */
+export interface CallCapabilities<State extends object = Record<string, never>> {
+  readonly appId: AppId
+  readonly appDir: string
+  readonly state: State
+  readonly storage: AppStorage
+  readonly credentials: CredentialProvider
+  readonly config: AppConfig
+  readonly log: (...args: unknown[]) => void
+  readonly push: (name: string, params?: unknown) => void
+  readonly http: (url: string | AppHttpRequest, opts?: Omit<AppHttpRequest, 'url'>) => Promise<AppHttpResponse>
+  readonly bash: (command: string) => Promise<{ stdout: string; stderr: string; exitCode: number }>
+  readonly pwsh: (command: string) => Promise<{ stdout: string; stderr: string; exitCode: number }>
+  readonly metrics: () => Promise<AppSystemMetrics>
+  readonly mcp: (serverId: string, toolName: string, args?: Record<string, unknown>) => Promise<unknown>
+  readonly brain: BoundBrain
+  readonly workbench?: AppWorkbench
+}
+
+/**
+ * Run one app method inside a context built from injected ports.
+ * A method that yields, or that returns a model stream, is read here.
+ * `publish` receives each yielded value. A plain `call` omits it.
+ * The signal aborts when the call settles. An unknown name emits `unknown-method`.
+ */
+export async function runCall<State extends object>(
+  capabilities: CallCapabilities<State>,
+  api: Record<string, AppApiMethod<State>>,
+  name: string,
+  args: unknown,
+  publish?: (value: unknown) => Promise<void> | void,
+): Promise<unknown> {
+  const method = api[name]
+  if (method === undefined) {
+    throw new HostError('unknown-method', `unknown api method: ${name}`)
+  }
+  const controller = new AbortController()
+  const ctx: AppContext<State> = contextFor(capabilities, controller.signal)
+  try {
+    return await readMethod(method(ctx, args), publish)
+  } finally {
+    controller.abort()
+  }
+}
+
+function credentialsFor(provider: CredentialProvider): AppCredentials {
+  return {
+    get: name => provider.get(name),
+  }
+}
+
+function contextFor<State extends object>(capabilities: CallCapabilities<State>, signal: AbortSignal): AppContext<State> {
+  return {
+    appId: capabilities.appId,
+    appDir: capabilities.appDir,
+    storage: capabilities.storage,
+    state: capabilities.state,
+    credentials: credentialsFor(capabilities.credentials),
+    config: capabilities.config,
+    log: capabilities.log,
+    signal,
+    push: capabilities.push,
+    http: capabilities.http,
+    bash: capabilities.bash,
+    pwsh: capabilities.pwsh,
+    system: { metrics: capabilities.metrics },
+    llm: ((prompt, options) => {
+      if (options?.stream !== true) {
+        return capabilities.brain.llm(prompt, { ...options, signal: options?.signal ?? signal })
+      }
+      return modelStream((emit: (event: AppLlmEvent) => void) => capabilities.brain.llm(prompt, {
+        ...options,
+        signal: options.signal ?? signal,
+        onEvent: emit,
+      }))
+    }) as AppContext<State>['llm'],
+    agent: ((goal, options) => {
+      const forwarded = {
+        ...options,
+        ...present('signal', options?.signal ?? signal),
+      }
+      if (options?.stream !== true) return capabilities.brain.agent(goal, forwarded)
+      return modelStream((emit: (event: AppAgentEvent) => void) => capabilities.brain.agent(goal, {
+        ...forwarded,
+        onEvent: emit,
+      }))
+    }) as AppContext<State>['agent'],
+    mcp: capabilities.mcp,
+    ...capabilities.workbench === undefined ? {} : { workbench: capabilities.workbench },
+  }
+}
+
+async function readMethod(output: unknown, publish?: (value: unknown) => Promise<void> | void): Promise<unknown> {
+  const value = isThenable(output) && !isAsyncIterable(output) ? await output : output
+  if (!isAsyncIterable(value)) return value
+  const iterator = value[Symbol.asyncIterator]()
+  let step = await iterator.next()
+  while (!step.done) {
+    await publish?.(step.value)
+    step = await iterator.next()
+  }
+  if (step.value !== undefined) return step.value
+  if (isThenable(value)) return value
+  return undefined
+}
+
+function isAsyncIterable(value: unknown): value is AsyncIterable<unknown> {
+  return typeof value === 'object' && value !== null && Symbol.asyncIterator in value
+}
+
+function isThenable(value: unknown): value is PromiseLike<unknown> {
+  return typeof value === 'object' && value !== null && typeof (value as { then?: unknown }).then === 'function'
+}

package/src/kernel/codes.ts

@@ -0,0 +1,21 @@
+/** Codes this host slice emits. */
+
+export const hostCodes = ['cwd-invalid', 'unknown-method', 'model-policy'] as const
+
+/** A failure emitted while preparing a brain call. */
+export type HostCode = (typeof hostCodes)[number]
+
+/** Failure a caller branches on. The message is for a person. */
+export class HostError extends Error {
+  readonly code: HostCode
+
+  /**
+   * @param code - one of {@link hostCodes}
+   * @param message - human text; not the match key
+   */
+  constructor(code: HostCode, message: string) {
+    super(message)
+    this.name = 'HostError'
+    this.code = code
+  }
+}

package/src/kernel/index.ts

@@ -0,0 +1,13 @@
+/** Call loop. @module @mohou/host */
+
+export { HostError, hostCodes, type HostCode } from './codes.ts'
+export { resolveWorkingDirectory, type WorkingDirectoryInput } from './working-directory.ts'
+export { bindBrain, type BoundBrain, type BrainBinding } from './bind-brain.ts'
+export {
+  DEFAULT_MODEL_POLICY,
+  admitModelBudget,
+  callWithRetry,
+  stripSchemaFence,
+  type ModelPolicy,
+} from './model-policy.ts'
+export { runCall, type CallCapabilities } from './call.ts'

package/src/kernel/model-policy.ts

@@ -0,0 +1,83 @@
+import { ProviderError } from '@mohou/runtime-provider'
+
+import { HostError } from './codes.ts'
+
+/** Token and retry bounds. Host policy, not a locked product value. */
+export interface ModelPolicy {
+  maxTokens: number
+  maxTokensLimit: number
+  retryTimes: number
+  retryTimesLimit: number
+  maxIterations: number
+  maxIterationsLimit: number
+}
+
+export const DEFAULT_MODEL_POLICY: ModelPolicy = {
+  maxTokens: 2_048,
+  maxTokensLimit: 8_192,
+  retryTimes: 1,
+  retryTimesLimit: 3,
+  maxIterations: 100,
+  maxIterationsLimit: 100,
+}
+
+/** Strip one markdown fence when `schema` asked for JSON. The caller still parses the string. */
+export function stripSchemaFence(text: string): string {
+  const match = /^```(?:json)?\s*([\s\S]*?)\s*```$/.exec(text.trim())
+  return match?.[1] ?? text
+}
+
+export function admitModelBudget(options: {
+  maxTokens?: number
+  retryTimes?: number
+  maxIterations?: number
+} | undefined, policy: ModelPolicy): {
+  maxTokens: number
+  retryTimes: number
+  maxIterations: number
+} {
+  return {
+    maxTokens: admitNumber(options?.maxTokens, policy.maxTokens, policy.maxTokensLimit, 'maxTokens'),
+    retryTimes: admitNumber(options?.retryTimes, policy.retryTimes, policy.retryTimesLimit, 'retryTimes'),
+    maxIterations: admitNumber(options?.maxIterations, policy.maxIterations, policy.maxIterationsLimit, 'maxIterations'),
+  }
+}
+
+/**
+ * Run a model call up to `times`, counting the first attempt.
+ * Cancel is not retried. An empty string is a failed attempt.
+ */
+export async function callWithRetry(
+  times: number,
+  signal: AbortSignal | undefined,
+  run: () => Promise<string>,
+): Promise<string> {
+  let last: unknown
+  for (let attempt = 0; attempt < times; attempt += 1) {
+    if (signal?.aborted) throw new ProviderError('cancelled', 'model call was cancelled')
+    try {
+      const text = await run()
+      if (text.length === 0) throw new ProviderError('empty-completion', 'model call returned an empty completion')
+      return text
+    } catch (error) {
+      if (isCancelled(error, signal)) {
+        throw error instanceof ProviderError ? error : new ProviderError('cancelled', 'model call was cancelled', { cause: error })
+      }
+      last = error
+    }
+  }
+  throw new ProviderError('retry-exhausted', 'model call retries exhausted', { cause: last })
+}
+
+function admitNumber(value: number | undefined, fallback: number, limit: number, field: string): number {
+  const chosen = value ?? fallback
+  if (!Number.isInteger(chosen) || chosen < 1 || chosen > limit) {
+    throw new HostError('model-policy', `${field} is outside the host policy`)
+  }
+  return chosen
+}
+
+function isCancelled(error: unknown, signal: AbortSignal | undefined): boolean {
+  if (signal?.aborted) return true
+  return typeof error === 'object' && error !== null && 'code' in error && error.code === 'cancelled'
+}