@mohou/runtime-provider 1.0.20

package/README.md

@@ -0,0 +1,10 @@
+---
+status: locked
+updated: 2026-10-01
+---
+
+# @mohou/runtime-provider
+
+Role: `provider`.
+
+The brain interface and `echo` live here. Pi is `@mohou/runtime-pi`. Host consumes this package. It does not embed a vendor. Product: [provider injection](../../../docs/product/runtime/provider.md).

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@mohou/runtime-provider",
+  "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"
+  }
+}

package/src/codes.ts

@@ -0,0 +1,31 @@
+/** Codes this provider package emits. Callers match `code`. */
+
+export const providerCodes = [
+  'provider-missing',
+  'provider-duplicate',
+  'provider-unhealthy',
+  'empty-completion',
+  'cancelled',
+  'unknown-model-provider',
+  'unknown-model',
+  'retry-exhausted',
+] as const
+
+/** A failure emitted by a runtime provider or its registry. */
+export type ProviderCode = (typeof providerCodes)[number]
+
+/** Failure a caller branches on. The message is for a person. */
+export class ProviderError extends Error {
+  readonly code: ProviderCode
+
+  /**
+   * @param code - one of {@link providerCodes}
+   * @param message - human text; not the match key
+   * @param options - optional `cause`
+   */
+  constructor(code: ProviderCode, message: string, options?: { cause?: unknown }) {
+    super(message, options)
+    this.name = 'ProviderError'
+    this.code = code
+  }
+}

package/src/echo.ts

@@ -0,0 +1,74 @@
+import { ProviderError } from './codes.ts'
+import type { RuntimeAgentOptions, RuntimeLlmOptions, RuntimeProvider } from './provider.ts'
+
+/**
+ * The always-registered brain. `llm` returns the prompt. `agent` returns the goal.
+ * The tool set stays empty. A model name does not change it.
+ */
+export function createEchoProvider(): RuntimeProvider {
+  let running = false
+  return {
+    id: 'echo',
+    label: 'Echo',
+    configure() {},
+    start() {
+      running = true
+      return Promise.resolve()
+    },
+    stop() {
+      running = false
+      return Promise.resolve()
+    },
+    healthy() {
+      return running
+    },
+    describe() {
+      return [{ name: 'model', kind: 'string' }]
+    },
+    llm(prompt, options) {
+      const failed = rejection(running, options?.signal)
+      if (failed) return failed
+      if (prompt.length === 0) {
+        return Promise.reject(new ProviderError('empty-completion', 'llm returned an empty completion'))
+      }
+      if (options?.stream === true) {
+        observeLlm(options, { type: 'status', status: 'running' })
+        observeLlm(options, { type: 'text-delta', text: prompt })
+        observeLlm(options, { type: 'done', text: prompt })
+      }
+      return Promise.resolve(prompt)
+    },
+    agent(goal, options) {
+      const failed = rejection(running, options?.signal)
+      if (failed) return failed
+      if (goal.length === 0) {
+        return Promise.reject(new ProviderError('empty-completion', 'agent returned an empty completion'))
+      }
+      observe(options, { type: 'status', status: 'running' })
+      observe(options, { type: 'done', text: goal })
+      return Promise.resolve(goal)
+    },
+  }
+}
+
+function rejection(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
+}
+
+function observeLlm(options: RuntimeLlmOptions, event: Parameters<NonNullable<RuntimeLlmOptions['onEvent']>>[0]): void {
+  try {
+    options.onEvent?.(event)
+  } catch {
+    // A throwing observer does not abort the completion.
+  }
+}
+
+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/index.ts

@@ -0,0 +1,9 @@
+/** Brain interface and the echo provider. @module @mohou/runtime-provider */
+
+export const packageId = '@mohou/runtime-provider' as const
+
+export { ProviderError, providerCodes, type ProviderCode } from './codes.ts'
+export type { ModelListing, RuntimeAgentOptions, RuntimeLlmOptions, RuntimeProvider, RuntimeProviderConfig, SettingsField } from './provider.ts'
+export { assertKnownModel, type ModelChoice } from './model-choice.ts'
+export { createProviderRegistry, type ProviderRegistry } from './registry.ts'
+export { createEchoProvider } from './echo.ts'

package/src/model-choice.ts

@@ -0,0 +1,39 @@
+import { ProviderError } from './codes.ts'
+import type { RuntimeProvider } from './provider.ts'
+
+/** The vendor and model on one call. Neither is the brain id. */
+export interface ModelChoice {
+  readonly provider?: string
+  readonly model?: string
+}
+
+/**
+ * Admit a call's vendor and model against the brain's catalog.
+ * A brain that does not implement `models` accepts any pair.
+ * This does not change the brain id or its tools.
+ * @param provider - the registered brain
+ * @param choice - call options, after host policy filled omissions
+ */
+export async function assertKnownModel(provider: RuntimeProvider, choice: ModelChoice): Promise<void> {
+  if (provider.models === undefined) return
+  const listings = await provider.models()
+  const vendor = choice.provider
+  const model = choice.model
+  if (vendor === undefined && model === undefined) return
+
+  if (vendor !== undefined) {
+    const listing = listings.find(item => item.provider === vendor)
+    if (listing === undefined) {
+      throw new ProviderError('unknown-model-provider', `unknown model provider: ${vendor}`)
+    }
+    if (model !== undefined && !listing.models.includes(model)) {
+      throw new ProviderError('unknown-model', `unknown model: ${vendor}/${model}`)
+    }
+    return
+  }
+
+  const owners = listings.filter(item => item.models.includes(model ?? ''))
+  if (owners.length !== 1) {
+    throw new ProviderError('unknown-model', `unknown model: ${model ?? ''}`)
+  }
+}

package/src/provider.ts

@@ -0,0 +1,49 @@
+import type { AppAgentEvent, AppAgentOptions, AppLlmEvent, AppLlmOptions } from '@mohou/contract'
+
+/** Provider-only listener. Authors read a stream. They do not pass this. */
+export type RuntimeLlmOptions = AppLlmOptions & {
+  onEvent?: (event: AppLlmEvent) => void
+}
+
+/** Provider-only listener. Authors read a stream. They do not pass this. */
+export type RuntimeAgentOptions = AppAgentOptions & {
+  onEvent?: (event: AppAgentEvent) => void
+}
+
+/** One settings field a panel can render. */
+export interface SettingsField {
+  readonly name: string
+  readonly kind: 'string' | 'secret' | 'select'
+  readonly options?: readonly string[]
+}
+
+/** Models one vendor inside a brain exposes. The brain id is not this field. */
+export interface ModelListing {
+  readonly provider: string
+  readonly models: readonly string[]
+}
+
+/** Config Shell injects. Numeric limits are not this package's policy. */
+export interface RuntimeProviderConfig {
+  readonly provider?: string
+  readonly model?: string
+  readonly options?: Record<string, string>
+}
+
+/**
+ * One brain. Host calls `configure`, then `start`, then `llm` and `agent`.
+ * Switching model does not change the tools that provider already runs. That set is not a method on this interface.
+ */
+export interface RuntimeProvider {
+  readonly id: string
+  readonly label?: string
+  configure?(config: RuntimeProviderConfig): void
+  start(): Promise<void>
+  stop(): Promise<void>
+  healthy(): boolean
+  /** Vendor groups. Absent means this brain does not reject a model name. Each call may fetch. */
+  models?(): Promise<readonly ModelListing[]>
+  llm(prompt: string, options?: RuntimeLlmOptions): Promise<string>
+  agent(goal: string, options?: RuntimeAgentOptions): Promise<string>
+  describe?(): readonly SettingsField[]
+}

package/src/registry.ts

@@ -0,0 +1,35 @@
+import { ProviderError } from './codes.ts'
+import type { RuntimeProvider } from './provider.ts'
+
+/** Registrations of brains Shell knows how to construct. */
+export interface ProviderRegistry {
+  register(provider: RuntimeProvider): () => void
+  get(id: string): RuntimeProvider
+  ids(): readonly string[]
+}
+
+/** A registry whose `register` returns the disposer. A second id throws. */
+export function createProviderRegistry(): ProviderRegistry {
+  const providers = new Map<string, RuntimeProvider>()
+  return {
+    register(provider) {
+      if (providers.has(provider.id)) {
+        throw new ProviderError('provider-duplicate', `already registered: ${provider.id}`)
+      }
+      providers.set(provider.id, provider)
+      return () => {
+        providers.delete(provider.id)
+      }
+    },
+    get(id) {
+      const found = providers.get(id)
+      if (found === undefined) {
+        throw new ProviderError('provider-missing', `no runtime provider: ${id}`)
+      }
+      return found
+    },
+    ids() {
+      return [...providers.keys()]
+    },
+  }
+}