Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

6.8 KB
Raw Blame
/**
 * In-tree AI toolkit (formerly the `portos-ai-toolkit` npm package).
 * Provides configurable AI provider, runner, and prompt services with
 * matching Express routes. See server/index.js for the wiring.
 */

import { fileURLToPath } from 'url';
import { dirname, join } from 'path';
import {
  canRefreshModels,
  createProviderService,
  isOllamaBackedProvider,
  ollamaRefreshGroupKey,
} from './providers.js';
import { createRunnerService } from './runner.js';
import { createPromptsService } from './prompts.js';
import { contextWindowRejection, createProviderStatusService, knownContextWindow } from './providerStatus.js';
import { createProvidersRoutes } from './routes/providers.js';
import { createRunsRoutes } from './routes/runs.js';
import { createPromptsRoutes } from './routes/prompts.js';
import { createProviderStatusRoutes } from './routes/providerStatus.js';
import { defaultAsyncHandler } from './internal/httpError.js';
import * as errorDetection from './errorDetection.js';

const __dirname = dirname(fileURLToPath(import.meta.url));

export const DEFAULT_PROVIDERS_SAMPLE = join(__dirname, 'defaults/providers.sample.json');

export * from './validation.js';
export * from './errorDetection.js';
export * from './endpointGuard.js';
export * from './constants.js';
export { createProviderService, createRunnerService, createPromptsService, createProviderStatusService };
// The context-fit rule, for the host's pre-dispatch gate on the EXPLICITLY
// requested provider — the one candidate `getFallbackProvider` never sees.
export { contextWindowRejection, knownContextWindow };
export { isOllamaBackedProvider, canRefreshModels, ollamaRefreshGroupKey };
export { createProvidersRoutes, createRunsRoutes, createPromptsRoutes, createProviderStatusRoutes };

export function createAIToolkit(config = {}) {
  const {
    dataDir = './data',
    providersFile = 'providers.json',
    statusFile = 'provider-status.json',
    runsDir = 'runs',
    promptsDir = 'prompts',
    screenshotsDir = './data/screenshots',
    sampleProvidersFile = null,
    io = null,
    // Standalone, fall back to the toolkit's own JSON-serializing handler so
    // thrown errors still produce the canonical envelope (not Express 5's HTML
    // error page). PortOS injects its own asyncHandler (→ errorMiddleware).
    asyncHandler = defaultAsyncHandler,
    withRunAdmission = handler => handler,
    withAssetPublication = work => work(),
    // Host-injected HTTP error class (PortOS passes its `ServerError` so route
    // errors normalize into `{ error, code, timestamp, context? }`). Threaded
    // to every router; routes default to the toolkit's own ToolkitHttpError
    // when this is unset (standalone use).
    ServerError,
    hooks = {},
    maxConcurrentRuns = 5,
    enableProviderStatus = true,
    defaultFallbackPriority = ['claude-code', 'codex', 'lmstudio', 'ollama', 'antigravity-cli', 'gemini-cli'],
    // Host gate for "can this provider run at all?" — see providerStatus.js.
    // Unset standalone, so the toolkit routes on enabled + availability alone.
    prerequisitesMet = null,
    // Host ordered fallback list — see providerStatus.js. Unset standalone.
    getFallbackChain = null,
    // Host persistence hook fired after every providers.json write — see
    // createProviderService(). PortOS keeps its provider connection graph
    // reconciled through it; unset standalone.
    onProvidersSaved = null,
    // Host probe for the checkpoints a one-model-per-process local runtime has
    // cached but is not serving — see createProviderService(). Unset
    // standalone, so a refresh reports only what the endpoint answers with.
    cachedModelIds = null,
    // Host resolver for composite provider ids — see createProviderService().
    resolveCompositeProvider = null
  } = config;

  const providerService = createProviderService({
    dataDir,
    providersFile,
    sampleFile: sampleProvidersFile,
    onProvidersSaved,
    cachedModelIds,
    resolveCompositeProvider
  });

  let providerStatusService = null;
  if (enableProviderStatus) {
    providerStatusService = createProviderStatusService({
      dataDir,
      statusFile,
      defaultFallbackPriority,
      prerequisitesMet,
      getFallbackChain,
      onStatusChange: (eventData) => {
        io?.emit('provider:status:changed', eventData);
      }
    });

    providerStatusService.init().catch(err => {
      console.error(`❌ Failed to initialize provider status: ${err.message}`);
    });
  }

  const runnerService = createRunnerService({
    withAssetPublication,
    dataDir,
    runsDir,
    screenshotsDir,
    providerService,
    providerStatusService,
    hooks: {
      ...hooks,
      onProviderError: (providerId, errorAnalysis, output) => {
        io?.emit('provider:error', { providerId, errorAnalysis });
        hooks.onProviderError?.(providerId, errorAnalysis, output);
      }
    },
    maxConcurrentRuns
  });

  const promptsService = createPromptsService({
    dataDir,
    promptsDir
  });

  promptsService.init().catch(err => {
    console.error(`❌ Failed to initialize prompts: ${err.message}`);
  });

  // `ServerError: undefined` lets the router's own default (ToolkitHttpError)
  // apply — destructuring defaults fire for undefined values.
  const providersRouter = createProvidersRoutes(providerService, { asyncHandler, ServerError });
  const runsRouter = createRunsRoutes(runnerService, { asyncHandler, io, ServerError, withRunAdmission });
  const promptsRouter = createPromptsRoutes(promptsService, { asyncHandler, ServerError });

  let providerStatusRouter = null;
  if (providerStatusService) {
    providerStatusRouter = createProviderStatusRoutes(providerStatusService, { asyncHandler, ServerError });
  }

  return {
    services: {
      providers: providerService,
      runner: runnerService,
      prompts: promptsService,
      providerStatus: providerStatusService,
      // Expose error detection so the PortOS runner override (and any
      // direct toolkit consumer) can call `services.errorDetection.analyzeError`
      // without separately importing the module. Without this, CLI runs that
      // exit non-zero silently skip error analysis and leave metadata.error
      // null.
      errorDetection
    },

    routes: {
      providers: providersRouter,
      runs: runsRouter,
      prompts: promptsRouter,
      providerStatus: providerStatusRouter
    },

    mountRoutes(app, basePath = '/api') {
      // Mount the more specific /providers/status BEFORE /providers so that
      // the providers router's GET /:id doesn't intercept "status" as an id.
      if (providerStatusRouter) {
        app.use(`${basePath}/providers/status`, providerStatusRouter);
      }
      app.use(`${basePath}/providers`, providersRouter);
      app.use(`${basePath}/runs`, runsRouter);
      app.use(`${basePath}/prompts`, promptsRouter);
    }
  };
}