Files
waggle-os/packages/server/src/local/index.ts
shumeiko.it 74200d46e8 fix: five defects found while rewriting the docs (UF-061 to UF-065)
- Key messages named a Settings > API Keys tab that does not exist; they
  now point at Settings > Models (UF-061).
- The connector suggestion looked for vault.db, which never exists; it
  now checks the vault for a connector entry (UF-062).
- /config and /preferences were registered with a leading slash and
  never matched (UF-063).
- Pins and documents were written under ~/.waggle whatever the data
  directory; they now use the server's data directory (UF-064).
- The Windows uninstaller named a Data & Privacy page that does not
  exist (UF-065).
2026-11-01 02:08:57 +01:00

2481 lines
107 KiB
TypeScript

import crypto from 'node:crypto';
import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);
import Fastify, { type FastifyInstance, type FastifyRequest } from 'fastify';
import cors from '@fastify/cors';
import fastifyStatic from '@fastify/static';
import websocket from '@fastify/websocket';
import { WaggleDB, workspaceDataScope, WorkspaceManager, WaggleConfig, createEmbeddingProvider, type EmbeddingProviderConfig, type EmbeddingProviderInstance, CronStore, AwarenessLayer, VaultStore, SkillHashStore, TelemetryStore, TELEMETRY_EVENTS, ExecutionTraceStore } from '@waggle/core';
import { corsOriginAllowed } from './cors-config.js';
import { InstallAuditStore } from './install-audit.js';
import { selfBaseUrl, selfRequestHeaders } from './self-request.js';
import { getStorageProvider } from './storage/index.js';
import { isLoopbackBind, resolveBindHost } from './net-config.js';
import { isLocalRequest } from './origin-guard.js';
import {
Orchestrator,
createSystemTools,
createPlanTools,
createGitTools,
createDocumentTools,
createSpreadsheetTools,
createPresentationTools,
createPdfTools,
createSkillTools,
createSubAgentTools,
createWorkflowTools,
runAgentLoop,
parseOpenAiTextCompletion,
ensureIdentity,
loadSystemPrompt,
loadSkills,
HookRegistry,
loadHooksFromConfig,
CostTracker,
CommandRegistry,
registerWorkflowCommands,
registerMarketplaceCommands,
createCronTools,
createSearchTools,
createBrowserTools,
createLspTools,
createCliTools,
createConnectorSearchTools,
createCrossWorkspaceTools,
McpRuntime,
McpToolRetriever,
setPersonaDataDir,
deliverCronResult,
createDefaultDeliveryPreferences,
buildActiveBehavioralSpec,
TraceRecorder,
HarnessTraceBridge,
safeFetch,
detectInstalledTools,
PERSONAS,
type ToolDefinition,
type LoadedSkill,
type DeliveryPreferences,
} from '@waggle/agent';
import { PluginRuntimeManager, getStarterSkillsDir, validatePluginManifest } from '@waggle/sdk';
import { MarketplaceDB, MarketplaceSync, seedMcpServers, seedNewSources } from '@waggle/marketplace';
import type { RiskLevel } from '@waggle/shared';
import { runConnectorFetch } from './connector-harvest.js';
import { openMemoryStore } from './memory-runtime.js';
import { MemoryExtractionQueue } from './memory-extraction.js';
import { PERSONAL_SCOPE, workspaceScope, type MemoryStore } from '@waggle/memory-contract';
import { runLoopTick } from './loop-executor.js';
import { enqueueHeldAction } from './held-action-executor.js';
import { workspaceRoutes } from './routes/workspaces.js';
import { chatRoutes, type AgentRunner } from './routes/chat.js';
import { memoryRoutes } from './routes/memory.js';
import { memoryCenterRoutes } from './routes/memory-center.js';
import { artifactRoutes } from './routes/artifacts.js';
import { settingsRoutes } from './routes/settings.js';
import { embeddingRoutes, buildEmbeddingStatusPayload } from './routes/embedding.js';
import { sessionRoutes } from './routes/sessions.js';
import { knowledgeRoutes } from './routes/knowledge.js';
import { litellmRoutes } from './routes/litellm.js';
import { ingestRoutes, readFileRegistry } from './routes/ingest.js';
import { mindRoutes } from './routes/mind.js';
import { agentRoutes } from './routes/agent.js';
import { skillRoutes } from './routes/skills.js';
import { skillsAliasRoutes } from './routes/skills-aliases.js';
import { skillsHygieneRoutes } from './routes/skills-hygiene.js';
import { skillsAuditRoutes } from './routes/skills-audit.js';
import { approvalRoutes } from './routes/approval.js';
import { anthropicProxyRoutes } from './routes/anthropic-proxy.js';
import { taskRoutes } from './routes/tasks.js';
import { capabilitiesRoutes } from './routes/capabilities.js';
import { toolsRoutes } from './routes/tools.js';
import { externalToolRunRoutes } from './routes/external-tool-runs.js';
import { routeProposalRoutes } from './routes/route-proposals.js';
import { SignalBus } from './signal-bus.js';
import { commandRoutes } from './routes/commands.js';
import { commandRoutes as commandCenterRoutes } from './routes/command.js';
import { homeRoutes } from './routes/home.js';
import { onboardingRoutes } from './routes/onboarding.js';
import { cronRoutes } from './routes/cron.js';
import { notificationRoutes, emitNotification, emitSubagentStatus } from './routes/notifications.js';
import { marketplaceDevRoutes } from './routes/marketplace-dev.js';
import { marketplaceRoutes } from './routes/marketplace.js';
import {
CapabilityProposalStore,
createCapabilityProposalRoutes,
installMarketplaceApprovalIdentity,
} from './routes/capability-proposals.js';
import { agentSearchRoutes } from './routes/agent-search.js';
import { connectorRoutes } from './routes/connectors.js';
import { mcpRoutes } from './routes/mcps.js';
import { extendRoutes } from './routes/extend.js';
import { populateMcpRuntimeFromConfig } from './mcp-config.js';
import { scheduleMarketplaceBackgroundSync } from './marketplace-background-sync.js';
import { fleetRoutes } from './routes/fleet.js';
import { vaultRoutes } from './routes/vault.js';
import { personaRoutes } from './routes/personas.js';
import { feedbackRoutes } from './routes/feedback.js';
import { workflowRoutes } from './routes/workflows.js';
import { workspaceTemplateRoutes } from './routes/workspace-templates.js';
import { exportRoutes } from './routes/export.js';
import { dataEraseRoutes } from './routes/data-erase.js';
import { costRoutes } from './routes/cost.js';
import { backupRoutes } from './routes/backup.js';
import { offlineRoutes } from './routes/offline.js';
import { eventRoutes, closeAuditDb, cleanupAuditEvents, emitAuditEvent } from './routes/events.js';
import { pinRoutes } from './routes/pins.js';
import { documentRoutes } from './routes/documents.js';
import { fileRoutes } from './routes/files.js';
import { browseRoutes } from './routes/browse.js';
import { browserExtRoutes } from './routes/browser-ext.js';
import {
BROWSER_COMPANION_CREDENTIAL_VAULT_KEY,
browserCompanionCredentialMatches,
isBrowserCompanionCredentialHash,
} from './browser-companion-pairing.js';
import { telegramRoutes, pushTelegramMessage } from './routes/telegram.js';
import { ChannelManager } from './channels/manager.js';
import { runChannelChatTurn } from './channels/chat-client.js';
import { channelRoutes } from './channels/routes.js';
import { isChannelPlatform } from './channels/types.js';
import { WorkspaceTurnCoordinator } from './workspace-turn-coordinator.js';
import { DreamJournal } from './dream-journal.js';
import { dreamRoutes } from './routes/dreams.js';
import { oauthRoutes } from './routes/oauth.js';
import { waggleSignalRoutes } from './routes/waggle-signals.js';
import { providerRoutes } from './routes/providers.js';
import { profileRoutes } from './routes/profile.js';
import { telemetryRoutes } from './routes/telemetry.js';
import { agentGroupRoutes } from './routes/agent-groups.js';
import { localJobRoutes } from './routes/jobs.js';
import { agentEntityRoutes } from './routes/agents.js';
import { automationRoutes } from './routes/automations.js';
import { identityRoutes } from './routes/identity.js';
import { agentRunRoutes } from './routes/agent-run.js';
import { agentRunsRoutes } from './routes/agent-runs.js';
import { localInferenceRoutes } from './routes/local-inference.js';
import { OfflineManager } from './offline-manager.js';
import { listOllamaChatModelIds } from './model-availability.js';
import { log, createLogger } from './logger.js';
import { installErrorHandler } from './error-handler.js';
import { seedDefaultCrons } from './setup-crons.js';
import { registerConnectors } from './setup-connectors.js';
import {
cronScheduleHasReadOnlyViewerTarget,
securityMiddleware,
} from './security-middleware.js';
import { LocalScheduler, makeRecordExecutionCallback } from './cron.js';
import {
generateMorningBriefing,
checkStaleWorkspaces,
checkPendingTasks,
suggestCapabilities,
type ProactiveContext,
type ProactiveMessage,
} from './proactive-handlers.js';
import { MAX_WORKSPACE_SESSIONS, WorkspaceSessionManager } from './workspace-sessions.js';
import { EventEmitter } from 'node:events';
import { LocalJobStore } from './job-store.js';
import { AgentRunRegistry } from './agent-run-registry.js';
import { ExecutorRegistry } from './executor-registry.js';
import { copyProviderKeysToVault, hydrateProviderEnvFromVault } from './provider-env.js';
export interface LocalConfig {
port: number;
host: string;
dataDir: string; // ~/.waggle
litellmUrl: string; // http://localhost:4000
/** Immutable desktop-launch identity used to prove sidecar ownership. */
instanceId?: string;
/** Governed CLI execution — allowlist of program names the agent may run. */
cli?: { allowlist?: string[] };
/** True only when startService owns the LiteLLM child lifecycle. */
manageLiteLLM?: boolean;
/** Stable child-process port, retained even while requests use a fallback proxy. */
managedLiteLLMPort?: number;
/** Route all agent-loop traffic through this server's built-in provider proxy. */
useBuiltInProxy?: boolean;
/** False when a managed caller must resolve provider state before health probes start. */
startOfflineManagerOnListen?: boolean;
}
/** Pending approval request — resolved when user approves or denies. */
export interface PendingApproval {
resolve: (approved: boolean) => void;
toolName: string;
input: Record<string, unknown>;
timestamp: number;
riskLevel?: RiskLevel;
}
/**
* Shared agent state — initialized once at server startup,
* accessible by all route modules for feature parity with CLI.
*/
/** LLM provider health: healthy (verified), degraded (configured, not verified), unavailable */
export type LlmHealthStatus = 'healthy' | 'degraded' | 'unavailable';
/** Which LLM provider is active and its runtime health */
export interface LlmProviderStatus {
/** Which provider is handling LLM requests */
provider: 'litellm' | 'anthropic-proxy' | 'ollama';
/** Runtime health — truthful, not optimistic */
health: LlmHealthStatus;
/** Human-readable detail (e.g. "LiteLLM on port 4000" or "No API key configured") */
detail: string;
/** When this status was last checked */
checkedAt: string;
}
export interface WorkspaceCollaborationBinding {
/** Tools visible to the owning turn after persona, availability, and intent filtering. */
visibleTools: ToolDefinition[];
/** Broader policy-filtered pool from which child workers receive their tools. */
workerTools: ToolDefinition[];
runLoop: AgentRunner;
signal: AbortSignal;
runChildTransaction: (
tools: readonly ToolDefinition[],
operation: () => Promise<import('@waggle/agent').AgentResponse>,
) => Promise<import('@waggle/agent').AgentResponse>;
defaultModel: string;
}
const WORKSPACE_COLLABORATION_TOOL_NAMES = new Set([
'spawn_agent',
'list_agents',
'get_agent_result',
'compose_workflow',
'orchestrate_workflow',
'list_harnesses',
'run_harness',
]);
export type WorkspaceCollaborationToolFactory = (
workerTools: ToolDefinition[],
runLoop: AgentRunner,
defaultModel: string,
signal?: AbortSignal,
) => ToolDefinition[];
export function bindWorkspaceChildTools(
options: WorkspaceCollaborationBinding,
createTools: WorkspaceCollaborationToolFactory,
): ToolDefinition[] {
const enabledNames = new Set(options.visibleTools.map((tool) => tool.name));
const workerTools = options.workerTools.filter(
(tool) => !WORKSPACE_COLLABORATION_TOOL_NAMES.has(tool.name),
);
const childRunLoop: AgentRunner = (config) => options.runChildTransaction(
config.tools,
() => options.runLoop({ ...config, signal: options.signal }),
);
const replacements = createTools(
workerTools,
childRunLoop,
options.defaultModel,
options.signal,
).filter((tool) => enabledNames.has(tool.name));
return [
...options.visibleTools.filter(
(tool) => !WORKSPACE_COLLABORATION_TOOL_NAMES.has(tool.name),
),
...replacements,
];
}
export interface AgentState {
orchestrator: Orchestrator;
allTools: ToolDefinition[];
hookRegistry: HookRegistry;
costTracker: CostTracker;
skills: LoadedSkill[];
userSystemPrompt: string | null;
sessionHistories: Map<string, import('./routes/chat-persistence.js').ChatHistoryMessage[]>;
currentModel: string;
litellmApiKey: string;
pendingApprovals: Map<string, PendingApproval>;
/** Serializes checkout-reading/writing agent turns by canonical physical root. */
workspaceTurnCoordinator: WorkspaceTurnCoordinator;
/** Phase B.3: persistent "always allow" grant store for gated tools. */
approvalGrantStore: import('./approval-grants.js').ApprovalGrantStore;
/**
* Rebuild workspace-scoped tools (system, git, document) for a given directory.
* Optional `orchForMindTools` replaces the shared-orchestrator mind tools with a
* session-specific orchestrator's tools so concurrent sessions don't collide.
*/
buildToolsForWorkspace: (workspacePath: string, orchForMindTools?: Orchestrator, workspaceId?: string) => ToolDefinition[];
/**
* Create a fresh Orchestrator for a workspace session with the given mind mounted.
* Each session gets its own instance (Option Y fix from docs/plans/phase-a-the-room.md §9).
*/
createSessionOrchestrator: (workspaceId?: string) => Orchestrator;
/**
* Build the full tool pool for a session, using the session's orchestrator for mind tools.
* When `sourceWorkspaceId` is provided, also injects Phase B.2 cross-workspace read tools
* (read_other_workspace, list_workspaces, list_workspace_files) scoped to that source.
*/
buildToolsForSession: (sessionOrch: Orchestrator, workspacePath: string, sourceWorkspaceId?: string) => ToolDefinition[];
/**
* Recreate collaboration producers after primitive workspace tools are lease-wrapped.
* The fresh producers run each child loop as one scope-local transaction.
*/
bindWorkspaceCollaborationTools: (options: WorkspaceCollaborationBinding) => ToolDefinition[];
/**
* Activate workspace mind for the given workspace ID. Returns true if switched.
* @deprecated — use `sessionManager.getOrCreate()` with `createSessionOrchestrator`
* and `buildToolsForSession` instead. This legacy path uses a shared orchestrator
* singleton and is unsafe for concurrent sessions. Being migrated per Phase A.1.
*/
activateWorkspaceMind: (workspaceId: string) => boolean;
/** Close a workspace's live sessions and detach it from the shared orchestrator. Used before workspace deletion. */
releaseWorkspace: (workspaceId: string) => void;
/** List all workspaces (id + name). Used by global memory search. */
listWorkspaces: () => Array<{ id: string; name: string }>;
/** Currently active workspace ID (null = personal only) */
activeWorkspaceId: string | null;
/** Current sub-agent orchestrator instance (set during workflow execution) */
subagentOrchestrator: import('@waggle/agent').SubagentOrchestrator | null;
/** Plugin runtime manager — lifecycle, tools, skills from plugins */
pluginRuntimeManager: import('@waggle/sdk').PluginRuntimeManager;
/** MCP server runtime — stdio servers, health, tools */
mcpRuntime: import('@waggle/agent').McpRuntime;
/** Steal #6: relevance-gates MCP tools into the model pool per conversation */
mcpToolRetriever: import('@waggle/agent').McpToolRetriever;
/** Command registry — slash commands */
commandRegistry: import('@waggle/agent').CommandRegistry;
/** LLM provider status — which provider is active and whether it's truly healthy */
llmProvider: LlmProviderStatus;
/** Session token for WebSocket authentication (generated on server startup) */
wsSessionToken: string;
/** SHA-256 hash of the paired Browser Companion credential, or null when unpaired. */
browserCompanionCredentialHash: string | null;
}
declare module 'fastify' {
interface FastifyInstance {
localConfig: LocalConfig;
workspaceManager: WorkspaceManager;
eventBus: EventEmitter;
agentRunner?: AgentRunner;
agentState: AgentState;
auditStore: InstallAuditStore;
cronStore: import('@waggle/core').CronStore;
waggleDb: import('@waggle/core').WaggleDB;
/** Memory (ADR-0007): personal and workspace memories, reached only through the contract. */
memory: MemoryStore;
/** Background fact extraction from chat turns (ADR-0007, decision 6). */
memoryExtraction: MemoryExtractionQueue;
traceStore: import('@waggle/core').ExecutionTraceStore;
/** Active behavioral spec — the compiled `BEHAVIORAL_SPEC` baseline. */
activeBehavioralSpec: ReturnType<typeof import('@waggle/agent').buildActiveBehavioralSpec>;
vault: import('@waggle/core').SecretStore;
embeddingProvider: import('@waggle/core').EmbeddingProviderInstance;
skillHashStore: import('@waggle/core').SkillHashStore;
scheduler: import('./cron.js').LocalScheduler;
marketplace: import('@waggle/marketplace').MarketplaceDB | null;
offlineManager: OfflineManager;
rateLimiter: import('./security-middleware.js').RateLimiter;
telemetry: import('@waggle/core').TelemetryStore;
connectorRegistry: import('@waggle/agent').ConnectorRegistry;
sessionManager: import('./workspace-sessions.js').WorkspaceSessionManager;
/**
* Bridges workflow-harness phase events into the execution trace store
* so harnessed runs show up in cost tracking and run history.
* Started at boot, stopped on close.
*/
harnessTraceBridge: HarnessTraceBridge;
/** Clears the cached LLM key-validation result; called by the settings route after a key update. */
_invalidateKeyValidationCache?: () => void;
}
}
const LOOPBACK_BOOTSTRAP_HOSTS = new Set(['127.0.0.1', 'localhost', '::1']);
function loopbackAuthorityMatchesRequest(
rawOrigin: string,
rawHost: string | undefined,
): boolean {
if (!rawHost) return false;
try {
const origin = new URL(rawOrigin);
const requestUrl = new URL(`http://${rawHost}`);
const originHost = origin.hostname.replace(/^\[|\]$/g, '');
const requestHost = requestUrl.hostname.replace(/^\[|\]$/g, '');
return origin.protocol === 'http:'
&& origin.username === ''
&& origin.password === ''
&& LOOPBACK_BOOTSTRAP_HOSTS.has(originHost)
&& LOOPBACK_BOOTSTRAP_HOSTS.has(requestHost)
&& origin.host === requestUrl.host;
} catch {
return false;
}
}
function browserBootstrapAuthorityAllowed(request: FastifyRequest): boolean {
const secFetchSite = request.headers['sec-fetch-site'];
if (secFetchSite !== undefined && secFetchSite !== 'same-origin') return false;
const rawOrigin = request.headers.origin ?? request.headers.referer;
if (!rawOrigin) return secFetchSite === 'same-origin';
return loopbackAuthorityMatchesRequest(rawOrigin, request.headers.host);
}
function desktopBootstrapMatches(
rawHeader: string | string[] | undefined,
expected: string | null,
): boolean {
if (!expected || typeof rawHeader !== 'string') return false;
const actualBytes = Buffer.from(rawHeader);
const expectedBytes = Buffer.from(expected);
return actualBytes.length === expectedBytes.length
&& crypto.timingSafeEqual(actualBytes, expectedBytes);
}
export async function buildLocalServer(config: Partial<LocalConfig> = {}) {
const fullConfig: LocalConfig = {
port: parseInt(process.env.WAGGLE_PORT ?? '3333'),
host: resolveBindHost(),
dataDir: config.dataDir ?? process.env.WAGGLE_DATA_DIR ?? '',
litellmUrl: config.litellmUrl ?? 'http://localhost:4000',
...config,
instanceId: config.instanceId ?? process.env.WAGGLE_INSTANCE_ID,
};
const managedDesktopBootstrap = typeof fullConfig.instanceId === 'string'
&& fullConfig.instanceId.trim().length > 0;
const rawDesktopBootstrapToken = process.env.WAGGLE_DESKTOP_BOOTSTRAP_TOKEN?.trim();
// The credential is needed only to bind this server instance to its Tauri
// launcher. Remove it before any tool discovery or child process can inherit it.
delete process.env.WAGGLE_DESKTOP_BOOTSTRAP_TOKEN;
const desktopBootstrapToken = rawDesktopBootstrapToken
&& rawDesktopBootstrapToken.length >= 32
&& rawDesktopBootstrapToken.length <= 200
? rawDesktopBootstrapToken
: null;
const server = Fastify({ logger: false });
const localJobStore = new LocalJobStore();
server.decorate('localJobStore', localJobStore);
const agentRunRegistry = new AgentRunRegistry(path.join(fullConfig.dataDir, 'agent-runs.json'));
server.decorate('agentRunRegistry', agentRunRegistry);
// ── Global error handler ──
// Fastify's own logger is disabled here, so without this an unhandled route
// exception logs nowhere and leaks raw err.message in the 500 body. One handler
// for the whole instance: 4xx pass through; 5xx log full context via `log` and
// return a generic envelope (message only outside production). See error-handler.ts.
installErrorHandler(server, log);
// Decorate with local config
server.decorate('localConfig', fullConfig);
// Set data dir for custom personas (loaded from ~/.waggle/personas/)
setPersonaDataDir(fullConfig.dataDir);
// Event bus (replaces Redis pub/sub)
const eventBus = new EventEmitter();
server.decorate('eventBus', eventBus);
// Workspace manager
const wsManager = new WorkspaceManager(fullConfig.dataDir);
const defaultWorkspaceConfig = wsManager.ensureDefault();
const defaultWorkspaceId = defaultWorkspaceConfig.id;
server.decorate('workspaceManager', wsManager);
// Waggle's own data (automations, notifications, cost tracking, profile and
// awareness) lives in waggle.db, apart from memory (ADR-0007).
const waggleDb = WaggleDB.openInDataDir(fullConfig.dataDir);
server.decorate('waggleDb', waggleDb);
// Install audit store — persistent trail for capability install events.
const auditStore = new InstallAuditStore(waggleDb);
server.decorate('auditStore', auditStore);
// Cron store — SQLite-backed schedule persistence for Solo
const cronStore = new CronStore(waggleDb);
server.decorate('cronStore', cronStore);
seedDefaultCrons(cronStore);
// Execution trace store — persistent log of agent runs (cost tracking, run history)
const traceStore = new ExecutionTraceStore(waggleDb);
server.decorate('traceStore', traceStore);
// Workflow-harness → trace bridge. Any harness phase that completes or
// aborts anywhere in the app emits on the shared `harnessEvents` emitter;
// this bridge translates those into rows in `execution_traces` so harness
// runs show up in cost tracking.
const harnessTraceBridge = new HarnessTraceBridge({
recorder: new TraceRecorder(traceStore),
});
harnessTraceBridge.start();
server.decorate('harnessTraceBridge', harnessTraceBridge);
server.addHook('onClose', async () => {
harnessTraceBridge.stop();
});
server.decorate('activeBehavioralSpec', buildActiveBehavioralSpec());
// Vault — encrypted secret storage
const vault = new VaultStore(fullConfig.dataDir);
server.decorate('vault', vault);
// Vault is canonical; env is the compatibility layer for provider SDKs.
let hydrated = hydrateProviderEnvFromVault(vault);
// Pass-through secrets whose vault name already matches the env var name
for (const passthrough of ['TAVILY_API_KEY', 'BRAVE_API_KEY']) {
const entry = vault.get(passthrough);
if (entry?.value && !process.env[passthrough]) {
process.env[passthrough] = entry.value;
hydrated++;
}
}
if (hydrated > 0) {
log.info(`Hydrated ${hydrated} env var(s) from vault for provider SDKs`);
}
// M2-7: Telemetry — local, opt-in, privacy-first
const waggleConfigForTelemetry = new WaggleConfig(fullConfig.dataDir);
const telemetry = new TelemetryStore(fullConfig.dataDir, waggleConfigForTelemetry.getTelemetryEnabled());
server.decorate('telemetry', telemetry);
telemetry.track(TELEMETRY_EVENTS.APP_START, { version: '0.2.0', platform: process.platform });
// embeddingProvider decorated later after creation (needs vault for API keys)
// Migrate plaintext keys from config.json to vault on first run
try {
const waggleConfig = new WaggleConfig(fullConfig.dataDir);
const configProviders = waggleConfig.getProviders();
if (Object.keys(configProviders).length > 0) {
const migrated = copyProviderKeysToVault(vault, configProviders);
let scrubbed = 0;
for (const [name, provider] of Object.entries(configProviders)) {
if (!provider.apiKey) continue;
waggleConfig.setProvider(name, { ...provider, apiKey: '' });
scrubbed++;
}
if (scrubbed > 0) waggleConfig.save();
if (migrated > 0) {
log.info(` Migrated ${migrated} API key(s) to encrypted vault`);
}
if (scrubbed > 0) {
log.info(` Scrubbed ${scrubbed} plaintext provider key(s) from config`);
}
}
} catch {
// Migration failure should never block startup
}
// Connector Registry — manages registered connectors and generates dynamic tools
const connectorRegistry = registerConnectors(vault);
server.decorate('connectorRegistry', connectorRegistry);
// Seed marketplace.db if not present, then open it for production routes
let marketplaceDb: MarketplaceDB | null = null;
try {
const marketplaceDbTarget = path.join(fullConfig.dataDir, 'marketplace.db');
if (!fs.existsSync(marketplaceDbTarget)) {
// Packaged service.js and marketplace.db are sibling Tauri resources.
// Development and built-package candidates follow for non-Tauri runs.
// __dirname resolves to packages/server/src/local during tsx dev, and
// to packages/server/dist/local after a build — both need ../../..
// to reach the packages/ root, plus a fallback for the production bundle.
const seedPaths = [
path.resolve(__dirname, 'marketplace.db'), // packaged Tauri resource
path.resolve(__dirname, '../../../marketplace/marketplace.db'), // dev: tsx from src/local
path.resolve(__dirname, '../../../../marketplace/marketplace.db'), // built: dist/local
path.resolve(__dirname, '../../../../packages/marketplace/marketplace.db'),
path.resolve(__dirname, '../../../../../packages/marketplace/marketplace.db'),
];
for (const seedPath of seedPaths) {
if (fs.existsSync(seedPath)) {
fs.copyFileSync(seedPath, marketplaceDbTarget);
log.info(` Seeded marketplace.db from ${seedPath}`);
break;
}
}
}
if (fs.existsSync(marketplaceDbTarget)) {
marketplaceDb = new MarketplaceDB(marketplaceDbTarget);
// Seed MCP server registry entries if not already present
try {
const mcpAdded = seedMcpServers(marketplaceDb);
if (mcpAdded > 0) {
log.info(` Seeded ${mcpAdded} MCP servers into marketplace`);
}
} catch (err) {
log.warn(` MCP registry seed failed: ${(err as Error).message}`);
}
// Seed new marketplace sources (skills.sh, mcpmarket, npm, awesome-mcp-servers, etc.)
try {
const sourcesAdded = seedNewSources(marketplaceDb);
if (sourcesAdded > 0) {
log.info(` Seeded ${sourcesAdded} new marketplace sources`);
}
} catch (err) {
log.warn(` Source seed failed: ${(err as Error).message}`);
}
log.info(' Marketplace DB loaded');
}
} catch (err) {
log.warn(` Marketplace DB failed to load: ${(err as Error).message}`);
// Marketplace is optional — never block startup
}
server.decorate('marketplace', marketplaceDb);
const capabilityProposalStore = new CapabilityProposalStore();
server.decorate('capabilityProposalStore', capabilityProposalStore);
// ── Daily marketplace sync (non-blocking, 60s delay after startup) ──
const stopMarketplaceBackgroundSync = scheduleMarketplaceBackgroundSync({ marketplaceDb, log });
// ── Agent state (matches CLI initialization) ────────────────────────
const wsSessionToken = crypto.randomBytes(32).toString('hex');
const storedBrowserCompanionHash = vault.get(BROWSER_COMPANION_CREDENTIAL_VAULT_KEY)?.value;
const browserCompanionCredentialHash = isBrowserCompanionCredentialHash(storedBrowserCompanionHash)
? storedBrowserCompanionHash
: null;
const litellmApiKey = fullConfig.useBuiltInProxy
? wsSessionToken
: process.env.LITELLM_API_KEY ?? process.env.LITELLM_MASTER_KEY ?? 'sk-waggle-dev';
// Build embedding config from WaggleConfig + Vault keys
const waggleConfig = new WaggleConfig(fullConfig.dataDir || undefined);
fullConfig.cli = { allowlist: waggleConfig.getCliAllowlist() };
const embeddingConfig: EmbeddingProviderConfig = waggleConfig.getEmbeddingConfig();
// Inject API keys from encrypted Vault (never from config.json)
try {
const voyageEntry = vault.get('voyage-api-key');
if (voyageEntry?.value) embeddingConfig.voyage = { apiKey: voyageEntry.value };
} catch { /* vault may not have this key */ }
try {
const openaiEntry = vault.get('openai');
if (openaiEntry?.value) embeddingConfig.openai = { apiKey: openaiEntry.value };
} catch { /* vault may not have this key */ }
// Environment variable override for CI/headless
if (process.env.VOYAGE_API_KEY && !embeddingConfig.voyage) {
embeddingConfig.voyage = { apiKey: process.env.VOYAGE_API_KEY };
}
if (process.env.OPENAI_API_KEY && !embeddingConfig.openai) {
embeddingConfig.openai = { apiKey: process.env.OPENAI_API_KEY };
}
// Create embedding provider with InProcess → Ollama → API → Mock fallback chain
const embeddingProvider = await createEmbeddingProvider(embeddingConfig);
const embedder = embeddingProvider; // satisfies Embedder — drop-in replacement
// Decorate server with embedding provider for status endpoints
server.decorate('embeddingProvider', embeddingProvider);
const waggleHome = fullConfig.dataDir || path.join(os.homedir(), '.waggle');
const rerankerCacheDir = path.join(waggleHome, 'models', 'reranker');
// Memory (ADR-0007): one mem0 store in <dataDir>/memory/, embedded by the
// in-process model. Facts are extracted with the model the user chose,
// through the built-in proxy (or LiteLLM when the user runs it).
const memory = await openMemoryStore({
dataDir: fullConfig.dataDir,
modelCacheDir: embeddingConfig.inprocess?.cacheDir ?? path.join(waggleHome, 'models'),
embeddingModel: embeddingConfig.inprocess?.model,
extraction: {
baseURL: fullConfig.useBuiltInProxy
? `http://127.0.0.1:${fullConfig.port}/v1`
: fullConfig.litellmUrl,
apiKey: litellmApiKey,
model: () => server.agentState?.currentModel || 'claude-sonnet-4-6',
},
});
server.decorate('memory', memory);
const memoryExtraction = new MemoryExtractionQueue({
memory,
isEnabled: () => new WaggleConfig(fullConfig.dataDir).getMemoryExtraction(),
onError: (err) => log.warn(`[memory] fact extraction failed: ${err instanceof Error ? err.message : String(err)}`),
});
server.decorate('memoryExtraction', memoryExtraction);
// Orchestrator — personal memory; a workspace is added with setWorkspace()
const orchestrator = new Orchestrator({
memory,
waggleDb,
mode: 'local',
version: '0.4',
rerankerCacheDir,
});
ensureIdentity(orchestrator.getIdentity());
// Build tools — use a default workspace (homedir), but tools are rebuilt
// per-request when a workspace directory is specified in chat.
const defaultWorkspace = os.homedir();
const mindTools = orchestrator.getTools();
const systemTools = createSystemTools({
workspace: defaultWorkspace,
denySensitiveFiles: true,
});
const planTools = createPlanTools();
const gitTools = createGitTools(defaultWorkspace);
const documentTools = [
...createDocumentTools(defaultWorkspace),
...createSpreadsheetTools(defaultWorkspace),
...createPresentationTools(defaultWorkspace),
...createPdfTools(defaultWorkspace),
];
// Skill management tools — let the agent discover, install, create, and acquire skills
const starterSkillsDir = getStarterSkillsDir();
const skillTools = createSkillTools({
waggleHome,
starterSkillsDir,
auditStore,
nativeToolNames: [
...mindTools.map(t => t.name),
...systemTools.map(t => t.name),
...planTools.map(t => t.name),
...gitTools.map(t => t.name),
...documentTools.map(t => t.name),
],
getInstalledSkills: () => {
// Return the current in-memory skill state (hot-reloadable)
return server.agentState?.skills ?? loadSkills(waggleHome);
},
onSkillsChanged: () => {
// Hot-reload skills into agent state
const fresh = loadSkills(waggleHome);
// Will be set after agentState is created (see below)
reloadSkills?.(fresh);
},
searchMarketplace: async (query: string) => {
// Search the marketplace DB if available (graceful degradation)
if (!marketplaceDb) return [];
try {
const results = marketplaceDb.search({ query, limit: 10 });
return results.packages.map(pkg => ({
packageId: pkg.id,
name: pkg.name,
description: pkg.description,
packageType: pkg.package_type,
installType: pkg.waggle_install_type,
version: pkg.version,
author: pkg.author,
source: 'marketplace',
score: undefined, // FTS5 doesn't expose raw scores through our API
}));
} catch {
return [];
}
},
});
// Cron tools — let the agent manage cron schedules (via REST API).
// The chat route replaces surviving cron tools with request-bound copies so
// overlapping turns cannot exchange delivery origins.
const cronTools = createCronTools();
// Search tools — Tavily + Brave with vault-backed API keys
const searchTools = createSearchTools(async (key: string) => {
try { return vault.get(key)?.value ?? null; } catch { return null; }
});
// Browser tools — Playwright-based browser automation
const browserTools = createBrowserTools(defaultWorkspace);
// LSP tools — TypeScript language server integration
const lspTools = createLspTools(defaultWorkspace);
// CLI tools — governed CLI program execution
const cliAllowlist = fullConfig.cli?.allowlist ?? [];
const cliTools = createCliTools({
allowlist: cliAllowlist,
getAllowlist: () => fullConfig.cli?.allowlist ?? [],
});
// Dynamic connector tools (initial — regenerated per workspace in buildToolsForWorkspace)
const defaultConnectorTools = connectorRegistry.generateTools();
// Connector search tools — give the agent natural-language discovery over
// the 148-entry MCP catalog (find_connector, list_connector_categories).
// Static data, zero I/O, no deps — cheap to always-include.
const connectorSearchTools = createConnectorSearchTools();
// Collect all non-subagent tools first (sub-agent tools need the full list)
const baseTools = [...mindTools, ...systemTools, ...planTools, ...gitTools, ...documentTools, ...skillTools, ...cronTools, ...searchTools, ...browserTools, ...lspTools, ...cliTools, ...connectorSearchTools, ...defaultConnectorTools];
// PR4: expose the full native-tool name union to the agent-search route so
// its "you already have a tool for this" lane isn't blind to search/browser/
// cli/cron/connector tools (the agent's own union omits them).
server.decorate('agentToolNames', baseTools.map(t => t.name));
// Sub-agent tools — let the main agent spawn specialist sub-agents.
// onSubAgentStatus relays start/done/error transitions to the notifications
// SSE stream so the Room canvas can render live tiles for sub-agents
// spawned via spawn_agent (bug #9). Without this wiring, sub-agents ran
// silently and Room stayed empty.
//
// onSubAgentComplete persists the result into the active mind (workspace if
// active, else personal) so specialist work survives beyond the 30-min
// in-memory eviction window — Skills 2.0 gap L.
const subAgentTools = createSubAgentTools({
availableTools: baseTools,
runLoop: runAgentLoop,
get litellmUrl() { return fullConfig.litellmUrl; },
litellmApiKey: litellmApiKey,
defaultModel: 'claude-sonnet-4-6',
onSubAgentStatus: (event) => {
emitSubagentStatus(server, server.agentState.activeWorkspaceId ?? defaultWorkspaceId, [{
id: event.agentId,
name: event.name,
role: event.role,
// emitSubagentStatus uses the workflow-orchestrator vocabulary
// ('failed' vs our internal 'error'); map at the boundary.
status: event.status === 'error' ? 'failed' : event.status,
task: event.task,
toolsUsed: event.toolsUsed,
startedAt: event.startedAt,
completedAt: event.completedAt,
}]);
},
onSubAgentComplete: async (result) => {
// Gap L — persist sub-agent result to the active mind so specialist
// work is searchable after the 30-min in-memory cache evicts.
// Best-effort: any failure is swallowed by subagent-tools so the
// main-agent-visible return path stays intact.
try {
const wsId = server.agentState.activeWorkspaceId;
const scope = wsId ? workspaceScope(wsId) : PERSONAL_SCOPE;
// Structured content: tag provenance so humans can see where it came from.
const content = `[Sub-agent: ${result.role}] ${result.agentName}\n\n${result.response}\n\n— tools: ${result.toolsUsed.join(', ') || 'none'} · ${(result.duration / 1000).toFixed(1)}s · ${result.usage.inputTokens + result.usage.outputTokens} tokens`;
await memory.remember({
scope,
text: content,
kind: 'note',
source: 'agent_inferred',
origin: 'sub-agent',
});
log.debug(`Gap L: persisted sub-agent result ${result.agentId} to ${wsId ? `workspace:${wsId}` : 'personal'} memory`);
} catch (err) {
log.debug('Gap L: sub-agent persistence failed (non-blocking)', err);
}
},
});
// Workflow tools — multi-agent workflow templates (research, review, plan-execute)
const workflowTools = createWorkflowTools({
availableTools: baseTools,
runLoop: runAgentLoop,
get litellmUrl() { return fullConfig.litellmUrl; },
litellmApiKey: litellmApiKey,
defaultModel: 'claude-sonnet-4-6',
onWorkerStatus: (event) => {
// Relay sub-agent status to eventBus for SSE notification stream
const orch = server.agentState.subagentOrchestrator;
const agents = orch ? orch.getWorkers().map(w => ({
id: w.id,
name: w.name,
role: w.role,
status: w.status,
task: w.task,
toolsUsed: w.toolsUsed,
startedAt: w.startedAt,
completedAt: w.completedAt,
})) : [{
id: event.workerId,
name: event.workerState.name,
role: event.workerState.role,
status: event.workerState.status,
task: event.workerState.task,
toolsUsed: event.workerState.toolsUsed,
startedAt: event.workerState.startedAt,
completedAt: event.workerState.completedAt,
}];
emitSubagentStatus(server, server.agentState.activeWorkspaceId ?? defaultWorkspaceId, agents);
},
});
const allTools = [...baseTools, ...subAgentTools, ...workflowTools];
// Load user customizations from ~/.waggle/
const userSystemPrompt = loadSystemPrompt(waggleHome);
const skills = loadSkills(waggleHome);
// Skill hash store — detect skill changes on disk
const skillHashStore = new SkillHashStore(waggleDb);
server.decorate('skillHashStore', skillHashStore);
// Check for changed skills at startup
const hashCheck = skillHashStore.checkAll(skills);
// Auto-verify new skills (first install — no change to flag)
for (const name of hashCheck.added) {
const skill = skills.find(s => s.name === name);
if (skill) skillHashStore.verify(name, skill.content);
}
// Log changed skills as warnings
if (hashCheck.changed.length > 0) {
log.info(` WARNING: ${hashCheck.changed.length} skill(s) changed on disk: ${hashCheck.changed.join(', ')}`);
log.info(' Run /skills to review changes');
}
// Clean up removed skill hashes
for (const name of hashCheck.removed) {
skillHashStore.removeHash(name);
}
// Hook registry with user-configured hooks
const hookRegistry = new HookRegistry();
await loadHooksFromConfig(path.join(waggleHome, 'hooks.json'), hookRegistry);
// Cost tracker
const costTracker = new CostTracker({});
const budgetConfig = new WaggleConfig(fullConfig.dataDir);
costTracker.setBudget(
budgetConfig.getDailyBudget(),
budgetConfig.getBudgetHardCap() ? 'hard' : 'soft',
);
const budgetDay = new Date().toISOString().slice(0, 10);
const budgetDayStart = `${budgetDay}T00:00:00.000Z`;
try {
costTracker.initializeDailyCarryover(
budgetDay,
traceStore.getTotalCostSince(budgetDayStart, traceStore.getLatestId()),
);
} catch (error) {
if (budgetConfig.getBudgetHardCap() && budgetConfig.getDailyBudget() !== null) {
throw new Error('Cannot initialize hard daily model budget from persisted spend', { cause: error });
}
server.log.warn({ err: error }, 'Persisted daily model spend unavailable');
}
// Command registry — workflow-native slash commands
const commandRegistry = new CommandRegistry();
registerWorkflowCommands(commandRegistry);
registerMarketplaceCommands(commandRegistry);
// Plugin runtime manager — lifecycle, tools, skills from plugins
const pluginRuntimeManager = new PluginRuntimeManager();
// Auto-load installed plugins from ~/.waggle/plugins/
const pluginsDir = path.join(waggleHome, 'plugins');
if (fs.existsSync(pluginsDir)) {
try {
const pluginDirs = fs.readdirSync(pluginsDir, { withFileTypes: true })
.filter(d => d.isDirectory())
.map(d => d.name);
for (const pluginName of pluginDirs) {
const pluginPath = path.join(pluginsDir, pluginName);
const manifestPath = path.join(pluginPath, 'plugin.json');
if (!fs.existsSync(manifestPath)) continue;
try {
const raw = JSON.parse(fs.readFileSync(manifestPath, 'utf-8')) as Record<string, unknown>;
const validation = validatePluginManifest(raw);
if (!validation.valid) {
log.info(` Skipping plugin "${pluginName}": invalid manifest — ${validation.errors.join(', ')}`);
continue;
}
pluginRuntimeManager.register(
raw as unknown as Parameters<typeof pluginRuntimeManager.register>[0],
{ pluginDir: pluginPath },
);
await pluginRuntimeManager.enable(raw.name as string);
} catch (err) {
log.info(` Failed to load plugin "${pluginName}": ${(err as Error).message}`);
}
}
const active = pluginRuntimeManager.getActive();
if (active.length > 0) {
log.info(` Loaded ${active.length} plugin(s): ${active.map(p => p.getManifest().name).join(', ')}`);
}
} catch { /* non-blocking — plugin scan failure must not prevent startup */ }
}
// MCP server runtime — stdio servers, health, tools.
// UX-Refactor Phase 4 (C4): populated at boot from the persisted
// <dataDir>/.mcp.json (written by the marketplace installer + /api/mcps).
// Register-only — servers stay 'stopped' until started via
// POST /api/mcps/:id/start, so boot never spawns surprise processes.
const mcpRuntime = new McpRuntime();
populateMcpRuntimeFromConfig(mcpRuntime, fullConfig.dataDir, log);
// Steal #6: relevance-gates MCP tools into the model pool. Holds the lazy
// embedding index + per-conversation union-only accumulator; the mock-embedder
// fallback keeps it honest when semantic embeddings are unavailable.
const mcpToolRetriever = new McpToolRetriever({ embedder });
// Session histories (server-side, like CLI)
const sessionHistories = new Map<string, import('./routes/chat-persistence.js').ChatHistoryMessage[]>();
// Default model — W2C: initialize from config.json's defaultModel so the
// top-bar chip and Settings → Models agree from the first launch (this was
// hardcoded, so a user whose default was e.g. Opus saw Sonnet in the chip
// until they changed it). The literal is only the last-resort fallback.
const currentModel = new WaggleConfig(fullConfig.dataDir).getDefaultModel() || 'claude-sonnet-4-6';
// Pending approvals map for confirmation gates
const pendingApprovals = new Map<string, PendingApproval>();
const workspaceTurnCoordinator = new WorkspaceTurnCoordinator();
// Phase B.3: persistent "always allow" grant store — survives sessions
// so approved (tool, target) combinations don't re-prompt every time.
const { ApprovalGrantStore } = await import('./approval-grants.js');
const approvalGrantStore = new ApprovalGrantStore(fullConfig.dataDir);
// Skill hot-reload callback is defined as a const after agentState is created
// (see `reloadSkills` below); referenced lazily from the onSkillsChanged closure.
// L-18: Resolve a FileBackend for a workspace's storage type. Team (S3/MinIO)
// workspaces return a provider-backed FileBackend so the agent's file tools
// route through the shared bucket instead of the local filesystem. Local /
// virtual workspaces return undefined — system-tools falls back to fs.*
// and existing behavior is unchanged.
const buildFileBackendForWorkspace = (workspaceId: string | undefined) => {
if (!workspaceId) return undefined;
try {
const wsMeta = wsManager.get(workspaceId);
if (!wsMeta || wsMeta.storageType !== 'team') return undefined;
const provider = getStorageProvider(
{
id: wsMeta.id,
storageType: wsMeta.storageType,
storagePath: wsMeta.storagePath,
storageConfig: (wsMeta as unknown as { storageConfig?: Record<string, unknown> }).storageConfig,
},
fullConfig.dataDir,
);
return {
read: (p: string) => provider.read(p),
write: async (p: string, data: Buffer, mime?: string) => {
await provider.write(p, data, mime);
},
exists: (p: string) => provider.exists(p),
delete: (p: string) => provider.delete(p),
};
} catch (err) {
server.log.warn({ err, workspaceId }, 'Failed to build FileBackend for workspace');
return undefined;
}
};
const createWorkspaceCollaborationTools = (
workerTools: ToolDefinition[],
runLoop: AgentRunner,
defaultModel: string,
signal?: AbortSignal,
): ToolDefinition[] => {
const workspaceSubAgentTools = createSubAgentTools({
availableTools: workerTools,
runLoop,
get litellmUrl() { return fullConfig.litellmUrl; },
litellmApiKey,
defaultModel,
onSubAgentStatus: (event) => {
emitSubagentStatus(server, server.agentState.activeWorkspaceId ?? defaultWorkspaceId, [{
id: event.agentId,
name: event.name,
role: event.role,
status: event.status === 'error' ? 'failed' : event.status,
task: event.task,
toolsUsed: event.toolsUsed,
startedAt: event.startedAt,
completedAt: event.completedAt,
}]);
},
});
const workspaceWorkflowTools = createWorkflowTools({
availableTools: workerTools,
runLoop,
get litellmUrl() { return fullConfig.litellmUrl; },
litellmApiKey,
defaultModel,
signal,
onWorkerStatus: (event) => {
const orch = server.agentState.subagentOrchestrator;
const agents = orch ? orch.getWorkers().map(w => ({
id: w.id, name: w.name, role: w.role, status: w.status,
task: w.task, toolsUsed: w.toolsUsed, startedAt: w.startedAt, completedAt: w.completedAt,
})) : [{
id: event.workerId, name: event.workerState.name, role: event.workerState.role,
status: event.workerState.status, task: event.workerState.task,
toolsUsed: event.workerState.toolsUsed, startedAt: event.workerState.startedAt,
completedAt: event.workerState.completedAt,
}];
emitSubagentStatus(server, server.agentState.activeWorkspaceId ?? defaultWorkspaceId, agents);
},
});
return [...workspaceSubAgentTools, ...workspaceWorkflowTools];
};
const bindWorkspaceCollaborationTools = (
options: WorkspaceCollaborationBinding,
): ToolDefinition[] => bindWorkspaceChildTools(options, createWorkspaceCollaborationTools);
// Factory to rebuild workspace-scoped tools for a given directory.
// Optional `orchForMindTools` replaces the shared-orchestrator mind tools with
// a session-specific orchestrator's tools (Option Y fix from Phase A.1 plan).
const buildToolsForWorkspace = (
wsPath: string,
orchForMindTools?: Orchestrator,
workspaceId?: string,
): ToolDefinition[] => {
// Dynamic connector tools (only for connected connectors)
const connectorTools = connectorRegistry.generateTools();
// Resolve which mind tools to use — per-session (if provided) or the shared default.
// Per-session is required for concurrent multi-workspace chat; the shared default
// is kept for legacy call sites that are still being migrated.
const mindToolsForRequest = orchForMindTools
? orchForMindTools.getTools()
: mindTools;
// L-18: when the workspace is team-backed, route file tools through the
// shared provider. Otherwise pass only the cwd (fs fallback).
const fileBackend = buildFileBackendForWorkspace(workspaceId);
const wsMeta = workspaceId ? wsManager.get(workspaceId) : null;
const denySensitiveFiles = Boolean(wsMeta?.directory || wsMeta?.storagePath);
const wsBase = [
...mindToolsForRequest,
...createSystemTools({ workspace: wsPath, fileBackend, denySensitiveFiles }),
...createPlanTools(),
...createGitTools(wsPath),
...createDocumentTools(wsPath),
...createSpreadsheetTools(wsPath),
...createPresentationTools(wsPath),
...createPdfTools(wsPath),
...skillTools,
...cronTools,
...searchTools,
...createBrowserTools(wsPath),
...createLspTools(wsPath),
...cliTools,
...connectorTools,
];
return [
...wsBase,
...createWorkspaceCollaborationTools(wsBase, runAgentLoop, 'claude-sonnet-4-6'),
];
};
// ── Workspace Session Manager ────────────────────────────────────
// Manages concurrent workspace sessions with independent minds, orchestrators,
// and tools.
const sessionManager = new WorkspaceSessionManager(MAX_WORKSPACE_SESSIONS);
server.decorate('sessionManager', sessionManager);
/**
* Create a fresh Orchestrator for a workspace session.
*
* Each session gets its own instance so concurrent sessions on different
* workspaces cannot corrupt each other's workspace layers via setWorkspaceMind().
* Pointer to the shared personal mind is safe — better-sqlite3 WAL mode handles
* concurrent reads and serializes writes through SQLite's internal lock.
*
* See docs/plans/phase-a-the-room.md §9 for the Option X vs Option Y decision.
*/
const createSessionOrchestrator = (workspaceId?: string): Orchestrator => {
const sessionOrch = new Orchestrator({
memory,
waggleDb,
mode: 'local',
version: '0.4',
rerankerCacheDir,
});
if (workspaceId) sessionOrch.setWorkspace(workspaceId);
return sessionOrch;
};
/**
* Build the tool pool for a workspace session using the session's own orchestrator
* for mind tools. Includes cross-workspace read tools (Phase B.2) that capture
* the source workspace as a closure so cross-workspace citations identify both
* sides of the access.
*/
const buildToolsForSession = (
sessionOrch: Orchestrator,
wsPath: string,
sourceWorkspaceId?: string,
): ToolDefinition[] => {
// L-18: pass sourceWorkspaceId through so buildToolsForWorkspace can resolve
// the workspace's storage type and thread a FileBackend for team storage.
const base = buildToolsForWorkspace(wsPath, sessionOrch, sourceWorkspaceId);
if (!sourceWorkspaceId) return base;
const crossTools = createCrossWorkspaceTools({
sourceWorkspaceId,
memory,
listWorkspaces: () => wsManager.list().map(w => ({ id: w.id, name: w.name })),
listWorkspaceFiles: async (id, subPath) => {
try {
const entries = readFileRegistry(fullConfig.dataDir, id);
// FileRegistryEntry only has name/type/summary/sizeBytes/ingestedAt —
// there's no real path hierarchy for virtual storage, so we filter by
// name prefix when a subPath is provided.
const filtered = subPath
? entries.filter(e => e.name.startsWith(subPath))
: entries;
return filtered.map(e => ({
name: e.name,
type: 'file' as const,
size: e.sizeBytes,
modifiedAt: e.ingestedAt,
}));
} catch {
return [];
}
},
});
return [...base, ...crossTools];
};
let activeWorkspaceId: string | null = null;
const setActiveWorkspaceId = (workspaceId: string | null): void => {
activeWorkspaceId = workspaceId;
const decorated = (server as FastifyInstance & { agentState?: AgentState }).agentState;
if (decorated) decorated.activeWorkspaceId = workspaceId;
};
/** Make a workspace's memory active on the shared orchestrator. */
const activateWorkspaceMind = (workspaceId: string): boolean => {
if (activeWorkspaceId === workspaceId) return true; // already active
if (!wsManager.get(workspaceId)) return false;
orchestrator.setWorkspace(workspaceId);
setActiveWorkspaceId(workspaceId);
return true;
};
// Before a workspace is deleted: close its live sessions and detach it from
// the shared orchestrator.
const releaseWorkspace = (workspaceId: string): void => {
sessionManager.close(workspaceId);
if (activeWorkspaceId === workspaceId) {
orchestrator.setWorkspace(null);
setActiveWorkspaceId(null);
}
};
// Decorate with shared agent state
server.decorate('agentState', {
orchestrator,
allTools,
hookRegistry,
costTracker,
skills,
userSystemPrompt,
sessionHistories,
currentModel,
litellmApiKey,
pendingApprovals,
workspaceTurnCoordinator,
approvalGrantStore,
buildToolsForWorkspace,
createSessionOrchestrator,
buildToolsForSession,
bindWorkspaceCollaborationTools,
activateWorkspaceMind: activateWorkspaceMind,
releaseWorkspace,
listWorkspaces: () => wsManager.list().map(w => ({ id: w.id, name: w.name })),
activeWorkspaceId,
subagentOrchestrator: null,
pluginRuntimeManager,
mcpRuntime,
mcpToolRetriever,
commandRegistry,
llmProvider: {
provider: 'anthropic-proxy' as const,
health: 'unavailable' as const,
detail: 'Not yet initialized',
checkedAt: new Date().toISOString(),
},
wsSessionToken,
browserCompanionCredentialHash,
});
activateWorkspaceMind(defaultWorkspaceId);
// Wire up skill hot-reload callback
const reloadSkills = (fresh: LoadedSkill[]) => {
server.agentState.skills.length = 0;
server.agentState.skills.push(...fresh);
};
// Dream Diary — records the nightly curation runs below so /api/dreams can
// narrate them to the user (docs/plans/DREAM-DIARY-2026-07-09.md).
const dreamJournal = new DreamJournal(fullConfig.dataDir);
server.decorate('dreamJournal', dreamJournal);
const executorRegistry = new ExecutorRegistry({
detectTools: async () => (await detectInstalledTools()).tools,
personas: () => PERSONAS,
});
server.decorate('executorRegistry', executorRegistry);
// Local scheduler — runs cron jobs in-process (Solo, no Redis/BullMQ)
const persistCronHistory = makeRecordExecutionCallback(cronStore);
// #17: hard daily bound on ai_task firings per schedule — each firing is a
// full agent turn (real LLM spend), so a runaway cron must self-limit even
// past the create-time min-interval guard.
const AI_TASK_DAILY_CAP = 24;
const scheduler = new LocalScheduler(cronStore, async (schedule) => {
switch (schedule.job_type) {
case 'memory_consolidation': {
// Check if this is a marketplace sync (uses memory_consolidation type for system-level scheduling)
const mcJobConfig = JSON.parse(schedule.job_config || '{}');
if (mcJobConfig.action === 'marketplace_sync' && marketplaceDb) {
try {
const vaultLookup = server.vault ? (key: string) => server.vault!.get(key)?.value ?? null : undefined;
const sync = new MarketplaceSync(marketplaceDb, vaultLookup, (url, init) => safeFetch(url, init));
const results = await sync.syncAll();
const totalAdded = results.reduce((sum, r) => sum + r.added, 0);
if (totalAdded > 0) {
eventBus.emit('notification', {
type: 'notification',
timestamp: new Date().toISOString(),
title: 'Marketplace sync complete',
body: `${totalAdded} new capability${totalAdded === 1 ? '' : 's'} discovered`,
category: 'agent',
actionUrl: '/skills',
});
}
log.info(`[cron] Marketplace sync: ${totalAdded} added across ${results.length} sources`);
} catch (err) {
log.warn(`[cron] Marketplace sync failed: ${(err as Error).message}`);
}
}
// index_reconcile, harvest_sync, memory_compact, memory_lane_extract and
// plain consolidation maintained the legacy memory engine. mem0 indexes
// on write and background extraction replaces the lanes (ADR-0007), so
// schedules left over from the legacy data only run the retention below.
// UX-Refactor Phase 3: cron_execution_history retention. recordExecution
// now writes a row per tick (Journey 16), so prune >30-day rows on the
// same nightly consolidation cadence (mirrors optStore.pruneOlderThan).
try { cronStore.pruneExecutionHistory(30); } catch { /* best-effort */ }
// L2: flip held actions past their 7-day TTL to 'expired' so stale
// proposals stop being approvable and the queue doesn't grow unbounded.
try { cronStore.expireStalePendingActions(); } catch { /* best-effort */ }
break;
}
case 'workspace_health':
// Flagged memories untouched for a week; mem0 does not track access,
// so there is nothing to flag (ADR-0007).
break;
case 'proactive': {
const proactiveConfig = JSON.parse(schedule.job_config || '{}');
const proactiveCtx: ProactiveContext = {
dataDir: fullConfig.dataDir,
workspaceManager: wsManager,
memory,
waggleDb,
vault,
};
/** Emit a ProactiveMessage through the delivery router pipeline. */
const emitProactive = (msg: ProactiveMessage) => {
// Load delivery preferences from config (or use defaults)
let deliveryPrefs: DeliveryPreferences;
try {
const configPath = path.join(fullConfig.dataDir, 'delivery-preferences.json');
if (fs.existsSync(configPath)) {
deliveryPrefs = { ...createDefaultDeliveryPreferences(), ...JSON.parse(fs.readFileSync(configPath, 'utf-8')) };
} else {
deliveryPrefs = createDefaultDeliveryPreferences();
}
} catch {
deliveryPrefs = createDefaultDeliveryPreferences();
}
const inAppEmitter = (notification: { title: string; body: string; category: string; actionUrl?: string }) => {
emitNotification(
server,
{ ...notification, category: notification.category as 'cron' | 'agent' | 'task' },
msg.dedupeKey && msg.materialHash ? { dedupeKey: msg.dedupeKey, materialHash: msg.materialHash } : undefined,
);
};
deliverCronResult(
{ title: msg.title, body: msg.body, jobType: msg.type, workspaceId: msg.workspaceId, priority: msg.priority },
deliveryPrefs,
server.connectorRegistry,
inAppEmitter,
).catch(err => log.warn(`[cron-delivery] Delivery failed: ${(err as Error).message}`));
};
try {
switch (proactiveConfig.action) {
case 'morning_briefing': {
const briefing = await generateMorningBriefing(proactiveCtx);
if (briefing) emitProactive(briefing);
break;
}
case 'stale_workspace_check': {
const staleAlerts = await checkStaleWorkspaces(proactiveCtx);
for (const alert of staleAlerts) emitProactive(alert);
break;
}
case 'task_reminder': {
const reminders = checkPendingTasks(proactiveCtx);
for (const reminder of reminders) emitProactive(reminder);
break;
}
case 'capability_suggestion': {
const suggestion = await suggestCapabilities(proactiveCtx);
if (suggestion) emitProactive(suggestion);
break;
}
default:
log.warn(`[cron] Unknown proactive action: ${proactiveConfig.action}`);
}
} catch (err) {
log.warn(`[cron] Proactive handler failed: ${(err as Error).message}`);
}
break;
}
case 'agent_task': {
// F9: Execute an agent task prompt in a workspace context
const taskConfig = JSON.parse(schedule.job_config || '{}');
const taskPrompt = taskConfig.prompt as string | undefined;
const taskWorkspace = schedule.workspace_id;
if (!taskPrompt) {
log.warn(`[cron] agent_task "${schedule.name}" has no prompt in job_config, skipping`);
break;
}
try {
// Determine target workspaces: "*" means all, otherwise single workspace
const targetWorkspaces: Array<{ id: string; name: string }> = [];
if (taskWorkspace === '*') {
// F30: Global/cross-workspace — iterate all workspaces
const allWs = wsManager.list();
for (const ws of allWs) {
targetWorkspaces.push({ id: ws.id, name: ws.name });
}
} else if (taskWorkspace) {
const ws = wsManager.get(taskWorkspace);
if (ws) {
targetWorkspaces.push({ id: ws.id, name: ws.name });
} else {
log.warn(`[cron] agent_task "${schedule.name}" references unknown workspace "${taskWorkspace}"`);
}
}
if (targetWorkspaces.length === 0) {
log.warn(`[cron] agent_task "${schedule.name}" has no valid target workspaces`);
break;
}
// #17 ai_task daily cap: every firing is a full agent turn (real
// LLM spend) — bound runaway schedules regardless of cron expr.
if (taskConfig.mode === 'ai_task'
&& cronStore.countExecutionsToday(schedule.id) >= AI_TASK_DAILY_CAP) {
log.warn(`[cron] ai_task "${schedule.name}" skipped — daily cap (${AI_TASK_DAILY_CAP}) reached`);
break;
}
let aiTaskSucceeded = false;
const targetErrors: unknown[] = [];
for (const target of targetWorkspaces) {
try {
// Activate workspace mind so agent has context
activateWorkspaceMind(target.id);
if (taskConfig.mode === 'ai_task') {
// #17: full agent turn through the loopback chat route —
// tools, memory recall, governance, approval-gated writes
// HELD (proposeHeld). origin:'automation' (#13) keeps the
// scheduled turn out of memory write-back. Legacy rows
// without mode keep the toolless completion path below.
const turn = await runChannelChatTurn({
port: fullConfig.port ?? 3333,
sessionToken: server.agentState.wsSessionToken,
message: `[Scheduled task "${schedule.name}" for workspace "${target.name}"]\n\n${taskPrompt}`,
workspace: target.id,
session: `schedule-${schedule.id}`,
proposeHeld: true,
origin: 'automation',
});
const output = turn.content || '';
if (!turn.error) aiTaskSucceeded = true;
// Delivery: origin channel first (stamped from the trusted
// turn-origin snapshot at create time), notification always.
const deliverTo = taskConfig.deliverTo as { platform?: string; chatId?: string } | undefined;
if (!turn.error && deliverTo?.platform && deliverTo?.chatId && output && isChannelPlatform(deliverTo.platform)) {
const sent = await server.channelManager
?.sendTo(deliverTo.platform, deliverTo.chatId, `[${schedule.name}]\n${output}`)
.catch((e: unknown) => {
log.warn(`[cron] ai_task "${schedule.name}" channel delivery failed: ${e instanceof Error ? e.message : e}`);
return false;
});
if (!sent) log.warn(`[cron] ai_task "${schedule.name}" delivery skipped — ${deliverTo.platform} adapter not running`);
}
const summary = output.length > 200 ? output.slice(0, 197) + '...' : output;
emitNotification(server, {
title: `Scheduled task: ${schedule.name}`,
body: turn.error ? `Error: ${turn.error}` : (summary || 'Task completed'),
category: 'cron',
actionUrl: `/workspaces/${target.id}`,
});
if (turn.error) {
throw new Error(`ai_task failed for workspace "${target.name}": ${turn.error}`);
} else {
log.info(`[cron] ai_task "${schedule.name}" completed for workspace "${target.name}" (${output.length} chars)`);
}
continue;
}
// Use the built-in Anthropic proxy to process the prompt
const proxyUrl = `${selfBaseUrl(server)}/v1/chat/completions`;
const response = await fetch(proxyUrl, {
method: 'POST',
headers: selfRequestHeaders(server),
body: JSON.stringify({
model: server.agentState.currentModel ?? 'claude-sonnet-4-6',
max_tokens: 2048,
messages: [
{
role: 'user',
content: `[Scheduled task for workspace "${target.name}"]\n\n${taskPrompt}`,
},
],
}),
signal: AbortSignal.timeout(120_000),
});
if (response.ok) {
const body = await response.json() as unknown;
const output = parseOpenAiTextCompletion(body).content;
const summary = output.length > 200 ? output.slice(0, 197) + '...' : output;
emitNotification(server, {
title: `Scheduled task: ${schedule.name}`,
body: summary || 'Task completed',
category: 'cron',
actionUrl: `/workspaces/${target.id}`,
});
log.info(`[cron] agent_task "${schedule.name}" completed for workspace "${target.name}" (${output.length} chars)`);
} else {
throw new Error(`agent_task LLM call failed: HTTP ${response.status}`);
}
} catch (wsErr) {
log.warn(`[cron] agent_task "${schedule.name}" failed for workspace "${target.name}": ${(wsErr as Error).message}`);
targetErrors.push(wsErr);
}
}
if (targetErrors.length === 1) throw targetErrors[0];
if (targetErrors.length > 1) {
throw new AggregateError(targetErrors, `agent_task failed in ${targetErrors.length} workspaces`);
}
// #17 once mode: one-shot ai_task disables itself after the first
// successful run (row kept for execution history).
if (taskConfig.mode === 'ai_task' && taskConfig.once === true && aiTaskSucceeded) {
cronStore.update(schedule.id, { enabled: false });
log.info(`[cron] ai_task "${schedule.name}" was one-shot — schedule disabled after successful run`);
}
} catch (err) {
log.warn(`[cron] agent_task handler failed: ${(err as Error).message}`);
throw err;
}
break;
}
case 'connector_fetch': {
// Auto-fetch (§3.C): pull fresh data from opted-in connectors into the
// personal mind. Cost-free — raw frames, no LLM extraction. Free (Solo).
try {
const statePath = path.join(fullConfig.dataDir, 'connector-harvest-state.json');
const r = await runConnectorFetch({
connectors: connectorRegistry.getConnected(),
writeFrame: async (content) => {
await memory.remember({
scope: PERSONAL_SCOPE,
text: content,
kind: 'note',
source: 'import',
origin: 'connector-fetch',
});
},
loadState: () => {
try {
const raw = JSON.parse(fs.readFileSync(statePath, 'utf-8')) as Partial<{ lastFetchedAt: string; hashes: Record<string, string> }>;
return { lastFetchedAt: raw.lastFetchedAt, hashes: raw.hashes ?? {} };
} catch { return { hashes: {} }; }
},
saveState: (s) => {
try { fs.writeFileSync(statePath, JSON.stringify(s)); } catch { /* best-effort */ }
},
// Safety floor: at most one real sweep per ~20h even if the cron
// expression is mis-set tight (auto-fetch is a daily cadence by design).
minIntervalMs: 20 * 60 * 60 * 1000,
log: (m) => log.info(`[cron] connector_fetch: ${m}`),
});
if (r.skippedByFloor) {
log.info('[cron] connector_fetch: within frequency floor — skipped');
} else {
log.info(`[cron] connector_fetch: ${r.framesWritten} frames from ${r.connectorsFetched} connector(s); ${r.skippedUnchanged} unchanged, ${r.skippedUnsafe} unsafe, ${r.errors.length} error(s)`);
}
} catch (err) {
log.warn(`[cron] connector_fetch failed: ${err instanceof Error ? err.message : String(err)}`);
}
break;
}
case 'loop': {
// Loop v0 (L1, report-only): a stateful, memory-powered scheduled
// automation. Resolve the target mind (a specific workspace, else the
// personal mind), build a toolless completion against the local proxy,
// and delegate to runLoopTick (recall → maker → checker → memory write).
// Throws from the maker/checker LLM path are intentionally NOT caught
// here so the scheduler records the failure and auto-disables after
// repeated failures (recall/write failures are caught inside runLoopTick).
const wsId = schedule.workspace_id;
const loopWorkspace = wsId && wsId !== '*' ? wsId : null;
if (loopWorkspace && !wsManager.get(loopWorkspace)) {
log.warn(`[cron] loop "${schedule.name}" references unknown workspace "${wsId}" — skipping`);
break;
}
if (wsId && wsId !== '*') activateWorkspaceMind(wsId);
const loopModel = server.agentState.currentModel ?? 'claude-sonnet-4-6';
const loopProxyUrl = `${selfBaseUrl(server)}/v1/chat/completions`;
const loopChat = async (prompt: string, maxTokens = 2048): Promise<string> => {
const resp = await fetch(loopProxyUrl, {
method: 'POST',
headers: selfRequestHeaders(server),
body: JSON.stringify({
model: loopModel,
max_tokens: maxTokens,
messages: [{ role: 'user', content: prompt }],
}),
signal: AbortSignal.timeout(120_000),
});
if (!resp.ok) throw new Error(`Loop LLM call failed: HTTP ${resp.status}`);
const body = await resp.json() as unknown;
return parseOpenAiTextCompletion(body).content;
};
const loopAwareness = new AwarenessLayer(waggleDb, wsId && wsId !== '*' ? workspaceDataScope(wsId) : 'personal');
const loopResult = await runLoopTick({
schedule,
memory,
scope: loopWorkspace ? workspaceScope(loopWorkspace) : PERSONAL_SCOPE,
awareness: loopAwareness,
chat: loopChat,
log,
});
if (!loopResult.skipped) {
emitNotification(server, {
title: `Loop: ${schedule.name}`,
body: loopResult.summary || 'Loop ran',
category: 'cron',
actionUrl: wsId && wsId !== '*' ? `/workspaces/${wsId}` : '/',
});
log.info(`[cron] loop "${schedule.name}" ran${loopResult.score !== undefined ? ` (score ${loopResult.score.toFixed(2)})` : ''}${loopResult.wrote ? ', wrote 1 frame' : ''}`);
// L2 assist mode: hold the maker's proposed action for human approval.
// enqueueHeldAction validates (allowlist + critical + injection) and
// persists 'held'; nothing executes until a human approves.
if (loopResult.proposedAction) {
const enq = enqueueHeldAction(server, {
workspaceId: wsId ?? null,
source: `loop:${schedule.id}`,
tool: loopResult.proposedAction.tool,
args: loopResult.proposedAction.args,
summary: loopResult.proposedAction.summary || undefined,
});
log.info(
'refused' in enq
? `[cron] loop "${schedule.name}" proposed ${loopResult.proposedAction.tool} — refused (${enq.refused})`
: `[cron] loop "${schedule.name}" proposed ${loopResult.proposedAction.tool} — held for approval (${enq.id})`,
);
}
}
break;
}
}
}, (schedule, result) => {
// UX-Refactor Phase 3 (Journey 16): persist the execution outcome to
// cron_execution_history. Until now recordExecution was never called, so
// GET /api/cron/:id/history, /api/automations/:id/logs and the Home
// overnight failure feed all read an empty table. Fires for scheduler
// ticks AND manual triggers (executeJob); the C26 /api/automations/test
// preview is validation-only and never reaches the executor. The
// persistence closure is the shared makeRecordExecutionCallback (cron.ts)
// so automations.test.ts exercises the SAME code, not a hand-copied mirror.
persistCronHistory(schedule, result);
// Q16:C — Emit notification after every cron job tick (success or failure)
if (result.success) {
emitNotification(server, {
title: `${schedule.name || 'Scheduled task'} completed`,
body: 'Scheduled task ran successfully.',
category: 'cron',
actionUrl: '/settings/mission-control',
});
} else {
emitNotification(server, {
title: `${schedule.name || 'Scheduled task'} failed`,
body: `Error: ${result.error ?? 'Unknown error'}`,
category: 'cron',
actionUrl: '/settings/mission-control',
});
}
// FR-2 §runtime · 2026-05-28 addictiveness audit. When the user
// sets `outputChannel: 'telegram'` in a schedule's job_config,
// push a one-line digest line to their Telegram so the cron
// becomes a daily-driver hook for personas P6/P8/P10. Fire-and-
// forget — the catch ensures a Telegram outage never crashes
// the scheduler tick.
try {
const cfg = JSON.parse(schedule.job_config || '{}') as { outputChannel?: string };
if (cfg.outputChannel === 'telegram') {
const name = schedule.name || 'Scheduled task';
const expr = schedule.cron_expr ? ` (${schedule.cron_expr})` : '';
const text = result.success
? `Waggle: ${name}${expr} ran successfully.`
: `Waggle: ${name}${expr} failed: ${result.error ?? 'unknown error'}`;
pushTelegramMessage(server, text)
.then(r => { if (!r.ok) log.warn(`[cron→telegram] skipped: ${r.reason}`); })
.catch(err => log.warn(`[cron→telegram] push failed: ${err}`));
}
} catch (err) {
log.warn(`[cron→telegram] config parse failed: ${err}`);
}
}, notification => {
emitNotification(server, {
...notification,
category: 'cron',
actionUrl: '/settings/mission-control',
});
}, schedule => !cronScheduleHasReadOnlyViewerTarget(schedule, server));
scheduler.start();
server.decorate('scheduler', scheduler);
// F2: Daily audit event cleanup (retain 90 days by default)
const auditRetentionDays = parseInt(process.env.WAGGLE_AUDIT_RETENTION_DAYS ?? '90', 10);
const auditCleanupTimer = setInterval(() => {
const deleted = cleanupAuditEvents(fullConfig.dataDir, auditRetentionDays);
if (deleted > 0) {
log.info(`[audit] Cleaned up ${deleted} events older than ${auditRetentionDays} days`);
}
}, 24 * 60 * 60 * 1000); // once per day
// PM-6: Offline manager — periodic LLM health checks
const resolveOfflineManagerEndpoint = (): string => {
if (!fullConfig.useBuiltInProxy) return fullConfig.litellmUrl;
const address = server.server.address();
return address && typeof address === 'object'
? `http://127.0.0.1:${address.port}/v1`
: fullConfig.litellmUrl;
};
const offlineManager = new OfflineManager({
dataDir: fullConfig.dataDir,
getLlmEndpoint: resolveOfflineManagerEndpoint,
getLlmApiKey: () => server.agentState?.litellmApiKey ?? '',
checkLlmReadiness: async (signal) => {
const selectedModel = server.agentState.currentModel.trim();
const selectedOllama = selectedModel.toLowerCase().startsWith('ollama/');
const unselectedOllama = !selectedModel
&& server.agentState.llmProvider.provider === 'ollama';
if (selectedOllama || unselectedOllama) {
const localModels = await listOllamaChatModelIds(signal);
return selectedOllama
? localModels.some(model => model.toLowerCase() === selectedModel.toLowerCase())
: localModels.length > 0;
}
const endpoint = resolveOfflineManagerEndpoint().replace(/\/+$/, '');
const apiKey = server.agentState.litellmApiKey;
const headers: Record<string, string> = {};
if (apiKey) headers.Authorization = `Bearer ${apiKey}`;
const response = await fetch(`${endpoint}/health/readiness`, {
method: 'GET',
headers,
signal: AbortSignal.any([signal, AbortSignal.timeout(5_000)]),
});
if (!response.ok) return false;
if (server.agentState.llmProvider.provider !== 'litellm') return true;
// LiteLLM readiness alone only proves the router process is accepting
// traffic. Its local model catalog must also expose the selected route.
const modelsResponse = await fetch(`${endpoint}/models`, {
method: 'GET',
headers,
signal: AbortSignal.any([signal, AbortSignal.timeout(5_000)]),
});
if (!modelsResponse.ok) return false;
const modelsPayload = await modelsResponse.json() as {
data?: Array<{ id?: string }>;
};
const modelIds = (modelsPayload.data ?? [])
.map(model => model.id)
.filter((model): model is string => typeof model === 'string');
return selectedModel ? modelIds.includes(selectedModel) : modelIds.length > 0;
},
eventBus,
checkIntervalMs: 30_000,
});
if (fullConfig.startOfflineManagerOnListen !== false) {
server.addHook('onListen', async () => {
offlineManager.start();
});
}
server.addHook('preClose', async () => {
await offlineManager.stop();
});
server.decorate('offlineManager', offlineManager);
// Plugins
// CORS restricted to known Tauri/dev origins — prevents cross-origin attacks from arbitrary websites
await server.register(cors, {
origin: (origin, cb) => {
if (corsOriginAllowed(origin)) {
cb(null, true);
} else {
cb(new Error('CORS: origin not allowed'), false);
}
},
});
await server.register(websocket);
// Security middleware — headers + rate limiting + bearer auth (local server only)
const rateLimiterMaxRequests = Number.parseInt(process.env.WAGGLE_RATE_LIMIT_MAX_REQUESTS ?? '', 10);
const rateLimiterWindowMs = Number.parseInt(process.env.WAGGLE_RATE_LIMIT_WINDOW_MS ?? '', 10);
const rateLimiterConfig = {
...(Number.isFinite(rateLimiterMaxRequests) && rateLimiterMaxRequests > 0
? { maxRequests: rateLimiterMaxRequests }
: {}),
...(Number.isFinite(rateLimiterWindowMs) && rateLimiterWindowMs > 0
? { windowMs: rateLimiterWindowMs }
: {}),
};
await server.register(securityMiddleware, {
sessionToken: server.agentState.wsSessionToken,
authenticateBrowserCompanionToken: (token) => browserCompanionCredentialMatches(
token,
server.agentState.browserCompanionCredentialHash,
),
authenticateRunToken: (token) => {
const run = agentRunRegistry.authenticateCredential(token);
if (!run) return false;
return { runId: run.id, model: run.executor.model };
},
rateLimiter: Object.keys(rateLimiterConfig).length > 0 ? rateLimiterConfig : undefined,
});
// D1: session-token bootstrap. Managed desktop launches require a random
// per-launch credential delivered only through Tauri IPC. An ordinary browser
// can forge a tauri.localhost Origin, so Origin alone is not an application
// identity. Browser-only mode has no IPC channel and is instead bound to the
// exact loopback request authority (host + port).
server.get('/api/auth/session-token', async (request, reply) => {
if (!isLoopbackBind()) {
return reply.code(403).send({
error: 'Session bootstrap is available only on a loopback-bound sidecar.',
code: 'SESSION_BOOTSTRAP_LOOPBACK_ONLY',
});
}
if (managedDesktopBootstrap) {
if (!desktopBootstrapMatches(
request.headers['x-waggle-desktop-bootstrap'],
desktopBootstrapToken,
)) {
return reply.code(403).send({
error: 'Desktop session bootstrap requires the owned launch credential.',
code: 'DESKTOP_BOOTSTRAP_REQUIRED',
});
}
} else if (!browserBootstrapAuthorityAllowed(request)) {
return reply.code(403).send({
error: 'Session bootstrap origin does not match the local service authority.',
code: 'SESSION_BOOTSTRAP_ORIGIN_MISMATCH',
});
}
reply.header('Cache-Control', 'no-store');
return { token: server.agentState.wsSessionToken };
});
// P5 (PDF 2026-04-17): minimal debug-log viewer for support attachments.
// Returns health + last 500 audit events + recent cost entries as JSON.
server.get('/api/debug/logs', async (request, reply) => {
// R2-006: same-origin gate — this endpoint exposes audit history and is
// recon material; never serve it cross-origin (defense in depth behind
// the loopback bind).
if (!isLocalRequest(request)) {
return reply.code(403).send({ error: 'Forbidden: external origin' });
}
const payload: Record<string, unknown> = {
timestamp: new Date().toISOString(),
version: '0.2.0',
platform: process.platform,
};
try { payload.health = await server.inject({ method: 'GET', url: '/health' }).then(r => JSON.parse(r.payload)); } catch { /* non-blocking */ }
try {
// R2-006: expose only a coarse, non-recon column subset (no capability
// names/versions/sources, risk_level, approval_class, initiator or detail)
// and cap the rows — the support bundle needs activity shape, not an inventory.
payload.auditRecent = server.auditStore.getRecentSummary(50);
} catch { /* non-blocking */ }
// R2-006: vault key NAMES dropped — even names are recon material and the
// support bundle does not need them.
reply.header('Content-Type', 'application/json; charset=utf-8');
reply.header('Content-Disposition', `attachment; filename="waggle-logs-${Date.now()}.json"`);
return payload;
});
// Routes
await server.register(workspaceRoutes);
await server.register(chatRoutes);
await server.register(memoryRoutes);
await server.register(memoryCenterRoutes);
await server.register(settingsRoutes);
await server.register(embeddingRoutes);
await server.register(sessionRoutes);
await server.register(knowledgeRoutes);
await server.register(litellmRoutes);
await server.register(ingestRoutes);
await server.register(mindRoutes);
await server.register(agentRoutes);
await server.register(skillRoutes);
// UX-Refactor Phase 3: /api/skills/:id aliases (S06/S19) — delegates into
// skillRoutes handlers, so it registers right after them.
await server.register(skillsAliasRoutes);
await server.register(skillsHygieneRoutes);
await server.register(skillsAuditRoutes);
await server.register(approvalRoutes);
await server.register(anthropicProxyRoutes);
await server.register(taskRoutes);
await server.register(capabilitiesRoutes);
await server.register(toolsRoutes);
await server.register(externalToolRunRoutes);
await server.register(routeProposalRoutes);
server.decorate('signalBus', new SignalBus());
await server.register(commandRoutes);
// UX-Refactor Phase 1: Home Cockpit (S01) + Command Center (S00/S03) surfaces.
// commandCenterRoutes registers the singular /api/command/* aliases (B4) — it
// is distinct from the plural commandRoutes (/api/commands/execute) above.
await server.register(homeRoutes);
await server.register(onboardingRoutes);
await server.register(commandCenterRoutes);
await server.register(cronRoutes);
// UX-Refactor Phase 3: Agent entity (S09/S18, B3 agents.json) + the
// /api/automations/* PRD-vocabulary alias over cron (S11/S20, B4).
// agentEntityRoutes is distinct from agentRoutes (/api/agent/* + /api/agents/
// active) and agentGroupRoutes; the static /api/agents/active keeps precedence
// over the new /:id param route (find-my-way prefers static segments).
await server.register(agentEntityRoutes);
await server.register(automationRoutes);
await server.register(notificationRoutes);
await server.register(marketplaceDevRoutes);
await server.register(marketplaceRoutes);
await server.register(createCapabilityProposalRoutes(
capabilityProposalStore,
(identity) => installMarketplaceApprovalIdentity(server, identity),
));
await server.register(agentSearchRoutes);
await server.register(connectorRoutes);
// UX-Refactor Phase 4 (Extend layer): MCP Hub (S08) + the marketplace
// bare-path alias / shared install-audit read (S21, C18). extendRoutes
// delegates onto marketplaceRoutes via inject — register after it.
await server.register(mcpRoutes);
await server.register(extendRoutes);
await server.register(fleetRoutes);
await server.register(vaultRoutes);
await server.register(personaRoutes);
await server.register(feedbackRoutes);
await server.register(workspaceTemplateRoutes);
await server.register(exportRoutes);
await server.register(dataEraseRoutes);
await server.register(costRoutes);
await server.register(backupRoutes);
await server.register(offlineRoutes);
await server.register(eventRoutes);
await server.register(workflowRoutes);
await server.register(pinRoutes);
await server.register(documentRoutes);
await server.register(artifactRoutes);
await server.register(fileRoutes);
await server.register(waggleSignalRoutes);
await server.register(providerRoutes);
await server.register(profileRoutes);
await server.register(oauthRoutes);
await server.register(browseRoutes);
await server.register(browserExtRoutes);
await server.register(telegramRoutes);
// IM channel adapters (Slack/Telegram/WhatsApp/Discord) — see
// docs/plans/CHANNELS-ARC-2026-07-09.md. Manager owns adapter lifecycle;
// adapters run agent turns through loopback POST /api/chat.
{
const channelManager = new ChannelManager({
dataDir: server.localConfig.dataDir,
port: server.localConfig.port,
sessionToken: server.agentState.wsSessionToken,
vault: {
get: (key: string) => server.vault?.get(key) ?? null,
has: (key: string) => server.vault?.has(key) ?? false,
set: (key: string, value: string, metadata?: Record<string, unknown>) => {
if (!server.vault) throw new Error('Vault is unavailable');
server.vault.set(key, value, metadata);
},
delete: (key: string) => server.vault?.delete(key) ?? false,
},
log: {
info: (msg: string) => server.log.info(msg),
warn: (msg: string) => server.log.warn(msg),
},
listWorkspaces: () => wsManager.list().map(w => ({ id: w.id, name: w.name })),
onAudit: (event) => emitAuditEvent(server, {
workspaceId: 'default',
eventType: event.type,
input: JSON.stringify({ platform: event.platform, detail: event.detail ?? '' }),
}),
});
server.decorate('channelManager', channelManager);
// Auto-start enabled channels once the server is up; skip under test to
// keep unit runs hermetic.
if (!process.env.VITEST && process.env.NODE_ENV !== 'test') {
server.addHook('onReady', async () => {
await channelManager.startEnabled();
});
}
server.addHook('onClose', async () => {
await channelManager.stopAll();
});
}
await server.register(channelRoutes);
await server.register(dreamRoutes);
await server.register(telemetryRoutes);
await server.register(agentGroupRoutes);
await server.register(localJobRoutes);
await server.register(identityRoutes);
await server.register(agentRunRoutes);
await server.register(agentRunsRoutes);
await server.register(localInferenceRoutes);
// ── Static file serving for web mode ──────────────────────────
// When WAGGLE_FRONTEND_DIR is set, serve the React frontend as static files.
// Otherwise probe likely build outputs. The canonical build (per root
// package.json `build` script) is `<root>/dist`, which apps/web/vite
// writes to. `app/dist` is kept as a fallback for legacy Tauri-shell
// builds but is no longer the primary source — if both exist, root dist wins.
const frontendDir = process.env.WAGGLE_FRONTEND_DIR
?? [
// Root `dist/` — primary build target from `npm run build`
path.resolve(process.cwd(), 'dist'), // from monorepo root
path.resolve(process.cwd(), '..', '..', 'dist'), // from packages/server/
path.resolve(process.cwd(), '..', 'dist'), // from packages/
...(typeof process.argv[1] === 'string' ? [path.resolve(path.dirname(process.argv[1]), '..', '..', '..', '..', 'dist')] : []),
// Legacy `app/dist/` — Tauri shell build, kept as fallback
path.resolve(process.cwd(), 'app', 'dist'), // from monorepo root
path.resolve(process.cwd(), '..', '..', 'app', 'dist'), // from packages/server/
path.resolve(process.cwd(), '..', 'app', 'dist'), // from packages/
...(typeof process.argv[1] === 'string' ? [path.resolve(path.dirname(process.argv[1]), '..', '..', '..', '..', 'app', 'dist')] : []),
].find(d => fs.existsSync(path.join(d, 'index.html'))) ?? path.resolve(process.cwd(), 'dist');
if (fs.existsSync(frontendDir) && fs.existsSync(path.join(frontendDir, 'index.html'))) {
await server.register(fastifyStatic, {
root: frontendDir,
prefix: '/',
wildcard: false,
});
// SPA fallback: serve index.html for all non-API, non-static, non-asset routes
server.setNotFoundHandler((request, reply) => {
// Don't intercept API routes, WebSocket upgrades, or static assets
if (request.url.startsWith('/api/') || request.url.startsWith('/v1/') ||
request.url.startsWith('/assets/') ||
request.url === '/health' || request.url === '/ws') {
reply.code(404).send({ error: 'Not found' });
return;
}
reply.sendFile('index.html', frontendDir);
});
}
// WebSocket endpoint — event bus relay to frontend
// 11A-6: Require session token for WebSocket authentication
// 11A-8: Per-connection listener tracking (don't kill other clients on disconnect)
server.get('/ws', { websocket: true }, (socket, request) => {
// 11A-6: Validate session token from query param
const url = new URL(request.url, 'http://localhost');
const token = url.searchParams.get('token');
if (token !== server.agentState.wsSessionToken) {
socket.close(4001, 'Unauthorized: invalid session token');
return;
}
// Per-connection listener references for clean removal on disconnect
const listenerMap = new Map<string, (...args: unknown[]) => void>();
// Forward approval events and agent events to the WebSocket client
const eventTypes = ['approval_required', 'step', 'tool', 'done', 'error', 'presence_update', 'notification'] as const;
for (const evt of eventTypes) {
const handler = (data: unknown) => {
try {
socket.send(JSON.stringify({ event: evt, data }));
} catch {
// Client disconnected
}
};
listenerMap.set(evt, handler);
eventBus.on(evt, handler);
}
socket.on('message', (raw: Buffer) => {
try {
const msg = JSON.parse(raw.toString()) as { type: string; requestId?: string; reason?: string };
if (msg.type === 'approve' && msg.requestId) {
const pending = server.agentState.pendingApprovals.get(msg.requestId);
if (pending) {
server.agentState.pendingApprovals.delete(msg.requestId);
pending.resolve(true);
}
} else if (msg.type === 'deny' && msg.requestId) {
const pending = server.agentState.pendingApprovals.get(msg.requestId);
if (pending) {
server.agentState.pendingApprovals.delete(msg.requestId);
pending.resolve(false);
}
}
} catch {
// Ignore malformed messages
}
});
socket.on('close', () => {
// Remove only THIS connection's listeners, not all clients'
for (const [evt, handler] of listenerMap) {
eventBus.removeListener(evt, handler);
}
listenerMap.clear();
});
});
// P0-3: Cached API key validation — verify key actually works, not just exists
let keyValidationCache: { valid: boolean; checkedAt: number; keyHash: string } | null = null;
let keyValidationInFlight: Promise<void> | null = null;
const KEY_VALIDATION_TTL = 30 * 1000; // 30 seconds — short so vault updates are picked up quickly
function hashKey(key: string): string {
// Simple hash for cache invalidation — not cryptographic
let h = 0;
for (let i = 0; i < key.length; i++) {
h = ((h << 5) - h + key.charCodeAt(i)) | 0;
}
return String(h);
}
function getAnthropicApiKey(): string {
const vaultKey = server.vault?.get('anthropic')?.value;
return vaultKey || process.env.ANTHROPIC_API_KEY || '';
}
function freshAnthropicValidation(): boolean | null {
const apiKey = getAnthropicApiKey();
if (!apiKey) return false;
const currentHash = hashKey(apiKey);
if (
keyValidationCache &&
keyValidationCache.keyHash === currentHash &&
Date.now() - keyValidationCache.checkedAt < KEY_VALIDATION_TTL
) {
return keyValidationCache.valid;
}
return null;
}
function markAnthropicProxyDegraded(detail = 'Built-in Anthropic proxy (API key invalid or expired, update in Settings > Models)'): void {
server.agentState.llmProvider.health = 'degraded';
server.agentState.llmProvider.detail = detail;
}
async function validateAnthropicKey(): Promise<boolean> {
// Read key from vault first, fall back to env var
const apiKey = getAnthropicApiKey();
if (!apiKey) return false;
const currentHash = hashKey(apiKey);
// Return cached result if fresh AND key hasn't changed
if (
keyValidationCache &&
keyValidationCache.keyHash === currentHash &&
Date.now() - keyValidationCache.checkedAt < KEY_VALIDATION_TTL
) {
return keyValidationCache.valid;
}
try {
// Lightweight API call to verify key works
const res = await fetch('https://api.anthropic.com/v1/messages', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': apiKey,
'anthropic-version': '2023-06-01',
},
body: JSON.stringify({
model: 'claude-haiku-4-5-20251001',
max_tokens: 1,
messages: [{ role: 'user', content: 'hi' }],
}),
signal: AbortSignal.timeout(5000),
});
// 200 = valid, 401 = invalid/expired, 400 = valid key but bad request (still means key works)
const valid = res.status !== 401 && res.status !== 403;
keyValidationCache = { valid, checkedAt: Date.now(), keyHash: currentHash };
return valid;
} catch {
// Network error — don't cache failure, key might be fine
return keyValidationCache?.valid ?? true;
}
}
function validateAnthropicKeyInBackground(): void {
if (keyValidationInFlight) return;
keyValidationInFlight = validateAnthropicKey()
.then((valid) => {
if (!valid && server.agentState.llmProvider.provider === 'anthropic-proxy') {
markAnthropicProxyDegraded();
}
})
.finally(() => {
keyValidationInFlight = null;
});
keyValidationInFlight.catch(() => { /* fire-and-forget guard */ });
}
// Expose cache invalidation for settings route to call after key update
server._invalidateKeyValidationCache = () => {
keyValidationCache = null;
// If currently degraded due to bad key, reset to healthy for re-validation
if (server.agentState.llmProvider.health === 'degraded') {
server.agentState.llmProvider.health = 'healthy';
server.agentState.llmProvider.detail = 're-validating after key change';
}
};
// IMP-15: API docs — auto-generated from Fastify route registry
server.get('/api/docs', async () => {
const routes: Array<{ method: string; url: string; prefix: string }> = [];
// Fastify exposes registered routes via the internal routing tree, which is
// not part of the public typings — read it through an `unknown[]` and narrow.
const allRoutes: unknown[] = (server as { routes?: unknown[] }).routes ?? [];
// Iterate printRoutes() style — Fastify 4.x stores routes differently
// Use server.printRoutes() as a fallback reference
try {
// Fastify stores routes in server[Symbol.for('registered-routes')] or similar
// Best approach: iterate after ready using routesByMethod
for (const route of allRoutes) {
if (route && typeof route === 'object' && 'url' in route && 'method' in route) {
const r = route as { url: string; method: string | string[]; prefix?: string };
const methods = Array.isArray(r.method) ? r.method : [r.method];
for (const m of methods) {
routes.push({ method: m, url: r.url, prefix: r.prefix ?? '' });
}
}
}
} catch { /* fallback to empty */ }
// If routes array is empty (Fastify internals differ), provide static list
if (routes.length === 0) {
return {
openapi: '3.0.0',
info: { title: 'Waggle API', version: '1.0.0', description: 'Workspace-native AI agent platform' },
note: 'Dynamic route listing unavailable. Use GET /health for status.',
categories: {
chat: ['POST /api/chat'],
workspaces: ['GET /api/workspaces', 'POST /api/workspaces', 'GET /api/workspaces/:id', 'PUT /api/workspaces/:id', 'DELETE /api/workspaces/:id', 'GET /api/workspaces/:id/cost', 'GET /api/workspaces/:id/context', 'GET /api/workspaces/:id/files', 'GET /api/workspaces/:id/storage', 'GET /api/workspaces/:id/storage/files', 'GET /api/workspaces/:id/storage/read', 'POST /api/workspaces/:id/storage/write', 'DELETE /api/workspaces/:id/storage/delete'],
memory: ['GET /api/memory/search', 'GET /api/memory/frames', 'POST /api/memory/frames', 'DELETE /api/memory/frames/:id', 'GET /api/memory/stats', 'GET /api/memory/graph'],
sessions: ['GET /api/workspaces/:workspaceId/sessions', 'POST /api/workspaces/:workspaceId/sessions', 'PATCH /api/sessions/:sessionId', 'DELETE /api/sessions/:sessionId', 'GET /api/sessions/:sessionId/summary'],
events: ['GET /api/events', 'GET /api/events/stats', 'GET /api/events/stream'],
settings: ['GET /api/settings', 'PUT /api/settings', 'PATCH /api/settings', 'POST /api/settings/test-key', 'POST /api/settings/probe-provider'],
vault: ['GET /api/vault', 'POST /api/vault', 'DELETE /api/vault/:name'],
fleet: ['GET /api/fleet', 'POST /api/fleet/:workspaceId/pause', 'POST /api/fleet/:workspaceId/resume', 'POST /api/fleet/:workspaceId/kill'],
cost: ['GET /api/cost/summary', 'GET /api/cost/by-workspace', 'GET /api/costs'],
agent: ['GET /api/agent/status', 'GET /api/agent/model', 'GET /api/agent/cost'],
marketplace: ['GET /api/marketplace/search', 'GET /api/marketplace/packs', 'POST /api/marketplace/install', 'POST /api/marketplace/uninstall'],
connectors: ['GET /api/connectors', 'POST /api/connectors/:id/connect', 'POST /api/connectors/:id/disconnect'],
other: ['GET /health', 'POST /api/export', 'POST /api/backup', 'POST /api/restore', 'GET /api/cron', 'POST /api/ingest', 'GET /api/personas', 'GET /api/workspace-templates'],
},
};
}
// Dynamic route listing
const grouped: Record<string, string[]> = {};
for (const r of routes) {
if (!r.url.startsWith('/api/') && r.url !== '/health') continue;
const category = r.url.split('/')[2] ?? 'other';
if (!grouped[category]) grouped[category] = [];
grouped[category].push(`${r.method} ${r.url}`);
}
return {
openapi: '3.0.0',
info: { title: 'Waggle API', version: '1.0.0', description: 'Workspace-native AI agent platform' },
endpointCount: routes.filter(r => r.url.startsWith('/api/')).length,
categories: grouped,
};
});
// Embedding provider status + reprobe endpoints. (The set/write side —
// POST /api/embedding/provider — lives in routes/embedding.ts.)
server.get('/api/embedding/status', async () => {
// Enriched shape: live status + persisted `configuredProvider` + `envOverride`.
return buildEmbeddingStatusPayload(server);
});
server.post('/api/embedding/reprobe', async () => {
// Re-read API keys from Vault (user may have just added one)
try {
const voyageEntry = vault.get('voyage-api-key');
if (voyageEntry?.value) embeddingConfig.voyage = { apiKey: voyageEntry.value };
} catch { /* skip */ }
try {
const openaiEntry = vault.get('openai');
if (openaiEntry?.value) embeddingConfig.openai = { apiKey: openaiEntry.value };
} catch { /* skip */ }
return embeddingProvider.reprobe();
});
// Health check — truthful, not optimistic
server.get('/health', async () => {
const llm = { ...server.agentState.llmProvider };
const listeningAddress = server.server.address();
const servicePort = typeof listeningAddress === 'object' && listeningAddress
? listeningAddress.port
: server.localConfig.port;
// P0-3: If provider is anthropic-proxy and claims healthy, validate the key actually works
if (
llm.provider === 'anthropic-proxy'
&& llm.health === 'healthy'
&& llm.detail.startsWith('Built-in Anthropic proxy')
) {
const keyValid = freshAnthropicValidation();
if (keyValid === false) {
llm.health = 'degraded';
llm.detail = 'Built-in Anthropic proxy (API key invalid or expired, update in Settings > Models)';
markAnthropicProxyDegraded(llm.detail);
} else if (keyValid === null) {
validateAnthropicKeyInBackground();
}
}
const dbHealthy = (() => {
try {
waggleDb.getDatabase().prepare('SELECT 1').get();
return true;
} catch {
return false;
}
})();
// Startup may resolve a provider after OfflineManager's initial probe.
// Once a later completion-readiness probe runs, it becomes authoritative.
const offlineState = offlineManager.state;
const providerCheckedAt = Date.parse(llm.checkedAt);
const readinessCheckedAt = Date.parse(offlineManager.lastCheck);
const providerStatusIsNewer = Number.isFinite(providerCheckedAt)
&& providerCheckedAt > readinessCheckedAt;
const llmReachable = providerStatusIsNewer
? llm.health === 'healthy'
: !offlineState.offline;
const effectiveOfflineState = {
...offlineState,
offline: !llmReachable,
since: llmReachable ? null : offlineState.since,
};
const overallStatus = llmReachable && llm.health === 'healthy' && dbHealthy
? 'ok'
: llm.health === 'unavailable' || !dbHealthy
? 'unavailable'
: 'degraded';
// Memory stats — memory count and the size of the memory directory.
// mem0 embeds every memory on write, so coverage is complete by design.
const memoryStats = await (async () => {
const embeddingProviderStatus = server.embeddingProvider?.getStatus?.() ?? null;
try {
const scopes = [PERSONAL_SCOPE, ...wsManager.list().map(ws => workspaceScope(ws.id))];
const frameCount = await memory.count({ scopes });
let mindSizeBytes = 0;
try {
const memoryDir = path.join(fullConfig.dataDir, 'memory');
for (const file of fs.readdirSync(memoryDir)) {
mindSizeBytes += fs.statSync(path.join(memoryDir, file)).size;
}
} catch { /* nothing stored yet */ }
return { frameCount, mindSizeBytes, embeddingCoverage: 100, embeddingProvider: embeddingProviderStatus };
} catch {
return { frameCount: 0, mindSizeBytes: 0, embeddingCoverage: 0, embeddingProvider: embeddingProviderStatus };
}
})();
// Service health — watchdog and notification SSE status
const serviceHealth = {
watchdogRunning: scheduler.isRunning(),
notificationSSEActive: eventBus.listenerCount('notification') > 0,
};
return {
status: overallStatus,
mode: 'local',
instanceId: server.localConfig.instanceId ?? null,
port: servicePort,
timestamp: new Date().toISOString(),
llm: {
provider: llm.provider,
health: llm.health,
detail: llm.detail,
checkedAt: llm.checkedAt,
reachable: llmReachable,
lastCheck: new Date().toISOString(),
},
database: { healthy: dbHealthy },
memoryStats,
serviceHealth,
defaultModel: server.agentState.currentModel,
offline: effectiveOfflineState,
// R1-001: wsToken intentionally NOT returned — /health is unauthenticated
// and the token authenticates every other route. Localhost clients are
// trusted by security-middleware and never needed it.
};
});
// Cleanup on close
server.addHook('onClose', async () => {
// Stop cron scheduler
localJobStore.close();
agentRunRegistry.close();
stopMarketplaceBackgroundSync();
scheduler.stop();
await offlineManager.stop();
clearInterval(auditCleanupTimer);
// Stop MCP servers
await mcpRuntime.stopAll().catch(() => {});
// Stop collecting chat turns for fact extraction.
memoryExtraction.stop();
// Close all workspace sessions (new concurrent model)
sessionManager.closeAll();
await memory.close();
waggleDb.close();
// Close audit DB and telemetry
closeAuditDb();
try { telemetry.close(); } catch { /* already closed */ }
// Close marketplace DB
if (marketplaceDb) {
try { marketplaceDb.close(); } catch { /* already closed */ }
}
});
return server;
}