@studio-foundation/api 0.3.0-beta.1

package/src/integrations/types.ts

@@ -0,0 +1,37 @@
+// api/src/integrations/types.ts
+import type { FastifyReply } from 'fastify';
+import type { IntegrationPluginDef } from '@studio-foundation/contracts';
+import type { GroupFeedbackEvent } from '@studio-foundation/engine';
+import type { IntegrationStore } from '../integration-store.js';
+import type { RunLauncher } from '../launcher.js';
+import type { ApiConfig } from '../server.js';
+
+export interface WebhookHandlerContext {
+  rawBody: Buffer;
+  headers: Record<string, string | string[] | undefined>;
+  integration: IntegrationPluginDef;
+  store: IntegrationStore;
+  launcher: RunLauncher;
+  configsDir: string;
+  projectsDir?: string;
+  apiConfig: ApiConfig;
+  integrationConfig: Record<string, unknown>;
+}
+
+export interface FailureHandlerContext {
+  runId: string;
+  durationMs: number;
+  status: string;
+  meta: Record<string, unknown>;
+  lastGroupFeedback?: GroupFeedbackEvent;
+  integration: IntegrationPluginDef;
+  integrationConfig: Record<string, unknown>;
+}
+
+export interface WebhookHandler {
+  handle(ctx: WebhookHandlerContext, reply: FastifyReply): Promise<unknown>;
+}
+
+export interface FailureHandler {
+  handleFailure(ctx: FailureHandlerContext): Promise<void>;
+}

package/src/launcher.ts

@@ -0,0 +1,214 @@
+// Run launcher — interface + InProcessLauncher implementation
+// InProcessLauncher creates a new PipelineEngine per run for event isolation.
+// Future: BullMQLauncher, etc.
+
+import type { PipelineRun } from '@studio-foundation/contracts';
+import type {
+  EngineConfig,
+  EngineEvents,
+  AnyRunStore,
+  PipelineStartEvent,
+  StageStartEvent,
+  StageCompleteEvent,
+  StageRetryEvent,
+  StageContextEvent,
+  GroupStartEvent,
+  GroupIterationEvent,
+  GroupFeedbackEvent,
+  GroupCompleteEvent,
+  PipelineCompleteEvent,
+  PipelineCancelledEvent,
+  StagedToolCallStartEvent,
+  StagedToolCallCompleteEvent,
+} from '@studio-foundation/engine';
+import { PipelineEngine } from '@studio-foundation/engine';
+import { loadProjectTools } from '@studio-foundation/runner';
+import { join } from 'node:path';
+import { createApiLogger } from './logger.js';
+import type { RunEventBus, BusListener, SseEventType } from './event-bus.js';
+import type { AnyUserStore } from './user-store-pg.js';
+import { getPlanLimits, DEFAULT_PLANS, type PlansConfig } from './plans.js';
+
+export interface LaunchConfig {
+  runId: string;
+  pipeline: string;
+  input: Record<string, unknown>;
+  configsDir: string;
+  /** Pre-resolved repo path (cloned or local). Overrides engineConfig.repoPath for this run. */
+  repoPath?: string;
+  providerOverride?: string;
+  depth?: number;
+  parentRunId?: string;
+  meta?: Record<string, unknown>;
+  userId?: string;
+}
+
+export type EngineFactory = (
+  config: EngineConfig,
+  events: EngineEvents,
+) => Pick<PipelineEngine, 'run'>;
+
+export interface RunLauncher {
+  launch(config: LaunchConfig): Promise<{ run_id: string }>;
+  cancel(run_id: string): Promise<void>;
+  subscribe(runId: string, listener: BusListener): () => void;
+}
+
+export class InProcessLauncher implements RunLauncher {
+  private active = new Map<string, AbortController>();
+  private activePerUser = new Map<string, Set<string>>(); // userId → Set<runId>
+
+  constructor(
+    private engineConfig: EngineConfig,
+    private store: AnyRunStore,
+    private runsDir: string,
+    private bus: RunEventBus,
+    private engineFactory: EngineFactory = (cfg, evts) => new PipelineEngine(cfg, evts),
+    private userStore?: AnyUserStore,
+    private plans: PlansConfig = DEFAULT_PLANS,
+  ) {}
+
+  subscribe(runId: string, listener: BusListener): () => void {
+    return this.bus.subscribe(runId, listener);
+  }
+
+  async launch(config: LaunchConfig): Promise<{ run_id: string }> {
+    const { runId, pipeline, input, meta, parentRunId, userId } = config;
+
+    // Quota enforcement (only if userId provided and userStore available)
+    if (userId && this.userStore) {
+      const user = await this.userStore.getUserById(userId);
+      if (user) {
+        const today = new Date().toISOString().slice(0, 10);
+        const limits = getPlanLimits(this.plans, user.plan);
+
+        // Check runs_per_day
+        if (limits.runs_per_day !== -1) {
+          const usage = await this.userStore.getDailyUsage(userId, today);
+          if (usage.runs_count >= limits.runs_per_day) {
+            throw Object.assign(
+              new Error('Daily run limit exceeded'),
+              { code: 'QUOTA_EXCEEDED', limit: limits.runs_per_day, used: usage.runs_count }
+            );
+          }
+        }
+
+        // Check max_concurrent
+        const activeForUser = this.activePerUser.get(userId)?.size ?? 0;
+        if (activeForUser >= limits.max_concurrent) {
+          throw Object.assign(
+            new Error('Concurrent run limit exceeded'),
+            { code: 'QUOTA_EXCEEDED', limit: limits.max_concurrent, used: activeForUser }
+          );
+        }
+
+        // Increment runs_count
+        await this.userStore.incrementRuns(userId, today);
+      }
+    }
+
+    // Track active run for user (before creating the controller)
+    if (userId) {
+      if (!this.activePerUser.has(userId)) this.activePerUser.set(userId, new Set());
+      this.activePerUser.get(userId)!.add(runId);
+    }
+
+    const controller = new AbortController();
+    this.active.set(runId, controller);
+
+    const logger = createApiLogger(this.runsDir, runId, pipeline);
+
+    // Pre-create the run in the store so GET /api/runs/:id/stream can find it immediately
+    // after launch() returns. The engine will upsert it again at onPipelineStart with the
+    // same id (savePipelineRun is ON CONFLICT DO UPDATE in all store implementations).
+    const stubRun: PipelineRun = {
+      id: runId,
+      pipeline_name: pipeline,
+      status: 'running',
+      started_at: new Date().toISOString(),
+      stages: [],
+      ...(input && typeof input === 'object' ? { input: input as Record<string, unknown> } : {}),
+      ...(parentRunId ? { parent_run_id: parentRunId } : {}),
+    };
+    await this.store.savePipelineRun(stubRun);
+
+    // Save log path immediately so callers can locate the log file right after launch().
+    // For InMemoryRunStore this is a simple Map.set() and works regardless of row existence.
+    // For SQLiteRunStore/PgRunStore the row now exists, so the UPDATE will take effect.
+    void this.store.saveLogPath(runId, logger.logPath);
+
+    const emit = (type: SseEventType, data: object) => {
+      this.bus.emit(runId, type, data);
+      logger.log({ event: type, ...(data as Record<string, unknown>) });
+    };
+
+    // Track last group feedback for inclusion in the pipeline_complete bus event
+    let lastGroupFeedback: GroupFeedbackEvent | undefined;
+
+    const perRunEvents: EngineEvents = {
+      onPipelineStart: (e: PipelineStartEvent) => {
+        // Row exists now — persist log_path for SQLiteRunStore (the call in launch() was a no-op there).
+        void this.store.saveLogPath(runId, logger.logPath);
+        emit('pipeline_start', e);
+      },
+      onStageStart:        (e: StageStartEvent) =>        emit('stage_start', e),
+      onStageComplete:     (e: StageCompleteEvent) =>     emit('stage_complete', e),
+      onTaskRetry:         (e: StageRetryEvent) =>        emit('stage_retry', e),
+      onGroupStart:        (e: GroupStartEvent) =>        emit('group_start', e),
+      onGroupIteration:    (e: GroupIterationEvent) =>    emit('group_iteration', e),
+      onGroupFeedback:     (e: GroupFeedbackEvent) => {
+        lastGroupFeedback = e;
+        emit('group_feedback', e);
+      },
+      onGroupComplete:     (e: GroupCompleteEvent) =>          emit('group_complete', e),
+      onStageContext:      (e: StageContextEvent) =>           emit('stage_context', e),
+      onToolCallStart:     (e: StagedToolCallStartEvent) =>    emit('tool_call_start', e),
+      onToolCallComplete:  (e: StagedToolCallCompleteEvent) => emit('tool_call_complete', e),
+      onPipelineComplete:  (e: PipelineCompleteEvent) => {
+        emit('pipeline_complete', { ...e, meta: meta ?? {}, last_group_feedback: lastGroupFeedback });
+        this.bus.close(runId);
+      },
+      onPipelineCancelled: (e: PipelineCancelledEvent) => {
+        emit('pipeline_cancelled', e);
+      },
+    };
+
+    let runEngineConfig: EngineConfig = this.engineConfig;
+    if (config.repoPath !== undefined) {
+      const toolsDir = join(this.engineConfig.configsDir, 'tools');
+      const freshPlugins = await loadProjectTools(toolsDir, config.repoPath);
+      // toolRegistry is always provided when using the API launcher
+      const freshRegistry = this.engineConfig.toolRegistry!.clone();
+      for (const plugin of freshPlugins) {
+        freshRegistry.registerPlugin(plugin.name, plugin.tools, plugin.promptSnippet);
+      }
+      runEngineConfig = { ...this.engineConfig, repoPath: config.repoPath, toolRegistry: freshRegistry };
+    }
+    const engine = this.engineFactory(runEngineConfig, perRunEvents);
+
+    void engine
+      .run({ pipeline, input, meta, signal: controller.signal, id: runId, depth: config.depth, parentRunId })
+      .then(async () => {
+        await logger.close();
+      })
+      .catch(async (err: unknown) => {
+        logger.log({ event: 'pipeline_error', error: String(err) });
+        this.bus.close(runId);
+        await logger.close();
+      })
+      .finally(() => {
+        this.active.delete(runId);
+        if (userId) {
+          this.activePerUser.get(userId)?.delete(runId);
+        }
+      });
+
+    return { run_id: runId };
+  }
+
+  async cancel(run_id: string): Promise<void> {
+    this.active.get(run_id)?.abort();
+  }
+}
+
+export { randomUUID as generateRunId } from 'node:crypto';

package/src/logger.ts

@@ -0,0 +1,50 @@
+// JSONL logger for API runs
+// Writes to <runsDir>/<date>-<pipeline>-<runId>.jsonl
+
+import { createWriteStream, mkdirSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+function runIdShort(runId: string): string {
+  return runId.slice(0, 8);
+}
+
+function dateForFilename(): string {
+  const iso = new Date().toISOString();
+  return iso.slice(0, 16).replace(/(\d{2}):(\d{2})$/, '$1h$2m');
+}
+
+export interface ApiRunLogger {
+  logPath: string;
+  log(payload: Record<string, unknown>): void;
+  close(): Promise<void>;
+}
+
+export function createApiLogger(runsDir: string, runId: string, pipeline: string): ApiRunLogger {
+  const shortId = runIdShort(runId);
+  const date = dateForFilename();
+  const logPath = resolve(runsDir, `${date}-${pipeline}-${shortId}.jsonl`);
+
+  mkdirSync(runsDir, { recursive: true });
+  const stream = createWriteStream(logPath, { flags: 'a' });
+
+  return {
+    logPath,
+
+    log(payload: Record<string, unknown>): void {
+      const line = {
+        ts: new Date().toISOString(),
+        run_id: shortId,
+        ...payload,
+      };
+      if (stream.writable) {
+        stream.write(JSON.stringify(line) + '\n');
+      }
+    },
+
+    close(): Promise<void> {
+      return new Promise((resolve) => {
+        stream.end(() => resolve());
+      });
+    },
+  };
+}

package/src/plans.ts

@@ -0,0 +1,43 @@
+// api/src/plans.ts
+// Plan configuration types and default plans
+
+export interface PlanLimits {
+  runs_per_day: number;          // -1 = unlimited
+  max_concurrent: number;
+  max_tokens_per_run: number;    // -1 = unlimited
+  rate_limit_per_minute: number;
+}
+
+export type PlansConfig = Record<string, PlanLimits>;
+
+export const DEFAULT_PLANS: PlansConfig = {
+  free: {
+    runs_per_day: 5,
+    max_concurrent: 1,
+    max_tokens_per_run: 50_000,
+    rate_limit_per_minute: 10,
+  },
+  pro: {
+    runs_per_day: 100,
+    max_concurrent: 5,
+    max_tokens_per_run: 500_000,
+    rate_limit_per_minute: 60,
+  },
+  unlimited: {
+    runs_per_day: -1,
+    max_concurrent: 20,
+    max_tokens_per_run: -1,
+    rate_limit_per_minute: 300,
+  },
+};
+
+/** Merge user-supplied partial plans with defaults. Unknown plans fall back to 'free'. */
+export function resolvePlans(configPlans?: Record<string, PlanLimits>): PlansConfig {
+  if (!configPlans) return DEFAULT_PLANS;
+  return { ...DEFAULT_PLANS, ...configPlans };
+}
+
+/** Get plan limits for a user, defaulting to 'free' if plan is unknown. */
+export function getPlanLimits(plans: PlansConfig, planName: string): PlanLimits {
+  return plans[planName] ?? plans.free ?? DEFAULT_PLANS.free;
+}

package/src/routes/agents.ts

@@ -0,0 +1,131 @@
+import { readdir, readFile, writeFile, unlink, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import * as yaml from 'js-yaml';
+import type { FastifyInstance } from 'fastify';
+import type { ServerDeps } from '../server.js';
+
+export async function agentsRoutes(
+  fastify: FastifyInstance,
+  options: { deps: ServerDeps }
+): Promise<void> {
+  const agentsDir = join(options.deps.configsDir, 'agents');
+
+  const errorSchema = { type: 'object', properties: { error: { type: 'string' } } };
+
+  // GET /api/agents
+  fastify.get('/agents', {
+    schema: {
+      tags: ['agents'],
+      summary: 'List all agent names',
+      response: {
+        200: {
+          type: 'object',
+          properties: {
+            agents: { type: 'array', items: { type: 'string' } },
+          },
+        },
+      },
+    },
+  }, async (_request, reply) => {
+    let entries: string[];
+    try {
+      entries = await readdir(agentsDir);
+    } catch {
+      return reply.send({ agents: [] });
+    }
+    const agents = entries
+      .filter(f => f.endsWith('.agent.yaml'))
+      .map(f => f.slice(0, -'.agent.yaml'.length));
+    return reply.send({ agents });
+  });
+
+  // GET /api/agents/:name
+  fastify.get<{ Params: { name: string } }>('/agents/:name', {
+    schema: {
+      tags: ['agents'],
+      summary: 'Get an agent by name',
+      params: {
+        type: 'object',
+        properties: { name: { type: 'string' } },
+        required: ['name'],
+      },
+      response: {
+        200: { type: 'object', additionalProperties: true },
+        404: errorSchema,
+      },
+    },
+  }, async (request, reply) => {
+    const filePath = join(agentsDir, `${request.params.name}.agent.yaml`);
+    let content: string;
+    try {
+      content = await readFile(filePath, 'utf-8');
+    } catch {
+      return reply.status(404).send({ error: 'Agent not found' });
+    }
+    return reply.send(yaml.load(content));
+  });
+
+  // PUT /api/agents/:name
+  fastify.put<{
+    Params: { name: string };
+    Body: Record<string, unknown>;
+  }>('/agents/:name', {
+    schema: {
+      tags: ['agents'],
+      summary: 'Create or update an agent',
+      params: {
+        type: 'object',
+        properties: { name: { type: 'string' } },
+        required: ['name'],
+      },
+      body: { type: 'object' },
+      response: {
+        200: {
+          type: 'object',
+          properties: {
+            name: { type: 'string' },
+            content: { type: 'object', additionalProperties: true },
+          },
+        },
+        400: errorSchema,
+      },
+    },
+  }, async (request, reply) => {
+    const body = request.body;
+
+    if (!body['name'] || typeof body['name'] !== 'string') {
+      return reply.status(400).send({ error: "Agent must have a 'name' field (string)" });
+    }
+
+    await mkdir(agentsDir, { recursive: true });
+    const filePath = join(agentsDir, `${request.params.name}.agent.yaml`);
+    await writeFile(filePath, yaml.dump(body), 'utf-8');
+
+    return reply.send({ name: request.params.name, content: body });
+  });
+
+  // DELETE /api/agents/:name
+  fastify.delete<{ Params: { name: string } }>('/agents/:name', {
+    schema: {
+      tags: ['agents'],
+      summary: 'Delete an agent',
+      params: {
+        type: 'object',
+        properties: { name: { type: 'string' } },
+        required: ['name'],
+      },
+      response: {
+        204: { type: 'null', description: 'No content' },
+        404: errorSchema,
+      },
+    },
+  }, async (request, reply) => {
+    const filePath = join(agentsDir, `${request.params.name}.agent.yaml`);
+    try {
+      await unlink(filePath);
+    } catch {
+      return reply.status(404).send({ error: 'Agent not found' });
+    }
+    return reply.status(204).send();
+  });
+}

package/src/routes/config.ts

@@ -0,0 +1,154 @@
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import * as yaml from 'js-yaml';
+import type { FastifyInstance } from 'fastify';
+import type { ServerDeps } from '../server.js';
+
+const KNOWN_PROVIDERS = new Set(['anthropic', 'openai', 'ollama']);
+
+interface RawConfig {
+  providers?: Record<string, { apiKey?: string }>;
+  defaults?: Record<string, unknown>;
+}
+
+async function readConfig(configsDir: string): Promise<RawConfig> {
+  try {
+    const content = await readFile(join(configsDir, 'config.yaml'), 'utf-8');
+    return (yaml.load(content) as RawConfig) ?? {};
+  } catch {
+    return {};
+  }
+}
+
+async function writeConfig(configsDir: string, config: RawConfig): Promise<void> {
+  await mkdir(configsDir, { recursive: true });
+  await writeFile(join(configsDir, 'config.yaml'), yaml.dump(config), 'utf-8');
+}
+
+function maskConfig(config: RawConfig): RawConfig {
+  if (!config.providers) return config;
+  const maskedProviders: Record<string, { apiKey: string }> = {};
+  for (const [name, provider] of Object.entries(config.providers)) {
+    maskedProviders[name] = { apiKey: provider.apiKey ? '***' : '' };
+  }
+  return { ...config, providers: maskedProviders };
+}
+
+export async function configRoutes(
+  fastify: FastifyInstance,
+  options: { deps: ServerDeps }
+): Promise<void> {
+  const { configsDir } = options.deps;
+
+  const configResponseSchema = {
+    type: 'object',
+    properties: {
+      providers: {
+        type: 'object',
+        additionalProperties: {
+          type: 'object',
+          properties: { apiKey: { type: 'string' } },
+        },
+      },
+      defaults: {
+        type: 'object',
+        properties: {
+          provider: { type: 'string' },
+          model: { type: 'string' },
+        },
+      },
+    },
+  };
+
+  // GET /api/config
+  fastify.get('/config', {
+    schema: {
+      tags: ['config'],
+      summary: 'Get current config',
+      response: {
+        200: configResponseSchema,
+      },
+    },
+  }, async (_request, reply) => {
+    const config = await readConfig(configsDir);
+    return reply.send({
+      providers: {},
+      ...maskConfig(config),
+    });
+  });
+
+  // PATCH /api/config
+  fastify.patch<{ Body: Partial<RawConfig> }>('/config', {
+    schema: {
+      tags: ['config'],
+      summary: 'Patch config (merge defaults and providers)',
+      body: { type: 'object' },
+      response: {
+        200: configResponseSchema,
+      },
+    },
+  }, async (request, reply) => {
+    const config = await readConfig(configsDir);
+    const patch = request.body;
+
+    if (patch.defaults) {
+      config.defaults = { ...config.defaults, ...patch.defaults };
+    }
+    if (patch.providers) {
+      config.providers = { ...config.providers, ...patch.providers };
+    }
+
+    await writeConfig(configsDir, config);
+    return reply.send({
+      providers: {},
+      ...maskConfig(config),
+    });
+  });
+
+  // POST /api/config/providers
+  fastify.post<{ Body: { provider: string; apiKeyEnvVar: string } }>(
+    '/config/providers',
+    {
+      schema: {
+        tags: ['config'],
+        summary: 'Add or update a provider',
+        body: {
+          type: 'object',
+          required: ['provider', 'apiKeyEnvVar'],
+          properties: {
+            provider: { type: 'string' },
+            apiKeyEnvVar: { type: 'string' },
+          },
+        },
+        response: {
+          200: configResponseSchema,
+          400: {
+            type: 'object',
+            properties: { error: { type: 'string' } },
+          },
+        },
+      },
+    },
+    async (request, reply) => {
+      const { provider, apiKeyEnvVar } = request.body;
+
+      if (!KNOWN_PROVIDERS.has(provider)) {
+        return reply.status(400).send({
+          error: `Unknown provider: '${provider}'. Supported: ${[...KNOWN_PROVIDERS].join(', ')}`,
+        });
+      }
+
+      const config = await readConfig(configsDir);
+      config.providers = {
+        ...config.providers,
+        [provider]: { apiKey: `\${${apiKeyEnvVar}}` },
+      };
+
+      await writeConfig(configsDir, config);
+      return reply.send({
+        providers: {},
+        ...maskConfig(config),
+      });
+    }
+  );
+}