A local-first multi-agent app development platform, built on PenguinHarness
import { Component, Module, moduleDefOf, Use } from "@adelie/core/kernel";
import type { ManifestTable, ModuleClass, ModuleDef } from "@adelie/core/kernel";
import { DEFAULT_PROJECT_ID, DEFAULT_PROJECT_NAME } from "@adelie/core";
import table from "./ifaces.json" with { type: "json" };
import type { HmrCapabilities, ReassemblyChange } from "./hmr/capabilities.js";
import {
ConfigPaths,
ConsoleLog,
RuntimeAuthState,
RuntimeChannels,
RuntimeLifecycle,
RuntimeConfig,
RuntimeDb,
RuntimeDesktop,
RuntimeHmr,
RuntimeHmrControl,
AppReassembly,
RuntimeProxy,
RuntimeResourceGroups,
SystemClock,
AuthState,
Channels,
Clock,
Config,
Db,
Desktop,
Lifecycle,
Hmr,
Reassembly,
HmrControl,
Log,
Paths,
Proxy,
ResourceGroups,
} from "./hmr/capabilities.js";
import { ScryptHasher, PasswordHasher } from "./auth/password.js";
import { LiveStreamRegistry, LiveStreams } from "./auth/live-streams.js";
import {
DefaultMessagingTuning,
Messaging,
MessagingTaskRunner,
MessagingModule,
QQScan,
} from "./runtime/messaging/bridge.js";
import { FeishuSdkProvider } from "./runtime/messaging/feishu-connector.js";
import { TelegramTransportProvider } from "./runtime/messaging/telegram-connector.js";
import { QQTransportProvider } from "./runtime/messaging/qq-connector.js";
import { QQScanTransportProvider } from "./runtime/messaging/qq-scan.js";
import { WeChatTransportProvider } from "./runtime/messaging/wechat-connector.js";
import { WeChatScanTransportProvider } from "./runtime/messaging/wechat-scan.js";
import { PluginConfig, PluginConfigProvider } from "./plugin/config.js";
import { PluginConfigAdmin, PluginConfigPage } from "./plugin/config-page.js";
import {
CoreSessionLoaders,
DefaultTitleGenerators,
SessionsModule,
SessionEnv,
Sessions,
SessionServiceIface,
} from "./runtime/session-manager.js";
import {
GlobalFetch,
UpdateCheckService,
VersionRoutes,
UpdateCheck,
} from "./services/update-check-service.js";
import { UpdateJobService } from "./services/update-job.js";
import { HarnessHistoryStore } from "./services/harness-history.js";
import { FeedbackRoutes } from "./http/routes/feedback.js";
import { UsersRepo } from "./db/repos/users.js";
import { AuthSessionsRepo } from "./db/repos/auth-sessions.js";
import { ServerSettingsRepo } from "./db/repos/server-settings.js";
import { UiPrefsRepo } from "./db/repos/ui-prefs.js";
import { SessionsRepo } from "./db/repos/sessions.js";
import { ProjectsRepo } from "./db/repos/projects.js";
import { ModelPromotionsRepo } from "./db/repos/model-promotions.js";
import { ModelProviderAuthTokensRepo } from "./db/repos/model-provider-auth-tokens.js";
import { MembersRepo } from "./db/repos/members.js";
import { AgentsRepo } from "./db/repos/agents.js";
import { UsageRepo } from "./db/repos/usage.js";
import { SchedulesRepo } from "./db/repos/schedules.js";
import { TraceIndexRepo } from "./db/repos/trace-index.js";
import { MessagingBindingsRepo } from "./db/repos/messaging-bindings.js";
import { OrgCacheRepo } from "./db/repos/organizations.js";
import { ErrorsRepo } from "./db/repos/errors.js";
import { SessionSources } from "./runtime/session-sources.js";
import { ErrorRecorder } from "./runtime/error-recorder.js";
import { UsageRecorder } from "./runtime/usage-recorder.js";
import { UsageService } from "./services/usage-service.js";
import { StorageAdmin, StorageService } from "./services/storage-service.js";
import { ProjectConfigService } from "./services/project-config-service.js";
import { ModelOAuthService } from "./services/model-oauth-service.js";
import { PlatformAuth, PlatformAuthProvider } from "./services/platform-auth-service.js";
import { ModelScopeAuth, ModelScopeAuthProvider } from "./services/modelscope-auth-service.js";
import { TraceIndexService } from "./services/trace-index.js";
import { TraceService } from "./services/trace-service.js";
import { WorkspaceFilesService } from "./services/workspace-files-service.js";
import { RevealService } from "./services/reveal-path.js";
import { ProjectAccess } from "./services/project-access.js";
import { ProjectNotifier } from "./services/project-events.js";
import { ProjectService, ProjectRuns } from "./services/project-service.js";
import { AuthService, InitialProjectProvisioner } from "./auth/service.js";
import { AdminService } from "./services/admin-service.js";
import { Scheduler, ScheduleSessionCreator, ScheduleTaskRunner } from "./runtime/scheduler.js";
import { AgentConfigService } from "./services/agent-config-service.js";
import { UserVaultService } from "./services/user-vault-service.js";
import { SnapshotService } from "./services/snapshot-service.js";
import { AgentRoutes } from "./services/agent-routes.js";
import { AgentService } from "./services/agent-service.js";
import { MemoryService } from "./services/memory-service.js";
import { BenchmarkService } from "./services/benchmark-service.js";
import { ProjectsRoutes } from "./http/routes/dirs.js";
import { SandboxModule } from "./sandbox/service.js";
import { SandboxSettings } from "./sandbox/settings-store.js";
import { SandboxSettingsStatus } from "./sandbox/settings-status.js";
import { SchedulerRoutes } from "./http/routes/schedules.js";
import { Machines, MachinesModule } from "./machines/service.js";
import { OrganizationModule, OrgScheduler, OrgService } from "./runtime/organization/service.js";
import { OrgRoutes } from "./http/routes/organizations.js";
import { OrgRuns, OrgSessions } from "./runtime/organization/deps.js";
import { TerminalRelay } from "./machines/terminal-relay.js";
import { ProjectAdminRoutes } from "./http/routes/projects.js";
import { AdminRoutes } from "./http/routes/admin.js";
import { AsrRoutes } from "./http/routes/asr.js";
import { MeRoutes } from "./http/routes/me.js";
import { UserVaultRoutes } from "./http/routes/user-vault.js";
import { AuthRoutes } from "./http/routes/auth.js";
import {
DesktopLoginItemRoutes,
DesktopPetRoutes,
DesktopPrivacySettingsRoutes,
DesktopRoutes,
DesktopTrayRoutes,
DesktopUpdateRoutes,
} from "./http/routes/desktop.js";
import { InstallRoutes } from "./http/routes/install.js";
import { ThemesRoutes, ThemeStylesheetRoutes } from "./http/routes/themes.js";
import { HmrRoutes } from "./hmr/routes.js";
import { EventsRoutes } from "./http/routes/events.js";
import { PluginRegistryRoutes, PluginRoutes } from "./http/routes/plugins.js";
import { InstalledPluginRoutes } from "./http/routes/plugins-installed.js";
import { SuggestIdRoutes } from "./http/routes/suggest-id.js";
import { TerminalModule } from "./terminal/manager.js";
import { SessionApiRoutes } from "./http/routes/sessions.js";
import { Admin, Auth, AuthSessions, Users } from "./mechanisms/identity.js";
import {
Access,
AgentIndex,
Members,
ModelOAuth,
ModelProviderAuthTokens,
ProjectConfigStore,
ProjectEvents,
ProjectLifecycle,
Projects,
} from "./mechanisms/projects.js";
import { Schedules, Scheduling, SessionIndex, SessionOrigins } from "./mechanisms/sessions.js";
import { Workflows } from "./mechanisms/workflows.js";
import { WorkflowService } from "./workflows/service.js";
import { WorkflowRoutes } from "./workflows/routes.js";
import {
ErrorLog,
Errors,
UsageQueries,
UsageRecording,
UsageStore,
} from "./mechanisms/observability.js";
import { TraceIndex, TraceIndexStore, Traces } from "./mechanisms/traces.js";
import { AgentConfig, AgentLifecycle, Benchmarks, Memory, Snapshots } from "./mechanisms/agents.js";
import { UserVault } from "./mechanisms/vault.js";
import { FileReveal, WorkspaceFiles } from "./mechanisms/workspace.js";
import { Settings, UiPrefsStore } from "./mechanisms/settings.js";
import { MessagingBindings } from "./mechanisms/messaging.js";
import { OrgCache } from "./mechanisms/organization.js";
import { PreviewModule, PreviewTokens } from "./http/routes/preview.js";
import { Http, HttpModule } from "./http/app.js";
import { WebModule, WebShell } from "./http/routes/contributions.js";
import { BuiltinBrowserModule } from "./builtin-browser/module.js";
import { AgentApiModule } from "./amsp/module.js";
/**
* The platform's module tree: the root module and its children, in one place.
*
* The root provides nothing and requires nothing itself; it exists so the children have a
* scope to see each other in, and its create() — which runs LAST, after every child — does
* the App-wide steps that need the whole tree up (the trace
* adoption sweep, the machine sweeps). Everything else a module used to reach through
* `AppDeps` it now names in its manifest.
*/
/**
* The App-wide steps that need the whole business tree up, as a component of its own:
* requiring what it sweeps puts it after those nodes in dependency order, and typed by
* their classes — nothing reaches into a sibling by name.
*/
@Component()
export class Startup {
@Use() private readonly scheduler!: Scheduling;
@Use() private readonly orgScheduler!: OrgScheduler;
@Use() private readonly sessionService!: SessionServiceIface;
@Use() private readonly machines!: Machines;
@Use() private readonly errors!: Errors;
@Use() private readonly projectConfig!: ProjectConfigStore;
@Use() private readonly usage!: UsageQueries;
@Use() private readonly agents!: AgentLifecycle;
async setup() {
// The shared default Project's display name, on every start rather than only where it is
// adopted (auth/service.ts seedAdmin adopts it once, and that seed early-returns on any
// root that already has its admin): an install older than this behavior would go on
// showing the raw id as the Project's label. Idempotent and file-guarded — a root without
// that Project's config file is untouched, so nothing is ever created here.
await this.projectConfig.ensureDisplayName(DEFAULT_PROJECT_ID, DEFAULT_PROJECT_NAME);
// Usage rows with no fixed cost yet — from before costs were fixed at record time, or
// written by an older build a hot update rolled back to — are costed once, before anything
// reads the cost center (COMPATIBILITY: see UsageService.settleUnsettledCosts). Awaited, but
// a failure is recorded rather than thrown: the rows then read as uncosted until a later boot.
try {
await this.usage.settleUnsettledCosts();
} catch (err) {
this.errors.record({ source: "process", err, code: "usage_cost_settle_failed" });
}
// Schedule scheduler: startup reconciliation (missed, don't backfill) + periodic scan.
await this.scheduler.start();
// Company mode's scheduler: same lifetime and the same startup rule (reconcile once,
// no backfill), only active while this App is.
await this.orgScheduler.start();
// Startup adoption sweep: fold Trace-only Sessions into the index. Fire-and-forget —
// a broken trace shard must not block the boot.
void this.sessionService.adoptUnmanagedTraceSessions().catch((err: unknown) => {
this.errors.record({ source: "process", err, code: "trace_adoption_failed" });
});
// Deleted Agents whose files a stopped process had not finished removing: removed now, in
// the background, the way the delete itself removes them.
void this.agents.resumeDeletions().catch((err: unknown) => {
this.errors.record({ source: "process", err, code: "agent_purge_failed" });
});
// Machines, in one sweep (machines/service.ts start()): a push here is a push everywhere,
// so this App booting hands the same build on to any machine still carrying a different
// one, and then re-holds every connection the record says was held — the generation
// before closed what it opened on its way out. Without this, every push and every
// restart leaves each machine disconnected until someone connects it by hand.
// Fire-and-forget for the same reason as the adoption sweep: a host that is slow to
// answer must not hold up the App that serves everything else.
void this.machines.start().catch((err: unknown) => {
this.errors.record({ source: "process", err, code: "machines_reconnect_failed" });
});
}
}
/**
* The tree, grouped by mechanism. Each group is a @Module whose `exports` are the
* interfaces its children offer the rest of the tree; everything else in a group — the
* repos, the seams a test replaces, the route components — is visible only inside it.
* A whole group is replaceable, and so is any node inside one.
*/
@Module({
children: [
RuntimeConfig,
RuntimeDb,
RuntimeChannels,
RuntimeProxy,
RuntimeHmr,
RuntimeHmrControl,
AppReassembly,
RuntimeDesktop,
RuntimeAuthState,
RuntimeLifecycle,
RuntimeResourceGroups,
ConsoleLog,
SystemClock,
ConfigPaths,
],
exports: [
Config,
Db,
Channels,
Proxy,
Hmr,
HmrControl,
Reassembly,
Desktop,
AuthState,
Lifecycle,
ResourceGroups,
Log,
Clock,
Paths,
],
})
export class RuntimeModule {}
@Module({
children: [
UsersRepo,
AuthSessionsRepo,
ScryptHasher,
LiveStreamRegistry,
AuthService,
AdminService,
AdminRoutes,
MeRoutes,
UserVaultRoutes,
AuthRoutes,
],
exports: [Users, AuthSessions, Auth, Admin, PasswordHasher, LiveStreams],
})
export class IdentityModule {}
@Module({
children: [
ProjectsRepo,
ModelPromotionsRepo,
ModelProviderAuthTokensRepo,
MembersRepo,
AgentsRepo,
ProjectAccess,
ProjectNotifier,
ProjectService,
ProjectConfigService,
ModelOAuthService,
PlatformAuthProvider,
ModelScopeAuthProvider,
ProjectsRoutes,
ProjectAdminRoutes,
],
exports: [
Projects,
Members,
AgentIndex,
Access,
ProjectLifecycle,
ProjectConfigStore,
ModelProviderAuthTokens,
ModelOAuth,
PlatformAuth,
ModelScopeAuth,
InitialProjectProvisioner,
ProjectEvents,
],
})
export class ProjectsModule {}
@Module({
children: [
SessionsRepo,
SessionSources,
SchedulesRepo,
Scheduler,
CoreSessionLoaders,
DefaultTitleGenerators,
SessionsModule,
SessionApiRoutes,
SchedulerRoutes,
EventsRoutes,
],
exports: [
SessionIndex,
SessionOrigins,
Schedules,
Scheduling,
Sessions,
SessionServiceIface,
SessionEnv,
ScheduleTaskRunner,
ScheduleSessionCreator,
MessagingTaskRunner,
OrgRuns,
OrgSessions,
ProjectRuns,
],
})
export class SessionRuntimeModule {}
@Module({
children: [ServerSettingsRepo, UiPrefsRepo],
exports: [Settings, UiPrefsStore],
})
export class SettingsModule {}
/**
* Plugin configuration as a group of its own, beside the settings it is stored in: a plugin
* that stands in for the settings group replaces the store, not the schema-and-watch layer
* over it, and a plugin's manifest names this module as where `PluginConfig` comes from.
*/
@Module({
children: [PluginConfigProvider, PluginConfigPage],
exports: [PluginConfig, PluginConfigAdmin],
})
export class PluginConfigModule {}
/**
* Sandbox settings as a group of their own: the sandbox service boots on the capability-free
* floor, while its settings group and the node applying it need plugin configuration (and
* through it the database), so they sit above it.
*/
@Module({
children: [SandboxSettings, SandboxSettingsStatus],
exports: [],
})
export class SandboxSettingsModule {}
@Module({
children: [ErrorsRepo, ErrorRecorder, UsageRepo, UsageRecorder, UsageService, StorageService],
exports: [ErrorLog, Errors, UsageStore, UsageRecording, UsageQueries, StorageAdmin],
})
export class ObservabilityModule {}
@Module({
children: [TraceIndexRepo, TraceIndexService, TraceService],
exports: [TraceIndexStore, TraceIndex, Traces],
})
export class TracesModule {}
@Module({
children: [
AgentConfigService,
UserVaultService,
SnapshotService,
AgentService,
MemoryService,
BenchmarkService,
AgentRoutes,
],
exports: [AgentConfig, UserVault, Snapshots, AgentLifecycle, Memory, Benchmarks],
})
export class AgentsModule {}
@Module({
children: [WorkspaceFilesService, RevealService, PreviewModule],
exports: [WorkspaceFiles, FileReveal, PreviewTokens],
})
export class WorkspaceModule {}
@Module({
children: [
FeishuSdkProvider,
TelegramTransportProvider,
QQTransportProvider,
QQScanTransportProvider,
WeChatTransportProvider,
WeChatScanTransportProvider,
DefaultMessagingTuning,
MessagingBindingsRepo,
MessagingModule,
],
exports: [Messaging, QQScan, MessagingBindings],
})
export class MessagingHubModule {}
/**
* Company mode: the organization runtime, its routes and the caches they project into.
* The caches are the group's own store — only the four members the session runtime and
* Project deletion reach for leave the group, as OrgCache.
*/
@Module({
children: [OrgCacheRepo, OrganizationModule, OrgRoutes],
exports: [OrgCache, OrgService, OrgScheduler],
})
export class CompanyModule {}
@Module({
children: [
GlobalFetch,
UpdateCheckService,
UpdateJobService,
HarnessHistoryStore,
HttpModule,
WebModule,
InstallRoutes,
VersionRoutes,
FeedbackRoutes,
AsrRoutes,
HmrRoutes,
DesktopRoutes,
DesktopUpdateRoutes,
DesktopTrayRoutes,
DesktopPetRoutes,
DesktopLoginItemRoutes,
DesktopPrivacySettingsRoutes,
PluginRoutes,
PluginRegistryRoutes,
InstalledPluginRoutes,
SuggestIdRoutes,
ThemesRoutes,
ThemeStylesheetRoutes,
],
exports: [Http, WebShell, UpdateCheck],
})
export class ApiModule {}
@Module({
children: [WorkflowService, WorkflowRoutes],
exports: [Workflows],
})
export class WorkflowsModule {}
/** The root: provides nothing and requires nothing; it exists so the groups have a scope to see each other in. */
@Module({
children: [
RuntimeModule,
SettingsModule,
PluginConfigModule,
IdentityModule,
ProjectsModule,
SessionRuntimeModule,
ObservabilityModule,
TracesModule,
AgentsModule,
WorkspaceModule,
MessagingHubModule,
CompanyModule,
ApiModule,
SandboxModule,
SandboxSettingsModule,
TerminalModule,
MachinesModule,
TerminalRelay,
WorkflowsModule,
BuiltinBrowserModule,
AgentApiModule,
Startup,
],
})
export class PlatformModule {}
/**
* The platform tree as the booter takes it: the runtime nodes pre-built over the claimed
* capabilities, the claim's replacements standing in for the nodes a test names, and
* plugin modules appended under the root.
*/
export function platformDef(
caps: HmrCapabilities,
adoptable: (group: string) => boolean,
plugins: ModuleDef[] = [],
replace: ReadonlyMap<string, ModuleDef> = new Map(),
/** The platform's own re-assembly (hmr/platform.ts); a test tree that never re-assembles writes the change and answers false. */
reassemble: (change?: ReassemblyChange) => Promise<boolean> = async (change) => {
await change?.write();
return false;
},
): ModuleDef {
const instances = new Map<ModuleClass, object>([
[RuntimeConfig, new RuntimeConfig(caps)],
[RuntimeDb, new RuntimeDb(caps)],
[RuntimeChannels, new RuntimeChannels(caps)],
[RuntimeProxy, new RuntimeProxy(caps)],
[RuntimeHmr, new RuntimeHmr(caps)],
[RuntimeHmrControl, new RuntimeHmrControl(caps)],
[AppReassembly, new AppReassembly(reassemble)],
[RuntimeDesktop, new RuntimeDesktop(caps)],
[RuntimeAuthState, new RuntimeAuthState(caps)],
[RuntimeLifecycle, new RuntimeLifecycle(caps)],
[RuntimeResourceGroups, new RuntimeResourceGroups(adoptable)],
]);
for (const [cls, instance] of caps.replacements) instances.set(cls, instance);
return moduleDefOf(PlatformModule, {
manifests: table.modules as ManifestTable,
instances,
extra: plugins,
replace,
});
}