@piecemaker-legal/piecemaker 1.0.0

package/server/modules/providers/services/mcp.service.ts

@@ -0,0 +1,109 @@
+import { providerRegistry } from '@/modules/providers/provider.registry.js';
+import type { LLMProvider, McpScope, ProviderMcpServer, UpsertProviderMcpServerInput } from '@/shared/types.js';
+import { AppError } from '@/shared/utils.js';
+
+
+export const providerMcpService = {
+  /**
+   * Lists MCP servers for one provider grouped by supported scopes.
+   */
+  async listProviderMcpServers(
+    providerName: string,
+    options?: { workspacePath?: string },
+  ): Promise<Record<McpScope, ProviderMcpServer[]>> {
+    const provider = providerRegistry.resolveProvider(providerName);
+    return provider.mcp.listServers(options);
+  },
+
+  /**
+   * Lists MCP servers for one provider scope.
+   */
+  async listProviderMcpServersForScope(
+    providerName: string,
+    scope: McpScope,
+    options?: { workspacePath?: string },
+  ): Promise<ProviderMcpServer[]> {
+    const provider = providerRegistry.resolveProvider(providerName);
+    return provider.mcp.listServersForScope(scope, options);
+  },
+
+  /**
+   * Adds or updates one provider MCP server.
+   */
+  async upsertProviderMcpServer(
+    providerName: string,
+    input: UpsertProviderMcpServerInput,
+  ): Promise<ProviderMcpServer> {
+    const provider = providerRegistry.resolveProvider(providerName);
+    return provider.mcp.upsertServer(input);
+  },
+
+  /**
+   * Removes one provider MCP server.
+   */
+  async removeProviderMcpServer(
+    providerName: string,
+    input: { name: string; scope?: McpScope; workspacePath?: string },
+  ): Promise<{ removed: boolean; provider: LLMProvider; name: string; scope: McpScope }> {
+    const provider = providerRegistry.resolveProvider(providerName);
+    return provider.mcp.removeServer(input);
+  },
+
+  /**
+   * Adds one HTTP/stdio MCP server to every provider.
+   */
+  async addMcpServerToAllProviders(
+    input: Omit<UpsertProviderMcpServerInput, 'scope'> & { scope?: Exclude<McpScope, 'local'> },
+  ): Promise<Array<{ provider: LLMProvider; created: boolean; error?: string }>> {
+    if (input.transport !== 'stdio' && input.transport !== 'http') {
+      throw new AppError('Global MCP add supports only "stdio" and "http".', {
+        code: 'INVALID_GLOBAL_MCP_TRANSPORT',
+        statusCode: 400,
+      });
+    }
+
+    const scope = input.scope ?? 'project';
+    const results: Array<{ provider: LLMProvider; created: boolean; error?: string }> = [];
+    const providers = providerRegistry.listProviders();
+    for (const provider of providers) {
+      try {
+        await provider.mcp.upsertServer({ ...input, scope });
+        results.push({ provider: provider.id, created: true });
+      } catch (error) {
+        results.push({
+          provider: provider.id,
+          created: false,
+          error: error instanceof Error ? error.message : 'Unknown error',
+        });
+      }
+    }
+
+    return results;
+  },
+
+  /**
+   * Removes one MCP server from every provider. Mirrors `addMcpServerToAllProviders`
+   * by iterating the live provider registry, so callers stay in sync with which
+   * providers exist instead of maintaining their own provider list.
+   */
+  async removeMcpServerFromAllProviders(
+    input: { name: string; scope?: McpScope; workspacePath?: string },
+  ): Promise<Array<{ provider: LLMProvider; removed: boolean; error?: string }>> {
+    const results: Array<{ provider: LLMProvider; removed: boolean; error?: string }> = [];
+    const providers = providerRegistry.listProviders();
+    for (const provider of providers) {
+      try {
+        const result = await provider.mcp.removeServer(input);
+        results.push({ provider: provider.id, removed: result.removed });
+      } catch (error) {
+        results.push({
+          provider: provider.id,
+          removed: false,
+          error: error instanceof Error ? error.message : 'Unknown error',
+        });
+      }
+    }
+
+    return results;
+  },
+};

package/server/modules/providers/services/provider-auth.service.ts

@@ -0,0 +1,26 @@
+import { providerRegistry } from '@/modules/providers/provider.registry.js';
+import type { LLMProvider, ProviderAuthStatus } from '@/shared/types.js';
+
+export const providerAuthService = {
+  /**
+   * Resolves a provider and returns its installation/authentication status.
+   */
+  async getProviderAuthStatus(providerName: string): Promise<ProviderAuthStatus> {
+    const provider = providerRegistry.resolveProvider(providerName);
+    return provider.auth.getStatus();
+  },
+
+  /**
+   * Returns whether a provider runtime appears installed.
+   * Falls back to true if status lookup itself fails so callers preserve the
+   * original runtime error instead of replacing it with a status-check failure.
+   */
+  async isProviderInstalled(providerName: LLMProvider): Promise<boolean> {
+    try {
+      const status = await this.getProviderAuthStatus(providerName);
+      return status.installed;
+    } catch {
+      return true;
+    }
+  },
+};

package/server/modules/providers/services/provider-capabilities.service.ts

@@ -0,0 +1,133 @@
+import type { LLMProvider } from '@/shared/types.js';
+
+/**
+ * Static, backend-owned description of what one provider integration supports.
+ *
+ * The frontend renders its composer UI (permission mode picker, image upload,
+ * abort button, ...) purely from this shape, which is what keeps the frontend
+ * free of per-provider conditionals. New provider features should be exposed
+ * here instead of branching on the provider id in React components.
+ */
+type ProviderCapabilities = {
+  provider: LLMProvider;
+  /** Permission modes the provider runtime understands, in cycle order. */
+  permissionModes: string[];
+  defaultPermissionMode: string;
+  /** Whether image attachments can be included in a chat.send. */
+  supportsImages: boolean;
+  /** Whether general file attachments can be included in a chat.send. */
+  supportsFiles: boolean;
+  /** Whether an in-flight run can be cancelled via chat.abort. */
+  supportsAbort: boolean;
+  /** Whether interactive tool permission prompts can reach the UI. */
+  supportsPermissionRequests: boolean;
+  /** Whether the token-usage endpoint has data for this provider. */
+  supportsTokenUsage: boolean;
+  /** Whether the provider runtime can accept model-level reasoning effort. */
+  supportsEffort: boolean;
+  /**
+   * Whether an already-sent message can be replaced, which requires the
+   * provider to re-run a conversation truncated at a chosen point.
+   */
+  supportsMessageEditing: boolean;
+  /**
+   * Whether a session's transcript can be branched into an independent one.
+   */
+  supportsSessionForking: boolean;
+};
+
+/**
+ * The capability matrix mirrors what each runtime actually implements today:
+ * - permission modes match the option sets accepted by each CLI/SDK.
+ * - only the Claude SDK integration surfaces interactive permission requests.
+ * - Cursor has no token usage endpoint support (its store.db has no usage rows).
+ */
+const PROVIDER_CAPABILITIES: Record<LLMProvider, ProviderCapabilities> = {
+  claude: {
+    provider: 'claude',
+    permissionModes: ['default', 'auto', 'acceptEdits', 'bypassPermissions', 'plan'],
+    defaultPermissionMode: 'default',
+    supportsImages: true,
+    supportsFiles: true,
+    supportsAbort: true,
+    supportsPermissionRequests: true,
+    supportsTokenUsage: true,
+    supportsEffort: true,
+    // `resumeSessionAt` re-runs a conversation truncated at a message, and
+    // `forkSession` copies a transcript prefix into a new session file.
+    supportsMessageEditing: true,
+    supportsSessionForking: true,
+  },
+  cursor: {
+    provider: 'cursor',
+    permissionModes: ['default', 'acceptEdits', 'bypassPermissions', 'plan'],
+    defaultPermissionMode: 'default',
+    supportsImages: true,
+    supportsFiles: true,
+    supportsAbort: true,
+    supportsPermissionRequests: false,
+    supportsTokenUsage: false,
+    supportsEffort: false,
+    supportsMessageEditing: false,
+    supportsSessionForking: false,
+  },
+  codex: {
+    provider: 'codex',
+    permissionModes: ['default', 'acceptEdits', 'bypassPermissions'],
+    defaultPermissionMode: 'default',
+    supportsImages: true,
+    supportsFiles: true,
+    supportsAbort: true,
+    supportsPermissionRequests: false,
+    supportsTokenUsage: true,
+    supportsEffort: true,
+    // Not from the Codex SDK, which only starts and resumes threads: both ride
+    // the same CLI's `app-server` protocol, whose `thread/fork` copies a
+    // thread up to a chosen turn. Editing is that fork plus a new prompt,
+    // which is how Codex's own IDE clients do it.
+    supportsMessageEditing: true,
+    supportsSessionForking: true,
+  },
+  opencode: {
+    provider: 'opencode',
+    // Mapped by the runtime onto OpenCode's controls: `--agent plan` (plan),
+    // `--auto` (bypassPermissions) and the OPENCODE_PERMISSION env var
+    // (acceptEdits). See resolveOpenCodePermissionOptions in the OpenCode runtime adapter.
+    permissionModes: ['default', 'acceptEdits', 'bypassPermissions', 'plan'],
+    defaultPermissionMode: 'default',
+    supportsImages: true,
+    supportsFiles: true,
+    supportsAbort: true,
+    supportsPermissionRequests: false,
+    supportsTokenUsage: true,
+    supportsEffort: true,
+    supportsMessageEditing: false,
+    supportsSessionForking: false,
+  },
+  mistral: {
+    provider: 'mistral',
+    permissionModes: ['default', 'acceptEdits', 'bypassPermissions'],
+    defaultPermissionMode: 'default',
+    supportsImages: true,
+    supportsFiles: true,
+    supportsAbort: true,
+    supportsPermissionRequests: false,
+    supportsTokenUsage: false,
+    supportsEffort: true,
+    supportsMessageEditing: false,
+    supportsSessionForking: false,
+  },
+};
+
+/**
+ * Application service exposing the provider capability matrix.
+ */
+export const providerCapabilitiesService = {
+  getProviderCapabilities(provider: LLMProvider): ProviderCapabilities {
+    return PROVIDER_CAPABILITIES[provider];
+  },
+
+  listAllProviderCapabilities(): ProviderCapabilities[] {
+    return Object.values(PROVIDER_CAPABILITIES);
+  },
+};

package/server/modules/providers/services/provider-models.service.ts

@@ -0,0 +1,401 @@
+import { providerModelsDb, sessionsDb } from '@/modules/database/index.js';
+import { providerRegistry } from '@/modules/providers/provider.registry.js';
+import type { IProvider } from '@/shared/interfaces.js';
+import type {
+  CustomProviderModelInput,
+  CustomProviderModelRecord,
+  LLMProvider,
+  ProviderCurrentActiveModel,
+  ProviderModelOption,
+  ProviderModelsDefinition,
+  ProviderSessionModel,
+} from '@/shared/types.js';
+import { AppError } from '@/shared/utils.js';
+
+/** Session-row access the service needs, narrowed so tests can stub it. */
+type ProviderModelsSessionStore = {
+  getSessionById(sessionId: string): { model: string | null; effort: string | null } | null;
+  setSessionModel(sessionId: string, model: string): void;
+  setSessionEffort(sessionId: string, effort: string): void;
+};
+
+/** SQLite catalog operations used by the Providers service and its unit fakes. */
+type ProviderModelsCatalogStore = Pick<
+  typeof providerModelsDb,
+  | 'listCustomProviderModels'
+  | 'getCustomProviderModel'
+  | 'findCustomProviderModelByModelId'
+  | 'createCustomProviderModel'
+  | 'updateCustomProviderModel'
+  | 'deleteCustomProviderModel'
+>;
+
+type ProviderModelsServiceDependencies = {
+  resolveProvider?: (provider: LLMProvider) => Pick<IProvider, 'models'>;
+  catalog?: ProviderModelsCatalogStore;
+  sessions?: ProviderModelsSessionStore;
+};
+
+const toCustomProviderModelOption = (
+  record: CustomProviderModelRecord,
+): ProviderModelOption => ({
+  value: record.modelId,
+  label: record.model,
+  recordId: record.recordId,
+  isCustom: true,
+});
+
+const mergeProviderModels = (
+  predefined: ProviderModelsDefinition,
+  custom: CustomProviderModelRecord[],
+): ProviderModelsDefinition => {
+  return {
+    OPTIONS: [
+      ...predefined.OPTIONS.map((option) => ({ ...option, isCustom: false })),
+      ...custom.map(toCustomProviderModelOption),
+    ],
+    DEFAULT: predefined.DEFAULT,
+  };
+};
+
+const normalizeCustomModelInput = (input: CustomProviderModelInput): CustomProviderModelInput => ({
+  id: input.id.trim(),
+  model: input.model.trim(),
+});
+
+const isUniqueConstraintError = (error: unknown): boolean => (
+  error !== null
+  && error !== undefined
+  && typeof error === 'object'
+  && 'code' in error
+  && String(error.code).startsWith('SQLITE_CONSTRAINT')
+);
+
+/**
+ * Creates the provider model application service used by Providers routes,
+ * Commands, and provider runtimes.
+ *
+ * Curated adapter definitions stay source-controlled and are merged at read
+ * time with custom SQLite rows. This deliberately has no predefined-model
+ * persistence, memory cache, disk cache, TTL, or provider-native discovery.
+ * Tests inject a small custom-model store through the same boundary.
+ */
+export const createProviderModelsService = (dependencies: ProviderModelsServiceDependencies = {}) => {
+  const resolveProvider = dependencies.resolveProvider ?? providerRegistry.resolveProvider;
+  const catalog = dependencies.catalog ?? providerModelsDb;
+  const sessions = dependencies.sessions ?? sessionsDb;
+
+  const getProviderModels = async (provider: LLMProvider): Promise<ProviderModelsDefinition> => {
+    const predefined = await resolveProvider(provider).models.getSupportedModels();
+    return mergeProviderModels(predefined, catalog.listCustomProviderModels(provider));
+  };
+
+  const getCurrentActiveModel = async (
+    provider: LLMProvider,
+    sessionId?: string,
+  ): Promise<ProviderCurrentActiveModel> => resolveProvider(provider).models.getCurrentActiveModel(sessionId);
+
+  const readCustomModel = (
+    provider: LLMProvider,
+    recordId: number,
+  ): CustomProviderModelRecord => {
+    const existing = catalog.getCustomProviderModel(provider, recordId);
+    if (!existing) {
+      throw new AppError('Model not found.', {
+        code: 'MODEL_NOT_FOUND',
+        statusCode: 404,
+      });
+    }
+
+    return existing;
+  };
+
+  const assertModelIdAvailable = (
+    provider: LLMProvider,
+    predefined: ProviderModelsDefinition,
+    modelId: string,
+    currentRecordId?: number,
+  ): void => {
+    if (predefined.OPTIONS.some((option) => option.value === modelId)) {
+      throw new AppError(`A ${provider} model with this ID already exists.`, {
+        code: 'MODEL_ID_ALREADY_EXISTS',
+        statusCode: 409,
+      });
+    }
+
+    const duplicate = catalog.findCustomProviderModelByModelId(provider, modelId);
+    if (duplicate && duplicate.recordId !== currentRecordId) {
+      throw new AppError(`A ${provider} model with this ID already exists.`, {
+        code: 'MODEL_ID_ALREADY_EXISTS',
+        statusCode: 409,
+      });
+    }
+  };
+
+  const createCustomModel = async (
+    provider: LLMProvider,
+    input: CustomProviderModelInput,
+  ): Promise<{ model: ProviderModelOption; models: ProviderModelsDefinition }> => {
+    const predefined = await resolveProvider(provider).models.getSupportedModels();
+    const normalized = normalizeCustomModelInput(input);
+    assertModelIdAvailable(provider, predefined, normalized.id);
+
+    try {
+      const created = catalog.createCustomProviderModel(provider, normalized);
+      return {
+        model: toCustomProviderModelOption(created),
+        models: mergeProviderModels(predefined, catalog.listCustomProviderModels(provider)),
+      };
+    } catch (error) {
+      if (isUniqueConstraintError(error)) {
+        throw new AppError(`A ${provider} model with this ID already exists.`, {
+          code: 'MODEL_ID_ALREADY_EXISTS',
+          statusCode: 409,
+        });
+      }
+      throw error;
+    }
+  };
+
+  const updateCustomModel = async (
+    provider: LLMProvider,
+    recordId: number,
+    input: CustomProviderModelInput,
+  ): Promise<{ model: ProviderModelOption; models: ProviderModelsDefinition }> => {
+    const predefined = await resolveProvider(provider).models.getSupportedModels();
+    readCustomModel(provider, recordId);
+    const normalized = normalizeCustomModelInput(input);
+    assertModelIdAvailable(provider, predefined, normalized.id, recordId);
+
+    try {
+      const updated = catalog.updateCustomProviderModel(provider, recordId, normalized);
+      if (!updated) {
+        throw new AppError('Model not found.', {
+          code: 'MODEL_NOT_FOUND',
+          statusCode: 404,
+        });
+      }
+
+      return {
+        model: toCustomProviderModelOption(updated),
+        models: mergeProviderModels(predefined, catalog.listCustomProviderModels(provider)),
+      };
+    } catch (error) {
+      if (isUniqueConstraintError(error)) {
+        throw new AppError(`A ${provider} model with this ID already exists.`, {
+          code: 'MODEL_ID_ALREADY_EXISTS',
+          statusCode: 409,
+        });
+      }
+      throw error;
+    }
+  };
+
+  const deleteCustomModel = async (
+    provider: LLMProvider,
+    recordId: number,
+  ): Promise<{ model: ProviderModelOption; models: ProviderModelsDefinition }> => {
+    const predefined = await resolveProvider(provider).models.getSupportedModels();
+    readCustomModel(provider, recordId);
+    const removed = catalog.deleteCustomProviderModel(provider, recordId, predefined.DEFAULT);
+    if (!removed) {
+      throw new AppError('Model not found.', {
+        code: 'MODEL_NOT_FOUND',
+        statusCode: 404,
+      });
+    }
+
+    return {
+      model: toCustomProviderModelOption(removed),
+      models: mergeProviderModels(predefined, catalog.listCustomProviderModels(provider)),
+    };
+  };
+
+  const readRecordedSessionSelection = (
+    sessionId: string,
+  ): { model: string | null; effort: string | null } | null => {
+    const session = sessions.getSessionById(sessionId);
+    if (!session) {
+      return null;
+    }
+
+    return {
+      model: session.model?.trim() || null,
+      effort: session.effort?.trim() || null,
+    };
+  };
+
+  /**
+   * Records the model one session runs with.
+   *
+   * Called from the active-model route when the user picks a model and from
+   * `chat.send` on every turn, so the row always matches what the session last
+   * ran with. Sessions the app has not created yet (no row) are ignored rather
+   * than treated as an error: the client keeps its own pending selection and
+   * the value lands on the row with the first send.
+   */
+  const setSessionModel = (
+    provider: LLMProvider,
+    sessionId: string,
+    model: string,
+  ): ProviderSessionModel | null => {
+    const normalizedSessionId = sessionId.trim();
+    const normalizedModel = model.trim();
+    if (!normalizedSessionId || !normalizedModel) {
+      return null;
+    }
+
+    const recordedSelection = readRecordedSessionSelection(normalizedSessionId);
+    if (!recordedSelection) {
+      return null;
+    }
+
+    sessions.setSessionModel(normalizedSessionId, normalizedModel);
+    return {
+      provider,
+      sessionId: normalizedSessionId,
+      model: normalizedModel,
+      effort: recordedSelection.effort,
+      source: 'session',
+    };
+  };
+
+  /**
+   * Records the reasoning effort one session runs with.
+   *
+   * Like `setSessionModel`, this ignores an id that has not been allocated by
+   * the session gateway yet. The websocket send path records it once the row
+   * exists, so a pre-session composer choice is not lost.
+   */
+  const setSessionEffort = (
+    provider: LLMProvider,
+    sessionId: string,
+    effort: string,
+  ): { provider: LLMProvider; sessionId: string; effort: string; source: 'session' } | null => {
+    const normalizedSessionId = sessionId.trim();
+    const normalizedEffort = effort.trim();
+    if (!normalizedSessionId || !normalizedEffort) {
+      return null;
+    }
+
+    if (!readRecordedSessionSelection(normalizedSessionId)) {
+      return null;
+    }
+
+    sessions.setSessionEffort(normalizedSessionId, normalizedEffort);
+    return {
+      provider,
+      sessionId: normalizedSessionId,
+      effort: normalizedEffort,
+      source: 'session',
+    };
+  };
+
+  /**
+   * Answers "which model is this session using?" for every display surface.
+   *
+   * Precedence, highest first:
+   *   1. the model recorded on the session row;
+   *   2. the provider's own session state for externally-created sessions;
+   *   3. `requestedModel`, the client's current default;
+   *   4. the source-controlled provider catalog default.
+   */
+  const resolveSessionModel = async (
+    provider: LLMProvider,
+    options: { sessionId?: string | null; requestedModel?: string | null } = {},
+  ): Promise<ProviderSessionModel> => {
+    const normalizedSessionId = typeof options.sessionId === 'string' ? options.sessionId.trim() : '';
+    const normalizedRequestedModel = typeof options.requestedModel === 'string'
+      ? options.requestedModel.trim()
+      : '';
+
+    if (normalizedSessionId) {
+      const recordedSelection = readRecordedSessionSelection(normalizedSessionId);
+      if (recordedSelection?.model) {
+        return {
+          provider,
+          sessionId: normalizedSessionId,
+          model: recordedSelection.model,
+          effort: recordedSelection.effort,
+          source: 'session',
+        };
+      }
+
+      const providerCatalog = await getProviderModels(provider);
+      const providerModel = await getCurrentActiveModel(provider, normalizedSessionId);
+      const resolvedProviderModel = providerModel.model?.trim();
+      if (resolvedProviderModel && resolvedProviderModel !== providerCatalog.DEFAULT) {
+        return {
+          provider,
+          sessionId: normalizedSessionId,
+          model: resolvedProviderModel,
+          effort: recordedSelection?.effort ?? null,
+          source: 'provider',
+        };
+      }
+
+      return {
+        provider,
+        sessionId: normalizedSessionId,
+        model: normalizedRequestedModel || providerCatalog.DEFAULT,
+        effort: recordedSelection?.effort ?? null,
+        source: normalizedRequestedModel ? 'session' : 'default',
+      };
+    }
+
+    if (normalizedRequestedModel) {
+      return {
+        provider,
+        sessionId: null,
+        model: normalizedRequestedModel,
+        effort: null,
+        source: 'session',
+      };
+    }
+
+    const providerCatalog = await getProviderModels(provider);
+    return {
+      provider,
+      sessionId: null,
+      model: providerCatalog.DEFAULT,
+      effort: null,
+      source: 'default',
+    };
+  };
+
+  /**
+   * Picks the model one resumed provider run should use.
+   *
+   * Provider-global state is deliberately ignored because it must never
+   * override the model explicitly selected in the composer.
+   */
+  const resolveResumeModel = async (
+    provider: LLMProvider,
+    sessionId: string | undefined,
+    requestedModel?: string | null,
+  ): Promise<string | undefined> => {
+    void provider;
+    const normalizedRequestedModel = typeof requestedModel === 'string' ? requestedModel.trim() : '';
+    const normalizedSessionId = sessionId?.trim();
+    if (!normalizedSessionId) {
+      return normalizedRequestedModel || undefined;
+    }
+
+    const recordedModel = readRecordedSessionSelection(normalizedSessionId)?.model;
+    return recordedModel || normalizedRequestedModel || undefined;
+  };
+
+  return {
+    getProviderModels,
+    createCustomModel,
+    updateCustomModel,
+    deleteCustomModel,
+    setSessionModel,
+    setSessionEffort,
+    resolveSessionModel,
+    resolveResumeModel,
+  };
+};
+
+/** Shared Providers service used by routes, Commands, and provider runtimes. */
+export const providerModelsService = createProviderModelsService();