Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

10.6 KB
Raw Blame
/**
 * The projects mechanisms: what a node may require, declared apart from what implements it.
 */
import { Interface } from "@adelie/core/kernel";
import type { AccessibleProjectRow, ProjectRow } from "../db/repos/projects.js";
import type { MemberRow } from "../db/repos/members.js";
import type { AgentRow } from "../db/repos/agents.js";
import type {
  ChatDefaultsDto,
  CommandPolicyDto,
  EndpointModelListRequest,
  EndpointModelListResponse,
  MemberInfo,
  ModelProtocolDetectRequest,
  ModelProtocolDetectResponse,
  ModelRefDto,
  ModelTestRequest,
  ModelTestResponse,
  ModelVisionDetectRequest,
  ModelVisionDetectResponse,
  ModelsResponse,
  ModelsUpdateRequest,
  ProjectRole,
  ProjectSummary,
  ServerEvent,
} from "../api/types.js";
import type { UserRow } from "../db/repos/users.js";
import type { RawTable, UtilityCompletion } from "../services/project-config-service.js";
import type {
  ListEndpointModelsOptions,
  ModelRequestContext,
  ModelRef,
  PluginTables,
  ProjectConfig,
} from "@adelie/core";
import type { PricingRates } from "../services/usage-service.js";
import type {
  PlatformModelApplyResult,
  PlatformModelCatalog,
} from "../services/platform-auth-types.js";
import type {
  ModelOAuthErrorCode,
  ModelOAuthMode,
  ModelOAuthStartResult,
  ModelOAuthStatus,
} from "../services/model-oauth-service.js";

/** Projects: the mechanism ProjectsRepo implements. */
@Interface()
export abstract class Projects {
  abstract insert(row: ProjectRow): void;
  abstract findById(projectId: string): ProjectRow | null;
  abstract listAll(): ProjectRow[];
  abstract listAccessible(userId: string): AccessibleProjectRow[];
  abstract listByOwner(userId: string): ProjectRow[];
  abstract delete(projectId: string): void;
}

/** Members: the mechanism MembersRepo implements. */
@Interface()
export abstract class Members {
  abstract insert(row: MemberRow): void;
  abstract isMember(projectId: string, userId: string): boolean;
  abstract list(projectId: string): MemberRow[];
  abstract delete(projectId: string, userId: string): void;
}

/** AgentIndex: the mechanism AgentsRepo implements. */
@Interface()
export abstract class AgentIndex {
  abstract insertOrIgnore(row: AgentRow): void;
  abstract exists(projectId: string, agentId: string): boolean;
  abstract list(projectId: string): AgentRow[];
  abstract delete(projectId: string, agentId: string): void;
  abstract deleteByProject(projectId: string): void;
}

/** Access: the mechanism ProjectAccess implements. */
@Interface()
export abstract class Access {
  abstract find(userId: string, projectId: string): (ProjectRow & { role: ProjectRole }) | null;
  abstract requireProjectAccess(
    userId: string,
    projectId: string,
  ): ProjectRow & { role: ProjectRole };
  abstract canAccess(userId: string, projectId: string): boolean;
  abstract requireProjectOwner(userId: string, projectId: string): ProjectRow;
  abstract accessibleProjectIds(userId: string): string[];
  abstract listProjects(userId: string): Promise<ProjectSummary[]>;
}

/** ProjectLifecycle: the mechanism ProjectService implements. */
@Interface()
export abstract class ProjectLifecycle {
  abstract requireProjectAccess(
    userId: string,
    projectId: string,
  ): ProjectRow & { role: ProjectRole };
  abstract canAccess(userId: string, projectId: string): boolean;
  abstract requireProjectOwner(userId: string, projectId: string): ProjectRow;
  abstract accessibleProjectIds(userId: string): string[];
  abstract listProjects(userId: string): Promise<ProjectSummary[]>;
  abstract createProject(owner: UserRow, projectId: string, name?: string): Promise<ProjectSummary>;
  /** Every id `createProject` refuses as taken, as names only: the rows and the data root's entries. */
  abstract takenProjectIds(): Promise<string[]>;
  abstract provisionInitialProject(user: UserRow, isAdmin: boolean): Promise<void>;
  abstract renameProject(userId: string, projectId: string, name: string): Promise<ProjectSummary>;
  abstract deleteProject(userId: string, projectId: string): Promise<void>;
  abstract destroyProject(projectId: string): Promise<void>;
  abstract listMembers(userId: string, projectId: string): MemberInfo[];
  abstract addMember(userId: string, projectId: string, targetUserId: string): MemberInfo;
  abstract removeMember(userId: string, projectId: string, targetUserId: string): void;
}

/** ProjectConfigStore: the mechanism ProjectConfigService implements. */
@Interface()
export abstract class ProjectConfigStore {
  abstract readRaw(projectId: string): Promise<RawTable>;
  abstract loadConfig(projectId: string): Promise<ProjectConfig>;
  abstract writeRaw(projectId: string, data: RawTable): Promise<void>;
  abstract writeInitialConfig(projectId: string, name: string): Promise<void>;
  abstract ensurePresetModels(projectId: string): Promise<boolean>;
  /** Fills in a display name for an adopted Project that has none (see the implementation's own doc). */
  abstract ensureDisplayName(projectId: string, name: string): Promise<void>;
  abstract seedPresetPromotions(projectId: string): Promise<void>;
  abstract getName(projectId: string): Promise<string | undefined>;
  abstract setName(projectId: string, name: string): Promise<void>;
  abstract getDefaultModelRef(projectId: string): Promise<ModelRef | undefined>;
  abstract setDefaultModelRef(projectId: string, ref: ModelRefDto): Promise<ModelRefDto>;
  abstract getChatDefaults(projectId: string): Promise<ChatDefaultsDto>;
  abstract setChatDefaults(projectId: string, req: ChatDefaultsDto): Promise<ChatDefaultsDto>;
  /** The `[plugins]` key: the shared table and each machine's own, package name → requirement, in the file's order. */
  abstract getPluginTables(projectId: string): Promise<PluginTables>;
  /** Replaces the tables (a declarative PUT); answers what was written. */
  abstract setPluginTables(projectId: string, tables: PluginTables): Promise<PluginTables>;
  abstract getCommandPolicy(projectId: string): Promise<CommandPolicyDto>;
  abstract setCommandPolicy(
    projectId: string,
    req: {
      enabled?: boolean;
      rules: { name: string; pattern: string; description?: string; enabled?: boolean }[];
    },
  ): Promise<CommandPolicyDto>;
  abstract getPricing(
    projectId: string,
    provider: string,
    modelId: string,
    at: Date,
  ): Promise<PricingRates | undefined>;
  abstract detectVision(
    projectId: string,
    req: ModelVisionDetectRequest,
  ): Promise<ModelVisionDetectResponse>;
  abstract testModel(projectId: string, req: ModelTestRequest): Promise<ModelTestResponse>;
  abstract detectProtocol(
    projectId: string,
    req: ModelProtocolDetectRequest,
  ): Promise<ModelProtocolDetectResponse>;
  abstract listEndpointModels(
    req: EndpointModelListRequest,
    listImpl?: (options: ListEndpointModelsOptions) => Promise<string[]>,
    timeoutMs?: number,
  ): Promise<EndpointModelListResponse>;
  abstract getModels(projectId: string): Promise<ModelsResponse>;
  abstract updateModels(projectId: string, req: ModelsUpdateRequest): Promise<ModelsResponse>;
  abstract setGroupApiKey(projectId: string, provider: string, apiKey: string): Promise<number>;
  abstract setGroupApiKeyWithProviderAuthToken(
    projectId: string,
    provider: string,
    apiKey: string,
    token: Omit<ModelProviderAuthToken, "provider" | "updatedAt">,
    options?: { expectedRefreshToken?: string },
  ): Promise<number>;
  abstract getGroupApiKey(projectId: string, provider: string): Promise<string | undefined>;
  /**
   * The key a group's account balance is read with: the stored group key, or else the
   * environment key a Session on one of the group's rows would use, when that variable's
   * official endpoint is the balance endpoint's own host. Server-side only.
   */
  abstract getGroupBalanceKey(projectId: string, provider: string): Promise<string | undefined>;
  abstract setModelApiKeyResolver(
    resolver: (context: ModelRequestContext) => Promise<string | undefined>,
  ): void;
  abstract mergePlatformModels(
    projectId: string,
    provider: string,
    catalog: PlatformModelCatalog,
    apiKey: string,
    applyKeyToExisting: boolean,
  ): Promise<PlatformModelApplyResult>;
  abstract completeOnce(projectId: string, prompt: string): Promise<UtilityCompletion>;
}

export interface ModelPromotion {
  provider: string;
  modelId: string;
  discount: number;
}

/** Per-Project model promotions (web.db `model_promotions`). */
@Interface()
export abstract class ModelPromotions {
  abstract get(projectId: string, provider: string, modelId: string): number | undefined;
  abstract list(projectId: string): ModelPromotion[];
  /** Replaces every promotion of the Project, in one transaction. */
  abstract replaceAll(projectId: string, rows: readonly ModelPromotion[]): void;
  /** Replaces the promotions of one provider group, in one transaction. */
  abstract replaceProvider(
    projectId: string,
    provider: string,
    rows: readonly ModelPromotion[],
  ): void;
}

export interface ModelProviderAuthToken {
  provider: string;
  refreshToken: string;
  accessTokenExpiresAt?: string;
  updatedAt: string;
}

/** Server-side OAuth refresh metadata for provider groups (web.db `model_provider_auth_tokens`). */
@Interface()
export abstract class ModelProviderAuthTokens {
  abstract get(projectId: string, provider: string): ModelProviderAuthToken | undefined;
  abstract upsert(projectId: string, row: Omit<ModelProviderAuthToken, "updatedAt">): void;
  abstract delete(projectId: string, provider: string): void;
}

/** ModelOAuth: the mechanism ModelOAuthService implements. */
@Interface()
export abstract class ModelOAuth {
  abstract start(input: {
    projectId: string;
    userId: string;
    provider: string;
    mode: ModelOAuthMode;
    callbackOrigin: string;
  }): ModelOAuthStartResult;
  abstract deposit(input: { flowId: string; projectId: string; code: string }): void;
  abstract poll(input: { flowId: string; userId: string; projectId: string }): Promise<{
    status: ModelOAuthStatus;
    provider: string;
    error?: ModelOAuthErrorCode;
    applied?: number;
  }>;
  abstract complete(input: {
    flowId: string;
    userId: string;
    projectId: string;
    code: string;
  }): Promise<{ ok: true; applied: number } | { ok: false; error: ModelOAuthErrorCode }>;
}

/**
 * ProjectEvents: the mechanism ProjectNotifier implements — a user-level event to everyone
 * who can see a Project, its owner and its members with GET /api/events open. The runtime
 * publishes a Session's state flips and its generated title this way, and a route
 * publishes a change the list could not otherwise learn of (a rename, a new Session).
 */
@Interface()
export abstract class ProjectEvents {
  abstract notifyProjectUsers(projectId: string, event: ServerEvent): void;
}