@mohou/runtime-pi 1.0.20

package/README.md

@@ -0,0 +1,10 @@
+---
+status: locked
+updated: 2026-10-01
+---
+
+# @mohou/runtime-pi
+
+Role: `provider`.
+
+Pi brain. `llm` is one `ModelRuntime.completeSimple` call. `models` is `ModelRuntime.getModels()`. Pi owns the catalog path and the provider API. This package does not read `models.json` and does not send its own HTTP request. `agent` is one in-memory coding-agent session and does not write a session file. Shell injects it. Host does not import this package. Product: [ctx.agent](../../../docs/product/runtime/ctx-agent.md).

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@mohou/runtime-pi",
+  "version": "1.0.20",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "lib/types",
+    "README.md",
+    "!**/*.tsbuildinfo"
+  ],
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@mohou/contract": "^1.0.20",
+    "@mohou/runtime-provider": "^1.0.20"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": ">=0.85.0",
+    "@earendil-works/pi-coding-agent": ">=0.85.0"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "0.85.1",
+    "@earendil-works/pi-coding-agent": "0.85.1"
+  }
+}

package/src/agent-session.ts

@@ -0,0 +1,144 @@
+import type { ModelRuntime } from '@earendil-works/pi-coding-agent'
+import { ProviderError, type RuntimeAgentOptions, type RuntimeProviderConfig } from '@mohou/runtime-provider'
+
+/**
+ * One Pi coding-agent run. The session is in memory. The conversation is not written.
+ * The loader uses Pi's agent directory. No tool allowlist is passed.
+ * @param config - configured provider and model. Both absent leaves Pi's own default.
+ * @param goal - the user turn
+ * @param call - cwd, system text, model override, abort, and the observer
+ * @returns the last assistant text
+ * @throws ProviderError `unknown-model` when the provider/model pair is missing or unknown.
+ * `empty-completion` when the run ends with no text. `cancelled` when the signal aborts.
+ * `provider-unhealthy` when the session fails.
+ */
+export async function runPiAgent(
+  config: RuntimeProviderConfig,
+  goal: string,
+  call: RuntimeAgentOptions | undefined,
+): Promise<string> {
+  const { createAgentSession, DefaultResourceLoader, ModelRuntime, SessionManager, SettingsManager, getAgentDir } = await import('@earendil-works/pi-coding-agent')
+  const agentDir = getAgentDir()
+  const cwd = call?.cwd ?? process.cwd()
+  observe(call, { type: 'status', status: 'running' })
+  const runtime = await ModelRuntime.create({ refreshOnCreate: false }).catch(unhealthy)
+  const model = selectedModel(runtime, config, call) ?? piDefaultModel(runtime, SettingsManager.create(cwd, agentDir))
+  const loader = new DefaultResourceLoader({
+    cwd,
+    agentDir,
+    ...call?.system === undefined ? {} : { appendSystemPrompt: [call.system] },
+  })
+  await loader.reload().catch(unhealthy)
+  const { session } = await createAgentSession({
+    cwd,
+    agentDir,
+    modelRuntime: runtime,
+    resourceLoader: loader,
+    sessionManager: SessionManager.inMemory(cwd),
+    ...model === undefined ? {} : { model },
+  }).catch(unhealthy)
+  let turn = 0
+  const unsubscribe = session.subscribe((event) => {
+    if (event.type === 'turn_start') {
+      turn += 1
+      observe(call, { type: 'turn', phase: 'start', turn })
+      return
+    }
+    if (event.type === 'turn_end') {
+      observe(call, {
+        type: 'turn',
+        phase: 'end',
+        turn,
+        reason: { kind: call?.signal?.aborted ? 'aborted' : 'completed' },
+      })
+      return
+    }
+    if (event.type === 'message_update' && event.assistantMessageEvent.type === 'text_delta') {
+      observe(call, { type: 'text-delta', text: event.assistantMessageEvent.delta })
+      return
+    }
+    if (event.type === 'tool_execution_start') {
+      observe(call, { type: 'tool', phase: 'start', name: event.toolName, args: event.args })
+      return
+    }
+    if (event.type === 'tool_execution_end') {
+      observe(call, { type: 'tool', phase: 'end', name: event.toolName, result: event.result })
+    }
+  })
+  const abort = (): void => {
+    void session.abort().catch(() => {
+      // Abort is reported through the signal, not this rejection.
+    })
+  }
+  call?.signal?.addEventListener('abort', abort, { once: true })
+  try {
+    await session.prompt(goal)
+    if (call?.signal?.aborted) throw new ProviderError('cancelled', 'cancelled')
+    const text = assistantText(session.messages)
+    if (text.length === 0) throw new ProviderError('empty-completion', 'agent returned an empty completion')
+    observe(call, { type: 'done', text })
+    return text
+  } catch (error) {
+    if (error instanceof ProviderError) throw error
+    if (call?.signal?.aborted) throw new ProviderError('cancelled', 'cancelled', { cause: error })
+    throw new ProviderError('provider-unhealthy', 'pi agent failed', { cause: error })
+  } finally {
+    call?.signal?.removeEventListener('abort', abort)
+    unsubscribe()
+    session.dispose()
+  }
+}
+
+function unhealthy(error: unknown): never {
+  throw new ProviderError('provider-unhealthy', 'pi agent failed', { cause: error })
+}
+
+export function selectedModel(
+  runtime: Pick<ModelRuntime, 'getModel'>,
+  config: RuntimeProviderConfig,
+  call: { readonly provider?: string; readonly model?: string } | undefined,
+): ReturnType<ModelRuntime['getModel']> {
+  const provider = call?.provider ?? config.provider
+  const model = call?.model ?? config.model
+  if (provider === undefined && model === undefined) return undefined
+  if (provider === undefined || model === undefined) {
+    throw new ProviderError('unknown-model', 'pi model selection is incomplete')
+  }
+  const found = runtime.getModel(provider, model)
+  if (found === undefined) throw new ProviderError('unknown-model', `unknown model: ${provider}/${model}`)
+  return found
+}
+
+export function piDefaultModel(
+  runtime: Pick<ModelRuntime, 'getModel'>,
+  settings: { getDefaultProvider(): string | undefined; getDefaultModel(): string | undefined },
+): ReturnType<ModelRuntime['getModel']> {
+  const provider = settings.getDefaultProvider()
+  const model = settings.getDefaultModel()
+  if (provider === undefined || model === undefined) return undefined
+  const found = runtime.getModel(provider, model)
+  if (found === undefined) throw new ProviderError('unknown-model', `unknown model: ${provider}/${model}`)
+  return found
+}
+
+function assistantText(messages: readonly { readonly role: string; readonly content?: unknown }[]): string {
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    const message = messages[index]
+    if (message === undefined || message.role !== 'assistant' || !Array.isArray(message.content)) continue
+    const text = message.content.flatMap((part) => {
+      if (typeof part !== 'object' || part === null) return []
+      const record = part as { type?: unknown; text?: unknown }
+      return record.type === 'text' && typeof record.text === 'string' ? [record.text] : []
+    }).join('').trim()
+    if (text.length > 0) return text
+  }
+  return ''
+}
+
+function observe(options: RuntimeAgentOptions | undefined, event: Parameters<NonNullable<RuntimeAgentOptions['onEvent']>>[0]): void {
+  try {
+    options?.onEvent?.(event)
+  } catch {
+    // A throwing observer does not abort the run.
+  }
+}

package/src/completion-reasoning.ts

@@ -0,0 +1,16 @@
+import type { Api, Model, ThinkingLevel } from '@earendil-works/pi-ai'
+
+/**
+ * Thinking level for one completion.
+ * Loads `pi-ai` only when a completion runs (optional peer).
+ * `clampThinkingLevel(model, 'off')` is Pi's off for this model.
+ * `off` is omitted: Pi sends `thinkingLevelMap.off` when that token exists, otherwise the call keeps the server default.
+ * @param model - the resolved catalog model
+ */
+export async function completionReasoning(model: Model<Api>): Promise<ThinkingLevel | undefined> {
+  if (!model.reasoning) return undefined
+  const { clampThinkingLevel } = await import('@earendil-works/pi-ai')
+  const level = clampThinkingLevel(model, 'off')
+  if (level === 'off') return undefined
+  return level
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+/** Pi catalog brain. @module @mohou/runtime-pi */
+
+export { createPiProvider, probePiRuntime } from './pi.ts'
+export { createPiLoad, ensurePiLoaded, installRoot, linkPiPeers, peerRoots, piPackage, registerPiRuntime } from './register.ts'

package/src/pi.ts

@@ -0,0 +1,156 @@
+import type { AppLlmEvent } from '@mohou/contract'
+import type { RuntimeLlmOptions } from '@mohou/runtime-provider'
+import { ProviderError, type ModelListing, type RuntimeProvider, type RuntimeProviderConfig } from '@mohou/runtime-provider'
+
+import { piDefaultModel, runPiAgent, selectedModel } from './agent-session.ts'
+import { completionReasoning } from './completion-reasoning.ts'
+
+/**
+ * True when Node can resolve the optional Pi packages (peer / environment).
+ * Does not scan install paths — ordinary package resolution only.
+ */
+export async function probePiRuntime(): Promise<boolean> {
+  try {
+    await import('@earendil-works/pi-coding-agent')
+    await import('@earendil-works/pi-ai')
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Pi catalog brain. Pi owns the catalog path and the provider API.
+ * `llm` calls `ModelRuntime.completeSimple`. `models` calls `getModels`.
+ * Requires optional peers `@earendil-works/pi-coding-agent` and `pi-ai` at call time.
+ */
+export function createPiProvider(): RuntimeProvider {
+  let running = false
+  let config: RuntimeProviderConfig = {}
+  return {
+    id: 'pi',
+    label: 'Pi',
+    configure(next) {
+      config = next
+    },
+    start() {
+      running = true
+      return Promise.resolve()
+    },
+    stop() {
+      running = false
+      return Promise.resolve()
+    },
+    healthy() {
+      return running
+    },
+    async models() {
+      const runtime = await openRuntime().catch(() => undefined)
+      return runtime === undefined ? [] : listings(runtime.getModels())
+    },
+    async llm(prompt, call) {
+      return complete(config, running, prompt, call)
+    },
+    async agent(goal, call) {
+      const failed = notRunning(running, call?.signal)
+      if (failed) return failed
+      if (goal.length === 0) throw new ProviderError('empty-completion', 'agent returned an empty completion')
+      return runPiAgent(config, goal, call)
+    },
+  }
+}
+
+async function openRuntime() {
+  const { ModelRuntime } = await import('@earendil-works/pi-coding-agent')
+  return ModelRuntime.create({ refreshOnCreate: false })
+}
+
+async function complete(
+  config: RuntimeProviderConfig,
+  running: boolean,
+  prompt: string,
+  call: RuntimeLlmOptions | undefined,
+): Promise<string> {
+  const failed = notRunning(running, call?.signal)
+  if (failed) return failed
+  if (prompt.length === 0) {
+    throw new ProviderError('empty-completion', 'llm returned an empty completion')
+  }
+  const { SettingsManager, getAgentDir } = await import('@earendil-works/pi-coding-agent')
+  const runtime = await openRuntime().catch((error: unknown) => {
+    throw new ProviderError('provider-unhealthy', 'pi completion failed', { cause: error })
+  })
+  const model = selectedModel(runtime, config, call) ?? piDefaultModel(runtime, SettingsManager.create(process.cwd(), getAgentDir()))
+  if (model === undefined) throw new ProviderError('unknown-model', 'pi model selection is incomplete')
+  const reasoning = await completionReasoning(model)
+  const context = {
+    messages: [{ role: 'user' as const, content: prompt, timestamp: Date.now() }],
+    ...call?.system === undefined ? {} : { systemPrompt: call.system },
+  }
+  const request = {
+    ...reasoning === undefined ? {} : { reasoning },
+    ...call?.maxTokens === undefined ? {} : { maxTokens: call.maxTokens },
+    ...call?.signal === undefined ? {} : { signal: call.signal },
+  }
+  const message = await (call?.stream === true
+    ? readStream(runtime.streamSimple(model, context, request), call)
+    : runtime.completeSimple(model, context, request)
+  ).catch((error: unknown) => {
+    if (call?.signal?.aborted) throw new ProviderError('cancelled', 'cancelled', { cause: error })
+    throw new ProviderError('provider-unhealthy', 'pi completion failed', { cause: error })
+  })
+  if (call?.signal?.aborted || message.stopReason === 'aborted') throw new ProviderError('cancelled', 'cancelled')
+  if (message.stopReason === 'error') throw new ProviderError('provider-unhealthy', 'pi completion failed')
+  const text = messageText(message.content)
+  if (text.length === 0) throw new ProviderError('empty-completion', 'llm returned an empty completion')
+  return text
+}
+
+async function readStream(
+  stream: AsyncIterable<{ type: string; delta?: string }> & { result: () => Promise<{ stopReason: string; content: unknown }> },
+  call: RuntimeLlmOptions,
+): Promise<{ stopReason: string; content: unknown }> {
+  observeLlm(call, { type: 'status', status: 'running' })
+  for await (const event of stream) {
+    if (event.type === 'text_delta' && typeof event.delta === 'string' && event.delta.length > 0) {
+      observeLlm(call, { type: 'text-delta', text: event.delta })
+    }
+  }
+  const message = await stream.result()
+  const text = messageText(message.content)
+  if (text.length > 0) observeLlm(call, { type: 'done', text })
+  return message
+}
+
+function observeLlm(call: RuntimeLlmOptions, event: AppLlmEvent): void {
+  try {
+    call.onEvent?.(event)
+  } catch {
+    // A throwing observer does not abort the completion.
+  }
+}
+
+function listings(models: readonly { readonly provider: string; readonly id: string }[]): ModelListing[] {
+  const groups = new Map<string, string[]>()
+  for (const model of models) {
+    const list = groups.get(model.provider)
+    if (list === undefined) groups.set(model.provider, [model.id])
+    else list.push(model.id)
+  }
+  return [...groups].map(([provider, names]) => ({ provider, models: names }))
+}
+
+function messageText(content: unknown): string {
+  if (!Array.isArray(content)) return ''
+  return content.flatMap((part) => {
+    if (typeof part !== 'object' || part === null) return []
+    const record = part as { type?: unknown; text?: unknown }
+    return record.type === 'text' && typeof record.text === 'string' ? [record.text] : []
+  }).join('').trim()
+}
+
+function notRunning(running: boolean, signal: AbortSignal | undefined): Promise<never> | undefined {
+  if (signal?.aborted) return Promise.reject(new ProviderError('cancelled', 'cancelled'))
+  if (!running) return Promise.reject(new ProviderError('provider-unhealthy', 'runtime provider is not started'))
+  return undefined
+}

package/src/register.ts

@@ -0,0 +1,207 @@
+import { execFile } from 'node:child_process'
+import { existsSync, lstatSync, mkdirSync, rmSync, symlinkSync } from 'node:fs'
+import { homedir } from 'node:os'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { ProviderError, type ProviderRegistry, type RuntimeProvider } from '@mohou/runtime-provider'
+
+import { createPiProvider } from './pi.ts'
+
+const peers = ['@earendil-works/pi-coding-agent', '@earendil-works/pi-ai'] as const
+
+/**
+ * The three things one load does, injectable so a test can watch their order and the retry.
+ * `present` answers from the filesystem on purpose: see {@link createPiLoad}.
+ */
+export interface PiLoadSteps {
+  present(): boolean
+  link(): void | Promise<void>
+  load(): Promise<void>
+}
+
+export interface PiLoad {
+  /** One attempt, shared with any concurrent caller. A failure is not remembered. */
+  ensure(): Promise<boolean>
+  /** Whether the last finished attempt loaded both peers. */
+  loaded(): boolean
+  /** Why the last finished attempt failed, for the message a caller shows. */
+  failure(): string | undefined
+}
+
+/**
+ * One loader for the Pi peers.
+ *
+ * The first step is a filesystem question, never a module-loader one. Node remembers a failed
+ * resolution for the rest of the process, so asking the loader whether `@earendil-works/…` resolves
+ * and only then creating the link poisons every later attempt in that process: the host would repair
+ * its own prefix and still report Pi as unavailable until the next restart. Repair first, then the
+ * one loader call an attempt makes.
+ * @param steps - presence check, repair, and the load itself
+ */
+export function createPiLoad(steps: PiLoadSteps): PiLoad {
+  let loading: Promise<boolean> | undefined
+  let loaded = false
+  let failure: string | undefined
+
+  async function attempt(): Promise<boolean> {
+    try {
+      // The repair is inside the guard too: a prefix the user cannot write must leave the id
+      // registered and unhealthy, not reject the promise every caller awaits.
+      if (!steps.present()) await steps.link()
+      await steps.load()
+      failure = undefined
+      return true
+    } catch (error) {
+      failure = error instanceof Error && error.message.length > 0 ? error.message : 'the peers did not load'
+      return false
+    }
+  }
+
+  return {
+    ensure() {
+      loading ??= attempt().then((ok) => {
+        loaded = ok
+        // A failed attempt is forgotten, so the next caller retries instead of inheriting it.
+        if (!ok) loading = undefined
+        return ok
+      })
+      return loading
+    },
+    loaded: () => loaded,
+    failure: () => failure,
+  }
+}
+
+/** The real steps: the prefix's own `node_modules`, this machine's Pi installs, and the two imports. */
+function realSteps(): PiLoadSteps {
+  const prefix = installRoot()
+  const roots = () => peerRoots(process.execPath, homedir(), process.env)
+  return {
+    present: () => peersPresent(prefix),
+    async link() {
+      linkPiPeers(prefix, roots())
+      if (peersPresent(prefix)) return
+      const global = await npmRootGlobal(process.env)
+      if (global !== undefined) linkPiPeers(prefix, [global])
+    },
+    async load() {
+      await import('@earendil-works/pi-coding-agent')
+      await import('@earendil-works/pi-ai')
+    },
+  }
+}
+
+const piLoad = createPiLoad(realSteps())
+
+/**
+ * Register Pi and return immediately. Linking and loading run after this call.
+ * A failed load leaves the id registered and unhealthy. It does not fail boot, and a later
+ * caller retries it.
+ */
+export function registerPiRuntime(registry: ProviderRegistry): RuntimeProvider {
+  void piLoad.ensure()
+  const inner = createPiProvider()
+  const provider: RuntimeProvider = {
+    id: inner.id,
+    ...inner.label === undefined ? {} : { label: inner.label },
+    configure: (config) => { inner.configure?.(config) },
+    start: () => inner.start(),
+    stop: () => inner.stop(),
+    healthy: () => inner.healthy() && piLoad.loaded(),
+    models: () => inner.models?.() ?? Promise.resolve([]),
+    async llm(prompt, options) {
+      if (!await piLoad.ensure()) throw new ProviderError('provider-unhealthy', unavailable(piLoad.failure()))
+      return inner.llm(prompt, options)
+    },
+    async agent(goal, options) {
+      if (!await piLoad.ensure()) throw new ProviderError('provider-unhealthy', unavailable(piLoad.failure()))
+      return inner.agent(goal, options)
+    },
+  }
+  registry.register(provider)
+  return provider
+}
+
+export function ensurePiLoaded(): Promise<boolean> {
+  return piLoad.ensure()
+}
+
+function unavailable(reason: string | undefined): string {
+  return reason === undefined ? 'pi is not available' : `pi is not available: ${reason}`
+}
+
+/**
+ * Whether both peers are reachable through the prefix's `node_modules`. Filesystem only: this runs
+ * before the repair, and a loader probe here is what {@link createPiLoad} exists to avoid.
+ */
+function peersPresent(prefix: string): boolean {
+  return peers.every(peer => existsSync(path.join(prefix, 'node_modules', ...peer.split('/'))))
+}
+
+/** Prefix that contains this package's `node_modules`. */
+export function installRoot(): string {
+  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../..')
+}
+
+export function peerRoots(node: string, home: string, env: NodeJS.ProcessEnv): string[] {
+  const nodeDir = path.dirname(node)
+  const prefix = path.dirname(nodeDir)
+  const roots = [
+    path.join(prefix, 'lib', 'node_modules'),
+    path.join(nodeDir, 'node_modules'),
+    path.join(nodeDir, 'lib', 'node_modules'),
+    path.join(home, 'AppData', 'Roaming', 'npm', 'node_modules'),
+  ]
+  if (typeof env.APPDATA === 'string' && env.APPDATA.length > 0) {
+    const appData = path.join(env.APPDATA, 'npm', 'node_modules')
+    if (!roots.includes(appData)) roots.push(appData)
+  }
+  return roots
+}
+
+export function piPackage(root: string, pkg: string): string | undefined {
+  const direct = path.join(root, '@earendil-works', pkg)
+  if (existsSync(direct)) return direct
+  const nested = path.join(root, '@earendil-works', 'pi-coding-agent', 'node_modules', '@earendil-works', pkg)
+  return existsSync(nested) ? nested : undefined
+}
+
+/** Link both peers into `prefix/node_modules`. A missing package is not an error. */
+export function linkPiPeers(prefix: string, roots: readonly string[]): boolean {
+  const destRoot = path.join(prefix, 'node_modules', '@earendil-works')
+  mkdirSync(destRoot, { recursive: true })
+  let linked = false
+  for (const pkg of ['pi-coding-agent', 'pi-ai'] as const) {
+    const src = roots.map(root => piPackage(root, pkg)).find(item => item !== undefined)
+    if (src === undefined) continue
+    placeLink(path.join(destRoot, pkg), src)
+    linked = true
+  }
+  return linked
+}
+
+function npmRootGlobal(env: NodeJS.ProcessEnv): Promise<string | undefined> {
+  const npm = path.join(path.dirname(process.execPath), process.platform === 'win32' ? 'npm.cmd' : 'npm')
+  if (!existsSync(npm)) return Promise.resolve(undefined)
+  return new Promise((resolve) => {
+    execFile(npm, ['root', '-g'], { env, timeout: 5_000 }, (error, stdout) => {
+      if (error) {
+        resolve(undefined)
+        return
+      }
+      resolve(stdout.split(/\r?\n/).find(line => line.length > 0))
+    })
+  })
+}
+
+function placeLink(dest: string, src: string): void {
+  try {
+    const stat = lstatSync(dest)
+    if (!stat.isSymbolicLink()) return
+    rmSync(dest)
+  } catch {
+    // missing dest
+  }
+  symlinkSync(src, dest, process.platform === 'win32' ? 'junction' : 'dir')
+}